chore(release): v3.5.6 — email masking, model toggle, OpenRouter registries & bug fixes (#1080)

* fix(minimax): switch auth from x-api-key to Authorization Bearer (#1076)

Integrated into release/v3.5.6 — MiniMax auth fix with authHeader consistency normalization

* feat(CI,i18n): autogenerate language files + Add missing strings (#1071)

Integrated into release/v3.5.6 — i18n translations for memory, skills, and missing keys across 31 languages

* fix(ci): restore i18n continue-on-error, remove auto-commit race condition

* fix(husky): load nvm in hooks for VS Code compatibility

* fix(husky): gracefully skip hooks when npm is not in PATH

* fix: convert OpenAI function tool_choice to Claude tool format (#1072)

* fix: prevent EPIPE feedback loop filling logs at GB/s (#1006)

* fix: fallback to native fetch when undici dispatcher fails (#1054)

* fix: improve Qoder PAT validation with actionable error messages (#966)

- Add QODER_PERSONAL_ACCESS_TOKEN env var fallback for both validation and execution
- Pre-flight ping check to diagnose connectivity issues (Docker/proxy)
- Detect encrypted auth blobs from ~/.qoder/.auth/user and guide to website PAT
- Clear error messages for auth failures with link to integrations page
- Treat non-auth 4xx as auth-pass (request format issue, not token issue)
- Update tests to cover new validation paths (23 tests, all passing)

* feat: Improve the Chinese translation (#1079)

Integrated into release/v3.5.6

* chore(release): v3.5.6 — i18n updates and credential security fixes

* fix(ci): resolve e2e and docs-sync pipeline failures

* fix(security): bump next to 16.2.3 to resolve SNYK-JS-NEXT-15954202

* fix: guard Memory/Cache UI against null toLocaleString crash (#1083)

* fix: translate OpenAI tool_choice type 'function' to Claude 'tool' format (#1072)

* fix: pass custom baseUrl in provider API key validation (#1078)

* docs: update CHANGELOG with v3.5.6 bug fixes and security patches

* docs: rewrite implement-features workflow with 5-phase harvest-research-report-plan-execute pipeline

* docs: organize _ideia/ into viable/defer/notfit + add Phase 2.5 auto-response workflow

* docs: implementation plans for #1025, #750, #960, #1046 + close already-implemented #833, #973, #982

* feat: mask email addresses in dashboard for privacy (#1025)

* feat: add OpenRouter and GitHub to embedding/image provider registries (#960)

* feat: add model visibility toggle and search filter to provider page (#750)

* docs: move implemented features to notfit, update task plans status

* chore: untrack _ideia/ and _tasks/ from git — private/internal only

* chore(release): bump to v3.5.6 — changelog, docs, version sync & any-budget fix

* fix: remove explicit .ts extension in qoderCli import that caused 500 error in production build

---------

Co-authored-by: Jean Brito <jeanfbrito@gmail.com>
Co-authored-by: zenobit <zenobit@disroot.org>
Co-authored-by: diegosouzapw <diegosouzapw@users.noreply.github.com>
Co-authored-by: Ethan Hunt <136065060+only4copilot@users.noreply.github.com>

.agents/workflows/capture-release-evidences.md

@@ -0,0 +1,49 @@
+---
+description: Automatically run the browser_subagent to visually validate all new UI features from the current release and capture evidence WebP recordings of the changes.
+---
+
+# Capture Release Evidences Workflow
+
+Use this workflow to automatically drive the `browser_subagent` to explore the newly deployed or locally running application and record evidence of the UI changes introduced in the latest release.
+
+## Prerequisites
+
+- OmniRoute must be actively running and accessible (e.g. locally at `http://localhost:20128` or on the Local VPS at `http://192.168.0.15:20128`).
+- The user must provide the target URL to be tested, or default to `http://192.168.0.15:20128`.
+
+## Workflow Steps
+
+### 1. Identify Target Features
+
+Review the `CHANGELOG.md` for the latest version to map out the new UI elements. For example:
+
+- **CLI Tools Settings**
+- **New Provider/Model Listings (e.g., Gemini 3.1, Qoder PAT)**
+- **New Feature Modals**
+
+### 2. Run the Browser Subagent
+
+For each identified feature, invoke the `browser_subagent` using the `default_api:browser_subagent` tool.
+**Important Task Guidelines for the Subagent:**
+
+- `TaskName`: Give it a clear name like "Validate CLIProxyAPI Tool Tab".
+- `TaskSummary`: "Navigate to the CLI Tools tab and verify the new Integration settings."
+- `Task`: Provide unambiguous instructions for the subagent, such as: "Navigate to http://192.168.0.15:20128/dashboard. Click on the 'Settings' or 'CLI Tools' nav link. Scroll down to find the CLIProxyAPI integration card. Hover over it to trigger UI state. Verify the components render correctly and exit."
+- `RecordingName`: Ensure it describes the feature (e.g. `v3_4_5_cli_proxy_api`). This is required and strictly automatically saved as a WebP artifacts video by the system.
+
+_(Note: The `browser_subagent` automatically creates a WebP recording named by the `RecordingName` parameter. No additional tools for screenshots are needed.)_
+
+### 3. Generate Report Artifact
+
+After the `browser_subagent` finishes its sessions, generate a final Markdown artifact (using `write_to_file` and `IsArtifact=true`) to present the recordings inline to the user using the `![caption](/absolute/path/to/media.webp)` syntax.
+
+### Example Invocation
+
+\```json
+{
+"TaskName": "Validating Qoder PAT Configuration UI",
+"TaskSummary": "Validates the Qoder provider configuration modal",
+"Task": "Go to http://192.168.0.15:20128/dashboard. Click on the 'Providers' tab. Find 'Qoder' in the list. Click 'Add Token' or 'Configure'. Type 'test_token' and submit. Return when done.",
+"RecordingName": "qoder_pat_ui_validation"
+}
+\```

.agents/workflows/deploy-vps-akamai.md

@@ -0,0 +1,39 @@
+---
+description: Deploy the latest OmniRoute code to the Akamai VPS (69.164.221.35)
+---
+
+# Deploy to Akamai VPS Workflow
+
+Deploy OmniRoute to the Akamai VPS using `npm pack + scp` + PM2.
+
+**Akamai VPS:** `69.164.221.35`
+**Process manager:** PM2 (`omniroute`)
+**Port:** `20128`
+
+## Steps
+
+### 1. Build + pack locally
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
+```
+
+### 2. Copy to Akamai VPS and install
+
+// turbo-all
+
+```bash
+scp omniroute-*.tgz root@69.164.221.35:/tmp/
+```
+
+```bash
+ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Akamai done'"
+```
+
+### 3. Verify the deployment
+
+```bash
+curl -s -o /dev/null -w 'AKAMAI HTTP %{http_code}\n' http://69.164.221.35:20128/
+```

.agents/workflows/deploy-vps-both.md

@@ -0,0 +1,49 @@
+---
+description: Deploy the latest OmniRoute code to BOTH the Akamai VPS and the Local VPS
+---
+
+# Deploy to VPS (Both) Workflow
+
+Deploy OmniRoute to the production VPSs using `npm pack + scp` + PM2.
+
+**Akamai VPS:** `69.164.221.35`
+**Local VPS:** `192.168.0.15`
+**Process manager:** PM2 (`omniroute`)
+**Port:** `20128`
+**PM2 entry:** `/usr/lib/node_modules/omniroute/app/server.js`
+
+> [!IMPORTANT]
+> The npm registry rejects packages > 100MB, so deployment uses **npm pack + scp**.
+
+## Steps
+
+### 1. Build + pack locally
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
+```
+
+### 2. Copy to both VPS and install
+
+// turbo-all
+
+```bash
+scp omniroute-*.tgz root@69.164.221.35:/tmp/ && scp omniroute-*.tgz root@192.168.0.15:/tmp/
+```
+
+```bash
+ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Akamai done'"
+```
+
+```bash
+ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
+```
+
+### 3. Verify the deployment
+
+```bash
+curl -s -o /dev/null -w 'AKAMAI HTTP %{http_code}\n' http://69.164.221.35:20128/
+curl -s -o /dev/null -w 'LOCAL HTTP %{http_code}\n' http://192.168.0.15:20128/
+```

.agents/workflows/deploy-vps-local.md

@@ -0,0 +1,39 @@
+---
+description: Deploy the latest OmniRoute code to the Local VPS (192.168.0.15)
+---
+
+# Deploy to Local VPS Workflow
+
+Deploy OmniRoute to the Local VPS using `npm pack + scp` + PM2.
+
+**Local VPS:** `192.168.0.15`
+**Process manager:** PM2 (`omniroute`)
+**Port:** `20128`
+
+## Steps
+
+### 1. Build + pack locally
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
+```
+
+### 2. Copy to Local VPS and install
+
+// turbo-all
+
+```bash
+scp omniroute-*.tgz root@192.168.0.15:/tmp/
+```
+
+```bash
+ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
+```
+
+### 3. Verify the deployment
+
+```bash
+curl -s -o /dev/null -w 'LOCAL HTTP %{http_code}\n' http://192.168.0.15:20128/
+```

.agents/workflows/generate-release.md

@@ -0,0 +1,284 @@
+---
+description: Create a new release, bump version up to 1.x.10 threshold, update changelog, and manage Pull Requests
+---
+
+# Generate Release Workflow
+
+Bump version, finalize CHANGELOG, commit, open a **PR to main** and wait for user confirmation before tagging, publishing, and deploying.
+
+> **VERSION RULE: Always use PATCH bumps (2.x.y → 2.x.y+1)**
+> NEVER use `npm version minor` or `npm version major`.
+> Always use: `npm version patch --no-git-tag-version`
+> The threshold rule: when `y` reaches 10, bump to `2.(x+1).0` — e.g. `2.1.10` → `2.2.0`.
+
+> **🔴 SINGLE BRANCH RULE**: The `release/vX.Y.Z` branch is the **ONLY** development branch for the entire release cycle. ALL work — bug fixes, feature implementations, PR integrations, issue resolutions — MUST be committed directly on this branch. Never create separate `fix/`, `feat/`, or topic branches. When running `/resolve-issues`, `/implement-features`, or `/review-prs`, always work on the current release branch.
+
+---
+
+## ⚠️ Two-Phase Flow
+
+```
+Phase 1 (automated): bump → docs → i18n → commit → push → open PR
+  ↕  🛑 STOP: Notify user, wait for PR confirmation
+Phase 2 (post-merge): tag → publish → GitHub release → Docker → deploy
+```
+
+**NEVER push directly to main or create tags before the user confirms the PR.**
+
+---
+
+## Phase 0: Security Verification (MANDATORY)
+
+Before creating the release, you must ensure the codebase and supply chain are secure and free of known vulnerabilities.
+
+1. **Run Local Dependencies Audit:**
+
+   ```bash
+   npm audit
+   ```
+
+   _Fix any `high` or `critical` vulnerabilities identified._
+
+2. **Check GitHub CodeQL & Dependabot Alerts:**
+   Navigate to the repository's **Security** tab on GitHub, or use the project's `vulnerability-scanner` skill to analyze active alerts. Ensure all static analysis findings (e.g., prototype pollution, insecure randomness, ReDoS, shell injections) are addressed and logically committed on a target branch.
+
+---
+
+## Phase 1: Pre-Merge
+
+### 1. Create release branch
+
+```bash
+git checkout -b release/v2.x.y
+```
+
+### 2. Determine new version
+
+Check current version in `package.json` and increment the **patch** number only:
+
+```bash
+grep '"version"' package.json
+```
+
+Version format: `2.x.y` — examples:
+
+- `2.1.2` → `2.1.3` (patch)
+- `2.1.9` → `2.1.10` (patch)
+- `2.1.10` → `2.2.0` (minor threshold — do manually with `sed`)
+
+> **⚠️ ATOMIC COMMIT RULE — Version bump MUST happen before committing feature files.**
+>
+> **CORRECT order:**
+>
+> 1. `npm version patch --no-git-tag-version` ← bump first
+> 2. implement features / fix bugs
+> 3. `git add -A && git commit -m "chore(release): v2.x.y — all changes in ONE commit"`
+>
+> **OR if features are already staged:**
+>
+> 1. implement features (do NOT commit yet)
+> 2. `npm version patch --no-git-tag-version` ← bump before committing
+> 3. `git add -A && git commit -m "chore(release): v2.x.y — all changes in ONE commit"`
+>
+> **NEVER do this (creates version mismatch in git history):**
+>
+> - ~~commit features → then bump version → commit package.json separately~~
+>
+> This ensures that `git show v2.x.y` always contains both code changes and the version bump together.
+> The GitHub release tag will point to a commit that includes ALL changes for that version.
+
+### 3. Regenerate lock file (REQUIRED after version bump)
+
+**Mandatory** — skipping causes `@swc/helpers` lock mismatch and CI failures:
+
+```bash
+npm install
+```
+
+### 4. Finalize CHANGELOG.md
+
+Replace `[Unreleased]` header with the new version and date.
+Keep an empty `## [Unreleased]` section above it.
+
+```markdown
+## [Unreleased]
+
+---
+
+## [2.x.y] — YYYY-MM-DD
+```
+
+### 5. Update openapi.yaml version ⚠️ MANDATORY
+
+> **CI will fail** if `docs/openapi.yaml` version ≠ `package.json` version (`check:docs-sync` enforces this).
+
+// turbo
+
+```bash
+VERSION=$(node -p "require('./package.json').version")
+sed -i "s/  version: .*/  version: $VERSION/" docs/openapi.yaml
+echo "✓ openapi.yaml → $VERSION"
+
+for dir in electron open-sse; do
+  if [ -d "$dir" ] && [ -f "$dir/package.json" ]; then
+    (cd "$dir" && npm version "$VERSION" --no-git-tag-version --allow-same-version > /dev/null)
+    echo "✓ $dir/package.json → $VERSION"
+  fi
+done
+# Re-run install to assert the workspace lockfile is updated
+npm install
+```
+
+### 6. Update README.md and i18n docs
+
+Run `/update-docs` workflow steps to:
+
+- Update feature table rows in `README.md`
+- Sync changes to all 29 language `docs/i18n/*/README.md` files
+- Update `docs/FEATURES.md` if Settings section changed
+
+### 7. Run tests
+
+// turbo
+
+```bash
+npm test
+```
+
+All tests must pass before creating the PR.
+
+### 8. Stage, commit, and push
+
+// turbo-all
+
+```bash
+git add -A
+git commit -m "chore(release): v2.x.y — summary of changes"
+git push origin release/v2.x.y
+```
+
+### 9. Open PR to main
+
+```bash
+gh pr create \
+  --repo diegosouzapw/OmniRoute \
+  --base main \
+  --head release/v2.x.y \
+  --title "chore(release): v2.x.y — summary" \
+  --body "## 🚀 Release v2.x.y
+
+### Changes
+...
+
+### Tests
+- X/X tests pass
+
+### ⚠️ After merging: run Phase 2 steps to tag, publish, and deploy."
+```
+
+### 10. 🛑 STOP — Notify User & Await PR Confirmation
+
+**This is a mandatory stop point.** Use `notify_user` with `BlockedOnUser: true`:
+
+Inform the user:
+
+- PR URL
+- Summary of changes
+- Test results
+- List of files changed
+
+**DO NOT proceed to Phase 2 until the user confirms the PR looks good and merges it.**
+
+---
+
+## Phase 2: Post-Merge (only after user confirms)
+
+> Run these steps only AFTER the user has merged the PR.
+
+### 11. Create Git Tag and GitHub Release (MANDATORY)
+
+// turbo
+
+```bash
+git checkout main
+git pull origin main
+VERSION=$(node -p "require('./package.json').version")
+
+# Extracts the changelog section for this version
+NOTES=$(awk "/^## \\[$VERSION\\]/{flag=1; next} /^## \\[[0-9]+/{if(flag) exit} flag" CHANGELOG.md | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+if [ -z "$NOTES" ]; then NOTES="OmniRoute v$VERSION Release"; fi
+
+git tag -a "v$VERSION" -m "Release v$VERSION"
+git push origin --tags
+gh release create "v$VERSION" --title "v$VERSION" --notes "$NOTES" --target main
+```
+
+### 14. 🐳 Trigger Docker Hub build (MANDATORY — keep npm and Docker in sync)
+
+> **CRITICAL**: Docker Hub and npm MUST always publish the same version.
+> The Docker image is built automatically via GitHub Actions when a new tag is pushed.
+> After pushing the tag in step 11-12, **verify the workflow runs**:
+
+```bash
+# Verify the Docker workflow triggered
+gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 3
+
+# Wait for the Docker build to complete (usually 5–10 min)
+gh run watch --repo diegosouzapw/OmniRoute
+
+# After completion, verify on Docker Hub:
+# https://hub.docker.com/r/diegosouzapw/omniroute/tags
+```
+
+If the Docker build was not triggered automatically, trigger it manually:
+
+```bash
+gh workflow run docker-publish.yml --repo diegosouzapw/OmniRoute --ref v2.x.y
+```
+
+### 15. Deploy to BOTH VPS environments (MANDATORY)
+
+> Always deploy to **both** environments after every release.
+> See `/deploy-vps` workflow for detailed steps.
+
+```bash
+# Build and pack locally
+cd /home/diegosouzapw/dev/proxys/9router && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
+
+# Deploy to LOCAL VPS (192.168.0.15)
+scp omniroute-*.tgz root@192.168.0.15:/tmp/
+ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
+
+# Deploy to AKAMAI VPS (69.164.221.35)
+scp omniroute-*.tgz root@69.164.221.35:/tmp/
+ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Akamai done'"
+
+# Verify both
+curl -s -o /dev/null -w "LOCAL:  HTTP %{http_code}\n" http://192.168.0.15:20128/
+curl -s -o /dev/null -w "AKAMAI: HTTP %{http_code}\n" http://69.164.221.35:20128/
+```
+
+### 16. Clean up release branch
+
+```bash
+git branch -d release/v2.x.y
+```
+
+---
+
+## Notes
+
+- Always run `/update-docs` BEFORE this workflow (ensures CHANGELOG and README are current)
+- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`
+- After npm publish, verify with `npm info omniroute version`
+- Lock file sync errors are caused by skipping `npm install` after version bump
+- Use `gh auth switch -u diegosouzapw` if git push fails with wrong account
+
+## Known CI Pitfalls
+
+| CI failure                                                                | Cause                                                    | Fix                                                                    |
+| ------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `[docs-sync] FAIL - OpenAPI version differs from package.json`            | Skipped step 5 — `docs/openapi.yaml` version not updated | Run step 5 (`sed -i ...`) and commit                                   |
+| `[docs-sync] FAIL - CHANGELOG.md first section must be "## [Unreleased]"` | `## [Unreleased]` missing or not at top of CHANGELOG     | Add `## [Unreleased]\n\n---\n` before the first versioned `## [x.y.z]` |
+| Electron Linux `.deb` build fails (`FpmTarget` error)                     | `fpm` Ruby gem not installed on `ubuntu-latest` runner   | Already fixed in `electron-release.yml` (`gem install fpm` step)       |
+| Docker Hub `502 error writing layer blob`                                 | Transient Docker Hub network error during ARM64 push     | Re-run the Docker publish workflow; no code change needed              |

.agents/workflows/implement-features.md

@@ -2,130 +2,705 @@
 description: Analyze open feature request issues, implement viable ones on dedicated branches, and respond to authors
 ---
 
-# /implement-features — Feature Request Implementation Workflow
+# /implement-features — Feature Request Harvest, Research & Implementation Workflow
 
 ## Overview
 
-Fetches open feature request issues, analyzes each against the current codebase, implements viable ones on dedicated branches, and responds to authors with results. Does NOT merge to main — leaves branches for author validation.
+A **5-phase** workflow that systematically harvests feature requests from GitHub issues, creates structured idea files, researches solutions across the internet and Git repositories, presents a consolidated report for user approval, then generates detailed implementation plans and executes them.
 
-## Steps
+**Output directory structure:**
 
-### 1. Identify the Repository
+```
+_ideia/
+├── viable/                  # Features approved for implementation
+│   ├── need_details/        # ❓ Good idea but waiting for author clarification (issues stay OPEN)
+│   │   └── 1015-warp-terminal-mitm.md
+│   ├── 1046-native-playground.md           # ✅ Ready — researched and planned
+│   └── 1046-native-playground.requirements.md
+├── defer/                   # ⏭️ Good ideas deferred for future cycles (issues CLOSED)
+│   └── 1041-smart-auto-combos.md
+└── notfit/                  # ❌ Out of scope / already exists (issues CLOSED)
+    └── 945-telegram-integration.md
+
+_tasks/features-vX.Y.Z/   # Implementation plans (per-release)
+└── 1046-native-playground.plan.md
+```
+
+> **LIFECYCLE RULE:** `viable/` files are **DELETED** once the feature is implemented — they are not moved. Only unimplemented features live in `viable/` (or `viable/need_details/`). Files in `defer/` and `notfit/` remain as permanent reference.
+
+> **BRANCH RULE**: All implementation work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `feat/` branches. If no release branch exists yet, create one first using `/generate-release` Phase 1 steps 1–5.
+
+---
+
+## Phase 1 — Harvest: Collect & Catalog Feature Ideas
+
+### 1.1 Identify the Repository
 
 // turbo
 
-- Run: `git -C <project_root> remote get-url origin` to extract owner/repo
+- Run: `git -C <project_root> remote get-url origin` to extract owner/repo.
 
-### 2. Fetch Open Feature Request Issues
+### 1.2 Ensure Release Branch Exists
 
 // turbo
 
-- Run: `gh issue list --repo <owner>/<repo> --state open --limit 50 --json number,title,labels,body,comments,createdAt,author`
-- Filter for issues that are feature requests (label `enhancement`/`feature`, or body describes new functionality, or previously classified as feature request)
-- Sort by oldest first
+Before doing any work, ensure you are on the current release branch:
 
-### 3. Analyze Each Feature Request
+```bash
+# Check current branch
+git branch --show-current
 
-For each feature request issue, perform a **two-level analysis**:
+# If on main, determine next version and create the release branch
+VERSION=$(node -p "require('./package.json').version")
+NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
+git checkout -b release/v$NEXT
+npm version patch --no-git-tag-version
+npm install
+```
 
-#### Level 1 — Viability Assessment
+If already on a `release/vX.Y.Z` branch, continue working there.
 
-Ask yourself:
+### 1.3 Fetch ALL Open Feature Requests
 
-- Does this feature align with the project's goals and architecture?
-- Is the request technically feasible with the current codebase?
-- Does it duplicate existing functionality?
-- Would it introduce breaking changes or security risks?
-- Is there enough detail to implement it?
+// turbo-all
+
+**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. You MUST use the two-step approach below.
+
+**Step 1 — Get Issue numbers only** (small output, never truncated):
+
+```bash
+# Fetch issues with feature/enhancement labels
+gh issue list --repo <owner>/<repo> --state open -l "enhancement" --limit 500 --json number --jq '.[].number'
+
+# Also check for [Feature] in title (common pattern when no labels are set)
+gh issue list --repo <owner>/<repo> --state open --limit 500 --json number,title --jq '.[] | select(.title | test("\\[Feature\\]|\\[feature\\]|feature request"; "i")) | .number'
+```
+
+- Merge both lists, deduplicate. Count and confirm the total.
+
+**Step 2 — Fetch full metadata for each Issue** (one call per issue):
+
+```bash
+gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author,assignees
+```
+
+- Read the **entire body** — including description, use cases, screenshots, mockups, and any embedded images.
+- Read **ALL comments** — community discussion, agreements, restrictions, owner responses, and linked PRs.
+- **Images**: If the body or comments contain image URLs (`![...](...)` or `https://...png/jpg/gif`), note them — they may contain UI mockups, wireframes, or architecture diagrams that are essential to understanding the request.
+- You may batch these into parallel calls (up to 4 at a time).
+- Sort by oldest first (FIFO).
+
+### 1.4 Create Idea Files (initially in `_ideia/` root)
+
+For each feature request, create a structured idea file in `<project_root>/_ideia/`:
+
+**Filename convention**: `<NUMBER>-<kebab-case-short-title>.md`
+Example: `1046-native-playground.md`, `1041-smart-auto-combos.md`
+
+#### 1.4a — If the idea file does NOT exist yet, create it:
+
+```markdown
+# Feature: <Title from Issue>
+
+> GitHub Issue: #<NUMBER> — opened by @<author> on <date>
+> Status: 📋 Cataloged | Priority: TBD
+
+## 📝 Original Request
+
+<Paste the FULL issue body here, preserving all formatting, images, and code blocks>
+
+## 💬 Community Discussion
+
+<Summarize ALL comments chronologically, noting who said what and any decisions or objections raised>
+
+### Participants
+
+- @<author> — Original requester
+- @<commenter1> — <brief role/opinion>
+- ...
+
+### Key Points
+
+- <bullet list of the most important discussion points>
+- <agreements reached>
+- <objections raised>
+
+## 🎯 Refined Feature Description
+
+<YOUR interpretation and enrichment of the feature request. Expand on what was asked, fill in logical gaps, provide concrete examples of how it would work. This section should be MORE detailed and clearer than the original request.>
+
+### What it solves
+
+- <problem 1>
+- <problem 2>
+
+### How it should work (high level)
+
+1. <step 1>
+2. <step 2>
+3. ...
+
+### Affected areas
+
+- <list of codebase areas, modules, files likely affected>
+
+## 📎 Attachments & References
+
+- <any image URLs, mockup links, or external references from the issue>
+
+## 🔗 Related Ideas
+
+- <links to related \_ideia/ files if any overlap found>
+```
+
+#### 1.4b — If the idea file ALREADY exists, update it:
+
+- Append new comments from the issue to the **Community Discussion** section.
+- Update the **Refined Feature Description** if new information changes the understanding.
+- Add any new **Related Ideas** cross-references found.
+- **Do NOT overwrite** existing content — append and enrich it.
+
+### 1.5 Cross-Reference & Deduplication
+
+After processing all issues:
+
+- Scan all `_ideia/*.md` files for overlapping features.
+- If two features are substantially the same, add `🔗 Related Ideas` cross-references to both.
+- If one is a strict subset of another, note it in the smaller file: `> ℹ️ This feature is a subset of #<OTHER_NUMBER>. Consider implementing together.`
+
+---
+
+## Phase 2 — Research: Find Solutions & Build Requirements
+
+For each cataloged idea that is **viable** (aligns with the project's goals):
+
+### 2.1 Viability Pre-Check
+
+Before investing in research, quickly assess:
+
+- [ ] Does this feature align with the project's goals and architecture?
+- [ ] Is it technically feasible with the current codebase?
+- [ ] Does it duplicate existing functionality?
+- [ ] Would it introduce breaking changes or security risks?
+- [ ] Is there enough detail to understand what's needed?
 
 **Verdict options:**
 
-1. ✅ **VIABLE** — Makes sense, enough detail to implement → Go to Level 2
-2. ❓ **NEEDS MORE INFO** — Good idea but insufficient detail → Post comment asking for specifics
-3. ❌ **NOT VIABLE** — Doesn't fit the project or is fundamentally flawed → Post comment explaining why, close issue
+| Verdict               | When                                  | Action                      |
+| --------------------- | ------------------------------------- | --------------------------- |
+| ✅ **VIABLE**         | Good idea, enough context             | Proceed to Research         |
+| ❓ **NEEDS DETAIL**   | Good idea, insufficient spec          | Skip research, ask author   |
+| ⏭️ **DEFER**          | Good idea, too complex for this cycle | Catalog only, skip research |
+| ❌ **NOT FIT**        | Doesn't fit the project               | Explain why                 |
+| 🔁 **ALREADY EXISTS** | Feature already implemented           | Point to existing feature   |
 
-#### Level 2 — Implementation (only for VIABLE features)
+### 2.2 Internet Research (for VIABLE features)
 
-1. **Research** — Read all related source files to understand the current architecture
-2. **Design** — Plan the implementation, filling gaps in the original request
-3. **Create branch** — Name format: `feat/issue-<NUMBER>-<short-slug>`
-   ```bash
-   git checkout main
-   git pull origin main
-   git checkout -b feat/issue-<NUMBER>-<short-slug>
-   ```
-4. **Implement** — Build the complete solution following project patterns
-5. **Build** — Run `npm run build` to verify compilation
-6. **Commit** — Commit with: `feat: <description> (#<NUMBER>)`
-7. **Push** — Push the branch: `git push -u origin feat/issue-<NUMBER>-<short-slug>`
-8. **Return to main** — `git checkout main`
+For each viable feature, perform systematic research:
 
-### 4. Respond to Authors
+**Step 1 — Web search for similar implementations:**
 
-#### For VIABLE (implemented) features:
+```
+search_web("how to implement <feature description> in <tech stack>")
+search_web("<feature keyword> implementation nextjs typescript 2025 2026")
+search_web("<feature keyword> open source library npm")
+```
+
+**Step 2 — Find reference Git repositories:**
+
+```
+search_web("site:github.com <feature keyword> <tech stack> stars:>100")
+search_web("github <feature keyword> implementation recently updated 2026")
+```
+
+- Find **up to 10 relevant repositories**, sorted by most recently updated.
+- For each repository:
+  - Note the repo URL, star count, last commit date
+  - Read its README and relevant source files via `read_url_content`
+  - Extract the architectural approach, patterns used, and key code snippets
+
+**Step 3 — Read API docs and standards:**
+
+If the feature involves an external API, protocol, or standard:
+
+- Find and read the official documentation
+- Note version requirements, authentication patterns, rate limits
+
+### 2.3 Create Requirements File
+
+For each researched feature, create a requirements file alongside its idea file:
+
+**Filename**: `<NUMBER>-<kebab-case-short-title>.requirements.md`
+
+```markdown
+# Requirements: <Feature Title>
+
+> Feature Idea: [#<NUMBER>](./<NUMBER>-<kebab-case-short-title>.md)
+> Research Date: <YYYY-MM-DD>
+> Verdict: ✅ VIABLE
+
+## 🔍 Research Summary
+
+<Brief summary of what was found during research>
+
+## 📚 Reference Implementations
+
+| #   | Repository       | Stars | Last Updated | Approach | Relevance    |
+| --- | ---------------- | ----- | ------------ | -------- | ------------ |
+| 1   | [repo/name](url) | ⭐ N  | YYYY-MM-DD   | <brief>  | High/Med/Low |
+| 2   | ...              |       |              |          |              |
+
+### Key Patterns Found
+
+- <pattern 1 with code snippet or link>
+- <pattern 2>
+
+## 📐 Proposed Solution Architecture
+
+### Approach
+
+<Describe the chosen approach based on research findings>
+
+### New Files
+
+| File                  | Purpose       |
+| --------------------- | ------------- |
+| `path/to/new/file.ts` | <description> |
+
+### Modified Files
+
+| File                       | Changes        |
+| -------------------------- | -------------- |
+| `path/to/existing/file.ts` | <what changes> |
+
+### Database Changes
+
+- <migrations needed, if any>
+
+### API Changes
+
+- <new/modified endpoints, if any>
+
+### UI Changes
+
+- <new/modified pages/components, if any>
+
+## ⚙️ Implementation Effort
+
+- **Estimated complexity**: Low / Medium / High / Very High
+- **Estimated files changed**: ~N
+- **Dependencies needed**: <new npm packages, if any>
+- **Breaking changes**: Yes/No — <details>
+- **i18n impact**: <number of new translation keys>
+- **Test coverage needed**: <brief description>
+
+## ⚠️ Open Questions
+
+- <question 1>
+- <question 2>
+
+## 🔗 External References
+
+- <documentation URLs>
+- <API references>
+```
+
+---
+
+## Phase 2.5 — Organize & Respond: Sort Files and Post GitHub Comments
+
+### 2.5.1 Create Directory Structure
 
 // turbo
-Post a comment on the issue:
-
-````markdown
-## ✅ Feature Implemented!
-
-Hi @<author>! We've analyzed your request and implemented it on a dedicated branch.
-
-**Branch:** `feat/issue-<NUMBER>-<short-slug>`
-
-### What was implemented:
-
-- <bullet list of what was done>
-
-### How to try it:
 
 ```bash
-git fetch origin
-git checkout feat/issue-<NUMBER>-<short-slug>
+mkdir -p <project_root>/_ideia/viable
+mkdir -p <project_root>/_ideia/viable/need_details
+mkdir -p <project_root>/_ideia/defer
+mkdir -p <project_root>/_ideia/notfit
+```
+
+### 2.5.2 Move Idea Files to Category Subdirectories
+
+After classification, move EVERY idea file to its correct subdirectory:
+
+```bash
+# ✅ VIABLE — move idea + requirements files
+mv _ideia/<NUMBER>-*.md _ideia/viable/
+mv _ideia/<NUMBER>-*.requirements.md _ideia/viable/
+
+# ❓ NEEDS DETAIL — viable but waiting for author response
+mv _ideia/<NUMBER>-*.md _ideia/viable/need_details/
+
+# ⏭️ DEFER — move idea files only
+mv _ideia/<NUMBER>-*.md _ideia/defer/
+
+# ❌ NOT FIT & 🔁 ALREADY EXISTS — move idea files only
+mv _ideia/<NUMBER>-*.md _ideia/notfit/
+```
+
+No files should remain in `_ideia/` root after this step (except subdirectories).
+
+### 2.5.3 Post GitHub Comments by Category
+
+**Each category has a specific comment template and action:**
+
+---
+
+#### For 🔁 ALREADY EXISTS — Comment + CLOSE issue
+
+// turbo
+
+The feature already exists in the system. Explain WHERE it is and HOW to use it.
+
+```markdown
+Hi @<author>! Thanks for the suggestion! 🙏
+
+Great news — this functionality **already exists** in OmniRoute:
+
+**📍 Where to find it:** <exact dashboard path or settings location>
+
+**🔧 How to use it:**
+
+1. <step 1>
+2. <step 2>
+3. <step 3>
+
+If you have any trouble finding or using it, feel free to ask in a Discussion. We're always happy to help!
+
+Closing this as the feature is already available. 🎉
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ⏭️ DEFER — Comment + CLOSE issue
+
+// turbo
+
+Thank the user, explain the idea was cataloged, and that we'll study it before implementing.
+
+```markdown
+Hi @<author>! Thanks for this thoughtful feature request! 🙏
+
+We really appreciate the detailed proposal. We've **cataloged your idea** and it's now part of our improvement backlog.
+
+Due to the **significant architectural impact** of this feature, we'll need to conduct thorough use-case studies and architectural analysis before we start development. This ensures we build it right and don't introduce regressions.
+
+**What happens next:**
+
+- Your idea is saved in our internal feature backlog
+- We'll conduct architecture studies when this area is prioritized
+- We'll notify you here when development begins
+
+Thank you for contributing to OmniRoute's roadmap! Your input helps shape the product. 🚀
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ❌ NOT FIT — Comment + CLOSE issue
+
+// turbo
+
+Politely explain why the feature doesn't fit the project scope.
+
+```markdown
+Hi @<author>! Thanks for the suggestion! 🙏
+
+After careful analysis, we've determined that this feature **falls outside OmniRoute's core scope** as a proxy/router.
+
+**Reason:** <explain why — e.g., "Telegram integration belongs in the application/orchestrator layer that consumes OmniRoute's API, not inside the router itself.">
+
+**Alternative:** <suggest an alternative approach if possible>
+
+We appreciate you thinking of ways to improve OmniRoute! If you'd like to discuss this further, feel free to open a Discussion. 🙏
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ❓ NEEDS DETAIL — Comment (keep OPEN)
+
+// turbo
+
+Ask for the specific missing details needed.
+
+```markdown
+Hi @<author>! Thanks for the feature request — it's an interesting idea and we'd love to explore it further. 🙏
+
+To move forward, we need a few more details:
+
+1. <specific question 1>
+2. <specific question 2>
+3. <specific question 3>
+
+If you know of any **open-source projects or repositories** that implement something similar, please share links — it would help us design the best solution.
+
+Looking forward to your response! 🚀
+```
+
+---
+
+#### For ✅ VIABLE — Comment (keep OPEN)
+
+// turbo
+
+Thank the user, confirm we've cataloged their idea, and explain it may be implemented in future versions.
+
+```markdown
+Hi @<author>! Thanks for the great feature suggestion! 🙏
+
+We've analyzed your request and it aligns well with OmniRoute's roadmap. We've **cataloged this feature** and it's in our implementation backlog.
+
+**Status:** 📋 Cataloged for future implementation
+
+This feature may be included in upcoming releases. We'll **respond to this issue and tag you** as soon as implementation begins so you can test it.
+
+Thank you for helping improve OmniRoute! 🚀
+```
+
+**⚠️ Do NOT close viable issues — they remain OPEN for tracking.**
+
+---
+
+## Phase 3 — Report: Present Findings to User
+
+### 3.1 🛑 MANDATORY STOP — Present Consolidated Report
+
+After completing Phase 1, Phase 2, and Phase 2.5, **STOP and present the following report** in the chat. Do NOT proceed to implementation.
+
+Present a structured report containing:
+
+#### 3.1a — Feature Summary Table
+
+| #   | Issue | Title | Verdict         | Location                      | Action                        |
+| --- | ----- | ----- | --------------- | ----------------------------- | ----------------------------- |
+| 1   | #N    | Title | ✅ VIABLE       | `_ideia/viable/`              | Issue OPEN, comment posted    |
+| 2   | #N    | Title | ⏭️ DEFER        | `_ideia/defer/`               | Issue CLOSED with explanation |
+| 3   | #N    | Title | ❌ NOT FIT      | `_ideia/notfit/`              | Issue CLOSED with explanation |
+| 4   | #N    | Title | 🔁 EXISTS       | `_ideia/notfit/`              | Issue CLOSED with guidance    |
+| 5   | #N    | Title | ❓ NEEDS DETAIL | `_ideia/viable/need_details/` | Issue OPEN, questions posted  |
+
+#### 3.1b — Viable Features Detail
+
+For each VIABLE feature, provide a brief paragraph:
+
+- What was found during research
+- The proposed approach
+- Key risks or unknowns
+- Which reference repositories were most useful
+
+#### 3.1c — Issues Requiring Author Feedback
+
+For features marked ❓ NEEDS DETAIL, list:
+
+- What specific information is missing
+- What examples or repository references would help
+
+#### 3.1d — Ask for User Confirmation
+
+End the report with:
+
+> **Ready to proceed with implementation?**
+>
+> - Reply **"sim"** or **"yes"** to generate full implementation plans for all VIABLE features.
+> - Reply with specific issue numbers to select only certain features.
+> - Reply **"não"** or **"no"** to stop here.
+
+---
+
+## Phase 4 — Plan: Generate Implementation Plans (after user says "yes")
+
+> **⚠️ Do NOT enter this phase without explicit user approval from Phase 3.**
+
+### 4.1 Create Task Directory
+
+```bash
+mkdir -p <project_root>/_tasks/features-vX.Y.Z/
+```
+
+### 4.2 Generate One Implementation Plan Per Feature
+
+For each VIABLE feature approved by the user, create:
+
+**Filename**: `_tasks/features-vX.Y.Z/<NUMBER>-<kebab-case-title>.plan.md`
+
+```markdown
+# Implementation Plan: <Feature Title>
+
+> Issue: #<NUMBER>
+> Idea: [\_ideia/viable/<NUMBER>-title.md](../../_ideia/viable/<NUMBER>-title.md)
+> Requirements: [\_ideia/viable/<NUMBER>-title.requirements.md](../../_ideia/viable/<NUMBER>-title.requirements.md)
+> Branch: `release/vX.Y.Z`
+
+## Overview
+
+<Brief description of what will be built>
+
+## Pre-Implementation Checklist
+
+- [ ] Read all related source files listed below
+- [ ] Confirm no conflicts with in-flight PRs
+- [ ] Verify database migration numbering
+
+## Implementation Steps
+
+### Step 1: <Title>
+
+**Files:**
+
+- `path/to/file.ts` — <what to change>
+
+**Details:**
+<Detailed description of the change, including code patterns to follow, function signatures, etc.>
+
+### Step 2: <Title>
+
+...
+
+### Step N: Tests
+
+**New test files:**
+
+- `tests/unit/<test-file>.test.mjs` — <what to test>
+
+**Test cases:**
+
+- [ ] <test case 1>
+- [ ] <test case 2>
+
+### Step N+1: i18n
+
+**Translation keys to add:**
+
+- `<namespace>.<key>` — "<English value>"
+
+### Step N+2: Documentation
+
+- [ ] Update CHANGELOG.md
+- [ ] Update relevant docs/ files
+
+## Verification Plan
+
+1. Run `npm run build` — must pass
+2. Run `npm test` — all tests must pass
+3. Run `npm run lint` — no new errors
+4. <Manual verification steps>
+
+## Commit Plan
+```
+
+feat: <description> (#<NUMBER>)
+
+```
+
+```
+
+### 4.3 Present Plans for Final Approval
+
+Present a summary of all generated plans:
+
+> **Implementation plans generated:**
+>
+> | #   | Feature | Plan File                                | Steps   | Effort |
+> | --- | ------- | ---------------------------------------- | ------- | ------ |
+> | 1   | <title> | `_tasks/features-vX.Y.Z/N-title.plan.md` | N steps | Medium |
+>
+> Reply **"sim"** or **"yes"** to begin implementation of all features.
+> Reply with specific issue numbers to implement only certain ones.
+
+---
+
+## Phase 5 — Execute: Implement the Plans (after user says "yes")
+
+> **⚠️ Do NOT enter this phase without explicit user approval from Phase 4.**
+
+### 5.1 Implement Each Feature
+
+For each approved plan, execute it step by step:
+
+1. **Follow the plan** — implement exactly as specified in the `.plan.md` file
+2. **Build** — Run `npm run build` after each feature to verify compilation
+3. **Test** — Run `npm test` to ensure no regressions
+4. **Commit** — Commit with: `feat: <description> (#<NUMBER>)`
+5. **Update the plan** — Mark completed steps with `[x]` in the plan file
+6. **Continue** — Move to the next feature (do NOT switch branches)
+
+### 5.2 Respond to Authors (Update Viable Issues)
+
+For each implemented feature, **close the issue with a final comment**:
+
+````markdown
+✅ **Implemented in `release/vX.Y.Z`!**
+
+Hi @<author>! Great news — your feature request has been implemented! 🎉
+
+**What was done:**
+
+- <bullet list of what was built>
+
+**How to try it:**
+
+```bash
+git fetch origin && git checkout release/vX.Y.Z
 npm install && npm run dev
 ```
 ````
 
-### Next steps:
+This will be included in the upcoming **vX.Y.Z** release. Feel free to reopen if you spot any issues! 🚀
 
-1. **Test it** — Please verify it works as you expected
-2. **Want to improve it?** — You're welcome to contribute! Just:
-   ```bash
-   git checkout feat/issue-<NUMBER>-<short-slug>
-   # Make your improvements
-   git add -A && git commit -m "improve: <your changes>"
-   git push origin feat/issue-<NUMBER>-<short-slug>
-   ```
-   Then open a Pull Request from your branch to `main` 🎉
-3. **Not quite right?** — Let us know in this issue what needs to change
+````
 
-Looking forward to your feedback! 🚀
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+````
 
+Then **DELETE the idea file** — it has served its purpose:
+
+```bash
+# ✅ Implemented files are DELETED (not moved)
+rm _ideia/viable/<NUMBER>-<title>.md
+rm _ideia/viable/<NUMBER>-<title>.requirements.md  # if exists
 ```
 
-#### For NEEDS MORE INFO:
-// turbo
-Post a comment asking for specific missing details needed to implement, e.g.:
-- "Could you describe the exact behavior when X happens?"
-- "Which API endpoints should be affected?"
-- "Should this apply to all providers or only specific ones?"
+> **Why delete?** `viable/` only holds features that still NEED to be done. Once implemented, the commit history and CHANGELOG are the source of truth. Keeping the file would be confusing.
 
-Add the context of WHY you need each piece of information.
+### 5.3 Finalize & Push
 
-#### For NOT VIABLE:
-// turbo
-Post a polite comment explaining why the feature doesn't fit at this time:
-- If the idea is decent but timing is wrong: "This is an interesting idea, but it doesn't align with our current priorities. Feel free to open a new issue with more details if you'd like us to reconsider."
-- If fundamentally flawed: Explain the technical or architectural reasons why it won't work, suggest alternatives if possible.
-- Close the issue after posting the comment.
+After implementing all approved features:
 
-### 5. Summary Report
-Present a summary report to the user via `notify_user`:
+1. **Update CHANGELOG.md** on the release branch with all new feature entries
+2. Push the release branch: `git push origin release/vX.Y.Z`
+3. Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)
 
-| Issue | Title | Verdict | Branch / Action |
-|---|---|---|---|
-| #N | Title | ✅ Implemented | `feat/issue-N-slug` |
-| #N | Title | ❓ Needs Info | Comment posted |
-| #N | Title | ❌ Not Viable | Closed with explanation |
-```
+### 5.4 Final Summary Report
+
+Present a final summary report to the user:
+
+| Issue | Title | Verdict         | Action                                             | Commit    |
+| ----- | ----- | --------------- | -------------------------------------------------- | --------- |
+| #N    | Title | ✅ Implemented  | Issue closed, idea file deleted                    | `abc1234` |
+| #N    | Title | ⏭️ Deferred     | Issue closed + saved in `_ideia/defer/`            | —         |
+| #N    | Title | ❌ Not Fit      | Issue closed + saved in `_ideia/notfit/`           | —         |
+| #N    | Title | 🔁 Exists       | Issue closed + saved in `_ideia/notfit/`           | —         |
+| #N    | Title | ❓ Needs Detail | Issue OPEN, moved to `_ideia/viable/need_details/` | —         |
+
+Include:
+
+- Total features harvested
+- Total ideas cataloged (`viable/need_details/` + `defer/` + `notfit/`)
+- Total features implemented (idea files deleted, issues closed)
+- Total features deferred
+- Total issues closed
+- Total issues left open (needs detail only — viable are closed after implementation)
+- Test results (pass/fail count)

.agents/workflows/issue-triage.md

@@ -0,0 +1,50 @@
+---
+description: How to respond to GitHub issues with insufficient information
+---
+
+# Issue Triage Workflow
+
+Respond to GitHub issues that need more information before they can be investigated.
+
+## Steps
+
+### 1. Identify issues needing triage
+
+```bash
+gh issue list --state open --limit 20
+```
+
+### 2. Evaluate each issue
+
+Check if the issue has:
+
+- Clear reproduction steps
+- Environment details (OS, Node.js version, OmniRoute version)
+- Error logs/screenshots
+- Expected vs actual behavior
+
+### 3. Respond with triage template
+
+For issues missing information:
+
+```markdown
+Thank you for reporting this issue! To help us investigate, please provide:
+
+1. **OmniRoute version**: (`omniroute --version`)
+2. **Node.js version**: (`node --version`)
+3. **Operating system**: (e.g., Ubuntu 24.04, macOS 15, Windows 11)
+4. **Installation method**: (npm, Docker, source)
+5. **Steps to reproduce**: (exact commands/actions that trigger the issue)
+6. **Error logs**: (paste relevant logs from the console)
+7. **Expected behavior**: (what should happen)
+
+This will help us debug and resolve your issue faster. 🙏
+```
+
+### 4. Label the issue
+
+Add appropriate labels: `needs-info`, `bug`, `enhancement`, `question`, etc.
+
+```bash
+gh issue edit <NUMBER> --add-label "needs-info"
+```

.agents/workflows/resolve-issues.md

@@ -1,12 +1,14 @@
 ---
-description: Fetch all open GitHub issues, analyze bugs, resolve what's possible, triage the rest, then commit and release
+description: Fetch all open GitHub issues, analyze bugs, resolve what's possible, triage the rest, wait for user validation, then commit and release
 ---
 
 # /resolve-issues — Automated Issue Resolution Workflow
 
 ## Overview
 
-This workflow fetches all open issues from the project's GitHub repository, classifies them, analyzes bugs, resolves what can be fixed, triages issues with insufficient information, and generates a release with all fixes.
+This workflow fetches all open issues from the project's GitHub repository, classifies them, analyzes bugs, resolves what can be fixed, and triages issues with insufficient information. **All fixes are committed on the current release branch** (`release/vX.Y.Z`). It does NOT merge or release automatically — the release branch is later merged via PR to main.
+
+> **BRANCH RULE**: All work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `fix/` branches. If no release branch exists yet, create one first using `/generate-release` Phase 1 steps 1–5.
 
 ## Steps
 
@@ -17,15 +19,45 @@ This workflow fetches all open issues from the project's GitHub repository, clas
 - Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
 - Parse the owner and repo name from the URL
 
-### 2. Fetch All Open Issues
+### 2. Ensure Release Branch Exists
 
 // turbo
 
-- Run: `gh issue list --repo <owner>/<repo> --state open --limit 100 --json number,title,labels,body,comments,createdAt,author`
-- Parse the JSON output to get a list of all open issues
-- Sort by oldest first (FIFO)
+Before doing any work, ensure you are on the current release branch:
 
-### 3. Classify Each Issue
+```bash
+# Check current branch
+git branch --show-current
+
+# If on main, determine next version and create the release branch
+VERSION=$(node -p "require('./package.json').version")
+NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
+git checkout -b release/v$NEXT
+npm version patch --no-git-tag-version
+npm install
+```
+
+If already on a `release/vX.Y.Z` branch, continue working there.
+
+### 3. Fetch All Open Issues
+
+// turbo-all
+
+**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. You MUST use the two-step approach below to guarantee **all** issues are fetched.
+
+**Step 3a — Get Issue numbers only** (small output, never truncated):
+
+- Run: `gh issue list --repo <owner>/<repo> --state open --limit 500 --json number --jq '.[].number'`
+- This outputs one issue number per line. Count them and confirm total.
+
+**Step 3b — Fetch full metadata for each Issue** (one call per issue):
+
+- For each issue number from step 3a, run:
+  `gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author`
+- You may batch these into parallel calls (up to 4 at a time).
+- Sort by oldest first (FIFO).
+
+### 4. Classify Each Issue
 
 For each issue, determine its type:
 
@@ -36,65 +68,111 @@ For each issue, determine its type:
 
 Focus ONLY on **Bugs** for resolution. Feature requests and questions should be skipped with a note in the final report.
 
-### 4. Analyze Each Bug — For each bug issue:
+### 5. Deep-Read Each Bug Issue (One-by-One Analysis)
 
-#### 4a. Check Information Sufficiency
+**IMPORTANT**: Read each bug issue thoroughly, one at a time, before moving to the next. This is NOT a batch process — each issue needs focused attention.
 
-Verify the issue contains enough information to reproduce and fix:
+#### 5a. Understand the Problem
+
+For each bug issue, perform the full analysis:
+
+1. **Read the entire body** — including Description, Steps to Reproduce, Expected/Actual Behavior, Error Logs, and Screenshots
+2. **Read ALL comments** — including bot triage comments (Kilo, etc.) and owner/community responses. Pay attention to:
+   - Whether someone already responded with a fix
+   - Whether a community member confirmed the issue is resolved
+   - Whether the issue was marked as duplicate by a bot
+3. **Identify the claimed error** — extract the exact error message, status code, and provider/model involved
+
+#### 5b. Check Information Sufficiency
+
+Verify the issue contains enough to act on:
 
 - [ ] Clear description of the problem
-- [ ] Steps to reproduce
-- [ ] Error messages or logs
+- [ ] Steps to reproduce OR error logs
+- [ ] Provider/model/version information
 - [ ] Expected vs actual behavior
 
-#### 4b. If Information Is INSUFFICIENT
+#### 5c. Determine Issue Disposition
 
-Call the `/issue-triage` workflow (located at `~/.gemini/antigravity/global_workflows/issue-triage.md`):
-// turbo
+For each bug, classify into one of 5 actions:
 
-- Post a comment asking for more details using `gh issue comment`
-- Add `needs-info` label using `gh issue edit`
-- Mark this issue as **DEFERRED** and move to the next one
+| Disposition                  | When to Apply                                                                               | Action                                              |
+| ---------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| **✅ CLOSE — Already Fixed** | Owner responded with fix + no user follow-up, OR community confirmed fix                    | Close with comment citing which version fixed it    |
+| **✅ CLOSE — Duplicate**     | Bot flagged >85% similarity + user provides no new info                                     | Close referencing the original issue                |
+| **📝 RESPOND — Needs Info**  | Issue is real but missing critical reproduction details                                     | Comment asking for specifics per `/issue-triage`    |
+| **📝 RESPOND — User Config** | Error is caused by unsupported env (Node version, wrong model path, missing API enablement) | Comment explaining the user-side fix                |
+| **🔧 FIX — Code Change**     | Root cause is confirmed in the codebase                                                     | Research, implement, test, commit on release branch |
 
-#### 4c. If Information Is SUFFICIENT
+#### 5d. For "FIX — Code Change" Issues
 
-Proceed with resolution:
+Before coding, perform deep source analysis:
 
-1. **Research** — Search the codebase for files related to the issue
-2. **Root Cause** — Identify the root cause by reading the relevant source files
-3. **Implement Fix** — Apply the fix following existing code patterns and conventions
-4. **Test** — Build the project and run tests to verify the fix
-5. **Commit** — Commit with message format: `fix: <description> (#<issue_number>)`
+1. **Search the codebase** — `grep_search` for error strings, relevant function names, affected files
+2. **Search the web** — for upstream API changes, SDK updates, or breaking changes that explain the bug
+3. **Read the full source file** — don't rely on grep snippets; understand the surrounding logic
+4. **Verify the root cause** — confirm the bug is reproducible based on the code, not just a user misconfiguration
+5. **Implement the fix** — follow existing code patterns and conventions
+6. **Run tests** — `node --import tsx/esm --test tests/unit/*.test.mjs` (must pass 100%)
+7. **Commit** — `fix: <description> (#<issue_number>)`
 
-### 5. Commit All Fixes
+#### 5e. For "RESPOND" Issues
 
-After processing all issues:
+Post a substantive comment that:
 
-- Ensure all fixes are committed with proper issue references
-- Each fix should be its own commit for clean git history
+- Acknowledges the specific error they reported
+- Explains the likely root cause
+- Provides concrete steps to resolve (version upgrade, env var fix, model path correction)
+- Asks for follow-up info if needed
 
-### 6. Close Resolved Issues
+**Do NOT post generic template responses.** Every comment should reference the user's specific error messages and environment.
 
-For each successfully fixed issue:
-// turbo
+### 6. Generate Report & Wait for Validation
 
-- Close with a comment: `gh issue close <NUMBER> --repo <owner>/<repo> --comment "Fixed in <commit_hash>. The fix will be included in the next release."`
-
-### 7. Generate Report
-
-Present a summary report to the user via `notify_user`:
+Present a summary report to the user via `notify_user` with `BlockedOnUser: true`:
 
 | Issue | Title | Status        | Action                      |
 | ----- | ----- | ------------- | --------------------------- |
-| #N    | Title | ✅ Fixed      | Commit hash                 |
+| #N    | Title | ✅ Closed     | Already fixed / duplicate   |
+| #N    | Title | 🔧 Fixed      | Code fix applied            |
+| #N    | Title | 📝 Responded  | Guidance comment posted     |
 | #N    | Title | ❓ Needs Info | Triage comment posted       |
 | #N    | Title | ⏭️ Skipped    | Feature request / not a bug |
 
-### 8. Update Docs & Release
+> **⚠️ IMPORTANT**: Do NOT merge or generate releases at this step.
+> Wait for the user to review the changes and respond with **OK** before proceeding.
 
-If any fixes were committed:
+- If the user says **OK** or approves → Proceed to step 7
+- If the user requests changes → Apply the requested adjustments first, then present the report again
+- If the user rejects → Revert the changes and stop
 
-1. Run the `/update-docs` workflow (at `~/.gemini/antigravity/global_workflows/update-docs.md`) to update CHANGELOG and README
-2. Run the `/generate-release` workflow (at `.agents/workflows/generate-release.md`) to bump version, tag, and publish
+### 7. Commit & Push (only after user approval)
+
+After the user validates:
+
+- Commit each fix individually on the release branch with message format: `fix: <description> (#<issue_number>)`
+- Push the release branch: `git push origin release/vX.Y.Z`
+- **Update CHANGELOG.md** with all new bug fix entries
+
+### 8. 🛑 WAIT — Notify User & Await Verification
+
+**This is a mandatory stop point.** Use `notify_user` with `BlockedOnUser: true`:
+
+- Inform the user that fixes have been **committed and pushed to the release branch**
+- Include summary of fixes, test status, and files changed
+- **DO NOT merge, close issues, generate releases, or deploy until the user confirms**
+
+Wait for the user to respond:
+
+- **User confirms** → Proceed to step 9
+- **User requests changes** → Apply changes, push to the same branch, notify again
+- **User rejects** → Revert and stop
+
+### 9. Close Issues & Finalize (only after user confirms)
+
+After the user confirms:
+
+1. **Close** resolved issues with a comment: `gh issue close <NUMBER> --repo <owner>/<repo> --comment "Fixed in release/vX.Y.Z. The fix will be included in the next release."`
+2. Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)
 
 If NO fixes were committed, skip this step and just present the report.

.agents/workflows/review-discussions.md

@@ -0,0 +1,118 @@
+---
+description: Read all open GitHub Discussions, summarize them, respond to pending ones, and create issues from actionable feature requests
+---
+
+# /review-discussions — GitHub Discussions Review & Response Workflow
+
+## Overview
+
+This workflow reads all open GitHub Discussions, generates a categorized summary, identifies which ones need a response, drafts and posts replies, and optionally creates issues from actionable feature requests. It follows the same flow used for Issues but adapted for the Discussions forum.
+
+// turbo-all
+
+## Steps
+
+### 1. Identify the GitHub Repository
+
+- Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
+- Parse the owner and repo name from the URL
+
+### 2. Fetch All Open Discussions
+
+- Use `read_url_content` to fetch `https://github.com/<owner>/<repo>/discussions`
+- Parse the discussion list to get all discussion titles, IDs, authors, categories, and dates
+- For each discussion, fetch the individual page to read the full content and all comments/replies
+
+### 3. Summarize All Discussions
+
+For each discussion, extract:
+
+- **Title** and **#Number**
+- **Author** (GitHub username)
+- **Category** (Announcements, General, Ideas, Q&A, Show and tell)
+- **Date** created
+- **Summary** of the original post (1-2 sentences)
+- **Comments count** and key participants
+- **Your previous response** (if any)
+- **Pending action** — whether a response or follow-up is needed
+
+### 4. Present Summary Report to User
+
+Present the full summary to the user organized by category, using a table:
+
+| #   | Category | Title | Author | Date   | Status            |
+| --- | -------- | ----- | ------ | ------ | ----------------- |
+| #N  | Ideas    | Title | @user  | Mar 23 | ⚠️ Needs response |
+| #N  | Q&A      | Title | @user  | Mar 9  | ✅ Answered       |
+| #N  | General  | Title | @user  | Mar 19 | ⚠️ Needs response |
+
+Highlight:
+
+- **⚠️ Needs response** — No reply from maintainer, or a follow-up comment was left unanswered
+- **✅ Answered** — Maintainer already responded
+- **🐛 Bug reported** — A bug was mentioned that needs tracking
+- **💡 Actionable** — Contains a concrete feature request that could become an issue
+
+### 5. Draft & Post Responses
+
+For each discussion that needs a response, draft a reply following these guidelines:
+
+#### Response Style
+
+- **Friendly and professional** — Start with "Hey @username!"
+- **Acknowledge the contribution** — Thank the user for their input
+- **Be specific** — Reference existing features, settings, or dashboard pages if the feature already exists
+- **Provide workarounds** — If the request isn't implemented yet, suggest current alternatives
+- **Commit to action** — If the request is valid, state that you'll open an issue or add it to the roadmap
+- **Keep it concise** — 3-5 paragraphs max
+
+#### Posting via Browser
+
+- Use `browser_subagent` to navigate to each discussion and post the comment
+- **IMPORTANT**: When typing text in GitHub comment boxes via the browser, use only plain ASCII characters:
+  - Use regular hyphens `-` instead of em-dashes
+  - Use `->` instead of arrow symbols
+  - Do NOT use emoji Unicode characters (the browser keyboard may fail on them)
+  - Use `**bold**` and `\`code\`` markdown formatting
+- Click the green "Comment" button (or "Reply" for threaded replies) after typing
+- Verify the comment was posted by checking the page shows the new comment
+
+### 6. Create Issues from Actionable Feature Requests
+
+For discussions that contain concrete, actionable feature requests:
+
+1. Ask the user which ones should become issues
+2. For each approved request, create a GitHub issue via `browser_subagent`:
+   - Navigate to `https://github.com/<owner>/<repo>/issues/new`
+   - **Title**: `<Feature Name> - <Short description>`
+   - **Body** should include:
+     - `## Feature Request` header
+     - `**Source:** Discussion #N by @author`
+     - `## Problem` — What limitation the user hit
+     - `## Proposed Solution` — How it could work
+     - `### Implementation Ideas` — Technical approach
+     - `### Current Workarounds` — What users can do today
+     - `## Additional Context` — Links to related issues/discussions
+   - Add `enhancement` label
+   - Click "Submit new issue" / "Create"
+3. After creation, go back to the original discussion and post a comment linking to the new issue:
+   - "I've opened Issue #N to track this feature request. Follow along there for updates!"
+
+### 7. Final Report
+
+Present a final summary to the user:
+
+| Discussion | Action Taken                       |
+| ---------- | ---------------------------------- |
+| #N — Title | Responded with workarounds         |
+| #N — Title | Responded + created Issue #N       |
+| #N — Title | Already answered, no action needed |
+| #N — Title | Responded to follow-up comment     |
+
+## Notes
+
+- This workflow is **interactive** — always present the summary and wait for user approval before posting responses or creating issues
+- If the user says "pode responder" (or similar approval), proceed with posting all drafted responses
+- For discussions in non-English languages, respond in the same language as the original post
+- Always reference specific dashboard paths, config options, or code files when explaining existing features
+- When a discussion reveals a bug, note it separately from feature requests

.agents/workflows/review-prs.md

@@ -6,7 +6,9 @@ description: Analyze open Pull Requests from the project's GitHub repository, ge
 
 ## Overview
 
-This workflow fetches all open PRs from the project's GitHub repository, performs a critical analysis of each one, generates a detailed report, and waits for user approval before proceeding with implementation.
+This workflow fetches all open PRs from the project's GitHub repository, performs a critical analysis of each one, generates a detailed report, and waits for user approval before proceeding with implementation. **All improvements are committed on the current release branch** (`release/vX.Y.Z`).
+
+> **BRANCH RULE**: PRs are ALWAYS merged into the current `release/vX.Y.Z` branch, NEVER directly into `main`. The release branch acts as a staging area — only after all PRs are integrated and tests pass does the release branch get merged into `main` via the `/generate-release` workflow.
 
 ## Steps
 
@@ -16,51 +18,132 @@ This workflow fetches all open PRs from the project's GitHub repository, perform
   // turbo
 - Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
 
-### 2. Fetch Open Pull Requests
+### 2. Ensure Release Branch Exists
+
+// turbo
+
+Before doing any work, ensure you are on the current release branch:
+
+```bash
+# Check current branch
+git branch --show-current
+
+# If on main, determine next version and create the release branch
+VERSION=$(node -p "require('./package.json').version")
+# Bump patch: e.g. 3.3.11 → 3.3.12
+NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
+git checkout -b release/v$NEXT
+npm version patch --no-git-tag-version
+npm install
+```
+
+If already on a `release/vX.Y.Z` branch, continue working there.
+
+### 3. Fetch Open Pull Requests
+
+// turbo-all
+
+**⚠️ CRITICAL**: The JSON output of `gh pr list` can be truncated by the tool, silently hiding PRs. You MUST use the two-step approach below to guarantee **all** PRs are fetched.
+
+**Step 3a — Get PR numbers only** (small output, never truncated):
+
+- Run: `gh pr list --repo <owner>/<repo> --state open --limit 500 --json number --jq '.[].number'`
+- This outputs one PR number per line. Count them and confirm total.
+
+**Step 3b — Fetch full metadata for each PR** (one call per PR):
+
+- For each PR number from step 3a, run:
+  `gh pr view <NUMBER> --repo <owner>/<repo> --json number,title,author,headRefName,baseRefName,body,createdAt,additions,deletions,files`
+- You may batch these into parallel calls (up to 4 at a time).
+
+**Step 3c — Fetch diffs for each PR** (one call per PR, saved to /tmp):
+
+- For each PR number, run:
+  `gh pr diff <NUMBER> --repo <owner>/<repo> > /tmp/pr<NUMBER>.diff`
+- Then read each diff file with `view_file`.
 
-- Navigate to `https://github.com/<owner>/<repo>/pulls` and scrape all open PRs
 - For each open PR, collect:
   - PR number, title, author, branch, number of commits, date
   - PR description/body
   - Files changed (diff)
   - Existing review comments (from bots or humans)
 
-### 3. Analyze Each PR — For each open PR, perform the following analysis:
+**Verification**: Confirm the count of PRs analyzed matches the count from step 3a before proceeding.
 
-#### 3a. Feature Assessment
+### 3.5 Redirect PR Base Branches to Release Branch
+
+// turbo-all
+
+**⚠️ CRITICAL**: Contributors typically open PRs targeting `main`. Before analyzing or merging, redirect ALL open PRs to target the current release branch instead.
+
+```bash
+# Get the current release branch name
+RELEASE_BRANCH=$(git branch --show-current)  # e.g. release/v3.5.4
+
+# For each open PR that targets main, change its base to the release branch
+for PR_NUM in $(gh pr list --repo <owner>/<repo> --state open --json number,baseRefName --jq '.[] | select(.baseRefName == "main") | .number'); do
+  echo "Redirecting PR #$PR_NUM → $RELEASE_BRANCH"
+  gh pr edit "$PR_NUM" --repo <owner>/<repo> --base "$RELEASE_BRANCH"
+done
+```
+
+This ensures:
+1. PRs merge into the release branch, not directly into `main`
+2. Merge conflict detection is accurate against the release branch
+3. The release branch accumulates all changes before the final merge to `main`
+4. If the release branch doesn't exist on remote yet, push it first: `git push origin $RELEASE_BRANCH`
+
+### 4. Analyze Each PR — For each open PR, perform the following analysis:
+
+#### 4a. Feature Assessment
 
 - **Does it make sense?** Evaluate if the feature fills a real gap or solves a valid problem
 - **Alignment** — Check if it aligns with the project's architecture and roadmap
 - **Complexity** — Assess if the scope is reasonable or if it should be split
 
-#### 3b. Code Quality Review
+#### 4b. Code Quality Review
 
 - Check for code duplication
 - Evaluate error handling patterns (consistent with existing codebase?)
 - Check naming conventions and code style
 - Verify TypeScript types (any `any` usage, missing types?)
 
-#### 3c. Security Review
+#### 4c. Security Review
 
 - Check for missing authentication/authorization on new endpoints
 - Check for injection vulnerabilities (URL params, SQL, XSS)
 - Verify input validation on all user-controlled data
 - Check for hardcoded secrets or credentials
 
-#### 3d. Architecture Review
+#### 4d. Architecture Review
 
 - Does the change follow existing patterns?
 - Are there any breaking changes to public APIs?
 - Is the database schema affected? Migration needed?
 - Impact on performance (N+1 queries, missing indexes?)
 
-#### 3e. Test Coverage
+#### 4e. Test Coverage
 
 - Does the PR include tests?
 - Are edge cases covered?
 - Would existing tests break?
 
-### 4. Generate Report — Create a markdown report for each PR including:
+#### 4f. Cross-Layer (Global) Analysis
+
+Perform a **global impact assessment** to verify whether the PR changes are complete across all layers of the application:
+
+- **Backend → Frontend check**: If the PR adds or modifies backend-only resources (new endpoints, services, data models), evaluate whether corresponding frontend changes are missing:
+  - Does a new endpoint require a new screen/page in the dashboard?
+  - Should there be a new action button, menu item, or navigation link?
+  - Are there new data fields that should be displayed or editable in the UI?
+  - Does a new feature need a toggle, configuration panel, or status indicator?
+- **Frontend → Backend check**: If the PR adds frontend elements, verify the backend support exists:
+  - Are the required API endpoints implemented?
+  - Is the data model sufficient for the new UI components?
+- **Cross-cutting concerns**: Check shared layers (types, DTOs, validation schemas, routes, middleware) for completeness
+- **Document gaps** — If missing layers are detected, list them as **IMPORTANT** issues in the report with concrete suggestions for what should be added
+
+### 5. Generate Report — Create a markdown report for each PR including:
 
 - **PR Summary** — What it does, files affected, commit count
 - **Improvements/Benefits** — Numbered list with impact level (HIGH/MEDIUM/LOW)
@@ -69,28 +152,86 @@ This workflow fetches all open PRs from the project's GitHub repository, perform
 - **Verdict** — Ready to merge? With mandatory vs optional fixes
 - **Next Steps** — What will happen if approved
 
-### 5. Present to User
+### 6. Present to User
 
 - Show the report via `notify_user` with `BlockedOnUser: true`
 - Wait for user decision:
-  - **Approved** → Proceed to step 6
+  - **Approved** → Proceed to step 7
   - **Approved with changes** → Implement the fixes and corrections before merging
   - **Rejected** → Close the PR or leave a review comment
 
-### 6. Implementation (if approved)
+### 7. Pre-Merge Fixes & CI Green-Lighting (if approved)
 
-- Checkout the PR branch or apply changes locally
-- Implement any required fixes identified in the analysis
-- Run the project's test suite to verify nothing breaks
+> **⚠️ Fixes should be pushed back to the PR branch before merging.** We want the PR itself to be green and fully valid before it integrates.
+
+- **Sync latest fixes:** Merge the current `release` branch into the PR branch so the PR inherits any latest CI or integration test fixes (preventing false-positive failures).
+- **Implement improvements:** Apply the required fixes identified in the analysis directly on the PR branch (e.g., adding missing API routes, fixing SSRF, applying comments from other agents).
+- **Pushing changes to PR branches:**
+
+  ```bash
+  # Checkout the PR locally
+  gh pr checkout <NUMBER>
+
+  # Apply fixes, commit your changes
+  git commit -m "chore: apply review suggestions and missing layers"
+
+  # Attempt to push directly to the PR branch
+  git push
+  ```
+
+- **Fallback (For external forks without maintainer edit access):**
+  If `git push` fails because the PR comes from an external fork without write access, you MUST:
+  1. Create a new branch ending in `-fix` (e.g., `checkout -b fix-pr-<NUMBER>`).
+  2. Push your branch to the main repo (`git push origin fix-pr-<NUMBER>`).
+  3. Create a Pull Request targeting the contributor's repository and branch (use `gh pr create --repo <contributor-repo> --base <contributor-branch> --head diegosouzapw:fix-pr-<NUMBER>`).
+  4. Once they accept our PR into their branch, their original PR to our `main` will automatically update and become green.
+
+- Run the project's test suite locally to verify nothing breaks:
   // turbo
 - Run: `npm test` or equivalent test command
-- Build the project to verify compilation
-  // turbo
-- Run: `npm run build` or equivalent build command
-- If all checks pass, prepare the merge
 
-### 7. Post-Merge (if applicable)
+### 8. Merge into Release Branch
 
-- Update CHANGELOG.md with the new feature
-- Consider version bump if warranted
-- Follow the `/generate-release` workflow if a release is needed
+> **⚠️ IMPORTANT**: PRs are merged into the **release branch** (`release/vX.Y.Z`), NOT into `main`.
+
+- Once the PR is green (you can check with `gh pr status`), merge the PR into the release branch.
+- The PR's base was already changed to the release branch in step 3.5, so the default merge target is correct.
+
+  ```bash
+  # Merge the PR (base is already set to release/vX.Y.Z from step 3.5)
+  gh pr merge <NUMBER> --repo <owner>/<repo> --squash --body "Integrated into release/vX.Y.Z"
+
+  # If the PR is a draft, mark it as ready first
+  gh pr ready <NUMBER> --repo <owner>/<repo>
+  ```
+
+- Post a **thank-you comment** on the PR via the GitHub API
+- The message should:
+  - Thank the author by name/username for their contribution
+  - Briefly mention what the PR accomplishes and any improvements applied
+  - Note it will be included in the upcoming release
+  - Be friendly, professional, and encouraging
+- Example: _"Thanks @author for this great contribution! 🎉 The [feature/fix] has been integrated into the release/vX.Y.Z branch and will be part of the next release. We appreciate your effort!"_
+
+### 9. Sync Local Release Branch
+
+After merging PRs, sync the local release branch to include the new changes:
+
+```bash
+git fetch origin
+git pull origin release/vX.Y.Z
+```
+
+### 10. Continue or Finalize
+
+After processing all approved PRs:
+
+- If more PRs remain, go back to step 7
+- When all PRs are processed, **update CHANGELOG.md** on the release branch with all new entries
+- Run **test coverage** to verify all metrics stay above 85%:
+  ```bash
+  npm run test:coverage
+  ```
+- Fix any test regressions introduced by merged PRs
+- Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)
+- The `/generate-release` workflow handles the final merge from `release/vX.Y.Z` → `main`

.agents/workflows/version-bump.md

@@ -0,0 +1,327 @@
+---
+description: Bump version, auto-generate CHANGELOG from git commits, update all versioned files, and refresh root + docs/ documentation to reflect the current project state
+---
+
+# Version Bump Workflow
+
+Automatically bump the project version, generate CHANGELOG entries from git history since the last tag, update every file that references the version, and refresh project documentation to reflect the current state.
+
+> **VERSION RULE: Always use PATCH bumps (3.x.y → 3.x.y+1)**
+> NEVER use `npm version minor` or `npm version major`.
+> Always use: `npm version patch --no-git-tag-version`
+> The threshold rule: when `y` reaches 10, bump to `3.(x+1).0` — e.g. `3.4.10` → `3.5.0`.
+
+---
+
+## Phase 1: Determine Version
+
+### 1. Read current version and last tag
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+CURRENT_VERSION=$(node -p "require('./package.json').version")
+LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+CURRENT_BRANCH=$(git branch --show-current)
+echo "Current version: $CURRENT_VERSION"
+echo "Last tag: $LAST_TAG"
+echo "Current branch: $CURRENT_BRANCH"
+```
+
+### 2. Calculate new version
+
+Apply the patch bump rule:
+
+- If the current patch number is `9`, the new version is `3.(minor+1).0`
+- Otherwise, increment patch: `3.x.y` → `3.x.(y+1)`
+
+If the version was ALREADY bumped (e.g. you are on a release branch and package.json already has the new version), **skip the npm version bump** and use the existing version.
+
+### 3. Bump package.json (if needed)
+
+// turbo
+
+```bash
+# Only if version hasn't been bumped yet
+npm version patch --no-git-tag-version
+```
+
+Or for threshold (y=10):
+
+```bash
+# Manual threshold bump
+VERSION="3.X.0"  # compute manually
+npm version "$VERSION" --no-git-tag-version
+```
+
+---
+
+## Phase 2: Generate CHANGELOG from Git History
+
+### 4. Collect commits since last tag
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
+echo "=== Commits since $LAST_TAG ==="
+git log "$LAST_TAG"..HEAD --pretty=format:"%h %s" --no-merges | head -100
+echo ""
+echo "=== Merge commits ==="
+git log "$LAST_TAG"..HEAD --merges --pretty=format:"%h %s" | head -50
+```
+
+### 5. Classify commits and generate CHANGELOG section
+
+Analyze each commit message and classify into categories based on the conventional-commit prefix and content:
+
+| Category            | Patterns                                         |
+| ------------------- | ------------------------------------------------ |
+| ✨ New Features     | `feat:`, `feat(*):`                              |
+| 🐛 Bug Fixes        | `fix:`, `fix(*):`                                |
+| ⚠️ Breaking Changes | `BREAKING CHANGE`, `!:` suffix                   |
+| 🛠️ Maintenance      | `chore:`, `refactor:`, `perf:`, `build:`         |
+| 🧪 Tests            | `test:`, `tests:`                                |
+| 📝 Documentation    | `docs:`                                          |
+| 🔒 Security         | `security:`, CVE references, vulnerability fixes |
+| 🌍 i18n             | translation updates, locale changes              |
+
+For each category with entries, create a markdown section with descriptive bullet points. Use the commit messages but rewrite them to be human-readable and descriptive (not raw commit messages).
+
+**If a commit references a PR number** (e.g. `#880`, `PR #885`), include it in the description.
+
+### 6. Update CHANGELOG.md
+
+Replace the `## [Unreleased]` section content with the generated entries, then add the new versioned section:
+
+```markdown
+## [Unreleased]
+
+---
+
+## [NEW_VERSION] — YYYY-MM-DD
+
+### ✨ New Features
+
+- **Feature name:** Description (#PR)
+
+### 🐛 Bug Fixes
+
+- **Fix name:** Description (#PR)
+
+### 🛠️ Maintenance
+
+- **Item:** Description
+
+---
+
+## [PREVIOUS_VERSION] — YYYY-MM-DD
+
+...
+```
+
+The date must be today's date in `YYYY-MM-DD` format.
+
+---
+
+## Phase 3: Sync Version Across All Files
+
+### 7. Update workspace package.json files and openapi.yaml
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+VERSION=$(node -p "require('./package.json').version")
+
+# Update docs/openapi.yaml version
+sed -i "s/  version: .*/  version: $VERSION/" docs/openapi.yaml
+echo "✓ docs/openapi.yaml → $VERSION"
+
+# Update workspace packages (open-sse, electron)
+for dir in electron open-sse; do
+  if [ -d "$dir" ] && [ -f "$dir/package.json" ]; then
+    (cd "$dir" && npm version "$VERSION" --no-git-tag-version --allow-same-version > /dev/null)
+    echo "✓ $dir/package.json → $VERSION"
+  fi
+done
+
+echo "✓ All workspace packages synced to $VERSION"
+```
+
+### 8. Update llm.txt version references
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+VERSION=$(node -p "require('./package.json').version")
+OLD_VERSION_PATTERN='[0-9]\+\.[0-9]\+\.[0-9]\+'
+
+# Update "Current version:" line
+sed -i "s/\*\*Current version:\*\* $OLD_VERSION_PATTERN/**Current version:** $VERSION/" llm.txt
+
+# Update "Key Features (vX.Y.Z)" header
+sed -i "s/## Key Features (v$OLD_VERSION_PATTERN)/## Key Features (v$VERSION)/" llm.txt
+
+echo "✓ llm.txt → $VERSION"
+```
+
+### 9. Regenerate lock file
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+npm install
+echo "✓ Lock file regenerated"
+```
+
+---
+
+## Phase 4: Update Root Documentation
+
+Based on the CHANGELOG entries generated in Phase 2, review and update these root-level files if relevant changes warrant updates:
+
+### 10. Review and update root documentation files
+
+For each file below, read the current content and determine if the CHANGELOG entries require any updates. Only modify files where substantive changes have occurred:
+
+| File              | When to update                                                                                                              |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `README.md`       | New providers, major features, stats changes (test count, provider count), badges, installation instructions, feature table |
+| `AGENTS.md`       | Architecture changes, new modules, new commands, new providers, new services/handlers/executors                             |
+| `CONTRIBUTING.md` | Dev workflow changes, new tooling, test infrastructure changes                                                              |
+| `SECURITY.md`     | Security fixes, new auth mechanisms, vulnerability disclosures                                                              |
+| `llm.txt`         | Provider count changes, new features, architecture changes                                                                  |
+
+**Update rules:**
+
+- **README.md**: Update provider count, test count, feature highlights table, badges if any numbers changed. If a new provider was added, add it to the provider table. If a major feature was added, add it to the features section.
+- **AGENTS.md**: If new architecture components (handlers, executors, services, DB modules) were added, update the Architecture section. If new commands were added, update the Build/Test table.
+- **SECURITY.md**: Add new vulnerability fixes or security improvements to the relevant section.
+- **llm.txt**: Update provider count, feature list, version references.
+
+### 11. Review and update docs/ files (excluding i18n/)
+
+For each file in `docs/` (excluding `docs/i18n/`), review if CHANGELOG changes affect it:
+
+| File                             | When to update                                      |
+| -------------------------------- | --------------------------------------------------- |
+| `docs/API_REFERENCE.md`          | New API endpoints, changed request/response formats |
+| `docs/ARCHITECTURE.md`           | New modules, new services, changed data flow        |
+| `docs/CLI-TOOLS.md`              | New CLI tool integrations, config format changes    |
+| `docs/FEATURES.md`               | New features, removed features, changed settings    |
+| `docs/MCP-SERVER.md`             | New MCP tools, changed tool signatures              |
+| `docs/A2A-SERVER.md`             | New A2A skills, protocol changes                    |
+| `docs/USER_GUIDE.md`             | UX changes, new dashboard pages, settings changes   |
+| `docs/VM_DEPLOYMENT_GUIDE.md`    | Deployment changes, new env vars                    |
+| `docs/TROUBLESHOOTING.md`        | New known issues, resolved problems                 |
+| `docs/AUTO-COMBO.md`             | Routing changes, new strategies                     |
+| `docs/CODEBASE_DOCUMENTATION.md` | New files, architectural changes                    |
+| `docs/RELEASE_CHECKLIST.md`      | Process changes                                     |
+| `docs/COVERAGE_PLAN.md`          | Test changes                                        |
+| `docs/openapi.yaml`              | Already updated in step 7                           |
+
+**Only update files where the CHANGELOG entries directly affect the documented content.** Do NOT update files just to bump a version number — only when the documented behavior, features, or architecture has actually changed.
+
+---
+
+## Phase 5: Verify
+
+### 12. Run lint check
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+npm run lint
+```
+
+### 13. Run tests
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+npm test
+```
+
+### 14. Verify version sync across all files
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+VERSION=$(node -p "require('./package.json').version")
+echo "Expected version: $VERSION"
+echo ""
+
+echo "--- package.json ---"
+grep '"version"' package.json | head -1
+
+echo "--- open-sse/package.json ---"
+grep '"version"' open-sse/package.json | head -1
+
+echo "--- electron/package.json ---"
+[ -f electron/package.json ] && grep '"version"' electron/package.json | head -1
+
+echo "--- docs/openapi.yaml ---"
+grep "  version:" docs/openapi.yaml | head -1
+
+echo "--- llm.txt ---"
+grep "Current version:" llm.txt
+
+echo "--- CHANGELOG.md (first versioned entry) ---"
+grep "^## \[" CHANGELOG.md | head -2
+```
+
+### 15. 🛑 STOP — Present Summary to User
+
+**STOP** and present a summary to the user including:
+
+- Old version → New version
+- CHANGELOG entries generated
+- Files modified
+- Test results
+- Any documentation updates made
+
+**Wait for the user to confirm before committing.**
+
+---
+
+## Phase 6: Commit (only after user approval)
+
+### 16. Stage and commit
+
+// turbo-all
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+git add -A
+VERSION=$(node -p "require('./package.json').version")
+git commit -m "chore(release): bump to v$VERSION — changelog, docs, version sync"
+```
+
+---
+
+## Notes
+
+- This workflow does **NOT** create tags, releases, or deploy. Use `/generate-release` for the full release cycle after this.
+- This workflow does **NOT** update `docs/i18n/` translations. Use `/update-i18n` separately after committing.
+- The CHANGELOG generation is based on git commits since the last tag. If there are no new commits, the workflow should inform the user and stop.
+- Always verify the generated CHANGELOG entries make sense — raw commit messages may need rewriting for clarity.
+- If the version was already bumped (e.g. you're on a `release/vX.Y.Z` branch), skip the `npm version` step and use the existing version.
+
+## Version Touchpoints Checklist
+
+| File                    | Field/Pattern                                               |
+| ----------------------- | ----------------------------------------------------------- |
+| `package.json`          | `"version": "X.Y.Z"`                                        |
+| `open-sse/package.json` | `"version": "X.Y.Z"`                                        |
+| `electron/package.json` | `"version": "X.Y.Z"`                                        |
+| `docs/openapi.yaml`     | `version: X.Y.Z`                                            |
+| `llm.txt`               | `**Current version:** X.Y.Z` and `## Key Features (vX.Y.Z)` |
+| `CHANGELOG.md`          | `## [X.Y.Z] — YYYY-MM-DD`                                   |

.dockerignore

@@ -30,3 +30,40 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 .pnpm-debug.log*
+
+# Test suites
+tests
+test-results
+playwright-report
+blob-report
+
+# Documentation (not needed in container)
+docs
+*.md
+!README.md
+
+# Electron (separate build)
+electron
+
+# VS Code extension (separate project)
+vscode-extension
+
+# Build artifacts
+*.tgz
+*.AppImage
+*.deb
+*.rpm
+
+# Package manager lock (bun)
+bun.lock
+
+# Agent config
+.agents
+.gemini
+
+# Misc
+llm.txt
+images
+clipr
+omnirouteCloud
+omnirouteSite

.env.example

@@ -11,27 +11,38 @@ API_KEY_SECRET=
 
 # Initial admin password — CHANGE THIS before first use!
 INITIAL_PASSWORD=CHANGEME
-DATA_DIR=/var/lib/omniroute
+# DATA_DIR=/var/lib/omniroute
 
 # Storage (SQLite)
 STORAGE_DRIVER=sqlite
 # Generate with: openssl rand -hex 32
 STORAGE_ENCRYPTION_KEY=
 STORAGE_ENCRYPTION_KEY_VERSION=v1
-LOG_RETENTION_DAYS=90
+APP_LOG_RETENTION_DAYS=90
+CALL_LOG_RETENTION_DAYS=90
 SQLITE_MAX_SIZE_MB=2048
 SQLITE_CLEAN_LEGACY_FILES=true
+DISABLE_SQLITE_AUTO_BACKUP=false
 
 # Recommended runtime variables
+# Canonical/base port (keeps backward compatibility)
 PORT=20128
+# Optional split ports:
+# API_PORT=20129
+# API_HOST=0.0.0.0
+# DASHBOARD_PORT=20128
+# Optional Docker production host publish ports:
+# PROD_DASHBOARD_PORT=20130
+# PROD_API_PORT=20131
 NODE_ENV=production
 INSTANCE_NAME=omniroute
 
 # Recommended security and ops variables
 MACHINE_ID_SALT=endpoint-proxy-salt
-ENABLE_REQUEST_LOGS=false
 AUTH_COOKIE_SECURE=false
 REQUIRE_API_KEY=false
+ALLOW_API_KEY_REVEAL=false
+PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70
 
 # Input Sanitizer (FASE-01 — prompt injection & PII protection)
 # INPUT_SANITIZER_ENABLED=true
@@ -79,48 +90,107 @@ NEXT_PUBLIC_ENABLE_SOCKS5_PROXY=true
 # CLI_ROO_BIN=roo
 # CLI_CONTINUE_BIN=cn
 
-# Provider OAuth Credentials (optional — override hardcoded defaults)
-# These can also be set via data/provider-credentials.json
-# CLAUDE_OAUTH_CLIENT_ID=
+# Internal agent / tool integrations (optional)
+# Used by the MCP server, A2A skills, and CLI sidecars when they need to call
+# the running OmniRoute instance explicitly instead of relying on localhost.
+# OMNIROUTE_BASE_URL=http://localhost:20128
+# OMNIROUTE_API_KEY=
+# ROUTER_API_KEY=
+# MODEL_SYNC_INTERVAL_HOURS=24
+
+# ═══════════════════════════════════════════════════
+#   OAUTH PROVIDER CREDENTIALS
+# ═══════════════════════════════════════════════════
+# These are the built-in default credentials that work for localhost setups.
+# For remote/VPS deployments, register your own credentials at each provider.
+# The sync-env script will auto-populate these in your .env if missing.
+#
+# These can also be overridden via data/provider-credentials.json where supported.
+
+# ── Claude Code (Anthropic) ──
+CLAUDE_OAUTH_CLIENT_ID=9d1c250a-e61b-44d9-88ed-5944d1962f5e
+
+# ── Codex / OpenAI ──
+CODEX_OAUTH_CLIENT_ID=app_EMoamEEZ73f0CkXaXp7hrann
+
+# ── Gemini (Google) ──
+GEMINI_OAUTH_CLIENT_ID=681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com
+GEMINI_OAUTH_CLIENT_SECRET=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
+
+# ── Gemini CLI (Google) ──
+GEMINI_CLI_OAUTH_CLIENT_ID=681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com
+GEMINI_CLI_OAUTH_CLIENT_SECRET=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
+
+# ── Qwen (Alibaba) ──
+QWEN_OAUTH_CLIENT_ID=f0304373b74a44d2b584a3fb70ca9e56
+
+# ── Kimi Coding (Moonshot) ──
+KIMI_CODING_OAUTH_CLIENT_ID=17e5f671-d194-4dfb-9706-5516cb48c098
+
+# ── Antigravity (Google Cloud Code) ──
+ANTIGRAVITY_OAUTH_CLIENT_ID=1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com
+ANTIGRAVITY_OAUTH_CLIENT_SECRET=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
+
+# ── GitHub Copilot ──
+GITHUB_OAUTH_CLIENT_ID=Iv1.b507a08c87ecfe98
+
+# ── Qoder ──
+QODER_OAUTH_CLIENT_SECRET=4Z3YjXycVsQvyGF1etiNlIBB4RsqSDtW
+
+# ── Qoder (URLs — set these to enable Qoder OAuth login) ──
+# QODER_OAUTH_AUTHORIZE_URL=
+# QODER_OAUTH_TOKEN_URL=
+# QODER_OAUTH_USERINFO_URL=
+# QODER_OAUTH_CLIENT_ID=
 
 # ─────────────────────────────────────────────────────────────────────────────
 # ⚠️  GOOGLE OAUTH (Antigravity, Gemini CLI) — IMPORTANT FOR REMOTE SERVERS
 # ─────────────────────────────────────────────────────────────────────────────
-# The built-in Google OAuth credentials ONLY work when OmniRoute runs on
-# localhost (127.0.0.1 / local network). They are registered with
-# redirect_uri = http://localhost:PORT/callback and Google will reject any
-# other redirect URI with: redirect_uri_mismatch.
-#
-# If you are hosting OmniRoute on a remote server (VPS, Docker, cloud), you
-# MUST register your own Google Cloud OAuth 2.0 credentials:
-#
+# The credentials above ONLY work when OmniRoute runs on localhost.
+# If you are hosting OmniRoute on a remote server, register your own:
 #   1. Go to https://console.cloud.google.com/apis/credentials
 #   2. Create an OAuth 2.0 Client ID (type: "Web application")
-#   3. Add your server URL as Authorized redirect URI:
-#        https://your-server.com/callback
-#   4. Copy the Client ID and Client Secret below.
-#
-# See the full tutorial in README.md → "OAuth em Servidor Remoto" section.
-#
-# Antigravity (Google Gemini Code Assist):
-# ANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
-# ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret
-ANTIGRAVITY_OAUTH_CLIENT_SECRET=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
-
-# Gemini CLI (Google AI):
-# GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
-# GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret
-# GEMINI_CLI_OAUTH_CLIENT_ID=
-GEMINI_OAUTH_CLIENT_SECRET=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
-GEMINI_CLI_OAUTH_CLIENT_SECRET=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
+#   3. Add your server URL as Authorized redirect URI
+#   4. Replace the values above with your credentials.
 # ─────────────────────────────────────────────────────────────────────────────
 
-# CLAUDE_OAUTH_CLIENT_ID=
-# CODEX_OAUTH_CLIENT_ID=
-# CODEX_OAUTH_CLIENT_SECRET=
-# QWEN_OAUTH_CLIENT_ID=
-# IFLOW_OAUTH_CLIENT_ID=
-IFLOW_OAUTH_CLIENT_SECRET=4Z3YjXycVsQvyGF1etiNlIBB4RsqSDtW
+# ─────────────────────────────────────────────────────────────────────────────
+# Provider User-Agent Overrides (optional — customize per-provider UA headers)
+# ─────────────────────────────────────────────────────────────────────────────
+# Format: {PROVIDER_ID}_USER_AGENT=custom-value
+# When set, overrides the default User-Agent header sent to that provider.
+# Useful when providers update versions or block old user-agents.
+CLAUDE_USER_AGENT=claude-cli/1.0.83 (external, cli)
+CODEX_USER_AGENT=codex-cli/0.92.0 (Windows 10.0.26100; x64)
+GITHUB_USER_AGENT=GitHubCopilotChat/0.26.7
+ANTIGRAVITY_USER_AGENT=antigravity/1.104.0 darwin/arm64
+KIRO_USER_AGENT=AWS-SDK-JS/3.0.0 kiro-ide/1.0.0
+QODER_USER_AGENT=Qoder-Cli
+QWEN_USER_AGENT=QwenCode/0.12.3 (linux; x64)
+CURSOR_USER_AGENT=connect-es/1.6.1
+GEMINI_CLI_USER_AGENT=google-api-nodejs-client/9.15.1
+
+# ─────────────────────────────────────────────────────────────────────────────
+# CLI Fingerprint Compatibility (optional — match native CLI binary signatures)
+# ─────────────────────────────────────────────────────────────────────────────
+# When enabled, OmniRoute reorders HTTP headers and JSON body fields to match
+# the exact signature of official CLI tools, reducing account flagging risk.
+# Your proxy IP is preserved — you get both stealth AND IP masking.
+#
+# Enable per-provider:
+# CLI_COMPAT_CODEX=1
+# CLI_COMPAT_CLAUDE=1
+# CLI_COMPAT_GITHUB=1
+# CLI_COMPAT_ANTIGRAVITY=1
+# CLI_COMPAT_KIRO=1
+# CLI_COMPAT_CURSOR=1
+# CLI_COMPAT_KIMI_CODING=1
+# CLI_COMPAT_KILOCODE=1
+# CLI_COMPAT_CLINE=1
+# CLI_COMPAT_QWEN=1
+#
+# Or enable for all providers at once:
+# CLI_COMPAT_ALL=1
 
 # API Key Providers (Phase 1 + Phase 4)
 # Add via Dashboard → Providers → Add API Key, or set here
@@ -140,16 +210,51 @@ IFLOW_OAUTH_CLIENT_SECRET=4Z3YjXycVsQvyGF1etiNlIBB4RsqSDtW
 # Provider keys above (openai, mistral, together, fireworks, nvidia) also work for embeddings
 
 # Timeout settings
-# FETCH_TIMEOUT_MS=120000
-# STREAM_IDLE_TIMEOUT_MS=60000
+# REQUEST_TIMEOUT_MS=600000
+# STREAM_IDLE_TIMEOUT_MS=600000
+# Advanced timeout overrides (optional)
+# FETCH_TIMEOUT_MS=600000
+# FETCH_HEADERS_TIMEOUT_MS=600000
+# FETCH_BODY_TIMEOUT_MS=600000
+# FETCH_CONNECT_TIMEOUT_MS=30000
+# FETCH_KEEPALIVE_TIMEOUT_MS=4000
+# TLS_CLIENT_TIMEOUT_MS=600000
+# API bridge timeout for /v1 proxy requests (default: 30000)
+# API_BRIDGE_PROXY_TIMEOUT_MS=600000
+# API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS=600000
+# API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS=60000
+# API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS=5000
+# API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS=0
 
 # CORS configuration (default: * allows all origins)
-# CORS_ORIGINS=*
+# CORS_ORIGIN=*
 
 # Logging
-# LOG_LEVEL=info
-# LOG_FORMAT=text
-LOG_TO_FILE=true
-# LOG_FILE_PATH=logs/application/app.log
-# LOG_MAX_FILE_SIZE=50M
-# LOG_RETENTION_DAYS=7
+# APP_LOG_LEVEL=info
+# APP_LOG_FORMAT=text
+APP_LOG_TO_FILE=true
+# APP_LOG_FILE_PATH=logs/application/app.log
+# APP_LOG_MAX_FILE_SIZE=50M
+# APP_LOG_RETENTION_DAYS=7
+# APP_LOG_MAX_FILES=20
+# CALL_LOG_RETENTION_DAYS=7
+# CALL_LOG_MAX_ENTRIES=10000
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Memory Optimization (Low-RAM configurations)
+# ─────────────────────────────────────────────────────────────────────────────
+# Node.js heap limit in MB (default: 256 for Docker, system default for npm)
+# OMNIROUTE_MEMORY_MB=256
+
+# Prompt cache settings
+# PROMPT_CACHE_MAX_SIZE=50
+# PROMPT_CACHE_MAX_BYTES=2097152
+# PROMPT_CACHE_TTL_MS=300000
+
+# Semantic cache settings (temperature=0 responses)
+# SEMANTIC_CACHE_MAX_SIZE=100
+# SEMANTIC_CACHE_MAX_BYTES=4194304
+# SEMANTIC_CACHE_TTL_MS=1800000
+
+# In-memory log buffers
+# STREAM_HISTORY_MAX=50

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+* @diegosouzapw
+

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,171 @@
+name: Bug Report
+description: Report a bug or unexpected behavior in OmniRoute
+title: "[BUG] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. Please fill out the sections below so we can reproduce and fix the issue.
+
+  - type: input
+    id: version
+    attributes:
+      label: OmniRoute Version
+      description: "Run `omniroute --version` or check the left sidebar in the dashboard."
+      placeholder: "e.g. 3.0.9"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: Installation Method
+      options:
+        - npm (global)
+        - Docker / Docker Compose
+        - Electron desktop app
+        - Built from source
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - Windows
+        - macOS
+        - Linux
+    validations:
+      required: true
+
+  - type: input
+    id: os-version
+    attributes:
+      label: OS Version
+      placeholder: "e.g. Windows 11 23H2, macOS 15.3, Ubuntu 24.04"
+    validations:
+      required: false
+
+  - type: input
+    id: node-version
+    attributes:
+      label: Node.js Version
+      description: "Run `node --version`. Skip if using Docker."
+      placeholder: "e.g. 22.12.0"
+    validations:
+      required: false
+
+  - type: input
+    id: provider
+    attributes:
+      label: Provider(s) Involved
+      description: "Which AI provider(s) does this affect?"
+      placeholder: "e.g. Antigravity, OpenRouter, Ollama, Qwen"
+    validations:
+      required: false
+
+  - type: input
+    id: model
+    attributes:
+      label: Model(s) Involved
+      placeholder: "e.g. claude-sonnet-4-20250514, gpt-4o, gemini-2.5-pro"
+    validations:
+      required: false
+
+  - type: input
+    id: client-tool
+    attributes:
+      label: Client Tool
+      description: "Which tool are you using OmniRoute with?"
+      placeholder: "e.g. Claude Code, Cursor, Roo Code, OpenClaw, Gemini CLI, cURL"
+    validations:
+      required: false
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: "A clear description of what the bug is."
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: "Step-by-step instructions to reproduce the behavior."
+      placeholder: |
+        1. Go to '...'
+        2. Click on '...'
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: "What did you expect to happen?"
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: "What actually happened?"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: test-impact
+    attributes:
+      label: Test Impact
+      description: "What automated test coverage should exist for this bug?"
+      options:
+        - Needs a new unit test
+        - Needs a new integration test
+        - Needs a new e2e test
+        - Existing automated test already fails
+        - Unsure
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error Logs / Output
+      description: "Paste any relevant error messages, logs, or terminal output. This will be automatically formatted as code."
+      render: shell
+    validations:
+      required: false
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots
+      description: "If applicable, add screenshots to help explain the problem. Please also include the text of any error messages above — screenshots alone are not searchable."
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: "Any other context about the problem (e.g. proxy config, number of accounts, network setup)."
+    validations:
+      required: false
+
+  - type: textarea
+    id: validation-plan
+    attributes:
+      label: Validation Plan
+      description: "Which commands or tests should prove this bug is fixed?"
+      placeholder: |
+        Example:
+        - node --import tsx/esm --test tests/unit/my-file.test.mjs
+        - npm run test:coverage
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question / Help
+    url: https://github.com/diegosouzapw/OmniRoute/discussions
+    about: For questions or help with setup, please use GitHub Discussions instead of opening an issue.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,96 @@
+name: Feature Request
+description: Suggest a new feature or improvement for OmniRoute
+title: "[Feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please describe the problem you're trying to solve and how you'd like it to work.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Use Case
+      description: "What problem does this feature solve? Why do you need it?"
+      placeholder: "I'm trying to ... but currently ..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: "How would you like this to work?"
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: "Have you considered any workarounds or alternative approaches?"
+    validations:
+      required: false
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance Criteria
+      description: "Describe the concrete behaviors or outcomes that should be validated before this is considered done."
+      placeholder: |
+        Example:
+        - API route returns 200 with valid payload
+        - Unit coverage added for the new branch
+        - Existing integrations remain green
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: "Which part of OmniRoute does this relate to?"
+      multiple: true
+      options:
+        - Dashboard / UI
+        - Proxy / Routing
+        - Provider Support
+        - CLI Tools Integration
+        - OAuth / Authentication
+        - Analytics / Usage Tracking
+        - Docker / Deployment
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: provider
+    attributes:
+      label: Related Provider(s)
+      description: "If this relates to specific providers, list them."
+      placeholder: "e.g. Antigravity, OpenRouter, Ollama"
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: "Any other context, mockups, or references."
+    validations:
+      required: false
+
+  - type: textarea
+    id: test-plan
+    attributes:
+      label: Expected Test Plan
+      description: "Which automated tests or coverage changes should accompany this work?"
+      placeholder: |
+        Example:
+        - Add unit tests for open-sse/services/combo.ts
+        - Extend integration coverage for /api/v1/models
+        - Keep npm run test:coverage at 60%+
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/test_coverage_task.yml

@@ -0,0 +1,73 @@
+name: Test Coverage Task
+description: Create a focused coverage-improvement issue tied to concrete files and targets
+title: "[Coverage] "
+labels: ["test", "coverage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template for scoped coverage work. Keep it tied to specific files, measurable targets, and the gate that must stay green.
+
+  - type: input
+    id: baseline
+    attributes:
+      label: Current Coverage Baseline
+      description: "Paste the current overall or file-level coverage number that justifies this task."
+      placeholder: "e.g. Lines 79.00%, Branches 72.85%, open-sse/handlers/chatCore.ts = 67.22%"
+    validations:
+      required: true
+
+  - type: textarea
+    id: scope
+    attributes:
+      label: Target Files Or Modules
+      description: "List the concrete source files or directories that this task will cover."
+      placeholder: |
+        Example:
+        - open-sse/handlers/chatCore.ts
+        - open-sse/services/combo.ts
+        - tests/integration/chat-pipeline.test.mjs
+    validations:
+      required: true
+
+  - type: textarea
+    id: scenarios
+    attributes:
+      label: Missing Scenarios
+      description: "Describe the specific behaviors, branches, or failure paths that are currently uncovered."
+      placeholder: |
+        Example:
+        - Upstream timeout path
+        - Empty tool_calls normalization
+        - Fallback route after first provider failure
+    validations:
+      required: true
+
+  - type: input
+    id: target
+    attributes:
+      label: Coverage Target
+      description: "Set the expected target for this task."
+      placeholder: "e.g. Raise open-sse/handlers to 80%+ lines and keep global gate >= 60%"
+    validations:
+      required: true
+
+  - type: textarea
+    id: validation
+    attributes:
+      label: Validation Commands
+      description: "List the commands that must pass before this issue can be closed."
+      placeholder: |
+        Example:
+        - node --import tsx/esm --test tests/unit/my-suite.test.mjs
+        - npm run test:coverage
+    validations:
+      required: true
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: "Optional context, blockers, or dependencies."
+    validations:
+      required: false

.github/copilot-instructions.md

@@ -0,0 +1,15 @@
+# OmniRoute PR and Coverage Instructions
+
+- Treat `npm run test:coverage` as a required gate for PR work.
+- The repository minimum is `60%` for statements, lines, functions, and branches.
+- If a PR changes production code in `src/`, `open-sse/`, `electron/`, or `bin/`, it must include automated tests in the same PR.
+- When reviewing or updating a PR, if the report shows missing tests or coverage below `60%`, do not stop after reporting the problem. Add or update tests in the PR first, rerun the coverage gate, and only then ask for confirmation.
+- Prefer the smallest test layer that proves the behavior:
+  - unit tests first
+  - integration tests when multiple modules or DB state are involved
+  - e2e only when the behavior is truly UI or workflow-dependent
+- For bug issues, try to encode the reproduction as an automated test before or alongside the fix.
+- In the final PR report, include:
+  - the commands you ran
+  - the changed test files
+  - the final coverage result

.github/pull_request_template.md

@@ -0,0 +1,30 @@
+## Summary
+
+- Describe the user-facing or operational change.
+
+## Related Issues
+
+- Closes #
+- Related to #
+
+## Validation
+
+- [ ] `npm run lint`
+- [ ] `npm run test:unit`
+- [ ] `npm run test:coverage`
+- [ ] Coverage is still `>= 60%` for statements, lines, functions, and branches
+- [ ] SonarQube PR analysis is green or any remaining issues are explicitly documented below
+
+## Tests Added Or Updated
+
+- List every changed or added automated test file.
+- If no production code changed, state that here.
+
+## Coverage Notes
+
+- If this PR changes `src/`, `open-sse/`, `electron/`, or `bin/`, explain which tests cover the change.
+- If coverage moved down in any touched file, explain why and what follow-up task will recover it.
+
+## Reviewer Notes
+
+- Call out any risky areas, migrations, feature flags, or manual validation that reviewers should know about.

.github/workflows/ci.yml

@@ -5,11 +5,15 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+    types: [opened, synchronize, reopened, ready_for_review]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   lint:
     name: Lint
@@ -22,22 +26,109 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run lint
+      - run: npm run check:cycles
+      - run: npm run check:route-validation:t06
+      - run: npm run check:any-budget:t11
+      - run: npm run check:docs-sync
+      - run: npm run typecheck:core
+      - run: npm run typecheck:noimplicit:core
 
-  security:
-    name: Security Audit
+  i18n-matrix:
+    name: Build language matrix
+    runs-on: ubuntu-latest
+    outputs:
+      langs: ${{ steps.langs.outputs.langs }}
+    steps:
+      - uses: actions/checkout@v6
+      - id: langs
+        run: |
+          LANG_DIR="src/i18n/messages"
+          LANGS=$(ls "$LANG_DIR"/*.json | xargs -n1 basename | sed 's/.json$//' | grep -v '^en$' | jq -R . | jq -s . | jq -c .)
+          echo "langs=${LANGS}" >> "$GITHUB_OUTPUT"
+
+  i18n:
+    name: i18n Validation
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    strategy:
+      fail-fast: false
+      matrix:
+        lang: ${{ fromJson(needs.i18n-matrix.outputs.langs) }}
+    needs: i18n-matrix
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Validate ${{ matrix.lang }}
+        run: |
+          python3 scripts/validate_translation.py quick -l '${{ matrix.lang }}' > result.txt
+
+      - name: Upload result
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: i18n-${{ matrix.lang }}
+          path: result.txt
+
+  pr-test-policy:
+    name: PR Test Policy
+    if: ${{ github.event_name == 'pull_request' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - name: Fetch base branch
+        run: git fetch --no-tags origin "${GITHUB_BASE_REF}" --depth=1
+      - name: Validate source changes include tests
+        run: node scripts/check-pr-test-policy.mjs --summary-file .artifacts/pr-test-policy.md
+      - name: Publish PR test policy summary
+        if: always()
+        run: |
+          if [ -f .artifacts/pr-test-policy.md ]; then
+            cat .artifacts/pr-test-policy.md >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+  advanced-security:
+    name: Advanced Security Scans
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: TruffleHog Secret Scan
+        uses: trufflesecurity/trufflehog@main
+        with:
+          path: ./
+          base: ${{ github.event.repository.default_branch }}
+          head: HEAD
+          extra_args: --only-verified
+
       - uses: actions/setup-node@v6
         with:
           node-version: 22
           cache: npm
+
       - run: npm ci
+
       - name: Dependency audit
-        run: npm audit --audit-level=high --omit=dev
+        run: npm audit --audit-level=high --omit=dev || true
+
       - name: Check for known vulnerabilities
-        run: npx is-my-node-vulnerable
-        continue-on-error: true
+        run: npx is-my-node-vulnerable || true
+
+      - name: Run Snyk Vulnerability checks
+        uses: snyk/actions/node@master
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+        with:
+          args: --severity-threshold=high
 
   build:
     name: Build
@@ -57,6 +148,7 @@ jobs:
   test-unit:
     name: Unit Tests
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     needs: build
     strategy:
       matrix:
@@ -76,6 +168,7 @@ jobs:
   test-coverage:
     name: Coverage
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     needs: build
     env:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
@@ -87,15 +180,150 @@ jobs:
           node-version: 22
           cache: npm
       - run: npm ci
-      - run: npm run test:coverage
-      - name: Check coverage threshold
+      - name: Run coverage gate
+        run: npm run test:coverage
+      - name: Build coverage summary
+        if: always()
         run: |
-          echo "Coverage report generated. Check output for threshold compliance."
+          mkdir -p coverage
+          if [ -f coverage/coverage-summary.json ]; then
+            node scripts/test-report-summary.mjs \
+              --input coverage/coverage-summary.json \
+              --output coverage/coverage-report.md \
+              --threshold 60
+          else
+            printf '%s\n' \
+              '# Coverage Report' \
+              '' \
+              'Coverage summary JSON was not generated. Inspect the Coverage job logs.' \
+              > coverage/coverage-report.md
+          fi
+          cat coverage/coverage-report.md >> "$GITHUB_STEP_SUMMARY"
+      - name: Upload coverage artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: |
+            coverage/coverage-summary.json
+            coverage/lcov.info
+            coverage/coverage-report.md
+          if-no-files-found: warn
+
+  sonarqube:
+    name: SonarQube
+    runs-on: ubuntu-latest
+    needs: test-coverage
+    if: ${{ always() && needs.test-coverage.result == 'success' }}
+    env:
+      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+      SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/download-artifact@v4
+        with:
+          name: coverage-report
+          path: .
+      - name: Explain SonarQube skip
+        if: ${{ env.SONAR_TOKEN == '' || env.SONAR_HOST_URL == '' }}
+        run: |
+          echo "SonarQube scan skipped because SONAR_TOKEN or SONAR_HOST_URL is not configured." >> "$GITHUB_STEP_SUMMARY"
+      - name: SonarQube Scan
+        if: ${{ env.SONAR_TOKEN != '' && env.SONAR_HOST_URL != '' }}
+        uses: SonarSource/sonarqube-scan-action@v7
+        env:
+          SONAR_TOKEN: ${{ env.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ env.SONAR_HOST_URL }}
+
+  coverage-pr-comment:
+    name: PR Coverage Comment
+    runs-on: ubuntu-latest
+    if: ${{ always() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false }}
+    needs:
+      - pr-test-policy
+      - test-coverage
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Download coverage artifact
+        if: ${{ needs.test-coverage.result != 'cancelled' }}
+        continue-on-error: true
+        uses: actions/download-artifact@v4
+        with:
+          name: coverage-report
+          path: .
+      - name: Prepare PR coverage comment
+        env:
+          COVERAGE_RESULT: ${{ needs.test-coverage.result }}
+          POLICY_RESULT: ${{ needs.pr-test-policy.result }}
+        run: |
+          mkdir -p .artifacts
+          {
+            echo "<!-- omniroute-coverage-report -->"
+            echo "## CI Coverage Report"
+            echo ""
+            echo "- Coverage job: \`${COVERAGE_RESULT}\`"
+            echo "- PR test policy: \`${POLICY_RESULT}\`"
+            echo ""
+            if [ -f coverage/coverage-report.md ]; then
+              cat coverage/coverage-report.md
+            else
+              echo "Coverage artifact was not available for this run."
+            fi
+            if [ "${POLICY_RESULT}" = "failure" ]; then
+              echo ""
+              echo "## PR Test Policy"
+              echo ""
+              echo "This PR changes production code in \`src/\`, \`open-sse/\`, \`electron/\`, or \`bin/\` without accompanying automated tests."
+            fi
+          } > .artifacts/pr-coverage-comment.md
+      - uses: actions/github-script@v8
+        with:
+          script: |
+            const fs = require("fs");
+            const marker = "<!-- omniroute-coverage-report -->";
+            const body = fs.readFileSync(".artifacts/pr-coverage-comment.md", "utf8");
+            const { owner, repo } = context.repo;
+            const issue_number = context.issue.number;
+
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner,
+              repo,
+              issue_number,
+              per_page: 100,
+            });
+
+            const existing = comments.find((comment) => comment.body?.includes(marker));
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner,
+                repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number,
+                body,
+              });
+            }
 
   test-e2e:
-    name: E2E Tests
+    name: E2E Tests (${{ matrix.shard }}/4)
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4]
     env:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
@@ -108,11 +336,12 @@ jobs:
       - run: npm ci
       - run: npx playwright install --with-deps chromium
       - run: npm run build
-      - run: npm run test:e2e
+      - run: npx playwright test tests/e2e/*.spec.ts --shard=${{ matrix.shard }}/4
 
   test-integration:
     name: Integration Tests
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     needs: build
     env:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
@@ -127,7 +356,6 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run test:integration
-        continue-on-error: true
 
   test-security:
     name: Security Tests
@@ -144,4 +372,101 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run test:security
+
+  ci-summary:
+    name: CI Dashboard
+    runs-on: ubuntu-latest
+    if: always()
+    needs:
+      - lint
+      - i18n
+      - pr-test-policy
+      - advanced-security
+      - build
+      - test-unit
+      - test-coverage
+      - sonarqube
+      - coverage-pr-comment
+      - test-e2e
+      - test-integration
+      - test-security
+    steps:
+      - name: Download i18n results
         continue-on-error: true
+        uses: actions/download-artifact@v4
+        with:
+          pattern: i18n-*
+          path: results
+          merge-multiple: true
+
+      - name: Generate dashboard
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+        run: |
+          status() {
+            case "$1" in
+              success) echo "🟢 PASS" ;;
+              failure) echo "🔴 FAIL" ;;
+              cancelled) echo "⚫ CANCELLED" ;;
+              skipped) echo "⚪ SKIPPED" ;;
+              *) echo "🟡 UNKNOWN" ;;
+            esac
+          }
+
+          echo "# 🚀 CI Dashboard" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+
+          echo "## 🧱 Core Checks" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Job | Status |" >> "$GITHUB_STEP_SUMMARY"
+          echo "|-----|--------|" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Lint | $(status '${{ needs.lint.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| PR Test Policy | $(status '${{ needs.pr-test-policy.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Advanced Security | $(status '${{ needs.advanced-security.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| SonarQube | $(status '${{ needs.sonarqube.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "## 🏗️ Build" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Job | Status |" >> "$GITHUB_STEP_SUMMARY"
+          echo "|-----|--------|" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Build Matrix | $(status '${{ needs.build.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "## 🧪 Tests" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Suite | Status |" >> "$GITHUB_STEP_SUMMARY"
+          echo "|-------|--------|" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Unit | $(status '${{ needs.test-unit.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Coverage | $(status '${{ needs.test-coverage.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| PR Coverage Comment | $(status '${{ needs.coverage-pr-comment.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| E2E | $(status '${{ needs.test-e2e.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Integration | $(status '${{ needs.test-integration.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Security Tests | $(status '${{ needs.test-security.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "## 🌍 Translations" >> "$GITHUB_STEP_SUMMARY"
+
+          total=0
+          langs=0
+
+          if [ -d results ]; then
+            for file in results/*.txt; do
+              [ -f "$file" ] || continue
+              val=$(sed -r 's/\x1B\[[0-9;]*[mK]//g' "$file" | grep "Untranslated:" | awk '{print $2}')
+              val=${val:-0}
+              total=$((total + val))
+              langs=$((langs + 1))
+            done
+          fi
+
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Metric | Value |" >> "$GITHUB_STEP_SUMMARY"
+          echo "|--------|------|" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Languages checked | $langs |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Total untranslated | $total |" >> "$GITHUB_STEP_SUMMARY"
+
+          if [ "$total" -gt 0 ]; then
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo "⚠️ **Translations need attention**" >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo "✅ **All translations complete**" >> "$GITHUB_STEP_SUMMARY"
+          fi

.github/workflows/codex-review.yml

@@ -1,22 +0,0 @@
-# name: Codex PR Review
-
-# on:
-#   pull_request:
-#     types: [opened, synchronize]
-
-# jobs:
-#   request-codex-review:
-#     runs-on: ubuntu-latest
-#     permissions:
-#       pull-requests: write
-#     steps:
-#       - name: Request Codex Review
-#         uses: actions/github-script@v8
-#         with:
-#           script: |
-#             await github.rest.issues.createComment({
-#               owner: context.repo.owner,
-#               repo: context.repo.repo,
-#               issue_number: context.payload.pull_request.number,
-#               body: '@codex review'
-#             });

.github/workflows/deploy-vps.yml

@@ -6,28 +6,27 @@ on:
     types: [completed]
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   deploy:
-    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    if: >-
+      (github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success')
+      && vars.DEPLOY_ENABLED == 'true'
     name: Deploy OmniRoute to VPS
     runs-on: ubuntu-latest
     steps:
-      - name: Install Tailscale
-        uses: tailscale/github-action@v3
-        with:
-          oauth-client-id: ""
-          oauth-secret: ""
-          tags: tag:ci-deploy
-        continue-on-error: true
-
       - name: Deploy via SSH
         uses: appleboy/ssh-action@v1
+        continue-on-error: true
         with:
           host: ${{ secrets.VPS_HOST }}
           username: ${{ secrets.VPS_USER }}
           key: ${{ secrets.VPS_SSH_KEY }}
           port: 22
           timeout: 30s
+          command_timeout: 5m
           script: |
             echo "=== Updating OmniRoute ==="
             npm install -g omniroute@latest 2>&1

.github/workflows/docker-publish.yml

@@ -1,34 +1,39 @@
 name: Publish to Docker Hub
 
 on:
+  push:
+    branches:
+      - main
   release:
     types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version tag to build (e.g. 2.6.0)"
+        required: true
+        type: string
 
 permissions:
   contents: read
+  packages: write
 
 jobs:
-  build:
-    name: Build (${{ matrix.platform }})
-    runs-on: ${{ matrix.runner }}
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - platform: linux/amd64
-            platform_pair: linux-amd64
-            runner: ubuntu-latest
-          - platform: linux/arm64
-            platform_pair: linux-arm64
-            runner: ubuntu-24.04-arm
+  docker:
+    name: Build and Push Docker (multi-arch)
+    runs-on: ubuntu-latest
     env:
       IMAGE_NAME: diegosouzapw/omniroute
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/v{0}', inputs.version) || '' }}
+
+      - name: Set up QEMU (for multi-arch builds)
+        uses: docker/setup-qemu-action@v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Login to Docker Hub
         uses: docker/login-action@v3
@@ -36,79 +41,49 @@ jobs:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      - name: Build and push by digest
-        id: build
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract version from release tag or input
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION="${{ inputs.version }}"
+          else
+            VERSION="${GITHUB_REF_NAME}"
+            VERSION="${VERSION#v}"
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Publishing Docker image: $IMAGE_NAME:$VERSION"
+
+      - name: Build and push multi-arch image
         uses: docker/build-push-action@v6
         with:
           context: .
           target: runner-base
-          platforms: ${{ matrix.platform }}
-          outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
-          cache-from: type=gha,scope=omniroute-runner-base-${{ matrix.platform_pair }}
-          cache-to: type=gha,mode=max,scope=omniroute-runner-base-${{ matrix.platform_pair }}
-
-      - name: Export digest
-        run: |
-          mkdir -p "${{ runner.temp }}/digests"
-          digest="${{ steps.build.outputs.digest }}"
-          touch "${{ runner.temp }}/digests/${digest#sha256:}"
-
-      - name: Upload digest
-        uses: actions/upload-artifact@v4
-        with:
-          name: digests-${{ matrix.platform_pair }}
-          path: ${{ runner.temp }}/digests/*
-          if-no-files-found: error
-          retention-days: 1
-
-  merge:
-    name: Merge manifest and publish tags
-    runs-on: ubuntu-latest
-    needs: build
-    env:
-      IMAGE_NAME: diegosouzapw/omniroute
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-
-      - name: Extract version from release tag
-        id: version
-        run: |
-          VERSION="${GITHUB_REF_NAME}"
-          VERSION="${VERSION#v}"
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "Publishing Docker image version: $VERSION"
-
-      - name: Download digests
-        uses: actions/download-artifact@v4
-        with:
-          path: ${{ runner.temp }}/digests
-          pattern: digests-*
-          merge-multiple: true
-
-      - name: Login to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Create manifest list and push
-        working-directory: ${{ runner.temp }}/digests
-        run: |
-          docker buildx imagetools create \
-            -t "${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }}" \
-            -t "${{ env.IMAGE_NAME }}:latest" \
-            $(printf '${{ env.IMAGE_NAME }}@sha256:%s ' *)
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            ${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }}
+            ${{ env.IMAGE_NAME }}:latest
+            ghcr.io/diegosouzapw/omniroute:${{ steps.version.outputs.version }}
+            ghcr.io/diegosouzapw/omniroute:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          no-cache: false
+        env:
+          DOCKER_BUILDKIT_INLINE_CACHE: 1
 
       - name: Inspect image
         run: |
           docker buildx imagetools inspect "${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }}"
 
       - name: Update Docker Hub description
-        uses: peter-evans/dockerhub-description@v5
+        uses: peter-evans/dockerhub-description@v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}

.github/workflows/electron-release.yml

@@ -0,0 +1,215 @@
+name: Build Electron Desktop App
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version (e.g., v1.6.8)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  id-token: write
+  packages: write
+
+jobs:
+  validate:
+    name: Validate version
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.validate.outputs.version }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Validate version format
+        id: validate
+        run: |
+          if [[ "${{ github.event_name }}" == "push" ]]; then
+            VERSION="${GITHUB_REF#refs/tags/}"
+          else
+            VERSION="${{ inputs.version }}"
+          fi
+
+          if [[ ! "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Error: Invalid version format. Expected: v1.6.8"
+            exit 1
+          fi
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "✓ Valid version: $VERSION"
+
+  build:
+    name: Build Electron (${{ matrix.platform }})
+    needs: validate
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: windows
+            runner: windows-latest
+            target: win
+            ext: .exe
+          - platform: macos-intel
+            runner: macos-15-intel
+            target: mac-x64
+            ext: .dmg
+          - platform: macos-arm64
+            runner: macos-latest
+            target: mac-arm64
+            ext: -arm64.dmg
+          - platform: linux
+            runner: ubuntu-latest
+            target: linux
+            ext: .AppImage
+            deb_ext: .deb
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Cache node_modules
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build Next.js standalone
+        env:
+          JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
+        run: npm run build
+
+      - name: Sync version in electron/package.json
+        shell: bash
+        run: |
+          VERSION="${{ needs.validate.outputs.version }}"
+          VERSION_NO_V="${VERSION#v}"
+          node -e "
+            const fs = require('fs');
+            const pkg = JSON.parse(fs.readFileSync('electron/package.json'));
+            pkg.version = '$VERSION_NO_V';
+            fs.writeFileSync('electron/package.json', JSON.stringify(pkg, null, 2) + '\\n');
+          "
+          echo "✓ electron/package.json version set to $VERSION_NO_V"
+
+      - name: Install fpm (Linux .deb packaging tool)
+        if: matrix.platform == 'linux'
+        run: sudo gem install fpm --no-document
+
+      - name: Install Electron dependencies
+        working-directory: electron
+        run: npm install --no-audit --no-fund
+
+      - name: Build Electron for ${{ matrix.platform }}
+        working-directory: electron
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npm run build:${{ matrix.target }}
+
+      - name: Collect installers
+        shell: bash
+        run: |
+          mkdir -p release-assets
+          cd electron/dist-electron
+          # Copy only installer files for this platform
+          for file in *${{ matrix.ext }}; do
+            [ -f "$file" ] && cp "$file" ../../release-assets/
+          done
+          # Linux: also copy .deb package
+          if [ "${{ matrix.platform }}" = "linux" ]; then
+            for file in *.deb; do
+              [ -f "$file" ] && cp "$file" ../../release-assets/
+            done
+          fi
+          # Windows: also copy portable standalone exe as OmniRoute.exe
+          if [ "${{ matrix.platform }}" = "windows" ]; then
+            for file in *.exe; do
+              # Skip the NSIS installer (contains "Setup")
+              case "$file" in *Setup*) continue ;; esac
+              [ -f "$file" ] && cp "$file" "../../release-assets/OmniRoute.exe" && break
+            done
+          fi
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: electron-${{ matrix.platform }}
+          path: release-assets/
+
+  release:
+    name: Create Release
+    needs: [validate, build]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v8
+        with:
+          path: release-assets
+          merge-multiple: true
+
+      - name: Create source archives
+        run: |
+          # Create source code archives (excluding dev dependencies and build artifacts)
+          export TARBALL="OmniRoute-${{ needs.validate.outputs.version }}.source.tar.gz"
+          export ZIPBALL="OmniRoute-${{ needs.validate.outputs.version }}.source.zip"
+
+          # Use git archive for clean source export
+          git archive --format=tar.gz --prefix=OmniRoute-${{ needs.validate.outputs.version }}/ HEAD -o "release-assets/$TARBALL"
+          git archive --format=zip --prefix=OmniRoute-${{ needs.validate.outputs.version }}/ HEAD -o "release-assets/$ZIPBALL"
+
+          echo "✓ Created source archives:"
+          ls -lh "release-assets/$TARBALL" "release-assets/$ZIPBALL"
+
+      - name: List release files
+        run: ls -la release-assets/
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ needs.validate.outputs.version }}
+          draft: false
+          prerelease: false
+          generate_release_notes: true
+          fail_on_unmatched_files: false
+          files: |
+            release-assets/*.dmg
+            release-assets/*.exe
+            release-assets/*.AppImage
+            release-assets/*.deb
+            release-assets/*.blockmap
+            release-assets/*.source.tar.gz
+            release-assets/*.source.zip
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-npm:
+    name: Publish to npm
+    needs: [validate, release]
+    uses: ./.github/workflows/npm-publish.yml
+    with:
+      version: ${{ needs.validate.outputs.version }}
+      tag: latest
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/npm-publish.yml

@@ -3,10 +3,39 @@ name: Publish to npm
 on:
   release:
     types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to publish (e.g. 2.9.5 or 3.0.0-rc.15)"
+        required: true
+        type: string
+      tag:
+        description: "npm dist-tag (latest / next)"
+        required: false
+        default: "latest"
+        type: choice
+        options:
+          - latest
+          - next
+  workflow_call:
+    inputs:
+      version:
+        description: "Version to publish (without v prefix)"
+        required: true
+        type: string
+      tag:
+        description: "npm dist-tag (latest / next)"
+        required: false
+        default: "latest"
+        type: string
+    secrets:
+      NPM_TOKEN:
+        required: true
 
 permissions:
   contents: read
   id-token: write
+  packages: write
 
 jobs:
   publish:
@@ -22,21 +51,77 @@ jobs:
           node-version: 22
           registry-url: https://registry.npmjs.org
 
-      - name: Install dependencies
-        run: npm ci
+      - name: Install dependencies (skip scripts to avoid heavy build)
+        run: npm install --ignore-scripts --no-audit --no-fund
 
-      - name: Build standalone app
-        run: npm run build:cli
-
-      - name: Sync version from release tag
+      - name: Resolve version and dist-tag
+        id: resolve
         run: |
-          VERSION="${GITHUB_REF_NAME}"
-          # Remove 'v' prefix if present (v0.1.0 -> 0.1.0)
+          VERSION="${{ inputs.version }}"
+          TAG="${{ inputs.tag }}"
+
+          if [ -z "$VERSION" ]; then
+            if [ "${{ github.event_name }}" = "release" ]; then
+              VERSION="${GITHUB_REF_NAME}"
+            fi
+          fi
+
+          # Strip v prefix if present
           VERSION="${VERSION#v}"
-          npm version "$VERSION" --no-git-tag-version --allow-same-version
-          echo "Publishing version: $VERSION"
+
+          # Default dist-tag logic
+          if [ -z "$TAG" ]; then
+            if [[ "$VERSION" == *-* ]]; then
+              TAG="next"
+            else
+              TAG="latest"
+            fi
+          fi
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "tag=$TAG" >> $GITHUB_OUTPUT
+          echo "📦 Publishing omniroute@$VERSION with tag=$TAG"
+
+      - name: Sync package.json version
+        run: |
+          npm version "${{ steps.resolve.outputs.version }}" --no-git-tag-version --allow-same-version
+
+      - name: Build CLI bundle (standalone app)
+        env:
+          JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
+        run: node scripts/prepublish.mjs
 
       - name: Publish to npm
-        run: npm publish --access public
+        run: |
+          VERSION="${{ steps.resolve.outputs.version }}"
+          TAG="${{ steps.resolve.outputs.tag }}"
+          # Check if this version is already published — skip instead of failing with E403
+          if npm view "omniroute@${VERSION}" version --silent 2>/dev/null | grep -q "^${VERSION}$"; then
+            echo "⚠️ Version ${VERSION} is already published on npm — skipping."
+            exit 0
+          fi
+          if [ "$TAG" = "latest" ]; then
+            npm publish --access public
+          else
+            npm publish --access public --tag "$TAG"
+          fi
+          echo "✅ Published omniroute@$VERSION (tag: $TAG)"
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish to GitHub Packages
+        run: |
+          VERSION="${{ steps.resolve.outputs.version }}"
+          TAG="${{ steps.resolve.outputs.tag }}"
+
+          echo "Configuring for GitHub Packages..."
+          echo "//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" > .npmrc
+          npm pkg set name="@diegosouzapw/omniroute"
+
+          if [ "$TAG" = "latest" ]; then
+            npm publish --registry=https://npm.pkg.github.com || echo "⚠️ Version ${VERSION} might already be published on GitHub."
+          else
+            npm publish --registry=https://npm.pkg.github.com --tag "$TAG" || echo "⚠️ Version ${VERSION} might already be published on GitHub."
+          fi
+          echo "✅ Action finished for GitHub Packages"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -1,7 +1,18 @@
 # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
 
+# project-specific directories
+.omnivscodeagent/
+omnirouteCloud/
+omnirouteSite/
+
+# Root-level underscore-prefixed directories (private/draft — never commit)
+/_*/
+
+# Draft features documentation (internal only)
+docs/new-features/
+
 # dependencies
-/node_modules
+node_modules/
 /.pnp
 .pnp.*
 .yarn/*
@@ -9,12 +20,15 @@
 !.yarn/plugins
 !.yarn/releases
 !.yarn/versions
+.data/
+.next-playwright/
 
 # testing
-/coverage
+coverage/
+coverage**
 
 # next.js
-/.next/
+.next/
 /out/
 
 # production
@@ -45,11 +59,14 @@ next-env.d.ts
 
 # data and logs
 data/
+.data/
 logs/*
 
 # analysis directories (generated, not tracked)
 .analysis/
 antigravity-manager-analysis/
+.sisyphus/
+.plans/
 
 # docs (allow specific tracked files)
 docs/*
@@ -63,6 +80,7 @@ docs/*
 !docs/TASK_NEBIUS_BACKEND_ENABLEMENT.md
 !docs/frontend-backend-provider-gap-report.md
 !docs/openapi.yaml
+!docs/RELEASE_CHECKLIST.md
 !docs/PLANO-IMPLANTACAO.md
 !docs/TASKS.md
 !docs/FASE-*.md
@@ -74,6 +92,14 @@ docs/*
 !docs/VM_DEPLOYMENT_GUIDE.md
 !docs/FEATURES.md
 !docs/screenshots/
+!docs/i18n/
+!docs/i18n/**
+!docs/A2A-SERVER.md
+!docs/AUTO-COMBO.md
+!docs/MCP-SERVER.md
+!docs/CLI-TOOLS.md
+!docs/COVERAGE_PLAN.md
+
 
 # open-sse tests
 open-sse/test/*
@@ -86,14 +112,56 @@ test-results/
 playwright-report/
 blob-report/
 cloud/
-omnirouteCloud/
-omnirouteSite/
 
 # Security Analysis (standalone project with own git)
 security-analysis/
 
 # Deploy workflow (contains sensitive VPS credentials)
-.agent/workflows/deploy.md
 clipr/
 app.log
 *.tgz
+.gh-discussions.json
+
+# Backup directories
+app.__qa_backup/
+.app-build-backup-*/
+
+# Production standalone build (created by scripts/prepublish.mjs)
+# Conflicts with Next.js App Router detection in dev (root app/ shadows src/app/)
+# npm publish still includes it via package.json "files" field
+/app/
+
+# Electron (subproject dependency lock and build artifacts)
+electron/package-lock.json
+electron/dist-electron/
+electron/node_modules/
+icon.iconset/
+
+# VS Code Extension (independent Git repo)
+vscode-extension/
+
+# SQLite residual files
+*.sqlite-shm
+*.sqlite-wal
+*.sqlite-journal
+
+# Compiled npm-package build artifact (not source, should not be in git)
+/app
+
+# IDEA
+.idea/
+
+# Local OpenCode agent config
+.config/
+
+# Empty/dangling files
+typescript
+
+# Gemini Antigravity agent data
+.gemini/
+
+# Superpowers plans/specs (internal tooling, not project code)
+docs/superpowers/
+
+# GitNexus local index
+.gitnexus

.husky/pre-commit

@@ -1 +1,10 @@
+#!/usr/bin/env sh
+if ! command -v npx >/dev/null 2>&1; then
+  echo "⚠️  npx not found in PATH — skipping pre-commit hooks"
+  echo "   Run 'npm run lint && npm run check:any-budget:t11' manually before pushing."
+  exit 0
+fi
+
 npx lint-staged
+node scripts/check-docs-sync.mjs
+npm run check:any-budget:t11

.husky/pre-push

@@ -0,0 +1,8 @@
+#!/usr/bin/env sh
+if ! command -v npm >/dev/null 2>&1; then
+  echo "⚠️  npm not found in PATH — skipping pre-push hooks"
+  echo "   Run 'npm test' manually before pushing."
+  exit 0
+fi
+
+npm run test:unit

.node-version

@@ -0,0 +1 @@
+22

.npmignore

@@ -3,6 +3,11 @@ data/
 **/data/
 **/db.json
 
+# VS Code extension test runtime (large binary, not needed in npm package)
+app/vscode-extension/
+**/data/
+**/db.json
+
 # Source code (pre-built app/ is published instead)
 src/
 open-sse/
@@ -21,14 +26,19 @@ scripts/
 .github/
 .husky/
 .vscode/
+.agents/
 .env*
 eslint.config.mjs
 prettier.config.mjs
 postcss.config.mjs
 next.config.mjs
 tsconfig.json
+tsconfig.typecheck-core.json
+tsconfig.typecheck-noimplicit-core.json
 playwright.config.ts
+vitest.config.ts
 next-env.d.ts
+llm.txt
 
 # Docker
 docker-compose*.yml
@@ -36,9 +46,24 @@ Dockerfile
 .dockerignore
 
 # Misc
-restart.sh
 AGENTS.md
+bun.lock
 
 # Build artifacts (pre-built goes inside app/)
 .next/
 node_modules/
+
+# Ignore large binary files and other build directories
+*.tgz
+*.AppImage
+*.deb
+*.rpm
+electron/
+app/electron/
+app/vscode-extension/
+
+# Subprojects
+clipr/
+omnirouteCloud/
+omnirouteSite/
+vscode-extension/

.nvmrc

@@ -0,0 +1 @@
+22

.omc/project-memory.json

@@ -0,0 +1,250 @@
+{
+  "version": "1.0.0",
+  "lastScanned": 1775016362438,
+  "projectRoot": "/home/openclaw/omniroute-src",
+  "techStack": {
+    "languages": [
+      {
+        "name": "JavaScript/TypeScript",
+        "version": ">=18.0.0 <24.0.0",
+        "confidence": "high",
+        "markers": ["package.json"]
+      },
+      {
+        "name": "TypeScript",
+        "version": null,
+        "confidence": "high",
+        "markers": ["tsconfig.json"]
+      }
+    ],
+    "frameworks": [
+      {
+        "name": "express",
+        "version": "5.2.1",
+        "category": "backend"
+      },
+      {
+        "name": "next",
+        "version": "16.0.10",
+        "category": "fullstack"
+      },
+      {
+        "name": "react",
+        "version": "19.2.4",
+        "category": "frontend"
+      },
+      {
+        "name": "react-dom",
+        "version": "19.2.4",
+        "category": "frontend"
+      },
+      {
+        "name": "@playwright/test",
+        "version": "1.58.2",
+        "category": "testing"
+      },
+      {
+        "name": "vitest",
+        "version": "4.0.18",
+        "category": "testing"
+      }
+    ],
+    "packageManager": "npm",
+    "runtime": "Node.js 18.0.024.0.0"
+  },
+  "build": {
+    "buildCommand": "npm run build",
+    "testCommand": "npm test",
+    "lintCommand": "npm run lint",
+    "devCommand": "npm run dev",
+    "scripts": {
+      "dev": "node scripts/run-next.mjs dev",
+      "build": "node scripts/build-next-isolated.mjs",
+      "build:cli": "node scripts/prepublish.mjs",
+      "start": "node scripts/run-next.mjs start",
+      "lint": "eslint .",
+      "electron:dev": "concurrently \"npm run dev\" \"wait-on http://localhost:20128 && cd electron && npm run dev\"",
+      "electron:build": "npm run build && cd electron && npm run build",
+      "electron:build:win": "npm run build && cd electron && npm run build:win",
+      "electron:build:mac": "npm run build && cd electron && npm run build:mac",
+      "electron:build:linux": "npm run build && cd electron && npm run build:linux",
+      "test": "node --import tsx/esm --test tests/unit/*.test.mjs",
+      "test:unit": "node --import tsx/esm --test tests/unit/*.test.mjs",
+      "test:plan3": "node --import tsx/esm --test tests/unit/plan3-p0.test.mjs",
+      "test:fixes": "node --import tsx/esm --test tests/unit/fixes-p1.test.mjs",
+      "test:security": "node --import tsx/esm --test tests/unit/security-fase01.test.mjs",
+      "check:cycles": "node scripts/check-cycles.mjs",
+      "check:route-validation:t06": "node scripts/check-route-validation.mjs",
+      "check:any-budget:t11": "node scripts/check-t11-any-budget.mjs",
+      "check:docs-sync": "node scripts/check-docs-sync.mjs",
+      "typecheck:core": "tsc --pretty false -p tsconfig.typecheck-core.json",
+      "typecheck:noimplicit:core": "tsc --pretty false -p tsconfig.typecheck-noimplicit-core.json",
+      "test:integration": "node --import tsx/esm --test tests/integration/*.test.mjs",
+      "test:e2e": "node scripts/run-playwright-tests.mjs test tests/e2e/*.spec.ts",
+      "test:protocols:e2e": "node scripts/run-protocol-clients-tests.mjs",
+      "test:vitest": "vitest run open-sse/mcp-server/__tests__/*.test.ts open-sse/services/autoCombo/__tests__/*.test.ts",
+      "test:ecosystem": "node scripts/run-ecosystem-tests.mjs",
+      "test:coverage": "c8 --exclude=tests/** --exclude=**/*.test.* --reporter=text-summary --reporter=html --reporter=json-summary --reporter=lcov --check-coverage --statements 55 --lines 55 --functions 55 --branches 60 node --import tsx/esm --test tests/unit/*.test.mjs",
+      "test:coverage:legacy": "c8 --exclude=open-sse --check-coverage --lines 50 --functions 50 --branches 50 node --import tsx/esm --test tests/unit/*.test.mjs",
+      "coverage:report": "c8 report --exclude=tests/** --exclude=**/*.test.* --reporter=text --reporter=text-summary --reporter=html --reporter=json-summary --reporter=lcov",
+      "coverage:report:legacy": "c8 report --exclude=open-sse --reporter=text --reporter=text-summary",
+      "test:all": "npm run test:unit && npm run test:vitest && npm run test:ecosystem && npm run test:e2e",
+      "check": "npm run lint && npm run test",
+      "prepublishOnly": "npm run build:cli",
+      "postinstall": "node scripts/postinstall.mjs",
+      "prepare": "husky",
+      "system-info": "node scripts/system-info.mjs"
+    }
+  },
+  "conventions": {
+    "namingStyle": "camelCase",
+    "importStyle": null,
+    "testPattern": null,
+    "fileOrganization": null
+  },
+  "structure": {
+    "isMonorepo": true,
+    "workspaces": ["open-sse"],
+    "mainDirectories": ["bin", "docs", "public", "scripts", "src", "tests"],
+    "gitBranches": {
+      "defaultBranch": "main",
+      "branchingStrategy": null
+    }
+  },
+  "customNotes": [],
+  "directoryMap": {
+    "bin": {
+      "path": "bin",
+      "purpose": "Executable scripts",
+      "fileCount": 3,
+      "lastAccessed": 1775016362426,
+      "keyFiles": ["mcp-server.mjs", "omniroute.mjs", "reset-password.mjs"]
+    },
+    "docs": {
+      "path": "docs",
+      "purpose": "Documentation",
+      "fileCount": 14,
+      "lastAccessed": 1775016362426,
+      "keyFiles": [
+        "A2A-SERVER.md",
+        "API_REFERENCE.md",
+        "ARCHITECTURE.md",
+        "AUTO-COMBO.md",
+        "CLI-TOOLS.md"
+      ]
+    },
+    "electron": {
+      "path": "electron",
+      "purpose": null,
+      "fileCount": 5,
+      "lastAccessed": 1775016362431,
+      "keyFiles": ["README.md", "main.js", "package.json", "preload.js", "types.d.ts"]
+    },
+    "images": {
+      "path": "images",
+      "purpose": null,
+      "fileCount": 1,
+      "lastAccessed": 1775016362434,
+      "keyFiles": ["omniroute.png"]
+    },
+    "logs": {
+      "path": "logs",
+      "purpose": null,
+      "fileCount": 3,
+      "lastAccessed": 1775016362434,
+      "keyFiles": ["build_clean_tools.log", "build_debug.log", "build_force_clean.log"]
+    },
+    "open-sse": {
+      "path": "open-sse",
+      "purpose": null,
+      "fileCount": 5,
+      "lastAccessed": 1775016362434,
+      "keyFiles": ["index.ts", "package.json", "tsconfig.json", "types.d.ts"]
+    },
+    "public": {
+      "path": "public",
+      "purpose": "Public files",
+      "fileCount": 3,
+      "lastAccessed": 1775016362435,
+      "keyFiles": ["apple-touch-icon.svg", "favicon.svg", "icon-192.svg"]
+    },
+    "scripts": {
+      "path": "scripts",
+      "purpose": "Build/utility scripts",
+      "fileCount": 23,
+      "lastAccessed": 1775016362435,
+      "keyFiles": [
+        "bootstrap-env.mjs",
+        "build-next-isolated.mjs",
+        "check-cycles.mjs",
+        "check-docs-sync.mjs",
+        "check-route-validation.mjs"
+      ]
+    },
+    "src": {
+      "path": "src",
+      "purpose": "Source code",
+      "fileCount": 4,
+      "lastAccessed": 1775016362435,
+      "keyFiles": ["instrumentation-node.ts", "instrumentation.ts", "proxy.ts", "server-init.ts"]
+    },
+    "tests": {
+      "path": "tests",
+      "purpose": "Test files",
+      "fileCount": 0,
+      "lastAccessed": 1775016362435,
+      "keyFiles": []
+    },
+    "electron/assets": {
+      "path": "electron/assets",
+      "purpose": "Static assets",
+      "fileCount": 4,
+      "lastAccessed": 1775016362436,
+      "keyFiles": ["icon.icns", "icon.ico", "icon.png"]
+    },
+    "open-sse/config": {
+      "path": "open-sse/config",
+      "purpose": "Configuration files",
+      "fileCount": 17,
+      "lastAccessed": 1775016362436,
+      "keyFiles": ["audioRegistry.ts", "cliFingerprints.ts", "codexInstructions.ts"]
+    },
+    "open-sse/services": {
+      "path": "open-sse/services",
+      "purpose": "Business logic services",
+      "fileCount": 35,
+      "lastAccessed": 1775016362437,
+      "keyFiles": ["accountFallback.ts", "accountSelector.ts", "apiKeyRotator.ts"]
+    },
+    "src/app": {
+      "path": "src/app",
+      "purpose": "Application code",
+      "fileCount": 7,
+      "lastAccessed": 1775016362438,
+      "keyFiles": ["error.tsx", "global-error.tsx", "globals.css"]
+    },
+    "src/lib": {
+      "path": "src/lib",
+      "purpose": "Library code",
+      "fileCount": 30,
+      "lastAccessed": 1775016362438,
+      "keyFiles": ["apiBridgeServer.ts", "apiKeyExposure.ts", "cacheControlSettings.ts"]
+    },
+    "src/middleware": {
+      "path": "src/middleware",
+      "purpose": "Middleware",
+      "fileCount": 1,
+      "lastAccessed": 1775016362438,
+      "keyFiles": ["promptInjectionGuard.ts"]
+    },
+    "src/models": {
+      "path": "src/models",
+      "purpose": "Data models",
+      "fileCount": 1,
+      "lastAccessed": 1775016362438,
+      "keyFiles": ["index.ts"]
+    }
+  },
+  "hotPaths": [],
+  "userDirectives": []
+}

.omc/sessions/53c002c3-36a6-47c3-a52d-a8f756c264eb.json

@@ -0,0 +1,8 @@
+{
+  "session_id": "53c002c3-36a6-47c3-a52d-a8f756c264eb",
+  "ended_at": "2026-04-01T04:06:04.924Z",
+  "reason": "prompt_input_exit",
+  "agents_spawned": 0,
+  "agents_completed": 0,
+  "modes_used": []
+}

AGENTS.md

@@ -3,104 +3,264 @@
 ## Project
 
 Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support
-(OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks, Cohere, etc.)
+with **60+ providers** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks,
+Cohere, NVIDIA, Cerebras, Pollinations, Puter, Cloudflare AI, HuggingFace, and many more)
+with **MCP Server** (25 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.
 
 ## Stack
 
-- **Runtime**: Next.js 16 (App Router), Node.js, ES Modules
-- **Language**: TypeScript 5.9 (`src/`) + JavaScript (`open-sse/`)
+- **Runtime**: Next.js 16 (App Router), Node.js ≥18 <24, ES Modules (`"type": "module"`)
+- **Language**: TypeScript 5.9 (`src/`) + JavaScript (`open-sse/`, `electron/`)
 - **Database**: better-sqlite3 (SQLite) — `DATA_DIR` configurable, default `~/.omniroute/`
-- **Streaming**: SSE via `open-sse` internal package
+- **Streaming**: SSE via `open-sse` internal workspace package
 - **Styling**: Tailwind CSS v4
-- **Docker**: Multi-stage Dockerfile, 3 profiles (base / cli / host)
+- **i18n**: next-intl with 30 languages
+- **Desktop**: Electron (cross-platform: Windows, macOS, Linux)
+- **Schemas**: Zod v4 for all API / MCP input validation
+
+---
+
+## Build, Lint, and Test Commands
+
+| Command                             | Description                       |
+| ----------------------------------- | --------------------------------- |
+| `npm run dev`                       | Start Next.js dev server          |
+| `npm run build`                     | Production build (isolated)       |
+| `npm run start`                     | Run production build              |
+| `npm run build:cli`                 | Build CLI package                 |
+| `npm run lint`                      | ESLint on all source files        |
+| `npm run typecheck:core`            | TypeScript core type checking     |
+| `npm run typecheck:noimplicit:core` | Strict checking (no implicit any) |
+| `npm run check`                     | Run lint + test                   |
+| `npm run check:cycles`              | Check for circular dependencies   |
+| `npm run electron:dev`              | Run Electron app in dev mode      |
+| `npm run electron:build`            | Build Electron app for current OS |
+
+### Running Tests
+
+```bash
+# All tests (unit + vitest + ecosystem + e2e)
+npm run test:all
+
+# Single test file (Node.js native test runner — most tests use this)
+node --import tsx/esm --test tests/unit/your-file.test.mjs
+node --import tsx/esm --test tests/unit/plan3-p0.test.mjs
+node --import tsx/esm --test tests/unit/fixes-p1.test.mjs
+node --import tsx/esm --test tests/unit/security-fase01.test.mjs
+
+# Integration tests
+node --import tsx/esm --test tests/integration/*.test.mjs
+
+# Vitest (MCP server, autoCombo)
+npm run test:vitest
+
+# E2E with Playwright
+npm run test:e2e
+
+# Protocol clients E2E (MCP transports, A2A)
+npm run test:protocols:e2e
+
+# Ecosystem compatibility tests
+npm run test:ecosystem
+
+# Coverage (60% minimum for statements, lines, functions, and branches)
+npm run test:coverage
+```
+
+### PR Coverage Policy
+
+- `npm run test:coverage` is the PR coverage gate in CI.
+- The repository minimum is **60%** for statements, lines, functions, and branches.
+- If a PR changes production code in `src/`, `open-sse/`, `electron/`, or `bin/`, it must include or update automated tests in the same PR.
+- For agent-driven review or coding flows: if coverage is below the gate or source changes ship without tests, do not stop at reporting. Add or update tests first, rerun the gate, and only then ask for confirmation.
+
+---
+
+## Code Style Guidelines
+
+### Formatting (Prettier — enforced via lint-staged)
+
+2 spaces · semicolons required · double quotes (`"`) · 100 char width · es5 trailing commas.
+Always run `prettier --write` on changed files.
+
+### TypeScript
+
+- **Target**: ES2022 · **Module**: `esnext` · **Resolution**: `bundler`
+- `strict: false` — prefer explicit types, don't rely on inference
+- Path aliases: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
+
+### ESLint Rules
+
+- **Security (error, everywhere)**: `no-eval`, `no-implied-eval`, `no-new-func`
+- **Relaxed in `open-sse/` and `tests/`**: `@typescript-eslint/no-explicit-any` = warn
+- React hooks rules and `@next/next/no-assign-module-variable` disabled in `open-sse/` and `tests/`
+
+### Naming
+
+| Element             | Convention                       | Example                              |
+| ------------------- | -------------------------------- | ------------------------------------ |
+| Files               | camelCase / kebab-case           | `chatCore.ts`, `tokenHealthCheck.ts` |
+| React components    | PascalCase                       | `Dashboard.tsx`, `ProviderCard.tsx`  |
+| Functions/variables | camelCase                        | `getHealth()`, `switchCombo()`       |
+| Constants           | UPPER_SNAKE                      | `MAX_RETRIES`, `DEFAULT_TIMEOUT`     |
+| Interfaces          | PascalCase (`I` prefix optional) | `ProviderConfig`                     |
+| Enums               | PascalCase (members too)         | `LogLevel.Error`                     |
+
+### Imports
+
+- **Order**: external → internal (`@/`, `@omniroute/open-sse`) → relative (`./`, `../`)
+- **No barrel imports** from `localDb.ts` — import from the specific `db/` module instead
+
+### Error Handling
+
+- try/catch with specific error types; always log with context (pino logger)
+- Never silently swallow errors in SSE streams — use abort signals for cleanup
+- Return proper HTTP status codes (4xx client, 5xx server)
+
+### Security
+
+- **NEVER** commit API keys, secrets, or credentials
+- Validate all user inputs with Zod schemas
+- Auth middleware required on all API routes
+- Never log SQLite encryption keys
+- Sanitize user content (dompurify for HTML)
+
+---
 
 ## Architecture
 
 ### Data Layer (`src/lib/db/`)
 
 All persistence uses SQLite through domain-specific modules:
-
-| Module         | Responsibility                             |
-| -------------- | ------------------------------------------ |
-| `core.ts`      | SQLite engine, migrations, WAL, encryption |
-| `providers.ts` | Provider connections & nodes               |
-| `models.ts`    | Model aliases, MITM aliases, custom models |
-| `combos.ts`    | Combo configurations                       |
-| `apiKeys.ts`   | API key management & validation            |
-| `settings.ts`  | Settings, pricing, proxy config            |
-| `backup.ts`    | Backup / restore operations                |
-
-`src/lib/localDb.ts` is a **re-export layer only** — all 27+ consumers import from it,
-but the real logic lives in `src/lib/db/`.
+`core.ts`, `providers.ts`, `models.ts`, `combos.ts`, `apiKeys.ts`, `settings.ts`,
+`backup.ts`, `proxies.ts`, `prompts.ts`, `webhooks.ts`, `detailedLogs.ts`,
+`domainState.ts`, `registeredKeys.ts`, `quotaSnapshots.ts`, `modelComboMappings.ts`,
+`cliToolState.ts`, `encryption.ts`, `readCache.ts`, `secrets.ts`, `stateReset.ts`,
+`contextHandoffs.ts`.
+Schema migrations live in `db/migrations/` and run via `migrationRunner.ts`.
+`src/lib/localDb.ts` is a **re-export layer only** — never add logic there.
 
 ### Request Pipeline (`open-sse/`)
 
-| Handler                 | Role                                        |
-| ----------------------- | ------------------------------------------- |
-| `chatCore.js`           | Main chat completions proxy (SSE / non-SSE) |
-| `responsesHandler.js`   | OpenAI Responses API compat                 |
-| `responseTranslator.js` | Format translation for Responses API        |
-| `embeddings.js`         | Embedding proxy                             |
-| `imageGeneration.js`    | Image generation proxy                      |
-| `sseParser.js`          | SSE stream parser                           |
-| `usageExtractor.js`     | Token usage extraction from responses       |
+`chatCore.ts` → executor → upstream provider. Translations in `open-sse/translator/`.
 
-Translation between provider formats: `open-sse/translator/`
+**Handlers** (`open-sse/handlers/`): `chatCore.ts`, `responsesHandler.ts`, `embeddings.ts`,
+`imageGeneration.ts`, `videoGeneration.ts`, `musicGeneration.ts`, `audioSpeech.ts`,
+`audioTranscription.ts`, `moderations.ts`, `rerank.ts`, `search.ts`.
 
-### OAuth & Tokens (`src/lib/oauth/`)
+**Upstream headers**: merged after default auth; same header name replaces executor value.
+**T5 intra-family fallback** recomputes headers using only the fallback model id.
+Forbidden header names: `src/shared/constants/upstreamHeaders.ts` — keep sanitize,
+Zod schemas, and unit tests aligned when editing.
 
-18 modules handling OAuth flows, token refresh, and provider credentials.
-Default credentials are hardcoded in `src/lib/oauth/constants/oauth.ts`,
-overridable via env vars or `data/provider-credentials.json`.
+### Provider Categories
 
-### Supporting Systems
+- **Free** (4): Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+- **OAuth** (8): Claude Code, Antigravity, Codex, GitHub Copilot, Cursor, Kimi Coding, Kilo Code, Cline
+- **API Key** (48+): OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Perplexity,
+  Together, Fireworks, Cerebras, Cohere, NVIDIA, Nebius, SiliconFlow, Hyperbolic,
+  HuggingFace, OpenRouter, Vertex AI, Cloudflare AI, Scaleway, AI/ML API, Pollinations,
+  Puter, Longcat, Alibaba, Kimi, Minimax, Blackbox, Synthetic, Kilo Gateway,
+  Z.AI, GLM, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld,
+  NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper, Brave, Exa,
+  Tavily, OpenCode Zen/Go, Bailian Coding Plan, and more.
+- **Custom**: OpenAI-compatible (`openai-compatible-*`) and Anthropic-compatible (`anthropic-compatible-*`) prefixes
 
-| System                     | Location                                          |
-| -------------------------- | ------------------------------------------------- |
-| Usage tracking & analytics | `src/lib/usageDb.ts`, `src/lib/usageAnalytics.ts` |
-| Token health checks        | `src/lib/tokenHealthCheck.ts`                     |
-| Cloud sync                 | `src/lib/cloudSync.ts`                            |
-| Proxy logging              | `src/lib/proxyLogger.ts`                          |
-| Data paths resolution      | `src/lib/dataPaths.ts`                            |
+Providers are registered in `src/shared/constants/providers.ts` with Zod validation at module load.
+
+### Executors (`open-sse/executors/`)
+
+Provider-specific request executors: `base.ts`, `default.ts`, `cursor.ts`, `codex.ts`,
+`antigravity.ts`, `github.ts`, `gemini-cli.ts`, `kiro.ts`, `qoder.ts`, `vertex.ts`,
+`cloudflare-ai.ts`, `opencode.ts`, `pollinations.ts`, `puter.ts`.
+
+### Translator (`open-sse/translator/`)
+
+Translates between API formats (OpenAI-format ↔ Anthropic, Gemini, etc.).
+Includes request/response translators with helpers for image handling.
+
+### Transformer (`open-sse/transformer/`)
+
+`responsesTransformer.ts` — transforms Responses API format to/from Chat Completions format.
+
+### Services (`open-sse/services/`)
+
+36+ service modules including: `combo.ts` (routing engine), `usage.ts`, `tokenRefresh.ts`,
+`rateLimitManager.ts`, `accountFallback.ts`, `sessionManager.ts`, `wildcardRouter.ts`,
+`autoCombo/`, `intentClassifier.ts`, `taskAwareRouter.ts`, `thinkingBudget.ts`,
+`contextManager.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`,
+`emergencyFallback.ts`, `workflowFSM.ts`, `backgroundTaskDetector.ts`, `ipFilter.ts`,
+`signatureCache.ts`, `volumeDetector.ts`, `contextHandoff.ts`, and more.
+
+### Domain Layer (`src/domain/`)
+
+Policy engine modules: `policyEngine.ts`, `comboResolver.ts`, `costRules.ts`,
+`degradation.ts`, `fallbackPolicy.ts`, `lockoutPolicy.ts`, `modelAvailability.ts`,
+`providerExpiration.ts`, `quotaCache.ts`, `responses.ts`, `configAudit.ts`.
+
+### MCP Server (`open-sse/mcp-server/`)
+
+25 tools, 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (10 scopes), Zod schemas.
+
+**Core tools** (18): get_health, list_combos, get_combo_metrics, switch_combo, check_quota,
+route_request, cost_report, list_models_catalog, simulate_route, set_budget_guard,
+set_routing_strategy, set_resilience_profile, test_combo, get_provider_metrics,
+best_combo_for_task, explain_route, get_session_snapshot, sync_pricing.
+
+**Memory tools** (3): memory_search, memory_add, memory_clear.
+
+**Skill tools** (4): skills_list, skills_enable, skills_execute, skills_executions.
+
+### A2A Server (`src/lib/a2a/`)
+
+JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup(
+Agent Card at `/.well-known/agent.json`.
+Skills: `quotaManagement.ts`, `smartRouting.ts`.
+
+### ACP Module (`src/lib/acp/`)
+
+Agent Communication Protocol registry and manager.
+
+### Memory System (`src/lib/memory/`)
+
+Extraction, injection, retrieval, summarization, and store modules for persistent
+conversational memory across sessions.
+
+### Skills System (`src/lib/skills/`)
+
+Extensible skill framework: registry, executor, sandbox, built-in skills,
+custom skill support, interception, and injection.
+
+### Compliance (`src/lib/compliance/`)
+
+Policy index for compliance enforcement.
+
+### MITM Proxy (`src/mitm/`)
+
+MITM proxy capability with certificate management, DNS handling, and target routing.
+
+### Middleware (`src/middleware/`)
+
+Request middleware including `promptInjectionGuard.ts`.
 
 ### Adding a New Provider
 
 1. Register in `src/shared/constants/providers.ts`
-2. Add executor in `open-sse/executors/`
-3. Add translator rules in `open-sse/translator/` (if non-OpenAI format)
+2. Add executor in `open-sse/executors/` (if custom logic needed)
+3. Add translator in `open-sse/translator/` (if non-OpenAI format)
 4. Add OAuth config in `src/lib/oauth/constants/oauth.ts` (if OAuth-based)
+5. Add models in `open-sse/config/providerRegistry.ts`
+
+---
 
 ## Review Focus
 
-### Security
-
-- No hardcoded API keys or secrets in commits
-- Auth middleware on all API routes
-- Input validation on user-facing endpoints
-- SQLite encryption key must not be logged
-
-### Architecture
-
-- DB operations go through `src/lib/db/` modules, never raw SQL in routes
-- Provider requests flow through `open-sse/handlers/`
-- Translations use `open-sse/translator/` modules
-- `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module
-
-### Code Quality
-
-- Consistent error handling with try/catch
-- Proper HTTP status codes
-- No memory leaks in SSE streams (abort signals, cleanup)
-- Rate limit headers must be parsed correctly
-
-### Docker
-
-- Dockerfile has two targets: `runner-base` and `runner-cli`
-- `docker-compose.yml` — development (3 profiles)
-- `docker-compose.prod.yml` — isolated production instance (port 20130)
-- Data persists in named volumes (`omniroute-data` / `omniroute-prod-data`)
-
-### Review Mode
-
-- Provide analysis and suggestions only
-- Focus on bugs, security, performance, and best practices
+- **DB ops** go through `src/lib/db/` modules, never raw SQL in routes
+- **Provider requests** flow through `open-sse/handlers/`
+- **MCP/A2A pages** are tabs inside `/dashboard/endpoint`, not standalone routes
+- **No memory leaks** in SSE streams (abort signals, cleanup)
+- **Rate limit headers** must be parsed correctly
+- All API inputs validated with **Zod schemas**
+- **Provider constants** validated at module load via Zod (`src/shared/validation/providerSchema.ts`)
+- **Pricing data** syncs from LiteLLM via `src/lib/pricingSync.ts`
+- **Memory/Skills** are cross-cutting: affect MCP tools, request pipeline, and A2A skills

CONTRIBUTING.md

@@ -8,7 +8,7 @@ Thank you for your interest in contributing! This guide covers everything you ne
 
 ### Prerequisites
 
-- **Node.js** 20+ (recommended: 22 LTS)
+- **Node.js** >= 18 < 24 (recommended: 22 LTS)
 - **npm** 10+
 - **Git**
 
@@ -33,13 +33,24 @@ echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env
 
 Key variables for development:
 
-| Variable               | Development Default     | Description               |
-| ---------------------- | ----------------------- | ------------------------- |
-| `PORT`                 | `3000`                  | Server port               |
-| `NEXT_PUBLIC_BASE_URL` | `http://localhost:3000` | Base URL for frontend     |
-| `JWT_SECRET`           | (generate above)        | JWT signing secret        |
-| `INITIAL_PASSWORD`     | `123456`                | First login password      |
-| `ENABLE_REQUEST_LOGS`  | `false`                 | Enable debug request logs |
+| Variable               | Development Default      | Description           |
+| ---------------------- | ------------------------ | --------------------- |
+| `PORT`                 | `20128`                  | Server port           |
+| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend |
+| `JWT_SECRET`           | (generate above)         | JWT signing secret    |
+| `INITIAL_PASSWORD`     | `CHANGEME`               | First login password  |
+| `APP_LOG_LEVEL`        | `info`                   | Log verbosity level   |
+
+### Dashboard Settings
+
+The dashboard provides UI toggles for features that can also be configured via environment variables:
+
+| Setting Location    | Toggle             | Description                    |
+| ------------------- | ------------------ | ------------------------------ |
+| Settings → Advanced | Debug Mode         | Enable debug request logs (UI) |
+| Settings → General  | Sidebar Visibility | Show/hide sidebar sections     |
+
+These settings are stored in the database and persist across restarts, overriding env var defaults when set.
 
 ### Running Locally
 
@@ -57,8 +68,8 @@ PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
 
 Default URLs:
 
-- **Dashboard**: `http://localhost:3000/dashboard`
-- **API**: `http://localhost:3000/v1`
+- **Dashboard**: `http://localhost:20128/dashboard`
+- **API**: `http://localhost:20128/v1`
 
 ---
 
@@ -97,50 +108,80 @@ test: add observability unit tests
 refactor(db): consolidate rate limit tables
 ```
 
-Scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`.
+Scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`.
 
 ---
 
 ## Running Tests
 
 ```bash
-# All unit tests
-npm test
-npm run test:unit
+# All tests (unit + vitest + ecosystem + e2e)
+npm run test:all
 
-# Specific test suites
-npm run test:security     # Security tests
-npm run test:fixes        # Fix verification tests
+# Single test file (Node.js native test runner — most tests use this)
+node --import tsx/esm --test tests/unit/your-file.test.mjs
 
-# With coverage
-npm run test:coverage
+# Vitest (MCP server, autoCombo, cache)
+npm run test:vitest
 
 # E2E tests (requires Playwright)
 npm run test:e2e
 
+# Protocol clients E2E (MCP transports, A2A)
+npm run test:protocols:e2e
+
+# Ecosystem compatibility tests
+npm run test:ecosystem
+
+# Coverage (60% min statements/lines/functions/branches)
+npm run test:coverage
+npm run coverage:report
+
 # Lint + format check
 npm run lint
 npm run check
 ```
 
-Current test status: **368+ unit tests** covering:
+Coverage notes:
+
+- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**`
+- Pull requests must keep the overall coverage gate at **60% or higher** for statements, lines, functions, and branches
+- If a PR changes production code in `src/`, `open-sse/`, `electron/`, or `bin/`, it must add or update automated tests in the same PR
+- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run
+- `npm run test:coverage:legacy` preserves the older metric for historical comparison
+- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap
+
+### Pull Request Requirements
+
+Before opening or merging a PR:
+
+- Run `npm run test:unit`
+- Run `npm run test:coverage`
+- Ensure the coverage gate stays at **60%+** for all metrics
+- Include the changed or added test files in the PR description when production code changed
+- Check the SonarQube result on the PR when the project secrets are configured in CI
+
+Current test status: **122 unit test files** covering:
 
 - Provider translators and format conversion
 - Rate limiting, circuit breaker, and resilience
 - Semantic cache, idempotency, progress tracking
-- Database operations and schema
+- Database operations and schema (21 DB modules)
 - OAuth flows and authentication
-- API endpoint validation
+- API endpoint validation (Zod v4)
+- MCP server tools and scope enforcement
+- Memory and Skills systems
 
 ---
 
 ## Code Style
 
 - **ESLint** — Run `npm run lint` before committing
-- **Prettier** — Auto-formatted via `lint-staged` on commit
-- **TypeScript** — All `src/` code uses `.ts`/`.tsx`; document with TSDoc (`@param`, `@returns`, `@throws`)
+- **Prettier** — Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas)
+- **TypeScript** — All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`)
 - **No `eval()`** — ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func`
-- **Zod validation** — Use Zod schemas for API input validation
+- **Zod validation** — Use Zod v4 schemas for all API input validation
+- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE
 
 ---
 
@@ -148,40 +189,60 @@ Current test status: **368+ unit tests** covering:
 
 ```
 src/                        # TypeScript (.ts / .tsx)
-├── app/                    # Next.js App Router
-│   ├── (dashboard)/        # Dashboard pages (.tsx)
-│   ├── api/                # API routes (.ts)
+├── app/                    # Next.js 16 App Router
+│   ├── (dashboard)/        # Dashboard pages (23 sections)
+│   ├── api/                # API routes (51 directories)
 │   └── login/              # Auth pages (.tsx)
-├── domain/                 # Domain types and response helpers (.ts)
+├── domain/                 # Policy engine (policyEngine, comboResolver, costRules, etc.)
 ├── lib/                    # Core business logic (.ts)
-│   ├── db/                 # SQLite database layer
-│   ├── oauth/              # OAuth services per provider
-│   ├── cacheLayer.ts       # LRU cache
-│   ├── semanticCache.ts    # Semantic response cache
-│   ├── idempotencyLayer.ts # Request deduplication
-│   └── localDb.ts          # Settings facade (LowDB for config, SQLite for domain data)
+│   ├── a2a/                # Agent-to-Agent v0.3 protocol server
+│   ├── acp/                # Agent Communication Protocol registry
+│   ├── compliance/         # Compliance policy engine
+│   ├── db/                 # SQLite database layer (21 modules + 16 migrations)
+│   ├── memory/             # Persistent conversational memory
+│   ├── oauth/              # OAuth providers, services, and utilities
+│   ├── skills/             # Extensible skill framework
+│   ├── usage/              # Usage tracking and cost calculation
+│   └── localDb.ts          # Re-export layer only — never add logic here
+├── middleware/              # Request middleware (promptInjectionGuard)
+├── mitm/                   # MITM proxy (cert, DNS, target routing)
 ├── shared/
 │   ├── components/         # React components (.tsx)
-│   ├── middleware/          # Correlation IDs, etc.
-│   ├── utils/              # Circuit breaker, sanitizer, etc.
-│   └── validation/         # Zod schemas
-└── sse/                    # SSE chat handlers (.ts)
+│   ├── constants/          # Provider definitions (60+), MCP scopes, routing strategies
+│   ├── utils/              # Circuit breaker, sanitizer, auth helpers
+│   └── validation/         # Zod v4 schemas
+└── sse/                    # SSE proxy pipeline
 
-open-sse/                   # @omniroute/open-sse workspace (JavaScript)
-├── handlers/               # chatCore.js — main request handler
-├── services/               # Rate limit, fallback
-├── translators/            # Format converters (OpenAI ↔ Claude ↔ Gemini)
-└── utils/                  # Progress tracker, stream helpers
+open-sse/                   # @omniroute/open-sse workspace
+├── executors/              # 14 provider-specific request executors
+├── handlers/               # 11 request handlers (chat, responses, embeddings, images, etc.)
+├── mcp-server/             # MCP server (25 tools, 3 transports, 10 scopes)
+├── services/               # 36+ services (combo, autoCombo, rateLimitManager, etc.)
+├── translator/             # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama)
+├── transformer/            # Responses API transformer
+└── utils/                  # 22 utility modules (stream, TLS, proxy, logging)
+
+electron/                   # Electron desktop app (cross-platform)
 
 tests/
-├── unit/                   # Node.js test runner (.test.mjs)
-└── e2e/                    # Playwright tests
+├── unit/                   # Node.js test runner (122 test files)
+├── integration/            # Integration tests
+├── e2e/                    # Playwright tests
+├── security/               # Security tests
+├── translator/             # Translator-specific tests
+└── load/                   # Load tests
 
 docs/                       # Documentation
-├── USER_GUIDE.md           # Provider setup, CLI integration
-├── API_REFERENCE.md        # All endpoints
-├── TROUBLESHOOTING.md      # Common issues
 ├── ARCHITECTURE.md         # System architecture
+├── API_REFERENCE.md        # All endpoints
+├── USER_GUIDE.md           # Provider setup, CLI integration
+├── TROUBLESHOOTING.md      # Common issues
+├── MCP-SERVER.md           # MCP server (25 tools)
+├── A2A-SERVER.md           # A2A agent protocol
+├── AUTO-COMBO.md           # Auto-combo engine
+├── CLI-TOOLS.md            # CLI tools integration
+├── COVERAGE_PLAN.md        # Test coverage improvement plan
+├── openapi.yaml            # OpenAPI specification
 └── adr/                    # Architecture Decision Records
 ```
 
@@ -189,50 +250,25 @@ docs/                       # Documentation
 
 ## Adding a New Provider
 
-### Step 1: OAuth Service (if using OAuth)
+### Step 1: Register Provider Constants
 
-Create `src/lib/oauth/services/your-provider.ts` extending `OAuthService`:
+Add to `src/shared/constants/providers.ts` — Zod-validated at module load.
 
-```typescript
-import { OAuthService } from "../OAuthService";
+### Step 2: Add Executor (if custom logic needed)
 
-export class YourProviderService extends OAuthService {
-  constructor() {
-    super({
-      name: "your-provider",
-      authUrl: "https://provider.com/oauth/authorize",
-      tokenUrl: "https://provider.com/oauth/token",
-      clientId: "...",
-      scopes: ["..."],
-    });
-  }
-}
-```
+Create executor in `open-sse/executors/your-provider.ts` extending the base executor.
 
-### Step 2: Register Provider
+### Step 3: Add Translator (if non-OpenAI format)
 
-Add to `src/lib/oauth/providers.ts`:
+Create request/response translators in `open-sse/translator/`.
 
-```typescript
-import { YourProviderService } from "./services/your-provider";
-// Add to the providers map
-```
+### Step 4: Add OAuth Config (if OAuth-based)
 
-### Step 3: Add Constants
+Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`.
 
-Add provider constants in `src/lib/providerConstants.ts`:
+### Step 5: Register Models
 
-- Provider prefix (e.g., `yp/`)
-- Default models
-- Pricing info
-
-### Step 4: Add Translator (if non-OpenAI format)
-
-Create translator in `open-sse/translators/` if the provider uses a custom API format.
-
-### Step 5: Add Timeout
-
-Add request timeout configuration in `src/shared/utils/requestTimeout.ts`.
+Add model definitions in `open-sse/config/providerRegistry.ts`.
 
 ### Step 6: Add Tests
 
@@ -251,6 +287,7 @@ Write unit tests in `tests/unit/` covering at minimum:
 - [ ] Build succeeds (`npm run build`)
 - [ ] TypeScript types added for new public functions and interfaces
 - [ ] No hardcoded secrets or fallback values
+- [ ] All inputs validated with Zod schemas
 - [ ] CHANGELOG updated (if user-facing change)
 - [ ] Documentation updated (if applicable)
 
@@ -258,16 +295,13 @@ Write unit tests in `tests/unit/` covering at minimum:
 
 ## Releasing
 
-When a new GitHub Release is created (e.g. `v0.4.0`), the package is **automatically published to npm** via GitHub Actions:
-
-```bash
-gh release create v0.4.0 --title "v0.4.0" --generate-notes
-```
+Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions.
 
 ---
 
 ## Getting Help
 
 - **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
+- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md)
 - **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
 - **ADRs**: See `docs/adr/` for architectural decision records

Dockerfile

@@ -1,13 +1,19 @@
-FROM node:22-bookworm-slim AS builder
+FROM node:22.22.2-trixie-slim AS builder
 WORKDIR /app
 
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends libsecret-1-0 ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
+
 COPY package*.json ./
+COPY scripts/postinstall.mjs ./scripts/postinstall.mjs
+COPY scripts/native-binary-compat.mjs ./scripts/native-binary-compat.mjs
 RUN if [ -f package-lock.json ]; then npm ci --no-audit --no-fund; else npm install --no-audit --no-fund; fi
 
 COPY . ./
-RUN mkdir -p /app/data && npm run build
+RUN mkdir -p /app/data && npm run build -- --webpack
 
-FROM node:22-bookworm-slim AS runner-base
+FROM node:22.22.2-trixie-slim AS runner-base
 WORKDIR /app
 
 LABEL org.opencontainers.image.title="omniroute" \
@@ -19,30 +25,44 @@ LABEL org.opencontainers.image.title="omniroute" \
 ENV NODE_ENV=production
 ENV PORT=20128
 ENV HOSTNAME=0.0.0.0
+ENV NODE_OPTIONS="--max-old-space-size=256"
 
 # Data directory inside Docker — must match the volume mount in docker-compose.yml
 ENV DATA_DIR=/app/data
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends libsecret-1-0 ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
 RUN mkdir -p /app/data
 
 COPY --from=builder /app/public ./public
 COPY --from=builder /app/.next/static ./.next/static
 COPY --from=builder /app/.next/standalone ./
+# Explicitly copy @swc/helpers — not always traced by standalone output but needed at runtime
+COPY --from=builder /app/node_modules/@swc/helpers ./node_modules/@swc/helpers
+# Explicitly copy pino transport dependencies — pino spawns a worker that requires
+# pino-abstract-transport at runtime; Next.js standalone trace does not capture it (#449)
+COPY --from=builder /app/node_modules/pino-abstract-transport ./node_modules/pino-abstract-transport
+COPY --from=builder /app/node_modules/pino-pretty ./node_modules/pino-pretty
+COPY --from=builder /app/node_modules/split2 ./node_modules/split2
+COPY --from=builder /app/scripts/run-standalone.mjs ./run-standalone.mjs
+COPY --from=builder /app/scripts/runtime-env.mjs ./runtime-env.mjs
+COPY --from=builder /app/scripts/bootstrap-env.mjs ./bootstrap-env.mjs
+COPY --from=builder /app/scripts/healthcheck.mjs ./healthcheck.mjs
 
 EXPOSE 20128
 
 HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
-  CMD node -e "fetch('http://127.0.0.1:20128/api/settings').then(r=>{if(!r.ok)throw r.status}).catch(()=>process.exit(1))"
+  CMD ["node", "healthcheck.mjs"]
 
-CMD ["node", "server.js"]
+CMD ["node", "run-standalone.mjs"]
 
 FROM runner-base AS runner-cli
 
 # Install system dependencies required by openclaw (git+ssh references).
 RUN apt-get update \
-  && apt-get install -y --no-install-recommends git ca-certificates \
+  && apt-get install -y --no-install-recommends git ca-certificates docker.io docker-compose \
   && rm -rf /var/lib/apt/lists/* \
   && git config --system url."https://github.com/".insteadOf "ssh://git@github.com/"
 
 # Install CLI tools globally. Separate layer from apt for better cache reuse.
 RUN npm install -g --no-audit --no-fund @openai/codex @anthropic-ai/claude-code droid openclaw@latest
-

README.es.md

@@ -1,999 +0,0 @@
-<div align="center">
-  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute Dashboard" width="800"/>
-  
-  # 🚀 OmniRoute — El Gateway de IA Gratuito
-
-### Nunca dejes de programar. Enrutamiento inteligente hacia **modelos de IA GRATUITOS y económicos** con fallback automático.
-
-_Tu proxy de API universal — un endpoint, 36+ proveedores, cero tiempo de inactividad._
-
-**Chat Completions • Embeddings • Generación de Imágenes • Audio • Reranking • 100% TypeScript**
-
----
-
-### 🤖 Proveedor de IA Gratuito para tus agentes de programación favoritos
-
-_Conecta cualquier IDE o herramienta CLI con IA a través de OmniRoute — gateway de API gratuito para programación ilimitada._
-
-  <table>
-    <tr>
-      <td align="center" width="110">
-        <a href="https://github.com/cline/cline">
-          <img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
-          <b>OpenClaw</b>
-        </a><br/>
-        <sub>⭐ 205K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/HKUDS/nanobot">
-          <img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
-          <b>NanoBot</b>
-        </a><br/>
-        <sub>⭐ 20.9K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/sipeed/picoclaw">
-          <img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
-          <b>PicoClaw</b>
-        </a><br/>
-        <sub>⭐ 14.6K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/zeroclaw-labs/zeroclaw">
-          <img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
-          <b>ZeroClaw</b>
-        </a><br/>
-        <sub>⭐ 9.9K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/nearai/ironclaw">
-          <img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
-          <b>IronClaw</b>
-        </a><br/>
-        <sub>⭐ 2.1K</sub>
-      </td>
-    </tr>
-    <tr>
-      <td align="center" width="110">
-        <a href="https://github.com/anomalyco/opencode">
-          <img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
-          <b>OpenCode</b>
-        </a><br/>
-        <sub>⭐ 106K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/openai/codex">
-          <img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
-          <b>Codex CLI</b>
-        </a><br/>
-        <sub>⭐ 60.8K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/anthropics/claude-code">
-          <img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
-          <b>Claude Code</b>
-        </a><br/>
-        <sub>⭐ 67.3K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/google-gemini/gemini-cli">
-          <img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
-          <b>Gemini CLI</b>
-        </a><br/>
-        <sub>⭐ 94.7K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/Kilo-Org/kilocode">
-          <img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
-          <b>Kilo Code</b>
-        </a><br/>
-        <sub>⭐ 15.5K</sub>
-      </td>
-    </tr>
-  </table>
-
-<sub>📡 Todos los agentes se conectan vía <code>http://localhost:20128/v1</code> o <code>http://cloud.omniroute.online/v1</code> — una configuración, modelos y cuota ilimitados</sub>
-
----
-
-[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
-[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)
-[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)
-[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-
-[🌐 Website](https://omniroute.online) • [🚀 Inicio Rápido](#-inicio-rápido) • [💡 Características](#-características-principales) • [📖 Docs](#-documentación) • [💰 Precios](#-precios-resumidos)
-
-🌐 **Disponible en:** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
-
-</div>
-
----
-
-## 🤔 ¿Por qué OmniRoute?
-
-**Deja de desperdiciar dinero y chocar con límites:**
-
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> La cuota de suscripción expira sin usar cada mes
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Los límites de tasa te detienen en medio de la programación
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> APIs caras ($20-50/mes por proveedor)
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Cambiar manualmente entre proveedores
-
-**OmniRoute resuelve esto:**
-
-- ✅ **Maximiza suscripciones** - Rastrea cuotas, usa cada bit antes del reset
-- ✅ **Fallback automático** - Suscripción → API Key → Barato → Gratuito, cero tiempo de inactividad
-- ✅ **Multi-cuenta** - Round-robin entre cuentas por proveedor
-- ✅ **Universal** - Funciona con Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, cualquier herramienta CLI
-
----
-
-## 🔄 Cómo Funciona
-
-```
-┌─────────────┐
-│  Tu CLI     │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
-│   Tool      │
-└──────┬──────┘
-       │ http://localhost:20128/v1
-       ↓
-┌─────────────────────────────────────────┐
-│        OmniRoute (Enrutador Inteligente)  │
-│  • Traducción de formato (OpenAI ↔ Claude) │
-│  • Rastreo de cuota + Embeddings + Imágenes │
-│  • Renovación automática de tokens        │
-└──────┬──────────────────────────────────┘
-       │
-       ├─→ [Tier 1: SUSCRIPCIÓN] Claude Code, Codex, Gemini CLI
-       │   ↓ cuota agotada
-       ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
-       │   ↓ límite de presupuesto
-       ├─→ [Tier 3: BARATO] GLM ($0.6/1M), MiniMax ($0.2/1M)
-       │   ↓ límite de presupuesto
-       └─→ [Tier 4: GRATUITO] iFlow, Qwen, Kiro (ilimitado)
-
-Resultado: Nunca dejes de programar, costo mínimo
-```
-
----
-
-## ⚡ Inicio Rápido
-
-**1. Instala globalmente:**
-
-```bash
-npm install -g omniroute
-omniroute
-```
-
-🎉 El Dashboard se abre en `http://localhost:20128`
-
-| Comando                 | Descripción                                    |
-| ----------------------- | ---------------------------------------------- |
-| `omniroute`             | Iniciar servidor (puerto predeterminado 20128) |
-| `omniroute --port 3000` | Usar puerto personalizado                      |
-| `omniroute --no-open`   | No abrir navegador automáticamente             |
-| `omniroute --help`      | Mostrar ayuda                                  |
-
-**2. Conecta un proveedor GRATUITO:**
-
-Dashboard → Proveedores → Conectar **Claude Code** o **Antigravity** → Login OAuth → ¡Listo!
-
-**3. Usa en tu herramienta CLI:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Configuración:
-  Endpoint: http://localhost:20128/v1
-  API Key: [copiar del dashboard]
-  Model: if/kimi-k2-thinking
-```
-
-**¡Eso es todo!** Comienza a programar con modelos de IA GRATUITOS.
-
-**Alternativa — ejecutar desde código fuente:**
-
-```bash
-cp .env.example .env
-npm install
-PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
-```
-
----
-
-## 🐳 Docker
-
-OmniRoute está disponible como imagen Docker pública en [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-
-**Ejecución rápida:**
-
-```bash
-docker run -d \
-  --name omniroute \
-  --restart unless-stopped \
-  -p 20128:20128 \
-  -v omniroute-data:/app/data \
-  diegosouzapw/omniroute:latest
-```
-
-**Con archivo de entorno:**
-
-```bash
-# Copia y edita el .env primero
-cp .env.example .env
-
-docker run -d \
-  --name omniroute \
-  --restart unless-stopped \
-  --env-file .env \
-  -p 20128:20128 \
-  -v omniroute-data:/app/data \
-  diegosouzapw/omniroute:latest
-```
-
-**Usando Docker Compose:**
-
-```bash
-# Perfil base (sin herramientas CLI)
-docker compose --profile base up -d
-
-# Perfil CLI (Claude Code, Codex, OpenClaw integrados)
-docker compose --profile cli up -d
-```
-
-| Imagen                   | Tag      | Tamaño | Descripción            |
-| ------------------------ | -------- | ------ | ---------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Última versión estable |
-| `diegosouzapw/omniroute` | `1.0.6`  | ~250MB | Versión actual         |
-
----
-
-## 💰 Precios Resumidos
-
-| Tier               | Proveedor         | Costo                        | Reset de Cuota    | Mejor Para              |
-| ------------------ | ----------------- | ---------------------------- | ----------------- | ----------------------- |
-| **💳 SUSCRIPCIÓN** | Claude Code (Pro) | $20/mes                      | 5h + semanal      | Ya suscrito             |
-|                    | Codex (Plus/Pro)  | $20-200/mes                  | 5h + semanal      | Usuarios OpenAI         |
-|                    | Gemini CLI        | **GRATUITO**                 | 180K/mes + 1K/día | ¡Todos!                 |
-|                    | GitHub Copilot    | $10-19/mes                   | Mensual           | Usuarios GitHub         |
-| **🔑 API KEY**     | NVIDIA NIM        | **GRATUITO** (1000 créditos) | Único             | Pruebas gratuitas       |
-|                    | DeepSeek          | Por uso                      | Ninguno           | Mejor precio/calidad    |
-|                    | Groq              | Tier gratuito + pago         | Limitado          | Inferencia ultra-rápida |
-|                    | xAI (Grok)        | Por uso                      | Ninguno           | Modelos Grok            |
-|                    | Mistral           | Tier gratuito + pago         | Limitado          | IA Europea              |
-|                    | OpenRouter        | Por uso                      | Ninguno           | 100+ modelos            |
-| **💰 BARATO**      | GLM-4.7           | $0.6/1M                      | Diario 10h        | Respaldo económico      |
-|                    | MiniMax M2.1      | $0.2/1M                      | Rotativo 5h       | Opción más barata       |
-|                    | Kimi K2           | $9/mes fijo                  | 10M tokens/mes    | Costo predecible        |
-| **🆓 GRATUITO**    | iFlow             | $0                           | Ilimitado         | 8 modelos gratuitos     |
-|                    | Qwen              | $0                           | Ilimitado         | 3 modelos gratuitos     |
-|                    | Kiro              | $0                           | Ilimitado         | Claude gratuito         |
-
-**💡 Consejo Pro:** ¡Comienza con Gemini CLI (180K gratis/mes) + iFlow (ilimitado gratis) = $0 de costo!
-
----
-
-## 🎯 Casos de Uso
-
-### Caso 1: "Tengo suscripción Claude Pro"
-
-**Problema:** La cuota expira sin usar, límites de tasa durante programación intensa
-
-```
-Combo: "maximize-claude"
-  1. cc/claude-opus-4-6        (usar suscripción al máximo)
-  2. glm/glm-4.7               (respaldo barato cuando la cuota se agota)
-  3. if/kimi-k2-thinking       (fallback de emergencia gratuito)
-
-Costo mensual: $20 (suscripción) + ~$5 (respaldo) = $25 total
-vs. $20 + chocar con límites = frustración
-```
-
-### Caso 2: "Quiero costo cero"
-
-**Problema:** No puede pagar suscripciones, necesita IA confiable para programar
-
-```
-Combo: "free-forever"
-  1. gc/gemini-3-flash         (180K gratis/mes)
-  2. if/kimi-k2-thinking       (ilimitado gratis)
-  3. qw/qwen3-coder-plus       (ilimitado gratis)
-
-Costo mensual: $0
-Calidad: Modelos listos para producción
-```
-
-### Caso 3: "Necesito programar 24/7, sin interrupciones"
-
-**Problema:** Plazos ajustados, no puede permitirse tiempo de inactividad
-
-```
-Combo: "always-on"
-  1. cc/claude-opus-4-6        (mejor calidad)
-  2. cx/gpt-5.2-codex          (segunda suscripción)
-  3. glm/glm-4.7               (barato, reset diario)
-  4. minimax/MiniMax-M2.1      (más barato, reset 5h)
-  5. if/kimi-k2-thinking       (gratuito ilimitado)
-
-Resultado: 5 capas de fallback = cero tiempo de inactividad
-```
-
-### Caso 4: "Quiero IA GRATUITA en OpenClaw"
-
-**Problema:** Necesita asistente de IA en apps de mensajería, completamente gratuito
-
-```
-Combo: "openclaw-free"
-  1. if/glm-4.7                (ilimitado gratis)
-  2. if/minimax-m2.1           (ilimitado gratis)
-  3. if/kimi-k2-thinking       (ilimitado gratis)
-
-Costo mensual: $0
-Acceso vía: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-```
-
----
-
-## 💡 Características Principales
-
-### 🧠 Enrutamiento e Inteligencia
-
-| Característica                         | Qué Hace                                                                        |
-| -------------------------------------- | ------------------------------------------------------------------------------- |
-| 🎯 **Fallback Inteligente 4 Tiers**    | Auto-enrutamiento: Suscripción → API Key → Barato → Gratuito                    |
-| 📊 **Rastreo de Cuota en Tiempo Real** | Conteo de tokens en vivo + countdown de reset por proveedor                     |
-| 🔄 **Traducción de Formato**           | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro transparente                           |
-| 👥 **Soporte Multi-Cuenta**            | Múltiples cuentas por proveedor con selección inteligente                       |
-| 🔄 **Renovación Automática de Token**  | Tokens OAuth se renuevan automáticamente con reintentos                         |
-| 🎨 **Combos Personalizados**           | 6 estrategias: fill-first, round-robin, p2c, random, least-used, cost-optimized |
-| 🧩 **Modelos Personalizados**          | Agrega cualquier ID de modelo a cualquier proveedor                             |
-| 🌐 **Enrutador Wildcard**              | Enruta patrones `provider/*` a cualquier proveedor dinámicamente                |
-| 🧠 **Presupuesto de Razonamiento**     | Modos passthrough, auto, custom y adaptativo para modelos de razonamiento       |
-| 💬 **Inyección de System Prompt**      | System prompt global aplicado en todas las solicitudes                          |
-| 📄 **API Responses**                   | Soporte completo de la API Responses de OpenAI (`/v1/responses`) para Codex     |
-
-### 🎵 APIs Multi-Modal
-
-| Característica                | Qué Hace                                               |
-| ----------------------------- | ------------------------------------------------------ |
-| 🖼️ **Generación de Imágenes** | `/v1/images/generations` — 4 proveedores, 9+ modelos   |
-| 📐 **Embeddings**             | `/v1/embeddings` — 6 proveedores, 9+ modelos           |
-| 🎤 **Transcripción de Audio** | `/v1/audio/transcriptions` — Compatible con Whisper    |
-| 🔊 **Texto a Voz**            | `/v1/audio/speech` — Síntesis de audio multi-proveedor |
-| 🛡️ **Moderaciones**           | `/v1/moderations` — Verificaciones de seguridad        |
-| 🔀 **Reranking**              | `/v1/rerank` — Reranking de relevancia de documentos   |
-
-### 🛡️ Resiliencia y Seguridad
-
-| Característica                     | Qué Hace                                                         |
-| ---------------------------------- | ---------------------------------------------------------------- |
-| 🔌 **Circuit Breaker**             | Auto-apertura/cierre por proveedor con umbrales configurables    |
-| 🛡️ **Anti-Thundering Herd**        | Mutex + semáforo rate-limit para proveedores con API key         |
-| 🧠 **Caché Semántico**             | Caché de dos niveles (firma + semántico) reduce costo y latencia |
-| ⚡ **Idempotencia de Solicitud**   | Ventana de dedup de 5s para solicitudes duplicadas               |
-| 🔒 **Spoofing de Fingerprint TLS** | Bypass de detección de bot vía TLS con wreq-js                   |
-| 🌐 **Filtrado de IP**              | Allowlist/blocklist para control de acceso a la API              |
-| 📊 **Rate Limits Editables**       | RPM, gap mínimo y concurrencia máxima configurables              |
-
-### 📊 Observabilidad y Analytics
-
-| Característica                 | Qué Hace                                                              |
-| ------------------------------ | --------------------------------------------------------------------- |
-| 📝 **Logs de Solicitud**       | Modo debug con logs completos de request/response                     |
-| 💾 **Logs SQLite**             | Logs de proxy persistentes sobreviven a reinicios                     |
-| 📊 **Dashboard de Analytics**  | Recharts: cards de estadísticas, gráfico de uso, tabla de proveedores |
-| 📈 **Rastreo de Progreso**     | Eventos de progreso SSE opt-in para streaming                         |
-| 🧪 **Evaluaciones de LLM**     | Pruebas con conjunto golden y 4 estrategias de match                  |
-| 🔍 **Telemetría de Solicitud** | Agregación de latencia p50/p95/p99 + rastreo X-Request-Id             |
-| 📋 **Logs + Cuotas**           | Páginas dedicadas para navegación de logs y rastreo de cuotas         |
-| 🏥 **Dashboard de Salud**      | Uptime, estados de circuit breaker, lockouts, stats de caché          |
-| 💰 **Rastreo de Costos**       | Gestión de presupuesto + configuración de precios por modelo          |
-
-### ☁️ Deploy y Sincronización
-
-| Característica                    | Qué Hace                                                                        |
-| --------------------------------- | ------------------------------------------------------------------------------- |
-| 💾 **Cloud Sync**                 | Sincroniza configuraciones entre dispositivos vía Cloudflare Workers            |
-| 🌐 **Deploy en Cualquier Lugar**  | Localhost, VPS, Docker, Cloudflare Workers                                      |
-| 🔑 **Gestión de API Keys**        | Genera, rota y define alcance de API keys por proveedor                         |
-| 🧙 **Asistente de Configuración** | Setup guiado en 4 pasos para nuevos usuarios                                    |
-| 🔧 **Dashboard CLI Tools**        | Configuración en un clic para Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Backups de DB**              | Backup y restauración automáticos de todas las configuraciones                  |
-
-<details>
-<summary><b>📖 Detalles de Características</b></summary>
-
-### 🎯 Fallback Inteligente 4 Tiers
-
-Crea combos con fallback automático:
-
-```
-Combo: "my-coding-stack"
-  1. cc/claude-opus-4-6        (tu suscripción)
-  2. nvidia/llama-3.3-70b      (API NVIDIA gratuita)
-  3. glm/glm-4.7               (respaldo barato, $0.6/1M)
-  4. if/kimi-k2-thinking       (fallback gratuito)
-
-→ Cambia automáticamente cuando la cuota se agota o ocurren errores
-```
-
-### 📊 Rastreo de Cuota en Tiempo Real
-
-- Consumo de tokens por proveedor
-- Countdown de reset (5 horas, diario, semanal)
-- Estimación de costo para tiers pagos
-- Reportes de gastos mensuales
-
-### 🔄 Traducción de Formato
-
-Traducción transparente entre formatos:
-
-- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
-- Tu herramienta CLI envía formato OpenAI → OmniRoute traduce → El proveedor recibe formato nativo
-- Funciona con cualquier herramienta que soporte endpoints OpenAI personalizados
-
-### 👥 Soporte Multi-Cuenta
-
-- Agrega múltiples cuentas por proveedor
-- Round-robin automático o enrutamiento por prioridad
-- Fallback a la siguiente cuenta cuando una alcanza la cuota
-
-### 🔄 Renovación Automática de Token
-
-- Los tokens OAuth se renuevan automáticamente antes de expirar
-- Sin necesidad de re-autenticación manual
-- Experiencia transparente en todos los proveedores
-
-### 🎨 Combos Personalizados
-
-- Crea combinaciones ilimitadas de modelos
-- 6 estrategias: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized
-- Comparte combos entre dispositivos con Cloud Sync
-
-### 🏥 Dashboard de Salud
-
-- Estado del sistema (uptime, versión, uso de memoria)
-- Estados de circuit breaker por proveedor (Closed/Open/Half-Open)
-- Estado de rate limit y lockouts activos
-- Estadísticas de caché de firma
-- Telemetría de latencia (p50/p95/p99) + caché de prompt
-- Reset de salud con un clic
-
-### 🔧 Playground del Traductor
-
-- Debug, prueba y visualiza traducciones de formato de API
-- Envía solicitudes y ve cómo OmniRoute traduce entre formatos de proveedores
-- Invaluable para troubleshooting de problemas de integración
-
-### 💾 Cloud Sync
-
-- Sincroniza proveedores, combos y configuraciones entre dispositivos
-- Sincronización automática en segundo plano
-- Almacenamiento cifrado seguro
-
-</details>
-
----
-
-## 📖 Guía de Configuración
-
-<details>
-<summary><b>💳 Proveedores por Suscripción</b></summary>
-
-### Claude Code (Pro/Max)
-
-```bash
-Dashboard → Proveedores → Conectar Claude Code
-→ Login OAuth → Renovación automática de token
-→ Rastreo de cuota 5h + semanal
-
-Modelos:
-  cc/claude-opus-4-6
-  cc/claude-sonnet-4-5-20250929
-  cc/claude-haiku-4-5-20251001
-```
-
-**Consejo Pro:** Usa Opus para tareas complejas, Sonnet para velocidad. ¡OmniRoute rastrea cuota por modelo!
-
-### OpenAI Codex (Plus/Pro)
-
-```bash
-Dashboard → Proveedores → Conectar Codex
-→ Login OAuth (puerto 1455)
-→ Reset 5h + semanal
-
-Modelos:
-  cx/gpt-5.2-codex
-  cx/gpt-5.1-codex-max
-```
-
-### Gemini CLI (¡GRATUITO 180K/mes!)
-
-```bash
-Dashboard → Proveedores → Conectar Gemini CLI
-→ Google OAuth
-→ 180K completions/mes + 1K/día
-
-Modelos:
-  gc/gemini-3-flash-preview
-  gc/gemini-2.5-pro
-```
-
-**Mejor Valor:** ¡Tier gratuito enorme! Úsalo antes de los tiers pagos.
-
-### GitHub Copilot
-
-```bash
-Dashboard → Proveedores → Conectar GitHub
-→ OAuth vía GitHub
-→ Reset mensual (1ro del mes)
-
-Modelos:
-  gh/gpt-5
-  gh/claude-4.5-sonnet
-  gh/gemini-3-pro
-```
-
-</details>
-
-<details>
-<summary><b>🔑 Proveedores por API Key</b></summary>
-
-### NVIDIA NIM (¡GRATUITO 1000 créditos!)
-
-1. Regístrate: [build.nvidia.com](https://build.nvidia.com)
-2. Obtén API key gratuita (1000 créditos de inferencia incluidos)
-3. Dashboard → Agregar Proveedor → NVIDIA NIM:
-   - API Key: `nvapi-your-key`
-
-**Modelos:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, y 50+ más
-
-**Consejo Pro:** ¡API compatible con OpenAI — funciona perfectamente con la traducción de formato de OmniRoute!
-
-### DeepSeek
-
-1. Regístrate: [platform.deepseek.com](https://platform.deepseek.com)
-2. Obtén API key
-3. Dashboard → Agregar Proveedor → DeepSeek
-
-**Modelos:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`
-
-### Groq (¡Tier Gratuito Disponible!)
-
-1. Regístrate: [console.groq.com](https://console.groq.com)
-2. Obtén API key (tier gratuito incluido)
-3. Dashboard → Agregar Proveedor → Groq
-
-**Modelos:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`
-
-**Consejo Pro:** ¡Inferencia ultra-rápida — mejor para programación en tiempo real!
-
-### OpenRouter (100+ Modelos)
-
-1. Regístrate: [openrouter.ai](https://openrouter.ai)
-2. Obtén API key
-3. Dashboard → Agregar Proveedor → OpenRouter
-
-**Modelos:** Accede a 100+ modelos de todos los principales proveedores a través de una única API key.
-
-</details>
-
-<details>
-<summary><b>💰 Proveedores Baratos (Respaldo)</b></summary>
-
-### GLM-4.7 (Reset diario, $0.6/1M)
-
-1. Regístrate: [Zhipu AI](https://open.bigmodel.cn/)
-2. Obtén API key del Plan Coding
-3. Dashboard → Agregar API Key:
-   - Proveedor: `glm`
-   - API Key: `your-key`
-
-**Usa:** `glm/glm-4.7`
-
-**Consejo Pro:** ¡El Plan Coding ofrece 3× cuota a 1/7 del costo! Reset diario 10:00 AM.
-
-### MiniMax M2.1 (Reset 5h, $0.20/1M)
-
-1. Regístrate: [MiniMax](https://www.minimax.io/)
-2. Obtén API key
-3. Dashboard → Agregar API Key
-
-**Usa:** `minimax/MiniMax-M2.1`
-
-**Consejo Pro:** ¡Opción más barata para contexto largo (1M tokens)!
-
-### Kimi K2 ($9/mes fijo)
-
-1. Suscríbete: [Moonshot AI](https://platform.moonshot.ai/)
-2. Obtén API key
-3. Dashboard → Agregar API Key
-
-**Usa:** `kimi/kimi-latest`
-
-**Consejo Pro:** ¡$9/mes fijo por 10M tokens = $0.90/1M de costo efectivo!
-
-</details>
-
-<details>
-<summary><b>🆓 Proveedores GRATUITOS (Respaldo de Emergencia)</b></summary>
-
-### iFlow (8 modelos GRATUITOS)
-
-```bash
-Dashboard → Conectar iFlow
-→ Login OAuth iFlow
-→ Uso ilimitado
-
-Modelos:
-  if/kimi-k2-thinking
-  if/qwen3-coder-plus
-  if/glm-4.7
-  if/minimax-m2
-  if/deepseek-r1
-```
-
-### Qwen (3 modelos GRATUITOS)
-
-```bash
-Dashboard → Conectar Qwen
-→ Autorización por código de dispositivo
-→ Uso ilimitado
-
-Modelos:
-  qw/qwen3-coder-plus
-  qw/qwen3-coder-flash
-```
-
-### Kiro (Claude GRATUITO)
-
-```bash
-Dashboard → Conectar Kiro
-→ AWS Builder ID o Google/GitHub
-→ Uso ilimitado
-
-Modelos:
-  kr/claude-sonnet-4.5
-  kr/claude-haiku-4.5
-```
-
-</details>
-
-<details>
-<summary><b>🎨 Crear Combos</b></summary>
-
-### Ejemplo 1: Maximizar Suscripción → Respaldo Barato
-
-```
-Dashboard → Combos → Crear Nuevo
-
-Nombre: premium-coding
-Modelos:
-  1. cc/claude-opus-4-6 (Suscripción primaria)
-  2. glm/glm-4.7 (Respaldo barato, $0.6/1M)
-  3. minimax/MiniMax-M2.1 (Fallback más barato, $0.20/1M)
-
-Usa en CLI: premium-coding
-```
-
-### Ejemplo 2: Solo Gratuito (Costo Cero)
-
-```
-Nombre: free-combo
-Modelos:
-  1. gc/gemini-3-flash-preview (180K gratis/mes)
-  2. if/kimi-k2-thinking (ilimitado)
-  3. qw/qwen3-coder-plus (ilimitado)
-
-Costo: ¡$0 para siempre!
-```
-
-</details>
-
-<details>
-<summary><b>🔧 Integración CLI</b></summary>
-
-### Cursor IDE
-
-```
-Configuración → Modelos → Avanzado:
-  OpenAI API Base URL: http://localhost:20128/v1
-  OpenAI API Key: [del dashboard OmniRoute]
-  Model: cc/claude-opus-4-6
-```
-
-### Claude Code
-
-Usa la página **CLI Tools** en el dashboard para configuración en un clic, o edita `~/.claude/settings.json` manualmente.
-
-### Codex CLI
-
-```bash
-export OPENAI_BASE_URL="http://localhost:20128"
-export OPENAI_API_KEY="your-omniroute-api-key"
-
-codex "your prompt"
-```
-
-### OpenClaw
-
-**Opción 1 — Dashboard (recomendado):**
-
-```
-Dashboard → CLI Tools → OpenClaw → Seleccionar Modelo → Aplicar
-```
-
-**Opción 2 — Manual:** Edita `~/.openclaw/openclaw.json`:
-
-```json
-{
-  "models": {
-    "providers": {
-      "omniroute": {
-        "baseUrl": "http://127.0.0.1:20128/v1",
-        "apiKey": "sk_omniroute",
-        "api": "openai-completions"
-      }
-    }
-  }
-}
-```
-
-> **Nota:** OpenClaw solo funciona con OmniRoute local. Usa `127.0.0.1` en lugar de `localhost` para evitar problemas de resolución IPv6.
-
-### Cline / Continue / RooCode
-
-```
-Configuración → Configuración de API:
-  Proveedor: OpenAI Compatible
-  Base URL: http://localhost:20128/v1
-  API Key: [del dashboard OmniRoute]
-  Model: if/kimi-k2-thinking
-```
-
-</details>
-
----
-
-## 📊 Modelos Disponibles
-
-<details>
-<summary><b>Ver todos los modelos disponibles</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/`)** - GRATUITO:
-
-- `gc/gemini-3-flash-preview`
-- `gc/gemini-2.5-pro`
-
-**GitHub Copilot (`gh/`)**:
-
-- `gh/gpt-5`
-- `gh/claude-4.5-sonnet`
-
-**NVIDIA NIM (`nvidia/`)** - Créditos GRATUITOS:
-
-- `nvidia/llama-3.3-70b-instruct`
-- `nvidia/mistral-7b-instruct`
-- 50+ más modelos en [build.nvidia.com](https://build.nvidia.com)
-
-**GLM (`glm/`)** - $0.6/1M:
-
-- `glm/glm-4.7`
-
-**MiniMax (`minimax/`)** - $0.2/1M:
-
-- `minimax/MiniMax-M2.1`
-
-**iFlow (`if/`)** - GRATUITO:
-
-- `if/kimi-k2-thinking`
-- `if/qwen3-coder-plus`
-- `if/deepseek-r1`
-- `if/glm-4.7`
-- `if/minimax-m2`
-
-**Qwen (`qw/`)** - GRATUITO:
-
-- `qw/qwen3-coder-plus`
-- `qw/qwen3-coder-flash`
-
-**Kiro (`kr/`)** - GRATUITO:
-
-- `kr/claude-sonnet-4.5`
-- `kr/claude-haiku-4.5`
-
-**OpenRouter (`or/`)** - 100+ modelos:
-
-- `or/anthropic/claude-4-sonnet`
-- `or/google/gemini-2.5-pro`
-- Cualquier modelo de [openrouter.ai/models](https://openrouter.ai/models)
-
-</details>
-
----
-
-## 🧪 Evaluaciones (Evals)
-
-OmniRoute incluye un framework de evaluación integrado para probar la calidad de respuestas de LLM contra un conjunto golden. Accede vía **Analytics → Evals** en el dashboard.
-
-### Conjunto Golden Integrado
-
-El "OmniRoute Golden Set" precargado contiene 10 casos de prueba que cubren:
-
-- Saludos, matemáticas, geografía, generación de código
-- Conformidad de formato JSON, traducción, markdown
-- Rechazo de seguridad (contenido dañino), conteo, lógica booleana
-
-### Estrategias de Evaluación
-
-| Estrategia | Descripción                                          | Ejemplo                          |
-| ---------- | ---------------------------------------------------- | -------------------------------- |
-| `exact`    | La salida debe coincidir exactamente                 | `"4"`                            |
-| `contains` | La salida debe contener subcadena (case-insensitive) | `"Paris"`                        |
-| `regex`    | La salida debe coincidir con el patrón regex         | `"1.*2.*3"`                      |
-| `custom`   | Función JS personalizada retorna true/false          | `(output) => output.length > 10` |
-
----
-
-## 🐛 Solución de Problemas
-
-<details>
-<summary><b>Haz clic para expandir la guía de solución de problemas</b></summary>
-
-**"Language model did not provide messages"**
-
-- Cuota del proveedor agotada → Verifica el rastreador de cuota en el dashboard
-- Solución: Usa combo con fallback o cambia a tier más barato
-
-**Rate limiting**
-
-- Cuota de suscripción agotada → Fallback a GLM/MiniMax
-- Agrega combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-
-**Token OAuth expirado**
-
-- Renovado automáticamente por OmniRoute
-- Si persiste: Dashboard → Proveedor → Reconectar
-
-**Costos altos**
-
-- Verifica estadísticas de uso en Dashboard → Costos
-- Cambia modelo primario a GLM/MiniMax
-- Usa tier gratuito (Gemini CLI, iFlow) para tareas no críticas
-
-**Dashboard se abre en el puerto equivocado**
-
-- Establece `PORT=20128` y `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
-
-**Errores de cloud sync**
-
-- Verifica que `BASE_URL` apunte a tu instancia en ejecución
-- Verifica que `CLOUD_URL` apunte a tu endpoint cloud esperado
-- Mantén los valores `NEXT_PUBLIC_*` alineados con los valores del servidor
-
-**Primer login no funciona**
-
-- Verifica `INITIAL_PASSWORD` en `.env`
-- Si no está definido, la contraseña predeterminada es `123456`
-
-**Sin logs de solicitud**
-
-- Establece `ENABLE_REQUEST_LOGS=true` en `.env`
-
-**Prueba de conexión muestra "Invalid" para proveedores compatibles con OpenAI**
-
-- Muchos proveedores no exponen el endpoint `/models`
-- OmniRoute v1.0.6+ incluye validación vía chat completions como fallback
-- Asegúrate de que la URL base incluya el sufijo `/v1`
-
-</details>
-
----
-
-## 🛠️ Stack Tecnológico
-
-- **Runtime**: Node.js 20+
-- **Lenguaje**: TypeScript 5.9 — **100% TypeScript** en `src/` y `open-sse/` (v1.0.6)
-- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Base de Datos**: LowDB (JSON) + SQLite (estado del dominio + logs de proxy)
-- **Streaming**: Server-Sent Events (SSE)
-- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys
-- **Testing**: Node.js test runner (368+ tests unitarios)
-- **CI/CD**: GitHub Actions (publicación automática npm + Docker Hub en release)
-- **Website**: [omniroute.online](https://omniroute.online)
-- **Paquete**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Resiliencia**: Circuit breaker, backoff exponencial, anti-thundering herd, spoofing TLS
-
----
-
-## 📖 Documentación
-
-| Documento                                        | Descripción                                        |
-| ------------------------------------------------ | -------------------------------------------------- |
-| [Guía del Usuario](docs/USER_GUIDE.md)           | Proveedores, combos, integración CLI, deploy       |
-| [Referencia de API](docs/API_REFERENCE.md)       | Todos los endpoints con ejemplos                   |
-| [Solución de Problemas](docs/TROUBLESHOOTING.md) | Problemas comunes y soluciones                     |
-| [Arquitectura](docs/ARCHITECTURE.md)             | Arquitectura del sistema e internos                |
-| [Contribuir](CONTRIBUTING.md)                    | Setup de desarrollo y directrices                  |
-| [Spec OpenAPI](docs/openapi.yaml)                | Especificación OpenAPI 3.0                         |
-| [Política de Seguridad](SECURITY.md)             | Reportar vulnerabilidades y prácticas de seguridad |
-
----
-
-## 📧 Soporte
-
-> 💬 **¡Únete a la comunidad!** [Grupo WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obtén ayuda, comparte consejos y mantente al día.
-
-- **Website**: [omniroute.online](https://omniroute.online)
-- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **WhatsApp**: [Grupo de la Comunidad](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Proyecto Original**: [9router por decolua](https://github.com/decolua/9router)
-
----
-
-## 👥 Contribuidores
-
-[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-
-### Cómo Contribuir
-
-1. Haz fork del repositorio
-2. Crea tu rama de funcionalidad (`git checkout -b feature/amazing-feature`)
-3. Haz commit de tus cambios (`git commit -m 'Add amazing feature'`)
-4. Haz push a la rama (`git push origin feature/amazing-feature`)
-5. Abre un Pull Request
-
-Consulta [CONTRIBUTING.md](CONTRIBUTING.md) para directrices detalladas.
-
-### Lanzar una Nueva Versión
-
-```bash
-# Crea un release — la publicación en npm ocurre automáticamente
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
-```
-
----
-
-## 📊 Historial de Stars
-
-<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
- </picture>
-</a>
-
----
-
-## 🙏 Agradecimientos
-
-Agradecimiento especial a **[9router](https://github.com/decolua/9router)** por **[decolua](https://github.com/decolua)** — el proyecto original que inspiró este fork. OmniRoute se construye sobre esa increíble base con características adicionales, APIs multi-modal y una reescritura completa en TypeScript.
-
-Agradecimiento especial a **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — la implementación original en Go que inspiró esta adaptación a JavaScript.
-
----
-
-## 📄 Licencia
-
-Licencia MIT - consulta [LICENSE](LICENSE) para detalles.
-
----
-
-<div align="center">
-  <sub>Hecho con ❤️ para desarrolladores que programan 24/7</sub>
-  <br/>
-  <sub><a href="https://omniroute.online">omniroute.online</a></sub>
-</div>

README.fr.md

@@ -1,999 +0,0 @@
-<div align="center">
-  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute Dashboard" width="800"/>
-  
-  # 🚀 OmniRoute — La Passerelle IA Gratuite
-
-### N'arrêtez jamais de coder. Routage intelligent vers des **modèles IA GRATUITS et économiques** avec fallback automatique.
-
-_Votre proxy API universel — un endpoint, 36+ fournisseurs, zéro temps d'arrêt._
-
-**Chat Completions • Embeddings • Génération d'images • Audio • Reranking • 100% TypeScript**
-
----
-
-### 🤖 Fournisseur IA gratuit pour vos agents de programmation préférés
-
-_Connectez n'importe quel IDE ou outil CLI alimenté par l'IA via OmniRoute — passerelle API gratuite pour un codage illimité._
-
-  <table>
-    <tr>
-      <td align="center" width="110">
-        <a href="https://github.com/cline/cline">
-          <img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
-          <b>OpenClaw</b>
-        </a><br/>
-        <sub>⭐ 205K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/HKUDS/nanobot">
-          <img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
-          <b>NanoBot</b>
-        </a><br/>
-        <sub>⭐ 20.9K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/sipeed/picoclaw">
-          <img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
-          <b>PicoClaw</b>
-        </a><br/>
-        <sub>⭐ 14.6K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/zeroclaw-labs/zeroclaw">
-          <img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
-          <b>ZeroClaw</b>
-        </a><br/>
-        <sub>⭐ 9.9K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/nearai/ironclaw">
-          <img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
-          <b>IronClaw</b>
-        </a><br/>
-        <sub>⭐ 2.1K</sub>
-      </td>
-    </tr>
-    <tr>
-      <td align="center" width="110">
-        <a href="https://github.com/anomalyco/opencode">
-          <img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
-          <b>OpenCode</b>
-        </a><br/>
-        <sub>⭐ 106K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/openai/codex">
-          <img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
-          <b>Codex CLI</b>
-        </a><br/>
-        <sub>⭐ 60.8K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/anthropics/claude-code">
-          <img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
-          <b>Claude Code</b>
-        </a><br/>
-        <sub>⭐ 67.3K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/google-gemini/gemini-cli">
-          <img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
-          <b>Gemini CLI</b>
-        </a><br/>
-        <sub>⭐ 94.7K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/Kilo-Org/kilocode">
-          <img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
-          <b>Kilo Code</b>
-        </a><br/>
-        <sub>⭐ 15.5K</sub>
-      </td>
-    </tr>
-  </table>
-
-<sub>📡 Tous les agents se connectent via <code>http://localhost:20128/v1</code> ou <code>http://cloud.omniroute.online/v1</code> — une configuration, modèles et quota illimités</sub>
-
----
-
-[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
-[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)
-[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)
-[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-
-[🌐 Site web](https://omniroute.online) • [🚀 Démarrage rapide](#-démarrage-rapide) • [💡 Fonctionnalités](#-fonctionnalités-principales) • [📖 Docs](#-documentation) • [💰 Tarifs](#-aperçu-des-tarifs)
-
-🌐 **Disponible en :** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
-
-</div>
-
----
-
-## 🤔 Pourquoi OmniRoute ?
-
-**Arrêtez de gaspiller de l'argent et de vous heurter aux limites :**
-
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Le quota d'abonnement expire inutilisé chaque mois
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Les limites de débit vous arrêtent en plein codage
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> APIs coûteuses (20-50 $/mois par fournisseur)
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Changement manuel entre fournisseurs
-
-**OmniRoute résout ces problèmes :**
-
-- ✅ **Maximisez les abonnements** — Suivez les quotas, utilisez chaque bit avant la réinitialisation
-- ✅ **Fallback automatique** — Abonnement → Clé API → Économique → Gratuit, zéro temps d'arrêt
-- ✅ **Multi-comptes** — Round-robin entre les comptes par fournisseur
-- ✅ **Universel** — Fonctionne avec Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, tout outil CLI
-
----
-
-## 🔄 Comment ça fonctionne
-
-```
-┌─────────────┐
-│  Votre CLI  │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
-│   Tool      │
-└──────┬──────┘
-       │ http://localhost:20128/v1
-       ↓
-┌─────────────────────────────────────────┐
-│        OmniRoute (Routeur intelligent)   │
-│  • Traduction de format (OpenAI ↔ Claude) │
-│  • Suivi des quotas + Embeddings + Images │
-│  • Renouvellement automatique des tokens   │
-└──────┬──────────────────────────────────┘
-       │
-       ├─→ [Tier 1: ABONNEMENT] Claude Code, Codex, Gemini CLI
-       │   ↓ quota épuisé
-       ├─→ [Tier 2: CLÉ API] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
-       │   ↓ limite de budget
-       ├─→ [Tier 3: ÉCONOMIQUE] GLM ($0.6/1M), MiniMax ($0.2/1M)
-       │   ↓ limite de budget
-       └─→ [Tier 4: GRATUIT] iFlow, Qwen, Kiro (illimité)
-
-Résultat : Ne jamais arrêter de coder, coût minimal
-```
-
----
-
-## ⚡ Démarrage rapide
-
-**1. Installer globalement :**
-
-```bash
-npm install -g omniroute
-omniroute
-```
-
-🎉 Le tableau de bord s'ouvre sur `http://localhost:20128`
-
-| Commande                | Description                                 |
-| ----------------------- | ------------------------------------------- |
-| `omniroute`             | Démarrer le serveur (port par défaut 20128) |
-| `omniroute --port 3000` | Utiliser un port personnalisé               |
-| `omniroute --no-open`   | Ne pas ouvrir le navigateur automatiquement |
-| `omniroute --help`      | Afficher l'aide                             |
-
-**2. Connecter un fournisseur GRATUIT :**
-
-Tableau de bord → Fournisseurs → Connecter **Claude Code** ou **Antigravity** → Connexion OAuth → Terminé !
-
-**3. Utiliser dans votre outil CLI :**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Paramètres :
-  Endpoint : http://localhost:20128/v1
-  API Key : [copier depuis le tableau de bord]
-  Model : if/kimi-k2-thinking
-```
-
-**C'est tout !** Commencez à coder avec des modèles IA GRATUITS.
-
-**Alternative — exécuter depuis le code source :**
-
-```bash
-cp .env.example .env
-npm install
-PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
-```
-
----
-
-## 🐳 Docker
-
-OmniRoute est disponible en tant qu'image Docker publique sur [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-
-**Démarrage rapide :**
-
-```bash
-docker run -d \
-  --name omniroute \
-  --restart unless-stopped \
-  -p 20128:20128 \
-  -v omniroute-data:/app/data \
-  diegosouzapw/omniroute:latest
-```
-
-**Avec fichier d'environnement :**
-
-```bash
-# Copier et modifier le .env d'abord
-cp .env.example .env
-
-docker run -d \
-  --name omniroute \
-  --restart unless-stopped \
-  --env-file .env \
-  -p 20128:20128 \
-  -v omniroute-data:/app/data \
-  diegosouzapw/omniroute:latest
-```
-
-**Avec Docker Compose :**
-
-```bash
-# Profil de base (sans outils CLI)
-docker compose --profile base up -d
-
-# Profil CLI (Claude Code, Codex, OpenClaw intégrés)
-docker compose --profile cli up -d
-```
-
-| Image                    | Tag      | Taille | Description             |
-| ------------------------ | -------- | ------ | ----------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Dernière version stable |
-| `diegosouzapw/omniroute` | `1.0.6`  | ~250MB | Version actuelle        |
-
----
-
-## 💰 Aperçu des tarifs
-
-| Tier              | Fournisseur       | Coût                       | Réinitialisation    | Idéal pour                    |
-| ----------------- | ----------------- | -------------------------- | ------------------- | ----------------------------- |
-| **💳 ABONNEMENT** | Claude Code (Pro) | 20 $/mois                  | 5h + hebdomadaire   | Déjà abonné                   |
-|                   | Codex (Plus/Pro)  | 20-200 $/mois              | 5h + hebdomadaire   | Utilisateurs OpenAI           |
-|                   | Gemini CLI        | **GRATUIT**                | 180K/mois + 1K/jour | Tout le monde !               |
-|                   | GitHub Copilot    | 10-19 $/mois               | Mensuel             | Utilisateurs GitHub           |
-| **🔑 CLÉ API**    | NVIDIA NIM        | **GRATUIT** (1000 crédits) | Unique              | Tests gratuits                |
-|                   | DeepSeek          | À l'usage                  | Aucune              | Meilleur rapport qualité-prix |
-|                   | Groq              | Niveau gratuit + payant    | Limité              | Inférence ultra-rapide        |
-|                   | xAI (Grok)        | À l'usage                  | Aucune              | Modèles Grok                  |
-|                   | Mistral           | Niveau gratuit + payant    | Limité              | IA européenne                 |
-|                   | OpenRouter        | À l'usage                  | Aucune              | 100+ modèles                  |
-| **💰 ÉCONOMIQUE** | GLM-4.7           | 0,6 $/1M                   | Quotidien 10h       | Backup économique             |
-|                   | MiniMax M2.1      | 0,2 $/1M                   | Rotatif 5h          | Option la moins chère         |
-|                   | Kimi K2           | 9 $/mois fixe              | 10M tokens/mois     | Coût prévisible               |
-| **🆓 GRATUIT**    | iFlow             | 0 $                        | Illimité            | 8 modèles gratuits            |
-|                   | Qwen              | 0 $                        | Illimité            | 3 modèles gratuits            |
-|                   | Kiro              | 0 $                        | Illimité            | Claude gratuit                |
-
-**💡 Conseil Pro :** Commencez avec Gemini CLI (180K gratuits/mois) + iFlow (illimité gratuit) = 0 $ de coût !
-
----
-
-## 🎯 Cas d'utilisation
-
-### Cas 1 : « J'ai un abonnement Claude Pro »
-
-**Problème :** Le quota expire inutilisé, limites de débit pendant le codage intensif
-
-```
-Combo : "maximize-claude"
-  1. cc/claude-opus-4-6        (utiliser l'abonnement au maximum)
-  2. glm/glm-4.7               (backup économique quand le quota est épuisé)
-  3. if/kimi-k2-thinking       (fallback d'urgence gratuit)
-
-Coût mensuel : 20 $ (abonnement) + ~5 $ (backup) = 25 $ au total
-vs. 20 $ + atteindre les limites = frustration
-```
-
-### Cas 2 : « Je veux zéro coût »
-
-**Problème :** Impossible de payer des abonnements, besoin d'IA fiable pour coder
-
-```
-Combo : "free-forever"
-  1. gc/gemini-3-flash         (180K gratuits/mois)
-  2. if/kimi-k2-thinking       (illimité gratuit)
-  3. qw/qwen3-coder-plus       (illimité gratuit)
-
-Coût mensuel : 0 $
-Qualité : Modèles prêts pour la production
-```
-
-### Cas 3 : « Je dois coder 24/7, sans interruption »
-
-**Problème :** Délais serrés, ne peut pas se permettre de temps d'arrêt
-
-```
-Combo : "always-on"
-  1. cc/claude-opus-4-6        (meilleure qualité)
-  2. cx/gpt-5.2-codex          (deuxième abonnement)
-  3. glm/glm-4.7               (économique, reset quotidien)
-  4. minimax/MiniMax-M2.1      (le moins cher, reset 5h)
-  5. if/kimi-k2-thinking       (gratuit illimité)
-
-Résultat : 5 niveaux de fallback = zéro temps d'arrêt
-```
-
-### Cas 4 : « Je veux l'IA GRATUITE dans OpenClaw »
-
-**Problème :** Besoin d'assistant IA dans les apps de messagerie, entièrement gratuit
-
-```
-Combo : "openclaw-free"
-  1. if/glm-4.7                (illimité gratuit)
-  2. if/minimax-m2.1           (illimité gratuit)
-  3. if/kimi-k2-thinking       (illimité gratuit)
-
-Coût mensuel : 0 $
-Accès via : WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-```
-
----
-
-## 💡 Fonctionnalités principales
-
-### 🧠 Routage & Intelligence
-
-| Fonctionnalité                        | Ce qu'elle fait                                                                 |
-| ------------------------------------- | ------------------------------------------------------------------------------- |
-| 🎯 **Fallback intelligent 4 niveaux** | Auto-routage : Abonnement → Clé API → Économique → Gratuit                      |
-| 📊 **Suivi des quotas en temps réel** | Comptage de tokens en direct + compte à rebours de réinitialisation             |
-| 🔄 **Traduction de format**           | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro transparent                            |
-| 👥 **Support multi-comptes**          | Plusieurs comptes par fournisseur avec sélection intelligente                   |
-| 🔄 **Renouvellement auto des tokens** | Les tokens OAuth se renouvellent automatiquement avec retry                     |
-| 🎨 **Combos personnalisés**           | 6 stratégies : fill-first, round-robin, p2c, random, least-used, cost-optimized |
-| 🧩 **Modèles personnalisés**          | Ajoutez n'importe quel ID de modèle à n'importe quel fournisseur                |
-| 🌐 **Routeur wildcard**               | Routez les patterns `provider/*` vers n'importe quel fournisseur dynamiquement  |
-| 🧠 **Budget de raisonnement**         | Modes passthrough, auto, custom et adaptive pour les modèles de raisonnement    |
-| 💬 **Injection System Prompt**        | System prompt global appliqué à toutes les requêtes                             |
-| 📄 **API Responses**                  | Support complet de l'API Responses d'OpenAI (`/v1/responses`) pour Codex        |
-
-### 🎵 APIs multi-modales
-
-| Fonctionnalité             | Ce qu'elle fait                                         |
-| -------------------------- | ------------------------------------------------------- |
-| 🖼️ **Génération d'images** | `/v1/images/generations` — 4 fournisseurs, 9+ modèles   |
-| 📐 **Embeddings**          | `/v1/embeddings` — 6 fournisseurs, 9+ modèles           |
-| 🎤 **Transcription audio** | `/v1/audio/transcriptions` — compatible Whisper         |
-| 🔊 **Texte vers parole**   | `/v1/audio/speech` — synthèse audio multi-fournisseur   |
-| 🛡️ **Modérations**         | `/v1/moderations` — vérifications de sécurité           |
-| 🔀 **Reranking**           | `/v1/rerank` — reclassement de pertinence des documents |
-
-### 🛡️ Résilience & Sécurité
-
-| Fonctionnalité                  | Ce qu'elle fait                                                      |
-| ------------------------------- | -------------------------------------------------------------------- |
-| 🔌 **Circuit Breaker**          | Ouverture/fermeture auto par fournisseur avec seuils configurables   |
-| 🛡️ **Anti-Thundering Herd**     | Mutex + sémaphore de rate-limit pour les fournisseurs avec clé API   |
-| 🧠 **Cache sémantique**         | Cache à deux niveaux (signature + sémantique) réduit coût et latence |
-| ⚡ **Idempotence des requêtes** | Fenêtre de dédup 5s pour les requêtes dupliquées                     |
-| 🔒 **Spoofing TLS Fingerprint** | Contournement de détection de bot via wreq-js                        |
-| 🌐 **Filtrage IP**              | Allowlist/blocklist pour le contrôle d'accès API                     |
-| 📊 **Rate limits éditables**    | RPM configurable, intervalle minimum, concurrence max                |
-
-### 📊 Observabilité & Analytique
-
-| Fonctionnalité                    | Ce qu'elle fait                                                           |
-| --------------------------------- | ------------------------------------------------------------------------- |
-| 📝 **Logs de requêtes**           | Mode debug avec logs complets requête/réponse                             |
-| 💾 **Logs SQLite**                | Logs proxy persistants survivant aux redémarrages                         |
-| 📊 **Tableau de bord analytique** | Recharts : cartes de stats, graphique d'utilisation, tableau fournisseurs |
-| 📈 **Suivi de progression**       | Événements SSE de progression opt-in pour le streaming                    |
-| 🧪 **Évaluations LLM**            | Tests avec golden set et 4 stratégies de correspondance                   |
-| 🔍 **Télémétrie des requêtes**    | Agrégation de latence p50/p95/p99 + traçage X-Request-Id                  |
-| 📋 **Logs + Quotas**              | Pages dédiées pour navigation des logs et suivi des quotas                |
-| 🏥 **Tableau de bord santé**      | Uptime, états circuit breaker, lockouts, stats cache                      |
-| 💰 **Suivi des coûts**            | Gestion de budget + configuration des prix par modèle                     |
-
-### ☁️ Déploiement & Synchronisation
-
-| Fonctionnalité                    | Ce qu'elle fait                                                                 |
-| --------------------------------- | ------------------------------------------------------------------------------- |
-| 💾 **Cloud Sync**                 | Synchroniser les paramètres entre appareils via Cloudflare Workers              |
-| 🌐 **Déployer partout**           | Localhost, VPS, Docker, Cloudflare Workers                                      |
-| 🔑 **Gestion des clés API**       | Générer, faire tourner et limiter les clés API par fournisseur                  |
-| 🧙 **Assistant de configuration** | Setup guidé en 4 étapes pour les nouveaux utilisateurs                          |
-| 🔧 **Tableau de bord CLI Tools**  | Configuration en un clic pour Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Sauvegardes DB**             | Sauvegarde et restauration automatiques de tous les paramètres                  |
-
-<details>
-<summary><b>📖 Détails des fonctionnalités</b></summary>
-
-### 🎯 Fallback intelligent 4 niveaux
-
-Créez des combos avec fallback automatique :
-
-```
-Combo : "my-coding-stack"
-  1. cc/claude-opus-4-6        (votre abonnement)
-  2. nvidia/llama-3.3-70b      (API NVIDIA gratuite)
-  3. glm/glm-4.7               (backup économique, $0.6/1M)
-  4. if/kimi-k2-thinking       (fallback gratuit)
-
-→ Bascule automatiquement lorsque le quota est épuisé ou en cas d'erreurs
-```
-
-### 📊 Suivi des quotas en temps réel
-
-- Consommation de tokens par fournisseur
-- Compte à rebours de réinitialisation (5 heures, quotidien, hebdomadaire)
-- Estimation des coûts pour les niveaux payants
-- Rapports de dépenses mensuels
-
-### 🔄 Traduction de format
-
-Traduction transparente entre les formats :
-
-- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
-- Votre CLI envoie le format OpenAI → OmniRoute traduit → Le fournisseur reçoit le format natif
-- Fonctionne avec tout outil supportant les endpoints OpenAI personnalisés
-
-### 👥 Support multi-comptes
-
-- Ajouter plusieurs comptes par fournisseur
-- Round-robin automatique ou routage par priorité
-- Basculement vers le compte suivant lorsqu'un quota est atteint
-
-### 🔄 Renouvellement automatique des tokens
-
-- Les tokens OAuth se renouvellent automatiquement avant expiration
-- Pas de réauthentification manuelle nécessaire
-- Expérience transparente sur tous les fournisseurs
-
-### 🎨 Combos personnalisés
-
-- Créer des combinaisons de modèles illimitées
-- 6 stratégies : fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized
-- Partager les combos entre appareils avec Cloud Sync
-
-### 🏥 Tableau de bord santé
-
-- Statut du système (uptime, version, utilisation mémoire)
-- États des circuit breakers par fournisseur (Closed/Open/Half-Open)
-- Statut des rate limits et lockouts actifs
-- Statistiques du cache de signatures
-- Télémétrie de latence (p50/p95/p99) + cache de prompt
-- Réinitialisation de la santé en un clic
-
-### 🔧 Playground du traducteur
-
-- Déboguer, tester et visualiser les traductions de format d'API
-- Envoyer des requêtes et voir comment OmniRoute traduit entre les formats des fournisseurs
-- Inestimable pour résoudre les problèmes d'intégration
-
-### 💾 Cloud Sync
-
-- Synchroniser fournisseurs, combos et paramètres entre appareils
-- Synchronisation en arrière-plan automatique
-- Stockage chiffré sécurisé
-
-</details>
-
----
-
-## 📖 Guide de configuration
-
-<details>
-<summary><b>💳 Fournisseurs par abonnement</b></summary>
-
-### Claude Code (Pro/Max)
-
-```bash
-Tableau de bord → Fournisseurs → Connecter Claude Code
-→ Connexion OAuth → Renouvellement auto des tokens
-→ Suivi de quota 5h + hebdomadaire
-
-Modèles :
-  cc/claude-opus-4-6
-  cc/claude-sonnet-4-5-20250929
-  cc/claude-haiku-4-5-20251001
-```
-
-**Conseil Pro :** Utilisez Opus pour les tâches complexes, Sonnet pour la vitesse. OmniRoute suit les quotas par modèle !
-
-### OpenAI Codex (Plus/Pro)
-
-```bash
-Tableau de bord → Fournisseurs → Connecter Codex
-→ Connexion OAuth (port 1455)
-→ Reset 5h + hebdomadaire
-
-Modèles :
-  cx/gpt-5.2-codex
-  cx/gpt-5.1-codex-max
-```
-
-### Gemini CLI (GRATUIT 180K/mois !)
-
-```bash
-Tableau de bord → Fournisseurs → Connecter Gemini CLI
-→ Google OAuth
-→ 180K completions/mois + 1K/jour
-
-Modèles :
-  gc/gemini-3-flash-preview
-  gc/gemini-2.5-pro
-```
-
-**Meilleure valeur :** Niveau gratuit énorme ! Utilisez avant les niveaux payants.
-
-### GitHub Copilot
-
-```bash
-Tableau de bord → Fournisseurs → Connecter GitHub
-→ OAuth via GitHub
-→ Reset mensuel (1er du mois)
-
-Modèles :
-  gh/gpt-5
-  gh/claude-4.5-sonnet
-  gh/gemini-3-pro
-```
-
-</details>
-
-<details>
-<summary><b>🔑 Fournisseurs par clé API</b></summary>
-
-### NVIDIA NIM (GRATUIT 1000 crédits !)
-
-1. S'inscrire : [build.nvidia.com](https://build.nvidia.com)
-2. Obtenir une clé API gratuite (1000 crédits d'inférence inclus)
-3. Tableau de bord → Ajouter fournisseur → NVIDIA NIM :
-   - API Key : `nvapi-your-key`
-
-**Modèles :** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` et 50+ autres
-
-**Conseil Pro :** API compatible OpenAI — fonctionne parfaitement avec la traduction de format d'OmniRoute !
-
-### DeepSeek
-
-1. S'inscrire : [platform.deepseek.com](https://platform.deepseek.com)
-2. Obtenir une clé API
-3. Tableau de bord → Ajouter fournisseur → DeepSeek
-
-**Modèles :** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`
-
-### Groq (Niveau gratuit disponible !)
-
-1. S'inscrire : [console.groq.com](https://console.groq.com)
-2. Obtenir une clé API (niveau gratuit inclus)
-3. Tableau de bord → Ajouter fournisseur → Groq
-
-**Modèles :** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`
-
-**Conseil Pro :** Inférence ultra-rapide — idéal pour le codage en temps réel !
-
-### OpenRouter (100+ modèles)
-
-1. S'inscrire : [openrouter.ai](https://openrouter.ai)
-2. Obtenir une clé API
-3. Tableau de bord → Ajouter fournisseur → OpenRouter
-
-**Modèles :** Accès à 100+ modèles de tous les grands fournisseurs via une seule clé API.
-
-</details>
-
-<details>
-<summary><b>💰 Fournisseurs économiques (Backup)</b></summary>
-
-### GLM-4.7 (Reset quotidien, $0.6/1M)
-
-1. S'inscrire : [Zhipu AI](https://open.bigmodel.cn/)
-2. Obtenir une clé API du Coding Plan
-3. Tableau de bord → Ajouter clé API :
-   - Fournisseur : `glm`
-   - API Key : `your-key`
-
-**Utilisez :** `glm/glm-4.7`
-
-**Conseil Pro :** Le Coding Plan offre 3× le quota à 1/7 du coût ! Reset quotidien à 10h.
-
-### MiniMax M2.1 (Reset 5h, $0.20/1M)
-
-1. S'inscrire : [MiniMax](https://www.minimax.io/)
-2. Obtenir une clé API
-3. Tableau de bord → Ajouter clé API
-
-**Utilisez :** `minimax/MiniMax-M2.1`
-
-**Conseil Pro :** L'option la moins chère pour le contexte long (1M tokens) !
-
-### Kimi K2 (9 $/mois fixe)
-
-1. S'abonner : [Moonshot AI](https://platform.moonshot.ai/)
-2. Obtenir une clé API
-3. Tableau de bord → Ajouter clé API
-
-**Utilisez :** `kimi/kimi-latest`
-
-**Conseil Pro :** 9 $/mois fixe pour 10M tokens = 0,90 $/1M de coût effectif !
-
-</details>
-
-<details>
-<summary><b>🆓 Fournisseurs GRATUITS (Backup d'urgence)</b></summary>
-
-### iFlow (8 modèles GRATUITS)
-
-```bash
-Tableau de bord → Connecter iFlow
-→ Connexion OAuth iFlow
-→ Utilisation illimitée
-
-Modèles :
-  if/kimi-k2-thinking
-  if/qwen3-coder-plus
-  if/glm-4.7
-  if/minimax-m2
-  if/deepseek-r1
-```
-
-### Qwen (3 modèles GRATUITS)
-
-```bash
-Tableau de bord → Connecter Qwen
-→ Autorisation par code d'appareil
-→ Utilisation illimitée
-
-Modèles :
-  qw/qwen3-coder-plus
-  qw/qwen3-coder-flash
-```
-
-### Kiro (Claude GRATUIT)
-
-```bash
-Tableau de bord → Connecter Kiro
-→ AWS Builder ID ou Google/GitHub
-→ Utilisation illimitée
-
-Modèles :
-  kr/claude-sonnet-4.5
-  kr/claude-haiku-4.5
-```
-
-</details>
-
-<details>
-<summary><b>🎨 Créer des combos</b></summary>
-
-### Exemple 1 : Maximiser l'abonnement → Backup économique
-
-```
-Tableau de bord → Combos → Créer nouveau
-
-Nom : premium-coding
-Modèles :
-  1. cc/claude-opus-4-6 (Abonnement principal)
-  2. glm/glm-4.7 (Backup économique, $0.6/1M)
-  3. minimax/MiniMax-M2.1 (Fallback le moins cher, $0.20/1M)
-
-Utilisez en CLI : premium-coding
-```
-
-### Exemple 2 : Gratuit uniquement (Zéro coût)
-
-```
-Nom : free-combo
-Modèles :
-  1. gc/gemini-3-flash-preview (180K gratuits/mois)
-  2. if/kimi-k2-thinking (illimité)
-  3. qw/qwen3-coder-plus (illimité)
-
-Coût : 0 $ pour toujours !
-```
-
-</details>
-
-<details>
-<summary><b>🔧 Intégration CLI</b></summary>
-
-### Cursor IDE
-
-```
-Paramètres → Modèles → Avancé :
-  OpenAI API Base URL : http://localhost:20128/v1
-  OpenAI API Key : [du tableau de bord OmniRoute]
-  Model : cc/claude-opus-4-6
-```
-
-### Claude Code
-
-Utilisez la page **CLI Tools** dans le tableau de bord pour la configuration en un clic, ou modifiez `~/.claude/settings.json` manuellement.
-
-### Codex CLI
-
-```bash
-export OPENAI_BASE_URL="http://localhost:20128"
-export OPENAI_API_KEY="your-omniroute-api-key"
-
-codex "your prompt"
-```
-
-### OpenClaw
-
-**Option 1 — Tableau de bord (recommandé) :**
-
-```
-Tableau de bord → CLI Tools → OpenClaw → Sélectionner modèle → Appliquer
-```
-
-**Option 2 — Manuel :** Modifier `~/.openclaw/openclaw.json` :
-
-```json
-{
-  "models": {
-    "providers": {
-      "omniroute": {
-        "baseUrl": "http://127.0.0.1:20128/v1",
-        "apiKey": "sk_omniroute",
-        "api": "openai-completions"
-      }
-    }
-  }
-}
-```
-
-> **Note :** OpenClaw fonctionne uniquement avec OmniRoute local. Utilisez `127.0.0.1` au lieu de `localhost` pour éviter les problèmes de résolution IPv6.
-
-### Cline / Continue / RooCode
-
-```
-Paramètres → Configuration API :
-  Fournisseur : OpenAI Compatible
-  Base URL : http://localhost:20128/v1
-  API Key : [du tableau de bord OmniRoute]
-  Model : if/kimi-k2-thinking
-```
-
-</details>
-
----
-
-## 📊 Modèles disponibles
-
-<details>
-<summary><b>Voir tous les modèles disponibles</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/`)** - GRATUIT :
-
-- `gc/gemini-3-flash-preview`
-- `gc/gemini-2.5-pro`
-
-**GitHub Copilot (`gh/`)** :
-
-- `gh/gpt-5`
-- `gh/claude-4.5-sonnet`
-
-**NVIDIA NIM (`nvidia/`)** - Crédits GRATUITS :
-
-- `nvidia/llama-3.3-70b-instruct`
-- `nvidia/mistral-7b-instruct`
-- 50+ modèles sur [build.nvidia.com](https://build.nvidia.com)
-
-**GLM (`glm/`)** - $0.6/1M :
-
-- `glm/glm-4.7`
-
-**MiniMax (`minimax/`)** - $0.2/1M :
-
-- `minimax/MiniMax-M2.1`
-
-**iFlow (`if/`)** - GRATUIT :
-
-- `if/kimi-k2-thinking`
-- `if/qwen3-coder-plus`
-- `if/deepseek-r1`
-- `if/glm-4.7`
-- `if/minimax-m2`
-
-**Qwen (`qw/`)** - GRATUIT :
-
-- `qw/qwen3-coder-plus`
-- `qw/qwen3-coder-flash`
-
-**Kiro (`kr/`)** - GRATUIT :
-
-- `kr/claude-sonnet-4.5`
-- `kr/claude-haiku-4.5`
-
-**OpenRouter (`or/`)** - 100+ modèles :
-
-- `or/anthropic/claude-4-sonnet`
-- `or/google/gemini-2.5-pro`
-- Tout modèle de [openrouter.ai/models](https://openrouter.ai/models)
-
-</details>
-
----
-
-## 🧪 Évaluations (Evals)
-
-OmniRoute inclut un framework d'évaluation intégré pour tester la qualité des réponses LLM contre un golden set. Accès via **Analytics → Evals** dans le tableau de bord.
-
-### Golden Set intégré
-
-Le « OmniRoute Golden Set » préchargé contient 10 cas de test :
-
-- Salutations, mathématiques, géographie, génération de code
-- Conformité format JSON, traduction, markdown
-- Rejet de sécurité (contenu nocif), comptage, logique booléenne
-
-### Stratégies d'évaluation
-
-| Stratégie  | Description                                                    | Exemple                          |
-| ---------- | -------------------------------------------------------------- | -------------------------------- |
-| `exact`    | La sortie doit correspondre exactement                         | `"4"`                            |
-| `contains` | La sortie doit contenir la sous-chaîne (insensible à la casse) | `"Paris"`                        |
-| `regex`    | La sortie doit correspondre au motif regex                     | `"1.*2.*3"`                      |
-| `custom`   | Fonction JS personnalisée retourne true/false                  | `(output) => output.length > 10` |
-
----
-
-## 🐛 Dépannage
-
-<details>
-<summary><b>Cliquez pour développer le guide de dépannage</b></summary>
-
-**« Language model did not provide messages »**
-
-- Quota du fournisseur épuisé → Vérifiez le suivi de quota dans le tableau de bord
-- Solution : Utilisez un combo avec fallback ou passez à un niveau moins cher
-
-**Rate limiting**
-
-- Quota d'abonnement épuisé → Fallback vers GLM/MiniMax
-- Ajoutez un combo : `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-
-**Token OAuth expiré**
-
-- Renouvelé automatiquement par OmniRoute
-- Si le problème persiste : Tableau de bord → Fournisseur → Reconnecter
-
-**Coûts élevés**
-
-- Vérifiez les statistiques d'utilisation dans Tableau de bord → Coûts
-- Changez le modèle principal pour GLM/MiniMax
-- Utilisez le niveau gratuit (Gemini CLI, iFlow) pour les tâches non critiques
-
-**Le tableau de bord s'ouvre sur le mauvais port**
-
-- Définissez `PORT=20128` et `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
-
-**Erreurs de cloud sync**
-
-- Vérifiez que `BASE_URL` pointe vers votre instance en cours d'exécution
-- Vérifiez que `CLOUD_URL` pointe vers le point de terminaison cloud attendu
-- Gardez les valeurs `NEXT_PUBLIC_*` alignées avec les valeurs du serveur
-
-**Le premier login ne fonctionne pas**
-
-- Vérifiez `INITIAL_PASSWORD` dans `.env`
-- Si non défini, le mot de passe par défaut est `123456`
-
-**Pas de logs de requêtes**
-
-- Définissez `ENABLE_REQUEST_LOGS=true` dans `.env`
-
-**Le test de connexion affiche « Invalid » pour les fournisseurs compatibles OpenAI**
-
-- Beaucoup de fournisseurs n'exposent pas le point de terminaison `/models`
-- OmniRoute v1.0.6+ inclut une validation de secours via chat completions
-- Assurez-vous que l'URL de base inclut le suffixe `/v1`
-
-</details>
-
----
-
-## 🛠️ Stack technologique
-
-- **Runtime** : Node.js 20+
-- **Langage** : TypeScript 5.9 — **100% TypeScript** dans `src/` et `open-sse/` (v1.0.6)
-- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4
-- **Base de données** : LowDB (JSON) + SQLite (état du domaine + logs proxy)
-- **Streaming** : Server-Sent Events (SSE)
-- **Auth** : OAuth 2.0 (PKCE) + JWT + API Keys
-- **Tests** : Node.js test runner (368+ tests unitaires)
-- **CI/CD** : GitHub Actions (publication automatique npm + Docker Hub lors du release)
-- **Site web** : [omniroute.online](https://omniroute.online)
-- **Package** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Résilience** : Circuit breaker, backoff exponentiel, anti-thundering herd, spoofing TLS
-
----
-
-## 📖 Documentation
-
-| Document                                   | Description                                         |
-| ------------------------------------------ | --------------------------------------------------- |
-| [Guide utilisateur](docs/USER_GUIDE.md)    | Fournisseurs, combos, intégration CLI, déploiement  |
-| [Référence API](docs/API_REFERENCE.md)     | Tous les endpoints avec exemples                    |
-| [Dépannage](docs/TROUBLESHOOTING.md)       | Problèmes courants et solutions                     |
-| [Architecture](docs/ARCHITECTURE.md)       | Architecture système et détails internes            |
-| [Contribuer](CONTRIBUTING.md)              | Configuration de développement et directives        |
-| [Spécification OpenAPI](docs/openapi.yaml) | Spécification OpenAPI 3.0                           |
-| [Politique de sécurité](SECURITY.md)       | Signalement de vulnérabilités et pratiques sécurité |
-
----
-
-## 📧 Support
-
-> 💬 **Rejoignez notre communauté !** [Groupe WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obtenez de l'aide, partagez des astuces et restez informé.
-
-- **Site web** : [omniroute.online](https://omniroute.online)
-- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Issues** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **WhatsApp** : [Groupe communautaire](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Projet original** : [9router par decolua](https://github.com/decolua/9router)
-
----
-
-## 👥 Contributeurs
-
-[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-
-### Comment contribuer
-
-1. Forkez le dépôt
-2. Créez votre branche de fonctionnalité (`git checkout -b feature/amazing-feature`)
-3. Committez vos changements (`git commit -m 'Add amazing feature'`)
-4. Poussez vers la branche (`git push origin feature/amazing-feature`)
-5. Ouvrez une Pull Request
-
-Consultez [CONTRIBUTING.md](CONTRIBUTING.md) pour les directives détaillées.
-
-### Publier une nouvelle version
-
-```bash
-# Créer un release — la publication npm est automatique
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
-```
-
----
-
-## 📊 Historique des Stars
-
-<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
- </picture>
-</a>
-
----
-
-## 🙏 Remerciements
-
-Remerciements spéciaux à **[9router](https://github.com/decolua/9router)** par **[decolua](https://github.com/decolua)** — le projet original qui a inspiré ce fork. OmniRoute construit sur cette base incroyable avec des fonctionnalités supplémentaires, des APIs multi-modales et une réécriture complète en TypeScript.
-
-Remerciements spéciaux à **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — l'implémentation originale en Go qui a inspiré ce portage en JavaScript.
-
----
-
-## 📄 Licence
-
-Licence MIT — voir [LICENSE](LICENSE) pour les détails.
-
----
-
-<div align="center">
-  <sub>Fait avec ❤️ pour les développeurs qui codent 24/7</sub>
-  <br/>
-  <sub><a href="https://omniroute.online">omniroute.online</a></sub>
-</div>

README.ru.md

@@ -1,999 +0,0 @@
-<div align="center">
-  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute Dashboard" width="800"/>
-  
-  # 🚀 OmniRoute — Бесплатный AI Gateway
-
-### Никогда не прекращайте программировать. Умная маршрутизация к **БЕСПЛАТНЫМ и дешёвым AI-моделям** с автоматическим fallback.
-
-_Ваш универсальный API-прокси — одна точка доступа, 36+ провайдеров, нулевой простой._
-
-**Chat Completions • Embeddings • Генерация изображений • Аудио • Reranking • 100% TypeScript**
-
----
-
-### 🤖 Бесплатный AI-провайдер для ваших любимых агентов программирования
-
-_Подключайте любую IDE или CLI-инструмент с AI через OmniRoute — бесплатный API gateway для неограниченного программирования._
-
-  <table>
-    <tr>
-      <td align="center" width="110">
-        <a href="https://github.com/cline/cline">
-          <img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
-          <b>OpenClaw</b>
-        </a><br/>
-        <sub>⭐ 205K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/HKUDS/nanobot">
-          <img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
-          <b>NanoBot</b>
-        </a><br/>
-        <sub>⭐ 20.9K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/sipeed/picoclaw">
-          <img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
-          <b>PicoClaw</b>
-        </a><br/>
-        <sub>⭐ 14.6K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/zeroclaw-labs/zeroclaw">
-          <img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
-          <b>ZeroClaw</b>
-        </a><br/>
-        <sub>⭐ 9.9K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/nearai/ironclaw">
-          <img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
-          <b>IronClaw</b>
-        </a><br/>
-        <sub>⭐ 2.1K</sub>
-      </td>
-    </tr>
-    <tr>
-      <td align="center" width="110">
-        <a href="https://github.com/anomalyco/opencode">
-          <img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
-          <b>OpenCode</b>
-        </a><br/>
-        <sub>⭐ 106K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/openai/codex">
-          <img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
-          <b>Codex CLI</b>
-        </a><br/>
-        <sub>⭐ 60.8K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/anthropics/claude-code">
-          <img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
-          <b>Claude Code</b>
-        </a><br/>
-        <sub>⭐ 67.3K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/google-gemini/gemini-cli">
-          <img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
-          <b>Gemini CLI</b>
-        </a><br/>
-        <sub>⭐ 94.7K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/Kilo-Org/kilocode">
-          <img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
-          <b>Kilo Code</b>
-        </a><br/>
-        <sub>⭐ 15.5K</sub>
-      </td>
-    </tr>
-  </table>
-
-<sub>📡 Все агенты подключаются через <code>http://localhost:20128/v1</code> или <code>http://cloud.omniroute.online/v1</code> — одна конфигурация, неограниченные модели и квота</sub>
-
----
-
-[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
-[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)
-[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)
-[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-
-[🌐 Сайт](https://omniroute.online) • [🚀 Быстрый старт](#-быстрый-старт) • [💡 Функции](#-основные-функции) • [📖 Документация](#-документация) • [💰 Цены](#-обзор-цен)
-
-🌐 **Доступно на:** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
-
-</div>
-
----
-
-## 🤔 Почему OmniRoute?
-
-**Перестаньте тратить деньги и упираться в лимиты:**
-
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Квота подписки истекает неиспользованной каждый месяц
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Лимиты скорости останавливают вас посреди программирования
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Дорогие API ($20-50/месяц за провайдера)
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Ручное переключение между провайдерами
-
-**OmniRoute решает это:**
-
-- ✅ **Максимизируйте подписки** — Отслеживайте квоты, используйте всё до сброса
-- ✅ **Автоматический fallback** — Подписка → API Key → Дешёвый → Бесплатный, нулевой простой
-- ✅ **Мульти-аккаунт** — Round-robin между аккаунтами каждого провайдера
-- ✅ **Универсальный** — Работает с Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, любым CLI-инструментом
-
----
-
-## 🔄 Как это работает
-
-```
-┌─────────────┐
-│  Ваш CLI    │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
-│   Tool      │
-└──────┬──────┘
-       │ http://localhost:20128/v1
-       ↓
-┌─────────────────────────────────────────┐
-│        OmniRoute (Умный маршрутизатор)   │
-│  • Трансляция формата (OpenAI ↔ Claude) │
-│  • Отслеживание квот + Embeddings + Изображения │
-│  • Автообновление токенов               │
-└──────┬──────────────────────────────────┘
-       │
-       ├─→ [Tier 1: ПОДПИСКА] Claude Code, Codex, Gemini CLI
-       │   ↓ квота исчерпана
-       ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM и др.
-       │   ↓ лимит бюджета
-       ├─→ [Tier 3: ДЕШЁВЫЙ] GLM ($0.6/1M), MiniMax ($0.2/1M)
-       │   ↓ лимит бюджета
-       └─→ [Tier 4: БЕСПЛАТНЫЙ] iFlow, Qwen, Kiro (неограниченно)
-
-Результат: Никогда не прекращайте программировать, минимальные затраты
-```
-
----
-
-## ⚡ Быстрый старт
-
-**1. Установите глобально:**
-
-```bash
-npm install -g omniroute
-omniroute
-```
-
-🎉 Dashboard открывается на `http://localhost:20128`
-
-| Команда                 | Описание                                   |
-| ----------------------- | ------------------------------------------ |
-| `omniroute`             | Запустить сервер (порт по умолчанию 20128) |
-| `omniroute --port 3000` | Использовать другой порт                   |
-| `omniroute --no-open`   | Не открывать браузер автоматически         |
-| `omniroute --help`      | Показать справку                           |
-
-**2. Подключите БЕСПЛАТНОГО провайдера:**
-
-Dashboard → Провайдеры → Подключить **Claude Code** или **Antigravity** → OAuth вход → Готово!
-
-**3. Используйте в CLI-инструменте:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Настройки:
-  Endpoint: http://localhost:20128/v1
-  API Key: [скопируйте из dashboard]
-  Model: if/kimi-k2-thinking
-```
-
-**Готово!** Начните программировать с БЕСПЛАТНЫМИ AI-моделями.
-
-**Альтернатива — запуск из исходного кода:**
-
-```bash
-cp .env.example .env
-npm install
-PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
-```
-
----
-
-## 🐳 Docker
-
-OmniRoute доступен как публичный Docker-образ на [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-
-**Быстрый запуск:**
-
-```bash
-docker run -d \
-  --name omniroute \
-  --restart unless-stopped \
-  -p 20128:20128 \
-  -v omniroute-data:/app/data \
-  diegosouzapw/omniroute:latest
-```
-
-**С файлом окружения:**
-
-```bash
-# Скопируйте и отредактируйте .env
-cp .env.example .env
-
-docker run -d \
-  --name omniroute \
-  --restart unless-stopped \
-  --env-file .env \
-  -p 20128:20128 \
-  -v omniroute-data:/app/data \
-  diegosouzapw/omniroute:latest
-```
-
-**Используя Docker Compose:**
-
-```bash
-# Базовый профиль (без CLI-инструментов)
-docker compose --profile base up -d
-
-# CLI-профиль (Claude Code, Codex, OpenClaw встроены)
-docker compose --profile cli up -d
-```
-
-| Образ                    | Тег      | Размер | Описание                   |
-| ------------------------ | -------- | ------ | -------------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Последний стабильный релиз |
-| `diegosouzapw/omniroute` | `1.0.6`  | ~250MB | Текущая версия             |
-
----
-
-## 💰 Обзор цен
-
-| Tier              | Провайдер         | Стоимость                     | Сброс квоты        | Лучше всего для                  |
-| ----------------- | ----------------- | ----------------------------- | ------------------ | -------------------------------- |
-| **💳 ПОДПИСКА**   | Claude Code (Pro) | $20/мес                       | 5ч + еженедельно   | Уже подписан                     |
-|                   | Codex (Plus/Pro)  | $20-200/мес                   | 5ч + еженедельно   | Пользователи OpenAI              |
-|                   | Gemini CLI        | **БЕСПЛАТНО**                 | 180K/мес + 1K/день | Все!                             |
-|                   | GitHub Copilot    | $10-19/мес                    | Ежемесячно         | Пользователи GitHub              |
-| **🔑 API KEY**    | NVIDIA NIM        | **БЕСПЛАТНО** (1000 кредитов) | Одноразово         | Бесплатное тестирование          |
-|                   | DeepSeek          | По использованию              | Нет                | Лучшее соотношение цена/качество |
-|                   | Groq              | Беспл. уровень + платный      | Ограничено         | Сверхбыстрый вывод               |
-|                   | xAI (Grok)        | По использованию              | Нет                | Модели Grok                      |
-|                   | Mistral           | Беспл. уровень + платный      | Ограничено         | Европейский AI                   |
-|                   | OpenRouter        | По использованию              | Нет                | 100+ моделей                     |
-| **💰 ДЕШЁВЫЙ**    | GLM-4.7           | $0.6/1M                       | Ежедневно 10ч      | Бюджетный бэкап                  |
-|                   | 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!
-
----
-
-## 🎯 Сценарии использования
-
-### Сценарий 1: «У меня подписка Claude Pro»
-
-**Проблема:** Квота истекает неиспользованной, лимиты скорости во время интенсивного программирования
-
-```
-Combo: "maximize-claude"
-  1. cc/claude-opus-4-6        (используйте подписку полностью)
-  2. glm/glm-4.7               (дешёвый бэкап при исчерпании квоты)
-  3. if/kimi-k2-thinking       (бесплатный аварийный fallback)
-
-Месячная стоимость: $20 (подписка) + ~$5 (бэкап) = $25 итого
-vs. $20 + упирание в лимиты = разочарование
-```
-
-### Сценарий 2: «Хочу нулевую стоимость»
-
-**Проблема:** Не может позволить подписки, нужен надёжный AI для программирования
-
-```
-Combo: "free-forever"
-  1. gc/gemini-3-flash         (180K бесплатно/мес)
-  2. if/kimi-k2-thinking       (неограниченно бесплатно)
-  3. qw/qwen3-coder-plus       (неограниченно бесплатно)
-
-Месячная стоимость: $0
-Качество: Модели готовые к продакшену
-```
-
-### Сценарий 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 уровней fallback = нулевой простой
-```
-
-### Сценарий 4: «Хочу БЕСПЛАТНЫЙ AI в OpenClaw»
-
-**Проблема:** Нужен AI-ассистент в мессенджерах, полностью бесплатно
-
-```
-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...
-```
-
----
-
-## 💡 Основные функции
-
-### 🧠 Маршрутизация и интеллект
-
-| Функция                                     | Что делает                                                                    |
-| ------------------------------------------- | ----------------------------------------------------------------------------- |
-| 🎯 **Умный 4-уровневый Fallback**           | Авто-маршрутизация: Подписка → API Key → Дешёвый → Бесплатный                 |
-| 📊 **Отслеживание квот в реальном времени** | Счётчик токенов в реальном времени + обратный отсчёт до сброса                |
-| 🔄 **Трансляция формата**                   | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro бесшовно                             |
-| 👥 **Мульти-аккаунт**                       | Несколько аккаунтов на провайдера с интеллектуальным выбором                  |
-| 🔄 **Автообновление токенов**               | OAuth-токены обновляются автоматически с повторами                            |
-| 🎨 **Пользовательские комбо**               | 6 стратегий: fill-first, round-robin, p2c, random, least-used, cost-optimized |
-| 🧩 **Пользовательские модели**              | Добавьте любой ID модели к любому провайдеру                                  |
-| 🌐 **Wildcard-маршрутизатор**               | Маршрутизируйте паттерны `provider/*` к любому провайдеру динамически         |
-| 🧠 **Бюджет рассуждений**                   | Режимы passthrough, auto, custom и adaptive для моделей рассуждений           |
-| 💬 **Инъекция System Prompt**               | Глобальный system prompt для всех запросов                                    |
-| 📄 **API Responses**                        | Полная поддержка OpenAI Responses API (`/v1/responses`) для Codex             |
-
-### 🎵 Мультимодальные API
-
-| Функция                      | Что делает                                          |
-| ---------------------------- | --------------------------------------------------- |
-| 🖼️ **Генерация изображений** | `/v1/images/generations` — 4 провайдера, 9+ моделей |
-| 📐 **Embeddings**            | `/v1/embeddings` — 6 провайдеров, 9+ моделей        |
-| 🎤 **Транскрипция аудио**    | `/v1/audio/transcriptions` — Совместимо с Whisper   |
-| 🔊 **Текст в речь**          | `/v1/audio/speech` — Мульти-провайдерный синтез     |
-| 🛡️ **Модерация**             | `/v1/moderations` — Проверки безопасности контента  |
-| 🔀 **Reranking**             | `/v1/rerank` — Переранжирование релевантности       |
-
-### 🛡️ Устойчивость и безопасность
-
-| Функция                          | Что делает                                                     |
-| -------------------------------- | -------------------------------------------------------------- |
-| 🔌 **Circuit Breaker**           | Авто-открытие/закрытие по провайдеру с настраиваемыми порогами |
-| 🛡️ **Anti-Thundering Herd**      | Mutex + семафор для API key провайдеров                        |
-| 🧠 **Семантический кеш**         | Двухуровневый кеш (сигнатура + семантика) снижает стоимость    |
-| ⚡ **Идемпотентность запросов**  | 5с окно дедупликации для дублирующихся запросов                |
-| 🔒 **Спуфинг TLS Fingerprint**   | Обход обнаружения ботов через wreq-js                          |
-| 🌐 **Фильтрация IP**             | Allowlist/blocklist для контроля доступа к API                 |
-| 📊 **Настраиваемые Rate Limits** | Настраиваемые RPM, минимальный интервал, макс. конкуррентность |
-
-### 📊 Наблюдаемость и аналитика
-
-| Функция                       | Что делает                                                               |
-| ----------------------------- | ------------------------------------------------------------------------ |
-| 📝 **Логи запросов**          | Режим debug с полными логами запросов/ответов                            |
-| 💾 **Логи SQLite**            | Постоянные proxy-логи переживают перезапуски                             |
-| 📊 **Dashboard аналитики**    | Recharts: карточки статистики, график использования, таблица провайдеров |
-| 📈 **Отслеживание прогресса** | Opt-in SSE-события прогресса для стриминга                               |
-| 🧪 **Оценки LLM**             | Тестирование с golden set и 4 стратегиями сравнения                      |
-| 🔍 **Телеметрия запросов**    | Агрегация латентности p50/p95/p99 + трекинг X-Request-Id                 |
-| 📋 **Логи + Квоты**           | Отдельные страницы для просмотра логов и отслеживания квот               |
-| 🏥 **Dashboard здоровья**     | Uptime, состояния circuit breaker, блокировки, статистика кеша           |
-| 💰 **Отслеживание стоимости** | Управление бюджетом + настройка цен по моделям                           |
-
-### ☁️ Деплой и синхронизация
-
-| Функция                    | Что делает                                                                  |
-| -------------------------- | --------------------------------------------------------------------------- |
-| 💾 **Cloud Sync**          | Синхронизация настроек между устройствами через Cloudflare Workers          |
-| 🌐 **Деплой куда угодно**  | Localhost, VPS, Docker, Cloudflare Workers                                  |
-| 🔑 **Управление API Keys** | Генерация, ротация и настройка scope API keys по провайдерам                |
-| 🧙 **Мастер настройки**    | 4-шаговая настройка для новых пользователей                                 |
-| 🔧 **Dashboard CLI Tools** | Настройка в один клик для Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Бэкапы БД**           | Автоматическое резервное копирование и восстановление всех настроек         |
-
-<details>
-<summary><b>📖 Подробности функций</b></summary>
-
-### 🎯 Умный 4-уровневый Fallback
-
-Создавайте комбо с автоматическим fallback:
-
-```
-Combo: "my-coding-stack"
-  1. cc/claude-opus-4-6        (ваша подписка)
-  2. nvidia/llama-3.3-70b      (бесплатный NVIDIA API)
-  3. glm/glm-4.7               (дешёвый бэкап, $0.6/1M)
-  4. if/kimi-k2-thinking       (бесплатный fallback)
-
-→ Автоматически переключается при исчерпании квоты или ошибках
-```
-
-### 📊 Отслеживание квот в реальном времени
-
-- Потребление токенов по провайдерам
-- Обратный отсчёт до сброса (5 часов, ежедневно, еженедельно)
-- Оценка стоимости для платных уровней
-- Ежемесячные отчёты о расходах
-
-### 🔄 Трансляция формата
-
-Бесшовная трансляция между форматами:
-
-- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
-- Ваш CLI отправляет формат OpenAI → OmniRoute транслирует → Провайдер получает нативный формат
-- Работает с любым инструментом, поддерживающим пользовательские OpenAI endpoints
-
-### 👥 Мульти-аккаунт
-
-- Добавляйте несколько аккаунтов на провайдера
-- Автоматический round-robin или маршрутизация по приоритету
-- Fallback на следующий аккаунт при исчерпании квоты
-
-### 🔄 Автообновление токенов
-
-- OAuth-токены обновляются автоматически до истечения
-- Без необходимости ручной повторной аутентификации
-- Бесшовный опыт по всем провайдерам
-
-### 🎨 Пользовательские комбо
-
-- Создавайте неограниченные комбинации моделей
-- 6 стратегий: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized
-- Делитесь комбо между устройствами с Cloud Sync
-
-### 🏥 Dashboard здоровья
-
-- Статус системы (uptime, версия, использование памяти)
-- Состояния circuit breaker по провайдерам (Closed/Open/Half-Open)
-- Статус rate limit и активные блокировки
-- Статистика кеша сигнатур
-- Телеметрия латентности (p50/p95/p99) + кеш промптов
-- Сброс состояния здоровья одним кликом
-
-### 🔧 Playground транслятора
-
-- Отладка, тестирование и визуализация трансляции форматов API
-- Отправляйте запросы и смотрите, как OmniRoute транслирует между форматами провайдеров
-- Бесценно для устранения проблем интеграции
-
-### 💾 Cloud Sync
-
-- Синхронизация провайдеров, комбо и настроек между устройствами
-- Автоматическая фоновая синхронизация
-- Безопасное шифрованное хранилище
-
-</details>
-
----
-
-## 📖 Руководство по настройке
-
-<details>
-<summary><b>💳 Провайдеры по подписке</b></summary>
-
-### Claude Code (Pro/Max)
-
-```bash
-Dashboard → Провайдеры → Подключить Claude Code
-→ OAuth вход → Автообновление токенов
-→ Отслеживание квоты 5ч + еженедельно
-
-Модели:
-  cc/claude-opus-4-6
-  cc/claude-sonnet-4-5-20250929
-  cc/claude-haiku-4-5-20251001
-```
-
-**Совет:** Используйте Opus для сложных задач, Sonnet для скорости. OmniRoute отслеживает квоту по моделям!
-
-### OpenAI Codex (Plus/Pro)
-
-```bash
-Dashboard → Провайдеры → Подключить Codex
-→ OAuth вход (порт 1455)
-→ Сброс 5ч + еженедельно
-
-Модели:
-  cx/gpt-5.2-codex
-  cx/gpt-5.1-codex-max
-```
-
-### Gemini CLI (БЕСПЛАТНО 180K/мес!)
-
-```bash
-Dashboard → Провайдеры → Подключить Gemini CLI
-→ Google OAuth
-→ 180K completions/мес + 1K/день
-
-Модели:
-  gc/gemini-3-flash-preview
-  gc/gemini-2.5-pro
-```
-
-**Лучшая ценность:** Огромный бесплатный уровень! Используйте перед платными.
-
-### GitHub Copilot
-
-```bash
-Dashboard → Провайдеры → Подключить GitHub
-→ OAuth через GitHub
-→ Ежемесячный сброс (1-е число)
-
-Модели:
-  gh/gpt-5
-  gh/claude-4.5-sonnet
-  gh/gemini-3-pro
-```
-
-</details>
-
-<details>
-<summary><b>🔑 Провайдеры по API Key</b></summary>
-
-### NVIDIA NIM (БЕСПЛАТНО 1000 кредитов!)
-
-1. Регистрация: [build.nvidia.com](https://build.nvidia.com)
-2. Получите бесплатный API key (1000 кредитов включены)
-3. Dashboard → Добавить провайдера → NVIDIA NIM:
-   - API Key: `nvapi-your-key`
-
-**Модели:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` и 50+ других
-
-**Совет:** OpenAI-совместимый API — работает идеально с трансляцией форматов OmniRoute!
-
-### DeepSeek
-
-1. Регистрация: [platform.deepseek.com](https://platform.deepseek.com)
-2. Получите API key
-3. Dashboard → Добавить провайдера → DeepSeek
-
-**Модели:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`
-
-### Groq (Бесплатный уровень доступен!)
-
-1. Регистрация: [console.groq.com](https://console.groq.com)
-2. Получите API key (бесплатный уровень включён)
-3. Dashboard → Добавить провайдера → Groq
-
-**Модели:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`
-
-**Совет:** Сверхбыстрый вывод — лучший для программирования в реальном времени!
-
-### OpenRouter (100+ моделей)
-
-1. Регистрация: [openrouter.ai](https://openrouter.ai)
-2. Получите API key
-3. Dashboard → Добавить провайдера → OpenRouter
-
-**Модели:** Доступ к 100+ моделям от всех основных провайдеров через один API key.
-
-</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. Dashboard → Добавить API Key:
-   - Провайдер: `glm`
-   - API Key: `your-key`
-
-**Используйте:** `glm/glm-4.7`
-
-**Совет:** Coding Plan предлагает 3× квоту по цене 1/7! Ежедневный сброс в 10:00.
-
-### MiniMax M2.1 (Сброс 5ч, $0.20/1M)
-
-1. Регистрация: [MiniMax](https://www.minimax.io/)
-2. Получите API key
-3. Dashboard → Добавить API Key
-
-**Используйте:** `minimax/MiniMax-M2.1`
-
-**Совет:** Самый дешёвый вариант для длинного контекста (1M токенов)!
-
-### Kimi K2 ($9/мес фикс)
-
-1. Подпишитесь: [Moonshot AI](https://platform.moonshot.ai/)
-2. Получите API key
-3. Dashboard → Добавить API Key
-
-**Используйте:** `kimi/kimi-latest`
-
-**Совет:** Фикс $9/мес за 10M токенов = $0.90/1M эффективная стоимость!
-
-</details>
-
-<details>
-<summary><b>🆓 БЕСПЛАТНЫЕ провайдеры (Аварийный бэкап)</b></summary>
-
-### iFlow (8 БЕСПЛАТНЫХ моделей)
-
-```bash
-Dashboard → Подключить iFlow
-→ OAuth вход iFlow
-→ Неограниченное использование
-
-Модели:
-  if/kimi-k2-thinking
-  if/qwen3-coder-plus
-  if/glm-4.7
-  if/minimax-m2
-  if/deepseek-r1
-```
-
-### Qwen (3 БЕСПЛАТНЫЕ модели)
-
-```bash
-Dashboard → Подключить Qwen
-→ Авторизация по коду устройства
-→ Неограниченное использование
-
-Модели:
-  qw/qwen3-coder-plus
-  qw/qwen3-coder-flash
-```
-
-### Kiro (Claude БЕСПЛАТНО)
-
-```bash
-Dashboard → Подключить Kiro
-→ AWS Builder ID или Google/GitHub
-→ Неограниченное использование
-
-Модели:
-  kr/claude-sonnet-4.5
-  kr/claude-haiku-4.5
-```
-
-</details>
-
-<details>
-<summary><b>🎨 Создание комбо</b></summary>
-
-### Пример 1: Максимизация подписки → Дешёвый бэкап
-
-```
-Dashboard → Комбо → Создать новое
-
-Название: premium-coding
-Модели:
-  1. cc/claude-opus-4-6 (Основная подписка)
-  2. glm/glm-4.7 (Дешёвый бэкап, $0.6/1M)
-  3. minimax/MiniMax-M2.1 (Самый дешёвый fallback, $0.20/1M)
-
-Используйте в CLI: premium-coding
-```
-
-### Пример 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
-
-```
-Настройки → Модели → Расширенные:
-  OpenAI API Base URL: http://localhost:20128/v1
-  OpenAI API Key: [из dashboard OmniRoute]
-  Model: cc/claude-opus-4-6
-```
-
-### Claude Code
-
-Используйте страницу **CLI Tools** в dashboard для настройки в один клик, или редактируйте `~/.claude/settings.json` вручную.
-
-### Codex CLI
-
-```bash
-export OPENAI_BASE_URL="http://localhost:20128"
-export OPENAI_API_KEY="your-omniroute-api-key"
-
-codex "your prompt"
-```
-
-### OpenClaw
-
-**Вариант 1 — Dashboard (рекомендуется):**
-
-```
-Dashboard → CLI Tools → OpenClaw → Выбрать модель → Применить
-```
-
-**Вариант 2 — Вручную:** Редактируйте `~/.openclaw/openclaw.json`:
-
-```json
-{
-  "models": {
-    "providers": {
-      "omniroute": {
-        "baseUrl": "http://127.0.0.1:20128/v1",
-        "apiKey": "sk_omniroute",
-        "api": "openai-completions"
-      }
-    }
-  }
-}
-```
-
-> **Примечание:** OpenClaw работает только с локальным OmniRoute. Используйте `127.0.0.1` вместо `localhost` для избежания проблем с IPv6.
-
-### Cline / Continue / RooCode
-
-```
-Настройки → Конфигурация API:
-  Провайдер: OpenAI Compatible
-  Base URL: http://localhost:20128/v1
-  API Key: [из dashboard OmniRoute]
-  Model: if/kimi-k2-thinking
-```
-
-</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`
-
-**NVIDIA NIM (`nvidia/`)** - БЕСПЛАТНЫЕ кредиты:
-
-- `nvidia/llama-3.3-70b-instruct`
-- `nvidia/mistral-7b-instruct`
-- 50+ моделей на [build.nvidia.com](https://build.nvidia.com)
-
-**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`
-- `if/glm-4.7`
-- `if/minimax-m2`
-
-**Qwen (`qw/`)** - БЕСПЛАТНО:
-
-- `qw/qwen3-coder-plus`
-- `qw/qwen3-coder-flash`
-
-**Kiro (`kr/`)** - БЕСПЛАТНО:
-
-- `kr/claude-sonnet-4.5`
-- `kr/claude-haiku-4.5`
-
-**OpenRouter (`or/`)** - 100+ моделей:
-
-- `or/anthropic/claude-4-sonnet`
-- `or/google/gemini-2.5-pro`
-- Любая модель с [openrouter.ai/models](https://openrouter.ai/models)
-
-</details>
-
----
-
-## 🧪 Оценки (Evals)
-
-OmniRoute включает встроенный фреймворк оценки для тестирования качества ответов LLM по golden set. Доступ через **Analytics → Evals** в dashboard.
-
-### Встроенный Golden Set
-
-Предзагруженный «OmniRoute Golden Set» содержит 10 тестов:
-
-- Приветствия, математика, география, генерация кода
-- Соответствие формату JSON, перевод, markdown
-- Отказ от небезопасного контента, подсчёт, булева логика
-
-### Стратегии оценки
-
-| Стратегия  | Описание                                              | Пример                           |
-| ---------- | ----------------------------------------------------- | -------------------------------- |
-| `exact`    | Вывод должен совпадать точно                          | `"4"`                            |
-| `contains` | Вывод должен содержать подстроку (без учёта регистра) | `"Paris"`                        |
-| `regex`    | Вывод должен соответствовать regex-паттерну           | `"1.*2.*3"`                      |
-| `custom`   | Пользовательская JS-функция возвращает true/false     | `(output) => output.length > 10` |
-
----
-
-## 🐛 Устранение неполадок
-
-<details>
-<summary><b>Нажмите для раскрытия руководства</b></summary>
-
-**«Language model did not provide messages»**
-
-- Квота провайдера исчерпана → Проверьте трекер квот в dashboard
-- Решение: Используйте комбо с fallback или переключитесь на более дешёвый уровень
-
-**Rate limiting**
-
-- Квота подписки исчерпана → Fallback на GLM/MiniMax
-- Добавьте комбо: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-
-**OAuth-токен истёк**
-
-- Обновляется автоматически OmniRoute
-- Если проблема сохраняется: Dashboard → Провайдер → Переподключить
-
-**Высокие расходы**
-
-- Проверьте статистику в Dashboard → Расходы
-- Переключите основную модель на GLM/MiniMax
-- Используйте бесплатный уровень (Gemini CLI, iFlow) для некритичных задач
-
-**Dashboard открывается на неправильном порту**
-
-- Установите `PORT=20128` и `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
-
-**Ошибки cloud sync**
-
-- Проверьте что `BASE_URL` указывает на ваш запущенный экземпляр
-- Проверьте что `CLOUD_URL` указывает на правильный облачный endpoint
-- Держите значения `NEXT_PUBLIC_*` синхронизированными с серверными значениями
-
-**Первый вход не работает**
-
-- Проверьте `INITIAL_PASSWORD` в `.env`
-- Если не задан, пароль по умолчанию `123456`
-
-**Нет логов запросов**
-
-- Установите `ENABLE_REQUEST_LOGS=true` в `.env`
-
-**Тест подключения показывает «Invalid» для OpenAI-совместимых провайдеров**
-
-- Многие провайдеры не предоставляют endpoint `/models`
-- OmniRoute v1.0.6+ включает fallback-валидацию через chat completions
-- Убедитесь что base URL содержит суффикс `/v1`
-
-</details>
-
----
-
-## 🛠️ Технологический стек
-
-- **Runtime**: Node.js 20+
-- **Язык**: TypeScript 5.9 — **100% TypeScript** в `src/` и `open-sse/` (v1.0.6)
-- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
-- **База данных**: LowDB (JSON) + SQLite (состояние домена + proxy-логи)
-- **Стриминг**: Server-Sent Events (SSE)
-- **Аутентификация**: OAuth 2.0 (PKCE) + JWT + API Keys
-- **Тестирование**: Node.js test runner (368+ юнит-тестов)
-- **CI/CD**: GitHub Actions (авто-публикация npm + Docker Hub при релизе)
-- **Сайт**: [omniroute.online](https://omniroute.online)
-- **Пакет**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Устойчивость**: Circuit breaker, экспоненциальный backoff, anti-thundering herd, TLS-спуфинг
-
----
-
-## 📖 Документация
-
-| Документ                                        | Описание                                         |
-| ----------------------------------------------- | ------------------------------------------------ |
-| [Руководство пользователя](docs/USER_GUIDE.md)  | Провайдеры, комбо, интеграция CLI, деплой        |
-| [Справка API](docs/API_REFERENCE.md)            | Все endpoints с примерами                        |
-| [Устранение неполадок](docs/TROUBLESHOOTING.md) | Частые проблемы и решения                        |
-| [Архитектура](docs/ARCHITECTURE.md)             | Архитектура системы и внутреннее устройство      |
-| [Как внести вклад](CONTRIBUTING.md)             | Настройка разработки и руководящие принципы      |
-| [Спецификация OpenAPI](docs/openapi.yaml)       | Спецификация OpenAPI 3.0                         |
-| [Политика безопасности](SECURITY.md)            | Сообщение об уязвимостях и практики безопасности |
-
----
-
-## 📧 Поддержка
-
-> 💬 **Присоединяйтесь к сообществу!** [Группа WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Получайте помощь, делитесь советами и оставайтесь в курсе.
-
-- **Сайт**: [omniroute.online](https://omniroute.online)
-- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **WhatsApp**: [Группа сообщества](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Оригинальный проект**: [9router от decolua](https://github.com/decolua/9router)
-
----
-
-## 👥 Участники
-
-[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-
-### Как внести вклад
-
-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
-
-См. [CONTRIBUTING.md](CONTRIBUTING.md) для подробных рекомендаций.
-
-### Выпуск новой версии
-
-```bash
-# Создайте релиз — публикация в npm происходит автоматически
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
-```
-
----
-
-## 📊 История звёзд
-
-<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
- </picture>
-</a>
-
----
-
-## 🙏 Благодарности
-
-Особая благодарность **[9router](https://github.com/decolua/9router)** от **[decolua](https://github.com/decolua)** — оригинальному проекту, вдохновившему этот форк. OmniRoute строится на этом невероятном фундаменте с дополнительными функциями, мультимодальными API и полной переписью на TypeScript.
-
-Особая благодарность **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — оригинальной реализации на Go, вдохновившей этот порт на JavaScript.
-
----
-
-## 📄 Лицензия
-
-Лицензия MIT — см. [LICENSE](LICENSE) для подробностей.
-
----
-
-<div align="center">
-  <sub>Сделано с ❤️ для разработчиков, которые программируют 24/7</sub>
-  <br/>
-  <sub><a href="https://omniroute.online">omniroute.online</a></sub>
-</div>

README.zh-CN.md

@@ -1,999 +0,0 @@
-<div align="center">
-  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute Dashboard" width="800"/>
-  
-  # 🚀 OmniRoute — 免费 AI 网关
-
-### 永不停止编程。智能路由至**免费和低成本 AI 模型**，自动故障转移。
-
-_您的通用 API 代理 — 一个端点，36+ 提供商，零停机时间。_
-
-**Chat Completions • Embeddings • 图像生成 • 音频 • Reranking • 100% TypeScript**
-
----
-
-### 🤖 为您最爱的编程代理提供免费 AI
-
-_通过 OmniRoute 连接任何 AI 驱动的 IDE 或 CLI 工具 — 免费 API 网关，无限编程。_
-
-  <table>
-    <tr>
-      <td align="center" width="110">
-        <a href="https://github.com/cline/cline">
-          <img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
-          <b>OpenClaw</b>
-        </a><br/>
-        <sub>⭐ 205K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/HKUDS/nanobot">
-          <img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
-          <b>NanoBot</b>
-        </a><br/>
-        <sub>⭐ 20.9K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/sipeed/picoclaw">
-          <img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
-          <b>PicoClaw</b>
-        </a><br/>
-        <sub>⭐ 14.6K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/zeroclaw-labs/zeroclaw">
-          <img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
-          <b>ZeroClaw</b>
-        </a><br/>
-        <sub>⭐ 9.9K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/nearai/ironclaw">
-          <img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
-          <b>IronClaw</b>
-        </a><br/>
-        <sub>⭐ 2.1K</sub>
-      </td>
-    </tr>
-    <tr>
-      <td align="center" width="110">
-        <a href="https://github.com/anomalyco/opencode">
-          <img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
-          <b>OpenCode</b>
-        </a><br/>
-        <sub>⭐ 106K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/openai/codex">
-          <img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
-          <b>Codex CLI</b>
-        </a><br/>
-        <sub>⭐ 60.8K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/anthropics/claude-code">
-          <img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
-          <b>Claude Code</b>
-        </a><br/>
-        <sub>⭐ 67.3K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/google-gemini/gemini-cli">
-          <img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
-          <b>Gemini CLI</b>
-        </a><br/>
-        <sub>⭐ 94.7K</sub>
-      </td>
-      <td align="center" width="110">
-        <a href="https://github.com/Kilo-Org/kilocode">
-          <img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
-          <b>Kilo Code</b>
-        </a><br/>
-        <sub>⭐ 15.5K</sub>
-      </td>
-    </tr>
-  </table>
-
-<sub>📡 所有代理通过 <code>http://localhost:20128/v1</code> 或 <code>http://cloud.omniroute.online/v1</code> 连接 — 一个配置，无限模型和配额</sub>
-
----
-
-[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
-[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)
-[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)
-[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-
-[🌐 网站](https://omniroute.online) • [🚀 快速开始](#-快速开始) • [💡 功能特性](#-核心功能) • [📖 文档](#-文档) • [💰 定价](#-定价概览)
-
-🌐 **多语言版本：** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
-
-</div>
-
----
-
-## 🤔 为什么选择 OmniRoute？
-
-**停止浪费金钱和遭遇限制：**
-
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> 订阅配额每月未使用就过期
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> 速率限制在编程中途停止你
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> 昂贵的 API（每个提供商 $20-50/月）
-- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> 手动在提供商间切换
-
-**OmniRoute 解决这些问题：**
-
-- ✅ **最大化订阅** — 追踪配额，在重置前用完每一点
-- ✅ **自动故障转移** — 订阅 → API Key → 低价 → 免费，零停机
-- ✅ **多账号** — 每个提供商的账号轮询
-- ✅ **通用** — 适用于 Claude Code、Codex、Gemini CLI、Cursor、Cline、OpenClaw、任何 CLI 工具
-
----
-
-## 🔄 工作原理
-
-```
-┌─────────────┐
-│  您的 CLI   │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
-│   工具      │
-└──────┬──────┘
-       │ http://localhost:20128/v1
-       ↓
-┌─────────────────────────────────────────┐
-│         OmniRoute（智能路由器）           │
-│  • 格式转换（OpenAI ↔ Claude）          │
-│  • 配额追踪 + Embeddings + 图像         │
-│  • 自动令牌刷新                         │
-└──────┬──────────────────────────────────┘
-       │
-       ├─→ [第1层: 订阅] Claude Code, Codex, Gemini CLI
-       │   ↓ 配额用完
-       ├─→ [第2层: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM 等
-       │   ↓ 预算限制
-       ├─→ [第3层: 低价] GLM ($0.6/1M), MiniMax ($0.2/1M)
-       │   ↓ 预算限制
-       └─→ [第4层: 免费] iFlow, Qwen, Kiro（无限制）
-
-结果：永不停止编程，成本最低
-```
-
----
-
-## ⚡ 快速开始
-
-**1. 全局安装：**
-
-```bash
-npm install -g omniroute
-omniroute
-```
-
-🎉 仪表板在 `http://localhost:20128` 打开
-
-| 命令                    | 描述                         |
-| ----------------------- | ---------------------------- |
-| `omniroute`             | 启动服务器（默认端口 20128） |
-| `omniroute --port 3000` | 使用自定义端口               |
-| `omniroute --no-open`   | 不自动打开浏览器             |
-| `omniroute --help`      | 显示帮助                     |
-
-**2. 连接免费提供商：**
-
-仪表板 → 提供商 → 连接 **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 模型编程。
-
-**替代方案 — 从源代码运行：**
-
-```bash
-cp .env.example .env
-npm install
-PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
-```
-
----
-
-## 🐳 Docker
-
-OmniRoute 作为公共 Docker 镜像在 [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute) 上可用。
-
-**快速运行：**
-
-```bash
-docker run -d \
-  --name omniroute \
-  --restart unless-stopped \
-  -p 20128:20128 \
-  -v omniroute-data:/app/data \
-  diegosouzapw/omniroute:latest
-```
-
-**使用环境文件：**
-
-```bash
-# 先复制并编辑 .env
-cp .env.example .env
-
-docker run -d \
-  --name omniroute \
-  --restart unless-stopped \
-  --env-file .env \
-  -p 20128:20128 \
-  -v omniroute-data:/app/data \
-  diegosouzapw/omniroute:latest
-```
-
-**使用 Docker Compose：**
-
-```bash
-# 基础配置（无 CLI 工具）
-docker compose --profile base up -d
-
-# CLI 配置（内置 Claude Code、Codex、OpenClaw）
-docker compose --profile cli up -d
-```
-
-| 镜像                     | 标签     | 大小   | 描述       |
-| ------------------------ | -------- | ------ | ---------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | 最新稳定版 |
-| `diegosouzapw/omniroute` | `1.0.6`  | ~250MB | 当前版本   |
-
----
-
-## 💰 定价概览
-
-| 层级           | 提供商            | 费用                  | 配额重置        | 最适合       |
-| -------------- | ----------------- | --------------------- | --------------- | ------------ |
-| **💳 订阅**    | Claude Code (Pro) | $20/月                | 5小时 + 每周    | 已订阅用户   |
-|                | Codex (Plus/Pro)  | $20-200/月            | 5小时 + 每周    | OpenAI 用户  |
-|                | Gemini CLI        | **免费**              | 180K/月 + 1K/天 | 所有人！     |
-|                | GitHub Copilot    | $10-19/月             | 每月            | GitHub 用户  |
-| **🔑 API KEY** | NVIDIA NIM        | **免费**（1000 积分） | 一次性          | 免费测试     |
-|                | DeepSeek          | 按使用量              | 无              | 最佳性价比   |
-|                | Groq              | 免费层 + 付费         | 限速            | 超快推理     |
-|                | xAI (Grok)        | 按使用量              | 无              | Grok 模型    |
-|                | Mistral           | 免费层 + 付费         | 限速            | 欧洲 AI      |
-|                | OpenRouter        | 按使用量              | 无              | 100+ 模型    |
-| **💰 低价**    | GLM-4.7           | $0.6/1M               | 每日 10时       | 经济备用     |
-|                | MiniMax M2.1      | $0.2/1M               | 5小时滚动       | 最便宜选项   |
-|                | Kimi K2           | $9/月固定             | 每月 10M Token  | 可预测成本   |
-| **🆓 免费**    | iFlow             | $0                    | 无限制          | 8 个免费模型 |
-|                | Qwen              | $0                    | 无限制          | 3 个免费模型 |
-|                | Kiro              | $0                    | 无限制          | 免费 Claude  |
-
-**💡 专业建议：** 从 Gemini CLI（每月 180K 免费）+ iFlow（无限免费）开始 = $0 成本！
-
----
-
-## 🎯 使用场景
-
-### 场景 1："我有 Claude Pro 订阅"
-
-**问题：** 配额未使用就过期，编程高峰期遇到速率限制
-
-```
-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
-质量：生产级模型
-```
-
-### 场景 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 层故障转移 = 零停机
-```
-
-### 场景 4："我想在 OpenClaw 中使用免费 AI"
-
-**问题：** 需要在消息应用中使用 AI 助手，完全免费
-
-```
-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...
-```
-
----
-
-## 💡 核心功能
-
-### 🧠 路由与智能
-
-| 功能                      | 功能描述                                                                   |
-| ------------------------- | -------------------------------------------------------------------------- |
-| 🎯 **智能 4 层故障转移**  | 自动路由：订阅 → API Key → 低价 → 免费                                     |
-| 📊 **实时配额追踪**       | 实时 Token 计数 + 每个提供商的重置倒计时                                   |
-| 🔄 **格式转换**           | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro 无缝切换                          |
-| 👥 **多账号支持**         | 每个提供商多个账号，智能选择                                               |
-| 🔄 **自动令牌刷新**       | OAuth 令牌自动刷新并重试                                                   |
-| 🎨 **自定义组合**         | 6 种策略：fill-first、round-robin、p2c、random、least-used、cost-optimized |
-| 🧩 **自定义模型**         | 为任何提供商添加任何模型 ID                                                |
-| 🌐 **通配符路由**         | 动态路由 `provider/*` 模式到任何提供商                                     |
-| 🧠 **推理预算**           | passthrough、auto、custom 和 adaptive 模式用于推理模型                     |
-| 💬 **System Prompt 注入** | 全局 System Prompt 应用于所有请求                                          |
-| 📄 **Responses API**      | 完整支持 OpenAI Responses API (`/v1/responses`) 用于 Codex                 |
-
-### 🎵 多模态 API
-
-| 功能              | 功能描述                                       |
-| ----------------- | ---------------------------------------------- |
-| 🖼️ **图像生成**   | `/v1/images/generations` — 4 个提供商，9+ 模型 |
-| 📐 **Embeddings** | `/v1/embeddings` — 6 个提供商，9+ 模型         |
-| 🎤 **音频转录**   | `/v1/audio/transcriptions` — Whisper 兼容      |
-| 🔊 **文字转语音** | `/v1/audio/speech` — 多提供商音频合成          |
-| 🛡️ **内容审核**   | `/v1/moderations` — 内容安全检查               |
-| 🔀 **重排序**     | `/v1/rerank` — 文档相关性重排序                |
-
-### 🛡️ 弹性与安全
-
-| 功能                  | 功能描述                               |
-| --------------------- | -------------------------------------- |
-| 🔌 **断路器**         | 每个提供商自动打开/关闭，可配置阈值    |
-| 🛡️ **反惊群**         | Mutex + 信号量限速用于 API Key 提供商  |
-| 🧠 **语义缓存**       | 两层缓存（签名 + 语义）降低成本和延迟  |
-| ⚡ **请求幂等性**     | 5 秒去重窗口防止重复请求               |
-| 🔒 **TLS 指纹伪装**   | 通过 wreq-js 绕过基于 TLS 的机器人检测 |
-| 🌐 **IP 过滤**        | 白名单/黑名单用于 API 访问控制         |
-| 📊 **可编辑速率限制** | 可配置的 RPM、最小间隔和最大并发       |
-
-### 📊 可观察性与分析
-
-| 功能               | 功能描述                                   |
-| ------------------ | ------------------------------------------ |
-| 📝 **请求日志**    | 调试模式，完整的请求/响应日志              |
-| 💾 **SQLite 日志** | 持久化代理日志，服务器重启后仍然保留       |
-| 📊 **分析仪表板**  | Recharts：统计卡片、使用量图表、提供商表格 |
-| 📈 **进度追踪**    | 流式传输的 SSE 进度事件（可选）            |
-| 🧪 **LLM 评估**    | 黄金集测试，4 种匹配策略                   |
-| 🔍 **请求遥测**    | p50/p95/p99 延迟聚合 + X-Request-Id 追踪   |
-| 📋 **日志 + 配额** | 专用页面用于日志浏览和配额追踪             |
-| 🏥 **健康仪表板**  | 运行时间、断路器状态、锁定、缓存统计       |
-| 💰 **成本追踪**    | 预算管理 + 每模型定价配置                  |
-
-### ☁️ 部署与同步
-
-| 功能                  | 功能描述                                                   |
-| --------------------- | ---------------------------------------------------------- |
-| 💾 **Cloud Sync**     | 通过 Cloudflare Workers 在设备间同步配置                   |
-| 🌐 **随处部署**       | Localhost、VPS、Docker、Cloudflare Workers                 |
-| 🔑 **API Key 管理**   | 按提供商生成、轮换和设定 API Key 范围                      |
-| 🧙 **配置向导**       | 4 步引导式设置，面向新用户                                 |
-| 🔧 **CLI 工具仪表板** | 一键配置 Claude、Codex、Cline、OpenClaw、Kilo、Antigravity |
-| 🔄 **数据库备份**     | 自动备份和恢复所有设置                                     |
-
-<details>
-<summary><b>📖 功能详情</b></summary>
-
-### 🎯 智能 4 层故障转移
-
-创建带自动故障转移的组合：
-
-```
-Combo: "my-coding-stack"
-  1. cc/claude-opus-4-6        （您的订阅）
-  2. nvidia/llama-3.3-70b      （免费 NVIDIA API）
-  3. glm/glm-4.7               （便宜备用，$0.6/1M）
-  4. if/kimi-k2-thinking       （免费后备）
-
-→ 配额用完或出错时自动切换
-```
-
-### 📊 实时配额追踪
-
-- 每个提供商的 Token 消耗
-- 重置倒计时（5 小时、每日、每周）
-- 付费层级的成本估算
-- 月度支出报告
-
-### 🔄 格式转换
-
-格式间的无缝转换：
-
-- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
-- 您的 CLI 发送 OpenAI 格式 → OmniRoute 转换 → 提供商接收原生格式
-- 适用于任何支持自定义 OpenAI 端点的工具
-
-### 👥 多账号支持
-
-- 每个提供商添加多个账号
-- 自动轮询或基于优先级的路由
-- 当一个账号达到配额时自动切换到下一个
-
-### 🔄 自动令牌刷新
-
-- OAuth 令牌在过期前自动刷新
-- 无需手动重新认证
-- 所有提供商的无缝体验
-
-### 🎨 自定义组合
-
-- 创建无限模型组合
-- 6 种策略：fill-first、round-robin、power-of-two-choices、random、least-used、cost-optimized
-- 通过 Cloud Sync 在设备间共享组合
-
-### 🏥 健康仪表板
-
-- 系统状态（运行时间、版本、内存使用）
-- 每个提供商的断路器状态（Closed/Open/Half-Open）
-- 速率限制状态和活动锁定
-- 签名缓存统计
-- 延迟遥测（p50/p95/p99）+ 提示缓存
-- 一键重置健康状态
-
-### 🔧 翻译器 Playground
-
-- 调试、测试和可视化 API 格式转换
-- 发送请求并查看 OmniRoute 如何在提供商格式间转换
-- 对排查集成问题非常有价值
-
-### 💾 Cloud Sync
-
-- 在设备间同步提供商、组合和设置
-- 自动后台同步
-- 安全加密存储
-
-</details>
-
----
-
-## 📖 设置指南
-
-<details>
-<summary><b>💳 订阅提供商</b></summary>
-
-### Claude Code (Pro/Max)
-
-```bash
-仪表板 → 提供商 → 连接 Claude Code
-→ OAuth 登录 → 自动令牌刷新
-→ 5 小时 + 每周配额追踪
-
-模型：
-  cc/claude-opus-4-6
-  cc/claude-sonnet-4-5-20250929
-  cc/claude-haiku-4-5-20251001
-```
-
-**专业建议：** 复杂任务用 Opus，追求速度用 Sonnet。OmniRoute 按模型追踪配额！
-
-### OpenAI Codex (Plus/Pro)
-
-```bash
-仪表板 → 提供商 → 连接 Codex
-→ OAuth 登录（端口 1455）
-→ 5 小时 + 每周重置
-
-模型：
-  cx/gpt-5.2-codex
-  cx/gpt-5.1-codex-max
-```
-
-### Gemini CLI（免费 180K/月！）
-
-```bash
-仪表板 → 提供商 → 连接 Gemini CLI
-→ Google OAuth
-→ 每月 180K completions + 每天 1K
-
-模型：
-  gc/gemini-3-flash-preview
-  gc/gemini-2.5-pro
-```
-
-**最佳价值：** 巨大的免费额度！在付费层级之前使用。
-
-### GitHub Copilot
-
-```bash
-仪表板 → 提供商 → 连接 GitHub
-→ 通过 GitHub OAuth
-→ 每月重置（每月 1 日）
-
-模型：
-  gh/gpt-5
-  gh/claude-4.5-sonnet
-  gh/gemini-3-pro
-```
-
-</details>
-
-<details>
-<summary><b>🔑 API Key 提供商</b></summary>
-
-### NVIDIA NIM（免费 1000 积分！）
-
-1. 注册：[build.nvidia.com](https://build.nvidia.com)
-2. 获取免费 API key（包含 1000 推理积分）
-3. 仪表板 → 添加提供商 → NVIDIA NIM：
-   - API Key：`nvapi-your-key`
-
-**模型：** `nvidia/llama-3.3-70b-instruct`、`nvidia/mistral-7b-instruct` 及 50+ 更多
-
-**专业建议：** OpenAI 兼容的 API — 与 OmniRoute 的格式转换完美配合！
-
-### DeepSeek
-
-1. 注册：[platform.deepseek.com](https://platform.deepseek.com)
-2. 获取 API key
-3. 仪表板 → 添加提供商 → DeepSeek
-
-**模型：** `deepseek/deepseek-chat`、`deepseek/deepseek-coder`
-
-### Groq（免费层可用！）
-
-1. 注册：[console.groq.com](https://console.groq.com)
-2. 获取 API key（包含免费层）
-3. 仪表板 → 添加提供商 → Groq
-
-**模型：** `groq/llama-3.3-70b`、`groq/mixtral-8x7b`
-
-**专业建议：** 超快推理 — 最适合实时编程！
-
-### OpenRouter（100+ 模型）
-
-1. 注册：[openrouter.ai](https://openrouter.ai)
-2. 获取 API key
-3. 仪表板 → 添加提供商 → OpenRouter
-
-**模型：** 通过一个 API key 访问所有主要提供商的 100+ 模型。
-
-</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：
-   - 提供商：`glm`
-   - API Key：`your-key`
-
-**使用：** `glm/glm-4.7`
-
-**专业建议：** Coding Plan 以 1/7 的价格提供 3 倍配额！每日 10:00 AM 重置。
-
-### MiniMax M2.1（5 小时重置，$0.20/1M）
-
-1. 注册：[MiniMax](https://www.minimax.io/)
-2. 获取 API key
-3. 仪表板 → 添加 API Key
-
-**使用：** `minimax/MiniMax-M2.1`
-
-**专业建议：** 长上下文（1M Token）最便宜的选项！
-
-### Kimi K2（$9/月固定）
-
-1. 订阅：[Moonshot AI](https://platform.moonshot.ai/)
-2. 获取 API key
-3. 仪表板 → 添加 API Key
-
-**使用：** `kimi/kimi-latest`
-
-**专业建议：** 固定 $9/月 10M Token = $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：最大化订阅 → 便宜备用
-
-```
-仪表板 → 组合 → 创建新的
-
-名称：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
-```
-
-### 示例 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
-
-```
-设置 → 模型 → 高级：
-  OpenAI API Base URL: http://localhost:20128/v1
-  OpenAI API Key: [从 OmniRoute 仪表板获取]
-  Model: cc/claude-opus-4-6
-```
-
-### Claude Code
-
-使用仪表板中的 **CLI Tools** 页面一键配置，或手动编辑 `~/.claude/settings.json`。
-
-### Codex CLI
-
-```bash
-export OPENAI_BASE_URL="http://localhost:20128"
-export OPENAI_API_KEY="your-omniroute-api-key"
-
-codex "your prompt"
-```
-
-### OpenClaw
-
-**选项 1 — 仪表板（推荐）：**
-
-```
-仪表板 → CLI Tools → OpenClaw → 选择模型 → 应用
-```
-
-**选项 2 — 手动：** 编辑 `~/.openclaw/openclaw.json`：
-
-```json
-{
-  "models": {
-    "providers": {
-      "omniroute": {
-        "baseUrl": "http://127.0.0.1:20128/v1",
-        "apiKey": "sk_omniroute",
-        "api": "openai-completions"
-      }
-    }
-  }
-}
-```
-
-> **注意：** OpenClaw 仅支持本地 OmniRoute。使用 `127.0.0.1` 而非 `localhost` 以避免 IPv6 解析问题。
-
-### Cline / Continue / RooCode
-
-```
-设置 → API 配置：
-  提供商：OpenAI Compatible
-  Base URL: http://localhost:20128/v1
-  API Key: [从 OmniRoute 仪表板获取]
-  Model: if/kimi-k2-thinking
-```
-
-</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`
-
-**NVIDIA NIM (`nvidia/`)** - 免费积分:
-
-- `nvidia/llama-3.3-70b-instruct`
-- `nvidia/mistral-7b-instruct`
-- 50+ 更多模型在 [build.nvidia.com](https://build.nvidia.com)
-
-**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`
-- `if/glm-4.7`
-- `if/minimax-m2`
-
-**Qwen (`qw/`)** - 免费:
-
-- `qw/qwen3-coder-plus`
-- `qw/qwen3-coder-flash`
-
-**Kiro (`kr/`)** - 免费:
-
-- `kr/claude-sonnet-4.5`
-- `kr/claude-haiku-4.5`
-
-**OpenRouter (`or/`)** - 100+ 模型:
-
-- `or/anthropic/claude-4-sonnet`
-- `or/google/gemini-2.5-pro`
-- [openrouter.ai/models](https://openrouter.ai/models) 上的任何模型
-
-</details>
-
----
-
-## 🧪 评估 (Evals)
-
-OmniRoute 包含内置评估框架，用于针对黄金集测试 LLM 响应质量。通过仪表板中的 **Analytics → Evals** 访问。
-
-### 内置黄金集
-
-预加载的「OmniRoute Golden Set」包含 10 个测试用例：
-
-- 问候、数学、地理、代码生成
-- JSON 格式合规性、翻译、markdown
-- 安全拒绝（有害内容）、计数、布尔逻辑
-
-### 评估策略
-
-| 策略       | 描述                             | 示例                             |
-| ---------- | -------------------------------- | -------------------------------- |
-| `exact`    | 输出必须完全匹配                 | `"4"`                            |
-| `contains` | 输出必须包含子串（不区分大小写） | `"Paris"`                        |
-| `regex`    | 输出必须匹配正则表达式模式       | `"1.*2.*3"`                      |
-| `custom`   | 自定义 JS 函数返回 true/false    | `(output) => output.length > 10` |
-
----
-
-## 🐛 故障排除
-
-<details>
-<summary><b>点击展开故障排除指南</b></summary>
-
-**"Language model did not provide messages"**
-
-- 提供商配额已耗尽 → 检查仪表板配额追踪器
-- 解决方案：使用组合故障转移或切换到更便宜的层级
-
-**速率限制**
-
-- 订阅配额耗尽 → 回退到 GLM/MiniMax
-- 添加组合：`cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-
-**OAuth 令牌过期**
-
-- OmniRoute 自动刷新
-- 如果问题持续：仪表板 → 提供商 → 重新连接
-
-**高成本**
-
-- 在仪表板 → 成本中检查使用统计
-- 将主要模型切换为 GLM/MiniMax
-- 对非关键任务使用免费层（Gemini CLI、iFlow）
-
-**仪表板在错误端口打开**
-
-- 设置 `PORT=20128` 和 `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
-
-**Cloud sync 错误**
-
-- 验证 `BASE_URL` 指向您正在运行的实例
-- 验证 `CLOUD_URL` 指向预期的云端点
-- 保持 `NEXT_PUBLIC_*` 值与服务器端值一致
-
-**首次登录不工作**
-
-- 检查 `.env` 中的 `INITIAL_PASSWORD`
-- 如未设置，默认密码为 `123456`
-
-**没有请求日志**
-
-- 在 `.env` 中设置 `ENABLE_REQUEST_LOGS=true`
-
-**兼容 OpenAI 的提供商连接测试显示 "Invalid"**
-
-- 许多提供商不暴露 `/models` 端点
-- OmniRoute v1.0.6+ 包含通过 chat completions 的回退验证
-- 确保 base URL 包含 `/v1` 后缀
-
-</details>
-
----
-
-## 🛠️ 技术栈
-
-- **运行时**: Node.js 20+
-- **语言**: TypeScript 5.9 — `src/` 和 `open-sse/` 中 **100% TypeScript**（v1.0.6）
-- **框架**: Next.js 16 + React 19 + Tailwind CSS 4
-- **数据库**: LowDB (JSON) + SQLite（领域状态 + 代理日志）
-- **流式传输**: Server-Sent Events (SSE)
-- **认证**: OAuth 2.0 (PKCE) + JWT + API Keys
-- **测试**: Node.js test runner（368+ 单元测试）
-- **CI/CD**: GitHub Actions（发布时自动 npm 发布 + Docker Hub）
-- **网站**: [omniroute.online](https://omniroute.online)
-- **包**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **弹性**: 断路器、指数退避、反惊群、TLS 伪装
-
----
-
-## 📖 文档
-
-| 文档                                | 描述                         |
-| ----------------------------------- | ---------------------------- |
-| [用户指南](docs/USER_GUIDE.md)      | 提供商、组合、CLI 集成、部署 |
-| [API 参考](docs/API_REFERENCE.md)   | 所有端点及示例               |
-| [故障排除](docs/TROUBLESHOOTING.md) | 常见问题和解决方案           |
-| [架构](docs/ARCHITECTURE.md)        | 系统架构和内部机制           |
-| [贡献指南](CONTRIBUTING.md)         | 开发设置和指南               |
-| [OpenAPI 规范](docs/openapi.yaml)   | OpenAPI 3.0 规范             |
-| [安全策略](SECURITY.md)             | 漏洞报告和安全实践           |
-
----
-
-## 📧 支持
-
-> 💬 **加入我们的社区！** [WhatsApp 群组](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — 获取帮助、分享技巧、了解最新动态。
-
-- **网站**: [omniroute.online](https://omniroute.online)
-- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **WhatsApp**: [社区群组](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **原始项目**: [decolua 的 9router](https://github.com/decolua/9router)
-
----
-
-## 👥 贡献者
-
-[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-
-### 如何贡献
-
-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
-
-详细指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
-
-### 发布新版本
-
-```bash
-# 创建发布 — npm 发布自动完成
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
-```
-
----
-
-## 📊 Star 历史
-
-<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
- </picture>
-</a>
-
----
-
-## 🙏 致谢
-
-特别感谢 **[decolua](https://github.com/decolua)** 的 **[9router](https://github.com/decolua/9router)** — 启发了本 fork 的原始项目。OmniRoute 在这个令人难以置信的基础上添加了额外功能、多模态 API 和完整的 TypeScript 重写。
-
-特别感谢 **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — 启发了本 JavaScript 移植的原始 Go 实现。
-
----
-
-## 📄 许可证
-
-MIT 许可证 — 详见 [LICENSE](LICENSE)。
-
----
-
-<div align="center">
-  <sub>用 ❤️ 为 24/7 编程的开发者打造</sub>
-  <br/>
-  <sub><a href="https://omniroute.online">omniroute.online</a></sub>
-</div>

SECURITY.md

@@ -20,9 +20,9 @@ If you discover a security vulnerability in OmniRoute, please report it responsi
 
 | Version | Support Status |
 | ------- | -------------- |
-| 1.0.x   | ✅ Active      |
-| 0.8.x   | ✅ Security    |
-| < 0.8.0 | ❌ Unsupported |
+| 3.4.x   | ✅ Active      |
+| 3.0.x   | ✅ Security    |
+| < 3.0.0 | ❌ Unsupported |
 
 ---
 
@@ -43,6 +43,7 @@ Request → CORS → API Key Auth → Prompt Injection Guard → Input Sanitizer
 | **OAuth 2.0 + PKCE** | Secure provider auth (Claude, Codex, Gemini, Cursor, etc.) |
 | **Token Refresh**    | Automatic OAuth token refresh before expiry                |
 | **Secure Cookies**   | `AUTH_COOKIE_SECURE=true` for HTTPS environments           |
+| **MCP Scopes**       | 10 granular scopes for MCP tool access control             |
 
 ### 🛡️ Encryption at Rest
 
@@ -98,9 +99,11 @@ PII_REDACTION_ENABLED=true
 | Feature                  | Description                                                      |
 | ------------------------ | ---------------------------------------------------------------- |
 | **CORS**                 | Configurable origin control (`CORS_ORIGIN` env var, default `*`) |
-| **IP Filtering**         | Whitelist/blacklist IP ranges in dashboard                       |
+| **IP Filtering**         | Allowlist/blocklist IP ranges in dashboard                       |
 | **Rate Limiting**        | Per-provider rate limits with automatic backoff                  |
 | **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s           |
+| **TLS Fingerprint**      | Browser-like TLS fingerprint spoofing to reduce bot detection    |
+| **CLI Fingerprint**      | Per-provider header/body ordering to match native CLI signatures |
 
 ### 🔌 Resilience & Availability
 
@@ -113,11 +116,13 @@ PII_REDACTION_ENABLED=true
 
 ### 📋 Compliance
 
-| Feature            | Description                                         |
-| ------------------ | --------------------------------------------------- |
-| **Log Retention**  | Automatic cleanup after `LOG_RETENTION_DAYS`        |
-| **No-Log Opt-out** | Per API key `noLog` flag disables request logging   |
-| **Audit Log**      | Administrative actions tracked in `audit_log` table |
+| Feature            | Description                                                 |
+| ------------------ | ----------------------------------------------------------- |
+| **Log Retention**  | Automatic cleanup after `CALL_LOG_RETENTION_DAYS`           |
+| **No-Log Opt-out** | Per API key `noLog` flag disables request logging           |
+| **Audit Log**      | Administrative actions tracked in `audit_log` table         |
+| **MCP Audit**      | SQLite-backed audit logging for all MCP tool calls          |
+| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load |
 
 ---
 
@@ -167,3 +172,4 @@ docker run -d \
 - Keep dependencies updated
 - The project uses `husky` + `lint-staged` for pre-commit checks
 - CI pipeline runs ESLint security rules on every push
+- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`)

bin/mcp-server.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT = join(__dirname, "..");
+
+function resolveMcpEntry(rootDir = ROOT) {
+  const candidates = [
+    // Preferred distributable JS entry (npm publish artifact)
+    join(rootDir, "app", "open-sse", "mcp-server", "server.js"),
+    // Local workspace TypeScript source fallback
+    join(rootDir, "open-sse", "mcp-server", "server.ts"),
+  ];
+
+  for (const entry of candidates) {
+    if (existsSync(entry)) return entry;
+  }
+  return null;
+}
+
+function formatSpawnError(exitCode, signal) {
+  if (signal) return `MCP server exited by signal ${signal}`;
+  return `MCP server exited with code ${exitCode ?? 1}`;
+}
+
+export async function startMcpCli(rootDir = ROOT) {
+  const mcpEntry = resolveMcpEntry(rootDir);
+  if (!mcpEntry) {
+    throw new Error(
+      "MCP server entrypoint not found. Expected app/open-sse/mcp-server/server.js or open-sse/mcp-server/server.ts."
+    );
+  }
+
+  // `tsx` loader is only required for local `.ts` fallback; JS entry works without it.
+  const loaderArgs = mcpEntry.endsWith(".ts") ? ["--import", "tsx/esm"] : [];
+
+  await new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [...loaderArgs, mcpEntry], {
+      cwd: rootDir,
+      env: process.env,
+      stdio: "inherit",
+    });
+
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if ((code ?? 0) === 0 && !signal) {
+        resolve(undefined);
+        return;
+      }
+      reject(new Error(formatSpawnError(code, signal)));
+    });
+  });
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  startMcpCli().catch((err) => {
+    console.error("\x1b[31m✖ Failed to start MCP server:\x1b[0m", err?.message || err);
+    process.exit(1);
+  });
+}

bin/omniroute.mjs

@@ -7,20 +7,76 @@
  *   omniroute              Start the server (default port 20128)
  *   omniroute --port 3000  Start on custom port
  *   omniroute --no-open    Start without opening browser
+ *   omniroute --mcp        Start MCP server (stdio transport for IDEs)
  *   omniroute --help       Show help
  *   omniroute --version    Show version
  */
 
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { homedir, platform } from "node:os";
+import { isNativeBinaryCompatible } from "../scripts/native-binary-compat.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const ROOT = join(__dirname, "..");
 const APP_DIR = join(ROOT, "app");
 
+// ── Load .env file (for global npm install) ─────────────────
+function loadEnvFile() {
+  const envPaths = [];
+
+  // 1. DATA_DIR/.env if set
+  if (process.env.DATA_DIR) {
+    envPaths.push(join(process.env.DATA_DIR, ".env"));
+  }
+
+  // 2. ~/.omniroute/.env (default data dir)
+  const home = homedir();
+  if (home) {
+    if (platform() === "win32") {
+      const appData = process.env.APPDATA || join(home, "AppData", "Roaming");
+      envPaths.push(join(appData, "omniroute", ".env"));
+    } else {
+      envPaths.push(join(home, ".omniroute", ".env"));
+    }
+  }
+
+  // 3. ./.env (current working directory)
+  envPaths.push(join(process.cwd(), ".env"));
+
+  for (const envPath of envPaths) {
+    try {
+      if (existsSync(envPath)) {
+        const content = readFileSync(envPath, "utf-8");
+        for (const line of content.split("\n")) {
+          const trimmed = line.trim();
+          // Skip empty lines and comments
+          if (!trimmed || trimmed.startsWith("#")) continue;
+          const eqIdx = trimmed.indexOf("=");
+          if (eqIdx > 0) {
+            const key = trimmed.slice(0, eqIdx).trim();
+            const value = trimmed.slice(eqIdx + 1).trim();
+            // Don't override existing env vars
+            if (process.env[key] === undefined) {
+              // Remove surrounding quotes
+              process.env[key] = value.replace(/^["']|["']$/g, "");
+            }
+          }
+        }
+        console.log(`  \x1b[2m📋 Loaded env from ${envPath}\x1b[0m`);
+        return;
+      }
+    } catch {
+      // Ignore errors reading env files
+    }
+  }
+}
+
+loadEnvFile();
+
 // ── Parse args ─────────────────────────────────────────────
 const args = process.argv.slice(2);
 
@@ -30,55 +86,86 @@ if (args.includes("--help") || args.includes("-h")) {
 
   \x1b[1mUsage:\x1b[0m
     omniroute                 Start the server
-    omniroute --port <port>   Use custom port (default: 20128)
+    omniroute --port <port>   Use custom API port (default: 20128)
     omniroute --no-open       Don't open browser automatically
+    omniroute --mcp           Start MCP server (stdio transport for IDEs)
     omniroute --help          Show this help
     omniroute --version       Show version
 
+  \x1b[1mMCP Integration:\x1b[0m
+    The --mcp flag starts an MCP server over stdio, exposing OmniRoute
+    tools for AI agents in VS Code, Cursor, Claude Desktop, and Copilot.
+
+    Available tools: omniroute_get_health, omniroute_list_combos,
+    omniroute_check_quota, omniroute_route_request, and more.
+
+  \x1b[1mConfig:\x1b[0m
+    Loads .env from: ~/.omniroute/.env or ./.env
+    Memory limit: OMNIROUTE_MEMORY_MB (default: 512)
+
   \x1b[1mAfter starting:\x1b[0m
-    Dashboard:  http://localhost:<port>
-    API:        http://localhost:<port>/v1
+    Dashboard:  http://localhost:<dashboard-port>
+    API:        http://localhost:<api-port>/v1
 
   \x1b[1mConnect your tools:\x1b[0m
     Set your CLI tool (Cursor, Cline, Codex, etc.) to use:
-    \x1b[33mhttp://localhost:20128/v1\x1b[0m
+    \x1b[33mhttp://localhost:<api-port>/v1\x1b[0m
   `);
   process.exit(0);
 }
 
 if (args.includes("--version") || args.includes("-v")) {
   try {
-    const pkg = await import(join(ROOT, "package.json"), {
-      with: { type: "json" },
-    });
-    console.log(pkg.default.version);
+    const { version } = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+    console.log(version);
   } catch {
     console.log("unknown");
   }
   process.exit(0);
 }
 
-// Parse --port
-let port = 20128;
+// ── MCP Server Mode ───────────────────────────────────────
+if (args.includes("--mcp")) {
+  try {
+    const { startMcpCli } = await import(join(ROOT, "bin", "mcp-server.mjs"));
+    await startMcpCli(ROOT);
+  } catch (err) {
+    console.error("\x1b[31m✖ Failed to start MCP server:\x1b[0m", err.message || err);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+function parsePort(value, fallback) {
+  const parsed = parseInt(String(value), 10);
+  return Number.isFinite(parsed) && parsed > 0 && parsed <= 65535 ? parsed : fallback;
+}
+
+// Parse --port (canonical/base port)
+let port = parsePort(process.env.PORT || "20128", 20128);
 const portIdx = args.indexOf("--port");
 if (portIdx !== -1 && args[portIdx + 1]) {
-  port = parseInt(args[portIdx + 1], 10);
-  if (isNaN(port)) {
+  const cliPort = parsePort(args[portIdx + 1], null);
+  if (cliPort === null) {
     console.error("\x1b[31m✖ Invalid port number\x1b[0m");
     process.exit(1);
   }
+  port = cliPort;
 }
 
+const apiPort = parsePort(process.env.API_PORT || String(port), port);
+const dashboardPort = parsePort(process.env.DASHBOARD_PORT || String(port), port);
+
 const noOpen = args.includes("--no-open");
 
 // ── Banner ─────────────────────────────────────────────────
 console.log(`
 \x1b[36m   ____                  _ ____              _
-  / __ \\                (_) __ \\            | |
- | |  | |_ __ ___  _ __ _| |__) |___  _   _| |_ ___
- | |  | | '_ \` _ \\| '_ \\ |  _  // _ \\| | | | __/ _ \\
- | |__| | | | | | | | | | | | \\ \\ (_) | |_| | ||  __/
-  \\____/|_| |_| |_|_| |_|_|_|  \\_\\___/ \\__,_|\\__\\___|
+   / __ \\                (_) __ \\            | |
+  | |  | |_ __ ___  _ __ _| |__) |___  _   _| |_ ___
+  | |  | | '_ \` _ \\| '_ \\ |  _  // _ \\| | | | __/ _ \\
+  | |__| | | | | | | | | | | | \\ \\ (_) | |_| | ||  __/
+   \\____/|_| |_| |_|_| |_|_|_|  \\_\\___/ \\__,_|\\__\\___|
 \x1b[0m`);
 
 // ── Node.js version check ──────────────────────────────────
@@ -100,22 +187,73 @@ const serverJs = join(APP_DIR, "server.js");
 
 if (!existsSync(serverJs)) {
   console.error("\x1b[31m✖ Server not found at:\x1b[0m", serverJs);
-  console.error("  This usually means the package was not built correctly.");
-  console.error("  Try reinstalling: npm install -g omniroute");
+  console.error("  The package may not have been built correctly.");
+  console.error("");
+  // (#492) Detect common non-standard Node managers that cause this issue
+  const nodeExec = process.execPath || "";
+  const isMise = nodeExec.includes("mise") || nodeExec.includes(".local/share/mise");
+  const isNvm = nodeExec.includes(".nvm") || nodeExec.includes("nvm");
+  if (isMise) {
+    console.error(
+      "  \x1b[33m⚠ mise detected:\x1b[0m If you installed via `npm install -g omniroute`,"
+    );
+    console.error("    try: \x1b[36mnpx omniroute@latest\x1b[0m  (downloads a fresh copy)");
+    console.error("    or:  \x1b[36mmise exec -- npx omniroute\x1b[0m");
+  } else if (isNvm) {
+    console.error(
+      "  \x1b[33m⚠ nvm detected:\x1b[0m Try reinstalling after loading the correct Node version:"
+    );
+    console.error("    \x1b[36mnvm use --lts && npm install -g omniroute\x1b[0m");
+  } else {
+    console.error("  Try: \x1b[36mnpm install -g omniroute\x1b[0m  (reinstall)");
+    console.error("  Or:  \x1b[36mnpx omniroute@latest\x1b[0m");
+  }
+  process.exit(1);
+}
+
+// ── Pre-flight: verify better-sqlite3 native binary ───────
+// Verify the binary's actual target platform/arch before trusting dlopen.
+// This avoids the macOS false positive where a bundled linux-x64 addon can
+// appear to load even though the runtime will fail when better-sqlite3 starts.
+const sqliteBinary = join(
+  APP_DIR,
+  "node_modules",
+  "better-sqlite3",
+  "build",
+  "Release",
+  "better_sqlite3.node"
+);
+if (existsSync(sqliteBinary) && !isNativeBinaryCompatible(sqliteBinary)) {
+  console.error(
+    "\x1b[31m✖ better-sqlite3 native module is incompatible with this platform.\x1b[0m"
+  );
+  console.error(`  Run: cd ${APP_DIR} && npm rebuild better-sqlite3`);
+  if (platform() === "darwin") {
+    console.error("  If build tools are missing: xcode-select --install");
+  }
   process.exit(1);
 }
 
 // ── Start server ───────────────────────────────────────────
 console.log(`  \x1b[2m⏳ Starting server...\x1b[0m\n`);
 
+// Sanitize memory limit — parseInt to prevent command injection (#150)
+const rawMemory = parseInt(process.env.OMNIROUTE_MEMORY_MB || "512", 10);
+const memoryLimit =
+  Number.isFinite(rawMemory) && rawMemory >= 64 && rawMemory <= 16384 ? rawMemory : 512;
+
 const env = {
   ...process.env,
-  PORT: String(port),
+  OMNIROUTE_PORT: String(port),
+  PORT: String(dashboardPort),
+  DASHBOARD_PORT: String(dashboardPort),
+  API_PORT: String(apiPort),
   HOSTNAME: "0.0.0.0",
   NODE_ENV: "production",
+  NODE_OPTIONS: `--max-old-space-size=${memoryLimit}`,
 };
 
-const server = spawn("node", [serverJs], {
+const server = spawn("node", [`--max-old-space-size=${memoryLimit}`, serverJs], {
   cwd: APP_DIR,
   env,
   stdio: "pipe",
@@ -168,16 +306,17 @@ process.on("SIGTERM", shutdown);
 
 // ── On ready ───────────────────────────────────────────────
 async function onReady() {
-  const url = `http://localhost:${port}`;
+  const dashboardUrl = `http://localhost:${dashboardPort}`;
+  const apiUrl = `http://localhost:${apiPort}`;
 
   console.log(`
   \x1b[32m✔ OmniRoute is running!\x1b[0m
 
-  \x1b[1m  Dashboard:\x1b[0m  ${url}
-  \x1b[1m  API Base:\x1b[0m   ${url}/v1
+  \x1b[1m  Dashboard:\x1b[0m  ${dashboardUrl}
+  \x1b[1m  API Base:\x1b[0m   ${apiUrl}/v1
 
   \x1b[2m  Point your CLI tool (Cursor, Cline, Codex) to:\x1b[0m
-  \x1b[33m  ${url}/v1\x1b[0m
+  \x1b[33m  ${apiUrl}/v1\x1b[0m
 
   \x1b[2m  Press Ctrl+C to stop\x1b[0m
   `);
@@ -185,7 +324,7 @@ async function onReady() {
   if (!noOpen) {
     try {
       const open = await import("open");
-      await open.default(url);
+      await open.default(dashboardUrl);
     } catch {
       // open is optional — if not available, just skip
     }

bin/reset-password.mjs

@@ -17,7 +17,7 @@ import { createInterface } from "node:readline";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
-import { createHash } from "node:crypto";
+import bcrypt from "bcryptjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -34,8 +34,10 @@ function ask(question) {
   return new Promise((resolve) => rl.question(question, resolve));
 }
 
-function hashPassword(password) {
-  return createHash("sha256").update(password).digest("hex");
+function generateSecretDigest(input) {
+  // Use bcrypt with a salt round of 10 to match login/route.ts expectations
+  // and resolve CodeQL js/insufficient-password-hash warning.
+  return bcrypt.hashSync(input, 10);
 }
 
 console.log("\n🔑 OmniRoute — Password Reset\n");
@@ -86,7 +88,7 @@ async function main() {
     process.exit(1);
   }
 
-  const hashed = hashPassword(password);
+  const hashed = generateSecretDigest(password);
 
   // Upsert the password
   const stmt = db.prepare(`

docker-compose.prod.yml

@@ -16,27 +16,26 @@ services:
     container_name: omniroute-prod
     build:
       context: .
-      target: runner-base
+      target: runner-cli
     image: omniroute:prod
     restart: unless-stopped
+    stop_grace_period: 40s
     env_file: .env
     environment:
       - NODE_ENV=production
-      - PORT=20128
+      - PORT=${PORT:-20128}
+      - DASHBOARD_PORT=${DASHBOARD_PORT:-${PORT:-20128}}
+      - API_PORT=${API_PORT:-20129}
+      - API_HOST=${API_HOST:-0.0.0.0}
       - HOSTNAME=0.0.0.0
       - DATA_DIR=/app/data
     ports:
-      - "20130:20128"
+      - "${PROD_DASHBOARD_PORT:-20130}:${DASHBOARD_PORT:-${PORT:-20128}}"
+      - "${PROD_API_PORT:-20131}:${API_PORT:-20129}"
     volumes:
       - omniroute-prod-data:/app/data
     healthcheck:
-      test:
-        [
-          "CMD",
-          "node",
-          "-e",
-          "fetch('http://127.0.0.1:20128/api/settings').then(r=>{if(!r.ok)throw r.status}).catch(()=>process.exit(1))",
-        ]
+      test: ["CMD", "node", "healthcheck.mjs"]
       interval: 30s
       timeout: 5s
       retries: 3

docker-compose.yml

@@ -6,11 +6,14 @@
 #    base  → minimal image, no CLI tools
 #    cli   → CLIs installed inside the container (portable)
 #    host  → runner-base + host-mounted CLI binaries (Linux-first)
+#    cliproxyapi → CLIProxyAPI sidecar on port 8317
 #
 #  Usage:
 #    docker compose --profile base up -d
 #    docker compose --profile cli up -d
 #    docker compose --profile host up -d
+#    docker compose --profile cliproxyapi up -d
+#    docker compose --profile cli --profile cliproxyapi up -d
 #
 #  Before first run, copy .env.example → .env and edit your secrets.
 # ──────────────────────────────────────────────────────────────────────
@@ -20,16 +23,14 @@ x-common: &common
   env_file: .env
   environment:
     - DATA_DIR=/app/data # Must match the volume mount below
+    - PORT=${PORT:-20128}
+    - DASHBOARD_PORT=${DASHBOARD_PORT:-${PORT:-20128}}
+    - API_PORT=${API_PORT:-20129}
+    - API_HOST=${API_HOST:-0.0.0.0}
   volumes:
     - omniroute-data:/app/data
   healthcheck:
-    test:
-      [
-        "CMD",
-        "node",
-        "-e",
-        "fetch('http://127.0.0.1:20128/api/settings').then(r=>{if(!r.ok)throw r.status}).catch(()=>process.exit(1))",
-      ]
+    test: ["CMD", "node", "healthcheck.mjs"]
     interval: 30s
     timeout: 5s
     retries: 3
@@ -45,7 +46,8 @@ services:
       target: runner-base
     image: omniroute:base
     ports:
-      - "${PORT:-20128}:20128"
+      - "${DASHBOARD_PORT:-${PORT:-20128}}:${DASHBOARD_PORT:-${PORT:-20128}}"
+      - "${API_PORT:-20129}:${API_PORT:-20129}"
     profiles:
       - base
 
@@ -58,7 +60,13 @@ services:
       target: runner-cli
     image: omniroute:cli
     ports:
-      - "${PORT:-20128}:20128"
+      - "${DASHBOARD_PORT:-${PORT:-20128}}:${DASHBOARD_PORT:-${PORT:-20128}}"
+      - "${API_PORT:-20129}:${API_PORT:-20129}"
+    volumes:
+      - omniroute-data:/app/data
+      - /var/run/docker.sock:/var/run/docker.sock
+      - /usr/libexec/docker/cli-plugins:/usr/libexec/docker/cli-plugins:ro
+      - ${AUTO_UPDATE_HOST_REPO_DIR:-.}:/workspace/omniroute:rw
     profiles:
       - cli
 
@@ -71,8 +79,14 @@ services:
       target: runner-base
     image: omniroute:base
     ports:
-      - "${PORT:-20128}:20128"
+      - "${DASHBOARD_PORT:-${PORT:-20128}}:${DASHBOARD_PORT:-${PORT:-20128}}"
+      - "${API_PORT:-20129}:${API_PORT:-20129}"
     environment:
+      - DATA_DIR=/app/data
+      - PORT=${PORT:-20128}
+      - DASHBOARD_PORT=${DASHBOARD_PORT:-${PORT:-20128}}
+      - API_PORT=${API_PORT:-20129}
+      - API_HOST=${API_HOST:-0.0.0.0}
       - CLI_MODE=host
       - CLI_EXTRA_PATHS=/host-local/bin:/host-node/bin
       - CLI_CONFIG_HOME=/host-home
@@ -98,6 +112,30 @@ services:
     profiles:
       - host
 
+  # ── Profile: cliproxyapi (CLIProxyAPI as sidecar) ─────────────────
+  cliproxyapi:
+    container_name: cliproxyapi
+    image: ghcr.io/router-for-me/cliproxyapi:v6.9.7
+    restart: unless-stopped
+    ports:
+      - "${CLIPROXYAPI_PORT:-8317}:${CLIPROXYAPI_PORT:-8317}"
+    volumes:
+      - cliproxyapi-data:/root/.cli-proxy-api
+    environment:
+      - PORT=${CLIPROXYAPI_PORT:-8317}
+      - HOST=0.0.0.0
+    healthcheck:
+      test:
+        ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:${CLIPROXYAPI_PORT:-8317}/v1/models"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    profiles:
+      - cliproxyapi
+
 volumes:
   omniroute-data:
     name: omniroute-data
+  cliproxyapi-data:
+    name: cliproxyapi-data

docs/A2A-SERVER.md

@@ -0,0 +1,196 @@
+# OmniRoute A2A Server Documentation
+
+> Agent-to-Agent Protocol v0.3 — OmniRoute as an intelligent routing agent
+
+## Agent Discovery
+
+```bash
+curl http://localhost:20128/.well-known/agent.json
+```
+
+Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements.
+
+---
+
+## Authentication
+
+All `/a2a` requests require an API key via the `Authorization` header:
+
+```
+Authorization: Bearer YOUR_OMNIROUTE_API_KEY
+```
+
+If no API key is configured on the server, authentication is bypassed.
+
+---
+
+## JSON-RPC 2.0 Methods
+
+### `message/send` — Synchronous Execution
+
+Sends a message to a skill and waits for the complete response.
+
+```bash
+curl -X POST http://localhost:20128/a2a \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_KEY" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "message/send",
+    "params": {
+      "skill": "smart-routing",
+      "messages": [{"role": "user", "content": "Write a hello world in Python"}],
+      "metadata": {"model": "auto", "combo": "fast-coding"}
+    }
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "result": {
+    "task": { "id": "uuid", "state": "completed" },
+    "artifacts": [{ "type": "text", "content": "..." }],
+    "metadata": {
+      "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)",
+      "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" },
+      "resilience_trace": [
+        { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." }
+      ],
+      "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" }
+    }
+  }
+}
+```
+
+### `message/stream` — SSE Streaming
+
+Same as `message/send` but returns Server-Sent Events for real-time streaming.
+
+```bash
+curl -N -X POST http://localhost:20128/a2a \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_KEY" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "message/stream",
+    "params": {
+      "skill": "smart-routing",
+      "messages": [{"role": "user", "content": "Explain quantum computing"}]
+    }
+  }'
+```
+
+**SSE Events:**
+
+```
+data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}}
+
+: heartbeat 2026-03-03T17:00:00Z
+
+data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}}
+```
+
+### `tasks/get` — Query Task Status
+
+```bash
+curl -X POST http://localhost:20128/a2a \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_KEY" \
+  -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}'
+```
+
+### `tasks/cancel` — Cancel a Task
+
+```bash
+curl -X POST http://localhost:20128/a2a \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_KEY" \
+  -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}'
+```
+
+---
+
+## Available Skills
+
+| Skill              | Description                                                                                                                     |
+| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ |
+| `smart-routing`    | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. |
+| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings.                      |
+
+---
+
+## Task Lifecycle
+
+```
+submitted → working → completed
+                    → failed
+                    → cancelled
+```
+
+- Tasks expire after 5 minutes (configurable)
+- Terminal states: `completed`, `failed`, `cancelled`
+- Event log tracks every state transition
+
+---
+
+## Error Codes
+
+| Code   | Meaning                        |
+| :----- | :----------------------------- |
+| -32700 | Parse error (invalid JSON)     |
+| -32600 | Invalid request / Unauthorized |
+| -32601 | Method or skill not found      |
+| -32602 | Invalid params                 |
+| -32603 | Internal error                 |
+
+---
+
+## Integration Examples
+
+### Python (requests)
+
+```python
+import requests
+
+resp = requests.post("http://localhost:20128/a2a", json={
+    "jsonrpc": "2.0", "id": "1",
+    "method": "message/send",
+    "params": {
+        "skill": "smart-routing",
+        "messages": [{"role": "user", "content": "Hello"}]
+    }
+}, headers={"Authorization": "Bearer YOUR_KEY"})
+
+result = resp.json()["result"]
+print(result["artifacts"][0]["content"])
+print(result["metadata"]["routing_explanation"])
+```
+
+### TypeScript (fetch)
+
+```typescript
+const resp = await fetch("http://localhost:20128/a2a", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    Authorization: "Bearer YOUR_KEY",
+  },
+  body: JSON.stringify({
+    jsonrpc: "2.0",
+    id: "1",
+    method: "message/send",
+    params: {
+      skill: "smart-routing",
+      messages: [{ role: "user", content: "Hello" }],
+    },
+  }),
+});
+const { result } = await resp.json();
+console.log(result.metadata.routing_explanation);
+```

docs/API_REFERENCE.md

@@ -1,5 +1,7 @@
 # API Reference
 
+🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) | 🇨🇿 [Čeština](i18n/cs/API_REFERENCE.md)
+
 Complete reference for all OmniRoute API endpoints.
 
 ---
@@ -36,15 +38,20 @@ Content-Type: application/json
 
 ### Custom Headers
 
-| Header                   | Direction | Description                       |
-| ------------------------ | --------- | --------------------------------- |
-| `X-OmniRoute-No-Cache`   | Request   | Set to `true` to bypass cache     |
-| `X-OmniRoute-Progress`   | Request   | Set to `true` for progress events |
-| `Idempotency-Key`        | Request   | Dedup key (5s window)             |
-| `X-Request-Id`           | Request   | Alternative dedup key             |
-| `X-OmniRoute-Cache`      | Response  | `HIT` or `MISS` (non-streaming)   |
-| `X-OmniRoute-Idempotent` | Response  | `true` if deduplicated            |
-| `X-OmniRoute-Progress`   | Response  | `enabled` if progress tracking on |
+| Header                   | Direction | Description                                      |
+| ------------------------ | --------- | ------------------------------------------------ |
+| `X-OmniRoute-No-Cache`   | Request   | Set to `true` to bypass cache                    |
+| `X-OmniRoute-Progress`   | Request   | Set to `true` for progress events                |
+| `X-Session-Id`           | Request   | Sticky session key for external session affinity |
+| `x_session_id`           | Request   | Underscore variant also accepted (direct HTTP)   |
+| `Idempotency-Key`        | Request   | Dedup key (5s window)                            |
+| `X-Request-Id`           | Request   | Alternative dedup key                            |
+| `X-OmniRoute-Cache`      | Response  | `HIT` or `MISS` (non-streaming)                  |
+| `X-OmniRoute-Idempotent` | Response  | `true` if deduplicated                           |
+| `X-OmniRoute-Progress`   | Response  | `enabled` if progress tracking on                |
+| `X-OmniRoute-Session-Id` | Response  | Effective session ID used by OmniRoute           |
+
+> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers on;`.
 
 ---
 
@@ -61,7 +68,7 @@ Content-Type: application/json
 }
 ```
 
-Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, **GitHub Models**.
 
 ```bash
 # List all embedding models
@@ -84,7 +91,7 @@ Content-Type: application/json
 }
 ```
 
-Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+Available providers: OpenAI (DALL-E, GPT Image 1), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (local), ComfyUI (local).
 
 ```bash
 # List all image models
@@ -135,10 +142,10 @@ The provider prefix is auto-added if missing. Mismatched models return `400`.
 
 ```bash
 # Get cache stats
-GET /api/cache
+GET /api/cache/stats
 
 # Clear all caches
-DELETE /api/cache
+DELETE /api/cache/stats
 ```
 
 Response example:
@@ -172,15 +179,15 @@ Response example:
 
 ### Provider Management
 
-| Endpoint                     | Method          | Description              |
-| ---------------------------- | --------------- | ------------------------ |
-| `/api/providers`             | GET/POST        | List / create providers  |
-| `/api/providers/[id]`        | GET/PUT/DELETE  | Manage a provider        |
-| `/api/providers/[id]/test`   | POST            | Test provider connection |
-| `/api/providers/[id]/models` | GET             | List provider models     |
-| `/api/providers/validate`    | POST            | Validate provider config |
-| `/api/provider-nodes*`       | Various         | Provider node management |
-| `/api/provider-models`       | GET/POST/DELETE | Custom models            |
+| Endpoint                     | Method                | Description                                    |
+| ---------------------------- | --------------------- | ---------------------------------------------- |
+| `/api/providers`             | GET/POST              | List / create providers                        |
+| `/api/providers/[id]`        | GET/PUT/DELETE        | Manage a provider                              |
+| `/api/providers/[id]/test`   | POST                  | Test provider connection                       |
+| `/api/providers/[id]/models` | GET                   | List provider models                           |
+| `/api/providers/validate`    | POST                  | Validate provider config                       |
+| `/api/provider-nodes*`       | Various               | Provider node management                       |
+| `/api/provider-models`       | GET/POST/PATCH/DELETE | Custom models (add, update, hide/show, delete) |
 
 ### OAuth Flows
 
@@ -209,23 +216,23 @@ Response example:
 
 ### Settings
 
-| Endpoint                        | Method  | Description            |
-| ------------------------------- | ------- | ---------------------- |
-| `/api/settings`                 | GET/PUT | General settings       |
-| `/api/settings/proxy`           | GET/PUT | Network proxy config   |
-| `/api/settings/proxy/test`      | POST    | Test proxy connection  |
-| `/api/settings/ip-filter`       | GET/PUT | IP allowlist/blocklist |
-| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget |
-| `/api/settings/system-prompt`   | GET/PUT | Global system prompt   |
+| Endpoint                        | Method        | Description            |
+| ------------------------------- | ------------- | ---------------------- |
+| `/api/settings`                 | GET/PUT/PATCH | General settings       |
+| `/api/settings/proxy`           | GET/PUT       | Network proxy config   |
+| `/api/settings/proxy/test`      | POST          | Test proxy connection  |
+| `/api/settings/ip-filter`       | GET/PUT       | IP allowlist/blocklist |
+| `/api/settings/thinking-budget` | GET/PUT       | Reasoning token budget |
+| `/api/settings/system-prompt`   | GET/PUT       | Global system prompt   |
 
 ### Monitoring
 
-| Endpoint                 | Method     | Description             |
-| ------------------------ | ---------- | ----------------------- |
-| `/api/sessions`          | GET        | Active session tracking |
-| `/api/rate-limits`       | GET        | Per-account rate limits |
-| `/api/monitoring/health` | GET        | Health check            |
-| `/api/cache`             | GET/DELETE | Cache stats / clear     |
+| Endpoint                 | Method     | Description                                                                                          |
+| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------- |
+| `/api/sessions`          | GET        | Active session tracking                                                                              |
+| `/api/rate-limits`       | GET        | Per-account rate limits                                                                              |
+| `/api/monitoring/health` | GET        | Health check + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) |
+| `/api/cache/stats`       | GET/DELETE | Cache stats / clear                                                                                  |
 
 ### Backup & Export/Import
 
@@ -246,6 +253,13 @@ Response example:
 | `/api/sync/initialize` | POST    | Initialize sync       |
 | `/api/cloud/*`         | Various | Cloud management      |
 
+### Tunnels
+
+| Endpoint                   | Method | Description                                                             |
+| -------------------------- | ------ | ----------------------------------------------------------------------- |
+| `/api/tunnels/cloudflared` | GET    | Read Cloudflare Quick Tunnel install/runtime status for the dashboard   |
+| `/api/tunnels/cloudflared` | POST   | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) |
+
 ### CLI Tools
 
 | Endpoint                           | Method | Description         |
@@ -258,14 +272,24 @@ Response example:
 
 CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
 
+### ACP Agents
+
+| Endpoint          | Method | Description                                              |
+| ----------------- | ------ | -------------------------------------------------------- |
+| `/api/acp/agents` | GET    | List all detected agents (built-in + custom) with status |
+| `/api/acp/agents` | POST   | Add custom agent or refresh detection cache              |
+| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param                |
+
+GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom).
+
 ### Resilience & Rate Limits
 
-| Endpoint                | Method  | Description                     |
-| ----------------------- | ------- | ------------------------------- |
-| `/api/resilience`       | GET/PUT | Get/update resilience profiles  |
-| `/api/resilience/reset` | POST    | Reset circuit breakers          |
-| `/api/rate-limits`      | GET     | Per-account rate limit status   |
-| `/api/rate-limit`       | GET     | Global rate limit configuration |
+| Endpoint                | Method    | Description                     |
+| ----------------------- | --------- | ------------------------------- |
+| `/api/resilience`       | GET/PATCH | Get/update resilience profiles  |
+| `/api/resilience/reset` | POST      | Reset circuit breakers          |
+| `/api/rate-limits`      | GET       | Per-account rate limit status   |
+| `/api/rate-limit`       | GET       | Global rate limit configuration |
 
 ### Evals
 

docs/ARCHITECTURE.md

@@ -1,6 +1,8 @@
 # OmniRoute Architecture
 
-_Last updated: 2026-02-18_
+🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) | 🇨🇿 [Čeština](i18n/cs/ARCHITECTURE.md)
+
+_Last updated: 2026-03-28_
 
 ## Executive Summary
 
@@ -32,6 +34,7 @@ Core capabilities:
 - Anti-thundering herd protection with mutex locking
 - Signature-based request deduplication cache
 - Domain layer: model availability, cost rules, fallback policy, lockout policy
+- Context Relay: session handoff summaries for account rotation continuity
 - Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers)
 - Policy engine for centralized request evaluation (lockout → budget → fallback)
 - Request telemetry with p50/p95/p99 latency aggregation
@@ -63,6 +66,26 @@ Primary runtime model:
 - Provider SLA/control plane outside local process
 - External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
 
+## Dashboard Surface (Current)
+
+Main pages under `src/app/(dashboard)/dashboard/`:
+
+- `/dashboard` — quick start + provider overview
+- `/dashboard/endpoint` — endpoint proxy + MCP + A2A + API endpoint tabs
+- `/dashboard/providers` — provider connections and credentials
+- `/dashboard/combos` — combo strategies, templates, model routing rules
+- `/dashboard/costs` — cost aggregation and pricing visibility
+- `/dashboard/analytics` — usage analytics and evaluations
+- `/dashboard/limits` — quota/rate controls
+- `/dashboard/cli-tools` — CLI onboarding, runtime detection, config generation
+- `/dashboard/agents` — detected ACP agents + custom agent registration
+- `/dashboard/media` — image/video/music playground
+- `/dashboard/search-tools` — search provider testing and history
+- `/dashboard/health` — uptime, circuit breakers, rate limits
+- `/dashboard/logs` — request/proxy/audit/console logs
+- `/dashboard/settings` — system settings tabs (general, routing, combo defaults, etc.)
+- `/dashboard/api-manager` — API key lifecycle and model permissions
+
 ## High-Level System Context
 
 ```mermaid
@@ -79,12 +102,12 @@ flowchart LR
         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)]
+        DB[(storage.sqlite)]
+        UDB[(usage tables + log artifacts)]
     end
 
     subgraph Upstreams[Upstream Providers]
-        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity]
+        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/GitHub/Kiro/Cursor/Antigravity]
         P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
         P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
     end
@@ -142,7 +165,7 @@ Management domains:
 - Providers/connections: `src/app/api/providers*`
 - Provider nodes: `src/app/api/provider-nodes*`
 - Custom models: `src/app/api/provider-models` (GET/POST/DELETE)
-- Model catalog: `src/app/api/models/catalog` (GET)
+- Model catalog: `src/app/api/models/route.ts` (GET)
 - Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
 - 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`
@@ -198,6 +221,8 @@ Services (business logic):
 - Wildcard model routing: `open-sse/services/wildcardRouter.ts`
 - Rate limit management: `open-sse/services/rateLimitManager.ts`
 - Circuit breaker: `open-sse/services/circuitBreaker.ts`
+- Context handoff: `open-sse/services/contextHandoff.ts` — handoff summary generation and injection for context-relay strategy
+- Codex quota fetcher: `open-sse/services/codexQuotaFetcher.ts` — fetches Codex quota for context-relay handoff decisions
 
 Domain layer modules:
 
@@ -218,23 +243,24 @@ Domain layer modules:
 OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
 - Registry index: `src/lib/oauth/providers/index.ts`
-- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
+- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `qoder.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
 - Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
 ## 3) Persistence Layer
 
-Primary state DB:
+Primary state DB (SQLite):
 
-- `src/lib/localDb.ts`
-- file: `${DATA_DIR}/db.json` (or `$XDG_CONFIG_HOME/omniroute/db.json` when set, else `~/.omniroute/db.json`)
-- entities: providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
+- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL)
+- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers)
+- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`)
+- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
 
-Usage DB:
+Usage persistence:
 
-- `src/lib/usageDb.ts`
-- files: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
-- follows same base directory policy as `localDb` (`DATA_DIR`, then `XDG_CONFIG_HOME/omniroute` when set)
-- decomposed into focused sub-modules: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts`
+- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`)
+- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
+- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
+- legacy JSON files are migrated to SQLite by startup migrations when present
 
 Domain State DB (SQLite):
 
@@ -251,8 +277,9 @@ Domain State DB (SQLite):
 
 ## 5) Cloud Sync
 
-- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
+- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
 - Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Periodic task: `src/shared/services/modelSyncScheduler.ts`
 - Control route: `src/app/api/sync/cloud/route.ts`
 
 ## Request Lifecycle (`/v1/chat/completions`)
@@ -332,7 +359,7 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics.
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run.
 
 ## OAuth Onboarding and Token Refresh Lifecycle
 
@@ -503,9 +530,9 @@ erDiagram
 
 Physical storage files:
 
-- main state: `${DATA_DIR}/db.json` (or `$XDG_CONFIG_HOME/omniroute/db.json` when set, else `~/.omniroute/db.json`)
-- usage stats: `${DATA_DIR}/usage.json`
-- request log lines: `${DATA_DIR}/log.txt`
+- primary runtime DB: `${DATA_DIR}/storage.sqlite`
+- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact)
+- structured call payload archives: `${DATA_DIR}/call_logs/`
 - optional translator/request debug sessions: `<repo>/logs/...`
 
 ## Deployment Topology
@@ -520,8 +547,8 @@ flowchart LR
     subgraph ContainerOrProcess[OmniRoute Runtime]
         Next[Next.js Server\nPORT=20128]
         Core[SSE Core + Executors]
-        MainDB[(db.json)]
-        UsageDB[(usage.json/log.txt)]
+        MainDB[(storage.sqlite)]
+        UsageDB[(usage tables + log artifacts)]
     end
 
     subgraph External[External Services]
@@ -548,7 +575,7 @@ flowchart LR
 - `src/app/api/providers*`: provider CRUD, validation, testing
 - `src/app/api/provider-nodes*`: custom compatible node management
 - `src/app/api/provider-models`: custom model management (CRUD)
-- `src/app/api/models/catalog`: full model catalog API (all types grouped by provider)
+- `src/app/api/models/route.ts`: model catalog API (aliases + custom models)
 - `src/app/api/oauth/*`: OAuth/device-code flows
 - `src/app/api/keys*`: local API key lifecycle
 - `src/app/api/models/alias`: alias management
@@ -580,8 +607,9 @@ flowchart LR
 
 ### Persistence
 
-- `src/lib/localDb.ts`: persistent config/state
-- `src/lib/usageDb.ts`: usage history and rolling request logs
+- `src/lib/db/*`: persistent config/state and domain persistence on SQLite
+- `src/lib/localDb.ts`: compatibility re-export for DB modules
+- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables
 
 ## Provider Executor Coverage (Strategy Pattern)
 
@@ -589,7 +617,7 @@ Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/
 
 | Executor              | Provider(s)                                                                                                                                                  | Special Handling                                                     |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
-| `DefaultExecutor`     | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider                               |
+| `DefaultExecutor`     | OpenAI, Claude, Gemini, Qwen, Qoder, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider                               |
 | `AntigravityExecutor` | Google Antigravity                                                                                                                                           | Custom project/session IDs, Retry-After parsing                      |
 | `CodexExecutor`       | OpenAI Codex                                                                                                                                                 | Injects system instructions, forces reasoning effort                 |
 | `CursorExecutor`      | Cursor IDE                                                                                                                                                   | ConnectRPC protocol, Protobuf encoding, request signing via checksum |
@@ -613,7 +641,7 @@ All other providers (including custom compatible nodes) use the `DefaultExecutor
 | Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
 | Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
 | Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
-| iFlow            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Qoder            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
 | OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
@@ -661,40 +689,38 @@ Additional processing layers in the translation pipeline:
 
 ## Supported API Endpoints
 
-| Endpoint                                           | Format             | Handler                                              |
-| -------------------------------------------------- | ------------------ | ---------------------------------------------------- |
-| `POST /v1/chat/completions`                        | OpenAI Chat        | `src/sse/handlers/chat.ts`                           |
-| `POST /v1/messages`                                | Claude Messages    | Same handler (auto-detected)                         |
-| `POST /v1/responses`                               | OpenAI Responses   | `open-sse/handlers/responsesHandler.ts`              |
-| `POST /v1/embeddings`                              | OpenAI Embeddings  | `open-sse/handlers/embeddings.ts`                    |
-| `GET /v1/embeddings`                               | Model listing      | API route                                            |
-| `POST /v1/images/generations`                      | OpenAI Images      | `open-sse/handlers/imageGeneration.ts`               |
-| `GET /v1/images/generations`                       | Model listing      | API route                                            |
-| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat        | Dedicated per-provider with model validation         |
-| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings  | Dedicated per-provider with model validation         |
-| `POST /v1/providers/{provider}/images/generations` | OpenAI Images      | Dedicated per-provider with model validation         |
-| `POST /v1/messages/count_tokens`                   | Claude Token Count | API route                                            |
-| `GET /v1/models`                                   | OpenAI Models list | API route (chat + embedding + image + custom models) |
-| `GET /api/models/catalog`                          | Catalog            | All models grouped by provider + type                |
-| `POST /v1beta/models/*:streamGenerateContent`      | Gemini native      | API route                                            |
-| `GET/PUT/DELETE /api/settings/proxy`               | Proxy Config       | Network proxy configuration                          |
-| `POST /api/settings/proxy/test`                    | Proxy Connectivity | Proxy health/connectivity test endpoint              |
-| `GET/POST/DELETE /api/provider-models`             | Custom Models      | Custom model management per provider                 |
+| Endpoint                                           | Format             | Handler                                                             |
+| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------- |
+| `POST /v1/chat/completions`                        | OpenAI Chat        | `src/sse/handlers/chat.ts`                                          |
+| `POST /v1/messages`                                | Claude Messages    | Same handler (auto-detected)                                        |
+| `POST /v1/responses`                               | OpenAI Responses   | `open-sse/handlers/responsesHandler.ts`                             |
+| `POST /v1/embeddings`                              | OpenAI Embeddings  | `open-sse/handlers/embeddings.ts`                                   |
+| `GET /v1/embeddings`                               | Model listing      | API route                                                           |
+| `POST /v1/images/generations`                      | OpenAI Images      | `open-sse/handlers/imageGeneration.ts`                              |
+| `GET /v1/images/generations`                       | Model listing      | API route                                                           |
+| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat        | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings  | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/images/generations` | OpenAI Images      | Dedicated per-provider with model validation                        |
+| `POST /v1/messages/count_tokens`                   | Claude Token Count | API route                                                           |
+| `GET /v1/models`                                   | OpenAI Models list | API route (chat + embedding + image + custom models)                |
+| `GET /api/models/catalog`                          | Catalog            | All models grouped by provider + type                               |
+| `POST /v1beta/models/*:streamGenerateContent`      | Gemini native      | API route                                                           |
+| `GET/PUT/DELETE /api/settings/proxy`               | Proxy Config       | Network proxy configuration                                         |
+| `POST /api/settings/proxy/test`                    | Proxy Connectivity | Proxy health/connectivity test endpoint                             |
+| `GET/POST/DELETE /api/provider-models`             | Provider Models    | Provider model metadata backing custom and managed available models |
 
 ## Bypass Handler
 
 The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`.
 
-## Request Logger Pipeline
+## Request Logging and Artifacts
 
-The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`:
+The older file-based request logger (`open-sse/utils/requestLogger.ts`) is retained only for
+legacy compatibility. The current runtime contract uses:
 
-```
-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
-```
-
-Files are written to `<repo>/logs/<session>/` for each request session.
+- `APP_LOG_TO_FILE=true` for application and audit logs written under `<repo>/logs/`
+- SQLite-backed call log records in `call_logs`
+- `${DATA_DIR}/call_logs/YYYY-MM-DD/...` artifacts when the call log pipeline is enabled
 
 ## Failure Modes and Resilience
 
@@ -722,23 +748,32 @@ Files are written to `<repo>/logs/<session>/` for each request session.
 
 ## 5) Data Integrity
 
-- DB shape migration/repair for missing keys
-- corrupt JSON reset safeguards for localDb and usageDb
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
 ## Observability and Operational Signals
 
 Runtime visibility sources:
 
 - console logs from `src/sse/utils/logger.ts`
-- 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`
+- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true`
+- textual request status log in `log.txt` (optional/compat)
+- optional application log files under `logs/` when `APP_LOG_TO_FILE=true`
+- optional request artifacts under `${DATA_DIR}/call_logs/` when the call log pipeline is enabled
 - dashboard usage endpoints (`/api/usage/*`) for UI consumption
 
+Detailed request payload capture stores up to four JSON payload stages per routed call:
+
+- raw request received from the client
+- translated request actually sent upstream
+- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata
+- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form
+
 ## 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
+- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning
 - 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
@@ -752,7 +787,7 @@ Environment variables actively used by code:
 - Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
 - Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME`
 - Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
-- Logging: `ENABLE_REQUEST_LOGS`
+- Logging: `APP_LOG_TO_FILE`, `APP_LOG_RETENTION_DAYS`, `CALL_LOG_RETENTION_DAYS`
 - Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
 - Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants
 - SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
@@ -760,14 +795,17 @@ Environment variables actively used by code:
 
 ## Known Architectural Notes
 
-1. `usageDb` and `localDb` now share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.
-2. `/api/v1/route.ts` returns a static model list and is not the main models source used by `/v1/models`.
+1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.
+2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift.
 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.
 5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency.
 6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates).
-7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:plan3`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`).
-8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
+7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`).
+8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies, **Context Relay** handoff config), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
+9. **Context Relay** strategy (`context-relay`) is split across two layers: `combo.ts` decides if a handoff should be generated, `chat.ts` injects the handoff after account resolution. Handoff data lives in `context_handoffs` SQLite table. This split is intentional because only `chat.ts` knows whether the actual account changed.
+10. **Proxy enforcement** is now comprehensive: `tokenHealthCheck.ts` resolves proxy per connection, `/api/providers/validate` uses `runWithProxyContext`, and `proxyFetch.ts` uses `undici.fetch()` to maintain dispatcher compatibility on Node 22.
+11. **Node.js 24+ detection**: `/api/settings/require-login` returns `nodeVersion` and `nodeCompatible` fields. The login page renders a warning banner when the runtime is incompatible.
 
 ## Operational Verification Checklist
 

docs/AUTO-COMBO.md

@@ -0,0 +1,63 @@
+# OmniRoute Auto-Combo Engine
+
+> Self-managing model chains with adaptive scoring
+
+## How It Works
+
+The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**:
+
+| Factor     | Weight | Description                                     |
+| :--------- | :----- | :---------------------------------------------- |
+| Quota      | 0.20   | Remaining capacity [0..1]                       |
+| Health     | 0.25   | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 |
+| CostInv    | 0.20   | Inverse cost (cheaper = higher score)           |
+| LatencyInv | 0.15   | Inverse p95 latency (faster = higher)           |
+| TaskFit    | 0.10   | Model × task type fitness score                 |
+| Stability  | 0.10   | Low variance in latency/errors                  |
+
+## Mode Packs
+
+| Pack                    | Focus        | Key Weight       |
+| :---------------------- | :----------- | :--------------- |
+| 🚀 **Ship Fast**        | Speed        | latencyInv: 0.35 |
+| 💰 **Cost Saver**       | Economy      | costInv: 0.40    |
+| 🎯 **Quality First**    | Best model   | taskFit: 0.40    |
+| 📡 **Offline Friendly** | Availability | quota: 0.40      |
+
+## Self-Healing
+
+- **Temporary exclusion**: Score < 0.2 → excluded for 5 min (progressive backoff, max 30 min)
+- **Circuit breaker awareness**: OPEN → auto-excluded; HALF_OPEN → probe requests
+- **Incident mode**: >50% OPEN → disable exploration, maximize stability
+- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout
+
+## Bandit Exploration
+
+5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode.
+
+## API
+
+```bash
+# Create auto-combo
+curl -X POST http://localhost:20128/api/combos/auto \
+  -H "Content-Type: application/json" \
+  -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}'
+
+# List auto-combos
+curl http://localhost:20128/api/combos/auto
+```
+
+## Task Fitness
+
+30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` → high coding score).
+
+## Files
+
+| File                                         | Purpose                               |
+| :------------------------------------------- | :------------------------------------ |
+| `open-sse/services/autoCombo/scoring.ts`     | Scoring function & pool normalization |
+| `open-sse/services/autoCombo/taskFitness.ts` | Model × task fitness lookup           |
+| `open-sse/services/autoCombo/engine.ts`      | Selection logic, bandit, budget cap   |
+| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode      |
+| `open-sse/services/autoCombo/modePacks.ts`   | 4 weight profiles                     |
+| `src/app/api/combos/auto/route.ts`           | REST API                              |

docs/CLI-TOOLS.md

@@ -0,0 +1,344 @@
+# CLI Tools Setup Guide — OmniRoute
+
+This guide explains how to install and configure all supported AI coding CLI tools
+to use **OmniRoute** as the unified backend, giving you centralized key management,
+cost tracking, model switching, and request logging across every tool.
+
+---
+
+## How It Works
+
+```
+Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot
+           │
+           ▼  (all point to OmniRoute)
+    http://YOUR_SERVER:20128/v1
+           │
+           ▼  (OmniRoute routes to the right provider)
+    Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...
+```
+
+**Benefits:**
+
+- One API key to manage all tools
+- Cost tracking across all CLIs in the dashboard
+- Model switching without reconfiguring every tool
+- Works locally and on remote servers (VPS)
+
+---
+
+## Supported Tools (Dashboard Source of Truth)
+
+The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`.
+Current list (v3.0.0-rc.16):
+
+| Tool             | ID            | Command      | Setup Mode | Install Method |
+| ---------------- | ------------- | ------------ | ---------- | -------------- |
+| **Claude Code**  | `claude`      | `claude`     | env        | npm            |
+| **OpenAI Codex** | `codex`       | `codex`      | custom     | npm            |
+| **Factory Droid**| `droid`       | `droid`      | custom     | bundled/CLI    |
+| **OpenClaw**     | `openclaw`    | `openclaw`   | custom     | bundled/CLI    |
+| **Cursor**       | `cursor`      | app          | guide      | desktop app    |
+| **Cline**        | `cline`       | `cline`      | custom     | npm            |
+| **Kilo Code**    | `kilo`        | `kilocode`   | custom     | npm            |
+| **Continue**     | `continue`    | extension    | guide      | VS Code        |
+| **Antigravity**  | `antigravity` | internal     | mitm       | OmniRoute      |
+| **GitHub Copilot**| `copilot`    | extension    | custom     | VS Code        |
+| **OpenCode**     | `opencode`    | `opencode`   | guide      | npm            |
+| **Kiro AI**      | `kiro`        | app/cli      | mitm       | desktop/CLI    |
+
+### CLI fingerprint sync (Agents + Settings)
+
+`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`.
+This keeps provider IDs aligned with CLI cards and legacy IDs.
+
+| CLI ID | Fingerprint Provider ID |
+| ------ | ----------------------- |
+| `kilo` | `kilocode`              |
+| `copilot` | `github`             |
+| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID |
+
+Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`.
+
+---
+
+## Step 1 — Get an OmniRoute API Key
+
+1. Open the OmniRoute dashboard → **API Manager** (`/dashboard/api-manager`)
+2. Click **Create API Key**
+3. Give it a name (e.g. `cli-tools`) and select all permissions
+4. Copy the key — you'll need it for every CLI below
+
+> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`
+
+---
+
+## Step 2 — Install CLI Tools
+
+All npm-based tools require Node.js 18+:
+
+```bash
+# Claude Code (Anthropic)
+npm install -g @anthropic-ai/claude-code
+
+# OpenAI Codex
+npm install -g @openai/codex
+
+# OpenCode
+npm install -g opencode-ai
+
+# Cline
+npm install -g cline
+
+# KiloCode
+npm install -g kilocode
+
+# Kiro CLI (Amazon — requires curl + unzip)
+apt-get install -y unzip   # on Debian/Ubuntu
+curl -fsSL https://cli.kiro.dev/install | bash
+export PATH="$HOME/.local/bin:$PATH"   # add to ~/.bashrc
+```
+
+**Verify:**
+
+```bash
+claude --version     # 2.x.x
+codex --version      # 0.x.x
+opencode --version   # x.x.x
+cline --version      # 2.x.x
+kilocode --version   # x.x.x (or: kilo --version)
+kiro-cli --version   # 1.x.x
+```
+
+---
+
+## Step 3 — Set Global Environment Variables
+
+Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`:
+
+```bash
+# OmniRoute Universal Endpoint
+export OPENAI_BASE_URL="http://localhost:20128/v1"
+export OPENAI_API_KEY="sk-your-omniroute-key"
+export ANTHROPIC_BASE_URL="http://localhost:20128/v1"
+export ANTHROPIC_API_KEY="sk-your-omniroute-key"
+export GEMINI_BASE_URL="http://localhost:20128/v1"
+export GEMINI_API_KEY="sk-your-omniroute-key"
+```
+
+> For a **remote server** replace `localhost:20128` with the server IP or domain,
+> e.g. `http://192.168.0.15:20128`.
+
+---
+
+## Step 4 — Configure Each Tool
+
+### Claude Code
+
+```bash
+# Via CLI:
+claude config set --global api-base-url http://localhost:20128/v1
+
+# Or create ~/.claude/settings.json:
+mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF
+{
+  "apiBaseUrl": "http://localhost:20128/v1",
+  "apiKey": "sk-your-omniroute-key"
+}
+EOF
+```
+
+**Test:** `claude "say hello"`
+
+---
+
+### OpenAI Codex
+
+```bash
+mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF
+model: auto
+apiKey: sk-your-omniroute-key
+apiBaseUrl: http://localhost:20128/v1
+EOF
+```
+
+**Test:** `codex "what is 2+2?"`
+
+---
+
+### OpenCode
+
+```bash
+mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF
+[provider.openai]
+base_url = "http://localhost:20128/v1"
+api_key = "sk-your-omniroute-key"
+EOF
+```
+
+**Test:** `opencode`
+
+---
+
+### Cline (CLI or VS Code)
+
+**CLI mode:**
+
+```bash
+mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF
+{
+  "apiProvider": "openai",
+  "openAiBaseUrl": "http://localhost:20128/v1",
+  "openAiApiKey": "sk-your-omniroute-key"
+}
+EOF
+```
+
+**VS Code mode:**
+Cline extension settings → API Provider: `OpenAI Compatible` → Base URL: `http://localhost:20128/v1`
+
+Or use the OmniRoute dashboard → **CLI Tools → Cline → Apply Config**.
+
+---
+
+### KiloCode (CLI or VS Code)
+
+**CLI mode:**
+
+```bash
+kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key
+```
+
+**VS Code settings:**
+
+```json
+{
+  "kilo-code.openAiBaseUrl": "http://localhost:20128/v1",
+  "kilo-code.apiKey": "sk-your-omniroute-key"
+}
+```
+
+Or use the OmniRoute dashboard → **CLI Tools → KiloCode → Apply Config**.
+
+---
+
+### Continue (VS Code Extension)
+
+Edit `~/.continue/config.yaml`:
+
+```yaml
+models:
+  - name: OmniRoute
+    provider: openai
+    model: auto
+    apiBase: http://localhost:20128/v1
+    apiKey: sk-your-omniroute-key
+    default: true
+```
+
+Restart VS Code after editing.
+
+---
+
+### Kiro CLI (Amazon)
+
+```bash
+# Login to your AWS/Kiro account:
+kiro-cli login
+
+# The CLI uses its own auth — OmniRoute is not needed as backend for Kiro CLI itself.
+# Use kiro-cli alongside OmniRoute for other tools.
+kiro-cli status
+```
+
+---
+
+### Cursor (Desktop App)
+
+> **Note:** Cursor routes requests through its cloud. For OmniRoute integration,
+> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL.
+
+Via GUI: **Settings → Models → OpenAI API Key**
+
+- Base URL: `https://your-domain.com/v1`
+- API Key: your OmniRoute key
+
+---
+
+## Dashboard Auto-Configuration
+
+The OmniRoute dashboard automates configuration for most tools:
+
+1. Go to `http://localhost:20128/dashboard/cli-tools`
+2. Expand any tool card
+3. Select your API key from the dropdown
+4. Click **Apply Config** (if tool is detected as installed)
+5. Or copy the generated config snippet manually
+
+---
+
+## Built-in Agents: Droid & OpenClaw
+
+**Droid** and **OpenClaw** are AI agents built directly into OmniRoute — no installation needed.
+They run as internal routes and use OmniRoute's model routing automatically.
+
+- Access: `http://localhost:20128/dashboard/agents`
+- Configure: same combos and providers as all other tools
+- No API key or CLI install required
+
+---
+
+## Available API Endpoints
+
+| Endpoint                   | Description                   | Use For                     |
+| -------------------------- | ----------------------------- | --------------------------- |
+| `/v1/chat/completions`     | Standard chat (all providers) | All modern tools            |
+| `/v1/responses`            | Responses API (OpenAI format) | Codex, agentic workflows    |
+| `/v1/completions`          | Legacy text completions       | Older tools using `prompt:` |
+| `/v1/embeddings`           | Text embeddings               | RAG, search                 |
+| `/v1/images/generations`   | Image generation              | DALL-E, Flux, etc.          |
+| `/v1/audio/speech`         | Text-to-speech                | ElevenLabs, OpenAI TTS      |
+| `/v1/audio/transcriptions` | Speech-to-text                | Deepgram, AssemblyAI        |
+
+---
+
+## Troubleshooting
+
+| Error                     | Cause                   | Fix                                        |
+| ------------------------- | ----------------------- | ------------------------------------------ |
+| `Connection refused`      | OmniRoute not running   | `pm2 start omniroute`                      |
+| `401 Unauthorized`        | Wrong API key           | Check in `/dashboard/api-manager`          |
+| `No combo configured`     | No active routing combo | Set up in `/dashboard/combos`              |
+| `invalid model`           | Model not in catalog    | Use `auto` or check `/dashboard/providers` |
+| CLI shows "not installed" | Binary not in PATH      | Check `which <command>`                    |
+| `kiro-cli: not found`     | Not in PATH             | `export PATH="$HOME/.local/bin:$PATH"`     |
+
+---
+
+## Quick Setup Script (One Command)
+
+```bash
+# Install all CLIs and configure for OmniRoute (replace with your key and server URL)
+OMNIROUTE_URL="http://localhost:20128/v1"
+OMNIROUTE_KEY="sk-your-omniroute-key"
+
+npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode
+
+# Kiro CLI
+apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash
+
+# Write configs
+mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue
+
+cat > ~/.claude/settings.json   <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}"
+cat > ~/.codex/config.yaml      <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL"
+cat >> ~/.bashrc << EOF
+export OPENAI_BASE_URL="$OMNIROUTE_URL"
+export OPENAI_API_KEY="$OMNIROUTE_KEY"
+export ANTHROPIC_BASE_URL="$OMNIROUTE_URL"
+export ANTHROPIC_API_KEY="$OMNIROUTE_KEY"
+EOF
+
+source ~/.bashrc
+echo "✅ All CLIs installed and configured for OmniRoute"
+```

docs/CODEBASE_DOCUMENTATION.md

@@ -1,5 +1,7 @@
 # omniroute — Codebase Documentation
 
+🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) | 🇨🇿 [Čeština](i18n/cs/CODEBASE_DOCUMENTATION.md)
+
 > A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router.
 
 ---
@@ -265,7 +267,7 @@ Business logic that supports the handlers and executors.
 | `provider.ts`        | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. |
 | `model.ts`           | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support.                                                                             |
 | `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not).                                                                                                                                                                         |
-| `tokenRefresh.ts`    | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff.                                                                       |
+| `tokenRefresh.ts`    | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, Qoder, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff.                                                                       |
 | `combo.ts`           | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes.                                                                                                                                                                          |
 | `usage.ts`           | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings).                                                                                                                                                                              |
 | `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request.                                                                                                                                                              |
@@ -401,7 +403,7 @@ import "./request/claude-to-openai.js"; // ← self-registers
 | `stream.ts`        | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. |
 | `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup).                                                       |
 | `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors.                                |
-| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers.                                                              |
+| `requestLogger.ts` | Legacy file-based request logging helper kept for compatibility. Current deployments should prefer `APP_LOG_TO_FILE` for application logs and the call log pipeline for persisted request artifacts.                                                                                 |
 | `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope.                                                        |
 | `networkProxy.ts`  | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s.                                                  |
 
@@ -537,7 +539,7 @@ A 2000-token buffer is added to reported usage to prevent clients from hitting c
 | Kiro (AWS)               | AWS SSO OIDC or Social | Kiro        | Binary EventStream parsing                    |
 | Cursor IDE               | Checksum auth          | Cursor      | Protobuf encoding, SHA-256 checksums          |
 | Qwen                     | OAuth                  | Default     | Standard auth                                 |
-| iFlow                    | OAuth (Basic + Bearer) | Default     | Dual auth header                              |
+| Qoder                    | OAuth (Basic + Bearer) | Default     | Dual auth header                              |
 | OpenRouter               | API key                | Default     | Standard Bearer auth                          |
 | GLM, Kimi, MiniMax       | API key                | Default     | Claude-compatible, use `x-api-key`            |
 | `openai-compatible-*`    | API key                | Default     | Dynamic: any OpenAI-compatible endpoint       |

docs/COVERAGE_PLAN.md

@@ -0,0 +1,166 @@
+# Test Coverage Plan
+
+Last updated: 2026-03-28
+
+## Baseline
+
+There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful.
+
+| Metric               | Scope                                                 | Statements / Lines | Branches | Functions | Notes                                               |
+| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- |
+| Legacy               | Old `npm run test:coverage`                           |             79.42% |   75.15% |    67.94% | Inflated: counts test files and excludes `open-sse` |
+| Diagnostic           | Source-only, excluding tests and excluding `open-sse` |             68.16% |   63.55% |    64.06% | Useful only to isolate `src/**`                     |
+| Recommended baseline | Source-only, excluding tests and including `open-sse` |             56.95% |   66.05% |    57.80% | This is the project-wide baseline to improve        |
+
+The recommended baseline is the number to optimize against.
+
+## Rules
+
+- Coverage targets apply to source files, not to `tests/**`.
+- `open-sse/**` is part of the product and must remain in scope.
+- New code should not reduce coverage in touched areas.
+- Prefer testing behavior and branch outcomes over implementation details.
+- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`.
+
+## Current command set
+
+- `npm run test:coverage`
+  - Main source coverage gate for the unit test suite
+  - Generates `text-summary`, `html`, `json-summary`, and `lcov`
+- `npm run coverage:report`
+  - Detailed file-by-file report from the latest run
+- `npm run test:coverage:legacy`
+  - Historical comparison only
+
+## Milestones
+
+| Phase   |                 Target | Focus                                             |
+| ------- | ---------------------: | ------------------------------------------------- |
+| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage          |
+| Phase 2 | 65% statements / lines | DB and route foundations                          |
+| Phase 3 | 70% statements / lines | Provider validation and usage analytics           |
+| Phase 4 | 75% statements / lines | `open-sse` translators and helpers                |
+| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches         |
+| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites |
+| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet          |
+
+Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines.
+
+## Priority hotspots
+
+These files or areas offer the best return for the next phases:
+
+1. `open-sse/handlers`
+   - `chatCore.ts` at 7.57%
+   - Overall directory at 29.07%
+2. `open-sse/translator/request`
+   - Overall directory at 36.39%
+   - Many translators are still near single-digit coverage
+3. `open-sse/translator/response`
+   - Overall directory at 8.07%
+4. `open-sse/executors`
+   - Overall directory at 36.62%
+5. `src/lib/db`
+   - `models.ts` at 20.66%
+   - `registeredKeys.ts` at 34.46%
+   - `modelComboMappings.ts` at 36.25%
+   - `settings.ts` at 46.40%
+   - `webhooks.ts` at 33.33%
+6. `src/lib/usage`
+   - `usageHistory.ts` at 21.12%
+   - `usageStats.ts` at 9.56%
+   - `costCalculator.ts` at 30.00%
+7. `src/lib/providers`
+   - `validation.ts` at 41.16%
+8. Low-risk utility and API files for early gains
+   - `src/shared/utils/upstreamError.ts`
+   - `src/shared/utils/apiAuth.ts`
+   - `src/lib/api/errorResponse.ts`
+   - `src/app/api/settings/require-login/route.ts`
+   - `src/app/api/providers/[id]/models/route.ts`
+
+## Execution checklist
+
+### Phase 1: 56.95% -> 60%
+
+- [x] Fix coverage metric so it reflects source code instead of test files
+- [x] Keep a legacy coverage script for comparison
+- [x] Record the baseline and hotspots in-repo
+- [ ] Add focused tests for low-risk utilities:
+  - `src/shared/utils/upstreamError.ts`
+  - `src/shared/utils/fetchTimeout.ts`
+  - `src/lib/api/errorResponse.ts`
+  - `src/shared/utils/apiAuth.ts`
+  - `src/lib/display/names.ts`
+- [ ] Add route tests for:
+  - `src/app/api/settings/require-login/route.ts`
+  - `src/app/api/providers/[id]/models/route.ts`
+
+### Phase 2: 60% -> 65%
+
+- [ ] Add DB-backed tests for:
+  - `src/lib/db/modelComboMappings.ts`
+  - `src/lib/db/settings.ts`
+  - `src/lib/db/registeredKeys.ts`
+- [ ] Cover branch behavior in:
+  - `src/lib/providers/validation.ts`
+  - `src/app/api/v1/embeddings/route.ts`
+  - `src/app/api/v1/moderations/route.ts`
+
+### Phase 3: 65% -> 70%
+
+- [ ] Add usage analytics tests for:
+  - `src/lib/usage/usageHistory.ts`
+  - `src/lib/usage/usageStats.ts`
+  - `src/lib/usage/costCalculator.ts`
+- [ ] Expand route coverage for proxy management and settings branches
+
+### Phase 4: 70% -> 75%
+
+- [ ] Cover translator helpers and central translation paths:
+  - `open-sse/translator/index.ts`
+  - `open-sse/translator/helpers/*`
+  - `open-sse/translator/request/*`
+  - `open-sse/translator/response/*`
+
+### Phase 5: 75% -> 80%
+
+- [ ] Add handler-level tests for:
+  - `open-sse/handlers/chatCore.ts`
+  - `open-sse/handlers/responsesHandler.js`
+  - `open-sse/handlers/imageGeneration.js`
+  - `open-sse/handlers/embeddings.js`
+- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides
+
+### Phase 6: 80% -> 85%
+
+- [ ] Merge more edge-case suites into the main coverage path
+- [ ] Increase function coverage for DB modules with weak constructor/helper coverage
+- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers
+
+### Phase 7: 85% -> 90%
+
+- [ ] Treat the remaining low-coverage files as blockers
+- [ ] Add regression tests for every uncovered production bug fixed during the push to 90%
+- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs
+
+## Ratchet policy
+
+Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer.
+
+Recommended ratchet sequence:
+
+1. 55/60/55
+2. 60/62/58
+3. 65/64/62
+4. 70/66/66
+5. 75/70/72
+6. 80/75/78
+7. 85/80/84
+8. 90/85/88
+
+Order is `statements-lines / branches / functions`.
+
+## Known gap
+
+The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb.

docs/FEATURES.md

@@ -1,12 +1,14 @@
 # OmniRoute — Dashboard Features Gallery
 
+🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) | 🇨🇿 [Čeština](i18n/cs/FEATURES.md)
+
 Visual guide to every section of the OmniRoute dashboard.
 
 ---
 
 ## 🔌 Providers
 
-Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro).
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
 
 ![Providers Dashboard](screenshots/01-providers.png)
 
@@ -14,7 +16,7 @@ Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI)
 
 ## 🎨 Combos
 
-Create model routing combos with 6 strategies: fill-first, round-robin, power-of-two-choices, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback.
+Create model routing combos with 13 strategies: priority, weighted, round-robin, random, least-used, cost-optimized, strict-random, auto, fill-first, p2c, lkgp, context-optimized, and **context-relay**. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
 
 ![Combos Dashboard](screenshots/02-combos.png)
 
@@ -44,9 +46,28 @@ Four modes for debugging API translations: **Playground** (format converter), **
 
 ---
 
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
 ## ⚙️ Settings
 
-General settings, system storage, backup management (export/import database), appearance (dark/light mode), security (includes API endpoint protection and custom provider blocking), routing, resilience, and advanced configuration.
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring, **Context Relay** handoff threshold and summary model configuration
+- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
 
 ![Settings Dashboard](screenshots/06-settings.png)
 
@@ -54,12 +75,53 @@ General settings, system storage, backup management (export/import database), ap
 
 ## 🔧 CLI Tools
 
-One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, and Antigravity.
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
 
 ![CLI Tools Dashboard](screenshots/07-cli-tools.png)
 
 ---
 
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🔗 Context Relay _(v3.5.5+)_
+
+A combo strategy that preserves session continuity when account rotation happens mid-conversation. Before the active account is exhausted, OmniRoute generates a structured handoff summary in the background. After the next request resolves to a different account, the summary is injected as a system message so the new account continues with full context.
+
+Configurable via combo-level or global settings:
+- **Handoff Threshold** — Quota usage percentage that triggers summary generation (default 85%)
+- **Max Messages For Summary** — How much recent history to condense
+- **Summary Model** — Optional override model for generating the handoff summary
+
+Currently supports Codex account rotation. See [Context Relay documentation](features/context-relay.md).
+
+---
+
+## 🛡️ Proxy Hardening _(v3.5.5+)_
+
+Comprehensive proxy configuration enforcement across the entire request pipeline:
+
+- **Token Health Check** — Background OAuth refresh now resolves proxy config per connection, preventing failures in proxy-required environments
+- **API Key Validation** — Provider key validation (`POST /api/providers/validate`) routes through `runWithProxyContext`, honoring provider-level and global proxy settings
+- **undici Dispatcher Fix** — Proxy dispatchers use undici's own fetch implementation instead of Node's built-in fetch, resolving `invalid onRequestStart method` errors on Node.js 22
+- **Node.js Version Detection** — Login page proactively detects incompatible Node.js versions (24+) and displays a warning banner with instructions to use Node 22 LTS
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
 ## 📝 Request Logs
 
 Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
@@ -70,6 +132,36 @@ Real-time request logging with filtering by provider, model, account, and API ke
 
 ## 🌐 API Endpoint
 
-Your unified API endpoint with capability breakdown: Chat Completions, Embeddings, Image Generation, Reranking, Audio Transcription, and registered API keys.
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
 
 ![Endpoint Dashboard](screenshots/09-endpoint.png)
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/FLY_IO_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,451 @@
+# OmniRoute Fly.io 部署指南
+
+本文档记录 OmniRoute 在 Fly.io 上的实际部署方法，适用于两类场景：
+
+- 首次把当前项目部署到 Fly.io
+- 后续代码更新后继续发布
+- 新项目参考同样流程部署
+
+本文基于当前项目已经验证通过的配置整理，应用名为 `omniroute`。
+
+---
+
+## 1. 部署目标
+
+- 平台：Fly.io
+- 部署方式：本地 `flyctl` 直接发布
+- 运行方式：使用仓库内现有 `Dockerfile` 和 `fly.toml`
+- 数据持久化：Fly Volume 挂载到 `/data`
+- 访问地址：`https://omniroute.fly.dev/`
+
+---
+
+## 2. 当前项目关键配置
+
+当前仓库中的 `fly.toml` 已确认包含以下关键项：
+
+```toml
+app = 'omniroute'
+primary_region = 'sin'
+
+[[mounts]]
+  source = 'data'
+  destination = '/data'
+
+[processes]
+  app = 'node run-standalone.mjs'
+
+[http_service]
+  internal_port = 20128
+
+[env]
+  TZ = "Asia/Shanghai"
+  HOST = "0.0.0.0"
+  HOSTNAME = "0.0.0.0"
+  BIND = "0.0.0.0"
+```
+
+说明：
+
+- `app = 'omniroute'` 决定实际部署到哪个 Fly 应用
+- `destination = '/data'` 决定持久卷挂载目录
+- 本项目必须让 `DATA_DIR=/data`，否则数据库和密钥会写到容器临时目录
+
+---
+
+## 3. 必备工具
+
+### 3.1 安装 Fly CLI
+
+Windows PowerShell：
+
+```powershell
+pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"
+```
+
+如果安装脚本在当前环境失败，也可以手动下载 `flyctl` 二进制并放到 `PATH` 中。
+
+### 3.2 登录 Fly 账号
+
+```powershell
+flyctl auth login
+```
+
+### 3.3 检查登录状态
+
+```powershell
+flyctl auth whoami
+flyctl version
+```
+
+---
+
+## 4. 首次部署当前项目
+
+### 4.1 获取代码并进入目录
+
+```powershell
+git clone https://github.com/xiaoge1688/OmniRoute.git
+cd OmniRoute
+```
+
+### 4.2 确认应用名
+
+打开 `fly.toml`，重点看这一行：
+
+```toml
+app = 'omniroute'
+```
+
+如果你准备部署到自己的新应用，可改成全局唯一名称，例如：
+
+```toml
+app = 'omniroute-yourname'
+```
+
+注意：
+
+- 控制台里要看的是与 `fly.toml` 里 `app` 一致的应用
+- 以前如果用过别的名字，例如 `oroute`，不要和 `omniroute` 混淆
+
+### 4.3 创建应用
+
+如果该应用尚不存在：
+
+```powershell
+flyctl apps create omniroute
+```
+
+如果你已经改成别的应用名，把 `omniroute` 替换成你的名字。
+
+### 4.4 首次部署
+
+```powershell
+flyctl deploy
+```
+
+---
+
+## 5. 必配参数
+
+本项目在 Fly.io 上建议至少配置以下参数。
+
+### 5.1 已验证使用的参数
+
+这些参数已经在当前 `omniroute` 应用上实际部署：
+
+- `API_KEY_SECRET`
+- `DATA_DIR`
+- `JWT_SECRET`
+- `MACHINE_ID_SALT`
+- `NEXT_PUBLIC_BASE_URL`
+- `STORAGE_ENCRYPTION_KEY`
+
+### 5.2 关于 `INITIAL_PASSWORD`
+
+当前项目没有设置 `INITIAL_PASSWORD`，因为本次部署按需求不使用它。
+
+如果不设置：
+
+- 启动日志会提示默认密码是 `CHANGEME`
+- 部署后应尽快在系统设置中修改登录密码
+
+如果你希望无人值守初始化后台密码，也可以后续补：
+
+- `INITIAL_PASSWORD`
+
+---
+
+## 6. 推荐参数说明
+
+### 6.1 Secrets 中设置
+
+建议放入 Fly Secrets：
+
+| 变量名 | 是否推荐 | 说明 |
+| --- | --- | --- |
+| `API_KEY_SECRET` | 必需 | API Key 生成与校验使用 |
+| `JWT_SECRET` | 必需 | 登录态和 JWT 签名使用 |
+| `STORAGE_ENCRYPTION_KEY` | 强烈推荐 | 加密存储敏感连接信息 |
+| `MACHINE_ID_SALT` | 推荐 | 生成稳定机器标识 |
+| `INITIAL_PASSWORD` | 可选 | 首次部署时直接指定后台初始密码 |
+| OAuth/API 私密凭证 | 按需 | 各类外部平台鉴权配置 |
+
+### 6.2 当前项目推荐值
+
+| 变量名 | 推荐值 |
+| --- | --- |
+| `DATA_DIR` | `/data` |
+| `NEXT_PUBLIC_BASE_URL` | `https://omniroute.fly.dev` |
+
+说明：
+
+- `DATA_DIR=/data` 非常关键，必须与 Fly Volume 挂载点一致
+- `NEXT_PUBLIC_BASE_URL` 用于调度器和前端回调等场景
+
+---
+
+## 7. 一键设置参数
+
+下面命令会生成安全随机值，并把当前项目需要的参数一次性写入 Fly Secrets。
+
+说明：
+
+- 不包含 `INITIAL_PASSWORD`
+- 适用于当前项目 `omniroute`
+
+```powershell
+$apiKeySecret = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
+$jwtSecret = [Convert]::ToHexString((1..64 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
+$machineIdSalt = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
+$storageKey = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
+
+flyctl secrets set `
+  API_KEY_SECRET=$apiKeySecret `
+  JWT_SECRET=$jwtSecret `
+  MACHINE_ID_SALT=$machineIdSalt `
+  STORAGE_ENCRYPTION_KEY=$storageKey `
+  DATA_DIR=/data `
+  NEXT_PUBLIC_BASE_URL=https://omniroute.fly.dev `
+  -a omniroute
+```
+
+如果你还要加初始密码：
+
+```powershell
+flyctl secrets set INITIAL_PASSWORD=你的强密码 -a omniroute
+```
+
+---
+
+## 8. 查看当前参数
+
+```powershell
+flyctl secrets list -a omniroute
+```
+
+如果控制台 `Secrets` 页面没有显示你期待的变量，先检查：
+
+- 看的应用是不是 `omniroute`
+- `fly.toml` 的 `app` 是否和控制台应用一致
+
+---
+
+## 9. 后续更新发布
+
+代码有更新后，发布步骤很简单：
+
+```powershell
+git pull
+flyctl deploy
+```
+
+如果只更新参数，不改代码：
+
+```powershell
+flyctl secrets set KEY=value -a omniroute
+```
+
+Fly 会自动滚动更新机器。
+
+### 9.1 跟踪原仓库更新并保留 fork 的 `fly.toml`
+
+如果当前仓库是 fork，并且你要同步上游 `https://github.com/diegosouzapw/OmniRoute` 的更新，推荐按下面流程执行。
+
+先确认远程：
+
+```powershell
+git remote -v
+```
+
+应至少包含：
+
+- `origin` 指向你自己的 fork
+- `upstream` 指向原仓库
+
+如果没有 `upstream`，先添加：
+
+```powershell
+git remote add upstream https://github.com/diegosouzapw/OmniRoute.git
+```
+
+同步上游前，先抓取最新提交和标签：
+
+```powershell
+git fetch upstream --tags
+```
+
+查看当前版本和上游标签：
+
+```powershell
+git describe --tags --always
+git show --no-patch --oneline v3.4.7
+```
+
+如果你想合并上游最新 `main`，并强制保留 fork 当前的 `fly.toml`，可按下面流程执行：
+
+```powershell
+git merge upstream/main
+git checkout HEAD~1 -- fly.toml
+git add -- fly.toml
+git commit -m "chore(deploy): keep fork fly.toml"
+git push origin main
+```
+
+说明：
+
+- `git merge upstream/main` 用于同步原仓库最新代码
+- `git checkout HEAD~1 -- fly.toml` 用于恢复合并前你 fork 自己的 `fly.toml`
+- 如果上游没有改 `fly.toml`，这一步不会带来额外差异
+- 如果上游改了 `fly.toml`，这一步能确保 Fly 应用名、挂载卷、区域等 fork 自定义部署配置不被覆盖
+
+如果你明确只想对齐某个发布标签，例如 `v3.4.7`，也可以先确认标签是否已经包含在 `upstream/main`：
+
+```powershell
+git merge-base --is-ancestor v3.4.7 upstream/main
+```
+
+返回成功表示 `upstream/main` 已经包含该版本，直接合并 `upstream/main` 即可。
+
+### 9.2 同步上游后的标准发布顺序
+
+同步原仓库完成后，推荐按下面顺序发布：
+
+1. `git fetch upstream --tags`
+2. `git merge upstream/main`
+3. 恢复 fork 的 `fly.toml`
+4. `git push origin main`
+5. `flyctl deploy`
+6. `flyctl status -a omniroute`
+7. `flyctl logs --no-tail -a omniroute`
+
+这就是当前项目升级到 `v3.4.7` 时使用的实际流程。
+
+---
+
+## 10. 发布后检查
+
+### 10.1 查看应用状态
+
+```powershell
+flyctl status -a omniroute
+```
+
+### 10.2 查看启动日志
+
+```powershell
+flyctl logs --no-tail -a omniroute
+```
+
+### 10.3 检查网站可访问
+
+```powershell
+try {
+  (Invoke-WebRequest -Uri "https://omniroute.fly.dev" -MaximumRedirection 5 -UseBasicParsing).StatusCode
+} catch {
+  if ($_.Exception.Response) {
+    $_.Exception.Response.StatusCode.value__
+  } else {
+    throw
+  }
+}
+```
+
+返回 `200` 说明站点已正常响应。
+
+---
+
+## 11. 成功标志
+
+部署成功后，日志里应看到类似内容：
+
+```text
+[bootstrap] Secrets persisted to: /data/server.env
+[DB] SQLite database ready: /data/storage.sqlite
+```
+
+这两个点很关键：
+
+- `/data/server.env` 说明运行时密钥落到了持久卷
+- `/data/storage.sqlite` 说明数据库写入持久卷
+
+如果你看到的是 `/app/data/...`，说明 `DATA_DIR` 没配对，需要立即修正。
+
+---
+
+## 12. 常见问题
+
+### 12.1 `Secrets` 页面是空的
+
+通常有两种原因：
+
+- 你还没执行 `flyctl secrets set`
+- 你打开的是另一个应用，例如 `oroute`，不是 `omniroute`
+
+### 12.2 `flyctl deploy` 报 `app not found`
+
+先创建应用：
+
+```powershell
+flyctl apps create omniroute
+```
+
+### 12.3 `fly.toml` 解析失败
+
+重点检查：
+
+- 注释里是否有乱码字符
+- TOML 引号和缩进是否正确
+
+### 12.4 数据没有持久化
+
+检查以下两点：
+
+- `fly.toml` 中是否存在 `destination = '/data'`
+- `DATA_DIR` 是否设置为 `/data`
+
+### 12.5 不设置 `INITIAL_PASSWORD` 是否能跑
+
+可以运行，但会回退到默认 `CHANGEME`。生产环境建议尽快修改后台密码。
+
+---
+
+## 13. 新项目复用建议
+
+如果以后是新项目照着这份文档部署，最少改这几项：
+
+1. 修改 `fly.toml` 里的 `app`
+2. 修改 `NEXT_PUBLIC_BASE_URL`
+3. 保持 `DATA_DIR=/data`
+4. 重新生成 `API_KEY_SECRET`、`JWT_SECRET`、`MACHINE_ID_SALT`、`STORAGE_ENCRYPTION_KEY`
+5. 首次部署后检查日志是否写入 `/data`
+
+不要直接复用旧项目的密钥。
+
+---
+
+## 14. 当前项目的最小发布清单
+
+当前项目后续最常用的命令如下：
+
+```powershell
+flyctl auth whoami
+flyctl status -a omniroute
+flyctl secrets list -a omniroute
+flyctl deploy
+flyctl logs --no-tail -a omniroute
+```
+
+如果只是正常发版，核心就是：
+
+```powershell
+flyctl deploy
+```
+
+如果是新环境首次部署，核心就是：
+
+1. `flyctl auth login`
+2. `flyctl apps create omniroute`
+3. `flyctl secrets set ... -a omniroute`
+4. `flyctl deploy`
+5. `flyctl logs --no-tail -a omniroute`

docs/I18N.md

@@ -0,0 +1,409 @@
+# i18n — Internationalization Guide
+
+OmniRoute supports **30 languages** with full dashboard UI translation, translated documentation, and RTL support for Arabic and Hebrew.
+
+🌐 **Languages:** 🇺🇸 [English](../I18N.md) | 🇧🇷 [Português (Brasil)](./pt-BR/I18N.md) | 🇪🇸 [Español](./es/I18N.md) | 🇫🇷 [Français](./fr/I18N.md) | 🇩🇪 [Deutsch](./de/I18N.md) | 🇮🇹 [Italiano](./it/I18N.md) | 🇷🇺 [Русский](./ru/I18N.md) | 🇨🇳 [中文 (简体)](./zh-CN/I18N.md) | 🇯🇵 [日本語](./ja/I18N.md) | 🇰🇷 [한국어](./ko/I18N.md) | 🇸🇦 [العربية](./ar/I18N.md) | 🇮🇳 [हिन्दी](./hi/I18N.md) | 🇹🇭 [ไทย](./th/I18N.md) | 🇹🇷 [Türkçe](./tr/I18N.md) | 🇺🇦 [Українська](./uk-UA/I18N.md) | 🇻🇳 [Tiếng Việt](./vi/I18N.md) | 🇧🇬 [Български](./bg/I18N.md) | 🇩🇰 [Dansk](./da/I18N.md) | 🇫🇮 [Suomi](./fi/I18N.md) | 🇮🇱 [עברית](./he/I18N.md) | 🇭🇺 [Magyar](./hu/I18N.md) | 🇮🇩 [Bahasa Indonesia](./id/I18N.md) | 🇲🇾 [Bahasa Melayu](./ms/I18N.md) | 🇳🇱 [Nederlands](./nl/I18N.md) | 🇳🇴 [Norsk](./no/I18N.md) | 🇵🇹 [Português (Portugal)](./pt/I18N.md) | 🇷🇴 [Română](./ro/I18N.md) | 🇵🇱 [Polski](./pl/I18N.md) | 🇸🇰 [Slovenčina](./sk/I18N.md) | 🇸🇪 [Svenska](./sv/I18N.md) | 🇵🇭 [Filipino](./phi/I18N.md) | 🇨🇿 [Čeština](./cs/I18N.md)
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Generate translations | `node scripts/i18n/generate-multilang.mjs messages` |
+| Translate docs (LLM) | `python3 scripts/i18n_autotranslate.py --api-url <url> --api-key <key> --model <model>` |
+| Validate a locale | `python3 scripts/validate_translation.py quick -l cs` |
+| Check code keys | `python3 scripts/check_translations.py` |
+| Generate QA report | `node scripts/i18n/generate-qa-checklist.mjs` |
+| Visual QA (Playwright) | `node scripts/i18n/run-visual-qa.mjs` |
+
+## Architecture
+
+### Source of Truth
+- **UI strings**: `src/i18n/messages/en.json` (English source, ~2800 keys)
+- **Locale files**: `src/i18n/messages/{locale}.json` (30 translations)
+- **Framework**: `next-intl` with cookie-based locale resolution
+- **Config**: `src/i18n/config.ts` — defines all 30 locales, language names, flags
+
+### Runtime Flow
+1. User selects language → `NEXT_LOCALE` cookie set
+2. `src/i18n/request.ts` resolves locale: cookie → `Accept-Language` header → fallback `en`
+3. Dynamic import loads `messages/{locale}.json`
+4. Components use `useTranslations("namespace")` and `t("key")`
+
+### Supported Locales
+
+| Code | Language | RTL | Google Translate Code |
+|------|----------|-----|----------------------|
+| `ar` | العربية | Yes | `ar` |
+| `bg` | Български | No | `bg` |
+| `cs` | Čeština | No | `cs` |
+| `da` | Dansk | No | `da` |
+| `de` | Deutsch | No | `de` |
+| `es` | Español | No | `es` |
+| `fi` | Suomi | No | `fi` |
+| `fr` | Français | No | `fr` |
+| `he` | עברית | Yes | `iw` |
+| `hi` | हिन्दी | No | `hi` |
+| `hu` | Magyar | No | `hu` |
+| `id` | Bahasa Indonesia | No | `id` |
+| `it` | Italiano | No | `it` |
+| `ja` | 日本語 | No | `ja` |
+| `ko` | 한국어 | No | `ko` |
+| `ms` | Bahasa Melayu | No | `ms` |
+| `nl` | Nederlands | No | `nl` |
+| `no` | Norsk | No | `no` |
+| `phi` | Filipino | No | `tl` |
+| `pl` | Polski | No | `pl` |
+| `pt` | Português (Portugal) | No | `pt` |
+| `pt-BR` | Português (Brasil) | No | `pt` |
+| `ro` | Română | No | `ro` |
+| `ru` | Русский | No | `ru` |
+| `sk` | Slovenčina | No | `sk` |
+| `sv` | Svenska | No | `sv` |
+| `th` | ไทย | No | `th` |
+| `tr` | Türkçe | No | `tr` |
+| `uk-UA` | Українська | No | `uk` |
+| `vi` | Tiếng Việt | No | `vi` |
+| `zh-CN` | 中文 (简体) | No | `zh-CN` |
+
+## Adding a New Language
+
+### 1. Register the Locale
+Edit `src/i18n/config.ts`:
+```ts
+// Add to LOCALES array
+"xx",
+// Add to LANGUAGES array
+{ code: "xx", label: "XX", name: "Language Name", flag: "🏳️" },
+```
+
+### 2. Add to Generator
+Edit `scripts/i18n/generate-multilang.mjs` — add entry to `LOCALE_SPECS`:
+```js
+{
+  code: "xx",
+  googleTl: "xx",
+  label: "XX",
+  flag: "🏳️",
+  languageName: "Language Name",
+  readmeName: "Language Name",
+  docsName: "Language Name",
+},
+```
+
+### 3. Generate Initial Translation
+```bash
+node scripts/i18n/generate-multilang.mjs messages
+```
+This creates `src/i18n/messages/xx.json` auto-translated from `en.json` via Google Translate.
+
+### 4. Review & Fix Auto-Translations
+Auto-translations are a starting point. Review manually for:
+- Technical accuracy
+- Context-appropriate terminology
+- Proper handling of placeholders (`{count}`, `{value}`, etc.)
+
+### 5. Validate
+```bash
+python3 scripts/validate_translation.py quick -l xx
+python3 scripts/validate_translation.py diff common -l xx
+```
+
+### 6. Generate Translated Documentation
+```bash
+node scripts/i18n/generate-multilang.mjs docs
+```
+
+## Auto-Translation Pipeline
+
+### generate-multilang.mjs (Google Translate)
+
+**Primary auto-translation engine** — uses Google Translate free API to generate translations for UI strings, READMEs, and documentation.
+
+```bash
+node scripts/i18n/generate-multilang.mjs [messages|readme|docs|all]
+```
+
+| Mode | What it does |
+|------|-------------|
+| `messages` | Translates missing keys in `src/i18n/messages/{locale}.json` from `en.json` |
+| `readme` | Translates `README.md` into all locales as `README.{code}.md` in project root |
+| `docs` | Translates `DOC_SOURCE_FILES` into `docs/i18n/{locale}/{docName}` |
+| `all` | Runs all three modes |
+
+**Features:**
+- **Text protection**: Masks code blocks (```` ``` ````), inline code (`` ` ``), markdown links/images (`[text](url)`), HTML tags, tables, and ICU placeholders (`{count}`, `{value}`, `{total}`, etc.) before translation, then restores them
+- **Chunked batching**: Joins multiple strings with `__OMNIROUTE_I18N_SEPARATOR__` delimiters to minimize API calls (max 1800 chars per request)
+- **In-memory cache**: Avoids redundant API calls for repeated strings within a session
+- **Retry logic**: Exponential backoff (up to 5 attempts with 300ms × attempt delay) for 429/5xx errors
+- **Timeout**: 20 seconds per request
+- **Skip existing**: If target file already exists, it is NOT overwritten
+
+**Important behaviors:**
+- `docs/i18n/README.md` is **regenerated** each run — it's an auto-generated index of all docs
+- Root `README.{code}.md` files are only created if they don't exist (skips locales in `EXISTING_README_CODES`)
+- Language bars (`🌐 **Languages:** ...`) are automatically inserted/updated in all translated docs
+
+### i18n_autotranslate.py (LLM-based)
+
+**Secondary translator** — uses any OpenAI-compatible LLM API (including OmniRoute itself) to translate existing `docs/i18n/` markdown files. Best for polishing or re-translating docs with better quality than Google Translate.
+
+```bash
+python3 scripts/i18n_autotranslate.py \
+  --api-url http://localhost:20128/v1 \
+  --api-key sk-your-key \
+  --model gpt-4o
+```
+
+**Features:**
+- Scans `docs/i18n/` markdown files for English paragraphs
+- Skips code blocks, tables, and already-translated content
+- Sends paragraphs to LLM with technical translation system prompt
+- Supports all 30 languages
+
+## Validation & QA
+
+### validate_translation.py
+
+**Translation validator** — compares any locale JSON against `en.json` and reports issues.
+
+```bash
+# Quick check (counts only)
+python3 scripts/validate_translation.py quick -l cs
+# Output:
+# Missing: 0
+# Untranslated: 0
+# Ignored (UNTRANSLATABLE_KEYS): 236
+
+# Detailed diff by category
+python3 scripts/validate_translation.py diff common -l cs
+python3 scripts/validate_translation.py diff settings -l cs
+
+# Export to CSV
+python3 scripts/validate_translation.py csv -l cs > report.csv
+
+# Export to Markdown
+python3 scripts/validate_translation.py md -l cs > report.md
+
+# Full report (default)
+python3 scripts/validate_translation.py -l cs
+```
+
+**Detects:**
+- **Missing keys** — keys in `en.json` but not in locale file
+- **Extra keys** — keys in locale file but not in `en.json`
+- **Untranslated keys** — keys where locale value equals English source (excluding allowlist)
+- **Placeholder mismatches** — ICU placeholders that don't match between source and translation
+
+**Exit codes:**
+| Code | Meaning |
+|------|---------|
+| 0 | OK |
+| 1 | Generic error |
+| 2 | Missing strings (hard error) |
+| 3 | Untranslated warning (soft) |
+
+**Environment:** Set `TRANSLATION_LANG=cs` or use `-l cs` flag.
+
+### check_translations.py
+
+**Code-to-JSON key checker** — scans `src/**/*.tsx` and `src/**/*.ts` for `useTranslations()` calls and verifies all referenced keys exist in `en.json`.
+
+```bash
+# Basic check
+python3 scripts/check_translations.py
+
+# Verbose output
+python3 scripts/check_translations.py --verbose
+
+# Auto-fix (adds missing keys to en.json)
+python3 scripts/check_translations.py --fix
+```
+
+### generate-qa-checklist.mjs
+
+**Static analysis QA** — scans Next.js page files for i18n risk metrics and generates a Markdown report.
+
+```bash
+node scripts/i18n/generate-qa-checklist.mjs
+```
+
+**Checks:**
+- Fixed-width class usage (overflow risk)
+- Directional left/right classes (RTL risk)
+- Clipping-prone patterns
+- Locale parity (missing/extra keys vs `en.json`)
+- README language selector bars in priority locales (`es`, `fr`, `de`, `ja`, `ar`)
+
+**Output:** `docs/reports/i18n-qa-checklist-{date}.md`
+
+### run-visual-qa.mjs
+
+**Visual QA via Playwright** — takes screenshots of all dashboard routes in multiple locales and viewports, then evaluates page health.
+
+```bash
+# Default: es, fr, de, ja, ar on localhost:20128
+node scripts/i18n/run-visual-qa.mjs
+
+# Custom base URL and locales
+QA_BASE_URL=http://staging.example.com QA_LOCALES=de,fr node scripts/i18n/run-visual-qa.mjs
+
+# Custom routes
+QA_ROUTES=/dashboard/settings,/dashboard/providers node scripts/i18n/run-visual-qa.mjs
+```
+
+**Detects:**
+- Text overflow
+- Element clipping
+- RTL layout mismatches
+
+**Output:** `docs/reports/i18n-visual-qa-{date}.md` + JSON report
+
+## Managing Untranslatable Keys
+
+### untranslatable-keys.json
+
+**File:** `scripts/i18n/untranslatable-keys.json`
+
+Allowlist of keys that should remain identical to English source. Used by `validate_translation.py` to avoid false-positive "untranslated" warnings.
+
+```json
+{
+  "description": "Keys that should remain untranslated...",
+  "keys": [
+    "common.model",
+    "common.oauth",
+    "health.cpu",
+    ...
+  ]
+}
+```
+
+**What belongs here:**
+- Brand/product names: `landing.brandName`, `common.social-github`
+- Technical terms/acronyms: `health.cpu`, `mcpDashboard.pid`, `settings.ai`
+- ICU/format strings: `apiManager.modelsCount`, `health.millisecondsShort`
+- Placeholder values: `providers.openaiBaseUrlPlaceholder`, `cliTools.baseUrlPlaceholder`
+- Protocol names: `common.http`, `common.oauth`, `providers.oauth2Label`
+- Navigation sections: `sidebar.primarySection`, `sidebar.cliSection`
+
+**To add a key:** Edit the `keys` array in `scripts/i18n/untranslatable-keys.json` and re-run validation.
+
+## CI Integration
+
+### GitHub Actions (`.github/workflows/ci.yml`)
+
+The CI pipeline validates all locales on every push and PR:
+
+1. **`i18n-matrix` job** — dynamically discovers all locale files (excluding `en.json`)
+2. **`i18n` job** — runs `validate_translation.py quick -l '<lang>'` for each locale in parallel
+3. **`ci-summary` job** — aggregates results into a dashboard summary
+
+```yaml
+# i18n-matrix: discovers languages
+LANGS=$(ls src/i18n/messages/*.json | xargs -n1 basename | sed 's/.json$//' | grep -v '^en$')
+
+# i18n: validates each language
+python3 scripts/validate_translation.py quick -l '${{ matrix.lang }}'
+```
+
+**Dashboard output:**
+```
+## 🌍 Translations
+| Metric | Value |
+|--------|------|
+| Languages checked | 30 |
+| Total untranslated | 0 |
+
+✅ All translations complete
+```
+
+## File Structure
+
+```
+src/i18n/
+├── config.ts                    # Locale definitions (30 locales, RTL config)
+├── request.ts                   # Runtime locale resolution
+└── messages/
+    ├── en.json                  # Source of truth (~2800 keys)
+    ├── cs.json                  # Czech translation
+    ├── de.json                  # German translation
+    └── ...                      # 30 locale files total
+
+scripts/
+├── i18n/
+│   ├── generate-multilang.mjs   # Auto-translation engine (Google Translate, 888 lines)
+│   ├── generate-qa-checklist.mjs # Static analysis QA
+│   ├── run-visual-qa.mjs        # Playwright visual QA
+│   └── untranslatable-keys.json # Allowlist for validation (236 keys)
+├── validate_translation.py      # Translation validator
+├── check_translations.py        # Code-to-JSON key checker
+└── i18n_autotranslate.py        # LLM-based doc translator
+
+.github/workflows/
+└── ci.yml                       # i18n validation in CI matrix
+
+docs/
+├── I18N.md                      # This file — i18n toolchain documentation
+├── i18n/
+│   ├── README.md                # Auto-generated language index
+│   ├── cs/                      # Czech docs
+│   │   └── docs/
+│   │       ├── I18N.md          # Czech translation of this file
+│   │       └── ...
+│   ├── de/                      # German docs
+│   └── ...                      # 30 locale directories
+└── reports/
+    ├── i18n-qa-checklist-*.md   # Static analysis reports
+    └── i18n-visual-qa-*.md      # Visual QA reports
+```
+
+## Best Practices
+
+### When Editing Translations
+1. **Always edit `en.json` first** — it's the source of truth
+2. **Run `generate-multilang.mjs messages`** to propagate new keys to all locales
+3. **Review auto-translations** — Google Translate is a starting point, not final
+4. **Validate before committing** — `python3 scripts/validate_translation.py quick -l <lang>`
+5. **Update `untranslatable-keys.json`** if a key should remain in English
+
+### Placeholder Safety
+- ICU placeholders (`{count}`, `{value}`, `{total}`, `{seconds}`) must be preserved exactly
+- Plural formats (`{count, plural, one {# model} other {# models}}`) must maintain structure
+- The validator detects placeholder mismatches automatically
+
+### Adding New Translation Keys in Code
+```tsx
+// Use namespaced keys
+const t = useTranslations("settings");
+t("cacheSettings"); // maps to settings.cacheSettings in JSON
+
+// Run check_translations.py to verify keys exist
+python3 scripts/check_translations.py --verbose
+```
+
+### RTL Considerations
+- Arabic (`ar`) and Hebrew (`he`) are RTL locales
+- Avoid hardcoded `left`/`right` CSS — use `start`/`end` logical properties
+- Visual QA catches RTL layout mismatches via `run-visual-qa.mjs`
+
+## Known Issues & History
+
+### `in.json` → `hi.json` Fix
+The generator originally used `code: "in"` (deprecated Google Translate code) for Hindi instead of the correct ISO 639-1 `hi`. This created an orphaned `in.json` duplicate of `hi.json`. Fixed by changing `code: "in"` to `code: "hi"` in `generate-multilang.mjs` and removing the orphaned file.
+
+### `docs/i18n/README.md` Is Auto-Generated
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+
+### External Untranslatable Keys List
+The `untranslatable-keys.json` allowlist was moved from an inline Python set in `validate_translation.py` to an external JSON file for easier maintenance. The validator loads it at runtime.
+
+### `generate-multilang.mjs` Hindi Code Fix
+The generator originally used `code: "in"` (deprecated Google Translate code) for Hindi instead of the correct ISO 639-1 `hi`. This was introduced in upstream commit `952b0b22c` by `diegosouzapw`. Fixed by changing `code: "in"` to `code: "hi"` in the `LOCALE_SPECS` array and removing the orphaned `in.json` file.
+
+### `validate_translation.py` Ignored Count Output
+The `quick` check now displays the count of ignored keys from `untranslatable-keys.json`:
+```
+Missing: 0
+Untranslated: 0
+Ignored (UNTRANSLATABLE_KEYS): 236
+```

docs/MCP-SERVER.md

@@ -0,0 +1,83 @@
+# OmniRoute MCP Server Documentation
+
+> Model Context Protocol server with 16 intelligent tools
+
+## Installation
+
+OmniRoute MCP is built-in. Start it with:
+
+```bash
+omniroute --mcp
+```
+
+Or via the open-sse transport:
+
+```bash
+# HTTP streamable transport (port 20130)
+omniroute --dev  # MCP auto-starts on /mcp endpoint
+```
+
+## IDE Configuration
+
+See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup.
+
+---
+
+## Essential Tools (8)
+
+| Tool                            | Description                              |
+| :------------------------------ | :--------------------------------------- |
+| `omniroute_get_health`          | Gateway health, circuit breakers, uptime |
+| `omniroute_list_combos`         | All configured combos with models        |
+| `omniroute_get_combo_metrics`   | Performance metrics for a specific combo |
+| `omniroute_switch_combo`        | Switch active combo by ID/name           |
+| `omniroute_check_quota`         | Quota status per provider or all         |
+| `omniroute_route_request`       | Send a chat completion through OmniRoute |
+| `omniroute_cost_report`         | Cost analytics for a time period         |
+| `omniroute_list_models_catalog` | Full model catalog with capabilities     |
+
+## Advanced Tools (8)
+
+| Tool                               | Description                                                 |
+| :--------------------------------- | :---------------------------------------------------------- |
+| `omniroute_simulate_route`         | Dry-run routing simulation with fallback tree               |
+| `omniroute_set_budget_guard`       | Session budget with degrade/block/alert actions             |
+| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset               |
+| `omniroute_test_combo`             | Live-test all models in a combo via a real upstream request |
+| `omniroute_get_provider_metrics`   | Detailed metrics for one provider                           |
+| `omniroute_best_combo_for_task`    | Task-fitness recommendation with alternatives               |
+| `omniroute_explain_route`          | Explain a past routing decision                             |
+| `omniroute_get_session_snapshot`   | Full session state: costs, tokens, errors                   |
+
+## Authentication
+
+MCP tools are authenticated via API key scopes. Each tool requires specific scopes:
+
+| Scope          | Tools                                            |
+| :------------- | :----------------------------------------------- |
+| `read:health`  | get_health, get_provider_metrics                 |
+| `read:combos`  | list_combos, get_combo_metrics                   |
+| `write:combos` | switch_combo                                     |
+| `read:quota`   | check_quota                                      |
+| `write:route`  | route_request, simulate_route, test_combo        |
+| `read:usage`   | cost_report, get_session_snapshot, explain_route |
+| `write:config` | set_budget_guard, set_resilience_profile         |
+| `read:models`  | list_models_catalog, best_combo_for_task         |
+
+## Audit Logging
+
+Every tool call is logged to `mcp_tool_audit` with:
+
+- Tool name, arguments, result
+- Duration (ms), success/failure
+- API key hash, timestamp
+
+## Files
+
+| File                                         | Purpose                                     |
+| :------------------------------------------- | :------------------------------------------ |
+| `open-sse/mcp-server/server.ts`              | MCP server creation + 16 tool registrations |
+| `open-sse/mcp-server/transport.ts`           | Stdio + HTTP transport                      |
+| `open-sse/mcp-server/auth.ts`                | API key + scope validation                  |
+| `open-sse/mcp-server/audit.ts`               | Tool call audit logging                     |
+| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers                    |

docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,33 @@
+# Release Checklist
+
+Use this checklist before tagging or publishing a new OmniRoute release.
+
+## Version and Changelog
+
+1. Bump `package.json` version (`x.y.z`) in the release branch.
+2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section:
+   - `## [x.y.z] — YYYY-MM-DD`
+3. Keep `## [Unreleased]` as the first changelog section for upcoming work.
+4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version.
+
+## API Docs
+
+1. Update `docs/openapi.yaml`:
+   - `info.version` must equal `package.json` version.
+2. Validate endpoint examples if API contracts changed.
+
+## Runtime Docs
+
+1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+3. Update localized docs if source docs changed significantly.
+
+## Automated Check
+
+Run the sync guard locally before opening PR:
+
+```bash
+npm run check:docs-sync
+```
+
+CI also runs this check in `.github/workflows/ci.yml` (lint job).

docs/TASKS.md

@@ -1,113 +0,0 @@
-# Rate Limiting & Flow Control Overhaul — Tasks
-
-> Referência: [Relatório de Análise](../walkthrough.md) · Fase docs em `/docs/phases/`
-
----
-
-## Fase 1 — Error Classification & Provider Profiles
-
-### Backend Core
-
-- [x] `constants.ts` — Substituir `COOLDOWN_MS.transient` por `transientInitial` (5s) + `transientMax` (60s)
-- [x] `constants.ts` — Adicionar `PROVIDER_PROFILES` (oauth / apikey) com cooldowns diferenciados
-- [x] `constants.ts` — Adicionar `DEFAULT_API_LIMITS` (100 RPM, 200ms minTime)
-- [x] `providerRegistry.ts` — Criar helper `getProviderCategory(providerId)` → `"oauth"` | `"apikey"`
-- [x] `accountFallback.ts` — Aceitar `provider` como parâmetro em `checkFallbackError`
-- [x] `accountFallback.ts` — Implementar backoff exponencial para 502/503/504 transientes
-- [x] `accountFallback.ts` — Calcular cooldown baseado no perfil do provedor
-- [x] `accountFallback.ts` — Adicionar helper `getProviderProfile(provider)`
-
-### Callers (propagar `provider`)
-
-- [x] `auth.ts` → `markAccountUnavailable` — Passar `provider` para `checkFallbackError`
-- [x] `combo.ts` → `handleComboChat` / `handleRoundRobinCombo` — Passar `provider` nos erros
-
-### Testes
-
-- [x] Atualizar `rate-limit-enhanced.test.mjs` — Teste "transient errors don't increase backoff" → `newBackoffLevel = 1`
-- [x] Criar `error-classification.test.mjs` — Cooldown exponencial 502, perfis OAuth/API, helper `getProviderCategory`
-
----
-
-## Fase 2 — Circuit Breaker no Combo Pipeline
-
-### Backend
-
-- [x] `combo.ts` — Importar `getCircuitBreaker` e `CircuitBreakerOpenError`
-- [x] `combo.ts` — `handleComboChat` — Verificar `breaker.canExecute()` antes de cada modelo
-- [x] `combo.ts` — `handleRoundRobinCombo` — Integrar breaker per-model
-- [x] `combo.ts` — Marcar `semaphore.markRateLimited` para 502/503/504 (não só 429)
-- [x] `combo.ts` — Implementar early exit quando todos os modelos têm breaker OPEN
-
-### Testes
-
-- [x] Criar `combo-circuit-breaker.test.mjs` — Combo skip breaker OPEN, early exit, semáforo 502
-
----
-
-## Fase 3 — Anti-Thundering Herd & Auto Rate Limit
-
-### Backend
-
-- [x] `rateLimitManager.ts` — Auto-enable para `apikey` providers com limites elevados
-- [x] `rateLimitManager.ts` — Criar limiter com defaults (100 RPM) quando não configurado
-- [x] `auth.ts` — Adicionar mutex na `markAccountUnavailable` para evitar marcação paralela
-
-### Testes
-
-- [x] Criar `thundering-herd.test.mjs` — Mutex, auto-enable, limites não restritivos
-
----
-
-## Fase 4 — Frontend Resilience UI
-
-### Settings Page
-
-- [x] `settings/page.tsx` — Adicionar tab "Resilience" (icon: `health_and_safety`) entre Routing e Pricing
-
-### Novos Componentes
-
-- [x] Criar `ResilienceTab.tsx` — Layout com 4 cards (Provider Profiles → Rate Limiting → Circuit Breakers → Policies)
-- [x] Criar `ProviderProfilesCard.tsx` — Toggle OAuth/API Key, inputs para cooldowns
-- [x] Criar `CircuitBreakerCard.tsx` — Status real-time per-provider, auto-refresh 5s, botão reset
-- [x] Criar `RateLimitOverviewCard.tsx` — Tabela providers × accounts × cooldown — **agora editável com RPM, Min Gap, Max Concurrent**
-
-### API Routes
-
-- [x] Criar `api/resilience/route.ts` — GET (estado completo + defaults mesclados) + PATCH (salvar perfis + defaults)
-- [x] Criar `api/resilience/reset/route.ts` — POST (resetar breakers + cooldowns)
-
-### Migração
-
-- [x] `PoliciesPanel.tsx` movido de Security para Resilience tab
-
----
-
-## Fase 5 — Settings Page Restructure (v0.9.0)
-
-### Tab Reorganization
-
-- [x] **Security** — Simplificado para Login/Password + IP Access Control
-- [x] **Routing** — Expandido para 6 estratégias globais com descrições
-- [x] **Resilience** — Reordenado: Provider Profiles → Rate Limiting (editável) → Circuit Breakers → Policies
-- [x] **AI** — Thinking Budget + System Prompt + Prompt Cache (movido do Advanced)
-- [x] **Advanced** — Simplificado para apenas Global Proxy
-
-### Backend Routing Strategies
-
-- [x] `auth.ts` — Implementar `random` (Fisher-Yates shuffle)
-- [x] `auth.ts` — Implementar `least-used` (sorted by lastUsedAt)
-- [x] `auth.ts` — Implementar `cost-optimized` (sorted by priority)
-- [x] `auth.ts` — Corrigir `p2c` (power-of-two-choices com health scoring)
-- [x] `settings.ts` — Expandir tipo `fallbackStrategy` para 6 valores
-
----
-
-## Verificação Final
-
-- [x] Rodar todos os testes unitários: `node --test tests/unit/*.test.mjs`
-- [x] Build do Next.js: `npm run build`
-- [x] Verificar aba Resilience no browser
-- [x] Testar persistência dos perfis (salvar → reload)
-- [x] Testar Reset All Breakers
-- [x] Verificar todas as 5 tabs reestruturadas

docs/TROUBLESHOOTING.md

@@ -1,16 +1,75 @@
 # Troubleshooting
 
+🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) | 🇨🇿 [Čeština](i18n/cs/TROUBLESHOOTING.md)
+
 Common problems and solutions for OmniRoute.
 
 ---
 
 ## Quick Fixes
 
-| Problem                       | Solution                                                           |
-| ----------------------------- | ------------------------------------------------------------------ |
-| First login not working       | Check `INITIAL_PASSWORD` in `.env` (default: `123456`)             |
-| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` |
-| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true`                                     |
+| Problem                       | Solution                                                                                  |
+| ----------------------------- | ----------------------------------------------------------------------------------------- |
+| First login not working       | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default)                                   |
+| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128`                        |
+| No logs written to disk       | Set `APP_LOG_TO_FILE=true` and verify call log capture is enabled                         |
+| EACCES: permission denied     | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute`                           |
+| Routing strategy not saving   | Update to v1.4.11+ (Zod schema fix for settings persistence)                              |
+| Login crash / blank page      | You may be on Node.js 24+ — see [Node.js Compatibility](#nodejs-compatibility) below      |
+| Proxy "fetch failed"          | Ensure proxy config is set at the correct level — see [Proxy Issues](#proxy-issues) below |
+
+---
+
+## Node.js Compatibility
+
+<a name="nodejs-compatibility"></a>
+
+### Login page crashes or shows "Module self-registration" error
+
+**Cause:** You are running Node.js 24+. The `better-sqlite3` native binary is not compatible with Node.js 24, which causes a fatal crash when the server tries to initialize the database.
+
+**Symptoms:**
+
+- Login page shows a blank screen or a server error
+- Console shows `Error: Module did not self-register` or similar native binding errors
+- Starting with v3.5.5, the login page shows an **orange warning banner** with your Node version if incompatibility is detected
+
+**Fix:**
+
+1. Install Node.js 22 LTS (recommended):
+   ```bash
+   nvm install 22
+   nvm use 22
+   ```
+2. Verify your version: `node --version` should show `v22.x.x`
+3. Reinstall OmniRoute: `npm install -g omniroute`
+4. Restart: `omniroute`
+
+> **Supported versions:** Node.js 18, 20, or 22 LTS. Node.js 24+ is **not supported**.
+
+---
+
+## Proxy Issues
+
+<a name="proxy-issues"></a>
+
+### Provider validation shows "fetch failed"
+
+**Cause:** The API key validation endpoint (`POST /api/providers/validate`) was previously bypassing proxy configuration, causing failures in environments that require proxy routing.
+
+**Fix (v3.5.5+):** This is now fixed. Provider validation routes through `runWithProxyContext`, honoring provider-level and global proxy settings automatically.
+
+### Token health check fails with "fetch failed"
+
+**Cause:** Background OAuth token refresh was not resolving proxy configuration per connection.
+
+**Fix (v3.5.5+):** The token health check scheduler now resolves proxy config per connection before attempting refresh. Update to v3.5.5+.
+
+### SOCKS5 proxy returns "invalid onRequestStart method"
+
+**Cause:** On Node.js 22, the undici@8 dispatcher is incompatible with Node's built-in `fetch()` implementation.
+
+**Fix (v3.5.5+):** OmniRoute now uses undici's own `fetch()` function when a proxy dispatcher is active, ensuring consistent behavior. Update to v3.5.5+.
 
 ---
 
@@ -93,16 +152,18 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
 
 1. Check usage stats in Dashboard → Usage
 2. Switch primary model to GLM/MiniMax
-3. Use free tier (Gemini CLI, iFlow) for non-critical tasks
+3. Use free tier (Gemini CLI, Qoder) for non-critical tasks
 4. Set cost budgets per API key: Dashboard → API Keys → Budget
 
 ---
 
 ## Debugging
 
-### Enable Request Logs
+### Enable Log Files
 
-Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory.
+Set `APP_LOG_TO_FILE=true` in your `.env` file. Application logs are written under `logs/`.
+Request artifacts are stored under `${DATA_DIR}/call_logs/` when the call log pipeline is
+enabled in settings.
 
 ### Check Provider Health
 
@@ -116,9 +177,10 @@ curl http://localhost:20128/api/monitoring/health
 
 ### Runtime Storage
 
-- Main state: `${DATA_DIR}/db.json` (providers, combos, aliases, keys, settings)
-- Usage: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
-- Request logs: `<repo>/logs/...` (when `ENABLE_REQUEST_LOGS=true`)
+- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings)
+- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/call_logs/`
+- Application logs: `<repo>/logs/...` (when `APP_LOG_TO_FILE=true`)
+- Call log artifacts: `${DATA_DIR}/call_logs/YYYY-MM-DD/...` when the call log pipeline is enabled
 
 ---
 
@@ -206,6 +268,41 @@ When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex
 
 ---
 
+## Optional RAG / LLM failure taxonomy (16 problems)
+
+Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong.
+
+In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself.
+
+If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers:
+
+- retrieval drift and broken context boundaries
+- empty or stale indexes and vector stores
+- embedding versus semantic mismatch
+- prompt assembly and context window issues
+- logic collapse and overconfident answers
+- long chain and agent coordination failures
+- multi agent memory and role drift
+- deployment and bootstrap ordering problems
+
+The idea is simple:
+
+1. When you investigate a bad response, capture:
+   - user task and request
+   - route or provider combo in OmniRoute
+   - any RAG context used downstream (retrieved documents, tool calls, etc)
+2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`).
+3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs.
+4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy.
+
+Full text and concrete recipes live here (MIT license, text only):
+
+[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
+
+You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute.
+
+---
+
 ## Still Stuck?
 
 - **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)

docs/USER_GUIDE.md

@@ -1,5 +1,7 @@
 # User Guide
 
+🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) | 🇨🇿 [Čeština](i18n/cs/USER_GUIDE.md)
+
 Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
 
 ---
@@ -37,11 +39,11 @@ Complete guide for configuring providers, creating combos, integrating CLI tools
 | **💰 CHEAP**        | GLM-4.7           | $0.6/1M     | Daily 10AM       | Budget backup        |
 |                     | MiniMax M2.1      | $0.2/1M     | 5-hour rolling   | Cheapest option      |
 |                     | Kimi K2           | $9/mo flat  | 10M tokens/mo    | Predictable cost     |
-| **🆓 FREE**         | iFlow             | $0          | Unlimited        | 8 models free        |
+| **🆓 FREE**         | Qoder             | $0          | Unlimited        | 8 models free        |
 |                     | Qwen              | $0          | Unlimited        | 3 models free        |
 |                     | Kiro              | $0          | Unlimited        | Claude free          |
 
-**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost!
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
 
 ---
 
@@ -162,7 +164,7 @@ Dashboard → Providers → Connect GitHub
 Models:
   gh/gpt-5
   gh/claude-4.5-sonnet
-  gh/gemini-3-pro
+  gh/gemini-3.1-pro-preview
 ```
 
 ### 💰 Cheap Providers
@@ -191,10 +193,10 @@ Models:
 
 ### 🆓 FREE Providers
 
-#### iFlow (8 FREE models)
+#### Qoder (8 FREE models)
 
 ```bash
-Dashboard → Connect iFlow → OAuth login → Unlimited usage
+Dashboard → Connect Qoder → OAuth login → Unlimited usage
 
 Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1
 ```
@@ -316,6 +318,25 @@ Model: cc/claude-opus-4-6
 
 ## 🚀 Deployment
 
+### Global npm install (Recommended)
+
+```bash
+npm install -g omniroute
+
+# Create config directory
+mkdir -p ~/.omniroute
+
+# Create .env file (see .env.example)
+cp .env.example ~/.omniroute/.env
+
+# Start server
+omniroute
+# Or with custom port:
+omniroute --port 3000
+```
+
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
 ### VPS Deployment
 
 ```bash
@@ -335,6 +356,43 @@ npm run start
 # Or: pm2 start npm --name omniroute -- start
 ```
 
+### PM2 Deployment (Low Memory)
+
+For servers with limited RAM, use the memory limit option:
+
+```bash
+# With 512MB limit (default)
+pm2 start npm --name omniroute -- start
+
+# Or with custom memory limit
+OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
+
+# Or using ecosystem.config.js
+pm2 start ecosystem.config.js
+```
+
+Create `ecosystem.config.js`:
+
+```javascript
+module.exports = {
+  apps: [
+    {
+      name: "omniroute",
+      script: "npm",
+      args: "start",
+      env: {
+        NODE_ENV: "production",
+        OMNIROUTE_MEMORY_MB: "512",
+        JWT_SECRET: "your-secret",
+        INITIAL_PASSWORD: "your-password",
+      },
+      node_args: "--max-old-space-size=512",
+      max_memory_restart: "300M",
+    },
+  ],
+};
+```
+
 ### Docker
 
 ```bash
@@ -347,22 +405,130 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat
 
 For host-integrated mode with CLI binaries, see the Docker section in the main docs.
 
+### Void Linux (xbps-src)
+
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+<details>
+<summary><b>View xbps-src template</b></summary>
+
+```bash
+# Template file for 'omniroute'
+pkgname=omniroute
+version=3.2.4
+revision=1
+hostmakedepends="nodejs python3 make"
+depends="openssl"
+short_desc="Universal AI gateway with smart routing for multiple LLM providers"
+maintainer="zenobit <zenobit@disroot.org>"
+license="MIT"
+homepage="https://github.com/diegosouzapw/OmniRoute"
+distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
+checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
+system_accounts="_omniroute"
+omniroute_homedir="/var/lib/omniroute"
+export NODE_ENV=production
+export npm_config_engine_strict=false
+export npm_config_loglevel=error
+export npm_config_fund=false
+export npm_config_audit=false
+
+do_build() {
+	# Determine target CPU arch for node-gyp
+	local _gyp_arch
+	case "$XBPS_TARGET_MACHINE" in
+		aarch64*) _gyp_arch=arm64 ;;
+		armv7*|armv6*) _gyp_arch=arm ;;
+		i686*) _gyp_arch=ia32 ;;
+		*) _gyp_arch=x64 ;;
+	esac
+
+	# 1) Install all deps – skip scripts
+	NODE_ENV=development npm ci --ignore-scripts
+
+	# 2) Build the Next.js standalone bundle
+	npm run build
+
+	# 3) Copy static assets into standalone
+	cp -r .next/static .next/standalone/.next/static
+	[ -d public ] && cp -r public .next/standalone/public || true
+
+	# 4) Compile better-sqlite3 native binding
+	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+
+	# 5) Place the compiled binding into the standalone bundle
+	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+	mkdir -p "$_bs3_release"
+	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+
+	# 6) Remove arch-specific sharp bundles
+	rm -rf .next/standalone/node_modules/@img
+
+	# 7) Copy pino runtime deps omitted by Next.js static analysis:
+	for _mod in pino-abstract-transport split2 process-warning; do
+		cp -r "node_modules/$_mod" .next/standalone/node_modules/
+	done
+}
+
+do_check() {
+	npm run test:unit
+}
+
+do_install() {
+	vmkdir usr/lib/omniroute/.next
+	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+
+	# Prevent removal of empty Next.js app router dirs by the post-install hook
+	for _d in \
+		.next/standalone/.next/server/app/dashboard \
+		.next/standalone/.next/server/app/dashboard/settings \
+		.next/standalone/.next/server/app/dashboard/providers; do
+		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+	done
+
+	cat > "${WRKDIR}/omniroute" <<'EOF'
+#!/bin/sh
+export PORT="${PORT:-20128}"
+export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
+export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
+mkdir -p "${DATA_DIR}"
+exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
+EOF
+	vbin "${WRKDIR}/omniroute"
+}
+
+post_install() {
+	vlicense LICENSE
+}
+```
+
+</details>
+
 ### Environment Variables
 
-| Variable              | Default                              | Description                                             |
-| --------------------- | ------------------------------------ | ------------------------------------------------------- |
-| `JWT_SECRET`          | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**)           |
-| `INITIAL_PASSWORD`    | `123456`                             | First login password                                    |
-| `DATA_DIR`            | `~/.omniroute`                       | Data directory (db, usage, logs)                        |
-| `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                           |
-| `CLOUD_URL`           | `https://omniroute.dev`              | Cloud sync endpoint base URL                            |
-| `API_KEY_SECRET`      | `endpoint-proxy-api-key-secret`      | HMAC secret for generated API keys                      |
-| `REQUIRE_API_KEY`     | `false`                              | Enforce Bearer API key on `/v1/*`                       |
-| `ENABLE_REQUEST_LOGS` | `false`                              | Enables request/response logs                           |
-| `AUTH_COOKIE_SECURE`  | `false`                              | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| Variable                                | Default                              | Description                                                                                               |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET`                            | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**)                                                             |
+| `INITIAL_PASSWORD`                      | `123456`                             | First login password                                                                                      |
+| `DATA_DIR`                              | `~/.omniroute`                       | Data directory (db, usage, logs)                                                                          |
+| `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                                                                             |
+| `CLOUD_URL`                             | `https://omniroute.dev`              | Cloud sync endpoint base URL                                                                              |
+| `API_KEY_SECRET`                        | `endpoint-proxy-api-key-secret`      | HMAC secret for generated API keys                                                                        |
+| `REQUIRE_API_KEY`                       | `false`                              | Enforce Bearer API key on `/v1/*`                                                                         |
+| `ALLOW_API_KEY_REVEAL`                  | `false`                              | Allow Api Manager to copy full API keys on demand                                                         |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70`                                 | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP`            | `false`                              | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work                |
+| `APP_LOG_TO_FILE`                       | `true`                               | Enables application and audit log output to disk                                                          |
+| `AUTH_COOKIE_SECURE`                    | `false`                              | Force `Secure` auth cookie (behind HTTPS reverse proxy)                                                   |
+| `CLOUDFLARED_BIN`                       | unset                                | Use an existing `cloudflared` binary instead of managed download                                          |
+| `CLOUDFLARED_PROTOCOL`                  | `http2`                              | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`)                                          |
+| `OMNIROUTE_MEMORY_MB`                   | `512`                                | Node.js heap limit in MB                                                                                  |
+| `PROMPT_CACHE_MAX_SIZE`                 | `50`                                 | Max prompt cache entries                                                                                  |
+| `SEMANTIC_CACHE_MAX_SIZE`               | `100`                                | Max semantic cache entries                                                                                |
 
 For the full environment variable reference, see the [README](../README.md).
 
@@ -385,7 +551,7 @@ For the full environment variable reference, see the [README](../README.md).
 
 **MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
 
-**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
 
 **Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
 
@@ -433,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \
 
 Or use Dashboard: **Providers → [Provider] → Custom Models**.
 
+Notes:
+
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
+
 ### Dedicated Provider Routes
 
 Route requests directly to a specific provider with model validation:
@@ -477,6 +648,17 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`).
 - Automatic background sync with timeout + fail-fast
 - Prefer server-side `BASE_URL`/`CLOUD_URL` in production
 
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
 ### LLM Gateway Intelligence (Phase 9)
 
 - **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
@@ -517,6 +699,22 @@ Configure via **Dashboard → Settings → Routing**.
 | **Least Used**                 | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly        |
 | **Cost Optimized**             | Routes to the account with the lowest priority value, optimizing for lowest-cost providers       |
 
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
+X-Session-Id: your-session-key
+```
+
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
+
+If you use Nginx and send underscore-form headers, enable:
+
+```nginx
+underscores_in_headers on;
+```
+
 #### Wildcard Model Aliases
 
 Create wildcard patterns to remap model names:
@@ -576,11 +774,11 @@ OmniRoute implements provider-level resilience with four components:
 
 Manage database backups in **Dashboard → Settings → System & Storage**.
 
-| Action                   | Description                                                                                                                    |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
-| **Export Database**      | Downloads the current SQLite database as a `.sqlite` file                                                                      |
-| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
-| **Import Database**      | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created                          |
+| Action                   | Description                                                                                                                                    |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database**      | Downloads the current SQLite database as a `.sqlite` file                                                                                      |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata                 |
+| **Import Database**      | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
 
 ```bash
 # API: Export database
@@ -606,10 +804,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \
 
 ### Settings Dashboard
 
-The settings page is organized into 5 tabs for easy navigation:
+The settings page is organized into 6 tabs for easy navigation:
 
 | Tab            | Contents                                                                                       |
 | -------------- | ---------------------------------------------------------------------------------------------- |
+| **General**    | System storage tools, appearance settings, theme controls, and per-item sidebar visibility     |
 | **Security**   | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking      |
 | **Routing**    | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults   |
 | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
@@ -694,3 +893,55 @@ Access via **Dashboard → Health**. Real-time system health overview with 6 car
 | **Latency Telemetry** | p50/p95/p99 latency aggregation per provider                |
 
 **Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
+
+## 🖥️ Desktop Application (Electron)
+
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Installation
+
+```bash
+# From the electron directory:
+cd electron
+npm install
+
+# Development mode (connect to running Next.js dev server):
+npm run dev
+
+# Production mode (uses standalone build):
+npm start
+```
+
+### Building Installers
+
+```bash
+cd electron
+npm run build          # Current platform
+npm run build:win      # Windows (.exe NSIS)
+npm run build:mac      # macOS (.dmg universal)
+npm run build:linux    # Linux (.AppImage)
+```
+
+Output → `electron/dist-electron/`
+
+### Key Features
+
+| Feature                     | Description                                          |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness**        | Polls server before showing window (no blank screen) |
+| **System Tray**             | Minimize to tray, change port, quit from tray menu   |
+| **Port Management**         | Change server port from tray (auto-restarts server)  |
+| **Content Security Policy** | Restrictive CSP via session headers                  |
+| **Single Instance**         | Only one app instance can run at a time              |
+| **Offline Mode**            | Bundled Next.js server works without internet        |
+
+### Environment Variables
+
+| Variable              | Default | Description                      |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT`      | `20128` | Server port                      |
+| `OMNIROUTE_MEMORY_MB` | `512`   | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)

docs/VM_DEPLOYMENT_GUIDE.md

@@ -1,69 +1,71 @@
-# OmniRoute — Guia de Deploy em VM com Cloudflare
+# OmniRoute — Deployment Guide on VM with Cloudflare
 
-Guia completo para instalar e configurar o OmniRoute em uma VM (VPS) com domínio gerenciado via Cloudflare.
+🌐 **Languages:** 🇺🇸 [English](VM_DEPLOYMENT_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/VM_DEPLOYMENT_GUIDE.md) | 🇪🇸 [Español](i18n/es/VM_DEPLOYMENT_GUIDE.md) | 🇫🇷 [Français](i18n/fr/VM_DEPLOYMENT_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/VM_DEPLOYMENT_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/VM_DEPLOYMENT_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/VM_DEPLOYMENT_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/VM_DEPLOYMENT_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/VM_DEPLOYMENT_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/VM_DEPLOYMENT_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/VM_DEPLOYMENT_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/VM_DEPLOYMENT_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/VM_DEPLOYMENT_GUIDE.md) | 🇧🇬 [Български](i18n/bg/VM_DEPLOYMENT_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/VM_DEPLOYMENT_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/VM_DEPLOYMENT_GUIDE.md) | 🇮🇱 [עברית](i18n/he/VM_DEPLOYMENT_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/VM_DEPLOYMENT_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/VM_DEPLOYMENT_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/VM_DEPLOYMENT_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/VM_DEPLOYMENT_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/VM_DEPLOYMENT_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/VM_DEPLOYMENT_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/VM_DEPLOYMENT_GUIDE.md) | 🇷🇴 [Română](i18n/ro/VM_DEPLOYMENT_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/VM_DEPLOYMENT_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/VM_DEPLOYMENT_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/VM_DEPLOYMENT_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/VM_DEPLOYMENT_GUIDE.md) | 🇨🇿 [Čeština](i18n/cs/VM_DEPLOYMENT_GUIDE.md)
+
+Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare.
 
 ---
 
-## Pré-Requisitos
+## Prerequisites
 
-| Item        | Mínimo                   | Recomendado      |
-| ----------- | ------------------------ | ---------------- |
-| **CPU**     | 1 vCPU                   | 2 vCPU           |
-| **RAM**     | 1 GB                     | 2 GB             |
-| **Disco**   | 10 GB SSD                | 25 GB SSD        |
-| **SO**      | Ubuntu 22.04 LTS         | Ubuntu 24.04 LTS |
-| **Domínio** | Registrado no Cloudflare | —                |
-| **Docker**  | Docker Engine 24+        | Docker 27+       |
+| Item       | Minimum                  | Recommended      |
+| ---------- | ------------------------ | ---------------- |
+| **CPU**    | 1 vCPU                   | 2 vCPU           |
+| **RAM**    | 1 GB                     | 2 GB             |
+| **Disk**   | 10 GB SSD                | 25 GB SSD        |
+| **OS**     | Ubuntu 22.04 LTS         | Ubuntu 24.04 LTS |
+| **Domain** | Registered on Cloudflare | —                |
+| **Docker** | Docker Engine 24+        | Docker 27+       |
 
-**Providers testados**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail.
+**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail.
 
 ---
 
-## 1. Configurar a VM
+## 1. Configure the VM
 
-### 1.1 Criar a instância
+### 1.1 Create the instance
 
-No seu provider de VPS preferido:
+On your preferred VPS provider:
 
-- Escolha Ubuntu 24.04 LTS
-- Selecione o plano mínimo (1 vCPU / 1 GB RAM)
-- Defina uma senha forte para root ou configure SSH key
-- Anote o **IP público** (ex: `203.0.113.10`)
+- Choose Ubuntu 24.04 LTS
+- Select the minimum plan (1 vCPU / 1 GB RAM)
+- Set a strong root password or configure SSH key
+- Note the **public IP** (e.g., `203.0.113.10`)
 
-### 1.2 Conectar via SSH
+### 1.2 Connect via SSH
 
 ```bash
 ssh root@203.0.113.10
 ```
 
-### 1.3 Atualizar o sistema
+### 1.3 Update the system
 
 ```bash
 apt update && apt upgrade -y
 ```
 
-### 1.4 Instalar Docker
+### 1.4 Install Docker
 
 ```bash
-# Instalar dependências
+# Install dependencies
 apt install -y ca-certificates curl gnupg
 
-# Adicionar repositório oficial do Docker
+# Add official Docker repository
 install -m 0755 -d /etc/apt/keyrings
 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
 chmod a+r /etc/apt/keyrings/docker.gpg
-echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $ (. /etc/os-release && echo “$VERSION_CODENAME”) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
 apt update
 apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
 ```
 
-### 1.5 Instalar nginx
+### 1.5 Install nginx
 
 ```bash
 apt install -y nginx
 ```
 
-### 1.6 Configurar Firewall (UFW)
+### 1.6 Configure Firewall (UFW)
 
 ```bash
 ufw default deny incoming
@@ -74,29 +76,29 @@ ufw allow 443/tcp   # HTTPS
 ufw enable
 ```
 
-> **Dica**: Para segurança máxima, restrinja as portas 80 e 443 apenas para IPs da Cloudflare. Veja a seção [Segurança Avançada](#segurança-avançada).
+> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section.
 
 ---
 
-## 2. Instalar o OmniRoute
+## 2. Install OmniRoute
 
-### 2.1 Criar diretório de configuração
+### 2.1 Create configuration directory
 
 ```bash
 mkdir -p /opt/omniroute
 ```
 
-### 2.2 Criar arquivo de variáveis de ambiente
+### 2.2 Create environment variables file
 
 ```bash
-cat > /opt/omniroute/.env << 'EOF'
-# === Segurança ===
-JWT_SECRET=ALTERE-PARA-CHAVE-SECRETA-UNICA-64-CHARS
-INITIAL_PASSWORD=SuaSenhaSegura123!
-API_KEY_SECRET=ALTERE-PARA-OUTRA-CHAVE-SECRETA
-STORAGE_ENCRYPTION_KEY=ALTERE-PARA-TERCEIRA-CHAVE-SECRETA
+cat > /opt/omniroute/.env << ‘EOF’
+# === Security ===
+JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY
+INITIAL_PASSWORD=YourSecurePassword123!
+API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY
+STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY
 STORAGE_ENCRYPTION_KEY_VERSION=v1
-MACHINE_ID_SALT=ALTERE-PARA-SALT-UNICO
+MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT
 
 # === App ===
 PORT=20128
@@ -104,23 +106,23 @@ NODE_ENV=production
 HOSTNAME=0.0.0.0
 DATA_DIR=/app/data
 STORAGE_DRIVER=sqlite
-ENABLE_REQUEST_LOGS=true
+APP_LOG_TO_FILE=true
 AUTH_COOKIE_SECURE=false
 REQUIRE_API_KEY=false
 
-# === Domain (altere para seu domínio) ===
+# === Domain (change to your domain) ===
 BASE_URL=https://llms.seudominio.com
 NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
 
-# === Cloud Sync (opcional) ===
+# === Cloud Sync (optional) ===
 # CLOUD_URL=https://cloud.omniroute.online
 # NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online
 EOF
 ```
 
-> ⚠️ **IMPORTANTE**: Gere chaves secretas únicas! Use `openssl rand -hex 32` para cada chave.
+> ⚠️ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key.
 
-### 2.3 Iniciar o container
+### 2.3 Start the container
 
 ```bash
 docker pull diegosouzapw/omniroute:latest
@@ -134,45 +136,45 @@ docker run -d \
   diegosouzapw/omniroute:latest
 ```
 
-### 2.4 Verificar se está rodando
+### 2.4 Verify that it is running
 
 ```bash
 docker ps | grep omniroute
 docker logs omniroute --tail 20
 ```
 
-Deve exibir: `[DB] SQLite database ready` e `listening on port 20128`.
+It should display: `[DB] SQLite database ready` and `listening on port 20128`.
 
 ---
 
-## 3. Configurar nginx (Reverse Proxy)
+## 3. Configure nginx (Reverse Proxy)
 
-### 3.1 Gerar certificado SSL (Cloudflare Origin)
+### 3.1 Generate SSL certificate (Cloudflare Origin)
 
-No painel da Cloudflare:
+In the Cloudflare dashboard:
 
-1. Vá em **SSL/TLS → Origin Server**
-2. Clique **Create Certificate**
-3. Deixe os padrões (15 anos, \*.seudominio.com)
-4. Copie o **Origin Certificate** e a **Private Key**
+1. Go to **SSL/TLS → Origin Server**
+2. Click **Create Certificate**
+3. Keep the defaults (15 years, \*.yourdomain.com)
+4. Copy the **Origin Certificate** and the **Private Key**
 
 ```bash
 mkdir -p /etc/nginx/ssl
 
-# Colar o certificado
+# Paste the certificate
 nano /etc/nginx/ssl/origin.crt
 
-# Colar a chave privada
+# Paste the private key
 nano /etc/nginx/ssl/origin.key
 
 chmod 600 /etc/nginx/ssl/origin.key
 ```
 
-### 3.2 Configuração do nginx
+### 3.2 Nginx Configuration
 
 ```bash
-cat > /etc/nginx/sites-available/omniroute << 'NGINX'
-# Default server — bloqueia acesso direto por IP
+cat > /etc/nginx/sites-available/omniroute << ‘NGINX’
+# Default server — blocks direct access via IP
 server {
     listen 80 default_server;
     listen [::]:80 default_server;
@@ -188,7 +190,7 @@ server {
 server {
     listen 443 ssl;
     listen [::]:443 ssl;
-    server_name llms.seudominio.com;  # Altere para seu domínio
+    server_name llms.yourdomain.com;  # Change to your domain
 
     ssl_certificate     /etc/nginx/ssl/origin.crt;
     ssl_certificate_key /etc/nginx/ssl/origin.key;
@@ -206,13 +208,13 @@ server {
         # WebSocket support
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
+        proxy_set_header Connection “upgrade”;
 
         # SSE (Server-Sent Events) — streaming AI responses
         proxy_buffering off;
         proxy_cache off;
-        proxy_read_timeout 300s;
-        proxy_send_timeout 300s;
+        proxy_read_timeout 600s;
+        proxy_send_timeout 600s;
     }
 }
 
@@ -220,61 +222,65 @@ server {
 server {
     listen 80;
     listen [::]:80;
-    server_name llms.seudominio.com;
+    server_name llms.yourdomain.com;
     return 301 https://$server_name$request_uri;
 }
 NGINX
 ```
 
-### 3.3 Ativar e testar
+Keep reverse-proxy stream timeouts aligned with your OmniRoute timeout env vars. If you raise
+`FETCH_TIMEOUT_MS` / `STREAM_IDLE_TIMEOUT_MS`, raise `proxy_read_timeout` / `proxy_send_timeout`
+above the same threshold.
+
+### 3.3 Enable and Test
 
 ```bash
-# Remover config padrão
+# Remove default configuration
 rm -f /etc/nginx/sites-enabled/default
 
-# Ativar OmniRoute
+# Enable OmniRoute
 ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute
 
-# Testar e recarregar
+# Test and reload
 nginx -t && systemctl reload nginx
 ```
 
 ---
 
-## 4. Configurar Cloudflare DNS
+## 4. Configure Cloudflare DNS
 
-### 4.1 Adicionar registro DNS
+### 4.1 Add DNS record
 
-No painel da Cloudflare → DNS:
+In the Cloudflare dashboard → DNS:
 
-| Type | Name   | Content                   | Proxy      |
-| ---- | ------ | ------------------------- | ---------- |
-| A    | `llms` | `203.0.113.10` (IP da VM) | ✅ Proxied |
+| Type | Name   | Content                | Proxy      |
+| ---- | ------ | ---------------------- | ---------- |
+| A    | `llms` | `203.0.113.10` (VM IP) | ✅ Proxied |
 
-### 4.2 Configurar SSL
+### 4.2 Configure SSL
 
-Em **SSL/TLS → Overview**:
+Under **SSL/TLS → Overview**:
 
-- Modo: **Full (Strict)**
+- Mode: **Full (Strict)**
 
-Em **SSL/TLS → Edge Certificates**:
+Under **SSL/TLS → Edge Certificates**:
 
 - Always Use HTTPS: ✅ On
 - Minimum TLS Version: TLS 1.2
 - Automatic HTTPS Rewrites: ✅ On
 
-### 4.3 Testar
+### 4.3 Testing
 
 ```bash
 curl -sI https://llms.seudominio.com/health
-# Deve retornar HTTP/2 200
+# Should return HTTP/2 200
 ```
 
 ---
 
-## 5. Operações e Manutenção
+## 5. Operations and Maintenance
 
-### Atualizar para nova versão
+### Upgrade to a new version
 
 ```bash
 docker pull diegosouzapw/omniroute:latest
@@ -286,42 +292,42 @@ docker run -d --name omniroute --restart unless-stopped \
   diegosouzapw/omniroute:latest
 ```
 
-### Ver logs
+### View logs
 
 ```bash
-docker logs -f omniroute          # Stream em tempo real
-docker logs omniroute --tail 50   # Últimas 50 linhas
+docker logs -f omniroute          # Real-time stream
+docker logs omniroute --tail 50   # Last 50 lines
 ```
 
-### Backup manual do banco
+### Manual database backup
 
 ```bash
-# Copiar dados do volume para o host
+# Copy data from the volume to the host
 docker cp omniroute:/app/data ./backup-$(date +%F)
 
-# Ou comprimir todo o volume
+# Or compress the entire volume
 docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
   alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data
 ```
 
-### Restaurar de backup
+### Restore from backup
 
 ```bash
 docker stop omniroute
 docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
-  alpine sh -c "rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /"
+  alpine sh -c “rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /”
 docker start omniroute
 ```
 
 ---
 
-## 6. Segurança Avançada
+## 6. Advanced Security
 
-### Restringir nginx para Cloudflare IPs
+### Restrict nginx to Cloudflare IPs
 
 ```bash
-cat > /etc/nginx/cloudflare-ips.conf << 'CF'
-# Cloudflare IPv4 ranges — atualizar periodicamente
+cat > /etc/nginx/cloudflare-ips.conf << ‘CF’
+# Cloudflare IPv4 ranges — update periodically
 # https://www.cloudflare.com/ips-v4/
 set_real_ip_from 173.245.48.0/20;
 set_real_ip_from 103.21.244.0/22;
@@ -342,7 +348,7 @@ real_ip_header CF-Connecting-IP;
 CF
 ```
 
-Adicionar no `nginx.conf` dentro do bloco `http {}`:
+Add the following to `nginx.conf` inside the `http {}` block:
 
 ```nginx
 include /etc/nginx/cloudflare-ips.conf;
@@ -355,45 +361,45 @@ apt install -y fail2ban
 systemctl enable fail2ban
 systemctl start fail2ban
 
-# Verificar status
+# Check status
 fail2ban-client status sshd
 ```
 
-### Bloquear acesso direto na porta do Docker
+### Block direct access to the Docker port
 
 ```bash
-# Impedir acesso externo direto à porta 20128
+# Prevent direct external access to port 20128
 iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP
 iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT
 
-# Persistir as regras
+# Persist the rules
 apt install -y iptables-persistent
 netfilter-persistent save
 ```
 
 ---
 
-## 7. Deploy do Cloud Worker (Opcional)
+## 7. Deploy to Cloudflare Workers (Optional)
 
-Para acesso remoto via Cloudflare Workers (sem expor a VM diretamente):
+For remote access via Cloudflare Workers (without exposing the VM directly):
 
 ```bash
-# No repositório local
+# In the local repository
 cd omnirouteCloud
 npm install
 npx wrangler login
 npx wrangler deploy
 ```
 
-Ver documentação completa em [omnirouteCloud/README.md](../omnirouteCloud/README.md).
+See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md).
 
 ---
 
-## Resumo de Portas
+## Port Summary
 
-| Porta | Serviço     | Acesso                        |
-| ----- | ----------- | ----------------------------- |
-| 22    | SSH         | Público (com fail2ban)        |
-| 80    | nginx HTTP  | Redirect → HTTPS              |
-| 443   | nginx HTTPS | Via Cloudflare Proxy          |
-| 20128 | OmniRoute   | Somente localhost (via nginx) |
+| Port  | Service     | Access                     |
+| ----- | ----------- | -------------------------- |
+| 22    | SSH         | Public (with fail2ban)     |
+| 80    | nginx HTTP  | Redirect → HTTPS           |
+| 443   | nginx HTTPS | Via Cloudflare Proxy       |
+| 20128 | OmniRoute   | Localhost only (via nginx) |

docs/adr/ADR-001-nextjs-foundation.md

@@ -1,37 +0,0 @@
-# ADR-001: Next.js as the Foundation for an AI Gateway
-
-## Status: Accepted
-
-## Context
-
-OmniRoute is an AI routing gateway that translates, forwards, and manages requests across 20+ LLM providers. We needed a framework that could serve both the API proxy layer and a management dashboard from a single codebase.
-
-**Alternatives considered:**
-
-- **Express.js only** — Simpler proxy, but requires separate frontend tooling
-- **Fastify** — Fast, but no built-in SSR/dashboard support
-- **Next.js** — Unified full-stack framework with API routes, SSR, and static pages
-
-## Decision
-
-We chose Next.js because:
-
-1. **Single deployment** — API routes (`/api/*`) and dashboard UI in one process
-2. **Middleware layer** — Native request interception for auth guards and request tracing
-3. **File-based routing** — Easy to map provider endpoints to handlers
-4. **Built-in TypeScript** — Type safety across the entire codebase
-
-## Consequences
-
-**Positive:**
-
-- One `npm run build` produces both API and UI
-- Middleware provides centralized auth and request tracing
-- Dashboard gets automatic code splitting and optimization
-
-**Negative:**
-
-- Next.js middleware has limitations (no heavy imports, edge runtime constraints)
-- Serverless deployment model doesn't align with persistent WebSocket/SSE connections
-- Build times are longer than Express-only setups
-- The SSE proxy layer (`open-sse/`) operates outside Next.js conventions

docs/adr/ADR-002-hub-spoke-translation.md

@@ -1,37 +0,0 @@
-# ADR-002: Hub-and-Spoke Translation with OpenAI as Intermediate Format
-
-## Status: Accepted
-
-## Context
-
-OmniRoute routes requests across 20+ providers, each with its own API format (OpenAI, Anthropic Messages, Google Gemini, AWS Bedrock, etc.). Direct provider-to-provider translation would require O(n²) translators.
-
-**Alternatives considered:**
-
-- **Direct translation** — Each pair needs a dedicated translator (n² complexity)
-- **Common intermediate format** — Translate to/from a canonical format (2n complexity)
-- **Protocol buffers** — Strong typing but heavy overhead for a proxy
-
-## Decision
-
-We use the **OpenAI Chat Completions format** as the canonical intermediate representation. All incoming requests are normalized to OpenAI format, processed, then translated to the target provider's format.
-
-```
-Client → [any format] → OpenAI canonical → [target format] → Provider
-Provider → [response] → OpenAI canonical → [original format] → Client
-```
-
-## Consequences
-
-**Positive:**
-
-- Only 2 translators per provider (inbound + outbound) instead of n² pairs
-- OpenAI format is the de facto standard — most clients already use it
-- Adding a new provider requires only implementing one translator pair
-- Streaming (SSE) works consistently through the canonical format
-
-**Negative:**
-
-- Some provider-specific features may be lost in translation
-- The double translation adds latency (typically < 5ms)
-- OpenAI format changes require updating the canonical representation

docs/adr/ADR-003-dual-storage-sqlite.md

@@ -1,39 +0,0 @@
-# ADR-003: Dual Storage — SQLite Primary with JSON Migration Path
-
-## Status: Accepted
-
-## Context
-
-OmniRoute originally used LowDB (JSON file) for all persistence. As the project grew, JSON-based storage became a bottleneck for concurrent access, querying, and data integrity.
-
-**Alternatives considered:**
-
-- **LowDB only** — Simple but no concurrent access, no ACID, no querying
-- **SQLite only** — Fast, ACID-compliant, but breaks existing deployments
-- **PostgreSQL** — Production-grade but requires external dependency
-- **Dual storage with migration** — SQLite primary + automatic JSON migration
-
-## Decision
-
-We migrated to **SQLite as the primary store** with an automatic one-time migration from `db.json`:
-
-1. On startup, if `db.json` exists and SQLite is empty, auto-migrate all data
-2. All new reads/writes go through SQLite
-3. The `db.json` file is preserved but no longer written to
-
-Settings remain in a hybrid model where LowDB handles simple key-value configuration for backward compatibility.
-
-## Consequences
-
-**Positive:**
-
-- ACID transactions for provider connections, API keys, and usage data
-- Proper SQL queries for analytics and log filtering
-- Concurrent read/write safety via WAL mode
-- Zero-downtime migration from JSON — users upgrade transparently
-
-**Negative:**
-
-- Two storage engines to maintain (SQLite + LowDB for settings)
-- Migration code must handle edge cases and partial data
-- SQLite binary dependency needed in deployment environments

docs/i18n-tasks/01-home.md

@@ -1,36 +0,0 @@
-# Task 01 — Home Page (Dashboard)
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `home`
-
-## Arquivos
-| Arquivo | Linhas | Strings |
-|---------|--------|---------|
-| `src/app/(dashboard)/dashboard/page.tsx` | 17 | 0 (wrapper) |
-| `src/app/(dashboard)/dashboard/HomePageClient.tsx` | 500 | ~25 |
-
-## Strings a Traduzir
-
-### HomePageClient.tsx
-| Linha | String EN | Chave i18n | String PT-BR |
-|-------|-----------|------------|--------------|
-| 138 | "Quick Start" | `home.quickStart` | "Início Rápido" |
-| 242 | "Providers Overview" | `home.providersOverview` | "Visão Geral dos Provedores" |
-| 436 | "No models available for this provider." | `home.noModelsAvailable` | "Nenhum modelo disponível para este provedor." |
-| — | "Total Requests" | `home.totalRequests` | "Total de Requisições" |
-| — | "Active Providers" | `home.activeProviders` | "Provedores Ativos" |
-| — | "Success Rate" | `home.successRate` | "Taxa de Sucesso" |
-| — | "Avg Latency" | `home.avgLatency` | "Latência Média" |
-| — | "Configure Endpoint" | `home.configureEndpoint` | "Configurar Endpoint" |
-| — | "Add Provider" | `home.addProvider` | "Adicionar Provedor" |
-| — | "View Docs" | `home.viewDocs` | "Ver Documentação" |
-| — | "Copied!" | `common.copied` | ✅ já existe |
-| — | "requests" | `home.requests` | "requisições" |
-| — | "models" | `home.models` | "modelos" |
-| — | "accounts" | `home.accounts` | "contas" |
-
-## Checklist
-- [ ] Adicionar chaves no `en.json` (namespace `home`)
-- [ ] Adicionar traduções no `pt-BR.json`
-- [ ] Substituir strings por `t()` no `HomePageClient.tsx`
-- [ ] Testar em EN e PT-BR

docs/i18n-tasks/02-analytics.md

@@ -1,25 +0,0 @@
-# Task 02 — Analytics Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `analytics`
-
-## Arquivos
-| Arquivo | Linhas | Strings |
-|---------|--------|---------|
-| `src/app/(dashboard)/dashboard/analytics/page.tsx` | 46 | ~8 |
-
-## Strings a Traduzir
-
-| Linha | String EN | Chave i18n | String PT-BR |
-|-------|-----------|------------|--------------|
-| 11 | "Monitor your API usage patterns..." | `analytics.overviewDescription` | "Monitore padrões de uso da API..." |
-| 13 | "Run evaluation suites to test..." | `analytics.evalsDescription` | "Execute suítes de avaliação..." |
-| 24 | "Analytics" | `analytics.title` | "Análises" |
-| 32 | "Overview" | `analytics.overview` | "Visão Geral" |
-| 33 | "Evals" | `analytics.evals` | "Avaliações" |
-
-## Checklist
-- [ ] Adicionar chaves no `en.json`
-- [ ] Adicionar traduções no `pt-BR.json`
-- [ ] Substituir strings por `t()` em `page.tsx`
-- [ ] Testar em EN e PT-BR

docs/i18n-tasks/03-api-manager.md

@@ -1,31 +0,0 @@
-# Task 03 — API Manager Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `apiManager`
-
-## Arquivos
-| Arquivo | Linhas | Strings |
-|---------|--------|---------|
-| `src/app/(dashboard)/dashboard/api-manager/ApiManagerPageClient.tsx` | ~400 | ~20 |
-
-## Strings a Traduzir (levantamento parcial — abrir código para completar)
-
-| String EN | Chave i18n | String PT-BR |
-|-----------|------------|--------------|
-| "API Keys" | `apiManager.title` | "Chaves de API" |
-| "Create API Key" | `apiManager.createKey` | "Criar Chave de API" |
-| "Name" | `apiManager.name` | "Nome" |
-| "Key" | `apiManager.key` | "Chave" |
-| "Created" | `apiManager.created` | "Criado em" |
-| "Last Used" | `apiManager.lastUsed` | "Último Uso" |
-| "Actions" | `apiManager.actions` | "Ações" |
-| "Delete" | `common.delete` | ✅ já existe |
-| "No API keys found" | `apiManager.noKeys` | "Nenhuma chave de API encontrada" |
-| ~11 strings adicionais | — | Levantar no código |
-
-## Checklist
-- [ ] Levantar todas as strings do `ApiManagerPageClient.tsx`
-- [ ] Adicionar chaves no `en.json`
-- [ ] Adicionar traduções no `pt-BR.json`
-- [ ] Substituir strings por `t()`
-- [ ] Testar em EN e PT-BR

docs/i18n-tasks/04-audit-log.md

@@ -1,31 +0,0 @@
-# Task 04 — Audit Log Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `auditLog`
-
-## Arquivos
-| Arquivo | Linhas | Strings |
-|---------|--------|---------|
-| `src/app/(dashboard)/dashboard/audit-log/page.tsx` | 241 | ~12 |
-| `src/app/(dashboard)/dashboard/logs/AuditLogTab.tsx` | ~100 | ~3 |
-
-## Strings a Traduzir
-
-| String EN | Chave i18n | String PT-BR |
-|-----------|------------|--------------|
-| "Audit Log" | `auditLog.title` | "Log de Auditoria" |
-| "Search actions..." | `auditLog.searchPlaceholder` | "Buscar ações..." |
-| "Action" | `auditLog.action` | "Ação" |
-| "Actor" | `auditLog.actor` | "Autor" |
-| "Target" | `auditLog.target` | "Alvo" |
-| "Details" | `auditLog.details` | "Detalhes" |
-| "IP Address" | `auditLog.ipAddress` | "Endereço IP" |
-| "Timestamp" | `auditLog.timestamp` | "Data/Hora" |
-| "No audit entries found" | `auditLog.noEntries` | "Nenhum registro de auditoria" |
-| "Load More" | `auditLog.loadMore` | "Carregar Mais" |
-
-## Checklist
-- [ ] Adicionar chaves no `en.json`
-- [ ] Adicionar traduções no `pt-BR.json`
-- [ ] Substituir strings em `audit-log/page.tsx` e `AuditLogTab.tsx`
-- [ ] Testar em EN e PT-BR

docs/i18n-tasks/05-cli-tools.md

@@ -1,37 +0,0 @@
-# Task 05 — CLI Tools Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `cliTools`
-
-## Arquivos
-| Arquivo | Strings |
-|---------|---------|
-| `cli-tools/components/AntigravityToolCard.tsx` | ~3 |
-| `cli-tools/components/ClaudeToolCard.tsx` | ~3 |
-| `cli-tools/components/ClineToolCard.tsx` | ~4 |
-| `cli-tools/components/CodexToolCard.tsx` | ~3 |
-| `cli-tools/components/DefaultToolCard.tsx` | ~3 |
-| `cli-tools/components/DroidToolCard.tsx` | ~2 |
-| `cli-tools/components/KiloToolCard.tsx` | ~4 |
-| `cli-tools/components/OpenClawToolCard.tsx` | ~2 |
-
-## Strings comuns entre Tool Cards
-
-| String EN | Chave i18n | String PT-BR |
-|-----------|------------|--------------|
-| "Status" | `cliTools.status` | "Status" |
-| "Connected" | `cliTools.connected` | "Conectado" |
-| "Not Connected" | `cliTools.notConnected` | "Não Conectado" |
-| "Configure" | `cliTools.configure` | "Configurar" |
-| "Test Connection" | `cliTools.testConnection` | "Testar Conexão" |
-| "Models" | `cliTools.models` | "Modelos" |
-| "Map Models" | `cliTools.mapModels` | "Mapear Modelos" |
-| "Save" | `common.save` | ✅ já existe |
-| "Cancel" | `common.cancel` | ✅ já existe |
-
-## Checklist
-- [ ] Levantar strings de cada ToolCard
-- [ ] Adicionar chaves no `en.json`
-- [ ] Adicionar traduções no `pt-BR.json`
-- [ ] Substituir por `t()` em cada componente
-- [ ] Testar em EN e PT-BR

docs/i18n-tasks/06-combos.md

@@ -1,34 +0,0 @@
-# Task 06 — Combos Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `combos`
-
-## Arquivos
-| Arquivo | Linhas | Strings |
-|---------|--------|---------|
-| `src/app/(dashboard)/dashboard/combos/page.tsx` | ~1000 | ~20 |
-
-## Strings a Traduzir
-
-| Linha | String EN | Chave i18n | String PT-BR |
-|-------|-----------|------------|--------------|
-| 207 | "Combos" | `combos.title` | "Combos" |
-| 372 | "No models" | `combos.noModels` | "Sem modelos" |
-| 747 | "Routing Strategy" | `combos.routingStrategy` | "Estratégia de Roteamento" |
-| 791 | "Models" | `combos.models` | "Modelos" |
-| 807 | "No models added yet" | `combos.noModelsYet` | "Nenhum modelo adicionado" |
-| 922 | "Max Retries" | `combos.maxRetries` | "Máximo de Tentativas" |
-| 959 | "Timeout (ms)" | `combos.timeout` | "Timeout (ms)" |
-| 977 | "Healthcheck" | `combos.healthcheck` | "Verificação de Saúde" |
-| — | "Create Combo" | `combos.create` | "Criar Combo" |
-| — | "Edit Combo" | `combos.edit` | "Editar Combo" |
-| — | "Delete Combo" | `combos.deleteCombo` | "Excluir Combo" |
-| — | "Add Model" | `combos.addModel` | "Adicionar Modelo" |
-| — | "Priority" | `combos.priority` | "Prioridade" |
-| — | "Fallback" | `combos.fallback` | "Fallback" |
-
-## Checklist
-- [ ] Adicionar chaves no `en.json`
-- [ ] Adicionar traduções no `pt-BR.json`
-- [ ] Substituir strings por `t()` em `combos/page.tsx`
-- [ ] Testar em EN e PT-BR

docs/i18n-tasks/07-costs.md

@@ -1,23 +0,0 @@
-# Task 07 — Costs Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `costs`
-
-## Arquivos
-| Arquivo | Linhas | Strings |
-|---------|--------|---------|
-| `src/app/(dashboard)/dashboard/costs/page.tsx` | ~200 | ~5 |
-
-## Strings a Traduzir
-
-| String EN | Chave i18n | String PT-BR |
-|-----------|------------|--------------|
-| "Costs" | `costs.title` | "Custos" |
-| "Total Cost" | `costs.totalCost` | "Custo Total" |
-| "Cost Breakdown" | `costs.breakdown` | "Detalhamento de Custos" |
-| "No cost data" | `costs.noData` | "Sem dados de custo" |
-
-## Checklist
-- [ ] Levantar strings completas do código
-- [ ] Adicionar chaves no `en.json` / `pt-BR.json`
-- [ ] Substituir por `t()` e testar

docs/i18n-tasks/08-endpoint.md

@@ -1,30 +0,0 @@
-# Task 08 — Endpoint Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `endpoint`
-
-## Arquivos
-| Arquivo | Linhas | Strings |
-|---------|--------|---------|
-| `src/app/(dashboard)/dashboard/endpoint/EndpointPageClient.tsx` | ~750 | ~20 |
-
-## Strings a Traduzir
-
-| Linha | String EN | Chave i18n | String PT-BR |
-|-------|-----------|------------|--------------|
-| 320 | "API Endpoint" | `endpoint.title` | "Endpoint da API" |
-| 403 | "Available Endpoints" | `endpoint.available` | "Endpoints Disponíveis" |
-| 561 | "Cloud Proxy" | `endpoint.cloudProxy` | "Proxy na Nuvem" |
-| 632 | "Note" | `endpoint.note` | "Nota" |
-| 717 | "Warning" | `endpoint.warning` | "Aviso" |
-| 740 | "Are you sure you want to disable cloud proxy?" | `endpoint.disableConfirm` | "Tem certeza que deseja desativar o proxy na nuvem?" |
-| — | "Copy" | `common.copy` | ✅ já existe |
-| — | "Base URL" | `endpoint.baseUrl` | "URL Base" |
-| — | "Connected" | `endpoint.connected` | "Conectado" |
-| — | "Enable" | `endpoint.enable` | "Ativar" |
-| — | "Disable" | `endpoint.disable` | "Desativar" |
-
-## Checklist
-- [ ] Levantar strings restantes
-- [ ] Adicionar chaves no `en.json` / `pt-BR.json`
-- [ ] Substituir por `t()` e testar

docs/i18n-tasks/09-health.md

@@ -1,30 +0,0 @@
-# Task 09 — Health Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `health`
-
-## Arquivos
-| Arquivo | Linhas | Strings |
-|---------|--------|---------|
-| `src/app/(dashboard)/dashboard/health/page.tsx` | ~350 | ~15 |
-
-## Strings a Traduzir
-
-| String EN | Chave i18n | String PT-BR |
-|-----------|------------|--------------|
-| "System Health" | `health.title` | "Saúde do Sistema" |
-| "Healthy" | `health.healthy` | "Saudável" |
-| "Degraded" | `health.degraded` | "Degradado" |
-| "Down" | `health.down` | "Offline" |
-| "Uptime" | `health.uptime` | "Tempo Ativo" |
-| "Memory" | `health.memory` | "Memória" |
-| "CPU" | `health.cpu` | "CPU" |
-| "Database" | `health.database` | "Banco de Dados" |
-| "Last Check" | `health.lastCheck` | "Última Verificação" |
-| "Refresh" | `common.refresh` | ✅ já existe |
-| ~5 strings adicionais | — | Levantar |
-
-## Checklist
-- [ ] Levantar strings restantes
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` e testar

docs/i18n-tasks/10-limits.md

@@ -1,24 +0,0 @@
-# Task 10 — Limits Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `limits`
-
-## Arquivos
-| Arquivo | Linhas | Strings |
-|---------|--------|---------|
-| `src/app/(dashboard)/dashboard/limits/page.tsx` | ~150 | ~5 |
-
-## Strings a Traduzir
-
-| String EN | Chave i18n | String PT-BR |
-|-----------|------------|--------------|
-| "Limits & Quotas" | `limits.title` | "Limites e Cotas" |
-| "Rate Limit" | `limits.rateLimit` | "Limite de Taxa" |
-| "Provider" | `limits.provider` | "Provedor" |
-| "Remaining" | `limits.remaining` | "Restante" |
-| "Reset" | `limits.reset` | "Reiniciar" |
-
-## Checklist
-- [ ] Levantar strings completas
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` e testar

docs/i18n-tasks/11-logs.md

@@ -1,24 +0,0 @@
-# Task 11 — Logs Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `logs`
-
-## Arquivos
-| Arquivo | Linhas | Strings |
-|---------|--------|---------|
-| `src/app/(dashboard)/dashboard/logs/` | ~200 | ~5 |
-
-## Strings a Traduzir
-
-| String EN | Chave i18n | String PT-BR |
-|-----------|------------|--------------|
-| "Logs" | `logs.title` | "Logs" |
-| "Request Logs" | `logs.requestLogs` | "Logs de Requisições" |
-| "Proxy Logs" | `logs.proxyLogs` | "Logs do Proxy" |
-| "Audit Log" | `logs.auditLog` | "Log de Auditoria" |
-| "Console" | `logs.console` | "Console" |
-
-## Checklist
-- [ ] Levantar strings completas
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` e testar

docs/i18n-tasks/12-onboarding.md

@@ -1,26 +0,0 @@
-# Task 12 — Onboarding Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `onboarding`
-
-## Arquivos
-| Arquivo | Linhas | Strings |
-|---------|--------|---------|
-| `src/app/(dashboard)/dashboard/onboarding/page.tsx` | ~300 | ~10 |
-
-## Strings a Traduzir
-
-| String EN | Chave i18n | String PT-BR |
-|-----------|------------|--------------|
-| "Welcome to OmniRoute" | `onboarding.welcome` | "Bem-vindo ao OmniRoute" |
-| "Set Password" | `onboarding.setPassword` | "Definir Senha" |
-| "Add Provider" | `onboarding.addProvider` | "Adicionar Provedor" |
-| "Get Started" | `onboarding.getStarted` | "Começar" |
-| "Skip" | `onboarding.skip` | "Pular" |
-| "Next" | `common.next` | ✅ já existe |
-| ~4 strings adicionais | — | Levantar |
-
-## Checklist
-- [ ] Levantar strings completas
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` e testar

docs/i18n-tasks/13-providers.md

@@ -1,35 +0,0 @@
-# Task 13 — Providers Pages
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `providers`
-
-## Arquivos
-| Arquivo | Strings |
-|---------|---------|
-| `providers/page.tsx` | ~5 |
-| `providers/[id]/page.tsx` | ~12 |
-| `providers/new/page.tsx` | ~3 |
-| `providers/components/ModelAvailabilityPanel.tsx` | ~3 |
-| `providers/components/ModelAvailabilityBadge.tsx` | ~1 |
-
-## Strings a Traduzir
-
-| String EN | Chave i18n | String PT-BR |
-|-----------|------------|--------------|
-| "Providers" | `providers.title` | "Provedores" |
-| "Add Provider" | `providers.add` | "Adicionar Provedor" |
-| "Edit Provider" | `providers.edit` | "Editar Provedor" |
-| "Test Connection" | `providers.testConnection` | "Testar Conexão" |
-| "Connected" | `providers.connected` | "Conectado" |
-| "Disconnected" | `providers.disconnected` | "Desconectado" |
-| "Models" | `providers.models` | "Modelos" |
-| "Accounts" | `providers.accounts` | "Contas" |
-| "Delete Provider" | `providers.deleteProvider` | "Excluir Provedor" |
-| "No providers configured" | `providers.noProviders` | "Nenhum provedor configurado" |
-| "Model Availability" | `providers.modelAvailability` | "Disponibilidade de Modelos" |
-| ~9 strings adicionais | — | Levantar |
-
-## Checklist
-- [ ] Levantar strings completas de todos os arquivos
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` e testar

docs/i18n-tasks/14-settings.md

@@ -1,51 +0,0 @@
-# Task 14 — Settings Page (MAIOR TAREFA)
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `settings`
-
-## Arquivos (20 componentes!)
-| Arquivo | Strings |
-|---------|---------|
-| `settings/components/AppearanceTab.tsx` | ~4 |
-| `settings/components/CacheStatsCard.tsx` | ~4 |
-| `settings/components/ComboDefaultsTab.tsx` | ~8 |
-| `settings/components/FallbackChainsEditor.tsx` | ~2 |
-| `settings/components/IPFilterSection.tsx` | ~2 |
-| `settings/components/PoliciesPanel.tsx` | ~5 |
-| `settings/components/PricingTab.tsx` | ~8 |
-| `settings/components/ProxyTab.tsx` | ~2 |
-| `settings/components/ResilienceTab.tsx` | ~7 |
-| `settings/components/RoutingTab.tsx` | ~4 |
-| `settings/components/SecurityTab.tsx` | ~5 |
-| `settings/components/SessionInfoCard.tsx` | ~5 |
-| `settings/components/SystemPromptTab.tsx` | ~2 |
-| `settings/components/SystemStorageTab.tsx` | ~8 |
-| `settings/components/ThinkingBudgetTab.tsx` | ~5 |
-| `settings/pricing/page.tsx` | ~17 |
-
-## Strings a Traduzir (amostra)
-
-| String EN | Chave i18n | String PT-BR |
-|-----------|------------|--------------|
-| "General" | `settings.general` | "Geral" |
-| "Security" | `settings.security` | "Segurança" |
-| "Appearance" | `settings.appearance` | "Aparência" |
-| "Routing" | `settings.routing` | "Roteamento" |
-| "Cache" | `settings.cache` | "Cache" |
-| "Resilience" | `settings.resilience` | "Resiliência" |
-| "System Prompt" | `settings.systemPrompt` | "Prompt do Sistema" |
-| "Thinking Budget" | `settings.thinkingBudget` | "Orçamento de Raciocínio" |
-| "Proxy" | `settings.proxy` | "Proxy" |
-| "Pricing" | `settings.pricing` | "Preços" |
-| "Storage" | `settings.storage` | "Armazenamento" |
-| "Policies" | `settings.policies` | "Políticas" |
-| "IP Filter" | `settings.ipFilter` | "Filtro de IP" |
-| "Combo Defaults" | `settings.comboDefaults` | "Padrões de Combo" |
-| "Fallback Chains" | `settings.fallbackChains` | "Cadeias de Fallback" |
-| ~40 strings adicionais | — | Levantar em cada tab |
-
-## Checklist
-- [ ] Levantar strings de CADA componente (16 arquivos)
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` em todos os 16 arquivos
-- [ ] Testar cada aba em EN e PT-BR

docs/i18n-tasks/15-translator.md

@@ -1,41 +0,0 @@
-# Task 15 — Translator Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `translator`
-
-## Arquivos
-| Arquivo | Strings |
-|---------|---------|
-| `translator/components/LiveMonitorMode.tsx` | ~11 |
-| `translator/components/PlaygroundMode.tsx` | ~5 |
-| `translator/components/TestBenchMode.tsx` | ~3 |
-| `translator/components/ChatTesterMode.tsx` | ~4 |
-
-## Strings a Traduzir
-
-| String EN | Chave i18n | String PT-BR |
-|-----------|------------|--------------|
-| "Real-Time Translation Activity" | `translator.realtime` | "Atividade de Tradução em Tempo Real" |
-| "Chat Tester" | `translator.chatTester` | "Testador de Chat" |
-| "Test Bench" | `translator.testBench` | "Bancada de Testes" |
-| "Recent Translations" | `translator.recentTranslations` | "Traduções Recentes" |
-| "No translations yet" | `translator.noTranslations` | "Nenhuma tradução ainda" |
-| "Time" | `translator.time` | "Tempo" |
-| "Source" | `translator.source` | "Origem" |
-| "Target" | `translator.target` | "Destino" |
-| "Model" | `translator.model` | "Modelo" |
-| "Status" | `translator.status` | "Status" |
-| "Latency" | `translator.latency` | "Latência" |
-| "Format Converter" | `translator.formatConverter` | "Conversor de Formato" |
-| "Input" | `translator.input` | "Entrada" |
-| "Output" | `translator.output` | "Saída" |
-| "Example Templates" | `translator.exampleTemplates` | "Modelos de Exemplo" |
-| "Compatibility Tester" | `translator.compatibilityTester` | "Testador de Compatibilidade" |
-| "Compatibility Report" | `translator.compatibilityReport` | "Relatório de Compatibilidade" |
-| "Pipeline Debugger" | `translator.pipelineDebugger` | "Depurador de Pipeline" |
-| "Translation Pipeline" | `translator.translationPipeline` | "Pipeline de Tradução" |
-
-## Checklist
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` em cada componente
-- [ ] Testar em EN e PT-BR

docs/i18n-tasks/16-usage.md

@@ -1,57 +0,0 @@
-# Task 16 — Usage Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `usage`
-
-## Arquivos
-| Arquivo | Strings |
-|---------|---------|
-| `usage/components/BudgetTab.tsx` | ~4 |
-| `usage/components/BudgetTelemetryCards.tsx` | ~9 |
-| `usage/components/EvalsTab.tsx` | ~6 |
-| `usage/components/RateLimitStatus.tsx` | ~2 |
-| `usage/components/SessionsTab.tsx` | ~7 |
-| `usage/components/ProviderLimits/index.tsx` | ~7 |
-| `usage/components/ProviderLimits/ProviderLimitCard.tsx` | ~1 |
-| `usage/components/ProviderLimits/QuotaTable.tsx` | ~1 |
-
-## Strings a Traduzir
-
-| String EN | Chave i18n | String PT-BR |
-|-----------|------------|--------------|
-| "Budget Management" | `usage.budgetManagement` | "Gerenciamento de Orçamento" |
-| "API Key" | `usage.apiKey` | "Chave de API" |
-| "This Month" | `usage.thisMonth` | "Este Mês" |
-| "Set Limits" | `usage.setLimits` | "Definir Limites" |
-| "Total requests" | `usage.totalRequests` | "Total de requisições" |
-| "No data yet" | `usage.noData` | "Sem dados ainda" |
-| "Entries" | `usage.entries` | "Entradas" |
-| "Hit Rate" | `usage.hitRate` | "Taxa de Acerto" |
-| "Circuit Breakers" | `usage.circuitBreakers` | "Disjuntores" |
-| "Locked IPs" | `usage.lockedIPs` | "IPs Bloqueados" |
-| "How It Works" | `usage.howItWorks` | "Como Funciona" |
-| "Define" | `usage.define` | "Definir" |
-| "Run" | `usage.run` | "Executar" |
-| "Evaluate" | `usage.evaluate` | "Avaliar" |
-| "Evaluation Suites" | `usage.evalSuites` | "Suítes de Avaliação" |
-| "Model Evaluations" | `usage.modelEvals` | "Avaliações de Modelos" |
-| "Model Lockouts" | `usage.modelLockouts` | "Bloqueios de Modelo" |
-| "No models currently locked" | `usage.noLockouts` | "Nenhum modelo bloqueado" |
-| "Active Sessions" | `usage.activeSessions` | "Sessões Ativas" |
-| "No active sessions" | `usage.noSessions` | "Sem sessões ativas" |
-| "Session" | `usage.session` | "Sessão" |
-| "Age" | `usage.age` | "Idade" |
-| "Requests" | `usage.requests` | "Requisições" |
-| "Connection" | `usage.connection` | "Conexão" |
-| "Provider Limits" | `usage.providerLimits` | "Limites do Provedor" |
-| "No Providers Connected" | `usage.noProviders` | "Nenhum Provedor Conectado" |
-| "Account" | `usage.account` | "Conta" |
-| "Model Quotas" | `usage.modelQuotas` | "Cotas de Modelo" |
-| "Last Used" | `usage.lastUsed` | "Último Uso" |
-| "Actions" | `usage.actions` | "Ações" |
-| "No quota data" | `usage.noQuota` | "Sem dados de cota" |
-
-## Checklist
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` em cada componente
-- [ ] Testar em EN e PT-BR

docs/i18n-tasks/17-shared-modals.md

@@ -1,44 +0,0 @@
-# Task 17 — Shared Modals
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `modals`
-
-## Arquivos
-| Arquivo | Strings |
-|---------|---------|
-| `shared/components/OAuthModal.tsx` | ~6 |
-| `shared/components/KiroAuthModal.tsx` | ~10 |
-| `shared/components/KiroSocialOAuthModal.tsx` | ~3 |
-| `shared/components/CursorAuthModal.tsx` | ~2 |
-| `shared/components/PricingModal.tsx` | ~10 |
-| `shared/components/ModelSelectModal.tsx` | ~2 |
-| `shared/components/ProxyConfigModal.tsx` | ~1 |
-
-## Strings a Traduzir
-
-| String EN | String PT-BR |
-|-----------|--------------|
-| "Waiting for Authorization" | "Aguardando Autorização" |
-| "Verification URL" | "URL de Verificação" |
-| "Your Code" | "Seu Código" |
-| "Remote access:" | "Acesso remoto:" |
-| "Connected Successfully!" | "Conectado com Sucesso!" |
-| "Connection Failed" | "Falha na Conexão" |
-| "Choose your authentication method:" | "Escolha seu método de autenticação:" |
-| "AWS Builder ID" | "AWS Builder ID" |
-| "AWS IAM Identity Center" | "AWS IAM Identity Center" |
-| "Google Account" | "Conta Google" |
-| "GitHub Account" | "Conta GitHub" |
-| "Import Token" | "Importar Token" |
-| "Auto-detecting tokens..." | "Detectando tokens automaticamente..." |
-| "Pricing Configuration" | "Configuração de Preços" |
-| "Loading pricing data..." | "Carregando dados de preços..." |
-| "Model" / "Input" / "Output" / "Cached" | "Modelo" / "Entrada" / "Saída" / "Em Cache" |
-| "Combos" | "Combos" |
-| "No models found" | "Nenhum modelo encontrado" |
-| "Connected" | "Conectado" |
-
-## Checklist
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` em cada modal
-- [ ] Testar cada modal em EN e PT-BR

docs/i18n-tasks/18-shared-loggers.md

@@ -1,37 +0,0 @@
-# Task 18 — Shared Loggers
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `loggers`
-
-## Arquivos
-| Arquivo | Strings |
-|---------|---------|
-| `shared/components/RequestLoggerV2.tsx` | ~12 |
-| `shared/components/RequestLoggerDetail.tsx` | ~4 |
-| `shared/components/ProxyLogger.tsx` | ~7 |
-| `shared/components/ProxyLogDetail.tsx` | ~6 |
-| `shared/components/ConsoleLogViewer.tsx` | ~2 |
-
-## Strings a Traduzir
-
-| String EN | String PT-BR |
-|-----------|--------------|
-| "All Providers" | "Todos os Provedores" |
-| "All Models" | "Todos os Modelos" |
-| "All Accounts" | "Todas as Contas" |
-| "All API Keys" | "Todas as Chaves de API" |
-| "Newest" / "Oldest" | "Mais Recente" / "Mais Antigo" |
-| "Model A-Z" / "Model Z-A" | "Modelo A-Z" / "Modelo Z-A" |
-| "Columns" | "Colunas" |
-| "Loading logs..." | "Carregando logs..." |
-| "All Types" | "Todos os Tipos" |
-| "All Levels" | "Todos os Níveis" |
-| "Proxy Event" | "Evento do Proxy" |
-| "Time" / "Model" / "Combo" | "Tempo" / "Modelo" / "Combo" |
-| "No log entries found" | "Nenhuma entrada de log encontrada" |
-| "No payload data available" | "Nenhum dado de payload disponível" |
-
-## Checklist
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` em cada logger
-- [ ] Testar em EN e PT-BR

docs/i18n-tasks/19-shared-charts.md

@@ -1,36 +0,0 @@
-# Task 19 — Shared Charts & Stats
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `stats`
-
-## Arquivos
-| Arquivo | Strings |
-|---------|---------|
-| `shared/components/UsageStats.tsx` | ~6 |
-| `shared/components/analytics/charts.tsx` | ~15 |
-| `shared/components/TokenHealthBadge.tsx` | ~6 |
-| `shared/components/SystemMonitor.tsx` | ~1 |
-| `shared/components/Footer.tsx` | ~3 |
-
-## Strings a Traduzir
-
-| String EN | String PT-BR |
-|-----------|--------------|
-| "Usage Overview" | "Visão Geral de Uso" |
-| "Output Tokens" | "Tokens de Saída" |
-| "Total Cost" | "Custo Total" |
-| "Usage by Model" | "Uso por Modelo" |
-| "Usage by Account" | "Uso por Conta" |
-| "Failed to load usage statistics." | "Falha ao carregar estatísticas." |
-| "Token Health" | "Saúde dos Tokens" |
-| "Total OAuth" | "Total OAuth" |
-| "Healthy" / "Errored" / "Warning" | "Saudável" / "Com Erro" / "Aviso" |
-| "Last check" | "Última verificação" |
-| "No data" / "Share" | "Sem dados" / "Compartilhar" |
-| "Unable to load system metrics" | "Não foi possível carregar métricas" |
-| "Product" / "Resources" / "Company" (Footer) | "Produto" / "Recursos" / "Empresa" |
-
-## Checklist
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` em cada componente
-- [ ] Testar em EN e PT-BR

docs/i18n-tasks/20-login-auth.md

@@ -1,36 +0,0 @@
-# Task 20 — Login & Auth Pages
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `auth`
-
-## Arquivos
-| Arquivo | Strings |
-|---------|---------|
-| `src/app/login/page.tsx` | ~8 |
-| `src/app/forgot-password/page.tsx` | ~3 |
-| `src/app/callback/page.tsx` | ~5 |
-| `src/app/forbidden/page.tsx` | ~1 |
-
-## Strings a Traduzir
-
-| String EN | String PT-BR |
-|-----------|--------------|
-| "Welcome" | "Bem-vindo" |
-| "OmniRoute" | "OmniRoute" (não traduzir) |
-| "Sign in" | "Entrar" |
-| "Enter your password to continue" | "Digite sua senha para continuar" |
-| "Password" | "Senha" |
-| "Unified AI API Proxy" | "Proxy Unificado de API de IA" |
-| "Loading..." | "Carregando..." |
-| "Password protection is not enabled" | "Proteção por senha não está ativada" |
-| "Reset Password" | "Redefinir Senha" |
-| "Choose a method to recover access" | "Escolha um método para recuperar acesso" |
-| "Processing..." | "Processando..." |
-| "Authorization Successful!" | "Autorização bem-sucedida!" |
-| "Copy This URL" | "Copiar esta URL" |
-| "Access Denied" | "Acesso Negado" |
-
-## Checklist
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` em cada página
-- [ ] Testar em EN e PT-BR

docs/i18n-tasks/21-landing.md

@@ -1,34 +0,0 @@
-# Task 21 — Landing Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `landing`
-
-## Arquivos
-| Arquivo | Strings |
-|---------|---------|
-| `landing/components/HeroSection.tsx` | ~3 |
-| `landing/components/Features.tsx` | ~10 |
-| `landing/components/HowItWorks.tsx` | ~5 |
-| `landing/components/GetStarted.tsx` | ~5 |
-| `landing/components/Navigation.tsx` | ~2 |
-| `landing/components/FlowAnimation.tsx` | ~2 |
-| `landing/components/Footer.tsx` | ~5 |
-
-## Strings a Traduzir (amostra)
-
-| String EN | String PT-BR |
-|-----------|--------------|
-| "All AI Providers" | "Todos os Provedores de IA" |
-| "One Endpoint" | "Um Endpoint" |
-| "Powerful Features" | "Recursos Poderosos" |
-| "How OmniRoute Works" | "Como o OmniRoute Funciona" |
-| "Install OmniRoute" | "Instalar o OmniRoute" |
-| "Open Dashboard" | "Abrir Painel" |
-| "Route Requests" | "Rotear Requisições" |
-| "Data Location:" | "Local dos Dados:" |
-| "Product" / "Resources" / "Legal" | "Produto" / "Recursos" / "Legal" |
-
-## Checklist
-- [ ] Levantar strings completas de cada componente
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` e testar

docs/i18n-tasks/22-docs.md

@@ -1,32 +0,0 @@
-# Task 22 — Docs Page
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `docs`
-
-## Arquivos
-| Arquivo | Strings |
-|---------|---------|
-| `src/app/docs/page.tsx` | ~25 |
-
-## Strings a Traduzir
-
-| String EN | String PT-BR |
-|-----------|--------------|
-| "Quick Start" | "Início Rápido" |
-| "Features" | "Recursos" |
-| "Supported Providers" | "Provedores Suportados" |
-| "Common Use Cases" | "Casos de Uso Comuns" |
-| "Client Compatibility" | "Compatibilidade de Clientes" |
-| "Cherry Studio" | "Cherry Studio" (não traduzir) |
-| "Codex / GitHub Copilot Models" | "Modelos Codex / GitHub Copilot" |
-| "Cursor IDE" | "Cursor IDE" (não traduzir) |
-| "Claude Code / Antigravity" | "Claude Code / Antigravity" |
-| "API Reference" | "Referência da API" |
-| "Method" / "Path" / "Notes" | "Método" / "Caminho" / "Notas" |
-| "Model Prefixes" | "Prefixos de Modelo" |
-| "Prefix" / "Provider" / "Type" | "Prefixo" / "Provedor" / "Tipo" |
-| "Troubleshooting" | "Solução de Problemas" |
-
-## Checklist
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` e testar

docs/i18n-tasks/23-legal.md

@@ -1,31 +0,0 @@
-# Task 23 — Legal Pages (Privacy & Terms)
-
-**Status:** `[ ]` Não iniciado  
-**Namespace JSON:** `legal`
-
-## Arquivos
-| Arquivo | Strings |
-|---------|---------|
-| `src/app/privacy/page.tsx` | ~10 |
-| `src/app/terms/page.tsx` | ~5 |
-
-## Strings a Traduzir
-
-| String EN | String PT-BR |
-|-----------|--------------|
-| "Privacy Policy" | "Política de Privacidade" |
-| "Terms of Service" | "Termos de Serviço" |
-| "Provider configurations" | "Configurações de provedores" |
-| "API keys" | "Chaves de API" |
-| "Usage logs" | "Logs de uso" |
-| "Application settings" | "Configurações do aplicativo" |
-| "View and export usage analytics" | "Visualizar e exportar análises de uso" |
-| "Clear usage history at any time" | "Limpar histórico de uso a qualquer momento" |
-| "Configure log retention policies" | "Configurar políticas de retenção de logs" |
-| "Back up and restore your database" | "Fazer backup e restaurar seu banco de dados" |
-
-## Checklist
-- [ ] Adicionar chaves / traduções
-- [ ] Substituir por `t()` e testar
-
-> **Nota:** Textos legais podem requerer revisão jurídica para tradução formal.

docs/i18n-tasks/README.md

@@ -1,51 +0,0 @@
-# i18n Translation Tasks
-
-Cada arquivo `.md` nesta pasta representa **uma tarefa de tradução** para uma página ou componente do OmniRoute.
-
-## Status Legend
-
-- `[ ]` — Não iniciado
-- `[/]` — Em progresso
-- `[x]` — Concluído
-
-## Dashboard Pages (~260 strings)
-
-| #   | Tarefa                             | Arquivo                                               | Strings | Status |
-| --- | ---------------------------------- | ----------------------------------------------------- | ------- | ------ |
-| 01  | [Home](./01-home.md)               | `HomePageClient.tsx`                                  | ~25     | `[ ]`  |
-| 02  | [Analytics](./02-analytics.md)     | `analytics/page.tsx`                                  | ~8      | `[ ]`  |
-| 03  | [API Manager](./03-api-manager.md) | `api-manager/`                                        | ~20     | `[ ]`  |
-| 04  | [Audit Log](./04-audit-log.md)     | `audit-log/page.tsx`, `logs/AuditLogTab.tsx`          | ~15     | `[ ]`  |
-| 05  | [CLI Tools](./05-cli-tools.md)     | `cli-tools/components/*.tsx`                          | ~20     | `[ ]`  |
-| 06  | [Combos](./06-combos.md)           | `combos/page.tsx`                                     | ~20     | `[ ]`  |
-| 07  | [Costs](./07-costs.md)             | `costs/page.tsx`                                      | ~5      | `[ ]`  |
-| 08  | [Endpoint](./08-endpoint.md)       | `endpoint/EndpointPageClient.tsx`                     | ~20     | `[ ]`  |
-| 09  | [Health](./09-health.md)           | `health/page.tsx`                                     | ~15     | `[ ]`  |
-| 10  | [Limits](./10-limits.md)           | `limits/page.tsx`                                     | ~5      | `[ ]`  |
-| 11  | [Logs](./11-logs.md)               | `logs/`                                               | ~5      | `[ ]`  |
-| 12  | [Onboarding](./12-onboarding.md)   | `onboarding/page.tsx`                                 | ~10     | `[ ]`  |
-| 13  | [Providers](./13-providers.md)     | `providers/page.tsx`, `[id]/page.tsx`, `new/page.tsx` | ~20     | `[ ]`  |
-| 14  | [Settings](./14-settings.md)       | `settings/components/*.tsx`                           | ~55     | `[ ]`  |
-| 15  | [Translator](./15-translator.md)   | `translator/components/*.tsx`                         | ~25     | `[ ]`  |
-| 16  | [Usage](./16-usage.md)             | `usage/components/*.tsx`                              | ~35     | `[ ]`  |
-
-## Shared Components (~95 strings)
-
-| #   | Tarefa                                         | Arquivo(s)                                           | Strings | Status |
-| --- | ---------------------------------------------- | ---------------------------------------------------- | ------- | ------ |
-| 17  | [Shared Modals](./17-shared-modals.md)         | `OAuthModal`, `KiroAuthModal`, `PricingModal`, etc.  | ~40     | `[ ]`  |
-| 18  | [Shared Loggers](./18-shared-loggers.md)       | `RequestLoggerV2`, `ProxyLogger`, `ProxyLogDetail`   | ~30     | `[ ]`  |
-| 19  | [Shared Charts & Stats](./19-shared-charts.md) | `UsageStats`, `analytics/charts`, `TokenHealthBadge` | ~25     | `[ ]`  |
-
-## Non-Dashboard Pages (~75 strings)
-
-| #   | Tarefa                             | Arquivo(s)                                              | Strings | Status |
-| --- | ---------------------------------- | ------------------------------------------------------- | ------- | ------ |
-| 20  | [Login & Auth](./20-login-auth.md) | `login/`, `forgot-password/`, `callback/`, `forbidden/` | ~20     | `[ ]`  |
-| 21  | [Landing Page](./21-landing.md)    | `landing/components/*.tsx`                              | ~25     | `[ ]`  |
-| 22  | [Docs Page](./22-docs.md)          | `docs/page.tsx`                                         | ~25     | `[ ]`  |
-| 23  | [Legal Pages](./23-legal.md)       | `privacy/`, `terms/`                                    | ~15     | `[ ]`  |
-
----
-
-**Total estimado: ~460 strings em 23 tarefas**

docs/i18n/README.md

@@ -0,0 +1,38 @@
+# 🌐 Multilingual Documentation — 9router
+
+Translations of documentation into 32 languages. Code blocks remain in English.
+
+---
+
+- 🇪🇸 **Español** (`es`): [Docs Root](./es/README.md)
+- 🇫🇷 **Français** (`fr`): [Docs Root](./fr/README.md)
+- 🇩🇪 **Deutsch** (`de`): [Docs Root](./de/README.md)
+- 🇮🇹 **Italiano** (`it`): [Docs Root](./it/README.md)
+- 🇷🇺 **Русский** (`ru`): [Docs Root](./ru/README.md)
+- 🇨🇳 **中文（简体）** (`zh-CN`): [Docs Root](./zh-CN/README.md)
+- 🇯🇵 **日本語** (`ja`): [Docs Root](./ja/README.md)
+- 🇰🇷 **한국어** (`ko`): [Docs Root](./ko/README.md)
+- 🇸🇦 **العربية** (`ar`): [Docs Root](./ar/README.md)
+- 🇮🇳 **हिन्दी** (`hi`): [Docs Root](./hi/README.md)
+- 🇮🇳 **हिन्दी (IN)** (`in`): [Docs Root](./in/README.md)
+- 🇹🇭 **ไทย** (`th`): [Docs Root](./th/README.md)
+- 🇻🇳 **Tiếng Việt** (`vi`): [Docs Root](./vi/README.md)
+- 🇮🇩 **Bahasa Indonesia** (`id`): [Docs Root](./id/README.md)
+- 🇲🇾 **Bahasa Melayu** (`ms`): [Docs Root](./ms/README.md)
+- 🇳🇱 **Nederlands** (`nl`): [Docs Root](./nl/README.md)
+- 🇵🇱 **Polski** (`pl`): [Docs Root](./pl/README.md)
+- 🇸🇪 **Svenska** (`sv`): [Docs Root](./sv/README.md)
+- 🇳🇴 **Norsk** (`no`): [Docs Root](./no/README.md)
+- 🇩🇰 **Dansk** (`da`): [Docs Root](./da/README.md)
+- 🇫🇮 **Suomi** (`fi`): [Docs Root](./fi/README.md)
+- 🇵🇹 **Português (Portugal)** (`pt`): [Docs Root](./pt/README.md)
+- 🇷🇴 **Română** (`ro`): [Docs Root](./ro/README.md)
+- 🇭🇺 **Magyar** (`hu`): [Docs Root](./hu/README.md)
+- 🇧🇬 **Български** (`bg`): [Docs Root](./bg/README.md)
+- 🇸🇰 **Slovenčina** (`sk`): [Docs Root](./sk/README.md)
+- 🇺🇦 **Українська** (`uk-UA`): [Docs Root](./uk-UA/README.md)
+- 🇮🇱 **עברית** (`he`): [Docs Root](./he/README.md)
+- 🇵🇭 **Filipino** (`phi`): [Docs Root](./phi/README.md)
+- 🇧🇷 **Português (Brasil)** (`pt-BR`): [Docs Root](./pt-BR/README.md)
+- 🇨🇿 **Čeština** (`cs`): [Docs Root](./cs/README.md)
+- 🇹🇷 **Türkçe** (`tr`): [Docs Root](./tr/README.md)

docs/i18n/ar/CONTRIBUTING.md

@@ -0,0 +1,235 @@
+# Contributing to OmniRoute (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../CONTRIBUTING.md) · 🇪🇸 [es](../es/CONTRIBUTING.md) · 🇫🇷 [fr](../fr/CONTRIBUTING.md) · 🇩🇪 [de](../de/CONTRIBUTING.md) · 🇮🇹 [it](../it/CONTRIBUTING.md) · 🇷🇺 [ru](../ru/CONTRIBUTING.md) · 🇨🇳 [zh-CN](../zh-CN/CONTRIBUTING.md) · 🇯🇵 [ja](../ja/CONTRIBUTING.md) · 🇰🇷 [ko](../ko/CONTRIBUTING.md) · 🇸🇦 [ar](../ar/CONTRIBUTING.md) · 🇮🇳 [hi](../hi/CONTRIBUTING.md) · 🇮🇳 [in](../in/CONTRIBUTING.md) · 🇹🇭 [th](../th/CONTRIBUTING.md) · 🇻🇳 [vi](../vi/CONTRIBUTING.md) · 🇮🇩 [id](../id/CONTRIBUTING.md) · 🇲🇾 [ms](../ms/CONTRIBUTING.md) · 🇳🇱 [nl](../nl/CONTRIBUTING.md) · 🇵🇱 [pl](../pl/CONTRIBUTING.md) · 🇸🇪 [sv](../sv/CONTRIBUTING.md) · 🇳🇴 [no](../no/CONTRIBUTING.md) · 🇩🇰 [da](../da/CONTRIBUTING.md) · 🇫🇮 [fi](../fi/CONTRIBUTING.md) · 🇵🇹 [pt](../pt/CONTRIBUTING.md) · 🇷🇴 [ro](../ro/CONTRIBUTING.md) · 🇭🇺 [hu](../hu/CONTRIBUTING.md) · 🇧🇬 [bg](../bg/CONTRIBUTING.md) · 🇸🇰 [sk](../sk/CONTRIBUTING.md) · 🇺🇦 [uk-UA](../uk-UA/CONTRIBUTING.md) · 🇮🇱 [he](../he/CONTRIBUTING.md) · 🇵🇭 [phi](../phi/CONTRIBUTING.md) · 🇧🇷 [pt-BR](../pt-BR/CONTRIBUTING.md) · 🇨🇿 [cs](../cs/CONTRIBUTING.md) · 🇹🇷 [tr](../tr/CONTRIBUTING.md)
+
+---
+
+شكرا لاهتمامك بالمساهمة! يغطي هذا الدليل كل ما تحتاجه للبدء.---##إعداد التطوير### Prerequisites
+
+-**Node.js**>= 18 < 24 (موصى به: 22 LTS) -**npm**10+ -**جيت**### النسخ والتثبيت`bash
+استنساخ بوابة https://github.com/diegosouzapw/OmniRoute.git
+قرص مضغوط OmniRoute
+تثبيت npm`
+
+### Environment Variables
+
+````bash
+# قم بإنشاء .env الخاص بك من القالب
+cp .env.example .env
+
+# توليد الأسرار المطلوبة
+صدى "JWT_SECRET=$(openssl rand -base64 48)" >> .env
+صدى "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env```
+
+المساهمة في التنمية الرئيسية:
+
+| فنية | التطوير الافتراضي | الوصف |
+| ---------------------- | ------------------------ | --------------------- |
+| "ميناء" | `20128` | منفذ الخادم |
+| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | عنوان URL الأساسي للواجهة |
+| `JWT_SECRET` | (أنشئ أعلاه) | سر توقيع JWT |
+| `INITIAL_PASSWORD` | "التغيير" | كلمة المرور الأولى لتسجيل الدخول |
+| `APP_LOG_LEVEL` | `معلومات` | تسجيل مستوى الإسهاب |### إعدادات لوحة التحكم
+
+توفر أدوات تعديل لوحة المعلومات للمستخدم للميزات التي يمكن تهيئتها أيضًا عبر البيئات المتنوعة:
+
+| تحديد الموقع | تغيير | الوصف |
+| ------------------- | ------------------ | ------------------------------ |
+| الإعدادات → متقدمة | وضع الرقعة | أرشيف الطلبات التصحيح (UI) |
+| الإعدادات → عام | رؤية الشريط الجانبي | إخفاء/ إخفاء أقسام الفصل الجانبي |
+
+يتم تخزين هذه الإعدادات في قاعدة البيانات وتستمر من خلال عمليات إعادة تشغيل التشغيل، مما يؤدي إلى تجاوز إعدادات env var الافتراضية عند ضبطها.### التشغيل محليًا```bash
+# Development mode (hot reload)
+npm run dev
+
+# Production build
+npm run build
+npm run start
+
+# Common port configuration
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+````
+
+عناوين URL الافتراضية:
+
+-**لوحة المعلومات**: `http://localhost:20128/dashboard` -**واجهة برمجة التطبيقات**: `http://localhost:20128/v1`---## Git Workflow
+
+> ⚠️**لا تلتزم مطلقًا بـ "الرئيسي".**استخدم ميزات الميزات دائمًا.```bash
+> git checkout -b feat/your-feature-name
+> #...إجراءات جديدة...
+> git الالتزام -m "الفذ: وصف التغيير الخاص بك"
+> git Push -u Origin feat/your-feature-name
+
+# قم بتسجيل الطلب على GitHub```### Branch Naming
+
+| المبادئ         | الحصاد                    |
+| --------------- | ------------------------- | ------------------ |
+| `الفذ/`         | مميزات جديدة              |
+| `/`             | إصلاحات الشويب            |
+| `إعادة البناء/` | إعادة هيكلة الكود         |
+| `المستندات/`    | تأثيرات التوثيق           |
+| `اختبار/`       | الإضافات/إصلاحات الاختبار |
+| `العمل الرتيب/` | الأدوات، CI، التبعيات     | ### رسائل الالتزام |
+
+اتبع [الالتزامات التقليدية](https://www.conventionalcommits.org/):`
+الفذ: إضافة قاطع الدائرة لمكالمات المزود
+الإصلاح: حل حالة حافة التحقق السري من JWT
+المستندات: قم بتحديث SECURITY.md مع حماية معلومات تحديد الهوية الشخصية (PII).
+الاختبار: إضافة اختبارات وحدة الملاحظة
+refactor(db): توحيد جداول حدود المعدل`
+
+النطاقات: `db`، `sse`، `oauth`، `dashboard`، `api`، `cli`، `docker`، `ci`، `mcp`، `a2a`، `memory`، `skills`.---## Running Tests
+
+````bash
+# جميع الاختبارات (الوحدة + فيتيست + النظام البيئي + e2e)
+اختبار تشغيل npm: الكل
+
+# ملف اختبار فردي (مشغل الاختبار الأصلي لـ Node.js — تستخدمه معظم الاختبارات)
+العقدة - استيراد tsx/esm - اختبارات الاختبار/الوحدة/your-file.test.mjs
+
+# Vitest (خادم MCP، autoCombo، ذاكرة التخزين المؤقت)
+اختبار تشغيل npm: vitest
+
+# اختبارات E2E (يتطلب الكاتب المسرحي)
+اختبار تشغيل npm: e2e
+
+# عملاء البروتوكول E2E (نقل MCP، A2A)
+اختبار تشغيل npm: البروتوكولات: e2e
+
+# اختبارات توافق النظام البيئي
+اختبار تشغيل npm: النظام البيئي
+
+# التغطية (60% الحد الأدنى من البيانات/السطور/الوظائف/الفروع)
+اختبار تشغيل npm: التغطية
+تغطية تشغيل npm: تقرير
+
+# فحص الوبر + التنسيق
+npm تشغيل الوبر
+فحص تشغيل npm```
+
+تغطية التعليقات:
+
+- `npm run test:coverage` يقيس المصدر لمجموعة اختبار الوحدة الرئيسية، ويستبعد `tests/**`، بما في ذلك `open-sse/**`
+- يجب أن تحافظ على طلبات التنظيف على بوابة التغطية الشاملة عند**60% أو أعلى**للكشوفات والخطوط والوظائف والأروع
+- إذا قام ممثل العلاقات العامة تغيير رمز الإنتاج في `src/` أو `open-sse/` أو `electron/` أو `bin/`، فيجب عليه إضافة أو تحديث النقاشة التلقائية في نفس العلاقات العامة
+- `تغطية تشغيل npm: التقرير' يطبع التقرير التفصيلي لكل ملف على المدى الطويل من أحدث طرق التغطية
+- `اختبار تشغيل npm:التغطية:التراث` يحافظ على قياس الأقدم للمقارنة التاريخية
+- راجع`docs/COVERAGE_PLAN.md` للحصول على خارطة طريق تحسين التغطية العامة### سحب متطلبات الطلب
+
+قبل فتح أو دمج العلاقات العامة:
+
+- اختبار تشغيل npm: الوحدة
+- اختبار تشغيل npm: التغطية
+- تأكد من بقاء بوابة التغطية عند**60%+**لجميع المعايير
+- تتضمن ملفات الاختبار التي تم تغييرها أو الهاتفا في وصف العلاقات العامة عند تغيير رمز الإنتاج
+- التحقق من نتيجة SonarQube على PR عندما يتم التأكد من أسرار المشروع في CI
+
+الاختبار الحالي:**ملفات اختبار 122 وحدة**تغطي:
+
+- تحويل المترجمين باستمرار
+- الحد من المعدل، وقواطع الضوء، والمرونة
+- ذاكرة تخزين مؤقتة الدلالية، والعجز، وتتبع التقدم
+- عمليات قاعدة البيانات والمخطط (21 وحدة قاعدة بيانات)
+- تدفقات OAuth والمصادقة
+- التحقق من صحة نقطة نهاية واجهة برمجة التطبيقات (Zod v4)
+- أدوات خادمة MCP وكارثة النطاق
+- لأنظمة الذاكرة والمهارات---## Code Style
+
+-**ESLint**— يسمح npm run lint قبل الالتزام
+-**Prettier**— يتم بشكل متزايد من خلال ``التجهيز المرحلي`` عند الالتزام (مسافتان، فواصل منقوطة، علامات رسل مزدوجة، عرض 100 حرف، فاصلة زائدة es5)
+-**TypeScript**— يستخدم جميع أكواد `src/` `.ts`/`.tsx`؛ `open-sse/` يستخدم `.ts`/`.js`؛ مستند باستخدام TSDoc (`@param`، `@returns`، `@throws`)
+-**لا يوجد `eval()`**- يفرض ESLint `no-eval`، `no-implied-eval`، `no-new-func`.
+-**التحقق من صحة Zod**— استخدم مخطط Zod v4 للتأكد من صحة واجهة برمجة التطبيقات (API).
+-**التسميه**: الملفات = الجمله/علبة الكباب، المكونات = PascalCase، الثوابت = UPPER_SNAKE---## Project Structure
+
+````
+
+src/ # تايب سكريبت (.ts / .tsx)
+├── التطبيق/ # Next.js 16 App Router
+│ ├── (لوحة المعلومات)/ # صفحات لوحة المعلومات (23 قسم)
+│ ├── واجهة برمجة التطبيقات/ # مسارات واجهة برمجة التطبيقات (51 دليلاً)
+│ └── تسجيل الدخول/ # صفحات المصادقة (.tsx)
+├── المجال/ # محرك السياسة (policyEngine، comboResolver، costRules، إلخ.)
+├── lib/ # منطق العمل الأساسي (.ts)
+│ ├── a2a/ # خادم بروتوكول وكيل إلى وكيل v0.3
+│ ├── acp/ # تسجيل بروتوكول اتصال الوكيل
+│ ├── الامتثال/ # محرك سياسة الامتثال
+│ ├── db/ # طبقة قاعدة بيانات SQLite (21 وحدة + 16 عملية ترحيل)
+│ ├── الذاكرة/ # ذاكرة المحادثة المستمرة
+│ ├── oauth/ # موفرو OAuth والخدمات والأدوات المساعدة
+│ ├── المهارات/ # إطار المهارات الموسعة
+│ ├── الاستخدام/ # تتبع الاستخدام وحساب التكلفة
+│ └── localDb.ts # طبقة إعادة التصدير فقط - لا تقم أبدًا بإضافة المنطق هنا
+├── البرامج الوسيطة/ # طلب البرامج الوسيطة (promptInjectionGuard)
+├── mitm/ # وكيل MITM (الشهادة، DNS، التوجيه المستهدف)
+├── مشترك/
+│ ├── المكونات/ # مكونات التفاعل (.tsx)
+│ ├── الثوابت/ # تعريفات الموفر (60+)، نطاقات MCP، استراتيجيات التوجيه
+│ ├── utils/ # قاطع الدائرة، المطهر، مساعدي المصادقة
+│ └── التحقق من الصحة/ # مخططات Zod v4
+└── sse/ # خط أنابيب الوكيل SSE
+
+open-sse/ # @omniroute/open-sse Workspace
+├── المنفذون/ # 14 منفذو الطلبات الخاصة بموفر الخدمة
+├── المعالجات/ # 11 معالجات الطلب (الدردشة والردود والتضمين والصور وما إلى ذلك)
+├── mcp-server/ # خادم MCP (25 أداة، 3 عمليات نقل، 10 نطاقات)
+├── الخدمات/ # 36+ خدمة (combo، autoCombo، RateLimitManager، إلخ.)
+├── مترجم/ # مترجمو التنسيق (OpenAI ↔ كلود ↔ الجوزاء ↔ الردود ↔ أولاما)
+├── محول/ # محول API الردود
+└── utils/ # 22 وحدة مساعدة (الدفق، TLS، الوكيل، التسجيل)
+
+إلكترون/ # تطبيق إلكترون لسطح المكتب (متعدد المنصات)
+
+الاختبارات/
+├── الوحدة/ # مشغل اختبار Node.js (122 ملف اختبار)
+├── التكامل/ # اختبارات التكامل
+├── e2e/ # اختبارات الكاتب المسرحي
+├── الأمان/ # اختبارات الأمان
+├── المترجم/ # اختبارات خاصة بالمترجم
+└── تحميل/ # اختبارات التحميلمستندات/ # التوثيق
+├── ARCHITECTURE.md # بنية النظام
+├── API_REFERENCE.md # جميع نقاط النهاية
+├── USER_GUIDE.md # إعداد الموفر، تكامل CLI
+├── استكشاف الأخطاء وإصلاحها.md # المشكلات الشائعة
+├── MCP-SERVER.md # خادم MCP (25 أداة)
+├── A2A-SERVER.md # بروتوكول الوكيل A2A
+├── AUTO-COMBO.md # محرك التحرير والسرد التلقائي
+├── تكامل أدوات CLI-TOOLS.md # تكامل أدوات CLI
+├── COVERAGE_PLAN.md # اختبار خطة تحسين التغطية
+├── openapi.yaml # مواصفات OpenAPI
+└── adr/ # سجلات قرارات الهندسة المعمارية```
+
+---
+
+## Adding a New Provider
+
+### Step 1: Register Provider Constants
+
+أضف إلى `src/shared/constants/providers.ts` - تم التحقق من صحة Zod عند تحميل الوحدة.### الخطوة 2: إضافة Executor (إذا كانت هناك حاجة إلى منطق مخصص)
+
+موجود بالفعل منفذ تنفيذي في open-sse/executors/your-provider.ts لتوسيع المنفذ الأساسي.### الخطوة 3: إضافة مترجم (إذا كان تنسيق غير OpenAI)
+
+يجب أن تكون موجودة في الطلب المترجم/الاستجابة في `open-sse/translator/`.### الخطوة 4: إضافة تكوين OAuth (إذا كان يعتمد على OAuth)
+
+إضافة بيانات موثوقة OAuth في `src/lib/oauth/constants/oauth.ts` وتطبيقات في `src/lib/oauth/services/`.### الخطوة 5: تسجيل النماذج
+
+أضف تعريفات الارتباطات في "open-sse/config/providerRegistry.ts".### الخطوة 6: إضافة الاختبارات
+
+اكتب السيولة الوحدة في `الاختبارات/الوحدة/` التي تغطي الحد الأدنى:
+
+- تسجيل المزود
+- ترجمة الطلب/الرد
+  -تسبب سبب---## Pull Request Checklist
+
+- [ ] اجتياز الاختبار (`اختبار npm`)
+- [ ] طباعات القلم (`npm run lint`)
+- [ ] نجاح البناء (`npm run build`)
+- [ ] تمت إضافة أنواع TypeScript للوظائف والواجهات العامة الجديدة
+- [ ] لا توجد أسرار ضمنية أو قيم بيعة
+- [ ] تم التحقق من صحة جميع المدخلات باستخدام مخططات Zod
+- [ ] تم تحديث سجل التغيير (في حالة التغيير الذي يواجهه المستخدم)
+- [ ] تم تحديث الوثائق (إن وجدت)---## Releasing
+
+تم إدارة الاختلاف عبر سير العمل `/generate-release`. عند إنشاء إصدار GitHub جديد، يتم**نشر المنتج اليدوي إلى npm**عبر إجراءات GitHub.---## Getting Help
+
+-**الهندسة المعمارية**: تجدد [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) -**مرجع واجهة برمجة التطبيقات**: راجع [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) -**المشاكل**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -**ADRs**: راجع `docs/adr/`