feat(release): v2.2.3 — bug fixes from community PRs

fix(google-cli): remove fake projectId fallback causing permission/verification errors (#285)
- antigravity.ts, openai-to-gemini.ts, geminiHelper.ts
- Throws clear error instead of silently sending with random project IDs

fix(claude): extend empty tool name filter to all message roles (#288)
- Pass 1.4 now covers all roles, not just assistant
- Filters tool_result with missing tool_use_id
- Filters top-level body.tools with empty names
- Explicit @swc/helpers COPY in Dockerfile runner-base stage

.agents/workflows/deploy-vps.md

@@ -4,52 +4,73 @@ description: Deploy the latest OmniRoute code to the Akamai VPS (69.164.221.35)
 
 # Deploy to VPS Workflow
 
-Deploy OmniRoute to the production VPS using Node.js + PM2 (no Docker).
+Deploy OmniRoute to the production VPS using `npm install -g` + PM2.
 
 **VPS:** `69.164.221.35` (Akamai, Ubuntu 24.04, 1GB RAM + 2.5GB swap)
-**App path:** `/opt/omniroute-app`
+**Local VPS:** `192.168.0.15` (same setup)
 **Process manager:** PM2 (`omniroute`)
 **Port:** `20128`
 
+> [!IMPORTANT]
+> PM2 runs from the global npm package at `/usr/lib/node_modules/omniroute`.
+> **DO NOT** use git clone or local copies. The `npm install -g` command handles
+> building, publishing, and installing the standalone app in one step.
+
 ## Steps
 
-### 1. Push to GitHub
+### 1. Publish to npm
 
-Ensure all changes are committed and pushed:
+Ensure the version in `package.json` is bumped and the package is published:
 
 ```bash
-git push origin main
+npm publish
 ```
 
-### 2. SSH into VPS, pull latest code, rebuild, and restart
+### 2. Install on VPS and restart PM2
 
 // turbo-all
 
 ```bash
-ssh root@69.164.221.35 "
-  cd /opt/omniroute-app &&
-  git fetch origin &&
-  git reset --hard origin/main &&
-  export NODE_OPTIONS='--max-old-space-size=1536' &&
-  npm install --no-audit --no-fund &&
-  npm run build &&
-  pm2 restart omniroute &&
-  pm2 save &&
-  echo '✅ Deploy complete!'
-"
+ssh root@69.164.221.35 "npm install -g omniroute@latest && pm2 restart omniroute && pm2 save && echo '✅ Deploy complete!'"
+```
+
+For the local VPS:
+
+```bash
+ssh root@192.168.0.15 "npm install -g omniroute@latest && pm2 restart omniroute && pm2 save && echo '✅ Deploy complete!'"
 ```
 
 ### 3. Verify the deployment
 
 ```bash
-ssh root@69.164.221.35 "pm2 list && curl -s -o /dev/null -w 'HTTP %{http_code}' http://localhost:20128/"
+ssh root@69.164.221.35 "pm2 list && cat \$(npm root -g)/omniroute/package.json | grep version | head -1 && curl -s -o /dev/null -w 'HTTP %{http_code}' http://localhost:20128/"
 ```
 
-Expected: PM2 shows `online`, HTTP returns `307` (redirect to login).
+Expected: PM2 shows `online`, version matches published, HTTP returns `307` (redirect to login).
+
+## How it works
+
+1. `npm publish` builds Next.js standalone + bundles everything into the npm package
+2. `npm install -g omniroute@latest` downloads and installs to `/usr/lib/node_modules/omniroute/`
+3. PM2 is registered to run `npm start` from that directory (cwd: `/usr/lib/node_modules/omniroute`)
+4. `pm2 restart omniroute` picks up the new code immediately
+
+## PM2 Setup (one-time)
+
+If PM2 needs to be reconfigured from scratch:
+
+```bash
+ssh root@<VPS> "
+  cd /usr/lib/node_modules/omniroute &&
+  PORT=20128 pm2 start app/server.js --name omniroute --env PORT=20128 &&
+  pm2 save &&
+  pm2 startup
+"
+```
 
 ## Notes
 
-- The VPS has only 1GB RAM. `NODE_OPTIONS='--max-old-space-size=1536'` uses swap for the build.
+- The `.env` file is at `/usr/lib/node_modules/omniroute/.env`. Back it up before major npm updates.
 - PM2 is configured with `pm2 startup` to auto-restart on reboot.
-- The `.env` file is at `/opt/omniroute-app/.env` (copied from the old Docker setup at `/opt/omniroute/.env`).
 - Nginx proxies `omniroute.online` → `localhost:20128`.
+- The VPS has only 1GB RAM — builds happen locally via `npm publish`, not on the VPS.

.agents/workflows/generate-release.md

@@ -6,61 +6,79 @@ description: Create a new release, bump version up to 1.x.10 threshold, update c
 
 Bump version, finalize CHANGELOG, commit, tag, push, publish to npm, and create GitHub release.
 
+> **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`.
+
 ## Steps
 
 ### 1. Determine new version
 
-Check current version in `package.json` and increment the patch number:
+Check current version in `package.json` and increment the **patch** number only:
 
 ```bash
 grep '"version"' package.json
 ```
 
-Version format: `1.x.y` — increment `y` for patch, `x` for minor (threshold: y=10 triggers x+1).
+Version format: `2.x.y` — examples:
 
-### 2. Finalize CHANGELOG.md
-
-Replace `[Unreleased]` header with the new version and date:
-
-```markdown
-## [1.x.y] — YYYY-MM-DD
-```
-
-### 3. Bump version in package.json
+- `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`)
 
 ```bash
-sed -i 's/"version": "OLD"/"version": "NEW"/' package.json
+# ALWAYS use patch:
+npm version patch --no-git-tag-version
 ```
 
-### 4. Stage, commit, and tag
+### 2. Regenerate lock file (REQUIRED after version bump)
+
+**Mandatory** — skipping causes `@swc/helpers` lock mismatch and CI failures:
+
+```bash
+npm install
+```
+
+### 3. 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
+```
+
+### 4. Update openapi.yaml version
+
+```bash
+sed -i 's/version: OLD/version: NEW/' docs/openapi.yaml
+```
+
+### 5. Stage, commit, and tag
 
 // turbo-all
 
 ```bash
-git add -A
-git commit -m "feat(release): vX.Y.Z — summary of changes"
-git tag -a vX.Y.Z -m "Release vX.Y.Z — summary"
+git add package.json package-lock.json CHANGELOG.md docs/openapi.yaml
+git commit -m "chore(release): v2.x.y — summary of changes"
+git tag -a v2.x.y -m "Release v2.x.y"
 ```
 
-### 5. Push to GitHub
+### 6. Push to GitHub
 
 ```bash
-git push origin main
-git push origin vX.Y.Z
+git push origin main --tags
 ```
 
-### 6. Publish to npm
-
-```bash
-npm publish
-```
-
-Wait for completion (prepublishOnly runs `npm run build:cli` automatically).
-
 ### 7. Create GitHub release
 
 ```bash
-gh release create vX.Y.Z --title "Release vX.Y.Z" --notes-file /tmp/release_notes.md
+gh release create v2.x.y --title "v2.x.y — summary" --notes "..."
 ```
 
 ### 8. Deploy to VPS (if requested)
@@ -68,7 +86,7 @@ gh release create vX.Y.Z --title "Release vX.Y.Z" --notes-file /tmp/release_note
 See `/deploy-vps` workflow for Akamai VPS or use npm for local VPS:
 
 ```bash
-ssh root@<VPS_IP> "npm install -g omniroute@X.Y.Z && pm2 restart omniroute"
+ssh root@<VPS_IP> "npm install -g omniroute@2.x.y && pm2 restart omniroute"
 ```
 
 ## Notes
@@ -76,3 +94,4 @@ ssh root@<VPS_IP> "npm install -g omniroute@X.Y.Z && pm2 restart omniroute"
 - 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

.github/workflows/ci.yml

@@ -10,6 +10,9 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   lint:
     name: Lint

.github/workflows/deploy-vps.yml

@@ -16,12 +16,14 @@ jobs:
     steps:
       - 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

@@ -8,100 +8,47 @@ permissions:
   contents: read
 
 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
 
+      - name: Set up QEMU (for multi-arch builds)
+        uses: docker/setup-qemu-action@v3
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      - name: Build and push by digest
-        id: build
-        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@v7
-        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"
+          echo "Publishing Docker image: $IMAGE_NAME:$VERSION"
 
-      - name: Download digests
-        uses: actions/download-artifact@v8
+      - name: Build and push multi-arch image
+        uses: docker/build-push-action@v7
         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 ' *)
+          context: .
+          target: runner-base
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            ${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }}
+            ${{ env.IMAGE_NAME }}:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
 
       - name: Inspect image
         run: |

.github/workflows/electron-release.yml

@@ -55,17 +55,18 @@ jobs:
             target: win
             ext: .exe
           - platform: macos-intel
-            runner: macos-latest
-            target: mac
+            runner: macos-15-intel
+            target: mac-x64
             ext: .dmg
           - platform: macos-arm64
             runner: macos-latest
-            target: mac
+            target: mac-arm64
             ext: -arm64.dmg
           - platform: linux
             runner: ubuntu-latest
             target: linux
             ext: .AppImage
+            deb_ext: .deb
 
     steps:
       - name: Checkout
@@ -78,7 +79,7 @@ jobs:
           cache: npm
 
       - name: Cache node_modules
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: node_modules
           key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
@@ -93,12 +94,27 @@ jobs:
           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 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
@@ -110,6 +126,12 @@ jobs:
           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
@@ -120,7 +142,7 @@ jobs:
           fi
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: electron-${{ matrix.platform }}
           path: release-assets/
@@ -136,7 +158,7 @@ jobs:
           fetch-depth: 0
 
       - name: Download all artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           path: release-assets
           merge-multiple: true
@@ -164,14 +186,14 @@ jobs:
           draft: false
           prerelease: false
           generate_release_notes: true
+          fail_on_unmatched_files: false
           files: |
             release-assets/*.dmg
-            release-assets/*-arm64.dmg
             release-assets/*.exe
             release-assets/*.AppImage
+            release-assets/*.deb
             release-assets/*.blockmap
             release-assets/*.source.tar.gz
             release-assets/*.source.zip
-            release-assets/OmniRoute.exe
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/npm-publish.yml

@@ -22,21 +22,30 @@ jobs:
           node-version: 22
           registry-url: https://registry.npmjs.org
 
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build standalone app
-        run: npm run build:cli
+      - name: Install dependencies (skip scripts to avoid heavy build)
+        run: npm install --ignore-scripts --no-audit --no-fund
 
       - name: Sync version from release tag
         run: |
           VERSION="${GITHUB_REF_NAME}"
-          # Remove 'v' prefix if present (v0.1.0 -> 0.1.0)
+          # Remove 'v' prefix if present (v2.1.0 -> 2.1.0)
           VERSION="${VERSION#v}"
           npm version "$VERSION" --no-git-tag-version --allow-same-version
           echo "Publishing version: $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=$(node -p "require('./package.json').version")
+          # 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
+          npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -1,5 +1,10 @@
 # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
 
+# project-specific directories
+.omnivscodeagent/
+omnirouteCloud/
+omnirouteSite/
+
 # dependencies
 node_modules/
 /.pnp
@@ -77,6 +82,9 @@ docs/*
 !docs/screenshots/
 !docs/i18n/
 !docs/i18n/**
+!docs/A2A-SERVER.md
+!docs/AUTO-COMBO.md
+!docs/MCP-SERVER.md
 
 # open-sse tests
 open-sse/test/*
@@ -89,14 +97,11 @@ 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
@@ -117,3 +122,8 @@ icon.iconset/
 
 # VS Code Extension (independent Git repo)
 vscode-extension/
+
+# SQLite residual files
+*.sqlite-shm
+*.sqlite-wal
+*.sqlite-journal

CHANGELOG.md

@@ -7,6 +7,593 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.2.3] — 2026-03-10
+
+> ### 🐛 Bug Fixes · 🔧 Reliability
+
+### Bug Fixes
+
+- **Antigravity/Gemini CLI: remove fake projectId fallback (#285)** — OmniRoute was generating random fallback project IDs (e.g. `useful-fuze-a04c5`) when OAuth credentials lacked a real GCP `projectId`. This caused confusing `Permission denied on resource project` and `Verify your account` errors from Google. Now throws a clear actionable error: _reconnect OAuth so OmniRoute can load your real Cloud Code project_. Affects `antigravity.ts`, `openai-to-gemini.ts`, `geminiHelper.ts`.
+- **Claude Code: filter empty-named tool_use blocks across all message roles (#288)** — Pass 1.4 only filtered empty tool names from `assistant` messages. Extended to all roles (user, system). Also filters `tool_result` blocks missing `tool_use_id`, and top-level `body.tools` declarations with empty names. Prevents `Invalid input[x].name: empty string` 400 errors from Claude API.
+- **Docker: explicit @swc/helpers copy (#288)** — Added `COPY --from=builder /app/node_modules/@swc/helpers` to Dockerfile `runner-base` stage. The standalone tracer doesn't always include this package, causing runtime `MODULE_NOT_FOUND` crashloops.
+
+---
+
+## [2.2.2] — 2026-03-10
+
+> ### ✨ New Features · 🔀 Model Aliases
+
+### New Features
+
+- **system-info.mjs (#280)** — New `npm run system-info` command that collects Node.js version, OmniRoute version, OS info, CLI tool versions (iflow, gemini, claude, codex, antigravity, droid, openclaw, kilo, cursor, aider), Docker/PM2 status, and system packages. Outputs `system-info.txt` for easy attachment to bug reports.
+
+### Model Aliases
+
+- **Kimi K2/K2.5 Fireworks aliases (#265)** — Built-in aliases added: `fireworks/accounts/fireworks/models/kimi-k2p5` and `kimi-k2p5` → `moonshotai/Kimi-K2.5`; same for `kimi-k2` → `moonshotai/Kimi-K2`. Fireworks long path model names now auto-resolve.
+- **Mistral short aliases (#278)** — `mistral-large` → `mistral-large-latest`, `mistral-small` → `mistral-small-latest`, `codestral` → `codestral-latest`.
+- **Llama short aliases** — `llama-3.3` → `llama-3.3-70b-versatile`, `llama-3-70b` → `llama-3.3-70b-versatile`, `llama-3-8b` → `llama3-8b-8192`.
+- **Custom aliases** — Users can define their own aliases in **Settings → Model Aliases** tab. Example: `gpt-5.4` → `cx/gpt-5.4`.
+
+---
+
+## [2.2.1] — 2026-03-10
+
+> ### 🐛 Bug Fixes · 🔐 Security · 🔧 CI
+
+### Bug Fixes
+
+- **Gemini image routing (#273)** — `gemini-3.1-flash-image-preview` was missing from the `antigravity` image provider registry in `imageRegistry.ts`, causing image generation to fall through to the chat handler. Added alongside `gemini-2.5-flash-preview-image-generation`.
+- **Ollama Cloud model listing (#276)** — `ollama-cloud` was absent from `PROVIDER_MODELS_CONFIG` in the models route, causing 400 errors when listing models from `api.ollama.com`. Entry added.
+- **Missing apiKey error clarity (#277)** — When login is disabled and a provider has no API key configured, the model import route now returns `400` with a clear message instead of a generic `401 Unauthorized`.
+
+### Security
+
+- **TLS validation re-enabled (GHSA-50)** — `mitm/server.ts`: `rejectUnauthorized` now defaults to `true`. Opt-out only via `MITM_DISABLE_TLS_VERIFY=1`.
+- **Path traversal hardening (GHSA-41–49)** — Added `safePath()`, `safeProfilePath()`, `safeLogPath()` helpers across `backupService.ts`, `db/backup.ts`, `codex-profiles/route.ts`, and `mitm/server.ts`. All user-supplied IDs/filenames are now anchored within their allowed directories using `path.resolve()` + bounds check.
+- **Prototype pollution fix (GHSA-18–20)** — `usageHistory.ts`: `pendingRequests` maps now use `Object.create(null)` + `hasOwnProperty` guards, preventing `__proto__` / `constructor` injection via crafted provider IDs.
+- **Dependency: dompurify updated to ^3.3.2** — Resolves CVE-2026-0540 (XSS in rendered HTML).
+- **GitHub Actions: added `permissions: contents: read`** — Prevents token over-permission in CI jobs.
+
+### CI
+
+- **Lock file sync** — Added `@swc/helpers: "^0.5.19"` override in `package.json`; regenerated `package-lock.json`. Fixes `npm ci` failures across `ci.yml` and `docker-publish.yml`.
+- **npm-publish: skip if version exists** — Workflow now checks registry before publishing; exits cleanly with a warning instead of failing with `E403` if the version is already on npm.
+- **npm-publish: use `npm install` instead of `npm ci`** — Prevents publish failures when a tag commit's lock file is slightly out of sync.
+- **Lint: `cursor.ts` any-budget** — Replaced `any` with `unknown` + type narrowing in `isToolBoundaryAbort()`.
+
+---
+
+## [2.2.0] — 2026-03-10
+
+> ### 🔧 Bug Fixes · Provider Support · CI Recovery
+
+### Bug Fixes
+
+- **Cursor tool-call loop (#275/#274)** — Stabilized Cursor executor to stop double-translating tool results. Set-based `finalizedIds` for O(1) dedup, byte guard (`0x7b`) before payload `.toString()`, `escapeXml()` to prevent tag injection, and converted all debug `console.log` to `debugLog()`. Fixes the 400 Bad Request loop that corrupted multi-turn Cursor sessions.
+- **A/V provider validation (#281)** — Added `validateElevenLabsProvider` (GET `/v1/voices` with `xi-api-key`) and `validateInworldProvider` (POST `/tts/v1/voice` with Basic auth) so both providers can be test-connected without false 400 errors.
+- **OpenAI-compatible Add Connection button (#272)** — "Add Connection" button was hidden behind `!isCompatible` guard in the Connections card. Button now appears for compatible providers when 0 connections exist, limited to 1 (matches single-key-per-node policy).
+- **CI: unit tests** — Fixed circuit breaker tests using wrong instance keys (`combo:groq` → `combo:groq/llama-3.3-70b`).
+- **CI: E2E protocol-visibility** — Updated spec to click "Protocols" tab before asserting MCP/A2A links (now tabs inside `/dashboard/endpoint`).
+- **CI: i18n** — Added missing `header.mcp`, `header.mcpDescription`, `header.a2a`, `header.a2aDescription` keys to `en.json`.
+
+### New Features
+
+- **Kimi Coding plan quota display (#279)** — New `getKimiUsage()` with `X-Msh-*` device headers. Parses weekly quota + rate-limit breakdown from `/v1/usages`. Wires `kimi-coding` into the provider usage switch; adds quota capability flag.
+
+### Dependencies
+
+- **Dev dependencies** — Bumped `@playwright/test`, `@types/react`, `eslint-plugin-*` and 2 others (#264).
+- **Prod dependencies** — Bumped 2 production packages (#263).
+
+---
+
+## [2.1.2] — 2026-03-09
+
+> ### 🔨 CI Green + Electron .deb + Link Fixes
+
+### Bug Fixes
+
+- **CI: `check:docs-sync`** — fixed 2 failures: bumped `docs/openapi.yaml` version to 2.1.1 (was 2.0.0), added required `## [Unreleased]` section to CHANGELOG.
+- **CI: npm-publish workflow** — rewrote to use `npm ci --ignore-scripts` + explicit `node scripts/prepublish.mjs` with `JWT_SECRET` env; fixes the prepublish loop that caused every npm CI publish to fail.
+- **README.md language bar** — fixed all 29 broken links that pointed to root `README.<lang>.md` (now `docs/i18n/<lang>/README.md`).
+- **docs/i18n READMEs** — fixed back-links to English (`../../README.md`) and cross-links to sibling languages.
+
+### New Features
+
+- **Electron Linux `.deb` package** — added `deb` target (x64 + arm64) to `electron/package.json`; updated `electron-release.yml` to collect and attach `.deb` files to GitHub releases alongside `.AppImage`.
+
+> ### 🔧 CI Fix + Docs Reorganization
+
+### Bug Fixes
+
+- **CI: fixed `any`-budget violation in `open-sse/services/usage.ts`** — replaced 5 explicit `any` annotations with proper TypeScript types (`UsageQuota`, `JsonRecord`, `Error`), restoring the green CI lint gate.
+- **Deleted all duplicate draft GitHub releases** — automated workflow was creating unnamed draft releases on each push; cleaned up all draft artifacts for v2.0.17–v2.1.0.
+
+### Documentation
+
+- **Root cleanup**: moved all 29 `README.<lang>.md` files from the project root into their correct `docs/i18n/<lang>/README.md` locations. The root now contains only `README.md` (English).
+- **i18n sync**: all 11 `docs/*.md` files synced with language bar headers to all 30 `docs/i18n/<lang>/` directories (319 file updates across ar, bg, da, de, es, fi, fr, he, hu, id, in, it, ja, ko, ms, nl, no, phi, pl, pt, pt-BR, ro, ru, sk, sv, th, uk-UA, vi, zh-CN).
+
+---
+
+## [2.1.0] — 2026-03-09
+
+> ### 🗺️ Full Provider-UI Gap Audit — All Backends Now Accessible from Dashboard
+
+### ✨ New Features
+
+- **7 missing API-key providers added to Providers page** — ElevenLabs, Cartesia, PlayHT, Inworld, SD WebUI, ComfyUI, and Ollama Cloud now all appear in `/dashboard/providers` with API key configuration cards. Previously these providers existed only in the backend with no UI entry point.
+
+- **Media page: provider + model selectors for all 5 modalities** — `/dashboard/media` now has a **Provider** dropdown and a **Model** dropdown for every tab. Selecting a provider shows only its models:
+  - 🖼️ **Image**: OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, SD WebUI, ComfyUI (9 providers)
+  - 🎬 **Video**: ComfyUI (AnimateDiff, SVD), SD WebUI (2 providers)
+  - 🎵 **Music**: ComfyUI (Stable Audio Open, MusicGen)
+  - 🔊 **Speech**: OpenAI, ElevenLabs, Deepgram, Hyperbolic, NVIDIA, Inworld, Cartesia, PlayHT, HuggingFace, Qwen (10 providers). Voice dropdown updates per provider.
+  - 🎙️ **Transcription**: New tab — OpenAI Whisper, Groq, Deepgram, AssemblyAI, NVIDIA, HuggingFace, Qwen (7 providers). File upload instead of text prompt.
+
+- **Playground: 4 new endpoint options** — Audio Transcription (`/v1/audio/transcriptions`), Video Generation (`/v1/videos/generations`), Music Generation (`/v1/music/generations`), Rerank (`/v1/rerank`). Previously only Chat, Responses, Images, Embeddings, Speech were available.
+
+- **CLI Tools: OpenCode + Kiro** — Both tools now appear in `/dashboard/cli-tools` with step-by-step setup guides. OpenCode was already detected in Agents but had no configuration screen.
+
+- **Agents: expanded CLI fingerprint providers** — kiro, cursor, kimi-coding, kilocode, cline added to the CLI fingerprint toggle list (previously only codex, claude, github, antigravity).
+
+### 🧹 Maintenance
+
+- Deleted 3 stale remote branches (`features-agente-mcp-a2a`, `fix/issue-218-round-robin-lastUsedAt`, `fix/resolve-open-issues`) — all their changes were already in main.
+- Added minimal `layout.tsx` to all error-page routes (`400`, `401`, `403`, `408`, `429`, `500`, `502`, `503`) to fix Next.js standalone build.
+
+### 📁 Files Changed
+
+| File                                                      | Change                                                     |
+| --------------------------------------------------------- | ---------------------------------------------------------- |
+| `src/shared/constants/providers.ts`                       | Add 7 missing APIKEY_PROVIDERS                             |
+| `src/shared/constants/cliTools.ts`                        | Add opencode, kiro entries                                 |
+| `src/app/(dashboard)/dashboard/media/MediaPageClient.tsx` | Full rewrite — provider/model selectors, transcription tab |
+| `src/app/(dashboard)/dashboard/playground/page.tsx`       | Add 4 new endpoint options                                 |
+| `src/app/(dashboard)/dashboard/agents/page.tsx`           | Expand cliCompatProviders list                             |
+| `src/app/{400..503}/layout.tsx`                           | Add minimal layouts to fix Next.js build                   |
+
+---
+
+## [2.0.20] — 2026-03-09
+
+> ### 🔊 TTS Expansion + 📱 Mobile UX + 🏷️ Friendly Names
+
+### ✨ New Features
+
+- **Inworld TTS provider** (`#248`) — Cloud TTS via `https://api.inworld.ai/tts/v1/voice`; Basic auth; JSON response with base64 `audioContent` decoded to binary. Use prefix `inworld/<model-id>`. Available models: `inworld-tts-1.5-max`, `inworld-tts-1.5-mini`.
+
+- **Cartesia TTS provider** (`#248`) — Cloud TTS via `https://api.cartesia.ai/tts/bytes`; `X-API-Key` + `Cartesia-Version: 2024-06-10` headers; returns binary audio stream. Use prefix `cartesia/<model-id>`. Available models: `sonic-2`, `sonic-3`. Voice is mapped via voice ID.
+
+- **PlayHT TTS provider** (`#248`) — Cloud TTS via `https://api.play.ht/api/v2/tts/stream`; dual auth `X-USER-ID` + `Authorization: Bearer` (store token as `userId:apiKey`). Use prefix `playht/<model-id>`. Available models: `PlayDialog`, `Play3.0-mini`.
+
+- **ElevenLabs voice presets in dashboard** (`#248`) — `/dashboard/media` → Speech tab now shows provider-aware voice dropdowns: ElevenLabs (9 premade voices), Cartesia (3 preset voices), Deepgram Aura (5 voices), Inworld (2 voices), OpenAI (6 standard voices). Voice list updates automatically based on the model prefix typed.
+
+- **Speech tab in `/dashboard/media`** (`#248`) — New "Text to Speech" tab alongside Image/Video/Music. Includes model text input (supports all provider prefixes), voice/format selectors, and an inline `<audio>` player with Blob URL + download button.
+
+- **Text to Speech in `/dashboard/playground`** (`#248`) — New endpoint option; pre-filled body with model/input/voice/response_format; binary audio responses auto-rendered in an inline audio player instead of JSON.
+
+- **Friendly display names** (`#260`) — New `src/lib/display/names.ts` with `getAccountDisplayName()` (name → displayName → email → Account #XXXXXX) and `getProviderDisplayName()` (node.name → node.prefix → de-UUIDed ID). Applied to `usageStats.ts` and `rate-limits/route.ts` to replace raw UUID fallbacks.
+
+### 📱 Mobile UX (`#261`)
+
+- **Sidebar scroll on short screens** — Mobile sidebar wrapper now uses `h-dvh` for true viewport height; `aside` receives `h-full` so the inner `nav` can actually scroll on short devices.
+- **Providers page action areas** — All 4 section headers changed from `flex justify-between` to `flex flex-wrap` so multi-button action bars wrap gracefully on narrow screens.
+
+### 📁 New Files
+
+| File                       | Purpose                                                      |
+| -------------------------- | ------------------------------------------------------------ |
+| `src/lib/display/names.ts` | Centralized friendly-name helpers for accounts and providers |
+
+### 📁 Files Changed
+
+| File                                                      | Change                                                                  |
+| --------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `open-sse/config/audioRegistry.ts`                        | Add Inworld, Cartesia, PlayHT to `AUDIO_SPEECH_PROVIDERS`               |
+| `open-sse/handlers/audioSpeech.ts`                        | Add `handleInworldSpeech`, `handleCartesiaSpeech`, `handlePlayHtSpeech` |
+| `src/app/(dashboard)/dashboard/media/MediaPageClient.tsx` | Full rewrite with Speech tab + provider-aware voice presets             |
+| `src/app/(dashboard)/dashboard/playground/page.tsx`       | Add Speech endpoint option + audio Blob URL response renderer           |
+| `src/app/(dashboard)/dashboard/providers/page.tsx`        | `flex-wrap` mobile fix for section headers                              |
+| `src/lib/usage/usageStats.ts`                             | Use `getAccountDisplayName()`                                           |
+| `src/app/api/rate-limits/route.ts`                        | Use `getAccountDisplayName()`                                           |
+| `src/shared/components/Sidebar.tsx`                       | Add `h-full` to aside                                                   |
+| `src/shared/components/layouts/DashboardLayout.tsx`       | Add `h-dvh` to mobile sidebar wrapper                                   |
+
+---
+
+## [2.0.19] — 2026-03-09
+
+> ### 🔌 New Provider: Ollama Cloud + 🔒 Security Hardening
+
+### ✨ New Features
+
+- **Ollama Cloud provider** (`#255`, alias: `ollamacloud`) — API-key provider via `https://api.ollama.com/v1` (OpenAI-compatible). Use any cloud model with the `ollamacloud/<model>` prefix. Generate API keys at https://ollama.com/settings/api-keys. Pre-loaded models: Gemma 3 27B, Llama 3.3 70B, Qwen3 72B, Devstral 24B, DeepSeek R2 671B, Phi 4 14B, Mistral Small 3.2 24B. Passthrough model names also supported.
+
+### 🔒 Security Fixes (`#258`)
+
+- **CRITICAL — DB export endpoint unprotected** — Added `isAuthRequired + isAuthenticated` guard to `GET /api/db-backups/export`. Previously any unauthenticated user could download the full SQLite database (containing OAuth tokens and API keys).
+
+- **CRITICAL — DB import endpoint unprotected** — Added `isAuthRequired + isAuthenticated` guard to `POST /api/db-backups/import`. Previously any unauthenticated user could replace the application database, effectively taking admin control.
+
+- **HIGH — Cursor auto-import endpoint unprotected** — Added auth guard to `GET /api/oauth/cursor/auto-import`. Previously any unauthenticated user could read Cursor IDE access tokens from the local machine.
+
+- **HIGH — Kiro auto-import endpoint unprotected** — Added auth guard to `GET /api/oauth/kiro/auto-import`. Previously any unauthenticated user could read AWS SSO refresh tokens from the local filesystem.
+
+- **LOW (×4) — Non-constant-time string comparison (CWE-208)** — Replaced `===` with `safeEqual()` via `crypto.timingSafeEqual()` at all 4 email/workspaceId comparison sites in the OAuth route, preventing timing-oracle attacks.
+
+- **False positive — `package.json` `reset-password`** — The scanner flagged `omniroute-reset-password` (a CLI binary name) as a hardcoded password. This is not a credential; no action required.
+
+### 📁 Files Changed
+
+| File                                             | Change                                    |
+| ------------------------------------------------ | ----------------------------------------- |
+| `open-sse/config/providerRegistry.ts`            | Add `ollama-cloud` registry entry         |
+| `src/app/api/db-backups/export/route.ts`         | Add auth guard (CRITICAL)                 |
+| `src/app/api/db-backups/import/route.ts`         | Add auth guard (CRITICAL)                 |
+| `src/app/api/oauth/cursor/auto-import/route.ts`  | Add auth guard (HIGH)                     |
+| `src/app/api/oauth/kiro/auto-import/route.ts`    | Add auth guard (HIGH)                     |
+| `src/app/api/oauth/[provider]/[action]/route.ts` | Replace `===` with `safeEqual()` (LOW ×4) |
+
+---
+
+## [2.0.18] — 2026-03-09
+
+> ### 🐛 Bug Fixes — Cursor Decompression, Codex Token Refresh, Password Setup
+
+### 🐛 Bug Fixes
+
+- **#250 — Cursor OAuth tool calls fail (decompression error)** — Frames flagged as `GZIP_ALT (0x02)` or `GZIP_BOTH (0x03)` may use zlib deflate format instead of gzip. `decompressPayload()` previously only tried `gunzipSync`, failing silently and returning raw bytes that downstream protobuf parsing rejected. Fix adds cascaded fallbacks: `gunzipSync` → `inflateSync` → `inflateRawSync`, with verbose error logging when all methods fail.
+
+- **#251 — Codex OAuth accounts fail after v2.0.16 upgrade** — `CodexExecutor` was inheriting `BaseExecutor.refreshCredentials()` which always returns `null`. When a Codex access token expires after a server upgrade/restart, `chatCore.ts` calls `executor.refreshCredentials()` on every 401 response — which returned `null` for Codex, blocking token renewal entirely. Fix: `CodexExecutor` now overrides `refreshCredentials()` to call the existing `refreshCodexToken()` from `tokenRefresh.ts`, restoring automatic recovery.
+
+- **#256 — Configure Password button broken after skipping onboarding** — `isAuthRequired()` in `apiAuth.ts` had a `setupComplete` guard: once `setupComplete=true`, it always required auth. But when the password step is skipped, `setupComplete=true` and `password=null`, making the dashboard inaccessible without a valid JWT (which doesn't exist because no password was ever set). Fix: removed the `setupComplete` check — auth is now skipped whenever no password is configured at all, allowing users to navigate to Settings → Security to set a first password.
+
+### 📁 Files Changed
+
+| File                           | Change                                                               |
+| ------------------------------ | -------------------------------------------------------------------- |
+| `open-sse/executors/cursor.ts` | Add `inflateSync`/`inflateRawSync` fallback in `decompressPayload()` |
+| `open-sse/executors/codex.ts`  | Override `refreshCredentials()` to call `refreshCodexToken()`        |
+| `src/shared/utils/apiAuth.ts`  | Remove `setupComplete` guard from `isAuthRequired()`                 |
+
+---
+
+## [2.0.17] — 2026-03-09
+
+> ### 🐛 Bug Fixes + 🔌 Integrations
+
+### 🐛 Bug Fixes
+
+- **Antigravity/Gemini streaming broken in Claude Code** — Fixed `gemini-to-claude.ts` response translator that was emitting `content_block_start` + `content_block_stop` on **every single streaming chunk**. Claude Code interpreted each block as a separate element, rendering each text delta on its own line. Fix: `openTextBlockIdx` state variable keeps the text block open across chunks and only closes it when the block type changes or at `finishReason`. Fixes #253.
+
+### 🔌 New Integrations
+
+- **OpenCode native integration** — Agents dashboard now shows a **"Download opencode.json"** button when `opencode` is detected as installed. Clicking it fetches all available models from `/v1/models`, auto-fills `baseURL` from your current OmniRoute instance, and downloads a ready-to-use `opencode.json` config file. Inspired by @Alph4d0g's plugin (discussion #162).
+
+### 🔧 CI Improvements
+
+- **Electron macOS Intel CI fixed** — Updated CI runner from deprecated `macos-13` to `macos-15-intel` (GitHub's new Intel x64 runner, GA since April 2025). Fixes all macOS Intel build failures.
+- **Electron binary version sync** — Added step to sync `electron/package.json` version before build so binaries are named correctly (`OmniRoute-2.0.17.dmg` instead of `OmniRoute-2.0.13.dmg`).
+- **Release asset deduplication** — Removed duplicate `*-arm64.dmg` pattern from release files; added `fail_on_unmatched_files: false` for optional `.blockmap` files.
+
+---
+
+## [2.0.16] — 2026-03-08
+
+> ### 🐛 Bug Fixes + 🔧 CI Hardening
+
+### 🐛 Bug Fixes
+
+- **NanoBanana async image polling** — Fixed `data: []` results from `/v1/images/generations` for NanoBanana. The previous implementation treated the submit response as a final image payload. NanoBanana APIs return a `taskId` requiring status polling — the handler now submits, extracts `taskId`, polls `/record-info` until `successFlag=1`, and normalizes to OpenAI format. Added `aspectRatio`/`resolution` inference from `size`. Backward compatible. PR #247 by @hijak
+
+### 🔧 CI Fixes
+
+- **Electron build token missing** — `electron-builder`'s GitHub publish provider requires `GH_TOKEN` to be set, but the build step didn't have it in its `env`. The workflow was failing with `GitHub Personal Access Token is not set` on all 4 platforms. **Fixed**: added `GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}` to the `Build Electron for...` step (`.github/workflows/electron-release.yml`)
+
+- **Security test `inputSanitizer.js` import** — `tests/unit/security-fase01.test.mjs` imported `inputSanitizer.js` (non-existent) instead of `inputSanitizer.ts`, causing `ERR_MODULE_NOT_FOUND` in CI. Fixed extension.
+
+- **Route validation lint (t06)** — `POST /api/acp/agents` used `request.json()` without `validateBody()`, failing `check:route-validation:t06`. Added `validateBody(jsonObjectSchema)` — all 139 routes now pass.
+
+- **Deploy to VPS SSH failure** — Added `continue-on-error: true` and `command_timeout: 5m` to the SSH step so that connection failures (when VPS is unreachable) don't mark the workflow as failed.
+
+### 📁 Files Changed
+
+| File                                              | Change                                                   |
+| ------------------------------------------------- | -------------------------------------------------------- |
+| `open-sse/config/imageRegistry.ts`                | Added NanoBanana `statusUrl`, extended `supportedSizes`  |
+| `open-sse/handlers/imageGeneration.ts`            | NanoBanana async submit/poll flow + sync backward compat |
+| `tests/unit/nanobanana-image-handler.test.mjs`    | **NEW** — unit tests                                     |
+| `tests/unit/nanobanana-image-generation.test.mjs` | **NEW** — unit tests                                     |
+| `.github/workflows/electron-release.yml`          | Add `GH_TOKEN` to build step (critical fix)              |
+| `tests/unit/security-fase01.test.mjs`             | Fix `inputSanitizer.js` → `.ts`                          |
+| `src/app/api/acp/agents/route.ts`                 | Add `validateBody(jsonObjectSchema)` to POST             |
+| `.github/workflows/deploy-vps.yml`                | `continue-on-error: true` + `command_timeout: 5m`        |
+
+---
+
+## [2.0.15] — 2026-03-08
+
+> ### ✨ New Features + 🐛 Bug Fix
+
+### ✨ New Features
+
+- **Codex Effort Clamp** — `CodexExecutor` now caps `reasoning_effort` to each model's maximum. Added `MAX_EFFORT_BY_MODEL` table and `clampEffort()` — silently clamps with debug log. Unknown models default to `xhigh` (unrestricted). PR #246
+
+- **OpenRouter Catalog Cache** — New `src/lib/catalog/openrouterCatalog.ts`: persistent JSON cache at `DATA_DIR/cache/openrouter-catalog.json`, TTL 24h (`OPENROUTER_CATALOG_TTL_MS`), stale-if-error fallback. New endpoint `GET /api/models/openrouter-catalog` (authenticated, `?refresh=true` forces refresh). PR #246
+
+- **Quota Preflight — opt-in toggle per provider** — New `open-sse/services/quotaPreflight.ts`. Proactively checks quota before requests, enabling account switching before 429s. Toggle via `providerSpecificData.quotaPreflightEnabled` (default: `false`). Extensible via `registerQuotaFetcher()`. Graceful degradation. PR #246
+
+- **Quota Session Monitor — opt-in toggle per provider** — New `open-sse/services/quotaMonitor.ts`. Adaptive polling: 60s normal → 15s critical. Alert deduplication per session (5min window). Toggle via `providerSpecificData.quotaMonitorEnabled` (default: `false`). `timer.unref()` for clean exit. PR #246
+
+### 🛠️ Improvements
+
+- **Provider API supports `providerSpecificData` partial patch** — `PUT /api/providers/[id]` merges `providerSpecificData` (preserves existing keys). Validation schema updated. PR #246
+
+### 🐛 Bug Fixes
+
+- **#244 — Gemini rejects schemas with `"optional"` field** — Added `"optional"` to `UNSUPPORTED_SCHEMA_CONSTRAINTS` in `geminiHelper.ts`. Gemini API returns `400: Cannot find field: optional` when tool schemas include this field. PR #245
+
+### 📦 Desktop Binaries (Electron)
+
+Auto-generated on tag push via `electron-release.yml`:
+
+| Platform            | Download                                           |
+| ------------------- | -------------------------------------------------- |
+| Windows             | `OmniRoute-Setup.exe` + `OmniRoute.exe` (portable) |
+| macOS Intel         | `OmniRoute.dmg`                                    |
+| macOS Apple Silicon | `OmniRoute-arm64.dmg`                              |
+| Linux               | `OmniRoute.AppImage`                               |
+
+### 📁 Files Changed
+
+| File                                             | Change                     |
+| ------------------------------------------------ | -------------------------- |
+| `open-sse/executors/codex.ts`                    | Effort clamp logic         |
+| `open-sse/services/quotaPreflight.ts`            | **NEW**                    |
+| `open-sse/services/quotaMonitor.ts`              | **NEW**                    |
+| `src/lib/catalog/openrouterCatalog.ts`           | **NEW**                    |
+| `src/app/api/models/openrouter-catalog/route.ts` | **NEW**                    |
+| `src/app/api/providers/[id]/route.ts`            | providerSpecificData merge |
+| `src/shared/validation/schemas.ts`               | Schema update              |
+| `open-sse/translator/helpers/geminiHelper.ts`    | Fix #244                   |
+
+---
+
+## [2.0.14] — 2026-03-08
+
+> ### 🐛 Bug Fixes + Electron Release Fix
+
+### 🐛 Bug Fixes
+
+- **#243 — OpenAI-Compatible model name stripping** — Fixed `model.split("/").pop()` stripping vendor namespace from model names with slashes. Models like `moonshotai/Kimi-K2-Instruct` were being truncated to just `Kimi-K2-Instruct`. Now uses `slice(1).join("/")` to preserve the full vendor/model path
+- **#242 — Multimodal image_url rejection on Responses API** — Fixed `image_url` content parts from Chat Completions format being passed through without conversion to `input_image` format expected by Responses/Codex backends. Now properly converts `{type: "image_url", image_url: {url: "..."}}` → `{type: "input_image", image_url: "..."}`
+
+### 🔧 Infrastructure
+
+- **PR #241 — Electron release workflow** — Synced `electron/package.json` version to `2.0.13`, separated macOS x64 and arm64 into dedicated CI runner jobs, using `macos-13` (Intel) runner for x64 builds to prevent cross-compilation timeouts (thanks @benzntech)
+
+### 📁 Files Changed
+
+| File                                              | Change                                                   |
+| ------------------------------------------------- | -------------------------------------------------------- |
+| `open-sse/executors/default.ts`                   | Fix model name stripping: `pop()` → `slice(1).join("/")` |
+| `open-sse/translator/request/openai-responses.ts` | Convert `image_url` → `input_image` for Responses API    |
+| `.github/workflows/electron-release.yml`          | Separate mac x64/arm64 builds                            |
+| `electron/package.json`                           | Version sync + arch-specific build scripts               |
+
+---
+
+## [2.0.11] — 2026-03-07
+
+> ### 🤖 ACP Agents Dashboard + Anti-Ban Docs
+
+### ✨ New Features
+
+- **ACP Agents Dashboard** — New Debug > Agents page: grid of 14 built-in CLI agents (codex, claude, goose, gemini, openclaw, aider, opencode, cline, qwen-code, forge, amazon-q, interpreter, cursor-cli, warp) with installation status, version detection, protocol badges, and custom agent form
+- **Custom Agent Support** — Users can register any CLI tool for auto-detection via dashboard form (name, binary, version command, spawn args). Stored in settings DB
+- **60-Second Detection Cache** — Agent detection results cached to avoid repeated `execSync` calls
+
+### 🐛 Bug Fixes
+
+- **Fix `settings.themeCoral` untranslated** — Theme color "Coral" was missing from the `settings` i18n namespace in all 30 languages. Added translations for all
+
+### 📝 Documentation
+
+- **Anti-Ban Features Clarified** — Improved README descriptions for TLS Fingerprint Spoofing and CLI Fingerprint Matching, emphasizing ban-risk reduction benefits and proxy IP preservation
+- **ACP Agents Dashboard** — Added to v2.0.9+ features table and deployment features table in README
+
+### 📁 Files Changed
+
+| File                                            | Change                                                           |
+| ----------------------------------------------- | ---------------------------------------------------------------- |
+| `src/lib/acp/registry.ts`                       | Expanded from 5 to 14 agents + custom agent support + 60s cache  |
+| `src/app/api/acp/agents/route.ts`               | GET/POST/DELETE for full agent management                        |
+| `src/app/(dashboard)/dashboard/agents/page.tsx` | New dashboard page                                               |
+| `src/shared/components/Sidebar.tsx`             | Added Agents to Debug section                                    |
+| `src/shared/validation/settingsSchemas.ts`      | Added `customAgents` array field                                 |
+| `src/i18n/messages/*.json` (×30)                | Fixed `themeCoral`, added sidebar `agents` key, agents namespace |
+
+---
+
+## [2.0.9] — 2026-03-07
+
+> ### 🚀 Feature Drop — Playground, CLI Fingerprints, ACP
+
+### ✨ New Features
+
+- **#234 — Model Playground** — Dashboard page to test any model directly (provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing metrics). Available in the Debug sidebar section.
+- **#223 — CLI Fingerprint Matching** — Per-provider header/body field ordering to match native CLI binary fingerprints, reducing account flagging risk. Enable via `CLI_COMPAT_<PROVIDER>=1` or `CLI_COMPAT_ALL=1` env vars.
+- **#235 — ACP Support** — Agent Client Protocol module with CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw), process spawner/manager, and `/api/acp/agents` endpoint.
+
+### 🧹 Housekeeping
+
+- **#192 & #200** — Closed as stale (needs-info, v1.8.1, no reproduction info provided)
+
+---
+
+## [2.0.8] — 2026-03-07
+
+> ### 🐛 Bug Fix — Custom Image Model Handler Resolution
+
+### 🐛 Bug Fixes
+
+- **#238 — Custom image models still fail in handler layer** — v2.0.7 fixed the route-layer validation, but the handler (`handleImageGeneration()`) called `parseImageModel()` again internally, rejecting custom models a second time. Fix: handler now accepts an optional `resolvedProvider` parameter; when provided, it skips re-validation and routes custom models to the OpenAI-compatible handler with a synthetic config. PR #239
+
+### 📁 Files Changed
+
+| File                                         | Change                                                                           |
+| -------------------------------------------- | -------------------------------------------------------------------------------- |
+| `open-sse/handlers/imageGeneration.ts`       | Added `resolvedProvider` param + custom model fallback                           |
+| `src/app/api/v1/images/generations/route.ts` | Tracks `isCustomModel`, passes `resolvedProvider`, credentials for custom models |
+
+---
+
+## [2.0.7] — 2026-03-07
+
+> ### 🐛 Bug Fixes — Custom Image Models + Codex OAuth Workspace Isolation
+
+### 🐛 Bug Fixes
+
+- **#232 — Custom Gemini image models fail on `/v1/images/generations`** — Custom models tagged with `supportedEndpoints: ["images"]` appeared in the model listing (GET) but were rejected by the POST handler. `parseImageModel()` only checked the built-in `IMAGE_PROVIDERS` registry. Fix: added a custom model DB fallback for models with the `images` endpoint tag. PR #237
+- **#236 — Codex OAuth overwrites existing connection when same email added to another workspace** — The OAuth callback route had 3 upsert blocks matching connections by email-only, bypassing the workspace-aware logic in `createProviderConnection()`. When the same email authenticated to a new workspace, the existing connection's `workspaceId` was silently overwritten. Fix: for Codex, the match now also checks `providerSpecificData.workspaceId`, allowing separate connections per workspace. PR #237
+
+### 📁 Files Changed
+
+| File                                             | Change                                               |
+| ------------------------------------------------ | ---------------------------------------------------- |
+| `src/app/api/v1/images/generations/route.ts`     | Custom model DB fallback in POST handler             |
+| `src/app/api/oauth/[provider]/[action]/route.ts` | Workspace-aware Codex matching in 3 upsert locations |
+
+### ⏭️ Issues Triaged
+
+- **#234** — Playground feature request — Acknowledged, added to roadmap
+- **#235** — ACP support feature request — Acknowledged, added to roadmap
+
+---
+
+## [2.0.6] — 2026-03-07
+
+> ### 🐛 Bug Fix — Custom Model API Format Routing
+
+### 🐛 Bug Fixes
+
+- **#204 — Custom model `apiFormat` not used in routing** — Custom models configured with `apiFormat: "responses"` in the dashboard were still being routed through the Chat Completions translator. The `apiFormat` field was stored in the DB and displayed in the UI, but never consumed by the routing layer. Fix: `getModelInfo()` now returns `apiFormat` from the custom model DB, and both `resolveModelOrError()` functions override `targetFormat` to `openai-responses` when set. PR #233
+
+### ✅ Issues Closed
+
+- **#205** — Combo endpoint support — Already implemented in v2.0.2
+- **#206** — Manual model→endpoint mapping — Already implemented in v2.0.2
+- **#223** — CLI fingerprint parity — Responded with 4-phase roadmap
+
+### 📁 Files Changed
+
+| File                              | Change                                                                 |
+| --------------------------------- | ---------------------------------------------------------------------- |
+| `src/sse/services/model.ts`       | Added `lookupCustomModelApiFormat()`, enriched `getModelInfo()` return |
+| `src/sse/handlers/chat.ts`        | Override `targetFormat` when `apiFormat === "responses"`               |
+| `src/sse/handlers/chatHelpers.ts` | Same override in duplicate `resolveModelOrError()`                     |
+
+---
+
+## [2.0.5] — 2026-03-06
+
+> ### 🐛 Bug Fix, Electron Auto-Update & Dependency Bumps
+
+### 🐛 Bug Fixes
+
+- **#224 — Chat→Responses translation creates invalid reasoning IDs** — Removed synthetic reasoning item generation in `openaiToOpenAIResponsesRequest()`. The translator was creating reasoning items with IDs like `reasoning_15`, but OpenAI's Responses API requires server-generated `rs_*` IDs, causing `400 Invalid Request` errors from Responses-compatible upstreams. Fix: omit reasoning items entirely during translation
+- **CI: duplicate OmniRoute.exe in release workflow** — Removed redundant explicit `release-assets/OmniRoute.exe` entry that caused `softprops/action-gh-release` to fail with 404 on duplicate upload. PR #222 by @benzntech
+
+### ✨ New Features
+
+- **Electron Auto-Update** — Added auto-update functionality to the desktop app using `electron-updater`. Includes IPC handlers for check/download/install, "Check for Updates" in system tray menu, desktop notification when update is ready, and silent startup check (3s delay). PR #221 by @benzntech
+
+### 📦 Dependencies
+
+- Bump `actions/cache` from 4 to 5 (#225)
+- Bump `actions/download-artifact` from 4 to 8 (#226)
+- Bump `docker/login-action` from 3 to 4 (#227)
+- Bump `actions/upload-artifact` from 4 to 7 (#228)
+- Bump `docker/build-push-action` from 6 to 7 (#229)
+- Bump `express-rate-limit` from 8.2.1 to 8.3.0 (#230)
+
+### 📁 Files Changed
+
+| File                                              | Change                                               |
+| ------------------------------------------------- | ---------------------------------------------------- |
+| `open-sse/translator/request/openai-responses.ts` | Remove synthetic reasoning item generation           |
+| `.github/workflows/electron-release.yml`          | Remove duplicate exe entry, bump GH Actions          |
+| `.github/workflows/docker-publish.yml`            | Bump docker/login-action and build-push-action       |
+| `electron/main.js`                                | Auto-updater setup, IPC handlers, tray menu          |
+| `electron/package.json`                           | Added electron-updater dep and GitHub publish config |
+| `electron/preload.js`                             | Exposed update APIs via contextBridge                |
+| `package-lock.json`                               | Updated express-rate-limit                           |
+
+---
+
+## [2.0.4] — 2026-03-06
+
+> ### 🐛 Bug Fixes — Round-Robin Persistence & Docker Compatibility
+
+### 🐛 Bug Fixes
+
+- **#218 — Round-robin sticks to one account** — Added `last_used_at` column to `provider_connections` schema. Round-robin routing relied on `lastUsedAt` to rotate between accounts, but the column was missing from the database — the value was always `null`, causing selection to fall back to the same account. Includes auto-migration for existing databases
+- **#217 — `Cannot find module 'zod'` in Docker/standalone builds** — Added `zod` to `serverExternalPackages` in `next.config.mjs`. Next.js standalone builds weren't tracing `zod` through dynamic imports, causing crashes on Docker startup. Data is **not lost** — the crash prevented the server from reading the existing database
+
+### 📁 Files Changed
+
+| File                      | Change                                                 |
+| ------------------------- | ------------------------------------------------------ |
+| `src/lib/db/core.ts`      | Schema + migration + JSON migration for `last_used_at` |
+| `src/lib/db/providers.ts` | INSERT + UPDATE SQL for `last_used_at`                 |
+| `next.config.mjs`         | `serverExternalPackages: ['better-sqlite3', 'zod']`    |
+
+---
+
+## [2.0.3] — 2026-03-05
+
+> ### 🐛 Bug Fixes & Quota System Hardening
+
+### 🐛 Bug Fixes
+
+- **#215 — Deferred tools 400 error** — Skip `cache_control` on tools with `defer_loading=true` when assigning prompt caching to the last tool. Previously, the API rejected requests with 400 when MCP tools (Playwright, etc.) had deferred loading enabled. Fix applied in both `claudeHelper.ts` and `openai-to-claude.ts` translation layers. PR #216 by @DavyMassoneto
+- **Stale compiled schemas.js** — Deleted stale compiled `schemas.js` (912 lines) that shadowed the TypeScript `.ts` source, causing `cloudSyncActionSchema` warnings in the dashboard. PR #216 by @DavyMassoneto
+- **#202 — False quota exhaustion** — Fixed empty API responses (`{}`) creating quota objects with `utilization ?? 0` = 0% remaining, incorrectly marking accounts as exhausted. Added `hasUtilization()` guard. PR #214 by @DavyMassoneto
+- **Invalid date crash** — `parseDate()` now validates dates before comparison, handling `Invalid Date` from malformed `resetAt` values gracefully. PR #214 by @DavyMassoneto
+- **`total=0` false infinite quota** — `normalizeQuotas` now defaults to 0% remaining when `total` is zero (was incorrectly reporting 100%). PR #214 by @DavyMassoneto
+- **Tailwind v4 build failure** — Tailwind v4 scanned `*.sqlite-shm`/`.sqlite-wal` binary files, triggering "Invalid code point" errors. Added `@source not` exclusions in `globals.css`. PR #214 by @DavyMassoneto
+
+### ✨ Improvements
+
+- **Quota-aware account selection** — All load-balancing strategies (sticky, round-robin, p2c, random, least-used, cost-optimized, fill-first) now prioritize accounts with available quota over exhausted ones. PR #214 by @DavyMassoneto
+- **Concurrent refresh protection** — `tickRunning` flag prevents overlapping background quota refresh ticks; `refreshingSet` deduplicates per-connection refreshes. Thundering herd prevention with `MAX_CONCURRENT_REFRESHES=5`. PR #214 by @DavyMassoneto
+- **`clearModelUnavailability` on success** — Model unavailability is now cleared on every successful request, not only on fallback paths. PR #214 by @DavyMassoneto
+- **Centralized `anthropic-version`** — Hardcoded `anthropic-version` header (3 occurrences) centralized into `CLAUDE_CONFIG.apiVersion`. PR #214 by @DavyMassoneto
+- **Extracted `safePercentage()` utility** — Shared percentage validation function extracted to `src/shared/utils/formatting.ts`, eliminating duplication between backend and frontend. PR #214 by @DavyMassoneto
+- **`isRecord()` type guard** — Replaces inline `typeof` chain in usage API route. PR #214 by @DavyMassoneto
+
+### 📁 Files Changed
+
+| File                                                                                  | Change                                                     |
+| ------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `open-sse/translator/helpers/claudeHelper.ts`                                         | Skip `cache_control` on deferred tools                     |
+| `open-sse/translator/request/openai-to-claude.ts`                                     | Same fix in translator layer                               |
+| `src/shared/validation/schemas.js`                                                    | **DELETED** — stale compiled JS                            |
+| `.gitignore`                                                                          | Exclude Tailwind binary scanning                           |
+| `open-sse/services/usage.ts`                                                          | Legacy endpoint fallback logging                           |
+| `src/domain/quotaCache.ts`                                                            | **NEW** — Core quota cache with hardening                  |
+| `src/shared/utils/formatting.ts`                                                      | **NEW** — `safePercentage()` utility                       |
+| `src/instrumentation.ts`                                                              | Startup log for quota cache                                |
+| `src/sse/handlers/chat.ts`                                                            | `clearModelUnavailability` + `markAccountExhaustedFrom429` |
+| `src/sse/services/auth.ts`                                                            | Quota-aware account selection                              |
+| `src/app/globals.css`                                                                 | Tailwind `@source not` exclusions                          |
+| `src/app/api/usage/[connectionId]/route.ts`                                           | `isRecord()` type guard                                    |
+| `src/app/(dashboard)/dashboard/usage/components/ProviderLimits/ProviderLimitCard.tsx` | Use `remainingPercentage` directly                         |
+| `src/app/(dashboard)/dashboard/usage/components/ProviderLimits/utils.tsx`             | Use shared `safePercentage()`                              |
+
+---
+
 ## [2.0.2] — 2026-03-05
 
 > ### 🐛 Bug Fixes & ✨ Endpoint-Aware Model Management

Dockerfile

@@ -29,6 +29,8 @@ 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
 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/healthcheck.mjs ./healthcheck.mjs

README.md

@@ -20,7 +20,7 @@ _Your universal API proxy — one endpoint, 36+ providers, zero downtime. Now wi
 
 </div>
 
-🌐 **Available in:** 🇺🇸 [English](README.md) | 🇧🇷 [Português (Brasil)](README.pt-BR.md) | 🇪🇸 [Español](README.es.md) | 🇫🇷 [Français](README.fr.md) | 🇮🇹 [Italiano](README.it.md) | 🇷🇺 [Русский](README.ru.md) | 🇨🇳 [中文 (简体)](README.zh-CN.md) | 🇩🇪 [Deutsch](README.de.md) | 🇮🇳 [हिन्दी](README.in.md) | 🇹🇭 [ไทย](README.th.md) | 🇺🇦 [Українська](README.uk-UA.md) | 🇸🇦 [العربية](README.ar.md) | 🇯🇵 [日本語](README.ja.md) | 🇻🇳 [Tiếng Việt](README.vi.md) | 🇧🇬 [Български](README.bg.md) | 🇩🇰 [Dansk](README.da.md) | 🇫🇮 [Suomi](README.fi.md) | 🇮🇱 [עברית](README.he.md) | 🇭🇺 [Magyar](README.hu.md) | 🇮🇩 [Bahasa Indonesia](README.id.md) | 🇰🇷 [한국어](README.ko.md) | 🇲🇾 [Bahasa Melayu](README.ms.md) | 🇳🇱 [Nederlands](README.nl.md) | 🇳🇴 [Norsk](README.no.md) | 🇵🇹 [Português (Portugal)](README.pt.md) | 🇷🇴 [Română](README.ro.md) | 🇵🇱 [Polski](README.pl.md) | 🇸🇰 [Slovenčina](README.sk.md) | 🇸🇪 [Svenska](README.sv.md) | 🇵🇭 [Filipino](README.phi.md)
+🌐 **Available in:** 🇺🇸 [English](README.md) | 🇧🇷 [Português (Brasil)](docs/i18n/pt-BR/README.md) | 🇪🇸 [Español](docs/i18n/es/README.md) | 🇫🇷 [Français](docs/i18n/fr/README.md) | 🇮🇹 [Italiano](docs/i18n/it/README.md) | 🇷🇺 [Русский](docs/i18n/ru/README.md) | 🇨🇳 [中文 (简体)](docs/i18n/zh-CN/README.md) | 🇩🇪 [Deutsch](docs/i18n/de/README.md) | 🇮🇳 [हिन्दी](docs/i18n/in/README.md) | 🇹🇭 [ไทย](docs/i18n/th/README.md) | 🇺🇦 [Українська](docs/i18n/uk-UA/README.md) | 🇸🇦 [العربية](docs/i18n/ar/README.md) | 🇯🇵 [日本語](docs/i18n/ja/README.md) | 🇻🇳 [Tiếng Việt](docs/i18n/vi/README.md) | 🇧🇬 [Български](docs/i18n/bg/README.md) | 🇩🇰 [Dansk](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [Magyar](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonesia](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nederlands](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugal)](docs/i18n/pt/README.md) | 🇷🇴 [Română](docs/i18n/ro/README.md) | 🇵🇱 [Polski](docs/i18n/pl/README.md) | 🇸🇰 [Slovenčina](docs/i18n/sk/README.md) | 🇸🇪 [Svenska](docs/i18n/sv/README.md) | 🇵🇭 [Filipino](docs/i18n/phi/README.md)
 
 ---
 
@@ -167,6 +167,16 @@ _Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway f
 - **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
 - **Original Project**: [9router by decolua](https://github.com/decolua/9router)
 
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.
+
 ---
 
 ## 🔄 How It Works
@@ -247,6 +257,7 @@ Providers like OpenAI/Codex block access from certain geographic regions. Users
 - **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)
 - **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing
 - **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection
+- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously
 
 </details>
 
@@ -258,6 +269,7 @@ Not everyone can pay $20–200/month for AI subscriptions. Students, devs from e
 **How OmniRoute solves it:**
 
 - **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (8 unlimited models), Qwen (3 unlimited models), Kiro (Claude for free), Gemini CLI (180K/month free)
+- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/<model>` prefix
 - **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime
 - **NVIDIA NIM Free Credits** — 1000 free credits integrated
 - **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider
@@ -356,6 +368,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w
 - **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)
 - **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing
 - **File-Based Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation
+- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.
 
 </details>
 
@@ -402,7 +415,7 @@ AI isn't just chat completion. Devs need to generate images, transcribe audio, c
 - **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI
 - **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)
 - **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3
-- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, + existing providers
+- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers
 - **Moderations** — `/v1/moderations` — Content safety checks
 - **Reranking** — `/v1/rerank` — Document relevance reranking
 - **Responses API** — Full `/v1/responses` support for Codex
@@ -888,6 +901,18 @@ When minimized, OmniRoute lives in your system tray with quick actions:
 
 OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 
+### 🚀 New in v2.0.9+ — Playground, CLI Fingerprints & ACP
+
+| Feature                                    | What It Does                                                                                                                                                                                                                            |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🎮 **Model Playground**                    | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing                                                                                                                  |
+| 🔏 **CLI Fingerprint Matching**            | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved**                                                                                           |
+| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint                                                                                                                  |
+| 🤖 **ACP Agents Dashboard**                | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a "Download opencode.json" button that auto-generates a ready-to-use config with all available models. |
+| 🔧 **Custom Model `apiFormat` Routing**    | Custom models with `apiFormat: "responses"` now correctly route to the Responses API translator                                                                                                                                         |
+| 🏢 **Codex Workspace Isolation**           | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID                                                                                                                                             |
+| 🔄 **Electron Auto-Update**                | Desktop app checks for updates + auto-install on restart                                                                                                                                                                                |
+
 ### 🤖 Agent & Protocol Operations (v2.0)
 
 | Feature                               | What It Does                                                                                       |
@@ -936,18 +961,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 
 ### 🛡️ Resilience, Security & Governance
 
-| Feature                             | What It Does                                               |
-| ----------------------------------- | ---------------------------------------------------------- |
-| 🔌 **Circuit Breakers**             | Per-model trip/recover with threshold controls             |
-| 🎯 **Endpoint-Aware Models**        | Custom models declare supported endpoints + API format     |
-| 🛡️ **Anti-Thundering Herd**         | Mutex + semaphore protections on retry/rate events         |
-| 🧠 **Semantic + Signature Cache**   | Cost/latency reduction with two cache layers               |
-| ⚡ **Request Idempotency**          | Duplicate protection window                                |
-| 🔒 **TLS Fingerprint Spoofing**     | Better compatibility with anti-bot filtered providers      |
-| 🌐 **IP Filtering**                 | Allowlist/blocklist control for exposed deployments        |
-| 📊 **Editable Rate Limits**         | Configurable global/provider-level limits with persistence |
-| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls   |
-| 🛡️ **Protected `/models`**          | Optional auth gating and provider hiding for model catalog |
+| Feature                             | What It Does                                                                           |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers**             | Per-model trip/recover with threshold controls                                         |
+| 🎯 **Endpoint-Aware Models**        | Custom models declare supported endpoints + API format                                 |
+| 🛡️ **Anti-Thundering Herd**         | Mutex + semaphore protections on retry/rate events                                     |
+| 🧠 **Semantic + Signature Cache**   | Cost/latency reduction with two cache layers                                           |
+| ⚡ **Request Idempotency**          | Duplicate protection window                                                            |
+| 🔒 **TLS Fingerprint Spoofing**     | Browser-like TLS fingerprint — **reduces bot detection and account flagging**          |
+| 🔏 **CLI Fingerprint Matching**     | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
+| 🌐 **IP Filtering**                 | Allowlist/blocklist control for exposed deployments                                    |
+| 📊 **Editable Rate Limits**         | Configurable global/provider-level limits with persistence                             |
+| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls                               |
+| 🛡️ **Protected `/models`**          | Optional auth gating and provider hiding for model catalog                             |
 
 ### 📊 Observability & Analytics
 
@@ -963,15 +989,17 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 
 ### ☁️ Deployment & Platform
 
-| Feature                      | What It Does                                             |
-| ---------------------------- | -------------------------------------------------------- |
-| 🌐 **Deploy Anywhere**       | Localhost, VPS, Docker, Cloud environments               |
-| 💾 **Cloud Sync**            | Configuration sync via cloud worker                      |
-| 🔄 **Backup/Restore**        | Export/import and disaster recovery flows                |
-| 🧙 **Onboarding Wizard**     | First-run guided setup                                   |
-| 🔧 **CLI Tools Dashboard**   | One-click setup for popular coding tools                 |
-| 🌐 **i18n (30 languages)**   | Full dashboard + docs language support with RTL coverage |
-| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location                 |
+| Feature                       | What It Does                                             |
+| ----------------------------- | -------------------------------------------------------- |
+| 🌐 **Deploy Anywhere**        | Localhost, VPS, Docker, Cloud environments               |
+| 💾 **Cloud Sync**             | Configuration sync via cloud worker                      |
+| 🔄 **Backup/Restore**         | Export/import and disaster recovery flows                |
+| 🧙 **Onboarding Wizard**      | First-run guided setup                                   |
+| 🔧 **CLI Tools Dashboard**    | One-click setup for popular coding tools                 |
+| 🎮 **Model Playground**       | Test any provider/model/endpoint from the dashboard      |
+| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |
+| 🌐 **i18n (30 languages)**    | Full dashboard + docs language support with RTL coverage |
+| 📂 **Custom Data Directory**  | `DATA_DIR` override for storage location                 |
 
 ### Feature Deep Dive
 
@@ -1677,6 +1705,8 @@ gh release create v2.0.0 --title "v2.0.0" --generate-notes
  </picture>
 </a>
 
+> 📈 **[View live star history on star-history.com](https://star-history.com/#diegosouzapw/OmniRoute&Date)** — The embedded chart may be cached. Click the link for real-time data.
+
 ---
 
 ## 🙏 Acknowledgments

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

@@ -260,6 +260,16 @@ 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                     |

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/FEATURES.md

@@ -16,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 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
 
 ![Combos Dashboard](screenshots/02-combos.png)
 
@@ -46,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 (model aliases, background task degradation), resilience (rate limit persistence), 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
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
 
 ![Settings Dashboard](screenshots/06-settings.png)
 
@@ -56,12 +75,29 @@ 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, Antigravity, and **GitHub Copilot** (config generator for `chatLanguageModels.json`).
+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
+
+---
+
+## 🖼️ 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.
@@ -72,15 +108,27 @@ 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. 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, and one-click install.
+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:
 
@@ -88,6 +136,7 @@ Key features:
 - 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)
 
 📖 See [`electron/README.md`](../electron/README.md) for full documentation.

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                 |
+| `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/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/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/ar/A2A-SERVER.md

@@ -0,0 +1,200 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/A2A-SERVER.md) · 🇪🇸 [es](../es/A2A-SERVER.md) · 🇫🇷 [fr](../fr/A2A-SERVER.md) · 🇩🇪 [de](../de/A2A-SERVER.md) · 🇮🇹 [it](../it/A2A-SERVER.md) · 🇷🇺 [ru](../ru/A2A-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/A2A-SERVER.md) · 🇯🇵 [ja](../ja/A2A-SERVER.md) · 🇰🇷 [ko](../ko/A2A-SERVER.md) · 🇸🇦 [ar](../ar/A2A-SERVER.md) · 🇮🇳 [in](../in/A2A-SERVER.md) · 🇹🇭 [th](../th/A2A-SERVER.md) · 🇻🇳 [vi](../vi/A2A-SERVER.md) · 🇮🇩 [id](../id/A2A-SERVER.md) · 🇲🇾 [ms](../ms/A2A-SERVER.md) · 🇳🇱 [nl](../nl/A2A-SERVER.md) · 🇵🇱 [pl](../pl/A2A-SERVER.md) · 🇸🇪 [sv](../sv/A2A-SERVER.md) · 🇳🇴 [no](../no/A2A-SERVER.md) · 🇩🇰 [da](../da/A2A-SERVER.md) · 🇫🇮 [fi](../fi/A2A-SERVER.md) · 🇵🇹 [pt](../pt/A2A-SERVER.md) · 🇷🇴 [ro](../ro/A2A-SERVER.md) · 🇭🇺 [hu](../hu/A2A-SERVER.md) · 🇧🇬 [bg](../bg/A2A-SERVER.md) · 🇸🇰 [sk](../sk/A2A-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/A2A-SERVER.md) · 🇮🇱 [he](../he/A2A-SERVER.md) · 🇵🇭 [phi](../phi/A2A-SERVER.md)
+
+---
+
+# 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/i18n/ar/API_REFERENCE.md

@@ -1,12 +1,16 @@
-# مرجع واجهة برمجة التطبيقات
-
-🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md)
-
-مرجع كامل لجميع نقاط نهاية OmniRoute API.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/API_REFERENCE.md) · 🇪🇸 [es](../es/API_REFERENCE.md) · 🇫🇷 [fr](../fr/API_REFERENCE.md) · 🇩🇪 [de](../de/API_REFERENCE.md) · 🇮🇹 [it](../it/API_REFERENCE.md) · 🇷🇺 [ru](../ru/API_REFERENCE.md) · 🇨🇳 [zh-CN](../zh-CN/API_REFERENCE.md) · 🇯🇵 [ja](../ja/API_REFERENCE.md) · 🇰🇷 [ko](../ko/API_REFERENCE.md) · 🇸🇦 [ar](../ar/API_REFERENCE.md) · 🇮🇳 [in](../in/API_REFERENCE.md) · 🇹🇭 [th](../th/API_REFERENCE.md) · 🇻🇳 [vi](../vi/API_REFERENCE.md) · 🇮🇩 [id](../id/API_REFERENCE.md) · 🇲🇾 [ms](../ms/API_REFERENCE.md) · 🇳🇱 [nl](../nl/API_REFERENCE.md) · 🇵🇱 [pl](../pl/API_REFERENCE.md) · 🇸🇪 [sv](../sv/API_REFERENCE.md) · 🇳🇴 [no](../no/API_REFERENCE.md) · 🇩🇰 [da](../da/API_REFERENCE.md) · 🇫🇮 [fi](../fi/API_REFERENCE.md) · 🇵🇹 [pt](../pt/API_REFERENCE.md) · 🇷🇴 [ro](../ro/API_REFERENCE.md) · 🇭🇺 [hu](../hu/API_REFERENCE.md) · 🇧🇬 [bg](../bg/API_REFERENCE.md) · 🇸🇰 [sk](../sk/API_REFERENCE.md) · 🇺🇦 [uk-UA](../uk-UA/API_REFERENCE.md) · 🇮🇱 [he](../he/API_REFERENCE.md) · 🇵🇭 [phi](../phi/API_REFERENCE.md)
 
 ---
 
-## جدول المحتويات
+# 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)
+
+Complete reference for all OmniRoute API endpoints.
+
+---
+
+## Table of Contents
 
 - [Chat Completions](#chat-completions)
 - [Embeddings](#embeddings)
@@ -20,7 +24,7 @@
 
 ---
 
-## إكمالات الدردشة
+## Chat Completions
 
 ```bash
 POST /v1/chat/completions
@@ -36,21 +40,21 @@ Content-Type: application/json
 }
 ```
 
-### رؤوس مخصصة
+### Custom Headers
 
-| رأس                      | الاتجاه | الوصف                                       |
-| ------------------------ | ------- | ------------------------------------------- |
-| `X-OmniRoute-No-Cache`   | طلب     | اضبط على `true` لتجاوز ذاكرة التخزين المؤقت |
-| `X-OmniRoute-Progress`   | طلب     | اضبط على `true` لأحداث التقدم               |
-| `Idempotency-Key`        | طلب     | مفتاح Dedup (نافذة 5 ثواني)                 |
-| `X-Request-Id`           | طلب     | مفتاح إلغاء الحذف البديل                    |
-| `X-OmniRoute-Cache`      | الرد    | `HIT` أو `MISS` (غير متدفق)                 |
-| `X-OmniRoute-Idempotent` | الرد    | `true` إذا تم إلغاء التكرار                 |
-| `X-OmniRoute-Progress`   | الرد    | `enabled` إذا تم تتبع التقدم على            |
+| 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 |
 
 ---
 
-## التضمينات
+## Embeddings
 
 ```bash
 POST /v1/embeddings
@@ -63,7 +67,7 @@ Content-Type: application/json
 }
 ```
 
-مقدمو الخدمة المتاحون: Nebius، وOpenAI، وMistral، وTogether AI، وFireworks، وNVIDIA.
+Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
 
 ```bash
 # List all embedding models
@@ -72,7 +76,7 @@ GET /v1/embeddings
 
 ---
 
-## توليد الصور
+## Image Generation
 
 ```bash
 POST /v1/images/generations
@@ -86,7 +90,7 @@ Content-Type: application/json
 }
 ```
 
-الموفرون المتاحون: OpenAI (DALL-E)، xAI (Grok Image)، Together AI (FLUX)، Fireworks AI.
+Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
 
 ```bash
 # List all image models
@@ -95,7 +99,7 @@ GET /v1/images/generations
 
 ---
 
-## قائمة النماذج
+## List Models
 
 ```bash
 GET /v1/models
@@ -106,22 +110,22 @@ Authorization: Bearer your-api-key
 
 ---
 
-## نقاط نهاية التوافق
+## Compatibility Endpoints
 
-| الطريقة  | المسار                      | تنسيق                 |
-| -------- | --------------------------- | --------------------- |
-| مشاركة   | `/v1/chat/completions`      | أوبن آي               |
-| مشاركة   | `/v1/messages`              | انثروبي               |
-| مشاركة   | `/v1/responses`             | ردود OpenAI           |
-| مشاركة   | `/v1/embeddings`            | أوبن آي               |
-| مشاركة   | `/v1/images/generations`    | أوبن آي               |
-| احصل على | `/v1/models`                | أوبن آي               |
-| مشاركة   | `/v1/messages/count_tokens` | انثروبي               |
-| احصل على | `/v1beta/models`            | الجوزاء               |
-| مشاركة   | `/v1beta/models/{...path}`  | الجوزاء توليد المحتوى |
-| مشاركة   | `/v1/api/chat`              | أولاما                |
+| Method | Path                        | Format                 |
+| ------ | --------------------------- | ---------------------- |
+| POST   | `/v1/chat/completions`      | OpenAI                 |
+| POST   | `/v1/messages`              | Anthropic              |
+| POST   | `/v1/responses`             | OpenAI Responses       |
+| POST   | `/v1/embeddings`            | OpenAI                 |
+| POST   | `/v1/images/generations`    | OpenAI                 |
+| GET    | `/v1/models`                | OpenAI                 |
+| POST   | `/v1/messages/count_tokens` | Anthropic              |
+| GET    | `/v1beta/models`            | Gemini                 |
+| POST   | `/v1beta/models/{...path}`  | Gemini generateContent |
+| POST   | `/v1/api/chat`              | Ollama                 |
 
-### مسارات موفر مخصصة
+### Dedicated Provider Routes
 
 ```bash
 POST /v1/providers/{provider}/chat/completions
@@ -129,11 +133,11 @@ POST /v1/providers/{provider}/embeddings
 POST /v1/providers/{provider}/images/generations
 ```
 
-تتم إضافة بادئة الموفر تلقائيًا في حالة فقدانها. تُرجع النماذج غير المتطابقة `400`.
+The provider prefix is auto-added if missing. Mismatched models return `400`.
 
 ---
 
-## ذاكرة التخزين المؤقت الدلالية
+## Semantic Cache
 
 ```bash
 # Get cache stats
@@ -143,7 +147,7 @@ GET /api/cache
 DELETE /api/cache
 ```
 
-مثال الاستجابة:
+Response example:
 
 ```json
 {
@@ -162,154 +166,164 @@ DELETE /api/cache
 
 ---
 
-## لوحة القيادة والإدارة
+## Dashboard & Management
 
-### المصادقة
+### Authentication
 
-| نقطة النهاية                  | الطريقة        | الوصف                    |
-| ----------------------------- | -------------- | ------------------------ |
-| `/api/auth/login`             | مشاركة         | تسجيل الدخول             |
-| `/api/auth/logout`            | مشاركة         | تسجيل الخروج             |
-| `/api/settings/require-login` | الحصول على/وضع | تبديل تسجيل الدخول مطلوب |
+| Endpoint                      | Method  | Description           |
+| ----------------------------- | ------- | --------------------- |
+| `/api/auth/login`             | POST    | Login                 |
+| `/api/auth/logout`            | POST    | Logout                |
+| `/api/settings/require-login` | GET/PUT | Toggle login required |
 
-### إدارة مقدمي الخدمة
+### Provider Management
 
-| نقطة النهاية                 | الطريقة            | الوصف                       |
-| ---------------------------- | ------------------ | --------------------------- |
-| `/api/providers`             | الحصول على/النشر   | قائمة / إنشاء مقدمي الخدمات |
-| `/api/providers/[id]`        | الحصول على/وضع/حذف | إدارة مزود                  |
-| `/api/providers/[id]/test`   | مشاركة             | اختبار اتصال الموفر         |
-| `/api/providers/[id]/models` | احصل على           | قائمة نماذج المزود          |
-| `/api/providers/validate`    | مشاركة             | التحقق من صحة تكوين الموفر  |
-| `/api/provider-nodes*`       | متنوع              | إدارة عقدة الموفر           |
-| `/api/provider-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/DELETE | Custom models            |
 
-### تدفقات OAuth
+### OAuth Flows
 
-| نقطة النهاية                     | الطريقة | الوصف                    |
-| -------------------------------- | ------- | ------------------------ |
-| `/api/oauth/[provider]/[action]` | متنوع   | OAuth الخاص بموفر الخدمة |
+| Endpoint                         | Method  | Description             |
+| -------------------------------- | ------- | ----------------------- |
+| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth |
 
-### التوجيه والتكوين
+### Routing & Config
 
-| نقطة النهاية          | الطريقة          | الوصف                             |
-| --------------------- | ---------------- | --------------------------------- |
-| `/api/models/alias`   | الحصول على/النشر | الأسماء المستعارة للنموذج         |
-| `/api/models/catalog` | احصل على         | جميع الموديلات حسب المزود + النوع |
-| `/api/combos*`        | متنوع            | إدارة التحرير والسرد              |
-| `/api/keys*`          | متنوع            | إدارة مفاتيح API                  |
-| `/api/pricing`        | احصل على         | التسعير النموذجي                  |
+| Endpoint              | Method   | Description                   |
+| --------------------- | -------- | ----------------------------- |
+| `/api/models/alias`   | GET/POST | Model aliases                 |
+| `/api/models/catalog` | GET      | All models by provider + type |
+| `/api/combos*`        | Various  | Combo management              |
+| `/api/keys*`          | Various  | API key management            |
+| `/api/pricing`        | GET      | Model pricing                 |
 
-### الاستخدام والتحليلات
+### Usage & Analytics
 
-| نقطة النهاية                | الطريقة  | الوصف                 |
-| --------------------------- | -------- | --------------------- |
-| `/api/usage/history`        | احصل على | تاريخ الاستخدام       |
-| `/api/usage/logs`           | احصل على | سجلات الاستخدام       |
-| `/api/usage/request-logs`   | احصل على | سجلات على مستوى الطلب |
-| `/api/usage/[connectionId]` | احصل على | الاستخدام لكل اتصال   |
+| Endpoint                    | Method | Description          |
+| --------------------------- | ------ | -------------------- |
+| `/api/usage/history`        | GET    | Usage history        |
+| `/api/usage/logs`           | GET    | Usage logs           |
+| `/api/usage/request-logs`   | GET    | Request-level logs   |
+| `/api/usage/[connectionId]` | GET    | Per-connection usage |
 
-### الإعدادات
+### Settings
 
-| نقطة النهاية                    | الطريقة        | الوصف                                           |
-| ------------------------------- | -------------- | ----------------------------------------------- |
-| `/api/settings`                 | الحصول على/وضع | الإعدادات العامة                                |
-| `/api/settings/proxy`           | الحصول على/وضع | تكوين وكيل الشبكة                               |
-| `/api/settings/proxy/test`      | مشاركة         | اختبار اتصال الوكيل                             |
-| `/api/settings/ip-filter`       | الحصول على/وضع | القائمة المسموح بها/القائمة المحظورة لعناوين IP |
-| `/api/settings/thinking-budget` | الحصول على/وضع | الميزانية الرمزية المنطقية                      |
-| `/api/settings/system-prompt`   | الحصول على/وضع | موجه النظام العالمي                             |
+| 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   |
 
-### المراقبة
+### Monitoring
 
-| نقطة النهاية             | الطريقة        | الوصف                               |
-| ------------------------ | -------------- | ----------------------------------- |
-| `/api/sessions`          | احصل على       | تتبع الجلسة النشطة                  |
-| `/api/rate-limits`       | احصل على       | حدود المعدل لكل حساب                |
-| `/api/monitoring/health` | احصل على       | فحص الصحة                           |
-| `/api/cache`             | الحصول على/حذف | إحصائيات ذاكرة التخزين المؤقت / مسح |
+| 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     |
 
-### النسخ الاحتياطي والتصدير/الاستيراد
+### Backup & Export/Import
 
-| نقطة النهاية                | الطريقة  | الوصف                                              |
-| --------------------------- | -------- | -------------------------------------------------- |
-| `/api/db-backups`           | احصل على | قائمة النسخ الاحتياطية المتاحة                     |
-| `/api/db-backups`           | ضع       | إنشاء نسخة احتياطية يدوية                          |
-| `/api/db-backups`           | مشاركة   | استعادة من نسخة احتياطية محددة                     |
-| `/api/db-backups/export`    | احصل على | تنزيل قاعدة البيانات كملف .sqlite                  |
-| `/api/db-backups/import`    | مشاركة   | قم بتحميل ملف .sqlite لاستبدال قاعدة البيانات      |
-| `/api/db-backups/exportAll` | احصل على | قم بتنزيل النسخة الاحتياطية الكاملة كأرشيف .tar.gz |
+| Endpoint                    | Method | Description                             |
+| --------------------------- | ------ | --------------------------------------- |
+| `/api/db-backups`           | GET    | List available backups                  |
+| `/api/db-backups`           | PUT    | Create a manual backup                  |
+| `/api/db-backups`           | POST   | Restore from a specific backup          |
+| `/api/db-backups/export`    | GET    | Download database as .sqlite file       |
+| `/api/db-backups/import`    | POST   | Upload .sqlite file to replace database |
+| `/api/db-backups/exportAll` | GET    | Download full backup as .tar.gz archive |
 
-### المزامنة السحابية
+### Cloud Sync
 
-| نقطة النهاية           | الطريقة | الوصف                    |
-| ---------------------- | ------- | ------------------------ |
-| `/api/sync/cloud`      | متنوع   | عمليات المزامنة السحابية |
-| `/api/sync/initialize` | مشاركة  | تهيئة المزامنة           |
-| `/api/cloud/*`         | متنوع   | إدارة السحابة            |
+| Endpoint               | Method  | Description           |
+| ---------------------- | ------- | --------------------- |
+| `/api/sync/cloud`      | Various | Cloud sync operations |
+| `/api/sync/initialize` | POST    | Initialize sync       |
+| `/api/cloud/*`         | Various | Cloud management      |
 
-### أدوات سطر الأوامر
+### CLI Tools
 
-| نقطة النهاية                       | الطريقة  | الوصف               |
-| ---------------------------------- | -------- | ------------------- |
-| `/api/cli-tools/claude-settings`   | احصل على | حالة كلود CLI       |
-| `/api/cli-tools/codex-settings`    | احصل على | حالة Codex CLI      |
-| `/api/cli-tools/droid-settings`    | احصل على | حالة Droid CLI      |
-| `/api/cli-tools/openclaw-settings` | احصل على | حالة OpenClaw CLI   |
-| `/api/cli-tools/runtime/[toolId]`  | احصل على | وقت تشغيل CLI العام |
+| Endpoint                           | Method | Description         |
+| ---------------------------------- | ------ | ------------------- |
+| `/api/cli-tools/claude-settings`   | GET    | Claude CLI status   |
+| `/api/cli-tools/codex-settings`    | GET    | Codex CLI status    |
+| `/api/cli-tools/droid-settings`    | GET    | Droid CLI status    |
+| `/api/cli-tools/openclaw-settings` | GET    | OpenClaw CLI status |
+| `/api/cli-tools/runtime/[toolId]`  | GET    | Generic CLI runtime |
 
-تتضمن استجابات واجهة سطر الأوامر: `installed`، `runnable`، `command`، `commandPath`، `runtimeMode`، `reason`.
+CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
 
-### المرونة وحدود الأسعار
+### ACP Agents
 
-| نقطة النهاية            | الطريقة        | الوصف                                |
-| ----------------------- | -------------- | ------------------------------------ |
-| `/api/resilience`       | الحصول على/وضع | الحصول على/تحديث ملفات تعريف المرونة |
-| `/api/resilience/reset` | مشاركة         | إعادة ضبط قواطع الدائرة              |
-| `/api/rate-limits`      | احصل على       | حالة حد المعدل لكل حساب              |
-| `/api/rate-limit`       | احصل على       | تكوين حد المعدل العالمي              |
+| 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).
 
-| نقطة النهاية | الطريقة          | الوصف                                 |
-| ------------ | ---------------- | ------------------------------------- |
-| `/api/evals` | الحصول على/النشر | قائمة مجموعات التقييم / تشغيل التقييم |
+### 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 |
 
-| نقطة النهاية    | الطريقة            | الوصف                |
-| --------------- | ------------------ | -------------------- |
-| `/api/policies` | الحصول على/نشر/حذف | إدارة سياسات التوجيه |
+### Evals
 
-###الامتثال
+| Endpoint     | Method   | Description                       |
+| ------------ | -------- | --------------------------------- |
+| `/api/evals` | GET/POST | List eval suites / run evaluation |
 
-| نقطة النهاية                | الطريقة  | الوصف                        |
-| --------------------------- | -------- | ---------------------------- |
-| `/api/compliance/audit-log` | احصل على | سجل تدقيق الامتثال (آخر رقم) |
+### Policies
 
-### v1beta (متوافق مع الجوزاء)
+| Endpoint        | Method          | Description             |
+| --------------- | --------------- | ----------------------- |
+| `/api/policies` | GET/POST/DELETE | Manage routing policies |
 
-| نقطة النهاية               | الطريقة  | الوصف                                  |
-| -------------------------- | -------- | -------------------------------------- |
-| `/v1beta/models`           | احصل على | قائمة النماذج بصيغة الجوزاء            |
-| `/v1beta/models/{...path}` | مشاركة   | الجوزاء `generateContent` نقطة النهاية |
+### Compliance
 
-تعكس نقاط النهاية هذه تنسيق Gemini API للعملاء الذين يتوقعون توافق Gemini SDK الأصلي.
+| Endpoint                    | Method | Description                   |
+| --------------------------- | ------ | ----------------------------- |
+| `/api/compliance/audit-log` | GET    | Compliance audit log (last N) |
 
-### واجهات برمجة التطبيقات الداخلية / النظام
+### v1beta (Gemini-Compatible)
 
-| نقطة النهاية    | الطريقة  | الوصف                                              |
-| --------------- | -------- | -------------------------------------------------- |
-| `/api/init`     | احصل على | فحص تهيئة التطبيق (يستخدم عند التشغيل لأول مرة)    |
-| `/api/tags`     | احصل على | علامات النماذج المتوافقة مع Ollama (لعملاء Ollama) |
-| `/api/restart`  | مشاركة   | تشغيل إعادة تشغيل الخادم الرشيقة                   |
-| `/api/shutdown` | مشاركة   | تشغيل إيقاف تشغيل الخادم بشكل رشيق                 |
+| Endpoint                   | Method | Description                       |
+| -------------------------- | ------ | --------------------------------- |
+| `/v1beta/models`           | GET    | List models in Gemini format      |
+| `/v1beta/models/{...path}` | POST   | Gemini `generateContent` endpoint |
 
-> **ملاحظة:** يتم استخدام نقاط النهاية هذه داخليًا بواسطة النظام أو للتوافق مع عميل Ollama. لا يتم استدعاؤها عادة من قبل المستخدمين النهائيين.
+These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility.
+
+### Internal / System APIs
+
+| Endpoint        | Method | Description                                          |
+| --------------- | ------ | ---------------------------------------------------- |
+| `/api/init`     | GET    | Application initialization check (used on first run) |
+| `/api/tags`     | GET    | Ollama-compatible model tags (for Ollama clients)    |
+| `/api/restart`  | POST   | Trigger graceful server restart                      |
+| `/api/shutdown` | POST   | Trigger graceful server shutdown                     |
+
+> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users.
 
 ---
 
-## النسخ الصوتي
+## Audio Transcription
 
 ```bash
 POST /v1/audio/transcriptions
@@ -317,9 +331,9 @@ Authorization: Bearer your-api-key
 Content-Type: multipart/form-data
 ```
 
-قم بنسخ الملفات الصوتية باستخدام Deepgram أو AssemblyAI.
+Transcribe audio files using Deepgram or AssemblyAI.
 
-**الطلب:**
+**Request:**
 
 ```bash
 curl -X POST http://localhost:20128/v1/audio/transcriptions \
@@ -328,7 +342,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
   -F "model=deepgram/nova-3"
 ```
 
-**الرد:**
+**Response:**
 
 ```json
 {
@@ -339,15 +353,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
 }
 ```
 
-**الموفرون المدعمون:** `deepgram/nova-3`، `assemblyai/best`.
+**Supported providers:** `deepgram/nova-3`, `assemblyai/best`.
 
-**التنسيقات المدعومة:** `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`.
+**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
 
 ---
 
-## التوافق مع أولاما
+## Ollama Compatibility
 
-بالنسبة للعملاء الذين يستخدمون تنسيق واجهة برمجة تطبيقات Olma:
+For clients that use Ollama's API format:
 
 ```bash
 # Chat endpoint (Ollama format)
@@ -357,18 +371,18 @@ POST /v1/api/chat
 GET /api/tags
 ```
 
-تتم ترجمة الطلبات تلقائيًا بين تنسيقات Ollama والتنسيقات الداخلية.
+Requests are automatically translated between Ollama and internal formats.
 
 ---
 
-## القياس عن بعد
+## Telemetry
 
 ```bash
 # Get latency telemetry summary (p50/p95/p99 per provider)
 GET /api/telemetry/summary
 ```
 
-**الرد:**
+**Response:**
 
 ```json
 {
@@ -381,7 +395,7 @@ GET /api/telemetry/summary
 
 ---
 
-## الميزانية
+## Budget
 
 ```bash
 # Get budget status for all API keys
@@ -400,7 +414,7 @@ Content-Type: application/json
 
 ---
 
-## توفر النموذج
+## Model Availability
 
 ```bash
 # Get real-time model availability across all providers
@@ -417,25 +431,25 @@ Content-Type: application/json
 
 ---
 
-## معالجة الطلب
+## Request Processing
 
-1. يرسل العميل طلبًا إلى `/v1/*`
-2. يستدعي معالج المسار `handleChat`، `handleEmbedding`، `handleAudioTranscription`، أو `handleImageGeneration`
-3. تم حل النموذج (المزود/النموذج المباشر أو الاسم المستعار/السرد)
-4. تم تحديد بيانات الاعتماد من قاعدة البيانات المحلية مع تصفية توفر الحساب
-5. للدردشة: `handleChatCore` — اكتشاف التنسيق، والترجمة، والتحقق من ذاكرة التخزين المؤقت، والتحقق من عدم الكفاءة
-6. يقوم منفذ الموفر بإرسال طلب المنبع
-7. تتم ترجمة الاستجابة مرة أخرى إلى تنسيق العميل (الدردشة) أو إعادتها كما هي (التضمينات/الصور/الصوت)
-8. تم تسجيل الاستخدام/التسجيل
-9. يتم تطبيق الإجراء الاحتياطي على الأخطاء وفقًا لقواعد التحرير والسرد
+1. Client sends request to `/v1/*`
+2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration`
+3. Model is resolved (direct provider/model or alias/combo)
+4. Credentials selected from local DB with account availability filtering
+5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check
+6. Provider executor sends upstream request
+7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio)
+8. Usage/logging recorded
+9. Fallback applies on errors according to combo rules
 
-مرجع البنية الكاملة: [link](ARCHITECTURE.md)
+Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md)
 
 ---
 
-## المصادقة
+## Authentication
 
-- تستخدم مسارات لوحة المعلومات (`/dashboard/*`) ملف تعريف الارتباط `auth_token`
-- يستخدم تسجيل الدخول تجزئة كلمة المرور المحفوظة؛ الرجوع إلى `INITIAL_PASSWORD`
-- `requireLogin` قابل للتبديل عبر `/api/settings/require-login`
-- تتطلب مسارات `/v1/*` بشكل اختياري مفتاح Bearer API عندما `REQUIRE_API_KEY=true`
+- Dashboard routes (`/dashboard/*`) use `auth_token` cookie
+- Login uses saved password hash; fallback to `INITIAL_PASSWORD`
+- `requireLogin` toggleable via `/api/settings/require-login`
+- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true`

docs/i18n/ar/ARCHITECTURE.md

@@ -1,71 +1,75 @@
-# العمارة OmniRoute
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/ARCHITECTURE.md) · 🇪🇸 [es](../es/ARCHITECTURE.md) · 🇫🇷 [fr](../fr/ARCHITECTURE.md) · 🇩🇪 [de](../de/ARCHITECTURE.md) · 🇮🇹 [it](../it/ARCHITECTURE.md) · 🇷🇺 [ru](../ru/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../zh-CN/ARCHITECTURE.md) · 🇯🇵 [ja](../ja/ARCHITECTURE.md) · 🇰🇷 [ko](../ko/ARCHITECTURE.md) · 🇸🇦 [ar](../ar/ARCHITECTURE.md) · 🇮🇳 [in](../in/ARCHITECTURE.md) · 🇹🇭 [th](../th/ARCHITECTURE.md) · 🇻🇳 [vi](../vi/ARCHITECTURE.md) · 🇮🇩 [id](../id/ARCHITECTURE.md) · 🇲🇾 [ms](../ms/ARCHITECTURE.md) · 🇳🇱 [nl](../nl/ARCHITECTURE.md) · 🇵🇱 [pl](../pl/ARCHITECTURE.md) · 🇸🇪 [sv](../sv/ARCHITECTURE.md) · 🇳🇴 [no](../no/ARCHITECTURE.md) · 🇩🇰 [da](../da/ARCHITECTURE.md) · 🇫🇮 [fi](../fi/ARCHITECTURE.md) · 🇵🇹 [pt](../pt/ARCHITECTURE.md) · 🇷🇴 [ro](../ro/ARCHITECTURE.md) · 🇭🇺 [hu](../hu/ARCHITECTURE.md) · 🇧🇬 [bg](../bg/ARCHITECTURE.md) · 🇸🇰 [sk](../sk/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../uk-UA/ARCHITECTURE.md) · 🇮🇱 [he](../he/ARCHITECTURE.md) · 🇵🇭 [phi](../phi/ARCHITECTURE.md)
 
-🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md)
+---
 
-_آخر تحديث: 2026-02-18_
+# OmniRoute Architecture
 
-## ملخص تنفيذي
+🌐 **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)
 
-OmniRoute عبارة عن بوابة توجيه محلية تعمل بالذكاء الاصطناعي ولوحة معلومات مبنية على Next.js.
-فهو يوفر نقطة نهاية واحدة متوافقة مع OpenAI (`/v1/*`) ويوجه حركة المرور عبر العديد من موفري الخدمات الأولية مع الترجمة والاحتياط وتحديث الرمز المميز وتتبع الاستخدام.
+_Last updated: 2026-03-04_
 
-القدرات الأساسية:
+## Executive Summary
 
-- سطح API متوافق مع OpenAI لـ CLI/الأدوات (28 مزودًا)
-- ترجمة الطلب/الاستجابة عبر تنسيقات الموفر
-- نموذج احتياطي التحرير والسرد (تسلسل متعدد النماذج)
-- احتياطي على مستوى الحساب (حسابات متعددة لكل مزود)
-- إدارة اتصال موفر OAuth + API-key
-- إنشاء التضمين عبر `/v1/embeddings` (6 موفري خدمات، 9 نماذج)
-- إنشاء الصور عبر `/v1/images/generations` (4 مقدمي خدمات، 9 نماذج)
-- فكر في تحليل العلامات (`<think>...</think>`) لنماذج الاستدلال
-- تعقيم الاستجابة للتوافق الصارم مع OpenAI SDK
-- تطبيع الدور (المطور → النظام، النظام → المستخدم) للتوافق بين الموفرين
-- تحويل الإخراج المنظم (json_schema → Gemini ResponseSchema)
-- الثبات المحلي لمقدمي الخدمات والمفاتيح والأسماء المستعارة والمجموعات والإعدادات والتسعير
-- تتبع الاستخدام/التكلفة وتسجيل الطلب
-- مزامنة سحابية اختيارية لمزامنة الأجهزة/الحالة المتعددة
-- القائمة المسموح بها/القائمة المحظورة لـ IP للتحكم في الوصول إلى واجهة برمجة التطبيقات
-- التفكير في إدارة الميزانية (العبور / التلقائي / المخصص / التكيفي)
-- الحقن الفوري للنظام العالمي
-- تتبع الجلسة وأخذ البصمات
-- تحديد المعدل المحسن لكل حساب مع الملفات الشخصية الخاصة بالمزود
-- نمط قاطع الدائرة لمرونة المزود
-- حماية القطيع ضد الرعد مع قفل Mutex
-- ذاكرة التخزين المؤقت لإلغاء البيانات المكررة للطلب المستندة إلى التوقيع
-- طبقة المجال: توفر النموذج، وقواعد التكلفة، والسياسة الاحتياطية، وسياسة الإغلاق
-- استمرارية حالة المجال (ذاكرة التخزين المؤقت للكتابة في SQLite للاحتياطيات والميزانيات وعمليات الإغلاق وقواطع الدائرة)
-- محرك السياسة لتقييم الطلب المركزي (التأمين → الميزانية → الاحتياطي)
-- طلب القياس عن بعد مع تجميع الكمون p50/p95/p99
-- معرف الارتباط (X-Request-Id) للتتبع الشامل
-- تسجيل تدقيق الامتثال مع إلغاء الاشتراك لكل مفتاح API
-- إطار تقييمي لضمان جودة LLM
-- لوحة تحكم واجهة المستخدم المرنة مع حالة قاطع الدائرة في الوقت الفعلي
-- موفرو OAuth المعياريون (12 وحدة فردية ضمن `src/lib/oauth/providers/`)
+OmniRoute is a local AI routing gateway and dashboard built on Next.js.
+It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
 
-نموذج وقت التشغيل الأساسي:
+Core capabilities:
 
-- تقوم مسارات تطبيق Next.js ضمن `src/app/api/*` بتنفيذ كل من واجهات برمجة تطبيقات لوحة المعلومات وواجهات برمجة تطبيقات التوافق
-- نواة توجيه/SSE مشتركة في `src/sse/*` + `open-sse/*` تتعامل مع تنفيذ الموفر والترجمة والتدفق والرجوع والاستخدام
+- OpenAI-compatible API surface for CLI/tools (28 providers)
+- Request/response translation across provider formats
+- Model combo fallback (multi-model sequence)
+- Account-level fallback (multi-account per provider)
+- OAuth + API-key provider connection management
+- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
+- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Think tag parsing (`<think>...</think>`) for reasoning models
+- Response sanitization for strict OpenAI SDK compatibility
+- Role normalization (developer→system, system→user) for cross-provider compatibility
+- Structured output conversion (json_schema → Gemini responseSchema)
+- Local persistence for providers, keys, aliases, combos, settings, pricing
+- Usage/cost tracking and request logging
+- Optional cloud sync for multi-device/state sync
+- IP allowlist/blocklist for API access control
+- Thinking budget management (passthrough/auto/custom/adaptive)
+- Global system prompt injection
+- Session tracking and fingerprinting
+- Per-account enhanced rate limiting with provider-specific profiles
+- Circuit breaker pattern for provider resilience
+- Anti-thundering herd protection with mutex locking
+- Signature-based request deduplication cache
+- Domain layer: model availability, cost rules, fallback policy, lockout policy
+- 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
+- Correlation ID (X-Request-Id) for end-to-end tracing
+- Compliance audit logging with opt-out per API key
+- Eval framework for LLM quality assurance
+- Resilience UI dashboard with real-time circuit breaker status
+- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`)
 
-## النطاق والحدود
+Primary runtime model:
 
-### في النطاق
+- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
+- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
 
-- وقت تشغيل البوابة المحلية
-- واجهات برمجة التطبيقات لإدارة لوحة المعلومات
-- مصادقة الموفر وتحديث الرمز المميز
-- طلب الترجمة وتدفق SSE
-- الحالة المحلية + استمرارية الاستخدام
-- تنسيق مزامنة سحابية اختيارية
+## Scope and Boundaries
 
-### خارج النطاق
+### In Scope
 
-- تنفيذ الخدمة السحابية خلف `NEXT_PUBLIC_CLOUD_URL`
-- مزود مستوى جيش تحرير السودان/مستوى التحكم خارج العملية المحلية
-- ثنائيات CLI الخارجية نفسها (Claude CLI، Codex CLI، وما إلى ذلك)
+- Local gateway runtime
+- Dashboard management APIs
+- Provider authentication and token refresh
+- Request translation and SSE streaming
+- Local state + usage persistence
+- Optional cloud sync orchestration
 
-## سياق النظام عالي المستوى
+### Out of Scope
+
+- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
+- Provider SLA/control plane outside local process
+- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
+
+## High-Level System Context
 
 ```mermaid
 flowchart LR
@@ -81,8 +85,8 @@ 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]
@@ -113,151 +117,152 @@ flowchart LR
     DASH --> CLOUD
 ```
 
-## مكونات وقت التشغيل الأساسية
+## Core Runtime Components
 
-## 1) واجهة برمجة التطبيقات وطبقة التوجيه (مسارات تطبيق Next.js)
+## 1) API and Routing Layer (Next.js App Routes)
 
-الدلائل الرئيسية:
+Main directories:
 
-- `src/app/api/v1/*` و`src/app/api/v1beta/*` لواجهات برمجة تطبيقات التوافق
-- `src/app/api/*` لواجهات برمجة التطبيقات للإدارة/التكوين
-- تتم إعادة الكتابة التالية في الخريطة `next.config.mjs` من `/v1/*` إلى `/api/v1/*`
+- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
+- `src/app/api/*` for management/configuration APIs
+- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
 
-طرق التوافق الهامة:
+Important compatibility routes:
 
 - `src/app/api/v1/chat/completions/route.ts`
 - `src/app/api/v1/messages/route.ts`
 - `src/app/api/v1/responses/route.ts`
-- `src/app/api/v1/models/route.ts` — يتضمن نماذج مخصصة مع `custom: true`
-- `src/app/api/v1/embeddings/route.ts` — إنشاء التضمين (6 موفري)
-- `src/app/api/v1/images/generations/route.ts` — إنشاء الصور (أكثر من 4 موفري خدمة، بما في ذلك Antigravity/Nebius)
+- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`
+- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)
+- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)
 - `src/app/api/v1/messages/count_tokens/route.ts`
-- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — دردشة مخصصة لكل مزود
-- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — عمليات التضمين المخصصة لكل مزود
-- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — صور مخصصة لكل مزود
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images
 - `src/app/api/v1beta/models/route.ts`
 - `src/app/api/v1beta/models/[...path]/route.ts`
 
-مجالات الإدارة:
+Management domains:
 
-- المصادقة/الإعدادات: `src/app/api/auth/*`، `src/app/api/settings/*`
-- مقدمو الخدمة/الاتصالات: `src/app/api/providers*`
-- عقد الموفر: `src/app/api/provider-nodes*`
-- النماذج المخصصة: `src/app/api/provider-models` (GET/POST/DELETE)
-- كتالوج النماذج: `src/app/api/models/catalog` (GET)
-- تكوين الوكيل: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
+- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
+- 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/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/*`
-- المفاتيح/الأسماء المستعارة/المجموعات/التسعير: `src/app/api/keys*`، `src/app/api/models/alias`، `src/app/api/combos*`، `src/app/api/pricing`
-- الاستخدام: `src/app/api/usage/*`
-- المزامنة/السحابة: `src/app/api/sync/*`، `src/app/api/cloud/*`
-- مساعدي أدوات CLI: `src/app/api/cli-tools/*`
-- مرشح IP: `src/app/api/settings/ip-filter` (GET/PUT)
-- ميزانية التفكير: `src/app/api/settings/thinking-budget` (GET/PUT)
-- موجه النظام: `src/app/api/settings/system-prompt` (GET/PUT)
-- الجلسات: `src/app/api/sessions` (GET)
-- حدود الأسعار: `src/app/api/rate-limits` (GET)
-- المرونة: `src/app/api/resilience` (GET/PATCH) - ملفات تعريف الموفر، قاطع الدائرة، حالة حد المعدل
-- إعادة ضبط المرونة: `src/app/api/resilience/reset` (POST) — إعادة ضبط الفواصل + فترات التهدئة
-- إحصائيات ذاكرة التخزين المؤقت: `src/app/api/cache/stats` (الحصول على/الحذف)
-- توفر النموذج: `src/app/api/models/availability` (GET/POST)
-- القياس عن بعد: `src/app/api/telemetry/summary` (GET)
-- الميزانية: `src/app/api/usage/budget` (GET/POST)
-- السلاسل الاحتياطية: `src/app/api/fallback/chains` (GET/POST/DELETE)
-- تدقيق الامتثال: `src/app/api/compliance/audit-log` (GET)
-- التقييمات: `src/app/api/evals` (GET/POST)، `src/app/api/evals/[suiteId]` (GET)
-- السياسات: `src/app/api/policies` (GET/POST)
+- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
+- Usage: `src/app/api/usage/*`
+- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
+- CLI tooling helpers: `src/app/api/cli-tools/*`
+- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)
+- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)
+- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)
+- Sessions: `src/app/api/sessions` (GET)
+- Rate limits: `src/app/api/rate-limits` (GET)
+- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns
+- Cache stats: `src/app/api/cache/stats` (GET/DELETE)
+- Model availability: `src/app/api/models/availability` (GET/POST)
+- Telemetry: `src/app/api/telemetry/summary` (GET)
+- Budget: `src/app/api/usage/budget` (GET/POST)
+- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET)
+- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
+- Policies: `src/app/api/policies` (GET/POST)
 
-## 2) SSE + جوهر الترجمة
+## 2) SSE + Translation Core
 
-وحدات التدفق الرئيسية:
+Main flow modules:
 
-- الإدخال: `src/sse/handlers/chat.ts`
-- التنسيق الأساسي: `open-sse/handlers/chatCore.ts`
-- محولات تنفيذ الموفر: `open-sse/executors/*`
-- اكتشاف التنسيق/تكوين الموفر: `open-sse/services/provider.ts`
-- تحليل/حل النموذج: `src/sse/services/model.ts`، `open-sse/services/model.ts`
-- المنطق الاحتياطي للحساب: `open-sse/services/accountFallback.ts`
-- سجل الترجمة: `open-sse/translator/index.ts`
-- تحويلات الدفق: `open-sse/utils/stream.ts`، `open-sse/utils/streamHandler.ts`
-- استخراج/تسوية الاستخدام: `open-sse/utils/usageTracking.ts`
-- محلل العلامات: `open-sse/utils/thinkTagParser.ts`
-- معالج التضمين: `open-sse/handlers/embeddings.ts`
-- تسجيل موفر التضمين: `open-sse/config/embeddingRegistry.ts`
-- معالج إنشاء الصور: `open-sse/handlers/imageGeneration.ts`
-- سجل موفر الصور: `open-sse/config/imageRegistry.ts`
-- تعقيم الاستجابة: `open-sse/handlers/responseSanitizer.ts`
-- تطبيع الدور: `open-sse/services/roleNormalizer.ts`
+- Entry: `src/sse/handlers/chat.ts`
+- Core orchestration: `open-sse/handlers/chatCore.ts`
+- Provider execution adapters: `open-sse/executors/*`
+- Format detection/provider config: `open-sse/services/provider.ts`
+- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
+- Account fallback logic: `open-sse/services/accountFallback.ts`
+- Translation registry: `open-sse/translator/index.ts`
+- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
+- Think tag parser: `open-sse/utils/thinkTagParser.ts`
+- Embedding handler: `open-sse/handlers/embeddings.ts`
+- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
+- Image generation handler: `open-sse/handlers/imageGeneration.ts`
+- Image provider registry: `open-sse/config/imageRegistry.ts`
+- Response sanitization: `open-sse/handlers/responseSanitizer.ts`
+- Role normalization: `open-sse/services/roleNormalizer.ts`
 
-الخدمات (منطق الأعمال):
+Services (business logic):
 
-- اختيار الحساب/تسجيل النقاط: `open-sse/services/accountSelector.ts`
-- إدارة دورة حياة السياق: `open-sse/services/contextManager.ts`
-- فرض عامل تصفية IP: `open-sse/services/ipFilter.ts`
-- تتبع الجلسة: `open-sse/services/sessionManager.ts`
-- طلب إلغاء البيانات المكررة: `open-sse/services/signatureCache.ts`
-- الحقن الفوري للنظام: `open-sse/services/systemPrompt.ts`
-- إدارة ميزانية التفكير: `open-sse/services/thinkingBudget.ts`
-- توجيه نموذج حرف البدل: `open-sse/services/wildcardRouter.ts`
-- إدارة حدود السعر: `open-sse/services/rateLimitManager.ts`
-- قاطع الدائرة: `open-sse/services/circuitBreaker.ts`
+- Account selection/scoring: `open-sse/services/accountSelector.ts`
+- Context lifecycle management: `open-sse/services/contextManager.ts`
+- IP filter enforcement: `open-sse/services/ipFilter.ts`
+- Session tracking: `open-sse/services/sessionManager.ts`
+- Request deduplication: `open-sse/services/signatureCache.ts`
+- System prompt injection: `open-sse/services/systemPrompt.ts`
+- Thinking budget management: `open-sse/services/thinkingBudget.ts`
+- Wildcard model routing: `open-sse/services/wildcardRouter.ts`
+- Rate limit management: `open-sse/services/rateLimitManager.ts`
+- Circuit breaker: `open-sse/services/circuitBreaker.ts`
 
-وحدات طبقة المجال:
+Domain layer modules:
 
-- توفر النموذج: `src/lib/domain/modelAvailability.ts`
-- قواعد/ميزانيات التكلفة: `src/lib/domain/costRules.ts`
-- السياسة الاحتياطية: `src/lib/domain/fallbackPolicy.ts`
-- محلل التحرير والسرد: `src/lib/domain/comboResolver.ts`
-- سياسة التأمين: `src/lib/domain/lockoutPolicy.ts`
-- محرك السياسة: `src/domain/policyEngine.ts` — الإغلاق المركزي ← الميزانية ← التقييم الاحتياطي
-- كتالوج رموز الأخطاء: `src/lib/domain/errorCodes.ts`
-- معرف الطلب: `src/lib/domain/requestId.ts`
-- مهلة الجلب: `src/lib/domain/fetchTimeout.ts`
-- طلب القياس عن بعد: `src/lib/domain/requestTelemetry.ts`
-- الامتثال/التدقيق: `src/lib/domain/compliance/index.ts`
-- عداء التقييم: `src/lib/domain/evalRunner.ts`
-- استمرارية حالة المجال: `src/lib/db/domainState.ts` — SQLite CRUD للسلاسل الاحتياطية، والميزانيات، وتاريخ التكلفة، وحالة الإغلاق، وقواطع الدائرة
+- Model availability: `src/lib/domain/modelAvailability.ts`
+- Cost rules/budgets: `src/lib/domain/costRules.ts`
+- Fallback policy: `src/lib/domain/fallbackPolicy.ts`
+- Combo resolver: `src/lib/domain/comboResolver.ts`
+- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
+- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
+- Error codes catalog: `src/lib/domain/errorCodes.ts`
+- Request ID: `src/lib/domain/requestId.ts`
+- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
+- Request telemetry: `src/lib/domain/requestTelemetry.ts`
+- Compliance/audit: `src/lib/domain/compliance/index.ts`
+- Eval runner: `src/lib/domain/evalRunner.ts`
+- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
 
-وحدات موفر OAuth (12 ملفًا فرديًا ضمن `src/lib/oauth/providers/`):
+OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
-- فهرس التسجيل: `src/lib/oauth/providers/index.ts`
-- مقدمو الخدمات الأفراد: `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`
-- الغلاف الرقيق: `src/lib/oauth/providers.ts` — إعادة التصدير من الوحدات الفردية
+- 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`
+- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
-## 3) طبقة الثبات
+## 3) Persistence Layer
 
-قاعدة بيانات الحالة الأساسية:
+Primary state DB (SQLite):
 
-- `src/lib/localDb.ts`
-- الملف: `${DATA_DIR}/db.json` (أو `$XDG_CONFIG_HOME/omniroute/db.json` عند التعيين، وإلا `~/.omniroute/db.json`)
-- الكيانات:providerConnections، وproviderNodes، وmodelAliases، والمجموعات، وapiKeys، والإعدادات، والتسعير، **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 persistence:
 
-- `src/lib/usageDb.ts`
-- الملفات: `${DATA_DIR}/usage.json`، `${DATA_DIR}/log.txt`، `${DATA_DIR}/call_logs/`
-- يتبع نفس سياسة الدليل الأساسي مثل `localDb` (`DATA_DIR`، ثم `XDG_CONFIG_HOME/omniroute` عند التعيين)
-- مقسمة إلى وحدات فرعية مركزة: `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
 
-قاعدة بيانات حالة المجال (SQLite):
+Domain State DB (SQLite):
 
-- `src/lib/db/domainState.ts` — عمليات CRUD لحالة المجال
-- الجداول (التي تم إنشاؤها في `src/lib/db/core.ts`): `domain_fallback_chains`، `domain_budgets`، `domain_cost_history`، `domain_lockout_state`، `domain_circuit_breakers`
-- نمط ذاكرة التخزين المؤقت للكتابة: تعد الخرائط الموجودة في الذاكرة موثوقة في وقت التشغيل؛ تتم كتابة الطفرات بشكل متزامن إلى SQLite؛ تتم استعادة الحالة من قاعدة البيانات عند البداية الباردة
+- `src/lib/db/domainState.ts` — CRUD operations for domain state
+- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
+- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
 
-## 4) المصادقة + الأسطح الأمنية
+## 4) Auth + Security Surfaces
 
-- مصادقة ملف تعريف الارتباط للوحة المعلومات: `src/proxy.ts`، `src/app/api/auth/login/route.ts`
-- إنشاء/التحقق من مفتاح واجهة برمجة التطبيقات: `src/shared/utils/apiKey.ts`
-- استمرت أسرار الموفر في إدخالات `providerConnections`
-- دعم الوكيل الصادر عبر `open-sse/utils/proxyFetch.ts` (env vars) و`open-sse/utils/networkProxy.ts` (قابل للتكوين لكل موفر أو عالمي)
+- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
+- API key generation/verification: `src/shared/utils/apiKey.ts`
+- Provider secrets persisted in `providerConnections` entries
+- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
 
-## 5) المزامنة السحابية
+## 5) Cloud Sync
 
-- الحرف الأول للمجدول: `src/lib/initCloudSync.ts`، `src/shared/services/initializeCloudSync.ts`
-- المهمة الدورية: `src/shared/services/cloudSyncScheduler.ts`
-- مسار التحكم: `src/app/api/sync/cloud/route.ts`
+- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
+- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Control route: `src/app/api/sync/cloud/route.ts`
 
-## دورة حياة الطلب (`/v1/chat/completions`)
+## Request Lifecycle (`/v1/chat/completions`)
 
 ```mermaid
 sequenceDiagram
@@ -304,7 +309,7 @@ sequenceDiagram
     Stream->>Usage: extract usage + persist history/log
 ```
 
-## التحرير والسرد + التدفق الاحتياطي للحساب
+## Combo + Account Fallback Flow
 
 ```mermaid
 flowchart TD
@@ -334,9 +339,9 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-يتم اتخاذ القرارات الاحتياطية بواسطة `open-sse/services/accountFallback.ts` باستخدام رموز الحالة والاستدلال على رسائل الخطأ.
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics.
 
-## دورة حياة OAuth Onboarding وتحديث الرمز المميز
+## OAuth Onboarding and Token Refresh Lifecycle
 
 ```mermaid
 sequenceDiagram
@@ -366,9 +371,9 @@ sequenceDiagram
     Test-->>UI: validation result
 ```
 
-يتم تنفيذ التحديث أثناء حركة المرور المباشرة داخل `open-sse/handlers/chatCore.ts` عبر المنفذ `refreshCredentials()`.
+Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
 
-## دورة حياة المزامنة السحابية (تمكين / مزامنة / تعطيل)
+## Cloud Sync Lifecycle (Enable / Sync / Disable)
 
 ```mermaid
 sequenceDiagram
@@ -400,9 +405,9 @@ sequenceDiagram
     Sync-->>UI: disabled
 ```
 
-يتم تشغيل المزامنة الدورية بواسطة `CloudSyncScheduler` عند تمكين السحابة.
+Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
 
-## نموذج البيانات وخريطة التخزين
+## Data Model and Storage Map
 
 ```mermaid
 erDiagram
@@ -503,14 +508,14 @@ erDiagram
     }
 ```
 
-ملفات التخزين المادية:
+Physical storage files:
 
-- الحالة الرئيسية: `${DATA_DIR}/db.json` (أو `$XDG_CONFIG_HOME/omniroute/db.json` عند التعيين، وإلا `~/.omniroute/db.json`)
-- إحصائيات الاستخدام: `${DATA_DIR}/usage.json`
-- خطوط سجل الطلب: `${DATA_DIR}/log.txt`
-- جلسات تصحيح أخطاء المترجم/الطلب الاختيارية: `<repo>/logs/...`
+- 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
 
 ```mermaid
 flowchart LR
@@ -522,8 +527,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]
@@ -541,241 +546,242 @@ flowchart LR
     Next --> SyncCloud
 ```
 
-## تعيين الوحدة (القرار الحاسم)
+## Module Mapping (Decision-Critical)
 
-### وحدات المسار وواجهة برمجة التطبيقات
+### Route and API Modules
 
-- `src/app/api/v1/*`، `src/app/api/v1beta/*`: واجهات برمجة تطبيقات التوافق
-- `src/app/api/v1/providers/[provider]/*`: مسارات مخصصة لكل مزود (الدردشة والتضمين والصور)
-- `src/app/api/providers*`: موفر CRUD والتحقق من الصحة والاختبار
-- `src/app/api/provider-nodes*`: إدارة العقدة المتوافقة المخصصة
-- `src/app/api/provider-models`: إدارة النماذج المخصصة (CRUD)
-- `src/app/api/models/catalog`: واجهة برمجة تطبيقات كتالوج النموذج الكامل (جميع الأنواع مجمعة حسب الموفر)
-- `src/app/api/oauth/*`: تدفقات OAuth/رمز الجهاز
-- `src/app/api/keys*`: دورة حياة مفتاح واجهة برمجة التطبيقات المحلية
-- `src/app/api/models/alias`: إدارة الاسم المستعار
-- `src/app/api/combos*`: إدارة التحرير والسرد الاحتياطية
-- `src/app/api/pricing`: تجاوزات التسعير لحساب التكلفة
-- `src/app/api/settings/proxy`: تكوين الوكيل (GET/PUT/DELETE)
-- `src/app/api/settings/proxy/test`: اختبار اتصال الوكيل الصادر (POST)
-- `src/app/api/usage/*`: واجهات برمجة تطبيقات الاستخدام والسجلات
-- `src/app/api/sync/*` + `src/app/api/cloud/*`: المزامنة السحابية والمساعدون الذين يواجهون السحابة
-- `src/app/api/cli-tools/*`: كاتب/أداة فحص تكوين CLI المحلية
-- `src/app/api/settings/ip-filter`: قائمة IP المسموح بها/القائمة المحظورة (GET/PUT)
-- `src/app/api/settings/thinking-budget`: تكوين ميزانية الرمز المميز (GET/PUT)
-- `src/app/api/settings/system-prompt`: موجه النظام العالمي (GET/PUT)
-- `src/app/api/sessions`: قائمة الجلسة النشطة (GET)
-- `src/app/api/rate-limits`: حالة حد السعر لكل حساب (GET)
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
+- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
+- `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/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
+- `src/app/api/combos*`: fallback combo management
+- `src/app/api/pricing`: pricing overrides for cost calculation
+- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
+- `src/app/api/usage/*`: usage and logs APIs
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
+- `src/app/api/cli-tools/*`: local CLI config writers/checkers
+- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
+- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
+- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
+- `src/app/api/sessions`: active session listing (GET)
+- `src/app/api/rate-limits`: per-account rate limit status (GET)
 
-### التوجيه والتنفيذ الأساسي
+### Routing and Execution Core
 
-- `src/sse/handlers/chat.ts`: تحليل الطلب، ومعالجة التحرير والسرد، وحلقة اختيار الحساب
-- `open-sse/handlers/chatCore.ts`: الترجمة، إرسال المنفذ، معالجة إعادة المحاولة/التحديث، إعداد الدفق
-- `open-sse/executors/*`: سلوك الشبكة والتنسيق الخاص بالموفر
+- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
+- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
+- `open-sse/executors/*`: provider-specific network and format behavior
 
-### سجل الترجمة ومحولات التنسيق
+### Translation Registry and Format Converters
 
-- `open-sse/translator/index.ts`: تسجيل المترجم وتنسيقه
-- طلب المترجمين: `open-sse/translator/request/*`
-- مترجمو الرد: `open-sse/translator/response/*`
-- ثوابت التنسيق: `open-sse/translator/formats.ts`
+- `open-sse/translator/index.ts`: translator registry and orchestration
+- Request translators: `open-sse/translator/request/*`
+- Response translators: `open-sse/translator/response/*`
+- Format constants: `open-sse/translator/formats.ts`
 
-### المثابرة
+### Persistence
 
-- `src/lib/localDb.ts`: التكوين/الحالة المستمرة
-- `src/lib/usageDb.ts`: سجل الاستخدام وسجلات الطلبات المتجددة
+- `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)
 
-كل مزود لديه منفذ متخصص يمتد `BaseExecutor` (في `open-sse/executors/base.ts`)، والذي يوفر بناء عنوان URL، وإنشاء الرأس، وإعادة المحاولة مع التراجع الأسي، وخطافات تحديث بيانات الاعتماد، وطريقة التنسيق `execute()`.
+Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method.
 
-| المنفذ                | المزود (المقدمون)                                                                                                                                            | التعامل الخاص                                                          |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
-| `DefaultExecutor`     | OpenAI، Claude، Gemini، Qwen، iFlow، OpenRouter، GLM، Kimi، MiniMax، DeepSeek، Groq، xAI، Mistral، Perplexity، Together، Fireworks، Cerebras، Cohere، NVIDIA | تكوين عنوان URL/الرأس الديناميكي لكل مزود                              |
-| `AntigravityExecutor` | جوجل مكافحة الجاذبية                                                                                                                                         | معرفات المشروع/الجلسة المخصصة، إعادة المحاولة بعد التحليل              |
-| `CodexExecutor`       | OpenAI Codex                                                                                                                                                 | يحقن تعليمات النظام، ويفرض جهدًا منطقيًا                               |
-| `CursorExecutor`      | بيئة تطوير متكاملة للمؤشر                                                                                                                                    | بروتوكول ConnectRPC، تشفير Protobuf، طلب التوقيع عبر المجموع الاختباري |
-| `GithubExecutor`      | جيثب مساعد الطيار                                                                                                                                            | تحديث الرمز المميز لـ Copilot، ورؤوس محاكاة VSCode                     |
-| `KiroExecutor`        | AWS CodeWhisperer/كيرو                                                                                                                                       | تنسيق AWS EventStream الثنائي → تحويل SSE                              |
-| `GeminiCLIExecutor`   | الجوزاء CLI                                                                                                                                                  | دورة تحديث رمز OAuth المميز لـ Google                                  |
+| 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                               |
+| `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 |
+| `GithubExecutor`      | GitHub Copilot                                                                                                                                               | Copilot token refresh, VSCode-mimicking headers                      |
+| `KiroExecutor`        | AWS CodeWhisperer/Kiro                                                                                                                                       | AWS EventStream binary format → SSE conversion                       |
+| `GeminiCLIExecutor`   | Gemini CLI                                                                                                                                                   | Google OAuth token refresh cycle                                     |
 
-يستخدم جميع الموفرين الآخرين (بما في ذلك العقد المتوافقة المخصصة) `DefaultExecutor`.
+All other providers (including custom compatible nodes) use the `DefaultExecutor`.
 
-## مصفوفة توافق الموفر
+## Provider Compatibility Matrix
 
-| مقدم                                | تنسيق            | مصادقة                      | تيار            | غير دفق | تحديث الرمز المميز | واجهة برمجة تطبيقات الاستخدام |
-| ----------------------------------- | ---------------- | --------------------------- | --------------- | ------- | ------------------ | ----------------------------- |
-| كلود                                | كلود             | مفتاح API / OAuth           | ✅              | ✅      | ✅                 | ⚠️ المشرف فقط                 |
-| الجوزاء                             | الجوزاء          | مفتاح API / OAuth           | ✅              | ✅      | ✅                 | ⚠️ وحدة التحكم السحابية       |
-| الجوزاء CLI                         | الجوزاء-cli      | أووث                        | ✅              | ✅      | ✅                 | ⚠️ وحدة التحكم السحابية       |
-| مكافحة الجاذبية                     | ضد الجاذبية      | أووث                        | ✅              | ✅      | ✅                 | ✅ الحصة الكاملة API          |
-| أوبن آي                             | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
-| الدستور الغذائي                     | openai-responses | أووث                        | ✅ مجبور        | ❌      | ✅                 | ✅ حدود المعدل                |
-| جيثب مساعد الطيار                   | أوبيناي          | OAuth + رمز مساعد الطيار    | ✅              | ✅      | ✅                 | ✅ لقطات الحصص                |
-| المؤشر                              | المؤشر           | المجموع الاختباري المخصص    | ✅              | ✅      | ❌                 | ❌                            |
-| كيرو                                | كيرو             | AWS SSO OIDC                | ✅(ايفنت ستريم) | ❌      | ✅                 | ✅ حدود الاستخدام             |
-| كوين                                | أوبيناي          | أووث                        | ✅              | ✅      | ✅                 | ⚠️ حسب الطلب                  |
-| اي فلو                              | أوبيناي          | OAuth (أساسي)               | ✅              | ✅      | ✅                 | ⚠️ حسب الطلب                  |
-| اوبن راوتر                          | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
-| جي إل إم/كيمي/ميني ماكس             | كلود             | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
-| ديب سيك                             | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
-| جروك                                | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
-| xAI (جروك)                          | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
-| ميسترال                             | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
-| الحيرة                              | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
-| معا منظمة العفو الدولية             | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
-| الألعاب النارية منظمة العفو الدولية | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
-| المخيخ                              | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
-| كوهير                               | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
-| نفيديا نيم                          | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
+| Provider         | Format           | Auth                  | Stream           | Non-Stream | Token Refresh | Usage API          |
+| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
+| Claude           | claude           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Admin only      |
+| Gemini           | gemini           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Gemini CLI       | gemini-cli       | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Antigravity      | antigravity      | OAuth                 | ✅               | ✅         | ✅            | ✅ Full quota API  |
+| OpenAI           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Codex            | openai-responses | OAuth                 | ✅ forced        | ❌         | ✅            | ✅ Rate limits     |
+| GitHub Copilot   | openai           | OAuth + Copilot Token | ✅               | ✅         | ✅            | ✅ Quota snapshots |
+| Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
+| Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
+| Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| iFlow            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Groq             | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| xAI (Grok)       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Mistral          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Perplexity       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Together AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Fireworks AI     | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 
-## تنسيق تغطية الترجمة
+## Format Translation Coverage
 
-تتضمن تنسيقات المصدر المكتشفة ما يلي:
+Detected source formats include:
 
 - `openai`
 - `openai-responses`
 - `claude`
 - `gemini`
 
-تتضمن التنسيقات المستهدفة ما يلي:
+Target formats include:
 
-- دردشة/ردود OpenAI
-- كلود
-- الجوزاء/الجوزاء-CLI/الظرف المضاد للجاذبية
-- كيرو
-- المؤشر
+- OpenAI chat/Responses
+- Claude
+- Gemini/Gemini-CLI/Antigravity envelope
+- Kiro
+- Cursor
 
-تستخدم الترجمات **OpenAI كتنسيق مركزي** — تمر جميع التحويلات عبر OpenAI كتنسيق وسيط:
+Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
 
 ```
 Source Format → OpenAI (hub) → Target Format
 ```
 
-يتم تحديد الترجمات ديناميكيًا استنادًا إلى شكل حمولة المصدر والتنسيق المستهدف للموفر.
+Translations are selected dynamically based on source payload shape and provider target format.
 
-طبقات معالجة إضافية في مسار الترجمة:
+Additional processing layers in the translation pipeline:
 
-- **تطهير الاستجابة** — يزيل الحقول غير القياسية من استجابات تنسيق OpenAI (سواء المتدفقة أو غير المتدفقة) لضمان الامتثال الصارم لـ SDK
-- **تطبيع الدور** — تحويل `developer` → `system` للأهداف غير التابعة لـ OpenAI؛ يدمج `system` → `user` للنماذج التي ترفض دور النظام (GLM، ERNIE)
-- **فكر في استخراج العلامات** — يوزع كتل `<think>...</think>` من المحتوى إلى حقل `reasoning_content`
-- **الإخراج المنظم** — يحول OpenAI `response_format.json_schema` إلى `responseMimeType` + `responseSchema` الخاص بـ Gemini
+- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance
+- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)
+- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field
+- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`
 
-## نقاط نهاية واجهة برمجة التطبيقات المدعومة
+## Supported API Endpoints
 
-| نقطة النهاية                                       | تنسيق              | معالج                                                                     |
-| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------------- |
-| `POST /v1/chat/completions`                        | دردشة OpenAI       | `src/sse/handlers/chat.ts`                                                |
-| `POST /v1/messages`                                | رسائل كلود         | نفس المعالج (تم اكتشافه تلقائيًا)                                         |
-| `POST /v1/responses`                               | ردود OpenAI        | `open-sse/handlers/responsesHandler.ts`                                   |
-| `POST /v1/embeddings`                              | تضمينات OpenAI     | `open-sse/handlers/embeddings.ts`                                         |
-| `GET /v1/embeddings`                               | قائمة النماذج      | طريق API                                                                  |
-| `POST /v1/images/generations`                      | صور OpenAI         | `open-sse/handlers/imageGeneration.ts`                                    |
-| `GET /v1/images/generations`                       | قائمة النماذج      | طريق API                                                                  |
-| `POST /v1/providers/{provider}/chat/completions`   | دردشة OpenAI       | مخصص لكل مزود مع التحقق من صحة النموذج                                    |
-| `POST /v1/providers/{provider}/embeddings`         | تضمينات OpenAI     | مخصص لكل مزود مع التحقق من صحة النموذج                                    |
-| `POST /v1/providers/{provider}/images/generations` | صور OpenAI         | مخصص لكل مزود مع التحقق من صحة النموذج                                    |
-| `POST /v1/messages/count_tokens`                   | عدد كلود توكن      | طريق API                                                                  |
-| `GET /v1/models`                                   | قائمة نماذج OpenAI | مسار واجهة برمجة التطبيقات (الدردشة + التضمين + الصورة + النماذج المخصصة) |
-| `GET /api/models/catalog`                          | كتالوج             | جميع النماذج مجمعة حسب الموفر + النوع                                     |
-| `POST /v1beta/models/*:streamGenerateContent`      | مولود برج الجوزاء  | طريق API                                                                  |
-| `GET/PUT/DELETE /api/settings/proxy`               | تكوين الوكيل       | تكوين وكيل الشبكة                                                         |
-| `POST /api/settings/proxy/test`                    | اتصال الوكيل       | نقطة نهاية اختبار صحة الوكيل/الاتصال                                      |
-| `GET/POST/DELETE /api/provider-models`             | نماذج مخصصة        | إدارة النماذج المخصصة لكل مزود                                            |
+| 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                 |
 
-## تجاوز المعالج
+## Bypass Handler
 
-يعترض معالج التجاوز (`open-sse/utils/bypassHandler.ts`) طلبات "الرمي" المعروفة من Claude CLI - أصوات التمهيد، واستخراج العناوين، وعدد الرموز المميزة - ويعيد **استجابة زائفة** دون استهلاك الرموز المميزة للموفر الرئيسي. يتم تشغيل هذا فقط عندما يحتوي `User-Agent` على `claude-cli`.
+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
 
-يوفر مسجل الطلب (`open-sse/utils/requestLogger.ts`) مسارًا لتسجيل تصحيح الأخطاء مكون من 7 مراحل، معطل افتراضيًا، وممكن عبر `ENABLE_REQUEST_LOGS=true`:
+The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`:
 
 ```
 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
 ```
 
-تتم كتابة الملفات إلى `<repo>/logs/<session>/` لكل جلسة طلب.
+Files are written to `<repo>/logs/<session>/` for each request session.
 
-## أوضاع الفشل والمرونة
+## Failure Modes and Resilience
 
-## 1) توفر الحساب/المزود
+## 1) Account/Provider Availability
 
-- فترة تباطؤ حساب الموفر عند حدوث أخطاء عابرة/معدل/مصادقة
-- احتياطي الحساب قبل فشل الطلب
-- نموذج التحرير والسرد الاحتياطي عند استنفاد مسار النموذج/المزود الحالي
+- provider account cooldown on transient/rate/auth errors
+- account fallback before failing request
+- combo model fallback when current model/provider path is exhausted
 
-## 2) انتهاء صلاحية الرمز المميز
+## 2) Token Expiry
 
-- الفحص المسبق والتحديث مع إعادة المحاولة لموفري الخدمة القابلين للتحديث
-- 401/403 إعادة المحاولة بعد محاولة التحديث في المسار الأساسي
+- pre-check and refresh with retry for refreshable providers
+- 401/403 retry after refresh attempt in core path
 
-## 3) سلامة الدفق
+## 3) Stream Safety
 
-- وحدة تحكم تيار قطع الاتصال
-- دفق الترجمة مع تدفق نهاية الدفق ومعالجة `[DONE]`
-- احتياطي تقدير الاستخدام عندما تكون البيانات الوصفية لاستخدام الموفر مفقودة
+- disconnect-aware stream controller
+- translation stream with end-of-stream flush and `[DONE]` handling
+- usage estimation fallback when provider usage metadata is missing
 
-## 4) تدهور المزامنة السحابية
+## 4) Cloud Sync Degradation
 
-- ظهرت أخطاء المزامنة ولكن يستمر وقت التشغيل المحلي
-- يحتوي المجدول على منطق قادر على إعادة المحاولة، ولكن التنفيذ الدوري يستدعي حاليًا مزامنة المحاولة الواحدة بشكل افتراضي
+- sync errors are surfaced but local runtime continues
+- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
 
-## 5) سلامة البيانات
+## 5) Data Integrity
 
-- ترحيل/إصلاح شكل قاعدة البيانات للمفاتيح المفقودة
-- ضمانات إعادة تعيين JSON الفاسدة لـ localDb وuseDb
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
-## إمكانية الملاحظة والإشارات التشغيلية
+## Observability and Operational Signals
 
-مصادر رؤية وقت التشغيل:
+Runtime visibility sources:
 
-- سجلات وحدة التحكم من `src/sse/utils/logger.ts`
-- مجاميع الاستخدام لكل طلب في `usage.json`
-- سجل حالة الطلب النصي في `log.txt`
-- سجلات الطلب/الترجمة العميقة الاختيارية ضمن `logs/` عندما `ENABLE_REQUEST_LOGS=true`
-- نقاط نهاية استخدام لوحة المعلومات (`/api/usage/*`) لاستهلاك واجهة المستخدم
+- console logs from `src/sse/utils/logger.ts`
+- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- textual request status log in `log.txt` (optional/compat)
+- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true`
+- dashboard usage endpoints (`/api/usage/*`) for UI consumption
 
-## الحدود الحساسة للأمن
+## Security-Sensitive Boundaries
 
-- سر JWT (`JWT_SECRET`) يؤمن التحقق/التوقيع على ملف تعريف الارتباط لجلسة لوحة المعلومات
-- يجب تجاوز الاحتياطي الأولي لكلمة المرور (`INITIAL_PASSWORD`، الافتراضي `123456`) في عمليات النشر الحقيقية
-- سر HMAC لمفتاح API (`API_KEY_SECRET`) يؤمن تنسيق مفتاح API المحلي الذي تم إنشاؤه
-- تظل أسرار الموفر (مفاتيح/رموز واجهة برمجة التطبيقات) موجودة في قاعدة البيانات المحلية ويجب حمايتها على مستوى نظام الملفات
-- تعتمد نقاط نهاية المزامنة السحابية على مصادقة مفتاح API + دلالات معرف الجهاز
+- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
+- 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
 
-## مصفوفة البيئة ووقت التشغيل
+## Environment and Runtime Matrix
 
-متغيرات البيئة المستخدمة بشكل نشط بواسطة التعليمات البرمجية:
+Environment variables actively used by code:
 
-- التطبيق/المصادقة: `JWT_SECRET`، `INITIAL_PASSWORD`
-- التخزين: `DATA_DIR`
-- سلوك العقدة المتوافقة: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
-- تجاوز قاعدة التخزين الاختيارية (Linux/macOS عند إلغاء تعيين `DATA_DIR`): `XDG_CONFIG_HOME`
-- التجزئة الأمنية: `API_KEY_SECRET`، `MACHINE_ID_SALT`
-- التسجيل: `ENABLE_REQUEST_LOGS`
-- عنوان URL للمزامنة/السحابة: `NEXT_PUBLIC_BASE_URL`، `NEXT_PUBLIC_CLOUD_URL`
-- الوكيل الصادر: `HTTP_PROXY`، `HTTPS_PROXY`، `ALL_PROXY`، `NO_PROXY` ومتغيرات الأحرف الصغيرة
-- علامات ميزات SOCKS5: `ENABLE_SOCKS5_PROXY`، `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
-- مساعدو النظام الأساسي/وقت التشغيل (ليس التكوين الخاص بالتطبيق): `APPDATA`، `NODE_ENV`، `PORT`، `HOSTNAME`
+- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Storage: `DATA_DIR`
+- 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`
+- 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`
+- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
 
-## الملاحظات المعمارية المعروفة
+## Known Architectural Notes
 
-1. يتشارك `usageDb` و`localDb` الآن نفس سياسة الدليل الأساسي (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) مع ترحيل الملفات القديمة.
-2. يقوم `/api/v1/route.ts` بإرجاع قائمة نماذج ثابتة وهو ليس مصدر النماذج الرئيسي الذي يستخدمه `/v1/models`.
-3. يقوم مسجل الطلب بكتابة الرؤوس/النص الكامل عند تمكينه؛ التعامل مع دليل السجل على أنه حساس.
-4. يعتمد سلوك السحابة على `NEXT_PUBLIC_BASE_URL` الصحيح وإمكانية الوصول إلى نقطة نهاية السحابة.
-5. تم نشر الدليل `open-sse/` باسم `@omniroute/open-sse` **حزمة مساحة عمل npm**. يقوم كود المصدر باستيراده عبر `@omniroute/open-sse/...` (تم حله بواسطة Next.js `transpilePackages`). لا تزال مسارات الملفات في هذا المستند تستخدم اسم الدليل `open-sse/` لتحقيق الاتساق.
-6. تستخدم المخططات الموجودة في لوحة المعلومات **Recharts** (المستندة إلى SVG) لتصورات التحليلات التفاعلية التي يمكن الوصول إليها (المخططات الشريطية لاستخدام النموذج، والجداول التفصيلية للموفرين مع معدلات النجاح).
-7. تستخدم اختبارات E2E **Playwright** (`tests/e2e/`)، ويتم تشغيلها عبر `npm run test:e2e`. تستخدم اختبارات الوحدة **مشغل اختبار Node.js** (`tests/unit/`)، ويتم تشغيله عبر `npm run test:plan3`. كود المصدر ضمن `src/` هو **TypeScript** (`.ts`/`.tsx`)؛ تظل مساحة العمل `open-sse/` JavaScript (`.js`).
-8. تم تنظيم صفحة الإعدادات في 5 علامات تبويب: الأمان، التوجيه (6 إستراتيجيات عالمية: التعبئة أولاً، جولة روبن، p2c، عشوائي، الأقل استخدامًا، تحسين التكلفة)، المرونة (حدود المعدل القابلة للتحرير، قاطع الدائرة، السياسات)، الذكاء الاصطناعي (ميزانية التفكير، موجه النظام، ذاكرة التخزين المؤقت السريعة)، المتقدم (الوكيل).
+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: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), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
 
-## قائمة التحقق التشغيلية
+## Operational Verification Checklist
 
-- البناء من المصدر: `npm run build`
-- إنشاء صورة Docker: `docker build -t omniroute .`
-- ابدأ الخدمة وتحقق:
+- Build from source: `npm run build`
+- Build Docker image: `docker build -t omniroute .`
+- Start service and verify:
 - `GET /api/settings`
 - `GET /api/v1/models`
-- يجب أن يكون عنوان URL الأساسي لهدف واجهة سطر الأوامر هو `http://<host>:20128/v1` عندما يكون `PORT=20128`
+- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`

docs/i18n/ar/AUTO-COMBO.md

@@ -0,0 +1,67 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/AUTO-COMBO.md) · 🇪🇸 [es](../es/AUTO-COMBO.md) · 🇫🇷 [fr](../fr/AUTO-COMBO.md) · 🇩🇪 [de](../de/AUTO-COMBO.md) · 🇮🇹 [it](../it/AUTO-COMBO.md) · 🇷🇺 [ru](../ru/AUTO-COMBO.md) · 🇨🇳 [zh-CN](../zh-CN/AUTO-COMBO.md) · 🇯🇵 [ja](../ja/AUTO-COMBO.md) · 🇰🇷 [ko](../ko/AUTO-COMBO.md) · 🇸🇦 [ar](../ar/AUTO-COMBO.md) · 🇮🇳 [in](../in/AUTO-COMBO.md) · 🇹🇭 [th](../th/AUTO-COMBO.md) · 🇻🇳 [vi](../vi/AUTO-COMBO.md) · 🇮🇩 [id](../id/AUTO-COMBO.md) · 🇲🇾 [ms](../ms/AUTO-COMBO.md) · 🇳🇱 [nl](../nl/AUTO-COMBO.md) · 🇵🇱 [pl](../pl/AUTO-COMBO.md) · 🇸🇪 [sv](../sv/AUTO-COMBO.md) · 🇳🇴 [no](../no/AUTO-COMBO.md) · 🇩🇰 [da](../da/AUTO-COMBO.md) · 🇫🇮 [fi](../fi/AUTO-COMBO.md) · 🇵🇹 [pt](../pt/AUTO-COMBO.md) · 🇷🇴 [ro](../ro/AUTO-COMBO.md) · 🇭🇺 [hu](../hu/AUTO-COMBO.md) · 🇧🇬 [bg](../bg/AUTO-COMBO.md) · 🇸🇰 [sk](../sk/AUTO-COMBO.md) · 🇺🇦 [uk-UA](../uk-UA/AUTO-COMBO.md) · 🇮🇱 [he](../he/AUTO-COMBO.md) · 🇵🇭 [phi](../phi/AUTO-COMBO.md)
+
+---
+
+# 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/i18n/ar/CODEBASE_DOCUMENTATION.md

@@ -1,22 +1,26 @@
-# الطريق الشامل - وثائق قاعدة التعليمات البرمجية
-
-🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md)
-
-> دليل شامل ومناسب للمبتدئين إلى جهاز التوجيه الوكيل AI **omniroute** متعدد الموفرين.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../es/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../fr/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../de/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../it/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../ru/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../ja/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../ko/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../ar/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [in](../in/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../th/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../vi/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../id/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../ms/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../nl/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../pl/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../sv/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../no/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../da/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../fi/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../pt/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../ro/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../hu/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../bg/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../sk/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../he/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../phi/CODEBASE_DOCUMENTATION.md)
 
 ---
 
-## 1. ما هو الطريق الشامل؟
+# omniroute — Codebase Documentation
 
-omniroute هو **جهاز توجيه وكيل** يقع بين عملاء الذكاء الاصطناعي (Claude CLI، وCodex، وCursor IDE، وما إلى ذلك) وموفري الذكاء الاصطناعي (Anthropic، وGoogle، وOpenAI، وAWS، وGitHub، وما إلى ذلك). إنه يحل مشكلة واحدة كبيرة:
+🌐 **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)
 
-> **يتحدث عملاء الذكاء الاصطناعي المختلفون "لغات" مختلفة (تنسيقات واجهة برمجة التطبيقات)، ويتوقع مقدمو خدمات الذكاء الاصطناعي المختلفون "لغات" مختلفة أيضًا. ** يترجم المسار الشامل بينهم تلقائيًا.
-
-فكر في الأمر وكأنه مترجم عالمي في الأمم المتحدة - يمكن لأي مندوب التحدث بأي لغة، ويقوم المترجم بتحويلها لأي مندوب آخر.
+> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router.
 
 ---
 
-## 2. نظرة عامة على الهندسة المعمارية
+## 1. What Is omniroute?
+
+omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem:
+
+> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically.
+
+Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate.
+
+---
+
+## 2. Architecture Overview
 
 ```mermaid
 graph LR
@@ -61,20 +65,20 @@ graph LR
     H -.-> G
 ```
 
-### المبدأ الأساسي: الترجمة المحورية
+### Core Principle: Hub-and-Spoke Translation
 
-تمر جميع ترجمة التنسيقات عبر **تنسيق OpenAI كمركز**:
+All format translation passes through **OpenAI format as the hub**:
 
 ```
 Client Format → [OpenAI Hub] → Provider Format    (request)
 Provider Format → [OpenAI Hub] → Client Format    (response)
 ```
 
-هذا يعني أنك تحتاج فقط إلى مترجمين **N** (واحد لكل تنسيق) بدلاً من **N²** (كل زوج).
+This means you only need **N translators** (one per format) instead of **N²** (every pair).
 
 ---
 
-## 3. هيكل المشروع
+## 3. Project Structure
 
 ```
 omniroute/
@@ -104,22 +108,22 @@ omniroute/
 
 ---
 
-## 4. تفصيل الوحدة تلو الأخرى
+## 4. Module-by-Module Breakdown
 
-### 4.1 التكوين (`open-sse/config/`)
+### 4.1 Config (`open-sse/config/`)
 
-**المصدر الوحيد للحقيقة** لجميع إعدادات الموفر.
+The **single source of truth** for all provider configuration.
 
-| ملف                           | الغرض                                                                                                                                                                                                                        |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `constants.ts`                | كائن `PROVIDERS` يحتوي على عناوين URL الأساسية وبيانات اعتماد OAuth (الافتراضية) والرؤوس ومطالبات النظام الافتراضية لكل موفر. يحدد أيضًا `HTTP_STATUS`، و`ERROR_TYPES`، و`COOLDOWN_MS`، و`BACKOFF_CONFIG`، و`SKIP_PATTERNS`. |
-| `credentialLoader.ts`         | يقوم بتحميل بيانات الاعتماد الخارجية من `data/provider-credentials.json` ويدمجها في الإعدادات الافتراضية المشفرة في `PROVIDERS`. يحافظ على الأسرار خارج نطاق التحكم بالمصدر مع الحفاظ على التوافق مع الإصدارات السابقة.      |
-| `providerModels.ts`           | سجل النموذج المركزي: الأسماء المستعارة لموفر الخرائط → معرفات النموذج. وظائف مثل `getModels()`، `getProviderByAlias()`.                                                                                                      |
-| `codexInstructions.ts`        | تعليمات النظام التي تم إدخالها في طلبات الدستور الغذائي (قيود التحرير، قواعد الاختبار، سياسات الموافقة).                                                                                                                     |
-| `defaultThinkingSignature.ts` | توقيعات "التفكير" الافتراضية لنماذج كلود وجيميني.                                                                                                                                                                            |
-| `ollamaModels.ts`             | تعريف المخطط لنماذج أولاما المحلية (الاسم، الحجم، العائلة، التكميم).                                                                                                                                                         |
+| File                          | Purpose                                                                                                                                                                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `constants.ts`                | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. |
+| `credentialLoader.ts`         | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility.               |
+| `providerModels.ts`           | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`.                                                                                                          |
+| `codexInstructions.ts`        | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies).                                                                                                                 |
+| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models.                                                                                                                                                               |
+| `ollamaModels.ts`             | Schema definition for local Ollama models (name, size, family, quantization).                                                                                                                                             |
 
-#### تدفق تحميل بيانات الاعتماد
+#### Credential Loading Flow
 
 ```mermaid
 flowchart TD
@@ -142,9 +146,9 @@ flowchart TD
 
 ---
 
-### 4.2 المنفذون (`open-sse/executors/`)
+### 4.2 Executors (`open-sse/executors/`)
 
-يقوم المنفذون بتغليف **المنطق الخاص بالمزود** باستخدام **نمط الإستراتيجية**. يتجاوز كل منفذ الأساليب الأساسية حسب الحاجة.
+Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed.
 
 ```mermaid
 classDiagram
@@ -194,32 +198,32 @@ classDiagram
     BaseExecutor <|-- GithubExecutor
 ```
 
-| المنفذ           | مقدم                                                | التخصصات الرئيسية                                                                                                                                   |
-| ---------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `base.ts`        | —                                                   | قاعدة الملخصات: إنشاء عنوان URL، والرؤوس، ومنطق إعادة المحاولة، وتحديث بيانات الاعتماد                                                              |
-| `default.ts`     | كلود، جيميني، أوبن آي آي، جي إل إم، كيمي، ميني ماكس | تحديث رمز OAuth العام للموفرين القياسيين                                                                                                            |
-| `antigravity.ts` | جوجل كلاود كود                                      | إنشاء معرف المشروع/الجلسة، وإرجاع عناوين URL المتعددة، وإعادة محاولة التحليل المخصصة من رسائل الخطأ ("إعادة التعيين بعد 2 ساعة و7 دقائق و23 ثانية") |
-| `cursor.ts`      | بيئة تطوير متكاملة للمؤشر                           | **الأكثر تعقيدًا**: مصادقة المجموع الاختباري SHA-256، وترميز طلب Protobuf، وEventStream الثنائي → تحليل استجابة SSE                                 |
-| `codex.ts`       | OpenAI Codex                                        | إدخال تعليمات النظام، وإدارة مستويات التفكير، وإزالة المعلمات غير المدعومة                                                                          |
-| `gemini-cli.ts`  | جوجل الجوزاء CLI                                    | بناء عنوان URL المخصص (`streamGenerateContent`)، تحديث رمز OAuth المميز لـ Google                                                                   |
-| `github.ts`      | جيثب مساعد الطيار                                   | نظام الرمز المزدوج (GitHub OAuth + Copilot token)، محاكاة رأس VSCode                                                                                |
-| `kiro.ts`        | AWS CodeWhisperer                                   | التحليل الثنائي لـ AWS EventStream، وإطارات أحداث AMZN، وتقدير الرمز المميز                                                                         |
-| `index.ts`       | —                                                   | المصنع: اسم موفر الخرائط ← فئة المنفذ، مع خيار احتياطي افتراضي                                                                                      |
+| Executor         | Provider                                   | Key Specializations                                                                                                 |
+| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `base.ts`        | —                                          | Abstract base: URL building, headers, retry logic, credential refresh                                               |
+| `default.ts`     | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers                                                                  |
+| `antigravity.ts` | Google Cloud Code                          | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") |
+| `cursor.ts`      | Cursor IDE                                 | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing       |
+| `codex.ts`       | OpenAI Codex                               | Injects system instructions, manages thinking levels, removes unsupported parameters                                |
+| `gemini-cli.ts`  | Google Gemini CLI                          | Custom URL building (`streamGenerateContent`), Google OAuth token refresh                                           |
+| `github.ts`      | GitHub Copilot                             | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking                                           |
+| `kiro.ts`        | AWS CodeWhisperer                          | AWS EventStream binary parsing, AMZN event frames, token estimation                                                 |
+| `index.ts`       | —                                          | Factory: maps provider name → executor class, with default fallback                                                 |
 
 ---
 
-### 4.3 المعالجات (`open-sse/handlers/`)
+### 4.3 Handlers (`open-sse/handlers/`)
 
-**طبقة التنسيق** — تتولى تنسيق الترجمة والتنفيذ والتدفق ومعالجة الأخطاء.
+The **orchestration layer** — coordinates translation, execution, streaming, and error handling.
 
-| ملف                   | الغرض                                                                                                                                                                                              |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `chatCore.ts`         | ** المنسق المركزي ** (~ 600 سطر). يتعامل مع دورة حياة الطلب الكاملة: اكتشاف التنسيق ← الترجمة ← إرسال المنفذ ← استجابة التدفق/غير المتدفق ← تحديث الرمز المميز ← معالجة الأخطاء ← تسجيل الاستخدام. |
-| `responsesHandler.ts` | محول واجهة برمجة تطبيقات استجابات OpenAI: يحول تنسيق الردود ← إكمالات الدردشة ← يرسل إلى `chatCore` ← يحول SSE مرة أخرى إلى تنسيق الردود.                                                          |
-| `embeddings.ts`       | معالج إنشاء التضمين: يحل نموذج التضمين → الموفر، ويرسل إلى واجهة برمجة تطبيقات الموفر، ويعيد استجابة التضمين المتوافقة مع OpenAI. يدعم 6+ مقدمي الخدمات.                                           |
-| `imageGeneration.ts`  | معالج إنشاء الصور: يحل نموذج الصورة → الموفر، ويدعم الأوضاع المتوافقة مع OpenAI، وGemini-image (Antigravity)، والوضع الاحتياطي (Nebius). إرجاع صور base64 أو URL.                                  |
+| File                  | Purpose                                                                                                                                                                                                                |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chatCore.ts`         | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. |
+| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format.                                                                        |
+| `embeddings.ts`       | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers.                                                    |
+| `imageGeneration.ts`  | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images.                                          |
 
-#### دورة حياة الطلب (chatCore.ts)
+#### Request Lifecycle (chatCore.ts)
 
 ```mermaid
 sequenceDiagram
@@ -258,28 +262,28 @@ sequenceDiagram
 
 ---
 
-### 4.4 الخدمات (`open-sse/services/`)
+### 4.4 Services (`open-sse/services/`)
 
-منطق الأعمال الذي يدعم المعالجات والمنفذين.
+Business logic that supports the handlers and executors.
 
-| ملف                  | الغرض                                                                                                                                                                                                                                                                                           |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `provider.ts`        | **كشف التنسيق** (`detectFormat`): تحليلات بنية الجسم لتحديد تنسيقات Claude/OpenAI/Gemini/Antigravity/Responses (تتضمن `max_tokens` الاستدلال لكلود). أيضًا: بناء عنوان URL، وبناء الرأس، وتطبيع تكوين التفكير. يدعم موفري الخدمات الديناميكيين `openai-compatible-*` و`anthropic-compatible-*`. |
-| `model.ts`           | تحليل سلسلة النموذج (`claude/model-name` → `{provider: "claude", model: "model-name"}`)، ودقة الاسم المستعار مع اكتشاف التصادم، وتعقيم الإدخال (يرفض أحرف اجتياز المسار/التحكم)، ودقة معلومات النموذج مع دعم getter للاسم المستعار غير المتزامن.                                                |
-| `accountFallback.ts` | التعامل مع الحد الأقصى للمعدل: التراجع الأسي (1s → 2s → 4s → 2min كحد أقصى)، وإدارة فترة تهدئة الحساب، وتصنيف الأخطاء (أي الأخطاء تؤدي إلى التراجع مقابل عدم حدوثه).                                                                                                                            |
-| `tokenRefresh.ts`    | تحديث رمز OAuth المميز **لكل مزود**: Google (Gemini، Antigravity)، Claude، Codex، Qwen، iFlow، GitHub (OAuth + Copilot Dual-Token)، Kiro (AWS SSO OIDC + Social Auth). يتضمن ذاكرة تخزين مؤقت لإلغاء البيانات المكررة أثناء الرحلة وإعادة المحاولة مع التراجع المتسارع.                         |
-| `combo.ts`           | **نماذج مجمعة**: سلاسل من النماذج الاحتياطية. إذا فشل النموذج A مع وجود خطأ مؤهل للرجوع إليه، فجرّب النموذج B، ثم C، وما إلى ذلك. يقوم بإرجاع رموز الحالة الأولية الفعلية.                                                                                                                      |
-| `usage.ts`           | جلب بيانات الحصص/الاستخدام من واجهات برمجة تطبيقات الموفر (حصص GitHub Copilot، وحصص نماذج Antigravity، وحدود معدل Codex، وأعطال استخدام Kiro، وإعدادات Claude).                                                                                                                                 |
-| `accountSelector.ts` | اختيار الحساب الذكي باستخدام خوارزمية التسجيل: يأخذ في الاعتبار الأولوية والحالة الصحية والموضع الدائري وحالة التهدئة لاختيار الحساب الأمثل لكل طلب.                                                                                                                                            |
-| `contextManager.ts`  | إدارة دورة حياة سياق الطلب: إنشاء وتتبع كائنات السياق لكل طلب باستخدام بيانات التعريف (معرف الطلب، والطوابع الزمنية، ومعلومات الموفر) لتصحيح الأخطاء والتسجيل.                                                                                                                                  |
-| `ipFilter.ts`        | التحكم في الوصول المستند إلى IP: يدعم وضعي القائمة المسموح بها والقائمة المحظورة. التحقق من صحة عنوان IP للعميل مقابل القواعد التي تم تكوينها قبل معالجة طلبات واجهة برمجة التطبيقات.                                                                                                           |
-| `sessionManager.ts`  | تتبع الجلسة باستخدام بصمة العميل: يتتبع الجلسات النشطة باستخدام معرفات العميل المجزأة، ويراقب عدد الطلبات، ويوفر مقاييس الجلسة.                                                                                                                                                                 |
-| `signatureCache.ts`  | طلب ذاكرة التخزين المؤقت لإلغاء البيانات المكررة المستندة إلى التوقيع: يمنع الطلبات المكررة عن طريق تخزين توقيعات الطلب الأخيرة مؤقتًا وإرجاع الاستجابات المخزنة مؤقتًا للطلبات المتطابقة خلال نافذة زمنية.                                                                                     |
-| `systemPrompt.ts`    | الحقن الفوري للنظام العالمي: يُلحق أو يُلحق موجه نظام قابل للتكوين لجميع الطلبات، مع معالجة التوافق لكل مزود.                                                                                                                                                                                   |
-| `thinkingBudget.ts`  | إدارة ميزانية الرموز المميزة: تدعم أوضاع المرور، والتلقائي (تكوين التفكير الشريطي)، والمخصص (الميزانية الثابتة)، والتكيفية (مدرجة التعقيد) للتحكم في رموز التفكير/الاستدلال.                                                                                                                    |
-| `wildcardRouter.ts`  | توجيه نمط نموذج حرف البدل: يحل أنماط حرف البدل (على سبيل المثال، `*/claude-*`) لأزواج الموفر/النموذج الملموسة بناءً على التوفر والأولوية.                                                                                                                                                       |
+| File                 | Purpose                                                                                                                                                                                                                                                                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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.                                                                       |
+| `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.                                                                                                                                                              |
+| `contextManager.ts`  | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging.                                                                                                                                                                  |
+| `ipFilter.ts`        | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests.                                                                                                                                                                                          |
+| `sessionManager.ts`  | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics.                                                                                                                                                                            |
+| `signatureCache.ts`  | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window.                                                                                                                                              |
+| `systemPrompt.ts`    | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling.                                                                                                                                                                                            |
+| `thinkingBudget.ts`  | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens.                                                                                                                                        |
+| `wildcardRouter.ts`  | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority.                                                                                                                                                                                   |
 
-#### إلغاء البيانات المكررة لتحديث الرمز المميز
+#### Token Refresh Deduplication
 
 ```mermaid
 sequenceDiagram
@@ -300,7 +304,7 @@ sequenceDiagram
     Cache->>Cache: Delete cache entry
 ```
 
-#### آلة الحالة الاحتياطية للحساب
+#### Account Fallback State Machine
 
 ```mermaid
 stateDiagram-v2
@@ -325,7 +329,7 @@ stateDiagram-v2
     }
 ```
 
-#### سلسلة نماذج كومبو
+#### Combo Model Chain
 
 ```mermaid
 flowchart LR
@@ -344,11 +348,11 @@ flowchart LR
 
 ---
 
-### مترجم 4.5 (`open-sse/translator/`)
+### 4.5 Translator (`open-sse/translator/`)
 
-**محرك ترجمة التنسيق** باستخدام نظام إضافي للتسجيل الذاتي.
+The **format translation engine** using a self-registering plugin system.
 
-####الهندسة المعمارية
+#### Architecture
 
 ```mermaid
 graph TD
@@ -374,15 +378,15 @@ graph TD
     end
 ```
 
-| الدليل       | ملفات     | الوصف                                                                                                                                                                                                                                                       |
-| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request/`   | 8 مترجمين | تحويل أجسام الطلب بين الصيغ. يتم تسجيل كل ملف ذاتيًا عبر `register(from, to, fn)` عند الاستيراد.                                                                                                                                                            |
-| `response/`  | 7 مترجمين | تحويل قطع الاستجابة المتدفقة بين الصيغ. يتعامل مع أنواع أحداث SSE وكتل التفكير واستدعاءات الأدوات.                                                                                                                                                          |
-| `helpers/`   | 6 مساعدين | الأدوات المساعدة المشتركة: `claudeHelper` (استخراج موجه النظام، تكوين التفكير)، `geminiHelper` (تعيين الأجزاء/المحتويات)، `openaiHelper` (تصفية التنسيق)، `toolCallHelper` (إنشاء المعرف، حقن الاستجابة المفقودة)، `maxTokensHelper`، `responsesApiHelper`. |
-| `index.ts`   | —         | محرك الترجمة: `translateRequest()`، `translateResponse()`، إدارة الحالة، التسجيل.                                                                                                                                                                           |
-| `formats.ts` | —         | ثوابت التنسيق: `OPENAI`، `CLAUDE`، `GEMINI`، `ANTIGRAVITY`، `KIRO`، `CURSOR`، `OPENAI_RESPONSES`.                                                                                                                                                           |
+| Directory    | Files         | Description                                                                                                                                                                                                                                                      |
+| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request/`   | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import.                                                                                                                                                         |
+| `response/`  | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls.                                                                                                                                                         |
+| `helpers/`   | 6 helpers     | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. |
+| `index.ts`   | —             | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry.                                                                                                                                                                     |
+| `formats.ts` | —             | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`.                                                                                                                                                             |
 
-#### التصميم الرئيسي: المكونات الإضافية للتسجيل الذاتي
+#### Key Design: Self-Registering Plugins
 
 ```javascript
 // Each translator file calls register() on import:
@@ -395,19 +399,19 @@ import "./request/claude-to-openai.js"; // ← self-registers
 
 ---
 
-### 4.6 الأدوات المساعدة (`open-sse/utils/`)
+### 4.6 Utils (`open-sse/utils/`)
 
-| ملف                | الغرض                                                                                                                                                                                                                                                                            |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `error.ts`         | إنشاء استجابة للأخطاء (تنسيق متوافق مع OpenAI)، وتحليل الأخطاء الأولية، واستخراج وقت إعادة محاولة Antigravity من رسائل الخطأ، وتدفق أخطاء SSE.                                                                                                                                   |
-| `stream.ts`        | **SSE Transform Stream** — خط أنابيب البث الأساسي. وضعان: `TRANSLATE` (ترجمة التنسيق الكامل) و`PASSTHROUGH` (تطبيع + استخراج الاستخدام). يتعامل مع التخزين المؤقت للقطعة وتقدير الاستخدام وتتبع طول المحتوى. تتجنب مثيلات وحدة التشفير/وحدة فك التشفير لكل تيار الحالة المشتركة. |
-| `streamHelpers.ts` | أدوات SSE ذات المستوى المنخفض: `parseSSELine` (تتحمل المسافات البيضاء)، `hasValuableContent` (تصفية الأجزاء الفارغة لـ OpenAI/Claude/Gemini)، `fixInvalidId`، `formatSSE` (تسلسل SSE مدرك للتنسيق مع تنظيف `perf_metrics`).                                                      |
-| `usageTracking.ts` | استخراج استخدام الرمز المميز من أي تنسيق (Claude/OpenAI/Gemini/Responses)، والتقدير باستخدام نسب الأحرف لكل رمز مميز للأداة/الرسالة، وإضافة المخزن المؤقت (هامش أمان 2000 رمز مميز)، وتصفية الحقول الخاصة بالتنسيق، وتسجيل وحدة التحكم بألوان ANSI.                              |
-| `requestLogger.ts` | تسجيل الطلب المستند إلى الملف (الاشتراك عبر `ENABLE_REQUEST_LOGS=true`). ينشئ مجلدات الجلسة بملفات مرقمة: `1_req_client.json` → `7_res_client.txt`. كل عمليات الإدخال/الإخراج غير متزامنة (أطلق النار وانسى). أقنعة الرؤوس الحساسة.                                              |
-| `bypassHandler.ts` | يعترض أنماطًا محددة من Claude CLI (استخراج العنوان، والتحمية، والعد) ويعيد استجابات مزيفة دون الاتصال بأي مزود. يدعم كلا من الدفق وغير الدفق. يقتصر عمدا على نطاق كلود CLI.                                                                                                      |
-| `networkProxy.ts`  | يحل عنوان URL للوكيل الصادر لموفر معين مع الأسبقية: التكوين الخاص بالموفر → التكوين العام → متغيرات البيئة (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). يدعم استثناءات `NO_PROXY`. تكوين ذاكرة التخزين المؤقت لمدة 30 ثانية.                                                        |
+| File               | Purpose                                                                                                                                                                                                                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `error.ts`         | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming.                                                                                                                              |
+| `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.                                                              |
+| `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.                                                  |
 
-#### خط أنابيب تدفق SSE
+#### SSE Streaming Pipeline
 
 ```mermaid
 flowchart TD
@@ -429,7 +433,7 @@ flowchart TD
     style M fill:#9f9,stroke:#333
 ```
 
-#### بنية جلسة مسجل الطلب
+#### Request Logger Session Structure
 
 ```
 logs/
@@ -447,109 +451,109 @@ logs/
 
 ---
 
-### 4.7 طبقة التطبيق (`src/`)
+### 4.7 Application Layer (`src/`)
 
-| الدليل        | الغرض                                                                                                   |
-| ------------- | ------------------------------------------------------------------------------------------------------- |
-| `src/app/`    | واجهة مستخدم الويب، مسارات واجهة برمجة التطبيقات (API)، البرامج الوسيطة السريعة، معالجات رد اتصال OAuth |
-| `src/lib/`    | الوصول إلى قاعدة البيانات (`localDb.ts`، `usageDb.ts`)، المصادقة، مشتركة                                |
-| `src/mitm/`   | أدوات مساعدة للوكيل الوسيط لاعتراض حركة مرور الموفر                                                     |
-| `src/models/` | تعريفات نماذج قواعد البيانات                                                                            |
-| `src/shared/` | أغلفة حول وظائف open-sse (المزود، الدفق، الخطأ، إلخ)                                                    |
-| `src/sse/`    | معالجات نقطة نهاية SSE التي تربط مكتبة open-sse بمسارات Express                                         |
-| `src/store/`  | إدارة حالة التطبيق                                                                                      |
+| Directory     | Purpose                                                                |
+| ------------- | ---------------------------------------------------------------------- |
+| `src/app/`    | Web UI, API routes, Express middleware, OAuth callback handlers        |
+| `src/lib/`    | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared   |
+| `src/mitm/`   | Man-in-the-middle proxy utilities for intercepting provider traffic    |
+| `src/models/` | Database model definitions                                             |
+| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.)     |
+| `src/sse/`    | SSE endpoint handlers that wire the open-sse library to Express routes |
+| `src/store/`  | Application state management                                           |
 
-#### مسارات API البارزة
+#### Notable API Routes
 
-| الطريق                                        | طرق                | الغرض                                                                          |
-| --------------------------------------------- | ------------------ | ------------------------------------------------------------------------------ |
-| `/api/provider-models`                        | الحصول على/نشر/حذف | CRUD للنماذج المخصصة لكل مزود                                                  |
-| `/api/models/catalog`                         | احصل على           | كتالوج مجمع لجميع النماذج (الدردشة، التضمين، الصورة، المخصصة) مجمعة حسب الموفر |
-| `/api/settings/proxy`                         | الحصول على/وضع/حذف | تكوين الوكيل الصادر الهرمي (`global/providers/combos/keys`)                    |
-| `/api/settings/proxy/test`                    | مشاركة             | التحقق من صحة اتصال الوكيل وإرجاع IP/زمن الوصول العام                          |
-| `/v1/providers/[provider]/chat/completions`   | مشاركة             | عمليات إكمال الدردشة المخصصة لكل مزود مع التحقق من صحة النموذج                 |
-| `/v1/providers/[provider]/embeddings`         | مشاركة             | عمليات التضمين المخصصة لكل مزود مع التحقق من صحة النموذج                       |
-| `/v1/providers/[provider]/images/generations` | مشاركة             | إنشاء صور مخصصة لكل مزود مع التحقق من صحة النموذج                              |
-| `/api/settings/ip-filter`                     | الحصول على/وضع     | قائمة IP المسموح بها/إدارة القائمة المحظورة                                    |
-| `/api/settings/thinking-budget`               | الحصول على/وضع     | تكوين ميزانية الرمز المميز (العبور/التلقائي/المخصص/التكيفي)                    |
-| `/api/settings/system-prompt`                 | الحصول على/وضع     | الحقن الفوري للنظام العالمي لجميع الطلبات                                      |
-| `/api/sessions`                               | احصل على           | تتبع الجلسة النشطة ومقاييسها                                                   |
-| `/api/rate-limits`                            | احصل على           | حالة حد المعدل لكل حساب                                                        |
+| Route                                         | Methods         | Purpose                                                                               |
+| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
+| `/api/provider-models`                        | GET/POST/DELETE | CRUD for custom models per provider                                                   |
+| `/api/models/catalog`                         | GET             | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider |
+| `/api/settings/proxy`                         | GET/PUT/DELETE  | Hierarchical outbound proxy configuration (`global/providers/combos/keys`)            |
+| `/api/settings/proxy/test`                    | POST            | Validates proxy connectivity and returns public IP/latency                            |
+| `/v1/providers/[provider]/chat/completions`   | POST            | Dedicated per-provider chat completions with model validation                         |
+| `/v1/providers/[provider]/embeddings`         | POST            | Dedicated per-provider embeddings with model validation                               |
+| `/v1/providers/[provider]/images/generations` | POST            | Dedicated per-provider image generation with model validation                         |
+| `/api/settings/ip-filter`                     | GET/PUT         | IP allowlist/blocklist management                                                     |
+| `/api/settings/thinking-budget`               | GET/PUT         | Reasoning token budget configuration (passthrough/auto/custom/adaptive)               |
+| `/api/settings/system-prompt`                 | GET/PUT         | Global system prompt injection for all requests                                       |
+| `/api/sessions`                               | GET             | Active session tracking and metrics                                                   |
+| `/api/rate-limits`                            | GET             | Per-account rate limit status                                                         |
 
 ---
 
-## 5. أنماط التصميم الرئيسية
+## 5. Key Design Patterns
 
-### 5.1 الترجمة المحورية والمتحدثة
+### 5.1 Hub-and-Spoke Translation
 
-تتم ترجمة جميع التنسيقات من خلال **تنسيق OpenAI كمحور**. لا تتطلب إضافة موفر جديد سوى كتابة **زوج واحد** من المترجمين (من/إلى OpenAI)، وليس عدد N من المترجمين.
+All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs.
 
-### 5.2 نمط استراتيجية المنفذ
+### 5.2 Executor Strategy Pattern
 
-كل مزود لديه فئة منفذة مخصصة ترث من `BaseExecutor`. يقوم المصنع في `executors/index.ts` باختيار المصنع المناسب في وقت التشغيل.
+Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime.
 
-### 5.3 نظام البرنامج المساعد للتسجيل الذاتي
+### 5.3 Self-Registering Plugin System
 
-تسجل وحدات المترجم نفسها عند الاستيراد عبر `register()`. إن إضافة مترجم جديد يعني مجرد إنشاء ملف واستيراده.
+Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it.
 
-### 5.4 التراجع في الحساب مع التراجع الأسي
+### 5.4 Account Fallback with Exponential Backoff
 
-عندما يقوم مقدم الخدمة بإرجاع 429/401/500، يمكن للنظام التبديل إلى الحساب التالي، مع تطبيق فترات التباطؤ الأسية (1ث → 2ث → 4ث → 2 دقيقة كحد أقصى).
+When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min).
 
-### 5.5 سلاسل نماذج كومبو
+### 5.5 Combo Model Chains
 
-يقوم "التحرير والسرد" بتجميع سلاسل `provider/model` متعددة. إذا فشل الأول، يتم الرجوع إلى التالي تلقائيًا.
+A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically.
 
-### 5.6 ترجمة متدفقة رائعة
+### 5.6 Stateful Streaming Translation
 
-تحافظ ترجمة الاستجابة على الحالة عبر أجزاء SSE (تتبع كتلة التفكير، وتراكم استدعاءات الأداة، وفهرسة كتلة المحتوى) عبر آلية `initState()`.
+Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism.
 
-### 5.7 المخزن المؤقت لسلامة الاستخدام
+### 5.7 Usage Safety Buffer
 
-تتم إضافة مخزن مؤقت مكون من 2000 رمز مميز إلى الاستخدام المبلغ عنه لمنع العملاء من الوصول إلى حدود نافذة السياق بسبب الحمل الزائد من مطالبات النظام وترجمة التنسيق.
+A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation.
 
 ---
 
-## 6. التنسيقات المدعومة
+## 6. Supported Formats
 
-| تنسيق                               | الاتجاه        | المعرف             |
-| ----------------------------------- | -------------- | ------------------ |
-| استكمالات الدردشة OpenAI            | المصدر + الهدف | `openai`           |
-| واجهة برمجة تطبيقات استجابات OpenAI | المصدر + الهدف | `openai-responses` |
-| أنثروبي كلود                        | المصدر + الهدف | `claude`           |
-| جوجل الجوزاء                        | المصدر + الهدف | `gemini`           |
-| جوجل الجوزاء CLI                    | الهدف فقط      | `gemini-cli`       |
-| مكافحة الجاذبية                     | المصدر + الهدف | `antigravity`      |
-| أوس كيرو                            | الهدف فقط      | `kiro`             |
-| المؤشر                              | الهدف فقط      | `cursor`           |
+| Format                  | Direction       | Identifier         |
+| ----------------------- | --------------- | ------------------ |
+| OpenAI Chat Completions | source + target | `openai`           |
+| OpenAI Responses API    | source + target | `openai-responses` |
+| Anthropic Claude        | source + target | `claude`           |
+| Google Gemini           | source + target | `gemini`           |
+| Google Gemini CLI       | target only     | `gemini-cli`       |
+| Antigravity             | source + target | `antigravity`      |
+| AWS Kiro                | target only     | `kiro`             |
+| Cursor                  | target only     | `cursor`           |
 
 ---
 
-## 7. مقدمو الخدمة المدعومين
+## 7. Supported Providers
 
-| مقدم                      | طريقة المصادقة           | المنفذ          | الملاحظات الرئيسية                                        |
-| ------------------------- | ------------------------ | --------------- | --------------------------------------------------------- |
-| أنثروبي كلود              | مفتاح API أو OAuth       | الافتراضي       | يستخدم رأس `x-api-key`                                    |
-| جوجل الجوزاء              | مفتاح API أو OAuth       | الافتراضي       | يستخدم رأس `x-goog-api-key`                               |
-| جوجل الجوزاء CLI          | أووث                     | الجوزاء كلي     | يستخدم `streamGenerateContent` نقطة النهاية               |
-| مكافحة الجاذبية           | أووث                     | مكافحة الجاذبية | احتياطي عناوين URL المتعددة، إعادة محاولة التحليل المخصصة |
-| أوبن آي                   | مفتاح API                | الافتراضي       | مصادقة حامل المعيار                                       |
-| الدستور الغذائي           | أووث                     | الدستور الغذائي | يدخل تعليمات النظام ويدير التفكير                         |
-| جيثب مساعد الطيار         | OAuth + رمز مساعد الطيار | جيثب            | رمز مزدوج، محاكاة رأس VSCode                              |
-| كيرو (AWS)                | AWS SSO OIDC أو Social   | كيرو            | تحليل دفق الأحداث الثنائية                                |
-| بيئة تطوير متكاملة للمؤشر | مصادقة المجموع الاختباري | المؤشر          | ترميز Protobuf، المجموع الاختباري SHA-256                 |
-| كوين                      | أووث                     | الافتراضي       | المصادقة القياسية                                         |
-| اي فلو                    | OAuth (أساسي + حامل)     | الافتراضي       | رأس المصادقة المزدوجة                                     |
-| اوبن راوتر                | مفتاح API                | الافتراضي       | مصادقة حامل المعيار                                       |
-| جي إل إم، كيمي، ميني ماكس | مفتاح API                | الافتراضي       | متوافق مع كلود، استخدم `x-api-key`                        |
-| `openai-compatible-*`     | مفتاح API                | الافتراضي       | ديناميكي: أي نقطة نهاية متوافقة مع OpenAI                 |
-| `anthropic-compatible-*`  | مفتاح API                | الافتراضي       | ديناميكي: أي نقطة نهاية متوافقة مع كلود                   |
+| Provider                 | Auth Method            | Executor    | Key Notes                                     |
+| ------------------------ | ---------------------- | ----------- | --------------------------------------------- |
+| Anthropic Claude         | API key or OAuth       | Default     | Uses `x-api-key` header                       |
+| Google Gemini            | API key or OAuth       | Default     | Uses `x-goog-api-key` header                  |
+| Google Gemini CLI        | OAuth                  | GeminiCLI   | Uses `streamGenerateContent` endpoint         |
+| Antigravity              | OAuth                  | Antigravity | Multi-URL fallback, custom retry parsing      |
+| OpenAI                   | API key                | Default     | Standard Bearer auth                          |
+| Codex                    | OAuth                  | Codex       | Injects system instructions, manages thinking |
+| GitHub Copilot           | OAuth + Copilot token  | Github      | Dual token, VSCode header mimicking           |
+| 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                              |
+| 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       |
+| `anthropic-compatible-*` | API key                | Default     | Dynamic: any Claude-compatible endpoint       |
 
 ---
 
-## 8. ملخص تدفق البيانات
+## 8. Data Flow Summary
 
-### طلب البث
+### Streaming Request
 
 ```mermaid
 flowchart LR
@@ -566,7 +570,7 @@ flowchart LR
     K --> L["logUsage()\nsaveRequestUsage()"]
 ```
 
-### طلب عدم البث
+### Non-Streaming Request
 
 ```mermaid
 flowchart LR
@@ -577,7 +581,7 @@ flowchart LR
     E --> F["Return JSON\nresponse"]
 ```
 
-### تجاوز التدفق (كلود CLI)
+### Bypass Flow (Claude CLI)
 
 ```mermaid
 flowchart LR

docs/i18n/ar/FEATURES.md

@@ -1,77 +1,148 @@
-# OmniRoute — معرض ميزات لوحة المعلومات
-
-🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md)
-
-دليل مرئي لكل قسم من لوحة معلومات OmniRoute.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/FEATURES.md) · 🇪🇸 [es](../es/FEATURES.md) · 🇫🇷 [fr](../fr/FEATURES.md) · 🇩🇪 [de](../de/FEATURES.md) · 🇮🇹 [it](../it/FEATURES.md) · 🇷🇺 [ru](../ru/FEATURES.md) · 🇨🇳 [zh-CN](../zh-CN/FEATURES.md) · 🇯🇵 [ja](../ja/FEATURES.md) · 🇰🇷 [ko](../ko/FEATURES.md) · 🇸🇦 [ar](../ar/FEATURES.md) · 🇮🇳 [in](../in/FEATURES.md) · 🇹🇭 [th](../th/FEATURES.md) · 🇻🇳 [vi](../vi/FEATURES.md) · 🇮🇩 [id](../id/FEATURES.md) · 🇲🇾 [ms](../ms/FEATURES.md) · 🇳🇱 [nl](../nl/FEATURES.md) · 🇵🇱 [pl](../pl/FEATURES.md) · 🇸🇪 [sv](../sv/FEATURES.md) · 🇳🇴 [no](../no/FEATURES.md) · 🇩🇰 [da](../da/FEATURES.md) · 🇫🇮 [fi](../fi/FEATURES.md) · 🇵🇹 [pt](../pt/FEATURES.md) · 🇷🇴 [ro](../ro/FEATURES.md) · 🇭🇺 [hu](../hu/FEATURES.md) · 🇧🇬 [bg](../bg/FEATURES.md) · 🇸🇰 [sk](../sk/FEATURES.md) · 🇺🇦 [uk-UA](../uk-UA/FEATURES.md) · 🇮🇱 [he](../he/FEATURES.md) · 🇵🇭 [phi](../phi/FEATURES.md)
 
 ---
 
-## 🔌 مقدمو الخدمة
+# OmniRoute — Dashboard Features Gallery
 
-إدارة اتصالات مزودي الذكاء الاصطناعي: موفري OAuth (Claude Code وCodex وGemini CLI) وموفري مفاتيح API (Groq وDeepSeek وOpenRouter) ومقدمي الخدمات المجانية (iFlow وQwen وKiro).
+🌐 **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)
+
+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).
+
+- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` (free "Light usage" tier); use `ollamacloud/<model>` prefix
 
 ![Providers Dashboard](screenshots/01-providers.png)
 
 ---
 
-## 🎨 المجموعات
+## 🎨 Combos
 
-أنشئ مجموعات توجيه النماذج باستخدام 6 إستراتيجيات: التعبئة أولاً، والتدوير الدائري، وقوة الاختيارين، والعشوائية، والأقل استخدامًا، والمُحسَّنة من حيث التكلفة. تقوم كل مجموعة بتسلسل نماذج متعددة مع الرجوع التلقائي.
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
 
 ![Combos Dashboard](screenshots/02-combos.png)
 
 ---
 
-## 📊تحليلات
+## 📊 Analytics
 
-تحليلات استخدام شاملة مع استهلاك الرمز المميز، وتقديرات التكلفة، وخرائط النشاط، ومخططات التوزيع الأسبوعية، والتفاصيل لكل مزود.
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
 
 ![Analytics Dashboard](screenshots/03-analytics.png)
 
 ---
 
-## 🏥 صحة النظام
+## 🏥 System Health
 
-المراقبة في الوقت الفعلي: وقت التشغيل، والذاكرة، والإصدار، والنسب المئوية لزمن الوصول (p50/p95/p99)، وإحصائيات ذاكرة التخزين المؤقت، وحالات قاطع دائرة الموفر.
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
 
 ![Health Dashboard](screenshots/04-health.png)
 
 ---
 
-## 🔧 ملعب المترجم
+## 🔧 Translator Playground
 
-أربعة أوضاع لتصحيح أخطاء ترجمات واجهة برمجة التطبيقات: **ساحة اللعب** (محول التنسيق)، **اختبار الدردشة** (الطلبات المباشرة)، **منصة الاختبار** (اختبارات الدفعة)، و **المراقب المباشر** (البث في الوقت الفعلي).
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
 
 ![Translator Playground](screenshots/05-translator.png)
 
 ---
 
-## ⚙️ الإعدادات
+## 🎮 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
+
+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
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
 
 ![Settings Dashboard](screenshots/06-settings.png)
 
 ---
 
-## 🔧 أدوات CLI
+## 🔧 CLI Tools
 
-تكوين بنقرة واحدة لأدوات ترميز الذكاء الاصطناعي: Claude Code، وCodex CLI، وGemini CLI، وOpenClaw، وKilo Code، و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
+
+---
+
+## 🖼️ 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.
 
 ![Usage Logs](screenshots/08-usage.png)
 
 ---
 
-## 🌐 نقطة نهاية API
+## 🌐 API Endpoint
 
-نقطة نهاية واجهة برمجة التطبيقات الموحدة الخاصة بك مع تفاصيل الإمكانات: عمليات إكمال الدردشة والتضمين وإنشاء الصور وإعادة الترتيب والنسخ الصوتي ومفاتيح واجهة برمجة التطبيقات المسجلة.
+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. 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)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/ar/MCP-SERVER.md

@@ -0,0 +1,87 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/MCP-SERVER.md) · 🇪🇸 [es](../es/MCP-SERVER.md) · 🇫🇷 [fr](../fr/MCP-SERVER.md) · 🇩🇪 [de](../de/MCP-SERVER.md) · 🇮🇹 [it](../it/MCP-SERVER.md) · 🇷🇺 [ru](../ru/MCP-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/MCP-SERVER.md) · 🇯🇵 [ja](../ja/MCP-SERVER.md) · 🇰🇷 [ko](../ko/MCP-SERVER.md) · 🇸🇦 [ar](../ar/MCP-SERVER.md) · 🇮🇳 [in](../in/MCP-SERVER.md) · 🇹🇭 [th](../th/MCP-SERVER.md) · 🇻🇳 [vi](../vi/MCP-SERVER.md) · 🇮🇩 [id](../id/MCP-SERVER.md) · 🇲🇾 [ms](../ms/MCP-SERVER.md) · 🇳🇱 [nl](../nl/MCP-SERVER.md) · 🇵🇱 [pl](../pl/MCP-SERVER.md) · 🇸🇪 [sv](../sv/MCP-SERVER.md) · 🇳🇴 [no](../no/MCP-SERVER.md) · 🇩🇰 [da](../da/MCP-SERVER.md) · 🇫🇮 [fi](../fi/MCP-SERVER.md) · 🇵🇹 [pt](../pt/MCP-SERVER.md) · 🇷🇴 [ro](../ro/MCP-SERVER.md) · 🇭🇺 [hu](../hu/MCP-SERVER.md) · 🇧🇬 [bg](../bg/MCP-SERVER.md) · 🇸🇰 [sk](../sk/MCP-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/MCP-SERVER.md) · 🇮🇱 [he](../he/MCP-SERVER.md) · 🇵🇭 [phi](../phi/MCP-SERVER.md)
+
+---
+
+# 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                 |
+| `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/i18n/ar/README.md

@@ -20,7 +20,7 @@ _وكيل API العالمي الخاص بك - نقطة نهاية واحدة،
 
 </div>
 
-🌐 **متوفر باللغة:** 🇺🇸 [الإنجليزية](README.md) | 🇧🇷 [البرتغالية (البرازيل)](README.pt-BR.md) | 🇪🇸 [الإسبانية](README.es.md) | 🇫🇷 [Français](README.fr.md) | 🇮🇹 [الإيطالية](README.it.md) | 🇷🇺 [Русский](README.ru.md) | 🇨🇳 [中文 (简体)](README.zh-CN.md) | 🇩🇪 [الألمانية](README.de.md) | 🇮🇳 [هندي](README.in.md) | 🇹🇭 [ไทย](README.th.md) | 🇺🇦 [أوكرانيا](README.uk-UA.md) | 🇸🇦 [العربية](README.ar.md) | 🇯🇵 [日本語](README.ja.md) | 🇻🇳 [تيانج فيت](README.vi.md) | 🇧🇬 [بلغارسكي](README.bg.md) | 🇩🇰 [الدانسك](README.da.md) | 🇫🇮 [سومي](README.fi.md) | 🇮🇱 [العربية](README.he.md) | 🇭🇺 [المجرية](README.hu.md) | 🇮🇩 [البهاسا الإندونيسية](README.id.md) | 🇰🇷 [한국어](README.ko.md) | 🇲🇾 [البهاسا ملايو](README.ms.md) | 🇳🇱 [هولندا](README.nl.md) | 🇳🇴 [نورسك](README.no.md) | 🇵🇹 [البرتغالية (البرتغال)](README.pt.md) | 🇷🇴 [روماني](README.ro.md) | 🇵🇱 [بولسكي](README.pl.md) | 🇸🇰 [سلوفينسينا](README.sk.md) | 🇸🇪 [سفينسكا](README.sv.md) | 🇵🇭 [فلبينية](README.phi.md)
+🌐 **متوفر باللغة:** 🇺🇸 [الإنجليزية](../../README.md) | 🇧🇷 [البرتغالية (البرازيل)](../pt-BR/README.md) | 🇪🇸 [الإسبانية](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [الإيطالية](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [الألمانية](../de/README.md) | 🇮🇳 [هندي](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [أوكرانيا](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [تيانج فيت](../vi/README.md) | 🇧🇬 [بلغارسكي](../bg/README.md) | 🇩🇰 [الدانسك](../da/README.md) | 🇫🇮 [سومي](../fi/README.md) | 🇮🇱 [العربية](../he/README.md) | 🇭🇺 [المجرية](../hu/README.md) | 🇮🇩 [البهاسا الإندونيسية](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [البهاسا ملايو](../ms/README.md) | 🇳🇱 [هولندا](../nl/README.md) | 🇳🇴 [نورسك](../no/README.md) | 🇵🇹 [البرتغالية (البرتغال)](../pt/README.md) | 🇷🇴 [روماني](../ro/README.md) | 🇵🇱 [بولسكي](../pl/README.md) | 🇸🇰 [سلوفينسينا](../sk/README.md) | 🇸🇪 [سفينسكا](../sv/README.md) | 🇵🇭 [فلبينية](../phi/README.md)
 
 ---
 
@@ -53,6 +53,18 @@ _وكيل API العالمي الخاص بك - نقطة نهاية واحدة،
 
 ---
 
+### 🚀 New in v2.0.9+ — Playground, CLI Fingerprints & ACP
+
+| Feature                                    | What It Does                                                                                                                                  |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🎮 **Model Playground**                    | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing                        |
+| 🔏 **CLI Fingerprint Matching**            | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |
+| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw), process spawner, `/api/acp/agents` endpoint                                 |
+| 🤖 **ACP Agents Dashboard**                | Debug > Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool                                      |
+| 🔧 **Custom Model `apiFormat` Routing**    | Custom models with `apiFormat: "responses"` now correctly route to the Responses API translator                                               |
+| 🏢 **Codex Workspace Isolation**           | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID                                                   |
+| 🔄 **Electron Auto-Update**                | Desktop app checks for updates + auto-install on restart                                                                                      |
+
 ### 🤖 موفر الذكاء الاصطناعي المجاني لوكلاء البرمجة المفضلين لديك
 
 _قم بتوصيل أي أداة IDE أو CLI مدعومة بالذكاء الاصطناعي من خلال OmniRoute - بوابة واجهة برمجة التطبيقات المجانية للترميز غير المحدود._
@@ -253,6 +265,7 @@ Result: Never stop coding, minimal cost
 **كيف يحل OmniRoute المشكلة:**
 
 - **موفرو الطبقة المجانية المضمنون** — دعم أصلي لمقدمي الخدمات المجانيين بنسبة 100%: iFlow (8 نماذج غير محدودة)، Qwen (3 نماذج غير محدودة)، Kiro (Claude مجانًا)، Gemini CLI (180 ألف/شهر مجانًا)
+- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/<model>` prefix
 - **المجموعات المجانية فقط** — السلسلة `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 USD/الشهر بدون أي توقف عن العمل
 - **أرصدة NVIDIA NIM المجانية** — 1000 رصيد مجاني مدمج
 - **استراتيجية التكلفة المحسنة** — استراتيجية التوجيه التي تختار تلقائيًا أرخص مزود متاح

docs/i18n/ar/RELEASE_CHECKLIST.md

@@ -0,0 +1,37 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) · 🇪🇸 [es](../es/RELEASE_CHECKLIST.md) · 🇫🇷 [fr](../fr/RELEASE_CHECKLIST.md) · 🇩🇪 [de](../de/RELEASE_CHECKLIST.md) · 🇮🇹 [it](../it/RELEASE_CHECKLIST.md) · 🇷🇺 [ru](../ru/RELEASE_CHECKLIST.md) · 🇨🇳 [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) · 🇯🇵 [ja](../ja/RELEASE_CHECKLIST.md) · 🇰🇷 [ko](../ko/RELEASE_CHECKLIST.md) · 🇸🇦 [ar](../ar/RELEASE_CHECKLIST.md) · 🇮🇳 [in](../in/RELEASE_CHECKLIST.md) · 🇹🇭 [th](../th/RELEASE_CHECKLIST.md) · 🇻🇳 [vi](../vi/RELEASE_CHECKLIST.md) · 🇮🇩 [id](../id/RELEASE_CHECKLIST.md) · 🇲🇾 [ms](../ms/RELEASE_CHECKLIST.md) · 🇳🇱 [nl](../nl/RELEASE_CHECKLIST.md) · 🇵🇱 [pl](../pl/RELEASE_CHECKLIST.md) · 🇸🇪 [sv](../sv/RELEASE_CHECKLIST.md) · 🇳🇴 [no](../no/RELEASE_CHECKLIST.md) · 🇩🇰 [da](../da/RELEASE_CHECKLIST.md) · 🇫🇮 [fi](../fi/RELEASE_CHECKLIST.md) · 🇵🇹 [pt](../pt/RELEASE_CHECKLIST.md) · 🇷🇴 [ro](../ro/RELEASE_CHECKLIST.md) · 🇭🇺 [hu](../hu/RELEASE_CHECKLIST.md) · 🇧🇬 [bg](../bg/RELEASE_CHECKLIST.md) · 🇸🇰 [sk](../sk/RELEASE_CHECKLIST.md) · 🇺🇦 [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) · 🇮🇱 [he](../he/RELEASE_CHECKLIST.md) · 🇵🇭 [phi](../phi/RELEASE_CHECKLIST.md)
+
+---
+
+# 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/i18n/ar/TROUBLESHOOTING.md

@@ -1,87 +1,91 @@
-# استكشاف الأخطاء وإصلاحها
-
-🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md)
-
-المشاكل والحلول الشائعة لـ OmniRoute.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/TROUBLESHOOTING.md) · 🇪🇸 [es](../es/TROUBLESHOOTING.md) · 🇫🇷 [fr](../fr/TROUBLESHOOTING.md) · 🇩🇪 [de](../de/TROUBLESHOOTING.md) · 🇮🇹 [it](../it/TROUBLESHOOTING.md) · 🇷🇺 [ru](../ru/TROUBLESHOOTING.md) · 🇨🇳 [zh-CN](../zh-CN/TROUBLESHOOTING.md) · 🇯🇵 [ja](../ja/TROUBLESHOOTING.md) · 🇰🇷 [ko](../ko/TROUBLESHOOTING.md) · 🇸🇦 [ar](../ar/TROUBLESHOOTING.md) · 🇮🇳 [in](../in/TROUBLESHOOTING.md) · 🇹🇭 [th](../th/TROUBLESHOOTING.md) · 🇻🇳 [vi](../vi/TROUBLESHOOTING.md) · 🇮🇩 [id](../id/TROUBLESHOOTING.md) · 🇲🇾 [ms](../ms/TROUBLESHOOTING.md) · 🇳🇱 [nl](../nl/TROUBLESHOOTING.md) · 🇵🇱 [pl](../pl/TROUBLESHOOTING.md) · 🇸🇪 [sv](../sv/TROUBLESHOOTING.md) · 🇳🇴 [no](../no/TROUBLESHOOTING.md) · 🇩🇰 [da](../da/TROUBLESHOOTING.md) · 🇫🇮 [fi](../fi/TROUBLESHOOTING.md) · 🇵🇹 [pt](../pt/TROUBLESHOOTING.md) · 🇷🇴 [ro](../ro/TROUBLESHOOTING.md) · 🇭🇺 [hu](../hu/TROUBLESHOOTING.md) · 🇧🇬 [bg](../bg/TROUBLESHOOTING.md) · 🇸🇰 [sk](../sk/TROUBLESHOOTING.md) · 🇺🇦 [uk-UA](../uk-UA/TROUBLESHOOTING.md) · 🇮🇱 [he](../he/TROUBLESHOOTING.md) · 🇵🇭 [phi](../phi/TROUBLESHOOTING.md)
 
 ---
 
-## إصلاحات سريعة
+# Troubleshooting
 
-| مشكلة                             | الحل                                                              |
-| --------------------------------- | ----------------------------------------------------------------- |
-| تسجيل الدخول الأول لا يعمل        | تحقق من `INITIAL_PASSWORD` في `.env` (الافتراضي: `123456`)        |
-| تفتح لوحة المعلومات على منفذ خاطئ | اضبط `PORT=20128` و`NEXT_PUBLIC_BASE_URL=http://localhost:20128`  |
-| لا توجد سجلات للطلب ضمن `logs/`   | تعيين `ENABLE_REQUEST_LOGS=true`                                  |
-| EACCES: تم رفض الإذن              | اضبط `DATA_DIR=/path/to/writable/dir` لتجاوز `~/.omniroute`       |
-| استراتيجية التوجيه لا تنقذ        | التحديث إلى الإصدار 1.4.11+ (إصلاح مخطط Zod لاستمرارية الإعدادات) |
+🌐 **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)
+
+Common problems and solutions for OmniRoute.
 
 ---
 
-## مشكلات المزود
+## Quick Fixes
 
-### "نموذج اللغة لم يقدم رسائل"
-
-**السبب:** استنفدت حصة الموفر.
-
-**الإصلاح:**
-
-1. تحقق من تعقب الحصص في لوحة القيادة
-2. استخدم مجموعة من المستويات الاحتياطية
-3. قم بالتبديل إلى الطبقة الأرخص/المجانية
-
-### تحديد المعدل
-
-**السبب:** استنفدت حصة الاشتراك.
-
-**الإصلاح:**
-
-- إضافة احتياطي: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-- استخدم GLM/MiniMax كنسخة احتياطية رخيصة الثمن
-
-### انتهت صلاحية رمز OAuth
-
-يقوم OmniRoute بتحديث الرموز المميزة تلقائيًا. إذا استمرت المشكلات:
-
-1. لوحة المعلومات → الموفر → إعادة الاتصال
-2. قم بحذف وإعادة إضافة اتصال الموفر
+| 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 request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true`                                     |
+| 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)       |
 
 ---
 
-## مشكلات السحابة
+## Provider Issues
 
-### أخطاء المزامنة السحابية
+### "Language model did not provide messages"
 
-1. تحقق من نقاط `BASE_URL` لمثيلك قيد التشغيل (على سبيل المثال، `http://localhost:20128`)
-2. تحقق من نقاط `CLOUD_URL` إلى نقطة نهاية السحابة الخاصة بك (على سبيل المثال، `https://omniroute.dev`)
-3. حافظ على محاذاة قيم `NEXT_PUBLIC_*` مع القيم من جانب الخادم
+**Cause:** Provider quota exhausted.
 
-### السحابة `stream=false` تُرجع 500
+**Fix:**
 
-**العَرَض:** `Unexpected token 'd'...` على نقطة نهاية السحابة للمكالمات غير المتدفقة.
+1. Check dashboard quota tracker
+2. Use a combo with fallback tiers
+3. Switch to cheaper/free tier
 
-**السبب:** يقوم المنبع بإرجاع حمولة SSE بينما يتوقع العميل JSON.
+### Rate Limiting
 
-**الحل البديل:** استخدم `stream=true` للمكالمات السحابية المباشرة. يتضمن وقت التشغيل المحلي SSE → JSON الاحتياطي.
+**Cause:** Subscription quota exhausted.
 
-### تقول السحابة إنها متصلة ولكن "مفتاح واجهة برمجة التطبيقات غير صالح"
+**Fix:**
 
-1. قم بإنشاء مفتاح جديد من لوحة المعلومات المحلية (`/api/keys`)
-2. قم بتشغيل المزامنة السحابية: قم بتمكين السحابة → المزامنة الآن
-3. لا يزال بإمكان المفاتيح القديمة/غير المتزامنة إرجاع `401` على السحابة
+- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Use GLM/MiniMax as cheap backup
+
+### OAuth Token Expired
+
+OmniRoute auto-refreshes tokens. If issues persist:
+
+1. Dashboard → Provider → Reconnect
+2. Delete and re-add the provider connection
 
 ---
 
-## مشكلات عامل الميناء
+## Cloud Issues
 
-### تظهر أداة CLI غير مثبتة
+### Cloud Sync Errors
 
-1. تحقق من حقول وقت التشغيل: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
-2. بالنسبة للوضع المحمول: استخدم هدف الصورة `runner-cli` (CLIs المجمعة)
-3. بالنسبة لوضع تثبيت المضيف: قم بتعيين `CLI_EXTRA_PATHS` وتثبيت دليل حاوية المضيف للقراءة فقط
-4. إذا تم العثور على `installed=true` و`runnable=false`: ثنائي ولكن فشل التحقق من الصحة
+1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
+2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
+3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
 
-### التحقق السريع من وقت التشغيل
+### Cloud `stream=false` Returns 500
+
+**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
+
+**Cause:** Upstream returns SSE payload while client expects JSON.
+
+**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
+
+### Cloud Says Connected but "Invalid API key"
+
+1. Create a fresh key from local dashboard (`/api/keys`)
+2. Run cloud sync: Enable Cloud → Sync Now
+3. Old/non-synced keys can still return `401` on cloud
+
+---
+
+## Docker Issues
+
+### CLI Tool Shows Not Installed
+
+1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. For portable mode: use image target `runner-cli` (bundled CLIs)
+3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
+4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
+
+### Quick Runtime Validation
 
 ```bash
 curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
@@ -91,24 +95,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
 
 ---
 
-## قضايا التكلفة
+## Cost Issues
 
-### ارتفاع التكاليف
+### High Costs
 
-1. تحقق من إحصائيات الاستخدام في لوحة المعلومات → الاستخدام
-2. قم بتبديل النموذج الأساسي إلى GLM/MiniMax
-3. استخدم الطبقة المجانية (Gemini CLI، iFlow) للمهام غير الحرجة
-4. قم بتعيين ميزانيات التكلفة لكل مفتاح واجهة برمجة التطبيقات: لوحة المعلومات ← مفاتيح واجهة برمجة التطبيقات ← الميزانية
+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
+4. Set cost budgets per API key: Dashboard → API Keys → Budget
 
 ---
 
-## التصحيح
+## Debugging
 
-### تمكين سجلات الطلبات
+### Enable Request Logs
 
-قم بتعيين `ENABLE_REQUEST_LOGS=true` في ملف `.env` الخاص بك. تظهر السجلات ضمن الدليل `logs/`.
+Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory.
 
-### التحقق من صحة مقدم الخدمة
+### Check Provider Health
 
 ```bash
 # Health dashboard
@@ -118,102 +122,137 @@ http://localhost:20128/dashboard/health
 curl http://localhost:20128/api/monitoring/health
 ```
 
-### تخزين وقت التشغيل
+### Runtime Storage
 
-- الحالة الرئيسية: `${DATA_DIR}/db.json` (المزودون، المجموعات، الأسماء المستعارة، المفاتيح، الإعدادات)
-- الاستخدام: `${DATA_DIR}/usage.json`، `${DATA_DIR}/log.txt`، `${DATA_DIR}/call_logs/`
-- سجلات الطلب: `<repo>/logs/...` (عندما `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}/log.txt` and `${DATA_DIR}/call_logs/`
+- Request logs: `<repo>/logs/...` (when `ENABLE_REQUEST_LOGS=true`)
 
 ---
 
-## مشكلات قواطع الدائرة
+## Circuit Breaker Issues
 
-### الموفر عالق في الحالة المفتوحة
+### Provider stuck in OPEN state
 
-عندما يكون قاطع دائرة الموفر مفتوحًا، يتم حظر الطلبات حتى تنتهي فترة التهدئة.
+When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
 
-**الإصلاح:**
+**Fix:**
 
-1. انتقل إلى **لوحة التحكم ← الإعدادات ← المرونة**
-2. تحقق من بطاقة قاطع الدائرة الكهربائية الخاصة بالمزود المتأثر
-3. انقر فوق **إعادة تعيين الكل** لمسح جميع القواطع، أو انتظر حتى تنتهي فترة التهدئة
-4. تحقق من أن الموفر متاح فعليًا قبل إعادة التعيين
+1. Go to **Dashboard → Settings → Resilience**
+2. Check the circuit breaker card for the affected provider
+3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
+4. Verify the provider is actually available before resetting
 
-### يستمر المزود في تعطيل قاطع الدائرة
+### Provider keeps tripping the circuit breaker
 
-إذا دخل مقدم الخدمة بشكل متكرر في الحالة المفتوحة:
+If a provider repeatedly enters OPEN state:
 
-1. تحقق من **Dashboard → Health → Provider Health** لمعرفة نمط الفشل
-2. انتقل إلى **الإعدادات → المرونة → ملفات تعريف الموفر** وقم بزيادة حد الفشل
-3. تحقق مما إذا كان الموفر قد قام بتغيير حدود واجهة برمجة التطبيقات (API) أو طلب إعادة المصادقة
-4. قم بمراجعة القياس عن بعد لزمن الاستجابة - قد يتسبب زمن الاستجابة العالي في حدوث أعطال بسبب انتهاء المهلة
+1. Check **Dashboard → Health → Provider Health** for the failure pattern
+2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
+3. Check if the provider has changed API limits or requires re-authentication
+4. Review latency telemetry — high latency may cause timeout-based failures
 
 ---
 
-## مشكلات النسخ الصوتي
+## Audio Transcription Issues
 
-### خطأ "نموذج غير مدعوم".
+### "Unsupported model" error
 
-- تأكد من أنك تستخدم البادئة الصحيحة: `deepgram/nova-3` أو `assemblyai/best`
-- تحقق من أن الموفر متصل في **لوحة التحكم ← الموفرون**
+- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
+- Verify the provider is connected in **Dashboard → Providers**
 
-### يعود النسخ فارغًا أو يفشل
+### Transcription returns empty or fails
 
-- تحقق من تنسيقات الصوت المدعومة: `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`
-- التحقق من أن حجم الملف يقع ضمن حدود الموفر (عادةً أقل من 25 ميجابايت)
-- التحقق من صلاحية مفتاح API الخاص بالموفر في بطاقة المزود
+- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Verify file size is within provider limits (typically < 25MB)
+- Check provider API key validity in the provider card
 
 ---
 
-## تصحيح أخطاء المترجم
+## Translator Debugging
 
-استخدم **لوحة المعلومات → المترجم** لتصحيح مشكلات ترجمة التنسيق:
+Use **Dashboard → Translator** to debug format translation issues:
 
-| الوضع                | متى تستخدم                                                                         |
-| -------------------- | ---------------------------------------------------------------------------------- |
-| **ساحة اللعب**       | قارن تنسيقات الإدخال/الإخراج جنبًا إلى جنب — الصق طلبًا فاشلاً لترى كيف تتم ترجمته |
-| ** اختبار الدردشة ** | أرسل رسائل مباشرة وافحص حمولة الطلب/الاستجابة الكاملة بما في ذلك الرؤوس            |
-| ** مقعد الاختبار **  | قم بإجراء اختبارات مجمعة عبر مجموعات التنسيق للعثور على الترجمات المعطلة           |
-| **مراقبة حية**       | شاهد تدفق الطلبات في الوقت الفعلي للتعرف على مشكلات الترجمة المتقطعة               |
+| Mode             | When to Use                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| **Playground**   | Compare input/output formats side by side — paste a failing request to see how it translates |
+| **Chat Tester**  | Send live messages and inspect the full request/response payload including headers           |
+| **Test Bench**   | Run batch tests across format combinations to find which translations are broken             |
+| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues                        |
 
-### مشكلات التنسيق الشائعة
+### Common format issues
 
-- **لا تظهر علامات التفكير** — تحقق مما إذا كان الموفر المستهدف يدعم التفكير وإعداد ميزانية التفكير
-- **استدعاءات الأداة** — قد تؤدي بعض ترجمات التنسيق إلى إزالة الحقول غير المدعومة؛ تحقق في وضع الملعب
-- **مطالبة النظام مفقودة** — يتعامل نظام Claude وGemini مع المطالبات بشكل مختلف؛ التحقق من إخراج الترجمة
-- ** تقوم SDK بإرجاع سلسلة أولية بدلاً من الكائن ** - تم الإصلاح في الإصدار 1.1.0: تقوم أداة معالجة الاستجابة الآن بإزالة الحقول غير القياسية (`x_groq`، `usage_breakdown`، وما إلى ذلك) التي تتسبب في فشل التحقق من صحة OpenAI SDK Pydantic
-- **GLM/ERNIE يرفض دور `system`** — تم إصلاحه في الإصدار 1.1.0: يقوم مُطبيع الدور تلقائيًا بدمج رسائل النظام في رسائل المستخدم للنماذج غير المتوافقة
-- **`developer` لم يتم التعرف على الدور** — تم إصلاحه في الإصدار 1.1.0: تم تحويله تلقائيًا إلى `system` لمقدمي الخدمات غير التابعين لـ OpenAI
-- **`json_schema` لا يعمل مع Gemini** — تم إصلاحه في الإصدار 1.1.0: `response_format` تم تحويله الآن إلى `responseMimeType` + `responseSchema` الخاص بـ Gemini\_\_
+- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
+- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
+- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
+- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures
+- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
+- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers
+- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema`
 
 ---
 
-## إعدادات المرونة
+## Resilience Settings
 
-### لا يتم تشغيل حد المعدل التلقائي
+### Auto rate-limit not triggering
 
-- ينطبق حد المعدل التلقائي فقط على موفري مفاتيح واجهة برمجة التطبيقات (وليس OAuth/الاشتراك)
-- تحقق من أن **الإعدادات → المرونة → ملفات تعريف الموفر** تم تمكين حد المعدل التلقائي
-- تحقق مما إذا كان الموفر يعرض `429` رموز الحالة أو رؤوس `Retry-After`
+- Auto rate-limit only applies to API key providers (not OAuth/subscription)
+- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
+- Check if the provider returns `429` status codes or `Retry-After` headers
 
-### ضبط التراجع الأسي
+### Tuning exponential backoff
 
-تدعم ملفات تعريف الموفر هذه الإعدادات:
+Provider profiles support these settings:
 
-- **التأخير الأساسي** — وقت الانتظار الأولي بعد الفشل الأول (الافتراضي: 1 ثانية)
-- **الحد الأقصى للتأخير** — الحد الأقصى لوقت الانتظار (الافتراضي: 30 ثانية)
-- **المضاعف** — مقدار زيادة التأخير لكل فشل متتالي (الافتراضي: 2x)
+- **Base delay** — Initial wait time after first failure (default: 1s)
+- **Max delay** — Maximum wait time cap (default: 30s)
+- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
 
-### قطيع مضاد للرعد
+### Anti-thundering herd
 
-عندما تصل العديد من الطلبات المتزامنة إلى موفر محدود السعر، يستخدم OmniRoute تحديد المعدل التلقائي + mutex لإجراء تسلسل للطلبات ومنع حالات الفشل المتتالية. وهذا تلقائي لموفري مفاتيح API.
+When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
 
 ---
 
-## هل مازلت عالقًا؟
+## Optional RAG / LLM failure taxonomy (16 problems)
 
-- **مشكلات GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **الهندسة المعمارية**: راجع [link](ARCHITECTURE.md) للحصول على التفاصيل الداخلية
-- **مرجع واجهة برمجة التطبيقات**: راجع [link](API_REFERENCE.md) لجميع نقاط النهاية
-- **لوحة معلومات الصحة**: تحقق من **لوحة المعلومات ← الصحة** لمعرفة حالة النظام في الوقت الفعلي
-- **المترجم**: استخدم **لوحة المعلومات ← المترجم** لتصحيح مشكلات التنسيق
+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)
+- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
+- **Translator**: Use **Dashboard → Translator** to debug format issues

docs/i18n/ar/USER_GUIDE.md

@@ -1,12 +1,16 @@
-# دليل المستخدم
-
-🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md)
-
-الدليل الكامل لتكوين مقدمي الخدمات، وإنشاء المجموعات، ودمج أدوات CLI، ونشر OmniRoute.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/USER_GUIDE.md) · 🇪🇸 [es](../es/USER_GUIDE.md) · 🇫🇷 [fr](../fr/USER_GUIDE.md) · 🇩🇪 [de](../de/USER_GUIDE.md) · 🇮🇹 [it](../it/USER_GUIDE.md) · 🇷🇺 [ru](../ru/USER_GUIDE.md) · 🇨🇳 [zh-CN](../zh-CN/USER_GUIDE.md) · 🇯🇵 [ja](../ja/USER_GUIDE.md) · 🇰🇷 [ko](../ko/USER_GUIDE.md) · 🇸🇦 [ar](../ar/USER_GUIDE.md) · 🇮🇳 [in](../in/USER_GUIDE.md) · 🇹🇭 [th](../th/USER_GUIDE.md) · 🇻🇳 [vi](../vi/USER_GUIDE.md) · 🇮🇩 [id](../id/USER_GUIDE.md) · 🇲🇾 [ms](../ms/USER_GUIDE.md) · 🇳🇱 [nl](../nl/USER_GUIDE.md) · 🇵🇱 [pl](../pl/USER_GUIDE.md) · 🇸🇪 [sv](../sv/USER_GUIDE.md) · 🇳🇴 [no](../no/USER_GUIDE.md) · 🇩🇰 [da](../da/USER_GUIDE.md) · 🇫🇮 [fi](../fi/USER_GUIDE.md) · 🇵🇹 [pt](../pt/USER_GUIDE.md) · 🇷🇴 [ro](../ro/USER_GUIDE.md) · 🇭🇺 [hu](../hu/USER_GUIDE.md) · 🇧🇬 [bg](../bg/USER_GUIDE.md) · 🇸🇰 [sk](../sk/USER_GUIDE.md) · 🇺🇦 [uk-UA](../uk-UA/USER_GUIDE.md) · 🇮🇱 [he](../he/USER_GUIDE.md) · 🇵🇭 [phi](../phi/USER_GUIDE.md)
 
 ---
 
-## جدول المحتويات
+# 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)
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
+
+## Table of Contents
 
 - [Pricing at a Glance](#-pricing-at-a-glance)
 - [Use Cases](#-use-cases)
@@ -18,40 +22,40 @@
 
 ---
 
-## 💰 لمحة سريعة عن الأسعار
+## 💰 Pricing at a Glance
 
-| الطبقة                             | مقدم                                | التكلفة                | إعادة ضبط الحصص         | الأفضل لـ                              |
-| ---------------------------------- | ----------------------------------- | ---------------------- | ----------------------- | -------------------------------------- |
-| **💳الإشتراك**                     | كلود كود (برو)                      | 20 دولارًا شهريًا      | 5 ساعات + أسبوعي        | اشتركت بالفعل                          |
-|                                    | الدستور الغذائي (زائد / برو)        | 20-200 دولار شهريًا    | 5 ساعات + أسبوعي        | مستخدمي OpenAI                         |
-|                                    | الجوزاء CLI                         | **مجاني**              | 180 ألف/شهر + 1 ألف/يوم | الجميع!                                |
-|                                    | جيثب مساعد الطيار                   | 10-19 دولارًا شهريًا   | شهري                    | مستخدمي جيثب                           |
-| **🔑 مفتاح واجهة برمجة التطبيقات** | ديب سيك                             | الدفع لكل استخدام      | لا شيء                  | الاستدلال الرخيص                       |
-|                                    | جروك                                | الدفع لكل استخدام      | لا شيء                  | الاستدلال فائق السرعة                  |
-|                                    | xAI (جروك)                          | الدفع لكل استخدام      | لا شيء                  | جروك 4 المنطق                          |
-|                                    | ميسترال                             | الدفع لكل استخدام      | لا شيء                  | النماذج التي يستضيفها الاتحاد الأوروبي |
-|                                    | الحيرة                              | الدفع لكل استخدام      | لا شيء                  | البحث المعزز                           |
-|                                    | معا منظمة العفو الدولية             | الدفع لكل استخدام      | لا شيء                  | نماذج مفتوحة المصدر                    |
-|                                    | الألعاب النارية منظمة العفو الدولية | الدفع لكل استخدام      | لا شيء                  | صور التدفق السريع                      |
-|                                    | المخيخ                              | الدفع لكل استخدام      | لا شيء                  | سرعة على نطاق الرقاقة                  |
-|                                    | كوهير                               | الدفع لكل استخدام      | لا شيء                  | الأمر R+ RAG                           |
-|                                    | نفيديا نيم                          | الدفع لكل استخدام      | لا شيء                  | نماذج المؤسسات                         |
-| **💰 رخيص**                        | جي إل إم-4.7                        | 0.6 دولار/1 مليون      | يوميا 10 صباحا          | نسخة احتياطية للميزانية                |
-|                                    | ميني ماكس M2.1                      | 0.2 دولار/1 مليون      | المتداول لمدة 5 ساعات   | الخيار الأرخص                          |
-|                                    | كيمي ك2                             | 9 دولارات شهريًا مسطحة | 10 مليون رمز/شهر        | التكلفة المتوقعة                       |
-| **🆓مجانًا**                       | اي فلو                              | $0                     | غير محدود               | 8 نماذج مجانية                         |
-|                                    | كوين                                | $0                     | غير محدود               | 3 نماذج مجانية                         |
-|                                    | كيرو                                | $0                     | غير محدود               | كلود مجاني                             |
+| Tier                | Provider          | Cost        | Quota Reset      | Best For             |
+| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |
+| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo      | 5h + weekly      | Already subscribed   |
+|                     | Codex (Plus/Pro)  | $20-200/mo  | 5h + weekly      | OpenAI users         |
+|                     | Gemini CLI        | **FREE**    | 180K/mo + 1K/day | Everyone!            |
+|                     | GitHub Copilot    | $10-19/mo   | Monthly          | GitHub users         |
+| **🔑 API KEY**      | DeepSeek          | Pay per use | None             | Cheap reasoning      |
+|                     | Groq              | Pay per use | None             | Ultra-fast inference |
+|                     | xAI (Grok)        | Pay per use | None             | Grok 4 reasoning     |
+|                     | Mistral           | Pay per use | None             | EU-hosted models     |
+|                     | Perplexity        | Pay per use | None             | Search-augmented     |
+|                     | Together AI       | Pay per use | None             | Open-source models   |
+|                     | Fireworks AI      | Pay per use | None             | Fast FLUX images     |
+|                     | Cerebras          | Pay per use | None             | Wafer-scale speed    |
+|                     | Cohere            | Pay per use | None             | Command R+ RAG       |
+|                     | NVIDIA NIM        | Pay per use | None             | Enterprise models    |
+| **💰 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        |
+|                     | Qwen              | $0          | Unlimited        | 3 models free        |
+|                     | Kiro              | $0          | Unlimited        | Claude free          |
 
-**💡 نصيحة احترافية:** ابدأ مع مجموعة Gemini CLI (180 ألفًا مجانًا شهريًا) + مجموعة iFlow (مجانية غير محدودة) = تكلفة 0 دولار!
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost!
 
 ---
 
-## 🎯 حالات الاستخدام
+## 🎯 Use Cases
 
-### الحالة 1: "لدي اشتراك Claude Pro"
+### Case 1: "I have Claude Pro subscription"
 
-**المشكلة:** تنتهي صلاحية الحصة غير المستخدمة، وحدود المعدل أثناء عملية الترميز المكثف
+**Problem:** Quota expires unused, rate limits during heavy coding
 
 ```
 Combo: "maximize-claude"
@@ -63,9 +67,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
 vs. $20 + hitting limits = frustration
 ```
 
-### الحالة 2: "أريد تكلفة صفرية"
+### Case 2: "I want zero cost"
 
-**المشكلة:** لا أستطيع تحمل تكلفة الاشتراكات، وتحتاج إلى ترميز يعتمد على الذكاء الاصطناعي
+**Problem:** Can't afford subscriptions, need reliable AI coding
 
 ```
 Combo: "free-forever"
@@ -77,9 +81,9 @@ Monthly cost: $0
 Quality: Production-ready models
 ```
 
-### الحالة 3: "أحتاج إلى تشفير على مدار 24 ساعة طوال أيام الأسبوع، دون انقطاع"
+### Case 3: "I need 24/7 coding, no interruptions"
 
-**المشكلة:** المواعيد النهائية، لا أستطيع تحمل فترات التوقف عن العمل
+**Problem:** Deadlines, can't afford downtime
 
 ```
 Combo: "always-on"
@@ -93,9 +97,9 @@ Result: 5 layers of fallback = zero downtime
 Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
 ```
 
-### الحالة 4: "أريد ذكاءً اصطناعيًا مجانيًا في OpenClaw"
+### Case 4: "I want FREE AI in OpenClaw"
 
-**المشكلة:** تحتاج إلى مساعد الذكاء الاصطناعي في تطبيقات المراسلة، مجانًا تمامًا
+**Problem:** Need AI assistant in messaging apps, completely free
 
 ```
 Combo: "openclaw-free"
@@ -109,11 +113,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 
 ---
 
-## 📖 إعداد الموفر
+## 📖 Provider Setup
 
-### 🔐 مقدمي الاشتراكات
+### 🔐 Subscription Providers
 
-#### كلود كود (برو/ماكس)
+#### Claude Code (Pro/Max)
 
 ```bash
 Dashboard → Providers → Connect Claude Code
@@ -126,7 +130,7 @@ Models:
   cc/claude-haiku-4-5-20251001
 ```
 
-**نصيحة احترافية:** استخدم Opus للمهام المعقدة، وSonnet للسرعة. OmniRoute يتتبع الحصة لكل نموذج!
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
 
 #### OpenAI Codex (Plus/Pro)
 
@@ -140,7 +144,7 @@ Models:
   cx/gpt-5.1-codex-max
 ```
 
-#### Gemini CLI (180 ألفًا شهريًا مجانًا!)
+#### Gemini CLI (FREE 180K/month!)
 
 ```bash
 Dashboard → Providers → Connect Gemini CLI
@@ -152,9 +156,9 @@ Models:
   gc/gemini-2.5-pro
 ```
 
-**أفضل قيمة:** طبقة مجانية ضخمة! استخدم هذا قبل المستويات المدفوعة.
+**Best Value:** Huge free tier! Use this before paid tiers.
 
-#### مساعد جيثب
+#### GitHub Copilot
 
 ```bash
 Dashboard → Providers → Connect GitHub
@@ -167,33 +171,33 @@ Models:
   gh/gemini-3-pro
 ```
 
-### 💰 مقدمو خدمات رخيصون
+### 💰 Cheap Providers
 
-#### GLM-4.7 (إعادة التعيين اليومي، 0.6 دولار/1 مليون)
+#### GLM-4.7 (Daily reset, $0.6/1M)
 
-1. قم بالتسجيل: [Zhipu AI](https://open.bigmodel.cn/)
-2. احصل على مفتاح API من خطة الترميز
-3. لوحة المعلومات → إضافة مفتاح واجهة برمجة التطبيقات: الموفر: `glm`، مفتاح واجهة برمجة التطبيقات: `your-key`
+1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)
+2. Get API key from Coding Plan
+3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`
 
-**الاستخدام:** `glm/glm-4.7` — **نصيحة احترافية:** توفر خطة البرمجة حصة 3× بتكلفة 1/7! إعادة الضبط يوميًا الساعة 10:00 صباحًا.
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
 
-#### MiniMax M2.1 (إعادة الضبط لمدة 5 ساعات، 0.20 دولار/1 مليون)
+#### MiniMax M2.1 (5h reset, $0.20/1M)
 
-1. قم بالتسجيل: [MiniMax](https://www.minimax.io/)
-2. احصل على مفتاح API → لوحة المعلومات → إضافة مفتاح API
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
 
-**الاستخدام:** `minimax/MiniMax-M2.1` — **نصيحة احترافية:** الخيار الأرخص للسياق الطويل (مليون رمز)!
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
 
-#### كيمي K2 (شقة بقيمة 9 دولارات في الشهر)
+#### Kimi K2 ($9/month flat)
 
-1. الاشتراك: [Moonshot AI](https://platform.moonshot.ai/)
-2. احصل على مفتاح API → لوحة المعلومات → إضافة مفتاح API
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
 
-**الاستخدام:** `kimi/kimi-latest` — **نصيحة احترافية:** سعر ثابت قدره 9 دولارات شهريًا مقابل 10 ملايين رمز مميز = 0.90 دولارًا أمريكيًا/التكلفة الفعلية لمليون واحد!
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
 
-### 🆓 مقدمي الخدمة مجانًا
+### 🆓 FREE Providers
 
-#### iFlow (8 نماذج مجانية)
+#### iFlow (8 FREE models)
 
 ```bash
 Dashboard → Connect iFlow → OAuth login → Unlimited usage
@@ -201,7 +205,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage
 Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1
 ```
 
-#### كوين (3 موديلات مجانية)
+#### Qwen (3 FREE models)
 
 ```bash
 Dashboard → Connect Qwen → Device code auth → Unlimited usage
@@ -209,7 +213,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage
 Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
 ```
 
-#### كيرو (كلود فري)
+#### Kiro (Claude FREE)
 
 ```bash
 Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
@@ -219,9 +223,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
 
 ---
 
-## 🎨 المجموعات
+## 🎨 Combos
 
-### مثال 1: زيادة الاشتراك إلى الحد الأقصى → النسخ الاحتياطي الرخيص
+### Example 1: Maximize Subscription → Cheap Backup
 
 ```
 Dashboard → Combos → Create New
@@ -235,7 +239,7 @@ Models:
 Use in CLI: premium-coding
 ```
 
-### المثال 2: مجاني فقط (بدون تكلفة)
+### Example 2: Free-Only (Zero Cost)
 
 ```
 Name: free-combo
@@ -249,9 +253,9 @@ Cost: $0 forever!
 
 ---
 
-## 🔧 تكامل CLI
+## 🔧 CLI Integration
 
-### بيئة تطوير متكاملة للمؤشر
+### Cursor IDE
 
 ```
 Settings → Models → Advanced:
@@ -260,9 +264,9 @@ Settings → Models → Advanced:
   Model: cc/claude-opus-4-6
 ```
 
-### كلود كود
+### Claude Code
 
-تحرير `~/.claude/config.json`:
+Edit `~/.claude/config.json`:
 
 ```json
 {
@@ -271,7 +275,7 @@ Settings → Models → Advanced:
 }
 ```
 
-### كوديكس سطر الأوامر
+### Codex CLI
 
 ```bash
 export OPENAI_BASE_URL="http://localhost:20128"
@@ -281,7 +285,7 @@ codex "your prompt"
 
 ### OpenClaw
 
-تحرير `~/.openclaw/openclaw.json`:
+Edit `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -303,9 +307,9 @@ codex "your prompt"
 }
 ```
 
-**أو استخدم لوحة المعلومات:** أدوات CLI → OpenClaw → التكوين التلقائي
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
 
-### كلاين / متابعة / RooCode
+### Cline / Continue / RooCode
 
 ```
 Provider: OpenAI Compatible
@@ -316,9 +320,28 @@ Model: cc/claude-opus-4-6
 
 ---
 
-## 🚀 النشر
+## 🚀 Deployment
 
-### نشر VPS
+### 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
 git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -337,7 +360,44 @@ 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
 # Build image (default = runner-cli with codex/claude/droid preinstalled)
@@ -347,81 +407,84 @@ docker build -t omniroute:cli .
 docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
 ```
 
-بالنسبة للوضع المدمج مع المضيف مع ثنائيات CLI، راجع قسم Docker في المستندات الرئيسية.
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
 
-### متغيرات البيئة
+### Environment Variables
 
-| متغير                 | الافتراضي                            | الوصف                                                            |
-| --------------------- | ------------------------------------ | ---------------------------------------------------------------- |
-| `JWT_SECRET`          | `omniroute-default-secret-change-me` | سر توقيع JWT (**تغيير في الإنتاج**)                              |
-| `INITIAL_PASSWORD`    | `123456`                             | كلمة المرور الأولى لتسجيل الدخول                                 |
-| `DATA_DIR`            | `~/.omniroute`                       | دليل البيانات (ديسيبل، الاستخدام، السجلات)                       |
-| `PORT`                | الإطار الافتراضي                     | منفذ الخدمة (`20128` في الأمثلة)                                 |
-| `HOSTNAME`            | الإطار الافتراضي                     | ربط المضيف (إعدادات Docker الافتراضية هي `0.0.0.0`)              |
-| `NODE_ENV`            | وقت التشغيل الافتراضي                | قم بتعيين `production` للنشر                                     |
-| `BASE_URL`            | `http://localhost:20128`             | عنوان URL الأساسي الداخلي من جانب الخادم                         |
-| `CLOUD_URL`           | `https://omniroute.dev`              | عنوان URL الأساسي لنقطة نهاية المزامنة السحابية                  |
-| `API_KEY_SECRET`      | `endpoint-proxy-api-key-secret`      | سر HMAC لمفاتيح API التي تم إنشاؤها                              |
-| `REQUIRE_API_KEY`     | `false`                              | فرض مفتاح Bearer API على `/v1/*`                                 |
-| `ENABLE_REQUEST_LOGS` | `false`                              | تمكين سجلات الطلب/الاستجابة                                      |
-| `AUTH_COOKIE_SECURE`  | `false`                              | فرض ملف تعريف ارتباط المصادقة `Secure` (خلف الوكيل العكسي HTTPS) |
+| 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) |
+| `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                              |
 
-للحصول على مرجع متغير البيئة الكامل، راجع [README](../README.md).
+For the full environment variable reference, see the [README](../README.md).
 
 ---
 
-## 📊 الموديلات المتوفرة
+## 📊 Available Models
 
 <details>
-<summary><b>عرض جميع الموديلات المتاحة</b></summary>
+<summary><b>View all available models</b></summary>
 
-**كود كلود (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
 
-**المخطوطة (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`، `cx/gpt-5.1-codex-max`
+**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`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
 
-**مساعد GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
 
-**GLM (`glm/`)** — 0.6 دولار/1 مليون: `glm/glm-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
 
-**ميني ماكس (`minimax/`)** — 0.2 دولار/1 مليون: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
 
-**iFlow (`if/`)** — مجانًا: `if/kimi-k2-thinking`، `if/qwen3-coder-plus`، `if/deepseek-r1`
+**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
 
-**كوين (`qw/`)** — مجانًا: `qw/qwen3-coder-plus`، `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
 
-**كيرو (`kr/`)** — مجانًا: `kr/claude-sonnet-4.5`، `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
 
-**DeepSeek (`ds/`)**: `ds/deepseek-chat`، `ds/deepseek-reasoner`
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
 
-** جروك (`groq/`)**: `groq/llama-3.3-70b-versatile`، `groq/llama-4-maverick-17b-128e-instruct`
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
 
-**xAI (`xai/`)**: `xai/grok-4`، `xai/grok-4-0709-fast-reasoning`، `xai/grok-code-mini`
+**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
 
-**ميسترال (`mistral/`)**: `mistral/mistral-large-2501`، `mistral/codestral-2501`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
 
-**الحيرة (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
 
-** معًا الذكاء الاصطناعي (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
 
-**الذكاء الاصطناعي للألعاب النارية (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
 
-** سيريبراس (`cerebras/`)**: `cerebras/llama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
 
-**الترابط (`cohere/`)**: `cohere/command-r-plus-08-2024`
+**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
 
-** نفيديا نيم (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
 
 </details>
 
 ---
 
-## 🧩 ميزات متقدمة
+## 🧩 Advanced Features
 
-### نماذج مخصصة
+### Custom Models
 
-أضف أي معرف نموذج إلى أي مزود دون انتظار تحديث التطبيق:
+Add any model ID to any provider without waiting for an app update:
 
 ```bash
 # Via API
@@ -433,11 +496,11 @@ curl -X POST http://localhost:20128/api/provider-models \
 # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
 ```
 
-أو استخدم لوحة المعلومات: **المزودون → [الموفر] → النماذج المخصصة**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
 
-### مسارات موفر مخصصة
+### Dedicated Provider Routes
 
-توجيه الطلبات مباشرة إلى موفر محدد مع التحقق من صحة النموذج:
+Route requests directly to a specific provider with model validation:
 
 ```bash
 POST http://localhost:20128/v1/providers/openai/chat/completions
@@ -445,9 +508,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings
 POST http://localhost:20128/v1/providers/fireworks/images/generations
 ```
 
-تتم إضافة بادئة الموفر تلقائيًا في حالة فقدانها. تُرجع النماذج غير المتطابقة `400`.
+The provider prefix is auto-added if missing. Mismatched models return `400`.
 
-### تكوين وكيل الشبكة
+### Network Proxy Configuration
 
 ```bash
 # Set global proxy
@@ -463,76 +526,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \
   -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
 ```
 
-**الأسبقية:** خاص بالمفتاح ← خاص بالسرد والسرد ← خاص بالموفر ← عالمي ← البيئة.
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
 
-### واجهة برمجة تطبيقات الكتالوج النموذجي
+### Model Catalog API
 
 ```bash
 curl http://localhost:20128/api/models/catalog
 ```
 
-إرجاع النماذج المجمعة حسب الموفر مع الأنواع (`chat`، `embedding`، `image`).
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
 
-### المزامنة السحابية
+### Cloud Sync
 
-- موفري المزامنة والمجموعات والإعدادات عبر الأجهزة
-- مزامنة الخلفية التلقائية مع انتهاء المهلة + الفشل السريع
-- تفضيل جانب الخادم `BASE_URL`/`CLOUD_URL` في الإنتاج
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
 
-### LLM Gateway Intelligence (المرحلة 9)
+### LLM Gateway Intelligence (Phase 9)
 
-- **ذاكرة التخزين المؤقت الدلالية** — ذاكرة تخزين مؤقت تلقائية غير متدفقة، درجة الحرارة = 0 استجابات (تجاوز باستخدام `X-OmniRoute-No-Cache: true`)
-- **صلاحية الطلب** — إلغاء تكرار الطلبات خلال 5 ثوانٍ عبر رأس `Idempotency-Key` أو `X-Request-Id`
-- **تتبع التقدم** — الاشتراك في أحداث SSE `event: progress` عبر رأس `X-OmniRoute-Progress: true`
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
 
 ---
 
-### ملعب المترجم
+### Translator Playground
 
-الوصول عبر **لوحة المعلومات → المترجم**. تصحيح الأخطاء وتصور كيفية قيام OmniRoute بترجمة طلبات واجهة برمجة التطبيقات (API) بين مقدمي الخدمة.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
 
-| الوضع                | الغرض                                                                         |
-| -------------------- | ----------------------------------------------------------------------------- |
-| **ساحة اللعب**       | حدد تنسيقات المصدر/الهدف، والصق طلبًا، وشاهد المخرجات المترجمة على الفور      |
-| ** اختبار الدردشة ** | أرسل رسائل الدردشة المباشرة من خلال الوكيل وافحص دورة الطلب/الاستجابة الكاملة |
-| ** مقعد الاختبار **  | قم بإجراء اختبارات مجمعة عبر مجموعات تنسيقات متعددة للتحقق من صحة الترجمة     |
-| **مراقبة حية**       | شاهد الترجمات في الوقت الفعلي أثناء تدفق الطلبات عبر الوكيل                   |
+| Mode             | Purpose                                                                                |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground**   | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester**  | Send live chat messages through the proxy and inspect the full request/response cycle  |
+| **Test Bench**   | Run batch tests across multiple format combinations to verify translation correctness  |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy                        |
 
-**حالات الاستخدام:**
+**Use cases:**
 
-- تصحيح سبب فشل مجموعة محددة من العميل/الموفر
-- التحقق من ترجمة علامات التفكير واستدعاءات الأدوات ومطالبات النظام بشكل صحيح
-- مقارنة اختلافات التنسيق بين تنسيقات OpenAI وClaude وGemini وResponsions API
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
 
 ---
 
-### استراتيجيات التوجيه
+### Routing Strategies
 
-قم بالتكوين عبر **لوحة المعلومات → الإعدادات → التوجيه**.
+Configure via **Dashboard → Settings → Routing**.
 
-| استراتيجية               | الوصف                                                                                    |
-| ------------------------ | ---------------------------------------------------------------------------------------- |
-| ** املأ أولا **          | يستخدم الحسابات بترتيب الأولوية — يعالج الحساب الأساسي جميع الطلبات حتى تصبح غير متاحة   |
-| ** راوند روبن **         | للتنقل عبر جميع الحسابات بحد ثابت قابل للتكوين (الافتراضي: 3 مكالمات لكل حساب)           |
-| **P2C (قوة الاختيارين)** | يختار حسابين عشوائيين ويوجهك إلى الحساب الأكثر صحة - الأرصدة محملة بالوعي الصحي          |
-| **عشوائي**               | تحديد حساب عشوائيًا لكل طلب باستخدام خلط Fisher-Yates                                    |
-| **الأقل استخدامًا**      | التوجيهات إلى الحساب ذو الطابع الزمني الأقدم `lastUsedAt`، مع توزيع حركة المرور بالتساوي |
-| **التكلفة الأمثل**       | التوجيهات إلى الحساب ذي أقل قيمة أولوية، مع تحسين موفري الخدمة الأقل تكلفة               |
+| Strategy                       | Description                                                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First**                 | Uses accounts in priority order — primary account handles all requests until unavailable         |
+| **Round Robin**                | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account)      |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random**                     | Randomly selects an account for each request using Fisher-Yates shuffle                          |
+| **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       |
 
-#### الأسماء المستعارة لنموذج البدل
+#### Wildcard Model Aliases
 
-قم بإنشاء أنماط أحرف البدل لإعادة تعيين أسماء النماذج:
+Create wildcard patterns to remap model names:
 
 ```
 Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-5-20250929
 Pattern: gpt-*               →  Target: gh/gpt-5.1-codex
 ```
 
-تدعم أحرف البدل `*` (أي أحرف) و`?` (حرف واحد).
+Wildcards support `*` (any characters) and `?` (single character).
 
-#### سلاسل احتياطية
+#### Fallback Chains
 
-تحديد السلاسل الاحتياطية العالمية التي تنطبق على جميع الطلبات:
+Define global fallback chains that apply across all requests:
 
 ```
 Chain: production-fallback
@@ -543,46 +606,46 @@ Chain: production-fallback
 
 ---
 
-### المرونة وقواطع الدائرة
+### Resilience & Circuit Breakers
 
-قم بالتكوين عبر **لوحة المعلومات → الإعدادات → المرونة**.
+Configure via **Dashboard → Settings → Resilience**.
 
-تطبق OmniRoute المرونة على مستوى المزود من خلال أربعة مكونات:
+OmniRoute implements provider-level resilience with four components:
 
-1. **ملفات تعريف الموفر** — التكوين لكل موفر لـ:
-   - عتبة الفشل (كم عدد حالات الفشل قبل الفتح)
-   - مدة التهدئة
-   - حساسية الكشف عن حد المعدل
-   - معلمات التراجع الأسي
+1. **Provider Profiles** — Per-provider configuration for:
+   - Failure threshold (how many failures before opening)
+   - Cooldown duration
+   - Rate limit detection sensitivity
+   - Exponential backoff parameters
 
-2. **حدود المعدل القابلة للتحرير** — الإعدادات الافتراضية على مستوى النظام قابلة للتكوين في لوحة المعلومات:
-   - **الطلبات في الدقيقة (RPM)** — الحد الأقصى للطلبات في الدقيقة لكل حساب
-   - **الحد الأدنى للوقت بين الطلبات** — الحد الأدنى للفجوة بالمللي ثانية بين الطلبات
-   - **الحد الأقصى للطلبات المتزامنة** — الحد الأقصى للطلبات المتزامنة لكل حساب
-   - انقر **تحرير** للتعديل، ثم **حفظ** أو **إلغاء**. تستمر القيم عبر واجهة برمجة تطبيقات المرونة.
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+   - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+   - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+   - **Max Concurrent Requests** — Maximum simultaneous requests per account
+   - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
 
-3. **قاطع الدائرة** — يتتبع حالات الفشل لكل مزود ويفتح الدائرة تلقائيًا عند الوصول إلى الحد الأدنى:
-   - **مغلق** (صحي) — تتدفق الطلبات بشكل طبيعي
-   - **مفتوح** — تم حظر الموفر مؤقتًا بعد الفشل المتكرر
-   - **HALF_OPEN** — اختبار ما إذا كان الموفر قد استعاد عافيته
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+   - **CLOSED** (Healthy) — Requests flow normally
+   - **OPEN** — Provider is temporarily blocked after repeated failures
+   - **HALF_OPEN** — Testing if provider has recovered
 
-4. **السياسات والمعرفات المقفلة** — تعرض حالة قاطع الدائرة والمعرفات المقفلة مع إمكانية إلغاء القفل بالقوة.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
 
-5. **الاكتشاف التلقائي لحدود المعدل** — يراقب الرؤوس `429` و`Retry-After` لتجنب الوصول إلى حدود معدل الموفر بشكل استباقي.
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
 
-**نصيحة احترافية:** استخدم زر **إعادة تعيين الكل** لمسح جميع قواطع الدائرة وفترات التباطؤ عندما يتعافى المزود من انقطاع الخدمة.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
 
 ---
 
-### تصدير / استيراد قاعدة البيانات
+### Database Export / Import
 
-إدارة النسخ الاحتياطية لقاعدة البيانات في **لوحة المعلومات → الإعدادات → النظام والتخزين**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
 
-| العمل                      | الوصف                                                                                                                                          |
-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| **تصدير قاعدة البيانات**   | يقوم بتنزيل قاعدة بيانات SQLite الحالية كملف `.sqlite`                                                                                         |
-| **تصدير الكل (.tar.gz)**   | تنزيل أرشيف نسخ احتياطي كامل بما في ذلك: قاعدة البيانات، والإعدادات، والمجموعات، واتصالات الموفر (بدون بيانات اعتماد)، وبيانات تعريف مفتاح API |
-| **استيراد قاعدة البيانات** | قم بتحميل ملف `.sqlite` لاستبدال قاعدة البيانات الحالية. يتم إنشاء نسخة احتياطية للاستيراد المسبق تلقائيًا                                     |
+| 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                          |
 
 ```bash
 # API: Export database
@@ -596,38 +659,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \
   -F "file=@backup.sqlite"
 ```
 
-**التحقق من صحة الاستيراد:** يتم التحقق من صحة الملف المستورد للتأكد من سلامته (فحص براغما SQLite)، والجداول المطلوبة (`provider_connections`، `provider_nodes`، `combos`، `api_keys`)، والحجم (100 ميجابايت كحد أقصى).
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
 
-**حالات الاستخدام:**
+**Use Cases:**
 
-- ترحيل OmniRoute بين الأجهزة
-- إنشاء نسخ احتياطية خارجية للتعافي من الكوارث
-- مشاركة التكوينات بين أعضاء الفريق (تصدير الكل → مشاركة الأرشيف)
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
 
 ---
 
-### لوحة تحكم الإعدادات
+### Settings Dashboard
 
-يتم تنظيم صفحة الإعدادات في 5 علامات تبويب لسهولة التنقل:
+The settings page is organized into 5 tabs for easy navigation:
 
-| علامة التبويب        | المحتويات                                                                                                                    |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| **الأمن**            | إعدادات تسجيل الدخول/كلمة المرور، والتحكم في الوصول إلى IP، ومصادقة API لـ `/models`، وحظر الموفر                            |
-| **التوجيه**          | استراتيجية التوجيه العالمية (6 خيارات)، والأسماء المستعارة لنماذج أحرف البدل، والسلاسل الاحتياطية، وافتراضيات التحرير والسرد |
-| **المرونة**          | ملفات تعريف الموفر، وحدود الأسعار القابلة للتحرير، وحالة قاطع الدائرة، والسياسات والمعرفات المقفلة                           |
-| **الذكاء الاصطناعي** | تكوين ميزانية التفكير، والحقن الفوري للنظام العالمي، وإحصائيات ذاكرة التخزين المؤقت السريعة                                  |
-| **متقدم**            | تكوين الوكيل العالمي (HTTP/SOCKS5)                                                                                           |
+| Tab            | Contents                                                                                       |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **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 |
+| **AI**         | Thinking budget configuration, global system prompt injection, prompt cache stats              |
+| **Advanced**   | Global proxy configuration (HTTP/SOCKS5)                                                       |
 
 ---
 
-### إدارة التكاليف والميزانية
+### Costs & Budget Management
 
-الوصول عبر **لوحة التحكم ← التكاليف**.
+Access via **Dashboard → Costs**.
 
-| علامة التبويب | الغرض                                                                                            |
-| ------------- | ------------------------------------------------------------------------------------------------ |
-| **الميزانية** | قم بتعيين حدود الإنفاق لكل مفتاح API باستخدام ميزانيات يومية/أسبوعية/شهرية وتتبع في الوقت الفعلي |
-| **التسعير**   | عرض وتحرير إدخالات تسعير النموذج - التكلفة لكل ألف رمز إدخال/إخراج لكل مزود                      |
+| Tab         | Purpose                                                                                  |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget**  | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider       |
 
 ```bash
 # API: Set a budget
@@ -639,13 +702,13 @@ curl -X POST http://localhost:20128/api/usage/budget \
 curl http://localhost:20128/api/usage/budget
 ```
 
-**تتبع التكلفة:** يقوم كل طلب بتسجيل استخدام الرمز المميز وحساب التكلفة باستخدام جدول التسعير. عرض التفاصيل في **لوحة المعلومات → الاستخدام** حسب الموفر والطراز ومفتاح واجهة برمجة التطبيقات.
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
 
 ---
 
-### النسخ الصوتي
+### Audio Transcription
 
-يدعم OmniRoute النسخ الصوتي عبر نقطة النهاية المتوافقة مع OpenAI:
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
 
 ```bash
 POST /v1/audio/transcriptions
@@ -659,40 +722,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
   -F "model=deepgram/nova-3"
 ```
 
-الموفرون المتاحون: **Deepgram** (`deepgram/`)، **AssemblyAI** (`assemblyai/`).
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
 
-تنسيقات الصوت المدعومة: `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`.
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
 
 ---
 
-### استراتيجيات موازنة التحرير والسرد
+### Combo Balancing Strategies
 
-قم بتكوين التوازن لكل مجموعة في **لوحة المعلومات → المجموعات → إنشاء/تحرير → الإستراتيجية**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
 
-| استراتيجية          | الوصف                                                                                          |
-| ------------------- | ---------------------------------------------------------------------------------------------- |
-| **جولة روبن**       | يدور عبر النماذج بالتتابع                                                                      |
-| **الأولوية**        | يحاول دائمًا النموذج الأول؛ لا يعود إلا على الخطأ                                              |
-| **عشوائي**          | يختار نموذجًا عشوائيًا من المجموعة لكل طلب                                                     |
-| **المرجح**          | تعتمد المسارات بشكل متناسب على الأوزان المخصصة لكل نموذج                                       |
-| **الأقل استخدامًا** | التوجيهات إلى النموذج الذي يحتوي على أقل عدد من الطلبات الأخيرة (يستخدم مقاييس التحرير والسرد) |
-| **التكلفة الأمثل**  | الطرق إلى أرخص طراز متاح (يستخدم جدول التسعير)                                                 |
+| Strategy           | Description                                                              |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin**    | Rotates through models sequentially                                      |
+| **Priority**       | Always tries the first model; falls back only on error                   |
+| **Random**         | Picks a random model from the combo for each request                     |
+| **Weighted**       | Routes proportionally based on assigned weights per model                |
+| **Least-Used**     | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table)              |
 
-يمكن ضبط إعدادات التحرير والسرد العامة في **لوحة المعلومات → الإعدادات → التوجيه → إعدادات التحرير والسرد الافتراضية**.
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
 
 ---
 
-### لوحة المعلومات الصحية
+### Health Dashboard
 
-الوصول عبر **لوحة التحكم → الصحة**. نظرة عامة على صحة النظام في الوقت الحقيقي مع 6 بطاقات:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
 
-| بطاقة                              | ما يظهر                                                        |
-| ---------------------------------- | -------------------------------------------------------------- |
-| **حالة النظام**                    | وقت التشغيل، الإصدار، استخدام الذاكرة، دليل البيانات           |
-| ** صحة المزود **                   | حالة قاطع الدائرة الكهربائية لكل مزود (مغلق/مفتوح/نصف مفتوح)   |
-| ** حدود المعدل **                  | فترات تهدئة حد المعدل النشط لكل حساب مع الوقت المتبقي          |
-| ** عمليات التأمين النشطة **        | تم حظر مقدمي الخدمة مؤقتًا بواسطة سياسة التأمين                |
-| ** ذاكرة التخزين المؤقت للتوقيع ** | إحصائيات إلغاء البيانات المكررة (المفاتيح النشطة، معدل الدخول) |
-| ** قياس زمن الوصول **              | p50/p95/p99 تجميع زمن الوصول لكل مزود                          |
+| Card                  | What It Shows                                               |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status**     | Uptime, version, memory usage, data directory               |
+| **Provider Health**   | Per-provider circuit breaker state (Closed/Open/Half-Open)  |
+| **Rate Limits**       | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts**   | Providers temporarily blocked by the lockout policy         |
+| **Signature Cache**   | Deduplication cache stats (active keys, hit rate)           |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider                |
 
-**نصيحة احترافية:** يتم تحديث صفحة الصحة تلقائيًا كل 10 ثوانٍ. استخدم بطاقة قاطع الدائرة لتحديد مقدمي الخدمة الذين يواجهون مشكلات.
+**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/i18n/ar/VM_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,403 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/VM_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../es/VM_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../fr/VM_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../de/VM_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../it/VM_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../ru/VM_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../zh-CN/VM_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../ja/VM_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../ko/VM_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../ar/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [in](../in/VM_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../th/VM_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../vi/VM_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../id/VM_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../ms/VM_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../nl/VM_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../pl/VM_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../sv/VM_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../no/VM_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../da/VM_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../fi/VM_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../pt/VM_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../ro/VM_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../hu/VM_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../bg/VM_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../sk/VM_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../uk-UA/VM_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../he/VM_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../phi/VM_DEPLOYMENT_GUIDE.md)
+
+---
+
+# OmniRoute — Guia de Deploy em VM com Cloudflare
+
+Guia completo para instalar e configurar o OmniRoute em uma VM (VPS) com domínio gerenciado via Cloudflare.
+
+---
+
+## Pré-Requisitos
+
+| 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+       |
+
+**Providers testados**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail.
+
+---
+
+## 1. Configurar a VM
+
+### 1.1 Criar a instância
+
+No seu provider de VPS preferido:
+
+- 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`)
+
+### 1.2 Conectar via SSH
+
+```bash
+ssh root@203.0.113.10
+```
+
+### 1.3 Atualizar o sistema
+
+```bash
+apt update && apt upgrade -y
+```
+
+### 1.4 Instalar Docker
+
+```bash
+# Instalar dependências
+apt install -y ca-certificates curl gnupg
+
+# Adicionar repositório oficial do Docker
+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
+apt update
+apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
+```
+
+### 1.5 Instalar nginx
+
+```bash
+apt install -y nginx
+```
+
+### 1.6 Configurar Firewall (UFW)
+
+```bash
+ufw default deny incoming
+ufw default allow outgoing
+ufw allow 22/tcp    # SSH
+ufw allow 80/tcp    # HTTP (redirect)
+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).
+
+---
+
+## 2. Instalar o OmniRoute
+
+### 2.1 Criar diretório de configuração
+
+```bash
+mkdir -p /opt/omniroute
+```
+
+### 2.2 Criar arquivo de variáveis de ambiente
+
+```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
+STORAGE_ENCRYPTION_KEY_VERSION=v1
+MACHINE_ID_SALT=ALTERE-PARA-SALT-UNICO
+
+# === App ===
+PORT=20128
+NODE_ENV=production
+HOSTNAME=0.0.0.0
+DATA_DIR=/app/data
+STORAGE_DRIVER=sqlite
+ENABLE_REQUEST_LOGS=true
+AUTH_COOKIE_SECURE=false
+REQUIRE_API_KEY=false
+
+# === Domain (altere para seu domínio) ===
+BASE_URL=https://llms.seudominio.com
+NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
+
+# === Cloud Sync (opcional) ===
+# 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.
+
+### 2.3 Iniciar o container
+
+```bash
+docker pull diegosouzapw/omniroute:latest
+
+docker run -d \
+  --name omniroute \
+  --restart unless-stopped \
+  --env-file /opt/omniroute/.env \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+### 2.4 Verificar se está rodando
+
+```bash
+docker ps | grep omniroute
+docker logs omniroute --tail 20
+```
+
+Deve exibir: `[DB] SQLite database ready` e `listening on port 20128`.
+
+---
+
+## 3. Configurar nginx (Reverse Proxy)
+
+### 3.1 Gerar certificado SSL (Cloudflare Origin)
+
+No painel da Cloudflare:
+
+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**
+
+```bash
+mkdir -p /etc/nginx/ssl
+
+# Colar o certificado
+nano /etc/nginx/ssl/origin.crt
+
+# Colar a chave privada
+nano /etc/nginx/ssl/origin.key
+
+chmod 600 /etc/nginx/ssl/origin.key
+```
+
+### 3.2 Configuração do nginx
+
+```bash
+cat > /etc/nginx/sites-available/omniroute << 'NGINX'
+# Default server — bloqueia acesso direto por IP
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    listen 443 ssl default_server;
+    listen [::]:443 ssl default_server;
+    ssl_certificate     /etc/nginx/ssl/origin.crt;
+    ssl_certificate_key /etc/nginx/ssl/origin.key;
+    server_name _;
+    return 444;
+}
+
+# OmniRoute — HTTPS
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    server_name llms.seudominio.com;  # Altere para seu domínio
+
+    ssl_certificate     /etc/nginx/ssl/origin.crt;
+    ssl_certificate_key /etc/nginx/ssl/origin.key;
+    ssl_protocols TLSv1.2 TLSv1.3;
+
+    client_max_body_size 100M;
+
+    location / {
+        proxy_pass http://127.0.0.1:20128;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket support
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_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;
+    }
+}
+
+# HTTP → HTTPS redirect
+server {
+    listen 80;
+    listen [::]:80;
+    server_name llms.seudominio.com;
+    return 301 https://$server_name$request_uri;
+}
+NGINX
+```
+
+### 3.3 Ativar e testar
+
+```bash
+# Remover config padrão
+rm -f /etc/nginx/sites-enabled/default
+
+# Ativar OmniRoute
+ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute
+
+# Testar e recarregar
+nginx -t && systemctl reload nginx
+```
+
+---
+
+## 4. Configurar Cloudflare DNS
+
+### 4.1 Adicionar registro DNS
+
+No painel da Cloudflare → DNS:
+
+| Type | Name   | Content                   | Proxy      |
+| ---- | ------ | ------------------------- | ---------- |
+| A    | `llms` | `203.0.113.10` (IP da VM) | ✅ Proxied |
+
+### 4.2 Configurar SSL
+
+Em **SSL/TLS → Overview**:
+
+- Modo: **Full (Strict)**
+
+Em **SSL/TLS → Edge Certificates**:
+
+- Always Use HTTPS: ✅ On
+- Minimum TLS Version: TLS 1.2
+- Automatic HTTPS Rewrites: ✅ On
+
+### 4.3 Testar
+
+```bash
+curl -sI https://llms.seudominio.com/health
+# Deve retornar HTTP/2 200
+```
+
+---
+
+## 5. Operações e Manutenção
+
+### Atualizar para nova versão
+
+```bash
+docker pull diegosouzapw/omniroute:latest
+docker stop omniroute && docker rm omniroute
+docker run -d --name omniroute --restart unless-stopped \
+  --env-file /opt/omniroute/.env \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+### Ver logs
+
+```bash
+docker logs -f omniroute          # Stream em tempo real
+docker logs omniroute --tail 50   # Últimas 50 linhas
+```
+
+### Backup manual do banco
+
+```bash
+# Copiar dados do volume para o host
+docker cp omniroute:/app/data ./backup-$(date +%F)
+
+# Ou comprimir todo o 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
+
+```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 /"
+docker start omniroute
+```
+
+---
+
+## 6. Segurança Avançada
+
+### Restringir nginx para Cloudflare IPs
+
+```bash
+cat > /etc/nginx/cloudflare-ips.conf << 'CF'
+# Cloudflare IPv4 ranges — atualizar periodicamente
+# https://www.cloudflare.com/ips-v4/
+set_real_ip_from 173.245.48.0/20;
+set_real_ip_from 103.21.244.0/22;
+set_real_ip_from 103.22.200.0/22;
+set_real_ip_from 103.31.4.0/22;
+set_real_ip_from 141.101.64.0/18;
+set_real_ip_from 108.162.192.0/18;
+set_real_ip_from 190.93.240.0/20;
+set_real_ip_from 188.114.96.0/20;
+set_real_ip_from 197.234.240.0/22;
+set_real_ip_from 198.41.128.0/17;
+set_real_ip_from 162.158.0.0/15;
+set_real_ip_from 104.16.0.0/13;
+set_real_ip_from 104.24.0.0/14;
+set_real_ip_from 172.64.0.0/13;
+set_real_ip_from 131.0.72.0/22;
+real_ip_header CF-Connecting-IP;
+CF
+```
+
+Adicionar no `nginx.conf` dentro do bloco `http {}`:
+
+```nginx
+include /etc/nginx/cloudflare-ips.conf;
+```
+
+### Install fail2ban
+
+```bash
+apt install -y fail2ban
+systemctl enable fail2ban
+systemctl start fail2ban
+
+# Verificar status
+fail2ban-client status sshd
+```
+
+### Bloquear acesso direto na porta do Docker
+
+```bash
+# Impedir acesso externo direto à porta 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
+apt install -y iptables-persistent
+netfilter-persistent save
+```
+
+---
+
+## 7. Deploy do Cloud Worker (Opcional)
+
+Para acesso remoto via Cloudflare Workers (sem expor a VM diretamente):
+
+```bash
+# No repositório local
+cd omnirouteCloud
+npm install
+npx wrangler login
+npx wrangler deploy
+```
+
+Ver documentação completa em [omnirouteCloud/README.md](../omnirouteCloud/README.md).
+
+---
+
+## Resumo de Portas
+
+| 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) |

docs/i18n/bg/A2A-SERVER.md

@@ -0,0 +1,200 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/A2A-SERVER.md) · 🇪🇸 [es](../es/A2A-SERVER.md) · 🇫🇷 [fr](../fr/A2A-SERVER.md) · 🇩🇪 [de](../de/A2A-SERVER.md) · 🇮🇹 [it](../it/A2A-SERVER.md) · 🇷🇺 [ru](../ru/A2A-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/A2A-SERVER.md) · 🇯🇵 [ja](../ja/A2A-SERVER.md) · 🇰🇷 [ko](../ko/A2A-SERVER.md) · 🇸🇦 [ar](../ar/A2A-SERVER.md) · 🇮🇳 [in](../in/A2A-SERVER.md) · 🇹🇭 [th](../th/A2A-SERVER.md) · 🇻🇳 [vi](../vi/A2A-SERVER.md) · 🇮🇩 [id](../id/A2A-SERVER.md) · 🇲🇾 [ms](../ms/A2A-SERVER.md) · 🇳🇱 [nl](../nl/A2A-SERVER.md) · 🇵🇱 [pl](../pl/A2A-SERVER.md) · 🇸🇪 [sv](../sv/A2A-SERVER.md) · 🇳🇴 [no](../no/A2A-SERVER.md) · 🇩🇰 [da](../da/A2A-SERVER.md) · 🇫🇮 [fi](../fi/A2A-SERVER.md) · 🇵🇹 [pt](../pt/A2A-SERVER.md) · 🇷🇴 [ro](../ro/A2A-SERVER.md) · 🇭🇺 [hu](../hu/A2A-SERVER.md) · 🇧🇬 [bg](../bg/A2A-SERVER.md) · 🇸🇰 [sk](../sk/A2A-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/A2A-SERVER.md) · 🇮🇱 [he](../he/A2A-SERVER.md) · 🇵🇭 [phi](../phi/A2A-SERVER.md)
+
+---
+
+# 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/i18n/bg/API_REFERENCE.md

@@ -1,12 +1,16 @@
-# Справка за API
-
-🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md)
-
-Пълна справка за всички крайни точки на OmniRoute API.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/API_REFERENCE.md) · 🇪🇸 [es](../es/API_REFERENCE.md) · 🇫🇷 [fr](../fr/API_REFERENCE.md) · 🇩🇪 [de](../de/API_REFERENCE.md) · 🇮🇹 [it](../it/API_REFERENCE.md) · 🇷🇺 [ru](../ru/API_REFERENCE.md) · 🇨🇳 [zh-CN](../zh-CN/API_REFERENCE.md) · 🇯🇵 [ja](../ja/API_REFERENCE.md) · 🇰🇷 [ko](../ko/API_REFERENCE.md) · 🇸🇦 [ar](../ar/API_REFERENCE.md) · 🇮🇳 [in](../in/API_REFERENCE.md) · 🇹🇭 [th](../th/API_REFERENCE.md) · 🇻🇳 [vi](../vi/API_REFERENCE.md) · 🇮🇩 [id](../id/API_REFERENCE.md) · 🇲🇾 [ms](../ms/API_REFERENCE.md) · 🇳🇱 [nl](../nl/API_REFERENCE.md) · 🇵🇱 [pl](../pl/API_REFERENCE.md) · 🇸🇪 [sv](../sv/API_REFERENCE.md) · 🇳🇴 [no](../no/API_REFERENCE.md) · 🇩🇰 [da](../da/API_REFERENCE.md) · 🇫🇮 [fi](../fi/API_REFERENCE.md) · 🇵🇹 [pt](../pt/API_REFERENCE.md) · 🇷🇴 [ro](../ro/API_REFERENCE.md) · 🇭🇺 [hu](../hu/API_REFERENCE.md) · 🇧🇬 [bg](../bg/API_REFERENCE.md) · 🇸🇰 [sk](../sk/API_REFERENCE.md) · 🇺🇦 [uk-UA](../uk-UA/API_REFERENCE.md) · 🇮🇱 [he](../he/API_REFERENCE.md) · 🇵🇭 [phi](../phi/API_REFERENCE.md)
 
 ---
 
-## Съдържание
+# 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)
+
+Complete reference for all OmniRoute API endpoints.
+
+---
+
+## Table of Contents
 
 - [Chat Completions](#chat-completions)
 - [Embeddings](#embeddings)
@@ -20,7 +24,7 @@
 
 ---
 
-## Завършвания на чат
+## Chat Completions
 
 ```bash
 POST /v1/chat/completions
@@ -36,21 +40,21 @@ Content-Type: application/json
 }
 ```
 
-### Персонализирани заглавки
+### Custom Headers
 
-| Заглавка                 | Посока  | Описание                                   |
-| ------------------------ | ------- | ------------------------------------------ |
-| `X-OmniRoute-No-Cache`   | Заявка  | Задайте `true` за заобикаляне на кеша      |
-| `X-OmniRoute-Progress`   | Заявка  | Задайте `true` за събития за прогрес       |
-| `Idempotency-Key`        | Заявка  | Ключ за дедупиране (5s прозорец)           |
-| `X-Request-Id`           | Заявка  | Алтернативен дедуп ключ                    |
-| `X-OmniRoute-Cache`      | Отговор | `HIT` или `MISS` (без поточно предаване)   |
-| `X-OmniRoute-Idempotent` | Отговор | `true` ако е дедупликиран                  |
-| `X-OmniRoute-Progress`   | Отговор | `enabled` ако проследяване на напредъка на |
+| 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 |
 
 ---
 
-## Вграждания
+## Embeddings
 
 ```bash
 POST /v1/embeddings
@@ -63,7 +67,7 @@ Content-Type: application/json
 }
 ```
 
-Налични доставчици: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
 
 ```bash
 # List all embedding models
@@ -72,7 +76,7 @@ GET /v1/embeddings
 
 ---
 
-## Генериране на изображения
+## Image Generation
 
 ```bash
 POST /v1/images/generations
@@ -86,7 +90,7 @@ Content-Type: application/json
 }
 ```
 
-Налични доставчици: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
 
 ```bash
 # List all image models
@@ -95,7 +99,7 @@ GET /v1/images/generations
 
 ---
 
-## Списък с модели
+## List Models
 
 ```bash
 GET /v1/models
@@ -106,22 +110,22 @@ Authorization: Bearer your-api-key
 
 ---
 
-## Крайни точки за съвместимост
+## Compatibility Endpoints
 
-| Метод      | Път                         | Формат                     |
-| ---------- | --------------------------- | -------------------------- |
-| ПУБЛИКАЦИЯ | `/v1/chat/completions`      | OpenAI                     |
-| ПУБЛИКАЦИЯ | `/v1/messages`              | Антропен                   |
-| ПУБЛИКАЦИЯ | `/v1/responses`             | OpenAI отговори            |
-| ПУБЛИКАЦИЯ | `/v1/embeddings`            | OpenAI                     |
-| ПУБЛИКАЦИЯ | `/v1/images/generations`    | OpenAI                     |
-| ВЗЕМЕТЕ    | `/v1/models`                | OpenAI                     |
-| ПУБЛИКАЦИЯ | `/v1/messages/count_tokens` | Антропен                   |
-| ВЗЕМЕТЕ    | `/v1beta/models`            | Близнаци                   |
-| ПУБЛИКАЦИЯ | `/v1beta/models/{...path}`  | Gemini генерира съдържание |
-| ПУБЛИКАЦИЯ | `/v1/api/chat`              | Олама                      |
+| Method | Path                        | Format                 |
+| ------ | --------------------------- | ---------------------- |
+| POST   | `/v1/chat/completions`      | OpenAI                 |
+| POST   | `/v1/messages`              | Anthropic              |
+| POST   | `/v1/responses`             | OpenAI Responses       |
+| POST   | `/v1/embeddings`            | OpenAI                 |
+| POST   | `/v1/images/generations`    | OpenAI                 |
+| GET    | `/v1/models`                | OpenAI                 |
+| POST   | `/v1/messages/count_tokens` | Anthropic              |
+| GET    | `/v1beta/models`            | Gemini                 |
+| POST   | `/v1beta/models/{...path}`  | Gemini generateContent |
+| POST   | `/v1/api/chat`              | Ollama                 |
 
-### Специализирани маршрути на доставчик
+### Dedicated Provider Routes
 
 ```bash
 POST /v1/providers/{provider}/chat/completions
@@ -129,11 +133,11 @@ POST /v1/providers/{provider}/embeddings
 POST /v1/providers/{provider}/images/generations
 ```
 
-Префиксът на доставчика се добавя автоматично, ако липсва. Несъответстващите модели връщат `400`.
+The provider prefix is auto-added if missing. Mismatched models return `400`.
 
 ---
 
-## Семантичен кеш
+## Semantic Cache
 
 ```bash
 # Get cache stats
@@ -143,7 +147,7 @@ GET /api/cache
 DELETE /api/cache
 ```
 
-Пример за отговор:
+Response example:
 
 ```json
 {
@@ -162,154 +166,164 @@ DELETE /api/cache
 
 ---
 
-## Табло за управление и управление
+## Dashboard & Management
 
-### Удостоверяване
+### Authentication
 
-| Крайна точка                  | Метод         | Описание                           |
-| ----------------------------- | ------------- | ---------------------------------- |
-| `/api/auth/login`             | ПУБЛИКАЦИЯ    | Вход                               |
-| `/api/auth/logout`            | ПУБЛИКАЦИЯ    | Изход                              |
-| `/api/settings/require-login` | ВЗЕМИ/ПОСТАВИ | Изисква се превключване на влизане |
+| Endpoint                      | Method  | Description           |
+| ----------------------------- | ------- | --------------------- |
+| `/api/auth/login`             | POST    | Login                 |
+| `/api/auth/logout`            | POST    | Logout                |
+| `/api/settings/require-login` | GET/PUT | Toggle login required |
 
-### Управление на доставчика
+### Provider Management
 
-| Крайна точка                 | Метод                            | Описание                                 |
-| ---------------------------- | -------------------------------- | ---------------------------------------- |
-| `/api/providers`             | ВЗЕМЕТЕ/ПУБЛИКУВАЙТЕ             | Списък / създаване на доставчици         |
-| `/api/providers/[id]`        | ПОЛУЧАВАНЕ/ПОСТАВЯНЕ/ИЗТРИВАНЕ   | Управление на доставчик                  |
-| `/api/providers/[id]/test`   | ПУБЛИКАЦИЯ                       | Тествайте връзката с доставчик           |
-| `/api/providers/[id]/models` | ВЗЕМЕТЕ                          | Избройте модели на доставчици            |
-| `/api/providers/validate`    | ПУБЛИКАЦИЯ                       | Проверка на конфигурацията на доставчика |
-| `/api/provider-nodes*`       | Различни                         | Управление на възел на доставчик         |
-| `/api/provider-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/DELETE | Custom models            |
 
-### OAuth потоци
+### OAuth Flows
 
-| Крайна точка                     | Метод    | Описание                       |
-| -------------------------------- | -------- | ------------------------------ |
-| `/api/oauth/[provider]/[action]` | Различни | Специфичен за доставчика OAuth |
+| Endpoint                         | Method  | Description             |
+| -------------------------------- | ------- | ----------------------- |
+| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth |
 
-### Маршрутизиране и конфигурация
+### Routing & Config
 
-| Крайна точка          | Метод                | Описание                         |
-| --------------------- | -------------------- | -------------------------------- |
-| `/api/models/alias`   | ВЗЕМЕТЕ/ПУБЛИКУВАЙТЕ | Псевдоними на модели             |
-| `/api/models/catalog` | ВЗЕМЕТЕ              | Всички модели по доставчик + тип |
-| `/api/combos*`        | Различни             | Комбо управление                 |
-| `/api/keys*`          | Различни             | Управление на API ключове        |
-| `/api/pricing`        | ВЗЕМЕТЕ              | Моделна цена                     |
+| Endpoint              | Method   | Description                   |
+| --------------------- | -------- | ----------------------------- |
+| `/api/models/alias`   | GET/POST | Model aliases                 |
+| `/api/models/catalog` | GET      | All models by provider + type |
+| `/api/combos*`        | Various  | Combo management              |
+| `/api/keys*`          | Various  | API key management            |
+| `/api/pricing`        | GET      | Model pricing                 |
 
-### Използване и анализ
+### Usage & Analytics
 
-| Крайна точка                | Метод   | Описание                |
-| --------------------------- | ------- | ----------------------- |
-| `/api/usage/history`        | ВЗЕМЕТЕ | История на използването |
-| `/api/usage/logs`           | ВЗЕМЕТЕ | Дневници за използване  |
-| `/api/usage/request-logs`   | ВЗЕМЕТЕ | Дневници на ниво заявка |
-| `/api/usage/[connectionId]` | ВЗЕМЕТЕ | Използване на връзка    |
+| Endpoint                    | Method | Description          |
+| --------------------------- | ------ | -------------------- |
+| `/api/usage/history`        | GET    | Usage history        |
+| `/api/usage/logs`           | GET    | Usage logs           |
+| `/api/usage/request-logs`   | GET    | Request-level logs   |
+| `/api/usage/[connectionId]` | GET    | Per-connection usage |
 
-### Настройки
+### Settings
 
-| Крайна точка                    | Метод         | Описание                               |
-| ------------------------------- | ------------- | -------------------------------------- |
-| `/api/settings`                 | ВЗЕМИ/ПОСТАВИ | Общи настройки                         |
-| `/api/settings/proxy`           | ВЗЕМИ/ПОСТАВИ | Конфигурация на мрежов прокси          |
-| `/api/settings/proxy/test`      | ПУБЛИКАЦИЯ    | Тествайте прокси връзката              |
-| `/api/settings/ip-filter`       | ВЗЕМИ/ПОСТАВИ | Списък с разрешени/блокирани IP адреси |
-| `/api/settings/thinking-budget` | ВЗЕМИ/ПОСТАВИ | Бюджет на жетон за разсъждение         |
-| `/api/settings/system-prompt`   | ВЗЕМИ/ПОСТАВИ | Глобална системна подкана              |
+| 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   |
 
-### Мониторинг
+### Monitoring
 
-| Крайна точка             | Метод                | Описание                      |
-| ------------------------ | -------------------- | ----------------------------- |
-| `/api/sessions`          | ВЗЕМЕТЕ              | Проследяване на активна сесия |
-| `/api/rate-limits`       | ВЗЕМЕТЕ              | Лимити за лихви по сметка     |
-| `/api/monitoring/health` | ВЗЕМЕТЕ              | Здравна проверка              |
-| `/api/cache`             | ПОЛУЧАВАНЕ/ИЗТРИВАНЕ | Кеш статистики / изчистване   |
+| 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     |
 
-### Архивиране и експортиране/импортиране
+### Backup & Export/Import
 
-| Крайна точка                | Метод      | Описание                                         |
-| --------------------------- | ---------- | ------------------------------------------------ |
-| `/api/db-backups`           | ВЗЕМЕТЕ    | Избройте наличните резервни копия                |
-| `/api/db-backups`           | ПОСТАВЕТЕ  | Създайте ръчно архивиране                        |
-| `/api/db-backups`           | ПУБЛИКАЦИЯ | Възстановяване от конкретен архив                |
-| `/api/db-backups/export`    | ВЗЕМЕТЕ    | Изтегляне на база данни като .sqlite файл        |
-| `/api/db-backups/import`    | ПУБЛИКАЦИЯ | Качете .sqlite файл, за да замените базата данни |
-| `/api/db-backups/exportAll` | ВЗЕМЕТЕ    | Изтеглете пълното архивиране като .tar.gz архив  |
+| Endpoint                    | Method | Description                             |
+| --------------------------- | ------ | --------------------------------------- |
+| `/api/db-backups`           | GET    | List available backups                  |
+| `/api/db-backups`           | PUT    | Create a manual backup                  |
+| `/api/db-backups`           | POST   | Restore from a specific backup          |
+| `/api/db-backups/export`    | GET    | Download database as .sqlite file       |
+| `/api/db-backups/import`    | POST   | Upload .sqlite file to replace database |
+| `/api/db-backups/exportAll` | GET    | Download full backup as .tar.gz archive |
 
-### Облачно синхронизиране
+### Cloud Sync
 
-| Крайна точка           | Метод      | Описание                           |
-| ---------------------- | ---------- | ---------------------------------- |
-| `/api/sync/cloud`      | Различни   | Операции за синхронизиране в облак |
-| `/api/sync/initialize` | ПУБЛИКАЦИЯ | Инициализиране на синхронизиране   |
-| `/api/cloud/*`         | Различни   | Облачно управление                 |
+| Endpoint               | Method  | Description           |
+| ---------------------- | ------- | --------------------- |
+| `/api/sync/cloud`      | Various | Cloud sync operations |
+| `/api/sync/initialize` | POST    | Initialize sync       |
+| `/api/cloud/*`         | Various | Cloud management      |
 
-### CLI инструменти
+### CLI Tools
 
-| Крайна точка                       | Метод   | Описание               |
-| ---------------------------------- | ------- | ---------------------- |
-| `/api/cli-tools/claude-settings`   | ВЗЕМЕТЕ | Клод CLI състояние     |
-| `/api/cli-tools/codex-settings`    | ВЗЕМЕТЕ | Codex CLI състояние    |
-| `/api/cli-tools/droid-settings`    | ВЗЕМЕТЕ | Droid CLI състояние    |
-| `/api/cli-tools/openclaw-settings` | ВЗЕМЕТЕ | OpenClaw CLI състояние |
-| `/api/cli-tools/runtime/[toolId]`  | ВЗЕМЕТЕ | Generic CLI runtime    |
+| Endpoint                           | Method | Description         |
+| ---------------------------------- | ------ | ------------------- |
+| `/api/cli-tools/claude-settings`   | GET    | Claude CLI status   |
+| `/api/cli-tools/codex-settings`    | GET    | Codex CLI status    |
+| `/api/cli-tools/droid-settings`    | GET    | Droid CLI status    |
+| `/api/cli-tools/openclaw-settings` | GET    | OpenClaw CLI status |
+| `/api/cli-tools/runtime/[toolId]`  | GET    | Generic CLI runtime |
 
-CLI отговорите включват: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
+CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
 
-### Устойчивост и ограничения на скоростта
+### ACP Agents
 
-| Крайна точка            | Метод         | Описание                                      |
-| ----------------------- | ------------- | --------------------------------------------- |
-| `/api/resilience`       | ВЗЕМИ/ПОСТАВИ | Вземете/актуализирайте профили за устойчивост |
-| `/api/resilience/reset` | ПУБЛИКАЦИЯ    | Нулиране на прекъсвачи                        |
-| `/api/rate-limits`      | ВЗЕМЕТЕ       | Състояние на ограничение на лимита по сметка  |
-| `/api/rate-limit`       | ВЗЕМЕТЕ       | Конфигурация на глобален лимит на скоростта   |
+| 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).
 
-| Крайна точка | Метод                | Описание                                |
-| ------------ | -------------------- | --------------------------------------- |
-| `/api/evals` | ВЗЕМЕТЕ/ПУБЛИКУВАЙТЕ | Избройте eval пакети / изпълнете оценка |
+### 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 |
 
-| Крайна точка    | Метод                            | Описание                                  |
-| --------------- | -------------------------------- | ----------------------------------------- |
-| `/api/policies` | ПОЛУЧАВАНЕ/ПУБЛИКУВАНЕ/ИЗТРИВАНЕ | Управление на правилата за маршрутизиране |
+### Evals
 
-### Съответствие
+| Endpoint     | Method   | Description                       |
+| ------------ | -------- | --------------------------------- |
+| `/api/evals` | GET/POST | List eval suites / run evaluation |
 
-| Крайна точка                | Метод   | Описание                                           |
-| --------------------------- | ------- | -------------------------------------------------- |
-| `/api/compliance/audit-log` | ВЗЕМЕТЕ | Дневник за проверка на съответствието (последно N) |
+### Policies
 
-### v1beta (съвместим с Gemini)
+| Endpoint        | Method          | Description             |
+| --------------- | --------------- | ----------------------- |
+| `/api/policies` | GET/POST/DELETE | Manage routing policies |
 
-| Крайна точка               | Метод      | Описание                              |
-| -------------------------- | ---------- | ------------------------------------- |
-| `/v1beta/models`           | ВЗЕМЕТЕ    | Избройте модели във формат Gemini     |
-| `/v1beta/models/{...path}` | ПУБЛИКАЦИЯ | Gemini `generateContent` крайна точка |
+### Compliance
 
-Тези крайни точки отразяват API формата на Gemini за клиенти, които очакват естествена съвместимост с Gemini SDK.
+| Endpoint                    | Method | Description                   |
+| --------------------------- | ------ | ----------------------------- |
+| `/api/compliance/audit-log` | GET    | Compliance audit log (last N) |
 
-### Вътрешен/системен API
+### v1beta (Gemini-Compatible)
 
-| Крайна точка    | Метод      | Описание                                                                       |
-| --------------- | ---------- | ------------------------------------------------------------------------------ |
-| `/api/init`     | ВЗЕМЕТЕ    | Проверка за инициализация на приложението (използва се при първото стартиране) |
-| `/api/tags`     | ВЗЕМЕТЕ    | Тагове за модели, съвместими с Ollama (за клиенти на Ollama)                   |
-| `/api/restart`  | ПУБЛИКАЦИЯ | Задейства грациозно рестартиране на сървъра                                    |
-| `/api/shutdown` | ПУБЛИКАЦИЯ | Задействайте грациозно изключване на сървъра                                   |
+| Endpoint                   | Method | Description                       |
+| -------------------------- | ------ | --------------------------------- |
+| `/v1beta/models`           | GET    | List models in Gemini format      |
+| `/v1beta/models/{...path}` | POST   | Gemini `generateContent` endpoint |
 
-> **Забележка:** Тези крайни точки се използват вътрешно от системата или за съвместимост с клиента Ollama. Те обикновено не се извикват от крайните потребители.
+These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility.
+
+### Internal / System APIs
+
+| Endpoint        | Method | Description                                          |
+| --------------- | ------ | ---------------------------------------------------- |
+| `/api/init`     | GET    | Application initialization check (used on first run) |
+| `/api/tags`     | GET    | Ollama-compatible model tags (for Ollama clients)    |
+| `/api/restart`  | POST   | Trigger graceful server restart                      |
+| `/api/shutdown` | POST   | Trigger graceful server shutdown                     |
+
+> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users.
 
 ---
 
-## Аудио транскрипция
+## Audio Transcription
 
 ```bash
 POST /v1/audio/transcriptions
@@ -317,9 +331,9 @@ Authorization: Bearer your-api-key
 Content-Type: multipart/form-data
 ```
 
-Транскрибирайте аудио файлове с помощта на Deepgram или AssemblyAI.
+Transcribe audio files using Deepgram or AssemblyAI.
 
-**Заявка:**
+**Request:**
 
 ```bash
 curl -X POST http://localhost:20128/v1/audio/transcriptions \
@@ -328,7 +342,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
   -F "model=deepgram/nova-3"
 ```
 
-**Отговор:**
+**Response:**
 
 ```json
 {
@@ -339,15 +353,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
 }
 ```
 
-**Поддържани доставчици:** `deepgram/nova-3`, `assemblyai/best`.
+**Supported providers:** `deepgram/nova-3`, `assemblyai/best`.
 
-**Поддържани формати:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
 
 ---
 
-## Съвместимост с Ollama
+## Ollama Compatibility
 
-За клиенти, които използват API формат на Ollama:
+For clients that use Ollama's API format:
 
 ```bash
 # Chat endpoint (Ollama format)
@@ -357,18 +371,18 @@ POST /v1/api/chat
 GET /api/tags
 ```
 
-Заявките се превеждат автоматично между Ollama и вътрешни формати.
+Requests are automatically translated between Ollama and internal formats.
 
 ---
 
-## Телеметрия
+## Telemetry
 
 ```bash
 # Get latency telemetry summary (p50/p95/p99 per provider)
 GET /api/telemetry/summary
 ```
 
-**Отговор:**
+**Response:**
 
 ```json
 {
@@ -381,7 +395,7 @@ GET /api/telemetry/summary
 
 ---
 
-## Бюджет
+## Budget
 
 ```bash
 # Get budget status for all API keys
@@ -400,7 +414,7 @@ Content-Type: application/json
 
 ---
 
-## Наличност на модела
+## Model Availability
 
 ```bash
 # Get real-time model availability across all providers
@@ -417,25 +431,25 @@ Content-Type: application/json
 
 ---
 
-## Обработка на заявка
+## Request Processing
 
-1. Клиентът изпраща заявка до `/v1/*`
-2. Обработчикът на маршрута извиква `handleChat`, `handleEmbedding`, `handleAudioTranscription` или `handleImageGeneration`
-3. Моделът е разрешен (директен доставчик/модел или псевдоним/комбо)
-4. Идентификационни данни, избрани от локална база данни с филтриране на наличността на акаунта
-5. За чат: `handleChatCore` — откриване на формат, превод, проверка на кеша, проверка на идемпотентност
-6. Изпълнителят на доставчика изпраща заявка нагоре по веригата
-7. Отговор, преведен обратно във формат на клиента (чат) или върнат такъв, какъвто е (вграждания/изображения/аудио)
-8. Записано използване/регистриране
-9. Резервният вариант се прилага при грешки според комбо правилата
+1. Client sends request to `/v1/*`
+2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration`
+3. Model is resolved (direct provider/model or alias/combo)
+4. Credentials selected from local DB with account availability filtering
+5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check
+6. Provider executor sends upstream request
+7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio)
+8. Usage/logging recorded
+9. Fallback applies on errors according to combo rules
 
-Пълна справка за архитектурата: [link](ARCHITECTURE.md)
+Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md)
 
 ---
 
-## Удостоверяване
+## Authentication
 
-- Маршрутите на таблото за управление (`/dashboard/*`) използват бисквитка `auth_token`
-- Входът използва запазен хеш на паролата; връщане към `INITIAL_PASSWORD`
-- `requireLogin` превключваем чрез `/api/settings/require-login`
-- `/v1/*` маршрутите по избор изискват Bearer API ключ, когато `REQUIRE_API_KEY=true`
+- Dashboard routes (`/dashboard/*`) use `auth_token` cookie
+- Login uses saved password hash; fallback to `INITIAL_PASSWORD`
+- `requireLogin` toggleable via `/api/settings/require-login`
+- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true`

docs/i18n/bg/ARCHITECTURE.md

@@ -1,71 +1,75 @@
-# Архитектура OmniRoute
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/ARCHITECTURE.md) · 🇪🇸 [es](../es/ARCHITECTURE.md) · 🇫🇷 [fr](../fr/ARCHITECTURE.md) · 🇩🇪 [de](../de/ARCHITECTURE.md) · 🇮🇹 [it](../it/ARCHITECTURE.md) · 🇷🇺 [ru](../ru/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../zh-CN/ARCHITECTURE.md) · 🇯🇵 [ja](../ja/ARCHITECTURE.md) · 🇰🇷 [ko](../ko/ARCHITECTURE.md) · 🇸🇦 [ar](../ar/ARCHITECTURE.md) · 🇮🇳 [in](../in/ARCHITECTURE.md) · 🇹🇭 [th](../th/ARCHITECTURE.md) · 🇻🇳 [vi](../vi/ARCHITECTURE.md) · 🇮🇩 [id](../id/ARCHITECTURE.md) · 🇲🇾 [ms](../ms/ARCHITECTURE.md) · 🇳🇱 [nl](../nl/ARCHITECTURE.md) · 🇵🇱 [pl](../pl/ARCHITECTURE.md) · 🇸🇪 [sv](../sv/ARCHITECTURE.md) · 🇳🇴 [no](../no/ARCHITECTURE.md) · 🇩🇰 [da](../da/ARCHITECTURE.md) · 🇫🇮 [fi](../fi/ARCHITECTURE.md) · 🇵🇹 [pt](../pt/ARCHITECTURE.md) · 🇷🇴 [ro](../ro/ARCHITECTURE.md) · 🇭🇺 [hu](../hu/ARCHITECTURE.md) · 🇧🇬 [bg](../bg/ARCHITECTURE.md) · 🇸🇰 [sk](../sk/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../uk-UA/ARCHITECTURE.md) · 🇮🇱 [he](../he/ARCHITECTURE.md) · 🇵🇭 [phi](../phi/ARCHITECTURE.md)
 
-🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md)
+---
 
-_Последна актуализация: 2026-02-18_
+# OmniRoute Architecture
 
-## Резюме
+🌐 **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)
 
-OmniRoute е локален AI маршрутизиращ шлюз и табло за управление, изградено на Next.js.
-Той осигурява една крайна точка, съвместима с OpenAI (`/v1/*`) и маршрутизира трафика през множество доставчици нагоре по веригата с превод, резервен вариант, опресняване на токени и проследяване на използването.
+_Last updated: 2026-03-04_
 
-Основни възможности:
+## Executive Summary
 
-- OpenAI-съвместима API повърхност за CLI/инструменти (28 доставчици)
-- Превод на заявка/отговор във форматите на доставчика
-- Резервна комбинация от модели (последователност от няколко модела)
-- Резервен вариант на ниво акаунт (мулти акаунт на доставчик)
-- OAuth + API-ключ управление на връзката на доставчика
-- Генериране на вграждане чрез `/v1/embeddings` (6 доставчика, 9 модела)
-- Генериране на изображения чрез `/v1/images/generations` (4 доставчика, 9 модела)
-- Мислен синтактичен анализ на етикет (`<think>...</think>`) за модели на разсъждение
-- Дезинфекция на отговора за стриктна съвместимост с OpenAI SDK
-- Нормализиране на ролята (разработчик→система, система→потребител) за съвместимост между доставчици
-- Структурирано преобразуване на изход (json_schema → Gemini responseSchema)
-- Локална устойчивост за доставчици, ключове, псевдоними, комбинации, настройки, ценообразуване
-- Проследяване на използване/разходи и регистриране на заявки
-- Допълнителна облачна синхронизация за синхронизиране на множество устройства/състояние
-- Списък с разрешени/блокирани IP адреси за контрол на достъпа до API
-- Мислещо управление на бюджета (преминаване/автоматично/персонализирано/адаптивно)
-- Бързо инжектиране на глобалната система
-- Проследяване на сесии и пръстови отпечатъци
-- Подобрено ограничаване на скоростта за всеки акаунт със специфични за доставчика профили
-- Модел на прекъсвача за устойчивост на доставчика
-- Анти-гръмотевична стадна защита с mutex заключване
-- Кеш за дедупликация на заявки, базиран на подпис
-- Слой на домейна: наличност на модела, правила за разходите, резервна политика, политика за блокиране
-- Устойчивост на състоянието на домейна (кеш за запис на SQLite за резервни варианти, бюджети, блокировки, прекъсвачи на верига)
-- Механизъм за правила за централизирана оценка на заявката (заключване → бюджет → резервен)
-- Заявка за телеметрия с p50/p95/p99 агрегиране на латентност
-- ID на корелация (X-Request-Id) за проследяване от край до край
-- Регистриране на одит за съответствие с отказ за всеки API ключ
-- Eval framework за осигуряване на качеството на LLM
-- Resilience UI табло със статус на прекъсвача в реално време
-- Модулни OAuth доставчици (12 отделни модула под `src/lib/oauth/providers/`)
+OmniRoute is a local AI routing gateway and dashboard built on Next.js.
+It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
 
-Основен модел на изпълнение:
+Core capabilities:
 
-- Маршрутите на приложението Next.js под `src/app/api/*` прилагат както API на таблото за управление, така и API за съвместимост
-- Споделено SSE/маршрутизиращо ядро в `src/sse/*` + `open-sse/*` обработва изпълнението на доставчика, превода, стрийминг, резервен вариант и използване
+- OpenAI-compatible API surface for CLI/tools (28 providers)
+- Request/response translation across provider formats
+- Model combo fallback (multi-model sequence)
+- Account-level fallback (multi-account per provider)
+- OAuth + API-key provider connection management
+- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
+- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Think tag parsing (`<think>...</think>`) for reasoning models
+- Response sanitization for strict OpenAI SDK compatibility
+- Role normalization (developer→system, system→user) for cross-provider compatibility
+- Structured output conversion (json_schema → Gemini responseSchema)
+- Local persistence for providers, keys, aliases, combos, settings, pricing
+- Usage/cost tracking and request logging
+- Optional cloud sync for multi-device/state sync
+- IP allowlist/blocklist for API access control
+- Thinking budget management (passthrough/auto/custom/adaptive)
+- Global system prompt injection
+- Session tracking and fingerprinting
+- Per-account enhanced rate limiting with provider-specific profiles
+- Circuit breaker pattern for provider resilience
+- Anti-thundering herd protection with mutex locking
+- Signature-based request deduplication cache
+- Domain layer: model availability, cost rules, fallback policy, lockout policy
+- 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
+- Correlation ID (X-Request-Id) for end-to-end tracing
+- Compliance audit logging with opt-out per API key
+- Eval framework for LLM quality assurance
+- Resilience UI dashboard with real-time circuit breaker status
+- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`)
 
-## Обхват и граници
+Primary runtime model:
 
-### В обхват
+- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
+- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
 
-- Време за изпълнение на локален шлюз
-- API за управление на таблото
-- Удостоверяване на доставчика и опресняване на токена
-- Заявка за превод и SSE стрийминг
-- Локално състояние + постоянство на използване
-- Допълнителна синхронизация в облака
+## Scope and Boundaries
 
-### Извън обхвата
+### In Scope
 
-- Внедряване на облачна услуга зад `NEXT_PUBLIC_CLOUD_URL`
-- SLA/контролна равнина на доставчика извън локалния процес
-- Самите външни CLI двоични файлове (Claude CLI, Codex CLI и т.н.)
+- Local gateway runtime
+- Dashboard management APIs
+- Provider authentication and token refresh
+- Request translation and SSE streaming
+- Local state + usage persistence
+- Optional cloud sync orchestration
 
-## Системен контекст на високо ниво
+### Out of Scope
+
+- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
+- Provider SLA/control plane outside local process
+- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
+
+## High-Level System Context
 
 ```mermaid
 flowchart LR
@@ -81,8 +85,8 @@ 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]
@@ -113,151 +117,152 @@ flowchart LR
     DASH --> CLOUD
 ```
 
-## Основни компоненти по време на изпълнение
+## Core Runtime Components
 
-## 1) API и слой за маршрутизиране (Маршрути на приложението Next.js)
+## 1) API and Routing Layer (Next.js App Routes)
 
-Основни директории:
+Main directories:
 
-- `src/app/api/v1/*` и `src/app/api/v1beta/*` за API за съвместимост
-- `src/app/api/*` за API за управление/конфигуриране
-- Следващото пренаписване в `next.config.mjs` преобразува `/v1/*` в `/api/v1/*`
+- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
+- `src/app/api/*` for management/configuration APIs
+- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
 
-Важни пътища за съвместимост:
+Important compatibility routes:
 
 - `src/app/api/v1/chat/completions/route.ts`
 - `src/app/api/v1/messages/route.ts`
 - `src/app/api/v1/responses/route.ts`
-- `src/app/api/v1/models/route.ts` — включва потребителски модели с `custom: true`
-- `src/app/api/v1/embeddings/route.ts` — генериране на вграждане (6 доставчика)
-- `src/app/api/v1/images/generations/route.ts` — генериране на изображения (4+ доставчици, вкл. Antigravity/Nebius)
+- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`
+- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)
+- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)
 - `src/app/api/v1/messages/count_tokens/route.ts`
-- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — специален чат за всеки доставчик
-- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — специални вграждания за всеки доставчик
-- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — специални изображения за всеки доставчик
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images
 - `src/app/api/v1beta/models/route.ts`
 - `src/app/api/v1beta/models/[...path]/route.ts`
 
-Домейни за управление:
+Management domains:
 
-- Удостоверяване/настройки: `src/app/api/auth/*`, `src/app/api/settings/*`
-- Доставчици/връзки: `src/app/api/providers*`
-- Възли на доставчик: `src/app/api/provider-nodes*`
-- Персонализирани модели: `src/app/api/provider-models` (GET/POST/DELETE)
-- Каталог с модели: `src/app/api/models/catalog` (GET)
-- Прокси конфигурация: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
+- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
+- 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/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/*`
-- Ключове/псевдоними/комбота/цени: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
-- Използване: `src/app/api/usage/*`
-- Синхронизиране/облак: `src/app/api/sync/*`, `src/app/api/cloud/*`
-- Помощни инструменти за CLI: `src/app/api/cli-tools/*`
-- IP филтър: `src/app/api/settings/ip-filter` (GET/PUT)
-- Бюджет за мислене: `src/app/api/settings/thinking-budget` (GET/PUT)
-- Системна подкана: `src/app/api/settings/system-prompt` (GET/PUT)
-- Сесии: `src/app/api/sessions` (GET)
-- Ограничения на скоростта: `src/app/api/rate-limits` (GET)
-- Устойчивост: `src/app/api/resilience` (GET/PATCH) — профили на доставчик, прекъсвач, състояние на ограничение на скоростта
-- Нулиране на устойчивостта: `src/app/api/resilience/reset` (POST) — нулиране на прекъсвачи + охлаждане
-- Кеш статистики: `src/app/api/cache/stats` (ПОЛУЧАВАНЕ/ИЗТРИВАНЕ)
-- Наличност на модела: `src/app/api/models/availability` (GET/POST)
-- Телеметрия: `src/app/api/telemetry/summary` (GET)
-- Бюджет: `src/app/api/usage/budget` (GET/POST)
-- Резервни вериги: `src/app/api/fallback/chains` (GET/POST/DELETE)
-- Одит за съответствие: `src/app/api/compliance/audit-log` (GET)
-- Стойности: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
-- Правила: `src/app/api/policies` (GET/POST)
+- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
+- Usage: `src/app/api/usage/*`
+- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
+- CLI tooling helpers: `src/app/api/cli-tools/*`
+- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)
+- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)
+- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)
+- Sessions: `src/app/api/sessions` (GET)
+- Rate limits: `src/app/api/rate-limits` (GET)
+- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns
+- Cache stats: `src/app/api/cache/stats` (GET/DELETE)
+- Model availability: `src/app/api/models/availability` (GET/POST)
+- Telemetry: `src/app/api/telemetry/summary` (GET)
+- Budget: `src/app/api/usage/budget` (GET/POST)
+- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET)
+- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
+- Policies: `src/app/api/policies` (GET/POST)
 
-## 2) SSE + ядро за превод
+## 2) SSE + Translation Core
 
-Основни модули на потока:
+Main flow modules:
 
-- Запис: `src/sse/handlers/chat.ts`
-- Основна оркестрация: `open-sse/handlers/chatCore.ts`
-- Адаптери за изпълнение на доставчика: `open-sse/executors/*`
-- Откриване на формат/конфигурация на доставчика: `open-sse/services/provider.ts`
-- Разбор/разрешаване на модела: `src/sse/services/model.ts`, `open-sse/services/model.ts`
-- Резервна логика на акаунта: `open-sse/services/accountFallback.ts`
-- Регистър на преводите: `open-sse/translator/index.ts`
-- Трансформации на потока: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
-- Извличане/нормализиране на използването: `open-sse/utils/usageTracking.ts`
-- Мислен анализатор на етикети: `open-sse/utils/thinkTagParser.ts`
-- Манипулатор за вграждане: `open-sse/handlers/embeddings.ts`
-- Регистър на доставчика на вграждане: `open-sse/config/embeddingRegistry.ts`
-- Манипулатор за генериране на изображения: `open-sse/handlers/imageGeneration.ts`
-- Регистър на доставчика на изображения: `open-sse/config/imageRegistry.ts`
-- Саниране на отговора: `open-sse/handlers/responseSanitizer.ts`
-- Нормализация на ролята: `open-sse/services/roleNormalizer.ts`
+- Entry: `src/sse/handlers/chat.ts`
+- Core orchestration: `open-sse/handlers/chatCore.ts`
+- Provider execution adapters: `open-sse/executors/*`
+- Format detection/provider config: `open-sse/services/provider.ts`
+- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
+- Account fallback logic: `open-sse/services/accountFallback.ts`
+- Translation registry: `open-sse/translator/index.ts`
+- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
+- Think tag parser: `open-sse/utils/thinkTagParser.ts`
+- Embedding handler: `open-sse/handlers/embeddings.ts`
+- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
+- Image generation handler: `open-sse/handlers/imageGeneration.ts`
+- Image provider registry: `open-sse/config/imageRegistry.ts`
+- Response sanitization: `open-sse/handlers/responseSanitizer.ts`
+- Role normalization: `open-sse/services/roleNormalizer.ts`
 
-Услуги (бизнес логика):
+Services (business logic):
 
-- Избор/точкуване на акаунт: `open-sse/services/accountSelector.ts`
-- Управление на жизнения цикъл на контекста: `open-sse/services/contextManager.ts`
-- Налагане на IP филтър: `open-sse/services/ipFilter.ts`
-- Проследяване на сесии: `open-sse/services/sessionManager.ts`
-- Искане за дедупликация: `open-sse/services/signatureCache.ts`
-- Системно бързо инжектиране: `open-sse/services/systemPrompt.ts`
-- Мислещо управление на бюджета: `open-sse/services/thinkingBudget.ts`
-- Маршрутизиране на модела със заместващи знаци: `open-sse/services/wildcardRouter.ts`
-- Управление на лимита на скоростта: `open-sse/services/rateLimitManager.ts`
-- Прекъсвач: `open-sse/services/circuitBreaker.ts`
+- Account selection/scoring: `open-sse/services/accountSelector.ts`
+- Context lifecycle management: `open-sse/services/contextManager.ts`
+- IP filter enforcement: `open-sse/services/ipFilter.ts`
+- Session tracking: `open-sse/services/sessionManager.ts`
+- Request deduplication: `open-sse/services/signatureCache.ts`
+- System prompt injection: `open-sse/services/systemPrompt.ts`
+- Thinking budget management: `open-sse/services/thinkingBudget.ts`
+- Wildcard model routing: `open-sse/services/wildcardRouter.ts`
+- Rate limit management: `open-sse/services/rateLimitManager.ts`
+- Circuit breaker: `open-sse/services/circuitBreaker.ts`
 
-Модули на ниво домейн:
+Domain layer modules:
 
-- Наличност на модела: `src/lib/domain/modelAvailability.ts`
-- Правила/бюджети за разходите: `src/lib/domain/costRules.ts`
-- Резервна политика: `src/lib/domain/fallbackPolicy.ts`
-- Комбо резолвер: `src/lib/domain/comboResolver.ts`
-- Правила за блокиране: `src/lib/domain/lockoutPolicy.ts`
-- Механизъм за правила: `src/domain/policyEngine.ts` — централизирано блокиране → бюджет → резервна оценка
-- Каталог с кодове за грешки: `src/lib/domain/errorCodes.ts`
-- ID на заявката: `src/lib/domain/requestId.ts`
-- Време за изчакване на извличане: `src/lib/domain/fetchTimeout.ts`
-- Заявка за телеметрия: `src/lib/domain/requestTelemetry.ts`
-- Съответствие/одит: `src/lib/domain/compliance/index.ts`
-- Евал бегач: `src/lib/domain/evalRunner.ts`
-- Устойчивост на състоянието на домейна: `src/lib/db/domainState.ts` — SQLite CRUD за резервни вериги, бюджети, история на разходите, състояние на блокиране, прекъсвачи
+- Model availability: `src/lib/domain/modelAvailability.ts`
+- Cost rules/budgets: `src/lib/domain/costRules.ts`
+- Fallback policy: `src/lib/domain/fallbackPolicy.ts`
+- Combo resolver: `src/lib/domain/comboResolver.ts`
+- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
+- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
+- Error codes catalog: `src/lib/domain/errorCodes.ts`
+- Request ID: `src/lib/domain/requestId.ts`
+- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
+- Request telemetry: `src/lib/domain/requestTelemetry.ts`
+- Compliance/audit: `src/lib/domain/compliance/index.ts`
+- Eval runner: `src/lib/domain/evalRunner.ts`
+- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
 
-Модули за доставчик на OAuth (12 отделни файла под `src/lib/oauth/providers/`):
+OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
-- Индекс на регистъра: `src/lib/oauth/providers/index.ts`
-- Индивидуални доставчици: `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`
-- Тънка обвивка: `src/lib/oauth/providers.ts` — повторно експортиране от отделни модули
+- 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`
+- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
-## 3) Слой за устойчивост
+## 3) Persistence Layer
 
-Основно състояние DB:
+Primary state DB (SQLite):
 
-- `src/lib/localDb.ts`
-- файл: `${DATA_DIR}/db.json` (или `$XDG_CONFIG_HOME/omniroute/db.json`, когато е зададено, в противен случай `~/.omniroute/db.json`)
-- обекти: providerConnections, providerNodes, modelAliases, комбинации, apiKeys, настройки, ценообразуване, **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**
 
-DB за използване:
+Usage persistence:
 
-- `src/lib/usageDb.ts`
-- файлове: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
-- следва същата основна политика за директория като `localDb` (`DATA_DIR`, след това `XDG_CONFIG_HOME/omniroute`, когато е зададено)
-- разложен на фокусирани подмодули: `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
 
-DB на състоянието на домейна (SQLite):
+Domain State DB (SQLite):
 
-- `src/lib/db/domainState.ts` — CRUD операции за състояние на домейна
-- Таблици (създадени в `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
-- Модел на кеша за запис: Картите в паметта са авторитетни по време на изпълнение; мутациите се записват синхронно в SQLite; състоянието се възстановява от DB при студен старт
+- `src/lib/db/domainState.ts` — CRUD operations for domain state
+- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
+- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
 
-## 4) Удостоверяване + повърхности за сигурност
+## 4) Auth + Security Surfaces
 
-- Удостоверяване на бисквитките на таблото за управление: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
-- Генериране/проверка на API ключ: `src/shared/utils/apiKey.ts`
-- Тайните на доставчика се запазват в `providerConnections` записи
-- Поддръжка на изходящ прокси чрез `open-sse/utils/proxyFetch.ts` (env vars) и `open-sse/utils/networkProxy.ts` (конфигурируем за всеки доставчик или глобално)
+- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
+- API key generation/verification: `src/shared/utils/apiKey.ts`
+- Provider secrets persisted in `providerConnections` entries
+- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
 
-## 5) Синхронизиране в облак
+## 5) Cloud Sync
 
-- Инициализация на планировчика: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
-- Периодична задача: `src/shared/services/cloudSyncScheduler.ts`
-- Контролен маршрут: `src/app/api/sync/cloud/route.ts`
+- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
+- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Control route: `src/app/api/sync/cloud/route.ts`
 
-## Жизнен цикъл на заявка (`/v1/chat/completions`)
+## Request Lifecycle (`/v1/chat/completions`)
 
 ```mermaid
 sequenceDiagram
@@ -304,7 +309,7 @@ sequenceDiagram
     Stream->>Usage: extract usage + persist history/log
 ```
 
-## Комбо + Резервен поток на акаунт
+## Combo + Account Fallback Flow
 
 ```mermaid
 flowchart TD
@@ -334,9 +339,9 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-Резервните решения се управляват от `open-sse/services/accountFallback.ts` с помощта на кодове за състояние и евристика за съобщения за грешка.
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics.
 
-## Жизнен цикъл на внедряване на OAuth и опресняване на токени
+## OAuth Onboarding and Token Refresh Lifecycle
 
 ```mermaid
 sequenceDiagram
@@ -366,9 +371,9 @@ sequenceDiagram
     Test-->>UI: validation result
 ```
 
-Опресняването по време на трафик на живо се изпълнява вътре в `open-sse/handlers/chatCore.ts` чрез изпълнител `refreshCredentials()`.
+Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
 
-## Жизнен цикъл на Cloud Sync (Активиране / Синхронизиране / Деактивиране)
+## Cloud Sync Lifecycle (Enable / Sync / Disable)
 
 ```mermaid
 sequenceDiagram
@@ -400,9 +405,9 @@ sequenceDiagram
     Sync-->>UI: disabled
 ```
 
-Периодичното синхронизиране се задейства от `CloudSyncScheduler`, когато облакът е активиран.
+Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
 
-## Модел на данни и карта за съхранение
+## Data Model and Storage Map
 
 ```mermaid
 erDiagram
@@ -503,14 +508,14 @@ erDiagram
     }
 ```
 
-Файлове за физическо съхранение:
+Physical storage files:
 
-- основно състояние: `${DATA_DIR}/db.json` (или `$XDG_CONFIG_HOME/omniroute/db.json`, когато е зададено, в противен случай `~/.omniroute/db.json`)
-- статистика за използване: `${DATA_DIR}/usage.json`
-- Редове на заявката: `${DATA_DIR}/log.txt`
-- незадължителни сесии за преводач/заявка за отстраняване на грешки: `<repo>/logs/...`
+- 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
 
 ```mermaid
 flowchart LR
@@ -522,8 +527,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]
@@ -541,241 +546,242 @@ flowchart LR
     Next --> SyncCloud
 ```
 
-## Съпоставяне на модул (критично за вземане на решения)
+## Module Mapping (Decision-Critical)
 
-### Модули за маршрут и API
+### Route and API Modules
 
-- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API за съвместимост
-- `src/app/api/v1/providers/[provider]/*`: специални маршрути за всеки доставчик (чат, вграждания, изображения)
-- `src/app/api/providers*`: доставчик CRUD, валидиране, тестване
-- `src/app/api/provider-nodes*`: персонализирано съвместимо управление на възли
-- `src/app/api/provider-models`: персонализирано управление на модела (CRUD)
-- `src/app/api/models/catalog`: пълен модел каталог API (всички типове групирани по доставчик)
-- `src/app/api/oauth/*`: OAuth/код на устройство протича
-- `src/app/api/keys*`: жизнен цикъл на локален API ключ
-- `src/app/api/models/alias`: управление на псевдоними
-- `src/app/api/combos*`: резервно комбо управление
-- `src/app/api/pricing`: ценообразуване отменя за изчисляване на разходите
-- `src/app/api/settings/proxy`: конфигурация на прокси (GET/PUT/DELETE)
-- `src/app/api/settings/proxy/test`: тест за изходяща прокси връзка (POST)
-- `src/app/api/usage/*`: API за използване и регистрационни файлове
-- `src/app/api/sync/*` + `src/app/api/cloud/*`: облачно синхронизиране и помощници в облака
-- `src/app/api/cli-tools/*`: локални писатели/контролери на CLI конфигурация
-- `src/app/api/settings/ip-filter`: списък с разрешени/блокирани IP адреси (GET/PUT)
-- `src/app/api/settings/thinking-budget`: конфигурация на бюджета на мислещ токен (GET/PUT)
-- `src/app/api/settings/system-prompt`: глобална системна подкана (GET/PUT)
-- `src/app/api/sessions`: списък с активни сесии (GET)
-- `src/app/api/rate-limits`: състояние на ограничение на скоростта на сметка (GET)
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
+- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
+- `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/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
+- `src/app/api/combos*`: fallback combo management
+- `src/app/api/pricing`: pricing overrides for cost calculation
+- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
+- `src/app/api/usage/*`: usage and logs APIs
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
+- `src/app/api/cli-tools/*`: local CLI config writers/checkers
+- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
+- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
+- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
+- `src/app/api/sessions`: active session listing (GET)
+- `src/app/api/rate-limits`: per-account rate limit status (GET)
 
-### Ядро за маршрутизиране и изпълнение
+### Routing and Execution Core
 
-- `src/sse/handlers/chat.ts`: анализ на заявка, комбо обработка, цикъл за избор на акаунт
-- `open-sse/handlers/chatCore.ts`: превод, изпращане на изпълнителя, обработка на повторен опит/опресняване, настройка на потока
-- `open-sse/executors/*`: специфично за доставчика поведение на мрежата и формата
+- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
+- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
+- `open-sse/executors/*`: provider-specific network and format behavior
 
-### Регистър за преводи и конвертори на формати
+### Translation Registry and Format Converters
 
-- `open-sse/translator/index.ts`: регистър на преводача и оркестрация
-- Заявка за преводачи: `open-sse/translator/request/*`
-- Преводачи на отговори: `open-sse/translator/response/*`
-- Константи на формата: `open-sse/translator/formats.ts`
+- `open-sse/translator/index.ts`: translator registry and orchestration
+- Request translators: `open-sse/translator/request/*`
+- Response translators: `open-sse/translator/response/*`
+- Format constants: `open-sse/translator/formats.ts`
 
-### Постоянство
+### Persistence
 
-- `src/lib/localDb.ts`: постоянна конфигурация/състояние
-- `src/lib/usageDb.ts`: хронология на използването и регистрационни файлове на текущи заявки
+- `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)
 
-Всеки доставчик има специализиран изпълнител, разширяващ `BaseExecutor` (в `open-sse/executors/base.ts`), който осигурява изграждане на URL адрес, изграждане на заглавка, повторен опит с експоненциално забавяне, кукички за опресняване на идентификационни данни и метода за оркестрация `execute()`.
+Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method.
 
-| Изпълнител            | Доставчик(и)                                                                                                                                                 | Специална обработка                                                                 |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
-| `DefaultExecutor`     | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Конфигурация на динамичен URL/заглавие за доставчик                                 |
-| `AntigravityExecutor` | Google Антигравитация                                                                                                                                        | Идентификационни номера на персонализирани проекти/сесии, повторен опит след анализ |
-| `CodexExecutor`       | OpenAI Codex                                                                                                                                                 | Вкарва системни инструкции, налага усилие за разсъждение                            |
-| `CursorExecutor`      | Курсор IDE                                                                                                                                                   | ConnectRPC протокол, Protobuf кодиране, подписване на заявка чрез контролна сума    |
-| `GithubExecutor`      | Копилот на GitHub                                                                                                                                            | Опресняване на Copilot token, заглавки, имитиращи VSCode                            |
-| `KiroExecutor`        | AWS CodeWhisperer/Киро                                                                                                                                       | AWS EventStream двоичен формат → SSE конвертиране                                   |
-| `GeminiCLIExecutor`   | Gemini CLI                                                                                                                                                   | Цикъл на опресняване на Google OAuth токен                                          |
+| 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                               |
+| `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 |
+| `GithubExecutor`      | GitHub Copilot                                                                                                                                               | Copilot token refresh, VSCode-mimicking headers                      |
+| `KiroExecutor`        | AWS CodeWhisperer/Kiro                                                                                                                                       | AWS EventStream binary format → SSE conversion                       |
+| `GeminiCLIExecutor`   | Gemini CLI                                                                                                                                                   | Google OAuth token refresh cycle                                     |
 
-Всички други доставчици (включително персонализирани съвместими възли) използват `DefaultExecutor`.
+All other providers (including custom compatible nodes) use the `DefaultExecutor`.
 
-## Матрица за съвместимост на доставчика
+## Provider Compatibility Matrix
 
-| Доставчик         | Формат          | Удостоверяване                 | Поток            | Непоточно | Опресняване на токена | API за използване            |
-| ----------------- | --------------- | ------------------------------ | ---------------- | --------- | --------------------- | ---------------------------- |
-| Клод              | Клод            | API ключ / OAuth               | ✅               | ✅        | ✅                    | ⚠️ Само администратор        |
-| Близнаци          | близнаци        | API ключ / OAuth               | ✅               | ✅        | ✅                    | ⚠️ Облачна конзола           |
-| Gemini CLI        | gemini-cli      | OAuth                          | ✅               | ✅        | ✅                    | ⚠️ Облачна конзола           |
-| Антигравитация    | антигравитация  | OAuth                          | ✅               | ✅        | ✅                    | ✅ API с пълна квота         |
-| OpenAI            | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Кодекс            | openai-отговори | OAuth                          | ✅ принуден      | ❌        | ✅                    | ✅ Ограничения на скоростта  |
-| Копилот на GitHub | openai          | OAuth + Copilot Token          | ✅               | ✅        | ✅                    | ✅ Моментни снимки на квоти  |
-| Курсор            | курсор          | Персонализирана контролна сума | ✅               | ✅        | ❌                    | ❌                           |
-| Киро              | киро            | AWS SSO OIDC                   | ✅ (EventStream) | ❌        | ✅                    | ✅ Ограничения за използване |
-| Куен              | openai          | OAuth                          | ✅               | ✅        | ✅                    | ⚠️ По заявка                 |
-| iFlow             | openai          | OAuth (основен)                | ✅               | ✅        | ✅                    | ⚠️ По заявка                 |
-| OpenRouter        | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| GLM/Кими/МиниМакс | Клод            | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| DeepSeek          | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Groq              | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| xAI (Grok)        | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Мистрал           | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Недоумение        | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Заедно AI         | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Фойерверки AI     | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Мозъци            | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Cohere            | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| NVIDIA NIM        | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
+| Provider         | Format           | Auth                  | Stream           | Non-Stream | Token Refresh | Usage API          |
+| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
+| Claude           | claude           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Admin only      |
+| Gemini           | gemini           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Gemini CLI       | gemini-cli       | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Antigravity      | antigravity      | OAuth                 | ✅               | ✅         | ✅            | ✅ Full quota API  |
+| OpenAI           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Codex            | openai-responses | OAuth                 | ✅ forced        | ❌         | ✅            | ✅ Rate limits     |
+| GitHub Copilot   | openai           | OAuth + Copilot Token | ✅               | ✅         | ✅            | ✅ Quota snapshots |
+| Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
+| Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
+| Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| iFlow            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Groq             | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| xAI (Grok)       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Mistral          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Perplexity       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Together AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Fireworks AI     | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 
-## Обхват на превод на формат
+## Format Translation Coverage
 
-Откритите изходни формати включват:
+Detected source formats include:
 
 - `openai`
 - `openai-responses`
 - `claude`
 - `gemini`
 
-Целевите формати включват:
+Target formats include:
 
-- OpenAI чат/Отговори
-- Клод
-- Gemini/Gemini-CLI/Антигравитационен плик
-- Киро
-- Курсор
+- OpenAI chat/Responses
+- Claude
+- Gemini/Gemini-CLI/Antigravity envelope
+- Kiro
+- Cursor
 
-Преводите използват **OpenAI като хъб формат** — всички реализации преминават през OpenAI като междинен:
+Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
 
 ```
 Source Format → OpenAI (hub) → Target Format
 ```
 
-Преводите се избират динамично въз основа на формата на изходния полезен товар и целевия формат на доставчика.
+Translations are selected dynamically based on source payload shape and provider target format.
 
-Допълнителни слоеве за обработка в тръбопровода за превод:
+Additional processing layers in the translation pipeline:
 
-- **Дефектификация на отговора** — Премахва нестандартните полета от отговорите във формат OpenAI (както стрийминг, така и без стрийминг), за да се гарантира стриктно съответствие с SDK
-- **Нормализиране на ролята** — Преобразува `developer` → `system` за цели, които не са OpenAI; обединява `system` → `user` за модели, които отхвърлят системната роля (GLM, ERNIE)
-- **Извличане на мислен етикет** — Анализира `<think>...</think>` блокове от съдържание в поле `reasoning_content`
-- **Структуриран изход** — Преобразува OpenAI `response_format.json_schema` в `responseMimeType` + `responseSchema` на Gemini
+- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance
+- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)
+- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field
+- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`
 
-## Поддържани API крайни точки
+## Supported API Endpoints
 
-| Крайна точка                                       | Формат                    | Манипулатор                                                        |
-| -------------------------------------------------- | ------------------------- | ------------------------------------------------------------------ |
-| `POST /v1/chat/completions`                        | OpenAI чат                | `src/sse/handlers/chat.ts`                                         |
-| `POST /v1/messages`                                | Съобщения на Клод         | Същият манипулатор (автоматично разпознат)                         |
-| `POST /v1/responses`                               | OpenAI отговори           | `open-sse/handlers/responsesHandler.ts`                            |
-| `POST /v1/embeddings`                              | OpenAI вграждания         | `open-sse/handlers/embeddings.ts`                                  |
-| `GET /v1/embeddings`                               | Списък на модели          | API маршрут                                                        |
-| `POST /v1/images/generations`                      | OpenAI изображения        | `open-sse/handlers/imageGeneration.ts`                             |
-| `GET /v1/images/generations`                       | Списък на модели          | API маршрут                                                        |
-| `POST /v1/providers/{provider}/chat/completions`   | OpenAI чат                | Специализиран за всеки доставчик с валидиране на модел             |
-| `POST /v1/providers/{provider}/embeddings`         | OpenAI вграждания         | Специализиран за всеки доставчик с валидиране на модел             |
-| `POST /v1/providers/{provider}/images/generations` | OpenAI изображения        | Специализиран за всеки доставчик с валидиране на модел             |
-| `POST /v1/messages/count_tokens`                   | Клод Токен Брой           | API маршрут                                                        |
-| `GET /v1/models`                                   | Списък с модели на OpenAI | API маршрут (чат + вграждане + изображение + потребителски модели) |
-| `GET /api/models/catalog`                          | Каталог                   | Всички модели, групирани по доставчик + тип                        |
-| `POST /v1beta/models/*:streamGenerateContent`      | Родом от Близнаци         | API маршрут                                                        |
-| `GET/PUT/DELETE /api/settings/proxy`               | Прокси конфигурация       | Конфигурация на мрежов прокси                                      |
-| `POST /api/settings/proxy/test`                    | Прокси връзка             | Крайна точка на прокси тест за изправност/свързаност               |
-| `GET/POST/DELETE /api/provider-models`             | Персонализирани модели    | Персонализирано управление на модели за всеки доставчик            |
+| 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                 |
 
-## Обходен манипулатор
+## Bypass Handler
 
-Обходният манипулатор (`open-sse/utils/bypassHandler.ts`) прихваща известни заявки за „изхвърляне“ от Claude CLI — пингове за загряване, извличане на заглавия и преброяване на токени — и връща **фалшив отговор**, без да консумира токени на доставчика нагоре по веригата. Това се задейства само когато `User-Agent` съдържа `claude-cli`.
+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
 
-Регистраторът на заявки (`open-sse/utils/requestLogger.ts`) осигурява 7-етапен конвейер за регистриране на грешки, деактивиран по подразбиране, активиран чрез `ENABLE_REQUEST_LOGS=true`:
+The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`:
 
 ```
 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
 ```
 
-Файловете се записват в `<repo>/logs/<session>/` за всяка сесия на заявка.
+Files are written to `<repo>/logs/<session>/` for each request session.
 
-## Режими на отказ и устойчивост
+## Failure Modes and Resilience
 
-## 1) Наличност на акаунт/доставчик
+## 1) Account/Provider Availability
 
-- изчакване на акаунта на доставчика при преходни/скоростни/удостоверителни грешки
-- резервен акаунт преди неуспешна заявка
-- резервен комбиниран модел, когато пътят на текущия модел/доставчик е изчерпан
+- provider account cooldown on transient/rate/auth errors
+- account fallback before failing request
+- combo model fallback when current model/provider path is exhausted
 
-## 2) Изтичане на токена
+## 2) Token Expiry
 
-- предварителна проверка и опресняване с повторен опит за опресняващи доставчици
-- 401/403 повторен опит след опит за опресняване в основния път
+- pre-check and refresh with retry for refreshable providers
+- 401/403 retry after refresh attempt in core path
 
-## 3) Безопасност на потока
+## 3) Stream Safety
 
-- контролер на потоци, който се изключва
-- поток за превод с промиване в края на потока и обработка на `[DONE]`
-- резервна оценка на използването, когато липсват метаданни за използване на доставчика
+- disconnect-aware stream controller
+- translation stream with end-of-stream flush and `[DONE]` handling
+- usage estimation fallback when provider usage metadata is missing
 
-## 4) Влошаване на облачната синхронизация
+## 4) Cloud Sync Degradation
 
-- появяват се грешки при синхронизиране, но локалното изпълнение продължава
-- планировчикът има логика с възможност за повторен опит, но периодичното изпълнение в момента извиква синхронизиране с един опит по подразбиране
+- sync errors are surfaced but local runtime continues
+- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
 
-## 5) Цялост на данните
+## 5) Data Integrity
 
-- Миграция/поправка на DB форма за липсващи ключове
-- повредени предпазни мерки за нулиране на JSON за localDb и usageDb
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
-## Наблюдаемост и оперативни сигнали
+## Observability and Operational Signals
 
-Източници на видимост по време на изпълнение:
+Runtime visibility sources:
 
-- регистрационни файлове на конзолата от `src/sse/utils/logger.ts`
-- агрегати за използване на заявка в `usage.json`
-- влизане на състоянието на текстова заявка `log.txt`
-- незадължителни дълбоки регистрационни файлове за заявка/превод под `logs/`, когато `ENABLE_REQUEST_LOGS=true`
-- крайни точки за използване на таблото за управление (`/api/usage/*`) за потребление на UI
+- console logs from `src/sse/utils/logger.ts`
+- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- textual request status log in `log.txt` (optional/compat)
+- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true`
+- dashboard usage endpoints (`/api/usage/*`) for UI consumption
 
-## Граници, чувствителни към сигурността
+## Security-Sensitive Boundaries
 
-- JWT тайна (`JWT_SECRET`) защитава проверката/подписването на бисквитките на таблото за управление
-- Първоначалната резервна парола (`INITIAL_PASSWORD`, по подразбиране `123456`) трябва да бъде заменена при реални внедрявания
-- API ключ HMAC secret (`API_KEY_SECRET`) защитава генерирания локален формат на API ключ
-- Тайните на доставчика (API ключове/токени) се съхраняват в локалната база данни и трябва да бъдат защитени на ниво файлова система
-- Крайните точки за синхронизиране в облак разчитат на удостоверяване на API ключ + семантика на идентификатор на машина
+- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
+- 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
 
-## Околна среда и матрица за изпълнение
+## Environment and Runtime Matrix
 
-Променливите на средата, използвани активно от кода:
+Environment variables actively used by code:
 
-- Приложение/удостоверяване: `JWT_SECRET`, `INITIAL_PASSWORD`
-- Съхранение: `DATA_DIR`
-- Съвместимо поведение на възел: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
-- Допълнителна отмяна на базата за съхранение (Linux/macOS, когато `DATA_DIR` не е зададен): `XDG_CONFIG_HOME`
-- Хеширане на сигурността: `API_KEY_SECRET`, `MACHINE_ID_SALT`
-- Регистриране: `ENABLE_REQUEST_LOGS`
-- Синхронизиране/облачно URL адресиране: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
-- Изходящ прокси: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` и варианти с малки букви
-- Флагове за функция SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
-- Помощници за платформа/време на изпълнение (не специфична за приложението конфигурация): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Storage: `DATA_DIR`
+- 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`
+- 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`
+- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
 
-## Известни архитектурни бележки
+## Known Architectural Notes
 
-1. `usageDb` и `localDb` сега споделят една и съща основна политика за директория (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) с мигриране на наследени файлове.
-2. `/api/v1/route.ts` връща списък със статичен модел и не е основният източник на модели, използван от `/v1/models`.
-3. Request logger записва пълни заглавки/тяло, когато е разрешено; третира регистрационната директория като чувствителна.
-4. Поведението в облака зависи от правилния `NEXT_PUBLIC_BASE_URL` и достижимостта на крайната точка на облака.
-5. Директорията `open-sse/` е публикувана като `@omniroute/open-sse` **npm workspace package**. Изходният код го импортира чрез `@omniroute/open-sse/...` (разрешено от Next.js `transpilePackages`). Пътищата на файловете в този документ все още използват името на директорията `open-sse/` за последователност.
-6. Диаграмите в таблото за управление използват **Recharts** (базирани на SVG) за достъпни, интерактивни аналитични визуализации (стълбовидни диаграми на използването на модела, таблици с разбивка на доставчиците с проценти на успех).
-7. E2E тестовете използват **Playwright** (`tests/e2e/`), изпълняват се чрез `npm run test:e2e`. Модулните тестове използват **Node.js test runner** (`tests/unit/`), изпълняват се чрез `npm run test:plan3`. Изходният код под `src/` е **TypeScript** (`.ts`/`.tsx`); работното пространство `open-sse/` остава JavaScript (`.js`).
-8. Страницата с настройки е организирана в 5 раздела: Сигурност, Маршрутизиране (6 глобални стратегии: първо попълване, кръгъл-робин, p2c, произволна, най-малко използвана, оптимизирана по отношение на разходите), Устойчивост (ограничения на скоростта за редактиране, прекъсвач, политики), AI (мислещ бюджет, системна подкана, кеш за подкана), Разширени (прокси).
+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: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), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
 
-## Контролен списък за оперативна проверка
+## Operational Verification Checklist
 
-- Създаване от източник: `npm run build`
-- Изграждане на Docker изображение: `docker build -t omniroute .`
-- Стартирайте услугата и проверете:
+- Build from source: `npm run build`
+- Build Docker image: `docker build -t omniroute .`
+- Start service and verify:
 - `GET /api/settings`
 - `GET /api/v1/models`
-- CLI целеви базов URL трябва да бъде `http://<host>:20128/v1`, когато `PORT=20128`
+- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`

docs/i18n/bg/AUTO-COMBO.md

@@ -0,0 +1,67 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/AUTO-COMBO.md) · 🇪🇸 [es](../es/AUTO-COMBO.md) · 🇫🇷 [fr](../fr/AUTO-COMBO.md) · 🇩🇪 [de](../de/AUTO-COMBO.md) · 🇮🇹 [it](../it/AUTO-COMBO.md) · 🇷🇺 [ru](../ru/AUTO-COMBO.md) · 🇨🇳 [zh-CN](../zh-CN/AUTO-COMBO.md) · 🇯🇵 [ja](../ja/AUTO-COMBO.md) · 🇰🇷 [ko](../ko/AUTO-COMBO.md) · 🇸🇦 [ar](../ar/AUTO-COMBO.md) · 🇮🇳 [in](../in/AUTO-COMBO.md) · 🇹🇭 [th](../th/AUTO-COMBO.md) · 🇻🇳 [vi](../vi/AUTO-COMBO.md) · 🇮🇩 [id](../id/AUTO-COMBO.md) · 🇲🇾 [ms](../ms/AUTO-COMBO.md) · 🇳🇱 [nl](../nl/AUTO-COMBO.md) · 🇵🇱 [pl](../pl/AUTO-COMBO.md) · 🇸🇪 [sv](../sv/AUTO-COMBO.md) · 🇳🇴 [no](../no/AUTO-COMBO.md) · 🇩🇰 [da](../da/AUTO-COMBO.md) · 🇫🇮 [fi](../fi/AUTO-COMBO.md) · 🇵🇹 [pt](../pt/AUTO-COMBO.md) · 🇷🇴 [ro](../ro/AUTO-COMBO.md) · 🇭🇺 [hu](../hu/AUTO-COMBO.md) · 🇧🇬 [bg](../bg/AUTO-COMBO.md) · 🇸🇰 [sk](../sk/AUTO-COMBO.md) · 🇺🇦 [uk-UA](../uk-UA/AUTO-COMBO.md) · 🇮🇱 [he](../he/AUTO-COMBO.md) · 🇵🇭 [phi](../phi/AUTO-COMBO.md)
+
+---
+
+# 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/i18n/bg/CODEBASE_DOCUMENTATION.md

@@ -1,22 +1,26 @@
-# omniroute — Документация на кодовата база
-
-🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md)
-
-> Изчерпателно, удобно за начинаещи ръководство за **omniroute** прокси рутер с изкуствен интелект с множество доставчици.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../es/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../fr/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../de/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../it/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../ru/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../ja/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../ko/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../ar/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [in](../in/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../th/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../vi/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../id/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../ms/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../nl/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../pl/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../sv/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../no/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../da/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../fi/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../pt/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../ro/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../hu/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../bg/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../sk/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../he/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../phi/CODEBASE_DOCUMENTATION.md)
 
 ---
 
-## 1. Какво е omniroute?
+# omniroute — Codebase Documentation
 
-omniroute е **прокси рутер**, който се намира между AI клиенти (Claude CLI, Codex, Cursor IDE и др.) и AI доставчици (Anthropic, Google, OpenAI, AWS, GitHub и др.). Решава един голям проблем:
+🌐 **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)
 
-> **Различните AI клиенти говорят различни „езици“ (API формати) и различните доставчици на AI също очакват различни „езици“.** omniroute превежда автоматично между тях.
-
-Мислете за това като за универсален преводач в Обединените нации - всеки делегат може да говори всеки език и преводачът го преобразува за всеки друг делегат.
+> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router.
 
 ---
 
-## 2. Преглед на архитектурата
+## 1. What Is omniroute?
+
+omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem:
+
+> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically.
+
+Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate.
+
+---
+
+## 2. Architecture Overview
 
 ```mermaid
 graph LR
@@ -61,20 +65,20 @@ graph LR
     H -.-> G
 ```
 
-### Основен принцип: Превод на централно ниво
+### Core Principle: Hub-and-Spoke Translation
 
-Всички преводи на формати преминават през **OpenAI формат като център**:
+All format translation passes through **OpenAI format as the hub**:
 
 ```
 Client Format → [OpenAI Hub] → Provider Format    (request)
 Provider Format → [OpenAI Hub] → Client Format    (response)
 ```
 
-Това означава, че имате нужда само от **N преводачи** (по един на формат) вместо от **N²** (всяка двойка).
+This means you only need **N translators** (one per format) instead of **N²** (every pair).
 
 ---
 
-## 3. Структура на проекта
+## 3. Project Structure
 
 ```
 omniroute/
@@ -104,22 +108,22 @@ omniroute/
 
 ---
 
-## 4. Разбивка модул по модул
+## 4. Module-by-Module Breakdown
 
-### 4.1 Конфигурация (`open-sse/config/`)
+### 4.1 Config (`open-sse/config/`)
 
-**Единственият източник на истина** за всички конфигурации на доставчика.
+The **single source of truth** for all provider configuration.
 
-| Файл                          | Цел                                                                                                                                                                                                                                                            |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `constants.ts`                | `PROVIDERS` обект с основни URL адреси, идентификационни данни за OAuth (по подразбиране), заглавки и системни подкани по подразбиране за всеки доставчик. Също така дефинира `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` и `SKIP_PATTERNS`. |
-| `credentialLoader.ts`         | Зарежда външни идентификационни данни от `data/provider-credentials.json` и ги обединява върху твърдо кодираните настройки по подразбиране в `PROVIDERS`. Пази тайните извън контрола на източника, като същевременно поддържа обратна съвместимост.           |
-| `providerModels.ts`           | Централен регистър на моделите: псевдоними на доставчика на карти → ID на модела. Функции като `getModels()`, `getProviderByAlias()`.                                                                                                                          |
-| `codexInstructions.ts`        | Системни инструкции, инжектирани в заявките на Codex (ограничения за редактиране, правила на пясъчника, правила за одобрение).                                                                                                                                 |
-| `defaultThinkingSignature.ts` | „Мислещи“ подписи по подразбиране за модели Claude и Gemini.                                                                                                                                                                                                   |
-| `ollamaModels.ts`             | Дефиниция на схема за локални модели Ollama (име, размер, семейство, квантуване).                                                                                                                                                                              |
+| File                          | Purpose                                                                                                                                                                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `constants.ts`                | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. |
+| `credentialLoader.ts`         | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility.               |
+| `providerModels.ts`           | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`.                                                                                                          |
+| `codexInstructions.ts`        | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies).                                                                                                                 |
+| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models.                                                                                                                                                               |
+| `ollamaModels.ts`             | Schema definition for local Ollama models (name, size, family, quantization).                                                                                                                                             |
 
-#### Поток на зареждане на идентификационни данни
+#### Credential Loading Flow
 
 ```mermaid
 flowchart TD
@@ -142,9 +146,9 @@ flowchart TD
 
 ---
 
-### 4.2 Изпълнители (`open-sse/executors/`)
+### 4.2 Executors (`open-sse/executors/`)
 
-Изпълнителите капсулират **специфична за доставчика логика**, използвайки **стратегически модел**. Всеки изпълнител замества основните методи, ако е необходимо.
+Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed.
 
 ```mermaid
 classDiagram
@@ -194,32 +198,32 @@ classDiagram
     BaseExecutor <|-- GithubExecutor
 ```
 
-| Изпълнител       | Доставчик                                  | Ключови специализации                                                                                                                                                                 |
-| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `base.ts`        | —                                          | Абстрактна база: изграждане на URL, заглавки, логика за повторен опит, опресняване на идентификационни данни                                                                          |
-| `default.ts`     | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Генерично опресняване на OAuth токен за стандартни доставчици                                                                                                                         |
-| `antigravity.ts` | Google Cloud Code                          | Генериране на идентификатор на проект/сесия, резервен URL адрес с множество URL адреси, персонализирано анализиране на повторен опит от съобщения за грешка („нулиране след 2h7m23s“) |
-| `cursor.ts`      | Курсор IDE                                 | **Най-сложни**: SHA-256 контролна сума auth, Protobuf кодиране на заявка, двоичен EventStream → SSE отговор анализ                                                                    |
-| `codex.ts`       | OpenAI Codex                               | Вкарва системни инструкции, управлява нивата на мислене, премахва неподдържаните параметри                                                                                            |
-| `gemini-cli.ts`  | Google Gemini CLI                          | Изграждане на персонализиран URL (`streamGenerateContent`), опресняване на Google OAuth токен                                                                                         |
-| `github.ts`      | Копилот на GitHub                          | Система с двоен токен (GitHub OAuth + Copilot token), имитиране на заглавката на VSCode                                                                                               |
-| `kiro.ts`        | AWS CodeWhisperer                          | Двоичен анализ на AWS EventStream, рамки за събития AMZN, оценка на токена                                                                                                            |
-| `index.ts`       | —                                          | Фабрика: картографира името на доставчика → клас изпълнител, с резервен вариант по подразбиране                                                                                       |
+| Executor         | Provider                                   | Key Specializations                                                                                                 |
+| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `base.ts`        | —                                          | Abstract base: URL building, headers, retry logic, credential refresh                                               |
+| `default.ts`     | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers                                                                  |
+| `antigravity.ts` | Google Cloud Code                          | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") |
+| `cursor.ts`      | Cursor IDE                                 | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing       |
+| `codex.ts`       | OpenAI Codex                               | Injects system instructions, manages thinking levels, removes unsupported parameters                                |
+| `gemini-cli.ts`  | Google Gemini CLI                          | Custom URL building (`streamGenerateContent`), Google OAuth token refresh                                           |
+| `github.ts`      | GitHub Copilot                             | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking                                           |
+| `kiro.ts`        | AWS CodeWhisperer                          | AWS EventStream binary parsing, AMZN event frames, token estimation                                                 |
+| `index.ts`       | —                                          | Factory: maps provider name → executor class, with default fallback                                                 |
 
 ---
 
-### 4.3 Манипулатори (`open-sse/handlers/`)
+### 4.3 Handlers (`open-sse/handlers/`)
 
-**Слоят за оркестрация** — координира превода, изпълнението, поточното предаване и обработката на грешки.
+The **orchestration layer** — coordinates translation, execution, streaming, and error handling.
 
-| Файл                  | Цел                                                                                                                                                                                                                                                     |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `chatCore.ts`         | **Централен оркестратор** (~600 реда). Обработва пълния жизнен цикъл на заявката: откриване на формат → превод → изпращане на изпълнител → стрийминг/не-стрийминг отговор → опресняване на токена → обработка на грешки → регистриране на използването. |
-| `responsesHandler.ts` | Адаптер за API за отговори на OpenAI: преобразува формата на отговорите → Завършвания на чат → изпраща до `chatCore` → конвертира SSE обратно във формат на отговорите.                                                                                 |
-| `embeddings.ts`       | Манипулатор за генериране на вграждане: разрешава модел на вграждане → доставчик, изпраща до API на доставчика, връща съвместим с OpenAI отговор за вграждане. Поддържа 6+ доставчици.                                                                  |
-| `imageGeneration.ts`  | Манипулатор за генериране на изображения: разрешава модел на изображение → доставчик, поддържа режими, съвместими с OpenAI, Gemini-image (Антигравитация) и резервни (Nebius). Връща base64 или URL изображения.                                        |
+| File                  | Purpose                                                                                                                                                                                                                |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chatCore.ts`         | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. |
+| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format.                                                                        |
+| `embeddings.ts`       | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers.                                                    |
+| `imageGeneration.ts`  | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images.                                          |
 
-#### Жизнен цикъл на заявка (chatCore.ts)
+#### Request Lifecycle (chatCore.ts)
 
 ```mermaid
 sequenceDiagram
@@ -258,28 +262,28 @@ sequenceDiagram
 
 ---
 
-### 4.4 Услуги (`open-sse/services/`)
+### 4.4 Services (`open-sse/services/`)
 
-Бизнес логика, която поддържа манипулаторите и изпълнителите.
+Business logic that supports the handlers and executors.
 
-| Файл                 | Цел                                                                                                                                                                                                                                                                                                                                                                                                 |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `provider.ts`        | **Откриване на формат** (`detectFormat`): анализира структурата на тялото на заявката, за да идентифицира форматите Claude/OpenAI/Gemini/Antigravity/Responses (включва `max_tokens` евристика за Claude). Също така: изграждане на URL адреси, изграждане на заглавки, нормализиране на конфигурацията на мислене. Поддържа `openai-compatible-*` и `anthropic-compatible-*` динамични доставчици. |
-| `model.ts`           | Разбор на низ на модел (`claude/model-name` → `{provider: "claude", model: "model-name"}`), разрешаване на псевдоними с откриване на сблъсък, дезинфекция на входа (отхвърля преминаване на пътя/контролни знаци) и разрешаване на информация за модела с поддръжка на асинхронно получаване на псевдоними.                                                                                         |
-| `accountFallback.ts` | Обработка на ограничение на скоростта: експоненциално забавяне (1s → 2s → 4s → макс. 2min), управление на изчакване на акаунта, класификация на грешките (кои грешки задействат резервно или не).                                                                                                                                                                                                   |
-| `tokenRefresh.ts`    | Опресняване на OAuth токена за **всеки доставчик**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Включва кеш за дедупликация на обещание по време на полет и повторен опит с експоненциално забавяне.                                                                                                          |
-| `combo.ts`           | **Комбинирани модели**: вериги от резервни модели. Ако модел A се провали с допустима грешка за резервен вариант, опитайте модел B, след това C и т.н. Връща действителните кодове за състояние нагоре по веригата.                                                                                                                                                                                 |
-| `usage.ts`           | Извлича данни за квоти/използване от API на доставчика (квоти на GitHub Copilot, квоти на модела на Antigravity, ограничения на скоростта на Codex, разбивки на използването на Kiro, настройки на Claude).                                                                                                                                                                                         |
-| `accountSelector.ts` | Интелигентен избор на акаунт с алгоритъм за точкуване: взема предвид приоритет, здравословно състояние, кръгова позиция и състояние на изчакване, за да избере оптималния акаунт за всяка заявка.                                                                                                                                                                                                   |
-| `contextManager.ts`  | Управление на жизнения цикъл на контекста на заявката: създава и проследява контекстни обекти на заявка с метаданни (идентификатор на заявка, времеви клейма, информация за доставчика) за отстраняване на грешки и регистриране.                                                                                                                                                                   |
-| `ipFilter.ts`        | IP-базиран контрол на достъпа: поддържа разрешени и блокирани режими. Валидира клиентския IP адрес спрямо конфигурирани правила, преди да обработи API заявки.                                                                                                                                                                                                                                      |
-| `sessionManager.ts`  | Проследяване на сесии с пръстов отпечатък на клиента: проследява активни сесии с помощта на хеширани клиентски идентификатори, следи броя на заявките и предоставя показатели за сесиите.                                                                                                                                                                                                           |
-| `signatureCache.ts`  | Кеш за дедупликация, базиран на подписи на заявки: предотвратява дублиране на заявки чрез кеширане на подписи на скорошни заявки и връщане на кеширани отговори за идентични заявки в рамките на времеви прозорец.                                                                                                                                                                                  |
-| `systemPrompt.ts`    | Инжектиране на глобална системна подкана: добавя пред или добавя конфигурируема системна подкана към всички заявки, с обработка на съвместимостта за всеки доставчик.                                                                                                                                                                                                                               |
-| `thinkingBudget.ts`  | Управление на бюджета на токените за разсъждение: поддържа режими за преминаване, автоматичен (конфигурация на лентово мислене), персонализиран (фиксиран бюджет) и адаптивен (мащабиран според сложността) режими за контролиране на токени за мислене/разсъждение.                                                                                                                                |
-| `wildcardRouter.ts`  | Маршрутизиране на модела със заместващи знаци: разрешава шаблони със заместващи знаци (напр. `*/claude-*`) до конкретни двойки доставчик/модел въз основа на наличност и приоритет.                                                                                                                                                                                                                 |
+| File                 | Purpose                                                                                                                                                                                                                                                                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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.                                                                       |
+| `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.                                                                                                                                                              |
+| `contextManager.ts`  | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging.                                                                                                                                                                  |
+| `ipFilter.ts`        | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests.                                                                                                                                                                                          |
+| `sessionManager.ts`  | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics.                                                                                                                                                                            |
+| `signatureCache.ts`  | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window.                                                                                                                                              |
+| `systemPrompt.ts`    | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling.                                                                                                                                                                                            |
+| `thinkingBudget.ts`  | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens.                                                                                                                                        |
+| `wildcardRouter.ts`  | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority.                                                                                                                                                                                   |
 
-#### Дедупликация на опресняване на токени
+#### Token Refresh Deduplication
 
 ```mermaid
 sequenceDiagram
@@ -300,7 +304,7 @@ sequenceDiagram
     Cache->>Cache: Delete cache entry
 ```
 
-#### Резервна държавна машина на акаунта
+#### Account Fallback State Machine
 
 ```mermaid
 stateDiagram-v2
@@ -325,7 +329,7 @@ stateDiagram-v2
     }
 ```
 
-#### Комбиниран модел верига
+#### Combo Model Chain
 
 ```mermaid
 flowchart LR
@@ -344,11 +348,11 @@ flowchart LR
 
 ---
 
-### 4.5 Преводач (`open-sse/translator/`)
+### 4.5 Translator (`open-sse/translator/`)
 
-**Машината за превод на формати**, използваща саморегистрираща се плъгин система.
+The **format translation engine** using a self-registering plugin system.
 
-#### Архитектура
+#### Architecture
 
 ```mermaid
 graph TD
@@ -374,15 +378,15 @@ graph TD
     end
 ```
 
-| Указател     | Файлове     | Описание                                                                                                                                                                                                                                                                                                 |
-| ------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request/`   | 8 преводачи | Преобразувайте тела на заявки между формати. Всеки файл се саморегистрира чрез `register(from, to, fn)` при импортиране.                                                                                                                                                                                 |
-| `response/`  | 7 преводачи | Преобразувайте поточно предавани отговори между формати. Обработва SSE типове събития, мисловни блокове, извиквания на инструменти.                                                                                                                                                                      |
-| `helpers/`   | 6 помощника | Споделени помощни програми: `claudeHelper` (извличане на системни подкани, мислеща конфигурация), `geminiHelper` (съпоставяне на части/съдържание), `openaiHelper` (филтриране на формат), `toolCallHelper` (генериране на ID, инжектиране на липсващ отговор), `maxTokensHelper`, `responsesApiHelper`. |
-| `index.ts`   | —           | Механизъм за превод: `translateRequest()`, `translateResponse()`, управление на състоянието, регистър.                                                                                                                                                                                                   |
-| `formats.ts` | —           | Константи на формата: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`.                                                                                                                                                                                                 |
+| Directory    | Files         | Description                                                                                                                                                                                                                                                      |
+| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request/`   | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import.                                                                                                                                                         |
+| `response/`  | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls.                                                                                                                                                         |
+| `helpers/`   | 6 helpers     | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. |
+| `index.ts`   | —             | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry.                                                                                                                                                                     |
+| `formats.ts` | —             | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`.                                                                                                                                                             |
 
-#### Ключов дизайн: Саморегистриращи се добавки
+#### Key Design: Self-Registering Plugins
 
 ```javascript
 // Each translator file calls register() on import:
@@ -395,17 +399,17 @@ import "./request/claude-to-openai.js"; // ← self-registers
 
 ---
 
-### 4.6 Помощни средства (`open-sse/utils/`)
+### 4.6 Utils (`open-sse/utils/`)
 
-| Файл               | Цел                                                                                                                                                                                                                                                                                                                                                    |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `error.ts`         | Изграждане на отговор при грешка (съвместим с OpenAI формат), анализиране на грешка нагоре по веригата, извличане на времето за повторен опит на Antigravity от съобщения за грешка, поточно предаване на грешка на SSE.                                                                                                                               |
-| `stream.ts`        | **SSE Transform Stream** — основният тръбопровод за стрийминг. Два режима: `TRANSLATE` (превод в пълен формат) и `PASSTHROUGH` (нормализиране + извличане на използването). Управлява буфериране на парчета, оценка на използването, проследяване на дължината на съдържанието. Екземплярите на енкодер/декодер на поток избягват споделено състояние. |
-| `streamHelpers.ts` | Помощни програми за SSE на ниско ниво: `parseSSELine` (толерантни към бели интервали), `hasValuableContent` (филтрира празни парчета за OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (сериализация на SSE, съобразена с формата с `perf_metrics` почистване).                                                                                    |
-| `usageTracking.ts` | Извличане на използване на токени от всеки формат (Claude/OpenAI/Gemini/Responses), оценка с отделни съотношения на инструмент/съобщение char-per-token, добавяне на буфер (марж за безопасност от 2000 токена), филтриране на специфично за формат поле, конзолно регистриране с ANSI цветове.                                                        |
-| `requestLogger.ts` | Регистриране на искания на базата на файл (включване чрез `ENABLE_REQUEST_LOGS=true`). Създава сесийни папки с номерирани файлове: `1_req_client.json` → `7_res_client.txt`. Всички I/O са асинхронни (задействай и забрави). Маскира чувствителните заглавки.                                                                                         |
-| `bypassHandler.ts` | Прихваща специфични модели от Claude CLI (извличане на заглавие, загряване, броене) и връща фалшиви отговори, без да се обажда на доставчик. Поддържа както стрийминг, така и не стрийминг. Умишлено ограничен до Claude CLI обхват.                                                                                                                   |
-| `networkProxy.ts`  | Разрешава URL адрес на изходящ прокси за даден доставчик с приоритет: специфична за доставчика конфигурация → глобална конфигурация → променливи на средата (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Поддържа `NO_PROXY` изключения. Кешира конфигурацията за 30s.                                                                                    |
+| File               | Purpose                                                                                                                                                                                                                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `error.ts`         | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming.                                                                                                                              |
+| `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.                                                              |
+| `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.                                                  |
 
 #### SSE Streaming Pipeline
 
@@ -429,7 +433,7 @@ flowchart TD
     style M fill:#9f9,stroke:#333
 ```
 
-#### Структура на сесията на регистратора на заявка
+#### Request Logger Session Structure
 
 ```
 logs/
@@ -447,109 +451,109 @@ logs/
 
 ---
 
-### 4.7 Приложен слой (`src/`)
+### 4.7 Application Layer (`src/`)
 
-| Указател      | Цел                                                                                                          |
-| ------------- | ------------------------------------------------------------------------------------------------------------ |
-| `src/app/`    | Уеб потребителски интерфейс, API маршрути, Express междинен софтуер, манипулатори за обратно извикване OAuth |
-| `src/lib/`    | Достъп до база данни (`localDb.ts`, `usageDb.ts`), удостоверяване, споделено                                 |
-| `src/mitm/`   | Прокси помощни програми Man-in-the-middle за прихващане на трафик на доставчик                               |
-| `src/models/` | Дефиниции на модел на база данни                                                                             |
-| `src/shared/` | Обвивки около open-sse функции (доставчик, поток, грешка и др.)                                              |
-| `src/sse/`    | SSE манипулатори на крайни точки, които свързват библиотеката open-sse към експресни маршрути                |
-| `src/store/`  | Управление на състоянието на приложението                                                                    |
+| Directory     | Purpose                                                                |
+| ------------- | ---------------------------------------------------------------------- |
+| `src/app/`    | Web UI, API routes, Express middleware, OAuth callback handlers        |
+| `src/lib/`    | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared   |
+| `src/mitm/`   | Man-in-the-middle proxy utilities for intercepting provider traffic    |
+| `src/models/` | Database model definitions                                             |
+| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.)     |
+| `src/sse/`    | SSE endpoint handlers that wire the open-sse library to Express routes |
+| `src/store/`  | Application state management                                           |
 
-#### Известни API маршрути
+#### Notable API Routes
 
-| Маршрут                                       | Методи                           | Цел                                                                                                     |
-| --------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `/api/provider-models`                        | ПОЛУЧАВАНЕ/ПУБЛИКУВАНЕ/ИЗТРИВАНЕ | CRUD за потребителски модели на доставчик                                                               |
-| `/api/models/catalog`                         | ВЗЕМЕТЕ                          | Обобщен каталог на всички модели (чат, вграждане, изображение, персонализирани), групирани по доставчик |
-| `/api/settings/proxy`                         | ПОЛУЧАВАНЕ/ПОСТАВЯНЕ/ИЗТРИВАНЕ   | Конфигурация на йерархичен изходящ прокси (`global/providers/combos/keys`)                              |
-| `/api/settings/proxy/test`                    | ПУБЛИКАЦИЯ                       | Потвърждава прокси свързаността и връща публичен IP/латентност                                          |
-| `/v1/providers/[provider]/chat/completions`   | ПУБЛИКАЦИЯ                       | Специализирани завършвания на чат за всеки доставчик с валидиране на модел                              |
-| `/v1/providers/[provider]/embeddings`         | ПУБЛИКАЦИЯ                       | Специализирани вграждания за всеки доставчик с валидиране на модел                                      |
-| `/v1/providers/[provider]/images/generations` | ПУБЛИКАЦИЯ                       | Специално генериране на изображения за всеки доставчик с валидиране на модел                            |
-| `/api/settings/ip-filter`                     | ВЗЕМИ/ПОСТАВИ                    | Управление на списък с разрешени/блокирани IP                                                           |
-| `/api/settings/thinking-budget`               | ВЗЕМИ/ПОСТАВИ                    | Конфигурация на бюджета на токена за разсъждение (пропускане/автоматично/персонализирано/адаптивно)     |
-| `/api/settings/system-prompt`                 | ВЗЕМИ/ПОСТАВИ                    | Бързо инжектиране на глобална система за всички заявки                                                  |
-| `/api/sessions`                               | ВЗЕМЕТЕ                          | Проследяване на активна сесия и показатели                                                              |
-| `/api/rate-limits`                            | ВЗЕМЕТЕ                          | Състояние на ограничение на лимита по сметка                                                            |
+| Route                                         | Methods         | Purpose                                                                               |
+| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
+| `/api/provider-models`                        | GET/POST/DELETE | CRUD for custom models per provider                                                   |
+| `/api/models/catalog`                         | GET             | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider |
+| `/api/settings/proxy`                         | GET/PUT/DELETE  | Hierarchical outbound proxy configuration (`global/providers/combos/keys`)            |
+| `/api/settings/proxy/test`                    | POST            | Validates proxy connectivity and returns public IP/latency                            |
+| `/v1/providers/[provider]/chat/completions`   | POST            | Dedicated per-provider chat completions with model validation                         |
+| `/v1/providers/[provider]/embeddings`         | POST            | Dedicated per-provider embeddings with model validation                               |
+| `/v1/providers/[provider]/images/generations` | POST            | Dedicated per-provider image generation with model validation                         |
+| `/api/settings/ip-filter`                     | GET/PUT         | IP allowlist/blocklist management                                                     |
+| `/api/settings/thinking-budget`               | GET/PUT         | Reasoning token budget configuration (passthrough/auto/custom/adaptive)               |
+| `/api/settings/system-prompt`                 | GET/PUT         | Global system prompt injection for all requests                                       |
+| `/api/sessions`                               | GET             | Active session tracking and metrics                                                   |
+| `/api/rate-limits`                            | GET             | Per-account rate limit status                                                         |
 
 ---
 
-## 5. Ключови модели на дизайн
+## 5. Key Design Patterns
 
-### 5.1 Hub-and-Spoke превод
+### 5.1 Hub-and-Spoke Translation
 
-Всички формати се превеждат през **OpenAI формат като център**. Добавянето на нов доставчик изисква само писане на **една двойка** преводачи (към/от OpenAI), а не на N двойки.
+All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs.
 
-### 5.2 Модел на стратегия за изпълнител
+### 5.2 Executor Strategy Pattern
 
-Всеки доставчик има специален клас изпълнител, наследен от `BaseExecutor`. Фабриката в `executors/index.ts` избира правилния по време на изпълнение.
+Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime.
 
-### 5.3 Саморегистрираща се плъгин система
+### 5.3 Self-Registering Plugin System
 
-Модулите за преводач се регистрират при импортиране чрез `register()`. Добавянето на нов преводач е просто създаване на файл и импортирането му.
+Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it.
 
-### 5.4 Резервен акаунт с експоненциално отстъпление
+### 5.4 Account Fallback with Exponential Backoff
 
-Когато доставчикът върне 429/401/500, системата може да превключи към следващия акаунт, прилагайки експоненциално охлаждане (1s → 2s → 4s → max 2min).
+When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min).
 
-### Комбинирани вериги за модели 5.5
+### 5.5 Combo Model Chains
 
-„Комбо“ групира множество низове `provider/model`. Ако първият не успее, автоматично се върнете към следващия.
+A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically.
 
-### 5.6 Поточен превод с пълно състояние
+### 5.6 Stateful Streaming Translation
 
-Преводът на отговор поддържа състоянието в SSE блокове (проследяване на мислещ блок, натрупване на извикване на инструмент, индексиране на блок съдържание) чрез механизма `initState()`.
+Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism.
 
-### 5.7 Буфер за безопасност при използване
+### 5.7 Usage Safety Buffer
 
-Добавя се буфер от 2000 токена към отчетеното използване, за да се предотврати достигането на ограниченията на контекстните прозорци на клиентите поради натоварване от системни подкани и превод на формати.
+A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation.
 
 ---
 
-## 6. Поддържани формати
+## 6. Supported Formats
 
-| Формат                    | Посока         | Идентификатор      |
-| ------------------------- | -------------- | ------------------ |
-| Завършвания на OpenAI чат | източник + цел | `openai`           |
-| OpenAI Responses API      | източник + цел | `openai-responses` |
-| Антропичен Клод           | източник + цел | `claude`           |
-| Google Gemini             | източник + цел | `gemini`           |
-| Google Gemini CLI         | само цел       | `gemini-cli`       |
-| Антигравитация            | източник + цел | `antigravity`      |
-| AWS Киро                  | само цел       | `kiro`             |
-| Курсор                    | само цел       | `cursor`           |
+| Format                  | Direction       | Identifier         |
+| ----------------------- | --------------- | ------------------ |
+| OpenAI Chat Completions | source + target | `openai`           |
+| OpenAI Responses API    | source + target | `openai-responses` |
+| Anthropic Claude        | source + target | `claude`           |
+| Google Gemini           | source + target | `gemini`           |
+| Google Gemini CLI       | target only     | `gemini-cli`       |
+| Antigravity             | source + target | `antigravity`      |
+| AWS Kiro                | target only     | `kiro`             |
+| Cursor                  | target only     | `cursor`           |
 
 ---
 
-## 7. Поддържани доставчици
+## 7. Supported Providers
 
-| Доставчик                | Метод за удостоверяване          | Изпълнител      | Основни бележки                                    |
-| ------------------------ | -------------------------------- | --------------- | -------------------------------------------------- |
-| Антропичен Клод          | API ключ или OAuth               | По подразбиране | Използва `x-api-key` заглавка                      |
-| Google Gemini            | API ключ или OAuth               | По подразбиране | Използва `x-goog-api-key` заглавка                 |
-| Google Gemini CLI        | OAuth                            | GeminiCLI       | Използва `streamGenerateContent` крайна точка      |
-| Антигравитация           | OAuth                            | Антигравитация  | Multi-URL резервен, персонализиран повторен анализ |
-| OpenAI                   | API ключ                         | По подразбиране | Удостоверяване на стандартен носител               |
-| Кодекс                   | OAuth                            | Кодекс          | Инжектира системни инструкции, управлява мисленето |
-| Копилот на GitHub        | OAuth + Copilot token            | Github          | Двоен токен, имитираща заглавка на VSCode          |
-| Киро (AWS)               | AWS SSO OIDC или социални        | Киро            | Парсинг на двоичен EventStream                     |
-| Курсор IDE               | Контролна сума за удостоверяване | Курсор          | Protobuf кодиране, SHA-256 контролни суми          |
-| Куен                     | OAuth                            | По подразбиране | Стандартно удостоверяване                          |
-| iFlow                    | OAuth (основен + носител)        | По подразбиране | Заглавка за двойно удостоверяване                  |
-| OpenRouter               | API ключ                         | По подразбиране | Удостоверяване на стандартен носител               |
-| GLM, Kimi, MiniMax       | API ключ                         | По подразбиране | Съвместим с Claude, използвайте `x-api-key`        |
-| `openai-compatible-*`    | API ключ                         | По подразбиране | Динамично: всяка крайна точка, съвместима с OpenAI |
-| `anthropic-compatible-*` | API ключ                         | По подразбиране | Динамично: всяка крайна точка, съвместима с Claude |
+| Provider                 | Auth Method            | Executor    | Key Notes                                     |
+| ------------------------ | ---------------------- | ----------- | --------------------------------------------- |
+| Anthropic Claude         | API key or OAuth       | Default     | Uses `x-api-key` header                       |
+| Google Gemini            | API key or OAuth       | Default     | Uses `x-goog-api-key` header                  |
+| Google Gemini CLI        | OAuth                  | GeminiCLI   | Uses `streamGenerateContent` endpoint         |
+| Antigravity              | OAuth                  | Antigravity | Multi-URL fallback, custom retry parsing      |
+| OpenAI                   | API key                | Default     | Standard Bearer auth                          |
+| Codex                    | OAuth                  | Codex       | Injects system instructions, manages thinking |
+| GitHub Copilot           | OAuth + Copilot token  | Github      | Dual token, VSCode header mimicking           |
+| 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                              |
+| 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       |
+| `anthropic-compatible-*` | API key                | Default     | Dynamic: any Claude-compatible endpoint       |
 
 ---
 
-## 8. Резюме на потока от данни
+## 8. Data Flow Summary
 
-### Заявка за поточно предаване
+### Streaming Request
 
 ```mermaid
 flowchart LR
@@ -566,7 +570,7 @@ flowchart LR
     K --> L["logUsage()\nsaveRequestUsage()"]
 ```
 
-### Заявка без поточно предаване
+### Non-Streaming Request
 
 ```mermaid
 flowchart LR
@@ -577,7 +581,7 @@ flowchart LR
     E --> F["Return JSON\nresponse"]
 ```
 
-### Байпасен поток (Claude CLI)
+### Bypass Flow (Claude CLI)
 
 ```mermaid
 flowchart LR

docs/i18n/bg/FEATURES.md

@@ -1,77 +1,148 @@
-# OmniRoute — Галерия с функции на таблото
-
-🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md)
-
-Визуално ръководство за всеки раздел на таблото за управление OmniRoute.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/FEATURES.md) · 🇪🇸 [es](../es/FEATURES.md) · 🇫🇷 [fr](../fr/FEATURES.md) · 🇩🇪 [de](../de/FEATURES.md) · 🇮🇹 [it](../it/FEATURES.md) · 🇷🇺 [ru](../ru/FEATURES.md) · 🇨🇳 [zh-CN](../zh-CN/FEATURES.md) · 🇯🇵 [ja](../ja/FEATURES.md) · 🇰🇷 [ko](../ko/FEATURES.md) · 🇸🇦 [ar](../ar/FEATURES.md) · 🇮🇳 [in](../in/FEATURES.md) · 🇹🇭 [th](../th/FEATURES.md) · 🇻🇳 [vi](../vi/FEATURES.md) · 🇮🇩 [id](../id/FEATURES.md) · 🇲🇾 [ms](../ms/FEATURES.md) · 🇳🇱 [nl](../nl/FEATURES.md) · 🇵🇱 [pl](../pl/FEATURES.md) · 🇸🇪 [sv](../sv/FEATURES.md) · 🇳🇴 [no](../no/FEATURES.md) · 🇩🇰 [da](../da/FEATURES.md) · 🇫🇮 [fi](../fi/FEATURES.md) · 🇵🇹 [pt](../pt/FEATURES.md) · 🇷🇴 [ro](../ro/FEATURES.md) · 🇭🇺 [hu](../hu/FEATURES.md) · 🇧🇬 [bg](../bg/FEATURES.md) · 🇸🇰 [sk](../sk/FEATURES.md) · 🇺🇦 [uk-UA](../uk-UA/FEATURES.md) · 🇮🇱 [he](../he/FEATURES.md) · 🇵🇭 [phi](../phi/FEATURES.md)
 
 ---
 
-## 🔌 Доставчици
+# OmniRoute — Dashboard Features Gallery
 
-Управлявайте връзките на доставчици на AI: OAuth доставчици (Claude Code, Codex, Gemini CLI), доставчици на API ключове (Groq, DeepSeek, OpenRouter) и безплатни доставчици (iFlow, Qwen, Kiro).
+🌐 **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)
+
+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).
+
+- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` (free "Light usage" tier); use `ollamacloud/<model>` prefix
 
 ![Providers Dashboard](screenshots/01-providers.png)
 
 ---
 
-## 🎨 Комбота
+## 🎨 Combos
 
-Създавайте комбинации за маршрутизиране на модели с 6 стратегии: първо попълване, кръгъл робин, мощност от два избора, произволна, най-малко използвана и оптимизирана по отношение на разходите. Всяка комбинация свързва няколко модела с автоматичен резервен вариант.
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
 
 ![Combos Dashboard](screenshots/02-combos.png)
 
 ---
 
-## 📊 Анализ
+## 📊 Analytics
 
-Изчерпателни анализи на използването с потребление на токени, оценки на разходите, топлинни карти на активността, седмични диаграми на разпределение и разбивки по доставчик.
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
 
 ![Analytics Dashboard](screenshots/03-analytics.png)
 
 ---
 
-## 🏥 Здраве на системата
+## 🏥 System Health
 
-Мониторинг в реално време: време на работа, памет, версия, процентили на латентност (p50/p95/p99), статистика на кеша и състояния на прекъсвача на доставчика.
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
 
 ![Health Dashboard](screenshots/04-health.png)
 
 ---
 
-## 🔧 Площадка за преводачи
+## 🔧 Translator Playground
 
-Четири режима за отстраняване на грешки в API преводи: **Playground** (конвертор на формати), **Chat Tester** (заявки на живо), **Test Bench** (пакетни тестове) и **Live Monitor** (поток в реално време).
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
 
 ![Translator Playground](screenshots/05-translator.png)
 
 ---
 
-## ⚙️ Настройки
+## 🎮 Model Playground _(v2.0.9+)_
 
-Общи настройки, системно съхранение, управление на архивиране (база данни за експортиране/импортиране), външен вид (тъмен/светъл режим), сигурност (включва защита на крайна точка на API и блокиране на потребителски доставчик), маршрутизиране, устойчивост и разширена конфигурация.
+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
+
+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
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
 
 ![Settings Dashboard](screenshots/06-settings.png)
 
 ---
 
-## 🔧 CLI инструменти
+## 🔧 CLI Tools
 
-Конфигурация с едно щракване за инструменти за кодиране на AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code и 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+)_
 
-Регистриране на заявки в реално време с филтриране по доставчик, модел, акаунт и API ключ. Показва кодове за състояние, използване на токени, латентност и подробности за отговора.
+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
+
+---
+
+## 🖼️ 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.
 
 ![Usage Logs](screenshots/08-usage.png)
 
 ---
 
-## 🌐 Крайна точка на API
+## 🌐 API Endpoint
 
-Вашата унифицирана крайна точка на API с разбивка на възможностите: завършвания на чат, вграждания, генериране на изображения, прекласиране, аудио транскрипция и регистрирани ключове за API.
+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. 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)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/bg/MCP-SERVER.md

@@ -0,0 +1,87 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/MCP-SERVER.md) · 🇪🇸 [es](../es/MCP-SERVER.md) · 🇫🇷 [fr](../fr/MCP-SERVER.md) · 🇩🇪 [de](../de/MCP-SERVER.md) · 🇮🇹 [it](../it/MCP-SERVER.md) · 🇷🇺 [ru](../ru/MCP-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/MCP-SERVER.md) · 🇯🇵 [ja](../ja/MCP-SERVER.md) · 🇰🇷 [ko](../ko/MCP-SERVER.md) · 🇸🇦 [ar](../ar/MCP-SERVER.md) · 🇮🇳 [in](../in/MCP-SERVER.md) · 🇹🇭 [th](../th/MCP-SERVER.md) · 🇻🇳 [vi](../vi/MCP-SERVER.md) · 🇮🇩 [id](../id/MCP-SERVER.md) · 🇲🇾 [ms](../ms/MCP-SERVER.md) · 🇳🇱 [nl](../nl/MCP-SERVER.md) · 🇵🇱 [pl](../pl/MCP-SERVER.md) · 🇸🇪 [sv](../sv/MCP-SERVER.md) · 🇳🇴 [no](../no/MCP-SERVER.md) · 🇩🇰 [da](../da/MCP-SERVER.md) · 🇫🇮 [fi](../fi/MCP-SERVER.md) · 🇵🇹 [pt](../pt/MCP-SERVER.md) · 🇷🇴 [ro](../ro/MCP-SERVER.md) · 🇭🇺 [hu](../hu/MCP-SERVER.md) · 🇧🇬 [bg](../bg/MCP-SERVER.md) · 🇸🇰 [sk](../sk/MCP-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/MCP-SERVER.md) · 🇮🇱 [he](../he/MCP-SERVER.md) · 🇵🇭 [phi](../phi/MCP-SERVER.md)
+
+---
+
+# 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                 |
+| `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/i18n/bg/README.md

@@ -20,7 +20,7 @@ _Вашият универсален API прокси — една крайна
 
 </div>
 
-🌐 **Налично на:** 🇺🇸 [английски](README.md) | 🇧🇷 [Португалски (Бразилия)](README.pt-BR.md) | 🇪🇸 [Испански] (README.es.md) | 🇫🇷 [Français](README.fr.md) | 🇮🇹 [италиански] (README.it.md) | 🇷🇺 [Русский](README.ru.md) | 🇨🇳 [中文 (简体)](README.zh-CN.md) | 🇩🇪 [Deutsch](README.de.md) | 🇮🇳 [हिन्दी] (README.in.md) | 🇹🇭 [ไทย](README.th.md) | 🇺🇦 [Українська](README.uk-UA.md) | 🇸🇦 [العربية](README.ar.md) | 🇯🇵 [日本語](README.ja.md) | 🇻🇳 [Tiếng Việt](README.vi.md) | 🇧🇬 [Български](README.bg.md) | 🇩🇰 [Dansk](README.da.md) | 🇫🇮 [Suomi](README.fi.md) | 🇮🇱 [עברית](README.he.md) | 🇭🇺 [маджарски] (README.hu.md) | 🇮🇩 [бахаса Индонезия](README.id.md) | 🇰🇷 [한국어](README.ko.md) | 🇲🇾 [Bahasa Melayu](README.ms.md) | 🇳🇱 [Нидерландия](README.nl.md) | 🇳🇴 [Norsk](README.no.md) | 🇵🇹 [Português (Португалия)](README.pt.md) | 🇷🇴 [Română](README.ro.md) | 🇵🇱 [Полски](README.pl.md) | 🇸🇰 [Slovenčina](README.sk.md) | 🇸🇪 [Svenska](README.sv.md) | 🇵🇭 [филипински] (README.phi.md)
+🌐 **Налично на:** 🇺🇸 [английски](../../README.md) | 🇧🇷 [Португалски (Бразилия)](../pt-BR/README.md) | 🇪🇸 [Испански] (../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [италиански] (../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी] (../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [маджарски] (../hu/README.md) | 🇮🇩 [бахаса Индонезия](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Нидерландия](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Португалия)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Полски](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [филипински] (../phi/README.md)
 
 ---
 
@@ -53,6 +53,18 @@ _Вашият универсален API прокси — една крайна
 
 ---
 
+### 🚀 New in v2.0.9+ — Playground, CLI Fingerprints & ACP
+
+| Feature                                    | What It Does                                                                                                                                  |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🎮 **Model Playground**                    | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing                        |
+| 🔏 **CLI Fingerprint Matching**            | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |
+| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw), process spawner, `/api/acp/agents` endpoint                                 |
+| 🤖 **ACP Agents Dashboard**                | Debug > Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool                                      |
+| 🔧 **Custom Model `apiFormat` Routing**    | Custom models with `apiFormat: "responses"` now correctly route to the Responses API translator                                               |
+| 🏢 **Codex Workspace Isolation**           | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID                                                   |
+| 🔄 **Electron Auto-Update**                | Desktop app checks for updates + auto-install on restart                                                                                      |
+
 ### 🤖 Безплатен доставчик на AI за вашите любими кодиращи агенти
 
 _Свържете всеки базиран на AI IDE или CLI инструмент чрез OmniRoute — безплатен API шлюз за неограничено кодиране._
@@ -253,6 +265,7 @@ OpenAI използва един формат, Claude (Anthropic) използв
 **Как OmniRoute го решава:**
 
 - **Вградени доставчици на безплатни нива** — Вградена поддръжка за 100% безплатни доставчици: iFlow (8 неограничени модела), Qwen (3 неограничени модела), Kiro (Claude безплатно), Gemini CLI (180K/месец безплатно)
+- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/<model>` prefix
 - **Безплатни само комбинации** — Верига `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/месец с нулев престой
 - **NVIDIA NIM безплатни кредити** — интегрирани 1000 безплатни кредита
 - **Стратегия за оптимизиране на разходите** — Стратегия за маршрутизиране, която автоматично избира най-евтиния наличен доставчик
@@ -393,7 +406,7 @@ AI не е просто завършване на чат. Разработчиц
 - **Текст към видео** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) и SD WebUI
 - **Текст към музика** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)
 - **Аудио транскрипция** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3
-- **Текст-към-говор** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, + съществуващи доставчици
+- **Текст-към-говор** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + съществуващи доставчици
 - **Модерации** — `/v1/moderations` — Проверки за безопасност на съдържанието
 - **Прекласиране** — `/v1/rerank` — Прекласиране на уместността на документа
 - **API за отговори** — Пълна `/v1/responses` поддръжка за Codex
@@ -919,17 +932,18 @@ OmniRoute v2.0 е създаден като операционна платфо
 
 ### 🛡️ Устойчивост, сигурност и управление
 
-| Характеристика                               | Какво прави                                                            |
-| -------------------------------------------- | ---------------------------------------------------------------------- |
-| 🔌 **Прекъсвачи**                            | Пътуване/възстановяване на ниво доставчик с прагови контроли           |
-| 🛡️ **Anti-Thundering Herd**                  | Защита на Mutex + семафор при събития за повторен опит/скорост         |
-| 🧠 **Семантичен + кеш на подписа**           | Намаляване на разходите/закъснението с два кеш слоя                    |
-| ⚡ **Искане на идемпотентност**              | Дублиран защитен прозорец                                              |
-| 🔒 **TLS Fingerprint Spoofing**              | По-добра съвместимост с доставчици, филтрирани срещу бот               |
-| 🌐 **IP филтриране**                         | Списък с разрешени/списъци с блокирани контроли за открити внедрявания |
-| 📊 **Редактируеми ограничения на скоростта** | Конфигурируеми глобални/на ниво доставчик ограничения с постоянство    |
-| 🔑 **API Key Management + Scoping**          | Сигурно издаване/ротация на ключове и контроли на модел/доставчик      |
-| 🛡️ **Защитен `/models`**                     | Опционално удостоверяване и скриване на доставчик за каталог на модели |
+| Характеристика                               | Какво прави                                                                            |
+| -------------------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Прекъсвачи**                            | Пътуване/възстановяване на ниво доставчик с прагови контроли                           |
+| 🛡️ **Anti-Thundering Herd**                  | Защита на Mutex + семафор при събития за повторен опит/скорост                         |
+| 🧠 **Семантичен + кеш на подписа**           | Намаляване на разходите/закъснението с два кеш слоя                                    |
+| ⚡ **Искане на идемпотентност**              | Дублиран защитен прозорец                                                              |
+| 🔒 **TLS Fingerprint Spoofing**              | По-добра съвместимост с доставчици, филтрирани срещу бот                               |
+| 🔏 **CLI Fingerprint Matching**              | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
+| 🌐 **IP филтриране**                         | Списък с разрешени/списъци с блокирани контроли за открити внедрявания                 |
+| 📊 **Редактируеми ограничения на скоростта** | Конфигурируеми глобални/на ниво доставчик ограничения с постоянство                    |
+| 🔑 **API Key Management + Scoping**          | Сигурно издаване/ротация на ключове и контроли на модел/доставчик                      |
+| 🛡️ **Защитен `/models`**                     | Опционално удостоверяване и скриване на доставчик за каталог на модели                 |
 
 ### 📊 Наблюдаемост и анализ
 

docs/i18n/bg/RELEASE_CHECKLIST.md

@@ -0,0 +1,37 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) · 🇪🇸 [es](../es/RELEASE_CHECKLIST.md) · 🇫🇷 [fr](../fr/RELEASE_CHECKLIST.md) · 🇩🇪 [de](../de/RELEASE_CHECKLIST.md) · 🇮🇹 [it](../it/RELEASE_CHECKLIST.md) · 🇷🇺 [ru](../ru/RELEASE_CHECKLIST.md) · 🇨🇳 [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) · 🇯🇵 [ja](../ja/RELEASE_CHECKLIST.md) · 🇰🇷 [ko](../ko/RELEASE_CHECKLIST.md) · 🇸🇦 [ar](../ar/RELEASE_CHECKLIST.md) · 🇮🇳 [in](../in/RELEASE_CHECKLIST.md) · 🇹🇭 [th](../th/RELEASE_CHECKLIST.md) · 🇻🇳 [vi](../vi/RELEASE_CHECKLIST.md) · 🇮🇩 [id](../id/RELEASE_CHECKLIST.md) · 🇲🇾 [ms](../ms/RELEASE_CHECKLIST.md) · 🇳🇱 [nl](../nl/RELEASE_CHECKLIST.md) · 🇵🇱 [pl](../pl/RELEASE_CHECKLIST.md) · 🇸🇪 [sv](../sv/RELEASE_CHECKLIST.md) · 🇳🇴 [no](../no/RELEASE_CHECKLIST.md) · 🇩🇰 [da](../da/RELEASE_CHECKLIST.md) · 🇫🇮 [fi](../fi/RELEASE_CHECKLIST.md) · 🇵🇹 [pt](../pt/RELEASE_CHECKLIST.md) · 🇷🇴 [ro](../ro/RELEASE_CHECKLIST.md) · 🇭🇺 [hu](../hu/RELEASE_CHECKLIST.md) · 🇧🇬 [bg](../bg/RELEASE_CHECKLIST.md) · 🇸🇰 [sk](../sk/RELEASE_CHECKLIST.md) · 🇺🇦 [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) · 🇮🇱 [he](../he/RELEASE_CHECKLIST.md) · 🇵🇭 [phi](../phi/RELEASE_CHECKLIST.md)
+
+---
+
+# 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/i18n/bg/TROUBLESHOOTING.md

@@ -1,87 +1,91 @@
-# Отстраняване на неизправности
-
-🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md)
-
-Често срещани проблеми и решения за OmniRoute.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/TROUBLESHOOTING.md) · 🇪🇸 [es](../es/TROUBLESHOOTING.md) · 🇫🇷 [fr](../fr/TROUBLESHOOTING.md) · 🇩🇪 [de](../de/TROUBLESHOOTING.md) · 🇮🇹 [it](../it/TROUBLESHOOTING.md) · 🇷🇺 [ru](../ru/TROUBLESHOOTING.md) · 🇨🇳 [zh-CN](../zh-CN/TROUBLESHOOTING.md) · 🇯🇵 [ja](../ja/TROUBLESHOOTING.md) · 🇰🇷 [ko](../ko/TROUBLESHOOTING.md) · 🇸🇦 [ar](../ar/TROUBLESHOOTING.md) · 🇮🇳 [in](../in/TROUBLESHOOTING.md) · 🇹🇭 [th](../th/TROUBLESHOOTING.md) · 🇻🇳 [vi](../vi/TROUBLESHOOTING.md) · 🇮🇩 [id](../id/TROUBLESHOOTING.md) · 🇲🇾 [ms](../ms/TROUBLESHOOTING.md) · 🇳🇱 [nl](../nl/TROUBLESHOOTING.md) · 🇵🇱 [pl](../pl/TROUBLESHOOTING.md) · 🇸🇪 [sv](../sv/TROUBLESHOOTING.md) · 🇳🇴 [no](../no/TROUBLESHOOTING.md) · 🇩🇰 [da](../da/TROUBLESHOOTING.md) · 🇫🇮 [fi](../fi/TROUBLESHOOTING.md) · 🇵🇹 [pt](../pt/TROUBLESHOOTING.md) · 🇷🇴 [ro](../ro/TROUBLESHOOTING.md) · 🇭🇺 [hu](../hu/TROUBLESHOOTING.md) · 🇧🇬 [bg](../bg/TROUBLESHOOTING.md) · 🇸🇰 [sk](../sk/TROUBLESHOOTING.md) · 🇺🇦 [uk-UA](../uk-UA/TROUBLESHOOTING.md) · 🇮🇱 [he](../he/TROUBLESHOOTING.md) · 🇵🇭 [phi](../phi/TROUBLESHOOTING.md)
 
 ---
 
-## Бързи поправки
+# Troubleshooting
 
-| Проблем                                           | Решение                                                                        |
-| ------------------------------------------------- | ------------------------------------------------------------------------------ |
-| Първото влизане не работи                         | Проверете `INITIAL_PASSWORD` в `.env` (по подразбиране: `123456`)              |
-| Таблото се отваря на грешен порт                  | Задайте `PORT=20128` и `NEXT_PUBLIC_BASE_URL=http://localhost:20128`           |
-| Няма регистрационни файлове за заявки под `logs/` | Задайте `ENABLE_REQUEST_LOGS=true`                                             |
-| EACCES: разрешението е отказано                   | Задайте `DATA_DIR=/path/to/writable/dir` да замени `~/.omniroute`              |
-| Стратегията за маршрутизиране не се запазва       | Актуализация до v1.4.11+ (корекция на Zod схема за постоянство на настройките) |
+🌐 **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)
+
+Common problems and solutions for OmniRoute.
 
 ---
 
-## Проблеми с доставчика
+## Quick Fixes
 
-### „Езиковият модел не предостави съобщения“
-
-**Причина:** Квотата на доставчика е изчерпана.
-
-**Коригиране:**
-
-1. Проверете инструмента за проследяване на квоти на таблото за управление
-2. Използвайте комбо с резервни нива
-3. Преминете към по-евтино/безплатно ниво
-
-### Ограничаване на скоростта
-
-**Причина:** Абонаментната квота е изчерпана.
-
-**Коригиране:**
-
-- Добавете резервен вариант: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-- Използвайте GLM/MiniMax като евтино резервно копие
-
-### OAuth Token е изтекъл
-
-OmniRoute автоматично опреснява токените. Ако проблемите продължават:
-
-1. Табло → Доставчик → Свързване отново
-2. Изтрийте и добавете отново връзката с доставчика
+| 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 request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true`                                     |
+| 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)       |
 
 ---
 
-## Проблеми с облака
+## Provider Issues
 
-### Грешки при синхронизиране в облак
+### "Language model did not provide messages"
 
-1. Проверете дали `BASE_URL` сочи към вашия работещ екземпляр (напр. `http://localhost:20128`)
-2. Проверете `CLOUD_URL` точки към вашата крайна точка в облака (напр. `https://omniroute.dev`)
-3. Поддържайте стойностите на `NEXT_PUBLIC_*` в съответствие със стойностите от страна на сървъра
+**Cause:** Provider quota exhausted.
 
-### Cloud `stream=false` Връща 500
+**Fix:**
 
-**Симптом:** `Unexpected token 'd'...` в крайна точка на облака за обаждания без поточно предаване.
+1. Check dashboard quota tracker
+2. Use a combo with fallback tiers
+3. Switch to cheaper/free tier
 
-**Причина:** Upstream връща SSE полезен товар, докато клиентът очаква JSON.
+### Rate Limiting
 
-**Заобиколно решение:** Използвайте `stream=true` за директни обаждания в облака. Локалното време на изпълнение включва резервен SSE→JSON.
+**Cause:** Subscription quota exhausted.
 
-### Облакът казва Свързан, но „Невалиден API ключ“
+**Fix:**
 
-1. Създайте нов ключ от локалното табло за управление (`/api/keys`)
-2. Стартирайте облачна синхронизация: Активирайте Облак → Синхронизирай сега
-3. Старите/несинхронизирани ключове все още могат да връщат `401` в облака
+- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Use GLM/MiniMax as cheap backup
+
+### OAuth Token Expired
+
+OmniRoute auto-refreshes tokens. If issues persist:
+
+1. Dashboard → Provider → Reconnect
+2. Delete and re-add the provider connection
 
 ---
 
-## Проблеми с Docker
+## Cloud Issues
 
-### CLI инструментът показва, че не е инсталиран
+### Cloud Sync Errors
 
-1. Проверете полетата по време на изпълнение: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
-2. За преносим режим: използвайте целево изображение `runner-cli` (пакетни CLI)
-3. За режим на монтиране на хост: задайте `CLI_EXTRA_PATHS` и монтирайте директорията bin на хоста като само за четене
-4. Ако `installed=true` и `runnable=false`: двоичен файл е намерен, но проверката на състоянието е неуспешна
+1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
+2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
+3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
 
-### Бързо валидиране по време на изпълнение
+### Cloud `stream=false` Returns 500
+
+**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
+
+**Cause:** Upstream returns SSE payload while client expects JSON.
+
+**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
+
+### Cloud Says Connected but "Invalid API key"
+
+1. Create a fresh key from local dashboard (`/api/keys`)
+2. Run cloud sync: Enable Cloud → Sync Now
+3. Old/non-synced keys can still return `401` on cloud
+
+---
+
+## Docker Issues
+
+### CLI Tool Shows Not Installed
+
+1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. For portable mode: use image target `runner-cli` (bundled CLIs)
+3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
+4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
+
+### Quick Runtime Validation
 
 ```bash
 curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
@@ -91,24 +95,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
 
 ---
 
-## Проблеми с разходите
+## Cost Issues
 
-### Високи разходи
+### High Costs
 
-1. Проверете статистическите данни за употреба в Табло → Използване
-2. Превключете основния модел на GLM/MiniMax
-3. Използвайте безплатно ниво (Gemini CLI, iFlow) за некритични задачи
-4. Задайте бюджети за разходи за API ключ: Табло за управление → API ключове → Бюджет
+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
+4. Set cost budgets per API key: Dashboard → API Keys → Budget
 
 ---
 
-## Отстраняване на грешки
+## Debugging
 
-### Активиране на регистрационните файлове на заявките
+### Enable Request Logs
 
-Задайте `ENABLE_REQUEST_LOGS=true` във вашия `.env` файл. Дневниците се появяват в директорията `logs/`.
+Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory.
 
-### Проверете здравето на доставчика
+### Check Provider Health
 
 ```bash
 # Health dashboard
@@ -118,102 +122,137 @@ http://localhost:20128/dashboard/health
 curl http://localhost:20128/api/monitoring/health
 ```
 
-### Съхранение по време на изпълнение
+### Runtime Storage
 
-- Основно състояние: `${DATA_DIR}/db.json` (доставчици, комбинации, псевдоними, ключове, настройки)
-- Използване: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
-- Регистрации за заявки: `<repo>/logs/...` (когато `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}/log.txt` and `${DATA_DIR}/call_logs/`
+- Request logs: `<repo>/logs/...` (when `ENABLE_REQUEST_LOGS=true`)
 
 ---
 
-## Проблеми с прекъсвача
+## Circuit Breaker Issues
 
-### Доставчикът остана в ОТВОРЕНО състояние
+### Provider stuck in OPEN state
 
-Когато прекъсвачът на доставчика е ОТВОРЕЕН, заявките се блокират, докато изтече времето за охлаждане.
+When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
 
-**Коригиране:**
+**Fix:**
 
-1. Отидете на **Табло → Настройки → Устойчивост**
-2. Проверете картата на прекъсвача на засегнатия доставчик
-3. Щракнете върху **Нулиране на всички**, за да изчистите всички прекъсвачи, или изчакайте времето за охлаждане да изтече
-4. Уверете се, че доставчикът действително е наличен, преди да нулирате
+1. Go to **Dashboard → Settings → Resilience**
+2. Check the circuit breaker card for the affected provider
+3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
+4. Verify the provider is actually available before resetting
 
-### Доставчикът продължава да изключва прекъсвача
+### Provider keeps tripping the circuit breaker
 
-Ако доставчик многократно влиза в ОТВОРЕНО състояние:
+If a provider repeatedly enters OPEN state:
 
-1. Проверете **Табло → Здраве → Здраве на доставчика** за модела на повреда
-2. Отидете на **Настройки → Устойчивост → Профили на доставчици** и увеличете прага на отказ
-3. Проверете дали доставчикът е променил ограниченията на API или изисква повторно удостоверяване
-4. Прегледайте телеметрията за латентност — високата латентност може да причини грешки, базирани на изчакване
+1. Check **Dashboard → Health → Provider Health** for the failure pattern
+2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
+3. Check if the provider has changed API limits or requires re-authentication
+4. Review latency telemetry — high latency may cause timeout-based failures
 
 ---
 
-## Проблеми с аудио транскрипцията
+## Audio Transcription Issues
 
-### Грешка „Неподдържан модел“.
+### "Unsupported model" error
 
-- Уверете се, че използвате правилния префикс: `deepgram/nova-3` или `assemblyai/best`
-- Проверете дали доставчикът е свързан в **Табло → Доставчици**
+- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
+- Verify the provider is connected in **Dashboard → Providers**
 
-### Транскрипцията се връща празна или е неуспешна
+### Transcription returns empty or fails
 
-- Проверете поддържаните аудио формати: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
-- Уверете се, че размерът на файла е в границите на доставчика (обикновено < 25MB)
-- Проверете валидността на API ключа на доставчика в картата на доставчика
+- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Verify file size is within provider limits (typically < 25MB)
+- Check provider API key validity in the provider card
 
 ---
 
-## Отстраняване на грешки на преводача
+## Translator Debugging
 
-Използвайте **Табло за управление → Преводач** за отстраняване на грешки при проблеми с превода на формат:
+Use **Dashboard → Translator** to debug format translation issues:
 
-| Режим               | Кога да използвате                                                                                        |
-| ------------------- | --------------------------------------------------------------------------------------------------------- |
-| **Детска площадка** | Сравнете входно/изходните формати един до друг — поставете неуспешна заявка, за да видите как се превежда |
-| **Чат тестер**      | Изпращайте съобщения на живо и проверявайте пълния полезен товар на заявка/отговор, включително заглавки  |
-| **Тестова стенда**  | Изпълнете пакетни тестове в комбинации от формати, за да откриете кои преводи са нарушени                 |
-| **Монитор на живо** | Гледайте потока на заявките в реално време, за да уловите периодични проблеми с превода                   |
+| Mode             | When to Use                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| **Playground**   | Compare input/output formats side by side — paste a failing request to see how it translates |
+| **Chat Tester**  | Send live messages and inspect the full request/response payload including headers           |
+| **Test Bench**   | Run batch tests across format combinations to find which translations are broken             |
+| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues                        |
 
-### Често срещани проблеми с формата
+### Common format issues
 
-- **Мислещите етикети не се появяват** — Проверете дали целевият доставчик поддържа мисленето и настройката на бюджета за мислене
-- **Отпадане на извикванията на инструменти** — Някои преводи на формати може да премахнат неподдържаните полета; потвърдете в режим Playground
-- **Липсва системна подкана** — Клод и Джемини обработват системните подкани по различен начин; проверка на резултата за превод
-- **SDK връща необработен низ вместо обект** — Коригирано във v1.1.0: дезинфекциращото средство за отговор вече премахва нестандартните полета (`x_groq`, `usage_breakdown` и т.н.), които причиняват неуспешно валидиране на OpenAI SDK Pydantic
-- **GLM/ERNIE отхвърля `system` роля** — Коригирано във v1.1.0: нормализаторът на роли автоматично обединява системни съобщения в потребителски съобщения за несъвместими модели
-- **`developer` ролята не е разпозната** — Коригирано във v1.1.0: автоматично преобразувано в `system` за доставчици, които не са OpenAI
-- **`json_schema` не работи с Gemini** — Коригирано във v1.1.0: `response_format` сега се преобразува в `responseMimeType` + `responseSchema` на Gemini
+- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
+- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
+- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
+- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures
+- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
+- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers
+- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema`
 
 ---
 
-## Настройки за устойчивост
+## Resilience Settings
 
-### Автоматичното ограничение на скоростта не се задейства
+### Auto rate-limit not triggering
 
-- Автоматичното ограничение на скоростта се прилага само за доставчици на API ключове (не OAuth/абонамент)
-- Уверете се, че **Настройки → Устойчивост → Профили на доставчици** има активиран автоматичен лимит на скоростта
-- Проверете дали доставчикът връща `429` кодове за състояние или `Retry-After` заглавки
+- Auto rate-limit only applies to API key providers (not OAuth/subscription)
+- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
+- Check if the provider returns `429` status codes or `Retry-After` headers
 
-### Настройване на експоненциално забавяне
+### Tuning exponential backoff
 
-Профилите на доставчика поддържат тези настройки:
+Provider profiles support these settings:
 
-- **Базово забавяне** — Първоначално време на изчакване след първата повреда (по подразбиране: 1s)
-- **Максимално забавяне** — Максимално ограничение на времето за изчакване (по подразбиране: 30 секунди)
-- **Множител** — Колко да се увеличи закъснението за последователен отказ (по подразбиране: 2x)
+- **Base delay** — Initial wait time after first failure (default: 1s)
+- **Max delay** — Maximum wait time cap (default: 30s)
+- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
 
-### Анти-гръмотевично стадо
+### Anti-thundering herd
 
-Когато много едновременни заявки попаднат на доставчик с ограничена скорост, OmniRoute използва mutex + автоматично ограничаване на скоростта, за да сериализира заявките и да предотврати каскадни грешки. Това е автоматично за доставчиците на API ключове.
+When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
 
 ---
 
-## Все още сте заседнали?
+## Optional RAG / LLM failure taxonomy (16 problems)
 
-- **Проблеми с GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Архитектура**: Вижте [link](ARCHITECTURE.md) за вътрешни подробности
-- **API Reference**: Вижте [link](API_REFERENCE.md) за всички крайни точки
-- **Табло за управление на здравето**: Проверете **Табло за управление → Здраве** за състоянието на системата в реално време
-- **Преводач**: Използвайте **Табло за управление → Преводач** за отстраняване на грешки при проблеми с формата
+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)
+- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
+- **Translator**: Use **Dashboard → Translator** to debug format issues

docs/i18n/bg/USER_GUIDE.md

@@ -1,12 +1,16 @@
-# Ръководство за потребителя
-
-🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md)
-
-Пълно ръководство за конфигуриране на доставчици, създаване на комбинации, интегриране на CLI инструменти и внедряване на OmniRoute.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/USER_GUIDE.md) · 🇪🇸 [es](../es/USER_GUIDE.md) · 🇫🇷 [fr](../fr/USER_GUIDE.md) · 🇩🇪 [de](../de/USER_GUIDE.md) · 🇮🇹 [it](../it/USER_GUIDE.md) · 🇷🇺 [ru](../ru/USER_GUIDE.md) · 🇨🇳 [zh-CN](../zh-CN/USER_GUIDE.md) · 🇯🇵 [ja](../ja/USER_GUIDE.md) · 🇰🇷 [ko](../ko/USER_GUIDE.md) · 🇸🇦 [ar](../ar/USER_GUIDE.md) · 🇮🇳 [in](../in/USER_GUIDE.md) · 🇹🇭 [th](../th/USER_GUIDE.md) · 🇻🇳 [vi](../vi/USER_GUIDE.md) · 🇮🇩 [id](../id/USER_GUIDE.md) · 🇲🇾 [ms](../ms/USER_GUIDE.md) · 🇳🇱 [nl](../nl/USER_GUIDE.md) · 🇵🇱 [pl](../pl/USER_GUIDE.md) · 🇸🇪 [sv](../sv/USER_GUIDE.md) · 🇳🇴 [no](../no/USER_GUIDE.md) · 🇩🇰 [da](../da/USER_GUIDE.md) · 🇫🇮 [fi](../fi/USER_GUIDE.md) · 🇵🇹 [pt](../pt/USER_GUIDE.md) · 🇷🇴 [ro](../ro/USER_GUIDE.md) · 🇭🇺 [hu](../hu/USER_GUIDE.md) · 🇧🇬 [bg](../bg/USER_GUIDE.md) · 🇸🇰 [sk](../sk/USER_GUIDE.md) · 🇺🇦 [uk-UA](../uk-UA/USER_GUIDE.md) · 🇮🇱 [he](../he/USER_GUIDE.md) · 🇵🇭 [phi](../phi/USER_GUIDE.md)
 
 ---
 
-## Съдържание
+# 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)
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
+
+## Table of Contents
 
 - [Pricing at a Glance](#-pricing-at-a-glance)
 - [Use Cases](#-use-cases)
@@ -18,40 +22,40 @@
 
 ---
 
-## 💰 Ценообразуването с един поглед
+## 💰 Pricing at a Glance
 
-| Ниво               | Доставчик         | Цена                  | Нулиране на квота       | Най-добро за              |
-| ------------------ | ----------------- | --------------------- | ----------------------- | ------------------------- |
-| **💳 АБОНАМЕНТ**   | Claude Code (Pro) | $20/месец             | 5 часа + седмично       | Вече сте абонирани        |
-|                    | Codex (Plus/Pro)  | $20-200/месец         | 5 часа + седмично       | Потребители на OpenAI     |
-|                    | Gemini CLI        | **БЕЗПЛАТНО**         | 180K/месец + 1K/ден     | всички!                   |
-|                    | Копилот на GitHub | $10-19/месец          | Месечно                 | Потребители на GitHub     |
-| **🔑 КЛЮЧ ЗА API** | DeepSeek          | Плащане за използване | Няма                    | Евтини разсъждения        |
-|                    | Groq              | Плащане за използване | Няма                    | Свръхбърз извод           |
-|                    | xAI (Grok)        | Плащане за използване | Няма                    | Грок 4 разсъждения        |
-|                    | Мистрал           | Плащане за използване | Няма                    | Хоствани в ЕС модели      |
-|                    | Недоумение        | Плащане за използване | Няма                    | Разширено търсене         |
-|                    | Заедно AI         | Плащане за използване | Няма                    | Модели с отворен код      |
-|                    | Фойерверки AI     | Плащане за използване | Няма                    | Бързи FLUX изображения    |
-|                    | Мозъци            | Плащане за използване | Няма                    | Скорост на вафла          |
-|                    | Cohere            | Плащане за използване | Няма                    | Команда R+ RAG            |
-|                    | NVIDIA NIM        | Плащане за използване | Няма                    | Корпоративни модели       |
-| **💰 ЕВТИНО**      | GLM-4.7           | $0,6/1 милион         | Ежедневно 10 сутринта   | Резервно копие на бюджета |
-|                    | MiniMax M2.1      | $0,2/1 милион         | 5-часово търкаляне      | Най-евтиният вариант      |
-|                    | Кими К2           | $9/месец апартамент   | 10 милиона токена/месец | Предвидими разходи        |
-| **🆓 БЕЗПЛАТНО**   | iFlow             | $0                    | Неограничен             | 8 модела безплатно        |
-|                    | Куен              | $0                    | Неограничен             | 3 модела безплатно        |
-|                    | Киро              | $0                    | Неограничен             | Клод безплатно            |
+| Tier                | Provider          | Cost        | Quota Reset      | Best For             |
+| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |
+| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo      | 5h + weekly      | Already subscribed   |
+|                     | Codex (Plus/Pro)  | $20-200/mo  | 5h + weekly      | OpenAI users         |
+|                     | Gemini CLI        | **FREE**    | 180K/mo + 1K/day | Everyone!            |
+|                     | GitHub Copilot    | $10-19/mo   | Monthly          | GitHub users         |
+| **🔑 API KEY**      | DeepSeek          | Pay per use | None             | Cheap reasoning      |
+|                     | Groq              | Pay per use | None             | Ultra-fast inference |
+|                     | xAI (Grok)        | Pay per use | None             | Grok 4 reasoning     |
+|                     | Mistral           | Pay per use | None             | EU-hosted models     |
+|                     | Perplexity        | Pay per use | None             | Search-augmented     |
+|                     | Together AI       | Pay per use | None             | Open-source models   |
+|                     | Fireworks AI      | Pay per use | None             | Fast FLUX images     |
+|                     | Cerebras          | Pay per use | None             | Wafer-scale speed    |
+|                     | Cohere            | Pay per use | None             | Command R+ RAG       |
+|                     | NVIDIA NIM        | Pay per use | None             | Enterprise models    |
+| **💰 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        |
+|                     | Qwen              | $0          | Unlimited        | 3 models free        |
+|                     | Kiro              | $0          | Unlimited        | Claude free          |
 
-**💡 Професионален съвет:** Започнете с Gemini CLI (180K безплатно/месец) + iFlow (неограничено безплатно) комбинация = $0 цена!
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost!
 
 ---
 
-## 🎯 Случаи на употреба
+## 🎯 Use Cases
 
-### Случай 1: „Имам абонамент за Claude Pro“
+### Case 1: "I have Claude Pro subscription"
 
-**Проблем:** Квотата изтича неизползвана, ограничения на скоростта по време на тежко кодиране
+**Problem:** Quota expires unused, rate limits during heavy coding
 
 ```
 Combo: "maximize-claude"
@@ -63,9 +67,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
 vs. $20 + hitting limits = frustration
 ```
 
-### Случай 2: „Искам нулеви разходи“
+### Case 2: "I want zero cost"
 
-**Проблем:** Не мога да си позволя абонаменти, имам нужда от надеждно AI кодиране
+**Problem:** Can't afford subscriptions, need reliable AI coding
 
 ```
 Combo: "free-forever"
@@ -77,9 +81,9 @@ Monthly cost: $0
 Quality: Production-ready models
 ```
 
-### Случай 3: „Имам нужда от кодиране 24/7, без прекъсвания“
+### Case 3: "I need 24/7 coding, no interruptions"
 
-**Проблем:** Крайни срокове, не мога да си позволя престой
+**Problem:** Deadlines, can't afford downtime
 
 ```
 Combo: "always-on"
@@ -93,9 +97,9 @@ Result: 5 layers of fallback = zero downtime
 Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
 ```
 
-### Случай 4: „Искам БЕЗПЛАТЕН AI в OpenClaw“
+### Case 4: "I want FREE AI in OpenClaw"
 
-**Проблем:** Имате нужда от AI асистент в приложенията за съобщения, напълно безплатно
+**Problem:** Need AI assistant in messaging apps, completely free
 
 ```
 Combo: "openclaw-free"
@@ -109,9 +113,9 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 
 ---
 
-## 📖 Настройка на доставчик
+## 📖 Provider Setup
 
-### 🔐 Доставчици на абонаменти
+### 🔐 Subscription Providers
 
 #### Claude Code (Pro/Max)
 
@@ -126,7 +130,7 @@ Models:
   cc/claude-haiku-4-5-20251001
 ```
 
-**Професионален съвет:** Използвайте Opus за сложни задачи, Sonnet за скорост. OmniRoute проследява квота за модел!
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
 
 #### OpenAI Codex (Plus/Pro)
 
@@ -140,7 +144,7 @@ Models:
   cx/gpt-5.1-codex-max
 ```
 
-#### Gemini CLI (БЕЗПЛАТНО 180K/месец!)
+#### Gemini CLI (FREE 180K/month!)
 
 ```bash
 Dashboard → Providers → Connect Gemini CLI
@@ -152,9 +156,9 @@ Models:
   gc/gemini-2.5-pro
 ```
 
-**Най-добра стойност:** Огромно безплатно ниво! Използвайте това преди платените нива.
+**Best Value:** Huge free tier! Use this before paid tiers.
 
-#### Копилот на GitHub
+#### GitHub Copilot
 
 ```bash
 Dashboard → Providers → Connect GitHub
@@ -167,33 +171,33 @@ Models:
   gh/gemini-3-pro
 ```
 
-### 💰 Евтини доставчици
+### 💰 Cheap Providers
 
-#### GLM-4.7 (Ежедневно нулиране, $0,6/1 млн.)
+#### GLM-4.7 (Daily reset, $0.6/1M)
 
-1. Регистрирайте се: [Zhipu AI](https://open.bigmodel.cn/)
-2. Вземете API ключ от Coding Plan
-3. Табло → Добавяне на API ключ: Доставчик: `glm`, API ключ: `your-key`
+1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)
+2. Get API key from Coding Plan
+3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`
 
-**Използване:** `glm/glm-4.7` — **Професионален съвет:** Планът за кодиране предлага 3× квота на цена 1/7! Нулирайте всеки ден в 10:00 ч.
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
 
-#### MiniMax M2.1 (5 часа нулиране, $0,20/1 млн.)
+#### MiniMax M2.1 (5h reset, $0.20/1M)
 
-1. Регистрирайте се: [MiniMax](https://www.minimax.io/)
-2. Вземете API ключ → Табло → Добавете API ключ
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
 
-**Използване:** `minimax/MiniMax-M2.1` — **Професионален съвет:** Най-евтината опция за дълъг контекст (1M токени)!
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
 
-#### Kimi K2 ($9/месец фиксиран)
+#### Kimi K2 ($9/month flat)
 
-1. Абонирайте се: [Moonshot AI](https://platform.moonshot.ai/)
-2. Вземете API ключ → Табло → Добавете API ключ
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
 
-**Използване:** `kimi/kimi-latest` — **Професионален съвет:** Фиксирани $9/месец за 10 милиона токена = $0,90/1 милион ефективна цена!
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
 
-### 🆓 БЕЗПЛАТНИ доставчици
+### 🆓 FREE Providers
 
-#### iFlow (8 БЕЗПЛАТНИ модела)
+#### iFlow (8 FREE models)
 
 ```bash
 Dashboard → Connect iFlow → OAuth login → Unlimited usage
@@ -201,7 +205,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage
 Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1
 ```
 
-#### Qwen (3 БЕЗПЛАТНИ модела)
+#### Qwen (3 FREE models)
 
 ```bash
 Dashboard → Connect Qwen → Device code auth → Unlimited usage
@@ -209,7 +213,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage
 Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
 ```
 
-#### Киро (Клод БЕЗПЛАТНО)
+#### Kiro (Claude FREE)
 
 ```bash
 Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
@@ -219,9 +223,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
 
 ---
 
-## 🎨 Комбота
+## 🎨 Combos
 
-### Пример 1: Увеличаване на абонамента → Евтино архивиране
+### Example 1: Maximize Subscription → Cheap Backup
 
 ```
 Dashboard → Combos → Create New
@@ -235,7 +239,7 @@ Models:
 Use in CLI: premium-coding
 ```
 
-### Пример 2: Само безплатно (нулева цена)
+### Example 2: Free-Only (Zero Cost)
 
 ```
 Name: free-combo
@@ -249,9 +253,9 @@ Cost: $0 forever!
 
 ---
 
-## 🔧 CLI интеграция
+## 🔧 CLI Integration
 
-### Курсор IDE
+### Cursor IDE
 
 ```
 Settings → Models → Advanced:
@@ -260,9 +264,9 @@ Settings → Models → Advanced:
   Model: cc/claude-opus-4-6
 ```
 
-### Клод Код
+### Claude Code
 
-Редактиране на `~/.claude/config.json`:
+Edit `~/.claude/config.json`:
 
 ```json
 {
@@ -281,7 +285,7 @@ codex "your prompt"
 
 ### OpenClaw
 
-Редактиране на `~/.openclaw/openclaw.json`:
+Edit `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -303,9 +307,9 @@ codex "your prompt"
 }
 ```
 
-**Или използвайте таблото за управление:** CLI инструменти → OpenClaw → Автоматично конфигуриране
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
 
-### Cline / Продължи / RooCode
+### Cline / Continue / RooCode
 
 ```
 Provider: OpenAI Compatible
@@ -316,9 +320,28 @@ Model: cc/claude-opus-4-6
 
 ---
 
-## 🚀 Внедряване
+## 🚀 Deployment
 
-### Внедряване на VPS
+### 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
 git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -337,7 +360,44 @@ 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
 # Build image (default = runner-cli with codex/claude/droid preinstalled)
@@ -347,51 +407,54 @@ docker build -t omniroute:cli .
 docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
 ```
 
-За интегриран в хост режим с двоични файлове на CLI вижте раздела Docker в основните документи.
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
 
-### Променливи на средата
+### Environment Variables
 
-| Променлива            | По подразбиране                        | Описание                                                                     |
-| --------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
-| `JWT_SECRET`          | `omniroute-default-secret-change-me`   | Тайна за подписване на JWT (**промяна в производството**)                    |
-| `INITIAL_PASSWORD`    | `123456`                               | Първа парола за влизане                                                      |
-| `DATA_DIR`            | `~/.omniroute`                         | Директория с данни (db, използване, регистрационни файлове)                  |
-| `PORT`                | рамка по подразбиране                  | Сервизен порт (`20128` в примерите)                                          |
-| `HOSTNAME`            | рамка по подразбиране                  | Свързване на хост (Docker по подразбиране е `0.0.0.0`)                       |
-| `NODE_ENV`            | по подразбиране по време на изпълнение | Задайте `production` за внедряване                                           |
-| `BASE_URL`            | `http://localhost:20128`               | Вътрешен основен URL адрес от страната на сървъра                            |
-| `CLOUD_URL`           | `https://omniroute.dev`                | Основен URL адрес на крайна точка за синхронизиране в облак                  |
-| `API_KEY_SECRET`      | `endpoint-proxy-api-key-secret`        | HMAC тайна за генерирани API ключове                                         |
-| `REQUIRE_API_KEY`     | `false`                                | Прилагане на API ключ на носител на `/v1/*`                                  |
-| `ENABLE_REQUEST_LOGS` | `false`                                | Разрешава регистрационни файлове за заявки/отговори                          |
-| `AUTH_COOKIE_SECURE`  | `false`                                | Принудително `Secure` бисквитка за удостоверяване (зад HTTPS обратен прокси) |
+| 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) |
+| `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                              |
 
-За пълната справка за променливите на средата вижте [README](../README.md).
+For the full environment variable reference, see the [README](../README.md).
 
 ---
 
-## 📊 Налични модели
+## 📊 Available Models
 
 <details>
-<summary><b>Вижте всички налични модели</b></summary>
+<summary><b>View all available models</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`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
 
 **GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
 
-**GLM (`glm/`)** — $0,6/1 млн.: `glm/glm-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
 
-**MiniMax (`minimax/`)** — $0,2/1 млн.: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
 
-**iFlow (`if/`)** — БЕЗПЛАТНО: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
 
-**Qwen (`qw/`)** — БЕЗПЛАТНО: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
 
-**Киро (`kr/`)** — БЕЗПЛАТНО: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
 
 **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
 
@@ -399,13 +462,13 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat
 
 **xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
 
-**Мистрал (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
 
-**Недоумение (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
 
-**Заедно AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
 
-**Фойерверки AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
 
 **Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
 
@@ -417,11 +480,11 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat
 
 ---
 
-## 🧩 Разширени функции
+## 🧩 Advanced Features
 
-### Персонализирани модели
+### Custom Models
 
-Добавете всеки ID на модел към всеки доставчик, без да чакате актуализация на приложението:
+Add any model ID to any provider without waiting for an app update:
 
 ```bash
 # Via API
@@ -433,11 +496,11 @@ curl -X POST http://localhost:20128/api/provider-models \
 # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
 ```
 
-Или използвайте таблото за управление: **Доставчици → [Доставчик] → Персонализирани модели**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
 
-### Специализирани маршрути на доставчик
+### Dedicated Provider Routes
 
-Насочвайте заявките директно към конкретен доставчик с валидиране на модела:
+Route requests directly to a specific provider with model validation:
 
 ```bash
 POST http://localhost:20128/v1/providers/openai/chat/completions
@@ -445,9 +508,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings
 POST http://localhost:20128/v1/providers/fireworks/images/generations
 ```
 
-Префиксът на доставчика се добавя автоматично, ако липсва. Несъответстващите модели връщат `400`.
+The provider prefix is auto-added if missing. Mismatched models return `400`.
 
-### Конфигурация на мрежов прокси
+### Network Proxy Configuration
 
 ```bash
 # Set global proxy
@@ -463,76 +526,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \
   -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
 ```
 
-**Приоритет:** Специфичен за ключ → Специфичен за комбинация → Специфичен за доставчик → Глобален → Среда.
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
 
-### API за каталог на модели
+### Model Catalog API
 
 ```bash
 curl http://localhost:20128/api/models/catalog
 ```
 
-Връща модели, групирани по доставчик с типове (`chat`, `embedding`, `image`).
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
 
-### Облачно синхронизиране
+### Cloud Sync
 
-- Синхронизиране на доставчици, комбинации и настройки на всички устройства
-- Автоматична фонова синхронизация с изчакване + бързо отказване
-- Предпочитане на сървъра `BASE_URL`/`CLOUD_URL` в производството
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
 
-### LLM Gateway Intelligence (Фаза 9)
+### LLM Gateway Intelligence (Phase 9)
 
-- **Семантичен кеш** — Автоматично кешира нестрийминг, температура=0 отговори (заобикаляне с `X-OmniRoute-No-Cache: true`)
-- **Request Idempotency** — Дедупликира заявките в рамките на 5s чрез `Idempotency-Key` или `X-Request-Id` заглавка
-- **Проследяване на напредъка** — Включване на SSE `event: progress` събития чрез `X-OmniRoute-Progress: true` заглавка
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
 
 ---
 
-### Площадка за преводачи
+### Translator Playground
 
-Достъп чрез **Табло → Преводач**. Отстранете грешки и визуализирайте как OmniRoute превежда API заявки между доставчици.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
 
-| Режим               | Цел                                                                                                  |
-| ------------------- | ---------------------------------------------------------------------------------------------------- |
-| **Детска площадка** | Изберете изходни/целеви формати, поставете заявка и незабавно вижте преведения резултат              |
-| **Чат тестер**      | Изпращайте чат съобщения на живо през проксито и проверявайте пълния цикъл на заявка/отговор         |
-| **Тестова стенда**  | Изпълнете групови тестове в множество комбинации от формати, за да проверите правилността на превода |
-| **Монитор на живо** | Гледайте преводи в реално време, докато заявките преминават през проксито                            |
+| Mode             | Purpose                                                                                |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground**   | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester**  | Send live chat messages through the proxy and inspect the full request/response cycle  |
+| **Test Bench**   | Run batch tests across multiple format combinations to verify translation correctness  |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy                        |
 
-**Случаи на употреба:**
+**Use cases:**
 
-- Отстраняване на грешки защо конкретна комбинация клиент/доставчик е неуспешна
-- Проверете дали мислещите тагове, извикванията на инструменти и системните подкани се превеждат правилно
-- Сравнете разликите във форматите между форматите OpenAI, Claude, Gemini и Responses API
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
 
 ---
 
-### Стратегии за маршрутизиране
+### Routing Strategies
 
-Конфигурирайте чрез **Табло → Настройки → Маршрутизация**.
+Configure via **Dashboard → Settings → Routing**.
 
-| Стратегия                    | Описание                                                                                                       |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| **Първо попълване**          | Използва акаунти в приоритетен ред — основният акаунт обработва всички заявки, докато стане недостъпен         |
-| **Round Robin**              | Преминава през всички акаунти с конфигурируем лепкав лимит (по подразбиране: 3 обаждания на акаунт)            |
-| **P2C (Сила на два избора)** | Избира 2 произволни акаунта и маршрути към по-здравословния — балансира натоварването с осъзнаване на здравето |
-| **Произволно**               | Произволно избира акаунт за всяка заявка чрез разбъркване на Fisher-Yates                                      |
-| **Най-малко използвани**     | Насочва към акаунта с най-стария `lastUsedAt` времеви печат, разпределяйки трафика равномерно                  |
-| **Оптимизирани разходи**     | Маршрути към акаунта с най-ниска стойност на приоритет, оптимизиране за доставчици с най-ниска цена            |
+| Strategy                       | Description                                                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First**                 | Uses accounts in priority order — primary account handles all requests until unavailable         |
+| **Round Robin**                | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account)      |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random**                     | Randomly selects an account for each request using Fisher-Yates shuffle                          |
+| **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       |
 
-#### Псевдоними на модели със заместващи символи
+#### Wildcard Model Aliases
 
-Създайте шаблони със заместващи знаци, за да пренасочите имената на моделите:
+Create wildcard patterns to remap model names:
 
 ```
 Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-5-20250929
 Pattern: gpt-*               →  Target: gh/gpt-5.1-codex
 ```
 
-Заместващите знаци поддържат `*` (всякакви знаци) и `?` (единичен знак).
+Wildcards support `*` (any characters) and `?` (single character).
 
-#### Резервни вериги
+#### Fallback Chains
 
-Дефинирайте глобални резервни вериги, които се прилагат за всички заявки:
+Define global fallback chains that apply across all requests:
 
 ```
 Chain: production-fallback
@@ -543,46 +606,46 @@ Chain: production-fallback
 
 ---
 
-### Устойчивост и прекъсвачи
+### Resilience & Circuit Breakers
 
-Конфигурирайте чрез **Табло → Настройки → Устойчивост**.
+Configure via **Dashboard → Settings → Resilience**.
 
-OmniRoute прилага устойчивост на ниво доставчик с четири компонента:
+OmniRoute implements provider-level resilience with four components:
 
-1. **Профили на доставчици** — Конфигурация за всеки доставчик за:
-   - Праг на повреда (колко повреда преди отваряне)
-   - Продължителност на изчакване
-   - Чувствителност на откриване на ограничение на скоростта
-   - Параметри на експоненциално забавяне
+1. **Provider Profiles** — Per-provider configuration for:
+   - Failure threshold (how many failures before opening)
+   - Cooldown duration
+   - Rate limit detection sensitivity
+   - Exponential backoff parameters
 
-2. **Редактируеми ограничения на скоростта** — Настройки по подразбиране на системно ниво, които могат да се конфигурират в таблото за управление:
-   - **Заявки в минута (RPM)** — Максимален брой заявки в минута за акаунт
-   - **Минимално време между заявките** — Минимална разлика в милисекунди между заявките
-   - **Максимални едновременни заявки** — Максимални едновременни заявки за акаунт
-   - Щракнете върху **Редактиране**, за да промените, след това върху **Запазване** или **Отказ**. Стойностите се запазват чрез API за устойчивост.
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+   - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+   - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+   - **Max Concurrent Requests** — Maximum simultaneous requests per account
+   - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
 
-3. **Прекъсвач на веригата** — Проследява повреди на доставчик и автоматично отваря веригата при достигане на праг:
-   - **ЗАТВОРЕНО** (здравословно) — Заявките протичат нормално
-   - **OPEN** — Доставчикът е временно блокиран след повтарящи се повреди
-   - **HALF_OPEN** — Тестване дали доставчикът се е възстановил
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+   - **CLOSED** (Healthy) — Requests flow normally
+   - **OPEN** — Provider is temporarily blocked after repeated failures
+   - **HALF_OPEN** — Testing if provider has recovered
 
-4. **Правила и заключени идентификатори** — Показва състоянието на прекъсвача и заключените идентификатори с възможност за принудително отключване.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
 
-5. **Автоматично откриване на ограничение на скоростта** — Наблюдава заглавките `429` и `Retry-After`, за да избегне проактивно достигане на ограниченията на скоростта на доставчика.
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
 
-**Професионален съвет:** Използвайте бутона **Нулиране на всички**, за да изчистите всички прекъсвачи и изчаквания, когато доставчикът се възстанови от прекъсване.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
 
 ---
 
-### Експорт/импорт на база данни
+### Database Export / Import
 
-Управлявайте резервни копия на бази данни в **Табло → Настройки → Система и съхранение**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
 
-| Действие                             | Описание                                                                                                                                          |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Експортиране на база данни**       | Изтегля текущата база данни SQLite като `.sqlite` файл                                                                                            |
-| **Експортиране на всички (.tar.gz)** | Изтегля пълен резервен архив, включително: база данни, настройки, комбинации, връзки с доставчик (без идентификационни данни), API ключ метаданни |
-| **Импортиране на база данни**        | Качете файл `.sqlite`, за да замените текущата база данни. Автоматично се създава резервно копие преди импортиране                                |
+| 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                          |
 
 ```bash
 # API: Export database
@@ -596,38 +659,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \
   -F "file=@backup.sqlite"
 ```
 
-**Проверка на импортиране:** Импортираният файл се валидира за цялост (проверка на SQLite pragma), необходими таблици (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) и размер (макс. 100MB).
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
 
-**Случаи на употреба:**
+**Use Cases:**
 
-- Мигрирайте OmniRoute между машини
-- Създаване на външни резервни копия за възстановяване след бедствие
-- Споделяне на конфигурации между членовете на екипа (експортиране на всички → споделяне на архив)
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
 
 ---
 
-### Табло за управление на настройките
+### Settings Dashboard
 
-Страницата с настройки е организирана в 5 раздела за лесна навигация:
+The settings page is organized into 5 tabs for easy navigation:
 
-| Раздел             | Съдържание                                                                                                                                          |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Сигурност**      | Настройки за вход/парола, IP контрол на достъпа, API удостоверяване за `/models` и блокиране на доставчик                                           |
-| **Маршрутизиране** | Стратегия за глобално маршрутизиране (6 опции), псевдоними на модели със заместващи символи, резервни вериги, комбинирани настройки по подразбиране |
-| **Устойчивост**    | Профили на доставчици, редактируеми лимити на скоростта, състояние на прекъсвача, политики и заключени идентификатори                               |
-| **AI**             | Обмисляне на конфигурация на бюджета, инжектиране на глобална система, статистика на бързия кеш                                                     |
-| **Разширено**      | Глобална прокси конфигурация (HTTP/SOCKS5)                                                                                                          |
+| Tab            | Contents                                                                                       |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **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 |
+| **AI**         | Thinking budget configuration, global system prompt injection, prompt cache stats              |
+| **Advanced**   | Global proxy configuration (HTTP/SOCKS5)                                                       |
 
 ---
 
-### Управление на разходите и бюджета
+### Costs & Budget Management
 
-Достъп чрез **Табло → Разходи**.
+Access via **Dashboard → Costs**.
 
-| Раздел     | Цел                                                                                                            |
-| ---------- | -------------------------------------------------------------------------------------------------------------- |
-| **Бюджет** | Задайте лимити на разходите за API ключ с дневни/седмични/месечни бюджети и проследяване в реално време        |
-| **Цени**   | Преглеждайте и редактирайте записи за ценообразуване на модела — цена за 1K входно/изходни токени на доставчик |
+| Tab         | Purpose                                                                                  |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget**  | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider       |
 
 ```bash
 # API: Set a budget
@@ -639,13 +702,13 @@ curl -X POST http://localhost:20128/api/usage/budget \
 curl http://localhost:20128/api/usage/budget
 ```
 
-**Проследяване на разходите:** Всяка заявка регистрира използването на токени и изчислява разходите с помощта на таблицата с цените. Вижте разбивки в **Табло за управление → Използване** по доставчик, модел и API ключ.
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
 
 ---
 
-### Аудио транскрипция
+### Audio Transcription
 
-OmniRoute поддържа аудио транскрипция чрез OpenAI-съвместима крайна точка:
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
 
 ```bash
 POST /v1/audio/transcriptions
@@ -659,40 +722,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
   -F "model=deepgram/nova-3"
 ```
 
-Налични доставчици: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
 
-Поддържани аудио формати: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
 
 ---
 
-### Комбинирани стратегии за балансиране
+### Combo Balancing Strategies
 
-Конфигурирайте балансирането за комбо в **Табло за управление → Комбота → Създаване/Редактиране → Стратегия**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
 
-| Стратегия                    | Описание                                                                         |
-| ---------------------------- | -------------------------------------------------------------------------------- |
-| **Round-Robin**              | Върти се през моделите последователно                                            |
-| **Приоритет**                | Винаги пробва първия модел; връща се само при грешка                             |
-| **Произволно**               | Избира произволен модел от комбинацията за всяка заявка                          |
-| **Претеглено**               | Маршрути пропорционално въз основа на зададени тегла за модел                    |
-| **Най-малко използвани**     | Насочва към модела с най-малко скорошни заявки (използва комбинирани показатели) |
-| **Оптимизиран за разходите** | Маршрути до най-евтиния наличен модел (използва ценова таблица)                  |
+| Strategy           | Description                                                              |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin**    | Rotates through models sequentially                                      |
+| **Priority**       | Always tries the first model; falls back only on error                   |
+| **Random**         | Picks a random model from the combo for each request                     |
+| **Weighted**       | Routes proportionally based on assigned weights per model                |
+| **Least-Used**     | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table)              |
 
-Глобалните настройки по подразбиране на комбинацията могат да бъдат зададени в **Табло → Настройки → Маршрут → Настройки по подразбиране на комбинация**.
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
 
 ---
 
-### Здравно табло
+### Health Dashboard
 
-Достъп чрез **Табло → Здраве**. Преглед на здравето на системата в реално време с 6 карти:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
 
-| Карта                        | Какво показва                                                              |
-| ---------------------------- | -------------------------------------------------------------------------- |
-| **Състояние на системата**   | Време на работа, версия, използване на паметта, директория с данни         |
-| **Здраве на доставчика**     | Състояние на прекъсвача за всеки доставчик (затворен/отворен/полуотворен)  |
-| **Ограничения на скоростта** | Активен лимит на изчакване за акаунт с оставащо време                      |
-| **Активни блокировки**       | Доставчици, временно блокирани от политиката за блокиране                  |
-| **Кеш на подписа**           | Статистика на кеша за дедупликация (активни ключове, процент на попадения) |
-| **Телеметрия за забавяне**   | p50/p95/p99 агрегиране на латентност за доставчик                          |
+| Card                  | What It Shows                                               |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status**     | Uptime, version, memory usage, data directory               |
+| **Provider Health**   | Per-provider circuit breaker state (Closed/Open/Half-Open)  |
+| **Rate Limits**       | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts**   | Providers temporarily blocked by the lockout policy         |
+| **Signature Cache**   | Deduplication cache stats (active keys, hit rate)           |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider                |
 
-**Професионален съвет:** Страницата Health се опреснява автоматично на всеки 10 секунди. Използвайте картата на прекъсвача, за да идентифицирате кои доставчици имат проблеми.
+**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/i18n/bg/VM_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,403 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/VM_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../es/VM_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../fr/VM_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../de/VM_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../it/VM_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../ru/VM_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../zh-CN/VM_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../ja/VM_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../ko/VM_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../ar/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [in](../in/VM_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../th/VM_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../vi/VM_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../id/VM_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../ms/VM_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../nl/VM_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../pl/VM_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../sv/VM_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../no/VM_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../da/VM_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../fi/VM_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../pt/VM_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../ro/VM_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../hu/VM_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../bg/VM_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../sk/VM_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../uk-UA/VM_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../he/VM_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../phi/VM_DEPLOYMENT_GUIDE.md)
+
+---
+
+# OmniRoute — Guia de Deploy em VM com Cloudflare
+
+Guia completo para instalar e configurar o OmniRoute em uma VM (VPS) com domínio gerenciado via Cloudflare.
+
+---
+
+## Pré-Requisitos
+
+| 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+       |
+
+**Providers testados**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail.
+
+---
+
+## 1. Configurar a VM
+
+### 1.1 Criar a instância
+
+No seu provider de VPS preferido:
+
+- 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`)
+
+### 1.2 Conectar via SSH
+
+```bash
+ssh root@203.0.113.10
+```
+
+### 1.3 Atualizar o sistema
+
+```bash
+apt update && apt upgrade -y
+```
+
+### 1.4 Instalar Docker
+
+```bash
+# Instalar dependências
+apt install -y ca-certificates curl gnupg
+
+# Adicionar repositório oficial do Docker
+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
+apt update
+apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
+```
+
+### 1.5 Instalar nginx
+
+```bash
+apt install -y nginx
+```
+
+### 1.6 Configurar Firewall (UFW)
+
+```bash
+ufw default deny incoming
+ufw default allow outgoing
+ufw allow 22/tcp    # SSH
+ufw allow 80/tcp    # HTTP (redirect)
+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).
+
+---
+
+## 2. Instalar o OmniRoute
+
+### 2.1 Criar diretório de configuração
+
+```bash
+mkdir -p /opt/omniroute
+```
+
+### 2.2 Criar arquivo de variáveis de ambiente
+
+```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
+STORAGE_ENCRYPTION_KEY_VERSION=v1
+MACHINE_ID_SALT=ALTERE-PARA-SALT-UNICO
+
+# === App ===
+PORT=20128
+NODE_ENV=production
+HOSTNAME=0.0.0.0
+DATA_DIR=/app/data
+STORAGE_DRIVER=sqlite
+ENABLE_REQUEST_LOGS=true
+AUTH_COOKIE_SECURE=false
+REQUIRE_API_KEY=false
+
+# === Domain (altere para seu domínio) ===
+BASE_URL=https://llms.seudominio.com
+NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
+
+# === Cloud Sync (opcional) ===
+# 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.
+
+### 2.3 Iniciar o container
+
+```bash
+docker pull diegosouzapw/omniroute:latest
+
+docker run -d \
+  --name omniroute \
+  --restart unless-stopped \
+  --env-file /opt/omniroute/.env \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+### 2.4 Verificar se está rodando
+
+```bash
+docker ps | grep omniroute
+docker logs omniroute --tail 20
+```
+
+Deve exibir: `[DB] SQLite database ready` e `listening on port 20128`.
+
+---
+
+## 3. Configurar nginx (Reverse Proxy)
+
+### 3.1 Gerar certificado SSL (Cloudflare Origin)
+
+No painel da Cloudflare:
+
+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**
+
+```bash
+mkdir -p /etc/nginx/ssl
+
+# Colar o certificado
+nano /etc/nginx/ssl/origin.crt
+
+# Colar a chave privada
+nano /etc/nginx/ssl/origin.key
+
+chmod 600 /etc/nginx/ssl/origin.key
+```
+
+### 3.2 Configuração do nginx
+
+```bash
+cat > /etc/nginx/sites-available/omniroute << 'NGINX'
+# Default server — bloqueia acesso direto por IP
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    listen 443 ssl default_server;
+    listen [::]:443 ssl default_server;
+    ssl_certificate     /etc/nginx/ssl/origin.crt;
+    ssl_certificate_key /etc/nginx/ssl/origin.key;
+    server_name _;
+    return 444;
+}
+
+# OmniRoute — HTTPS
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    server_name llms.seudominio.com;  # Altere para seu domínio
+
+    ssl_certificate     /etc/nginx/ssl/origin.crt;
+    ssl_certificate_key /etc/nginx/ssl/origin.key;
+    ssl_protocols TLSv1.2 TLSv1.3;
+
+    client_max_body_size 100M;
+
+    location / {
+        proxy_pass http://127.0.0.1:20128;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket support
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_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;
+    }
+}
+
+# HTTP → HTTPS redirect
+server {
+    listen 80;
+    listen [::]:80;
+    server_name llms.seudominio.com;
+    return 301 https://$server_name$request_uri;
+}
+NGINX
+```
+
+### 3.3 Ativar e testar
+
+```bash
+# Remover config padrão
+rm -f /etc/nginx/sites-enabled/default
+
+# Ativar OmniRoute
+ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute
+
+# Testar e recarregar
+nginx -t && systemctl reload nginx
+```
+
+---
+
+## 4. Configurar Cloudflare DNS
+
+### 4.1 Adicionar registro DNS
+
+No painel da Cloudflare → DNS:
+
+| Type | Name   | Content                   | Proxy      |
+| ---- | ------ | ------------------------- | ---------- |
+| A    | `llms` | `203.0.113.10` (IP da VM) | ✅ Proxied |
+
+### 4.2 Configurar SSL
+
+Em **SSL/TLS → Overview**:
+
+- Modo: **Full (Strict)**
+
+Em **SSL/TLS → Edge Certificates**:
+
+- Always Use HTTPS: ✅ On
+- Minimum TLS Version: TLS 1.2
+- Automatic HTTPS Rewrites: ✅ On
+
+### 4.3 Testar
+
+```bash
+curl -sI https://llms.seudominio.com/health
+# Deve retornar HTTP/2 200
+```
+
+---
+
+## 5. Operações e Manutenção
+
+### Atualizar para nova versão
+
+```bash
+docker pull diegosouzapw/omniroute:latest
+docker stop omniroute && docker rm omniroute
+docker run -d --name omniroute --restart unless-stopped \
+  --env-file /opt/omniroute/.env \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+### Ver logs
+
+```bash
+docker logs -f omniroute          # Stream em tempo real
+docker logs omniroute --tail 50   # Últimas 50 linhas
+```
+
+### Backup manual do banco
+
+```bash
+# Copiar dados do volume para o host
+docker cp omniroute:/app/data ./backup-$(date +%F)
+
+# Ou comprimir todo o 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
+
+```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 /"
+docker start omniroute
+```
+
+---
+
+## 6. Segurança Avançada
+
+### Restringir nginx para Cloudflare IPs
+
+```bash
+cat > /etc/nginx/cloudflare-ips.conf << 'CF'
+# Cloudflare IPv4 ranges — atualizar periodicamente
+# https://www.cloudflare.com/ips-v4/
+set_real_ip_from 173.245.48.0/20;
+set_real_ip_from 103.21.244.0/22;
+set_real_ip_from 103.22.200.0/22;
+set_real_ip_from 103.31.4.0/22;
+set_real_ip_from 141.101.64.0/18;
+set_real_ip_from 108.162.192.0/18;
+set_real_ip_from 190.93.240.0/20;
+set_real_ip_from 188.114.96.0/20;
+set_real_ip_from 197.234.240.0/22;
+set_real_ip_from 198.41.128.0/17;
+set_real_ip_from 162.158.0.0/15;
+set_real_ip_from 104.16.0.0/13;
+set_real_ip_from 104.24.0.0/14;
+set_real_ip_from 172.64.0.0/13;
+set_real_ip_from 131.0.72.0/22;
+real_ip_header CF-Connecting-IP;
+CF
+```
+
+Adicionar no `nginx.conf` dentro do bloco `http {}`:
+
+```nginx
+include /etc/nginx/cloudflare-ips.conf;
+```
+
+### Install fail2ban
+
+```bash
+apt install -y fail2ban
+systemctl enable fail2ban
+systemctl start fail2ban
+
+# Verificar status
+fail2ban-client status sshd
+```
+
+### Bloquear acesso direto na porta do Docker
+
+```bash
+# Impedir acesso externo direto à porta 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
+apt install -y iptables-persistent
+netfilter-persistent save
+```
+
+---
+
+## 7. Deploy do Cloud Worker (Opcional)
+
+Para acesso remoto via Cloudflare Workers (sem expor a VM diretamente):
+
+```bash
+# No repositório local
+cd omnirouteCloud
+npm install
+npx wrangler login
+npx wrangler deploy
+```
+
+Ver documentação completa em [omnirouteCloud/README.md](../omnirouteCloud/README.md).
+
+---
+
+## Resumo de Portas
+
+| 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) |

docs/i18n/da/A2A-SERVER.md

@@ -0,0 +1,200 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/A2A-SERVER.md) · 🇪🇸 [es](../es/A2A-SERVER.md) · 🇫🇷 [fr](../fr/A2A-SERVER.md) · 🇩🇪 [de](../de/A2A-SERVER.md) · 🇮🇹 [it](../it/A2A-SERVER.md) · 🇷🇺 [ru](../ru/A2A-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/A2A-SERVER.md) · 🇯🇵 [ja](../ja/A2A-SERVER.md) · 🇰🇷 [ko](../ko/A2A-SERVER.md) · 🇸🇦 [ar](../ar/A2A-SERVER.md) · 🇮🇳 [in](../in/A2A-SERVER.md) · 🇹🇭 [th](../th/A2A-SERVER.md) · 🇻🇳 [vi](../vi/A2A-SERVER.md) · 🇮🇩 [id](../id/A2A-SERVER.md) · 🇲🇾 [ms](../ms/A2A-SERVER.md) · 🇳🇱 [nl](../nl/A2A-SERVER.md) · 🇵🇱 [pl](../pl/A2A-SERVER.md) · 🇸🇪 [sv](../sv/A2A-SERVER.md) · 🇳🇴 [no](../no/A2A-SERVER.md) · 🇩🇰 [da](../da/A2A-SERVER.md) · 🇫🇮 [fi](../fi/A2A-SERVER.md) · 🇵🇹 [pt](../pt/A2A-SERVER.md) · 🇷🇴 [ro](../ro/A2A-SERVER.md) · 🇭🇺 [hu](../hu/A2A-SERVER.md) · 🇧🇬 [bg](../bg/A2A-SERVER.md) · 🇸🇰 [sk](../sk/A2A-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/A2A-SERVER.md) · 🇮🇱 [he](../he/A2A-SERVER.md) · 🇵🇭 [phi](../phi/A2A-SERVER.md)
+
+---
+
+# 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/i18n/da/API_REFERENCE.md

@@ -1,12 +1,16 @@
-# API-reference
-
-🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md)
-
-Komplet reference for alle OmniRoute API-slutpunkter.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/API_REFERENCE.md) · 🇪🇸 [es](../es/API_REFERENCE.md) · 🇫🇷 [fr](../fr/API_REFERENCE.md) · 🇩🇪 [de](../de/API_REFERENCE.md) · 🇮🇹 [it](../it/API_REFERENCE.md) · 🇷🇺 [ru](../ru/API_REFERENCE.md) · 🇨🇳 [zh-CN](../zh-CN/API_REFERENCE.md) · 🇯🇵 [ja](../ja/API_REFERENCE.md) · 🇰🇷 [ko](../ko/API_REFERENCE.md) · 🇸🇦 [ar](../ar/API_REFERENCE.md) · 🇮🇳 [in](../in/API_REFERENCE.md) · 🇹🇭 [th](../th/API_REFERENCE.md) · 🇻🇳 [vi](../vi/API_REFERENCE.md) · 🇮🇩 [id](../id/API_REFERENCE.md) · 🇲🇾 [ms](../ms/API_REFERENCE.md) · 🇳🇱 [nl](../nl/API_REFERENCE.md) · 🇵🇱 [pl](../pl/API_REFERENCE.md) · 🇸🇪 [sv](../sv/API_REFERENCE.md) · 🇳🇴 [no](../no/API_REFERENCE.md) · 🇩🇰 [da](../da/API_REFERENCE.md) · 🇫🇮 [fi](../fi/API_REFERENCE.md) · 🇵🇹 [pt](../pt/API_REFERENCE.md) · 🇷🇴 [ro](../ro/API_REFERENCE.md) · 🇭🇺 [hu](../hu/API_REFERENCE.md) · 🇧🇬 [bg](../bg/API_REFERENCE.md) · 🇸🇰 [sk](../sk/API_REFERENCE.md) · 🇺🇦 [uk-UA](../uk-UA/API_REFERENCE.md) · 🇮🇱 [he](../he/API_REFERENCE.md) · 🇵🇭 [phi](../phi/API_REFERENCE.md)
 
 ---
 
-## Indholdsfortegnelse
+# 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)
+
+Complete reference for all OmniRoute API endpoints.
+
+---
+
+## Table of Contents
 
 - [Chat Completions](#chat-completions)
 - [Embeddings](#embeddings)
@@ -20,7 +24,7 @@ Komplet reference for alle OmniRoute API-slutpunkter.
 
 ---
 
-## Chatafslutninger
+## Chat Completions
 
 ```bash
 POST /v1/chat/completions
@@ -36,21 +40,21 @@ Content-Type: application/json
 }
 ```
 
-### Brugerdefinerede overskrifter
+### Custom Headers
 
-| Overskrift               | Retning   | Beskrivelse                                    |
-| ------------------------ | --------- | ---------------------------------------------- |
-| `X-OmniRoute-No-Cache`   | Anmodning | Indstil til `true` for at omgå cache           |
-| `X-OmniRoute-Progress`   | Anmodning | Indstil til `true` for fremskridtsbegivenheder |
-| `Idempotency-Key`        | Anmodning | Dedup nøgle (5s vindue)                        |
-| `X-Request-Id`           | Anmodning | Alternativ dedup nøgle                         |
-| `X-OmniRoute-Cache`      | Svar      | `HIT` eller `MISS` (ikke-streaming)            |
-| `X-OmniRoute-Idempotent` | Svar      | `true` hvis deduplikeret                       |
-| `X-OmniRoute-Progress`   | Svar      | `enabled` hvis statussporing på                |
+| 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 |
 
 ---
 
-## Indlejringer
+## Embeddings
 
 ```bash
 POST /v1/embeddings
@@ -63,7 +67,7 @@ Content-Type: application/json
 }
 ```
 
-Tilgængelige udbydere: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
 
 ```bash
 # List all embedding models
@@ -72,7 +76,7 @@ GET /v1/embeddings
 
 ---
 
-## Billedgenerering
+## Image Generation
 
 ```bash
 POST /v1/images/generations
@@ -86,7 +90,7 @@ Content-Type: application/json
 }
 ```
 
-Tilgængelige udbydere: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
 
 ```bash
 # List all image models
@@ -95,7 +99,7 @@ GET /v1/images/generations
 
 ---
 
-## Liste over modeller
+## List Models
 
 ```bash
 GET /v1/models
@@ -106,22 +110,22 @@ Authorization: Bearer your-api-key
 
 ---
 
-## Kompatibilitetsslutpunkter
+## Compatibility Endpoints
 
-| Metode | Sti                         | Format                 |
+| Method | Path                        | Format                 |
 | ------ | --------------------------- | ---------------------- |
 | POST   | `/v1/chat/completions`      | OpenAI                 |
-| POST   | `/v1/messages`              | Antropisk              |
-| POST   | `/v1/responses`             | OpenAI-svar            |
+| POST   | `/v1/messages`              | Anthropic              |
+| POST   | `/v1/responses`             | OpenAI Responses       |
 | POST   | `/v1/embeddings`            | OpenAI                 |
 | POST   | `/v1/images/generations`    | OpenAI                 |
-| FÅ     | `/v1/models`                | OpenAI                 |
-| POST   | `/v1/messages/count_tokens` | Antropisk              |
-| FÅ     | `/v1beta/models`            | Tvillingerne           |
-| POST   | `/v1beta/models/{...path}`  | Gemini generer indhold |
+| GET    | `/v1/models`                | OpenAI                 |
+| POST   | `/v1/messages/count_tokens` | Anthropic              |
+| GET    | `/v1beta/models`            | Gemini                 |
+| POST   | `/v1beta/models/{...path}`  | Gemini generateContent |
 | POST   | `/v1/api/chat`              | Ollama                 |
 
-### Dedikerede udbyderruter
+### Dedicated Provider Routes
 
 ```bash
 POST /v1/providers/{provider}/chat/completions
@@ -129,11 +133,11 @@ POST /v1/providers/{provider}/embeddings
 POST /v1/providers/{provider}/images/generations
 ```
 
-Udbyderpræfikset tilføjes automatisk, hvis det mangler. Umatchede modeller returnerer `400`.
+The provider prefix is auto-added if missing. Mismatched models return `400`.
 
 ---
 
-## Semantisk cache
+## Semantic Cache
 
 ```bash
 # Get cache stats
@@ -143,7 +147,7 @@ GET /api/cache
 DELETE /api/cache
 ```
 
-Eksempel på svar:
+Response example:
 
 ```json
 {
@@ -164,152 +168,162 @@ Eksempel på svar:
 
 ## Dashboard & Management
 
-### Godkendelse
+### Authentication
 
-| Slutpunkt                     | Metode  | Beskrivelse          |
-| ----------------------------- | ------- | -------------------- |
-| `/api/auth/login`             | POST    | Log ind              |
-| `/api/auth/logout`            | POST    | Log ud               |
-| `/api/settings/require-login` | GET/PUT | Skift login påkrævet |
+| Endpoint                      | Method  | Description           |
+| ----------------------------- | ------- | --------------------- |
+| `/api/auth/login`             | POST    | Login                 |
+| `/api/auth/logout`            | POST    | Logout                |
+| `/api/settings/require-login` | GET/PUT | Toggle login required |
 
-### Udbyderstyring
+### Provider Management
 
-| Slutpunkt                    | Metode        | Beskrivelse                  |
-| ---------------------------- | ------------- | ---------------------------- |
-| `/api/providers`             | GET/POST      | Liste/opret udbydere         |
-| `/api/providers/[id]`        | GET/SETT/SLET | Administrer en udbyder       |
-| `/api/providers/[id]/test`   | POST          | Test udbyderforbindelse      |
-| `/api/providers/[id]/models` | FÅ            | Liste udbydermodeller        |
-| `/api/providers/validate`    | POST          | Valider udbyderkonfiguration |
-| `/api/provider-nodes*`       | Forskellige   | Udbyder node management      |
-| `/api/provider-models`       | GET/POST/SLET | Brugerdefinerede modeller    |
+| 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            |
 
-### OAuth-flows
+### OAuth Flows
 
-| Slutpunkt                        | Metode      | Beskrivelse           |
-| -------------------------------- | ----------- | --------------------- |
-| `/api/oauth/[provider]/[action]` | Forskellige | Udbyderspecifik OAuth |
+| Endpoint                         | Method  | Description             |
+| -------------------------------- | ------- | ----------------------- |
+| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth |
 
 ### Routing & Config
 
-| Slutpunkt             | Metode      | Beskrivelse                        |
-| --------------------- | ----------- | ---------------------------------- |
-| `/api/models/alias`   | GET/POST    | Modelaliaser                       |
-| `/api/models/catalog` | FÅ          | Alle modeller efter udbyder + type |
-| `/api/combos*`        | Forskellige | Combo management                   |
-| `/api/keys*`          | Forskellige | API nøglestyring                   |
-| `/api/pricing`        | FÅ          | Modelpriser                        |
+| Endpoint              | Method   | Description                   |
+| --------------------- | -------- | ----------------------------- |
+| `/api/models/alias`   | GET/POST | Model aliases                 |
+| `/api/models/catalog` | GET      | All models by provider + type |
+| `/api/combos*`        | Various  | Combo management              |
+| `/api/keys*`          | Various  | API key management            |
+| `/api/pricing`        | GET      | Model pricing                 |
 
-### Brug og analyse
+### Usage & Analytics
 
-| Slutpunkt                   | Metode | Beskrivelse                  |
-| --------------------------- | ------ | ---------------------------- |
-| `/api/usage/history`        | FÅ     | Brugshistorik                |
-| `/api/usage/logs`           | FÅ     | Brugslogs                    |
-| `/api/usage/request-logs`   | FÅ     | Logfiler på anmodningsniveau |
-| `/api/usage/[connectionId]` | FÅ     | Brug pr. forbindelse         |
+| Endpoint                    | Method | Description          |
+| --------------------------- | ------ | -------------------- |
+| `/api/usage/history`        | GET    | Usage history        |
+| `/api/usage/logs`           | GET    | Usage logs           |
+| `/api/usage/request-logs`   | GET    | Request-level logs   |
+| `/api/usage/[connectionId]` | GET    | Per-connection usage |
 
-### Indstillinger
+### Settings
 
-| Slutpunkt                       | Metode  | Beskrivelse                         |
-| ------------------------------- | ------- | ----------------------------------- |
-| `/api/settings`                 | GET/PUT | Generelle indstillinger             |
-| `/api/settings/proxy`           | GET/PUT | Netværk proxy-konfiguration         |
-| `/api/settings/proxy/test`      | POST    | Test proxyforbindelse               |
-| `/api/settings/ip-filter`       | GET/PUT | IP-tilladelsesliste/blokeringsliste |
-| `/api/settings/thinking-budget` | GET/PUT | Begrundelse token budget            |
-| `/api/settings/system-prompt`   | GET/PUT | Global systemprompt                 |
+| 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   |
 
-### Overvågning
+### Monitoring
 
-| Slutpunkt                | Metode  | Beskrivelse           |
-| ------------------------ | ------- | --------------------- |
-| `/api/sessions`          | FÅ      | Aktiv sessionssporing |
-| `/api/rate-limits`       | FÅ      | Satsgrænser pr. konto |
-| `/api/monitoring/health` | FÅ      | Sundhedstjek          |
-| `/api/cache`             | FÅ/SLET | Cache-statistik/ryd   |
+| 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     |
 
-### Sikkerhedskopiering og eksport/import
+### Backup & Export/Import
 
-| Slutpunkt                   | Metode | Beskrivelse                                  |
-| --------------------------- | ------ | -------------------------------------------- |
-| `/api/db-backups`           | FÅ     | Liste over tilgængelige sikkerhedskopier     |
-| `/api/db-backups`           | SÆT    | Opret en manuel backup                       |
-| `/api/db-backups`           | POST   | Gendan fra en specifik sikkerhedskopi        |
-| `/api/db-backups/export`    | FÅ     | Download database som .sqlite-fil            |
-| `/api/db-backups/import`    | POST   | Upload .sqlite-fil for at erstatte databasen |
-| `/api/db-backups/exportAll` | FÅ     | Download fuld backup som .tar.gz-arkiv       |
+| Endpoint                    | Method | Description                             |
+| --------------------------- | ------ | --------------------------------------- |
+| `/api/db-backups`           | GET    | List available backups                  |
+| `/api/db-backups`           | PUT    | Create a manual backup                  |
+| `/api/db-backups`           | POST   | Restore from a specific backup          |
+| `/api/db-backups/export`    | GET    | Download database as .sqlite file       |
+| `/api/db-backups/import`    | POST   | Upload .sqlite file to replace database |
+| `/api/db-backups/exportAll` | GET    | Download full backup as .tar.gz archive |
 
 ### Cloud Sync
 
-| Slutpunkt              | Metode      | Beskrivelse                      |
-| ---------------------- | ----------- | -------------------------------- |
-| `/api/sync/cloud`      | Forskellige | Cloud-synkroniseringsoperationer |
-| `/api/sync/initialize` | POST        | Initialiser synkronisering       |
-| `/api/cloud/*`         | Forskellige | Cloud management                 |
+| Endpoint               | Method  | Description           |
+| ---------------------- | ------- | --------------------- |
+| `/api/sync/cloud`      | Various | Cloud sync operations |
+| `/api/sync/initialize` | POST    | Initialize sync       |
+| `/api/cloud/*`         | Various | Cloud management      |
 
-### CLI-værktøjer
+### CLI Tools
 
-| Slutpunkt                          | Metode | Beskrivelse          |
-| ---------------------------------- | ------ | -------------------- |
-| `/api/cli-tools/claude-settings`   | FÅ     | Claude CLI status    |
-| `/api/cli-tools/codex-settings`    | FÅ     | Codex CLI-status     |
-| `/api/cli-tools/droid-settings`    | FÅ     | Droid CLI status     |
-| `/api/cli-tools/openclaw-settings` | FÅ     | OpenClaw CLI status  |
-| `/api/cli-tools/runtime/[toolId]`  | FÅ     | Generisk CLI runtime |
+| Endpoint                           | Method | Description         |
+| ---------------------------------- | ------ | ------------------- |
+| `/api/cli-tools/claude-settings`   | GET    | Claude CLI status   |
+| `/api/cli-tools/codex-settings`    | GET    | Codex CLI status    |
+| `/api/cli-tools/droid-settings`    | GET    | Droid CLI status    |
+| `/api/cli-tools/openclaw-settings` | GET    | OpenClaw CLI status |
+| `/api/cli-tools/runtime/[toolId]`  | GET    | Generic CLI runtime |
 
-CLI-svar inkluderer: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
+CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
 
-### Modstandsdygtighed og satsgrænser
+### ACP Agents
 
-| Slutpunkt               | Metode  | Beskrivelse                          |
-| ----------------------- | ------- | ------------------------------------ |
-| `/api/resilience`       | GET/PUT | Få/opdater resiliensprofiler         |
-| `/api/resilience/reset` | POST    | Nulstil afbrydere                    |
-| `/api/rate-limits`      | FÅ      | Satsgrænsestatus pr. konto           |
-| `/api/rate-limit`       | FÅ      | Global hastighedsgrænsekonfiguration |
+| 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 |
 
 ### Evals
 
-| Slutpunkt    | Metode   | Beskrivelse                         |
-| ------------ | -------- | ----------------------------------- |
-| `/api/evals` | GET/POST | Liste eval suiter / køre evaluering |
+| Endpoint     | Method   | Description                       |
+| ------------ | -------- | --------------------------------- |
+| `/api/evals` | GET/POST | List eval suites / run evaluation |
 
-### Politikker
+### Policies
 
-| Slutpunkt       | Metode        | Beskrivelse                   |
-| --------------- | ------------- | ----------------------------- |
-| `/api/policies` | GET/POST/SLET | Administrer routingpolitikker |
+| Endpoint        | Method          | Description             |
+| --------------- | --------------- | ----------------------- |
+| `/api/policies` | GET/POST/DELETE | Manage routing policies |
 
-### Overholdelse
+### Compliance
 
-| Slutpunkt                   | Metode | Beskrivelse                          |
-| --------------------------- | ------ | ------------------------------------ |
-| `/api/compliance/audit-log` | FÅ     | Overholdelsesrevisionslog (sidste N) |
+| Endpoint                    | Method | Description                   |
+| --------------------------- | ------ | ----------------------------- |
+| `/api/compliance/audit-log` | GET    | Compliance audit log (last N) |
 
-### v1beta (Gemini-kompatibel)
+### v1beta (Gemini-Compatible)
 
-| Slutpunkt                  | Metode | Beskrivelse                        |
-| -------------------------- | ------ | ---------------------------------- |
-| `/v1beta/models`           | FÅ     | Vis modeller i Gemini-format       |
-| `/v1beta/models/{...path}` | POST   | Gemini `generateContent` slutpunkt |
+| Endpoint                   | Method | Description                       |
+| -------------------------- | ------ | --------------------------------- |
+| `/v1beta/models`           | GET    | List models in Gemini format      |
+| `/v1beta/models/{...path}` | POST   | Gemini `generateContent` endpoint |
 
-Disse endepunkter afspejler Geminis API-format for klienter, der forventer indbygget Gemini SDK-kompatibilitet.
+These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility.
 
-### Interne / System API'er
+### Internal / System APIs
 
-| Slutpunkt       | Metode | Beskrivelse                                               |
-| --------------- | ------ | --------------------------------------------------------- |
-| `/api/init`     | FÅ     | Applikationsinitieringskontrol (bruges ved første kørsel) |
-| `/api/tags`     | FÅ     | Ollama-kompatible modelmærker (til Ollama-kunder)         |
-| `/api/restart`  | POST   | Udløs yndefuld servergenstart                             |
-| `/api/shutdown` | POST   | Udløs yndefuld serverlukning                              |
+| Endpoint        | Method | Description                                          |
+| --------------- | ------ | ---------------------------------------------------- |
+| `/api/init`     | GET    | Application initialization check (used on first run) |
+| `/api/tags`     | GET    | Ollama-compatible model tags (for Ollama clients)    |
+| `/api/restart`  | POST   | Trigger graceful server restart                      |
+| `/api/shutdown` | POST   | Trigger graceful server shutdown                     |
 
-> **Bemærk:** Disse endepunkter bruges internt af systemet eller til Ollama-klientkompatibilitet. De kaldes typisk ikke af slutbrugere.
+> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users.
 
 ---
 
-## Lydtransskription
+## Audio Transcription
 
 ```bash
 POST /v1/audio/transcriptions
@@ -317,9 +331,9 @@ Authorization: Bearer your-api-key
 Content-Type: multipart/form-data
 ```
 
-Transskriber lydfiler ved hjælp af Deepgram eller AssemblyAI.
+Transcribe audio files using Deepgram or AssemblyAI.
 
-**Forespørgsel:**
+**Request:**
 
 ```bash
 curl -X POST http://localhost:20128/v1/audio/transcriptions \
@@ -328,7 +342,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
   -F "model=deepgram/nova-3"
 ```
 
-**Svar:**
+**Response:**
 
 ```json
 {
@@ -339,15 +353,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
 }
 ```
 
-**Understøttede udbydere:** `deepgram/nova-3`, `assemblyai/best`.
+**Supported providers:** `deepgram/nova-3`, `assemblyai/best`.
 
-**Understøttede formater:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
 
 ---
 
-## Ollama-kompatibilitet
+## Ollama Compatibility
 
-For klienter, der bruger Ollamas API-format:
+For clients that use Ollama's API format:
 
 ```bash
 # Chat endpoint (Ollama format)
@@ -357,18 +371,18 @@ POST /v1/api/chat
 GET /api/tags
 ```
 
-Forespørgsler oversættes automatisk mellem Ollama og interne formater.
+Requests are automatically translated between Ollama and internal formats.
 
 ---
 
-## Telemetri
+## Telemetry
 
 ```bash
 # Get latency telemetry summary (p50/p95/p99 per provider)
 GET /api/telemetry/summary
 ```
 
-**Svar:**
+**Response:**
 
 ```json
 {
@@ -400,7 +414,7 @@ Content-Type: application/json
 
 ---
 
-## Modeltilgængelighed
+## Model Availability
 
 ```bash
 # Get real-time model availability across all providers
@@ -417,25 +431,25 @@ Content-Type: application/json
 
 ---
 
-## Anmodningsbehandling
+## Request Processing
 
-1. Klient sender anmodning til `/v1/*`
-2. Rutehandler kalder `handleChat`, `handleEmbedding`, `handleAudioTranscription` eller `handleImageGeneration`
-3. Modellen er løst (direkte udbyder/model eller alias/kombination)
-4. Oplysninger valgt fra lokal DB med filtrering af kontotilgængelighed
-5. Til chat: `handleChatCore` — formatdetektion, oversættelse, cachecheck, idempotenstjek
-6. Udbyder eksekutør sender upstream anmodning
-7. Svar oversat tilbage til klientformat (chat) eller returneret som det er (indlejringer/billeder/lyd)
-8. Brug/logning registreret
-9. Fallback gælder for fejl i henhold til combo regler
+1. Client sends request to `/v1/*`
+2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration`
+3. Model is resolved (direct provider/model or alias/combo)
+4. Credentials selected from local DB with account availability filtering
+5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check
+6. Provider executor sends upstream request
+7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio)
+8. Usage/logging recorded
+9. Fallback applies on errors according to combo rules
 
-Fuld arkitekturreference: [link](ARCHITECTURE.md)
+Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md)
 
 ---
 
-## Godkendelse
+## Authentication
 
-- Dashboard-ruter (`/dashboard/*`) bruger `auth_token`-cookie
-- Login bruger gemt adgangskode-hash; tilbagefald til `INITIAL_PASSWORD`
-- `requireLogin` kan skiftes via `/api/settings/require-login`
-- `/v1/*`-ruter kræver valgfrit Bearer API-nøgle, når `REQUIRE_API_KEY=true`
+- Dashboard routes (`/dashboard/*`) use `auth_token` cookie
+- Login uses saved password hash; fallback to `INITIAL_PASSWORD`
+- `requireLogin` toggleable via `/api/settings/require-login`
+- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true`

docs/i18n/da/ARCHITECTURE.md

@@ -1,71 +1,75 @@
-# OmniRoute-arkitektur
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/ARCHITECTURE.md) · 🇪🇸 [es](../es/ARCHITECTURE.md) · 🇫🇷 [fr](../fr/ARCHITECTURE.md) · 🇩🇪 [de](../de/ARCHITECTURE.md) · 🇮🇹 [it](../it/ARCHITECTURE.md) · 🇷🇺 [ru](../ru/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../zh-CN/ARCHITECTURE.md) · 🇯🇵 [ja](../ja/ARCHITECTURE.md) · 🇰🇷 [ko](../ko/ARCHITECTURE.md) · 🇸🇦 [ar](../ar/ARCHITECTURE.md) · 🇮🇳 [in](../in/ARCHITECTURE.md) · 🇹🇭 [th](../th/ARCHITECTURE.md) · 🇻🇳 [vi](../vi/ARCHITECTURE.md) · 🇮🇩 [id](../id/ARCHITECTURE.md) · 🇲🇾 [ms](../ms/ARCHITECTURE.md) · 🇳🇱 [nl](../nl/ARCHITECTURE.md) · 🇵🇱 [pl](../pl/ARCHITECTURE.md) · 🇸🇪 [sv](../sv/ARCHITECTURE.md) · 🇳🇴 [no](../no/ARCHITECTURE.md) · 🇩🇰 [da](../da/ARCHITECTURE.md) · 🇫🇮 [fi](../fi/ARCHITECTURE.md) · 🇵🇹 [pt](../pt/ARCHITECTURE.md) · 🇷🇴 [ro](../ro/ARCHITECTURE.md) · 🇭🇺 [hu](../hu/ARCHITECTURE.md) · 🇧🇬 [bg](../bg/ARCHITECTURE.md) · 🇸🇰 [sk](../sk/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../uk-UA/ARCHITECTURE.md) · 🇮🇱 [he](../he/ARCHITECTURE.md) · 🇵🇭 [phi](../phi/ARCHITECTURE.md)
 
-🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md)
+---
 
-_Sidst opdateret: 2026-02-18_
+# OmniRoute Architecture
 
-## Resumé
+🌐 **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)
 
-OmniRoute er en lokal AI-routinggateway og dashboard bygget på Next.js.
-Det giver et enkelt OpenAI-kompatibelt slutpunkt (`/v1/*`) og dirigerer trafik på tværs af flere upstream-udbydere med oversættelse, fallback, token-opdatering og brugssporing.
+_Last updated: 2026-03-04_
 
-Kerneegenskaber:
+## Executive Summary
 
-- OpenAI-kompatibel API-overflade til CLI/værktøjer (28 udbydere)
-- Anmodning/svar oversættelse på tværs af udbyderformater
-- Model combo fallback (multi-model sekvens)
-- Fallback på kontoniveau (multi-konto pr. udbyder)
-- Administration af forbindelse til OAuth + API-nøgleudbyder
-- Indlejringsgenerering via `/v1/embeddings` (6 udbydere, 9 modeller)
-- Billedgenerering via `/v1/images/generations` (4 udbydere, 9 modeller)
-- Tænk tag-parsing (`<think>...</think>`) for ræsonneringsmodeller
-- Response sanitization for streng OpenAI SDK-kompatibilitet
-- Rollenormalisering (udvikler→system, system→bruger) for kompatibilitet på tværs af udbydere
-- Struktureret outputkonvertering (json_schema → Gemini responseSchema)
-- Lokal persistens for udbydere, nøgler, aliaser, kombinationer, indstillinger, priser
-- Brug/omkostningssporing og anmodningslogning
-- Valgfri skysynkronisering til synkronisering af flere enheder/tilstande
-- IP-tilladelsesliste/blokeringsliste til API-adgangskontrol
-- Tænkende budgetstyring (passthrough/auto/custom/adaptive)
-- Global system prompt injektion
-- Sessionssporing og fingeraftryk
-- Forbedret prisbegrænsning pr. konto med udbyderspecifikke profiler
-- Circuit breaker mønster for udbyderens modstandsdygtighed
-- Anti-tordenbeskyttelse med mutex-låsning
-- Signaturbaseret anmodnings deduplikeringscache
-- Domænelag: modeltilgængelighed, omkostningsregler, fallback-politik, lockout-politik
-- Vedvarende domænetilstand (SQLite-gennemskrivningscache til fallbacks, budgetter, lockouts, strømafbrydere)
-- Politikmotor til centraliseret anmodningsevaluering (lockout → budget → fallback)
-- Anmod om telemetri med p50/p95/p99 latency aggregering
-- Korrelations-ID (X-Request-Id) til ende-til-ende-sporing
-- Overholdelsesrevisionslogning med opt-out pr. API-nøgle
-- Evalueringsramme for LLM kvalitetssikring
-- Resilience UI-dashboard med strømafbryderstatus i realtid
-- Modulære OAuth-udbydere (12 individuelle moduler under `src/lib/oauth/providers/`)
+OmniRoute is a local AI routing gateway and dashboard built on Next.js.
+It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
 
-Primær runtime model:
+Core capabilities:
 
-- Next.js app-ruter under `src/app/api/*` implementerer både dashboard-API'er og kompatibilitets-API'er
-- En delt SSE/routingkerne i `src/sse/*` + `open-sse/*` håndterer udbyderens udførelse, oversættelse, streaming, fallback og brug
+- OpenAI-compatible API surface for CLI/tools (28 providers)
+- Request/response translation across provider formats
+- Model combo fallback (multi-model sequence)
+- Account-level fallback (multi-account per provider)
+- OAuth + API-key provider connection management
+- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
+- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Think tag parsing (`<think>...</think>`) for reasoning models
+- Response sanitization for strict OpenAI SDK compatibility
+- Role normalization (developer→system, system→user) for cross-provider compatibility
+- Structured output conversion (json_schema → Gemini responseSchema)
+- Local persistence for providers, keys, aliases, combos, settings, pricing
+- Usage/cost tracking and request logging
+- Optional cloud sync for multi-device/state sync
+- IP allowlist/blocklist for API access control
+- Thinking budget management (passthrough/auto/custom/adaptive)
+- Global system prompt injection
+- Session tracking and fingerprinting
+- Per-account enhanced rate limiting with provider-specific profiles
+- Circuit breaker pattern for provider resilience
+- Anti-thundering herd protection with mutex locking
+- Signature-based request deduplication cache
+- Domain layer: model availability, cost rules, fallback policy, lockout policy
+- 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
+- Correlation ID (X-Request-Id) for end-to-end tracing
+- Compliance audit logging with opt-out per API key
+- Eval framework for LLM quality assurance
+- Resilience UI dashboard with real-time circuit breaker status
+- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`)
 
-## Omfang og grænser
+Primary runtime model:
 
-### I omfang
+- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
+- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
 
-- Lokal gateway køretid
-- Dashboard management API'er
-- Udbydergodkendelse og tokenopdatering
-- Anmod om oversættelse og SSE-streaming
-- Lokal stat + vedvarende brug
-- Valgfri skysynkroniseringsorkestrering
+## Scope and Boundaries
 
-### Uden for anvendelsesområde
+### In Scope
 
-- Cloud-tjenesteimplementering bag `NEXT_PUBLIC_CLOUD_URL`
-- Udbyder SLA/kontrolplan uden for lokal proces
-- Eksterne CLI-binære filer selv (Claude CLI, Codex CLI osv.)
+- Local gateway runtime
+- Dashboard management APIs
+- Provider authentication and token refresh
+- Request translation and SSE streaming
+- Local state + usage persistence
+- Optional cloud sync orchestration
 
-## Systemkontekst på højt niveau
+### Out of Scope
+
+- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
+- Provider SLA/control plane outside local process
+- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
+
+## High-Level System Context
 
 ```mermaid
 flowchart LR
@@ -81,8 +85,8 @@ 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]
@@ -115,149 +119,150 @@ flowchart LR
 
 ## Core Runtime Components
 
-## 1) API og Routing Layer (Next.js App Routes)
+## 1) API and Routing Layer (Next.js App Routes)
 
-Hovedmapper:
+Main directories:
 
-- `src/app/api/v1/*` og `src/app/api/v1beta/*` for kompatibilitets-API'er
-- `src/app/api/*` til administrations-/konfigurations-API'er
-- Næste omskrivninger i `next.config.mjs` kort `/v1/*` til `/api/v1/*`
+- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
+- `src/app/api/*` for management/configuration APIs
+- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
 
-Vigtige kompatibilitetsruter:
+Important compatibility routes:
 
 - `src/app/api/v1/chat/completions/route.ts`
 - `src/app/api/v1/messages/route.ts`
 - `src/app/api/v1/responses/route.ts`
-- `src/app/api/v1/models/route.ts` — inkluderer brugerdefinerede modeller med `custom: true`
-- `src/app/api/v1/embeddings/route.ts` — indlejringsgenerering (6 udbydere)
-- `src/app/api/v1/images/generations/route.ts` — billedgenerering (4+ udbydere inkl. Antigravity/Nebius)
+- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`
+- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)
+- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)
 - `src/app/api/v1/messages/count_tokens/route.ts`
-- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedikeret chat pr. udbyder
-- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedikerede indlejringer pr. udbyder
-- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedikerede billeder pr. udbyder
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images
 - `src/app/api/v1beta/models/route.ts`
 - `src/app/api/v1beta/models/[...path]/route.ts`
 
-Ledelsesdomæner:
+Management domains:
 
-- Godkendelse/indstillinger: `src/app/api/auth/*`, `src/app/api/settings/*`
-- Udbydere/forbindelser: `src/app/api/providers*`
-- Udbyder noder: `src/app/api/provider-nodes*`
-- Brugerdefinerede modeller: `src/app/api/provider-models` (GET/POST/DELETE)
-- Modelkatalog: `src/app/api/models/catalog` (GET)
-- Proxy-konfiguration: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
+- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
+- 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/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/*`
-- Nøgler/aliaser/kombinationer/priser: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
-- Anvendelse: `src/app/api/usage/*`
-- Synkroniser/sky: `src/app/api/sync/*`, `src/app/api/cloud/*`
-- CLI-værktøjshjælpere: `src/app/api/cli-tools/*`
-- IP-filter: `src/app/api/settings/ip-filter` (GET/PUT)
-- Tænkende budget: `src/app/api/settings/thinking-budget` (GET/PUT)
-- Systemprompt: `src/app/api/settings/system-prompt` (GET/PUT)
-- Sessioner: `src/app/api/sessions` (GET)
-- Satsgrænser: `src/app/api/rate-limits` (GET)
-- Modstandsdygtighed: `src/app/api/resilience` (GET/PATCH) — udbyderprofiler, strømafbryder, hastighedsgrænsetilstand
-- Resilience reset: `src/app/api/resilience/reset` (POST) — nulstil breakers + cooldowns
-- Cachestatistik: `src/app/api/cache/stats` (GET/DELETE)
-- Modeltilgængelighed: `src/app/api/models/availability` (GET/POST)
-- Telemetri: `src/app/api/telemetry/summary` (GET)
+- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
+- Usage: `src/app/api/usage/*`
+- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
+- CLI tooling helpers: `src/app/api/cli-tools/*`
+- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)
+- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)
+- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)
+- Sessions: `src/app/api/sessions` (GET)
+- Rate limits: `src/app/api/rate-limits` (GET)
+- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns
+- Cache stats: `src/app/api/cache/stats` (GET/DELETE)
+- Model availability: `src/app/api/models/availability` (GET/POST)
+- Telemetry: `src/app/api/telemetry/summary` (GET)
 - Budget: `src/app/api/usage/budget` (GET/POST)
-- Fallback-kæder: `src/app/api/fallback/chains` (GET/POST/DELETE)
-- Overholdelsesrevision: `src/app/api/compliance/audit-log` (GET)
-- Evaler: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
-- Politikker: `src/app/api/policies` (GET/POST)
+- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET)
+- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
+- Policies: `src/app/api/policies` (GET/POST)
 
-## 2) SSE + Oversættelseskerne
+## 2) SSE + Translation Core
 
-Hovedflowmoduler:
+Main flow modules:
 
-- Indgang: `src/sse/handlers/chat.ts`
-- Kerneorkestrering: `open-sse/handlers/chatCore.ts`
-- Leverandørudførelsesadaptere: `open-sse/executors/*`
-- Formatdetektion/udbyderkonfiguration: `open-sse/services/provider.ts`
-- Modelparse/opløsning: `src/sse/services/model.ts`, `open-sse/services/model.ts`
-- Konto fallback logik: `open-sse/services/accountFallback.ts`
-- Oversættelsesregister: `open-sse/translator/index.ts`
-- Strømtransformationer: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
-- Brugsekstraktion/normalisering: `open-sse/utils/usageTracking.ts`
-- Tænk tag-parser: `open-sse/utils/thinkTagParser.ts`
-- Indlejringshåndtering: `open-sse/handlers/embeddings.ts`
-- Indlejring af udbyderregistrering: `open-sse/config/embeddingRegistry.ts`
-- Billedgenereringsbehandler: `open-sse/handlers/imageGeneration.ts`
-- Billedudbyderregistrering: `open-sse/config/imageRegistry.ts`
-- Reaktionssanering: `open-sse/handlers/responseSanitizer.ts`
-- Rollenormalisering: `open-sse/services/roleNormalizer.ts`
+- Entry: `src/sse/handlers/chat.ts`
+- Core orchestration: `open-sse/handlers/chatCore.ts`
+- Provider execution adapters: `open-sse/executors/*`
+- Format detection/provider config: `open-sse/services/provider.ts`
+- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
+- Account fallback logic: `open-sse/services/accountFallback.ts`
+- Translation registry: `open-sse/translator/index.ts`
+- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
+- Think tag parser: `open-sse/utils/thinkTagParser.ts`
+- Embedding handler: `open-sse/handlers/embeddings.ts`
+- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
+- Image generation handler: `open-sse/handlers/imageGeneration.ts`
+- Image provider registry: `open-sse/config/imageRegistry.ts`
+- Response sanitization: `open-sse/handlers/responseSanitizer.ts`
+- Role normalization: `open-sse/services/roleNormalizer.ts`
 
-Tjenester (forretningslogik):
+Services (business logic):
 
-- Kontovalg/score: `open-sse/services/accountSelector.ts`
-- Kontekstlivscyklusstyring: `open-sse/services/contextManager.ts`
-- Håndhævelse af IP-filter: `open-sse/services/ipFilter.ts`
-- Sessionssporing: `open-sse/services/sessionManager.ts`
-- Anmod om deduplikering: `open-sse/services/signatureCache.ts`
-- Systemprompt indsprøjtning: `open-sse/services/systemPrompt.ts`
-- Tænkende budgetstyring: `open-sse/services/thinkingBudget.ts`
+- Account selection/scoring: `open-sse/services/accountSelector.ts`
+- Context lifecycle management: `open-sse/services/contextManager.ts`
+- IP filter enforcement: `open-sse/services/ipFilter.ts`
+- Session tracking: `open-sse/services/sessionManager.ts`
+- Request deduplication: `open-sse/services/signatureCache.ts`
+- System prompt injection: `open-sse/services/systemPrompt.ts`
+- Thinking budget management: `open-sse/services/thinkingBudget.ts`
 - Wildcard model routing: `open-sse/services/wildcardRouter.ts`
-- Satsgrænsestyring: `open-sse/services/rateLimitManager.ts`
-- Afbryder: `open-sse/services/circuitBreaker.ts`
+- Rate limit management: `open-sse/services/rateLimitManager.ts`
+- Circuit breaker: `open-sse/services/circuitBreaker.ts`
 
-Domænelagsmoduler:
+Domain layer modules:
 
-- Modeltilgængelighed: `src/lib/domain/modelAvailability.ts`
-- Omkostningsregler/budgetter: `src/lib/domain/costRules.ts`
-- Fallback-politik: `src/lib/domain/fallbackPolicy.ts`
+- Model availability: `src/lib/domain/modelAvailability.ts`
+- Cost rules/budgets: `src/lib/domain/costRules.ts`
+- Fallback policy: `src/lib/domain/fallbackPolicy.ts`
 - Combo resolver: `src/lib/domain/comboResolver.ts`
-- Lockout-politik: `src/lib/domain/lockoutPolicy.ts`
-- Politikmotor: `src/domain/policyEngine.ts` — centraliseret lockout → budget → fallback-evaluering
-- Fejlkodekatalog: `src/lib/domain/errorCodes.ts`
-- Anmodnings-id: `src/lib/domain/requestId.ts`
-- Hente timeout: `src/lib/domain/fetchTimeout.ts`
-- Anmod om telemetri: `src/lib/domain/requestTelemetry.ts`
-- Overholdelse/revision: `src/lib/domain/compliance/index.ts`
-- Evalløber: `src/lib/domain/evalRunner.ts`
-- Vedvarende domænetilstand: `src/lib/db/domainState.ts` — SQLite CRUD til reservekæder, budgetter, omkostningshistorik, lockouttilstand, afbrydere
+- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
+- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
+- Error codes catalog: `src/lib/domain/errorCodes.ts`
+- Request ID: `src/lib/domain/requestId.ts`
+- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
+- Request telemetry: `src/lib/domain/requestTelemetry.ts`
+- Compliance/audit: `src/lib/domain/compliance/index.ts`
+- Eval runner: `src/lib/domain/evalRunner.ts`
+- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
 
-OAuth-udbydermoduler (12 individuelle filer under `src/lib/oauth/providers/`):
+OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
-- Registerindeks: `src/lib/oauth/providers/index.ts`
-- Individuelle udbydere: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, , , `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
-- Tyndt omslag: `src/lib/oauth/providers.ts` — reeksport fra individuelle moduler
+- 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`
+- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
-## 3) Persistens-lag
+## 3) Persistence Layer
 
-Primær tilstand DB:
+Primary state DB (SQLite):
 
-- `src/lib/localDb.ts`
-- fil: `${DATA_DIR}/db.json` (eller `$XDG_CONFIG_HOME/omniroute/db.json` når indstillet, ellers `~/.omniroute/db.json`)
-- enheder: providerConnections, providerNodes, modelAliaser, combos, apiKeys, indstillinger, prissætning, **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**
 
-Brug DB:
+Usage persistence:
 
-- `src/lib/usageDb.ts`
-- filer: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
-- følger den samme grundlæggende bibliotekspolitik som `localDb` (`DATA_DIR`, derefter `XDG_CONFIG_HOME/omniroute`, når den er indstillet)
-- opdelt i fokuserede undermoduler: `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):
 
-- `src/lib/db/domainState.ts` — CRUD-operationer for domænetilstand
-- Tabeller (oprettet i `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
-- Gennemskrivningscachemønster: Kort i hukommelsen er autoritative under kørsel; mutationer skrives synkront til SQLite; tilstand gendannes fra DB ved koldstart
+- `src/lib/db/domainState.ts` — CRUD operations for domain state
+- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
+- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
 
-## 4) Auth + Sikkerhedsoverflader
+## 4) Auth + Security Surfaces
 
-- Dashboard-cookiegodkendelse: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
-- Generering/bekræftelse af API-nøgler: `src/shared/utils/apiKey.ts`
-- Udbyderhemmeligheder bestod i `providerConnections` poster
-- Udgående proxy-understøttelse via `open-sse/utils/proxyFetch.ts` (env vars) og `open-sse/utils/networkProxy.ts` (konfigurerbar pr. udbyder eller global)
+- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
+- API key generation/verification: `src/shared/utils/apiKey.ts`
+- Provider secrets persisted in `providerConnections` entries
+- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
 
 ## 5) Cloud Sync
 
-- Planlægger init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
-- Periodisk opgave: `src/shared/services/cloudSyncScheduler.ts`
-- Kontrolrute: `src/app/api/sync/cloud/route.ts`
+- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
+- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Control route: `src/app/api/sync/cloud/route.ts`
 
-## Anmod om livscyklus (`/v1/chat/completions`)
+## Request Lifecycle (`/v1/chat/completions`)
 
 ```mermaid
 sequenceDiagram
@@ -334,9 +339,9 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-Fallback-beslutninger er drevet af `open-sse/services/accountFallback.ts` ved hjælp af statuskoder og fejlmeddelelsesheuristik.
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics.
 
-## OAuth Onboarding og Token Refresh Lifecycle
+## OAuth Onboarding and Token Refresh Lifecycle
 
 ```mermaid
 sequenceDiagram
@@ -366,9 +371,9 @@ sequenceDiagram
     Test-->>UI: validation result
 ```
 
-Opdatering under live-trafik udføres inde i `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
+Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
 
-## Cloud Sync Lifecycle (Aktiver / Synkroniser / Deaktiver)
+## Cloud Sync Lifecycle (Enable / Sync / Disable)
 
 ```mermaid
 sequenceDiagram
@@ -400,9 +405,9 @@ sequenceDiagram
     Sync-->>UI: disabled
 ```
 
-Periodisk synkronisering udløses af `CloudSyncScheduler`, når skyen er aktiveret.
+Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
 
-## Datamodel og lagerkort
+## Data Model and Storage Map
 
 ```mermaid
 erDiagram
@@ -503,14 +508,14 @@ erDiagram
     }
 ```
 
-Fysiske lagerfiler:
+Physical storage files:
 
-- hovedtilstand: `${DATA_DIR}/db.json` (eller `$XDG_CONFIG_HOME/omniroute/db.json` når indstillet, ellers `~/.omniroute/db.json`)
-- brugsstatistik: `${DATA_DIR}/usage.json`
-- anmod om log linjer: `${DATA_DIR}/log.txt`
-- valgfri oversætter/anmodningsfejlfindingssessioner: `<repo>/logs/...`
+- 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/...`
 
-## Implementeringstopologi
+## Deployment Topology
 
 ```mermaid
 flowchart LR
@@ -522,8 +527,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]
@@ -541,241 +546,242 @@ flowchart LR
     Next --> SyncCloud
 ```
 
-## Modulkortlægning (beslutningskritisk)
+## Module Mapping (Decision-Critical)
 
-### Rute- og API-moduler
+### Route and API Modules
 
-- `src/app/api/v1/*`, `src/app/api/v1beta/*`: kompatibilitets-API'er
-- `src/app/api/v1/providers/[provider]/*`: dedikerede ruter pr. udbyder (chat, indlejringer, billeder)
-- `src/app/api/providers*`: udbyder CRUD, validering, test
-- `src/app/api/provider-nodes*`: brugerdefineret kompatibel nodestyring
-- `src/app/api/provider-models`: brugerdefineret modelstyring (CRUD)
-- `src/app/api/models/catalog`: komplet modelkatalog API (alle typer grupperet efter udbyder)
-- `src/app/api/oauth/*`: OAuth/enhedskode-flows
-- `src/app/api/keys*`: lokal API nøgle livscyklus
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
+- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
+- `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/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
 - `src/app/api/combos*`: fallback combo management
-- `src/app/api/pricing`: pristilsidesættelser til omkostningsberegning
-- `src/app/api/settings/proxy`: proxy-konfiguration (GET/PUT/DELETE)
-- `src/app/api/settings/proxy/test`: test af udgående proxyforbindelse (POST)
-- `src/app/api/usage/*`: brugs- og log-API'er
-- `src/app/api/sync/*` + `src/app/api/cloud/*`: skysynkronisering og skyvendte hjælpere
-- `src/app/api/cli-tools/*`: lokale CLI-konfigurationsskrivere/-brikker
-- `src/app/api/settings/ip-filter`: IP-tilladelsesliste/blokeringsliste (GET/PUT)
-- `src/app/api/settings/thinking-budget`: Tænkende token-budgetkonfiguration (GET/PUT)
-- `src/app/api/settings/system-prompt`: global systemprompt (GET/PUT)
-- `src/app/api/sessions`: aktiv sessionsfortegnelse (GET)
-- `src/app/api/rate-limits`: satsgrænsestatus pr. konto (GET)
+- `src/app/api/pricing`: pricing overrides for cost calculation
+- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
+- `src/app/api/usage/*`: usage and logs APIs
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
+- `src/app/api/cli-tools/*`: local CLI config writers/checkers
+- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
+- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
+- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
+- `src/app/api/sessions`: active session listing (GET)
+- `src/app/api/rate-limits`: per-account rate limit status (GET)
 
-### Routing og udførelseskerne
+### Routing and Execution Core
 
-- `src/sse/handlers/chat.ts`: anmodning om parse, kombinationshåndtering, kontovalgsløkke
-- `open-sse/handlers/chatCore.ts`: oversættelse, eksekutorafsendelse, genforsøg/opdateringshåndtering, stream-opsætning
-- `open-sse/executors/*`: udbyderspecifik netværks- og formatadfærd
+- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
+- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
+- `open-sse/executors/*`: provider-specific network and format behavior
 
-### Oversættelsesregister og formatkonvertere
+### Translation Registry and Format Converters
 
-- `open-sse/translator/index.ts`: oversætterregister og orkestrering
-- Anmod om oversættere: `open-sse/translator/request/*`
-- Svaroversættere: `open-sse/translator/response/*`
-- Formatkonstanter: `open-sse/translator/formats.ts`
+- `open-sse/translator/index.ts`: translator registry and orchestration
+- Request translators: `open-sse/translator/request/*`
+- Response translators: `open-sse/translator/response/*`
+- Format constants: `open-sse/translator/formats.ts`
 
-### Vedholdenhed
+### Persistence
 
-- `src/lib/localDb.ts`: vedvarende konfiguration/tilstand
-- `src/lib/usageDb.ts`: brugshistorik og rullende anmodningslogfiler
+- `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
 
-## Udbyder Eksekutør Dækning (Strategimønster)
+## Provider Executor Coverage (Strategy Pattern)
 
-Hver udbyder har en specialiseret udfører, der udvider `BaseExecutor` (i `open-sse/executors/base.ts`), som giver URL-opbygning, header-konstruktion, genforsøg med eksponentiel backoff, legitimationsopdateringshook og `execute()` orkestreringsmetoden.
+Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method.
 
-| Eksekutør             | Udbyder(e)                                                                                                                                                    | Særlig håndtering                                                       |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| `DefaultExecutor`     | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fyrværkeri, Cerebras, Cohere, NVIDIA | Dynamisk URL/header-konfiguration pr. udbyder                           |
-| `AntigravityExecutor` | Google Antigravity                                                                                                                                            | Brugerdefinerede projekt-/sessions-id'er, forsøg igen - efter parsing   |
-| `CodexExecutor`       | OpenAI Codex                                                                                                                                                  | Injicerer systeminstruktioner, fremtvinger ræsonnement indsats          |
-| `CursorExecutor`      | Markør IDE                                                                                                                                                    | ConnectRPC-protokol, Protobuf-kodning, anmodningssignering via checksum |
-| `GithubExecutor`      | GitHub Copilot                                                                                                                                                | Copilot token opdatering, VSCode-mimicing headers                       |
-| `KiroExecutor`        | AWS CodeWhisperer/Kiro                                                                                                                                        | AWS EventStream binært format → SSE-konvertering                        |
-| `GeminiCLIExecutor`   | Gemini CLI                                                                                                                                                    | Opdateringscyklus for Google OAuth-token                                |
+| 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                               |
+| `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 |
+| `GithubExecutor`      | GitHub Copilot                                                                                                                                               | Copilot token refresh, VSCode-mimicking headers                      |
+| `KiroExecutor`        | AWS CodeWhisperer/Kiro                                                                                                                                       | AWS EventStream binary format → SSE conversion                       |
+| `GeminiCLIExecutor`   | Gemini CLI                                                                                                                                                   | Google OAuth token refresh cycle                                     |
 
-Alle andre udbydere (inklusive brugerdefinerede kompatible noder) bruger `DefaultExecutor`.
+All other providers (including custom compatible nodes) use the `DefaultExecutor`.
 
-## Udbyderkompatibilitetsmatrix
+## Provider Compatibility Matrix
 
-| Udbyder          | Format          | Auth                  | Stream           | Ikke-stream | Token Opdater | Brug API             |
-| ---------------- | --------------- | --------------------- | ---------------- | ----------- | ------------- | -------------------- |
-| Claude           | claude          | API-nøgle / OAuth     | ✅               | ✅          | ✅            | ⚠️ Kun administrator |
-| Tvillingerne     | gemini          | API-nøgle / OAuth     | ✅               | ✅          | ✅            | ⚠️ Cloud Console     |
-| Gemini CLI       | gemini-cli      | OAuth                 | ✅               | ✅          | ✅            | ⚠️ Cloud Console     |
-| Antigravitation  | antityngdekraft | OAuth                 | ✅               | ✅          | ✅            | ✅ Fuld kvote API    |
-| OpenAI           | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Codex            | openai-svar     | OAuth                 | ✅ tvunget       | ❌          | ✅            | ✅ Satsgrænser       |
-| GitHub Copilot   | åbne            | OAuth + Copilot Token | ✅               | ✅          | ✅            | ✅ Kvote snapshots   |
-| Markør           | markør          | Tilpasset kontrolsum  | ✅               | ✅          | ❌            | ❌                   |
-| Kiro             | kiro            | AWS SSO OIDC          | ✅ (EventStream) | ❌          | ✅            | ✅ Brugsgrænser      |
-| Qwen             | åbne            | OAuth                 | ✅               | ✅          | ✅            | ⚠️ Efter anmodning   |
-| iFlow            | åbne            | OAuth (Grundlæggende) | ✅               | ✅          | ✅            | ⚠️ Efter anmodning   |
-| OpenRouter       | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| GLM/Kimi/MiniMax | claude          | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| DeepSeek         | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Groq             | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| xAI (Grok)       | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Mistral          | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Forvirring       | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Sammen AI        | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Fyrværkeri AI    | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Cerebras         | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Sammenhæng       | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| NVIDIA NIM       | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
+| Provider         | Format           | Auth                  | Stream           | Non-Stream | Token Refresh | Usage API          |
+| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
+| Claude           | claude           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Admin only      |
+| Gemini           | gemini           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Gemini CLI       | gemini-cli       | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Antigravity      | antigravity      | OAuth                 | ✅               | ✅         | ✅            | ✅ Full quota API  |
+| OpenAI           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Codex            | openai-responses | OAuth                 | ✅ forced        | ❌         | ✅            | ✅ Rate limits     |
+| GitHub Copilot   | openai           | OAuth + Copilot Token | ✅               | ✅         | ✅            | ✅ Quota snapshots |
+| Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
+| Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
+| Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| iFlow            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Groq             | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| xAI (Grok)       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Mistral          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Perplexity       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Together AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Fireworks AI     | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 
-## Format oversættelsesdækning
+## Format Translation Coverage
 
-Detekterede kildeformater omfatter:
+Detected source formats include:
 
 - `openai`
 - `openai-responses`
 - `claude`
 - `gemini`
 
-Målformater omfatter:
+Target formats include:
 
-- OpenAI chat/svar
+- OpenAI chat/Responses
 - Claude
-- Gemini/Gemini-CLI/Antigravity kuvert
+- Gemini/Gemini-CLI/Antigravity envelope
 - Kiro
-- Markør
+- Cursor
 
-Oversættelser bruger **OpenAI som hub-format** - alle konverteringer går gennem OpenAI som mellemliggende:
+Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
 
 ```
 Source Format → OpenAI (hub) → Target Format
 ```
 
-Oversættelser vælges dynamisk baseret på kildens nyttelastform og udbyderens målformat.
+Translations are selected dynamically based on source payload shape and provider target format.
 
-Yderligere behandlingslag i oversættelsespipelinen:
+Additional processing layers in the translation pipeline:
 
-- **Responssanering** — Fjerner ikke-standardfelter fra OpenAI-formatsvar (både streaming og ikke-streaming) for at sikre streng SDK-overholdelse
-- **Rollenormalisering** — Konverterer `developer` → `system` til ikke-OpenAI-mål; fusionerer `system` → `user` for modeller, der afviser systemrollen (GLM, ERNIE)
-- **Tænk tag-udtrækning** — Parser `<think>...</think>` blokke fra indhold til feltet `reasoning_content`
-- **Struktureret output** — Konverterer OpenAI `response_format.json_schema` til Gemini's `responseMimeType` + `responseSchema`
+- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance
+- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)
+- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field
+- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`
 
-## Understøttede API-endepunkter
+## Supported API Endpoints
 
-| Slutpunkt                                          | Format                    | Behandler                                                          |
-| -------------------------------------------------- | ------------------------- | ------------------------------------------------------------------ |
-| `POST /v1/chat/completions`                        | OpenAI Chat               | `src/sse/handlers/chat.ts`                                         |
-| `POST /v1/messages`                                | Claude Beskeder           | Samme handler (auto-detekteret)                                    |
-| `POST /v1/responses`                               | OpenAI-svar               | `open-sse/handlers/responsesHandler.ts`                            |
-| `POST /v1/embeddings`                              | OpenAI-indlejringer       | `open-sse/handlers/embeddings.ts`                                  |
-| `GET /v1/embeddings`                               | Modelliste                | API-rute                                                           |
-| `POST /v1/images/generations`                      | OpenAI Billeder           | `open-sse/handlers/imageGeneration.ts`                             |
-| `GET /v1/images/generations`                       | Modelliste                | API-rute                                                           |
-| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat               | Dedikeret per udbyder med modelvalidering                          |
-| `POST /v1/providers/{provider}/embeddings`         | OpenAI-indlejringer       | Dedikeret per udbyder med modelvalidering                          |
-| `POST /v1/providers/{provider}/images/generations` | OpenAI Billeder           | Dedikeret per udbyder med modelvalidering                          |
-| `POST /v1/messages/count_tokens`                   | Claude Token Count        | API-rute                                                           |
-| `GET /v1/models`                                   | OpenAI Models liste       | API-rute (chat + indlejring + billede + brugerdefinerede modeller) |
-| `GET /api/models/catalog`                          | Katalog                   | Alle modeller grupperet efter udbyder + type                       |
-| `POST /v1beta/models/*:streamGenerateContent`      | Tvilling hjemmehørende    | API-rute                                                           |
-| `GET/PUT/DELETE /api/settings/proxy`               | Proxy-konfiguration       | Netværk proxy-konfiguration                                        |
-| `POST /api/settings/proxy/test`                    | Proxy-forbindelse         | Proxy-sundheds-/forbindelsestestslutpunkt                          |
-| `GET/POST/DELETE /api/provider-models`             | Brugerdefinerede modeller | Brugerdefineret modelstyring pr. udbyder                           |
+| 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                 |
 
 ## Bypass Handler
 
-Bypass-handleren (`open-sse/utils/bypassHandler.ts`) opsnapper kendte "smid-anmodninger" fra Claude CLI - opvarmningsping, titeludtræk og tokentællinger - og returnerer et **falsk svar** uden at forbruge upstream-udbydertokens. Dette udløses kun, når `User-Agent` indeholder `claude-cli`.
+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`.
 
-## Anmod om Logger Pipeline
+## Request Logger Pipeline
 
-Anmodningsloggeren (`open-sse/utils/requestLogger.ts`) giver en 7-trins debug-logningspipeline, deaktiveret som standard, aktiveret via `ENABLE_REQUEST_LOGS=true`:
+The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`:
 
 ```
 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
 ```
 
-Filer skrives til `<repo>/logs/<session>/` for hver anmodningssession.
+Files are written to `<repo>/logs/<session>/` for each request session.
 
-## Fejltilstande og modstandsdygtighed
+## Failure Modes and Resilience
 
-## 1) Konto/udbyder tilgængelighed
+## 1) Account/Provider Availability
 
-- Nedkøling af udbyderkonto på forbigående/rate/godkendelsesfejl
-- konto fallback før mislykket anmodning
-- combo model fallback, når den nuværende model/udbydersti er udtømt
+- provider account cooldown on transient/rate/auth errors
+- account fallback before failing request
+- combo model fallback when current model/provider path is exhausted
 
-## 2) Tokens udløb
+## 2) Token Expiry
 
-- Forhåndstjek og opdater med genforsøg for udbydere, der kan opdateres
-- 401/403 forsøg igen efter opdateringsforsøg i kernestien
+- pre-check and refresh with retry for refreshable providers
+- 401/403 retry after refresh attempt in core path
 
-## 3) Strømsikkerhed
+## 3) Stream Safety
 
-- afbrydelsesbevidst streamcontroller
-- translationsstream med end-of-stream flush og `[DONE]` håndtering
-- forbrugsestimeret fallback, når udbyderens brugsmetadata mangler
+- disconnect-aware stream controller
+- translation stream with end-of-stream flush and `[DONE]` handling
+- usage estimation fallback when provider usage metadata is missing
 
-## 4) Cloud Sync-forringelse
+## 4) Cloud Sync Degradation
 
-- Synkroniseringsfejl dukker op, men lokal kørsel fortsætter
-- Scheduler har logik, der kan genforsøge, men periodisk udførelse kalder i øjeblikket enkelt-forsøgssynkronisering som standard
+- sync errors are surfaced but local runtime continues
+- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
 
-## 5) Dataintegritet
+## 5) Data Integrity
 
-- DB shape migration/reparation for manglende nøgler
-- korrupte JSON-nulstillingsbeskyttelsesforanstaltninger for localDb og usageDb
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
-## Observerbarhed og operationelle signaler
+## Observability and Operational Signals
 
-Kilder til synlighed ved kørsel:
+Runtime visibility sources:
 
-- konsollogfiler fra `src/sse/utils/logger.ts`
-- brugsaggregater pr. anmodning i `usage.json`
-- log på status for tekstanmodning `log.txt`
-- valgfri dybe anmodnings-/oversættelseslogfiler under `logs/` når `ENABLE_REQUEST_LOGS=true`
-- dashboardbrugsendepunkter (`/api/usage/*`) for brugergrænsefladeforbrug
+- console logs from `src/sse/utils/logger.ts`
+- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- textual request status log in `log.txt` (optional/compat)
+- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true`
+- dashboard usage endpoints (`/api/usage/*`) for UI consumption
 
-## Sikkerhedsfølsomme grænser
+## Security-Sensitive Boundaries
 
-- JWT-hemmelighed (`JWT_SECRET`) sikrer bekræftelse/signering af dashboard-sessionscookie
-- Indledende adgangskode fallback (`INITIAL_PASSWORD`, standard `123456`) skal tilsidesættes i rigtige implementeringer
-- API-nøgle HMAC-hemmelighed (`API_KEY_SECRET`) sikrer genereret lokalt API-nøgleformat
-- Udbyderhemmeligheder (API-nøgler/tokens) bevares i lokal DB og bør beskyttes på filsystemniveau
-- Slutpunkter for skysynkronisering er afhængige af API-nøglegodkendelse + maskin-id-semantik
+- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
+- 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
 
-## Miljø og Runtime Matrix
+## Environment and Runtime Matrix
 
-Miljøvariabler aktivt brugt af kode:
+Environment variables actively used by code:
 
-- App/godkendelse: `JWT_SECRET`, `INITIAL_PASSWORD`
-- Opbevaring: `DATA_DIR`
-- Kompatibel nodeadfærd: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
-- Valgfri lagerbasetilsidesættelse (Linux/macOS, når `DATA_DIR` ikke er indstillet): `XDG_CONFIG_HOME`
-- Sikkerhedshashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
-- Logning: `ENABLE_REQUEST_LOGS`
-- Synkronisering/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
-- Udgående proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` og varianter med små bogstaver
-- SOCKS5-funktionsflag: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
-- Platform-/runtime-hjælpere (ikke app-specifik konfiguration): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Storage: `DATA_DIR`
+- 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`
+- 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`
+- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
 
-## Kendte arkitektoniske noter
+## Known Architectural Notes
 
-1. `usageDb` og `localDb` deler nu den samme grundlæggende bibliotekspolitik (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) med ældre filmigrering.
-2. `/api/v1/route.ts` returnerer en statisk modelliste og er ikke den primære modelkilde, der bruges af `/v1/models`.
-3. Anmodningslogger skriver hele headers/body, når den er aktiveret; behandle logbiblioteket som følsomt.
-4. Cloudadfærd afhænger af korrekt `NEXT_PUBLIC_BASE_URL` og cloud-endepunkters tilgængelighed.
-5. `open-sse/` biblioteket udgives som `@omniroute/open-sse` **npm workspace-pakken**. Kildekoden importerer det via `@omniroute/open-sse/...` (løst af Next.js `transpilePackages`). Filstier i dette dokument bruger stadig mappenavnet `open-sse/` for at opnå konsistens.
-6. Diagrammer i dashboardet bruger **Recharts** (SVG-baseret) til tilgængelige, interaktive analysevisualiseringer (søjlediagrammer for modelbrug, udbyderopdelingstabeller med succesrater).
-7. E2E-tests bruger **Playwright** (`tests/e2e/`), køres via `npm run test:e2e`. Enhedstests bruger **Node.js testløber** (`tests/unit/`), køres via `npm run test:plan3`. Kildekoden under `src/` er **TypeScript** (`.ts`/`.tsx`); `open-sse/`-arbejdsområdet forbliver JavaScript (`.js`).
-8. Siden Indstillinger er organiseret i 5 faner: Sikkerhed, Routing (6 globale strategier: fill-first, round-robin, p2c, random, mindst brugt, omkostningsoptimeret), Resiliens (redigerbare hastighedsgrænser, strømafbryder, politikker), AI (tænkebudget, systemprompt, promptcache), Avanceret (proxy).
+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: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), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
 
-## Tjekliste for operationel verifikation
+## Operational Verification Checklist
 
-- Byg fra kilde: `npm run build`
-- Byg Docker-billede: `docker build -t omniroute .`
-- Start service og bekræft:
+- Build from source: `npm run build`
+- Build Docker image: `docker build -t omniroute .`
+- Start service and verify:
 - `GET /api/settings`
 - `GET /api/v1/models`
-- CLI-målbasis-URL skal være `http://<host>:20128/v1`, når `PORT=20128`
+- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`

docs/i18n/da/AUTO-COMBO.md

@@ -0,0 +1,67 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/AUTO-COMBO.md) · 🇪🇸 [es](../es/AUTO-COMBO.md) · 🇫🇷 [fr](../fr/AUTO-COMBO.md) · 🇩🇪 [de](../de/AUTO-COMBO.md) · 🇮🇹 [it](../it/AUTO-COMBO.md) · 🇷🇺 [ru](../ru/AUTO-COMBO.md) · 🇨🇳 [zh-CN](../zh-CN/AUTO-COMBO.md) · 🇯🇵 [ja](../ja/AUTO-COMBO.md) · 🇰🇷 [ko](../ko/AUTO-COMBO.md) · 🇸🇦 [ar](../ar/AUTO-COMBO.md) · 🇮🇳 [in](../in/AUTO-COMBO.md) · 🇹🇭 [th](../th/AUTO-COMBO.md) · 🇻🇳 [vi](../vi/AUTO-COMBO.md) · 🇮🇩 [id](../id/AUTO-COMBO.md) · 🇲🇾 [ms](../ms/AUTO-COMBO.md) · 🇳🇱 [nl](../nl/AUTO-COMBO.md) · 🇵🇱 [pl](../pl/AUTO-COMBO.md) · 🇸🇪 [sv](../sv/AUTO-COMBO.md) · 🇳🇴 [no](../no/AUTO-COMBO.md) · 🇩🇰 [da](../da/AUTO-COMBO.md) · 🇫🇮 [fi](../fi/AUTO-COMBO.md) · 🇵🇹 [pt](../pt/AUTO-COMBO.md) · 🇷🇴 [ro](../ro/AUTO-COMBO.md) · 🇭🇺 [hu](../hu/AUTO-COMBO.md) · 🇧🇬 [bg](../bg/AUTO-COMBO.md) · 🇸🇰 [sk](../sk/AUTO-COMBO.md) · 🇺🇦 [uk-UA](../uk-UA/AUTO-COMBO.md) · 🇮🇱 [he](../he/AUTO-COMBO.md) · 🇵🇭 [phi](../phi/AUTO-COMBO.md)
+
+---
+
+# 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/i18n/da/CODEBASE_DOCUMENTATION.md

@@ -1,22 +1,26 @@
-# omniroute — Kodebasedokumentation
-
-🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md)
-
-> En omfattende, begyndervenlig guide til **omniroute** multi-udbyder AI proxy-routeren.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../es/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../fr/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../de/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../it/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../ru/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../ja/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../ko/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../ar/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [in](../in/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../th/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../vi/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../id/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../ms/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../nl/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../pl/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../sv/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../no/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../da/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../fi/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../pt/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../ro/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../hu/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../bg/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../sk/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../he/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../phi/CODEBASE_DOCUMENTATION.md)
 
 ---
 
-## 1. Hvad er omniroute?
+# omniroute — Codebase Documentation
 
-omniroute er en **proxy-router**, der sidder mellem AI-klienter (Claude CLI, Codex, Cursor IDE osv.) og AI-udbydere (Anthropic, Google, OpenAI, AWS, GitHub osv.). Det løser et stort problem:
+🌐 **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)
 
-> **Forskellige AI-klienter taler forskellige "sprog" (API-formater), og forskellige AI-udbydere forventer også forskellige "sprog".** omniroute oversætter mellem dem automatisk.
-
-Tænk på det som en universel oversætter i FN - enhver delegeret kan tale et hvilket som helst sprog, og oversætteren konverterer det til enhver anden delegeret.
+> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router.
 
 ---
 
-## 2. Arkitekturoversigt
+## 1. What Is omniroute?
+
+omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem:
+
+> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically.
+
+Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate.
+
+---
+
+## 2. Architecture Overview
 
 ```mermaid
 graph LR
@@ -61,20 +65,20 @@ graph LR
     H -.-> G
 ```
 
-### Kerneprincip: Hub-and-Speake-oversættelse
+### Core Principle: Hub-and-Spoke Translation
 
-Al formatoversættelse passerer gennem **OpenAI-formatet som hub**:
+All format translation passes through **OpenAI format as the hub**:
 
 ```
 Client Format → [OpenAI Hub] → Provider Format    (request)
 Provider Format → [OpenAI Hub] → Client Format    (response)
 ```
 
-Det betyder, at du kun behøver **N oversættere** (én pr. format) i stedet for **N²** (hvert par).
+This means you only need **N translators** (one per format) instead of **N²** (every pair).
 
 ---
 
-## 3. Projektstruktur
+## 3. Project Structure
 
 ```
 omniroute/
@@ -104,20 +108,20 @@ omniroute/
 
 ---
 
-## 4. Modul-for-modul-opdeling
+## 4. Module-by-Module Breakdown
 
 ### 4.1 Config (`open-sse/config/`)
 
-Den **enkelte kilde til sandhed** for alle udbyderkonfigurationer.
+The **single source of truth** for all provider configuration.
 
-| Fil                           | Formål                                                                                                                                                                                                                                 |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `constants.ts`                | `PROVIDERS` objekt med basis-URL'er, OAuth-legitimationsoplysninger (standarder), headere og standardsystemprompter for hver udbyder. Definerer også `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` og `SKIP_PATTERNS`. |
-| `credentialLoader.ts`         | Indlæser eksterne legitimationsoplysninger fra `data/provider-credentials.json` og fletter dem over de hårdkodede standardindstillinger i `PROVIDERS`. Holder hemmeligheder uden for kildekontrol og bevarer bagudkompatibilitet.      |
-| `providerModels.ts`           | Central modelregistrering: kortudbyderaliasser → model-id'er. Funktioner som `getModels()`, `getProviderByAlias()`.                                                                                                                    |
-| `codexInstructions.ts`        | Systeminstruktioner indsat i Codex-anmodninger (redigeringsbegrænsninger, sandkasseregler, godkendelsespolitikker).                                                                                                                    |
-| `defaultThinkingSignature.ts` | Standard "tænkende" signaturer for Claude og Gemini modeller.                                                                                                                                                                          |
-| `ollamaModels.ts`             | Skemadefinition for lokale Ollama-modeller (navn, størrelse, familie, kvantisering).                                                                                                                                                   |
+| File                          | Purpose                                                                                                                                                                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `constants.ts`                | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. |
+| `credentialLoader.ts`         | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility.               |
+| `providerModels.ts`           | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`.                                                                                                          |
+| `codexInstructions.ts`        | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies).                                                                                                                 |
+| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models.                                                                                                                                                               |
+| `ollamaModels.ts`             | Schema definition for local Ollama models (name, size, family, quantization).                                                                                                                                             |
 
 #### Credential Loading Flow
 
@@ -142,9 +146,9 @@ flowchart TD
 
 ---
 
-### 4.2 Eksekutører (`open-sse/executors/`)
+### 4.2 Executors (`open-sse/executors/`)
 
-Eksekutører indkapsler **udbyderspecifik logik** ved hjælp af **Strategy Pattern**. Hver executor tilsidesætter basismetoder efter behov.
+Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed.
 
 ```mermaid
 classDiagram
@@ -194,32 +198,32 @@ classDiagram
     BaseExecutor <|-- GithubExecutor
 ```
 
-| Eksekutør        | Udbyder                                    | Nøglespecialiseringer                                                                                                                    |
-| ---------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `base.ts`        | —                                          | Abstrakt base: URL-opbygning, overskrifter, genforsøgslogik, opdatering af legitimationsoplysninger                                      |
-| `default.ts`     | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generisk OAuth-tokenopdatering til standardudbydere                                                                                      |
-| `antigravity.ts` | Google Cloud-kode                          | Generering af projekt-/sessions-id, multi-URL fallback, brugerdefineret genforsøg at parse fra fejlmeddelelser ("nulstil efter 2t7m23s") |
-| `cursor.ts`      | Markør IDE                                 | **Mest kompleks**: SHA-256 checksum auth, Protobuf request encoding, binær EventStream → SSE respons parsing                             |
-| `codex.ts`       | OpenAI Codex                               | Injicerer systeminstruktioner, styrer tankeniveauer, fjerner ikke-understøttede parametre                                                |
-| `gemini-cli.ts`  | Google Gemini CLI                          | Opbygning af tilpasset URL (`streamGenerateContent`), opdatering af Google OAuth-token                                                   |
-| `github.ts`      | GitHub Copilot                             | Dobbelt token-system (GitHub OAuth + Copilot-token), VSCode-header-efterligning                                                          |
-| `kiro.ts`        | AWS CodeWhisperer                          | AWS EventStream binær parsing, AMZN hændelsesrammer, token estimering                                                                    |
-| `index.ts`       | —                                          | Fabrik: navn på kortudbyder → eksekveringsklasse, med standard fallback                                                                  |
+| Executor         | Provider                                   | Key Specializations                                                                                                 |
+| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `base.ts`        | —                                          | Abstract base: URL building, headers, retry logic, credential refresh                                               |
+| `default.ts`     | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers                                                                  |
+| `antigravity.ts` | Google Cloud Code                          | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") |
+| `cursor.ts`      | Cursor IDE                                 | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing       |
+| `codex.ts`       | OpenAI Codex                               | Injects system instructions, manages thinking levels, removes unsupported parameters                                |
+| `gemini-cli.ts`  | Google Gemini CLI                          | Custom URL building (`streamGenerateContent`), Google OAuth token refresh                                           |
+| `github.ts`      | GitHub Copilot                             | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking                                           |
+| `kiro.ts`        | AWS CodeWhisperer                          | AWS EventStream binary parsing, AMZN event frames, token estimation                                                 |
+| `index.ts`       | —                                          | Factory: maps provider name → executor class, with default fallback                                                 |
 
 ---
 
-### 4.3 Håndtere (`open-sse/handlers/`)
+### 4.3 Handlers (`open-sse/handlers/`)
 
-**Orkestreringslaget** — koordinerer oversættelse, udførelse, streaming og fejlhåndtering.
+The **orchestration layer** — coordinates translation, execution, streaming, and error handling.
 
-| Fil                   | Formål                                                                                                                                                                                                                         |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `chatCore.ts`         | **Central orkestrator** (~600 linjer). Håndterer hele forespørgselslivscyklussen: formatdetektion → oversættelse → eksekutørafsendelse → streaming/ikke-streamingsvar → token-opdatering → fejlhåndtering → logføring af brug. |
-| `responsesHandler.ts` | Adapter til OpenAI's Responses API: konverterer svarformat → Chatfuldførelser → sender til `chatCore` → konverterer SSE tilbage til svarformat.                                                                                |
-| `embeddings.ts`       | Indlejringsgenereringshåndtering: løser indlejringsmodel → udbyder, sender til udbyder API, returnerer OpenAI-kompatibelt indlejringssvar. Understøtter 6+ udbydere.                                                           |
-| `imageGeneration.ts`  | Billedgenereringshåndtering: løser billedmodel → udbyder, understøtter OpenAI-kompatibel, Gemini-image (Antigravity) og fallback (Nebius) tilstande. Returnerer base64- eller URL-billeder.                                    |
+| File                  | Purpose                                                                                                                                                                                                                |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chatCore.ts`         | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. |
+| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format.                                                                        |
+| `embeddings.ts`       | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers.                                                    |
+| `imageGeneration.ts`  | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images.                                          |
 
-#### Anmod om livscyklus (chatCore.ts)
+#### Request Lifecycle (chatCore.ts)
 
 ```mermaid
 sequenceDiagram
@@ -258,26 +262,26 @@ sequenceDiagram
 
 ---
 
-### 4.4 Tjenester (`open-sse/services/`)
+### 4.4 Services (`open-sse/services/`)
 
-Forretningslogik, der understøtter behandlerne og udførerne.
+Business logic that supports the handlers and executors.
 
-| Fil                  | Formål                                                                                                                                                                                                                                                                                                                                                     |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `provider.ts`        | **Formatregistrering** (`detectFormat`): analyser anmoder om kropsstruktur for at identificere Claude/OpenAI/Gemini/Antigravity/Responses-formater (inkluderer `max_tokens` heuristik for Claude). Også: URL-opbygning, header-opbygning, normalisering af tænkekonfig. Understøtter `openai-compatible-*` og `anthropic-compatible-*` dynamiske udbydere. |
-| `model.ts`           | Modelstrengparsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias-opløsning med kollisionsdetektion, input-sanering (afviser stigennemgang/kontroltegn) og modelinformationsopløsning med understøttelse af async alias getter.                                                                                                |
-| `accountFallback.ts` | Håndtering af hastighedsgrænser: eksponentiel backoff (1s → 2s → 4s → max 2min), kontoafkølingsstyring, fejlklassificering (hvilke fejl udløser fallback vs. ikke).                                                                                                                                                                                        |
-| `tokenRefresh.ts`    | Opdatering af OAuth-token for **alle udbydere**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Inkluderer under flyvning lover deduplikation cache og forsøg igen med eksponentiel backoff.                                                                            |
-| `combo.ts`           | **Combo-modeller**: kæder af reservemodeller. Hvis model A fejler med en fallback-kvalificeret fejl, prøv model B, derefter C osv. Returnerer faktiske upstream-statuskoder.                                                                                                                                                                               |
-| `usage.ts`           | Henter kvote-/brugsdata fra udbyder-API'er (GitHub Copilot-kvoter, Antigravity-modelkvoter, Codex-hastighedsgrænser, Kiro-brugsopdelinger, Claude-indstillinger).                                                                                                                                                                                          |
-| `accountSelector.ts` | Smart kontovalg med scoringsalgoritme: overvejer prioritet, sundhedsstatus, round-robin-position og nedkølingstilstand for at vælge den optimale konto for hver anmodning.                                                                                                                                                                                 |
-| `contextManager.ts`  | Anmodningskontekstlivscyklusstyring: opretter og sporer kontekstobjekter pr. anmodning med metadata (anmodnings-id, tidsstempler, udbyderoplysninger) til fejlretning og logning.                                                                                                                                                                          |
-| `ipFilter.ts`        | IP-baseret adgangskontrol: understøtter tilladelsesliste og bloklistetilstande. Validerer klient-IP mod konfigurerede regler, før API-anmodninger behandles.                                                                                                                                                                                               |
-| `sessionManager.ts`  | Sessionssporing med klientfingeraftryk: sporer aktive sessioner ved hjælp af hashed klient-id'er, overvåger antallet af anmodninger og leverer sessionsmetrics.                                                                                                                                                                                            |
-| `signatureCache.ts`  | Anmod om signaturbaseret deduplikeringscache: forhindrer duplikerede anmodninger ved at cache de seneste anmodningssignaturer og returnere cachelagrede svar for identiske anmodninger inden for et tidsvindue.                                                                                                                                            |
-| `systemPrompt.ts`    | Global systemprompt-injektion: forudsætter eller tilføjer en konfigurerbar systemprompt til alle anmodninger med kompatibilitetshåndtering pr. udbyder.                                                                                                                                                                                                    |
-| `thinkingBudget.ts`  | Reasoning token budget management: understøtter passthrough, auto (strip thinking config), brugerdefineret (fast budget) og adaptive (kompleksitetsskaleret) tilstande til at kontrollere tanke/ræsonnement tokens.                                                                                                                                        |
-| `wildcardRouter.ts`  | Routing af jokertegnmodelmønster: løser jokertegnmønstre (f.eks. `*/claude-*`) til konkrete udbyder/modelpar baseret på tilgængelighed og prioritet.                                                                                                                                                                                                       |
+| File                 | Purpose                                                                                                                                                                                                                                                                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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.                                                                       |
+| `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.                                                                                                                                                              |
+| `contextManager.ts`  | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging.                                                                                                                                                                  |
+| `ipFilter.ts`        | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests.                                                                                                                                                                                          |
+| `sessionManager.ts`  | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics.                                                                                                                                                                            |
+| `signatureCache.ts`  | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window.                                                                                                                                              |
+| `systemPrompt.ts`    | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling.                                                                                                                                                                                            |
+| `thinkingBudget.ts`  | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens.                                                                                                                                        |
+| `wildcardRouter.ts`  | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority.                                                                                                                                                                                   |
 
 #### Token Refresh Deduplication
 
@@ -325,7 +329,7 @@ stateDiagram-v2
     }
 ```
 
-#### Kombi-modelkæde
+#### Combo Model Chain
 
 ```mermaid
 flowchart LR
@@ -344,11 +348,11 @@ flowchart LR
 
 ---
 
-### 4.5 Oversætter (`open-sse/translator/`)
+### 4.5 Translator (`open-sse/translator/`)
 
-**formatoversættelsesmotoren** ved hjælp af et selvregistrerende plugin-system.
+The **format translation engine** using a self-registering plugin system.
 
-#### Arkitektur
+#### Architecture
 
 ```mermaid
 graph TD
@@ -374,15 +378,15 @@ graph TD
     end
 ```
 
-| Katalog      | Filer         | Beskrivelse                                                                                                                                                                                                                                                                   |
-| ------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request/`   | 8 oversættere | Konverter anmodningstekster mellem formater. Hver fil selvregistreres via `register(from, to, fn)` ved import.                                                                                                                                                                |
-| `response/`  | 7 oversættere | Konverter streamingsvarstykker mellem formater. Håndterer SSE-hændelsestyper, tænkeblokke, værktøjskald.                                                                                                                                                                      |
-| `helpers/`   | 6 hjælpere    | Delte hjælpeprogrammer: `claudeHelper` (udtræk af systemprompt, tænkekonfiguration), `geminiHelper` (kortlægning af dele/indhold), `openaiHelper` (formatfiltrering), `toolCallHelper` (ID-generering, manglende svarindsprøjtning), `maxTokensHelper`, `responsesApiHelper`. |
-| `index.ts`   | —             | Oversættelsesmaskine: `translateRequest()`, `translateResponse()`, statsledelse, register.                                                                                                                                                                                    |
-| `formats.ts` | —             | Formatkonstanter: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`.                                                                                                                                                                          |
+| Directory    | Files         | Description                                                                                                                                                                                                                                                      |
+| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request/`   | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import.                                                                                                                                                         |
+| `response/`  | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls.                                                                                                                                                         |
+| `helpers/`   | 6 helpers     | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. |
+| `index.ts`   | —             | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry.                                                                                                                                                                     |
+| `formats.ts` | —             | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`.                                                                                                                                                             |
 
-#### Nøgledesign: Selvregistrerende plugins
+#### Key Design: Self-Registering Plugins
 
 ```javascript
 // Each translator file calls register() on import:
@@ -397,15 +401,15 @@ import "./request/claude-to-openai.js"; // ← self-registers
 
 ### 4.6 Utils (`open-sse/utils/`)
 
-| Fil                | Formål                                                                                                                                                                                                                                                                                          |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `error.ts`         | Opbygning af fejlsvar (OpenAI-kompatibelt format), upstream fejlparsing, Antigravity genforsøgstidsudtrækning fra fejlmeddelelser, SSE fejlstreaming.                                                                                                                                           |
-| `stream.ts`        | **SSE Transform Stream** — den centrale streamingpipeline. To tilstande: `TRANSLATE` (fuldformatoversættelse) og `PASSTHROUGH` (normalisering + ekstraktionsbrug). Håndterer chunk-buffring, brugsestimering, indholdslængdesporing. Per-stream encoder/decoder-instanser undgår delt tilstand. |
-| `streamHelpers.ts` | SSE-værktøjer på lavt niveau: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filtrerer tomme bidder til OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-bevidst SSETOKEN_101\*\* oprydning med oprydning med ).                                                         |
-| `usageTracking.ts` | Udtræk af tokenbrug fra ethvert format (Claude/OpenAI/Gemini/Responses), estimering med separate værktøj/meddelelse-char-per-token-forhold, buffertilsætning (2000 tokens sikkerhedsmargen), formatspecifik feltfiltrering, konsollogning med ANSI-farver.                                      |
-| `requestLogger.ts` | Filbaseret anmodningslogning (tilmelding via `ENABLE_REQUEST_LOGS=true`). Opretter sessionsmapper med nummererede filer: `1_req_client.json` → `7_res_client.txt`. Alle I/O er asynkrone (fire-and-forget). Masker følsomme overskrifter.                                                       |
-| `bypassHandler.ts` | Opsnapper specifikke mønstre fra Claude CLI (titeludtræk, opvarmning, optælling) og returnerer falske svar uden at ringe til nogen udbyder. Understøtter både streaming og ikke-streaming. Med vilje begrænset til Claude CLI-omfang.                                                           |
-| `networkProxy.ts`  | Løser udgående proxy-URL for en given udbyder med forrang: udbyderspecifik konfiguration → global konfiguration → miljøvariabler (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Understøtter `NO_PROXY` ekskluderinger. Caches konfiguration for 30'erne.                                            |
+| File               | Purpose                                                                                                                                                                                                                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `error.ts`         | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming.                                                                                                                              |
+| `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.                                                              |
+| `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.                                                  |
 
 #### SSE Streaming Pipeline
 
@@ -429,7 +433,7 @@ flowchart TD
     style M fill:#9f9,stroke:#333
 ```
 
-#### Anmod om loggersessionsstruktur
+#### Request Logger Session Structure
 
 ```
 logs/
@@ -447,109 +451,109 @@ logs/
 
 ---
 
-### 4.7 applikationslag (`src/`)
+### 4.7 Application Layer (`src/`)
 
-| Katalog       | Formål                                                                       |
-| ------------- | ---------------------------------------------------------------------------- |
-| `src/app/`    | Web-UI, API-ruter, Express-middleware, OAuth-tilbagekaldsbehandlere          |
-| `src/lib/`    | Databaseadgang (`localDb.ts`, `usageDb.ts`), godkendelse, delt               |
-| `src/mitm/`   | Man-in-the-middle proxy-værktøjer til at opsnappe udbydertrafik              |
-| `src/models/` | Databasemodeldefinitioner                                                    |
-| `src/shared/` | Indpakninger omkring åben-sse-funktioner (udbyder, stream, fejl osv.)        |
-| `src/sse/`    | SSE-slutpunktshandlere, der forbinder open-sse-biblioteket til Express-ruter |
-| `src/store/`  | Administration af applikationstilstand                                       |
+| Directory     | Purpose                                                                |
+| ------------- | ---------------------------------------------------------------------- |
+| `src/app/`    | Web UI, API routes, Express middleware, OAuth callback handlers        |
+| `src/lib/`    | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared   |
+| `src/mitm/`   | Man-in-the-middle proxy utilities for intercepting provider traffic    |
+| `src/models/` | Database model definitions                                             |
+| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.)     |
+| `src/sse/`    | SSE endpoint handlers that wire the open-sse library to Express routes |
+| `src/store/`  | Application state management                                           |
 
-#### Bemærkelsesværdige API-ruter
+#### Notable API Routes
 
-| Rute                                          | Metoder       | Formål                                                                                                 |
-| --------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------ |
-| `/api/provider-models`                        | GET/POST/SLET | CRUD til brugerdefinerede modeller pr. udbyder                                                         |
-| `/api/models/catalog`                         | FÅ            | Samlet katalog over alle modeller (chat, indlejring, billede, brugerdefineret) grupperet efter udbyder |
-| `/api/settings/proxy`                         | GET/SETT/SLET | Hierarkisk udgående proxy-konfiguration (`global/providers/combos/keys`)                               |
-| `/api/settings/proxy/test`                    | POST          | Validerer proxy-forbindelse og returnerer offentlig IP/latency                                         |
-| `/v1/providers/[provider]/chat/completions`   | POST          | Dedikerede chat-afslutninger pr. udbyder med modelvalidering                                           |
-| `/v1/providers/[provider]/embeddings`         | POST          | Dedikerede indlejringer pr. udbyder med modelvalidering                                                |
-| `/v1/providers/[provider]/images/generations` | POST          | Dedikeret billedgenerering pr. udbyder med modelvalidering                                             |
-| `/api/settings/ip-filter`                     | GET/PUT       | Administration af IP-tilladelsesliste/blokeringsliste                                                  |
-| `/api/settings/thinking-budget`               | GET/PUT       | Begrundelsestokens budgetkonfiguration (passthrough/auto/custom/adaptive)                              |
-| `/api/settings/system-prompt`                 | GET/PUT       | Global systemprompt-injektion for alle anmodninger                                                     |
-| `/api/sessions`                               | FÅ            | Aktiv sessionssporing og metrics                                                                       |
-| `/api/rate-limits`                            | FÅ            | Satsgrænsestatus pr. konto                                                                             |
+| Route                                         | Methods         | Purpose                                                                               |
+| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
+| `/api/provider-models`                        | GET/POST/DELETE | CRUD for custom models per provider                                                   |
+| `/api/models/catalog`                         | GET             | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider |
+| `/api/settings/proxy`                         | GET/PUT/DELETE  | Hierarchical outbound proxy configuration (`global/providers/combos/keys`)            |
+| `/api/settings/proxy/test`                    | POST            | Validates proxy connectivity and returns public IP/latency                            |
+| `/v1/providers/[provider]/chat/completions`   | POST            | Dedicated per-provider chat completions with model validation                         |
+| `/v1/providers/[provider]/embeddings`         | POST            | Dedicated per-provider embeddings with model validation                               |
+| `/v1/providers/[provider]/images/generations` | POST            | Dedicated per-provider image generation with model validation                         |
+| `/api/settings/ip-filter`                     | GET/PUT         | IP allowlist/blocklist management                                                     |
+| `/api/settings/thinking-budget`               | GET/PUT         | Reasoning token budget configuration (passthrough/auto/custom/adaptive)               |
+| `/api/settings/system-prompt`                 | GET/PUT         | Global system prompt injection for all requests                                       |
+| `/api/sessions`                               | GET             | Active session tracking and metrics                                                   |
+| `/api/rate-limits`                            | GET             | Per-account rate limit status                                                         |
 
 ---
 
-## 5. Nøgledesignmønstre
+## 5. Key Design Patterns
 
-### 5.1 Hub-and-Speake-oversættelse
+### 5.1 Hub-and-Spoke Translation
 
-Alle formater oversættes gennem **OpenAI-format som hub**. Tilføjelse af en ny udbyder kræver kun at skrive **et par** af oversættere (til/fra OpenAI), ikke N par.
+All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs.
 
-### 5.2 Eksekutørstrategimønster
+### 5.2 Executor Strategy Pattern
 
-Hver udbyder har en dedikeret eksekveringsklasse, der arver fra `BaseExecutor`. Fabrikken i `executors/index.ts` vælger den rigtige ved kørsel.
+Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime.
 
-### 5.3 Selvregistrerende plugin-system
+### 5.3 Self-Registering Plugin System
 
-Oversættermoduler registrerer sig selv ved import via `register()`. Tilføjelse af en ny oversætter er blot at oprette en fil og importere den.
+Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it.
 
-### 5.4 Account Fallback med eksponentiel backoff
+### 5.4 Account Fallback with Exponential Backoff
 
-Når en udbyder returnerer 429/401/500, kan systemet skifte til den næste konto ved at anvende eksponentielle nedkøling (1s → 2s → 4s → max 2min).
+When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min).
 
-### 5.5 Combo modelkæder
+### 5.5 Combo Model Chains
 
-En "combo" grupperer flere `provider/model` strenge. Hvis den første fejler, går du automatisk tilbage til den næste.
+A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically.
 
-### 5.6 Stateful streaming-oversættelse
+### 5.6 Stateful Streaming Translation
 
-Svaroversættelse opretholder tilstand på tværs af SSE-chunks (tænkebloksporing, akkumulering af værktøjsopkald, indholdsblokindeksering) via `initState()`-mekanismen.
+Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism.
 
-### 5.7 Sikkerhedsbuffer for brug
+### 5.7 Usage Safety Buffer
 
-En 2000-token buffer tilføjes til rapporteret brug for at forhindre klienter i at ramme kontekstvinduegrænser på grund af overhead fra systemprompter og formatoversættelse.
+A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation.
 
 ---
 
-## 6. Understøttede formater
+## 6. Supported Formats
 
-| Format                   | Retning     | Identifikator      |
-| ------------------------ | ----------- | ------------------ |
-| OpenAI Chat fuldførelser | kilde + mål | `openai`           |
-| OpenAI Responses API     | kilde + mål | `openai-responses` |
-| Antropiske Claude        | kilde + mål | `claude`           |
-| Google Gemini            | kilde + mål | `gemini`           |
-| Google Gemini CLI        | kun mål     | `gemini-cli`       |
-| Antigravitation          | kilde + mål | `antigravity`      |
-| AWS Kiro                 | kun mål     | `kiro`             |
-| Markør                   | kun mål     | `cursor`           |
+| Format                  | Direction       | Identifier         |
+| ----------------------- | --------------- | ------------------ |
+| OpenAI Chat Completions | source + target | `openai`           |
+| OpenAI Responses API    | source + target | `openai-responses` |
+| Anthropic Claude        | source + target | `claude`           |
+| Google Gemini           | source + target | `gemini`           |
+| Google Gemini CLI       | target only     | `gemini-cli`       |
+| Antigravity             | source + target | `antigravity`      |
+| AWS Kiro                | target only     | `kiro`             |
+| Cursor                  | target only     | `cursor`           |
 
 ---
 
-## 7. Understøttede udbydere
+## 7. Supported Providers
 
-| Udbyder                  | Auth metode                   | Eksekutør       | Nøglebemærkninger                               |
-| ------------------------ | ----------------------------- | --------------- | ----------------------------------------------- |
-| Antropiske Claude        | API-nøgle eller OAuth         | Standard        | Bruger `x-api-key` header                       |
-| Google Gemini            | API-nøgle eller OAuth         | Standard        | Bruger `x-goog-api-key` header                  |
-| Google Gemini CLI        | OAuth                         | GeminiCLI       | Bruger `streamGenerateContent` slutpunkt        |
-| Antigravitation          | OAuth                         | Antigravitation | Multi-URL fallback, tilpasset genforsøg parsing |
-| OpenAI                   | API nøgle                     | Standard        | Standard bærer auth                             |
-| Codex                    | OAuth                         | Codex           | Injicerer systeminstruktioner, styrer tænkning  |
-| GitHub Copilot           | OAuth + Copilot-token         | Github          | Dobbelt token, VSCode-header-efterligning       |
-| Kiro (AWS)               | AWS SSO OIDC eller Social     | Kiro            | Binær EventStream-parsing                       |
-| Markør IDE               | Kontrolsum auth               | Markør          | Protobuf-kodning, SHA-256 kontrolsummer         |
-| Qwen                     | OAuth                         | Standard        | Standard auth                                   |
-| iFlow                    | OAuth (grundlæggende + bærer) | Standard        | Dobbelt godkendelseshoved                       |
-| OpenRouter               | API nøgle                     | Standard        | Standard bærer auth                             |
-| GLM, Kimi, MiniMax       | API nøgle                     | Standard        | Claude-kompatibel, brug `x-api-key`             |
-| `openai-compatible-*`    | API nøgle                     | Standard        | Dynamisk: ethvert OpenAI-kompatibelt slutpunkt  |
-| `anthropic-compatible-*` | API nøgle                     | Standard        | Dynamisk: ethvert Claude-kompatibelt slutpunkt  |
+| Provider                 | Auth Method            | Executor    | Key Notes                                     |
+| ------------------------ | ---------------------- | ----------- | --------------------------------------------- |
+| Anthropic Claude         | API key or OAuth       | Default     | Uses `x-api-key` header                       |
+| Google Gemini            | API key or OAuth       | Default     | Uses `x-goog-api-key` header                  |
+| Google Gemini CLI        | OAuth                  | GeminiCLI   | Uses `streamGenerateContent` endpoint         |
+| Antigravity              | OAuth                  | Antigravity | Multi-URL fallback, custom retry parsing      |
+| OpenAI                   | API key                | Default     | Standard Bearer auth                          |
+| Codex                    | OAuth                  | Codex       | Injects system instructions, manages thinking |
+| GitHub Copilot           | OAuth + Copilot token  | Github      | Dual token, VSCode header mimicking           |
+| 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                              |
+| 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       |
+| `anthropic-compatible-*` | API key                | Default     | Dynamic: any Claude-compatible endpoint       |
 
 ---
 
-## 8. Oversigt over dataflow
+## 8. Data Flow Summary
 
-### Streaminganmodning
+### Streaming Request
 
 ```mermaid
 flowchart LR
@@ -566,7 +570,7 @@ flowchart LR
     K --> L["logUsage()\nsaveRequestUsage()"]
 ```
 
-### Ikke-streamende anmodning
+### Non-Streaming Request
 
 ```mermaid
 flowchart LR

docs/i18n/da/FEATURES.md

@@ -1,77 +1,148 @@
-# OmniRoute — Dashboard Feature Gallery
-
-🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md)
-
-Visuel guide til hver sektion af OmniRoute-dashboardet.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/FEATURES.md) · 🇪🇸 [es](../es/FEATURES.md) · 🇫🇷 [fr](../fr/FEATURES.md) · 🇩🇪 [de](../de/FEATURES.md) · 🇮🇹 [it](../it/FEATURES.md) · 🇷🇺 [ru](../ru/FEATURES.md) · 🇨🇳 [zh-CN](../zh-CN/FEATURES.md) · 🇯🇵 [ja](../ja/FEATURES.md) · 🇰🇷 [ko](../ko/FEATURES.md) · 🇸🇦 [ar](../ar/FEATURES.md) · 🇮🇳 [in](../in/FEATURES.md) · 🇹🇭 [th](../th/FEATURES.md) · 🇻🇳 [vi](../vi/FEATURES.md) · 🇮🇩 [id](../id/FEATURES.md) · 🇲🇾 [ms](../ms/FEATURES.md) · 🇳🇱 [nl](../nl/FEATURES.md) · 🇵🇱 [pl](../pl/FEATURES.md) · 🇸🇪 [sv](../sv/FEATURES.md) · 🇳🇴 [no](../no/FEATURES.md) · 🇩🇰 [da](../da/FEATURES.md) · 🇫🇮 [fi](../fi/FEATURES.md) · 🇵🇹 [pt](../pt/FEATURES.md) · 🇷🇴 [ro](../ro/FEATURES.md) · 🇭🇺 [hu](../hu/FEATURES.md) · 🇧🇬 [bg](../bg/FEATURES.md) · 🇸🇰 [sk](../sk/FEATURES.md) · 🇺🇦 [uk-UA](../uk-UA/FEATURES.md) · 🇮🇱 [he](../he/FEATURES.md) · 🇵🇭 [phi](../phi/FEATURES.md)
 
 ---
 
-## 🔌 Udbydere
+# OmniRoute — Dashboard Features Gallery
 
-Administrer AI-udbyderforbindelser: OAuth-udbydere (Claude Code, Codex, Gemini CLI), API-nøgleudbydere (Groq, DeepSeek, OpenRouter) og gratis udbydere (iFlow, Qwen, Kiro).
+🌐 **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)
+
+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).
+
+- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` (free "Light usage" tier); use `ollamacloud/<model>` prefix
 
 ![Providers Dashboard](screenshots/01-providers.png)
 
 ---
 
-## 🎨 Kombinationer
+## 🎨 Combos
 
-Opret modelrouting (model aliases, background task degradation)-kombinationer med 6 strategier: Fyld-først, round-robin, power-of-to-choices, tilfældig, mindst brugt og omkostningsoptimeret. Hver combo kæder flere modeller med automatisk fallback.
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
 
 ![Combos Dashboard](screenshots/02-combos.png)
 
 ---
 
-## 📊 Analyse
+## 📊 Analytics
 
-Omfattende brugsanalyse med token-forbrug, omkostningsestimater, aktivitetsvarmekort, ugentlige distributionsdiagrammer og opdelinger pr. udbyder.
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
 
 ![Analytics Dashboard](screenshots/03-analytics.png)
 
 ---
 
-## 🏥 Systemsundhed
+## 🏥 System Health
 
-Overvågning i realtid: oppetid, hukommelse, version, latency percentiler (p50/p95/p99), cache-statistik og udbyderens afbrydertilstande.
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
 
 ![Health Dashboard](screenshots/04-health.png)
 
 ---
 
-## 🔧 Oversætterlegeplads
+## 🔧 Translator Playground
 
-Fire tilstande til fejlfinding af API-oversættelser: **Playground** (formatkonverter), **Chat Tester** (live-anmodninger), **Test Bench** (batchtest) og **Live Monitor** (streaming i realtid).
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
 
 ![Translator Playground](screenshots/05-translator.png)
 
 ---
 
-## ⚙️ Indstillinger
+## 🎮 Model Playground _(v2.0.9+)_
 
-Generelle indstillinger, systemlagring, backup-styring (eksport/import-database), udseende (mørk/lys-tilstand), sikkerhed (inkluderer API-endepunktsbeskyttelse og blokering af tilpasset udbyder), routing, modstandsdygtighed og avanceret konfiguration.
+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
+
+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
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
 
 ![Settings Dashboard](screenshots/06-settings.png)
 
 ---
 
-## 🔧 CLI-værktøjer
+## 🔧 CLI Tools
 
-Et-klik-konfiguration til AI-kodningsværktøjer: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code og 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)
 
 ---
 
-## 📝 Anmodningslogs
+## 🤖 CLI Agents _(v2.0.11+)_
 
-Logning af anmodninger i realtid med filtrering efter udbyder, model, konto og API-nøgle. Viser statuskoder, tokenbrug, latenstid og svardetaljer.
+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
+
+---
+
+## 🖼️ 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.
 
 ![Usage Logs](screenshots/08-usage.png)
 
 ---
 
-## 🌐 API-endepunkt
+## 🌐 API Endpoint
 
-Dit forenede API-slutpunkt med kapacitetsopdeling: Chatfuldførelser, indlejringer, billedgenerering, omrangering, lydtransskription og registrerede API-nøgler.
+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. 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)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/da/MCP-SERVER.md

@@ -0,0 +1,87 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/MCP-SERVER.md) · 🇪🇸 [es](../es/MCP-SERVER.md) · 🇫🇷 [fr](../fr/MCP-SERVER.md) · 🇩🇪 [de](../de/MCP-SERVER.md) · 🇮🇹 [it](../it/MCP-SERVER.md) · 🇷🇺 [ru](../ru/MCP-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/MCP-SERVER.md) · 🇯🇵 [ja](../ja/MCP-SERVER.md) · 🇰🇷 [ko](../ko/MCP-SERVER.md) · 🇸🇦 [ar](../ar/MCP-SERVER.md) · 🇮🇳 [in](../in/MCP-SERVER.md) · 🇹🇭 [th](../th/MCP-SERVER.md) · 🇻🇳 [vi](../vi/MCP-SERVER.md) · 🇮🇩 [id](../id/MCP-SERVER.md) · 🇲🇾 [ms](../ms/MCP-SERVER.md) · 🇳🇱 [nl](../nl/MCP-SERVER.md) · 🇵🇱 [pl](../pl/MCP-SERVER.md) · 🇸🇪 [sv](../sv/MCP-SERVER.md) · 🇳🇴 [no](../no/MCP-SERVER.md) · 🇩🇰 [da](../da/MCP-SERVER.md) · 🇫🇮 [fi](../fi/MCP-SERVER.md) · 🇵🇹 [pt](../pt/MCP-SERVER.md) · 🇷🇴 [ro](../ro/MCP-SERVER.md) · 🇭🇺 [hu](../hu/MCP-SERVER.md) · 🇧🇬 [bg](../bg/MCP-SERVER.md) · 🇸🇰 [sk](../sk/MCP-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/MCP-SERVER.md) · 🇮🇱 [he](../he/MCP-SERVER.md) · 🇵🇭 [phi](../phi/MCP-SERVER.md)
+
+---
+
+# 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                 |
+| `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/i18n/da/README.md

@@ -20,7 +20,7 @@ _Din universelle API-proxy — ét slutpunkt, 36+ udbydere, ingen nedetid. Nu me
 
 </div>
 
-🌐 **Tilgængelig på:** 🇺🇸 [engelsk](README.md) | 🇧🇷 [Português (Brasil)](README.pt-BR.md) | 🇪🇸 [Español](README.es.md) | 🇫🇷 [Français](README.fr.md) | 🇮🇹 [Italiano](README.it.md) | 🇷🇺 [Русский](README.ru.md) | 🇨🇳 [中文 (简体)](README.zh-CN.md) | 🇩🇪 [Tysk](README.de.md) | 🇮🇳 [हिन्दी](README.in.md) | 🇹🇭 [ไทย](README.th.md) | 🇺🇦 [Українська](README.uk-UA.md) | 🇸🇦 [العربية](README.ar.md) | 🇯🇵 [日本語](README.ja.md) | 🇻🇳 [Tiếng Việt](README.vi.md) | 🇧🇬 [Български](README.bg.md) | 🇩🇰 [Dansk](README.da.md) | 🇫🇮 [Suomi](README.fi.md) | 🇮🇱 [engelsk](README.he.md) | 🇭🇺 [Magyar](README.hu.md) | 🇮🇩 [Bahasa Indonesien](README.id.md) | 🇰🇷 [한국어](README.ko.md) | 🇲🇾 [Bahasa Melayu](README.ms.md) | 🇳🇱 [Nederlands](README.nl.md) | 🇳🇴 [norsk](README.no.md) | 🇵🇹 [Português (Portugal)](README.pt.md) | 🇷🇴 [Română](README.ro.md) | 🇵🇱 [Polski](README.pl.md) | 🇸🇰 [Slovenčina](README.sk.md) | 🇸🇪 [Svenska](README.sv.md) | 🇵🇭 [filippinsk](README.phi.md)
+🌐 **Tilgængelig på:** 🇺🇸 [engelsk](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Tysk](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [engelsk](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesien](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [filippinsk](../phi/README.md)
 
 ---
 
@@ -53,6 +53,18 @@ _Din universelle API-proxy — ét slutpunkt, 36+ udbydere, ingen nedetid. Nu me
 
 ---
 
+### 🚀 New in v2.0.9+ — Playground, CLI Fingerprints & ACP
+
+| Feature                                    | What It Does                                                                                                                                  |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🎮 **Model Playground**                    | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing                        |
+| 🔏 **CLI Fingerprint Matching**            | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |
+| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw), process spawner, `/api/acp/agents` endpoint                                 |
+| 🤖 **ACP Agents Dashboard**                | Debug > Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool                                      |
+| 🔧 **Custom Model `apiFormat` Routing**    | Custom models with `apiFormat: "responses"` now correctly route to the Responses API translator                                               |
+| 🏢 **Codex Workspace Isolation**           | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID                                                   |
+| 🔄 **Electron Auto-Update**                | Desktop app checks for updates + auto-install on restart                                                                                      |
+
 ### 🤖 Gratis AI-udbyder til dine foretrukne kodningsagenter
 
 _Tilslut ethvert AI-drevet IDE- eller CLI-værktøj gennem OmniRoute - gratis API-gateway til ubegrænset kodning._
@@ -253,6 +265,7 @@ Ikke alle kan betale $20-200/måned for AI-abonnementer. Studerende, udviklere f
 **Sådan løser OmniRoute det:**
 
 - **Free Tier Providers Indbygget** — Indbygget support for 100 % gratis udbydere: iFlow (8 ubegrænsede modeller), Qwen (3 ubegrænsede modeller), Kiro (Claude gratis), Gemini CLI (180K/måned gratis)
+- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/<model>` prefix
 - **Kun gratis kombinationer** — Kæde `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/måned uden nedetid
 - **NVIDIA NIM gratis kreditter** — 1000 gratis kreditter integreret
 - **Cost Optimized Strategy** — Routingstrategi, der automatisk vælger den billigste tilgængelige udbyder
@@ -394,7 +407,7 @@ AI er ikke kun fuldførelse af chat. Udviklere skal generere billeder, transskri
 - **Tekst-til-video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) og SD WebUI
 - **Tekst-til-musik** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)
 - **Lydtransskription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3
-- **Tekst-til-tale** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, + eksisterende udbydere
+- **Tekst-til-tale** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + eksisterende udbydere
 - **Moderationer** — `/v1/moderations` — Indholdssikkerhedstjek
 - **Omrangering** — `/v1/rerank` — Omrangering af dokumentrelevans
 - **Responses API** — Fuld `/v1/responses`-understøttelse af Codex
@@ -920,17 +933,18 @@ OmniRoute v2.0 er bygget som en operationel platform, ikke kun en relæ-proxy.
 
 ### 🛡️ Resiliens, sikkerhed og styring
 
-| Funktion                            | Hvad det gør                                                          |
-| ----------------------------------- | --------------------------------------------------------------------- |
-| 🔌 **Maksimalafbrydere**            | Trip/recover på udbyderniveau med tærskelkontrol                      |
-| 🛡️ **Anti-tordenbesætning**         | Mutex + semaforbeskyttelse ved genforsøg/rate hændelser               |
-| 🧠 **Semantisk + signaturcache**    | Reduktion af omkostninger/latens med to cachelag                      |
-| ⚡ **Anmod om idempotens**          | Dobbelt beskyttelsesvindue                                            |
-| 🔒 **TLS Fingerprint Spoofing**     | Bedre kompatibilitet med anti-bot-filtrerede udbydere                 |
-| 🌐 **IP-filtrering**                | Tilladelsesliste/blokeringslistekontrol for udsatte implementeringer  |
-| 📊 **Redigerbare satsgrænser**      | Konfigurerbare grænser på globalt niveau/udbyderniveau med persistens |
-| 🔑 **API Key Management + Scoping** | Sikker nøgleudstedelse/rotation og model-/leverandørkontrol           |
-| 🛡️ **Beskyttet `/models`**          | Valgfri godkendelse og udbyderskjul til modelkatalog                  |
+| Funktion                            | Hvad det gør                                                                           |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Maksimalafbrydere**            | Trip/recover på udbyderniveau med tærskelkontrol                                       |
+| 🛡️ **Anti-tordenbesætning**         | Mutex + semaforbeskyttelse ved genforsøg/rate hændelser                                |
+| 🧠 **Semantisk + signaturcache**    | Reduktion af omkostninger/latens med to cachelag                                       |
+| ⚡ **Anmod om idempotens**          | Dobbelt beskyttelsesvindue                                                             |
+| 🔒 **TLS Fingerprint Spoofing**     | Bedre kompatibilitet med anti-bot-filtrerede udbydere                                  |
+| 🔏 **CLI Fingerprint Matching**     | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
+| 🌐 **IP-filtrering**                | Tilladelsesliste/blokeringslistekontrol for udsatte implementeringer                   |
+| 📊 **Redigerbare satsgrænser**      | Konfigurerbare grænser på globalt niveau/udbyderniveau med persistens                  |
+| 🔑 **API Key Management + Scoping** | Sikker nøgleudstedelse/rotation og model-/leverandørkontrol                            |
+| 🛡️ **Beskyttet `/models`**          | Valgfri godkendelse og udbyderskjul til modelkatalog                                   |
 
 ### 📊 Observerbarhed og analyse
 

docs/i18n/da/RELEASE_CHECKLIST.md

@@ -0,0 +1,37 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) · 🇪🇸 [es](../es/RELEASE_CHECKLIST.md) · 🇫🇷 [fr](../fr/RELEASE_CHECKLIST.md) · 🇩🇪 [de](../de/RELEASE_CHECKLIST.md) · 🇮🇹 [it](../it/RELEASE_CHECKLIST.md) · 🇷🇺 [ru](../ru/RELEASE_CHECKLIST.md) · 🇨🇳 [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) · 🇯🇵 [ja](../ja/RELEASE_CHECKLIST.md) · 🇰🇷 [ko](../ko/RELEASE_CHECKLIST.md) · 🇸🇦 [ar](../ar/RELEASE_CHECKLIST.md) · 🇮🇳 [in](../in/RELEASE_CHECKLIST.md) · 🇹🇭 [th](../th/RELEASE_CHECKLIST.md) · 🇻🇳 [vi](../vi/RELEASE_CHECKLIST.md) · 🇮🇩 [id](../id/RELEASE_CHECKLIST.md) · 🇲🇾 [ms](../ms/RELEASE_CHECKLIST.md) · 🇳🇱 [nl](../nl/RELEASE_CHECKLIST.md) · 🇵🇱 [pl](../pl/RELEASE_CHECKLIST.md) · 🇸🇪 [sv](../sv/RELEASE_CHECKLIST.md) · 🇳🇴 [no](../no/RELEASE_CHECKLIST.md) · 🇩🇰 [da](../da/RELEASE_CHECKLIST.md) · 🇫🇮 [fi](../fi/RELEASE_CHECKLIST.md) · 🇵🇹 [pt](../pt/RELEASE_CHECKLIST.md) · 🇷🇴 [ro](../ro/RELEASE_CHECKLIST.md) · 🇭🇺 [hu](../hu/RELEASE_CHECKLIST.md) · 🇧🇬 [bg](../bg/RELEASE_CHECKLIST.md) · 🇸🇰 [sk](../sk/RELEASE_CHECKLIST.md) · 🇺🇦 [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) · 🇮🇱 [he](../he/RELEASE_CHECKLIST.md) · 🇵🇭 [phi](../phi/RELEASE_CHECKLIST.md)
+
+---
+
+# 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/i18n/da/TROUBLESHOOTING.md

@@ -1,87 +1,91 @@
-# Fejlfinding
-
-🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md)
-
-Almindelige problemer og løsninger til OmniRoute.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/TROUBLESHOOTING.md) · 🇪🇸 [es](../es/TROUBLESHOOTING.md) · 🇫🇷 [fr](../fr/TROUBLESHOOTING.md) · 🇩🇪 [de](../de/TROUBLESHOOTING.md) · 🇮🇹 [it](../it/TROUBLESHOOTING.md) · 🇷🇺 [ru](../ru/TROUBLESHOOTING.md) · 🇨🇳 [zh-CN](../zh-CN/TROUBLESHOOTING.md) · 🇯🇵 [ja](../ja/TROUBLESHOOTING.md) · 🇰🇷 [ko](../ko/TROUBLESHOOTING.md) · 🇸🇦 [ar](../ar/TROUBLESHOOTING.md) · 🇮🇳 [in](../in/TROUBLESHOOTING.md) · 🇹🇭 [th](../th/TROUBLESHOOTING.md) · 🇻🇳 [vi](../vi/TROUBLESHOOTING.md) · 🇮🇩 [id](../id/TROUBLESHOOTING.md) · 🇲🇾 [ms](../ms/TROUBLESHOOTING.md) · 🇳🇱 [nl](../nl/TROUBLESHOOTING.md) · 🇵🇱 [pl](../pl/TROUBLESHOOTING.md) · 🇸🇪 [sv](../sv/TROUBLESHOOTING.md) · 🇳🇴 [no](../no/TROUBLESHOOTING.md) · 🇩🇰 [da](../da/TROUBLESHOOTING.md) · 🇫🇮 [fi](../fi/TROUBLESHOOTING.md) · 🇵🇹 [pt](../pt/TROUBLESHOOTING.md) · 🇷🇴 [ro](../ro/TROUBLESHOOTING.md) · 🇭🇺 [hu](../hu/TROUBLESHOOTING.md) · 🇧🇬 [bg](../bg/TROUBLESHOOTING.md) · 🇸🇰 [sk](../sk/TROUBLESHOOTING.md) · 🇺🇦 [uk-UA](../uk-UA/TROUBLESHOOTING.md) · 🇮🇱 [he](../he/TROUBLESHOOTING.md) · 🇵🇭 [phi](../phi/TROUBLESHOOTING.md)
 
 ---
 
-## Hurtige rettelser
+# Troubleshooting
 
-| Problem                                | Løsning                                                                     |
-| -------------------------------------- | --------------------------------------------------------------------------- |
-| Første login virker ikke               | Tjek `INITIAL_PASSWORD` i `.env` (standard: `123456`)                       |
-| Dashboard åbner ved forkert port       | Sæt `PORT=20128` og `NEXT_PUBLIC_BASE_URL=http://localhost:20128`           |
-| Ingen anmodningslogfiler under `logs/` | Sæt `ENABLE_REQUEST_LOGS=true`                                              |
-| EACCES: tilladelse nægtet              | Indstil `DATA_DIR=/path/to/writable/dir` til at tilsidesætte `~/.omniroute` |
-| Routingstrategi gemmer ikke            | Opdatering til v1.4.11+ (Zod-skemafix for indstillinger persistens)         |
+🌐 **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)
+
+Common problems and solutions for OmniRoute.
 
 ---
 
-## Udbyderproblemer
+## Quick Fixes
 
-### "Sprogmodellen leverede ikke beskeder"
-
-**Årsag:** Udbyderkvoten er opbrugt.
-
-**Ret:**
-
-1. Tjek dashboard kvotesporing
-2. Brug en kombination med reserveniveauer
-3. Skift til billigere/gratis niveau
-
-### Satsbegrænsende
-
-**Årsag:** Abonnementskvoten er opbrugt.
-
-**Ret:**
-
-- Tilføj reserve: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-- Brug GLM/MiniMax som billig backup
-
-### OAuth-token er udløbet
-
-OmniRoute opdaterer automatisk tokens. Hvis problemerne fortsætter:
-
-1. Dashboard → Udbyder → Genopret forbindelse
-2. Slet og tilføj udbyderforbindelsen igen
+| 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 request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true`                                     |
+| 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)       |
 
 ---
 
-## Skyproblemer
+## Provider Issues
 
-### Cloud Sync-fejl
+### "Language model did not provide messages"
 
-1. Bekræft `BASE_URL` point til din løbeforekomst (f.eks. `http://localhost:20128`)
-2. Bekræft `CLOUD_URL` punkter til dit cloud-endepunkt (f.eks. `https://omniroute.dev`)
-3. Hold `NEXT_PUBLIC_*` værdier på linje med værdier på serversiden
+**Cause:** Provider quota exhausted.
 
-### Cloud `stream=false` Returnerer 500
+**Fix:**
 
-**Symptom:** `Unexpected token 'd'...` på cloud-endepunkt til ikke-streamingopkald.
+1. Check dashboard quota tracker
+2. Use a combo with fallback tiers
+3. Switch to cheaper/free tier
 
-**Årsag:** Upstream returnerer SSE-nyttelast, mens klienten forventer JSON.
+### Rate Limiting
 
-**Løsning:** Brug `stream=true` til direkte skyopkald. Lokal kørselstid inkluderer SSE→JSON fallback.
+**Cause:** Subscription quota exhausted.
 
-### Cloud siger tilsluttet, men "Ugyldig API-nøgle"
+**Fix:**
 
-1. Opret en ny nøgle fra det lokale dashboard (`/api/keys`)
-2. Kør skysynkronisering: Aktiver sky → Synkroniser nu
-3. Gamle/ikke-synkroniserede nøgler kan stadig returnere `401` på skyen
+- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Use GLM/MiniMax as cheap backup
+
+### OAuth Token Expired
+
+OmniRoute auto-refreshes tokens. If issues persist:
+
+1. Dashboard → Provider → Reconnect
+2. Delete and re-add the provider connection
 
 ---
 
-## Docker-problemer
+## Cloud Issues
 
-### CLI-værktøj viser ikke installeret
+### Cloud Sync Errors
 
-1. Tjek runtime-felter: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
-2. For bærbar tilstand: brug billedmål `runner-cli` (bundtede CLI'er)
-3. For værtsmonteringstilstand: Indstil `CLI_EXTRA_PATHS` og monter værtsbin-mappen som skrivebeskyttet
-4. Hvis `installed=true` og `runnable=false`: binær blev fundet, men helbredstjekket mislykkedes
+1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
+2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
+3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
 
-### Hurtig runtime-validering
+### Cloud `stream=false` Returns 500
+
+**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
+
+**Cause:** Upstream returns SSE payload while client expects JSON.
+
+**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
+
+### Cloud Says Connected but "Invalid API key"
+
+1. Create a fresh key from local dashboard (`/api/keys`)
+2. Run cloud sync: Enable Cloud → Sync Now
+3. Old/non-synced keys can still return `401` on cloud
+
+---
+
+## Docker Issues
+
+### CLI Tool Shows Not Installed
+
+1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. For portable mode: use image target `runner-cli` (bundled CLIs)
+3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
+4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
+
+### Quick Runtime Validation
 
 ```bash
 curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
@@ -91,24 +95,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
 
 ---
 
-## Omkostningsproblemer
+## Cost Issues
 
-### Høje omkostninger
+### High Costs
 
-1. Tjek brugsstatistik i Dashboard → Brug
-2. Skift primær model til GLM/MiniMax
-3. Brug gratis niveau (Gemini CLI, iFlow) til ikke-kritiske opgaver
-4. Indstil omkostningsbudgetter pr. API-nøgle: Dashboard → API-nøgler → Budget
+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
+4. Set cost budgets per API key: Dashboard → API Keys → Budget
 
 ---
 
-## Fejlretning
+## Debugging
 
-### Aktiver anmodningslogfiler
+### Enable Request Logs
 
-Indstil `ENABLE_REQUEST_LOGS=true` i din `.env` fil. Logfiler vises under biblioteket `logs/`.
+Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory.
 
-### Tjek udbyderens helbred
+### Check Provider Health
 
 ```bash
 # Health dashboard
@@ -120,100 +124,135 @@ curl http://localhost:20128/api/monitoring/health
 
 ### Runtime Storage
 
-- Hovedtilstand: `${DATA_DIR}/db.json` (udbydere, kombinationer, aliaser, nøgler, indstillinger)
-- Anvendelse: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
-- Anmodningslogfiler: `<repo>/logs/...` (når `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}/log.txt` and `${DATA_DIR}/call_logs/`
+- Request logs: `<repo>/logs/...` (when `ENABLE_REQUEST_LOGS=true`)
 
 ---
 
-## Circuit Breaker Problemer
+## Circuit Breaker Issues
 
-### Udbyder sidder fast i ÅBEN tilstand
+### Provider stuck in OPEN state
 
-Når en udbyders afbryder er ÅBEN, blokeres anmodninger, indtil nedkølingen udløber.
+When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
 
-**Ret:**
+**Fix:**
 
-1. Gå til **Dashboard → Indstillinger → Resiliens**
-2. Tjek afbryderkortet for den berørte udbyder
-3. Klik på **Nulstil alle** for at rydde alle afbrydere, eller vent på, at nedkølingen udløber
-4. Bekræft, at udbyderen faktisk er tilgængelig, før du nulstiller
+1. Go to **Dashboard → Settings → Resilience**
+2. Check the circuit breaker card for the affected provider
+3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
+4. Verify the provider is actually available before resetting
 
-### Udbyderen bliver ved med at udløse strømafbryderen
+### Provider keeps tripping the circuit breaker
 
-Hvis en udbyder gentagne gange går i ÅBEN tilstand:
+If a provider repeatedly enters OPEN state:
 
-1. Tjek **Dashboard → Health → Provider Health** for fejlmønsteret
-2. Gå til **Indstillinger → Resiliens → Udbyderprofiler** og øg fejltærsklen
-3. Tjek, om udbyderen har ændret API-grænser eller kræver gengodkendelse
-4. Gennemgå latency-telemetri — høj latenstid kan forårsage timeout-baserede fejl
+1. Check **Dashboard → Health → Provider Health** for the failure pattern
+2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
+3. Check if the provider has changed API limits or requires re-authentication
+4. Review latency telemetry — high latency may cause timeout-based failures
 
 ---
 
-## Problemer med lydtransskription
+## Audio Transcription Issues
 
-### "Ikke-understøttet model" fejl
+### "Unsupported model" error
 
-- Sørg for, at du bruger det korrekte præfiks: `deepgram/nova-3` eller `assemblyai/best`
-- Bekræft, at udbyderen er tilsluttet i **Dashboard → Udbydere**
+- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
+- Verify the provider is connected in **Dashboard → Providers**
 
-### Transskription returnerer tom eller mislykkes
+### Transcription returns empty or fails
 
-- Tjek understøttede lydformater: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
-- Bekræft filstørrelsen er inden for udbyderens grænser (typisk < 25 MB)
-- Tjek gyldigheden af udbyderens API-nøgle på udbyderkortet
+- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Verify file size is within provider limits (typically < 25MB)
+- Check provider API key validity in the provider card
 
 ---
 
-## Oversætter-fejlretning
+## Translator Debugging
 
-Brug **Dashboard → Oversætter** til at fejlfinde problemer med formatoversættelse:
+Use **Dashboard → Translator** to debug format translation issues:
 
-| Tilstand         | Hvornår skal man bruge                                                                                          |
-| ---------------- | --------------------------------------------------------------------------------------------------------------- |
-| **Legeplads**    | Sammenlign input/output-formater side om side — indsæt en mislykket anmodning for at se, hvordan den oversættes |
-| **Chattester**   | Send livebeskeder og inspicer den fulde anmodnings-/svarnyttelast inklusive overskrifter                        |
-| **Testbænk**     | Kør batchtest på tværs af formatkombinationer for at finde ud af, hvilke oversættelser der er brudte            |
-| **Live Monitor** | Se anmodningsflow i realtid for at fange periodiske oversættelsesproblemer                                      |
+| Mode             | When to Use                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| **Playground**   | Compare input/output formats side by side — paste a failing request to see how it translates |
+| **Chat Tester**  | Send live messages and inspect the full request/response payload including headers           |
+| **Test Bench**   | Run batch tests across format combinations to find which translations are broken             |
+| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues                        |
 
-### Almindelige formatproblemer
+### Common format issues
 
-- **Tænke-tags vises ikke** — Tjek, om måludbyderen understøtter tænkning og indstilling af tænkebudget
-- **Værktøjsopkald falder** — Nogle formatoversættelser kan fjerne ikke-understøttede felter; verificere i Playground-tilstand
-- **Systemprompt mangler** — Claude og Gemini håndterer systemprompts forskelligt; kontrollere oversættelsesoutput
-- **SDK returnerer rå streng i stedet for objekt** — Rettet i v1.1.0: Response Sanizer fjerner nu ikke-standardfelter (`x_groq`, `usage_breakdown` osv.), der forårsager OpenAI SDK Pydantic valideringsfejl
-- **GLM/ERNIE afviser `system` rolle** — Rettet i v1.1.0: Rollenormalisering flettes automatisk systemmeddelelser ind i brugermeddelelser for inkompatible modeller
-- **`developer` rolle ikke genkendt** — Rettet i v1.1.0: automatisk konverteret til `system` for ikke-OpenAI-udbydere
-- **`json_schema` virker ikke med Gemini** — Rettet i v1.1.0: `response_format` er nu konverteret til Gemini's `responseMimeType` + `responseSchema`
+- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
+- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
+- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
+- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures
+- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
+- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers
+- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema`
 
 ---
 
-## Resiliensindstillinger
+## Resilience Settings
 
-### Automatisk hastighedsgrænse udløses ikke
+### Auto rate-limit not triggering
 
-- Automatisk hastighedsgrænse gælder kun for API-nøgleudbydere (ikke OAuth/abonnement)
-- Bekræft, at **Indstillinger → Modstandsdygtighed → Udbyderprofiler** har aktiveret automatisk satsgrænse
-- Tjek, om udbyderen returnerer `429` statuskoder eller `Retry-After` overskrifter
+- Auto rate-limit only applies to API key providers (not OAuth/subscription)
+- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
+- Check if the provider returns `429` status codes or `Retry-After` headers
 
-### Tuning eksponentiel backoff
+### Tuning exponential backoff
 
-Udbyderprofiler understøtter disse indstillinger:
+Provider profiles support these settings:
 
-- **Base delay** — Indledende ventetid efter første fejl (standard: 1s)
-- **Maksimal forsinkelse** — Maksimal ventetid (standard: 30s)
-- **Multiplikator** — Hvor meget skal forsinkelsen øges pr. på hinanden følgende fejl (standard: 2x)
+- **Base delay** — Initial wait time after first failure (default: 1s)
+- **Max delay** — Maximum wait time cap (default: 30s)
+- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
 
-### Anti-tordenbesætning
+### Anti-thundering herd
 
-Når mange samtidige anmodninger rammer en hastighedsbegrænset udbyder, bruger OmniRoute mutex + automatisk hastighedsbegrænsning til at serialisere anmodninger og forhindre kaskadefejl. Dette er automatisk for API-nøgleudbydere.
+When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
 
 ---
 
-## Stadig fast?
+## Optional RAG / LLM failure taxonomy (16 problems)
 
-- **GitHub-problemer**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Arkitektur**: Se [link](ARCHITECTURE.md) for interne detaljer
-- **API-reference**: Se [link](API_REFERENCE.md) for alle endepunkter
-- **Health Dashboard**: Tjek **Dashboard → Health** for systemstatus i realtid
-- **Oversætter**: Brug **Dashboard → Oversætter** til at fejlsøge formatproblemer
+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)
+- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
+- **Translator**: Use **Dashboard → Translator** to debug format issues

docs/i18n/da/USER_GUIDE.md

@@ -1,12 +1,16 @@
-# Brugervejledning
-
-🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md)
-
-Komplet guide til konfiguration af udbydere, oprettelse af kombinationer, integration af CLI-værktøjer og implementering af OmniRoute.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/USER_GUIDE.md) · 🇪🇸 [es](../es/USER_GUIDE.md) · 🇫🇷 [fr](../fr/USER_GUIDE.md) · 🇩🇪 [de](../de/USER_GUIDE.md) · 🇮🇹 [it](../it/USER_GUIDE.md) · 🇷🇺 [ru](../ru/USER_GUIDE.md) · 🇨🇳 [zh-CN](../zh-CN/USER_GUIDE.md) · 🇯🇵 [ja](../ja/USER_GUIDE.md) · 🇰🇷 [ko](../ko/USER_GUIDE.md) · 🇸🇦 [ar](../ar/USER_GUIDE.md) · 🇮🇳 [in](../in/USER_GUIDE.md) · 🇹🇭 [th](../th/USER_GUIDE.md) · 🇻🇳 [vi](../vi/USER_GUIDE.md) · 🇮🇩 [id](../id/USER_GUIDE.md) · 🇲🇾 [ms](../ms/USER_GUIDE.md) · 🇳🇱 [nl](../nl/USER_GUIDE.md) · 🇵🇱 [pl](../pl/USER_GUIDE.md) · 🇸🇪 [sv](../sv/USER_GUIDE.md) · 🇳🇴 [no](../no/USER_GUIDE.md) · 🇩🇰 [da](../da/USER_GUIDE.md) · 🇫🇮 [fi](../fi/USER_GUIDE.md) · 🇵🇹 [pt](../pt/USER_GUIDE.md) · 🇷🇴 [ro](../ro/USER_GUIDE.md) · 🇭🇺 [hu](../hu/USER_GUIDE.md) · 🇧🇬 [bg](../bg/USER_GUIDE.md) · 🇸🇰 [sk](../sk/USER_GUIDE.md) · 🇺🇦 [uk-UA](../uk-UA/USER_GUIDE.md) · 🇮🇱 [he](../he/USER_GUIDE.md) · 🇵🇭 [phi](../phi/USER_GUIDE.md)
 
 ---
 
-## Indholdsfortegnelse
+# 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)
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
+
+## Table of Contents
 
 - [Pricing at a Glance](#-pricing-at-a-glance)
 - [Use Cases](#-use-cases)
@@ -18,40 +22,40 @@ Komplet guide til konfiguration af udbydere, oprettelse af kombinationer, integr
 
 ---
 
-## 💰 Prissætning på et øjeblik
+## 💰 Pricing at a Glance
 
-| Tier              | Udbyder           | Omkostninger        | Kvote nulstilling  | Bedst til                  |
-| ----------------- | ----------------- | ------------------- | ------------------ | -------------------------- |
-| **💳 ABONNEMENT** | Claude Code (Pro) | 20 USD/md.          | 5 timer + ugentlig | Allerede abonneret         |
-|                   | Codex (Plus/Pro)  | $20-200/md.         | 5 timer + ugentlig | OpenAI-brugere             |
-|                   | Gemini CLI        | **GRATIS**          | 180K/md + 1K/dag   | Alle sammen!               |
-|                   | GitHub Copilot    | $10-19/md.          | Månedlig           | GitHub-brugere             |
-| **🔑 API NØGLE**  | DeepSeek          | Betal pr. brug      | Ingen              | Billig ræsonnement         |
-|                   | Groq              | Betal pr. brug      | Ingen              | Ultrahurtig slutning       |
-|                   | xAI (Grok)        | Betal pr. brug      | Ingen              | Grok 4 ræsonnement         |
-|                   | Mistral           | Betal pr. brug      | Ingen              | EU-hostede modeller        |
-|                   | Forvirring        | Betal pr. brug      | Ingen              | Søgeforøget                |
-|                   | Sammen AI         | Betal pr. brug      | Ingen              | Open source-modeller       |
-|                   | Fyrværkeri AI     | Betal pr. brug      | Ingen              | Fast FLUX billeder         |
-|                   | Cerebras          | Betal pr. brug      | Ingen              | Wafer-skala hastighed      |
-|                   | Sammenhæng        | Betal pr. brug      | Ingen              | Kommando R+ RAG            |
-|                   | NVIDIA NIM        | Betal pr. brug      | Ingen              | Virksomhedsmodeller        |
-| **💰 BILLIG**     | GLM-4.7           | 0,6 USD/1 mio.      | Dagligt 10:00      | Budget backup              |
-|                   | MiniMax M2.1      | $0,2/1 mio.         | 5-timers rullende  | Billigste mulighed         |
-|                   | Kimi K2           | 9 USD/md. lejlighed | 10M tokens/md.     | Forudsigelige omkostninger |
-| **🆓 GRATIS**     | iFlow             | $0                  | Ubegrænset         | 8 modeller gratis          |
-|                   | Qwen              | $0                  | Ubegrænset         | 3 modeller gratis          |
-|                   | Kiro              | $0                  | Ubegrænset         | Claude gratis              |
+| Tier                | Provider          | Cost        | Quota Reset      | Best For             |
+| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |
+| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo      | 5h + weekly      | Already subscribed   |
+|                     | Codex (Plus/Pro)  | $20-200/mo  | 5h + weekly      | OpenAI users         |
+|                     | Gemini CLI        | **FREE**    | 180K/mo + 1K/day | Everyone!            |
+|                     | GitHub Copilot    | $10-19/mo   | Monthly          | GitHub users         |
+| **🔑 API KEY**      | DeepSeek          | Pay per use | None             | Cheap reasoning      |
+|                     | Groq              | Pay per use | None             | Ultra-fast inference |
+|                     | xAI (Grok)        | Pay per use | None             | Grok 4 reasoning     |
+|                     | Mistral           | Pay per use | None             | EU-hosted models     |
+|                     | Perplexity        | Pay per use | None             | Search-augmented     |
+|                     | Together AI       | Pay per use | None             | Open-source models   |
+|                     | Fireworks AI      | Pay per use | None             | Fast FLUX images     |
+|                     | Cerebras          | Pay per use | None             | Wafer-scale speed    |
+|                     | Cohere            | Pay per use | None             | Command R+ RAG       |
+|                     | NVIDIA NIM        | Pay per use | None             | Enterprise models    |
+| **💰 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        |
+|                     | Qwen              | $0          | Unlimited        | 3 models free        |
+|                     | Kiro              | $0          | Unlimited        | Claude free          |
 
-**💡 Pro-tip:** Start med Gemini CLI (180K gratis/måned) + iFlow (ubegrænset gratis) combo = $0 omkostninger!
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost!
 
 ---
 
 ## 🎯 Use Cases
 
-### Case 1: "Jeg har Claude Pro-abonnement"
+### Case 1: "I have Claude Pro subscription"
 
-**Problem:** Kvoten udløber ubrugt, satsgrænser under tung kodning
+**Problem:** Quota expires unused, rate limits during heavy coding
 
 ```
 Combo: "maximize-claude"
@@ -63,9 +67,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
 vs. $20 + hitting limits = frustration
 ```
 
-### Case 2: "Jeg vil have nul omkostninger"
+### Case 2: "I want zero cost"
 
-**Problem:** Har ikke råd til abonnementer, har brug for pålidelig AI-kodning
+**Problem:** Can't afford subscriptions, need reliable AI coding
 
 ```
 Combo: "free-forever"
@@ -77,9 +81,9 @@ Monthly cost: $0
 Quality: Production-ready models
 ```
 
-### Case 3: "Jeg har brug for 24/7 kodning, ingen afbrydelser"
+### Case 3: "I need 24/7 coding, no interruptions"
 
-**Problem:** Deadlines, har ikke råd til nedetid
+**Problem:** Deadlines, can't afford downtime
 
 ```
 Combo: "always-on"
@@ -93,9 +97,9 @@ Result: 5 layers of fallback = zero downtime
 Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
 ```
 
-### Case 4: "Jeg vil have GRATIS AI i OpenClaw"
+### Case 4: "I want FREE AI in OpenClaw"
 
-**Problem:** Har brug for AI-assistent i beskedapps, helt gratis
+**Problem:** Need AI assistant in messaging apps, completely free
 
 ```
 Combo: "openclaw-free"
@@ -109,9 +113,9 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 
 ---
 
-## 📖 Udbyderopsætning
+## 📖 Provider Setup
 
-### 🔐 Abonnementsudbydere
+### 🔐 Subscription Providers
 
 #### Claude Code (Pro/Max)
 
@@ -126,7 +130,7 @@ Models:
   cc/claude-haiku-4-5-20251001
 ```
 
-**Prof tip:** Brug Opus til komplekse opgaver, Sonnet for hurtighed. OmniRoute sporer kvote pr. model!
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
 
 #### OpenAI Codex (Plus/Pro)
 
@@ -140,7 +144,7 @@ Models:
   cx/gpt-5.1-codex-max
 ```
 
-#### Gemini CLI (GRATIS 180K/måned!)
+#### Gemini CLI (FREE 180K/month!)
 
 ```bash
 Dashboard → Providers → Connect Gemini CLI
@@ -152,7 +156,7 @@ Models:
   gc/gemini-2.5-pro
 ```
 
-**Bedste værdi:** Kæmpe gratis niveau! Brug dette før betalte niveauer.
+**Best Value:** Huge free tier! Use this before paid tiers.
 
 #### GitHub Copilot
 
@@ -167,33 +171,33 @@ Models:
   gh/gemini-3-pro
 ```
 
-### 💰 Billige udbydere
+### 💰 Cheap Providers
 
-#### GLM-4.7 (Daglig nulstilling, $0,6/1 mio.)
+#### GLM-4.7 (Daily reset, $0.6/1M)
 
-1. Tilmeld dig: [Zhipu AI](https://open.bigmodel.cn/)
-2. Hent API-nøgle fra Coding Plan
-3. Dashboard → Tilføj API-nøgle: Udbyder: `glm`, API-nøgle: `your-key`
+1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)
+2. Get API key from Coding Plan
+3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`
 
-**Brug:** `glm/glm-4.7` — **Prof tip:** Kodningsplan tilbyder 3× kvote til 1/7 pris! Nulstil dagligt 10:00.
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
 
-#### MiniMax M2.1 (5 timers nulstilling, $0,20/1 mio.)
+#### MiniMax M2.1 (5h reset, $0.20/1M)
 
-1. Tilmeld dig: [MiniMax](https://www.minimax.io/)
-2. Hent API-nøgle → Dashboard → Tilføj API-nøgle
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
 
-**Brug:** `minimax/MiniMax-M2.1` — **Prof tip:** Billigste mulighed for lang sammenhæng (1M tokens)!
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
 
-#### Kimi K2 ($9/måned lejlighed)
+#### Kimi K2 ($9/month flat)
 
-1. Abonner: [Moonshot AI](https://platform.moonshot.ai/)
-2. Hent API-nøgle → Dashboard → Tilføj API-nøgle
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
 
-**Brug:** `kimi/kimi-latest` — **Prof tip:** Fast $9/måned for 10M tokens = $0,90/1M effektive omkostninger!
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
 
-### 🆓 GRATIS udbydere
+### 🆓 FREE Providers
 
-#### iFlow (8 GRATIS modeller)
+#### iFlow (8 FREE models)
 
 ```bash
 Dashboard → Connect iFlow → OAuth login → Unlimited usage
@@ -201,7 +205,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage
 Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1
 ```
 
-#### Qwen (3 GRATIS modeller)
+#### Qwen (3 FREE models)
 
 ```bash
 Dashboard → Connect Qwen → Device code auth → Unlimited usage
@@ -209,7 +213,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage
 Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
 ```
 
-#### Kiro (Claude GRATIS)
+#### Kiro (Claude FREE)
 
 ```bash
 Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
@@ -219,9 +223,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
 
 ---
 
-## 🎨 Kombinationer
+## 🎨 Combos
 
-### Eksempel 1: Maksimer abonnement → Billig backup
+### Example 1: Maximize Subscription → Cheap Backup
 
 ```
 Dashboard → Combos → Create New
@@ -235,7 +239,7 @@ Models:
 Use in CLI: premium-coding
 ```
 
-### Eksempel 2: Kun gratis (nul omkostninger)
+### Example 2: Free-Only (Zero Cost)
 
 ```
 Name: free-combo
@@ -249,9 +253,9 @@ Cost: $0 forever!
 
 ---
 
-## 🔧 CLI-integration
+## 🔧 CLI Integration
 
-### Markør IDE
+### Cursor IDE
 
 ```
 Settings → Models → Advanced:
@@ -262,7 +266,7 @@ Settings → Models → Advanced:
 
 ### Claude Code
 
-Rediger `~/.claude/config.json`:
+Edit `~/.claude/config.json`:
 
 ```json
 {
@@ -281,7 +285,7 @@ codex "your prompt"
 
 ### OpenClaw
 
-Rediger `~/.openclaw/openclaw.json`:
+Edit `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -303,9 +307,9 @@ Rediger `~/.openclaw/openclaw.json`:
 }
 ```
 
-**Eller brug Dashboard:** CLI Tools → OpenClaw → Auto-config
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
 
-### Cline / Fortsæt / RooCode
+### Cline / Continue / RooCode
 
 ```
 Provider: OpenAI Compatible
@@ -316,9 +320,28 @@ Model: cc/claude-opus-4-6
 
 ---
 
-## 🚀 Implementering
+## 🚀 Deployment
 
-### VPS-implementering
+### 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
 git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -337,6 +360,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,51 +407,54 @@ docker build -t omniroute:cli .
 docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
 ```
 
-For værtsintegreret tilstand med CLI-binære filer, se Docker-sektionen i hoveddokumenterne.
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
 
-### Miljøvariabler
+### Environment Variables
 
-| Variabel              | Standard                             | Beskrivelse                                          |
-| --------------------- | ------------------------------------ | ---------------------------------------------------- |
-| `JWT_SECRET`          | `omniroute-default-secret-change-me` | JWT signeringshemmelighed (**ændring i produktion**) |
-| `INITIAL_PASSWORD`    | `123456`                             | Første login-adgangskode                             |
-| `DATA_DIR`            | `~/.omniroute`                       | Datamappe (db, forbrug, logfiler)                    |
-| `PORT`                | ramme standard                       | Serviceport (`20128` i eksempler)                    |
-| `HOSTNAME`            | ramme standard                       | Bind vært (Docker er som standard `0.0.0.0`)         |
-| `NODE_ENV`            | runtime default                      | Indstil `production` til implementering              |
-| `BASE_URL`            | `http://localhost:20128`             | Intern basis-URL på serversiden                      |
-| `CLOUD_URL`           | `https://omniroute.dev`              | Base URL for slutpunkt for skysynkronisering         |
-| `API_KEY_SECRET`      | `endpoint-proxy-api-key-secret`      | HMAC-hemmelighed for genererede API-nøgler           |
-| `REQUIRE_API_KEY`     | `false`                              | Gennemtving Bearer API-nøgle på `/v1/*`              |
-| `ENABLE_REQUEST_LOGS` | `false`                              | Aktiverer anmodnings-/svarlogs                       |
-| `AUTH_COOKIE_SECURE`  | `false`                              | Tving `Secure` auth-cookie (bag HTTPS omvendt 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/*`                       |
+| `ENABLE_REQUEST_LOGS`     | `false`                              | Enables request/response logs                           |
+| `AUTH_COOKIE_SECURE`      | `false`                              | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `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 den fulde reference til miljøvariablen, se [README](../README.md).
+For the full environment variable reference, see the [README](../README.md).
 
 ---
 
-## 📊 Tilgængelige modeller
+## 📊 Available Models
 
 <details>
-<summary><b>Se alle tilgængelige modeller</b></summary>
+<summary><b>View all available models</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/`)** — GRATIS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
 
 **GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
 
-**GLM (`glm/`)** — 0,6 USD/1 mio.: `glm/glm-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
 
-**MiniMax (`minimax/`)** — $0,2/1 mio.: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
 
-**iFlow (`if/`)** — GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
 
-**Qwen (`qw/`)** — GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
 
-**Kiro (`kr/`)** — GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
 
 **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
 
@@ -401,7 +464,7 @@ For den fulde reference til miljøvariablen, se [README](../README.md).
 
 **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
 
-**Forvirring (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
 
 **Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
 
@@ -409,7 +472,7 @@ For den fulde reference til miljøvariablen, se [README](../README.md).
 
 **Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
 
-**Kohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
+**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
 
 **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
 
@@ -417,11 +480,11 @@ For den fulde reference til miljøvariablen, se [README](../README.md).
 
 ---
 
-## 🧩 Avancerede funktioner
+## 🧩 Advanced Features
 
-### Brugerdefinerede modeller
+### Custom Models
 
-Tilføj ethvert model-id til enhver udbyder uden at vente på en appopdatering:
+Add any model ID to any provider without waiting for an app update:
 
 ```bash
 # Via API
@@ -433,11 +496,11 @@ curl -X POST http://localhost:20128/api/provider-models \
 # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
 ```
 
-Eller brug Dashboard: **Udbydere → [Udbyder] → Brugerdefinerede modeller**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
 
-### Dedikerede udbyderruter
+### Dedicated Provider Routes
 
-Rut anmodninger direkte til en specifik udbyder med modelvalidering:
+Route requests directly to a specific provider with model validation:
 
 ```bash
 POST http://localhost:20128/v1/providers/openai/chat/completions
@@ -445,9 +508,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings
 POST http://localhost:20128/v1/providers/fireworks/images/generations
 ```
 
-Udbyderpræfikset tilføjes automatisk, hvis det mangler. Umatchede modeller returnerer `400`.
+The provider prefix is auto-added if missing. Mismatched models return `400`.
 
-### Konfiguration af netværksproxy
+### Network Proxy Configuration
 
 ```bash
 # Set global proxy
@@ -463,7 +526,7 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \
   -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
 ```
 
-**Forrang:** Nøglespecifik → Kombinationsspecifik → Udbyderspecifik → Global → Miljø.
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
 
 ### Model Catalog API
 
@@ -471,68 +534,68 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \
 curl http://localhost:20128/api/models/catalog
 ```
 
-Returnerer modeller grupperet efter udbyder med typer (`chat`, `embedding`, `image`).
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
 
 ### Cloud Sync
 
-- Synkroniser udbydere, kombinationer og indstillinger på tværs af enheder
-- Automatisk baggrundssynkronisering med timeout + fejl-hurtig
-- Foretrækker server-side `BASE_URL`/`CLOUD_URL` i produktion
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
 
-### LLM Gateway Intelligence (fase 9)
+### LLM Gateway Intelligence (Phase 9)
 
-- **Semantisk cache** — Auto-cacher ikke-streaming, temperatur=0 svar (omgå med `X-OmniRoute-No-Cache: true`)
-- **Anmod om idempotens** — Deduplikerer anmodninger inden for 5 sekunder via `Idempotency-Key` eller `X-Request-Id` header
-- **Progress Tracking** — Tilmeld SSE `event: progress` begivenheder via `X-OmniRoute-Progress: true` header
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
 
 ---
 
-### Oversætter Legeplads
+### Translator Playground
 
-Adgang via **Dashboard → Oversætter**. Fejlfind og visualiser, hvordan OmniRoute oversætter API-anmodninger mellem udbydere.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
 
-| Tilstand         | Formål                                                                                        |
-| ---------------- | --------------------------------------------------------------------------------------------- |
-| **Legeplads**    | Vælg kilde-/målformater, indsæt en anmodning, og se det oversatte output med det samme        |
-| **Chattester**   | Send live chatbeskeder gennem proxyen og inspicer den fulde anmodning/svar-cyklus             |
-| **Testbænk**     | Kør batchtest på tværs af flere formatkombinationer for at bekræfte oversættelsens korrekthed |
-| **Live Monitor** | Se oversættelser i realtid, mens anmodninger strømmer gennem proxyen                          |
+| Mode             | Purpose                                                                                |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground**   | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester**  | Send live chat messages through the proxy and inspect the full request/response cycle  |
+| **Test Bench**   | Run batch tests across multiple format combinations to verify translation correctness  |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy                        |
 
-**Brugstilfælde:**
+**Use cases:**
 
-- Fejlfinding af, hvorfor en specifik klient/udbyder-kombination mislykkes
-- Bekræft, at tankemærker, værktøjsopkald og systembeskeder oversættes korrekt
-- Sammenlign formatforskelle mellem OpenAI, Claude, Gemini og Responses API-formater
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
 
 ---
 
-### Routingstrategier
+### Routing Strategies
 
-Konfigurer via **Dashboard → Indstillinger → Routing**.
+Configure via **Dashboard → Settings → Routing**.
 
-| Strategi                       | Beskrivelse                                                                                                     |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| **Fyld først**                 | Bruger konti i prioriteret rækkefølge — primær konto håndterer alle anmodninger, indtil de ikke er tilgængelige |
-| **Round Robin**                | Går gennem alle konti med en konfigurerbar sticky-grænse (standard: 3 opkald pr. konto)                         |
-| **P2C (Power of Two Choices)** | Vælger 2 tilfældige konti og ruter til den sundere — balancerer belastning med bevidsthed om sundhed            |
-| **Tilfældig**                  | Vælger tilfældigt en konto for hver anmodning ved hjælp af Fisher-Yates shuffle                                 |
-| **Mindst brugt**               | Ruter til kontoen med det ældste `lastUsedAt` tidsstempel, der fordeler trafikken jævnt                         |
-| **Omkostningsoptimeret**       | Ruter til kontoen med den laveste prioritetsværdi, optimerer til udbydere med laveste omkostninger              |
+| Strategy                       | Description                                                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First**                 | Uses accounts in priority order — primary account handles all requests until unavailable         |
+| **Round Robin**                | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account)      |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random**                     | Randomly selects an account for each request using Fisher-Yates shuffle                          |
+| **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       |
 
-#### Wildcard-modelaliaser
+#### Wildcard Model Aliases
 
-Opret jokertegnmønstre for at omdanne modelnavne:
+Create wildcard patterns to remap model names:
 
 ```
 Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-5-20250929
 Pattern: gpt-*               →  Target: gh/gpt-5.1-codex
 ```
 
-Jokertegn understøtter `*` (alle tegn) og `?` (enkelt tegn).
+Wildcards support `*` (any characters) and `?` (single character).
 
-#### Fallback-kæder
+#### Fallback Chains
 
-Definer globale reservekæder, der gælder på tværs af alle anmodninger:
+Define global fallback chains that apply across all requests:
 
 ```
 Chain: production-fallback
@@ -543,46 +606,46 @@ Chain: production-fallback
 
 ---
 
-### Modstandsdygtighed og strømafbrydere
+### Resilience & Circuit Breakers
 
-Konfigurer via **Dashboard → Indstillinger → Resiliens**.
+Configure via **Dashboard → Settings → Resilience**.
 
-OmniRoute implementerer modstandsdygtighed på udbyderniveau med fire komponenter:
+OmniRoute implements provider-level resilience with four components:
 
-1. **Udbyderprofiler** — Konfiguration pr. udbyder for:
-   - Fejltærskel (hvor mange fejl før åbning)
-   - Nedkølingsvarighed
-   - Følsomhed for registrering af hastighedsgrænse
-   - Eksponentielle backoff-parametre
+1. **Provider Profiles** — Per-provider configuration for:
+   - Failure threshold (how many failures before opening)
+   - Cooldown duration
+   - Rate limit detection sensitivity
+   - Exponential backoff parameters
 
-2. **Redigerbare hastighedsgrænser** — Standardindstillinger på systemniveau, der kan konfigureres i dashboardet:
-   - **Requests Per Minute (RPM)** — Maksimale anmodninger pr. minut pr. konto
-   - **Min Time Between Requests** — Minimumsafstand i millisekunder mellem anmodninger
-   - **Maksimal samtidige anmodninger** — Maksimalt antal samtidige anmodninger pr. konto
-   - Klik på **Rediger** for at ændre, og klik derefter på **Gem** eller **Annuller**. Værdier bevarer via resilience API.
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+   - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+   - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+   - **Max Concurrent Requests** — Maximum simultaneous requests per account
+   - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
 
-3. **Circuit Breaker** — Sporer fejl pr. udbyder og åbner automatisk kredsløbet, når en tærskel er nået:
-   - **LUKKET** (Sund) — Anmodninger flyder normalt
-   - **ÅBEN** — Udbyderen er midlertidigt blokeret efter gentagne fejl
-   - **HALF_OPEN** — Tester, om udbyderen er genoprettet
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+   - **CLOSED** (Healthy) — Requests flow normally
+   - **OPEN** — Provider is temporarily blocked after repeated failures
+   - **HALF_OPEN** — Testing if provider has recovered
 
-4. **Politik og låste identifikatorer** — Viser strømafbryderstatus og låste identifikatorer med tvangsoplåsningsfunktion.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
 
-5. **Automatisk registrering af hastighedsgrænse** — Overvåger `429` og `Retry-After` overskrifter for proaktivt at undgå at ramme udbyderens satsgrænser.
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
 
-**Prof tip:** Brug knappen **Nulstil alle** til at rydde alle strømafbrydere og nedkøling, når en udbyder kommer sig efter en fejl.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
 
 ---
 
-### Databaseeksport/import
+### Database Export / Import
 
-Administrer databasesikkerhedskopier i **Dashboard → Indstillinger → System og lager**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
 
-| Handling                     | Beskrivelse                                                                                                                                                   |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Eksporter database**       | Downloader den aktuelle SQLite-database som en `.sqlite`-fil                                                                                                  |
-| **Eksporter alle (.tar.gz)** | Downloader et komplet backup-arkiv inklusive: database, indstillinger, kombinationer, udbyderforbindelser (ingen legitimationsoplysninger), API-nøglemetadata |
-| **Importer database**        | Upload en `.sqlite` fil for at erstatte den aktuelle database. Der oprettes automatisk en pre-import backup                                                   |
+| 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                          |
 
 ```bash
 # API: Export database
@@ -596,38 +659,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \
   -F "file=@backup.sqlite"
 ```
 
-**Importvalidering:** Den importerede fil er valideret for integritet (SQLite pragmatjek), påkrævede tabeller (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) og størrelse (maks. 100 MB).
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
 
-**Brugstilfælde:**
+**Use Cases:**
 
-- Migrer OmniRoute mellem maskiner
-- Opret eksterne sikkerhedskopier til katastrofegendannelse
-- Del konfigurationer mellem teammedlemmer (eksporter alle → del arkiv)
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
 
 ---
 
-### Indstillinger Dashboard
+### Settings Dashboard
 
-Indstillingssiden er organiseret i 5 faner for nem navigation:
+The settings page is organized into 5 tabs for easy navigation:
 
-| Faneblad      | Indhold                                                                                                   |
-| ------------- | --------------------------------------------------------------------------------------------------------- |
-| **Sikkerhed** | Indstillinger for login/adgangskode, IP-adgangskontrol, API-godkendelse for `/models` og udbyderblokering |
-| **Routing**   | Global routingstrategi (6 muligheder), jokertegn-modelaliaser, reservekæder, combo-standarder             |
-| **Resiliens** | Udbyderprofiler, redigerbare hastighedsgrænser, strømafbryderstatus, politikker og låste identifikatorer  |
-| **AI**        | Tænkende budgetkonfiguration, global systemprompt-injektion, prompt-cache-statistik                       |
-| **Avanceret** | Global proxy-konfiguration (HTTP/SOCKS5)                                                                  |
+| Tab            | Contents                                                                                       |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **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 |
+| **AI**         | Thinking budget configuration, global system prompt injection, prompt cache stats              |
+| **Advanced**   | Global proxy configuration (HTTP/SOCKS5)                                                       |
 
 ---
 
-### Omkostninger og budgetstyring
+### Costs & Budget Management
 
-Adgang via **Dashboard → Omkostninger**.
+Access via **Dashboard → Costs**.
 
-| Faneblad   | Formål                                                                                             |
-| ---------- | -------------------------------------------------------------------------------------------------- |
-| **Budget** | Indstil forbrugsgrænser pr. API-nøgle med daglige/ugentlige/månedlige budgetter og realtidssporing |
-| **Priser** | Se og rediger modelprissætninger — pris pr. 1K input/output-tokens pr. udbyder                     |
+| Tab         | Purpose                                                                                  |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget**  | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider       |
 
 ```bash
 # API: Set a budget
@@ -639,13 +702,13 @@ curl -X POST http://localhost:20128/api/usage/budget \
 curl http://localhost:20128/api/usage/budget
 ```
 
-**Omkostningssporing:** Hver anmodning logger tokenbrug og beregner omkostninger ved hjælp af pristabellen. Se opdelinger i **Dashboard → Brug** efter udbyder, model og API-nøgle.
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
 
 ---
 
-### Lydtransskription
+### Audio Transcription
 
-OmniRoute understøtter lydtransskription via det OpenAI-kompatible slutpunkt:
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
 
 ```bash
 POST /v1/audio/transcriptions
@@ -659,40 +722,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
   -F "model=deepgram/nova-3"
 ```
 
-Tilgængelige udbydere: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
 
-Understøttede lydformater: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
 
 ---
 
-### Kombinationsbalanceringsstrategier
+### Combo Balancing Strategies
 
-Konfigurer balancering pr. kombination i **Dashboard → Combos → Opret/Rediger → Strategi**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
 
-| Strategi                 | Beskrivelse                                                                   |
-| ------------------------ | ----------------------------------------------------------------------------- |
-| **Round-Robin**          | Roterer sekventielt gennem modeller                                           |
-| **Prioritet**            | Prøver altid den første model; falder kun tilbage på fejl                     |
-| **Tilfældig**            | Vælger en tilfældig model fra kombinationen for hver anmodning                |
-| **Vægtet**               | Ruter proportionalt baseret på tildelte vægte pr. model                       |
-| **Mindst brugt**         | Ruter til modellen med de færreste seneste anmodninger (bruger combo-metrics) |
-| **Omkostningsoptimeret** | Ruter til den billigste tilgængelige model (bruger pristabel)                 |
+| Strategy           | Description                                                              |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin**    | Rotates through models sequentially                                      |
+| **Priority**       | Always tries the first model; falls back only on error                   |
+| **Random**         | Picks a random model from the combo for each request                     |
+| **Weighted**       | Routes proportionally based on assigned weights per model                |
+| **Least-Used**     | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table)              |
 
-Globale kombinationsstandarder kan indstilles i **Dashboard → Indstillinger → Routing → Combo-standarder**.
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
 
 ---
 
-### Sundhedsdashboard
+### Health Dashboard
 
-Adgang via **Dashboard → Health**. Oversigt over systemets tilstand i realtid med 6 kort:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
 
-| Kort                  | Hvad det viser                                            |
-| --------------------- | --------------------------------------------------------- |
-| **Systemstatus**      | Oppetid, version, hukommelsesforbrug, datakatalog         |
-| **Udbydersundhed**    | Per-leverandør afbrydertilstand (Lukket/Åben/Halv-Åben)   |
-| **Satsgrænser**       | Aktive nedkølingsgrænser pr. konto med resterende tid     |
-| **Aktive lockouts**   | Udbydere midlertidigt blokeret af lockout-politikken      |
-| **Signatur Cache**    | Deduplikeringscache-statistikker (aktive nøgler, hitrate) |
-| **Latency Telemetri** | p50/p95/p99 latenssammenlægning pr. udbyder               |
+| Card                  | What It Shows                                               |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status**     | Uptime, version, memory usage, data directory               |
+| **Provider Health**   | Per-provider circuit breaker state (Closed/Open/Half-Open)  |
+| **Rate Limits**       | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts**   | Providers temporarily blocked by the lockout policy         |
+| **Signature Cache**   | Deduplication cache stats (active keys, hit rate)           |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider                |
 
-**Prof tip:** Sundhedssiden opdateres automatisk hvert 10. sekund. Brug afbryderkortet til at identificere, hvilke udbydere der oplever problemer.
+**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/i18n/da/VM_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,403 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/VM_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../es/VM_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../fr/VM_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../de/VM_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../it/VM_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../ru/VM_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../zh-CN/VM_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../ja/VM_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../ko/VM_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../ar/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [in](../in/VM_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../th/VM_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../vi/VM_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../id/VM_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../ms/VM_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../nl/VM_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../pl/VM_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../sv/VM_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../no/VM_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../da/VM_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../fi/VM_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../pt/VM_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../ro/VM_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../hu/VM_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../bg/VM_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../sk/VM_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../uk-UA/VM_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../he/VM_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../phi/VM_DEPLOYMENT_GUIDE.md)
+
+---
+
+# OmniRoute — Guia de Deploy em VM com Cloudflare
+
+Guia completo para instalar e configurar o OmniRoute em uma VM (VPS) com domínio gerenciado via Cloudflare.
+
+---
+
+## Pré-Requisitos
+
+| 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+       |
+
+**Providers testados**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail.
+
+---
+
+## 1. Configurar a VM
+
+### 1.1 Criar a instância
+
+No seu provider de VPS preferido:
+
+- 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`)
+
+### 1.2 Conectar via SSH
+
+```bash
+ssh root@203.0.113.10
+```
+
+### 1.3 Atualizar o sistema
+
+```bash
+apt update && apt upgrade -y
+```
+
+### 1.4 Instalar Docker
+
+```bash
+# Instalar dependências
+apt install -y ca-certificates curl gnupg
+
+# Adicionar repositório oficial do Docker
+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
+apt update
+apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
+```
+
+### 1.5 Instalar nginx
+
+```bash
+apt install -y nginx
+```
+
+### 1.6 Configurar Firewall (UFW)
+
+```bash
+ufw default deny incoming
+ufw default allow outgoing
+ufw allow 22/tcp    # SSH
+ufw allow 80/tcp    # HTTP (redirect)
+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).
+
+---
+
+## 2. Instalar o OmniRoute
+
+### 2.1 Criar diretório de configuração
+
+```bash
+mkdir -p /opt/omniroute
+```
+
+### 2.2 Criar arquivo de variáveis de ambiente
+
+```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
+STORAGE_ENCRYPTION_KEY_VERSION=v1
+MACHINE_ID_SALT=ALTERE-PARA-SALT-UNICO
+
+# === App ===
+PORT=20128
+NODE_ENV=production
+HOSTNAME=0.0.0.0
+DATA_DIR=/app/data
+STORAGE_DRIVER=sqlite
+ENABLE_REQUEST_LOGS=true
+AUTH_COOKIE_SECURE=false
+REQUIRE_API_KEY=false
+
+# === Domain (altere para seu domínio) ===
+BASE_URL=https://llms.seudominio.com
+NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
+
+# === Cloud Sync (opcional) ===
+# 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.
+
+### 2.3 Iniciar o container
+
+```bash
+docker pull diegosouzapw/omniroute:latest
+
+docker run -d \
+  --name omniroute \
+  --restart unless-stopped \
+  --env-file /opt/omniroute/.env \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+### 2.4 Verificar se está rodando
+
+```bash
+docker ps | grep omniroute
+docker logs omniroute --tail 20
+```
+
+Deve exibir: `[DB] SQLite database ready` e `listening on port 20128`.
+
+---
+
+## 3. Configurar nginx (Reverse Proxy)
+
+### 3.1 Gerar certificado SSL (Cloudflare Origin)
+
+No painel da Cloudflare:
+
+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**
+
+```bash
+mkdir -p /etc/nginx/ssl
+
+# Colar o certificado
+nano /etc/nginx/ssl/origin.crt
+
+# Colar a chave privada
+nano /etc/nginx/ssl/origin.key
+
+chmod 600 /etc/nginx/ssl/origin.key
+```
+
+### 3.2 Configuração do nginx
+
+```bash
+cat > /etc/nginx/sites-available/omniroute << 'NGINX'
+# Default server — bloqueia acesso direto por IP
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    listen 443 ssl default_server;
+    listen [::]:443 ssl default_server;
+    ssl_certificate     /etc/nginx/ssl/origin.crt;
+    ssl_certificate_key /etc/nginx/ssl/origin.key;
+    server_name _;
+    return 444;
+}
+
+# OmniRoute — HTTPS
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    server_name llms.seudominio.com;  # Altere para seu domínio
+
+    ssl_certificate     /etc/nginx/ssl/origin.crt;
+    ssl_certificate_key /etc/nginx/ssl/origin.key;
+    ssl_protocols TLSv1.2 TLSv1.3;
+
+    client_max_body_size 100M;
+
+    location / {
+        proxy_pass http://127.0.0.1:20128;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket support
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_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;
+    }
+}
+
+# HTTP → HTTPS redirect
+server {
+    listen 80;
+    listen [::]:80;
+    server_name llms.seudominio.com;
+    return 301 https://$server_name$request_uri;
+}
+NGINX
+```
+
+### 3.3 Ativar e testar
+
+```bash
+# Remover config padrão
+rm -f /etc/nginx/sites-enabled/default
+
+# Ativar OmniRoute
+ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute
+
+# Testar e recarregar
+nginx -t && systemctl reload nginx
+```
+
+---
+
+## 4. Configurar Cloudflare DNS
+
+### 4.1 Adicionar registro DNS
+
+No painel da Cloudflare → DNS:
+
+| Type | Name   | Content                   | Proxy      |
+| ---- | ------ | ------------------------- | ---------- |
+| A    | `llms` | `203.0.113.10` (IP da VM) | ✅ Proxied |
+
+### 4.2 Configurar SSL
+
+Em **SSL/TLS → Overview**:
+
+- Modo: **Full (Strict)**
+
+Em **SSL/TLS → Edge Certificates**:
+
+- Always Use HTTPS: ✅ On
+- Minimum TLS Version: TLS 1.2
+- Automatic HTTPS Rewrites: ✅ On
+
+### 4.3 Testar
+
+```bash
+curl -sI https://llms.seudominio.com/health
+# Deve retornar HTTP/2 200
+```
+
+---
+
+## 5. Operações e Manutenção
+
+### Atualizar para nova versão
+
+```bash
+docker pull diegosouzapw/omniroute:latest
+docker stop omniroute && docker rm omniroute
+docker run -d --name omniroute --restart unless-stopped \
+  --env-file /opt/omniroute/.env \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+### Ver logs
+
+```bash
+docker logs -f omniroute          # Stream em tempo real
+docker logs omniroute --tail 50   # Últimas 50 linhas
+```
+
+### Backup manual do banco
+
+```bash
+# Copiar dados do volume para o host
+docker cp omniroute:/app/data ./backup-$(date +%F)
+
+# Ou comprimir todo o 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
+
+```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 /"
+docker start omniroute
+```
+
+---
+
+## 6. Segurança Avançada
+
+### Restringir nginx para Cloudflare IPs
+
+```bash
+cat > /etc/nginx/cloudflare-ips.conf << 'CF'
+# Cloudflare IPv4 ranges — atualizar periodicamente
+# https://www.cloudflare.com/ips-v4/
+set_real_ip_from 173.245.48.0/20;
+set_real_ip_from 103.21.244.0/22;
+set_real_ip_from 103.22.200.0/22;
+set_real_ip_from 103.31.4.0/22;
+set_real_ip_from 141.101.64.0/18;
+set_real_ip_from 108.162.192.0/18;
+set_real_ip_from 190.93.240.0/20;
+set_real_ip_from 188.114.96.0/20;
+set_real_ip_from 197.234.240.0/22;
+set_real_ip_from 198.41.128.0/17;
+set_real_ip_from 162.158.0.0/15;
+set_real_ip_from 104.16.0.0/13;
+set_real_ip_from 104.24.0.0/14;
+set_real_ip_from 172.64.0.0/13;
+set_real_ip_from 131.0.72.0/22;
+real_ip_header CF-Connecting-IP;
+CF
+```
+
+Adicionar no `nginx.conf` dentro do bloco `http {}`:
+
+```nginx
+include /etc/nginx/cloudflare-ips.conf;
+```
+
+### Install fail2ban
+
+```bash
+apt install -y fail2ban
+systemctl enable fail2ban
+systemctl start fail2ban
+
+# Verificar status
+fail2ban-client status sshd
+```
+
+### Bloquear acesso direto na porta do Docker
+
+```bash
+# Impedir acesso externo direto à porta 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
+apt install -y iptables-persistent
+netfilter-persistent save
+```
+
+---
+
+## 7. Deploy do Cloud Worker (Opcional)
+
+Para acesso remoto via Cloudflare Workers (sem expor a VM diretamente):
+
+```bash
+# No repositório local
+cd omnirouteCloud
+npm install
+npx wrangler login
+npx wrangler deploy
+```
+
+Ver documentação completa em [omnirouteCloud/README.md](../omnirouteCloud/README.md).
+
+---
+
+## Resumo de Portas
+
+| 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) |

docs/i18n/de/A2A-SERVER.md

@@ -0,0 +1,200 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/A2A-SERVER.md) · 🇪🇸 [es](../es/A2A-SERVER.md) · 🇫🇷 [fr](../fr/A2A-SERVER.md) · 🇩🇪 [de](../de/A2A-SERVER.md) · 🇮🇹 [it](../it/A2A-SERVER.md) · 🇷🇺 [ru](../ru/A2A-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/A2A-SERVER.md) · 🇯🇵 [ja](../ja/A2A-SERVER.md) · 🇰🇷 [ko](../ko/A2A-SERVER.md) · 🇸🇦 [ar](../ar/A2A-SERVER.md) · 🇮🇳 [in](../in/A2A-SERVER.md) · 🇹🇭 [th](../th/A2A-SERVER.md) · 🇻🇳 [vi](../vi/A2A-SERVER.md) · 🇮🇩 [id](../id/A2A-SERVER.md) · 🇲🇾 [ms](../ms/A2A-SERVER.md) · 🇳🇱 [nl](../nl/A2A-SERVER.md) · 🇵🇱 [pl](../pl/A2A-SERVER.md) · 🇸🇪 [sv](../sv/A2A-SERVER.md) · 🇳🇴 [no](../no/A2A-SERVER.md) · 🇩🇰 [da](../da/A2A-SERVER.md) · 🇫🇮 [fi](../fi/A2A-SERVER.md) · 🇵🇹 [pt](../pt/A2A-SERVER.md) · 🇷🇴 [ro](../ro/A2A-SERVER.md) · 🇭🇺 [hu](../hu/A2A-SERVER.md) · 🇧🇬 [bg](../bg/A2A-SERVER.md) · 🇸🇰 [sk](../sk/A2A-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/A2A-SERVER.md) · 🇮🇱 [he](../he/A2A-SERVER.md) · 🇵🇭 [phi](../phi/A2A-SERVER.md)
+
+---
+
+# 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/i18n/de/API_REFERENCE.md

@@ -1,12 +1,16 @@
-# API-Referenz
-
-🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md)
-
-Vollständige Referenz für alle OmniRoute-API-Endpunkte.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/API_REFERENCE.md) · 🇪🇸 [es](../es/API_REFERENCE.md) · 🇫🇷 [fr](../fr/API_REFERENCE.md) · 🇩🇪 [de](../de/API_REFERENCE.md) · 🇮🇹 [it](../it/API_REFERENCE.md) · 🇷🇺 [ru](../ru/API_REFERENCE.md) · 🇨🇳 [zh-CN](../zh-CN/API_REFERENCE.md) · 🇯🇵 [ja](../ja/API_REFERENCE.md) · 🇰🇷 [ko](../ko/API_REFERENCE.md) · 🇸🇦 [ar](../ar/API_REFERENCE.md) · 🇮🇳 [in](../in/API_REFERENCE.md) · 🇹🇭 [th](../th/API_REFERENCE.md) · 🇻🇳 [vi](../vi/API_REFERENCE.md) · 🇮🇩 [id](../id/API_REFERENCE.md) · 🇲🇾 [ms](../ms/API_REFERENCE.md) · 🇳🇱 [nl](../nl/API_REFERENCE.md) · 🇵🇱 [pl](../pl/API_REFERENCE.md) · 🇸🇪 [sv](../sv/API_REFERENCE.md) · 🇳🇴 [no](../no/API_REFERENCE.md) · 🇩🇰 [da](../da/API_REFERENCE.md) · 🇫🇮 [fi](../fi/API_REFERENCE.md) · 🇵🇹 [pt](../pt/API_REFERENCE.md) · 🇷🇴 [ro](../ro/API_REFERENCE.md) · 🇭🇺 [hu](../hu/API_REFERENCE.md) · 🇧🇬 [bg](../bg/API_REFERENCE.md) · 🇸🇰 [sk](../sk/API_REFERENCE.md) · 🇺🇦 [uk-UA](../uk-UA/API_REFERENCE.md) · 🇮🇱 [he](../he/API_REFERENCE.md) · 🇵🇭 [phi](../phi/API_REFERENCE.md)
 
 ---
 
-## Inhaltsverzeichnis
+# 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)
+
+Complete reference for all OmniRoute API endpoints.
+
+---
+
+## Table of Contents
 
 - [Chat Completions](#chat-completions)
 - [Embeddings](#embeddings)
@@ -20,7 +24,7 @@ Vollständige Referenz für alle OmniRoute-API-Endpunkte.
 
 ---
 
-## Chat-Abschlüsse
+## Chat Completions
 
 ```bash
 POST /v1/chat/completions
@@ -36,21 +40,21 @@ Content-Type: application/json
 }
 ```
 
-### Benutzerdefinierte Header
+### Custom Headers
 
-| Kopfzeile                | Richtung | Beschreibung                                 |
-| ------------------------ | -------- | -------------------------------------------- |
-| `X-OmniRoute-No-Cache`   | Anfrage  | Auf `true` setzen, um den Cache zu umgehen   |
-| `X-OmniRoute-Progress`   | Anfrage  | Für Fortschrittsereignisse auf `true` setzen |
-| `Idempotency-Key`        | Anfrage  | Dedup-Schlüssel (5-Sekunden-Fenster)         |
-| `X-Request-Id`           | Anfrage  | Alternativer Deduplizierungsschlüssel        |
-| `X-OmniRoute-Cache`      | Antwort  | `HIT` oder `MISS` (kein Streaming)           |
-| `X-OmniRoute-Idempotent` | Antwort  | `true` wenn dedupliziert                     |
-| `X-OmniRoute-Progress`   | Antwort  | `enabled` wenn Fortschrittsverfolgung auf    |
+| 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 |
 
 ---
 
-## Einbettungen
+## Embeddings
 
 ```bash
 POST /v1/embeddings
@@ -63,7 +67,7 @@ Content-Type: application/json
 }
 ```
 
-Verfügbare Anbieter: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
 
 ```bash
 # List all embedding models
@@ -72,7 +76,7 @@ GET /v1/embeddings
 
 ---
 
-## Bildgenerierung
+## Image Generation
 
 ```bash
 POST /v1/images/generations
@@ -86,7 +90,7 @@ Content-Type: application/json
 }
 ```
 
-Verfügbare Anbieter: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
 
 ```bash
 # List all image models
@@ -95,7 +99,7 @@ GET /v1/images/generations
 
 ---
 
-## Modelle auflisten
+## List Models
 
 ```bash
 GET /v1/models
@@ -106,22 +110,22 @@ Authorization: Bearer your-api-key
 
 ---
 
-## Kompatibilitätsendpunkte
+## Compatibility Endpoints
 
-| Methode | Pfad                        | Formatieren                 |
-| ------- | --------------------------- | --------------------------- |
-| POST    | `/v1/chat/completions`      | OpenAI                      |
-| POST    | `/v1/messages`              | Anthropisch                 |
-| POST    | `/v1/responses`             | OpenAI-Antworten            |
-| POST    | `/v1/embeddings`            | OpenAI                      |
-| POST    | `/v1/images/generations`    | OpenAI                      |
-| GET     | `/v1/models`                | OpenAI                      |
-| POST    | `/v1/messages/count_tokens` | Anthropisch                 |
-| GET     | `/v1beta/models`            | Zwillinge                   |
-| POST    | `/v1beta/models/{...path}`  | Zwillinge generierenContent |
-| POST    | `/v1/api/chat`              | Ollama                      |
+| Method | Path                        | Format                 |
+| ------ | --------------------------- | ---------------------- |
+| POST   | `/v1/chat/completions`      | OpenAI                 |
+| POST   | `/v1/messages`              | Anthropic              |
+| POST   | `/v1/responses`             | OpenAI Responses       |
+| POST   | `/v1/embeddings`            | OpenAI                 |
+| POST   | `/v1/images/generations`    | OpenAI                 |
+| GET    | `/v1/models`                | OpenAI                 |
+| POST   | `/v1/messages/count_tokens` | Anthropic              |
+| GET    | `/v1beta/models`            | Gemini                 |
+| POST   | `/v1beta/models/{...path}`  | Gemini generateContent |
+| POST   | `/v1/api/chat`              | Ollama                 |
 
-### Dedizierte Anbieterrouten
+### Dedicated Provider Routes
 
 ```bash
 POST /v1/providers/{provider}/chat/completions
@@ -129,11 +133,11 @@ POST /v1/providers/{provider}/embeddings
 POST /v1/providers/{provider}/images/generations
 ```
 
-Das Anbieterpräfix wird automatisch hinzugefügt, wenn es fehlt. Nicht übereinstimmende Modelle geben `400` zurück.
+The provider prefix is auto-added if missing. Mismatched models return `400`.
 
 ---
 
-## Semantischer Cache
+## Semantic Cache
 
 ```bash
 # Get cache stats
@@ -143,7 +147,7 @@ GET /api/cache
 DELETE /api/cache
 ```
 
-Antwortbeispiel:
+Response example:
 
 ```json
 {
@@ -162,154 +166,164 @@ Antwortbeispiel:
 
 ---
 
-## Dashboard und Verwaltung
+## Dashboard & Management
 
-### Authentifizierung
+### Authentication
 
-| Endpunkt                      | Methode | Beschreibung                      |
-| ----------------------------- | ------- | --------------------------------- |
-| `/api/auth/login`             | POST    | Anmelden                          |
-| `/api/auth/logout`            | POST    | Abmelden                          |
-| `/api/settings/require-login` | GET/PUT | Anmeldung erforderlich umschalten |
+| Endpoint                      | Method  | Description           |
+| ----------------------------- | ------- | --------------------- |
+| `/api/auth/login`             | POST    | Login                 |
+| `/api/auth/logout`            | POST    | Logout                |
+| `/api/settings/require-login` | GET/PUT | Toggle login required |
 
-### Anbieterverwaltung
+### Provider Management
 
-| Endpunkt                     | Methode         | Beschreibung                     |
-| ---------------------------- | --------------- | -------------------------------- |
-| `/api/providers`             | GET/POST        | Anbieter auflisten/anlegen       |
-| `/api/providers/[id]`        | GET/PUT/DELETE  | Einen Anbieter verwalten         |
-| `/api/providers/[id]/test`   | POST            | Provider-Verbindung testen       |
-| `/api/providers/[id]/models` | GET             | Anbietermodelle auflisten        |
-| `/api/providers/validate`    | POST            | Anbieterkonfiguration validieren |
-| `/api/provider-nodes*`       | Verschiedene    | Provider-Knotenverwaltung        |
-| `/api/provider-models`       | GET/POST/DELETE | Kundenspezifische Modelle        |
+| 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            |
 
-### OAuth-Flows
+### OAuth Flows
 
-| Endpunkt                         | Methode      | Beschreibung               |
-| -------------------------------- | ------------ | -------------------------- |
-| `/api/oauth/[provider]/[action]` | Verschiedene | Anbieterspezifisches OAuth |
+| Endpoint                         | Method  | Description             |
+| -------------------------------- | ------- | ----------------------- |
+| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth |
 
-### Routing & Konfig
+### Routing & Config
 
-| Endpunkt              | Methode      | Beschreibung                     |
-| --------------------- | ------------ | -------------------------------- |
-| `/api/models/alias`   | GET/POST     | Modell-Aliase                    |
-| `/api/models/catalog` | GET          | Alle Modelle nach Anbieter + Typ |
-| `/api/combos*`        | Verschiedene | Combo-Management                 |
-| `/api/keys*`          | Verschiedene | API-Schlüsselverwaltung          |
-| `/api/pricing`        | GET          | Modellpreise                     |
+| Endpoint              | Method   | Description                   |
+| --------------------- | -------- | ----------------------------- |
+| `/api/models/alias`   | GET/POST | Model aliases                 |
+| `/api/models/catalog` | GET      | All models by provider + type |
+| `/api/combos*`        | Various  | Combo management              |
+| `/api/keys*`          | Various  | API key management            |
+| `/api/pricing`        | GET      | Model pricing                 |
 
-### Nutzung und Analyse
+### Usage & Analytics
 
-| Endpunkt                    | Methode | Beschreibung                     |
-| --------------------------- | ------- | -------------------------------- |
-| `/api/usage/history`        | GET     | Nutzungshistorie                 |
-| `/api/usage/logs`           | GET     | Nutzungsprotokolle               |
-| `/api/usage/request-logs`   | GET     | Protokolle auf Anforderungsebene |
-| `/api/usage/[connectionId]` | GET     | Nutzung pro Verbindung           |
+| Endpoint                    | Method | Description          |
+| --------------------------- | ------ | -------------------- |
+| `/api/usage/history`        | GET    | Usage history        |
+| `/api/usage/logs`           | GET    | Usage logs           |
+| `/api/usage/request-logs`   | GET    | Request-level logs   |
+| `/api/usage/[connectionId]` | GET    | Per-connection usage |
 
-### Einstellungen
+### Settings
 
-| Endpunkt                        | Methode | Beschreibung                     |
-| ------------------------------- | ------- | -------------------------------- |
-| `/api/settings`                 | GET/PUT | Allgemeine Einstellungen         |
-| `/api/settings/proxy`           | GET/PUT | Netzwerk-Proxy-Konfiguration     |
-| `/api/settings/proxy/test`      | POST    | Proxy-Verbindung testen          |
-| `/api/settings/ip-filter`       | GET/PUT | IP-Zulassungs-/Blockierungsliste |
-| `/api/settings/thinking-budget` | GET/PUT | Begründung des Token-Budgets     |
-| `/api/settings/system-prompt`   | GET/PUT | Globale Systemaufforderung       |
+| 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   |
 
-### Überwachung
+### Monitoring
 
-| Endpunkt                 | Methode          | Beschreibung                |
-| ------------------------ | ---------------- | --------------------------- |
-| `/api/sessions`          | GET              | Aktive Sitzungsverfolgung   |
-| `/api/rate-limits`       | GET              | Tariflimits pro Konto       |
-| `/api/monitoring/health` | GET              | Gesundheitscheck            |
-| `/api/cache`             | ERHALTEN/LÖSCHEN | Cache-Statistiken / löschen |
+| 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     |
 
-### Sichern und Exportieren/Importieren
+### Backup & Export/Import
 
-| Endpunkt                    | Methode | Beschreibung                                                   |
-| --------------------------- | ------- | -------------------------------------------------------------- |
-| `/api/db-backups`           | GET     | Verfügbare Backups auflisten                                   |
-| `/api/db-backups`           | PUT     | Erstellen Sie ein manuelles Backup                             |
-| `/api/db-backups`           | POST    | Von einem bestimmten Backup wiederherstellen                   |
-| `/api/db-backups/export`    | GET     | Datenbank als .sqlite-Datei herunterladen                      |
-| `/api/db-backups/import`    | POST    | Laden Sie die .sqlite-Datei hoch, um die Datenbank zu ersetzen |
-| `/api/db-backups/exportAll` | GET     | Vollständiges Backup als .tar.gz-Archiv herunterladen          |
+| Endpoint                    | Method | Description                             |
+| --------------------------- | ------ | --------------------------------------- |
+| `/api/db-backups`           | GET    | List available backups                  |
+| `/api/db-backups`           | PUT    | Create a manual backup                  |
+| `/api/db-backups`           | POST   | Restore from a specific backup          |
+| `/api/db-backups/export`    | GET    | Download database as .sqlite file       |
+| `/api/db-backups/import`    | POST   | Upload .sqlite file to replace database |
+| `/api/db-backups/exportAll` | GET    | Download full backup as .tar.gz archive |
 
-### Cloud-Synchronisierung
+### Cloud Sync
 
-| Endpunkt               | Methode      | Beschreibung                    |
-| ---------------------- | ------------ | ------------------------------- |
-| `/api/sync/cloud`      | Verschiedene | Cloud-Synchronisierungsvorgänge |
-| `/api/sync/initialize` | POST         | Synchronisierung initialisieren |
-| `/api/cloud/*`         | Verschiedene | Cloud-Management                |
+| Endpoint               | Method  | Description           |
+| ---------------------- | ------- | --------------------- |
+| `/api/sync/cloud`      | Various | Cloud sync operations |
+| `/api/sync/initialize` | POST    | Initialize sync       |
+| `/api/cloud/*`         | Various | Cloud management      |
 
-### CLI-Tools
+### CLI Tools
 
-| Endpunkt                           | Methode | Beschreibung            |
-| ---------------------------------- | ------- | ----------------------- |
-| `/api/cli-tools/claude-settings`   | GET     | Claude CLI-Status       |
-| `/api/cli-tools/codex-settings`    | GET     | Codex-CLI-Status        |
-| `/api/cli-tools/droid-settings`    | GET     | Droid-CLI-Status        |
-| `/api/cli-tools/openclaw-settings` | GET     | OpenClaw CLI-Status     |
-| `/api/cli-tools/runtime/[toolId]`  | GET     | Generische CLI-Laufzeit |
+| Endpoint                           | Method | Description         |
+| ---------------------------------- | ------ | ------------------- |
+| `/api/cli-tools/claude-settings`   | GET    | Claude CLI status   |
+| `/api/cli-tools/codex-settings`    | GET    | Codex CLI status    |
+| `/api/cli-tools/droid-settings`    | GET    | Droid CLI status    |
+| `/api/cli-tools/openclaw-settings` | GET    | OpenClaw CLI status |
+| `/api/cli-tools/runtime/[toolId]`  | GET    | Generic CLI runtime |
 
-Zu den CLI-Antworten gehören: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
+CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
 
-### Belastbarkeit und Ratenbeschränkungen
+### ACP Agents
 
-| Endpunkt                | Methode | Beschreibung                           |
-| ----------------------- | ------- | -------------------------------------- |
-| `/api/resilience`       | GET/PUT | Resilienzprofile abrufen/aktualisieren |
-| `/api/resilience/reset` | POST    | Leistungsschalter zurücksetzen         |
-| `/api/rate-limits`      | GET     | Status der Ratenbegrenzung pro Konto   |
-| `/api/rate-limit`       | GET     | Konfiguration des globalen Ratenlimits |
+| 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                |
 
-### Bewertungen
+GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom).
 
-| Endpunkt     | Methode  | Beschreibung                                         |
-| ------------ | -------- | ---------------------------------------------------- |
-| `/api/evals` | GET/POST | Evaluierungssuiten auflisten / Evaluierung ausführen |
+### Resilience & Rate Limits
 
-### Richtlinien
+| 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 |
 
-| Endpunkt        | Methode         | Beschreibung                  |
-| --------------- | --------------- | ----------------------------- |
-| `/api/policies` | GET/POST/DELETE | Routing-Richtlinien verwalten |
+### Evals
+
+| Endpoint     | Method   | Description                       |
+| ------------ | -------- | --------------------------------- |
+| `/api/evals` | GET/POST | List eval suites / run evaluation |
+
+### Policies
+
+| Endpoint        | Method          | Description             |
+| --------------- | --------------- | ----------------------- |
+| `/api/policies` | GET/POST/DELETE | Manage routing policies |
 
 ### Compliance
 
-| Endpunkt                    | Methode | Beschreibung                           |
-| --------------------------- | ------- | -------------------------------------- |
-| `/api/compliance/audit-log` | GET     | Compliance-Audit-Protokoll (letztes N) |
+| Endpoint                    | Method | Description                   |
+| --------------------------- | ------ | ----------------------------- |
+| `/api/compliance/audit-log` | GET    | Compliance audit log (last N) |
 
-### v1beta (Gemini-kompatibel)
+### v1beta (Gemini-Compatible)
 
-| Endpunkt                   | Methode | Beschreibung                       |
-| -------------------------- | ------- | ---------------------------------- |
-| `/v1beta/models`           | GET     | Modelle im Gemini-Format auflisten |
-| `/v1beta/models/{...path}` | POST    | Gemini `generateContent` Endpunkt  |
+| Endpoint                   | Method | Description                       |
+| -------------------------- | ------ | --------------------------------- |
+| `/v1beta/models`           | GET    | List models in Gemini format      |
+| `/v1beta/models/{...path}` | POST   | Gemini `generateContent` endpoint |
 
-Diese Endpunkte spiegeln das API-Format von Gemini für Kunden wider, die native Gemini SDK-Kompatibilität erwarten.
+These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility.
 
-### Interne/System-APIs
+### Internal / System APIs
 
-| Endpunkt        | Methode | Beschreibung                                                                 |
-| --------------- | ------- | ---------------------------------------------------------------------------- |
-| `/api/init`     | GET     | Überprüfung der Anwendungsinitialisierung (wird beim ersten Start verwendet) |
-| `/api/tags`     | GET     | Ollama-kompatible Modell-Tags (für Ollama-Clients)                           |
-| `/api/restart`  | POST    | Ordentlichen Serverneustart auslösen                                         |
-| `/api/shutdown` | POST    | Ordentliches Herunterfahren des Servers auslösen                             |
+| Endpoint        | Method | Description                                          |
+| --------------- | ------ | ---------------------------------------------------- |
+| `/api/init`     | GET    | Application initialization check (used on first run) |
+| `/api/tags`     | GET    | Ollama-compatible model tags (for Ollama clients)    |
+| `/api/restart`  | POST   | Trigger graceful server restart                      |
+| `/api/shutdown` | POST   | Trigger graceful server shutdown                     |
 
-> **Hinweis:** Diese Endpunkte werden intern vom System oder für die Ollama-Client-Kompatibilität verwendet. Sie werden normalerweise nicht von Endbenutzern aufgerufen.
+> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users.
 
 ---
 
-## Audiotranskription
+## Audio Transcription
 
 ```bash
 POST /v1/audio/transcriptions
@@ -317,9 +331,9 @@ Authorization: Bearer your-api-key
 Content-Type: multipart/form-data
 ```
 
-Transkribieren Sie Audiodateien mit Deepgram oder AssemblyAI.
+Transcribe audio files using Deepgram or AssemblyAI.
 
-**Anfrage:**
+**Request:**
 
 ```bash
 curl -X POST http://localhost:20128/v1/audio/transcriptions \
@@ -328,7 +342,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
   -F "model=deepgram/nova-3"
 ```
 
-**Antwort:**
+**Response:**
 
 ```json
 {
@@ -339,15 +353,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
 }
 ```
 
-**Unterstützte Anbieter:** `deepgram/nova-3`, `assemblyai/best`.
+**Supported providers:** `deepgram/nova-3`, `assemblyai/best`.
 
-**Unterstützte Formate:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
 
 ---
 
-## Ollama-Kompatibilität
+## Ollama Compatibility
 
-Für Kunden, die das API-Format von Ollama verwenden:
+For clients that use Ollama's API format:
 
 ```bash
 # Chat endpoint (Ollama format)
@@ -357,18 +371,18 @@ POST /v1/api/chat
 GET /api/tags
 ```
 
-Anfragen werden automatisch zwischen Ollama und internen Formaten übersetzt.
+Requests are automatically translated between Ollama and internal formats.
 
 ---
 
-## Telemetrie
+## Telemetry
 
 ```bash
 # Get latency telemetry summary (p50/p95/p99 per provider)
 GET /api/telemetry/summary
 ```
 
-**Antwort:**
+**Response:**
 
 ```json
 {
@@ -400,7 +414,7 @@ Content-Type: application/json
 
 ---
 
-## Modellverfügbarkeit
+## Model Availability
 
 ```bash
 # Get real-time model availability across all providers
@@ -417,26 +431,25 @@ Content-Type: application/json
 
 ---
 
-## Bearbeitung der Anfrage
+## Request Processing
 
-1. Client sendet Anfrage an `/v1/*`
-2. Route-Handler-Aufrufe `handleChat`, `handleEmbedding`, `handleAudioTranscription` oder `handleImageGeneration`
-3. Modell wird aufgelöst (direkter Anbieter/Modell oder Alias/Kombination)
-4. Aus der lokalen Datenbank ausgewählte Anmeldeinformationen mit Kontoverfügbarkeitsfilterung
-5. Für Chat: `handleChatCore` – Formaterkennung, Übersetzung, Cache-Prüfung, Idempotenzprüfung
-6. Der Executor des Anbieters sendet eine Upstream-Anfrage
-7. Antwort zurück ins Client-Format übersetzt (Chat) oder unverändert zurückgegeben (Einbettungen/Bilder/Audio)
-8. Nutzung/Protokollierung aufgezeichnet
-9. Bei Fehlern gilt ein Fallback gemäß den Combo-Regeln
+1. Client sends request to `/v1/*`
+2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration`
+3. Model is resolved (direct provider/model or alias/combo)
+4. Credentials selected from local DB with account availability filtering
+5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check
+6. Provider executor sends upstream request
+7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio)
+8. Usage/logging recorded
+9. Fallback applies on errors according to combo rules
 
-Vollständige Architekturreferenz: [link](ARCHITECTURE.md)
+Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md)
 
 ---
 
-## Authentifizierung
+## Authentication
 
-– Dashboard-Routen (`/dashboard/*`) verwenden das Cookie `auth_token`
-
-- Bei der Anmeldung wird der gespeicherte Passwort-Hash verwendet. Fallback auf `INITIAL_PASSWORD`
-- `requireLogin` umschaltbar über `/api/settings/require-login`
-  – `/v1/*` Routen erfordern optional einen Bearer-API-Schlüssel, wenn `REQUIRE_API_KEY=true`
+- Dashboard routes (`/dashboard/*`) use `auth_token` cookie
+- Login uses saved password hash; fallback to `INITIAL_PASSWORD`
+- `requireLogin` toggleable via `/api/settings/require-login`
+- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true`

docs/i18n/de/ARCHITECTURE.md

@@ -1,71 +1,75 @@
-# OmniRoute-Architektur
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/ARCHITECTURE.md) · 🇪🇸 [es](../es/ARCHITECTURE.md) · 🇫🇷 [fr](../fr/ARCHITECTURE.md) · 🇩🇪 [de](../de/ARCHITECTURE.md) · 🇮🇹 [it](../it/ARCHITECTURE.md) · 🇷🇺 [ru](../ru/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../zh-CN/ARCHITECTURE.md) · 🇯🇵 [ja](../ja/ARCHITECTURE.md) · 🇰🇷 [ko](../ko/ARCHITECTURE.md) · 🇸🇦 [ar](../ar/ARCHITECTURE.md) · 🇮🇳 [in](../in/ARCHITECTURE.md) · 🇹🇭 [th](../th/ARCHITECTURE.md) · 🇻🇳 [vi](../vi/ARCHITECTURE.md) · 🇮🇩 [id](../id/ARCHITECTURE.md) · 🇲🇾 [ms](../ms/ARCHITECTURE.md) · 🇳🇱 [nl](../nl/ARCHITECTURE.md) · 🇵🇱 [pl](../pl/ARCHITECTURE.md) · 🇸🇪 [sv](../sv/ARCHITECTURE.md) · 🇳🇴 [no](../no/ARCHITECTURE.md) · 🇩🇰 [da](../da/ARCHITECTURE.md) · 🇫🇮 [fi](../fi/ARCHITECTURE.md) · 🇵🇹 [pt](../pt/ARCHITECTURE.md) · 🇷🇴 [ro](../ro/ARCHITECTURE.md) · 🇭🇺 [hu](../hu/ARCHITECTURE.md) · 🇧🇬 [bg](../bg/ARCHITECTURE.md) · 🇸🇰 [sk](../sk/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../uk-UA/ARCHITECTURE.md) · 🇮🇱 [he](../he/ARCHITECTURE.md) · 🇵🇭 [phi](../phi/ARCHITECTURE.md)
 
-🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md)
+---
 
-_Letzte Aktualisierung: 18.02.2026_
+# OmniRoute Architecture
 
-## Zusammenfassung
+🌐 **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)
 
-OmniRoute ist ein lokales KI-Routing-Gateway und Dashboard, das auf Next.js basiert.
-Es bietet einen einzigen OpenAI-kompatiblen Endpunkt (`/v1/*`) und leitet den Datenverkehr über mehrere Upstream-Anbieter mit Übersetzung, Fallback, Token-Aktualisierung und Nutzungsverfolgung weiter.
+_Last updated: 2026-03-04_
 
-Kernkompetenzen:
+## Executive Summary
 
-- OpenAI-kompatible API-Oberfläche für CLI/Tools (28 Anbieter)
-- Anforderungs-/Antwortübersetzung über Anbieterformate hinweg
-- Modell-Combo-Fallback (Multi-Modell-Sequenz)
-- Fallback auf Kontoebene (mehrere Konten pro Anbieter)
-- OAuth + API-Schlüssel-Provider-Verbindungsverwaltung
-- Einbettungsgenerierung über `/v1/embeddings` (6 Anbieter, 9 Modelle)
-- Bildgenerierung über `/v1/images/generations` (4 Anbieter, 9 Modelle)
-- Denken Sie an Tag-Parsing (`<think>...</think>`) für Argumentationsmodelle
-- Antwortbereinigung für strikte OpenAI SDK-Kompatibilität
-- Rollennormalisierung (Entwickler→System, System→Benutzer) für anbieterübergreifende Kompatibilität
-- Strukturierte Ausgabekonvertierung (json_schema → Gemini ResponseSchema)
-- Lokale Persistenz für Anbieter, Schlüssel, Aliase, Kombinationen, Einstellungen, Preise
-- Nutzungs-/Kostenverfolgung und Anforderungsprotokollierung
-- Optionale Cloud-Synchronisierung für die Synchronisierung mehrerer Geräte/Status
-- IP-Zulassungs-/Blockierungsliste für die API-Zugriffskontrolle
-- Denken Sie an die Budgetverwaltung (Passthrough/Auto/Benutzerdefiniert/Adaptiv)
-- Sofortige Injektion des globalen Systems
-- Sitzungsverfolgung und Fingerabdruck
-- Erweiterte Ratenbegrenzung pro Konto mit anbieterspezifischen Profilen
-- Leistungsschaltermuster für die Ausfallsicherheit des Anbieters
-- Donnernder Herdenschutz mit Mutex-Sperre
-  – Signaturbasierter Anforderungsdeduplizierungs-Cache
-- Domänenschicht: Modellverfügbarkeit, Kostenregeln, Fallback-Richtlinie, Sperrrichtlinie
-- Persistenz des Domänenstatus (SQLite-Durchschreibcache für Fallbacks, Budgets, Sperrungen, Leistungsschalter)
-- Richtlinien-Engine für zentralisierte Anfrageauswertung (Sperrung → Budget → Fallback)
-- Fordern Sie Telemetrie mit p50/p95/p99-Latenzaggregation an
-- Korrelations-ID (X-Request-Id) für eine durchgängige Nachverfolgung
-- Compliance-Audit-Protokollierung mit Opt-out pro API-Schlüssel
-- Evaluierungsrahmen für die LLM-Qualitätssicherung
-- Resilience-UI-Dashboard mit Echtzeit-Leistungsschalterstatus
-- Modulare OAuth-Anbieter (12 einzelne Module unter `src/lib/oauth/providers/`)
+OmniRoute is a local AI routing gateway and dashboard built on Next.js.
+It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
 
-Primäres Laufzeitmodell:
+Core capabilities:
 
-– Next.js-App-Routen unter `src/app/api/*` implementieren sowohl Dashboard-APIs als auch Kompatibilitäts-APIs
-– Ein gemeinsam genutzter SSE/Routing-Kern in `src/sse/*` + `open-sse/*` kümmert sich um die Ausführung, Übersetzung, Streaming, Fallback und Nutzung des Anbieters
+- OpenAI-compatible API surface for CLI/tools (28 providers)
+- Request/response translation across provider formats
+- Model combo fallback (multi-model sequence)
+- Account-level fallback (multi-account per provider)
+- OAuth + API-key provider connection management
+- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
+- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Think tag parsing (`<think>...</think>`) for reasoning models
+- Response sanitization for strict OpenAI SDK compatibility
+- Role normalization (developer→system, system→user) for cross-provider compatibility
+- Structured output conversion (json_schema → Gemini responseSchema)
+- Local persistence for providers, keys, aliases, combos, settings, pricing
+- Usage/cost tracking and request logging
+- Optional cloud sync for multi-device/state sync
+- IP allowlist/blocklist for API access control
+- Thinking budget management (passthrough/auto/custom/adaptive)
+- Global system prompt injection
+- Session tracking and fingerprinting
+- Per-account enhanced rate limiting with provider-specific profiles
+- Circuit breaker pattern for provider resilience
+- Anti-thundering herd protection with mutex locking
+- Signature-based request deduplication cache
+- Domain layer: model availability, cost rules, fallback policy, lockout policy
+- 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
+- Correlation ID (X-Request-Id) for end-to-end tracing
+- Compliance audit logging with opt-out per API key
+- Eval framework for LLM quality assurance
+- Resilience UI dashboard with real-time circuit breaker status
+- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`)
 
-## Umfang und Grenzen
+Primary runtime model:
 
-### Im Geltungsbereich
+- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
+- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
 
-- Lokale Gateway-Laufzeit
-- Dashboard-Verwaltungs-APIs
-- Anbieterauthentifizierung und Token-Aktualisierung
-- Fordern Sie Übersetzung und SSE-Streaming an
-- Lokaler Status + Nutzungspersistenz
-- Optionale Orchestrierung der Cloud-Synchronisierung
+## Scope and Boundaries
 
-### Außerhalb des Gültigkeitsbereichs
+### In Scope
 
-- Cloud-Service-Implementierung hinter `NEXT_PUBLIC_CLOUD_URL`
-- Anbieter-SLA/Kontrollebene außerhalb des lokalen Prozesses
-- Externe CLI-Binärdateien selbst (Claude CLI, Codex CLI usw.)
+- Local gateway runtime
+- Dashboard management APIs
+- Provider authentication and token refresh
+- Request translation and SSE streaming
+- Local state + usage persistence
+- Optional cloud sync orchestration
 
-## Systemkontext auf hoher Ebene
+### Out of Scope
+
+- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
+- Provider SLA/control plane outside local process
+- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
+
+## High-Level System Context
 
 ```mermaid
 flowchart LR
@@ -81,8 +85,8 @@ 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]
@@ -113,152 +117,152 @@ flowchart LR
     DASH --> CLOUD
 ```
 
-## Kernlaufzeitkomponenten
+## Core Runtime Components
 
-## 1) API und Routing-Ebene (Next.js App Routes)
+## 1) API and Routing Layer (Next.js App Routes)
 
-Hauptverzeichnisse:
+Main directories:
 
-- `src/app/api/v1/*` und `src/app/api/v1beta/*` für Kompatibilitäts-APIs
-  – `src/app/api/*` für Verwaltungs-/Konfigurations-APIs
-- Nächste Umschreibungen in `next.config.mjs` ordnen `/v1/*` zu `/api/v1/*` zu
+- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
+- `src/app/api/*` for management/configuration APIs
+- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
 
-Wichtige Kompatibilitätsrouten:
+Important compatibility routes:
 
 - `src/app/api/v1/chat/completions/route.ts`
 - `src/app/api/v1/messages/route.ts`
 - `src/app/api/v1/responses/route.ts`
-- `src/app/api/v1/models/route.ts` – enthält benutzerdefinierte Modelle mit `custom: true`
-- `src/app/api/v1/embeddings/route.ts` – Einbettungsgenerierung (6 Anbieter)
-- `src/app/api/v1/images/generations/route.ts` — Bildgenerierung (4+ Anbieter inkl. Antigravity/Nebius)
+- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`
+- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)
+- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)
 - `src/app/api/v1/messages/count_tokens/route.ts`
-- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` – dedizierter Chat pro Anbieter
-- `src/app/api/v1/providers/[provider]/embeddings/route.ts` – dedizierte Einbettungen pro Anbieter
-- `src/app/api/v1/providers/[provider]/images/generations/route.ts` – dedizierte Bilder pro Anbieter
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images
 - `src/app/api/v1beta/models/route.ts`
 - `src/app/api/v1beta/models/[...path]/route.ts`
 
-Verwaltungsdomänen:
+Management domains:
 
-- Authentifizierung/Einstellungen: `src/app/api/auth/*`, `src/app/api/settings/*`
-- Anbieter/Verbindungen: `src/app/api/providers*`
-- Anbieterknoten: `src/app/api/provider-nodes*`
-- Benutzerdefinierte Modelle: `src/app/api/provider-models` (GET/POST/DELETE)
-- Modellkatalog: `src/app/api/models/catalog` (GET)
-- Proxy-Konfiguration: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
+- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
+- 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/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/*`
-- Schlüssel/Aliase/Kombinationen/Preise: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
-- Verwendung: `src/app/api/usage/*`
-- Synchronisierung/Cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
-- CLI-Tool-Helfer: `src/app/api/cli-tools/*`
-- IP-Filter: `src/app/api/settings/ip-filter` (GET/PUT)
-- Denkbudget: `src/app/api/settings/thinking-budget` (GET/PUT)
-- Systemaufforderung: `src/app/api/settings/system-prompt` (GET/PUT)
-- Sitzungen: `src/app/api/sessions` (GET)
-- Ratenlimits: `src/app/api/rate-limits` (GET)
-  – Belastbarkeit: `src/app/api/resilience` (GET/PATCH) – Anbieterprofile, Leistungsschalter, Ratengrenzzustand
-- Resilienz-Reset: `src/app/api/resilience/reset` (POST) – Breaker + Abklingzeiten zurücksetzen
-- Cache-Statistiken: `src/app/api/cache/stats` (GET/DELETE)
-- Modellverfügbarkeit: `src/app/api/models/availability` (GET/POST)
-- Telemetrie: `src/app/api/telemetry/summary` (GET)
+- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
+- Usage: `src/app/api/usage/*`
+- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
+- CLI tooling helpers: `src/app/api/cli-tools/*`
+- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)
+- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)
+- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)
+- Sessions: `src/app/api/sessions` (GET)
+- Rate limits: `src/app/api/rate-limits` (GET)
+- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns
+- Cache stats: `src/app/api/cache/stats` (GET/DELETE)
+- Model availability: `src/app/api/models/availability` (GET/POST)
+- Telemetry: `src/app/api/telemetry/summary` (GET)
 - Budget: `src/app/api/usage/budget` (GET/POST)
-- Fallback-Ketten: `src/app/api/fallback/chains` (GET/POST/DELETE)
-- Compliance-Audit: `src/app/api/compliance/audit-log` (GET)
-- Auswertungen: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
-- Richtlinien: `src/app/api/policies` (GET/POST)
+- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET)
+- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
+- Policies: `src/app/api/policies` (GET/POST)
 
-## 2) SSE + Übersetzungskern
+## 2) SSE + Translation Core
 
-Hauptflussmodule:
+Main flow modules:
 
-- Eintrag: `src/sse/handlers/chat.ts`
-- Kernorchestrierung: `open-sse/handlers/chatCore.ts`
-  – Anbieterausführungsadapter: `open-sse/executors/*`
-  – Formaterkennung/Anbieterkonfiguration: `open-sse/services/provider.ts`
-- Modellanalyse/-auflösung: `src/sse/services/model.ts`, `open-sse/services/model.ts`
-- Konto-Fallback-Logik: `open-sse/services/accountFallback.ts`
-- Übersetzungsregister: `open-sse/translator/index.ts`
-- Stream-Transformationen: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
-  – Extraktion/Normalisierung der Nutzung: `open-sse/utils/usageTracking.ts`
-- Think-Tag-Parser: `open-sse/utils/thinkTagParser.ts`
-- Einbettungshandler: `open-sse/handlers/embeddings.ts`
-- Anbieterregistrierung einbetten: `open-sse/config/embeddingRegistry.ts`
-- Handler für die Bildgenerierung: `open-sse/handlers/imageGeneration.ts`
-- Bildanbieter-Registrierung: `open-sse/config/imageRegistry.ts`
-  – Antwortbereinigung: `open-sse/handlers/responseSanitizer.ts`
-- Rollennormalisierung: `open-sse/services/roleNormalizer.ts`
+- Entry: `src/sse/handlers/chat.ts`
+- Core orchestration: `open-sse/handlers/chatCore.ts`
+- Provider execution adapters: `open-sse/executors/*`
+- Format detection/provider config: `open-sse/services/provider.ts`
+- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
+- Account fallback logic: `open-sse/services/accountFallback.ts`
+- Translation registry: `open-sse/translator/index.ts`
+- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
+- Think tag parser: `open-sse/utils/thinkTagParser.ts`
+- Embedding handler: `open-sse/handlers/embeddings.ts`
+- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
+- Image generation handler: `open-sse/handlers/imageGeneration.ts`
+- Image provider registry: `open-sse/config/imageRegistry.ts`
+- Response sanitization: `open-sse/handlers/responseSanitizer.ts`
+- Role normalization: `open-sse/services/roleNormalizer.ts`
 
-Dienste (Geschäftslogik):
+Services (business logic):
 
-- Kontoauswahl/-bewertung: `open-sse/services/accountSelector.ts`
-- Kontextlebenszyklusverwaltung: `open-sse/services/contextManager.ts`
-- Durchsetzung des IP-Filters: `open-sse/services/ipFilter.ts`
-- Sitzungsverfolgung: `open-sse/services/sessionManager.ts`
-  – Deduplizierung anfordern: `open-sse/services/signatureCache.ts`
-- Eingabeaufforderung des Systems: `open-sse/services/systemPrompt.ts`
-- Denkendes Budgetmanagement: `open-sse/services/thinkingBudget.ts`
-- Wildcard-Modell-Routing: `open-sse/services/wildcardRouter.ts`
-- Ratenlimitverwaltung: `open-sse/services/rateLimitManager.ts`
-- Leistungsschalter: `open-sse/services/circuitBreaker.ts`
+- Account selection/scoring: `open-sse/services/accountSelector.ts`
+- Context lifecycle management: `open-sse/services/contextManager.ts`
+- IP filter enforcement: `open-sse/services/ipFilter.ts`
+- Session tracking: `open-sse/services/sessionManager.ts`
+- Request deduplication: `open-sse/services/signatureCache.ts`
+- System prompt injection: `open-sse/services/systemPrompt.ts`
+- Thinking budget management: `open-sse/services/thinkingBudget.ts`
+- Wildcard model routing: `open-sse/services/wildcardRouter.ts`
+- Rate limit management: `open-sse/services/rateLimitManager.ts`
+- Circuit breaker: `open-sse/services/circuitBreaker.ts`
 
-Module der Domänenschicht:
+Domain layer modules:
 
-- Modellverfügbarkeit: `src/lib/domain/modelAvailability.ts`
-- Kostenregeln/Budgets: `src/lib/domain/costRules.ts`
-- Fallback-Richtlinie: `src/lib/domain/fallbackPolicy.ts`
-- Combo-Resolver: `src/lib/domain/comboResolver.ts`
-- Sperrrichtlinie: `src/lib/domain/lockoutPolicy.ts`
-  – Richtlinien-Engine: `src/domain/policyEngine.ts` – zentralisierte Sperrung → Budget → Fallback-Bewertung
-- Fehlercodekatalog: `src/lib/domain/errorCodes.ts`
-- Anforderungs-ID: `src/lib/domain/requestId.ts`
-  – Abrufzeitüberschreitung: `src/lib/domain/fetchTimeout.ts`
-- Telemetrie anfordern: `src/lib/domain/requestTelemetry.ts`
-- Compliance/Audit: `src/lib/domain/compliance/index.ts`
-  – Evaluierungsläufer: `src/lib/domain/evalRunner.ts`
-  – Domänenstatus-Persistenz: `src/lib/db/domainState.ts` – SQLite CRUD für Fallback-Ketten, Budgets, Kostenverlauf, Sperrstatus, Leistungsschalter
+- Model availability: `src/lib/domain/modelAvailability.ts`
+- Cost rules/budgets: `src/lib/domain/costRules.ts`
+- Fallback policy: `src/lib/domain/fallbackPolicy.ts`
+- Combo resolver: `src/lib/domain/comboResolver.ts`
+- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
+- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
+- Error codes catalog: `src/lib/domain/errorCodes.ts`
+- Request ID: `src/lib/domain/requestId.ts`
+- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
+- Request telemetry: `src/lib/domain/requestTelemetry.ts`
+- Compliance/audit: `src/lib/domain/compliance/index.ts`
+- Eval runner: `src/lib/domain/evalRunner.ts`
+- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
 
-OAuth-Provider-Module (12 einzelne Dateien unter `src/lib/oauth/providers/`):
+OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
-- Registrierungsindex: `src/lib/oauth/providers/index.ts`
-- Einzelne Anbieter: `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`
-  – Thin Wrapper: `src/lib/oauth/providers.ts` – Re-Exporte aus einzelnen Modulen
+- 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`
+- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
-## 3) Persistenzschicht
+## 3) Persistence Layer
 
-Primärer Zustands-DB:
+Primary state DB (SQLite):
 
-- `src/lib/localDb.ts`
-- Datei: `${DATA_DIR}/db.json` (oder `$XDG_CONFIG_HOME/omniroute/db.json`, wenn festgelegt, sonst `~/.omniroute/db.json`)
-- Entitäten: ProviderConnections, ProviderNodes, ModelAliases, Combos, APIKeys, Einstellungen, Preise, **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**
 
-Nutzungs-DB:
+Usage persistence:
 
-- `src/lib/usageDb.ts`
-- Dateien: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
-  – Folgt derselben Basisverzeichnisrichtlinie wie `localDb` (`DATA_DIR`, dann `XDG_CONFIG_HOME/omniroute`, wenn festgelegt)
-- zerlegt in fokussierte Untermodule: `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):
 
-– `src/lib/db/domainState.ts` – CRUD-Operationen für den Domänenstatus
+- `src/lib/db/domainState.ts` — CRUD operations for domain state
+- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
+- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
 
-- Tabellen (erstellt in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
-- Write-Through-Cache-Muster: In-Memory-Maps sind zur Laufzeit maßgeblich; Mutationen werden synchron zu SQLite geschrieben; Der Status wird beim Kaltstart aus der DB wiederhergestellt
+## 4) Auth + Security Surfaces
 
-## 4) Authentifizierung + Sicherheitsoberflächen
+- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
+- API key generation/verification: `src/shared/utils/apiKey.ts`
+- Provider secrets persisted in `providerConnections` entries
+- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
 
-- Dashboard-Cookie-Authentifizierung: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
-- API-Schlüsselgenerierung/-überprüfung: `src/shared/utils/apiKey.ts`
-  – Provider-Geheimnisse blieben in `providerConnections`-Einträgen bestehen
-- Unterstützung für ausgehende Proxys über `open-sse/utils/proxyFetch.ts` (Env-Variablen) und `open-sse/utils/networkProxy.ts` (pro Anbieter oder global konfigurierbar)
+## 5) Cloud Sync
 
-## 5) Cloud-Synchronisierung
+- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
+- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Control route: `src/app/api/sync/cloud/route.ts`
 
-- Scheduler-Init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
-- Periodische Aufgabe: `src/shared/services/cloudSyncScheduler.ts`
-- Kontrollroute: `src/app/api/sync/cloud/route.ts`
-
-## Anforderungslebenszyklus (`/v1/chat/completions`)
+## Request Lifecycle (`/v1/chat/completions`)
 
 ```mermaid
 sequenceDiagram
@@ -305,7 +309,7 @@ sequenceDiagram
     Stream->>Usage: extract usage + persist history/log
 ```
 
-## Combo + Konto-Fallback-Flow
+## Combo + Account Fallback Flow
 
 ```mermaid
 flowchart TD
@@ -335,9 +339,9 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-Fallback-Entscheidungen werden von `open-sse/services/accountFallback.ts` mithilfe von Statuscodes und Fehlermeldungsheuristiken gesteuert.
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics.
 
-## OAuth-Onboarding und Token-Aktualisierungslebenszyklus
+## OAuth Onboarding and Token Refresh Lifecycle
 
 ```mermaid
 sequenceDiagram
@@ -367,9 +371,9 @@ sequenceDiagram
     Test-->>UI: validation result
 ```
 
-Die Aktualisierung während des Live-Verkehrs wird in `open-sse/handlers/chatCore.ts` über den Executor `refreshCredentials()` ausgeführt.
+Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
 
-## Cloud-Sync-Lebenszyklus (Aktivieren/Synchronisieren/Deaktivieren)
+## Cloud Sync Lifecycle (Enable / Sync / Disable)
 
 ```mermaid
 sequenceDiagram
@@ -401,9 +405,9 @@ sequenceDiagram
     Sync-->>UI: disabled
 ```
 
-Die regelmäßige Synchronisierung wird durch `CloudSyncScheduler` ausgelöst, wenn die Cloud aktiviert ist.
+Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
 
-## Datenmodell und Speicherzuordnung
+## Data Model and Storage Map
 
 ```mermaid
 erDiagram
@@ -504,14 +508,14 @@ erDiagram
     }
 ```
 
-Physische Speicherdateien:
+Physical storage files:
 
-- Hauptstatus: `${DATA_DIR}/db.json` (oder `$XDG_CONFIG_HOME/omniroute/db.json`, wenn festgelegt, sonst `~/.omniroute/db.json`)
-- Nutzungsstatistiken: `${DATA_DIR}/usage.json`
-- Protokollzeilen anfordern: `${DATA_DIR}/log.txt`
-- optionale Übersetzer-/Anfrage-Debug-Sitzungen: `<repo>/logs/...`
+- 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/...`
 
-## Bereitstellungstopologie
+## Deployment Topology
 
 ```mermaid
 flowchart LR
@@ -523,8 +527,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]
@@ -542,242 +546,242 @@ flowchart LR
     Next --> SyncCloud
 ```
 
-## Modulzuordnung (entscheidungskritisch)
+## Module Mapping (Decision-Critical)
 
-### Routen- und API-Module
+### Route and API Modules
 
-- `src/app/api/v1/*`, `src/app/api/v1beta/*`: Kompatibilitäts-APIs
-- `src/app/api/v1/providers/[provider]/*`: dedizierte Routen pro Anbieter (Chat, Einbettungen, Bilder)
-- `src/app/api/providers*`: Anbieter CRUD, Validierung, Tests
-- `src/app/api/provider-nodes*`: Benutzerdefinierte kompatible Knotenverwaltung
-- `src/app/api/provider-models`: benutzerdefinierte Modellverwaltung (CRUD)
-- `src/app/api/models/catalog`: vollständige Modellkatalog-API (alle Typen nach Anbieter gruppiert)
-  – `src/app/api/oauth/*`: OAuth/Gerätecodeflüsse
-- `src/app/api/keys*`: Lebenszyklus des lokalen API-Schlüssels
-- `src/app/api/models/alias`: Alias-Verwaltung
-- `src/app/api/combos*`: Fallback-Kombinationsverwaltung
-- `src/app/api/pricing`: Preisüberschreibungen für die Kostenberechnung
-- `src/app/api/settings/proxy`: Proxy-Konfiguration (GET/PUT/DELETE)
-- `src/app/api/settings/proxy/test`: Test der ausgehenden Proxy-Konnektivität (POST)
-- `src/app/api/usage/*`: Nutzungs- und Protokoll-APIs
-- `src/app/api/sync/*` + `src/app/api/cloud/*`: Cloud-Synchronisierung und Cloud-orientierte Helfer
-- `src/app/api/cli-tools/*`: lokale CLI-Konfigurationsschreiber/-prüfer
-- `src/app/api/settings/ip-filter`: IP-Zulassungsliste/Blockliste (GET/PUT)
-- `src/app/api/settings/thinking-budget`: Denk-Token-Budget-Konfiguration (GET/PUT)
-- `src/app/api/settings/system-prompt`: globale Systemeingabeaufforderung (GET/PUT)
-- `src/app/api/sessions`: aktive Sitzungsliste (GET)
-- `src/app/api/rate-limits`: Status des Ratenlimits pro Konto (GET)
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
+- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
+- `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/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
+- `src/app/api/combos*`: fallback combo management
+- `src/app/api/pricing`: pricing overrides for cost calculation
+- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
+- `src/app/api/usage/*`: usage and logs APIs
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
+- `src/app/api/cli-tools/*`: local CLI config writers/checkers
+- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
+- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
+- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
+- `src/app/api/sessions`: active session listing (GET)
+- `src/app/api/rate-limits`: per-account rate limit status (GET)
 
-### Routing- und Ausführungskern
+### Routing and Execution Core
 
-- `src/sse/handlers/chat.ts`: Anforderungsanalyse, Kombinationsbehandlung, Kontoauswahlschleife
-- `open-sse/handlers/chatCore.ts`: Übersetzung, Executor-Versand, Wiederholungs-/Aktualisierungsbehandlung, Stream-Setup
-- `open-sse/executors/*`: anbieterspezifisches Netzwerk- und Formatverhalten
+- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
+- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
+- `open-sse/executors/*`: provider-specific network and format behavior
 
-### Übersetzungsregister und Formatkonverter
+### Translation Registry and Format Converters
 
-- `open-sse/translator/index.ts`: Übersetzerregistrierung und Orchestrierung
-- Übersetzer anfordern: `open-sse/translator/request/*`
-- Antwortübersetzer: `open-sse/translator/response/*`
-- Formatkonstanten: `open-sse/translator/formats.ts`
+- `open-sse/translator/index.ts`: translator registry and orchestration
+- Request translators: `open-sse/translator/request/*`
+- Response translators: `open-sse/translator/response/*`
+- Format constants: `open-sse/translator/formats.ts`
 
-### Beharrlichkeit
+### Persistence
 
-- `src/lib/localDb.ts`: persistente Konfiguration/Status
-- `src/lib/usageDb.ts`: Nutzungsverlauf und fortlaufende Anforderungsprotokolle
+- `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 (Strategiemuster)
+## Provider Executor Coverage (Strategy Pattern)
 
-Jeder Anbieter verfügt über einen speziellen Executor, der `BaseExecutor` (in `open-sse/executors/base.ts`) erweitert und URL-Erstellung, Header-Konstruktion, Wiederholungsversuche mit exponentiellem Backoff, Hooks für die Aktualisierung von Anmeldeinformationen und die Orchestrierungsmethode `execute()` bereitstellt.
+Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method.
 
-| Testamentsvollstrecker | Anbieter(n)                                                                                                                                                  | Besondere Handhabung                                                          |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
-| `DefaultExecutor`      | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamische URL-/Header-Konfiguration pro Anbieter                             |
-| `AntigravityExecutor`  | Google Antigravitation                                                                                                                                       | Benutzerdefinierte Projekt-/Sitzungs-IDs, Wiederholen nach dem Parsen         |
-| `CodexExecutor`        | OpenAI-Codex                                                                                                                                                 | Fügt Systemanweisungen ein und erzwingt den Denkaufwand                       |
-| `CursorExecutor`       | Cursor-IDE                                                                                                                                                   | ConnectRPC-Protokoll, Protobuf-Kodierung, Anforderungssignatur über Prüfsumme |
-| `GithubExecutor`       | GitHub-Copilot                                                                                                                                               | Copilot-Token-Aktualisierung, VSCode-imitierende Header                       |
-| `KiroExecutor`         | AWS CodeWhisperer/Kiro                                                                                                                                       | AWS EventStream-Binärformat → SSE-Konvertierung                               |
-| `GeminiCLIExecutor`    | Gemini CLI                                                                                                                                                   | Aktualisierungszyklus des Google OAuth-Tokens                                 |
+| 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                               |
+| `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 |
+| `GithubExecutor`      | GitHub Copilot                                                                                                                                               | Copilot token refresh, VSCode-mimicking headers                      |
+| `KiroExecutor`        | AWS CodeWhisperer/Kiro                                                                                                                                       | AWS EventStream binary format → SSE conversion                       |
+| `GeminiCLIExecutor`   | Gemini CLI                                                                                                                                                   | Google OAuth token refresh cycle                                     |
 
-Alle anderen Anbieter (einschließlich benutzerdefinierter kompatibler Knoten) verwenden `DefaultExecutor`.
+All other providers (including custom compatible nodes) use the `DefaultExecutor`.
 
-## Anbieterkompatibilitätsmatrix
+## Provider Compatibility Matrix
 
-| Anbieter         | Formatieren      | Authentifizierung            | Stream           | Nicht-Stream | Token-Aktualisierung | Nutzungs-API                   |
-| ---------------- | ---------------- | ---------------------------- | ---------------- | ------------ | -------------------- | ------------------------------ |
-| Claude           | Claude           | API-Schlüssel / OAuth        | ✅               | ✅           | ✅                   | ⚠️ Nur Administrator           |
-| Zwillinge        | Zwillinge        | API-Schlüssel / OAuth        | ✅               | ✅           | ✅                   | ⚠️ Cloud-Konsole               |
-| Gemini CLI       | gemini-cli       | OAuth                        | ✅               | ✅           | ✅                   | ⚠️ Cloud-Konsole               |
-| Antigravitation  | Antigravitation  | OAuth                        | ✅               | ✅           | ✅                   | ✅ Vollständige Kontingent-API |
-| OpenAI           | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Kodex            | Openai-Antworten | OAuth                        | ✅ gezwungen     | ❌           | ✅                   | ✅ Tariflimits                 |
-| GitHub-Copilot   | openai           | OAuth + Copilot-Token        | ✅               | ✅           | ✅                   | ✅ Kontingent-Snapshots        |
-| Cursor           | Cursor           | Benutzerdefinierte Prüfsumme | ✅               | ✅           | ❌                   | ❌                             |
-| Kiro             | kiro             | AWS SSO OIDC                 | ✅ (EventStream) | ❌           | ✅                   | ✅ Nutzungsbeschränkungen      |
-| Qwen             | openai           | OAuth                        | ✅               | ✅           | ✅                   | ⚠️ Auf Anfrage                 |
-| iFlow            | openai           | OAuth (Basic)                | ✅               | ✅           | ✅                   | ⚠️ Auf Anfrage                 |
-| OpenRouter       | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| GLM/Kimi/MiniMax | Claude           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| DeepSeek         | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Groq             | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| xAI (Grok)       | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Mistral          | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Ratlosigkeit     | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Zusammen KI      | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Feuerwerk KI     | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Großhirn         | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Kohärent         | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| NVIDIA NIM       | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
+| Provider         | Format           | Auth                  | Stream           | Non-Stream | Token Refresh | Usage API          |
+| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
+| Claude           | claude           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Admin only      |
+| Gemini           | gemini           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Gemini CLI       | gemini-cli       | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Antigravity      | antigravity      | OAuth                 | ✅               | ✅         | ✅            | ✅ Full quota API  |
+| OpenAI           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Codex            | openai-responses | OAuth                 | ✅ forced        | ❌         | ✅            | ✅ Rate limits     |
+| GitHub Copilot   | openai           | OAuth + Copilot Token | ✅               | ✅         | ✅            | ✅ Quota snapshots |
+| Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
+| Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
+| Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| iFlow            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Groq             | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| xAI (Grok)       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Mistral          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Perplexity       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Together AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Fireworks AI     | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 
-## Übersetzungsabdeckung im Format
+## Format Translation Coverage
 
-Zu den erkannten Quellformaten gehören:
+Detected source formats include:
 
 - `openai`
 - `openai-responses`
 - `claude`
 - `gemini`
 
-Zu den Zielformaten gehören:
+Target formats include:
 
-- OpenAI-Chat/Antworten
+- OpenAI chat/Responses
 - Claude
-- Gemini/Gemini-CLI/Antigravity-Umschlag
+- Gemini/Gemini-CLI/Antigravity envelope
 - Kiro
 - Cursor
 
-Übersetzungen verwenden **OpenAI als Hub-Format** – alle Konvertierungen durchlaufen OpenAI als Zwischenformat:
+Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
 
 ```
 Source Format → OpenAI (hub) → Target Format
 ```
 
-Übersetzungen werden dynamisch basierend auf der Form der Quellnutzlast und dem Zielformat des Anbieters ausgewählt.
+Translations are selected dynamically based on source payload shape and provider target format.
 
-Zusätzliche Verarbeitungsebenen in der Übersetzungspipeline:
+Additional processing layers in the translation pipeline:
 
-- **Antwortbereinigung** – Entfernt nicht standardmäßige Felder aus Antworten im OpenAI-Format (sowohl Streaming als auch Nicht-Streaming), um eine strikte SDK-Konformität sicherzustellen
-- **Rollennormalisierung** – Konvertiert `developer` → `system` für Nicht-OpenAI-Ziele; führt `system` → `user` für Modelle zusammen, die die Systemrolle ablehnen (GLM, ERNIE)
-- **Think-Tag-Extraktion** – Analysiert `<think>...</think>`-Blöcke aus dem Inhalt in das Feld `reasoning_content`
-- **Strukturierte Ausgabe** – Konvertiert OpenAI `response_format.json_schema` in Geminis `responseMimeType` + `responseSchema`
+- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance
+- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)
+- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field
+- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`
 
-## Unterstützte API-Endpunkte
+## Supported API Endpoints
 
-| Endpunkt                                           | Formatieren                | Handler                                                           |
-| -------------------------------------------------- | -------------------------- | ----------------------------------------------------------------- |
-| `POST /v1/chat/completions`                        | OpenAI-Chat                | `src/sse/handlers/chat.ts`                                        |
-| `POST /v1/messages`                                | Claude-Nachrichten         | Gleicher Handler (automatisch erkannt)                            |
-| `POST /v1/responses`                               | OpenAI-Antworten           | `open-sse/handlers/responsesHandler.ts`                           |
-| `POST /v1/embeddings`                              | OpenAI-Einbettungen        | `open-sse/handlers/embeddings.ts`                                 |
-| `GET /v1/embeddings`                               | Modellliste                | API-Route                                                         |
-| `POST /v1/images/generations`                      | OpenAI-Bilder              | `open-sse/handlers/imageGeneration.ts`                            |
-| `GET /v1/images/generations`                       | Modellliste                | API-Route                                                         |
-| `POST /v1/providers/{provider}/chat/completions`   | OpenAI-Chat                | Dedizierter pro Anbieter mit Modellvalidierung                    |
-| `POST /v1/providers/{provider}/embeddings`         | OpenAI-Einbettungen        | Dedizierter pro Anbieter mit Modellvalidierung                    |
-| `POST /v1/providers/{provider}/images/generations` | OpenAI-Bilder              | Dedizierter pro Anbieter mit Modellvalidierung                    |
-| `POST /v1/messages/count_tokens`                   | Claude Token Count         | API-Route                                                         |
-| `GET /v1/models`                                   | Liste der OpenAI-Modelle   | API-Route (Chat + Einbettung + Bild + benutzerdefinierte Modelle) |
-| `GET /api/models/catalog`                          | Katalog                    | Alle Modelle gruppiert nach Anbieter + Typ                        |
-| `POST /v1beta/models/*:streamGenerateContent`      | Zwillinge heimisch         | API-Route                                                         |
-| `GET/PUT/DELETE /api/settings/proxy`               | Proxy-Konfiguration        | Netzwerk-Proxy-Konfiguration                                      |
-| `POST /api/settings/proxy/test`                    | Proxy-Konnektivität        | Proxy-Zustands-/Konnektivitätstest-Endpunkt                       |
-| `GET/POST/DELETE /api/provider-models`             | Benutzerdefinierte Modelle | Benutzerdefinierte Modellverwaltung pro Anbieter                  |
+| 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                 |
 
-## Bypass-Handler
+## Bypass Handler
 
-Der Bypass-Handler (`open-sse/utils/bypassHandler.ts`) fängt bekannte „Wegwerf“-Anfragen von Claude CLI ab – Warmup-Pings, Titelextraktionen und Token-Zählungen – und gibt eine **falsche Antwort** zurück, ohne Upstream-Provider-Tokens zu verbrauchen. Dies wird nur ausgelöst, wenn `User-Agent` `claude-cli` enthält.
+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`.
 
-## Logger-Pipeline anfordern
+## Request Logger Pipeline
 
-Der Anforderungslogger (`open-sse/utils/requestLogger.ts`) stellt eine 7-stufige Debug-Protokollierungspipeline bereit, die standardmäßig deaktiviert und über `ENABLE_REQUEST_LOGS=true` aktiviert ist:
+The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`:
 
 ```
 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
 ```
 
-Dateien werden für jede Anforderungssitzung in `<repo>/logs/<session>/` geschrieben.
+Files are written to `<repo>/logs/<session>/` for each request session.
 
-## Fehlermodi und Belastbarkeit
+## Failure Modes and Resilience
 
-## 1) Konto-/Anbieterverfügbarkeit
+## 1) Account/Provider Availability
 
-- Abklingzeit des Anbieterkontos bei vorübergehenden/Raten-/Authentifizierungsfehlern
-- Konto-Fallback vor fehlgeschlagener Anfrage
-- Combo-Modell-Fallback, wenn der aktuelle Modell-/Anbieterpfad erschöpft ist
+- provider account cooldown on transient/rate/auth errors
+- account fallback before failing request
+- combo model fallback when current model/provider path is exhausted
 
-## 2) Token-Ablauf
+## 2) Token Expiry
 
-- Vorabprüfung und Aktualisierung mit erneutem Versuch für aktualisierbare Anbieter
-  – 401/403-Wiederholungsversuch nach Aktualisierungsversuch im Kernpfad
+- pre-check and refresh with retry for refreshable providers
+- 401/403 retry after refresh attempt in core path
 
-## 3) Stream-Sicherheit
+## 3) Stream Safety
 
-- Trennungsfähiger Stream-Controller
-  – Übersetzungsstream mit End-of-Stream-Flush und `[DONE]`-Behandlung
-- Fallback der Nutzungsschätzung, wenn Metadaten zur Anbieternutzung fehlen
+- disconnect-aware stream controller
+- translation stream with end-of-stream flush and `[DONE]` handling
+- usage estimation fallback when provider usage metadata is missing
 
-## 4) Verschlechterung der Cloud-Synchronisierung
+## 4) Cloud Sync Degradation
 
-– Synchronisierungsfehler werden angezeigt, die lokale Laufzeit wird jedoch fortgesetzt
-– Der Scheduler verfügt über eine wiederholfähige Logik, aber die regelmäßige Ausführung ruft derzeit standardmäßig eine Einzelversuchssynchronisierung auf
+- sync errors are surfaced but local runtime continues
+- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
 
-## 5) Datenintegrität
+## 5) Data Integrity
 
-- DB-Shape-Migration/Reparatur für fehlende Schlüssel
-- Schutzmaßnahmen zum Zurücksetzen beschädigter JSON-Dateien für localDb und useDb
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
-## Beobachtbarkeit und Betriebssignale
+## Observability and Operational Signals
 
-Quellen für die Laufzeitsichtbarkeit:
+Runtime visibility sources:
 
-– Konsolenprotokolle von `src/sse/utils/logger.ts`
-– Nutzungsaggregate pro Anfrage in `usage.json`
+- console logs from `src/sse/utils/logger.ts`
+- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- textual request status log in `log.txt` (optional/compat)
+- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true`
+- dashboard usage endpoints (`/api/usage/*`) for UI consumption
 
-- Statusprotokoll der Textanfrage in `log.txt`
-  – optionale Protokolle für tiefe Anfragen/Übersetzungen unter `logs/`, wenn `ENABLE_REQUEST_LOGS=true`
-  – Dashboard-Nutzungsendpunkte (`/api/usage/*`) für die UI-Nutzung
+## Security-Sensitive Boundaries
 
-## Sicherheitsrelevante Grenzen
+- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
+- 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
 
-– JWT-Geheimnis (`JWT_SECRET`) sichert die Überprüfung/Signierung von Dashboard-Sitzungscookies
-– Der anfängliche Passwort-Fallback (`INITIAL_PASSWORD`, Standard `123456`) muss in echten Bereitstellungen überschrieben werden
-– Das HMAC-Geheimnis des API-Schlüssels (`API_KEY_SECRET`) sichert das generierte lokale API-Schlüsselformat
-– Anbietergeheimnisse (API-Schlüssel/Tokens) werden in der lokalen Datenbank gespeichert und sollten auf Dateisystemebene geschützt werden
-– Cloud-Synchronisierungsendpunkte basieren auf der API-Schlüsselauthentifizierung und der Maschinen-ID-Semantik
+## Environment and Runtime Matrix
 
-## Umgebungs- und Laufzeitmatrix
+Environment variables actively used by code:
 
-Vom Code aktiv verwendete Umgebungsvariablen:
+- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Storage: `DATA_DIR`
+- 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`
+- 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`
+- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
 
-- App/Authentifizierung: `JWT_SECRET`, `INITIAL_PASSWORD`
-- Speicher: `DATA_DIR`
-- Kompatibles Knotenverhalten: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
-  – Optionale Speicherbasisüberschreibung (Linux/macOS, wenn `DATA_DIR` nicht gesetzt ist): `XDG_CONFIG_HOME`
-- Sicherheits-Hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
-- Protokollierung: `ENABLE_REQUEST_LOGS`
-- Synchronisierung/Cloud-URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
-- Ausgehender Proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` und Varianten in Kleinbuchstaben
-- SOCKS5-Funktionsflags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
-- Plattform-/Laufzeithelfer (keine App-spezifische Konfiguration): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+## Known Architectural Notes
 
-## Bekannte architektonische Hinweise
+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: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), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
 
-1. `usageDb` und `localDb` verwenden jetzt dieselbe Basisverzeichnisrichtlinie (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) mit der Migration älterer Dateien.
-2. `/api/v1/route.ts` gibt eine statische Modellliste zurück und ist nicht die Hauptmodellquelle, die von `/v1/models` verwendet wird.
-3. Der Anforderungslogger schreibt bei Aktivierung vollständige Header/Textkörper. Behandeln Sie das Protokollverzeichnis als vertraulich.
-4. Das Cloud-Verhalten hängt vom korrekten `NEXT_PUBLIC_BASE_URL` und der Erreichbarkeit des Cloud-Endpunkts ab.
-5. Das Verzeichnis `open-sse/` wird als `@omniroute/open-sse` **npm-Arbeitsbereichspaket** veröffentlicht. Der Quellcode importiert es über `@omniroute/open-sse/...` (aufgelöst durch Next.js `transpilePackages`). Dateipfade in diesem Dokument verwenden aus Konsistenzgründen weiterhin den Verzeichnisnamen `open-sse/`.
-6. Diagramme im Dashboard verwenden **Recharts** (SVG-basiert) für zugängliche, interaktive Analysevisualisierungen (Modellnutzungs-Balkendiagramme, Anbieteraufschlüsselungstabellen mit Erfolgsquoten).
-7. E2E-Tests verwenden **Playwright** (`tests/e2e/`) und werden über `npm run test:e2e` ausgeführt. Unit-Tests verwenden **Node.js Test Runner** (`tests/unit/`) und werden über `npm run test:plan3` ausgeführt. Der Quellcode unter `src/` ist **TypeScript** (`.ts`/`.tsx`); Der Arbeitsbereich `open-sse/` bleibt JavaScript (`.js`).
-8. Die Einstellungsseite ist in 5 Registerkarten unterteilt: Sicherheit, Routing (6 globale Strategien: Fill-First, Round-Robin, P2C, Random, Least-Used, Cost-Optimized), Resilience (bearbeitbare Ratenlimits, Leistungsschalter, Richtlinien), AI (Thinking Budget, System Prompt, Prompt Cache), Advanced (Proxy).
+## Operational Verification Checklist
 
-## Checkliste zur Betriebsüberprüfung
-
-- Build aus Quelle: `npm run build`
-- Docker-Image erstellen: `docker build -t omniroute .`
-- Starten Sie den Dienst und überprüfen Sie:
+- Build from source: `npm run build`
+- Build Docker image: `docker build -t omniroute .`
+- Start service and verify:
 - `GET /api/settings`
 - `GET /api/v1/models`
-  – Die Basis-URL des CLI-Ziels sollte `http://<host>:20128/v1` sein, wenn `PORT=20128`
+- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`

docs/i18n/de/AUTO-COMBO.md

@@ -0,0 +1,67 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/AUTO-COMBO.md) · 🇪🇸 [es](../es/AUTO-COMBO.md) · 🇫🇷 [fr](../fr/AUTO-COMBO.md) · 🇩🇪 [de](../de/AUTO-COMBO.md) · 🇮🇹 [it](../it/AUTO-COMBO.md) · 🇷🇺 [ru](../ru/AUTO-COMBO.md) · 🇨🇳 [zh-CN](../zh-CN/AUTO-COMBO.md) · 🇯🇵 [ja](../ja/AUTO-COMBO.md) · 🇰🇷 [ko](../ko/AUTO-COMBO.md) · 🇸🇦 [ar](../ar/AUTO-COMBO.md) · 🇮🇳 [in](../in/AUTO-COMBO.md) · 🇹🇭 [th](../th/AUTO-COMBO.md) · 🇻🇳 [vi](../vi/AUTO-COMBO.md) · 🇮🇩 [id](../id/AUTO-COMBO.md) · 🇲🇾 [ms](../ms/AUTO-COMBO.md) · 🇳🇱 [nl](../nl/AUTO-COMBO.md) · 🇵🇱 [pl](../pl/AUTO-COMBO.md) · 🇸🇪 [sv](../sv/AUTO-COMBO.md) · 🇳🇴 [no](../no/AUTO-COMBO.md) · 🇩🇰 [da](../da/AUTO-COMBO.md) · 🇫🇮 [fi](../fi/AUTO-COMBO.md) · 🇵🇹 [pt](../pt/AUTO-COMBO.md) · 🇷🇴 [ro](../ro/AUTO-COMBO.md) · 🇭🇺 [hu](../hu/AUTO-COMBO.md) · 🇧🇬 [bg](../bg/AUTO-COMBO.md) · 🇸🇰 [sk](../sk/AUTO-COMBO.md) · 🇺🇦 [uk-UA](../uk-UA/AUTO-COMBO.md) · 🇮🇱 [he](../he/AUTO-COMBO.md) · 🇵🇭 [phi](../phi/AUTO-COMBO.md)
+
+---
+
+# 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/i18n/de/CODEBASE_DOCUMENTATION.md

@@ -1,22 +1,26 @@
-# omniroute – Codebase-Dokumentation
-
-🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md)
-
-> Eine umfassende, einsteigerfreundliche Anleitung zum Multi-Provider-KI-Proxy-Router **omniroute**.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../es/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../fr/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../de/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../it/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../ru/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../ja/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../ko/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../ar/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [in](../in/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../th/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../vi/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../id/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../ms/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../nl/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../pl/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../sv/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../no/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../da/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../fi/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../pt/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../ro/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../hu/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../bg/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../sk/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../he/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../phi/CODEBASE_DOCUMENTATION.md)
 
 ---
 
-## 1. Was ist Omniroute?
+# omniroute — Codebase Documentation
 
-Omniroute ist ein **Proxy-Router**, der zwischen KI-Clients (Claude CLI, Codex, Cursor IDE usw.) und KI-Anbietern (Anthropic, Google, OpenAI, AWS, GitHub usw.) sitzt. Es löst ein großes Problem:
+🌐 **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)
 
-> **Verschiedene KI-Clients sprechen unterschiedliche „Sprachen“ (API-Formate) und unterschiedliche KI-Anbieter erwarten auch unterschiedliche „Sprachen“.** Omniroute übersetzt automatisch zwischen ihnen.
-
-Stellen Sie sich das wie einen Universalübersetzer bei den Vereinten Nationen vor: Jeder Delegierte kann jede Sprache sprechen, und der Übersetzer übersetzt sie für jeden anderen Delegierten.
+> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router.
 
 ---
 
-## 2. Architekturübersicht
+## 1. What Is omniroute?
+
+omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem:
+
+> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically.
+
+Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate.
+
+---
+
+## 2. Architecture Overview
 
 ```mermaid
 graph LR
@@ -61,20 +65,20 @@ graph LR
     H -.-> G
 ```
 
-### Grundprinzip: Hub-and-Spoke-Übersetzung
+### Core Principle: Hub-and-Spoke Translation
 
-Die gesamte Formatübersetzung erfolgt über das **OpenAI-Format als Hub**:
+All format translation passes through **OpenAI format as the hub**:
 
 ```
 Client Format → [OpenAI Hub] → Provider Format    (request)
 Provider Format → [OpenAI Hub] → Client Format    (response)
 ```
 
-Das bedeutet, dass Sie nur **N Übersetzer** (einen pro Format) statt **N²** (jedes Paar) benötigen.
+This means you only need **N translators** (one per format) instead of **N²** (every pair).
 
 ---
 
-## 3. Projektstruktur
+## 3. Project Structure
 
 ```
 omniroute/
@@ -104,22 +108,22 @@ omniroute/
 
 ---
 
-## 4. Aufschlüsselung nach Modulen
+## 4. Module-by-Module Breakdown
 
-### 4.1 Konfiguration (`open-sse/config/`)
+### 4.1 Config (`open-sse/config/`)
 
-Die **Single Source of Truth** für die gesamte Anbieterkonfiguration.
+The **single source of truth** for all provider configuration.
 
-| Datei                         | Zweck                                                                                                                                                                                                                                                           |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `constants.ts`                | `PROVIDERS`-Objekt mit Basis-URLs, OAuth-Anmeldeinformationen (Standard), Headern und Standard-Systemaufforderungen für jeden Anbieter. Definiert außerdem `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` und `SKIP_PATTERNS`.                   |
-| `credentialLoader.ts`         | Lädt externe Anmeldeinformationen von `data/provider-credentials.json` und führt sie über die fest codierten Standardeinstellungen in `PROVIDERS` zusammen. Hält Geheimnisse von der Quellcodeverwaltung fern und sorgt gleichzeitig für Abwärtskompatibilität. |
-| `providerModels.ts`           | Zentrale Modellregistrierung: Ordnet Anbieter-Aliase → Modell-IDs zu. Funktionen wie `getModels()`, `getProviderByAlias()`.                                                                                                                                     |
-| `codexInstructions.ts`        | In Codex-Anfragen eingefügte Systemanweisungen (Bearbeitungsbeschränkungen, Sandbox-Regeln, Genehmigungsrichtlinien).                                                                                                                                           |
-| `defaultThinkingSignature.ts` | Standardmäßige „denkende“ Signaturen für die Modelle Claude und Gemini.                                                                                                                                                                                         |
-| `ollamaModels.ts`             | Schemadefinition für lokale Ollama-Modelle (Name, Größe, Familie, Quantisierung).                                                                                                                                                                               |
+| File                          | Purpose                                                                                                                                                                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `constants.ts`                | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. |
+| `credentialLoader.ts`         | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility.               |
+| `providerModels.ts`           | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`.                                                                                                          |
+| `codexInstructions.ts`        | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies).                                                                                                                 |
+| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models.                                                                                                                                                               |
+| `ollamaModels.ts`             | Schema definition for local Ollama models (name, size, family, quantization).                                                                                                                                             |
 
-#### Ladevorgang für Anmeldeinformationen
+#### Credential Loading Flow
 
 ```mermaid
 flowchart TD
@@ -142,9 +146,9 @@ flowchart TD
 
 ---
 
-### 4.2 Ausführende (`open-sse/executors/`)
+### 4.2 Executors (`open-sse/executors/`)
 
-Ausführende kapseln **anbieterspezifische Logik** mithilfe des **Strategiemusters**. Jeder Executor überschreibt bei Bedarf Basismethoden.
+Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed.
 
 ```mermaid
 classDiagram
@@ -194,32 +198,32 @@ classDiagram
     BaseExecutor <|-- GithubExecutor
 ```
 
-| Testamentsvollstrecker | Anbieter                                   | Schlüsselspezialisierungen                                                                                                                      |
-| ---------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `base.ts`              | —                                          | Abstrakte Basis: URL-Erstellung, Header, Wiederholungslogik, Aktualisierung der Anmeldeinformationen                                            |
-| `default.ts`           | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generische OAuth-Token-Aktualisierung für Standardanbieter                                                                                      |
-| `antigravity.ts`       | Google Cloud-Code                          | Projekt-/Sitzungs-ID-Generierung, Multi-URL-Fallback, benutzerdefinierte Wiederholungsanalyse von Fehlermeldungen („Zurücksetzen nach 2h7m23s“) |
-| `cursor.ts`            | Cursor-IDE                                 | **Am komplexesten**: SHA-256-Prüfsummenauthentifizierung, Protobuf-Anforderungskodierung, binäres EventStream → SSE-Antwortanalyse              |
-| `codex.ts`             | OpenAI-Codex                               | Fügt Systemanweisungen ein, verwaltet Denkebenen und entfernt nicht unterstützte Parameter                                                      |
-| `gemini-cli.ts`        | Google Gemini-CLI                          | Benutzerdefinierte URL-Erstellung (`streamGenerateContent`), Google OAuth-Token-Aktualisierung                                                  |
-| `github.ts`            | GitHub-Copilot                             | Dual-Token-System (GitHub OAuth + Copilot-Token), VSCode-Header-Nachahmung                                                                      |
-| `kiro.ts`              | AWS CodeWhisperer                          | AWS EventStream-Binäranalyse, AMZN-Ereignisrahmen, Token-Schätzung                                                                              |
-| `index.ts`             | —                                          | Factory: ordnet Anbieternamen → Executor-Klasse zu, mit Standard-Fallback                                                                       |
+| Executor         | Provider                                   | Key Specializations                                                                                                 |
+| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `base.ts`        | —                                          | Abstract base: URL building, headers, retry logic, credential refresh                                               |
+| `default.ts`     | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers                                                                  |
+| `antigravity.ts` | Google Cloud Code                          | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") |
+| `cursor.ts`      | Cursor IDE                                 | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing       |
+| `codex.ts`       | OpenAI Codex                               | Injects system instructions, manages thinking levels, removes unsupported parameters                                |
+| `gemini-cli.ts`  | Google Gemini CLI                          | Custom URL building (`streamGenerateContent`), Google OAuth token refresh                                           |
+| `github.ts`      | GitHub Copilot                             | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking                                           |
+| `kiro.ts`        | AWS CodeWhisperer                          | AWS EventStream binary parsing, AMZN event frames, token estimation                                                 |
+| `index.ts`       | —                                          | Factory: maps provider name → executor class, with default fallback                                                 |
 
 ---
 
-### 4.3 Handler (`open-sse/handlers/`)
+### 4.3 Handlers (`open-sse/handlers/`)
 
-Die **Orchestrierungsebene** – koordiniert Übersetzung, Ausführung, Streaming und Fehlerbehandlung.
+The **orchestration layer** — coordinates translation, execution, streaming, and error handling.
 
-| Datei                 | Zweck                                                                                                                                                                                                                                                      |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `chatCore.ts`         | **Zentraler Orchestrator** (~600 Leitungen). Verarbeitet den gesamten Anforderungslebenszyklus: Formaterkennung → Übersetzung → Executor-Versand → Streaming-/Nicht-Streaming-Antwort → Token-Aktualisierung → Fehlerbehandlung → Nutzungsprotokollierung. |
-| `responsesHandler.ts` | Adapter für die Antwort-API von OpenAI: Konvertiert das Antwortformat → Chat-Abschlüsse → sendet an `chatCore` → konvertiert SSE zurück in das Antwortformat.                                                                                              |
-| `embeddings.ts`       | Handler für die Einbettungsgenerierung: Löst Einbettungsmodell → Anbieter auf, sendet an die Anbieter-API und gibt eine OpenAI-kompatible Einbettungsantwort zurück. Unterstützt mehr als 6 Anbieter.                                                      |
-| `imageGeneration.ts`  | Bildgenerierungs-Handler: Löst Bildmodell → Anbieter auf, unterstützt OpenAI-kompatible, Gemini-Image- (Antigravity) und Fallback-Modi (Nebius). Gibt Base64- oder URL-Bilder zurück.                                                                      |
+| File                  | Purpose                                                                                                                                                                                                                |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chatCore.ts`         | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. |
+| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format.                                                                        |
+| `embeddings.ts`       | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers.                                                    |
+| `imageGeneration.ts`  | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images.                                          |
 
-#### Anforderungslebenszyklus (chatCore.ts)
+#### Request Lifecycle (chatCore.ts)
 
 ```mermaid
 sequenceDiagram
@@ -258,28 +262,28 @@ sequenceDiagram
 
 ---
 
-### 4.4 Dienste (`open-sse/services/`)
+### 4.4 Services (`open-sse/services/`)
 
-Geschäftslogik, die die Handler und Ausführenden unterstützt.
+Business logic that supports the handlers and executors.
 
-| Datei                | Zweck                                                                                                                                                                                                                                                                                                                                                                                         |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `provider.ts`        | **Formaterkennung** (`detectFormat`): Analysiert die Struktur des Anfragetexts, um Claude/OpenAI/Gemini/Antigravity/Responses-Formate zu identifizieren (einschließlich `max_tokens`-Heuristik für Claude). Außerdem: URL-Erstellung, Header-Erstellung, Denken an die Konfigurationsnormalisierung. Unterstützt die dynamischen Anbieter `openai-compatible-*` und `anthropic-compatible-*`. |
-| `model.ts`           | Parsen von Modellzeichenfolgen (`claude/model-name` → `{provider: "claude", model: "model-name"}`), Alias-Auflösung mit Kollisionserkennung, Eingabebereinigung (weist Pfaddurchquerung/Kontrollzeichen zurück) und Auflösung von Modellinformationen mit asynchroner Alias-Getter-Unterstützung.                                                                                             |
-| `accountFallback.ts` | Umgang mit Ratenlimits: exponentielles Backoff (1 s → 2 s → 4 s → max. 2 min), Verwaltung der Kontoabklingzeit, Fehlerklassifizierung (welche Fehler einen Fallback auslösen und welche nicht).                                                                                                                                                                                               |
-| `tokenRefresh.ts`    | OAuth-Token-Aktualisierung für **jeden Anbieter**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot Dual-Token), Kiro (AWS SSO OIDC + Social Auth). Beinhaltet In-Flight-Promise-Deduplizierungs-Cache und Wiederholungsversuche mit exponentiellem Backoff.                                                                                                 |
-| `combo.ts`           | **Combo-Modelle**: Ketten von Fallback-Modellen. Wenn Modell A mit einem Fallback-fähigen Fehler ausfällt, versuchen Sie es mit Modell B, dann mit C usw. Gibt tatsächliche Upstream-Statuscodes zurück.                                                                                                                                                                                      |
-| `usage.ts`           | Ruft Kontingent-/Nutzungsdaten von Anbieter-APIs ab (GitHub Copilot-Kontingente, Antigravity-Modellkontingente, Codex-Ratenbegrenzungen, Kiro-Nutzungsaufschlüsselungen, Claude-Einstellungen).                                                                                                                                                                                               |
-| `accountSelector.ts` | Intelligente Kontoauswahl mit Bewertungsalgorithmus: Berücksichtigt Priorität, Gesundheitsstatus, Round-Robin-Position und Cooldown-Status, um für jede Anfrage das optimale Konto auszuwählen.                                                                                                                                                                                               |
-| `contextManager.ts`  | Lebenszyklusverwaltung des Anforderungskontexts: Erstellt und verfolgt Kontextobjekte pro Anforderung mit Metadaten (Anforderungs-ID, Zeitstempel, Anbieterinformationen) zum Debuggen und Protokollieren.                                                                                                                                                                                    |
-| `ipFilter.ts`        | IP-basierte Zugriffskontrolle: Unterstützt die Modi „Zulassungsliste“ und „Blockliste“. Validiert die Client-IP anhand konfigurierter Regeln, bevor API-Anfragen verarbeitet werden.                                                                                                                                                                                                          |
-| `sessionManager.ts`  | Sitzungsverfolgung mit Client-Fingerprinting: Verfolgt aktive Sitzungen mithilfe gehashter Client-IDs, überwacht die Anzahl der Anfragen und stellt Sitzungsmetriken bereit.                                                                                                                                                                                                                  |
-| `signatureCache.ts`  | Anforderungssignaturbasierter Deduplizierungscache: Verhindert doppelte Anforderungen, indem aktuelle Anforderungssignaturen zwischengespeichert werden und zwischengespeicherte Antworten für identische Anforderungen innerhalb eines Zeitfensters zurückgegeben werden.                                                                                                                    |
-| `systemPrompt.ts`    | Globale System-Prompt-Injektion: Stellt allen Anfragen eine konfigurierbare System-Prompt voran oder hängt sie an, mit Kompatibilitätsbehandlung pro Anbieter.                                                                                                                                                                                                                                |
-| `thinkingBudget.ts`  | Verwaltung des Reasoning-Token-Budgets: Unterstützt Passthrough-, Auto- (Strip-Thinking-Konfiguration), benutzerdefinierte (festes Budget) und adaptive (komplexitätsskalierte) Modi zur Steuerung von Thinking-/Argument-Tokens.                                                                                                                                                             |
-| `wildcardRouter.ts`  | Routing von Wildcard-Modellmustern: Löst Wildcard-Muster (z. B. `*/claude-*`) basierend auf Verfügbarkeit und Priorität in konkrete Anbieter/Modell-Paare auf.                                                                                                                                                                                                                                |
+| File                 | Purpose                                                                                                                                                                                                                                                                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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.                                                                       |
+| `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.                                                                                                                                                              |
+| `contextManager.ts`  | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging.                                                                                                                                                                  |
+| `ipFilter.ts`        | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests.                                                                                                                                                                                          |
+| `sessionManager.ts`  | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics.                                                                                                                                                                            |
+| `signatureCache.ts`  | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window.                                                                                                                                              |
+| `systemPrompt.ts`    | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling.                                                                                                                                                                                            |
+| `thinkingBudget.ts`  | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens.                                                                                                                                        |
+| `wildcardRouter.ts`  | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority.                                                                                                                                                                                   |
 
-#### Token-Aktualisierungsdeduplizierung
+#### Token Refresh Deduplication
 
 ```mermaid
 sequenceDiagram
@@ -300,7 +304,7 @@ sequenceDiagram
     Cache->>Cache: Delete cache entry
 ```
 
-#### Konto-Fallback-Zustandsmaschine
+#### Account Fallback State Machine
 
 ```mermaid
 stateDiagram-v2
@@ -325,7 +329,7 @@ stateDiagram-v2
     }
 ```
 
-#### Combo-Modellkette
+#### Combo Model Chain
 
 ```mermaid
 flowchart LR
@@ -344,11 +348,11 @@ flowchart LR
 
 ---
 
-### 4.5 Übersetzer (`open-sse/translator/`)
+### 4.5 Translator (`open-sse/translator/`)
 
-Die **Formatübersetzungs-Engine** verwendet ein selbstregistrierendes Plugin-System.
+The **format translation engine** using a self-registering plugin system.
 
-#### Architektur
+#### Architecture
 
 ```mermaid
 graph TD
@@ -374,15 +378,15 @@ graph TD
     end
 ```
 
-| Verzeichnis  | Dateien      | Beschreibung                                                                                                                                                                                                                                                                                                  |
-| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request/`   | 8 Übersetzer | Konvertieren Sie Anforderungstexte zwischen Formaten. Jede Datei registriert sich beim Import über `register(from, to, fn)` selbst.                                                                                                                                                                           |
-| `response/`  | 7 Übersetzer | Konvertieren Sie Streaming-Antwortblöcke zwischen Formaten. Behandelt SSE-Ereignistypen, Denkblockaden und Toolaufrufe.                                                                                                                                                                                       |
-| `helpers/`   | 6 Helfer     | Gemeinsame Dienstprogramme: `claudeHelper` (Extraktion von Systemeingabeaufforderungen, Thinking-Konfiguration), `geminiHelper` (Zuordnung von Teilen/Inhalten), `openaiHelper` (Formatfilterung), `toolCallHelper` (ID-Generierung, Injektion fehlender Antworten), `maxTokensHelper`, `responsesApiHelper`. |
-| `index.ts`   | —            | Übersetzungs-Engine: `translateRequest()`, `translateResponse()`, Statusverwaltung, Registrierung.                                                                                                                                                                                                            |
-| `formats.ts` | —            | Formatkonstanten: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`.                                                                                                                                                                                                          |
+| Directory    | Files         | Description                                                                                                                                                                                                                                                      |
+| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request/`   | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import.                                                                                                                                                         |
+| `response/`  | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls.                                                                                                                                                         |
+| `helpers/`   | 6 helpers     | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. |
+| `index.ts`   | —             | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry.                                                                                                                                                                     |
+| `formats.ts` | —             | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`.                                                                                                                                                             |
 
-#### Schlüsseldesign: Selbstregistrierende Plugins
+#### Key Design: Self-Registering Plugins
 
 ```javascript
 // Each translator file calls register() on import:
@@ -397,17 +401,17 @@ import "./request/claude-to-openai.js"; // ← self-registers
 
 ### 4.6 Utils (`open-sse/utils/`)
 
-| Datei              | Zweck                                                                                                                                                                                                                                                                                                                   |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `error.ts`         | Erstellung von Fehlerantworten (OpenAI-kompatibles Format), Upstream-Fehleranalyse, Antigravity-Wiederholungszeit-Extraktion aus Fehlermeldungen, SSE-Fehler-Streaming.                                                                                                                                                 |
-| `stream.ts`        | **SSE Transform Stream** – die zentrale Streaming-Pipeline. Zwei Modi: `TRANSLATE` (Vollformatübersetzung) und `PASSTHROUGH` (Nutzung normalisieren + extrahieren). Verarbeitet Chunk-Pufferung, Nutzungsschätzung und Inhaltslängenverfolgung. Pro-Stream-Encoder-/Decoder-Instanzen vermeiden den gemeinsamen Status. |
-| `streamHelpers.ts` | Low-Level-SSE-Dienstprogramme: `parseSSELine` (leerzeichentolerant), `hasValuableContent` (filtert leere Blöcke für OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (formatbewusste SSE-Serialisierung mit `perf_metrics`-Bereinigung).                                                                              |
-| `usageTracking.ts` | Extraktion der Token-Nutzung aus jedem Format (Claude/OpenAI/Gemini/Responses), Schätzung mit separaten Zeichen-pro-Token-Verhältnissen für Tools/Nachrichten, Pufferzugabe (2000 Token-Sicherheitsspielraum), formatspezifische Feldfilterung, Konsolenprotokollierung mit ANSI-Farben.                                |
-| `requestLogger.ts` | Dateibasierte Anforderungsprotokollierung (Opt-in über `ENABLE_REQUEST_LOGS=true`). Erstellt Sitzungsordner mit nummerierten Dateien: `1_req_client.json` → `7_res_client.txt`. Alle E/A erfolgen asynchron (Fire-and-Forget). Maskiert sensible Header.                                                                |
-| `bypassHandler.ts` | Fängt bestimmte Muster von Claude CLI ab (Titelextraktion, Aufwärmen, Zählung) und gibt gefälschte Antworten zurück, ohne einen Anbieter anzurufen. Unterstützt sowohl Streaming als auch Nicht-Streaming. Absichtlich auf den Claude-CLI-Bereich beschränkt.                                                           |
-| `networkProxy.ts`  | Löst die ausgehende Proxy-URL für einen bestimmten Anbieter mit der Priorität auf: anbieterspezifische Konfiguration → globale Konfiguration → Umgebungsvariablen (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Unterstützt `NO_PROXY`-Ausschlüsse. Speichert die Konfiguration 30 Sekunden lang im Cache.                  |
+| File               | Purpose                                                                                                                                                                                                                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `error.ts`         | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming.                                                                                                                              |
+| `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.                                                              |
+| `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.                                                  |
 
-#### SSE-Streaming-Pipeline
+#### SSE Streaming Pipeline
 
 ```mermaid
 flowchart TD
@@ -429,7 +433,7 @@ flowchart TD
     style M fill:#9f9,stroke:#333
 ```
 
-#### Logger-Sitzungsstruktur anfordern
+#### Request Logger Session Structure
 
 ```
 logs/
@@ -447,109 +451,109 @@ logs/
 
 ---
 
-### 4.7 Anwendungsschicht (`src/`)
+### 4.7 Application Layer (`src/`)
 
-| Verzeichnis   | Zweck                                                                               |
-| ------------- | ----------------------------------------------------------------------------------- |
-| `src/app/`    | Web-Benutzeroberfläche, API-Routen, Express-Middleware, OAuth-Callback-Handler      |
-| `src/lib/`    | Datenbankzugriff (`localDb.ts`, `usageDb.ts`), Authentifizierung, gemeinsam genutzt |
-| `src/mitm/`   | Man-in-the-Middle-Proxy-Dienstprogramme zum Abfangen des Provider-Verkehrs          |
-| `src/models/` | Datenbankmodelldefinitionen                                                         |
-| `src/shared/` | Wrapper um Open-SSE-Funktionen (Anbieter, Stream, Fehler usw.)                      |
-| `src/sse/`    | SSE-Endpunkthandler, die die open-sse-Bibliothek mit Express-Routen verbinden       |
-| `src/store/`  | Anwendungsstatusverwaltung                                                          |
+| Directory     | Purpose                                                                |
+| ------------- | ---------------------------------------------------------------------- |
+| `src/app/`    | Web UI, API routes, Express middleware, OAuth callback handlers        |
+| `src/lib/`    | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared   |
+| `src/mitm/`   | Man-in-the-middle proxy utilities for intercepting provider traffic    |
+| `src/models/` | Database model definitions                                             |
+| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.)     |
+| `src/sse/`    | SSE endpoint handlers that wire the open-sse library to Express routes |
+| `src/store/`  | Application state management                                           |
 
-#### Bemerkenswerte API-Routen
+#### Notable API Routes
 
-| Route                                         | Methoden        | Zweck                                                                                                   |
-| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------- |
-| `/api/provider-models`                        | GET/POST/DELETE | CRUD für benutzerdefinierte Modelle pro Anbieter                                                        |
-| `/api/models/catalog`                         | GET             | Aggregierter Katalog aller Modelle (Chat, Einbettung, Bild, benutzerdefiniert), gruppiert nach Anbieter |
-| `/api/settings/proxy`                         | GET/PUT/DELETE  | Hierarchische ausgehende Proxy-Konfiguration (`global/providers/combos/keys`)                           |
-| `/api/settings/proxy/test`                    | POST            | Validiert die Proxy-Konnektivität und gibt öffentliche IP/Latenz zurück                                 |
-| `/v1/providers/[provider]/chat/completions`   | POST            | Dedizierte Chat-Abschlüsse pro Anbieter mit Modellvalidierung                                           |
-| `/v1/providers/[provider]/embeddings`         | POST            | Dedizierte Einbettungen pro Anbieter mit Modellvalidierung                                              |
-| `/v1/providers/[provider]/images/generations` | POST            | Dedizierte Image-Generierung pro Anbieter mit Modellvalidierung                                         |
-| `/api/settings/ip-filter`                     | GET/PUT         | Verwaltung von IP-Zulassungs-/Blockierungslisten                                                        |
-| `/api/settings/thinking-budget`               | GET/PUT         | Konfiguration des Reasoning-Token-Budgets (Passthrough/Auto/Benutzerdefiniert/Adaptiv)                  |
-| `/api/settings/system-prompt`                 | GET/PUT         | Globale System-Prompt-Injektion für alle Anfragen                                                       |
-| `/api/sessions`                               | GET             | Aktive Sitzungsverfolgung und Metriken                                                                  |
-| `/api/rate-limits`                            | GET             | Status der Ratenbegrenzung pro Konto                                                                    |
+| Route                                         | Methods         | Purpose                                                                               |
+| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
+| `/api/provider-models`                        | GET/POST/DELETE | CRUD for custom models per provider                                                   |
+| `/api/models/catalog`                         | GET             | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider |
+| `/api/settings/proxy`                         | GET/PUT/DELETE  | Hierarchical outbound proxy configuration (`global/providers/combos/keys`)            |
+| `/api/settings/proxy/test`                    | POST            | Validates proxy connectivity and returns public IP/latency                            |
+| `/v1/providers/[provider]/chat/completions`   | POST            | Dedicated per-provider chat completions with model validation                         |
+| `/v1/providers/[provider]/embeddings`         | POST            | Dedicated per-provider embeddings with model validation                               |
+| `/v1/providers/[provider]/images/generations` | POST            | Dedicated per-provider image generation with model validation                         |
+| `/api/settings/ip-filter`                     | GET/PUT         | IP allowlist/blocklist management                                                     |
+| `/api/settings/thinking-budget`               | GET/PUT         | Reasoning token budget configuration (passthrough/auto/custom/adaptive)               |
+| `/api/settings/system-prompt`                 | GET/PUT         | Global system prompt injection for all requests                                       |
+| `/api/sessions`                               | GET             | Active session tracking and metrics                                                   |
+| `/api/rate-limits`                            | GET             | Per-account rate limit status                                                         |
 
 ---
 
-## 5. Wichtige Designmuster
+## 5. Key Design Patterns
 
-### 5.1 Hub-and-Spoke-Übersetzung
+### 5.1 Hub-and-Spoke Translation
 
-Alle Formate werden über das **OpenAI-Format als Hub** übersetzt. Für das Hinzufügen eines neuen Anbieters ist nur das Schreiben von **einem Paar** Übersetzern (zu/von OpenAI) erforderlich, nicht von N Paaren.
+All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs.
 
-### 5.2 Executor-Strategiemuster
+### 5.2 Executor Strategy Pattern
 
-Jeder Anbieter verfügt über eine dedizierte Executor-Klasse, die von `BaseExecutor` erbt. Die Factory in `executors/index.ts` wählt zur Laufzeit die richtige aus.
+Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime.
 
-### 5.3 Selbstregistrierendes Plugin-System
+### 5.3 Self-Registering Plugin System
 
-Übersetzermodule registrieren sich beim Import über `register()`. Beim Hinzufügen eines neuen Übersetzers wird lediglich eine Datei erstellt und importiert.
+Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it.
 
-### 5.4 Konto-Fallback mit exponentiellem Backoff
+### 5.4 Account Fallback with Exponential Backoff
 
-Wenn ein Anbieter 429/401/500 zurückgibt, kann das System zum nächsten Konto wechseln und dabei exponentielle Abklingzeiten anwenden (1 Sek. → 2 Sek. → 4 Sek. → max. 2 Min.).
+When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min).
 
-### 5.5 Combo-Modellketten
+### 5.5 Combo Model Chains
 
-Eine „Kombination“ gruppiert mehrere `provider/model`-Strings. Wenn der erste fehlschlägt, wird automatisch auf den nächsten zurückgegriffen.
+A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically.
 
-### 5.6 Stateful Streaming-Übersetzung
+### 5.6 Stateful Streaming Translation
 
-Die Antwortübersetzung behält den Status über SSE-Chunks hinweg bei (Nachverfolgung von Denkblöcken, Akkumulation von Toolaufrufen, Indizierung von Inhaltsblöcken) über den `initState()`-Mechanismus.
+Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism.
 
-### 5.7 Nutzungssicherheitspuffer
+### 5.7 Usage Safety Buffer
 
-Der gemeldeten Nutzung wird ein 2000-Token-Puffer hinzugefügt, um zu verhindern, dass Clients aufgrund von Overhead durch Systemeingabeaufforderungen und Formatübersetzung die Kontextfenstergrenzen erreichen.
+A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation.
 
 ---
 
-## 6. Unterstützte Formate
+## 6. Supported Formats
 
-| Formatieren            | Richtung      | Bezeichner         |
-| ---------------------- | ------------- | ------------------ |
-| OpenAI-Chat-Abschlüsse | Quelle + Ziel | `openai`           |
-| OpenAI Responses API   | Quelle + Ziel | `openai-responses` |
-| Anthropischer Claude   | Quelle + Ziel | `claude`           |
-| Google Gemini          | Quelle + Ziel | `gemini`           |
-| Google Gemini-CLI      | Nur Ziel      | `gemini-cli`       |
-| Antigravitation        | Quelle + Ziel | `antigravity`      |
-| AWS Kiro               | Nur Ziel      | `kiro`             |
-| Cursor                 | Nur Ziel      | `cursor`           |
+| Format                  | Direction       | Identifier         |
+| ----------------------- | --------------- | ------------------ |
+| OpenAI Chat Completions | source + target | `openai`           |
+| OpenAI Responses API    | source + target | `openai-responses` |
+| Anthropic Claude        | source + target | `claude`           |
+| Google Gemini           | source + target | `gemini`           |
+| Google Gemini CLI       | target only     | `gemini-cli`       |
+| Antigravity             | source + target | `antigravity`      |
+| AWS Kiro                | target only     | `kiro`             |
+| Cursor                  | target only     | `cursor`           |
 
 ---
 
-## 7. Unterstützte Anbieter
+## 7. Supported Providers
 
-| Anbieter                 | Authentifizierungsmethode   | Testamentsvollstrecker | Wichtige Anmerkungen                                        |
-| ------------------------ | --------------------------- | ---------------------- | ----------------------------------------------------------- |
-| Anthropischer Claude     | API-Schlüssel oder OAuth    | Standard               | Verwendet den Header `x-api-key`                            |
-| Google Gemini            | API-Schlüssel oder OAuth    | Standard               | Verwendet den Header `x-goog-api-key`                       |
-| Google Gemini-CLI        | OAuth                       | GeminiCLI              | Verwendet den Endpunkt `streamGenerateContent`              |
-| Antigravitation          | OAuth                       | Antigravitation        | Multi-URL-Fallback, benutzerdefinierte Wiederholungsanalyse |
-| OpenAI                   | API-Schlüssel               | Standard               | Standard Bearer-Authentifizierung                           |
-| Kodex                    | OAuth                       | Kodex                  | Fügt Systemanweisungen ein, verwaltet das Denken            |
-| GitHub-Copilot           | OAuth + Copilot-Token       | Github                 | Dual-Token, VSCode-Header-Nachahmung                        |
-| Kiro (AWS)               | AWS SSO OIDC oder Social    | Kiro                   | Binäres EventStream-Parsen                                  |
-| Cursor-IDE               | Prüfsummenauthentifizierung | Cursor                 | Protobuf-Kodierung, SHA-256-Prüfsummen                      |
-| Qwen                     | OAuth                       | Standard               | Standardauthentifizierung                                   |
-| iFlow                    | OAuth (Basic + Bearer)      | Standard               | Dual-Auth-Header                                            |
-| OpenRouter               | API-Schlüssel               | Standard               | Standard Bearer-Authentifizierung                           |
-| GLM, Kimi, MiniMax       | API-Schlüssel               | Standard               | Claude-kompatibel, verwenden Sie `x-api-key`                |
-| `openai-compatible-*`    | API-Schlüssel               | Standard               | Dynamisch: jeder OpenAI-kompatible Endpunkt                 |
-| `anthropic-compatible-*` | API-Schlüssel               | Standard               | Dynamisch: jeder Claude-kompatible Endpunkt                 |
+| Provider                 | Auth Method            | Executor    | Key Notes                                     |
+| ------------------------ | ---------------------- | ----------- | --------------------------------------------- |
+| Anthropic Claude         | API key or OAuth       | Default     | Uses `x-api-key` header                       |
+| Google Gemini            | API key or OAuth       | Default     | Uses `x-goog-api-key` header                  |
+| Google Gemini CLI        | OAuth                  | GeminiCLI   | Uses `streamGenerateContent` endpoint         |
+| Antigravity              | OAuth                  | Antigravity | Multi-URL fallback, custom retry parsing      |
+| OpenAI                   | API key                | Default     | Standard Bearer auth                          |
+| Codex                    | OAuth                  | Codex       | Injects system instructions, manages thinking |
+| GitHub Copilot           | OAuth + Copilot token  | Github      | Dual token, VSCode header mimicking           |
+| 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                              |
+| 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       |
+| `anthropic-compatible-*` | API key                | Default     | Dynamic: any Claude-compatible endpoint       |
 
 ---
 
-## 8. Zusammenfassung des Datenflusses
+## 8. Data Flow Summary
 
-### Streaming-Anfrage
+### Streaming Request
 
 ```mermaid
 flowchart LR
@@ -566,7 +570,7 @@ flowchart LR
     K --> L["logUsage()\nsaveRequestUsage()"]
 ```
 
-### Nicht-Streaming-Anfrage
+### Non-Streaming Request
 
 ```mermaid
 flowchart LR
@@ -577,7 +581,7 @@ flowchart LR
     E --> F["Return JSON\nresponse"]
 ```
 
-### Bypass-Flow (Claude CLI)
+### Bypass Flow (Claude CLI)
 
 ```mermaid
 flowchart LR

docs/i18n/de/FEATURES.md

@@ -1,77 +1,148 @@
-# OmniRoute – Dashboard-Funktionsgalerie
-
-🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md)
-
-Visuelle Anleitung zu jedem Abschnitt des OmniRoute-Dashboards.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/FEATURES.md) · 🇪🇸 [es](../es/FEATURES.md) · 🇫🇷 [fr](../fr/FEATURES.md) · 🇩🇪 [de](../de/FEATURES.md) · 🇮🇹 [it](../it/FEATURES.md) · 🇷🇺 [ru](../ru/FEATURES.md) · 🇨🇳 [zh-CN](../zh-CN/FEATURES.md) · 🇯🇵 [ja](../ja/FEATURES.md) · 🇰🇷 [ko](../ko/FEATURES.md) · 🇸🇦 [ar](../ar/FEATURES.md) · 🇮🇳 [in](../in/FEATURES.md) · 🇹🇭 [th](../th/FEATURES.md) · 🇻🇳 [vi](../vi/FEATURES.md) · 🇮🇩 [id](../id/FEATURES.md) · 🇲🇾 [ms](../ms/FEATURES.md) · 🇳🇱 [nl](../nl/FEATURES.md) · 🇵🇱 [pl](../pl/FEATURES.md) · 🇸🇪 [sv](../sv/FEATURES.md) · 🇳🇴 [no](../no/FEATURES.md) · 🇩🇰 [da](../da/FEATURES.md) · 🇫🇮 [fi](../fi/FEATURES.md) · 🇵🇹 [pt](../pt/FEATURES.md) · 🇷🇴 [ro](../ro/FEATURES.md) · 🇭🇺 [hu](../hu/FEATURES.md) · 🇧🇬 [bg](../bg/FEATURES.md) · 🇸🇰 [sk](../sk/FEATURES.md) · 🇺🇦 [uk-UA](../uk-UA/FEATURES.md) · 🇮🇱 [he](../he/FEATURES.md) · 🇵🇭 [phi](../phi/FEATURES.md)
 
 ---
 
-## 🔌 Anbieter
+# OmniRoute — Dashboard Features Gallery
 
-Verwalten Sie KI-Anbieterverbindungen: OAuth-Anbieter (Claude Code, Codex, Gemini CLI), API-Schlüsselanbieter (Groq, DeepSeek, OpenRouter) und kostenlose Anbieter (iFlow, Qwen, Kiro).
+🌐 **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)
+
+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).
+
+- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` (free "Light usage" tier); use `ollamacloud/<model>` prefix
 
 ![Providers Dashboard](screenshots/01-providers.png)
 
 ---
 
-## 🎨 Kombinationen
+## 🎨 Combos
 
-Erstellen Sie Modell-Routing-Kombinationen mit 6 Strategien: Fill-First, Round-Robin, Power-of-Two-Choices, Random, Least-Used und Cost-Optimized. Jede Combo verkettet mehrere Modelle mit automatischem Fallback.
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
 
 ![Combos Dashboard](screenshots/02-combos.png)
 
 ---
 
-## 📊 Analytik
+## 📊 Analytics
 
-Umfassende Nutzungsanalysen mit Token-Verbrauch, Kostenschätzungen, Aktivitäts-Heatmaps, wöchentlichen Verteilungsdiagrammen und Aufschlüsselungen pro Anbieter.
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
 
 ![Analytics Dashboard](screenshots/03-analytics.png)
 
 ---
 
-## 🏥 Systemgesundheit
+## 🏥 System Health
 
-Echtzeitüberwachung: Betriebszeit, Speicher, Version, Latenzperzentile (p50/p95/p99), Cache-Statistiken und Leistungsschalterzustände des Anbieters.
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
 
 ![Health Dashboard](screenshots/04-health.png)
 
 ---
 
-## 🔧 Übersetzerspielplatz
+## 🔧 Translator Playground
 
-Vier Modi zum Debuggen von API-Übersetzungen: **Playground** (Formatkonverter), **Chat Tester** (Live-Anfragen), **Test Bench** (Batch-Tests) und **Live Monitor** (Echtzeit-Stream).
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
 
 ![Translator Playground](screenshots/05-translator.png)
 
 ---
 
-## ⚙️ Einstellungen
+## 🎮 Model Playground _(v2.0.9+)_
 
-Allgemeine Einstellungen, Systemspeicher, Backup-Management (Datenbank exportieren/importieren), Erscheinungsbild (Dunkel-/Hellmodus), Sicherheit (einschließlich API-Endpunktschutz und benutzerdefinierter Anbieterblockierung), Routing, Ausfallsicherheit und erweiterte Konfiguration.
+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
+
+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
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
 
 ![Settings Dashboard](screenshots/06-settings.png)
 
 ---
 
-## 🔧 CLI-Tools
+## 🔧 CLI Tools
 
-Ein-Klick-Konfiguration für KI-Codierungstools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code und 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)
 
 ---
 
-## 📝 Protokolle anfordern
+## 🤖 CLI Agents _(v2.0.11+)_
 
-Echtzeit-Anfrageprotokollierung mit Filterung nach Anbieter, Modell, Konto und API-Schlüssel. Zeigt Statuscodes, Token-Nutzung, Latenz und Antwortdetails an.
+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
+
+---
+
+## 🖼️ 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.
 
 ![Usage Logs](screenshots/08-usage.png)
 
 ---
 
-## 🌐 API-Endpunkt
+## 🌐 API Endpoint
 
-Ihr einheitlicher API-Endpunkt mit Aufschlüsselung der Funktionen: Chat-Abschlüsse, Einbettungen, Bildgenerierung, Reranking, Audiotranskription und registrierte API-Schlüssel.
+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. 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)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/de/MCP-SERVER.md

@@ -0,0 +1,87 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/MCP-SERVER.md) · 🇪🇸 [es](../es/MCP-SERVER.md) · 🇫🇷 [fr](../fr/MCP-SERVER.md) · 🇩🇪 [de](../de/MCP-SERVER.md) · 🇮🇹 [it](../it/MCP-SERVER.md) · 🇷🇺 [ru](../ru/MCP-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/MCP-SERVER.md) · 🇯🇵 [ja](../ja/MCP-SERVER.md) · 🇰🇷 [ko](../ko/MCP-SERVER.md) · 🇸🇦 [ar](../ar/MCP-SERVER.md) · 🇮🇳 [in](../in/MCP-SERVER.md) · 🇹🇭 [th](../th/MCP-SERVER.md) · 🇻🇳 [vi](../vi/MCP-SERVER.md) · 🇮🇩 [id](../id/MCP-SERVER.md) · 🇲🇾 [ms](../ms/MCP-SERVER.md) · 🇳🇱 [nl](../nl/MCP-SERVER.md) · 🇵🇱 [pl](../pl/MCP-SERVER.md) · 🇸🇪 [sv](../sv/MCP-SERVER.md) · 🇳🇴 [no](../no/MCP-SERVER.md) · 🇩🇰 [da](../da/MCP-SERVER.md) · 🇫🇮 [fi](../fi/MCP-SERVER.md) · 🇵🇹 [pt](../pt/MCP-SERVER.md) · 🇷🇴 [ro](../ro/MCP-SERVER.md) · 🇭🇺 [hu](../hu/MCP-SERVER.md) · 🇧🇬 [bg](../bg/MCP-SERVER.md) · 🇸🇰 [sk](../sk/MCP-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/MCP-SERVER.md) · 🇮🇱 [he](../he/MCP-SERVER.md) · 🇵🇭 [phi](../phi/MCP-SERVER.md)
+
+---
+
+# 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                 |
+| `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/i18n/de/README.md

@@ -20,7 +20,7 @@ _Ihr universeller API-Proxy – ein Endpunkt, mehr als 36 Anbieter, keine Ausfal
 
 </div>
 
-🌐 **Verfügbar in:** 🇺🇸 [Englisch](README.md) | 🇧🇷 [Português (Brasilien)](README.pt-BR.md) | 🇪🇸 [Español](README.es.md) | 🇫🇷 [Français](README.fr.md) | 🇮🇹 [Italienisch](README.it.md) | 🇷🇺 [Русский](README.ru.md) | 🇨🇳 [中文 (简体)](README.zh-CN.md) | 🇩🇪 [Deutsch](README.de.md) | 🇮🇳 [हिन्दी](README.in.md) | 🇹🇭 [ไทย](README.th.md) | 🇺🇦 [Українська](README.uk-UA.md) | 🇸🇦 [العربية](README.ar.md) | 🇯🇵 [日本語](README.ja.md) | 🇻🇳 [Tiếng Việt](README.vi.md) | 🇧🇬 [Български](README.bg.md) | 🇩🇰 [Dänisch](README.da.md) | 🇫🇮 [Suomi](README.fi.md) | 🇮🇱 [עברית](README.he.md) | 🇭🇺 [Magyar](README.hu.md) | 🇮🇩 [Bahasa Indonesia](README.id.md) | 🇰🇷 [한국어](README.ko.md) | 🇲🇾 [Bahasa Melayu](README.ms.md) | 🇳🇱 [Niederlande](README.nl.md) | 🇳🇴 [Norsk](README.no.md) | 🇵🇹 [Português (Portugal)](README.pt.md) | 🇷🇴 [Română](README.ro.md) | 🇵🇱 [Polski](README.pl.md) | 🇸🇰 [Slovenčina](README.sk.md) | 🇸🇪 [Svenska](README.sv.md) | 🇵🇭 [Philippinisch](README.phi.md)
+🌐 **Verfügbar in:** 🇺🇸 [Englisch](../../README.md) | 🇧🇷 [Português (Brasilien)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italienisch](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dänisch](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Niederlande](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Philippinisch](../phi/README.md)
 
 ---
 
@@ -253,6 +253,7 @@ Nicht jeder kann 20–200 $/Monat für KI-Abonnements bezahlen. Studenten, Entwi
 **So löst OmniRoute das Problem:**
 
 - **Integrierte kostenlose Anbieter** – Native Unterstützung für 100 % kostenlose Anbieter: iFlow (8 unbegrenzte Modelle), Qwen (3 unbegrenzte Modelle), Kiro (Claude kostenlos), Gemini CLI (180.000/Monat kostenlos)
+- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/<model>` prefix
 - **Nur kostenlose Combos** – Kette `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/Monat ohne Ausfallzeit
 - **NVIDIA NIM Free Credits** – 1000 kostenlose Credits integriert
 - **Kostenoptimierte Strategie** – Routing-Strategie, die automatisch den günstigsten verfügbaren Anbieter auswählt
@@ -393,7 +394,7 @@ KI ist nicht nur der Abschluss eines Chats. Entwickler müssen Bilder generieren
 - **Text-zu-Video** – `/v1/videos/generations` – ComfyUI (AnimateDiff, SVD) und SD WebUI
 - **Text-zu-Musik** – `/v1/music/generations` – ComfyUI (Stable Audio Open, MusicGen)
 - **Audiotranskription** – `/v1/audio/transcriptions` – Whisper + Nvidia NIM, HuggingFace, Qwen3
-- **Text-to-Speech** – `/v1/audio/speech` – ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, + bestehende Anbieter
+- **Text-to-Speech** – `/v1/audio/speech` – ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + bestehende Anbieter
 - **Moderationen** – `/v1/moderations` – Überprüfung der Inhaltssicherheit
 - **Neueinstufung** – `/v1/rerank` – Neueinstufung der Dokumentenrelevanz
 - **Antwort-API** – Vollständige `/v1/responses`-Unterstützung für Codex
@@ -879,6 +880,18 @@ Wenn OmniRoute minimiert ist, befindet es sich mit schnellen Aktionen in Ihrer T
 
 OmniRoute v2.0 ist als Betriebsplattform konzipiert und nicht nur als Relay-Proxy.
 
+### 🚀 New in v2.0.9+ — Playground, CLI Fingerprints & ACP
+
+| Feature                                    | What It Does                                                                                                                                  |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🎮 **Model Playground**                    | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing                        |
+| 🔏 **CLI Fingerprint Matching**            | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |
+| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw), process spawner, `/api/acp/agents` endpoint                                 |
+| 🤖 **ACP Agents Dashboard**                | Debug > Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool                                      |
+| 🔧 **Custom Model `apiFormat` Routing**    | Custom models with `apiFormat: "responses"` now correctly route to the Responses API translator                                               |
+| 🏢 **Codex Workspace Isolation**           | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID                                                   |
+| 🔄 **Electron Auto-Update**                | Desktop app checks for updates + auto-install on restart                                                                                      |
+
 ### 🤖 Agenten- und Protokolloperationen (v2.0)| Funktion | Was es tut |
 
 | ------------------------------------ | -------------------------------------------------------------------------------- |

docs/i18n/de/RELEASE_CHECKLIST.md

@@ -0,0 +1,37 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) · 🇪🇸 [es](../es/RELEASE_CHECKLIST.md) · 🇫🇷 [fr](../fr/RELEASE_CHECKLIST.md) · 🇩🇪 [de](../de/RELEASE_CHECKLIST.md) · 🇮🇹 [it](../it/RELEASE_CHECKLIST.md) · 🇷🇺 [ru](../ru/RELEASE_CHECKLIST.md) · 🇨🇳 [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) · 🇯🇵 [ja](../ja/RELEASE_CHECKLIST.md) · 🇰🇷 [ko](../ko/RELEASE_CHECKLIST.md) · 🇸🇦 [ar](../ar/RELEASE_CHECKLIST.md) · 🇮🇳 [in](../in/RELEASE_CHECKLIST.md) · 🇹🇭 [th](../th/RELEASE_CHECKLIST.md) · 🇻🇳 [vi](../vi/RELEASE_CHECKLIST.md) · 🇮🇩 [id](../id/RELEASE_CHECKLIST.md) · 🇲🇾 [ms](../ms/RELEASE_CHECKLIST.md) · 🇳🇱 [nl](../nl/RELEASE_CHECKLIST.md) · 🇵🇱 [pl](../pl/RELEASE_CHECKLIST.md) · 🇸🇪 [sv](../sv/RELEASE_CHECKLIST.md) · 🇳🇴 [no](../no/RELEASE_CHECKLIST.md) · 🇩🇰 [da](../da/RELEASE_CHECKLIST.md) · 🇫🇮 [fi](../fi/RELEASE_CHECKLIST.md) · 🇵🇹 [pt](../pt/RELEASE_CHECKLIST.md) · 🇷🇴 [ro](../ro/RELEASE_CHECKLIST.md) · 🇭🇺 [hu](../hu/RELEASE_CHECKLIST.md) · 🇧🇬 [bg](../bg/RELEASE_CHECKLIST.md) · 🇸🇰 [sk](../sk/RELEASE_CHECKLIST.md) · 🇺🇦 [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) · 🇮🇱 [he](../he/RELEASE_CHECKLIST.md) · 🇵🇭 [phi](../phi/RELEASE_CHECKLIST.md)
+
+---
+
+# 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/i18n/de/TROUBLESHOOTING.md

@@ -1,87 +1,91 @@
-# Fehlerbehebung
-
-🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md)
-
-Häufige Probleme und Lösungen für OmniRoute.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/TROUBLESHOOTING.md) · 🇪🇸 [es](../es/TROUBLESHOOTING.md) · 🇫🇷 [fr](../fr/TROUBLESHOOTING.md) · 🇩🇪 [de](../de/TROUBLESHOOTING.md) · 🇮🇹 [it](../it/TROUBLESHOOTING.md) · 🇷🇺 [ru](../ru/TROUBLESHOOTING.md) · 🇨🇳 [zh-CN](../zh-CN/TROUBLESHOOTING.md) · 🇯🇵 [ja](../ja/TROUBLESHOOTING.md) · 🇰🇷 [ko](../ko/TROUBLESHOOTING.md) · 🇸🇦 [ar](../ar/TROUBLESHOOTING.md) · 🇮🇳 [in](../in/TROUBLESHOOTING.md) · 🇹🇭 [th](../th/TROUBLESHOOTING.md) · 🇻🇳 [vi](../vi/TROUBLESHOOTING.md) · 🇮🇩 [id](../id/TROUBLESHOOTING.md) · 🇲🇾 [ms](../ms/TROUBLESHOOTING.md) · 🇳🇱 [nl](../nl/TROUBLESHOOTING.md) · 🇵🇱 [pl](../pl/TROUBLESHOOTING.md) · 🇸🇪 [sv](../sv/TROUBLESHOOTING.md) · 🇳🇴 [no](../no/TROUBLESHOOTING.md) · 🇩🇰 [da](../da/TROUBLESHOOTING.md) · 🇫🇮 [fi](../fi/TROUBLESHOOTING.md) · 🇵🇹 [pt](../pt/TROUBLESHOOTING.md) · 🇷🇴 [ro](../ro/TROUBLESHOOTING.md) · 🇭🇺 [hu](../hu/TROUBLESHOOTING.md) · 🇧🇬 [bg](../bg/TROUBLESHOOTING.md) · 🇸🇰 [sk](../sk/TROUBLESHOOTING.md) · 🇺🇦 [uk-UA](../uk-UA/TROUBLESHOOTING.md) · 🇮🇱 [he](../he/TROUBLESHOOTING.md) · 🇵🇭 [phi](../phi/TROUBLESHOOTING.md)
 
 ---
 
-## Schnelle Lösungen
+# Troubleshooting
 
-| Problem                                    | Lösung                                                                   |
-| ------------------------------------------ | ------------------------------------------------------------------------ | ---------------- |
-| Erster Login funktioniert nicht            | Überprüfen Sie `INITIAL_PASSWORD` in `.env` (Standard: `123456`)         |
-| Dashboard wird am falschen Port geöffnet   | Legen Sie `PORT=20128` und `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | fest             |
-| Keine Anforderungsprotokolle unter `logs/` | Setze `ENABLE_REQUEST_LOGS=true`                                         |
-| EACCES: Berechtigung verweigert            | Legen Sie `DATA_DIR=/path/to/writable/dir` fest, um `~/.omniroute`       | zu überschreiben |
-| Routing-Strategie wird nicht gespeichert   | Update auf v1.4.11+ (Zod-Schema-Korrektur für Einstellungspersistenz)    |
+🌐 **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)
+
+Common problems and solutions for OmniRoute.
 
 ---
 
-## Anbieterprobleme
+## Quick Fixes
 
-### „Sprachmodell hat keine Nachrichten bereitgestellt“
+| 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 request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true`                                     |
+| 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)       |
 
-**Ursache:** Anbieterkontingent erschöpft.
+---
+
+## Provider Issues
+
+### "Language model did not provide messages"
+
+**Cause:** Provider quota exhausted.
 
 **Fix:**
 
-1. Überprüfen Sie den Quoten-Tracker im Dashboard
-2. Verwenden Sie eine Kombination mit Fallback-Stufen
-3. Wechseln Sie zum günstigeren/kostenlosen Tarif
+1. Check dashboard quota tracker
+2. Use a combo with fallback tiers
+3. Switch to cheaper/free tier
 
-### Ratenbegrenzung
+### Rate Limiting
 
-**Ursache:** Das Abonnementkontingent ist erschöpft.
+**Cause:** Subscription quota exhausted.
 
 **Fix:**
 
-- Fallback hinzufügen: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-- Verwenden Sie GLM/MiniMax als günstiges Backup
+- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Use GLM/MiniMax as cheap backup
 
-### OAuth-Token abgelaufen
+### OAuth Token Expired
 
-OmniRoute aktualisiert Token automatisch. Wenn die Probleme weiterhin bestehen:
+OmniRoute auto-refreshes tokens. If issues persist:
 
-1. Dashboard → Anbieter → Erneut verbinden
-2. Löschen Sie die Anbieterverbindung und fügen Sie sie erneut hinzu
+1. Dashboard → Provider → Reconnect
+2. Delete and re-add the provider connection
 
 ---
 
-## Cloud-Probleme
+## Cloud Issues
 
-### Cloud-Synchronisierungsfehler
+### Cloud Sync Errors
 
-1. Überprüfen Sie, ob `BASE_URL` auf Ihre laufende Instanz verweist (z. B. `http://localhost:20128`).
-2. Überprüfen Sie, ob `CLOUD_URL` auf Ihren Cloud-Endpunkt verweist (z. B. `https://omniroute.dev`).
-3. Halten Sie die Werte von `NEXT_PUBLIC_*` an den serverseitigen Werten ausgerichtet
+1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
+2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
+3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
 
-### Cloud `stream=false` Gibt 500 zurück
+### Cloud `stream=false` Returns 500
 
-**Symptom:** `Unexpected token 'd'...` am Cloud-Endpunkt für Nicht-Streaming-Anrufe.
+**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
 
-**Ursache:** Upstream gibt SSE-Nutzdaten zurück, während der Client JSON erwartet.
+**Cause:** Upstream returns SSE payload while client expects JSON.
 
-**Problemumgehung:** Verwenden Sie `stream=true` für Cloud-Direktaufrufe. Die lokale Laufzeit umfasst SSE→JSON-Fallback.
+**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
 
-### Cloud sagt verbunden, aber „Ungültiger API-Schlüssel“
+### Cloud Says Connected but "Invalid API key"
 
-1. Erstellen Sie einen neuen Schlüssel aus dem lokalen Dashboard (`/api/keys`).
-2. Führen Sie die Cloud-Synchronisierung aus: Cloud aktivieren → Jetzt synchronisieren
-3. Alte/nicht synchronisierte Schlüssel können weiterhin `401` in der Cloud zurückgeben
+1. Create a fresh key from local dashboard (`/api/keys`)
+2. Run cloud sync: Enable Cloud → Sync Now
+3. Old/non-synced keys can still return `401` on cloud
 
 ---
 
-## Docker-Probleme
+## Docker Issues
 
-### CLI-Tool wird als „Nicht installiert“ angezeigt
+### CLI Tool Shows Not Installed
 
-1. Laufzeitfelder prüfen: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
-2. Für den portablen Modus: Bildziel `runner-cli` verwenden (gebündelte CLIs)
-3. Für den Host-Mount-Modus: Legen Sie `CLI_EXTRA_PATHS` fest und mounten Sie das Host-Bin-Verzeichnis als schreibgeschützt
-4. Wenn `installed=true` und `runnable=false`: Binärdatei gefunden wurde, die Integritätsprüfung jedoch fehlgeschlagen ist
+1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. For portable mode: use image target `runner-cli` (bundled CLIs)
+3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
+4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
 
-### Schnelle Laufzeitvalidierung
+### Quick Runtime Validation
 
 ```bash
 curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
@@ -91,24 +95,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
 
 ---
 
-## Kostenprobleme
+## Cost Issues
 
-### Hohe Kosten
+### High Costs
 
-1. Überprüfen Sie die Nutzungsstatistiken im Dashboard → Nutzung
-2. Primärmodell auf GLM/MiniMax umstellen
-3. Nutzen Sie das kostenlose Kontingent (Gemini CLI, iFlow) für unkritische Aufgaben
-4. Legen Sie Kostenbudgets pro API-Schlüssel fest: Dashboard → API-Schlüssel → Budget
+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
+4. Set cost budgets per API key: Dashboard → API Keys → Budget
 
 ---
 
-## Debuggen
+## Debugging
 
-### Anforderungsprotokolle aktivieren
+### Enable Request Logs
 
-Legen Sie `ENABLE_REQUEST_LOGS=true` in Ihrer `.env`-Datei fest. Protokolle werden im Verzeichnis `logs/` angezeigt.
+Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory.
 
-### Überprüfen Sie den Zustand des Anbieters
+### Check Provider Health
 
 ```bash
 # Health dashboard
@@ -118,104 +122,137 @@ http://localhost:20128/dashboard/health
 curl http://localhost:20128/api/monitoring/health
 ```
 
-### Laufzeitspeicher
+### Runtime Storage
 
-- Hauptstatus: `${DATA_DIR}/db.json` (Anbieter, Combos, Aliase, Schlüssel, Einstellungen)
-- Verwendung: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
-  – Anforderungsprotokolle: `<repo>/logs/...` (wenn `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}/log.txt` and `${DATA_DIR}/call_logs/`
+- Request logs: `<repo>/logs/...` (when `ENABLE_REQUEST_LOGS=true`)
 
 ---
 
-## Probleme mit Leistungsschaltern
+## Circuit Breaker Issues
 
-### Provider bleibt im OPEN-Zustand hängen
+### Provider stuck in OPEN state
 
-Wenn der Leistungsschalter eines Anbieters OFFEN ist, werden Anfragen blockiert, bis die Abklingzeit abgelaufen ist.
+When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
 
 **Fix:**
 
-1. Gehen Sie zu **Dashboard → Einstellungen → Resilienz**
-2. Überprüfen Sie die Leistungsschalterkarte des betroffenen Anbieters
-3. Klicken Sie auf **Alle zurücksetzen**, um alle Unterbrecher zu löschen, oder warten Sie, bis die Abklingzeit abgelaufen ist
-4. Stellen Sie vor dem Zurücksetzen sicher, dass der Anbieter tatsächlich verfügbar ist
+1. Go to **Dashboard → Settings → Resilience**
+2. Check the circuit breaker card for the affected provider
+3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
+4. Verify the provider is actually available before resetting
 
-### Der Anbieter löst weiterhin den Schutzschalter aus
+### Provider keeps tripping the circuit breaker
 
-Wenn ein Anbieter wiederholt in den OPEN-Zustand wechselt:
+If a provider repeatedly enters OPEN state:
 
-1. Überprüfen Sie **Dashboard → Health → Provider Health** auf das Fehlermuster
-2. Gehen Sie zu **Einstellungen → Ausfallsicherheit → Anbieterprofile** und erhöhen Sie den Fehlerschwellenwert
-3. Überprüfen Sie, ob der Anbieter die API-Grenzwerte geändert hat oder eine erneute Authentifizierung erfordert
-4. Überprüfen Sie die Latenz-Telemetrie – hohe Latenz kann zu zeitüberschreitungsbedingten Fehlern führen
+1. Check **Dashboard → Health → Provider Health** for the failure pattern
+2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
+3. Check if the provider has changed API limits or requires re-authentication
+4. Review latency telemetry — high latency may cause timeout-based failures
 
 ---
 
-## Probleme mit der Audiotranskription
+## Audio Transcription Issues
 
-### Fehler „Nicht unterstütztes Modell“.
+### "Unsupported model" error
 
-– Stellen Sie sicher, dass Sie das richtige Präfix verwenden: `deepgram/nova-3` oder `assemblyai/best`
+- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
+- Verify the provider is connected in **Dashboard → Providers**
 
-- Überprüfen Sie, ob der Anbieter unter **Dashboard → Anbieter** verbunden ist.
+### Transcription returns empty or fails
 
-### Die Transkription ist leer oder schlägt fehl
-
-- Überprüfen Sie die unterstützten Audioformate: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
-- Stellen Sie sicher, dass die Dateigröße innerhalb der Anbietergrenzen liegt (normalerweise < 25 MB).
-- Überprüfen Sie die Gültigkeit des API-Schlüssels des Anbieters auf der Anbieterkarte
+- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Verify file size is within provider limits (typically < 25MB)
+- Check provider API key validity in the provider card
 
 ---
 
-## Übersetzer-Debugging
+## Translator Debugging
 
-Verwenden Sie **Dashboard → Übersetzer**, um Formatübersetzungsprobleme zu beheben:
+Use **Dashboard → Translator** to debug format translation issues:
 
-| Modus            | Wann zu verwenden                                                                                                                       |
-| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| **Spielplatz**   | Vergleichen Sie Eingabe-/Ausgabeformate nebeneinander – fügen Sie eine fehlgeschlagene Anfrage ein, um zu sehen, wie sie übersetzt wird |
-| **Chat-Tester**  | Senden Sie Live-Nachrichten und überprüfen Sie die vollständige Anfrage-/Antwort-Nutzlast einschließlich Header                         |
-| **Prüfstand**    | Führen Sie Stapeltests über Formatkombinationen hinweg durch, um herauszufinden, welche Übersetzungen fehlerhaft sind                   |
-| **Live-Monitor** | Beobachten Sie den Anfragefluss in Echtzeit, um zeitweise auftretende Übersetzungsprobleme zu erkennen                                  |
+| Mode             | When to Use                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| **Playground**   | Compare input/output formats side by side — paste a failing request to see how it translates |
+| **Chat Tester**  | Send live messages and inspect the full request/response payload including headers           |
+| **Test Bench**   | Run batch tests across format combinations to find which translations are broken             |
+| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues                        |
 
-### Häufige Formatprobleme
+### Common format issues
 
-- **Thinking-Tags werden nicht angezeigt** – Überprüfen Sie, ob der Zielanbieter Thinking und die Einstellung des Thinking-Budgets unterstützt
-- **Tool-Aufrufe löschen** – Bei einigen Formatübersetzungen werden möglicherweise nicht unterstützte Felder entfernt. im Playground-Modus überprüfen
-- **Systemaufforderung fehlt** – Claude und Gemini gehen unterschiedlich mit Systemaufforderungen um; Überprüfen Sie die Übersetzungsausgabe
-- **SDK gibt Rohzeichenfolge anstelle von Objekt zurück** – In Version 1.1.0 behoben: Antwortbereinigung entfernt jetzt nicht standardmäßige Felder (`x_groq`, `usage_breakdown` usw.), die zu OpenAI SDK Pydantic-Validierungsfehlern führen
-- **GLM/ERNIE lehnt die Rolle `system` ab** – In Version 1.1.0 behoben: Der Rollennormalisierer führt automatisch Systemnachrichten in Benutzernachrichten für inkompatible Modelle zusammen
-- **`developer` Rolle nicht erkannt** – In v1.1.0 behoben: automatisch in `system` für Nicht-OpenAI-Anbieter konvertiert
-- **`json_schema` funktioniert nicht mit Gemini** – In v1.1.0 behoben: `response_format` wird jetzt in Geminis `responseMimeType` + `responseSchema` konvertiert
+- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
+- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
+- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
+- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures
+- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
+- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers
+- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema`
 
 ---
 
-## Resilienzeinstellungen
+## Resilience Settings
 
-### Automatische Ratenbegrenzung wird nicht ausgelöst
+### Auto rate-limit not triggering
 
-– Die automatische Ratenbegrenzung gilt nur für API-Schlüsselanbieter (nicht OAuth/Abonnement).
+- Auto rate-limit only applies to API key providers (not OAuth/subscription)
+- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
+- Check if the provider returns `429` status codes or `Retry-After` headers
 
-- Überprüfen Sie, ob in **Einstellungen → Ausfallsicherheit → Anbieterprofile** die automatische Ratenbegrenzung aktiviert ist
-  – Überprüfen Sie, ob der Anbieter Statuscodes `429` oder Header `Retry-After` zurückgibt
+### Tuning exponential backoff
 
-### Optimierung des exponentiellen Backoffs
+Provider profiles support these settings:
 
-Anbieterprofile unterstützen diese Einstellungen:
+- **Base delay** — Initial wait time after first failure (default: 1s)
+- **Max delay** — Maximum wait time cap (default: 30s)
+- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
 
-- **Basisverzögerung** – Anfängliche Wartezeit nach dem ersten Fehler (Standard: 1 s)
-- **Max. Verzögerung** – Maximale Wartezeitobergrenze (Standard: 30 s)
-- **Multiplikator** – Wie viel Verzögerung pro aufeinanderfolgendem Fehler erhöht werden soll (Standard: 2x)
+### Anti-thundering herd
 
-### Anti-donnernde Herde
-
-Wenn viele gleichzeitige Anfragen einen Anbieter mit begrenzter Rate treffen, verwendet OmniRoute Mutex + automatische Ratenbegrenzung, um Anfragen zu serialisieren und kaskadierende Fehler zu verhindern. Dies geschieht automatisch für API-Schlüsselanbieter.
+When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
 
 ---
 
-## Immer noch nicht weitergekommen?
+## Optional RAG / LLM failure taxonomy (16 problems)
 
-- **GitHub-Probleme**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architektur**: Interne Details finden Sie unter [link](ARCHITECTURE.md)
-- **API-Referenz**: Siehe [link](API_REFERENCE.md) für alle Endpunkte
-- **Gesundheits-Dashboard**: Überprüfen Sie **Dashboard → Gesundheit** auf den Echtzeit-Systemstatus
-- **Übersetzer**: Verwenden Sie **Dashboard → Übersetzer**, um Formatprobleme zu beheben
+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)
+- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
+- **Translator**: Use **Dashboard → Translator** to debug format issues

docs/i18n/de/USER_GUIDE.md

@@ -1,12 +1,16 @@
-# Benutzerhandbuch
-
-🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md)
-
-Vollständiger Leitfaden zum Konfigurieren von Anbietern, Erstellen von Kombinationen, Integrieren von CLI-Tools und Bereitstellen von OmniRoute.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/USER_GUIDE.md) · 🇪🇸 [es](../es/USER_GUIDE.md) · 🇫🇷 [fr](../fr/USER_GUIDE.md) · 🇩🇪 [de](../de/USER_GUIDE.md) · 🇮🇹 [it](../it/USER_GUIDE.md) · 🇷🇺 [ru](../ru/USER_GUIDE.md) · 🇨🇳 [zh-CN](../zh-CN/USER_GUIDE.md) · 🇯🇵 [ja](../ja/USER_GUIDE.md) · 🇰🇷 [ko](../ko/USER_GUIDE.md) · 🇸🇦 [ar](../ar/USER_GUIDE.md) · 🇮🇳 [in](../in/USER_GUIDE.md) · 🇹🇭 [th](../th/USER_GUIDE.md) · 🇻🇳 [vi](../vi/USER_GUIDE.md) · 🇮🇩 [id](../id/USER_GUIDE.md) · 🇲🇾 [ms](../ms/USER_GUIDE.md) · 🇳🇱 [nl](../nl/USER_GUIDE.md) · 🇵🇱 [pl](../pl/USER_GUIDE.md) · 🇸🇪 [sv](../sv/USER_GUIDE.md) · 🇳🇴 [no](../no/USER_GUIDE.md) · 🇩🇰 [da](../da/USER_GUIDE.md) · 🇫🇮 [fi](../fi/USER_GUIDE.md) · 🇵🇹 [pt](../pt/USER_GUIDE.md) · 🇷🇴 [ro](../ro/USER_GUIDE.md) · 🇭🇺 [hu](../hu/USER_GUIDE.md) · 🇧🇬 [bg](../bg/USER_GUIDE.md) · 🇸🇰 [sk](../sk/USER_GUIDE.md) · 🇺🇦 [uk-UA](../uk-UA/USER_GUIDE.md) · 🇮🇱 [he](../he/USER_GUIDE.md) · 🇵🇭 [phi](../phi/USER_GUIDE.md)
 
 ---
 
-## Inhaltsverzeichnis
+# 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)
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
+
+## Table of Contents
 
 - [Pricing at a Glance](#-pricing-at-a-glance)
 - [Use Cases](#-use-cases)
@@ -18,40 +22,40 @@ Vollständiger Leitfaden zum Konfigurieren von Anbietern, Erstellen von Kombinat
 
 ---
 
-## 💰 Preise im Überblick
+## 💰 Pricing at a Glance
 
-| Stufe                | Anbieter          | Kosten                | Kontingent zurücksetzen   | Am besten für                   |
-| -------------------- | ----------------- | --------------------- | ------------------------- | ------------------------------- |
-| **💳 ABO**           | Claude Code (Pro) | 20 $/Monat            | 5h + wöchentlich          | Bereits abonniert               |
-|                      | Codex (Plus/Pro)  | 20–200 $/Monat        | 5h + wöchentlich          | OpenAI-Benutzer                 |
-|                      | Gemini CLI        | **KOSTENLOS**         | 180.000/Monat + 1.000/Tag | Alle!                           |
-|                      | GitHub-Copilot    | 10–19 $/Monat         | Monatlich                 | GitHub-Benutzer                 |
-| **🔑 API-SCHLÜSSEL** | DeepSeek          | Bezahlung pro Nutzung | Keine                     | Billiges Denken                 |
-|                      | Groq              | Bezahlung pro Nutzung | Keine                     | Ultraschnelle Inferenz          |
-|                      | xAI (Grok)        | Bezahlung pro Nutzung | Keine                     | Grok 4 Argumentation            |
-|                      | Mistral           | Bezahlung pro Nutzung | Keine                     | In der EU gehostete Modelle     |
-|                      | Ratlosigkeit      | Bezahlung pro Nutzung | Keine                     | Sucherweitert                   |
-|                      | Zusammen KI       | Bezahlung pro Nutzung | Keine                     | Open-Source-Modelle             |
-|                      | Feuerwerk KI      | Bezahlung pro Nutzung | Keine                     | Schnelle FLUX-Bilder            |
-|                      | Großhirn          | Bezahlung pro Nutzung | Keine                     | Geschwindigkeit im Wafermaßstab |
-|                      | Kohärent          | Bezahlung pro Nutzung | Keine                     | Befehl R+ RAG                   |
-|                      | NVIDIA NIM        | Bezahlung pro Nutzung | Keine                     | Unternehmensmodelle             |
-| **💰 GÜNSTIG**       | GLM-4.7           | 0,6 $/1 Mio.          | Täglich 10 Uhr            | Budgetsicherung                 |
-|                      | MiniMax M2.1      | 0,2 $/1 Mio.          | 5-Stunden-Rollen          | Günstigste Option               |
-|                      | Kimi K2           | $9/Monat pauschal     | 10 Millionen Token/Monat  | Vorhersehbare Kosten            |
-| **🆓 KOSTENLOS**     | iFlow             | $0                    | Unbegrenzt                | 8 Modelle kostenlos             |
-|                      | Qwen              | $0                    | Unbegrenzt                | 3 Modelle kostenlos             |
-|                      | Kiro              | $0                    | Unbegrenzt                | Claude frei                     |
+| Tier                | Provider          | Cost        | Quota Reset      | Best For             |
+| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |
+| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo      | 5h + weekly      | Already subscribed   |
+|                     | Codex (Plus/Pro)  | $20-200/mo  | 5h + weekly      | OpenAI users         |
+|                     | Gemini CLI        | **FREE**    | 180K/mo + 1K/day | Everyone!            |
+|                     | GitHub Copilot    | $10-19/mo   | Monthly          | GitHub users         |
+| **🔑 API KEY**      | DeepSeek          | Pay per use | None             | Cheap reasoning      |
+|                     | Groq              | Pay per use | None             | Ultra-fast inference |
+|                     | xAI (Grok)        | Pay per use | None             | Grok 4 reasoning     |
+|                     | Mistral           | Pay per use | None             | EU-hosted models     |
+|                     | Perplexity        | Pay per use | None             | Search-augmented     |
+|                     | Together AI       | Pay per use | None             | Open-source models   |
+|                     | Fireworks AI      | Pay per use | None             | Fast FLUX images     |
+|                     | Cerebras          | Pay per use | None             | Wafer-scale speed    |
+|                     | Cohere            | Pay per use | None             | Command R+ RAG       |
+|                     | NVIDIA NIM        | Pay per use | None             | Enterprise models    |
+| **💰 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        |
+|                     | Qwen              | $0          | Unlimited        | 3 models free        |
+|                     | Kiro              | $0          | Unlimited        | Claude free          |
 
-**💡 Profi-Tipp:** Beginnen Sie mit der Kombination Gemini CLI (180.000 kostenlos/Monat) + iFlow (unbegrenzt kostenlos) = 0 $ Kosten!
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost!
 
 ---
 
-## 🎯 Anwendungsfälle
+## 🎯 Use Cases
 
-### Fall 1: „Ich habe ein Claude Pro-Abonnement“
+### Case 1: "I have Claude Pro subscription"
 
-**Problem:** Kontingent läuft ungenutzt ab, Ratenbegrenzungen bei intensiver Codierung
+**Problem:** Quota expires unused, rate limits during heavy coding
 
 ```
 Combo: "maximize-claude"
@@ -63,9 +67,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
 vs. $20 + hitting limits = frustration
 ```
 
-### Fall 2: „Ich möchte Nullkosten“
+### Case 2: "I want zero cost"
 
-**Problem:** Ich kann mir keine Abonnements leisten und brauche zuverlässige KI-Codierung
+**Problem:** Can't afford subscriptions, need reliable AI coding
 
 ```
 Combo: "free-forever"
@@ -77,9 +81,9 @@ Monthly cost: $0
 Quality: Production-ready models
 ```
 
-### Fall 3: „Ich brauche 24/7-Codierung, keine Unterbrechungen“
+### Case 3: "I need 24/7 coding, no interruptions"
 
-**Problem:** Fristen, ich kann mir Ausfallzeiten nicht leisten
+**Problem:** Deadlines, can't afford downtime
 
 ```
 Combo: "always-on"
@@ -93,9 +97,9 @@ Result: 5 layers of fallback = zero downtime
 Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
 ```
 
-### Fall 4: „Ich möchte KOSTENLOSE KI in OpenClaw“
+### Case 4: "I want FREE AI in OpenClaw"
 
-**Problem:** Benötigen Sie einen KI-Assistenten in Messaging-Apps, völlig kostenlos
+**Problem:** Need AI assistant in messaging apps, completely free
 
 ```
 Combo: "openclaw-free"
@@ -109,9 +113,9 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 
 ---
 
-## 📖 Anbieter-Setup
+## 📖 Provider Setup
 
-### 🔐 Abonnementanbieter
+### 🔐 Subscription Providers
 
 #### Claude Code (Pro/Max)
 
@@ -126,7 +130,7 @@ Models:
   cc/claude-haiku-4-5-20251001
 ```
 
-**Profi-Tipp:** Verwenden Sie Opus für komplexe Aufgaben, Sonnet für Geschwindigkeit. OmniRoute verfolgt das Kontingent pro Modell!
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
 
 #### OpenAI Codex (Plus/Pro)
 
@@ -140,7 +144,7 @@ Models:
   cx/gpt-5.1-codex-max
 ```
 
-#### Gemini CLI (KOSTENLOS 180.000/Monat!)
+#### Gemini CLI (FREE 180K/month!)
 
 ```bash
 Dashboard → Providers → Connect Gemini CLI
@@ -152,9 +156,9 @@ Models:
   gc/gemini-2.5-pro
 ```
 
-**Bester Wert:** Riesiges kostenloses Kontingent! Verwenden Sie dies vor kostenpflichtigen Stufen.
+**Best Value:** Huge free tier! Use this before paid tiers.
 
-#### GitHub-Copilot
+#### GitHub Copilot
 
 ```bash
 Dashboard → Providers → Connect GitHub
@@ -167,33 +171,33 @@ Models:
   gh/gemini-3-pro
 ```
 
-### 💰 Günstige Anbieter
+### 💰 Cheap Providers
 
-#### GLM-4.7 (Täglicher Reset, 0,6 $/1 Mio.)
+#### GLM-4.7 (Daily reset, $0.6/1M)
 
-1. Registrieren Sie sich: [Zhipu AI](https://open.bigmodel.cn/)
-2. Holen Sie sich den API-Schlüssel vom Coding Plan
-3. Dashboard → API-Schlüssel hinzufügen: Anbieter: `glm`, API-Schlüssel: `your-key`
+1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)
+2. Get API key from Coding Plan
+3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`
 
-**Verwendung:** `glm/glm-4.7` — **Profi-Tipp:** Coding Plan bietet 3× Kontingent zu 1/7 Kosten! Täglich um 10:00 Uhr zurückgesetzt.
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
 
-#### MiniMax M2.1 (5 Stunden Zurücksetzen, 0,20 $/1 Mio.)
+#### MiniMax M2.1 (5h reset, $0.20/1M)
 
-1. Registrieren Sie sich: [MiniMax](https://www.minimax.io/)
-2. API-Schlüssel abrufen → Dashboard → API-Schlüssel hinzufügen
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
 
-**Verwendung:** `minimax/MiniMax-M2.1` – **Profi-Tipp:** Günstigste Option für langen Kontext (1 Mio. Token)!
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
 
-#### Kimi K2 (9 $/Monat pauschal)
+#### Kimi K2 ($9/month flat)
 
-1. Abonnieren: [Moonshot AI](https://platform.moonshot.ai/)
-2. API-Schlüssel abrufen → Dashboard → API-Schlüssel hinzufügen
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
 
-**Verwendung:** `kimi/kimi-latest` — **Profi-Tipp:** Feste 9 $/Monat für 10 Mio. Token = 0,90 $/1 Mio. effektive Kosten!
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
 
-### 🆓 KOSTENLOSE Anbieter
+### 🆓 FREE Providers
 
-#### iFlow (8 KOSTENLOSE Modelle)
+#### iFlow (8 FREE models)
 
 ```bash
 Dashboard → Connect iFlow → OAuth login → Unlimited usage
@@ -201,7 +205,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage
 Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1
 ```
 
-#### Qwen (3 KOSTENLOSE Modelle)
+#### Qwen (3 FREE models)
 
 ```bash
 Dashboard → Connect Qwen → Device code auth → Unlimited usage
@@ -209,7 +213,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage
 Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
 ```
 
-#### Kiro (Claude KOSTENLOS)
+#### Kiro (Claude FREE)
 
 ```bash
 Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
@@ -219,9 +223,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
 
 ---
 
-## 🎨 Kombinationen
+## 🎨 Combos
 
-### Beispiel 1: Abonnement maximieren → Günstiges Backup
+### Example 1: Maximize Subscription → Cheap Backup
 
 ```
 Dashboard → Combos → Create New
@@ -235,7 +239,7 @@ Models:
 Use in CLI: premium-coding
 ```
 
-### Beispiel 2: Nur kostenlos (kostenlos)
+### Example 2: Free-Only (Zero Cost)
 
 ```
 Name: free-combo
@@ -249,9 +253,9 @@ Cost: $0 forever!
 
 ---
 
-## 🔧 CLI-Integration
+## 🔧 CLI Integration
 
-### Cursor-IDE
+### Cursor IDE
 
 ```
 Settings → Models → Advanced:
@@ -262,7 +266,7 @@ Settings → Models → Advanced:
 
 ### Claude Code
 
-Bearbeiten Sie `~/.claude/config.json`:
+Edit `~/.claude/config.json`:
 
 ```json
 {
@@ -271,7 +275,7 @@ Bearbeiten Sie `~/.claude/config.json`:
 }
 ```
 
-### Codex-CLI
+### Codex CLI
 
 ```bash
 export OPENAI_BASE_URL="http://localhost:20128"
@@ -281,7 +285,7 @@ codex "your prompt"
 
 ### OpenClaw
 
-Bearbeiten Sie `~/.openclaw/openclaw.json`:
+Edit `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -303,9 +307,9 @@ Bearbeiten Sie `~/.openclaw/openclaw.json`:
 }
 ```
 
-**Oder verwenden Sie Dashboard:** CLI-Tools → OpenClaw → Auto-config
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
 
-### Cline / Weiter / RooCode
+### Cline / Continue / RooCode
 
 ```
 Provider: OpenAI Compatible
@@ -316,9 +320,28 @@ Model: cc/claude-opus-4-6
 
 ---
 
-## 🚀 Bereitstellung
+## 🚀 Deployment
 
-### VPS-Bereitstellung
+### 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
 git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -337,6 +360,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,51 +407,54 @@ docker build -t omniroute:cli .
 docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
 ```
 
-Informationen zum hostintegrierten Modus mit CLI-Binärdateien finden Sie im Abschnitt „Docker“ in den Hauptdokumenten.
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
 
-### Umgebungsvariablen
+### Environment Variables
 
-| Variable              | Standard                             | Beschreibung                                                             |
-| --------------------- | ------------------------------------ | ------------------------------------------------------------------------ | ---- |
-| `JWT_SECRET`          | `omniroute-default-secret-change-me` | JWT-Signaturgeheimnis (**Änderung in der Produktion**)                   |
-| `INITIAL_PASSWORD`    | `123456`                             | Erstes Login-Passwort                                                    |
-| `DATA_DIR`            | `~/.omniroute`                       | Datenverzeichnis (Datenbank, Nutzung, Protokolle)                        |
-| `PORT`                | Framework-Standard                   | Service-Port (`20128` in Beispielen)                                     |
-| `HOSTNAME`            | Framework-Standard                   | Host binden (Docker ist standardmäßig `0.0.0.0`)                         |
-| `NODE_ENV`            | Laufzeitstandard                     | Legen Sie `production` für die Bereitstellung                            | fest |
-| `BASE_URL`            | `http://localhost:20128`             | Serverseitige interne Basis-URL                                          |
-| `CLOUD_URL`           | `https://omniroute.dev`              | Basis-URL des Cloud-Synchronisierungsendpunkts                           |
-| `API_KEY_SECRET`      | `endpoint-proxy-api-key-secret`      | HMAC-Geheimnis für generierte API-Schlüssel                              |
-| `REQUIRE_API_KEY`     | `false`                              | Bearer-API-Schlüssel auf `/v1/*` erzwingen                               |
-| `ENABLE_REQUEST_LOGS` | `false`                              | Aktiviert Anforderungs-/Antwortprotokolle                                |
-| `AUTH_COOKIE_SECURE`  | `false`                              | `Secure` Authentifizierungscookie erzwingen (hinter 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/*`                       |
+| `ENABLE_REQUEST_LOGS`     | `false`                              | Enables request/response logs                           |
+| `AUTH_COOKIE_SECURE`      | `false`                              | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `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                              |
 
-Die vollständige Umgebungsvariablenreferenz finden Sie im [README](../README.md).
+For the full environment variable reference, see the [README](../README.md).
 
 ---
 
-## 📊 Verfügbare Modelle
+## 📊 Available Models
 
 <details>
-<summary><b>Alle verfügbaren Modelle anzeigen</b></summary>
+<summary><b>View all available models</b></summary>
 
-**Claude Code (`cc/`)** – Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**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`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
 
-**Gemini CLI (`gc/`)** – KOSTENLOS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
 
 **GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
 
-**GLM (`glm/`)** – 0,6 $/1 Mio.: `glm/glm-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
 
-**MiniMax (`minimax/`)** – 0,2 $/1 Mio.: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
 
-**iFlow (`if/`)** – KOSTENLOS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
 
-**Qwen (`qw/`)** – KOSTENLOS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
 
-**Kiro (`kr/`)** – KOSTENLOS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
 
 **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
 
@@ -401,15 +464,15 @@ Die vollständige Umgebungsvariablenreferenz finden Sie im [README](../README.md
 
 **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
 
-**Perplexität (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
 
 **Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
 
-**Feuerwerks-KI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
 
-**Großhirn (`cerebras/`)**: `cerebras/llama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
 
-**Zusammenhang (`cohere/`)**: `cohere/command-r-plus-08-2024`
+**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
 
 **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
 
@@ -417,11 +480,11 @@ Die vollständige Umgebungsvariablenreferenz finden Sie im [README](../README.md
 
 ---
 
-## 🧩 Erweiterte Funktionen
+## 🧩 Advanced Features
 
-### Benutzerdefinierte Modelle
+### Custom Models
 
-Fügen Sie jedem Anbieter eine beliebige Modell-ID hinzu, ohne auf ein App-Update warten zu müssen:
+Add any model ID to any provider without waiting for an app update:
 
 ```bash
 # Via API
@@ -433,11 +496,11 @@ curl -X POST http://localhost:20128/api/provider-models \
 # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
 ```
 
-Oder verwenden Sie das Dashboard: **Anbieter → [Anbieter] → Benutzerdefinierte Modelle**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
 
-### Dedizierte Anbieterrouten
+### Dedicated Provider Routes
 
-Leiten Sie Anfragen mit Modellvalidierung direkt an einen bestimmten Anbieter weiter:
+Route requests directly to a specific provider with model validation:
 
 ```bash
 POST http://localhost:20128/v1/providers/openai/chat/completions
@@ -445,9 +508,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings
 POST http://localhost:20128/v1/providers/fireworks/images/generations
 ```
 
-Das Anbieterpräfix wird automatisch hinzugefügt, wenn es fehlt. Nicht übereinstimmende Modelle geben `400` zurück.
+The provider prefix is auto-added if missing. Mismatched models return `400`.
 
-### Netzwerk-Proxy-Konfiguration
+### Network Proxy Configuration
 
 ```bash
 # Set global proxy
@@ -463,76 +526,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \
   -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
 ```
 
-**Vorrang:** Schlüsselspezifisch → Combo-spezifisch → Anbieterspezifisch → Global → Umgebung.
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
 
-### Modellkatalog-API
+### Model Catalog API
 
 ```bash
 curl http://localhost:20128/api/models/catalog
 ```
 
-Gibt nach Anbieter gruppierte Modelle mit Typen (`chat`, `embedding`, `image`) zurück.
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
 
-### Cloud-Synchronisierung
+### Cloud Sync
 
-- Synchronisieren Sie Anbieter, Kombinationen und Einstellungen geräteübergreifend
-- Automatische Hintergrundsynchronisierung mit Timeout + Fail-Fast
-  – Bevorzugen Sie serverseitiges `BASE_URL`/`CLOUD_URL` in der Produktion
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
 
 ### LLM Gateway Intelligence (Phase 9)
 
-- **Semantischer Cache** – Nicht-Streaming-Antworten mit Temperatur = 0 werden automatisch zwischengespeichert (Umgehung mit `X-OmniRoute-No-Cache: true`)
-- **Request Idempotency** – Dedupliziert Anfragen innerhalb von 5 Sekunden über den Header `Idempotency-Key` oder `X-Request-Id`
-- **Fortschrittsverfolgung** – Opt-in-SSE-`event: progress`-Ereignisse über den `X-OmniRoute-Progress: true`-Header
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
 
 ---
 
-### Übersetzerspielplatz
+### Translator Playground
 
-Zugriff über **Dashboard → Übersetzer**. Debuggen und visualisieren Sie, wie OmniRoute API-Anfragen zwischen Anbietern übersetzt.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
 
-| Modus            | Zweck                                                                                                              |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
-| **Spielplatz**   | Wählen Sie Quell-/Zielformate aus, fügen Sie eine Anfrage ein und sehen Sie sich sofort die übersetzte Ausgabe an  |
-| **Chat-Tester**  | Senden Sie Live-Chat-Nachrichten über den Proxy und überprüfen Sie den gesamten Anfrage-/Antwortzyklus             |
-| **Prüfstand**    | Führen Sie Batch-Tests über mehrere Formatkombinationen hinweg durch, um die Übersetzungskorrektheit zu überprüfen |
-| **Live-Monitor** | Beobachten Sie Übersetzungen in Echtzeit, während Anfragen über den Proxy fließen                                  |
+| Mode             | Purpose                                                                                |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground**   | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester**  | Send live chat messages through the proxy and inspect the full request/response cycle  |
+| **Test Bench**   | Run batch tests across multiple format combinations to verify translation correctness  |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy                        |
 
-**Anwendungsfälle:**
+**Use cases:**
 
-- Debuggen Sie, warum eine bestimmte Client-/Provider-Kombination fehlschlägt
-- Stellen Sie sicher, dass Denktags, Toolaufrufe und Systemaufforderungen korrekt übersetzt werden
-- Vergleichen Sie Formatunterschiede zwischen den API-Formaten OpenAI, Claude, Gemini und Responses
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
 
 ---
 
-### Routing-Strategien
+### Routing Strategies
 
-Konfigurieren Sie über **Dashboard → Einstellungen → Routing**.
+Configure via **Dashboard → Settings → Routing**.
 
-| Strategie                      | Beschreibung                                                                                                                      |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
-| **Zuerst füllen**              | Verwendet Konten in der Reihenfolge ihrer Priorität – das primäre Konto bearbeitet alle Anfragen, bis es nicht mehr verfügbar ist |
-| **Round Robin**                | Durchläuft alle Konten mit einem konfigurierbaren Sticky-Limit (Standard: 3 Anrufe pro Konto)                                     |
-| **P2C (Power of Two Choices)** | Wählt zwei zufällige Konten aus und leitet sie zum gesünderen weiter – gleicht Last mit Gesundheitsbewusstsein aus                |
-| **Zufällig**                   | Wählt für jede Anfrage per Fisher-Yates-Shuffle                                                                                   | zufällig ein Konto aus |
-| **Am wenigsten genutzt**       | Leitet zum Konto mit dem ältesten `lastUsedAt`-Zeitstempel weiter und verteilt den Datenverkehr gleichmäßig                       |
-| **Kostenoptimiert**            | Leitet zum Konto mit dem niedrigsten Prioritätswert weiter, optimiert für Anbieter mit den niedrigsten Kosten                     |
+| Strategy                       | Description                                                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First**                 | Uses accounts in priority order — primary account handles all requests until unavailable         |
+| **Round Robin**                | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account)      |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random**                     | Randomly selects an account for each request using Fisher-Yates shuffle                          |
+| **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       |
 
-#### Wildcard-Modellaliase
+#### Wildcard Model Aliases
 
-Erstellen Sie Platzhaltermuster, um Modellnamen neu zuzuordnen:
+Create wildcard patterns to remap model names:
 
 ```
 Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-5-20250929
 Pattern: gpt-*               →  Target: gh/gpt-5.1-codex
 ```
 
-Platzhalter unterstützen `*` (beliebige Zeichen) und `?` (einzelnes Zeichen).
+Wildcards support `*` (any characters) and `?` (single character).
 
-#### Fallback-Ketten
+#### Fallback Chains
 
-Definieren Sie globale Fallback-Ketten, die für alle Anfragen gelten:
+Define global fallback chains that apply across all requests:
 
 ```
 Chain: production-fallback
@@ -543,46 +606,46 @@ Chain: production-fallback
 
 ---
 
-### Belastbarkeit und Leistungsschalter
+### Resilience & Circuit Breakers
 
-Konfigurieren Sie über **Dashboard → Einstellungen → Resilienz**.
+Configure via **Dashboard → Settings → Resilience**.
 
-OmniRoute implementiert Resilienz auf Anbieterebene mit vier Komponenten:
+OmniRoute implements provider-level resilience with four components:
 
-1. **Anbieterprofile** – Konfiguration pro Anbieter für:
-   - Fehlerschwelle (wie viele Fehler vor dem Öffnen)
-   - Abklingdauer
-   - Empfindlichkeit der Grenzfrequenzerkennung
-   - Exponentielle Backoff-Parameter
+1. **Provider Profiles** — Per-provider configuration for:
+   - Failure threshold (how many failures before opening)
+   - Cooldown duration
+   - Rate limit detection sensitivity
+   - Exponential backoff parameters
 
-2. **Bearbeitbare Ratenbegrenzungen** – Standardeinstellungen auf Systemebene, konfigurierbar im Dashboard:
-   - **Anfragen pro Minute (RPM)** – Maximale Anfragen pro Minute und Konto
-   - **Min. Zeit zwischen Anfragen** – Mindestlücke in Millisekunden zwischen Anfragen
-   - **Max. gleichzeitige Anfragen** – Maximale gleichzeitige Anfragen pro Konto
-   - Klicken Sie zum Ändern auf **Bearbeiten** und dann auf **Speichern** oder **Abbrechen**. Werte bleiben über die Resilience-API bestehen.
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+   - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+   - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+   - **Max Concurrent Requests** — Maximum simultaneous requests per account
+   - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
 
-3. **Leistungsschalter** – Verfolgt Ausfälle pro Anbieter und öffnet automatisch den Stromkreis, wenn ein Schwellenwert erreicht wird:
-   - **GESCHLOSSEN** (fehlerfrei) – Anfragen fließen normal
-   - **OFFEN** – Der Anbieter ist nach wiederholten Ausfällen vorübergehend gesperrt
-   - **HALF_OPEN** – Testen, ob sich der Anbieter erholt hat
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+   - **CLOSED** (Healthy) — Requests flow normally
+   - **OPEN** — Provider is temporarily blocked after repeated failures
+   - **HALF_OPEN** — Testing if provider has recovered
 
-4. **Richtlinien und Sperrkennungen** – Zeigt den Status des Leistungsschalters und die Sperrkennungen mit der Möglichkeit zum erzwungenen Entsperren an.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
 
-5. **Automatische Erkennung von Ratenbegrenzungen** – Überwacht die Header `429` und `Retry-After`, um proaktiv zu vermeiden, dass die Ratenbegrenzungen der Anbieter erreicht werden.
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
 
-**Profi-Tipp:** Verwenden Sie die Schaltfläche **Alle zurücksetzen**, um alle Leistungsschalter und Abklingzeiten zu löschen, wenn ein Anbieter nach einem Ausfall wiederhergestellt wird.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
 
 ---
 
-### Datenbankexport/-import
+### Database Export / Import
 
-Verwalten Sie Datenbanksicherungen unter **Dashboard → Einstellungen → System & Speicher**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
 
-| Aktion                         | Beschreibung                                                                                                                                                                      |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Datenbank exportieren**      | Lädt die aktuelle SQLite-Datenbank als `.sqlite`-Datei herunter                                                                                                                   |
-| **Alle exportieren (.tar.gz)** | Lädt ein vollständiges Backup-Archiv herunter, einschließlich: Datenbank, Einstellungen, Kombinationen, Anbieterverbindungen (keine Anmeldeinformationen), API-Schlüsselmetadaten |
-| **Datenbank importieren**      | Laden Sie eine `.sqlite`-Datei hoch, um die aktuelle Datenbank zu ersetzen. Es wird automatisch ein Backup vor dem Import erstellt                                                |
+| 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                          |
 
 ```bash
 # API: Export database
@@ -596,38 +659,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \
   -F "file=@backup.sqlite"
 ```
 
-**Importvalidierung:** Die importierte Datei wird auf Integrität (SQLite-Pragmaprüfung), erforderliche Tabellen (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) und Größe (max. 100 MB) validiert.
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
 
-**Anwendungsfälle:**
+**Use Cases:**
 
-- OmniRoute zwischen Maschinen migrieren
-- Erstellen Sie externe Backups für die Notfallwiederherstellung
-- Konfigurationen zwischen Teammitgliedern teilen (alle exportieren → Archiv teilen)
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
 
 ---
 
-### Einstellungs-Dashboard
+### Settings Dashboard
 
-Die Einstellungsseite ist zur einfachen Navigation in 5 Registerkarten unterteilt:
+The settings page is organized into 5 tabs for easy navigation:
 
-| Tab                 | Inhalt                                                                                                            |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| **Sicherheit**      | Anmelde-/Passworteinstellungen, IP-Zugriffskontrolle, API-Authentifizierung für `/models` und Anbieterblockierung |
-| **Routing**         | Globale Routing-Strategie (6 Optionen), Wildcard-Modell-Aliase, Fallback-Ketten, Combo-Standardwerte              |
-| **Belastbarkeit**   | Anbieterprofile, bearbeitbare Tarifbegrenzungen, Leistungsschalterstatus, Richtlinien und Sperrkennungen          |
-| **KI**              | Denken Sie an die Budgetkonfiguration, die globale System-Prompt-Injektion, die Prompt-Cache-Statistiken          |
-| **Fortgeschritten** | Globale Proxy-Konfiguration (HTTP/SOCKS5)                                                                         |
+| Tab            | Contents                                                                                       |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **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 |
+| **AI**         | Thinking budget configuration, global system prompt injection, prompt cache stats              |
+| **Advanced**   | Global proxy configuration (HTTP/SOCKS5)                                                       |
 
 ---
 
-### Kosten- und Budgetmanagement
+### Costs & Budget Management
 
-Zugang über **Dashboard → Kosten**.
+Access via **Dashboard → Costs**.
 
-| Tab        | Zweck                                                                                                   |
-| ---------- | ------------------------------------------------------------------------------------------------------- |
-| **Budget** | Legen Sie Ausgabenlimits pro API-Schlüssel mit Tages-/Wochen-/Monatsbudgets und Echtzeitverfolgung fest |
-| **Preise** | Modellpreiseinträge anzeigen und bearbeiten – Kosten pro 1.000 Ein-/Ausgabe-Tokens pro Anbieter         |
+| Tab         | Purpose                                                                                  |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget**  | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider       |
 
 ```bash
 # API: Set a budget
@@ -639,13 +702,13 @@ curl -X POST http://localhost:20128/api/usage/budget \
 curl http://localhost:20128/api/usage/budget
 ```
 
-**Kostenverfolgung:** Bei jeder Anfrage wird die Token-Nutzung protokolliert und die Kosten anhand der Preistabelle berechnet. Sehen Sie sich Aufschlüsselungen in **Dashboard → Nutzung** nach Anbieter, Modell und API-Schlüssel an.
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
 
 ---
 
-### Audiotranskription
+### Audio Transcription
 
-OmniRoute unterstützt die Audiotranskription über den OpenAI-kompatiblen Endpunkt:
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
 
 ```bash
 POST /v1/audio/transcriptions
@@ -659,40 +722,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
   -F "model=deepgram/nova-3"
 ```
 
-Verfügbare Anbieter: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
 
-Unterstützte Audioformate: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
 
 ---
 
-### Combo-Balancing-Strategien
+### Combo Balancing Strategies
 
-Konfigurieren Sie die Balance pro Combo unter **Dashboard → Combos → Erstellen/Bearbeiten → Strategie**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
 
-| Strategie                | Beschreibung                                                                                   |
-| ------------------------ | ---------------------------------------------------------------------------------------------- |
-| **Round-Robin**          | Rotiert nacheinander durch die Modelle                                                         |
-| **Priorität**            | Versucht immer das erste Modell; fällt nur bei Fehler zurück                                   |
-| **Zufällig**             | Wählt für jede Anfrage ein zufälliges Modell aus der Kombination aus                           |
-| **Gewichtet**            | Routen proportional basierend auf den zugewiesenen Gewichten pro Modell                        |
-| **Am wenigsten genutzt** | Leitet zum Modell mit den wenigsten aktuellen Anfragen weiter (verwendet Kombinationsmetriken) |
-| **Kostenoptimiert**      | Leitet zum günstigsten verfügbaren Modell (unter Verwendung der Preistabelle)                  |
+| Strategy           | Description                                                              |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin**    | Rotates through models sequentially                                      |
+| **Priority**       | Always tries the first model; falls back only on error                   |
+| **Random**         | Picks a random model from the combo for each request                     |
+| **Weighted**       | Routes proportionally based on assigned weights per model                |
+| **Least-Used**     | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table)              |
 
-Globale Combo-Standards können unter **Dashboard → Einstellungen → Routing → Combo-Standards** festgelegt werden.
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
 
 ---
 
-### Gesundheits-Dashboard
+### Health Dashboard
 
-Zugriff über **Dashboard → Gesundheit**. Echtzeit-Übersicht über den Systemzustand mit 6 Karten:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
 
-| Karte                  | Was es zeigt                                                              |
-| ---------------------- | ------------------------------------------------------------------------- |
-| **Systemstatus**       | Betriebszeit, Version, Speichernutzung, Datenverzeichnis                  |
-| **Anbietergesundheit** | Zustand des Leistungsschalters pro Anbieter (geschlossen/offen/halboffen) |
-| **Ratenlimits**        | Aktive Abklingzeiten pro Konto mit verbleibender Zeit                     |
-| **Aktive Sperren**     | Anbieter, die durch die Sperrrichtlinie vorübergehend gesperrt sind       |
-| **Signatur-Cache**     | Statistiken zum Deduplizierungs-Cache (aktive Schlüssel, Trefferquote)    |
-| **Latenztelemetrie**   | p50/p95/p99-Latenzaggregation pro Anbieter                                |
+| Card                  | What It Shows                                               |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status**     | Uptime, version, memory usage, data directory               |
+| **Provider Health**   | Per-provider circuit breaker state (Closed/Open/Half-Open)  |
+| **Rate Limits**       | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts**   | Providers temporarily blocked by the lockout policy         |
+| **Signature Cache**   | Deduplication cache stats (active keys, hit rate)           |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider                |
 
-**Profi-Tipp:** Die Gesundheitsseite wird alle 10 Sekunden automatisch aktualisiert. Verwenden Sie die Leistungsschalterkarte, um zu ermitteln, bei welchen Anbietern Probleme auftreten.
+**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/i18n/de/VM_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,403 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/VM_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../es/VM_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../fr/VM_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../de/VM_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../it/VM_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../ru/VM_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../zh-CN/VM_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../ja/VM_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../ko/VM_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../ar/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [in](../in/VM_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../th/VM_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../vi/VM_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../id/VM_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../ms/VM_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../nl/VM_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../pl/VM_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../sv/VM_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../no/VM_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../da/VM_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../fi/VM_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../pt/VM_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../ro/VM_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../hu/VM_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../bg/VM_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../sk/VM_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../uk-UA/VM_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../he/VM_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../phi/VM_DEPLOYMENT_GUIDE.md)
+
+---
+
+# OmniRoute — Guia de Deploy em VM com Cloudflare
+
+Guia completo para instalar e configurar o OmniRoute em uma VM (VPS) com domínio gerenciado via Cloudflare.
+
+---
+
+## Pré-Requisitos
+
+| 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+       |
+
+**Providers testados**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail.
+
+---
+
+## 1. Configurar a VM
+
+### 1.1 Criar a instância
+
+No seu provider de VPS preferido:
+
+- 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`)
+
+### 1.2 Conectar via SSH
+
+```bash
+ssh root@203.0.113.10
+```
+
+### 1.3 Atualizar o sistema
+
+```bash
+apt update && apt upgrade -y
+```
+
+### 1.4 Instalar Docker
+
+```bash
+# Instalar dependências
+apt install -y ca-certificates curl gnupg
+
+# Adicionar repositório oficial do Docker
+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
+apt update
+apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
+```
+
+### 1.5 Instalar nginx
+
+```bash
+apt install -y nginx
+```
+
+### 1.6 Configurar Firewall (UFW)
+
+```bash
+ufw default deny incoming
+ufw default allow outgoing
+ufw allow 22/tcp    # SSH
+ufw allow 80/tcp    # HTTP (redirect)
+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).
+
+---
+
+## 2. Instalar o OmniRoute
+
+### 2.1 Criar diretório de configuração
+
+```bash
+mkdir -p /opt/omniroute
+```
+
+### 2.2 Criar arquivo de variáveis de ambiente
+
+```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
+STORAGE_ENCRYPTION_KEY_VERSION=v1
+MACHINE_ID_SALT=ALTERE-PARA-SALT-UNICO
+
+# === App ===
+PORT=20128
+NODE_ENV=production
+HOSTNAME=0.0.0.0
+DATA_DIR=/app/data
+STORAGE_DRIVER=sqlite
+ENABLE_REQUEST_LOGS=true
+AUTH_COOKIE_SECURE=false
+REQUIRE_API_KEY=false
+
+# === Domain (altere para seu domínio) ===
+BASE_URL=https://llms.seudominio.com
+NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
+
+# === Cloud Sync (opcional) ===
+# 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.
+
+### 2.3 Iniciar o container
+
+```bash
+docker pull diegosouzapw/omniroute:latest
+
+docker run -d \
+  --name omniroute \
+  --restart unless-stopped \
+  --env-file /opt/omniroute/.env \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+### 2.4 Verificar se está rodando
+
+```bash
+docker ps | grep omniroute
+docker logs omniroute --tail 20
+```
+
+Deve exibir: `[DB] SQLite database ready` e `listening on port 20128`.
+
+---
+
+## 3. Configurar nginx (Reverse Proxy)
+
+### 3.1 Gerar certificado SSL (Cloudflare Origin)
+
+No painel da Cloudflare:
+
+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**
+
+```bash
+mkdir -p /etc/nginx/ssl
+
+# Colar o certificado
+nano /etc/nginx/ssl/origin.crt
+
+# Colar a chave privada
+nano /etc/nginx/ssl/origin.key
+
+chmod 600 /etc/nginx/ssl/origin.key
+```
+
+### 3.2 Configuração do nginx
+
+```bash
+cat > /etc/nginx/sites-available/omniroute << 'NGINX'
+# Default server — bloqueia acesso direto por IP
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    listen 443 ssl default_server;
+    listen [::]:443 ssl default_server;
+    ssl_certificate     /etc/nginx/ssl/origin.crt;
+    ssl_certificate_key /etc/nginx/ssl/origin.key;
+    server_name _;
+    return 444;
+}
+
+# OmniRoute — HTTPS
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    server_name llms.seudominio.com;  # Altere para seu domínio
+
+    ssl_certificate     /etc/nginx/ssl/origin.crt;
+    ssl_certificate_key /etc/nginx/ssl/origin.key;
+    ssl_protocols TLSv1.2 TLSv1.3;
+
+    client_max_body_size 100M;
+
+    location / {
+        proxy_pass http://127.0.0.1:20128;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket support
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_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;
+    }
+}
+
+# HTTP → HTTPS redirect
+server {
+    listen 80;
+    listen [::]:80;
+    server_name llms.seudominio.com;
+    return 301 https://$server_name$request_uri;
+}
+NGINX
+```
+
+### 3.3 Ativar e testar
+
+```bash
+# Remover config padrão
+rm -f /etc/nginx/sites-enabled/default
+
+# Ativar OmniRoute
+ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute
+
+# Testar e recarregar
+nginx -t && systemctl reload nginx
+```
+
+---
+
+## 4. Configurar Cloudflare DNS
+
+### 4.1 Adicionar registro DNS
+
+No painel da Cloudflare → DNS:
+
+| Type | Name   | Content                   | Proxy      |
+| ---- | ------ | ------------------------- | ---------- |
+| A    | `llms` | `203.0.113.10` (IP da VM) | ✅ Proxied |
+
+### 4.2 Configurar SSL
+
+Em **SSL/TLS → Overview**:
+
+- Modo: **Full (Strict)**
+
+Em **SSL/TLS → Edge Certificates**:
+
+- Always Use HTTPS: ✅ On
+- Minimum TLS Version: TLS 1.2
+- Automatic HTTPS Rewrites: ✅ On
+
+### 4.3 Testar
+
+```bash
+curl -sI https://llms.seudominio.com/health
+# Deve retornar HTTP/2 200
+```
+
+---
+
+## 5. Operações e Manutenção
+
+### Atualizar para nova versão
+
+```bash
+docker pull diegosouzapw/omniroute:latest
+docker stop omniroute && docker rm omniroute
+docker run -d --name omniroute --restart unless-stopped \
+  --env-file /opt/omniroute/.env \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+### Ver logs
+
+```bash
+docker logs -f omniroute          # Stream em tempo real
+docker logs omniroute --tail 50   # Últimas 50 linhas
+```
+
+### Backup manual do banco
+
+```bash
+# Copiar dados do volume para o host
+docker cp omniroute:/app/data ./backup-$(date +%F)
+
+# Ou comprimir todo o 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
+
+```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 /"
+docker start omniroute
+```
+
+---
+
+## 6. Segurança Avançada
+
+### Restringir nginx para Cloudflare IPs
+
+```bash
+cat > /etc/nginx/cloudflare-ips.conf << 'CF'
+# Cloudflare IPv4 ranges — atualizar periodicamente
+# https://www.cloudflare.com/ips-v4/
+set_real_ip_from 173.245.48.0/20;
+set_real_ip_from 103.21.244.0/22;
+set_real_ip_from 103.22.200.0/22;
+set_real_ip_from 103.31.4.0/22;
+set_real_ip_from 141.101.64.0/18;
+set_real_ip_from 108.162.192.0/18;
+set_real_ip_from 190.93.240.0/20;
+set_real_ip_from 188.114.96.0/20;
+set_real_ip_from 197.234.240.0/22;
+set_real_ip_from 198.41.128.0/17;
+set_real_ip_from 162.158.0.0/15;
+set_real_ip_from 104.16.0.0/13;
+set_real_ip_from 104.24.0.0/14;
+set_real_ip_from 172.64.0.0/13;
+set_real_ip_from 131.0.72.0/22;
+real_ip_header CF-Connecting-IP;
+CF
+```
+
+Adicionar no `nginx.conf` dentro do bloco `http {}`:
+
+```nginx
+include /etc/nginx/cloudflare-ips.conf;
+```
+
+### Install fail2ban
+
+```bash
+apt install -y fail2ban
+systemctl enable fail2ban
+systemctl start fail2ban
+
+# Verificar status
+fail2ban-client status sshd
+```
+
+### Bloquear acesso direto na porta do Docker
+
+```bash
+# Impedir acesso externo direto à porta 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
+apt install -y iptables-persistent
+netfilter-persistent save
+```
+
+---
+
+## 7. Deploy do Cloud Worker (Opcional)
+
+Para acesso remoto via Cloudflare Workers (sem expor a VM diretamente):
+
+```bash
+# No repositório local
+cd omnirouteCloud
+npm install
+npx wrangler login
+npx wrangler deploy
+```
+
+Ver documentação completa em [omnirouteCloud/README.md](../omnirouteCloud/README.md).
+
+---
+
+## Resumo de Portas
+
+| 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) |

docs/i18n/es/A2A-SERVER.md

@@ -0,0 +1,200 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/A2A-SERVER.md) · 🇪🇸 [es](../es/A2A-SERVER.md) · 🇫🇷 [fr](../fr/A2A-SERVER.md) · 🇩🇪 [de](../de/A2A-SERVER.md) · 🇮🇹 [it](../it/A2A-SERVER.md) · 🇷🇺 [ru](../ru/A2A-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/A2A-SERVER.md) · 🇯🇵 [ja](../ja/A2A-SERVER.md) · 🇰🇷 [ko](../ko/A2A-SERVER.md) · 🇸🇦 [ar](../ar/A2A-SERVER.md) · 🇮🇳 [in](../in/A2A-SERVER.md) · 🇹🇭 [th](../th/A2A-SERVER.md) · 🇻🇳 [vi](../vi/A2A-SERVER.md) · 🇮🇩 [id](../id/A2A-SERVER.md) · 🇲🇾 [ms](../ms/A2A-SERVER.md) · 🇳🇱 [nl](../nl/A2A-SERVER.md) · 🇵🇱 [pl](../pl/A2A-SERVER.md) · 🇸🇪 [sv](../sv/A2A-SERVER.md) · 🇳🇴 [no](../no/A2A-SERVER.md) · 🇩🇰 [da](../da/A2A-SERVER.md) · 🇫🇮 [fi](../fi/A2A-SERVER.md) · 🇵🇹 [pt](../pt/A2A-SERVER.md) · 🇷🇴 [ro](../ro/A2A-SERVER.md) · 🇭🇺 [hu](../hu/A2A-SERVER.md) · 🇧🇬 [bg](../bg/A2A-SERVER.md) · 🇸🇰 [sk](../sk/A2A-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/A2A-SERVER.md) · 🇮🇱 [he](../he/A2A-SERVER.md) · 🇵🇭 [phi](../phi/A2A-SERVER.md)
+
+---
+
+# 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/i18n/es/API_REFERENCE.md

@@ -1,12 +1,16 @@
-# Referencia de API
-
-🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md)
-
-Referencia completa para todos los puntos finales de la API de OmniRoute.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/API_REFERENCE.md) · 🇪🇸 [es](../es/API_REFERENCE.md) · 🇫🇷 [fr](../fr/API_REFERENCE.md) · 🇩🇪 [de](../de/API_REFERENCE.md) · 🇮🇹 [it](../it/API_REFERENCE.md) · 🇷🇺 [ru](../ru/API_REFERENCE.md) · 🇨🇳 [zh-CN](../zh-CN/API_REFERENCE.md) · 🇯🇵 [ja](../ja/API_REFERENCE.md) · 🇰🇷 [ko](../ko/API_REFERENCE.md) · 🇸🇦 [ar](../ar/API_REFERENCE.md) · 🇮🇳 [in](../in/API_REFERENCE.md) · 🇹🇭 [th](../th/API_REFERENCE.md) · 🇻🇳 [vi](../vi/API_REFERENCE.md) · 🇮🇩 [id](../id/API_REFERENCE.md) · 🇲🇾 [ms](../ms/API_REFERENCE.md) · 🇳🇱 [nl](../nl/API_REFERENCE.md) · 🇵🇱 [pl](../pl/API_REFERENCE.md) · 🇸🇪 [sv](../sv/API_REFERENCE.md) · 🇳🇴 [no](../no/API_REFERENCE.md) · 🇩🇰 [da](../da/API_REFERENCE.md) · 🇫🇮 [fi](../fi/API_REFERENCE.md) · 🇵🇹 [pt](../pt/API_REFERENCE.md) · 🇷🇴 [ro](../ro/API_REFERENCE.md) · 🇭🇺 [hu](../hu/API_REFERENCE.md) · 🇧🇬 [bg](../bg/API_REFERENCE.md) · 🇸🇰 [sk](../sk/API_REFERENCE.md) · 🇺🇦 [uk-UA](../uk-UA/API_REFERENCE.md) · 🇮🇱 [he](../he/API_REFERENCE.md) · 🇵🇭 [phi](../phi/API_REFERENCE.md)
 
 ---
 
-## Tabla de contenidos
+# 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)
+
+Complete reference for all OmniRoute API endpoints.
+
+---
+
+## Table of Contents
 
 - [Chat Completions](#chat-completions)
 - [Embeddings](#embeddings)
@@ -20,7 +24,7 @@ Referencia completa para todos los puntos finales de la API de OmniRoute.
 
 ---
 
-## Finalizaciones de chat
+## Chat Completions
 
 ```bash
 POST /v1/chat/completions
@@ -36,21 +40,21 @@ Content-Type: application/json
 }
 ```
 
-### Encabezados personalizados
+### Custom Headers
 
-| Encabezado               | Dirección | Descripción                                            |
-| ------------------------ | --------- | ------------------------------------------------------ |
-| `X-OmniRoute-No-Cache`   | Solicitar | Establezca en `true` para omitir el caché              |
-| `X-OmniRoute-Progress`   | Solicitar | Establecer en `true` para eventos de progreso          |
-| `Idempotency-Key`        | Solicitar | Clave de desduplicación (ventana 5s)                   |
-| `X-Request-Id`           | Solicitar | Clave de desduplicación alternativa                    |
-| `X-OmniRoute-Cache`      | Respuesta | `HIT` o `MISS` (sin transmisión)                       |
-| `X-OmniRoute-Idempotent` | Respuesta | `true` si está deduplicado                             |
-| `X-OmniRoute-Progress`   | Respuesta | `enabled` si el seguimiento del progreso está activado |
+| 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 |
 
 ---
 
-## Incrustaciones
+## Embeddings
 
 ```bash
 POST /v1/embeddings
@@ -63,7 +67,7 @@ Content-Type: application/json
 }
 ```
 
-Proveedores disponibles: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
 
 ```bash
 # List all embedding models
@@ -72,7 +76,7 @@ GET /v1/embeddings
 
 ---
 
-## Generación de imágenes
+## Image Generation
 
 ```bash
 POST /v1/images/generations
@@ -86,7 +90,7 @@ Content-Type: application/json
 }
 ```
 
-Proveedores disponibles: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
 
 ```bash
 # List all image models
@@ -95,7 +99,7 @@ GET /v1/images/generations
 
 ---
 
-## Listar modelos
+## List Models
 
 ```bash
 GET /v1/models
@@ -106,22 +110,22 @@ Authorization: Bearer your-api-key
 
 ---
 
-## Puntos finales de compatibilidad
+## Compatibility Endpoints
 
-| Método   | Camino                      | Formato                  |
-| -------- | --------------------------- | ------------------------ |
-| PUBLICAR | `/v1/chat/completions`      | Abierta AI               |
-| PUBLICAR | `/v1/messages`              | Antrópico                |
-| PUBLICAR | `/v1/responses`             | Respuestas de OpenAI     |
-| PUBLICAR | `/v1/embeddings`            | Abierta AI               |
-| PUBLICAR | `/v1/images/generations`    | Abierta AI               |
-| OBTENER  | `/v1/models`                | Abierta AI               |
-| PUBLICAR | `/v1/messages/count_tokens` | Antrópico                |
-| OBTENER  | `/v1beta/models`            | Géminis                  |
-| PUBLICAR | `/v1beta/models/{...path}`  | Géminis genera contenido |
-| PUBLICAR | `/v1/api/chat`              | Ollamá                   |
+| Method | Path                        | Format                 |
+| ------ | --------------------------- | ---------------------- |
+| POST   | `/v1/chat/completions`      | OpenAI                 |
+| POST   | `/v1/messages`              | Anthropic              |
+| POST   | `/v1/responses`             | OpenAI Responses       |
+| POST   | `/v1/embeddings`            | OpenAI                 |
+| POST   | `/v1/images/generations`    | OpenAI                 |
+| GET    | `/v1/models`                | OpenAI                 |
+| POST   | `/v1/messages/count_tokens` | Anthropic              |
+| GET    | `/v1beta/models`            | Gemini                 |
+| POST   | `/v1beta/models/{...path}`  | Gemini generateContent |
+| POST   | `/v1/api/chat`              | Ollama                 |
 
-### Rutas de proveedores dedicadas
+### Dedicated Provider Routes
 
 ```bash
 POST /v1/providers/{provider}/chat/completions
@@ -129,11 +133,11 @@ POST /v1/providers/{provider}/embeddings
 POST /v1/providers/{provider}/images/generations
 ```
 
-El prefijo del proveedor se agrega automáticamente si falta. Los modelos no coincidentes devuelven `400`.
+The provider prefix is auto-added if missing. Mismatched models return `400`.
 
 ---
 
-## Caché semántico
+## Semantic Cache
 
 ```bash
 # Get cache stats
@@ -143,7 +147,7 @@ GET /api/cache
 DELETE /api/cache
 ```
 
-Ejemplo de respuesta:
+Response example:
 
 ```json
 {
@@ -162,154 +166,164 @@ Ejemplo de respuesta:
 
 ---
 
-## Panel de control y gestión
+## Dashboard & Management
 
-### Autenticación
+### Authentication
 
-| Punto final                   | Método        | Descripción                         |
-| ----------------------------- | ------------- | ----------------------------------- |
-| `/api/auth/login`             | PUBLICAR      | Iniciar sesión                      |
-| `/api/auth/logout`            | PUBLICAR      | Cerrar sesión                       |
-| `/api/settings/require-login` | OBTENER/PONER | Alternar inicio de sesión requerido |
+| Endpoint                      | Method  | Description           |
+| ----------------------------- | ------- | --------------------- |
+| `/api/auth/login`             | POST    | Login                 |
+| `/api/auth/logout`            | POST    | Logout                |
+| `/api/settings/require-login` | GET/PUT | Toggle login required |
 
-### Gestión de proveedores
+### Provider Management
 
-| Punto final                  | Método                    | Descripción                         |
-| ---------------------------- | ------------------------- | ----------------------------------- |
-| `/api/providers`             | OBTENER/PUBLICAR          | Listar/crear proveedores            |
-| `/api/providers/[id]`        | OBTENER/PONER/ELIMINAR    | Gestionar un proveedor              |
-| `/api/providers/[id]/test`   | PUBLICAR                  | Conexión del proveedor de pruebas   |
-| `/api/providers/[id]/models` | OBTENER                   | Listar modelos de proveedores       |
-| `/api/providers/validate`    | PUBLICAR                  | Validar configuración del proveedor |
-| `/api/provider-nodes*`       | Varios                    | Gestión de nodos de proveedores     |
-| `/api/provider-models`       | OBTENER/PUBLICAR/ELIMINAR | Modelos personalizados              |
+| 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            |
 
-### Flujos de OAuth
+### OAuth Flows
 
-| Punto final                      | Método | Descripción                    |
-| -------------------------------- | ------ | ------------------------------ |
-| `/api/oauth/[provider]/[action]` | Varios | OAuth específico del proveedor |
+| Endpoint                         | Method  | Description             |
+| -------------------------------- | ------- | ----------------------- |
+| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth |
 
-### Enrutamiento y configuración
+### Routing & Config
 
-| Punto final           | Método           | Descripción                            |
-| --------------------- | ---------------- | -------------------------------------- |
-| `/api/models/alias`   | OBTENER/PUBLICAR | Alias ​​de modelos                     |
-| `/api/models/catalog` | OBTENER          | Todos los modelos por proveedor + tipo |
-| `/api/combos*`        | Varios           | Gestión combinada                      |
-| `/api/keys*`          | Varios           | Gestión de claves API                  |
-| `/api/pricing`        | OBTENER          | Precios del modelo                     |
+| Endpoint              | Method   | Description                   |
+| --------------------- | -------- | ----------------------------- |
+| `/api/models/alias`   | GET/POST | Model aliases                 |
+| `/api/models/catalog` | GET      | All models by provider + type |
+| `/api/combos*`        | Various  | Combo management              |
+| `/api/keys*`          | Various  | API key management            |
+| `/api/pricing`        | GET      | Model pricing                 |
 
-### Uso y análisis
+### Usage & Analytics
 
-| Punto final                 | Método  | Descripción                    |
-| --------------------------- | ------- | ------------------------------ |
-| `/api/usage/history`        | OBTENER | Historial de uso               |
-| `/api/usage/logs`           | OBTENER | Registros de uso               |
-| `/api/usage/request-logs`   | OBTENER | Registros a nivel de solicitud |
-| `/api/usage/[connectionId]` | OBTENER | Uso por conexión               |
+| Endpoint                    | Method | Description          |
+| --------------------------- | ------ | -------------------- |
+| `/api/usage/history`        | GET    | Usage history        |
+| `/api/usage/logs`           | GET    | Usage logs           |
+| `/api/usage/request-logs`   | GET    | Request-level logs   |
+| `/api/usage/[connectionId]` | GET    | Per-connection usage |
 
-### Configuración
+### Settings
 
-| Punto final                     | Método        | Descripción                             |
-| ------------------------------- | ------------- | --------------------------------------- |
-| `/api/settings`                 | OBTENER/PONER | Configuraciones generales               |
-| `/api/settings/proxy`           | OBTENER/PONER | Configuración de proxy de red           |
-| `/api/settings/proxy/test`      | PUBLICAR      | Probar conexión proxy                   |
-| `/api/settings/ip-filter`       | OBTENER/PONER | Lista de IP permitidas/lista de bloqueo |
-| `/api/settings/thinking-budget` | OBTENER/PONER | Presupuesto simbólico de razonamiento   |
-| `/api/settings/system-prompt`   | OBTENER/PONER | Aviso del sistema global                |
+| 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   |
 
-### Monitoreo
+### Monitoring
 
-| Punto final              | Método           | Descripción                    |
-| ------------------------ | ---------------- | ------------------------------ |
-| `/api/sessions`          | OBTENER          | Seguimiento de sesión activa   |
-| `/api/rate-limits`       | OBTENER          | Límites de tasas por cuenta    |
-| `/api/monitoring/health` | OBTENER          | Control de salud               |
-| `/api/cache`             | OBTENER/ELIMINAR | Estadísticas de caché / borrar |
+| 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     |
 
-### Copia de seguridad y exportación/importación
+### Backup & Export/Import
 
-| Punto final                 | Método   | Descripción                                                   |
-| --------------------------- | -------- | ------------------------------------------------------------- |
-| `/api/db-backups`           | OBTENER  | Listar copias de seguridad disponibles                        |
-| `/api/db-backups`           | PONER    | Crear una copia de seguridad manual                           |
-| `/api/db-backups`           | PUBLICAR | Restaurar desde una copia de seguridad específica             |
-| `/api/db-backups/export`    | OBTENER  | Descargar la base de datos como archivo .sqlite               |
-| `/api/db-backups/import`    | PUBLICAR | Cargue el archivo .sqlite para reemplazar la base de datos    |
-| `/api/db-backups/exportAll` | OBTENER  | Descargue la copia de seguridad completa como archivo .tar.gz |
+| Endpoint                    | Method | Description                             |
+| --------------------------- | ------ | --------------------------------------- |
+| `/api/db-backups`           | GET    | List available backups                  |
+| `/api/db-backups`           | PUT    | Create a manual backup                  |
+| `/api/db-backups`           | POST   | Restore from a specific backup          |
+| `/api/db-backups/export`    | GET    | Download database as .sqlite file       |
+| `/api/db-backups/import`    | POST   | Upload .sqlite file to replace database |
+| `/api/db-backups/exportAll` | GET    | Download full backup as .tar.gz archive |
 
-### Sincronización en la nube
+### Cloud Sync
 
-| Punto final            | Método   | Descripción                              |
-| ---------------------- | -------- | ---------------------------------------- |
-| `/api/sync/cloud`      | Varios   | Operaciones de sincronización en la nube |
-| `/api/sync/initialize` | PUBLICAR | Inicializar sincronización               |
-| `/api/cloud/*`         | Varios   | Gestión de la nube                       |
+| Endpoint               | Method  | Description           |
+| ---------------------- | ------- | --------------------- |
+| `/api/sync/cloud`      | Various | Cloud sync operations |
+| `/api/sync/initialize` | POST    | Initialize sync       |
+| `/api/cloud/*`         | Various | Cloud management      |
 
-### Herramientas CLI
+### CLI Tools
 
-| Punto final                        | Método  | Descripción                         |
-| ---------------------------------- | ------- | ----------------------------------- |
-| `/api/cli-tools/claude-settings`   | OBTENER | Estado de Claude CLI                |
-| `/api/cli-tools/codex-settings`    | OBTENER | Estado de la CLI del Códice         |
-| `/api/cli-tools/droid-settings`    | OBTENER | Estado de la CLI del droide         |
-| `/api/cli-tools/openclaw-settings` | OBTENER | Estado de la CLI de OpenClaw        |
-| `/api/cli-tools/runtime/[toolId]`  | OBTENER | Tiempo de ejecución de CLI genérico |
+| Endpoint                           | Method | Description         |
+| ---------------------------------- | ------ | ------------------- |
+| `/api/cli-tools/claude-settings`   | GET    | Claude CLI status   |
+| `/api/cli-tools/codex-settings`    | GET    | Codex CLI status    |
+| `/api/cli-tools/droid-settings`    | GET    | Droid CLI status    |
+| `/api/cli-tools/openclaw-settings` | GET    | OpenClaw CLI status |
+| `/api/cli-tools/runtime/[toolId]`  | GET    | Generic CLI runtime |
 
-Las respuestas de CLI incluyen: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
+CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
 
-### Resiliencia y límites de tasas
+### ACP Agents
 
-| Punto final             | Método        | Descripción                                |
-| ----------------------- | ------------- | ------------------------------------------ |
-| `/api/resilience`       | OBTENER/PONER | Obtener/actualizar perfiles de resiliencia |
-| `/api/resilience/reset` | PUBLICAR      | Restablecer disyuntores                    |
-| `/api/rate-limits`      | OBTENER       | Estado del límite de tasa por cuenta       |
-| `/api/rate-limit`       | OBTENER       | Configuración del límite de tasa global    |
+| 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                |
 
-### Evaluaciones
+GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom).
 
-| Punto final  | Método           | Descripción                                        |
-| ------------ | ---------------- | -------------------------------------------------- |
-| `/api/evals` | OBTENER/PUBLICAR | Listar conjuntos de evaluación/ejecutar evaluación |
+### Resilience & Rate Limits
 
-### Políticas
+| 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 |
 
-| Punto final     | Método                    | Descripción                           |
-| --------------- | ------------------------- | ------------------------------------- |
-| `/api/policies` | OBTENER/PUBLICAR/ELIMINAR | Administrar políticas de enrutamiento |
+### Evals
 
-### Cumplimiento
+| Endpoint     | Method   | Description                       |
+| ------------ | -------- | --------------------------------- |
+| `/api/evals` | GET/POST | List eval suites / run evaluation |
 
-| Punto final                 | Método  | Descripción                                      |
-| --------------------------- | ------- | ------------------------------------------------ |
-| `/api/compliance/audit-log` | OBTENER | Registro de auditoría de cumplimiento (última N) |
+### Policies
 
-### v1beta (Compatible con Gemini)
+| Endpoint        | Method          | Description             |
+| --------------- | --------------- | ----------------------- |
+| `/api/policies` | GET/POST/DELETE | Manage routing policies |
 
-| Punto final                | Método   | Descripción                           |
-| -------------------------- | -------- | ------------------------------------- |
-| `/v1beta/models`           | OBTENER  | Listar modelos en formato Gemini      |
-| `/v1beta/models/{...path}` | PUBLICAR | Géminis `generateContent` punto final |
+### Compliance
 
-Estos puntos finales reflejan el formato API de Gemini para clientes que esperan compatibilidad nativa con el SDK de Gemini.
+| Endpoint                    | Method | Description                   |
+| --------------------------- | ------ | ----------------------------- |
+| `/api/compliance/audit-log` | GET    | Compliance audit log (last N) |
 
-### API internas/del sistema
+### v1beta (Gemini-Compatible)
 
-| Punto final     | Método   | Descripción                                                                         |
-| --------------- | -------- | ----------------------------------------------------------------------------------- |
-| `/api/init`     | OBTENER  | Comprobación de inicialización de la aplicación (utilizada en la primera ejecución) |
-| `/api/tags`     | OBTENER  | Etiquetas de modelo compatibles con Ollama (para clientes de Ollama)                |
-| `/api/restart`  | PUBLICAR | Activar reinicio ordenado del servidor                                              |
-| `/api/shutdown` | PUBLICAR | Activar el cierre ordenado del servidor                                             |
+| Endpoint                   | Method | Description                       |
+| -------------------------- | ------ | --------------------------------- |
+| `/v1beta/models`           | GET    | List models in Gemini format      |
+| `/v1beta/models/{...path}` | POST   | Gemini `generateContent` endpoint |
 
-> **Nota:** Estos puntos finales se utilizan internamente por el sistema o para la compatibilidad del cliente Ollama. Por lo general, los usuarios finales no los llaman.
+These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility.
+
+### Internal / System APIs
+
+| Endpoint        | Method | Description                                          |
+| --------------- | ------ | ---------------------------------------------------- |
+| `/api/init`     | GET    | Application initialization check (used on first run) |
+| `/api/tags`     | GET    | Ollama-compatible model tags (for Ollama clients)    |
+| `/api/restart`  | POST   | Trigger graceful server restart                      |
+| `/api/shutdown` | POST   | Trigger graceful server shutdown                     |
+
+> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users.
 
 ---
 
-## Transcripción de audio
+## Audio Transcription
 
 ```bash
 POST /v1/audio/transcriptions
@@ -317,9 +331,9 @@ Authorization: Bearer your-api-key
 Content-Type: multipart/form-data
 ```
 
-Transcribe archivos de audio usando Deepgram o AssemblyAI.
+Transcribe audio files using Deepgram or AssemblyAI.
 
-**Solicitud:**
+**Request:**
 
 ```bash
 curl -X POST http://localhost:20128/v1/audio/transcriptions \
@@ -328,7 +342,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
   -F "model=deepgram/nova-3"
 ```
 
-**Respuesta:**
+**Response:**
 
 ```json
 {
@@ -339,15 +353,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
 }
 ```
 
-**Proveedores admitidos:** `deepgram/nova-3`, `assemblyai/best`.
+**Supported providers:** `deepgram/nova-3`, `assemblyai/best`.
 
-**Formatos admitidos:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
 
 ---
 
-## Compatibilidad con Ollama
+## Ollama Compatibility
 
-Para clientes que utilizan el formato API de Ollama:
+For clients that use Ollama's API format:
 
 ```bash
 # Chat endpoint (Ollama format)
@@ -357,18 +371,18 @@ POST /v1/api/chat
 GET /api/tags
 ```
 
-Las solicitudes se traducen automáticamente entre Ollama y los formatos internos.
+Requests are automatically translated between Ollama and internal formats.
 
 ---
 
-## Telemetría
+## Telemetry
 
 ```bash
 # Get latency telemetry summary (p50/p95/p99 per provider)
 GET /api/telemetry/summary
 ```
 
-**Respuesta:**
+**Response:**
 
 ```json
 {
@@ -381,7 +395,7 @@ GET /api/telemetry/summary
 
 ---
 
-## Presupuesto
+## Budget
 
 ```bash
 # Get budget status for all API keys
@@ -400,7 +414,7 @@ Content-Type: application/json
 
 ---
 
-## Disponibilidad del modelo
+## Model Availability
 
 ```bash
 # Get real-time model availability across all providers
@@ -417,25 +431,25 @@ Content-Type: application/json
 
 ---
 
-## Procesamiento de solicitudes
+## Request Processing
 
-1. El cliente envía la solicitud a `/v1/*`
-2. Llamadas del controlador de ruta `handleChat`, `handleEmbedding`, `handleAudioTranscription` o `handleImageGeneration`
-3. Se resuelve el modelo (proveedor directo/modelo o alias/combo)
-4. Credenciales seleccionadas de la base de datos local con filtrado de disponibilidad de cuenta
-5. Para chat: `handleChatCore`: detección de formato, traducción, verificación de caché, verificación de idempotencia
-6. El ejecutor del proveedor envía una solicitud ascendente
-7. Respuesta traducida al formato del cliente (chat) o devuelta tal como está (incrustaciones/imágenes/audio)
-8. Uso/registro registrado
-9. El respaldo se aplica en caso de errores de acuerdo con las reglas combinadas.
+1. Client sends request to `/v1/*`
+2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration`
+3. Model is resolved (direct provider/model or alias/combo)
+4. Credentials selected from local DB with account availability filtering
+5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check
+6. Provider executor sends upstream request
+7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio)
+8. Usage/logging recorded
+9. Fallback applies on errors according to combo rules
 
-Referencia de arquitectura completa: [link](ARCHITECTURE.md)
+Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md)
 
 ---
 
-## Autenticación
+## Authentication
 
-- Las rutas del panel (`/dashboard/*`) utilizan la cookie `auth_token`
-- El inicio de sesión utiliza el hash de contraseña guardado; recurrir a `INITIAL_PASSWORD`
-- `requireLogin` conmutable a través de `/api/settings/require-login`
-- Las rutas `/v1/*` opcionalmente requieren una clave API de portador cuando `REQUIRE_API_KEY=true`
+- Dashboard routes (`/dashboard/*`) use `auth_token` cookie
+- Login uses saved password hash; fallback to `INITIAL_PASSWORD`
+- `requireLogin` toggleable via `/api/settings/require-login`
+- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true`

docs/i18n/es/ARCHITECTURE.md

@@ -1,71 +1,75 @@
-# Arquitectura OmniRoute
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/ARCHITECTURE.md) · 🇪🇸 [es](../es/ARCHITECTURE.md) · 🇫🇷 [fr](../fr/ARCHITECTURE.md) · 🇩🇪 [de](../de/ARCHITECTURE.md) · 🇮🇹 [it](../it/ARCHITECTURE.md) · 🇷🇺 [ru](../ru/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../zh-CN/ARCHITECTURE.md) · 🇯🇵 [ja](../ja/ARCHITECTURE.md) · 🇰🇷 [ko](../ko/ARCHITECTURE.md) · 🇸🇦 [ar](../ar/ARCHITECTURE.md) · 🇮🇳 [in](../in/ARCHITECTURE.md) · 🇹🇭 [th](../th/ARCHITECTURE.md) · 🇻🇳 [vi](../vi/ARCHITECTURE.md) · 🇮🇩 [id](../id/ARCHITECTURE.md) · 🇲🇾 [ms](../ms/ARCHITECTURE.md) · 🇳🇱 [nl](../nl/ARCHITECTURE.md) · 🇵🇱 [pl](../pl/ARCHITECTURE.md) · 🇸🇪 [sv](../sv/ARCHITECTURE.md) · 🇳🇴 [no](../no/ARCHITECTURE.md) · 🇩🇰 [da](../da/ARCHITECTURE.md) · 🇫🇮 [fi](../fi/ARCHITECTURE.md) · 🇵🇹 [pt](../pt/ARCHITECTURE.md) · 🇷🇴 [ro](../ro/ARCHITECTURE.md) · 🇭🇺 [hu](../hu/ARCHITECTURE.md) · 🇧🇬 [bg](../bg/ARCHITECTURE.md) · 🇸🇰 [sk](../sk/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../uk-UA/ARCHITECTURE.md) · 🇮🇱 [he](../he/ARCHITECTURE.md) · 🇵🇭 [phi](../phi/ARCHITECTURE.md)
 
-🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md)
+---
 
-_Última actualización: 2026-02-18_
+# OmniRoute Architecture
 
-## Resumen ejecutivo
+🌐 **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)
 
-OmniRoute es un panel y una puerta de enlace de enrutamiento de IA local creado en Next.js.
-Proporciona un único punto final compatible con OpenAI (`/v1/*`) y enruta el tráfico a través de múltiples proveedores ascendentes con traducción, respaldo, actualización de tokens y seguimiento de uso.
+_Last updated: 2026-03-04_
 
-Capacidades principales:
+## Executive Summary
 
-- Superficie API compatible con OpenAI para CLI/herramientas (28 proveedores)
-- Traducción de solicitudes/respuestas entre formatos de proveedores.
-- Modelo combinado de respaldo (secuencia multimodelo)
-- Respaldo a nivel de cuenta (varias cuentas por proveedor)
-- Gestión de conexión de proveedor de claves OAuth + API
-- Generación de incrustación vía `/v1/embeddings` (6 proveedores, 9 modelos)
-- Generación de imágenes vía `/v1/images/generations` (4 proveedores, 9 modelos)
-- Piense en el análisis de etiquetas (`<think>...</think>`) para modelos de razonamiento
-- Saneamiento de respuesta para una estricta compatibilidad con OpenAI SDK
-- Normalización de roles (desarrollador → sistema, sistema → usuario) para compatibilidad entre proveedores
-- Conversión de salida estructurada (json_schema → Gemini ResponseSchema)
-- Persistencia local para proveedores, claves, alias, combos, configuraciones, precios.
-- Seguimiento de uso/costos y registro de solicitudes
-- Sincronización en la nube opcional para sincronización multidispositivo/estado
-- Lista de IP permitidas/lista de bloqueo para control de acceso a API
-- Pensando en la gestión del presupuesto (transferencia/automática/personalizada/adaptativa)
-- Inyección rápida del sistema global
-- Seguimiento de sesiones y toma de huellas digitales
-- Limitación de tarifas mejorada por cuenta con perfiles específicos del proveedor
-- Patrón de disyuntor para la resiliencia del proveedor
-- Protección de rebaño anti-truenos con bloqueo mutex
-- Caché de deduplicación de solicitudes basado en firmas
-- Capa de dominio: disponibilidad del modelo, reglas de costos, política de respaldo, política de bloqueo
-- Persistencia del estado del dominio (caché de escritura SQLite para respaldos, presupuestos, bloqueos, disyuntores)
-- Motor de políticas para la evaluación centralizada de solicitudes (bloqueo → presupuesto → respaldo)
-- Solicitar telemetría con agregación de latencia p50/p95/p99
-- ID de correlación (X-Request-Id) para seguimiento de un extremo a otro
-- Registro de auditoría de cumplimiento con opción de exclusión por clave API
-- Marco de evaluación para el aseguramiento de la calidad del LLM.
-- Panel de interfaz de usuario de resiliencia con estado del disyuntor en tiempo real
-- Proveedores modulares de OAuth (12 módulos individuales bajo `src/lib/oauth/providers/`)
+OmniRoute is a local AI routing gateway and dashboard built on Next.js.
+It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
 
-Modelo de tiempo de ejecución principal:
+Core capabilities:
 
-- Las rutas de la aplicación Next.js bajo `src/app/api/*` implementan API de panel y API de compatibilidad.
-- Un núcleo de enrutamiento/SSE compartido en `src/sse/*` + `open-sse/*` maneja la ejecución, traducción, transmisión, respaldo y uso del proveedor.
+- OpenAI-compatible API surface for CLI/tools (28 providers)
+- Request/response translation across provider formats
+- Model combo fallback (multi-model sequence)
+- Account-level fallback (multi-account per provider)
+- OAuth + API-key provider connection management
+- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
+- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Think tag parsing (`<think>...</think>`) for reasoning models
+- Response sanitization for strict OpenAI SDK compatibility
+- Role normalization (developer→system, system→user) for cross-provider compatibility
+- Structured output conversion (json_schema → Gemini responseSchema)
+- Local persistence for providers, keys, aliases, combos, settings, pricing
+- Usage/cost tracking and request logging
+- Optional cloud sync for multi-device/state sync
+- IP allowlist/blocklist for API access control
+- Thinking budget management (passthrough/auto/custom/adaptive)
+- Global system prompt injection
+- Session tracking and fingerprinting
+- Per-account enhanced rate limiting with provider-specific profiles
+- Circuit breaker pattern for provider resilience
+- Anti-thundering herd protection with mutex locking
+- Signature-based request deduplication cache
+- Domain layer: model availability, cost rules, fallback policy, lockout policy
+- 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
+- Correlation ID (X-Request-Id) for end-to-end tracing
+- Compliance audit logging with opt-out per API key
+- Eval framework for LLM quality assurance
+- Resilience UI dashboard with real-time circuit breaker status
+- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`)
 
-## Alcance y límites
+Primary runtime model:
 
-### En alcance
+- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
+- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
 
-- Tiempo de ejecución de la puerta de enlace local
-- API de gestión de paneles
-- Autenticación de proveedor y actualización de token
-- Solicitar traducción y transmisión SSE
-- Estado local + persistencia de uso.
-- Orquestación de sincronización en la nube opcional
+## Scope and Boundaries
 
-### Fuera de alcance
+### In Scope
 
-- Implementación del servicio en la nube detrás de `NEXT_PUBLIC_CLOUD_URL`
-- Proveedor SLA/plano de control fuera del proceso local
-- Los propios binarios CLI externos (Claude CLI, Codex CLI, etc.)
+- Local gateway runtime
+- Dashboard management APIs
+- Provider authentication and token refresh
+- Request translation and SSE streaming
+- Local state + usage persistence
+- Optional cloud sync orchestration
 
-## Contexto del sistema de alto nivel
+### Out of Scope
+
+- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
+- Provider SLA/control plane outside local process
+- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
+
+## High-Level System Context
 
 ```mermaid
 flowchart LR
@@ -81,8 +85,8 @@ 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]
@@ -113,151 +117,152 @@ flowchart LR
     DASH --> CLOUD
 ```
 
-## Componentes principales del tiempo de ejecución
+## Core Runtime Components
 
-## 1) API y capa de enrutamiento (rutas de la aplicación Next.js)
+## 1) API and Routing Layer (Next.js App Routes)
 
-Directorios principales:
+Main directories:
 
-- `src/app/api/v1/*` y `src/app/api/v1beta/*` para API de compatibilidad
-- `src/app/api/*` para API de administración/configuración
-- Siguientes reescrituras en `next.config.mjs` asignan `/v1/*` a `/api/v1/*`
+- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
+- `src/app/api/*` for management/configuration APIs
+- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
 
-Rutas de compatibilidad importantes:
+Important compatibility routes:
 
 - `src/app/api/v1/chat/completions/route.ts`
 - `src/app/api/v1/messages/route.ts`
 - `src/app/api/v1/responses/route.ts`
-- `src/app/api/v1/models/route.ts` — incluye modelos personalizados con `custom: true`
-- `src/app/api/v1/embeddings/route.ts` — generación de incrustación (6 proveedores)
-- `src/app/api/v1/images/generations/route.ts` — generación de imágenes (4+ proveedores, incluido Antigravity/Nebius)
+- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`
+- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)
+- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)
 - `src/app/api/v1/messages/count_tokens/route.ts`
-- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — chat dedicado por proveedor
-- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — incorporaciones dedicadas por proveedor
-- `src/app/api/v1/providers/[provider]/images/generations/route.ts`: imágenes dedicadas por proveedor
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images
 - `src/app/api/v1beta/models/route.ts`
 - `src/app/api/v1beta/models/[...path]/route.ts`
 
-Dominios de gestión:
+Management domains:
 
-- Autenticación/configuración: `src/app/api/auth/*`, `src/app/api/settings/*`
-- Proveedores/conexiones: `src/app/api/providers*`
-- Nodos proveedores: `src/app/api/provider-nodes*`
-- Modelos personalizados: `src/app/api/provider-models` (GET/POST/DELETE)
-- Catálogo de modelos: `src/app/api/models/catalog` (OBTENER)
-- Configuración de proxy: `src/app/api/settings/proxy` (OBTENER/PONER/BORRAR) + `src/app/api/settings/proxy/test` (POST)
+- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
+- 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/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/*`
-- Claves/alias/combos/precios: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
-- Uso: `src/app/api/usage/*`
-- Sincronización/nube: `src/app/api/sync/*`, `src/app/api/cloud/*`
-- Ayudantes de herramientas CLI: `src/app/api/cli-tools/*`
-- Filtro IP: `src/app/api/settings/ip-filter` (OBTENER/PUT)
-- Presupuesto de pensamiento: `src/app/api/settings/thinking-budget` (GET/PUT)
-- Mensaje del sistema: `src/app/api/settings/system-prompt` (OBTENER/PUT)
-- Sesiones: `src/app/api/sessions` (OBTENER)
-- Límites de tasa: `src/app/api/rate-limits` (GET)
-- Resiliencia: `src/app/api/resilience` (GET/PATCH): perfiles de proveedor, disyuntor, estado límite de velocidad
-- Restablecimiento de resiliencia: `src/app/api/resilience/reset` (POST) — restablecer interruptores + tiempos de reutilización
-- Estadísticas de caché: `src/app/api/cache/stats` (OBTENER/ELIMINAR)
-- Disponibilidad del modelo: `src/app/api/models/availability` (GET/POST)
-- Telemetría: `src/app/api/telemetry/summary` (OBTENER)
-- Presupuesto: `src/app/api/usage/budget` (GET/POST)
-- Cadenas de respaldo: `src/app/api/fallback/chains` (GET/POST/DELETE)
-- Auditoría de cumplimiento: `src/app/api/compliance/audit-log` (GET)
-- Evaluaciones: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
-- Políticas: `src/app/api/policies` (GET/POST)
+- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
+- Usage: `src/app/api/usage/*`
+- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
+- CLI tooling helpers: `src/app/api/cli-tools/*`
+- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)
+- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)
+- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)
+- Sessions: `src/app/api/sessions` (GET)
+- Rate limits: `src/app/api/rate-limits` (GET)
+- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns
+- Cache stats: `src/app/api/cache/stats` (GET/DELETE)
+- Model availability: `src/app/api/models/availability` (GET/POST)
+- Telemetry: `src/app/api/telemetry/summary` (GET)
+- Budget: `src/app/api/usage/budget` (GET/POST)
+- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET)
+- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
+- Policies: `src/app/api/policies` (GET/POST)
 
-## 2) SSE + Núcleo de traducción
+## 2) SSE + Translation Core
 
-Módulos de flujo principales:
+Main flow modules:
 
-- Entrada: `src/sse/handlers/chat.ts`
-- Orquestación central: `open-sse/handlers/chatCore.ts`
-- Adaptadores de ejecución del proveedor: `open-sse/executors/*`
-- Detección de formato/configuración del proveedor: `open-sse/services/provider.ts`
-- Análisis/resolución del modelo: `src/sse/services/model.ts`, `open-sse/services/model.ts`
-- Lógica de reserva de cuenta: `open-sse/services/accountFallback.ts`
-- Registro de traducción: `open-sse/translator/index.ts`
-- Transformaciones de flujo: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
-- Extracción/normalización de uso: `open-sse/utils/usageTracking.ts`
-- Piense en el analizador de etiquetas: `open-sse/utils/thinkTagParser.ts`
-- Controlador de incrustación: `open-sse/handlers/embeddings.ts`
-- Incrustar registro de proveedores: `open-sse/config/embeddingRegistry.ts`
-- Controlador de generación de imágenes: `open-sse/handlers/imageGeneration.ts`
-- Registro de proveedor de imágenes: `open-sse/config/imageRegistry.ts`
-- Sanitización de respuesta: `open-sse/handlers/responseSanitizer.ts`
-- Normalización de roles: `open-sse/services/roleNormalizer.ts`
+- Entry: `src/sse/handlers/chat.ts`
+- Core orchestration: `open-sse/handlers/chatCore.ts`
+- Provider execution adapters: `open-sse/executors/*`
+- Format detection/provider config: `open-sse/services/provider.ts`
+- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
+- Account fallback logic: `open-sse/services/accountFallback.ts`
+- Translation registry: `open-sse/translator/index.ts`
+- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
+- Think tag parser: `open-sse/utils/thinkTagParser.ts`
+- Embedding handler: `open-sse/handlers/embeddings.ts`
+- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
+- Image generation handler: `open-sse/handlers/imageGeneration.ts`
+- Image provider registry: `open-sse/config/imageRegistry.ts`
+- Response sanitization: `open-sse/handlers/responseSanitizer.ts`
+- Role normalization: `open-sse/services/roleNormalizer.ts`
 
-Servicios (lógica de negocios):
+Services (business logic):
 
-- Selección/puntuación de cuenta: `open-sse/services/accountSelector.ts`
-- Gestión del ciclo de vida del contexto: `open-sse/services/contextManager.ts`
-- Aplicación del filtro IP: `open-sse/services/ipFilter.ts`
-- Seguimiento de sesión: `open-sse/services/sessionManager.ts`
-- Solicitar deduplicación: `open-sse/services/signatureCache.ts`
-- Inyección de aviso del sistema: `open-sse/services/systemPrompt.ts`
-- Pensando en la gestión del presupuesto: `open-sse/services/thinkingBudget.ts`
-- Enrutamiento del modelo comodín: `open-sse/services/wildcardRouter.ts`
-- Gestión de límites de tarifas: `open-sse/services/rateLimitManager.ts`
-- Disyuntor: `open-sse/services/circuitBreaker.ts`
+- Account selection/scoring: `open-sse/services/accountSelector.ts`
+- Context lifecycle management: `open-sse/services/contextManager.ts`
+- IP filter enforcement: `open-sse/services/ipFilter.ts`
+- Session tracking: `open-sse/services/sessionManager.ts`
+- Request deduplication: `open-sse/services/signatureCache.ts`
+- System prompt injection: `open-sse/services/systemPrompt.ts`
+- Thinking budget management: `open-sse/services/thinkingBudget.ts`
+- Wildcard model routing: `open-sse/services/wildcardRouter.ts`
+- Rate limit management: `open-sse/services/rateLimitManager.ts`
+- Circuit breaker: `open-sse/services/circuitBreaker.ts`
 
-Módulos de capa de dominio:
+Domain layer modules:
 
-- Disponibilidad del modelo: `src/lib/domain/modelAvailability.ts`
-- Reglas de costos/presupuestos: `src/lib/domain/costRules.ts`
-- Política alternativa: `src/lib/domain/fallbackPolicy.ts`
-- Resolución combinada: `src/lib/domain/comboResolver.ts`
-- Política de bloqueo: `src/lib/domain/lockoutPolicy.ts`
-- Motor de políticas: `src/domain/policyEngine.ts` — bloqueo centralizado → presupuesto → evaluación alternativa
-- Catálogo de códigos de error: `src/lib/domain/errorCodes.ts`
-- ID de solicitud: `src/lib/domain/requestId.ts`
-- Tiempo de espera de recuperación: `src/lib/domain/fetchTimeout.ts`
-- Solicitar telemetría: `src/lib/domain/requestTelemetry.ts`
-- Cumplimiento/auditoría: `src/lib/domain/compliance/index.ts`
-- Corredor de evaluación: `src/lib/domain/evalRunner.ts`
-- Persistencia del estado del dominio: `src/lib/db/domainState.ts` — SQLite CRUD para cadenas de respaldo, presupuestos, historial de costos, estado de bloqueo, disyuntores
+- Model availability: `src/lib/domain/modelAvailability.ts`
+- Cost rules/budgets: `src/lib/domain/costRules.ts`
+- Fallback policy: `src/lib/domain/fallbackPolicy.ts`
+- Combo resolver: `src/lib/domain/comboResolver.ts`
+- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
+- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
+- Error codes catalog: `src/lib/domain/errorCodes.ts`
+- Request ID: `src/lib/domain/requestId.ts`
+- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
+- Request telemetry: `src/lib/domain/requestTelemetry.ts`
+- Compliance/audit: `src/lib/domain/compliance/index.ts`
+- Eval runner: `src/lib/domain/evalRunner.ts`
+- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
 
-Módulos del proveedor OAuth (12 archivos individuales bajo `src/lib/oauth/providers/`):
+OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
-- Índice de registro: `src/lib/oauth/providers/index.ts`
-- Proveedores individuales: `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`
-- Contenedor delgado: `src/lib/oauth/providers.ts` — reexportaciones desde módulos individuales
+- 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`
+- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
-## 3) Capa de persistencia
+## 3) Persistence Layer
 
-BD de estado primario:
+Primary state DB (SQLite):
 
-- `src/lib/localDb.ts`
-- archivo: `${DATA_DIR}/db.json` (o `$XDG_CONFIG_HOME/omniroute/db.json` cuando está configurado, en caso contrario `~/.omniroute/db.json`)
-- entidades: proveedoresConexiones, proveedoresNodos, modelAliases, combos, apiKeys, configuraciones, precios, **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**
 
-Base de datos de uso:
+Usage persistence:
 
-- `src/lib/usageDb.ts`
-- archivos: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
-- sigue la misma política de directorio base que `localDb` (`DATA_DIR`, luego `XDG_CONFIG_HOME/omniroute` cuando se establece)
-- descompuesto en submódulos enfocados: `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
 
-Base de datos de estado de dominio (SQLite):
+Domain State DB (SQLite):
 
-- `src/lib/db/domainState.ts` — Operaciones CRUD para el estado del dominio
-- Tablas (creadas en `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
-- Patrón de caché de escritura simultánea: los mapas en memoria tienen autoridad en tiempo de ejecución; las mutaciones se escriben sincrónicamente en SQLite; El estado se restaura desde la base de datos en el arranque en frío.
+- `src/lib/db/domainState.ts` — CRUD operations for domain state
+- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
+- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
 
-## 4) Autenticación + Superficies de seguridad
+## 4) Auth + Security Surfaces
 
-- Autenticación de cookies del panel: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
-- Generación/verificación de clave API: `src/shared/utils/apiKey.ts`
-- Los secretos del proveedor persistieron en `providerConnections` entradas
-- Soporte de proxy saliente a través de `open-sse/utils/proxyFetch.ts` (env vars) y `open-sse/utils/networkProxy.ts` (configurable por proveedor o global)
+- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
+- API key generation/verification: `src/shared/utils/apiKey.ts`
+- Provider secrets persisted in `providerConnections` entries
+- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
 
-## 5) Sincronización en la nube
+## 5) Cloud Sync
 
-- Inicio del programador: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
-- Tarea periódica: `src/shared/services/cloudSyncScheduler.ts`
-- Ruta de control: `src/app/api/sync/cloud/route.ts`
+- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
+- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Control route: `src/app/api/sync/cloud/route.ts`
 
-## Solicitar ciclo de vida (`/v1/chat/completions`)
+## Request Lifecycle (`/v1/chat/completions`)
 
 ```mermaid
 sequenceDiagram
@@ -304,7 +309,7 @@ sequenceDiagram
     Stream->>Usage: extract usage + persist history/log
 ```
 
-## Combo + Flujo alternativo de cuenta
+## Combo + Account Fallback Flow
 
 ```mermaid
 flowchart TD
@@ -334,9 +339,9 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-Las decisiones alternativas están impulsadas por `open-sse/services/accountFallback.ts` utilizando códigos de estado y heurísticas de mensajes de error.
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics.
 
-## Incorporación de OAuth y ciclo de vida de actualización de tokens
+## OAuth Onboarding and Token Refresh Lifecycle
 
 ```mermaid
 sequenceDiagram
@@ -366,9 +371,9 @@ sequenceDiagram
     Test-->>UI: validation result
 ```
 
-La actualización durante el tráfico en vivo se ejecuta dentro de `open-sse/handlers/chatCore.ts` a través del ejecutor `refreshCredentials()`.
+Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
 
-## Ciclo de vida de sincronización en la nube (activar/sincronizar/desactivar)
+## Cloud Sync Lifecycle (Enable / Sync / Disable)
 
 ```mermaid
 sequenceDiagram
@@ -400,9 +405,9 @@ sequenceDiagram
     Sync-->>UI: disabled
 ```
 
-La sincronización periódica la activa `CloudSyncScheduler` cuando la nube está habilitada.
+Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
 
-## Modelo de datos y mapa de almacenamiento
+## Data Model and Storage Map
 
 ```mermaid
 erDiagram
@@ -503,14 +508,14 @@ erDiagram
     }
 ```
 
-Archivos de almacenamiento físico:
+Physical storage files:
 
-- estado principal: `${DATA_DIR}/db.json` (o `$XDG_CONFIG_HOME/omniroute/db.json` cuando está configurado, en caso contrario `~/.omniroute/db.json`)
-- estadísticas de uso: `${DATA_DIR}/usage.json`
-- líneas de registro de solicitud: `${DATA_DIR}/log.txt`
-- traductor opcional/solicitar sesiones de depuración: `<repo>/logs/...`
+- 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/...`
 
-## Topología de implementación
+## Deployment Topology
 
 ```mermaid
 flowchart LR
@@ -522,8 +527,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]
@@ -541,241 +546,242 @@ flowchart LR
     Next --> SyncCloud
 ```
 
-## Mapeo de módulos (de decisión crítica)
+## Module Mapping (Decision-Critical)
 
-### Módulos de ruta y API
+### Route and API Modules
 
-- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API de compatibilidad
-- `src/app/api/v1/providers/[provider]/*`: rutas dedicadas por proveedor (chat, incrustaciones, imágenes)
-- `src/app/api/providers*`: proveedor CRUD, validación, pruebas
-- `src/app/api/provider-nodes*`: gestión de nodos compatibles personalizados
-- `src/app/api/provider-models`: gestión de modelos personalizados (CRUD)
-- `src/app/api/models/catalog`: API de catálogo de modelos completo (todos los tipos agrupados por proveedor)
-- `src/app/api/oauth/*`: flujos de código de dispositivo/OAuth
-- `src/app/api/keys*`: ciclo de vida de la clave API local
-- `src/app/api/models/alias`: gestión de alias
-- `src/app/api/combos*`: gestión de combos alternativos
-- `src/app/api/pricing`: anulaciones de precios para el cálculo de costos
-- `src/app/api/settings/proxy`: configuración de proxy (GET/PUT/DELETE)
-- `src/app/api/settings/proxy/test`: prueba de conectividad de proxy saliente (POST)
-- `src/app/api/usage/*`: API de uso y registros
-- `src/app/api/sync/*` + `src/app/api/cloud/*`: sincronización en la nube y ayudantes orientados a la nube
-- `src/app/api/cli-tools/*`: escritores/comprobadores de configuración CLI local
-- `src/app/api/settings/ip-filter`: lista de IP permitidas/lista de bloqueo (GET/PUT)
-- `src/app/api/settings/thinking-budget`: configuración del presupuesto del token pensante (GET/PUT)
-- `src/app/api/settings/system-prompt`: mensaje global del sistema (GET/PUT)
-- `src/app/api/sessions`: listado de sesiones activas (GET)
-- `src/app/api/rate-limits`: estado de límite de tasa por cuenta (GET)
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
+- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
+- `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/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
+- `src/app/api/combos*`: fallback combo management
+- `src/app/api/pricing`: pricing overrides for cost calculation
+- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
+- `src/app/api/usage/*`: usage and logs APIs
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
+- `src/app/api/cli-tools/*`: local CLI config writers/checkers
+- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
+- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
+- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
+- `src/app/api/sessions`: active session listing (GET)
+- `src/app/api/rate-limits`: per-account rate limit status (GET)
 
-### Núcleo de enrutamiento y ejecución
+### Routing and Execution Core
 
-- `src/sse/handlers/chat.ts`: análisis de solicitudes, manejo de combos, bucle de selección de cuentas
-- `open-sse/handlers/chatCore.ts`: traducción, envío de ejecutores, manejo de reintento/actualización, configuración de transmisión
-- `open-sse/executors/*`: comportamiento de formato y red específico del proveedor
+- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
+- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
+- `open-sse/executors/*`: provider-specific network and format behavior
 
-### Registro de traducción y convertidores de formato
+### Translation Registry and Format Converters
 
-- `open-sse/translator/index.ts`: registro y orquestación de traductores
-- Solicitar traductores: `open-sse/translator/request/*`
-- Traductores de respuesta: `open-sse/translator/response/*`
-- Constantes de formato: `open-sse/translator/formats.ts`
+- `open-sse/translator/index.ts`: translator registry and orchestration
+- Request translators: `open-sse/translator/request/*`
+- Response translators: `open-sse/translator/response/*`
+- Format constants: `open-sse/translator/formats.ts`
 
-### Persistencia
+### Persistence
 
-- `src/lib/localDb.ts`: configuración/estado persistente
-- `src/lib/usageDb.ts`: historial de uso y registros continuos de solicitudes
+- `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
 
-## Cobertura del Ejecutor del Proveedor (Patrón de Estrategia)
+## Provider Executor Coverage (Strategy Pattern)
 
-Cada proveedor tiene un ejecutor especializado que extiende `BaseExecutor` (en `open-sse/executors/base.ts`), que proporciona creación de URL, construcción de encabezados, reintentos con retroceso exponencial, enlaces de actualización de credenciales y el método de orquestación `execute()`.
+Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method.
 
-| Ejecutor              | Proveedor(es)                                                                                                                                                | Manejo Especial                                                                               |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
-| `DefaultExecutor`     | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Configuración dinámica de URL/encabezado por proveedor                                        |
-| `AntigravityExecutor` | Antigravedad de Google                                                                                                                                       | ID personalizados de proyecto/sesión, reintento después del análisis                          |
-| `CodexExecutor`       | Códice OpenAI                                                                                                                                                | Inyecta instrucciones del sistema, fuerza el esfuerzo de razonamiento                         |
-| `CursorExecutor`      | Cursor IDE                                                                                                                                                   | Protocolo ConnectRPC, codificación Protobuf, solicitud de firma mediante suma de comprobación |
-| `GithubExecutor`      | Copiloto de GitHub                                                                                                                                           | Actualización del token Copilot, encabezados que imitan VSCode                                |
-| `KiroExecutor`        | AWS CodeWhisperer/Kiro                                                                                                                                       | Formato binario de AWS EventStream → Conversión SSE                                           |
-| `GeminiCLIExecutor`   | Géminis CLI                                                                                                                                                  | Ciclo de actualización del token OAuth de Google                                              |
+| 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                               |
+| `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 |
+| `GithubExecutor`      | GitHub Copilot                                                                                                                                               | Copilot token refresh, VSCode-mimicking headers                      |
+| `KiroExecutor`        | AWS CodeWhisperer/Kiro                                                                                                                                       | AWS EventStream binary format → SSE conversion                       |
+| `GeminiCLIExecutor`   | Gemini CLI                                                                                                                                                   | Google OAuth token refresh cycle                                     |
 
-Todos los demás proveedores (incluidos los nodos compatibles personalizados) utilizan `DefaultExecutor`.
+All other providers (including custom compatible nodes) use the `DefaultExecutor`.
 
-## Matriz de compatibilidad de proveedores
+## Provider Compatibility Matrix
 
-| Proveedor              | Formato           | Autenticación                      | Corriente                   | Sin transmisión | Actualización de token | API de uso                |
-| ---------------------- | ----------------- | ---------------------------------- | --------------------------- | --------------- | ---------------------- | ------------------------- |
-| Claudio                | claudio           | Clave API/OAuth                    | ✅                          | ✅              | ✅                     | ⚠️ Solo administrador     |
-| Géminis                | géminis           | Clave API/OAuth                    | ✅                          | ✅              | ✅                     | ⚠️ Consola en la nube     |
-| Géminis CLI            | gemini-cli        | OAuth                              | ✅                          | ✅              | ✅                     | ⚠️ Consola en la nube     |
-| Antigravedad           | antigravedad      | OAuth                              | ✅                          | ✅              | ✅                     | ✅ API de cuota completa  |
-| Abierta AI             | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Códice                 | respuestas-openai | OAuth                              | ✅ forzado                  | ❌              | ✅                     | ✅ Límites de tarifas     |
-| Copiloto de GitHub     | abierto           | OAuth + Token de copiloto          | ✅                          | ✅              | ✅                     | ✅ Instantáneas de cuotas |
-| Cursores               | cursor            | Suma de comprobación personalizada | ✅                          | ✅              | ❌                     | ❌                        |
-| kiro                   | kiro              | AWS SSO OIDC                       | ✅ (Transmisión de eventos) | ❌              | ✅                     | ✅ Límites de uso         |
-| Qwen                   | abierto           | OAuth                              | ✅                          | ✅              | ✅                     | ⚠️ Por solicitud          |
-| iFlujo                 | abierto           | OAuth (básico)                     | ✅                          | ✅              | ✅                     | ⚠️ Por solicitud          |
-| Enrutador abierto      | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| GLM/Kimi/MiniMax       | claudio           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Búsqueda profunda      | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Groq                   | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| xAI (Grok)             | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Mistral                | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Perplejidad            | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Juntos IA              | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Fuegos artificiales AI | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Cerebras               | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Coherir                | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| NIM de NVIDIA          | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
+| Provider         | Format           | Auth                  | Stream           | Non-Stream | Token Refresh | Usage API          |
+| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
+| Claude           | claude           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Admin only      |
+| Gemini           | gemini           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Gemini CLI       | gemini-cli       | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Antigravity      | antigravity      | OAuth                 | ✅               | ✅         | ✅            | ✅ Full quota API  |
+| OpenAI           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Codex            | openai-responses | OAuth                 | ✅ forced        | ❌         | ✅            | ✅ Rate limits     |
+| GitHub Copilot   | openai           | OAuth + Copilot Token | ✅               | ✅         | ✅            | ✅ Quota snapshots |
+| Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
+| Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
+| Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| iFlow            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Groq             | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| xAI (Grok)       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Mistral          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Perplexity       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Together AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Fireworks AI     | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 
-## Cobertura de traducción de formato
+## Format Translation Coverage
 
-Los formatos de origen detectados incluyen:
+Detected source formats include:
 
 - `openai`
 - `openai-responses`
 - `claude`
 - `gemini`
 
-Los formatos de destino incluyen:
+Target formats include:
 
-- Chat/Respuestas de OpenAI
-- Claudio
-- Géminis/Gemini-CLI/sobre antigravedad
-  -Kiro
-- Cursores
+- OpenAI chat/Responses
+- Claude
+- Gemini/Gemini-CLI/Antigravity envelope
+- Kiro
+- Cursor
 
-Las traducciones utilizan **OpenAI como formato central**; todas las conversiones pasan por OpenAI como formato intermedio:
+Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
 
 ```
 Source Format → OpenAI (hub) → Target Format
 ```
 
-Las traducciones se seleccionan dinámicamente según la forma de la carga útil de origen y el formato de destino del proveedor.
+Translations are selected dynamically based on source payload shape and provider target format.
 
-Capas de procesamiento adicionales en el proceso de traducción:
+Additional processing layers in the translation pipeline:
 
-- **Desinfección de respuestas**: elimina los campos no estándar de las respuestas en formato OpenAI (tanto en streaming como sin streaming) para garantizar el estricto cumplimiento del SDK.
-- **Normalización de roles**: convierte `developer` → `system` para objetivos que no son OpenAI; fusiona `system` → `user` para modelos que rechazan el rol del sistema (GLM, ERNIE)
-- **Piense en la extracción de etiquetas**: analiza `<think>...</think>` bloques del contenido en el campo `reasoning_content`
-- **Salida estructurada**: convierte OpenAI `response_format.json_schema` en `responseMimeType` + `responseSchema` de Gemini.
+- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance
+- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)
+- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field
+- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`
 
-## Puntos finales API compatibles
+## Supported API Endpoints
 
-| Punto final                                        | Formato                      | Manejador                                                        |
-| -------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------- |
-| `POST /v1/chat/completions`                        | Chat abierto de IA           | `src/sse/handlers/chat.ts`                                       |
-| `POST /v1/messages`                                | Mensajes de Claude           | Mismo controlador (detectado automáticamente)                    |
-| `POST /v1/responses`                               | Respuestas de OpenAI         | `open-sse/handlers/responsesHandler.ts`                          |
-| `POST /v1/embeddings`                              | Incrustaciones de OpenAI     | `open-sse/handlers/embeddings.ts`                                |
-| `GET /v1/embeddings`                               | Listado de modelos           | Ruta API                                                         |
-| `POST /v1/images/generations`                      | Imágenes de OpenAI           | `open-sse/handlers/imageGeneration.ts`                           |
-| `GET /v1/images/generations`                       | Listado de modelos           | Ruta API                                                         |
-| `POST /v1/providers/{provider}/chat/completions`   | Chat abierto de IA           | Dedicado por proveedor con validación de modelo                  |
-| `POST /v1/providers/{provider}/embeddings`         | Incrustaciones de OpenAI     | Dedicado por proveedor con validación de modelo                  |
-| `POST /v1/providers/{provider}/images/generations` | Imágenes de OpenAI           | Dedicado por proveedor con validación de modelo                  |
-| `POST /v1/messages/count_tokens`                   | Recuento de fichas de Claude | Ruta API                                                         |
-| `GET /v1/models`                                   | Lista de modelos OpenAI      | Ruta API (chat + incrustación + imagen + modelos personalizados) |
-| `GET /api/models/catalog`                          | Catálogo                     | Todos los modelos agrupados por proveedor + tipo                 |
-| `POST /v1beta/models/*:streamGenerateContent`      | Nativo de Géminis            | Ruta API                                                         |
-| `GET/PUT/DELETE /api/settings/proxy`               | Configuración de proxy       | Configuración del proxy de red                                   |
-| `POST /api/settings/proxy/test`                    | Conectividad de proxy        | Punto final de prueba de conectividad/estado del proxy           |
-| `GET/POST/DELETE /api/provider-models`             | Modelos personalizados       | Gestión de modelos personalizados por proveedor                  |
+| 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                 |
 
-## Controlador de omisión
+## Bypass Handler
 
-El controlador de omisión (`open-sse/utils/bypassHandler.ts`) intercepta solicitudes "desechables" conocidas de Claude CLI (pings de preparación, extracciones de títulos y recuentos de tokens) y devuelve una **respuesta falsa** sin consumir tokens de proveedores ascendentes. Esto se activa solo cuando `User-Agent` contiene `claude-cli`.
+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`.
 
-## Solicitar canalización de registro
+## Request Logger Pipeline
 
-El registrador de solicitudes (`open-sse/utils/requestLogger.ts`) proporciona una canalización de registro de depuración de 7 etapas, deshabilitada de forma predeterminada y habilitada a través de `ENABLE_REQUEST_LOGS=true`:
+The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`:
 
 ```
 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
 ```
 
-Los archivos se escriben en `<repo>/logs/<session>/` para cada sesión de solicitud.
+Files are written to `<repo>/logs/<session>/` for each request session.
 
-## Modos de falla y resiliencia
+## Failure Modes and Resilience
 
-## 1) Disponibilidad de cuenta/proveedor
+## 1) Account/Provider Availability
 
-- tiempo de reutilización de la cuenta del proveedor en errores transitorios/de tasa/autenticación
-- respaldo de la cuenta antes de fallar la solicitud
-- retroceso del modelo combinado cuando se agota la ruta del modelo/proveedor actual
+- provider account cooldown on transient/rate/auth errors
+- account fallback before failing request
+- combo model fallback when current model/provider path is exhausted
 
-## 2) Caducidad del token
+## 2) Token Expiry
 
-- verificación previa y actualización con reintento para proveedores actualizables
-- Reintento 401/403 después de un intento de actualización en la ruta principal
+- pre-check and refresh with retry for refreshable providers
+- 401/403 retry after refresh attempt in core path
 
-## 3) Seguridad de la transmisión
+## 3) Stream Safety
 
-- controlador de flujo con reconocimiento de desconexión
-- flujo de traducción con descarga de final de flujo y manejo de `[DONE]`
-- reserva de estimación de uso cuando faltan metadatos de uso del proveedor
+- disconnect-aware stream controller
+- translation stream with end-of-stream flush and `[DONE]` handling
+- usage estimation fallback when provider usage metadata is missing
 
-## 4) Degradación de la sincronización en la nube
+## 4) Cloud Sync Degradation
 
-- Aparecen errores de sincronización pero el tiempo de ejecución local continúa
-- El programador tiene una lógica con capacidad de reintento, pero la ejecución periódica actualmente llama a la sincronización de un solo intento de forma predeterminada.
+- sync errors are surfaced but local runtime continues
+- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
 
-## 5) Integridad de los datos
+## 5) Data Integrity
 
-- Migración/reparación de forma de base de datos por claves faltantes
-- salvaguardias de restablecimiento de JSON corruptas para localDb y useDb
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
-## Observabilidad y señales operativas
+## Observability and Operational Signals
 
-Fuentes de visibilidad en tiempo de ejecución:
+Runtime visibility sources:
 
-- registros de consola de `src/sse/utils/logger.ts`
-- agregados de uso por solicitud en `usage.json`
-- registro de estado de solicitud textual en `log.txt`
-- registros de traducción/solicitud profunda opcionales en `logs/` cuando `ENABLE_REQUEST_LOGS=true`
-- puntos finales de uso del panel (`/api/usage/*`) para el consumo de UI
+- console logs from `src/sse/utils/logger.ts`
+- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- textual request status log in `log.txt` (optional/compat)
+- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true`
+- dashboard usage endpoints (`/api/usage/*`) for UI consumption
 
-## Límites sensibles a la seguridad
+## Security-Sensitive Boundaries
 
-- El secreto JWT (`JWT_SECRET`) protege la verificación/firma de cookies de la sesión del panel
-- La reserva de contraseña inicial (`INITIAL_PASSWORD`, predeterminada `123456`) debe anularse en implementaciones reales
-- El secreto HMAC de la clave API (`API_KEY_SECRET`) protege el formato de clave API local generado
-- Los secretos del proveedor (claves/tokens de API) se conservan en la base de datos local y deben protegerse a nivel del sistema de archivos.
-- Los puntos finales de sincronización en la nube se basan en la semántica de autenticación de clave API + ID de máquina
+- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
+- 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
 
-## Matriz de entorno y tiempo de ejecución
+## Environment and Runtime Matrix
 
-Variables de entorno utilizadas activamente por el código:
+Environment variables actively used by code:
 
-- Aplicación/autenticación: `JWT_SECRET`, `INITIAL_PASSWORD`
-- Almacenamiento: `DATA_DIR`
-- Comportamiento de nodo compatible: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
-- Anulación de la base de almacenamiento opcional (Linux/macOS cuando `DATA_DIR` no está configurado): `XDG_CONFIG_HOME`
-- Hash de seguridad: `API_KEY_SECRET`, `MACHINE_ID_SALT`
-- Registro: `ENABLE_REQUEST_LOGS`
-- Sincronización/URL en la nube: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
-- Proxy saliente: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` y variantes en minúsculas
-- Marcas de características de SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
-- Ayudantes de plataforma/tiempo de ejecución (no configuración específica de la aplicación): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Storage: `DATA_DIR`
+- 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`
+- 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`
+- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
 
-## Notas arquitectónicas conocidas
+## Known Architectural Notes
 
-1. `usageDb` y `localDb` ahora comparten la misma política de directorio base (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) con la migración de archivos heredados.
-2. `/api/v1/route.ts` devuelve una lista de modelos estáticos y no es la fuente principal de modelos utilizada por `/v1/models`.
-3. El registrador de solicitudes escribe encabezados/cuerpo completo cuando está habilitado; trate el directorio de registro como confidencial.
-4. El comportamiento de la nube depende del `NEXT_PUBLIC_BASE_URL` correcto y de la accesibilidad del punto final de la nube.
-5. El directorio `open-sse/` se publica como `@omniroute/open-sse` **paquete de espacio de trabajo npm**. El código fuente lo importa a través de `@omniroute/open-sse/...` (resuelto por Next.js `transpilePackages`). Las rutas de archivo en este documento todavía usan el nombre de directorio `open-sse/` para mantener la coherencia.
-6. Los gráficos en el panel utilizan **Recharts** (basados ​​en SVG) para visualizaciones analíticas interactivas y accesibles (gráficos de barras de uso de modelos, tablas de desglose de proveedores con tasas de éxito).
-7. Las pruebas E2E utilizan **Dramaturgo** (`tests/e2e/`), ejecutado a través de `npm run test:e2e`. Las pruebas unitarias utilizan **ejecutor de pruebas Node.js** (`tests/unit/`), ejecutado a través de `npm run test:plan3`. El código fuente bajo `src/` es **TypeScript** (`.ts`/`.tsx`); el espacio de trabajo `open-sse/` sigue siendo JavaScript (`.js`).
-8. La página de configuración está organizada en 5 pestañas: Seguridad, Enrutamiento (6 estrategias globales: completar primero, por turnos, p2c, aleatorio, menos utilizado, de costo optimizado), Resiliencia (límites de velocidad editables, disyuntor, políticas), IA (presupuesto pensado, aviso del sistema, caché de avisos), Avanzado (proxy).
+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: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), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
 
-## Lista de verificación de verificación operativa
+## Operational Verification Checklist
 
-- Compilación desde la fuente: `npm run build`
-- Crear imagen de Docker: `docker build -t omniroute .`
-- Iniciar el servicio y verificar:
+- Build from source: `npm run build`
+- Build Docker image: `docker build -t omniroute .`
+- Start service and verify:
 - `GET /api/settings`
 - `GET /api/v1/models`
-- La URL base de destino de CLI debe ser `http://<host>:20128/v1` cuando `PORT=20128`
+- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`

docs/i18n/es/AUTO-COMBO.md

@@ -0,0 +1,67 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/AUTO-COMBO.md) · 🇪🇸 [es](../es/AUTO-COMBO.md) · 🇫🇷 [fr](../fr/AUTO-COMBO.md) · 🇩🇪 [de](../de/AUTO-COMBO.md) · 🇮🇹 [it](../it/AUTO-COMBO.md) · 🇷🇺 [ru](../ru/AUTO-COMBO.md) · 🇨🇳 [zh-CN](../zh-CN/AUTO-COMBO.md) · 🇯🇵 [ja](../ja/AUTO-COMBO.md) · 🇰🇷 [ko](../ko/AUTO-COMBO.md) · 🇸🇦 [ar](../ar/AUTO-COMBO.md) · 🇮🇳 [in](../in/AUTO-COMBO.md) · 🇹🇭 [th](../th/AUTO-COMBO.md) · 🇻🇳 [vi](../vi/AUTO-COMBO.md) · 🇮🇩 [id](../id/AUTO-COMBO.md) · 🇲🇾 [ms](../ms/AUTO-COMBO.md) · 🇳🇱 [nl](../nl/AUTO-COMBO.md) · 🇵🇱 [pl](../pl/AUTO-COMBO.md) · 🇸🇪 [sv](../sv/AUTO-COMBO.md) · 🇳🇴 [no](../no/AUTO-COMBO.md) · 🇩🇰 [da](../da/AUTO-COMBO.md) · 🇫🇮 [fi](../fi/AUTO-COMBO.md) · 🇵🇹 [pt](../pt/AUTO-COMBO.md) · 🇷🇴 [ro](../ro/AUTO-COMBO.md) · 🇭🇺 [hu](../hu/AUTO-COMBO.md) · 🇧🇬 [bg](../bg/AUTO-COMBO.md) · 🇸🇰 [sk](../sk/AUTO-COMBO.md) · 🇺🇦 [uk-UA](../uk-UA/AUTO-COMBO.md) · 🇮🇱 [he](../he/AUTO-COMBO.md) · 🇵🇭 [phi](../phi/AUTO-COMBO.md)
+
+---
+
+# 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/i18n/es/CODEBASE_DOCUMENTATION.md

@@ -1,22 +1,26 @@
-# omniroute — Documentación de la base de código
-
-🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md)
-
-> Una guía completa y fácil de usar para principiantes sobre el enrutador proxy de IA multiproveedor **omniroute**.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../es/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../fr/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../de/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../it/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../ru/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../ja/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../ko/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../ar/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [in](../in/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../th/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../vi/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../id/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../ms/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../nl/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../pl/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../sv/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../no/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../da/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../fi/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../pt/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../ro/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../hu/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../bg/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../sk/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../he/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../phi/CODEBASE_DOCUMENTATION.md)
 
 ---
 
-## 1. ¿Qué es omniruta?
+# omniroute — Codebase Documentation
 
-omniroute es un **enrutador proxy** que se encuentra entre clientes de IA (Claude CLI, Codex, Cursor IDE, etc.) y proveedores de IA (Anthropic, Google, OpenAI, AWS, GitHub, etc.). Resuelve un gran problema:
+🌐 **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)
 
-> **Diferentes clientes de IA hablan diferentes "idiomas" (formatos API), y diferentes proveedores de IA también esperan "idiomas" diferentes.** omniroute traduce entre ellos automáticamente.
-
-Piense en ello como un traductor universal en las Naciones Unidas: cualquier delegado puede hablar cualquier idioma y el traductor lo convierte para cualquier otro delegado.
+> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router.
 
 ---
 
-## 2. Descripción general de la arquitectura
+## 1. What Is omniroute?
+
+omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem:
+
+> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically.
+
+Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate.
+
+---
+
+## 2. Architecture Overview
 
 ```mermaid
 graph LR
@@ -61,20 +65,20 @@ graph LR
     H -.-> G
 ```
 
-### Principio básico: traducción radial
+### Core Principle: Hub-and-Spoke Translation
 
-Toda la traducción de formatos pasa a través del **formato OpenAI como centro**:
+All format translation passes through **OpenAI format as the hub**:
 
 ```
 Client Format → [OpenAI Hub] → Provider Format    (request)
 Provider Format → [OpenAI Hub] → Client Format    (response)
 ```
 
-Esto significa que solo necesitas **N traductores** (uno por formato) en lugar de **N²** (cada par).
+This means you only need **N translators** (one per format) instead of **N²** (every pair).
 
 ---
 
-## 3. Estructura del proyecto
+## 3. Project Structure
 
 ```
 omniroute/
@@ -104,22 +108,22 @@ omniroute/
 
 ---
 
-## 4. Desglose módulo por módulo
+## 4. Module-by-Module Breakdown
 
-### 4.1 Configuración (`open-sse/config/`)
+### 4.1 Config (`open-sse/config/`)
 
-La **única fuente de verdad** para todas las configuraciones de proveedores.
+The **single source of truth** for all provider configuration.
 
-| Archivo                       | Propósito                                                                                                                                                                                                                                                                 |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `constants.ts`                | Objeto `PROVIDERS` con URL base, credenciales de OAuth (predeterminadas), encabezados y mensajes del sistema predeterminados para cada proveedor. También define `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` y `SKIP_PATTERNS`.                         |
-| `credentialLoader.ts`         | Carga credenciales externas de `data/provider-credentials.json` y las combina con los valores predeterminados codificados en `PROVIDERS`. Mantiene los secretos fuera del control de código fuente y al mismo tiempo mantiene la compatibilidad con versiones anteriores. |
-| `providerModels.ts`           | Registro central de modelos: alias de proveedores de mapas → ID de modelos. Funciones como `getModels()`, `getProviderByAlias()`.                                                                                                                                         |
-| `codexInstructions.ts`        | Instrucciones del sistema inyectadas en solicitudes del Codex (restricciones de edición, reglas de espacio aislado, políticas de aprobación).                                                                                                                             |
-| `defaultThinkingSignature.ts` | Firmas "pensantes" predeterminadas para los modelos Claude y Gemini.                                                                                                                                                                                                      |
-| `ollamaModels.ts`             | Definición de esquemas para modelos locales de Ollama (nombre, tamaño, familia, cuantificación).                                                                                                                                                                          |
+| File                          | Purpose                                                                                                                                                                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `constants.ts`                | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. |
+| `credentialLoader.ts`         | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility.               |
+| `providerModels.ts`           | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`.                                                                                                          |
+| `codexInstructions.ts`        | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies).                                                                                                                 |
+| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models.                                                                                                                                                               |
+| `ollamaModels.ts`             | Schema definition for local Ollama models (name, size, family, quantization).                                                                                                                                             |
 
-#### Flujo de carga de credenciales
+#### Credential Loading Flow
 
 ```mermaid
 flowchart TD
@@ -142,9 +146,9 @@ flowchart TD
 
 ---
 
-### 4.2 Ejecutores (`open-sse/executors/`)
+### 4.2 Executors (`open-sse/executors/`)
 
-Los ejecutores encapsulan **lógica específica del proveedor** utilizando el **Patrón de estrategia**. Cada ejecutor anula los métodos base según sea necesario.
+Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed.
 
 ```mermaid
 classDiagram
@@ -194,32 +198,32 @@ classDiagram
     BaseExecutor <|-- GithubExecutor
 ```
 
-| Ejecutor         | Proveedor                                   | Especializaciones clave                                                                                                                                     |
-| ---------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `base.ts`        | —                                           | Base abstracta: creación de URL, encabezados, lógica de reintento, actualización de credenciales                                                            |
-| `default.ts`     | Claude, Géminis, OpenAI, GLM, Kimi, MiniMax | Actualización de token genérico de OAuth para proveedores estándar                                                                                          |
-| `antigravity.ts` | Código de la nube de Google                 | Generación de ID de proyecto/sesión, respaldo de múltiples URL, reintento personalizado de análisis de mensajes de error ("restablecer después de 2h7m23s") |
-| `cursor.ts`      | Cursor IDE                                  | **Más complejo**: autenticación de suma de comprobación SHA-256, codificación de solicitud Protobuf, EventStream binario → análisis de respuesta SSE        |
-| `codex.ts`       | Códice OpenAI                               | Inyecta instrucciones del sistema, gestiona los niveles de pensamiento, elimina parámetros no compatibles                                                   |
-| `gemini-cli.ts`  | CLI de Google Géminis                       | Creación de URL personalizada (`streamGenerateContent`), actualización del token OAuth de Google                                                            |
-| `github.ts`      | Copiloto de GitHub                          | Sistema de token dual (GitHub OAuth + token Copilot), imitación del encabezado VSCode                                                                       |
-| `kiro.ts`        | Susurrador de códigos de AWS                | Análisis binario de AWS EventStream, marcos de eventos AMZN, estimación de tokens                                                                           |
-| `index.ts`       | —                                           | Fábrica: nombre del proveedor de mapas → clase de ejecutor, con respaldo predeterminado                                                                     |
+| Executor         | Provider                                   | Key Specializations                                                                                                 |
+| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `base.ts`        | —                                          | Abstract base: URL building, headers, retry logic, credential refresh                                               |
+| `default.ts`     | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers                                                                  |
+| `antigravity.ts` | Google Cloud Code                          | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") |
+| `cursor.ts`      | Cursor IDE                                 | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing       |
+| `codex.ts`       | OpenAI Codex                               | Injects system instructions, manages thinking levels, removes unsupported parameters                                |
+| `gemini-cli.ts`  | Google Gemini CLI                          | Custom URL building (`streamGenerateContent`), Google OAuth token refresh                                           |
+| `github.ts`      | GitHub Copilot                             | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking                                           |
+| `kiro.ts`        | AWS CodeWhisperer                          | AWS EventStream binary parsing, AMZN event frames, token estimation                                                 |
+| `index.ts`       | —                                          | Factory: maps provider name → executor class, with default fallback                                                 |
 
 ---
 
-### 4.3 Controladores (`open-sse/handlers/`)
+### 4.3 Handlers (`open-sse/handlers/`)
 
-La **capa de orquestación**: coordina la traducción, la ejecución, la transmisión y el manejo de errores.
+The **orchestration layer** — coordinates translation, execution, streaming, and error handling.
 
-| Archivo               | Propósito                                                                                                                                                                                                                                                  |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `chatCore.ts`         | **Orquestador central** (~600 líneas). Maneja el ciclo de vida completo de la solicitud: detección de formato → traducción → envío del ejecutor → respuesta de transmisión/no transmisión → actualización del token → manejo de errores → registro de uso. |
-| `responsesHandler.ts` | Adaptador para la API de Respuestas de OpenAI: convierte el formato de Respuestas → Finalizaciones de chat → envía a `chatCore` → convierte SSE nuevamente al formato de Respuestas.                                                                       |
-| `embeddings.ts`       | Controlador de generación de incrustación: resuelve el modelo de incrustación → proveedor, envía la API del proveedor y devuelve una respuesta de incrustación compatible con OpenAI. Admite más de 6 proveedores.                                         |
-| `imageGeneration.ts`  | Controlador de generación de imágenes: resuelve el modelo de imagen → proveedor, admite los modos compatibles con OpenAI, imagen Gemini (Antigravity) y respaldo (Nebius). Devuelve imágenes base64 o URL.                                                 |
+| File                  | Purpose                                                                                                                                                                                                                |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chatCore.ts`         | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. |
+| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format.                                                                        |
+| `embeddings.ts`       | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers.                                                    |
+| `imageGeneration.ts`  | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images.                                          |
 
-#### Solicitar ciclo de vida (chatCore.ts)
+#### Request Lifecycle (chatCore.ts)
 
 ```mermaid
 sequenceDiagram
@@ -258,28 +262,28 @@ sequenceDiagram
 
 ---
 
-### 4.4 Servicios (`open-sse/services/`)
+### 4.4 Services (`open-sse/services/`)
 
-Lógica de negocios que soporta a los manejadores y ejecutores.
+Business logic that supports the handlers and executors.
 
-| Archivo              | Propósito                                                                                                                                                                                                                                                                                                                                                                                              |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `provider.ts`        | **Detección de formato** (`detectFormat`): analiza la estructura del cuerpo de la solicitud para identificar los formatos Claude/OpenAI/Gemini/Antigravity/Responses (incluye heurística `max_tokens` para Claude). Además: creación de URL, creación de encabezados, normalización de la configuración de pensamiento. Admite proveedores dinámicos `openai-compatible-*` y `anthropic-compatible-*`. |
-| `model.ts`           | Análisis de cadenas de modelo (`claude/model-name` → `{provider: "claude", model: "model-name"}`), resolución de alias con detección de colisiones, desinfección de entradas (rechaza el recorrido de ruta/caracteres de control) y resolución de información del modelo con soporte para captadores de alias asíncronos.                                                                              |
-| `accountFallback.ts` | Manejo de límite de velocidad: retroceso exponencial (1 s → 2 s → 4 s → máx. 2 min), gestión de tiempo de reutilización de la cuenta, clasificación de errores (qué errores activan el retroceso y cuáles no).                                                                                                                                                                                         |
-| `tokenRefresh.ts`    | Actualización del token de OAuth para **cada proveedor**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot de doble token), Kiro (AWS SSO OIDC + Social Auth). Incluye caché de deduplicación de promesa en curso y reintento con retroceso exponencial.                                                                                                              |
-| `combo.ts`           | **Modelos combinados**: cadenas de modelos alternativos. Si el modelo A falla con un error elegible para respaldo, pruebe con el modelo B, luego con el C, etc. Devuelve códigos de estado ascendentes reales.                                                                                                                                                                                         |
-| `usage.ts`           | Obtiene datos de cuota/uso de las API del proveedor (cuotas de GitHub Copilot, cuotas del modelo Antigravity, límites de velocidad del Codex, desgloses de uso de Kiro, configuración de Claude).                                                                                                                                                                                                      |
-| `accountSelector.ts` | Selección inteligente de cuentas con algoritmo de puntuación: considera la prioridad, el estado de salud, la posición del round-robin y el estado de recuperación para elegir la cuenta óptima para cada solicitud.                                                                                                                                                                                    |
-| `contextManager.ts`  | Gestión del ciclo de vida del contexto de solicitud: crea y rastrea objetos de contexto por solicitud con metadatos (ID de solicitud, marcas de tiempo, información del proveedor) para depuración y registro.                                                                                                                                                                                         |
-| `ipFilter.ts`        | Control de acceso basado en IP: admite modos de lista permitida y lista de bloqueo. Valida la IP del cliente según las reglas configuradas antes de procesar las solicitudes de API.                                                                                                                                                                                                                   |
-| `sessionManager.ts`  | Seguimiento de sesiones con huellas digitales del cliente: rastrea las sesiones activas utilizando identificadores de cliente con hash, monitorea el recuento de solicitudes y proporciona métricas de sesión.                                                                                                                                                                                         |
-| `signatureCache.ts`  | Solicitar caché de deduplicación basada en firmas: evita solicitudes duplicadas al almacenar en caché las firmas de solicitudes recientes y devolver respuestas almacenadas en caché para solicitudes idénticas dentro de un período de tiempo.                                                                                                                                                        |
-| `systemPrompt.ts`    | Inyección de avisos del sistema global: antepone o agrega un aviso del sistema configurable a todas las solicitudes, con manejo de compatibilidad por proveedor.                                                                                                                                                                                                                                       |
-| `thinkingBudget.ts`  | Gestión del presupuesto de tokens de razonamiento: admite modos de transferencia, automático (configuración de pensamiento de tira), personalizado (presupuesto fijo) y adaptativo (escalado por complejidad) para controlar los tokens de pensamiento/razonamiento.                                                                                                                                   |
-| `wildcardRouter.ts`  | Enrutamiento de patrones de modelo comodín: resuelve patrones comodín (por ejemplo, `*/claude-*`) en pares concretos de proveedor/modelo según la disponibilidad y la prioridad.                                                                                                                                                                                                                       |
+| File                 | Purpose                                                                                                                                                                                                                                                                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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.                                                                       |
+| `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.                                                                                                                                                              |
+| `contextManager.ts`  | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging.                                                                                                                                                                  |
+| `ipFilter.ts`        | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests.                                                                                                                                                                                          |
+| `sessionManager.ts`  | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics.                                                                                                                                                                            |
+| `signatureCache.ts`  | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window.                                                                                                                                              |
+| `systemPrompt.ts`    | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling.                                                                                                                                                                                            |
+| `thinkingBudget.ts`  | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens.                                                                                                                                        |
+| `wildcardRouter.ts`  | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority.                                                                                                                                                                                   |
 
-#### Deduplicación de actualización de tokens
+#### Token Refresh Deduplication
 
 ```mermaid
 sequenceDiagram
@@ -300,7 +304,7 @@ sequenceDiagram
     Cache->>Cache: Delete cache entry
 ```
 
-#### Máquina de estado de reserva de cuenta
+#### Account Fallback State Machine
 
 ```mermaid
 stateDiagram-v2
@@ -325,7 +329,7 @@ stateDiagram-v2
     }
 ```
 
-#### Cadena de modelo combinado
+#### Combo Model Chain
 
 ```mermaid
 flowchart LR
@@ -344,11 +348,11 @@ flowchart LR
 
 ---
 
-### 4.5 Traductor (`open-sse/translator/`)
+### 4.5 Translator (`open-sse/translator/`)
 
-El **motor de traducción de formatos** que utiliza un sistema de complementos de registro automático.
+The **format translation engine** using a self-registering plugin system.
 
-#### Arquitectura
+#### Architecture
 
 ```mermaid
 graph TD
@@ -374,15 +378,15 @@ graph TD
     end
 ```
 
-| Directorio   | Archivos      | Descripción                                                                                                                                                                                                                                                                                                   |
-| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request/`   | 8 traductores | Convierta cuerpos de solicitudes entre formatos. Cada archivo se registra automáticamente a través de `register(from, to, fn)` al importar.                                                                                                                                                                   |
-| `response/`  | 7 traductores | Convierta fragmentos de respuesta de transmisión entre formatos. Maneja tipos de eventos SSE, bloques de pensamiento y llamadas a herramientas.                                                                                                                                                               |
-| `helpers/`   | 6 ayudantes   | Utilidades compartidas: `claudeHelper` (extracción de avisos del sistema, configuración de pensamiento), `geminiHelper` (mapeo de partes/contenidos), `openaiHelper` (filtrado de formatos), `toolCallHelper` (generación de ID, inyección de respuestas faltantes), `maxTokensHelper`, `responsesApiHelper`. |
-| `index.ts`   | —             | Motor de traducción: `translateRequest()`, `translateResponse()`, gestión de estado, registro.                                                                                                                                                                                                                |
-| `formats.ts` | —             | Constantes de formato: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`.                                                                                                                                                                                                     |
+| Directory    | Files         | Description                                                                                                                                                                                                                                                      |
+| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request/`   | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import.                                                                                                                                                         |
+| `response/`  | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls.                                                                                                                                                         |
+| `helpers/`   | 6 helpers     | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. |
+| `index.ts`   | —             | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry.                                                                                                                                                                     |
+| `formats.ts` | —             | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`.                                                                                                                                                             |
 
-#### Diseño de claves: complementos de registro automático
+#### Key Design: Self-Registering Plugins
 
 ```javascript
 // Each translator file calls register() on import:
@@ -395,19 +399,19 @@ import "./request/claude-to-openai.js"; // ← self-registers
 
 ---
 
-### 4.6 Utilidades (`open-sse/utils/`)
+### 4.6 Utils (`open-sse/utils/`)
 
-| Archivo            | Propósito                                                                                                                                                                                                                                                                                                                                                                |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `error.ts`         | Creación de respuestas a errores (formato compatible con OpenAI), análisis de errores ascendentes, extracción en tiempo de reintento de Antigravity de mensajes de error, transmisión de errores SSE.                                                                                                                                                                    |
-| `stream.ts`        | **SSE Transform Stream**: el canal principal de transmisión. Dos modos: `TRANSLATE` (traducción de formato completo) y `PASSTHROUGH` (normalizar + extraer uso). Maneja el almacenamiento en búfer de fragmentos, la estimación de uso y el seguimiento de la longitud del contenido. Las instancias de codificador/decodificador por flujo evitan el estado compartido. |
-| `streamHelpers.ts` | Utilidades SSE de bajo nivel: `parseSSELine` (tolerante a espacios en blanco), `hasValuableContent` (filtra fragmentos vacíos para OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (serialización SSE con reconocimiento de formato con limpieza `perf_metrics`).                                                                                                     |
-| `usageTracking.ts` | Extracción de uso de tokens de cualquier formato (Claude/OpenAI/Gemini/Responses), estimación con proporciones separadas de caracteres por token de herramienta/mensaje, adición de búfer (margen de seguridad de 2000 tokens), filtrado de campos específicos del formato, registro de consola con colores ANSI.                                                        |
-| `requestLogger.ts` | Registro de solicitudes basado en archivos (optar a través de `ENABLE_REQUEST_LOGS=true`). Crea carpetas de sesión con archivos numerados: `1_req_client.json` → `7_res_client.txt`. Todas las E/S son asíncronas (disparar y olvidar). Enmascara encabezados sensibles.                                                                                                 |
-| `bypassHandler.ts` | Intercepta patrones específicos de Claude CLI (extracción de títulos, calentamiento, recuento) y devuelve respuestas falsas sin llamar a ningún proveedor. Admite tanto streaming como no streaming. Limitado intencionalmente al alcance de Claude CLI.                                                                                                                 |
-| `networkProxy.ts`  | Resuelve la URL del proxy saliente para un proveedor determinado con prioridad: configuración específica del proveedor → configuración global → variables de entorno (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Admite exclusiones `NO_PROXY`. Configuración de cachés durante 30 segundos.                                                                               |
+| File               | Purpose                                                                                                                                                                                                                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `error.ts`         | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming.                                                                                                                              |
+| `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.                                                              |
+| `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.                                                  |
 
-#### Tubería de transmisión de SSE
+#### SSE Streaming Pipeline
 
 ```mermaid
 flowchart TD
@@ -429,7 +433,7 @@ flowchart TD
     style M fill:#9f9,stroke:#333
 ```
 
-#### Solicitar estructura de sesión del registrador
+#### Request Logger Session Structure
 
 ```
 logs/
@@ -447,109 +451,109 @@ logs/
 
 ---
 
-### 4.7 Capa de aplicación (`src/`)
+### 4.7 Application Layer (`src/`)
 
-| Directorio    | Propósito                                                                                             |
-| ------------- | ----------------------------------------------------------------------------------------------------- |
-| `src/app/`    | Interfaz de usuario web, rutas API, middleware Express, controladores de devolución de llamadas OAuth |
-| `src/lib/`    | Acceso a base de datos (`localDb.ts`, `usageDb.ts`), autenticación, compartido                        |
-| `src/mitm/`   | Utilidades de proxy Man-in-the-middle para interceptar el tráfico de proveedores                      |
-| `src/models/` | Definiciones de modelos de bases de datos                                                             |
-| `src/shared/` | Envoltorios de funciones open-sse (proveedor, flujo, error, etc.)                                     |
-| `src/sse/`    | Controladores de puntos finales SSE que conectan la biblioteca open-sse a rutas Express               |
-| `src/store/`  | Gestión del estado de la aplicación                                                                   |
+| Directory     | Purpose                                                                |
+| ------------- | ---------------------------------------------------------------------- |
+| `src/app/`    | Web UI, API routes, Express middleware, OAuth callback handlers        |
+| `src/lib/`    | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared   |
+| `src/mitm/`   | Man-in-the-middle proxy utilities for intercepting provider traffic    |
+| `src/models/` | Database model definitions                                             |
+| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.)     |
+| `src/sse/`    | SSE endpoint handlers that wire the open-sse library to Express routes |
+| `src/store/`  | Application state management                                           |
 
-#### Rutas API notables
+#### Notable API Routes
 
-| Ruta                                          | Métodos                   | Propósito                                                                                                   |
-| --------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `/api/provider-models`                        | OBTENER/PUBLICAR/ELIMINAR | CRUD para modelos personalizados por proveedor                                                              |
-| `/api/models/catalog`                         | OBTENER                   | Catálogo agregado de todos los modelos (chat, incrustado, imagen, personalizado) agrupados por proveedor    |
-| `/api/settings/proxy`                         | OBTENER/PONER/ELIMINAR    | Configuración de proxy saliente jerárquico (`global/providers/combos/keys`)                                 |
-| `/api/settings/proxy/test`                    | PUBLICAR                  | Valida la conectividad del proxy y devuelve IP pública/latencia                                             |
-| `/v1/providers/[provider]/chat/completions`   | PUBLICAR                  | Finalizaciones de chat dedicadas por proveedor con validación de modelo                                     |
-| `/v1/providers/[provider]/embeddings`         | PUBLICAR                  | Incorporaciones dedicadas por proveedor con validación de modelo                                            |
-| `/v1/providers/[provider]/images/generations` | PUBLICAR                  | Generación de imágenes dedicada por proveedor con validación de modelo                                      |
-| `/api/settings/ip-filter`                     | OBTENER/PONER             | Gestión de listas de IP permitidas/bloqueadas                                                               |
-| `/api/settings/thinking-budget`               | OBTENER/PONER             | Configuración del presupuesto del token de razonamiento (transferencia/automático/personalizado/adaptativo) |
-| `/api/settings/system-prompt`                 | OBTENER/PONER             | Inyección rápida del sistema global para todas las solicitudes                                              |
-| `/api/sessions`                               | OBTENER                   | Seguimiento y métricas de sesiones activas                                                                  |
-| `/api/rate-limits`                            | OBTENER                   | Estado del límite de tasa por cuenta                                                                        |
+| Route                                         | Methods         | Purpose                                                                               |
+| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
+| `/api/provider-models`                        | GET/POST/DELETE | CRUD for custom models per provider                                                   |
+| `/api/models/catalog`                         | GET             | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider |
+| `/api/settings/proxy`                         | GET/PUT/DELETE  | Hierarchical outbound proxy configuration (`global/providers/combos/keys`)            |
+| `/api/settings/proxy/test`                    | POST            | Validates proxy connectivity and returns public IP/latency                            |
+| `/v1/providers/[provider]/chat/completions`   | POST            | Dedicated per-provider chat completions with model validation                         |
+| `/v1/providers/[provider]/embeddings`         | POST            | Dedicated per-provider embeddings with model validation                               |
+| `/v1/providers/[provider]/images/generations` | POST            | Dedicated per-provider image generation with model validation                         |
+| `/api/settings/ip-filter`                     | GET/PUT         | IP allowlist/blocklist management                                                     |
+| `/api/settings/thinking-budget`               | GET/PUT         | Reasoning token budget configuration (passthrough/auto/custom/adaptive)               |
+| `/api/settings/system-prompt`                 | GET/PUT         | Global system prompt injection for all requests                                       |
+| `/api/sessions`                               | GET             | Active session tracking and metrics                                                   |
+| `/api/rate-limits`                            | GET             | Per-account rate limit status                                                         |
 
 ---
 
-## 5. Patrones de diseño clave
+## 5. Key Design Patterns
 
-### 5.1 Traducción radial
+### 5.1 Hub-and-Spoke Translation
 
-Todos los formatos se traducen a través del **formato OpenAI como centro**. Agregar un nuevo proveedor solo requiere escribir **un par** de traductores (hacia/desde OpenAI), no N pares.
+All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs.
 
-### 5.2 Patrón de estrategia del ejecutor
+### 5.2 Executor Strategy Pattern
 
-Cada proveedor tiene una clase de ejecutor dedicada que hereda de `BaseExecutor`. La fábrica en `executors/index.ts` selecciona la correcta en tiempo de ejecución.
+Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime.
 
-### 5.3 Sistema de complementos de autorregistro
+### 5.3 Self-Registering Plugin System
 
-Los módulos traductores se registran al importar a través de `register()`. Agregar un nuevo traductor es simplemente crear un archivo e importarlo.
+Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it.
 
-### 5.4 Reserva de cuenta con retroceso exponencial
+### 5.4 Account Fallback with Exponential Backoff
 
-Cuando un proveedor devuelve 429/401/500, el sistema puede cambiar a la siguiente cuenta, aplicando tiempos de reutilización exponenciales (1 s → 2 s → 4 s → máx. 2 min).
+When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min).
 
-### 5.5 Cadenas de modelos combinados
+### 5.5 Combo Model Chains
 
-Un "combo" agrupa varias cadenas `provider/model`. Si el primero falla, se pasa automáticamente al siguiente.
+A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically.
 
-### 5.6 Traducción de transmisión con estado
+### 5.6 Stateful Streaming Translation
 
-La traducción de respuestas mantiene el estado en todos los fragmentos de SSE (seguimiento de bloques de pensamiento, acumulación de llamadas de herramientas, indexación de bloques de contenido) a través del mecanismo `initState()`.
+Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism.
 
-### 5.7 Búfer de seguridad de uso
+### 5.7 Usage Safety Buffer
 
-Se agrega un búfer de 2000 tokens al uso informado para evitar que los clientes alcancen los límites de la ventana de contexto debido a la sobrecarga de las indicaciones del sistema y la traducción de formato.
+A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation.
 
 ---
 
-## 6. Formatos admitidos
+## 6. Supported Formats
 
-| Formato                        | Dirección        | Identificador      |
-| ------------------------------ | ---------------- | ------------------ |
-| Finalizaciones del chat OpenAI | fuente + destino | `openai`           |
-| API de respuestas OpenAI       | fuente + destino | `openai-responses` |
-| Claude antrópico               | fuente + destino | `claude`           |
-| Google Géminis                 | fuente + destino | `gemini`           |
-| CLI de Google Géminis          | sólo objetivo    | `gemini-cli`       |
-| Antigravedad                   | fuente + destino | `antigravity`      |
-| AWS Kiro                       | sólo objetivo    | `kiro`             |
-| Cursores                       | sólo objetivo    | `cursor`           |
+| Format                  | Direction       | Identifier         |
+| ----------------------- | --------------- | ------------------ |
+| OpenAI Chat Completions | source + target | `openai`           |
+| OpenAI Responses API    | source + target | `openai-responses` |
+| Anthropic Claude        | source + target | `claude`           |
+| Google Gemini           | source + target | `gemini`           |
+| Google Gemini CLI       | target only     | `gemini-cli`       |
+| Antigravity             | source + target | `antigravity`      |
+| AWS Kiro                | target only     | `kiro`             |
+| Cursor                  | target only     | `cursor`           |
 
 ---
 
-## 7. Proveedores admitidos
+## 7. Supported Providers
 
-| Proveedor                | Método de autenticación               | Ejecutor       | Notas clave                                                     |
-| ------------------------ | ------------------------------------- | -------------- | --------------------------------------------------------------- |
-| Claude antrópico         | Clave API u OAuth                     | Predeterminado | Utiliza el encabezado `x-api-key`                               |
-| Google Géminis           | Clave API u OAuth                     | Predeterminado | Utiliza el encabezado `x-goog-api-key`                          |
-| CLI de Google Géminis    | OAuth                                 | GéminisCLI     | Utiliza el punto final `streamGenerateContent`                  |
-| Antigravedad             | OAuth                                 | Antigravedad   | Respaldo de múltiples URL, análisis de reintentos personalizado |
-| Abierta AI               | Clave API                             | Predeterminado | Autenticación de abanderado                                     |
-| Códice                   | OAuth                                 | Códice         | Inyecta instrucciones del sistema, gestiona el pensamiento      |
-| Copiloto de GitHub       | OAuth + token de copiloto             | GitHub         | Token dual, imitación del encabezado VSCode                     |
-| Kiro (AWS)               | AWS SSO OIDC o redes sociales         | kiro           | Análisis binario de EventStream                                 |
-| Cursor IDE               | Autenticación de suma de comprobación | Cursores       | Codificación Protobuf, sumas de comprobación SHA-256            |
-| Qwen                     | OAuth                                 | Predeterminado | Autenticación estándar                                          |
-| iFlujo                   | OAuth (Básico + Portador)             | Predeterminado | Encabezado de autenticación dual                                |
-| Enrutador abierto        | Clave API                             | Predeterminado | Autenticación de abanderado                                     |
-| GLM, Kimi, MiniMax       | Clave API                             | Predeterminado | Compatible con Claude, use `x-api-key`                          |
-| `openai-compatible-*`    | Clave API                             | Predeterminado | Dinámico: cualquier punto final compatible con OpenAI           |
-| `anthropic-compatible-*` | Clave API                             | Predeterminado | Dinámico: cualquier punto final compatible con Claude           |
+| Provider                 | Auth Method            | Executor    | Key Notes                                     |
+| ------------------------ | ---------------------- | ----------- | --------------------------------------------- |
+| Anthropic Claude         | API key or OAuth       | Default     | Uses `x-api-key` header                       |
+| Google Gemini            | API key or OAuth       | Default     | Uses `x-goog-api-key` header                  |
+| Google Gemini CLI        | OAuth                  | GeminiCLI   | Uses `streamGenerateContent` endpoint         |
+| Antigravity              | OAuth                  | Antigravity | Multi-URL fallback, custom retry parsing      |
+| OpenAI                   | API key                | Default     | Standard Bearer auth                          |
+| Codex                    | OAuth                  | Codex       | Injects system instructions, manages thinking |
+| GitHub Copilot           | OAuth + Copilot token  | Github      | Dual token, VSCode header mimicking           |
+| 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                              |
+| 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       |
+| `anthropic-compatible-*` | API key                | Default     | Dynamic: any Claude-compatible endpoint       |
 
 ---
 
-## 8. Resumen del flujo de datos
+## 8. Data Flow Summary
 
-### Solicitud de transmisión
+### Streaming Request
 
 ```mermaid
 flowchart LR
@@ -566,7 +570,7 @@ flowchart LR
     K --> L["logUsage()\nsaveRequestUsage()"]
 ```
 
-### Solicitud sin transmisión
+### Non-Streaming Request
 
 ```mermaid
 flowchart LR
@@ -577,7 +581,7 @@ flowchart LR
     E --> F["Return JSON\nresponse"]
 ```
 
-### Flujo de derivación (Claude CLI)
+### Bypass Flow (Claude CLI)
 
 ```mermaid
 flowchart LR

docs/i18n/es/FEATURES.md

@@ -1,77 +1,148 @@
-# OmniRoute — Galería de funciones del panel
-
-🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md)
-
-Guía visual de cada sección del panel de OmniRoute.
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/FEATURES.md) · 🇪🇸 [es](../es/FEATURES.md) · 🇫🇷 [fr](../fr/FEATURES.md) · 🇩🇪 [de](../de/FEATURES.md) · 🇮🇹 [it](../it/FEATURES.md) · 🇷🇺 [ru](../ru/FEATURES.md) · 🇨🇳 [zh-CN](../zh-CN/FEATURES.md) · 🇯🇵 [ja](../ja/FEATURES.md) · 🇰🇷 [ko](../ko/FEATURES.md) · 🇸🇦 [ar](../ar/FEATURES.md) · 🇮🇳 [in](../in/FEATURES.md) · 🇹🇭 [th](../th/FEATURES.md) · 🇻🇳 [vi](../vi/FEATURES.md) · 🇮🇩 [id](../id/FEATURES.md) · 🇲🇾 [ms](../ms/FEATURES.md) · 🇳🇱 [nl](../nl/FEATURES.md) · 🇵🇱 [pl](../pl/FEATURES.md) · 🇸🇪 [sv](../sv/FEATURES.md) · 🇳🇴 [no](../no/FEATURES.md) · 🇩🇰 [da](../da/FEATURES.md) · 🇫🇮 [fi](../fi/FEATURES.md) · 🇵🇹 [pt](../pt/FEATURES.md) · 🇷🇴 [ro](../ro/FEATURES.md) · 🇭🇺 [hu](../hu/FEATURES.md) · 🇧🇬 [bg](../bg/FEATURES.md) · 🇸🇰 [sk](../sk/FEATURES.md) · 🇺🇦 [uk-UA](../uk-UA/FEATURES.md) · 🇮🇱 [he](../he/FEATURES.md) · 🇵🇭 [phi](../phi/FEATURES.md)
 
 ---
 
-## 🔌 Proveedores
+# OmniRoute — Dashboard Features Gallery
 
-Administre las conexiones de proveedores de IA: proveedores de OAuth (Claude Code, Codex, Gemini CLI), proveedores de claves API (Groq, DeepSeek, OpenRouter) y proveedores gratuitos (iFlow, Qwen, Kiro).
+🌐 **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)
+
+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).
+
+- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` (free "Light usage" tier); use `ollamacloud/<model>` prefix
 
 ![Providers Dashboard](screenshots/01-providers.png)
 
 ---
 
-## 🎨Combinaciones
+## 🎨 Combos
 
-Cree combinaciones de enrutamiento de modelos con 6 estrategias: llenar primero, por turnos, poder de dos opciones, aleatorio, menos utilizado y de costo optimizado. Cada combo encadena múltiples modelos con respaldo automático.
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
 
 ![Combos Dashboard](screenshots/02-combos.png)
 
 ---
 
-## 📊 Análisis
+## 📊 Analytics
 
-Análisis de uso integral con consumo de tokens, estimaciones de costos, mapas de actividad, gráficos de distribución semanal y desgloses por proveedor.
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
 
 ![Analytics Dashboard](screenshots/03-analytics.png)
 
 ---
 
-## 🏥 Salud del sistema
+## 🏥 System Health
 
-Monitoreo en tiempo real: tiempo de actividad, memoria, versión, percentiles de latencia (p50/p95/p99), estadísticas de caché y estados de los disyuntores del proveedor.
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
 
 ![Health Dashboard](screenshots/04-health.png)
 
 ---
 
-## 🔧 Patio de juegos del traductor
+## 🔧 Translator Playground
 
-Cuatro modos para depurar traducciones de API: **Playground** (convertidor de formato), **Chat Tester** (solicitudes en vivo), **Test Bench** (pruebas por lotes) y **Live Monitor** (transmisión en tiempo real).
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
 
 ![Translator Playground](screenshots/05-translator.png)
 
 ---
 
-## ⚙️ Configuración
+## 🎮 Model Playground _(v2.0.9+)_
 
-Configuración general, almacenamiento del sistema, administración de copias de seguridad (exportación/importación de base de datos), apariencia (modo oscuro/claro), seguridad (incluye protección de terminales API y bloqueo de proveedores personalizado), enrutamiento, resiliencia y configuración avanzada.
+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
+
+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
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
 
 ![Settings Dashboard](screenshots/06-settings.png)
 
 ---
 
-## 🔧 Herramientas CLI
+## 🔧 CLI Tools
 
-Configuración con un clic para herramientas de codificación de IA: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code y 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)
 
 ---
 
-## 📝 Solicitar registros
+## 🤖 CLI Agents _(v2.0.11+)_
 
-Registro de solicitudes en tiempo real con filtrado por proveedor, modelo, cuenta y clave API. Muestra códigos de estado, uso de token, latencia y detalles de respuesta.
+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
+
+---
+
+## 🖼️ 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.
 
 ![Usage Logs](screenshots/08-usage.png)
 
 ---
 
-## 🌐 Punto final API
+## 🌐 API Endpoint
 
-Su punto final API unificado con desglose de capacidades: finalización de chat, incrustaciones, generación de imágenes, reclasificación, transcripción de audio y claves API registradas.
+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. 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)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/es/MCP-SERVER.md

@@ -0,0 +1,87 @@
+🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/MCP-SERVER.md) · 🇪🇸 [es](../es/MCP-SERVER.md) · 🇫🇷 [fr](../fr/MCP-SERVER.md) · 🇩🇪 [de](../de/MCP-SERVER.md) · 🇮🇹 [it](../it/MCP-SERVER.md) · 🇷🇺 [ru](../ru/MCP-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/MCP-SERVER.md) · 🇯🇵 [ja](../ja/MCP-SERVER.md) · 🇰🇷 [ko](../ko/MCP-SERVER.md) · 🇸🇦 [ar](../ar/MCP-SERVER.md) · 🇮🇳 [in](../in/MCP-SERVER.md) · 🇹🇭 [th](../th/MCP-SERVER.md) · 🇻🇳 [vi](../vi/MCP-SERVER.md) · 🇮🇩 [id](../id/MCP-SERVER.md) · 🇲🇾 [ms](../ms/MCP-SERVER.md) · 🇳🇱 [nl](../nl/MCP-SERVER.md) · 🇵🇱 [pl](../pl/MCP-SERVER.md) · 🇸🇪 [sv](../sv/MCP-SERVER.md) · 🇳🇴 [no](../no/MCP-SERVER.md) · 🇩🇰 [da](../da/MCP-SERVER.md) · 🇫🇮 [fi](../fi/MCP-SERVER.md) · 🇵🇹 [pt](../pt/MCP-SERVER.md) · 🇷🇴 [ro](../ro/MCP-SERVER.md) · 🇭🇺 [hu](../hu/MCP-SERVER.md) · 🇧🇬 [bg](../bg/MCP-SERVER.md) · 🇸🇰 [sk](../sk/MCP-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/MCP-SERVER.md) · 🇮🇱 [he](../he/MCP-SERVER.md) · 🇵🇭 [phi](../phi/MCP-SERVER.md)
+
+---
+
+# 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                 |
+| `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/i18n/es/README.md

@@ -11,6 +11,18 @@ _Tu proxy de API universal — un endpoint, 36+ proveedores, cero tiempo de inac
 
 ---
 
+### 🚀 New in v2.0.9+ — Playground, CLI Fingerprints & ACP
+
+| Feature                                    | What It Does                                                                                                                                  |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🎮 **Model Playground**                    | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing                        |
+| 🔏 **CLI Fingerprint Matching**            | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |
+| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw), process spawner, `/api/acp/agents` endpoint                                 |
+| 🤖 **ACP Agents Dashboard**                | Debug > Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool                                      |
+| 🔧 **Custom Model `apiFormat` Routing**    | Custom models with `apiFormat: "responses"` now correctly route to the Responses API translator                                               |
+| 🏢 **Codex Workspace Isolation**           | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID                                                   |
+| 🔄 **Electron Auto-Update**                | Desktop app checks for updates + auto-install on restart                                                                                      |
+
 ### 🤖 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._
@@ -104,7 +116,7 @@ _Conecta cualquier IDE o herramienta CLI con IA a través de OmniRoute — gatew
 
 [🌐 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 (Brasil)](README.pt-BR.md) | 🇪🇸 [Español](README.es.md) | 🇫🇷 [Français](README.fr.md) | 🇮🇹 [Italiano](README.it.md) | 🇷🇺 [Русский](README.ru.md) | 🇨🇳 [中文 (简体)](README.zh-CN.md) | 🇩🇪 [Deutsch](README.de.md) | 🇮🇳 [हिन्दी](README.in.md) | 🇹🇭 [ไทย](README.th.md) | 🇺🇦 [Українська](README.uk-UA.md) | 🇸🇦 [العربية](README.ar.md) | 🇯🇵 [日本語](README.ja.md) | 🇻🇳 [Tiếng Việt](README.vi.md) | 🇧🇬 [Български](README.bg.md) | 🇩🇰 [Dansk](README.da.md) | 🇫🇮 [Suomi](README.fi.md) | 🇮🇱 [עברית](README.he.md) | 🇭🇺 [Magyar](README.hu.md) | 🇮🇩 [Bahasa Indonesia](README.id.md) | 🇰🇷 [한국어](README.ko.md) | 🇲🇾 [Bahasa Melayu](README.ms.md) | 🇳🇱 [Nederlands](README.nl.md) | 🇳🇴 [Norsk](README.no.md) | 🇵🇹 [Português (Portugal)](README.pt.md) | 🇷🇴 [Română](README.ro.md) | 🇵🇱 [Polski](README.pl.md) | 🇸🇰 [Slovenčina](README.sk.md) | 🇸🇪 [Svenska](README.sv.md) | 🇵🇭 [Filipino](README.phi.md)
+🌐 **Disponible en:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
 
 </div>
 
@@ -258,6 +270,7 @@ No todo el mundo puede pagar entre 20 y 200 dólares al mes por suscripciones a
 **Cómo lo resuelve OmniRoute:**
 
 - **Proveedores de nivel gratuito integrados**: soporte nativo para proveedores 100% gratuitos: iFlow (8 modelos ilimitados), Qwen (3 modelos ilimitados), Kiro (Claude gratis), Gemini CLI (180K/mes gratis)
+- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/<model>` prefix
 - **Combos solo gratuitos**: cadena `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/mes sin tiempo de inactividad
 - **Créditos gratuitos NVIDIA NIM**: 1000 créditos gratuitos integrados
 - **Estrategia de optimización de costos**: estrategia de enrutamiento que elige automáticamente el proveedor más barato disponible
@@ -402,7 +415,7 @@ La IA no es solo completar un chat. Los desarrolladores necesitan generar imáge
 - **Texto a vídeo** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) y SD WebUI
 - **Texto a música** — `/v1/music/generations` — ComfyUI (audio estable abierto, MusicGen)
 - **Transcripción de audio** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3
-- **Texto a voz** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3 y proveedores existentes
+- **Texto a voz** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT y proveedores existentes
 - **Moderaciones** — `/v1/moderations` — Comprobaciones de seguridad del contenido
 - **Reclasificación** — `/v1/rerank` — Reclasificación de relevancia del documento
 - **API de respuestas**: compatibilidad total con `/v1/responses` para Codex