chore: bump to v2.0.2 (v2.0.1 was claimed on npm)

Bug Fixes:
- #212: Auto-generate API_KEY_SECRET at startup (like JWT_SECRET)
- #213: Circuit breaker now scoped per-model instead of per-provider
- #200: Connectivity fallback for custom providers (Ollama, LM Studio)

Features:
- #204: API Format selector (Chat Completions / Responses API) for custom models
- #205: Combo endpoint field (chat / embeddings / images) in schema
- #206: Supported Endpoints checkboxes (chat, embeddings, images, audio)
- Custom models with endpoint tags appear in /v1/embeddings and /v1/images/generations
- Model catalog includes api_format, type, and supported_endpoints metadata
- Provider detail page shows badges for non-default endpoint configurations

Files changed: instrumentation.ts, combo.ts, validation.ts, models.ts,
schemas.ts, provider-models/route.ts, providers/[id]/page.tsx,
catalog.ts, embeddings/route.ts, images/generations/route.ts

.agents/workflows/deploy-vps.md

@@ -0,0 +1,55 @@
+---
+description: Deploy the latest OmniRoute code to the Akamai VPS (69.164.221.35) via npm
+---
+
+# Deploy to VPS Workflow
+
+Deploy OmniRoute to the production VPS using Node.js + PM2 (no Docker).
+
+**VPS:** `69.164.221.35` (Akamai, Ubuntu 24.04, 1GB RAM + 2.5GB swap)
+**App path:** `/opt/omniroute-app`
+**Process manager:** PM2 (`omniroute`)
+**Port:** `20128`
+
+## Steps
+
+### 1. Push to GitHub
+
+Ensure all changes are committed and pushed:
+
+```bash
+git push origin main
+```
+
+### 2. SSH into VPS, pull latest code, rebuild, and restart
+
+// 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!'
+"
+```
+
+### 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/"
+```
+
+Expected: PM2 shows `online`, HTTP returns `307` (redirect to login).
+
+## Notes
+
+- The VPS has only 1GB RAM. `NODE_OPTIONS='--max-old-space-size=1536'` uses swap for the build.
+- 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`.

.agents/workflows/generate-release.md

@@ -0,0 +1,78 @@
+---
+description: Create a new release, bump version up to 1.x.10 threshold, update changelog, and manage Pull Requests
+---
+
+# Generate Release Workflow
+
+Bump version, finalize CHANGELOG, commit, tag, push, publish to npm, and create GitHub release.
+
+## Steps
+
+### 1. Determine new version
+
+Check current version in `package.json` and increment the patch number:
+
+```bash
+grep '"version"' package.json
+```
+
+Version format: `1.x.y` — increment `y` for patch, `x` for minor (threshold: y=10 triggers x+1).
+
+### 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
+
+```bash
+sed -i 's/"version": "OLD"/"version": "NEW"/' package.json
+```
+
+### 4. 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"
+```
+
+### 5. Push to GitHub
+
+```bash
+git push origin main
+git push origin vX.Y.Z
+```
+
+### 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
+```
+
+### 8. Deploy to VPS (if requested)
+
+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"
+```
+
+## Notes
+
+- Always run `/update-docs` BEFORE this workflow (ensures CHANGELOG and README are current)
+- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`
+- After npm publish, verify with `npm info omniroute version`

.agents/workflows/issue-triage.md

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

.agents/workflows/resolve-issues.md

@@ -1,12 +1,12 @@
 ---
-description: Fetch all open GitHub issues, analyze bugs, resolve what's possible, triage the rest, then commit and release
+description: Fetch all open GitHub issues, analyze bugs, resolve what's possible, triage the rest, wait for user validation, then commit and release
 ---
 
 # /resolve-issues — Automated Issue Resolution Workflow
 
 ## Overview
 
-This workflow fetches all open issues from the project's GitHub repository, classifies them, analyzes bugs, resolves what can be fixed, triages issues with insufficient information, and generates a release with all fixes.
+This workflow fetches all open issues from the project's GitHub repository, classifies them, analyzes bugs, resolves what can be fixed, and triages issues with insufficient information. **It does NOT merge or release automatically** — it creates a PR and waits for user validation before merging.
 
 ## Steps
 
@@ -60,41 +60,61 @@ Call the `/issue-triage` workflow (located at `~/.gemini/antigravity/global_work
 
 Proceed with resolution:
 
-1. **Research** — Search the codebase for files related to the issue
-2. **Root Cause** — Identify the root cause by reading the relevant source files
-3. **Implement Fix** — Apply the fix following existing code patterns and conventions
-4. **Test** — Build the project and run tests to verify the fix
-5. **Commit** — Commit with message format: `fix: <description> (#<issue_number>)`
+1. **Create a fix branch** — `git checkout -b fix/issue-<NUMBER>-<short-description>`
+2. **Research** — Search the codebase for files related to the issue
+3. **Root Cause** — Identify the root cause by reading the relevant source files
+4. **Implement Fix** — Apply the fix following existing code patterns and conventions
+5. **Test** — Build the project and run tests to verify the fix
+6. **Commit** — Commit with message format: `fix: <description> (#<issue_number>)`
 
-### 5. Commit All Fixes
+### 5. Generate Report & Wait for Validation
 
-After processing all issues:
+Present a summary report to the user via `notify_user` with `BlockedOnUser: true`:
 
-- Ensure all fixes are committed with proper issue references
-- Each fix should be its own commit for clean git history
+| Issue | Title | Status        | Action                        |
+| ----- | ----- | ------------- | ----------------------------- |
+| #N    | Title | ✅ Ready      | Files changed (not committed) |
+| #N    | Title | ❓ Needs Info | Triage comment posted         |
+| #N    | Title | ⏭️ Skipped    | Feature request / not a bug   |
 
-### 6. Close Resolved Issues
+> **⚠️ IMPORTANT**: Do NOT commit, close issues, or generate releases at this step.
+> Wait for the user to review the changes and respond with **OK** before proceeding.
 
-For each successfully fixed issue:
-// turbo
+- If the user says **OK** or approves → Proceed to step 6
+- If the user requests changes → Apply the requested adjustments first, then present the report again
+- If the user rejects → Revert the changes and stop
 
-- Close with a comment: `gh issue close <NUMBER> --repo <owner>/<repo> --comment "Fixed in <commit_hash>. The fix will be included in the next release."`
+### 6. Commit & Push Fix Branch (only after user approval)
 
-### 7. Generate Report
+After the user validates:
 
-Present a summary report to the user via `notify_user`:
+- Commit each fix individually with message format: `fix: <description> (#<issue_number>)`
+- Push the fix branch: `git push origin fix/issue-<NUMBER>-<short-description>`
+- Create a PR: `gh pr create --title "fix: <description> (#<issue_number>)" --body "<details>" --base main`
 
-| Issue | Title | Status        | Action                      |
-| ----- | ----- | ------------- | --------------------------- |
-| #N    | Title | ✅ Fixed      | Commit hash                 |
-| #N    | Title | ❓ Needs Info | Triage comment posted       |
-| #N    | Title | ⏭️ Skipped    | Feature request / not a bug |
+### 7. 🛑 WAIT — Notify User & Await PR Verification
 
-### 8. Update Docs & Release
+**This is a mandatory stop point.** Use `notify_user` with `BlockedOnUser: true`:
 
-If any fixes were committed:
+- Inform the user that the PR was created and is **awaiting their verification**
+- Include the PR number, URL, and a summary of what was changed
+- **DO NOT merge, close issues, generate releases, or deploy until the user confirms**
 
-1. Run the `/update-docs` workflow (at `~/.gemini/antigravity/global_workflows/update-docs.md`) to update CHANGELOG and README
-2. Run the `/generate-release` workflow (at `.agents/workflows/generate-release.md`) to bump version, tag, and publish
+Wait for the user to respond:
+
+- **User confirms** → Proceed to step 8
+- **User requests changes** → Apply changes, push to the same branch, notify again
+- **User rejects** → Close the PR and stop
+
+### 8. Merge, Close Issues & Release (only after user confirms PR)
+
+After the user confirms the PR:
+
+1. **Merge** the PR: `gh pr merge <NUMBER> --merge --repo <owner>/<repo>` or via local merge
+2. **Close** resolved issues with a comment: `gh issue close <NUMBER> --repo <owner>/<repo> --comment "Fixed in <commit_hash>. The fix will be included in the next release."`
+3. **Switch to main**: `git checkout main && git pull`
+4. Run the `/update-docs` workflow (at `~/.gemini/antigravity/global_workflows/update-docs.md`) to update CHANGELOG and README
+5. Run the `/generate-release` workflow (at `.agents/workflows/generate-release.md`) to bump version, tag, and publish
+6. Deploy to local VPS: `ssh root@192.168.0.15 "npm install -g omniroute@<VERSION> && pm2 restart omniroute"`
 
 If NO fixes were committed, skip this step and just present the report.

.agents/workflows/review-prs.md

@@ -6,7 +6,7 @@ description: Analyze open Pull Requests from the project's GitHub repository, ge
 
 ## Overview
 
-This workflow fetches all open PRs from the project's GitHub repository, performs a critical analysis of each one, generates a detailed report, and waits for user approval before proceeding with implementation.
+This workflow fetches all open PRs from the project's GitHub repository, performs a critical analysis of each one, generates a detailed report, and waits for user approval before proceeding with implementation. **All improvements are committed on top of the PR branch** and the user must verify before merge.
 
 ## Steps
 
@@ -60,6 +60,21 @@ This workflow fetches all open PRs from the project's GitHub repository, perform
 - Are edge cases covered?
 - Would existing tests break?
 
+#### 3f. Cross-Layer (Global) Analysis
+
+Perform a **global impact assessment** to verify whether the PR changes are complete across all layers of the application:
+
+- **Backend → Frontend check**: If the PR adds or modifies backend-only resources (new endpoints, services, data models), evaluate whether corresponding frontend changes are missing:
+  - Does a new endpoint require a new screen/page in the dashboard?
+  - Should there be a new action button, menu item, or navigation link?
+  - Are there new data fields that should be displayed or editable in the UI?
+  - Does a new feature need a toggle, configuration panel, or status indicator?
+- **Frontend → Backend check**: If the PR adds frontend elements, verify the backend support exists:
+  - Are the required API endpoints implemented?
+  - Is the data model sufficient for the new UI components?
+- **Cross-cutting concerns**: Check shared layers (types, DTOs, validation schemas, routes, middleware) for completeness
+- **Document gaps** — If missing layers are detected, list them as **IMPORTANT** issues in the report with concrete suggestions for what should be added
+
 ### 4. Generate Report — Create a markdown report for each PR including:
 
 - **PR Summary** — What it does, files affected, commit count
@@ -79,18 +94,52 @@ This workflow fetches all open PRs from the project's GitHub repository, perform
 
 ### 6. Implementation (if approved)
 
-- Checkout the PR branch or apply changes locally
+- Checkout the PR branch: `gh pr checkout <NUMBER>`
 - Implement any required fixes identified in the analysis
+- If the Cross-Layer Analysis (3f) identified missing frontend/backend counterparts, implement them
+- **Commit improvements on top of the PR branch** with descriptive commit messages
 - Run the project's test suite to verify nothing breaks
   // turbo
 - Run: `npm test` or equivalent test command
 - Build the project to verify compilation
   // turbo
 - Run: `npm run build` or equivalent build command
-- If all checks pass, prepare the merge
+- Push the updated branch: `git push origin <branch-name>`
 
-### 7. Post-Merge (if applicable)
+### 7. 🛑 WAIT — Notify User & Await PR Verification
 
-- Update CHANGELOG.md with the new feature
-- Consider version bump if warranted
-- Follow the `/generate-release` workflow if a release is needed
+**This is a mandatory stop point.** Use `notify_user` with `BlockedOnUser: true`:
+
+- Inform the user that the PR has been **improved and pushed**, and is **awaiting their verification**
+- Include:
+  - PR number and URL
+  - Summary of improvements/fixes applied
+  - Build/test status
+  - List of files changed
+- **DO NOT merge, generate releases, or deploy until the user confirms**
+
+Wait for the user to respond:
+
+- **User confirms** → Proceed to step 8
+- **User requests more changes** → Apply changes, push to the same branch, notify again
+- **User rejects** → Leave a review comment and stop
+
+### 8. Thank the Contributor
+
+- Post a **thank-you comment** on the PR via the GitHub API
+- The message should:
+  - Thank the author by name/username for their contribution
+  - Briefly mention what the PR accomplishes and any improvements applied
+  - Be friendly, professional, and encouraging
+- Example: _"Thanks @author for this great contribution! 🎉 The [feature/fix] is now merged and will be part of the next release. We appreciate your effort!"_
+
+### 9. Merge & Release (only after user confirms PR)
+
+After the user confirms the PR:
+
+1. **Merge** the PR into main (local merge with `--no-ff` or via `gh pr merge`)
+2. **Push** to main: `git push origin main`
+3. **Clean up** the feature branch: `git branch -d <branch-name>`
+4. **Update CHANGELOG.md** with the new feature/fix
+5. Run the `/generate-release` workflow (at `.agents/workflows/generate-release.md`) to bump version, tag, and publish
+6. Deploy to local VPS: `ssh root@192.168.0.15 "npm install -g omniroute@<VERSION> && pm2 restart omniroute"`

.agents/workflows/update-docs.md

@@ -0,0 +1,105 @@
+---
+description: How to automatically summarize recent changes and update README and CHANGELOG
+---
+
+# Update Documentation Workflow
+
+Update CHANGELOG.md, README.md, docs/ files, and all multi-language translations whenever features are added or changed.
+
+## Steps
+
+### 1. Summarize recent changes
+
+Review git log and identify new features, fixes, or changes since the last release tag:
+
+```bash
+git log $(git describe --tags --abbrev=0)..HEAD --oneline
+```
+
+### 2. Update English CHANGELOG.md
+
+Add an `[Unreleased]` section (or version header if releasing) with:
+
+- `### ✨ New Features` — each feature as a bullet point
+- `### 🐛 Bug Fixes` — if applicable
+- `### 🧪 Tests` — test count changes
+- `### 📁 New Files` — table of new files with purpose
+
+### 3. Update English README.md
+
+Update the feature tables in these sections:
+
+- **🧠 Routing & Intelligence** — for routing/model features
+- **🛡️ Resilience & Security** — for security/resilience features
+- **📊 Observability & Analytics** — for monitoring features
+- **☁️ Deploy & Sync** — for deployment features
+
+### 4. Update docs/ files
+
+- `docs/FEATURES.md` — update the Settings section description
+- `docs/API_REFERENCE.md` — add new API routes if any
+- `docs/ARCHITECTURE.md` — update architecture if structural changes
+
+### 5. 🌐 Sync Multi-Language Documentation (CRITICAL)
+
+// turbo-all
+
+**This step MUST be run after every README or docs update.**
+
+The project has **30 language versions** of documentation:
+
+**README files (root directory):**
+
+```
+README.md (English - source of truth)
+README.pt-BR.md README.pt.md README.es.md README.fr.md README.it.md
+README.de.md README.nl.md README.sv.md README.no.md README.da.md README.fi.md
+README.ru.md README.uk-UA.md README.bg.md README.sk.md README.pl.md README.ro.md README.hu.md
+README.ar.md README.he.md README.th.md README.in.md README.id.md README.ms.md README.vi.md
+README.ja.md README.ko.md README.zh-CN.md README.phi.md
+```
+
+**docs/i18n/ directories (29 languages):**
+
+```
+docs/i18n/{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}/
+Each contains: API_REFERENCE.md, ARCHITECTURE.md, CODEBASE_DOCUMENTATION.md, FEATURES.md, TROUBLESHOOTING.md, USER_GUIDE.md
+```
+
+**Sync approach for feature table updates:**
+
+a. Identify which feature table rows were added to English README.md
+b. For each translated README, find the corresponding anchor lines:
+
+- **Routing section:** Find the `💬` (System Prompt) table row — the line before it is always the last routing feature. Insert new routing features before System Prompt.
+- **Resilience section:** Find the `📊` Rate Limits table row (the one in lines 590-600, NOT the quota tracking one in lines 560-570). Insert new resilience features after it.
+  c. The new feature entries can stay in English for technical features, matching the pattern used in the existing translations.
+  d. Use `sed` or similar tool to batch-insert across all 29 translated READMEs.
+
+**Verification:**
+
+```bash
+# Verify all READMEs have the new features
+grep -l "NEW_FEATURE_NAME" README.*.md | wc -l
+# Should return 30 (all language versions)
+```
+
+**FEATURES.md sync:**
+
+```bash
+# Update Settings description in all docs/i18n/*/FEATURES.md
+for dir in docs/i18n/*/; do
+  # Update the Settings section description to mention new features
+  # Check FEATURES.md in each directory
+done
+```
+
+### 6. Verify documentation changes
+
+```bash
+# Check all modified files
+git status --short
+
+# Verify no broken markdown
+# Optional: run markdownlint if available
+```

.env.example

@@ -23,7 +23,15 @@ SQLITE_MAX_SIZE_MB=2048
 SQLITE_CLEAN_LEGACY_FILES=true
 
 # Recommended runtime variables
+# Canonical/base port (keeps backward compatibility)
 PORT=20128
+# Optional split ports:
+# API_PORT=20129
+# API_HOST=0.0.0.0
+# DASHBOARD_PORT=20128
+# Optional Docker production host publish ports:
+# PROD_DASHBOARD_PORT=20130
+# PROD_API_PORT=20131
 NODE_ENV=production
 INSTANCE_NAME=omniroute
 
@@ -122,6 +130,22 @@ GEMINI_CLI_OAUTH_CLIENT_SECRET=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
 # IFLOW_OAUTH_CLIENT_ID=
 IFLOW_OAUTH_CLIENT_SECRET=4Z3YjXycVsQvyGF1etiNlIBB4RsqSDtW
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Provider User-Agent Overrides (optional — customize per-provider UA headers)
+# ─────────────────────────────────────────────────────────────────────────────
+# Format: {PROVIDER_ID}_USER_AGENT=custom-value
+# When set, overrides the default User-Agent header sent to that provider.
+# Useful when providers update versions or block old user-agents.
+CLAUDE_USER_AGENT=claude-cli/1.0.83 (external, cli)
+CODEX_USER_AGENT=codex-cli/0.92.0 (Windows 10.0.26100; x64)
+GITHUB_USER_AGENT=GitHubCopilotChat/0.26.7
+ANTIGRAVITY_USER_AGENT=antigravity/1.104.0 darwin/arm64
+KIRO_USER_AGENT=AWS-SDK-JS/3.0.0 kiro-ide/1.0.0
+IFLOW_USER_AGENT=iFlow-Cli
+QWEN_USER_AGENT=google-api-nodejs-client/9.15.1
+CURSOR_USER_AGENT=connect-es/1.6.1
+GEMINI_CLI_USER_AGENT=google-api-nodejs-client/9.15.1
+
 # API Key Providers (Phase 1 + Phase 4)
 # Add via Dashboard → Providers → Add API Key, or set here
 # DEEPSEEK_API_KEY=
@@ -153,3 +177,24 @@ LOG_TO_FILE=true
 # LOG_FILE_PATH=logs/application/app.log
 # LOG_MAX_FILE_SIZE=50M
 # LOG_RETENTION_DAYS=7
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Memory Optimization (Low-RAM configurations)
+# ─────────────────────────────────────────────────────────────────────────────
+# Node.js heap limit in MB (default: 256 for Docker, system default for npm)
+# OMNIROUTE_MEMORY_MB=256
+
+# Prompt cache settings
+# PROMPT_CACHE_MAX_SIZE=50
+# PROMPT_CACHE_MAX_BYTES=2097152
+# PROMPT_CACHE_TTL_MS=300000
+
+# Semantic cache settings (temperature=0 responses)
+# SEMANTIC_CACHE_MAX_SIZE=100
+# SEMANTIC_CACHE_MAX_BYTES=4194304
+# SEMANTIC_CACHE_TTL_MS=1800000
+
+# In-memory log buffers
+# PROXY_LOG_MAX_ENTRIES=200
+# CALL_LOGS_MAX=200
+# STREAM_HISTORY_MAX=50

.github/workflows/ci.yml

@@ -22,6 +22,12 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run lint
+      - run: npm run check:cycles
+      - run: npm run check:route-validation:t06
+      - run: npm run check:any-budget:t11
+      - run: npm run check:docs-sync
+      - run: npm run typecheck:core
+      - run: npm run typecheck:noimplicit:core
 
   security:
     name: Security Audit
@@ -127,7 +133,6 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run test:integration
-        continue-on-error: true
 
   test-security:
     name: Security Tests
@@ -144,4 +149,3 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run test:security
-        continue-on-error: true

.github/workflows/codex-review.yml

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

.github/workflows/deploy-vps.yml

@@ -8,18 +8,12 @@ on:
 
 jobs:
   deploy:
-    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    if: >-
+      (github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success')
+      && vars.DEPLOY_ENABLED == 'true'
     name: Deploy OmniRoute to VPS
     runs-on: ubuntu-latest
     steps:
-      - name: Install Tailscale
-        uses: tailscale/github-action@v3
-        with:
-          oauth-client-id: ""
-          oauth-secret: ""
-          tags: tag:ci-deploy
-        continue-on-error: true
-
       - name: Deploy via SSH
         uses: appleboy/ssh-action@v1
         with:

.github/workflows/docker-publish.yml

@@ -54,7 +54,7 @@ jobs:
           touch "${{ runner.temp }}/digests/${digest#sha256:}"
 
       - name: Upload digest
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: digests-${{ matrix.platform_pair }}
           path: ${{ runner.temp }}/digests/*
@@ -80,7 +80,7 @@ jobs:
           echo "Publishing Docker image version: $VERSION"
 
       - name: Download digests
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           path: ${{ runner.temp }}/digests
           pattern: digests-*

.github/workflows/electron-release.yml

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

.gitignore

@@ -1,7 +1,7 @@
 # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
 
 # dependencies
-/node_modules
+node_modules/
 /.pnp
 .pnp.*
 .yarn/*
@@ -11,10 +11,10 @@
 !.yarn/versions
 
 # testing
-/coverage
+coverage/
 
 # next.js
-/.next/
+.next/
 /out/
 
 # production
@@ -63,6 +63,7 @@ docs/*
 !docs/TASK_NEBIUS_BACKEND_ENABLEMENT.md
 !docs/frontend-backend-provider-gap-report.md
 !docs/openapi.yaml
+!docs/RELEASE_CHECKLIST.md
 !docs/PLANO-IMPLANTACAO.md
 !docs/TASKS.md
 !docs/FASE-*.md
@@ -74,6 +75,8 @@ docs/*
 !docs/VM_DEPLOYMENT_GUIDE.md
 !docs/FEATURES.md
 !docs/screenshots/
+!docs/i18n/
+!docs/i18n/**
 
 # open-sse tests
 open-sse/test/*
@@ -97,3 +100,20 @@ security-analysis/
 clipr/
 app.log
 *.tgz
+
+# Backup directories
+app.__qa_backup/
+
+# Production standalone build (created by scripts/prepublish.mjs)
+# Conflicts with Next.js App Router detection in dev (root app/ shadows src/app/)
+# npm publish still includes it via package.json "files" field
+/app/
+
+# Electron (subproject dependency lock and build artifacts)
+electron/package-lock.json
+electron/dist-electron/
+electron/node_modules/
+icon.iconset/
+
+# VS Code Extension (independent Git repo)
+vscode-extension/

AGENTS.md

@@ -4,6 +4,7 @@
 
 Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support
 (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks, Cohere, etc.)
+with **MCP Server** (16 tools for agent control) and **A2A v0.3 Protocol** (Agent-to-Agent orchestration).
 
 ## Stack
 
@@ -13,6 +14,7 @@ Unified AI proxy/router — route any LLM through one endpoint. Multi-provider s
 - **Streaming**: SSE via `open-sse` internal package
 - **Styling**: Tailwind CSS v4
 - **Docker**: Multi-stage Dockerfile, 3 profiles (base / cli / host)
+- **i18n**: next-intl with 30 languages (`src/i18n/messages/`)
 
 ## Architecture
 
@@ -47,6 +49,56 @@ but the real logic lives in `src/lib/db/`.
 
 Translation between provider formats: `open-sse/translator/`
 
+### MCP Server (`open-sse/mcp-server/`)
+
+16 tools for AI agent control via **3 transport modes**:
+- **stdio** — Local IDE integration (Claude Desktop, Cursor, VS Code)
+- **SSE** — Remote Server-Sent Events at `/api/mcp/sse`
+- **Streamable HTTP** — Modern bidirectional HTTP at `/api/mcp/stream`
+
+HTTP transports run in-process via `httpTransport.ts` singleton using `WebStandardStreamableHTTPServerTransport`.
+
+| Category   | Tools                                                                                                                     |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Essential  | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog` |
+| Advanced   | `simulate_route`, `set_budget_guard`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot` |
+
+- Scoped authorization (9 scopes), audit logging, Zod schemas
+- IDE configs for Claude Desktop, Cursor, VS Code Copilot
+
+### A2A Server (`src/lib/a2a/`)
+
+Agent-to-Agent v0.3 protocol:
+
+- JSON-RPC 2.0: `message/send`, `message/stream`, `tasks/get`, `tasks/cancel`
+- Agent Card at `/.well-known/agent.json`
+- Skills: `smart-routing`, `quota-management`
+- SSE streaming with 15s heartbeat
+- Task Manager with state machine and TTL-based cleanup
+
+### Auto-Combo Engine (`open-sse/services/autoCombo/`)
+
+Self-healing routing optimization:
+- 6-factor scoring, 4 mode packs, bandit exploration
+- Progressive cooldown, probe-based re-admission
+
+### Dashboard (`src/app/(dashboard)/`)
+
+| Page                         | Description                                                    |
+| ---------------------------- | -------------------------------------------------------------- |
+| `/dashboard`                 | Home with quick start, provider overview                       |
+| `/dashboard/endpoint`        | **Endpoints** (tabbed): Endpoint Proxy, MCP, A2A, API Endpoints |
+| `/dashboard/providers`       | Provider management and connections                            |
+| `/dashboard/combos`          | Combo configurations with routing strategies                   |
+| `/dashboard/logs`            | Request, Proxy, Audit, Console logs (tabbed)                   |
+| `/dashboard/analytics`       | Usage analytics and evaluations                                |
+| `/dashboard/costs`           | Cost tracking and breakdown                                    |
+| `/dashboard/health`          | Uptime, circuit breakers, latency                              |
+| `/dashboard/cli-tools`       | CLI tool integrations (Claude, Codex, Antigravity, etc.)       |
+| `/dashboard/media`           | Image, Video, Music generation playground                      |
+| `/dashboard/settings`        | System settings with multiple tabs                             |
+| `/dashboard/api-manager`     | API key management with model permissions                      |
+
 ### OAuth & Tokens (`src/lib/oauth/`)
 
 18 modules handling OAuth flows, token refresh, and provider credentials.
@@ -76,7 +128,7 @@ overridable via env vars or `data/provider-credentials.json`.
 
 - No hardcoded API keys or secrets in commits
 - Auth middleware on all API routes
-- Input validation on user-facing endpoints
+- Input validation on user-facing endpoints (Zod schemas)
 - SQLite encryption key must not be logged
 
 ### Architecture
@@ -85,6 +137,7 @@ overridable via env vars or `data/provider-credentials.json`.
 - Provider requests flow through `open-sse/handlers/`
 - Translations use `open-sse/translator/` modules
 - `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module
+- MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`, not standalone routes
 
 ### Code Quality
 
@@ -92,6 +145,7 @@ overridable via env vars or `data/provider-credentials.json`.
 - Proper HTTP status codes
 - No memory leaks in SSE streams (abort signals, cleanup)
 - Rate limit headers must be parsed correctly
+- All API inputs validated with Zod schemas
 
 ### Docker
 

CHANGELOG.md

@@ -7,6 +7,606 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.0.2] — 2026-03-05
+
+> ### 🐛 Bug Fixes & ✨ Endpoint-Aware Model Management
+
+### 🐛 Bug Fixes
+
+- **#212 — API Key creation crash** — Auto-generate `API_KEY_SECRET` at startup (like `JWT_SECRET`) to prevent HMAC crashes
+- **#213 — Circuit breaker scope** — Changed circuit breaker key from provider-level to model-level; a 429 on one account no longer blocks all accounts for the same provider
+- **#200 — Custom provider connection check** — Added connectivity fallback for OpenAI-compatible providers (Ollama, LM Studio); if `/models` and `/chat/completions` fail, a simple HTTP ping to the base URL marks the provider as connected
+
+### ✨ New Features
+
+- **#204 — API Format selector** — Custom models can now specify `apiFormat`: `chat-completions` (default) or `responses` (for the Responses API)
+- **#205 — Combo endpoint support** — Combos now accept an `endpoint` field in the schema (`chat` | `embeddings` | `images`), enabling fallback/rotation combos for non-chat endpoints
+- **#206 — Supported Endpoints mapping** — When adding custom models, users can check which endpoints the model supports (💬 Chat, 📐 Embeddings, 🖼️ Images, 🔊 Audio). Models tagged for embeddings appear in `/v1/embeddings` and models tagged for images appear in `/v1/images/generations`
+- **Visual badges** — Model rows now display colored badges for non-default API formats and endpoint types
+- **Model catalog metadata** — `/v1/models` response includes `api_format`, `type`, and `supported_endpoints` for custom models
+
+### 📁 Files Changed
+
+| File                                                    | Change                                           |
+| ------------------------------------------------------- | ------------------------------------------------ |
+| `src/instrumentation.ts`                                | Auto-generate `API_KEY_SECRET`                   |
+| `open-sse/services/combo.ts`                            | Circuit breaker keyed per-model                  |
+| `src/lib/providers/validation.ts`                       | Connectivity fallback ping                       |
+| `src/lib/db/models.ts`                                  | `apiFormat` + `supportedEndpoints` fields        |
+| `src/shared/schemas/validation.ts`                      | `endpoint` in `comboSchema`                      |
+| `src/shared/validation/schemas.ts`                      | Extended `providerModelMutationSchema`           |
+| `src/app/api/provider-models/route.ts`                  | Pass new fields through API                      |
+| `src/app/(dashboard)/dashboard/providers/[id]/page.tsx` | API format dropdown, endpoint checkboxes, badges |
+| `src/app/api/v1/models/catalog.ts`                      | Custom model metadata enrichment                 |
+| `src/app/api/v1/embeddings/route.ts`                    | Include custom embedding models                  |
+| `src/app/api/v1/images/generations/route.ts`            | Include custom image models                      |
+
+---
+
+## [2.0.0] — 2026-03-05
+
+> ### 🚀 Major Release — MCP Multi-Transport, A2A Protocol, Auto-Combo Engine & Full Type Safety Overhaul
+>
+> **OmniRoute 2.0** transforms the AI gateway into a fully **agent-controllable platform**. AI agents can now discover, orchestrate, and optimize routing through 16 MCP tools (via 3 transports: stdio, SSE, Streamable HTTP) or the A2A v0.3 protocol. Accompanied by a self-healing Auto-Combo engine, VS Code extension, consolidated Endpoints dashboard with service toggles, and a comprehensive type safety overhaul across the entire codebase.
+
+### 🔌 MCP Multi-Transport (3 Modes)
+
+- **stdio** — Local transport for IDE integration (Claude Desktop, Cursor, VS Code Copilot). Launched via `omniroute --mcp`
+- **SSE (Server-Sent Events)** — Remote HTTP transport at `/api/mcp/sse` (GET+POST). Runs in-process inside Next.js
+- **Streamable HTTP** — Modern bidirectional HTTP transport at `/api/mcp/stream` (GET+POST+DELETE). Uses `WebStandardStreamableHTTPServerTransport` singleton
+- **Transport Selector UI** — When MCP is enabled, a transport picker shows all 3 modes with connection URLs and a Copy button
+- **Settings Persistence** — `mcpTransport` field in settings API (enum: `stdio` | `sse` | `streamable-http`)
+
+### 🆕 MCP Server (16 Tools)
+
+- **8 Essential Tools** — `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`
+- **8 Advanced Tools** — `simulate_route`, `set_budget_guard`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`
+- **Scoped Authorization** — 9 permission scopes (`read:health`, `read:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `write:combos`, `write:budget`, `write:resilience`) with wildcard support
+- **Audit Logging** — Every tool call logged to SQLite with SHA-256 input hashing, output summarization, and duration tracking
+- **IDE Configs** — MCP configuration templates for Claude Desktop, Cursor, VS Code Copilot, and stdio transport
+- **Type-Safe Schemas** — All 16 tools defined with Zod input/output schemas, descriptions, and scope declarations
+- 📖 **Documentation** — [`open-sse/mcp-server/README.md`](open-sse/mcp-server/README.md) with architecture, tool reference, and client examples in Python, TypeScript, and Go
+
+### 🤖 A2A Server (Agent-to-Agent v0.3)
+
+- **JSON-RPC 2.0** — Full router with `message/send`, `message/stream`, `tasks/get`, `tasks/cancel`
+- **Agent Card** — Dynamic `/.well-known/agent.json` with 2 skills and bearer auth
+- **Skills** — `smart-routing` (routing explanation, cost envelope, resilience trace, policy verdict) and `quota-management` (natural language quota queries with ranking, free combo suggestions, and full summaries)
+- **SSE Streaming** — Real-time task streaming with 15s heartbeat, chunk events, and completion metadata
+- **Task Manager** — State machine (`submitted`→`working`→`completed`/`failed`/`cancelled`), TTL (5min default), auto-cleanup (2× TTL)
+- **Routing Logger** — Decision audit trail with 7-day retention and routing statistics
+- **Task Execution** — Generic executor with proper state transitions on success/failure
+- 📖 **Documentation** — [`src/lib/a2a/README.md`](src/lib/a2a/README.md) with JSON-RPC methods, skill reference, client examples, and MCP vs A2A comparison
+
+### ⚡ Auto-Combo Engine
+
+- **6-Factor Scoring** — Quota, health, costInv, latencyInv, taskFit, stability (normalized 0-1)
+- **Task Fitness Table** — 30+ models × 6 task types with wildcard boosts
+- **4 Mode Packs** — Ship Fast, Cost Saver, Quality First, Offline Friendly
+- **Self-Healing** — Progressive cooldown exclusion, probe-based re-admission, incident mode (>50% OPEN)
+- **Bandit Exploration** — 5% exploratory routing for discovering better providers
+- **Adaptation Persistence** — EMA scoring with disk persistence every 10 decisions
+- **REST API** — `POST/GET /api/combos/auto` for CRUD operations
+
+### 🎛️ Consolidated Endpoints Dashboard
+
+- **Tabbed Navigation** — Merged standalone Endpoint, MCP, and A2A sidebar entries into a single **"Endpoints"** page using `SegmentedControl`. Four tabs: **Endpoint Proxy**, **MCP**, **A2A**, **API Endpoints**
+- **Service Enable/Disable Toggles** — MCP and A2A tabs have clickable ON/OFF toggle switches with settings persistence (default: OFF)
+- **Service Status Indicators** — Inline status badges (green "Online" / red "Offline") with 30s auto-refresh
+- **API Endpoints Tab** — Placeholder page with "Coming Soon" badge, listing planned features: REST API catalog, webhooks, OpenAPI/Swagger spec, and per-endpoint auth management
+- **Sidebar Cleanup** — Removed standalone MCP and A2A entries; renamed "Endpoint" to "Endpoints"
+
+### 🧩 VS Code Extension — Advanced Features
+
+- **MCP Client** — 16 tool wrappers with REST API fallback
+- **A2A Client** — Agent discovery, message send/stream, task management
+- **Smart Dispatch** — Task type detection, combo recommendation, risk scoring
+- **Preflight Dialog** — Risk-based display (auto-skip low, info medium, modal high)
+- **Budget Guard** — Session cost tracking with status bar indicator and threshold actions
+- **Mode Pack Selector** — Quick-pick UI for switching optimization profiles
+- **Health Monitor** — Circuit breaker state change notifications
+- **Human Checkpoint** — Multi-factor confidence evaluation with handoff dialog
+
+### 📊 Dashboard Pages
+
+- **MCP Dashboard** — Tool listing, usage stats, audit log with 30s auto-refresh
+- **A2A Dashboard** — Agent Card display, skill listing, task history with routing metadata
+- **Auto-Combo Dashboard** — Provider score bars, factor breakdown, mode pack selector, incident indicator, exclusion list
+- **Error Pages** — Custom error and not-found pages for the dashboard
+
+### 🔗 Integrations
+
+- **OpenClaw** — Dynamic `provider.order` endpoint at `/api/cli-tools/openclaw/auto-order`
+- **Configurable Tool Name Prefix** — `TOOL_NAME_PREFIX` env var for custom MCP tool naming (#199)
+- **Custom RPM/TPM Rate Limits** — Per-provider rate limit overrides (#198)
+- **CORS Fix** — CORS headers on early-return error responses (#208)
+- **Auto-Combo Validation** — Proper validation for auto-combo CRUD operations (#209)
+
+### 🌐 i18n (30 Languages)
+
+- **Endpoints Namespace** — Added `endpoints` i18n namespace with tab labels, toggle labels, and API Endpoints page translations across all 30 locales
+- **Sidebar & Header Updates** — Updated sidebar key from `endpoint` to `endpoints` and header breadcrumb descriptions across all 30 locales
+- **Media & Themes i18n** — Added media section and combo strategy guide translations across all 30 locales
+
+### 🔧 Code Quality & Type Safety
+
+- **Eliminated `any` types** — Replaced `any` casts across `open-sse/` services, translators, and handlers with proper generics and explicit types
+- **Zod Validation Schemas** — Added Zod-based validation for all MCP tool inputs/outputs and API validation layer
+- **Shared Contracts** — Normalized quota and combos API responses with shared contracts (`src/shared/contracts/quota.ts`) for consistent data shapes across MCP, A2A, and REST APIs
+- **TypeScript Translator Types** — Added strict types and modularized the translator registry with proper interfaces
+- **DB Layer Hardening** — Improved database layer with proper error handling and type safety in the compliance module
+- **A2A Lifecycle Safety** — Enhanced A2A task lifecycle with type-safe state transitions, preventing invalid state changes on completed tasks
+- **Stream Handling** — Improved ComfyUI and stream handling with proper type safety
+- **Webpack Barrel-File Fix** — Extracted `updateSettingsSchema` into dedicated `settingsSchemas.ts` to bypass webpack tree-shaking bug
+- **Security Fix** — Insecure randomness fix for code scanning alert #54
+
+### 🧪 Tests
+
+- **E2E Test Suite** — 6 scenarios covering MCP, A2A, Auto-Combo, OpenClaw, Stress (100+50 parallel), Security
+- **Unit Tests** — Essential tools (139 tests), advanced tools (141 tests), Auto-Combo engine (162 tests), A2A lifecycle regression tests
+- **Schema Hardening Tests** — `t06-schema-hardening.test.mjs` (132 tests) for input validation
+- **Security Tests** — `t07-no-log-key-config.test.mjs` (138 tests), `t08-mcp-scope-enforcement.test.mjs` (72 tests)
+- **Integration Tests** — `v1-contracts-behavior.test.mjs` (171 tests), `security-hardening.test.mjs` (103 tests)
+- **Migrated Tests to TypeScript** — E2E ecosystem tests migrated from `.mjs` to `.ts` with proper typing
+- **Combo E2E Tests** — Strategy guides, advanced settings, readiness checks
+
+### 📝 Documentation
+
+- **AGENTS.md** — Updated to v2.0.0 with MCP multi-transport, A2A Protocol, Auto-Combo Engine, consolidated Endpoints dashboard, and Zod validation references
+- **README.md** — Updated Agent & Protocol feature table with 3 transport modes, consolidated endpoints, and service toggles
+- **30 Translated READMEs** — Synced feature tables across all language versions
+- **CHANGELOG.md** — Comprehensive release notes covering all v1.8.1 → v2.0.0 changes
+
+### 📁 New Files (60+)
+
+| Directory                        | Files                                                                                                                                                      |
+| :------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open-sse/mcp-server/`           | `server.ts`, `index.ts`, `audit.ts`, `scopeEnforcement.ts`, `httpTransport.ts`, `tools/advancedTools.ts`, `README.md`                                      |
+| `open-sse/mcp-server/schemas/`   | `tools.ts`, `a2a.ts`, `audit.ts`, `index.ts`                                                                                                               |
+| `src/lib/a2a/`                   | `taskManager.ts`, `taskExecution.ts`, `streaming.ts`, `routingLogger.ts`, `README.md`                                                                      |
+| `src/lib/a2a/skills/`            | `smartRouting.ts`, `quotaManagement.ts`                                                                                                                    |
+| `src/app/a2a/`                   | `route.ts` (JSON-RPC 2.0 dispatch handler)                                                                                                                 |
+| `src/app/api/mcp/sse/`           | `route.ts` (SSE transport endpoint)                                                                                                                        |
+| `src/app/api/mcp/stream/`        | `route.ts` (Streamable HTTP transport endpoint)                                                                                                            |
+| `open-sse/services/autoCombo/`   | `scoring.ts`, `taskFitness.ts`, `engine.ts`, `selfHealing.ts`, `modePacks.ts`, `persistence.ts`, `index.ts`                                                |
+| `src/shared/contracts/`          | `quota.ts` (shared API contracts)                                                                                                                          |
+| `src/shared/constants/`          | `mcpScopes.ts`                                                                                                                                             |
+| `src/shared/validation/`         | `settingsSchemas.ts` (extracted settings Zod schema)                                                                                                       |
+| `src/lib/db/migrations/`         | `002_mcp_a2a_tables.sql`                                                                                                                                   |
+| `src/app/(dashboard)/`           | `dashboard/mcp/page.tsx`, `dashboard/a2a/page.tsx`, `dashboard/auto-combo/page.tsx`, `dashboard/endpoint/ApiEndpointsTab.tsx`                              |
+| `vscode-extension/src/services/` | `mcpClient.ts`, `a2aClient.ts`, `policyEngine.ts`, `preflightDialog.ts`, `budgetGuard.ts`, `healthMonitor.ts`, `modePackSelector.ts`, `humanCheckpoint.ts` |
+| `scripts/`                       | `check-cycles.mjs`, `check-docs-sync.mjs`, `check-route-validation.mjs`, `check-t11-any-budget.mjs`, `run-playwright-tests.mjs`, `runtime-env.mjs`         |
+| `tests/`                         | `t06-schema-hardening.test.mjs`, `t07-no-log-key-config.test.mjs`, `t08-mcp-scope-enforcement.test.mjs`, `ecosystem.test.ts`                               |
+| `docs/`                          | `mcp-server.md`, `a2a-server.md`, `auto-combo.md`, `vscode-extension.md`, `integrations/ide-configs.md`, `RELEASE_CHECKLIST.md`                            |
+
+### 📝 Commit History (`features-agente-mcp-a2a` branch)
+
+| Commit    | Date       | Description                                                                              |
+| :-------- | :--------- | :--------------------------------------------------------------------------------------- |
+| `e0ddb22` | 2026-03-03 | feat: add MCP server mode with `--mcp` flag for IDE integration                          |
+| `09a1748` | 2026-03-03 | feat: add Phase 3 advanced MCP tools and A2A smart routing skill                         |
+| `1e1a9c9` | 2026-03-04 | feat: migrate tests to TypeScript and add MCP advanced tools test suite                  |
+| `ab77452` | 2026-03-04 | feat: normalize quota and combos API responses with shared contracts                     |
+| `88ad4cc` | 2026-03-04 | feat: add MCP server, A2A protocol, auto-combo engine & VS Code extension                |
+| `cc429d4` | 2026-03-04 | feat: add TypeScript types and modularize translator registry                            |
+| `adc8fdf` | 2026-03-04 | feat: add A2A protocol support and refactor API validation layer                         |
+| `500cae3` | 2026-03-04 | refactor: replace `any` types with generics and add Zod validation schemas               |
+| `889e2ba` | 2026-03-04 | feat: add error pages, harden DB layer and compliance module                             |
+| `cbd0b1c` | 2026-03-04 | refactor: harden open-sse services, eliminate any casts, add dashboard pages             |
+| `b33a853` | 2026-03-04 | feat: Introduce A2A lifecycle management, add type safety to ComfyUI and stream handling |
+| `a1a2610` | 2026-03-04 | feat: v2.0.0 - MCP server, A2A agent, proxy improvements and docs update                 |
+| `d615ca5` | 2026-03-05 | feat: configurable tool name prefix (#199) and custom rpm/tpm rate limits (#198)         |
+| `6d8868b` | 2026-03-05 | fix: extract validation helpers to fix webpack barrel-file resolution bug                |
+| `bc2e60c` | 2026-03-05 | feat: Introduce new A2A and MCP API routes, enhance dashboard UI, E2E tests              |
+| `79c23df` | 2026-03-05 | feat: Add i18n for media/themes, enhance combos with strategy guides, E2E tests          |
+| `2490ba5` | 2026-03-05 | feat: Introduce combo readiness checks and strategy recommendations                      |
+| `48dda26` | 2026-03-05 | fix: CORS headers on early-return error responses + auto-combo validation (#208, #209)   |
+| `078a42b` | 2026-03-05 | feat: consolidate Endpoint, MCP, A2A into tabbed Endpoints page                          |
+| `6f1e6a0` | 2026-03-05 | feat: add MCP/A2A enable/disable toggle switches on Endpoints page                       |
+| `bb9d85b` | 2026-03-05 | fix: extract updateSettingsSchema to bypass webpack barrel-file bug                      |
+| `cc7e1a0` | 2026-03-05 | feat: add MCP multi-transport (stdio + SSE + Streamable HTTP)                            |
+
+---
+
+## [1.8.1] — 2026-03-03
+
+### 🐛 Bug Fixes
+
+- **Usage API Proxy Support** — Quota/usage fetch calls (`/api/usage/[connectionId]`) now route through the dashboard-configured proxy (Global → Provider → Key level). Previously, usage fetchers used bare `fetch()` which bypassed the Global Proxy setting, causing "fetch failed" errors in Docker deployments behind a proxy. Fixes #194
+
+## [1.8.0] — 2026-03-03
+
+### 🐛 Bug Fixes
+
+- **Empty `tool_use.name` Validation** — Fixed intermittent HTTP 400 errors when using Claude Code through OmniRoute. Assistant messages with empty `tool_use.name` fields (from interrupted tool calls or malformed history) are now validated and filtered at two layers: the `openai-to-claude` request translator and the `prepareClaudeRequest` sanitizer. Fixes #191
+- **Windows Electron Release** — Fixed the "Collect installers" step failing in every Windows build since v1.7.5+. `electron-builder` produces versioned portable exe filenames (e.g., `OmniRoute 1.6.9.exe`), not the hardcoded `OmniRoute.exe` the workflow expected. Now finds the portable exe dynamically by pattern. PR #190 by @benzntech
+
+## [1.7.14] — 2026-03-02
+
+### 🐛 Bug Fixes
+
+- **Responses SSE Passthrough** — Passthrough mode is now format-aware: Responses SSE payloads (`response.*` type) skip Chat Completions-specific sanitization (`sanitizeStreamingChunk`, `fixInvalidId`, `hasValuableContent`), preventing potential stream corruption for Responses-native clients. Usage extraction still works for both formats. Fixes #186
+
+### ✨ Features
+
+- **Blackbox AI Dashboard** — Added blackbox.ai provider to the dashboard frontend (providers page, pricing, models endpoint). Completes #175
+
+## [1.7.11] — 2026-03-02
+
+### ✨ Features
+
+- **Blackbox AI Provider** — Added blackbox.ai as a new OpenAI-compatible provider with 6 default models (GPT-4o, Gemini 2.5 Flash, Claude Sonnet 4, DeepSeek V3, Blackbox AI, Blackbox AI Pro) and provider logo. Fixes #175
+
+### 🐛 Bug Fixes
+
+- **Antigravity 404 Error** — Added warning logs when `generateProjectId()` generates a fallback project ID because `credentials.projectId` is null. The executor now prefers the translator-set `body.project` before generating a new fallback, eliminating duplicate warnings and ID mismatch. Fixes #176. Includes improvements from PRs #184 and #185
+
+## [1.7.10] — 2026-03-02
+
+### 🐛 Bug Fixes
+
+- **Streaming Tool Calls (Responses→ChatCompletions)** — Fixed two issues in the `openaiResponsesToOpenAIResponse` translator that broke tool call execution in agentic clients (OpenCode, Claude Code, Cursor, etc.): (1) Argument delta chunks now include `tool_calls[].id` and `type: "function"` so clients can associate argument fragments correctly. (2) `finish_reason` is now `"tool_calls"` instead of hardcoded `"stop"` when tool calls occurred. Fixes #180
+
+## [1.7.9] — 2026-03-02
+
+### 🐛 Bug Fixes
+
+- **Electron CI Build** — Added `JWT_SECRET` environment variable to the Electron release workflow `Build Next.js standalone` step, fixing build failures in GitHub Actions. PR #178 by @benzntech
+
+### 📝 Documentation
+
+- **README** — Updated OpenClaw link from `cline/cline` to `openclaw/openclaw` to reflect the project rename. PR #179 by @MAINER4IK
+
+## [1.7.8] — 2026-03-02
+
+### ✨ New Features
+
+- **Theme Color Customization** — Users can now select from 7 preset accent colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or define a custom color via color picker/hex input. The chosen color dynamically updates `--color-primary` and `--color-primary-hover` CSS variables across the entire UI. PR #174 by @mainer4ik
+
+### 🌐 Multi-Language Sync
+
+- **Theme & Media i18n** — Added `themeCoral`, `themeBlue`, `themeRed`, `themeGreen`, `themeViolet`, `themeOrange`, `themeCyan`, `themeAccent`, `themeAccentDesc`, `themeCustom`, `themeCreate`, and media section translations across all **30 language locales**
+
+### 🔧 Code Quality (Review Improvements)
+
+- Exported `COLOR_THEMES` constant from `themeStore.ts` for DRY reuse
+- Added hex color validation with visual feedback (red border + disabled apply button)
+- Synced local state via Zustand `subscribe` pattern for cross-tab consistency
+- Removed dead `/themes` route from Header.tsx
+- Added CSS `color-mix()` fallback for older browsers
+
+## [1.7.7] — 2026-03-02
+
+### 🐛 Bug Fixes
+
+- **Gemini Tool Schema Sanitization** — The standard Gemini provider now sanitizes OpenAI tool schemas before forwarding to Gemini API, removing unsupported JSON Schema keywords (`additionalProperties`, `$schema`, `const`, `default`, `not`, etc.). Previously, sanitization only ran in the CLI executor path, causing Gemini to reject tool calls when schemas contained unsupported constraints. Also applied sanitization to `response_format.json_schema`. Fixes #173
+
+## [1.7.6] — 2026-03-02
+
+### 🐛 Bug Fixes
+
+- **Cloud Proxy `undefined/v1` Fix** — When the `NEXT_PUBLIC_CLOUD_URL` environment variable is not set (common in Docker deployments), the endpoint page now correctly falls back instead of showing `undefined/v1`. The cloud sync API now returns `cloudUrl` in its response so the frontend can use it dynamically. Fixes #171
+
+### ✨ New Features
+
+- **Cloud Worker `/v1/models` Endpoint** — The Cloud Worker now supports the `/v1/models` endpoint for both URL formats (`/v1/models` and `/{machineId}/v1/models`), returning all available models synced from the local OmniRoute instance
+
+### 🔧 Infrastructure
+
+- **Cloudflare Workers Compatibility** — Fixed `setInterval` in global scope issue in `accountFallback.ts` that blocked Cloud Worker deployment. Lazy initialization pattern ensures compatibility with Cloudflare Workers runtime restrictions
+
+## [1.7.5] — 2026-03-02
+
+### 🐛 Bug Fixes
+
+- **OAuth Re-Auth Duplicate Fix** — Re-authenticating an expired OAuth connection now updates the existing connection instead of creating a duplicate entry. When re-auth is triggered, the system matches by `provider` + `email` + `authType` and refreshes tokens in-place. Fixes #170
+
+## [1.7.4] — 2026-03-01
+
+### ✨ New Features
+
+- **OpenCode CLI Integration** — Added full integration guide for [OpenCode](https://opencode.ai) AI CLI tool using `@ai-sdk/openai-compatible` adapter with custom `opencode.json` config. Resolves #169
+- **Endpoint Page Restructured** — Reorganized the Endpoint dashboard page into 3 grouped categories (Core APIs, Media & Multi-Modal, Utility & Management) with visual dividers. Added 2 new endpoint sections: **Responses API** (`/v1/responses`) and **List Models** (`/v1/models`)
+- **Model Aliases & Background Degradation i18n** — Added 14 translated settings keys and 7 translated endpoint keys across all **30 language locales**. Fixed missing translations showing raw keys like `settings.modelAliasesTitle` in the UI
+
+### 🌐 Multi-Language Sync
+
+- **30 README translations synced** — All 28 translated READMEs updated with v1.7.3 feature entries (Model Aliases, Background Degradation, Rate Limit Persistence, Token Refresh Resilience)
+- **6 docs/i18n FEATURES.md updated** — Settings description expanded in da, it, nl, phi, pl, sv
+
+### 📁 New Files
+
+| File                                    | Purpose                                                     |
+| --------------------------------------- | ----------------------------------------------------------- |
+| `.agents/workflows/update-docs.md`      | Documentation update workflow with multi-language sync step |
+| `.agents/workflows/generate-release.md` | Release generation workflow (version bump, npm, GitHub)     |
+| `.agents/workflows/issue-triage.md`     | Issue triage workflow for issues with insufficient info     |
+
+## [1.7.3] — 2026-03-01
+
+### ✨ New Features
+
+- **Model Deprecation Auto-Forward** — New `modelDeprecation.ts` service with 10+ built-in aliases for legacy Gemini, Claude, and OpenAI models. Deprecated model IDs (e.g., `gemini-pro`, `claude-2`) are automatically forwarded to their current replacements. Custom aliases configurable via new Settings → Routing → Model Aliases UI tab with full CRUD API (`/api/settings/model-aliases`)
+- **Background Task Smart Degradation** — New `backgroundTaskDetector.ts` service detects background/utility requests (title generation, summarization, etc.) via 19 system prompt patterns and `X-Request-Priority` header, and automatically reroutes them to cheaper models. Configurable degradation map and detection patterns via new Settings → Routing → Background Degradation UI tab. Disabled by default (opt-in)
+- **Rate Limit Persistence** — Learned rate limits from API response headers are now persisted to SQLite with 60-second debouncing and restored on startup (24h staleness filter). Rate limits survive server restarts instead of being lost in memory
+- **thinkingLevel String Conversion** — `applyThinkingBudget()` now handles string-based `thinkingLevel` inputs (`"high"`, `"medium"`, `"low"`, `"none"`) by converting them to numeric token budgets. Supports `thinkingLevel`, `thinking_level`, and Gemini's `generationConfig.thinkingConfig.thinkingLevel` fields
+- **Claude -thinking Model Auto-Injection** — Models ending with `-thinking` suffix (e.g., `claude-opus-4-6-thinking`) automatically get thinking parameters injected to prevent API errors. `hasThinkingCapableModel()` updated to recognize these suffixes
+- **Gemini 3.0/3.1 Model Registry** — Updated provider registry to explicitly distinguish Gemini 3.1 (Pro, Flash) from 3.0 Preview variants across `gemini`, `gemini-cli`, and `antigravity` providers with clear naming conventions
+- **Token Refresh Circuit Breaker** — Per-provider circuit breaker in `refreshWithRetry()`: 5 consecutive failures trigger a 30-minute cooldown to prevent infinite retry loops. Added 30-second timeout wrapper per refresh attempt. Exported `isProviderBlocked()` and `getCircuitBreakerStatus()` for diagnostics
+
+### 🧪 Tests
+
+- **40+ new unit tests** across 3 files: `model-deprecation.test.mjs` (14 tests), `background-task-detector.test.mjs` (14 tests), extended `thinking-budget.test.mjs` (+13 tests). Total suite: **561 tests, 0 failures**
+
+### 📁 New Files
+
+| File                                                                   | Purpose                                                               |
+| ---------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `open-sse/services/modelDeprecation.ts`                                | Model deprecation alias resolver with built-in + custom aliases       |
+| `open-sse/services/backgroundTaskDetector.ts`                          | Background task detection with pattern matching and model degradation |
+| `src/app/api/settings/model-aliases/route.ts`                          | CRUD API for model alias management                                   |
+| `src/app/api/settings/background-degradation/route.ts`                 | API for background degradation config                                 |
+| `src/app/(dashboard)/settings/components/ModelAliasesTab.tsx`          | Settings UI for model alias management                                |
+| `src/app/(dashboard)/settings/components/BackgroundDegradationTab.tsx` | Settings UI for background degradation                                |
+| `tests/unit/model-deprecation.test.mjs`                                | 14 unit tests for model deprecation                                   |
+| `tests/unit/background-task-detector.test.mjs`                         | 14 unit tests for background task detection                           |
+
+---
+
+## [1.7.2] — 2026-03-01
+
+### ✨ New Features
+
+- **Multi-Modal Provider Support** — Added 6 TTS providers (ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3), 3 STT providers, 2 image providers (SD WebUI, ComfyUI), and two new modalities: `/v1/videos/generations` (Text-to-Video) and `/v1/music/generations` (Text-to-Music). Shared abstractions via `registryUtils.ts` and `comfyuiClient.ts` ([PR #167](https://github.com/diegosouzapw/OmniRoute/pull/167) by @ken2190)
+- **Media Playground Page** — New dashboard page at `/dashboard/media` with tabbed interface (Image/Video/Music), model selector, prompt input, and JSON result viewer
+- **Unit Tests for Registry Utils** — 24 tests covering `parseModelFromRegistry`, `getAllModelsFromRegistry`, `buildAuthHeaders`, and integration with video/music registries
+- **WFGY 16-Problem RAG Failure Map** — Added troubleshooting reference for RAG/LLM failure taxonomy in `docs/TROUBLESHOOTING.md` ([PR #164](https://github.com/diegosouzapw/OmniRoute/pull/164) by @onestardao)
+
+### 🐛 Fixed
+
+- **Gemini Imported Models Return 404** — Strip `models/` prefix from Gemini model IDs during import to prevent doubled paths ([#163](https://github.com/diegosouzapw/OmniRoute/issues/163))
+- **Pino File Transport Fails in Next.js Production** — Log actual error + add sync `pino.destination()` fallback ([#165](https://github.com/diegosouzapw/OmniRoute/issues/165))
+- **Windows Electron CI Build** — Added `shell: bash` to Collect installers step for Windows runners ([PR #168](https://github.com/diegosouzapw/OmniRoute/pull/168) by @benzntech)
+- **TypeScript Safety** — Replaced `Record<string, any>` with `Record<string, unknown>` in `registryUtils.ts`
+
+---
+
+## [1.7.1] — 2026-02-28
+
+### 🐛 Fixed
+
+- **Dashboard Layout Breakage** — Tailwind CSS v4 auto-detection failed to scan Next.js route group directories with parentheses (e.g. `(dashboard)`), causing all responsive grid utilities (`sm:grid-cols-*`, `md:grid-cols-*`, `lg:grid-cols-*`, `xl:grid-cols-*`) to be purged from production CSS. Cards displayed in a single column instead of multi-column grids. Fixed by adding explicit `@source` directives in `globals.css`
+
+---
+
+## [1.7.0] — 2026-02-28
+
+### ✨ New Features
+
+- **16 Pain Points Documentation** — New collapsible section "🎯 What OmniRoute Solves — 16 Real Pain Points" added to the main README and all 29 language-specific READMEs. Each pain point uses `<details>/<summary>` tags for clean, expandable content
+- **Configurable User-Agent per Provider** — User-Agent strings for OAuth providers (Claude, Codex, GitHub, Antigravity, Kiro, iFlow, Qwen, Cursor, Gemini CLI) are now configurable via environment variables. Format: `{PROVIDER_ID}_USER_AGENT=custom-value` ([#155](https://github.com/diegosouzapw/OmniRoute/issues/155))
+
+### 🐛 Fixed
+
+- **Hardcoded `$HOME` Path in Standalone/Bun Builds** — 5 files (`backupService.ts`, `mitm/manager.ts`, `mitm/server.ts`, `mitm/cert/generate.ts`, `codex-profiles/route.ts`) were bypassing the centralized `dataPaths.ts` and using `os.homedir()` directly. This caused paths to bake the build machine's `$HOME` into standalone/bun builds, producing `EACCES: permission denied` errors on other machines. All files now use `resolveDataDir()` from `dataPaths.ts`, respecting `DATA_DIR` env var and XDG conventions ([#156](https://github.com/diegosouzapw/OmniRoute/issues/156))
+
+### 📝 Documentation
+
+- **`.env` and `.env.example` Synced** — Added 9 User-Agent env vars with latest known default values to both environment files
+- **30 README Translations Updated** — All language READMEs now include the 16 Pain Points section
+
+---
+
+## [1.6.9] — 2026-02-28
+
+### 🐛 Fixed
+
+- **Proxy Port Preservation** — `new URL()` silently strips default ports (80/443); proxy connections now extract the port from the raw URL string before parsing, preventing connection timeouts ([PR #161](https://github.com/diegosouzapw/OmniRoute/pull/161))
+- **Proxy Credential Encoding** — URL-encode special characters in proxy username/password; decode during legacy migration ([PR #161](https://github.com/diegosouzapw/OmniRoute/pull/161))
+- **HTTPS Proxy Default Port** — Changed from 8080 to 443 in frontend and migration logic ([PR #161](https://github.com/diegosouzapw/OmniRoute/pull/161))
+- **Proxy Dispatcher Cache** — Invalidate cached dispatchers when proxy config is updated or deleted ([PR #161](https://github.com/diegosouzapw/OmniRoute/pull/161))
+- **Proxy Logger SQLite Type** — Cast `proxyPort` to `Number` for INTEGER column ([PR #161](https://github.com/diegosouzapw/OmniRoute/pull/161))
+- **CopilotToolCard URL** — Use `baseUrl` prop directly instead of redundant `window.location.origin`; filter to chat models only (`!m.type && !m.parent`) ([PR #160](https://github.com/diegosouzapw/OmniRoute/pull/160))
+
+---
+
+## [1.6.8] — 2026-02-28
+
+### 🔧 Improved
+
+- **Electron Release Workflow** — Refactored CI to trigger on git tags (`v*`) + manual dispatch, with version validation, artifact upload/download pattern across 3 platforms, and a single release job. Only installer files (`.dmg`, `.exe`, `.AppImage`) are uploaded — no more 5K+ unpacked files ([PR #159](https://github.com/diegosouzapw/OmniRoute/pull/159))
+- **Windows Portable Exe** — Added standalone portable `.exe` build alongside the NSIS installer ([PR #159](https://github.com/diegosouzapw/OmniRoute/pull/159))
+- **Source Code Archives** — Releases now include `OmniRoute-vX.Y.Z.source.tar.gz` and `.zip` via `git archive` ([PR #159](https://github.com/diegosouzapw/OmniRoute/pull/159))
+- **Installation Docs** — Added platform-specific installation instructions with macOS Gatekeeper workaround ([PR #159](https://github.com/diegosouzapw/OmniRoute/pull/159))
+
+### 🐛 Fixed
+
+- **Next.js App Router Conflict** — Added `app/` (production standalone build) to `.gitignore`. This directory was conflicting with Next.js App Router detection in dev mode, causing all routes to return 404
+- **Git Tracking** — Added `electron/node_modules/` to `.gitignore`
+
+---
+
+## [1.6.7] — 2026-02-28
+
+### ✨ New Feature
+
+- **GitHub Copilot Configuration Generator** — New tool on the CLI Tools dashboard page. Select models and generate the `chatLanguageModels.json` config block for VS Code GitHub Copilot using the Azure vendor pattern. Features: bulk model selection from `/v1/models` (includes combos/custom), search/filter, configurable tokens/tool-calling/vision, one-click copy, persistent selection via localStorage. Version compatibility warning for VS Code ≥ 1.109 / Copilot Chat ≥ v0.37 ([#142](https://github.com/diegosouzapw/OmniRoute/issues/142))
+
+### 🧹 Housekeeping
+
+- Added `electron/dist-electron/` to `.gitignore` (build artifact)
+
+---
+
+## [1.6.6] — 2026-02-28
+
+### 🔒 Security Fix
+
+- **Auth bypass after onboarding** — Fixed regression where users could access the dashboard without authentication after upgrading from older versions. The "no password" safeguard (for fresh installs) was incorrectly firing after onboarding was complete, allowing unauthenticated access when `setupComplete=true` but the password DB row was missing ([#151](https://github.com/diegosouzapw/OmniRoute/issues/151))
+
+---
+
+## [1.6.5] — 2026-02-28
+
+### 🖥️ Electron Desktop
+
+- **Official app icons** — Added proper platform-specific icons derived from the OmniRoute SVG logo: `.icns` (macOS), `.ico` (Windows), `.png` (Linux), and `tray-icon.png` (32×32) — via PR [#154](https://github.com/diegosouzapw/OmniRoute/pull/154)
+- **Automated release workflow** — New GitHub Actions workflow (`electron-release.yml`) builds Electron for Windows/macOS/Linux on every GitHub release publish
+- **CI fix** — Changed `npm ci` → `npm install` in the Electron build step since `electron/package-lock.json` is `.gitignored`
+
+### 📖 Documentation
+
+- **Desktop App section** — Added to all 30 README files (9 fully translated: PT-BR, ES, FR, DE, ZH-CN, JA, RU, KO, AR)
+- **Electron Fix Plan** — Published detailed code review and fix documentation at `docs/ELECTRON_FIX_PLAN.md`
+
+### 🐛 Issue Triage
+
+- **#151** — Auth bypass after v1.6.3 upgrade — triaged, requesting more info from reporter
+- **#142** — Copilot Config Generator — previously triaged, 5 comments
+
+---
+
+## [1.6.4] — 2026-02-28
+
+### 🖥️ Electron Desktop — Code Review Hardening (16 Fixes)
+
+#### 🔴 Critical
+
+- **Server readiness** — Window now waits for server health check before loading URL; no more blank screens on cold start (#1)
+- **Restart timeout** — `restart-server` IPC handler now has 5s timeout + `SIGKILL` to prevent indefinite hangs (#2)
+- **Port change lifecycle** — `changePort()` now stops and restarts the server on the new port instead of just reloading the URL (#3)
+
+#### 🟡 Important
+
+- **Tray cleanup** — Old `Tray` instance is now destroyed before recreating, preventing duplicate icons and memory leaks (#4)
+- **IPC event emission** — Main process now emits `server-status` and `port-changed` events to renderer, making React hooks functional (#5)
+- **Listener accumulation** — Preload now returns disposer functions for precise listener cleanup instead of `removeAllListeners` (#6)
+- **useIsElectron performance** — Replaced `useState`+`useEffect` with `useSyncExternalStore` to eliminate 5x unnecessary re-renders (#7)
+
+#### 🔵 Minor
+
+- Removed dead `isProduction` variable (#8)
+- Platform-conditional `titleBarStyle` — `hiddenInset` only on macOS, `default` on Windows/Linux (#9)
+- `stdio: pipe` — Server output captured for logging and readiness detection instead of `inherit` (#10)
+- Shared `AppInfo` type — `useElectronAppInfo` now uses the shared interface from `types.d.ts` (#11)
+- `useDataDir` error state — Now exposes errors instead of swallowing silently (#12)
+- Synced `electron/package.json` version to `1.6.4` (#13)
+- Removed dead `omniroute://` protocol config — no handler existed (#14)
+- **Content Security Policy** — Added CSP via `session.webRequest.onHeadersReceived` (#15)
+- Simplified preload validation — Generic `safeInvoke`/`safeSend`/`safeOn` wrappers reduce boilerplate (#16)
+
+### 🧪 Test Suite Expansion
+
+- **76 tests** across 15 suites (up from 64 tests / 9 suites)
+- New: server readiness timeout, restart race condition, CSP directives, platform options, disposer pattern, generic IPC wrappers
+
+---
+
+## [1.6.3] — 2026-02-28
+
+### 🐛 Bug Fixes
+
+- **Database data preservation on upgrade** — Previously, upgrading from older versions (e.g. v1.2.0 → v1.6.x) could cause data loss by renaming the existing database when a legacy `schema_migrations` table was detected. Now checks for actual data before deciding to reset ([#146](https://github.com/diegosouzapw/OmniRoute/issues/146))
+- **Hardcoded build-machine paths in npm package** — Next.js standalone output baked absolute paths from the build machine into `server.js` and `required-server-files.json`. On other machines these paths don't exist, causing `ENOENT` errors. The prepublish script now sanitizes all build paths to relative ([#147](https://github.com/diegosouzapw/OmniRoute/issues/147))
+
+---
+
+## [1.6.2] — 2026-02-27
+
+### ✨ New Features
+
+- **Provider labels in Combos** — Combo cards now show user-defined provider names instead of long UUID identifiers, making complex multi-provider combos easier to read ([#121](https://github.com/diegosouzapw/OmniRoute/issues/121))
+- **Improved request log labels** — RequestLoggerV2 resolves OpenAI-compatible provider IDs to user-defined names via provider nodes lookup
+- **Smarter API key display** — `formatApiKey()` now shows the full key name for named keys instead of truncating them
+
+---
+
+## [1.6.1] — 2026-02-27
+
+### 🐛 Bug Fixes
+
+- **Cross-platform npm install** — Added `postinstall` script to auto-rebuild `better-sqlite3` for the user's OS/architecture. Previously, the npm package shipped Linux x64 binaries that failed on Windows and macOS ([#129](https://github.com/diegosouzapw/OmniRoute/issues/129))
+
+---
+
+## [1.6.0] — 2026-02-27
+
+> ### 🔀 Feature Release — Split-Port Mode
+>
+> API and Dashboard can now run on separate ports for advanced deployment scenarios (reverse proxies, container networking, network isolation). Community contribution by [@npmSteven](https://github.com/npmSteven) — PR [#140](https://github.com/diegosouzapw/OmniRoute/pull/140).
+
+### ✨ New Features
+
+- **Split-Port Runtime** — Serve dashboard and OpenAI-compatible API on different ports via `API_PORT` and `DASHBOARD_PORT` env vars. Opt-in; single-port mode unchanged ([#140](https://github.com/diegosouzapw/OmniRoute/pull/140))
+- **API Bridge Server** — Lightweight HTTP proxy routes only OpenAI-compatible paths (`/v1`, `/chat/completions`, `/responses`, `/models`, `/codex`) on the API port, returns 404 for everything else
+- **Centralized Port Resolution** — New `src/lib/runtime/ports.ts` module ensures consistent port config across server, CLI, OAuth, and cloud sync
+- **Runtime Wrapper Scripts** — `scripts/run-next.mjs` and `scripts/run-standalone.mjs` for proper env propagation in dev and Docker modes
+
+### 🐛 Bug Fixes & Polish
+
+- Added 30s timeout to API bridge proxy requests to prevent resource exhaustion
+- Extracted healthcheck into `scripts/healthcheck.mjs` (replaces duplicated inline code)
+- CLI tools page and onboarding derive endpoints from runtime API port
+- OAuth server fallback resolves to effective dashboard port
+- Cloud sync internal URL follows dashboard port
+
+### 🔒 Security
+
+- API bridge defaults to `127.0.0.1` (not `0.0.0.0`) — network-safe by default
+- `API_HOST` env var available for explicit override when needed
+
+### 📦 Dependencies
+
+- Bump `actions/upload-artifact` from 4 to 7 ([#143](https://github.com/diegosouzapw/OmniRoute/pull/143))
+- Bump `actions/download-artifact` from 4 to 8 ([#144](https://github.com/diegosouzapw/OmniRoute/pull/144))
+
+### 🧪 Tests
+
+- Added 14 unit tests for `parsePort` and `resolveRuntimePorts`
+
+---
+
+## [1.5.0] — 2026-02-26
+
+> ### 🌍 Massive i18n Expansion — 30 Languages
+>
+> Dashboard UI, README, and technical documentation now available in 30 languages. CI pipeline hardened with deploy guards.
+
+### ✨ New Features
+
+- **Dashboard i18n — 30 Languages** — Expanded dashboard internationalization from 2 languages (EN, PT-BR) to 30 languages: Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT), Portuguese (BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese (Simplified), Filipino, and English. All 500+ translation keys fully localized with RTL support for Arabic and Hebrew
+- **Multi-Language READMEs** — Added 22 new README translations (total: 30 languages), up from the original 8. Each translation includes full project overview, setup guide, feature list, and pricing table
+- **Multi-Language Documentation** — New `docs/i18n/` directory with translations of all core technical docs (API Reference, Architecture, Codebase Documentation, Features, Troubleshooting, User Guide) in 30 languages
+- **i18n QA Tooling** — Added `scripts/i18n/` with i18n-specific QA and validation scripts
+- **GitHub Discussions** — Enabled Discussions on the repository for community support and Q&A (#136)
+
+### 🐛 Bug Fixes
+
+- **Dashboard Responsiveness** — Fixed layout and responsiveness issues in dashboard components; improved i18n error message handling for missing translation keys
+
+### 🔧 CI/CD
+
+- **Deploy VPS Guard** — Added `DEPLOY_ENABLED` environment variable guard to `deploy-vps.yml` workflow, preventing accidental deployments. Removed broken Tailscale SSH step
+- **Deleted Broken Workflow** — Removed non-functional `codex-review.yml` workflow that was failing in CI
+
+---
+
+## [1.4.11] — 2026-02-25
+
+> ### 🐛 Settings Persistence Fix
+>
+> Fixes routing strategy and wildcard aliases not saving after page refresh.
+
+### 🐛 Bug Fixes
+
+- **Routing Strategy Not Saved After Refresh (#134)** — Added `fallbackStrategy`, `wildcardAliases`, and `stickyRoundRobinLimit` to the Zod validation schema. These fields were silently stripped during validation, preventing them from being persisted to the database
+
+### 📝 Notes
+
+- **#135 Closed** — Feature request for proxy configuration (global + per-provider) was already implemented in v1.4.10
+
+---
+
 ## [1.4.10] — 2026-02-25
 
 > ### 🔒 Proxy Visibility + Bug Fixes
@@ -673,6 +1273,15 @@ New environment variables:
 
 ---
 
+[1.6.3]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.6.3
+[1.6.2]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.6.2
+[1.6.1]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.6.1
+[1.6.0]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.6.0
+[1.5.0]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.5.0
+[1.4.11]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.4.11
+[1.4.10]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.4.10
+[1.4.9]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.4.9
+[1.4.8]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.4.8
 [1.4.7]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.4.7
 [1.4.6]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.4.6
 [1.4.5]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.4.5

Dockerfile

@@ -2,6 +2,7 @@ FROM node:22-bookworm-slim AS builder
 WORKDIR /app
 
 COPY package*.json ./
+COPY scripts/postinstall.mjs ./scripts/postinstall.mjs
 RUN if [ -f package-lock.json ]; then npm ci --no-audit --no-fund; else npm install --no-audit --no-fund; fi
 
 COPY . ./
@@ -19,6 +20,7 @@ LABEL org.opencontainers.image.title="omniroute" \
 ENV NODE_ENV=production
 ENV PORT=20128
 ENV HOSTNAME=0.0.0.0
+ENV NODE_OPTIONS="--max-old-space-size=256"
 
 # Data directory inside Docker — must match the volume mount in docker-compose.yml
 ENV DATA_DIR=/app/data
@@ -27,13 +29,16 @@ 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 ./
+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
 
 EXPOSE 20128
 
 HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
-  CMD node -e "fetch('http://127.0.0.1:20128/api/settings').then(r=>{if(!r.ok)throw r.status}).catch(()=>process.exit(1))"
+  CMD ["node", "healthcheck.mjs"]
 
-CMD ["node", "server.js"]
+CMD ["node", "run-standalone.mjs"]
 
 FROM runner-base AS runner-cli
 
@@ -45,4 +50,3 @@ RUN apt-get update \
 
 # Install CLI tools globally. Separate layer from apt for better cache reuse.
 RUN npm install -g --no-audit --no-fund @openai/codex @anthropic-ai/claude-code droid openclaw@latest
-

README.es.md

@@ -104,12 +104,41 @@ _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](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
+🌐 **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)
 
 </div>
 
 ---
 
+## 🖼️
+
+<div align="center">
+  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute" width="800"/>
+</div>
+
+---
+
+## 📸
+
+<details>
+<summary><b>...</b></summary>
+
+| #     | #                                        |
+| ----- | ---------------------------------------- |
+| **1** | ![1](docs/screenshots/01-providers.png)  |
+| **2** | ![2](docs/screenshots/02-combos.png)     |
+| **3** | ![3](docs/screenshots/03-analytics.png)  |
+| **4** | ![4](docs/screenshots/04-health.png)     |
+| **5** | ![5](docs/screenshots/05-translator.png) |
+| **6** | ![6](docs/screenshots/06-settings.png)   |
+| **7** | ![7](docs/screenshots/07-cli-tools.png)  |
+| **8** | ![8](docs/screenshots/08-usage.png)      |
+| **9** | ![9](docs/screenshots/09-endpoint.png)   |
+
+</details>
+
+---
+
 ## 🤔 ¿Por qué OmniRoute?
 
 **Deja de desperdiciar dinero y chocar con límites:**
@@ -128,6 +157,18 @@ _Conecta cualquier IDE o herramienta CLI con IA a través de OmniRoute — gatew
 
 ---
 
+## 📧 Soporte
+
+> 💬 **¡Únete a la comunidad!** [Grupo WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obtén ayuda, comparte consejos y mantente al día.
+
+- **Website**: [omniroute.online](https://omniroute.online)
+- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **WhatsApp**: [Grupo de la Comunidad](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+- **Proyecto Original**: [9router por decolua](https://github.com/decolua/9router)
+
+---
+
 ## 🔄 Cómo Funciona
 
 ```
@@ -157,6 +198,497 @@ Resultado: Nunca dejes de programar, costo mínimo
 
 ---
 
+## 🎯 Lo que resuelve OmniRoute: 30 puntos débiles reales y casos de uso
+
+> **Todos los desarrolladores que utilizan herramientas de IA se enfrentan a estos problemas a diario.** OmniRoute se creó para resolverlos todos: desde sobrecostos hasta bloqueos regionales, desde flujos rotos de OAuth hasta operaciones de protocolo y observabilidad empresarial.
+
+<details>
+<summary><b>💸 1. "Pago una suscripción costosa pero aún así me interrumpen los límites"</b></summary>
+
+Los desarrolladores pagan entre 20 y 200 dólares al mes por Claude Pro, Codex Pro o GitHub Copilot. Incluso pagando, la cuota tiene un límite: 5 horas de uso, límites semanales o límites de tarifa por minuto. A mitad de la sesión de codificación, el proveedor deja de responder y el desarrollador pierde flujo y productividad.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **Reserva inteligente de 4 niveles**: si se agota la cuota de suscripción, se redirige automáticamente a la clave API → Barato → Gratis sin intervención manual
+- **Seguimiento de cuotas en tiempo real**: muestra el consumo de tokens en tiempo real con cuenta regresiva de reinicio (5 h, diario, semanal)
+- **Soporte multicuenta**: varias cuentas por proveedor con rotación automática: cuando una se agota, cambia a la siguiente
+- **Combinaciones personalizadas**: cadenas de respaldo personalizables con 6 estrategias de equilibrio (completar primero, por turnos, P2C, aleatoria, menos utilizada, de costo optimizado)
+- **Cuotas comerciales de Codex**: monitoreo de cuotas del espacio de trabajo empresarial/de equipo directamente en el panel
+
+</details>
+
+<details>
+<summary><b>🔌 2. "Necesito usar varios proveedores pero cada uno tiene una API diferente"</b></summary>
+
+OpenAI usa un formato, Claude (Anthropic) usa otro, Gemini otro más. Si un desarrollador quiere probar modelos de diferentes proveedores o recurrir a ellos, debe reconfigurar los SDK, cambiar los puntos finales y lidiar con formatos incompatibles. Los proveedores personalizados (FriendLI, NIM) tienen puntos finales de modelo no estándar.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **Punto final unificado**: un único `http://localhost:20128/v1` sirve como proxy para los más de 36 proveedores
+- **Traducción de formato**: automática y transparente: OpenAI ↔ Claude ↔ Gemini ↔ API de respuestas
+- **Desinfección de respuesta**: elimina los campos no estándar (`x_groq`, `usage_breakdown`, `service_tier`) que interrumpen OpenAI SDK v1.83+
+- **Normalización de roles**: convierte `developer` → `system` para proveedores que no son OpenAI; `system` → `user` para GLM/ERNIE
+- **Think Tag Extraction**: extrae bloques `<think>` de modelos como DeepSeek R1 en `reasoning_content` estandarizado.
+- **Salida estructurada para Gemini** — `json_schema` → `responseMimeType`/`responseSchema` conversión automática
+- **`stream` por defecto es `false`**: se alinea con las especificaciones de OpenAI, evitando SSE inesperado en los SDK de Python/Rust/Go
+
+</details>
+
+<details>
+<summary><b>🌐 3. "Mi proveedor de IA bloquea mi región/país"</b></summary>
+
+Proveedores como OpenAI/Codex bloquean el acceso desde ciertas regiones geográficas. Los usuarios obtienen errores como `unsupported_country_region_territory` durante las conexiones OAuth y API. Esto resulta especialmente frustrante para los desarrolladores de los países en desarrollo.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **Configuración de proxy de 3 niveles**: Proxy configurable en 3 niveles: global (todo el tráfico), por proveedor (un solo proveedor) y por conexión/clave.
+- **Insignias de proxy codificadas por colores** — Indicadores visuales: 🟢 proxy global, 🟡 proxy de proveedor, 🔵 proxy de conexión, que siempre muestra la IP
+- **Intercambio de tokens de OAuth a través de proxy**: el flujo de OAuth también pasa a través del proxy, lo que resuelve `unsupported_country_region_territory`
+- **Pruebas de conexión a través de proxy**: las pruebas de conexión utilizan el proxy configurado (no más derivación directa)
+- **Soporte SOCKS5**: soporte completo de proxy SOCKS5 para enrutamiento saliente
+- **Suplantación de huellas dactilares TLS**: huella digital TLS similar a la de un navegador a través de `wreq-js` para evitar la detección de bots.
+
+</details>
+
+<details>
+<summary><b>🆓 4. "Quiero usar IA para codificar pero no tengo dinero"</b></summary>
+
+No todo el mundo puede pagar entre 20 y 200 dólares al mes por suscripciones a IA. Los estudiantes, desarrolladores de países emergentes, aficionados y autónomos necesitan acceso a modelos de calidad sin costo alguno.
+
+**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)
+- **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
+
+</details>
+
+<details>
+<summary><b>🔒 5. "Necesito proteger mi puerta de enlace AI del acceso no autorizado"</b></summary>
+
+Al exponer una puerta de enlace de IA a la red (LAN, VPS, Docker), cualquiera con la dirección puede consumir los tokens/cuota del desarrollador. Sin protección, las API son vulnerables al mal uso, la inyección rápida y el abuso.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **Administración de claves API**: generación, rotación y alcance por proveedor con una página `/dashboard/api-manager` dedicada
+- **Permisos a nivel de modelo**: restrinja las claves API a modelos específicos (`openai/*`, patrones comodín), con la opción Permitir todo/Restringir
+- **API Endpoint Protection**: requiere una clave para `/v1/models` y bloquea proveedores específicos del listado
+- **Auth Guard + Protección CSRF**: todas las rutas del panel protegidas con middleware `withAuth` + tokens CSRF
+- **Limitador de velocidad**: limitación de velocidad por IP con ventanas configurables
+- **Filtrado de IP**: lista permitida/lista bloqueada para control de acceso
+- **Prompt injection guard**: desinfección contra patrones de avisos maliciosos
+- **Cifrado AES-256-GCM**: credenciales cifradas en reposo
+
+</details>
+
+<details>
+<summary><b>🛑 6. "Mi proveedor dejó de funcionar y perdí mi flujo de codificación"</b></summary>
+
+Los proveedores de IA pueden volverse inestables, devolver errores 5xx o alcanzar límites de velocidad temporales. Si un desarrollador depende de un solo proveedor, se le interrumpe. Sin disyuntores, los reintentos repetidos pueden bloquear la aplicación.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **Disyuntor por proveedor**: apertura/cierre automático con umbrales configurables y enfriamiento (cerrado/abierto/medio abierto)
+- **Retroceso exponencial**: retrasos progresivos en los reintentos
+- **Anti-Thundering Herd** — Mutex + protección de semáforo contra tormentas de reintentos simultáneos
+- **Cadenas alternativas combinadas**: si el proveedor principal falla, automáticamente pasa por la cadena sin intervención.
+- **Disyuntor combinado**: desactiva automáticamente los proveedores defectuosos dentro de una cadena combinada
+- **Panel de estado**: monitoreo del tiempo de actividad, estados de disyuntores, bloqueos, estadísticas de caché, latencia p50/p95/p99
+
+</details>
+
+<details>
+<summary><b>🔧 7. "Configurar cada herramienta de IA es tedioso y repetitivo"</b></summary>
+
+Los desarrolladores utilizan Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Cada herramienta necesita una configuración diferente (punto final API, clave, modelo). Reconfigurar al cambiar de proveedor o modelo es una pérdida de tiempo.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **Panel de herramientas CLI**: página dedicada con configuración con un solo clic para Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
+- **Generador de configuración de GitHub Copilot**: genera `chatLanguageModels.json` para código VS con selección de modelo masivo
+- **Asistente de incorporación**: configuración guiada de 4 pasos para usuarios nuevos
+- **Un punto final, todos los modelos**: configure `http://localhost:20128/v1` una vez, acceda a más de 36 proveedores
+
+</details>
+
+<details>
+<summary><b>🔑 8. "Administrar tokens OAuth de múltiples proveedores es un infierno"</b></summary>
+
+Claude Code, Codex, Gemini CLI, Copilot: todos usan OAuth 2.0 con tokens que caducan. Los desarrolladores necesitan volver a autenticarse constantemente, lidiar con `client_secret is missing`, `redirect_uri_mismatch` y fallas en servidores remotos. OAuth en LAN/VPS es particularmente problemático.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **Actualización automática de tokens**: los tokens de OAuth se actualizan en segundo plano antes de que caduquen
+- **OAuth 2.0 (PKCE) integrado**: flujo automático para Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow
+- **OAuth multicuenta**: varias cuentas por proveedor mediante extracción de token JWT/ID
+- **OAuth LAN/Remote Fix** — Detección de IP privada para `redirect_uri` + modo URL manual para servidores remotos
+- **OAuth detrás de Nginx**: utiliza `window.location.origin` para compatibilidad con proxy inverso
+- **Guía remota de OAuth**: guía paso a paso para las credenciales de Google Cloud en VPS/Docker
+
+</details>
+
+<details>
+<summary><b>📊 9. "No sé cuánto estoy gastando ni dónde"</b></summary>
+
+Los desarrolladores utilizan múltiples proveedores pagos pero no tienen una visión unificada del gasto. Cada proveedor tiene su propio panel de facturación, pero no hay una vista consolidada. Los costos inesperados pueden acumularse.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **Panel de análisis de costos**: seguimiento de costos por token y gestión de presupuesto por proveedor
+- **Límites de presupuesto por nivel**: límite de gasto por nivel que activa el respaldo automático
+- **Configuración de precios por modelo**: precios configurables por modelo
+- **Estadísticas de uso por clave API**: recuento de solicitudes y marca de tiempo utilizada por última vez por clave
+- **Panel de análisis**: tarjetas de estadísticas, tabla de uso de modelos, tabla de proveedores con tasas de éxito y latencia.
+
+</details>
+
+<details>
+<summary><b>🐛 10. "No puedo diagnosticar errores y problemas en llamadas AI"</b></summary>
+
+Cuando falla una llamada, el desarrollador no sabe si se trata de un límite de velocidad, un token caducado, un formato incorrecto o un error del proveedor. Registros fragmentados en diferentes terminales. Sin observabilidad, la depuración es de prueba y error.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **Panel de registros unificados**: 4 pestañas: registros de solicitudes, registros de proxy, registros de auditoría y consola
+- **Visor de registros de consola**: visor estilo terminal en tiempo real con niveles codificados por colores, desplazamiento automático, búsqueda y filtro
+- **Registros de proxy SQLite**: registros persistentes que sobreviven a los reinicios del servidor
+- **Translator Playground**: 4 modos de depuración: Playground (traducción de formato), Chat Tester (ida y vuelta), Test Bench (por lotes), Live Monitor (en tiempo real)
+- **Solicitud de telemetría**: latencia p50/p95/p99 + seguimiento de X-Request-Id
+- **Registro basado en archivos con rotación**: el interceptor de consola captura todo en el registro JSON con rotación basada en el tamaño.
+
+</details>
+
+<details>
+<summary><b>🏗️ 11. "Implementar y mantener la puerta de enlace es complejo"</b></summary>
+
+Instalar, configurar y mantener un proxy de IA en diferentes entornos (local, VPS, Docker, nube) requiere mucha mano de obra. Problemas como rutas codificadas, `EACCES` en directorios, conflictos de puertos y compilaciones multiplataforma añaden fricción.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **instalación global de npm** — `npm install -g omniroute && omniroute` — hecho
+- **Docker multiplataforma**: AMD64 + ARM64 nativo (Apple Silicon, AWS Graviton, Raspberry Pi)
+- **Perfiles de Docker Compose**: `base` (sin herramientas CLI) y `cli` (con Claude Code, Codex, OpenClaw)
+- **Aplicación de escritorio Electron**: aplicación nativa para Windows/macOS/Linux con bandeja del sistema, inicio automático y modo sin conexión
+- **Modo de puerto dividido**: API y panel en puertos separados para escenarios avanzados (proxy inverso, redes de contenedores)
+- **Cloud Sync**: sincronización de configuración entre dispositivos a través de Cloudflare Workers
+- **Copias de seguridad de base de datos**: copia de seguridad, restauración, exportación e importación automáticas de todas las configuraciones
+
+</details>
+
+<details>
+<summary><b>🌍 12. "La interfaz es solo en inglés y mi equipo no habla inglés"</b></summary>
+
+Los equipos en países que no hablan inglés, especialmente en América Latina, Asia y Europa, tienen dificultades con las interfaces solo en inglés. Las barreras del idioma reducen la adopción y aumentan los errores de configuración.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **Panel i18n — 30 idiomas** — Las más de 500 teclas traducidas, incluidas árabe, búlgaro, danés, alemán, español, finlandés, francés, hebreo, hindi, húngaro, indonesio, italiano, japonés, coreano, malayo, holandés, noruego, polaco, portugués (PT/BR), rumano, ruso, eslovaco, sueco, tailandés, ucraniano, vietnamita, chino, filipino, inglés.
+- **Soporte RTL**: soporte de derecha a izquierda para árabe y hebreo
+- **README multilingüe**: 30 traducciones de documentación completa
+- **Selector de idioma**: ícono de globo en el encabezado para cambiar en tiempo real
+
+</details>
+
+<details>
+<summary><b>🔄 13. "Necesito más que chat: necesito incrustaciones, imágenes y audio"</b></summary>
+
+La IA no es solo completar un chat. Los desarrolladores necesitan generar imágenes, transcribir audio, crear incrustaciones para RAG, reclasificar documentos y moderar contenido. Cada API tiene un punto final y un formato diferentes.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **Integraciones** — `/v1/embeddings` con 6 proveedores y más de 9 modelos
+- **Generación de imágenes** — `/v1/images/generations` con 10 proveedores y más de 20 modelos (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)
+- **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
+- **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
+
+</details>
+
+<details>
+<summary><b>🧪 14. "No tengo forma de probar y comparar la calidad entre modelos"</b></summary>
+
+Los desarrolladores quieren saber qué modelo es mejor para su caso de uso (código, traducción, razonamiento), pero comparar manualmente es lento. No existen herramientas de evaluación integradas.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **Evaluaciones LLM**: pruebas de conjunto dorado con 10 casos precargados que cubren saludos, matemáticas, geografía, generación de código, cumplimiento de JSON, traducción, rebajas y rechazo de seguridad.
+- **4 estrategias de coincidencia**: `exact`, `contains`, `regex`, `custom` (función JS)
+- **Translator Playground Test Bench**: pruebas por lotes con múltiples entradas y resultados esperados, comparación entre proveedores
+- **Chat Tester**: recorrido completo de ida y vuelta con representación de respuesta visual
+- **Live Monitor**: flujo en tiempo real de todas las solicitudes que fluyen a través del proxy
+
+</details>
+
+<details>
+<summary><b>📈 15. "Necesito escalar sin perder rendimiento"</b></summary>
+
+A medida que crece el volumen de solicitudes, sin almacenar en caché las mismas preguntas generan costos duplicados. Sin idempotencia, las solicitudes duplicadas desperdician el procesamiento. Se deben respetar los límites de tarifas por proveedor.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **Caché semántica**: la caché de dos niveles (firma + semántica) reduce el costo y la latencia
+- **Solicitud de idempotencia**: ventana de deduplicación de 5 segundos para solicitudes idénticas
+- **Detección de límite de velocidad**: RPM por proveedor, intervalo mínimo y seguimiento simultáneo máximo
+- **Límites de velocidad editables**: valores predeterminados configurables en Configuración → Resiliencia con persistencia
+- **Caché de validación de clave API**: caché de 3 niveles para rendimiento de producción
+- **Panel de estado con telemetría**: latencia p50/p95/p99, estadísticas de caché, tiempo de actividad
+
+</details>
+
+<details>
+<summary><b>🤖 16. "Quiero controlar el comportamiento del modelo globalmente"</b></summary>
+
+Desarrolladores que quieran todas las respuestas en un idioma específico, con un tono específico o quieran limitar los tokens de razonamiento. Configurar esto en cada herramienta/solicitud no es práctico.
+
+**Cómo lo resuelve OmniRoute:**
+
+- **Inyección de aviso del sistema**: aviso global aplicado a todas las solicitudes
+- **Thinking Budget Validation**: control de asignación de tokens de razonamiento por solicitud (transferencia, automática, personalizada, adaptativa)
+- **6 estrategias de enrutamiento**: estrategias globales que determinan cómo se distribuyen las solicitudes
+- **Enrutador comodín**: los patrones `provider/*` se enrutan dinámicamente a cualquier proveedor
+- **Activar/desactivar combinación de alternar**: alterna combinaciones directamente desde el panel
+- **Alternar proveedor**: activa/desactiva todas las conexiones de un proveedor con un solo clic
+- **Proveedores bloqueados**: excluye proveedores específicos del listado `/v1/models`
+
+</details>
+
+<details>
+<summary><b>🧰 17. "Necesito herramientas MCP como capacidades de producto de primera clase"</b></summary>
+
+Muchas puertas de enlace de IA exponen MCP solo como un detalle de implementación oculto. Los equipos necesitan una capa operativa visible y manejable.
+
+**Cómo lo resuelve OmniRoute:**
+
+- MCP aparece en la pestaña de navegación del panel y protocolo de punto final
+- Página de gestión de MCP dedicada con procesos, herramientas, alcances y auditoría
+- Inicio rápido integrado para `omniroute --mcp` e incorporación de clientes
+
+</details>
+
+<details>
+<summary><b>🧠 18. "Necesito orquestación A2A con rutas de tareas de sincronización + transmisión"</b></summary>
+
+Los flujos de trabajo de los agentes necesitan respuestas directas y una ejecución continua de larga duración con control del ciclo de vida.
+
+**Cómo lo resuelve OmniRoute:**
+
+- Punto final A2A JSON-RPC (`POST /a2a`) con `message/send` y `message/stream`
+- Transmisión SSE con propagación del estado terminal
+- API de ciclo de vida de tareas para `tasks/get` y `tasks/cancel`
+
+</details>
+
+<details>
+<summary><b>🛰️ 19. "Necesito un estado real del proceso MCP, no un estado adivinado"</b></summary>
+
+Los equipos operativos necesitan saber si MCP está realmente activo, no solo si se puede acceder a una API.
+
+**Cómo lo resuelve OmniRoute:**
+
+- Archivo de latidos en tiempo de ejecución con PID, marcas de tiempo, transporte, recuento de herramientas y modo de alcance
+- API de estado de MCP que combina latidos + actividad reciente
+- Tarjetas de estado de la interfaz de usuario para el proceso/tiempo de actividad/actualización de latidos
+
+</details>
+
+<details>
+<summary><b>📋 20. "Necesito ejecución de herramienta MCP auditable"</b></summary>
+
+Cuando las herramientas modifican la configuración o desencadenan acciones de operaciones, los equipos necesitan trazabilidad forense.
+
+**Cómo lo resuelve OmniRoute:**
+
+- Registro de auditoría respaldado por SQLite para llamadas a herramientas MCP
+- Filtros por herramienta, éxito/fracaso, clave API y paginación
+- Tabla de auditoría del panel + puntos finales de estadísticas para automatización
+
+</details>
+
+<details>
+<summary><b>🔐 21. "Necesito permisos MCP con alcance por integración"</b></summary>
+
+Los diferentes clientes deberían tener acceso con privilegios mínimos a las categorías de herramientas.
+
+**Cómo lo resuelve OmniRoute:**
+
+- 9 alcances MCP granulares para acceso controlado a herramientas
+- Aplicación del alcance y visibilidad en la interfaz de usuario de gestión de MCP
+- Postura predeterminada segura para herramientas operativas
+
+</details>
+
+<details>
+<summary><b>⚙️ 22. "Necesito controles operativos sin redistribuir"</b></summary>
+
+Los equipos necesitan cambios rápidos en el tiempo de ejecución durante incidentes o eventos de costos.
+
+**Cómo lo resuelve OmniRoute:**
+
+- Cambie la activación combinada directamente desde el panel de MCP
+- Aplicar perfiles de resiliencia de paquetes de políticas predefinidos
+- Restablecer el estado del disyuntor desde el mismo panel de operaciones.
+
+</details>
+
+<details>
+<summary><b>🔄 23. "Necesito visibilidad y cancelación del ciclo de vida de la tarea A2A en vivo"</b></summary>
+
+Sin visibilidad del ciclo de vida, los incidentes de tareas se vuelven difíciles de clasificar.
+
+**Cómo lo resuelve OmniRoute:**
+
+- Listado de tareas/filtrado por estado/habilidad con paginación
+- Profundización en metadatos, eventos y artefactos de tareas
+- Punto final de cancelación de tarea y acción de UI con confirmación
+
+</details>
+
+<details>
+<summary><b>🌊 24. "Necesito métricas de transmisión activas para la carga A2A"</b></summary>
+
+Los flujos de trabajo de streaming requieren información operativa sobre la simultaneidad y las conexiones en vivo.
+
+**Cómo lo resuelve OmniRoute:**
+
+- Contadores de flujo activos integrados en el estado A2A
+- Marca de tiempo de la última tarea y recuentos por estado
+- Tarjetas de tablero A2A para monitoreo de operaciones en tiempo real
+
+</details>
+
+<details>
+<summary><b>🪪 25. "Necesito descubrimiento de agente estándar para clientes"</b></summary>
+
+Los clientes y orquestadores externos necesitan metadatos legibles por máquina para la incorporación.
+
+**Cómo lo resuelve OmniRoute:**
+
+- Tarjeta de agente expuesta en `/.well-known/agent.json`
+- Capacidades y habilidades mostradas en la interfaz de usuario de gestión.
+- La API de estado A2A incluye metadatos de descubrimiento para la automatización
+
+</details>
+
+<details>
+<summary><b>🧭 26. "Necesito capacidad de descubrimiento de protocolo en la UX del producto"</b></summary>
+
+Si los usuarios no pueden descubrir las superficies de protocolo, la calidad de la adopción y el soporte disminuye.
+
+**Cómo lo resuelve OmniRoute:**
+
+- Entradas de la barra lateral para MCP y A2A
+- Pestaña Protocolos de la página del endpoint con inicio rápido y estado
+- Enlaces desde la descripción general a paneles de gestión dedicados
+
+</details>
+
+<details>
+<summary><b>🧪 27. "Necesito validación de protocolo de extremo a extremo con clientes reales"</b></summary>
+
+Las pruebas simuladas no son suficientes para validar la compatibilidad del protocolo antes del lanzamiento.
+
+**Cómo lo resuelve OmniRoute:**
+
+- Suite E2E que inicia la aplicación y utiliza transporte de cliente MCP SDK real
+- Pruebas de cliente A2A para descubrimiento, envío, transmisión, obtención y cancelación de flujos
+- Verificar las afirmaciones con las API de auditoría MCP y tareas A2A.
+
+</details>
+
+<details>
+<summary><b>📡 28. "Necesito observabilidad unificada en todas las interfaces"</b></summary>
+
+Dividir la observabilidad por protocolo crea puntos ciegos y MTTR más largos.
+
+**Cómo lo resuelve OmniRoute:**
+
+- Paneles/registros/análisis unificados en un solo producto
+- Salud + auditoría + solicitud de telemetría en capas OpenAI, MCP y A2A
+- API operativas para estado y automatización.
+
+</details>
+
+<details>
+<summary><b>💼 29. "Necesito un tiempo de ejecución para proxy + herramientas + orquestación de agentes"</b></summary>
+
+La ejecución de muchos servicios separados aumenta los costos operativos y los modos de falla.
+
+**Cómo lo resuelve OmniRoute:**
+
+- Proxy compatible con OpenAI, servidor MCP y servidor A2A en una sola pila
+- Autenticación compartida, resiliencia, almacenamiento de datos y observabilidad.
+- Modelo de política consistente en todas las superficies de interacción.
+
+</details>
+
+<details>
+<summary><b>🚀 30. "Necesito enviar flujos de trabajo agentes sin expansión de código adhesivo"</b></summary>
+
+Los equipos pierden velocidad al unir múltiples scripts y servicios ad hoc.
+
+**Cómo lo resuelve OmniRoute:**
+
+- Estrategia de endpoint unificada para clientes y agentes
+- UI de gestión de protocolos integradas y rutas de validación de humo
+- Fundamentos listos para producción (seguridad, registro, resiliencia, respaldo)
+
+</details>
+
+### Guías de ejemplo (casos de uso integrados)
+
+**Libro de estrategias A: maximizar la suscripción paga + copia de seguridad económica**
+
+```txt
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6
+  2. glm/glm-4.7
+  3. if/kimi-k2-thinking
+
+Monthly cost: $20 + small backup spend
+Outcome: higher quality, near-zero interruption
+```
+
+**Libro de estrategias B: pila de codificación de costo cero**
+
+```txt
+Combo: "free-forever"
+  1. gc/gemini-3-flash
+  2. if/kimi-k2-thinking
+  3. qw/qwen3-coder-plus
+
+Monthly cost: $0
+Outcome: stable free coding workflow
+```
+
+**Libro de estrategias C: cadena alternativa siempre disponible las 24 horas del día, los 7 días de la semana**
+
+```txt
+Combo: "always-on"
+  1. cc/claude-opus-4-6
+  2. cx/gpt-5.2-codex
+  3. glm/glm-4.7
+  4. minimax/MiniMax-M2.1
+  5. if/kimi-k2-thinking
+
+Outcome: deep fallback depth for deadline-critical workloads
+```
+
+**Libro de jugadas D: Operaciones del agente con MCP + A2A**
+
+```txt
+1) Start MCP transport (`omniroute --mcp`) for tool-driven operations
+2) Run A2A tasks via `message/send` and `message/stream`
+3) Observe via /dashboard/mcp and /dashboard/a2a
+4) Control incidents with resilience profile + task cancellation
+```
+
+---
+
 ## ⚡ Inicio Rápido
 
 **1. Instala globalmente:**
@@ -247,6 +779,34 @@ docker compose --profile cli up -d
 
 ---
 
+---
+
+## 🖥️
+
+> 🆕 **¡NUEVO!** OmniRoute ahora está disponible como **aplicación de escritorio nativa** para Windows, macOS y Linux.
+
+Ejecuta OmniRoute como una aplicación de escritorio autónoma — sin terminal, sin navegador, sin internet necesario para modelos locales. La app basada en Electron incluye:
+
+- 🖥️ **Ventana Nativa** — Ventana dedicada con integración en la bandeja del sistema
+- 🔄 **Inicio Automático** — Inicia OmniRoute al iniciar sesión
+- 🔔 **Notificaciones Nativas** — Recibe alertas sobre cuota o problemas de proveedores
+- ⚡ **Instalación con Un Clic** — NSIS (Windows), DMG (macOS), AppImage (Linux)
+- 🌐 **Modo Sin Conexión** — Funciona completamente offline con servidor incluido
+
+### Inicio Rápido
+
+```bash
+npm run electron:dev           # Modo desarrollo
+npm run electron:build         # Plataforma actual
+npm run electron:build:win     # Windows (.exe)
+npm run electron:build:mac     # macOS (.dmg)
+npm run electron:build:linux   # Linux (.AppImage)
+```
+
+📖 Documentación completa: [`electron/README.md`](electron/README.md)
+
+---
+
 ## 💰 Precios Resumidos
 
 | Tier               | Proveedor         | Costo                        | Reset de Cuota    | Mejor Para              |
@@ -272,67 +832,6 @@ docker compose --profile cli up -d
 
 ---
 
-## 🎯 Casos de Uso
-
-### Caso 1: "Tengo suscripción Claude Pro"
-
-**Problema:** La cuota expira sin usar, límites de tasa durante programación intensa
-
-```
-Combo: "maximize-claude"
-  1. cc/claude-opus-4-6        (usar suscripción al máximo)
-  2. glm/glm-4.7               (respaldo barato cuando la cuota se agota)
-  3. if/kimi-k2-thinking       (fallback de emergencia gratuito)
-
-Costo mensual: $20 (suscripción) + ~$5 (respaldo) = $25 total
-vs. $20 + chocar con límites = frustración
-```
-
-### Caso 2: "Quiero costo cero"
-
-**Problema:** No puede pagar suscripciones, necesita IA confiable para programar
-
-```
-Combo: "free-forever"
-  1. gc/gemini-3-flash         (180K gratis/mes)
-  2. if/kimi-k2-thinking       (ilimitado gratis)
-  3. qw/qwen3-coder-plus       (ilimitado gratis)
-
-Costo mensual: $0
-Calidad: Modelos listos para producción
-```
-
-### Caso 3: "Necesito programar 24/7, sin interrupciones"
-
-**Problema:** Plazos ajustados, no puede permitirse tiempo de inactividad
-
-```
-Combo: "always-on"
-  1. cc/claude-opus-4-6        (mejor calidad)
-  2. cx/gpt-5.2-codex          (segunda suscripción)
-  3. glm/glm-4.7               (barato, reset diario)
-  4. minimax/MiniMax-M2.1      (más barato, reset 5h)
-  5. if/kimi-k2-thinking       (gratuito ilimitado)
-
-Resultado: 5 capas de fallback = cero tiempo de inactividad
-```
-
-### Caso 4: "Quiero IA GRATUITA en OpenClaw"
-
-**Problema:** Necesita asistente de IA en apps de mensajería, completamente gratuito
-
-```
-Combo: "openclaw-free"
-  1. if/glm-4.7                (ilimitado gratis)
-  2. if/minimax-m2.1           (ilimitado gratis)
-  3. if/kimi-k2-thinking       (ilimitado gratis)
-
-Costo mensual: $0
-Acceso vía: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-```
-
----
-
 ## 💡 Características Principales
 
 ### 🧠 Enrutamiento e Inteligencia
@@ -348,6 +847,8 @@ Acceso vía: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 | 🧩 **Modelos Personalizados**          | Agrega cualquier ID de modelo a cualquier proveedor                             |
 | 🌐 **Enrutador Wildcard**              | Enruta patrones `provider/*` a cualquier proveedor dinámicamente                |
 | 🧠 **Presupuesto de Razonamiento**     | Modos passthrough, auto, custom y adaptativo para modelos de razonamiento       |
+| 🔀 **Model Aliases**                   | Auto-forward deprecated model IDs to current replacements (built-in + custom)   |
+| ⚡ **Background Degradation**          | Auto-route background tasks (titles, summaries) to cheaper models               |
 | 💬 **Inyección de System Prompt**      | System prompt global aplicado en todas las solicitudes                          |
 | 📄 **API Responses**                   | Soporte completo de la API Responses de OpenAI (`/v1/responses`) para Codex     |
 
@@ -364,15 +865,18 @@ Acceso vía: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 
 ### 🛡️ Resiliencia y Seguridad
 
-| Característica                     | Qué Hace                                                         |
-| ---------------------------------- | ---------------------------------------------------------------- |
-| 🔌 **Circuit Breaker**             | Auto-apertura/cierre por proveedor con umbrales configurables    |
-| 🛡️ **Anti-Thundering Herd**        | Mutex + semáforo rate-limit para proveedores con API key         |
-| 🧠 **Caché Semántico**             | Caché de dos niveles (firma + semántico) reduce costo y latencia |
-| ⚡ **Idempotencia de Solicitud**   | Ventana de dedup de 5s para solicitudes duplicadas               |
-| 🔒 **Spoofing de Fingerprint TLS** | Bypass de detección de bot vía TLS con wreq-js                   |
-| 🌐 **Filtrado de IP**              | Allowlist/blocklist para control de acceso a la API              |
-| 📊 **Rate Limits Editables**       | RPM, gap mínimo y concurrencia máxima configurables              |
+| Característica                     | Qué Hace                                                                     |
+| ---------------------------------- | ---------------------------------------------------------------------------- |
+| 🔌 **Circuit Breaker**             | Auto-apertura/cierre por proveedor con umbrales configurables                |
+| 🎯 **Endpoint-Aware Models**       | Custom models declare supported endpoints + API format                       |
+| 🛡️ **Anti-Thundering Herd**        | Mutex + semáforo rate-limit para proveedores con API key                     |
+| 🧠 **Caché Semántico**             | Caché de dos niveles (firma + semántico) reduce costo y latencia             |
+| ⚡ **Idempotencia de Solicitud**   | Ventana de dedup de 5s para solicitudes duplicadas                           |
+| 🔒 **Spoofing de Fingerprint TLS** | Bypass de detección de bot vía TLS con wreq-js                               |
+| 🌐 **Filtrado de IP**              | Allowlist/blocklist para control de acceso a la API                          |
+| 📊 **Rate Limits Editables**       | RPM, gap mínimo y concurrencia máxima configurables                          |
+| 💾 **Rate Limit Persistence**      | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
+| 🔄 **Token Refresh Resilience**    | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt       |
 
 ### 📊 Observabilidad y Analytics
 
@@ -472,6 +976,27 @@ Traducción transparente entre formatos:
 
 </details>
 
+## 🧪 Evaluaciones (Evals)
+
+OmniRoute incluye un framework de evaluación integrado para probar la calidad de respuestas de LLM contra un conjunto golden. Accede vía **Analytics → Evals** en el dashboard.
+
+### Conjunto Golden Integrado
+
+El "OmniRoute Golden Set" precargado contiene 10 casos de prueba que cubren:
+
+- Saludos, matemáticas, geografía, generación de código
+- Conformidad de formato JSON, traducción, markdown
+- Rechazo de seguridad (contenido dañino), conteo, lógica booleana
+
+### Estrategias de Evaluación
+
+| Estrategia | Descripción                                          | Ejemplo                          |
+| ---------- | ---------------------------------------------------- | -------------------------------- |
+| `exact`    | La salida debe coincidir exactamente                 | `"4"`                            |
+| `contains` | La salida debe contener subcadena (case-insensitive) | `"Paris"`                        |
+| `regex`    | La salida debe coincidir con el patrón regex         | `"1.*2.*3"`                      |
+| `custom`   | Función JS personalizada retorna true/false          | `(output) => output.length > 10` |
+
 ---
 
 ## 📖 Guía de Configuración
@@ -754,97 +1279,6 @@ Configuración → Configuración de API:
 
 ---
 
-## 📊 Modelos Disponibles
-
-<details>
-<summary><b>Ver todos los modelos disponibles</b></summary>
-
-**Claude Code (`cc/`)** - Pro/Max:
-
-- `cc/claude-opus-4-6`
-- `cc/claude-sonnet-4-5-20250929`
-- `cc/claude-haiku-4-5-20251001`
-
-**Codex (`cx/`)** - Plus/Pro:
-
-- `cx/gpt-5.2-codex`
-- `cx/gpt-5.1-codex-max`
-
-**Gemini CLI (`gc/`)** - GRATUITO:
-
-- `gc/gemini-3-flash-preview`
-- `gc/gemini-2.5-pro`
-
-**GitHub Copilot (`gh/`)**:
-
-- `gh/gpt-5`
-- `gh/claude-4.5-sonnet`
-
-**NVIDIA NIM (`nvidia/`)** - Créditos GRATUITOS:
-
-- `nvidia/llama-3.3-70b-instruct`
-- `nvidia/mistral-7b-instruct`
-- 50+ más modelos en [build.nvidia.com](https://build.nvidia.com)
-
-**GLM (`glm/`)** - $0.6/1M:
-
-- `glm/glm-4.7`
-
-**MiniMax (`minimax/`)** - $0.2/1M:
-
-- `minimax/MiniMax-M2.1`
-
-**iFlow (`if/`)** - GRATUITO:
-
-- `if/kimi-k2-thinking`
-- `if/qwen3-coder-plus`
-- `if/deepseek-r1`
-- `if/glm-4.7`
-- `if/minimax-m2`
-
-**Qwen (`qw/`)** - GRATUITO:
-
-- `qw/qwen3-coder-plus`
-- `qw/qwen3-coder-flash`
-
-**Kiro (`kr/`)** - GRATUITO:
-
-- `kr/claude-sonnet-4.5`
-- `kr/claude-haiku-4.5`
-
-**OpenRouter (`or/`)** - 100+ modelos:
-
-- `or/anthropic/claude-4-sonnet`
-- `or/google/gemini-2.5-pro`
-- Cualquier modelo de [openrouter.ai/models](https://openrouter.ai/models)
-
-</details>
-
----
-
-## 🧪 Evaluaciones (Evals)
-
-OmniRoute incluye un framework de evaluación integrado para probar la calidad de respuestas de LLM contra un conjunto golden. Accede vía **Analytics → Evals** en el dashboard.
-
-### Conjunto Golden Integrado
-
-El "OmniRoute Golden Set" precargado contiene 10 casos de prueba que cubren:
-
-- Saludos, matemáticas, geografía, generación de código
-- Conformidad de formato JSON, traducción, markdown
-- Rechazo de seguridad (contenido dañino), conteo, lógica booleana
-
-### Estrategias de Evaluación
-
-| Estrategia | Descripción                                          | Ejemplo                          |
-| ---------- | ---------------------------------------------------- | -------------------------------- |
-| `exact`    | La salida debe coincidir exactamente                 | `"4"`                            |
-| `contains` | La salida debe contener subcadena (case-insensitive) | `"Paris"`                        |
-| `regex`    | La salida debe coincidir con el patrón regex         | `"1.*2.*3"`                      |
-| `custom`   | Función JS personalizada retorna true/false          | `(output) => output.length > 10` |
-
----
-
 ## 🐛 Solución de Problemas
 
 <details>
@@ -900,7 +1334,7 @@ El "OmniRoute Golden Set" precargado contiene 10 casos de prueba que cubren:
 
 ---
 
-## 🛠️ Stack Tecnológico
+## 🛠️
 
 - **Runtime**: Node.js 20+
 - **Lenguaje**: TypeScript 5.9 — **100% TypeScript** en `src/` y `open-sse/` (v1.0.6)
@@ -931,17 +1365,7 @@ El "OmniRoute Golden Set" precargado contiene 10 casos de prueba que cubren:
 
 ---
 
-## 📧 Soporte
-
-> 💬 **¡Únete a la comunidad!** [Grupo WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obtén ayuda, comparte consejos y mantente al día.
-
-- **Website**: [omniroute.online](https://omniroute.online)
-- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **WhatsApp**: [Grupo de la Comunidad](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Proyecto Original**: [9router por decolua](https://github.com/decolua/9router)
-
----
+## 🗺️
 
 ## 👥 Contribuidores
 

README.fr.md

@@ -104,12 +104,41 @@ _Connectez n'importe quel IDE ou outil CLI alimenté par l'IA via OmniRoute —
 
 [🌐 Site web](https://omniroute.online) • [🚀 Démarrage rapide](#-démarrage-rapide) • [💡 Fonctionnalités](#-fonctionnalités-principales) • [📖 Docs](#-documentation) • [💰 Tarifs](#-aperçu-des-tarifs)
 
-🌐 **Disponible en :** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
+🌐 **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)
 
 </div>
 
 ---
 
+## 🖼️
+
+<div align="center">
+  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute" width="800"/>
+</div>
+
+---
+
+## 📸
+
+<details>
+<summary><b>...</b></summary>
+
+| #     | #                                        |
+| ----- | ---------------------------------------- |
+| **1** | ![1](docs/screenshots/01-providers.png)  |
+| **2** | ![2](docs/screenshots/02-combos.png)     |
+| **3** | ![3](docs/screenshots/03-analytics.png)  |
+| **4** | ![4](docs/screenshots/04-health.png)     |
+| **5** | ![5](docs/screenshots/05-translator.png) |
+| **6** | ![6](docs/screenshots/06-settings.png)   |
+| **7** | ![7](docs/screenshots/07-cli-tools.png)  |
+| **8** | ![8](docs/screenshots/08-usage.png)      |
+| **9** | ![9](docs/screenshots/09-endpoint.png)   |
+
+</details>
+
+---
+
 ## 🤔 Pourquoi OmniRoute ?
 
 **Arrêtez de gaspiller de l'argent et de vous heurter aux limites :**
@@ -128,6 +157,18 @@ _Connectez n'importe quel IDE ou outil CLI alimenté par l'IA via OmniRoute —
 
 ---
 
+## 📧 Support
+
+> 💬 **Rejoignez notre communauté !** [Groupe WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obtenez de l'aide, partagez des astuces et restez informé.
+
+- **Site web** : [omniroute.online](https://omniroute.online)
+- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
+- **Issues** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **WhatsApp** : [Groupe communautaire](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+- **Projet original** : [9router par decolua](https://github.com/decolua/9router)
+
+---
+
 ## 🔄 Comment ça fonctionne
 
 ```
@@ -157,6 +198,497 @@ Résultat : Ne jamais arrêter de coder, coût minimal
 
 ---
 
+## 🎯 Ce qu'OmniRoute résout : 30 problèmes réels et cas d'utilisation
+
+> **Tous les développeurs utilisant des outils d'IA sont confrontés quotidiennement à ces problèmes.** OmniRoute a été conçu pour tous les résoudre : des dépassements de coûts aux blocages régionaux, des flux OAuth interrompus aux opérations de protocole et à l'observabilité de l'entreprise.
+
+<details>
+<summary><b>💸 1. "Je paie un abonnement coûteux mais je suis quand même interrompu par des limites" </b></summary>
+
+Les développeurs paient entre 20 et 200 $/mois pour Claude Pro, Codex Pro ou GitHub Copilot. Même payant, le quota est plafonné : 5 heures d'utilisation, limites hebdomadaires ou limites de tarif à la minute. En cours de session de codage, le fournisseur ne répond plus et le développeur perd en fluidité et en productivité.
+
+**Comment OmniRoute le résout :**
+
+- **Smart 4-Tier Fallback** — Si le quota d'abonnement est épuisé, redirige automatiquement vers la clé API → Pas cher → Gratuit sans intervention manuelle
+- **Suivi des quotas en temps réel** — Affiche la consommation de jetons en temps réel avec un compte à rebours réinitialisé (5 h, quotidiennement, hebdomadairement)
+- **Support multi-comptes** — Plusieurs comptes par fournisseur avec tourniquet automatique — lorsqu'un compte est épuisé, passe au suivant
+- **Combos personnalisés** — Chaînes de secours personnalisables avec 6 stratégies d'équilibrage (remplir en premier, round-robin, P2C, aléatoire, les moins utilisées, optimisées en termes de coûts)
+- **Codex Business Quotas** — Surveillance des quotas d'espace de travail Business/Équipe directement dans le tableau de bord
+
+</details>
+
+<details>
+<summary><b>🔌 2. "Je dois utiliser plusieurs fournisseurs mais chacun a une API différente" </b></summary>
+
+OpenAI utilise un format, Claude (Anthropic) en utilise un autre, Gemini encore un autre. Si un développeur souhaite tester des modèles de différents fournisseurs ou utiliser un modèle de secours entre eux, il doit reconfigurer les SDK, modifier les points de terminaison et gérer les formats incompatibles. Les fournisseurs personnalisés (FriendLI, NIM) ont des points de terminaison de modèle non standard.
+
+**Comment OmniRoute le résout :**
+
+- **Point de terminaison unifié** : un seul `http://localhost:20128/v1` sert de proxy pour les plus de 36 fournisseurs.
+- **Traduction de format** — Automatique et transparente : OpenAI ↔ Claude ↔ Gemini ↔ API Responses
+- **Response Sanitization** — Supprime les champs non standard (`x_groq`, `usage_breakdown`, `service_tier`) qui cassent OpenAI SDK v1.83+
+- **Role Normalization** — Convertit `developer` → `system` pour les fournisseurs non OpenAI ; `system` → `user` pour GLM/ERNIE
+- **Think Tag Extraction** — Extrait les blocs `<think>` de modèles comme DeepSeek R1 dans un `reasoning_content` standardisé.
+- **Sortie structurée pour Gemini** — Conversion automatique `json_schema` → `responseMimeType`/`responseSchema`
+- **`stream` est par défaut `false`** — S'aligne sur les spécifications OpenAI, évitant ainsi le SSE inattendu dans les SDK Python/Rust/Go
+
+</details>
+
+<details>
+<summary><b>🌐 3. "Mon fournisseur d'IA bloque ma région/pays" </b></summary>
+
+Des fournisseurs comme OpenAI/Codex bloquent l’accès depuis certaines régions géographiques. Les utilisateurs obtiennent des erreurs telles que `unsupported_country_region_territory` lors des connexions OAuth et API. Ceci est particulièrement frustrant pour les développeurs des pays en développement.
+
+**Comment OmniRoute le résout :**
+
+- **Configuration proxy à 3 niveaux** — Proxy configurable à 3 niveaux : global (tout le trafic), par fournisseur (un seul fournisseur) et par connexion/clé
+- **Badges proxy à code couleur** — Indicateurs visuels : 🟢 proxy global, 🟡 proxy fournisseur, 🔵 proxy de connexion, affichant toujours l'adresse IP
+- **Échange de jetons OAuth via proxy** — Le flux OAuth passe également par le proxy, résolvant `unsupported_country_region_territory`
+- **Tests de connexion via proxy** — Les tests de connexion utilisent le proxy configuré (plus de contournement direct)
+- **Support SOCKS5** — Prise en charge complète du proxy SOCKS5 pour le routage sortant
+- **TLS Fingerprint Spoofing** — Empreinte digitale TLS de type navigateur via `wreq-js` pour contourner la détection des robots
+
+</details>
+
+<details>
+<summary><b>🆓 4. "Je veux utiliser l'IA pour coder mais je n'ai pas d'argent"</b></summary>
+
+Tout le monde ne peut pas payer entre 20 et 200 $/mois pour des abonnements à l’IA. Les étudiants, les développeurs des pays émergents, les amateurs et les indépendants doivent avoir accès à des modèles de qualité à un coût nul.
+
+**Comment OmniRoute le résout :**
+
+- **Fournisseurs gratuits intégrés** — Prise en charge native des fournisseurs 100 % gratuits : iFlow (8 modèles illimités), Qwen (3 modèles illimités), Kiro (Claude gratuit), Gemini CLI (180 000 /mois gratuits)
+- **Combos gratuits uniquement** — Chaîne `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/mois sans temps d'arrêt
+- **Crédits gratuits NVIDIA NIM** — 1 000 crédits gratuits intégrés
+- **Stratégie d'optimisation des coûts** — Stratégie de routage qui choisit automatiquement le fournisseur disponible le moins cher
+
+</details>
+
+<details>
+<summary><b>🔒 5. "Je dois protéger ma passerelle IA contre les accès non autorisés" </b></summary>
+
+Lors de l'exposition d'une passerelle IA au réseau (LAN, VPS, Docker), toute personne possédant l'adresse peut consommer les jetons/quota du développeur. Sans protection, les API sont vulnérables aux utilisations abusives, aux injections rapides et aux abus.
+
+**Comment OmniRoute le résout :**
+
+- **Gestion des clés API** — Génération, rotation et portée par fournisseur avec une page `/dashboard/api-manager` dédiée
+- **Autorisations au niveau du modèle** : restreindre les clés API à des modèles spécifiques (`openai/*`, modèles génériques), avec la bascule Autoriser tout/Restreindre
+- **API Endpoint Protection** – exige une clé pour `/v1/models` et bloque des fournisseurs spécifiques de la liste
+- **Auth Guard + Protection CSRF** — Toutes les routes du tableau de bord protégées avec le middleware `withAuth` + les jetons CSRF
+- **Rate Limiter** — Limitation du débit par IP avec fenêtres configurables
+- **Filtrage IP** – Liste autorisée/liste de blocage pour le contrôle d'accès
+- **Prompt Injection Guard** — Nettoyage contre les modèles d'invite malveillants
+- **Chiffrement AES-256-GCM** — Informations d'identification chiffrées au repos
+
+</details>
+
+<details>
+<summary><b>🛑 6. "Mon fournisseur est tombé en panne et j'ai perdu mon flux de codage"</b></summary>
+
+Les fournisseurs d’IA peuvent devenir instables, renvoyer des erreurs 5xx ou atteindre des limites de débit temporaires. Si un développeur dépend d'un seul fournisseur, il est interrompu. Sans disjoncteurs, des tentatives répétées peuvent faire planter l’application.
+
+**Comment OmniRoute le résout :**
+
+- **Disjoncteur par fournisseur** — Ouverture/fermeture automatique avec seuils et temps de recharge configurables (Fermé/Ouvert/Semi-ouvert)
+- **Exponential Backoff** — Délais progressifs entre les tentatives
+- **Anti-Thundering Herd** — Protection mutex + sémaphore contre les tempêtes de nouvelles tentatives simultanées
+- **Chaînes de secours combinées** — Si le fournisseur principal échoue, passe automatiquement à travers la chaîne sans intervention
+- **Combo Circuit Breaker** – Désactive automatiquement les fournisseurs défaillants au sein d'une chaîne combo
+- **Tableau de bord de santé** — Surveillance de la disponibilité, états des disjoncteurs, verrouillages, statistiques du cache, latence p50/p95/p99
+
+</details>
+
+<details>
+<summary><b>🔧 7. "La configuration de chaque outil d'IA est fastidieuse et répétitive"</b></summary>
+
+Les développeurs utilisent Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Chaque outil nécessite une configuration différente (point de terminaison API, clé, modèle). La reconfiguration lors du changement de fournisseur ou de modèle est une perte de temps.
+
+**Comment OmniRoute le résout :**
+
+- **CLI Tools Dashboard** — Page dédiée avec configuration en un clic pour Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
+- **GitHub Copilot Config Generator** — Génère `chatLanguageModels.json` pour VS Code avec sélection groupée de modèles
+- **Assistant d'intégration** — Configuration guidée en 4 étapes pour les nouveaux utilisateurs
+- **Un point de terminaison, tous les modèles** – Configurez `http://localhost:20128/v1` une fois, accédez à plus de 36 fournisseurs
+
+</details>
+
+<details>
+<summary><b>🔑 8. "Gérer les jetons OAuth de plusieurs fournisseurs est un enfer"</b></summary>
+
+Claude Code, Codex, Gemini CLI, Copilot — tous utilisent OAuth 2.0 avec des jetons expirant. Les développeurs doivent se réauthentifier constamment, gérer `client_secret is missing`, `redirect_uri_mismatch` et les pannes sur les serveurs distants. OAuth sur LAN/VPS est particulièrement problématique.
+
+**Comment OmniRoute le résout :**
+
+- **Actualisation automatique des jetons** : les jetons OAuth sont actualisés en arrière-plan avant leur expiration.
+- **OAuth 2.0 (PKCE) intégré** — Flux automatique pour Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow
+- **Multi-Account OAuth** — Plusieurs comptes par fournisseur via l'extraction de jetons JWT/ID
+- **OAuth LAN/Remote Fix** — Détection IP privée pour `redirect_uri` + mode URL manuel pour les serveurs distants
+- **OAuth derrière Nginx** — Utilise `window.location.origin` pour la compatibilité du proxy inverse
+- **Guide OAuth à distance** — Guide étape par étape pour les informations d'identification Google Cloud sur VPS/Docker
+
+</details>
+
+<details>
+<summary><b>📊 9. "Je ne sais pas combien je dépense ni où" </b></summary>
+
+Les développeurs utilisent plusieurs fournisseurs payants mais n'ont pas de vue unifiée des dépenses. Chaque fournisseur dispose de son propre tableau de bord de facturation, mais il n'existe pas de vue consolidée. Les coûts inattendus peuvent s’accumuler.
+
+**Comment OmniRoute le résout :**
+
+- **Cost Analytics Dashboard** — Suivi des coûts par jeton et gestion du budget par fournisseur
+- **Limites budgétaires par niveau** — Plafond de dépenses par niveau qui déclenche un repli automatique
+- **Configuration de tarification par modèle** — Prix configurables par modèle
+- **Statistiques d'utilisation par clé API** — Nombre de demandes et horodatage de la dernière utilisation par clé
+- **Tableau de bord Analytics** — Cartes statistiques, tableau d'utilisation du modèle, tableau des fournisseurs avec taux de réussite et latence
+
+</details>
+
+<details>
+<summary><b>🐛 10. "Je ne peux pas diagnostiquer les erreurs et les problèmes dans les appels IA" </b></summary>
+
+Lorsqu'un appel échoue, le développeur ne sait pas s'il s'agit d'une limite de débit, d'un jeton expiré, d'un format incorrect ou d'une erreur du fournisseur. Journaux fragmentés sur différents terminaux. Sans observabilité, le débogage est un essai et une erreur.
+
+**Comment OmniRoute le résout :**
+
+- **Tableau de bord des journaux unifiés** — 4 onglets : journaux de requêtes, journaux proxy, journaux d'audit, console
+- **Console Log Viewer** — Visualiseur de style terminal en temps réel avec niveaux de code couleur, défilement automatique, recherche, filtre
+- **Journaux du proxy SQLite** — Journaux persistants qui survivent aux redémarrages du serveur
+- **Translator Playground** — 4 modes de débogage : Playground (traduction de format), Chat Tester (aller-retour), Test Bench (batch), Live Monitor (temps réel)
+- **Demande de télémétrie** — latence p50/p95/p99 + traçage X-Request-Id
+- **Journalisation basée sur des fichiers avec rotation** — L'intercepteur de console capture tout dans le journal JSON avec une rotation basée sur la taille
+
+</details>
+
+<details>
+<summary><b>🏗️ 11. "Le déploiement et la maintenance de la passerelle sont complexes"</b></summary>
+
+L'installation, la configuration et la maintenance d'un proxy IA dans différents environnements (local, VPS, Docker, cloud) demandent beaucoup de main-d'œuvre. Des problèmes tels que les chemins codés en dur, `EACCES` sur les répertoires, les conflits de ports et les versions multiplateformes ajoutent des frictions.
+
+**Comment OmniRoute le résout :**
+
+- **Installation globale npm** — `npm install -g omniroute && omniroute` — terminée
+- **Docker Multi-Platform** — AMD64 + ARM64 natif (Apple Silicon, AWS Graviton, Raspberry Pi)
+- **Profils Docker Compose** — `base` (pas d'outils CLI) et `cli` (avec Claude Code, Codex, OpenClaw)
+- **Electron Desktop App** — Application native pour Windows/macOS/Linux avec barre d'état système, démarrage automatique et mode hors ligne
+- **Mode Split-Port** — API et tableau de bord sur des ports séparés pour des scénarios avancés (proxy inverse, réseau de conteneurs)
+- **Cloud Sync** – Configurez la synchronisation entre les appareils via Cloudflare Workers
+- **Sauvegardes DB** — Sauvegarde, restauration, exportation et importation automatiques de tous les paramètres
+
+</details>
+
+<details>
+<summary><b>🌍 12. "L'interface est uniquement en anglais et mon équipe ne parle pas anglais" </b></summary>
+
+Les équipes des pays non anglophones, notamment en Amérique latine, en Asie et en Europe, ont du mal à utiliser des interfaces uniquement en anglais. Les barrières linguistiques réduisent l’adoption et augmentent les erreurs de configuration.
+
+**Comment OmniRoute le résout :**
+
+- **Tableau de bord i18n — 30 langues** — Plus de 500 touches traduites, dont arabe, bulgare, danois, allemand, espagnol, finnois, français, hébreu, hindi, hongrois, indonésien, italien, japonais, coréen, malais, néerlandais, norvégien, polonais, portugais (PT/BR), roumain, russe, slovaque, suédois, thaï, ukrainien, vietnamien, chinois, philippin, anglais.
+- **Support RTL** — Prise en charge de droite à gauche pour l'arabe et l'hébreu
+- ** README multilingues ** — 30 traductions complètes de la documentation
+- **Sélecteur de langue** — Icône de globe dans l'en-tête pour une commutation en temps réel
+
+</details>
+
+<details>
+<summary><b>🔄 13. "J'ai besoin de plus que du chat : j'ai besoin d'intégrations, d'images, d'audio" </b></summary>
+
+L'IA ne se limite pas à la réalisation de discussions. Les développeurs doivent générer des images, transcrire l'audio, créer des intégrations pour RAG, reclasser les documents et modérer le contenu. Chaque API a un point de terminaison et un format différents.
+
+**Comment OmniRoute le résout :**
+
+- **Embeddings** — `/v1/embeddings` avec 6 fournisseurs et plus de 9 modèles
+- **Génération d'images** — `/v1/images/generations` avec 10 fournisseurs et plus de 20 modèles (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)
+- **Texte vers vidéo** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) et SD WebUI
+- **Texte en musique** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)
+- **Transcription audio** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3
+- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, + fournisseurs existants
+- **Modérations** — `/v1/moderations` — Contrôles de sécurité du contenu
+- **Reclassement** — `/v1/rerank` — Reclassement de la pertinence du document
+- **API Réponses** — Prise en charge complète de `/v1/responses` pour le Codex
+
+</details>
+
+<details>
+<summary><b>🧪 14. "Je n'ai aucun moyen de tester et de comparer la qualité des modèles" </b></summary>
+
+Les développeurs veulent savoir quel modèle convient le mieux à leur cas d'utilisation (code, traduction, raisonnement) mais la comparaison manuelle est lente. Il n’existe aucun outil d’évaluation intégré.
+
+**Comment OmniRoute le résout :**
+
+- **Évaluations LLM** — Tests Golden Set avec 10 cas préchargés couvrant les salutations, les mathématiques, la géographie, la génération de code, la conformité JSON, la traduction, la démarque, le refus de sécurité
+- **4 stratégies de correspondance** — `exact`, `contains`, `regex`, `custom` (fonction JS)
+- **Banc de test Translator Playground** — Tests par lots avec plusieurs entrées et sorties attendues, comparaison entre fournisseurs
+- **Chat Tester** — Aller-retour complet avec rendu de réponse visuelle
+- **Live Monitor** — Flux en temps réel de toutes les requêtes transitant par le proxy
+
+</details>
+
+<details>
+<summary><b>📈 15. "J'ai besoin d'évoluer sans perdre en performances"</b></summary>
+
+À mesure que le volume de demandes augmente, sans mettre en cache les mêmes questions, cela génère des coûts en double. Sans idempotence, les demandes en double gaspillent le traitement. Les limites tarifaires par fournisseur doivent être respectées.
+
+**Comment OmniRoute le résout :**
+
+- **Cache sémantique** — Le cache à deux niveaux (signature + sémantique) réduit les coûts et la latence
+- **Request Idempotency** — Fenêtre de déduplication de 5 s pour des requêtes identiques
+- **Détection de limite de débit** — RPM par fournisseur, écart minimum et suivi simultané maximum
+- **Limites de débit modifiables** — Valeurs par défaut configurables dans Paramètres → Résilience avec persistance
+- **Cache de validation de clé API** — Cache à 3 niveaux pour les performances de production
+- **Tableau de bord de santé avec télémétrie** — latence p50/p95/p99, statistiques de cache, disponibilité
+
+</details>
+
+<details>
+<summary><b>🤖 16. "Je souhaite contrôler le comportement du modèle à l'échelle mondiale" </b></summary>
+
+Les développeurs qui souhaitent que toutes les réponses soient dans une langue spécifique, avec un ton spécifique, ou qui souhaitent limiter les jetons de raisonnement. Configurer cela dans chaque outil/demande n’est pas pratique.
+
+**Comment OmniRoute le résout :**
+
+- **Injection d'invite système** — Invite globale appliquée à toutes les requêtes
+- **Thinking Budget Validation** — Contrôle d'allocation de jetons de raisonnement par requête (passthrough, automatique, personnalisé, adaptatif)
+- **6 Stratégies de routage** – Stratégies globales qui déterminent la façon dont les demandes sont distribuées
+- **Wildcard Router** — Les modèles `provider/*` sont acheminés dynamiquement vers n'importe quel fournisseur.
+- **Combo Enable/Disable Toggle** — Basculez les combos directement depuis le tableau de bord
+- **Provider Toggle** — Activer/désactiver toutes les connexions pour un fournisseur en un seul clic
+- **Fournisseurs bloqués** — Exclure des fournisseurs spécifiques de la liste `/v1/models`
+
+</details>
+
+<details>
+<summary><b>🧰 17. "J'ai besoin d'outils MCP en tant que fonctionnalités de produit de première classe" </b></summary>
+
+De nombreuses passerelles IA exposent MCP uniquement en tant que détail d'implémentation caché. Les équipes ont besoin d’une couche opérationnelle visible et gérable.
+
+**Comment OmniRoute le résout :**
+
+- MCP apparaît dans l'onglet de navigation du tableau de bord et de protocole de point de terminaison
+- Page de gestion MCP dédiée avec processus, outils, portées et audit
+- Démarrage rapide intégré pour `omniroute --mcp` et intégration du client
+
+</details>
+
+<details>
+<summary><b>🧠 18. "J'ai besoin d'une orchestration A2A avec des chemins de tâches de synchronisation + flux" </b></summary>
+
+Les flux de travail des agents nécessitent à la fois des réponses directes et une exécution en continu de longue durée avec contrôle du cycle de vie.
+
+**Comment OmniRoute le résout :**
+
+- Point de terminaison A2A JSON-RPC (`POST /a2a`) avec `message/send` et `message/stream`
+- Streaming SSE avec propagation de l'état terminal
+- API de cycle de vie des tâches pour `tasks/get` et `tasks/cancel`
+
+</details>
+
+<details>
+<summary><b>🛰️ 19. "J'ai besoin d'un véritable état de santé du processus MCP, et non d'un état deviné" </b></summary>
+
+Les équipes opérationnelles doivent savoir si MCP est réellement actif, et pas seulement si une API est accessible.
+
+**Comment OmniRoute le résout :**
+
+- Fichier de battement de cœur d'exécution avec PID, horodatages, transport, nombre d'outils et mode de portée
+- API de statut MCP combinant battement de coeur + activité récente
+- Cartes d'état de l'interface utilisateur pour la fraîcheur des processus/disponibilité/battement de cœur
+
+</details>
+
+<details>
+<summary><b>📋 20. "J'ai besoin d'une exécution vérifiable de l'outil MCP" </b></summary>
+
+Lorsque les outils modifient la configuration ou déclenchent des actions opérationnelles, les équipes ont besoin d'une traçabilité médico-légale.
+
+**Comment OmniRoute le résout :**
+
+- Journalisation d'audit basée sur SQLite pour les appels d'outils MCP
+- Filtres par outil, succès/échec, clé API et pagination
+- Tableau d'audit du tableau de bord + points de terminaison de statistiques pour l'automatisation
+
+</details>
+
+<details>
+<summary><b>🔐 21. "J'ai besoin d'autorisations MCP limitées par intégration" </b></summary>
+
+Différents clients doivent avoir le moindre privilège d’accès aux catégories d’outils.
+
+**Comment OmniRoute le résout :**
+
+- 9 étendues MCP granulaires pour un accès contrôlé aux outils
+- Application de la portée et visibilité dans l'interface utilisateur de gestion MCP
+- Posture par défaut sûre pour les outils opérationnels
+
+</details>
+
+<details>
+<summary><b>⚙️ 22. "J'ai besoin de contrôles opérationnels sans redéploiement"</b></summary>
+
+Les équipes ont besoin de changements d'exécution rapides lors d'incidents ou d'événements de coûts.
+
+**Comment OmniRoute le résout :**
+
+- Activer le combo de commutation directement depuis le tableau de bord MCP
+- Appliquer des profils de résilience à partir de packs de politiques prédéfinis
+- Réinitialiser l'état du disjoncteur à partir du même panneau de commande
+
+</details>
+
+<details>
+<summary><b>🔄 23. "J'ai besoin d'une visibilité et d'une annulation en direct du cycle de vie des tâches A2A" </b></summary>
+
+Sans visibilité sur le cycle de vie, les incidents de tâches deviennent difficiles à trier.
+
+**Comment OmniRoute le résout :**
+
+- Liste des tâches/filtrage par état/compétence avec pagination
+- Analyse approfondie des métadonnées, des événements et des artefacts des tâches
+- Point de terminaison d'annulation de tâche et action de l'interface utilisateur avec confirmation
+
+</details>
+
+<details>
+<summary><b>🌊 24. "J'ai besoin de métriques de flux actif pour la charge A2A" </b></summary>
+
+Les flux de travail de streaming nécessitent une vision opérationnelle de la concurrence et des connexions en direct.
+
+**Comment OmniRoute le résout :**
+
+- Compteurs de flux actifs intégrés au statut A2A
+- Horodatage de la dernière tâche et nombre par état
+- Cartes de tableau de bord A2A pour la surveillance des opérations en temps réel
+
+</details>
+
+<details>
+<summary><b>🪪 25. "J'ai besoin d'une découverte d'agent standard pour les clients" </b></summary>
+
+Les clients et orchestrateurs externes ont besoin de métadonnées lisibles par machine pour l'intégration.
+
+**Comment OmniRoute le résout :**
+
+- Carte d'agent exposée à `/.well-known/agent.json`
+- Capacités et compétences affichées dans l'interface utilisateur de gestion
+- L'API de statut A2A inclut des métadonnées de découverte pour l'automatisation
+
+</details>
+
+<details>
+<summary><b>🧭 26. "J'ai besoin de la possibilité de découvrir le protocole dans le produit UX"</b></summary>
+
+Si les utilisateurs ne peuvent pas découvrir les surfaces de protocole, l’adoption et la qualité du support chutent.
+
+**Comment OmniRoute le résout :**
+
+- Entrées de la barre latérale pour MCP et A2A
+- Onglet Protocoles de la page du point de terminaison avec démarrage rapide et état
+- Liens depuis l'aperçu vers les tableaux de bord de gestion dédiés
+
+</details>
+
+<details>
+<summary><b>🧪 27. "J'ai besoin d'une validation de protocole de bout en bout avec de vrais clients"</b></summary>
+
+Les tests simulés ne suffisent pas pour valider la compatibilité des protocoles avant la publication.
+
+**Comment OmniRoute le résout :**
+
+- Suite E2E qui démarre l'application et utilise un véritable transport client MCP SDK
+- Tests client A2A pour les flux de découverte, d'envoi, de streaming, d'obtention et d'annulation
+- Vérifier les assertions par rapport aux API d'audit MCP et de tâches A2A
+
+</details>
+
+<details>
+<summary><b>📡 28. "J'ai besoin d'une observabilité unifiée sur toutes les interfaces"</b></summary>
+
+Le fractionnement de l'observabilité par protocole crée des angles morts et un MTTR plus long.
+
+**Comment OmniRoute le résout :**
+
+- Tableaux de bord/journaux/analyses unifiés dans un seul produit
+- Santé + audit + télémétrie des demandes sur les couches OpenAI, MCP et A2A
+- API opérationnelles pour le statut et l'automatisation
+
+</details>
+
+<details>
+<summary><b>💼 29. "J'ai besoin d'un environnement d'exécution pour l'orchestration proxy + outils + agent" </b></summary>
+
+L’exécution de nombreux services distincts augmente les coûts opérationnels et les modes de défaillance.
+
+**Comment OmniRoute le résout :**
+
+- Proxy compatible OpenAI, serveur MCP et serveur A2A dans une seule pile
+- Authentification partagée, résilience, stockage de données et observabilité
+- Modèle de politique cohérent sur toutes les surfaces d'interaction
+
+</details>
+
+<details>
+<summary><b>🚀 30. "Je dois expédier des flux de travail agentiques sans prolifération de codes adhésifs" </b></summary>
+
+Les équipes perdent de la vitesse lors de l’assemblage de plusieurs services et scripts ad hoc.
+
+**Comment OmniRoute le résout :**
+
+- Stratégie de point de terminaison unifiée pour les clients et les agents
+- Interfaces utilisateur de gestion de protocole intégrées et chemins de validation de fumée
+- Bases prêtes pour la production (sécurité, journalisation, résilience, sauvegarde)
+
+</details>
+
+### Exemples de playbooks (cas d'utilisation intégrés)
+
+**Playbook A : Maximisez l'abonnement payant + sauvegarde bon marché**
+
+```txt
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6
+  2. glm/glm-4.7
+  3. if/kimi-k2-thinking
+
+Monthly cost: $20 + small backup spend
+Outcome: higher quality, near-zero interruption
+```
+
+**Playbook B : pile de codage à coût nul**
+
+```txt
+Combo: "free-forever"
+  1. gc/gemini-3-flash
+  2. if/kimi-k2-thinking
+  3. qw/qwen3-coder-plus
+
+Monthly cost: $0
+Outcome: stable free coding workflow
+```
+
+**Playbook C : chaîne de secours toujours active 24h/24 et 7j/7**
+
+```txt
+Combo: "always-on"
+  1. cc/claude-opus-4-6
+  2. cx/gpt-5.2-codex
+  3. glm/glm-4.7
+  4. minimax/MiniMax-M2.1
+  5. if/kimi-k2-thinking
+
+Outcome: deep fallback depth for deadline-critical workloads
+```
+
+**Playbook D : Opérations d'agent avec MCP + A2A**
+
+```txt
+1) Start MCP transport (`omniroute --mcp`) for tool-driven operations
+2) Run A2A tasks via `message/send` and `message/stream`
+3) Observe via /dashboard/mcp and /dashboard/a2a
+4) Control incidents with resilience profile + task cancellation
+```
+
+---
+
 ## ⚡ Démarrage rapide
 
 **1. Installer globalement :**
@@ -247,6 +779,32 @@ docker compose --profile cli up -d
 
 ---
 
+---
+
+## 🖥️
+
+> 🆕 **NOUVEAU !** OmniRoute est maintenant disponible en tant qu'**application de bureau native** pour Windows, macOS et Linux.
+
+Exécutez OmniRoute en tant qu'application de bureau autonome — sans terminal, sans navigateur, sans internet requis pour les modèles locaux.
+
+- 🖥️ **Fenêtre Native** — Fenêtre dédiée avec intégration dans la barre d'état système
+- 🔄 **Démarrage Automatique** — Lancez OmniRoute à la connexion système
+- 🔔 **Notifications Natives** — Alertes pour l'épuisement de quota ou les problèmes
+- ⚡ **Installation en Un Clic** — NSIS (Windows), DMG (macOS), AppImage (Linux)
+- 🌐 **Mode Hors Ligne** — Fonctionne entièrement hors ligne avec serveur intégré
+
+```bash
+npm run electron:dev           # Mode développement
+npm run electron:build         # Plateforme actuelle
+npm run electron:build:win     # Windows (.exe)
+npm run electron:build:mac     # macOS (.dmg)
+npm run electron:build:linux   # Linux (.AppImage)
+```
+
+📖 Documentation complète : [`electron/README.md`](electron/README.md)
+
+---
+
 ## 💰 Aperçu des tarifs
 
 | Tier              | Fournisseur       | Coût                       | Réinitialisation    | Idéal pour                    |
@@ -272,67 +830,6 @@ docker compose --profile cli up -d
 
 ---
 
-## 🎯 Cas d'utilisation
-
-### Cas 1 : « J'ai un abonnement Claude Pro »
-
-**Problème :** Le quota expire inutilisé, limites de débit pendant le codage intensif
-
-```
-Combo : "maximize-claude"
-  1. cc/claude-opus-4-6        (utiliser l'abonnement au maximum)
-  2. glm/glm-4.7               (backup économique quand le quota est épuisé)
-  3. if/kimi-k2-thinking       (fallback d'urgence gratuit)
-
-Coût mensuel : 20 $ (abonnement) + ~5 $ (backup) = 25 $ au total
-vs. 20 $ + atteindre les limites = frustration
-```
-
-### Cas 2 : « Je veux zéro coût »
-
-**Problème :** Impossible de payer des abonnements, besoin d'IA fiable pour coder
-
-```
-Combo : "free-forever"
-  1. gc/gemini-3-flash         (180K gratuits/mois)
-  2. if/kimi-k2-thinking       (illimité gratuit)
-  3. qw/qwen3-coder-plus       (illimité gratuit)
-
-Coût mensuel : 0 $
-Qualité : Modèles prêts pour la production
-```
-
-### Cas 3 : « Je dois coder 24/7, sans interruption »
-
-**Problème :** Délais serrés, ne peut pas se permettre de temps d'arrêt
-
-```
-Combo : "always-on"
-  1. cc/claude-opus-4-6        (meilleure qualité)
-  2. cx/gpt-5.2-codex          (deuxième abonnement)
-  3. glm/glm-4.7               (économique, reset quotidien)
-  4. minimax/MiniMax-M2.1      (le moins cher, reset 5h)
-  5. if/kimi-k2-thinking       (gratuit illimité)
-
-Résultat : 5 niveaux de fallback = zéro temps d'arrêt
-```
-
-### Cas 4 : « Je veux l'IA GRATUITE dans OpenClaw »
-
-**Problème :** Besoin d'assistant IA dans les apps de messagerie, entièrement gratuit
-
-```
-Combo : "openclaw-free"
-  1. if/glm-4.7                (illimité gratuit)
-  2. if/minimax-m2.1           (illimité gratuit)
-  3. if/kimi-k2-thinking       (illimité gratuit)
-
-Coût mensuel : 0 $
-Accès via : WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-```
-
----
-
 ## 💡 Fonctionnalités principales
 
 ### 🧠 Routage & Intelligence
@@ -348,6 +845,8 @@ Accès via : WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 | 🧩 **Modèles personnalisés**          | Ajoutez n'importe quel ID de modèle à n'importe quel fournisseur                |
 | 🌐 **Routeur wildcard**               | Routez les patterns `provider/*` vers n'importe quel fournisseur dynamiquement  |
 | 🧠 **Budget de raisonnement**         | Modes passthrough, auto, custom et adaptive pour les modèles de raisonnement    |
+| 🔀 **Model Aliases**                  | Auto-forward deprecated model IDs to current replacements (built-in + custom)   |
+| ⚡ **Background Degradation**         | Auto-route background tasks (titles, summaries) to cheaper models               |
 | 💬 **Injection System Prompt**        | System prompt global appliqué à toutes les requêtes                             |
 | 📄 **API Responses**                  | Support complet de l'API Responses d'OpenAI (`/v1/responses`) pour Codex        |
 
@@ -364,15 +863,18 @@ Accès via : WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 
 ### 🛡️ Résilience & Sécurité
 
-| Fonctionnalité                  | Ce qu'elle fait                                                      |
-| ------------------------------- | -------------------------------------------------------------------- |
-| 🔌 **Circuit Breaker**          | Ouverture/fermeture auto par fournisseur avec seuils configurables   |
-| 🛡️ **Anti-Thundering Herd**     | Mutex + sémaphore de rate-limit pour les fournisseurs avec clé API   |
-| 🧠 **Cache sémantique**         | Cache à deux niveaux (signature + sémantique) réduit coût et latence |
-| ⚡ **Idempotence des requêtes** | Fenêtre de dédup 5s pour les requêtes dupliquées                     |
-| 🔒 **Spoofing TLS Fingerprint** | Contournement de détection de bot via wreq-js                        |
-| 🌐 **Filtrage IP**              | Allowlist/blocklist pour le contrôle d'accès API                     |
-| 📊 **Rate limits éditables**    | RPM configurable, intervalle minimum, concurrence max                |
+| Fonctionnalité                  | Ce qu'elle fait                                                              |
+| ------------------------------- | ---------------------------------------------------------------------------- |
+| 🔌 **Circuit Breaker**          | Ouverture/fermeture auto par fournisseur avec seuils configurables           |
+| 🎯 **Endpoint-Aware Models**    | Custom models declare supported endpoints + API format                       |
+| 🛡️ **Anti-Thundering Herd**     | Mutex + sémaphore de rate-limit pour les fournisseurs avec clé API           |
+| 🧠 **Cache sémantique**         | Cache à deux niveaux (signature + sémantique) réduit coût et latence         |
+| ⚡ **Idempotence des requêtes** | Fenêtre de dédup 5s pour les requêtes dupliquées                             |
+| 🔒 **Spoofing TLS Fingerprint** | Contournement de détection de bot via wreq-js                                |
+| 🌐 **Filtrage IP**              | Allowlist/blocklist pour le contrôle d'accès API                             |
+| 📊 **Rate limits éditables**    | RPM configurable, intervalle minimum, concurrence max                        |
+| 💾 **Rate Limit Persistence**   | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
+| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt       |
 
 ### 📊 Observabilité & Analytique
 
@@ -472,6 +974,27 @@ Traduction transparente entre les formats :
 
 </details>
 
+## 🧪 Évaluations (Evals)
+
+OmniRoute inclut un framework d'évaluation intégré pour tester la qualité des réponses LLM contre un golden set. Accès via **Analytics → Evals** dans le tableau de bord.
+
+### Set intégré
+
+Le « OmniRoute Golden Set » préchargé contient 10 cas de test :
+
+- Salutations, mathématiques, géographie, génération de code
+- Conformité format JSON, traduction, markdown
+- Rejet de sécurité (contenu nocif), comptage, logique booléenne
+
+### Stratégies d'évaluation
+
+| Stratégie  | Description                                                    | Exemple                          |
+| ---------- | -------------------------------------------------------------- | -------------------------------- |
+| `exact`    | La sortie doit correspondre exactement                         | `"4"`                            |
+| `contains` | La sortie doit contenir la sous-chaîne (insensible à la casse) | `"Paris"`                        |
+| `regex`    | La sortie doit correspondre au motif regex                     | `"1.*2.*3"`                      |
+| `custom`   | Fonction JS personnalisée retourne true/false                  | `(output) => output.length > 10` |
+
 ---
 
 ## 📖 Guide de configuration
@@ -754,97 +1277,6 @@ Paramètres → Configuration API :
 
 ---
 
-## 📊 Modèles disponibles
-
-<details>
-<summary><b>Voir tous les modèles disponibles</b></summary>
-
-**Claude Code (`cc/`)** - Pro/Max :
-
-- `cc/claude-opus-4-6`
-- `cc/claude-sonnet-4-5-20250929`
-- `cc/claude-haiku-4-5-20251001`
-
-**Codex (`cx/`)** - Plus/Pro :
-
-- `cx/gpt-5.2-codex`
-- `cx/gpt-5.1-codex-max`
-
-**Gemini CLI (`gc/`)** - GRATUIT :
-
-- `gc/gemini-3-flash-preview`
-- `gc/gemini-2.5-pro`
-
-**GitHub Copilot (`gh/`)** :
-
-- `gh/gpt-5`
-- `gh/claude-4.5-sonnet`
-
-**NVIDIA NIM (`nvidia/`)** - Crédits GRATUITS :
-
-- `nvidia/llama-3.3-70b-instruct`
-- `nvidia/mistral-7b-instruct`
-- 50+ modèles sur [build.nvidia.com](https://build.nvidia.com)
-
-**GLM (`glm/`)** - $0.6/1M :
-
-- `glm/glm-4.7`
-
-**MiniMax (`minimax/`)** - $0.2/1M :
-
-- `minimax/MiniMax-M2.1`
-
-**iFlow (`if/`)** - GRATUIT :
-
-- `if/kimi-k2-thinking`
-- `if/qwen3-coder-plus`
-- `if/deepseek-r1`
-- `if/glm-4.7`
-- `if/minimax-m2`
-
-**Qwen (`qw/`)** - GRATUIT :
-
-- `qw/qwen3-coder-plus`
-- `qw/qwen3-coder-flash`
-
-**Kiro (`kr/`)** - GRATUIT :
-
-- `kr/claude-sonnet-4.5`
-- `kr/claude-haiku-4.5`
-
-**OpenRouter (`or/`)** - 100+ modèles :
-
-- `or/anthropic/claude-4-sonnet`
-- `or/google/gemini-2.5-pro`
-- Tout modèle de [openrouter.ai/models](https://openrouter.ai/models)
-
-</details>
-
----
-
-## 🧪 Évaluations (Evals)
-
-OmniRoute inclut un framework d'évaluation intégré pour tester la qualité des réponses LLM contre un golden set. Accès via **Analytics → Evals** dans le tableau de bord.
-
-### Golden Set intégré
-
-Le « OmniRoute Golden Set » préchargé contient 10 cas de test :
-
-- Salutations, mathématiques, géographie, génération de code
-- Conformité format JSON, traduction, markdown
-- Rejet de sécurité (contenu nocif), comptage, logique booléenne
-
-### Stratégies d'évaluation
-
-| Stratégie  | Description                                                    | Exemple                          |
-| ---------- | -------------------------------------------------------------- | -------------------------------- |
-| `exact`    | La sortie doit correspondre exactement                         | `"4"`                            |
-| `contains` | La sortie doit contenir la sous-chaîne (insensible à la casse) | `"Paris"`                        |
-| `regex`    | La sortie doit correspondre au motif regex                     | `"1.*2.*3"`                      |
-| `custom`   | Fonction JS personnalisée retourne true/false                  | `(output) => output.length > 10` |
-
----
-
 ## 🐛 Dépannage
 
 <details>
@@ -900,7 +1332,7 @@ Le « OmniRoute Golden Set » préchargé contient 10 cas de test :
 
 ---
 
-## 🛠️ Stack technologique
+## 🛠️
 
 - **Runtime** : Node.js 20+
 - **Langage** : TypeScript 5.9 — **100% TypeScript** dans `src/` et `open-sse/` (v1.0.6)
@@ -931,17 +1363,7 @@ Le « OmniRoute Golden Set » préchargé contient 10 cas de test :
 
 ---
 
-## 📧 Support
-
-> 💬 **Rejoignez notre communauté !** [Groupe WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obtenez de l'aide, partagez des astuces et restez informé.
-
-- **Site web** : [omniroute.online](https://omniroute.online)
-- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Issues** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **WhatsApp** : [Groupe communautaire](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Projet original** : [9router par decolua](https://github.com/decolua/9router)
-
----
+## 🗺️
 
 ## 👥 Contributeurs
 

README.it.md

@@ -104,12 +104,41 @@ _Connetti qualsiasi IDE o strumento CLI con IA tramite OmniRoute — gateway API
 
 [🌐 Sito Web](https://omniroute.online) • [🚀 Avvio Rapido](#-avvio-rapido) • [💡 Funzionalità](#-funzionalità-principali) • [📖 Docs](#-documentazione) • [💰 Prezzi](#-panoramica-prezzi)
 
-🌐 **Disponibile in:** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
+🌐 **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)
 
 </div>
 
 ---
 
+## 🖼️
+
+<div align="center">
+  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute" width="800"/>
+</div>
+
+---
+
+## 📸
+
+<details>
+<summary><b>...</b></summary>
+
+| #     | #                                        |
+| ----- | ---------------------------------------- |
+| **1** | ![1](docs/screenshots/01-providers.png)  |
+| **2** | ![2](docs/screenshots/02-combos.png)     |
+| **3** | ![3](docs/screenshots/03-analytics.png)  |
+| **4** | ![4](docs/screenshots/04-health.png)     |
+| **5** | ![5](docs/screenshots/05-translator.png) |
+| **6** | ![6](docs/screenshots/06-settings.png)   |
+| **7** | ![7](docs/screenshots/07-cli-tools.png)  |
+| **8** | ![8](docs/screenshots/08-usage.png)      |
+| **9** | ![9](docs/screenshots/09-endpoint.png)   |
+
+</details>
+
+---
+
 ## 🤔 Perché OmniRoute?
 
 **Smetti di sprecare soldi e di sbattere contro i limiti:**
@@ -128,6 +157,19 @@ _Connetti qualsiasi IDE o strumento CLI con IA tramite OmniRoute — gateway API
 
 ---
 
+## 📧 Supporto
+
+> 💬 **Unisciti alla nostra community!** [Gruppo WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Ottieni aiuto, condividi consigli e rimani aggiornato.
+
+- **Sito Web**: [omniroute.online](https://omniroute.online)
+- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **WhatsApp**: [Gruppo della comunità](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+- **WhatsApp**: [Gruppo della comunità](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+- **Progetto Originale**: [9router di decolua](https://github.com/decolua/9router)
+
+---
+
 ## 🔄 Come Funziona
 
 ```
@@ -157,6 +199,497 @@ Risultato: Non smettere mai di programmare, costo minimo
 
 ---
 
+## 🎯 Cosa risolve OmniRoute: 30 punti critici reali e casi d'uso
+
+> **Ogni sviluppatore che utilizza strumenti di intelligenza artificiale affronta questi problemi quotidianamente.** OmniRoute è stato creato per risolverli tutti: dai superamenti dei costi ai blocchi regionali, dai flussi OAuth interrotti alle operazioni di protocollo e all'osservabilità aziendale.
+
+<details>
+<summary><b>💸 1. "Pago un abbonamento costoso ma vengo comunque interrotto dai limiti"</b></summary>
+
+Gli sviluppatori pagano $ 20-200 al mese per Claude Pro, Codex Pro o GitHub Copilot. Anche pagando, la quota ha un tetto: 5 ore di utilizzo, limiti settimanali o limiti di tariffa al minuto. A metà sessione di codifica, il provider smette di rispondere e lo sviluppatore perde flusso e produttività.
+
+**Come OmniRoute risolve il problema:**
+
+- **Fallback intelligente a 4 livelli**: se la quota dell'abbonamento si esaurisce, reindirizza automaticamente alla chiave API → Economico → Gratuito senza alcun intervento manuale
+- **Monitoraggio delle quote in tempo reale**: mostra il consumo di token in tempo reale con il conto alla rovescia ripristinato (5 ore, giornaliero, settimanale)
+- **Supporto multi-account**: più account per fornitore con round robin automatico: quando uno si esaurisce, passa a quello successivo
+- **Combo personalizzate** — Catene di fallback personalizzabili con 6 strategie di bilanciamento (fill-first, round-robin, P2C, casuale, meno utilizzato, ottimizzato in termini di costi)
+- **Quote aziendali Codex**: monitoraggio delle quote dello spazio di lavoro aziendale/team direttamente nella dashboard
+
+</details>
+
+<details>
+<summary><b>🔌 2. "Devo utilizzare più provider ma ognuno ha un'API diversa"</b></summary>
+
+OpenAI utilizza un formato, Claude (Anthropic) ne utilizza un altro, Gemini ancora un altro. Se uno sviluppatore desidera testare modelli di fornitori diversi o eseguire il fallback tra di loro, deve riconfigurare gli SDK, modificare gli endpoint e gestire formati incompatibili. I provider personalizzati (FriendLI, NIM) hanno endpoint del modello non standard.
+
+**Come OmniRoute risolve il problema:**
+
+- **Endpoint unificato**: un singolo `http://localhost:20128/v1` funge da proxy per tutti gli oltre 36 provider
+- **Traduzione del formato** — Automatica e trasparente: OpenAI ↔ Claude ↔ Gemini ↔ API di risposta
+- **Sanitizzazione della risposta**: rimuove i campi non standard (`x_groq`, `usage_breakdown`, `service_tier`) che interrompono OpenAI SDK v1.83+
+- **Normalizzazione del ruolo**: converte `developer` → `system` per provider non OpenAI; `system` → `user` per GLM/ERNIE
+- **Think Tag Extraction** — Estrae i blocchi `<think>` da modelli come DeepSeek R1 in `reasoning_content` standardizzati
+- **Uscita strutturata per Gemini** — `json_schema` → `responseMimeType`/`responseSchema` conversione automatica
+- **`stream` per impostazione predefinita è `false`** — Si allinea con le specifiche OpenAI, evitando SSE imprevisti negli SDK Python/Rust/Go
+
+</details>
+
+<details>
+<summary><b>🌐 3. "Il mio fornitore di intelligenza artificiale blocca la mia regione/paese"</b></summary>
+
+Provider come OpenAI/Codex bloccano l'accesso da determinate regioni geografiche. Gli utenti ricevono errori come `unsupported_country_region_territory` durante le connessioni OAuth e API. Ciò è particolarmente frustrante per gli sviluppatori dei paesi in via di sviluppo.
+
+**Come OmniRoute risolve il problema:**
+
+- **Configurazione proxy a 3 livelli**: proxy configurabile a 3 livelli: globale (tutto il traffico), per provider (un solo provider) e per connessione/chiave
+- **Badge proxy con codice colore** — Indicatori visivi: 🟢 proxy globale, 🟡 proxy provider, 🔵 proxy di connessione, che mostra sempre l'IP
+- **Scambio di token OAuth tramite proxy**: anche il flusso OAuth passa attraverso il proxy, risolvendo `unsupported_country_region_territory`
+- **Test di connessione tramite proxy**: i test di connessione utilizzano il proxy configurato (non più bypass diretto)
+- **Supporto SOCKS5**: supporto completo del proxy SOCKS5 per il routing in uscita
+- **Spoofing dell'impronta digitale TLS**: impronta digitale TLS simile a un browser tramite `wreq-js` per bypassare il rilevamento dei bot
+
+</details>
+
+<details>
+<summary><b>🆓 4. "Voglio usare l'intelligenza artificiale per programmare ma non ho soldi"</b></summary>
+
+Non tutti possono pagare $ 20-200 al mese per gli abbonamenti AI. Studenti, sviluppatori provenienti da paesi emergenti, hobbisti e liberi professionisti hanno bisogno di accedere a modelli di qualità a costo zero.
+
+**Come OmniRoute risolve il problema:**
+
+- **Fornitori del livello gratuito integrati**: supporto nativo per fornitori gratuiti al 100%: iFlow (8 modelli illimitati), Qwen (3 modelli illimitati), Kiro (Claude gratis), Gemini CLI (180.000/mese gratuiti)
+- **Combo solo gratuiti** — Catena `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $ 0/mese senza tempi di inattività
+- **Crediti gratuiti NVIDIA NIM**: 1000 crediti gratuiti integrati
+- **Strategia di ottimizzazione dei costi**: strategia di routing che sceglie automaticamente il fornitore più economico disponibile
+
+</details>
+
+<details>
+<summary><b>🔒 5. "Devo proteggere il mio gateway AI da accessi non autorizzati"</b></summary>
+
+Quando si espone un gateway AI alla rete (LAN, VPS, Docker), chiunque abbia l'indirizzo può consumare i token/la quota dello sviluppatore. Senza protezione, le API sono vulnerabili ad usi impropri, tempestive iniezioni e abusi.
+
+**Come OmniRoute risolve il problema:**
+
+- **Gestione delle chiavi API**: generazione, rotazione e ambito per provider con una pagina `/dashboard/api-manager` dedicata
+- **Autorizzazioni a livello di modello**: limita le chiavi API a modelli specifici (`openai/*`, modelli con caratteri jolly), con l'interruttore Consenti tutto/Limita
+- **API Endpoint Protection**: richiede una chiave per `/v1/models` e blocca provider specifici dall'elenco
+- **Auth Guard + Protezione CSRF**: tutti i percorsi del dashboard protetti con middleware `withAuth` + token CSRF
+- **Rate Limiter**: limitazione della velocità per IP con finestre configurabili
+- **Filtro IP**: lista consentita/lista bloccata per il controllo degli accessi
+- **Prompt Injection Guard**: sanificazione contro modelli di prompt dannosi
+- **Crittografia AES-256-GCM**: credenziali crittografate a riposo
+
+</details>
+
+<details>
+<summary><b>🛑 6. "Il mio provider è andato in tilt e ho perso il flusso di codifica"</b></summary>
+
+I fornitori di intelligenza artificiale possono diventare instabili, restituire errori 5xx o raggiungere limiti di velocità temporanei. Se uno sviluppatore dipende da un singolo fornitore, viene interrotto. Senza interruttori automatici, tentativi ripetuti possono bloccare l'applicazione.
+
+**Come OmniRoute risolve il problema:**
+
+- **Interruttore automatico per provider**: apertura/chiusura automatica con soglie e raffreddamento configurabili (chiuso/aperto/semiaperto)
+- **Backoff esponenziale**: ritardi progressivi tra i tentativi
+- **Anti-Thundering Herd** — Mutex + protezione semaforo contro tempeste di tentativi simultanei
+- **Catene di fallback combinate**: se il fornitore primario fallisce, cade automaticamente nella catena senza alcun intervento
+- **Combo Circuit Breaker**: disabilita automaticamente i provider in errore all'interno di una catena combinata
+- **Dashboard integrità**: monitoraggio del tempo di attività, stati degli interruttori automatici, blocchi, statistiche della cache, latenza p50/p95/p99
+
+</details>
+
+<details>
+<summary><b>🔧 7. "Configurare ogni strumento AI è noioso e ripetitivo"</b></summary>
+
+Gli sviluppatori utilizzano Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Ogni strumento necessita di una configurazione diversa (endpoint API, chiave, modello). La riconfigurazione quando si cambia fornitore o modello è una perdita di tempo.
+
+**Come OmniRoute risolve il problema:**
+
+- **Dashboard degli strumenti CLI**: pagina dedicata con configurazione con un clic per Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
+- **GitHub Copilot Config Generator**: genera `chatLanguageModels.json` per VS Code con selezione di modelli in blocco
+- **Procedura guidata di onboarding**: configurazione guidata in 4 passaggi per gli utenti alle prime armi
+- **Un endpoint, tutti i modelli**: configura `http://localhost:20128/v1` una volta, accedi a oltre 36 provider
+
+</details>
+
+<details>
+<summary><b>🔑 8. "Gestire token OAuth da più provider è un inferno"</b></summary>
+
+Claude Code, Codex, Gemini CLI, Copilot: utilizzano tutti OAuth 2.0 con token in scadenza. Gli sviluppatori devono autenticarsi nuovamente costantemente, gestire `client_secret is missing`, `redirect_uri_mismatch` e errori sui server remoti. OAuth su LAN/VPS è particolarmente problematico.
+
+**Come OmniRoute risolve il problema:**
+
+- **Aggiornamento automatico dei token**: i token OAuth si aggiornano in background prima della scadenza
+- **OAuth 2.0 (PKCE) integrato**: flusso automatico per Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow
+- **OAuth multi-account**: account multipli per provider tramite estrazione di token JWT/ID
+- **OAuth LAN/Correzione remota**: rilevamento IP privato per `redirect_uri` + modalità URL manuale per server remoti
+- **OAuth Behind Nginx**: utilizza `window.location.origin` per la compatibilità con proxy inverso
+- **Guida OAuth remota**: guida passo passo per le credenziali Google Cloud su VPS/Docker
+
+</details>
+
+<details>
+<summary><b>📊 9. "Non so quanto sto spendendo né dove"</b></summary>
+
+Gli sviluppatori utilizzano più fornitori a pagamento ma non hanno una visione unificata della spesa. Ogni fornitore ha il proprio dashboard di fatturazione, ma non esiste una visualizzazione consolidata. I costi imprevisti possono accumularsi.
+
+**Come OmniRoute risolve il problema:**
+
+- **Dashboard di analisi dei costi**: monitoraggio dei costi per token e gestione del budget per fornitore
+- **Limiti di budget per livello**: massimale di spesa per livello che attiva il fallback automatico
+- **Configurazione dei prezzi per modello**: prezzi configurabili per modello
+- **Statistiche di utilizzo per chiave API**: conteggio delle richieste e timestamp dell'ultimo utilizzo per chiave
+- **Dashboard di analisi**: schede statistiche, grafico di utilizzo del modello, tabella dei fornitori con percentuali di successo e latenza
+
+</details>
+
+<details>
+<summary><b>🐛 10. "Non riesco a diagnosticare errori e problemi nelle chiamate AI"</b></summary>
+
+Quando una chiamata fallisce, lo sviluppatore non sa se si trattava di un limite di velocità, di un token scaduto, di un formato errato o di un errore del provider. Registri frammentati su diversi terminali. Senza osservabilità, il debug è un processo per tentativi ed errori.
+
+**Come OmniRoute risolve il problema:**
+
+- **Dashboard dei registri unificati**: 4 schede: registri delle richieste, registri del proxy, registri di controllo, console
+- **Visualizzatore log della console**: visualizzatore in stile terminale in tempo reale con livelli codificati a colori, scorrimento automatico, ricerca, filtro
+- **Registri proxy SQLite**: registri persistenti che sopravvivono ai riavvii del server
+- **Translator Playground** — 4 modalità di debug: Playground (traduzione del formato), Chat Tester (andata e ritorno), Test Bench (batch), Live Monitor (in tempo reale)
+- **Telemetria richiesta**: latenza p50/p95/p99 + traccia X-Request-Id
+- **Registrazione basata su file con rotazione**: l'interceptor della console acquisisce tutto nel registro JSON con rotazione basata sulle dimensioni
+
+</details>
+
+<details>
+<summary><b>🏗️ 11. "L'implementazione e la manutenzione del gateway sono complesse"</b></summary>
+
+L'installazione, la configurazione e la manutenzione di un proxy AI in diversi ambienti (locale, VPS, Docker, cloud) richiedono molto lavoro. Problemi come percorsi codificati, `EACCES` nelle directory, conflitti di porte e build multipiattaforma aggiungono attrito.
+
+**Come OmniRoute risolve il problema:**
+
+- **Installazione globale npm** — `npm install -g omniroute && omniroute` — completata
+- **Docker multipiattaforma** — AMD64 + ARM64 nativo (Apple Silicon, AWS Graviton, Raspberry Pi)
+- **Docker Compose Profiles** — `base` (senza strumenti CLI) e `cli` (con Claude Code, Codex, OpenClaw)
+- **App desktop Electron**: app nativa per Windows/macOS/Linux con barra delle applicazioni, avvio automatico, modalità offline
+- **Modalità porta divisa**: API e dashboard su porte separate per scenari avanzati (proxy inverso, rete di contenitori)
+- **Cloud Sync**: configura la sincronizzazione tra dispositivi tramite Cloudflare Workers
+- **Backup DB**: backup, ripristino, esportazione e importazione automatici di tutte le impostazioni
+
+</details>
+
+<details>
+<summary><b>🌍 12. "L'interfaccia è solo inglese e il mio team non parla inglese"</b></summary>
+
+I team nei paesi non anglofoni, soprattutto in America Latina, Asia ed Europa, hanno difficoltà con le interfacce solo in inglese. Le barriere linguistiche riducono l'adozione e aumentano gli errori di configurazione.
+
+**Come OmniRoute risolve il problema:**
+
+- **Dashboard i18n — 30 lingue** — Tutti gli oltre 500 tasti tradotti tra cui arabo, bulgaro, danese, tedesco, spagnolo, finlandese, francese, ebraico, hindi, ungherese, indonesiano, italiano, giapponese, coreano, malese, olandese, norvegese, polacco, portoghese (PT/BR), rumeno, russo, slovacco, svedese, tailandese, ucraino, vietnamita, cinese, filippino, inglese
+- **Supporto RTL**: supporto da destra a sinistra per arabo ed ebraico
+- **README multilingue**: 30 traduzioni complete di documentazione
+- **Selettore lingua**: icona del globo nell'intestazione per la commutazione in tempo reale
+
+</details>
+
+<details>
+<summary><b>🔄 13. "Ho bisogno di qualcosa di più della semplice chat: ho bisogno di incorporamenti, immagini, audio"</b></summary>
+
+L'intelligenza artificiale non è solo il completamento della chat. Gli sviluppatori devono generare immagini, trascrivere audio, creare incorporamenti per RAG, riclassificare i documenti e moderare i contenuti. Ogni API ha un endpoint e un formato diversi.
+
+**Come OmniRoute risolve il problema:**
+
+- **Incorporamenti** — `/v1/embeddings` con 6 fornitori e oltre 9 modelli
+- **Generazione di immagini** — `/v1/images/generations` con 10 provider e oltre 20 modelli (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)
+- **Da testo a video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) e SD WebUI
+- **Trasformazione testo in musica** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)
+- **Trascrizione audio** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3
+- **Sintesi vocale** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, + fornitori esistenti
+- **Moderazioni** — `/v1/moderations` — Controlli di sicurezza dei contenuti
+- **Riclassificazione** — `/v1/rerank`: riclassificazione della pertinenza del documento
+- **API di risposta**: supporto `/v1/responses` completo per Codex
+
+</details>
+
+<details>
+<summary><b>🧪 14. "Non ho modo di testare e confrontare la qualità tra i modelli"</b></summary>
+
+Gli sviluppatori vogliono sapere quale modello è il migliore per il loro caso d'uso (codice, traduzione, ragionamento), ma il confronto manuale è lento. Non esistono strumenti di valutazione integrati.
+
+**Come OmniRoute risolve il problema:**
+
+- **Valutazioni LLM**: test Golden Set con 10 casi precaricati che coprono saluti, matematica, geografia, generazione di codice, conformità JSON, traduzione, ribasso, rifiuto di sicurezza
+- **4 strategie di corrispondenza** — `exact`, `contains`, `regex`, `custom` (funzione JS)
+- **Translator Playground Test Bench**: test in batch con input multipli e output previsti, confronto tra provider
+- **Chat Tester**: andata e ritorno completo con rendering della risposta visiva
+- **Live Monitor**: flusso in tempo reale di tutte le richieste che passano attraverso il proxy
+
+</details>
+
+<details>
+<summary><b>📈 15. "Ho bisogno di scalare senza perdere prestazioni"</b></summary>
+
+Man mano che il volume delle richieste cresce, senza la memorizzazione nella cache le stesse domande generano costi duplicati. Senza idempotenza, le richieste duplicate sprecano elaborazione. I limiti tariffari per fornitore devono essere rispettati.
+
+**Come OmniRoute risolve il problema:**
+
+- **Cache semantica**: la cache a due livelli (firma + semantica) riduce costi e latenza
+- **Idempotenza richiesta**: finestra di deduplicazione di 5 secondi per richieste identiche
+- **Rilevamento del limite di velocità**: RPM per provider, gap minimo e monitoraggio simultaneo massimo
+- **Limiti di velocità modificabili**: impostazioni predefinite configurabili in Impostazioni → Resilienza con persistenza
+- **Cache di convalida della chiave API**: cache a 3 livelli per prestazioni di produzione
+- **Dashboard integrità con telemetria**: latenza p50/p95/p99, statistiche cache, tempo di attività
+
+</details>
+
+<details>
+<summary><b>🤖 16. "Voglio controllare il comportamento del modello a livello globale"</b></summary>
+
+Sviluppatori che desiderano tutte le risposte in una lingua specifica, con un tono specifico o che desiderano limitare i token di ragionamento. Configurarlo in ogni strumento/richiesta non è pratico.
+
+**Come OmniRoute risolve il problema:**
+
+- **Inserimento prompt di sistema**: prompt globale applicato a tutte le richieste
+- **Thinking Budget Validation**: controllo dell'allocazione dei token tramite ragionamento per richiesta (passthrough, automatico, personalizzato, adattivo)
+- **6 Strategie di routing**: strategie globali che determinano la modalità di distribuzione delle richieste
+- **Wildcard Router**: i modelli `provider/*` instradano dinamicamente a qualsiasi provider
+- **Abilita/Disabilita combo**: attiva/disattiva le combo direttamente dalla dashboard
+- **Attiva/disattiva provider**: attiva/disattiva tutte le connessioni per un provider con un clic
+- **Fornitori bloccati**: esclude fornitori specifici dall'elenco `/v1/models`
+
+</details>
+
+<details>
+<summary><b>🧰 17. "Ho bisogno degli strumenti MCP come funzionalità di prodotto di prima classe"</b></summary>
+
+Molti gateway AI espongono MCP solo come dettaglio di implementazione nascosto. I team hanno bisogno di un livello operativo visibile e gestibile.
+
+**Come OmniRoute risolve il problema:**
+
+- MCP viene visualizzato nella navigazione del dashboard e nella scheda del protocollo dell'endpoint
+- Pagina di gestione MCP dedicata con processo, strumenti, ambiti e audit
+- Avvio rapido integrato per `omniroute --mcp` e onboarding del client
+
+</details>
+
+<details>
+<summary><b>🧠 18. "Ho bisogno dell'orchestrazione A2A con percorsi di attività di sincronizzazione + streaming"</b></summary>
+
+I flussi di lavoro degli agenti necessitano sia di risposte dirette che di esecuzione in streaming di lunga durata con controllo del ciclo di vita.
+
+**Come OmniRoute risolve il problema:**
+
+- Endpoint A2A JSON-RPC (`POST /a2a`) con `message/send` e `message/stream`
+- Streaming SSE con propagazione dello stato terminale
+- API del ciclo di vita delle attività per `tasks/get` e `tasks/cancel`
+
+</details>
+
+<details>
+<summary><b>🛰️ 19. "Ho bisogno dello stato reale del processo MCP, non di uno stato indovinato"</b></summary>
+
+I team operativi devono sapere se MCP è effettivamente attivo, non solo se un'API è raggiungibile.
+
+**Come OmniRoute risolve il problema:**
+
+- File heartbeat di runtime con PID, timestamp, trasporto, conteggio strumenti e modalità ambito
+- API di stato MCP che combina battito cardiaco + attività recente
+- Schede di stato dell'interfaccia utente per l'aggiornamento di processo/tempo di attività/battito cardiaco
+
+</details>
+
+<details>
+<summary><b>📋 20. "Ho bisogno dell'esecuzione verificabile dello strumento MCP"</b></summary>
+
+Quando gli strumenti modificano la configurazione o attivano azioni operative, i team necessitano di tracciabilità forense.
+
+**Come OmniRoute risolve il problema:**
+
+- Registrazione di controllo supportata da SQLite per le chiamate allo strumento MCP
+- Filtri per strumento, successo/fallimento, chiave API e impaginazione
+- Tabella di controllo della dashboard + endpoint statistici per l'automazione
+
+</details>
+
+<details>
+<summary><b>🔐 21. "Ho bisogno di autorizzazioni MCP con ambito per integrazione"</b></summary>
+
+Client diversi dovrebbero avere accesso con privilegi minimi alle categorie di strumenti.
+
+**Come OmniRoute risolve il problema:**
+
+- 9 ambiti MCP granulari per l'accesso controllato agli strumenti
+- Applicazione dell'ambito e visibilità nell'interfaccia utente di gestione MCP
+- Postura predefinita sicura per gli strumenti operativi
+
+</details>
+
+<details>
+<summary><b>⚙️ 22. "Ho bisogno di controlli operativi senza ridistribuirmi"</b></summary>
+
+I team necessitano di rapidi cambiamenti di runtime durante incidenti o eventi di costo.
+
+**Come OmniRoute risolve il problema:**
+
+- Cambia l'attivazione combinata direttamente dalla dashboard MCP
+- Applicare profili di resilienza da pacchetti di policy predefiniti
+- Ripristinare lo stato dell'interruttore dallo stesso pannello operativo
+
+</details>
+
+<details>
+<summary><b>🔄 23. "Ho bisogno di visibilità e cancellazione del ciclo di vita delle attività A2A in tempo reale"</b></summary>
+
+Senza visibilità del ciclo di vita, gli incidenti relativi alle attività diventano difficili da valutare.
+
+**Come OmniRoute risolve il problema:**
+
+- Elenco/filtro delle attività per stato/competenza con impaginazione
+- Esamina i metadati, gli eventi e gli artefatti delle attività
+- Endpoint di annullamento dell'attività e azione dell'interfaccia utente con conferma
+
+</details>
+
+<details>
+<summary><b>🌊 24. "Ho bisogno di metriche di flusso attive per il carico A2A"</b></summary>
+
+I flussi di lavoro in streaming richiedono informazioni operative sulla concorrenza e sulle connessioni live.
+
+**Come OmniRoute risolve il problema:**
+
+- Contatori di flussi attivi integrati nello stato A2A
+- Timestamp dell'ultima attività e conteggi per stato
+- Schede dashboard A2A per il monitoraggio delle operazioni in tempo reale
+
+</details>
+
+<details>
+<summary><b>🪪 25. "Ho bisogno del rilevamento degli agenti standard per i clienti"</b></summary>
+
+I client e gli agenti di orchestrazione esterni necessitano di metadati leggibili dal computer per l'onboarding.
+
+**Come OmniRoute risolve il problema:**
+
+- Carta Agente esposta a `/.well-known/agent.json`
+- Capacità e competenze mostrate nell'interfaccia utente di gestione
+- L'API di stato A2A include metadati di rilevamento per l'automazione
+
+</details>
+
+<details>
+<summary><b>🧭 26. "Ho bisogno della rilevabilità del protocollo nella UX del prodotto"</b></summary>
+
+Se gli utenti non riescono a scoprire le superfici del protocollo, l'adozione e la qualità del supporto diminuiscono.
+
+**Come OmniRoute risolve il problema:**
+
+- Voci della barra laterale per MCP e A2A
+- Scheda Protocolli della pagina Endpoint con avvio rapido e stato
+- Collegamenti dalla panoramica alle dashboard di gestione dedicate
+
+</details>
+
+<details>
+<summary><b>🧪 27. "Ho bisogno della convalida del protocollo end-to-end con clienti reali"</b></summary>
+
+I test simulati non sono sufficienti per verificare la compatibilità del protocollo prima del rilascio.
+
+**Come OmniRoute risolve il problema:**
+
+- Suite E2E che avvia l'app e utilizza il trasporto client SDK MCP reale
+- Test client A2A per i flussi di rilevamento, invio, streaming, acquisizione e annullamento
+- Effettuare un controllo incrociato delle asserzioni con l'audit MCP e le API delle attività A2A
+
+</details>
+
+<details>
+<summary><b>📡 28. "Ho bisogno di osservabilità unificata su tutte le interfacce"</b></summary>
+
+Suddividere l'osservabilità per protocollo crea punti ciechi e un MTTR più lungo.
+
+**Come OmniRoute risolve il problema:**
+
+- Dashboard/registri/analisi unificati in un unico prodotto
+- Salute + audit + richiesta di telemetria su livelli OpenAI, MCP e A2A
+- API operative per stato e automazione
+
+</details>
+
+<details>
+<summary><b>💼 29. "Ho bisogno di un runtime per proxy + strumenti + orchestrazione agente"</b></summary>
+
+L'esecuzione di numerosi servizi separati aumenta i costi operativi e le modalità di guasto.
+
+**Come OmniRoute risolve il problema:**
+
+- Proxy compatibile con OpenAI, server MCP e server A2A in uno stack
+- Autenticazione condivisa, resilienza, archivio dati e osservabilità
+- Modello politico coerente su tutte le superfici di interazione
+
+</details>
+
+<details>
+<summary><b>🚀 30. "Ho bisogno di spedire flussi di lavoro di agenti senza la proliferazione del codice adesivo"</b></summary>
+
+I team perdono velocità quando uniscono più servizi e script ad hoc.
+
+**Come OmniRoute risolve il problema:**
+
+- Strategia endpoint unificata per clienti e agenti
+- Interfacce utente di gestione del protocollo integrate e percorsi di convalida del fumo
+- Fondamenti pronti per la produzione (sicurezza, registrazione, resilienza, backup)
+
+</details>
+
+### Playbook di esempio (casi d'uso integrati)
+
+**Playbook A: massimizza l'abbonamento a pagamento + backup economico**
+
+```txt
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6
+  2. glm/glm-4.7
+  3. if/kimi-k2-thinking
+
+Monthly cost: $20 + small backup spend
+Outcome: higher quality, near-zero interruption
+```
+
+**Playbook B: stack di codifica a costo zero**
+
+```txt
+Combo: "free-forever"
+  1. gc/gemini-3-flash
+  2. if/kimi-k2-thinking
+  3. qw/qwen3-coder-plus
+
+Monthly cost: $0
+Outcome: stable free coding workflow
+```
+
+**Playbook C: catena di fallback sempre attiva 24 ore su 24, 7 giorni su 7**
+
+```txt
+Combo: "always-on"
+  1. cc/claude-opus-4-6
+  2. cx/gpt-5.2-codex
+  3. glm/glm-4.7
+  4. minimax/MiniMax-M2.1
+  5. if/kimi-k2-thinking
+
+Outcome: deep fallback depth for deadline-critical workloads
+```
+
+**Playbook D: operazioni dell'agente con MCP + A2A**
+
+```txt
+1) Start MCP transport (`omniroute --mcp`) for tool-driven operations
+2) Run A2A tasks via `message/send` and `message/stream`
+3) Observe via /dashboard/mcp and /dashboard/a2a
+4) Control incidents with resilience profile + task cancellation
+```
+
+---
+
 ## ⚡ Avvio Rapido
 
 **1. Installa globalmente:**
@@ -247,6 +780,30 @@ docker compose --profile cli up -d
 
 ---
 
+---
+
+## 🖥️
+
+> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.
+
+- 🖥️ **Native Window** — Dedicated app window with system tray integration
+- 🔄 **Auto-Start** — Launch OmniRoute on system login
+- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues
+- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)
+- 🌐 **Offline Mode** — Works fully offline with bundled server
+
+```bash
+npm run electron:dev           # Development mode
+npm run electron:build         # Current platform
+npm run electron:build:win     # Windows (.exe)
+npm run electron:build:mac     # macOS (.dmg)
+npm run electron:build:linux   # Linux (.AppImage)
+```
+
+📖 Full documentation: [`electron/README.md`](electron/README.md)
+
+---
+
 ## 💰 Panoramica Prezzi
 
 | Tier               | Provider          | Costo                        | Reset Quota           | Ideale Per                      |
@@ -272,67 +829,6 @@ docker compose --profile cli up -d
 
 ---
 
-## 🎯 Casi d'Uso
-
-### Caso 1: "Ho un abbonamento Claude Pro"
-
-**Problema:** La quota scade inutilizzata, limiti di rate durante la programmazione intensa
-
-```
-Combo: "maximize-claude"
-  1. cc/claude-opus-4-6        (usa l'abbonamento al massimo)
-  2. glm/glm-4.7               (backup economico quando la quota è esaurita)
-  3. if/kimi-k2-thinking       (fallback d'emergenza gratuito)
-
-Costo mensile: $20 (abbonamento) + ~$5 (backup) = $25 totale
-vs. $20 + sbattere contro i limiti = frustrazione
-```
-
-### Caso 2: "Voglio costo zero"
-
-**Problema:** Non può permettersi abbonamenti, ha bisogno di IA affidabile per programmare
-
-```
-Combo: "free-forever"
-  1. gc/gemini-3-flash         (180K gratis/mese)
-  2. if/kimi-k2-thinking       (illimitato gratis)
-  3. qw/qwen3-coder-plus       (illimitato gratis)
-
-Costo mensile: $0
-Qualità: Modelli pronti per la produzione
-```
-
-### Caso 3: "Devo programmare 24/7, senza interruzioni"
-
-**Problema:** Scadenze strette, non può permettersi downtime
-
-```
-Combo: "always-on"
-  1. cc/claude-opus-4-6        (migliore qualità)
-  2. cx/gpt-5.2-codex          (secondo abbonamento)
-  3. glm/glm-4.7               (economico, reset giornaliero)
-  4. minimax/MiniMax-M2.1      (più economico, reset 5h)
-  5. if/kimi-k2-thinking       (gratuito illimitato)
-
-Risultato: 5 livelli di fallback = zero downtime
-```
-
-### Caso 4: "Voglio IA GRATUITA in OpenClaw"
-
-**Problema:** Ha bisogno di assistente IA nelle app di messaggistica, completamente gratuito
-
-```
-Combo: "openclaw-free"
-  1. if/glm-4.7                (illimitato gratis)
-  2. if/minimax-m2.1           (illimitato gratis)
-  3. if/kimi-k2-thinking       (illimitato gratis)
-
-Costo mensile: $0
-Accesso via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-```
-
----
-
 ## 💡 Funzionalità Principali
 
 ### 🧠 Routing & Intelligenza
@@ -348,6 +844,8 @@ Accesso via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 | 🧩 **Modelli personalizzati**            | Aggiungi qualsiasi ID modello a qualsiasi provider                            |
 | 🌐 **Router wildcard**                   | Instrada pattern `provider/*` verso qualsiasi provider dinamicamente          |
 | 🧠 **Budget di ragionamento**            | Modalità passthrough, auto, custom e adaptive per modelli di ragionamento     |
+| 🔀 **Model Aliases**                     | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
+| ⚡ **Background Degradation**            | Auto-route background tasks (titles, summaries) to cheaper models             |
 | 💬 **Iniezione System Prompt**           | System prompt globale applicato a tutte le richieste                          |
 | 📄 **API Responses**                     | Supporto completo per OpenAI Responses API (`/v1/responses`) per Codex        |
 
@@ -364,15 +862,18 @@ Accesso via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 
 ### 🛡️ Resilienza & Sicurezza
 
-| Funzionalità                    | Cosa Fa                                                        |
-| ------------------------------- | -------------------------------------------------------------- |
-| 🔌 **Circuit Breaker**          | Apertura/chiusura auto per provider con soglie configurabili   |
-| 🛡️ **Anti-Thundering Herd**     | Mutex + semaforo rate-limit per provider con API key           |
-| 🧠 **Cache semantica**          | Cache a due livelli (firma + semantica) riduce costi e latenza |
-| ⚡ **Idempotenza richieste**    | Finestra dedup 5s per richieste duplicate                      |
-| 🔒 **Spoofing TLS Fingerprint** | Bypass rilevamento bot tramite wreq-js                         |
-| 🌐 **Filtro IP**                | Allowlist/blocklist per controllo accesso API                  |
-| 📊 **Rate limit modificabili**  | RPM, gap minimo e concorrenza massima configurabili            |
+| Funzionalità                    | Cosa Fa                                                                      |
+| ------------------------------- | ---------------------------------------------------------------------------- |
+| 🔌 **Circuit Breaker**          | Apertura/chiusura auto per provider con soglie configurabili                 |
+| 🎯 **Endpoint-Aware Models**    | Custom models declare supported endpoints + API format                       |
+| 🛡️ **Anti-Thundering Herd**     | Mutex + semaforo rate-limit per provider con API key                         |
+| 🧠 **Cache semantica**          | Cache a due livelli (firma + semantica) riduce costi e latenza               |
+| ⚡ **Idempotenza richieste**    | Finestra dedup 5s per richieste duplicate                                    |
+| 🔒 **Spoofing TLS Fingerprint** | Bypass rilevamento bot tramite wreq-js                                       |
+| 🌐 **Filtro IP**                | Allowlist/blocklist per controllo accesso API                                |
+| 📊 **Rate limit modificabili**  | RPM, gap minimo e concorrenza massima configurabili                          |
+| 💾 **Rate Limit Persistence**   | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
+| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt       |
 
 ### 📊 Osservabilità & Analytics
 
@@ -472,6 +973,27 @@ Traduzione trasparente tra formati:
 
 </details>
 
+## 🧪 Valutazioni (Evals)
+
+OmniRoute include un framework di valutazione integrato per testare la qualità delle risposte LLM contro un golden set. Accesso via **Analytics → Evals** nella dashboard.
+
+### Set integrato
+
+Il "OmniRoute Golden Set" precaricato contiene 10 casi di test:
+
+- Saluti, matematica, geografia, generazione codice
+- Conformità formato JSON, traduzione, markdown
+- Rifiuto sicurezza (contenuto nocivo), conteggio, logica booleana
+
+### Strategie di valutazione
+
+| Strategia  | Descrizione                                                | Esempio                          |
+| ---------- | ---------------------------------------------------------- | -------------------------------- |
+| `exact`    | L'output deve corrispondere esattamente                    | `"4"`                            |
+| `contains` | L'output deve contenere la sottostringa (case-insensitive) | `"Paris"`                        |
+| `regex`    | L'output deve corrispondere al pattern regex               | `"1.*2.*3"`                      |
+| `custom`   | Funzione JS personalizzata restituisce true/false          | `(output) => output.length > 10` |
+
 ---
 
 ## 📖 Guida alla Configurazione
@@ -754,97 +1276,6 @@ Impostazioni → Configurazione API:
 
 ---
 
-## 📊 Modelli Disponibili
-
-<details>
-<summary><b>Vedi tutti i modelli disponibili</b></summary>
-
-**Claude Code (`cc/`)** - Pro/Max:
-
-- `cc/claude-opus-4-6`
-- `cc/claude-sonnet-4-5-20250929`
-- `cc/claude-haiku-4-5-20251001`
-
-**Codex (`cx/`)** - Plus/Pro:
-
-- `cx/gpt-5.2-codex`
-- `cx/gpt-5.1-codex-max`
-
-**Gemini CLI (`gc/`)** - GRATUITO:
-
-- `gc/gemini-3-flash-preview`
-- `gc/gemini-2.5-pro`
-
-**GitHub Copilot (`gh/`)**:
-
-- `gh/gpt-5`
-- `gh/claude-4.5-sonnet`
-
-**NVIDIA NIM (`nvidia/`)** - Crediti GRATUITI:
-
-- `nvidia/llama-3.3-70b-instruct`
-- `nvidia/mistral-7b-instruct`
-- 50+ modelli su [build.nvidia.com](https://build.nvidia.com)
-
-**GLM (`glm/`)** - $0.6/1M:
-
-- `glm/glm-4.7`
-
-**MiniMax (`minimax/`)** - $0.2/1M:
-
-- `minimax/MiniMax-M2.1`
-
-**iFlow (`if/`)** - GRATUITO:
-
-- `if/kimi-k2-thinking`
-- `if/qwen3-coder-plus`
-- `if/deepseek-r1`
-- `if/glm-4.7`
-- `if/minimax-m2`
-
-**Qwen (`qw/`)** - GRATUITO:
-
-- `qw/qwen3-coder-plus`
-- `qw/qwen3-coder-flash`
-
-**Kiro (`kr/`)** - GRATUITO:
-
-- `kr/claude-sonnet-4.5`
-- `kr/claude-haiku-4.5`
-
-**OpenRouter (`or/`)** - 100+ modelli:
-
-- `or/anthropic/claude-4-sonnet`
-- `or/google/gemini-2.5-pro`
-- Qualsiasi modello da [openrouter.ai/models](https://openrouter.ai/models)
-
-</details>
-
----
-
-## 🧪 Valutazioni (Evals)
-
-OmniRoute include un framework di valutazione integrato per testare la qualità delle risposte LLM contro un golden set. Accesso via **Analytics → Evals** nella dashboard.
-
-### Golden Set integrato
-
-Il "OmniRoute Golden Set" precaricato contiene 10 casi di test:
-
-- Saluti, matematica, geografia, generazione codice
-- Conformità formato JSON, traduzione, markdown
-- Rifiuto sicurezza (contenuto nocivo), conteggio, logica booleana
-
-### Strategie di valutazione
-
-| Strategia  | Descrizione                                                | Esempio                          |
-| ---------- | ---------------------------------------------------------- | -------------------------------- |
-| `exact`    | L'output deve corrispondere esattamente                    | `"4"`                            |
-| `contains` | L'output deve contenere la sottostringa (case-insensitive) | `"Paris"`                        |
-| `regex`    | L'output deve corrispondere al pattern regex               | `"1.*2.*3"`                      |
-| `custom`   | Funzione JS personalizzata restituisce true/false          | `(output) => output.length > 10` |
-
----
-
 ## 🐛 Risoluzione Problemi
 
 <details>
@@ -900,7 +1331,7 @@ Il "OmniRoute Golden Set" precaricato contiene 10 casi di test:
 
 ---
 
-## 🛠️ Stack Tecnologico
+## 🛠️
 
 - **Runtime**: Node.js 20+
 - **Linguaggio**: TypeScript 5.9 — **100% TypeScript** in `src/` e `open-sse/` (v1.0.6)
@@ -931,18 +1362,7 @@ Il "OmniRoute Golden Set" precaricato contiene 10 casi di test:
 
 ---
 
-## 📧 Supporto
-
-> 💬 **Unisciti alla nostra community!** [Gruppo WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Ottieni aiuto, condividi consigli e rimani aggiornato.
-
-- **Sito Web**: [omniroute.online](https://omniroute.online)
-- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **WhatsApp**: [Gruppo della comunità](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **WhatsApp**: [Gruppo della comunità](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Progetto Originale**: [9router di decolua](https://github.com/decolua/9router)
-
----
+## 🗺️
 
 ## 👥 Contributori
 

README.pt-BR.md

@@ -7,7 +7,7 @@
 
 _Seu proxy de API universal — um endpoint, 36+ provedores, zero tempo de inatividade._
 
-**Chat Completions • Embeddings • Geração de Imagem • Áudio • Reranking • 100% TypeScript**
+**Chat Completions • Embeddings • Geração de Imagem • Vídeo • Música • Áudio • Reranking • 100% TypeScript**
 
 ---
 
@@ -104,12 +104,41 @@ _Conecte qualquer IDE ou ferramenta CLI com IA através do OmniRoute — gateway
 
 [🌐 Website](https://omniroute.online) • [🚀 Início Rápido](#-início-rápido) • [💡 Funcionalidades](#-funcionalidades-principais) • [📖 Docs](#-documentação) • [💰 Preços](#-preços-resumidos)
 
-🌐 **Disponível em:** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
+🌐 **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)
 
 </div>
 
 ---
 
+## 🖼️
+
+<div align="center">
+  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute" width="800"/>
+</div>
+
+---
+
+## 📸
+
+<details>
+<summary><b>...</b></summary>
+
+| #     | #                                        |
+| ----- | ---------------------------------------- |
+| **1** | ![1](docs/screenshots/01-providers.png)  |
+| **2** | ![2](docs/screenshots/02-combos.png)     |
+| **3** | ![3](docs/screenshots/03-analytics.png)  |
+| **4** | ![4](docs/screenshots/04-health.png)     |
+| **5** | ![5](docs/screenshots/05-translator.png) |
+| **6** | ![6](docs/screenshots/06-settings.png)   |
+| **7** | ![7](docs/screenshots/07-cli-tools.png)  |
+| **8** | ![8](docs/screenshots/08-usage.png)      |
+| **9** | ![9](docs/screenshots/09-endpoint.png)   |
+
+</details>
+
+---
+
 ## 🤔 Por que OmniRoute?
 
 **Pare de desperdiçar dinheiro e bater em limites:**
@@ -128,6 +157,18 @@ _Conecte qualquer IDE ou ferramenta CLI com IA através do OmniRoute — gateway
 
 ---
 
+## 📧 Suporte
+
+> 💬 **Participe da comunidade!** [Grupo WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Tire dúvidas, compartilhe dicas e fique atualizado.
+
+- **Website**: [omniroute.online](https://omniroute.online)
+- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **WhatsApp**: [Grupo da Comunidade](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+- **Projeto Original**: [9router por decolua](https://github.com/decolua/9router)
+
+---
+
 ## 🔄 Como Funciona
 
 ```
@@ -157,6 +198,473 @@ Resultado: Nunca pare de programar, custo mínimo
 
 ---
 
+## 🎯 O que o OmniRoute resolve — 30 dores reais e casos de uso
+
+> **Todo desenvolvedor que usa ferramentas de IA enfrenta esses problemas diariamente.** O OmniRoute foi criado para resolver todos eles, desde estouro de custos e bloqueios regionais até operações de protocolo e observabilidade de nível produção.
+
+<details>
+<summary><b>💸 1. "Pago uma assinatura cara e ainda sou interrompido por limites"</b></summary>
+
+Desenvolvedores pagam de $20 a $200/mês por Claude Pro, Codex Pro ou GitHub Copilot. Mesmo pagando, há teto de cota, limite de 5h, limites semanais ou por minuto. No meio da sessão de coding, o provedor para de responder e o desenvolvedor perde fluxo e produtividade.
+
+**Como o OmniRoute resolve isso:**
+
+- **Fallback Inteligente em 4 Tiers** — Se a cota de assinatura acabar, redireciona automaticamente para API Key → Barato → Gratuito sem intervenção manual
+- **Rastreamento de Cota em Tempo Real** — Exibe consumo de tokens ao vivo com contagem regressiva de reset (5h, diário, semanal)
+- **Suporte Multi-Conta** — Várias contas por provedor com round-robin automático; quando uma esgota, passa para a próxima
+- **Combos Personalizados** — Cadeias de fallback customizáveis com 6 estratégias (fill-first, round-robin, P2C, aleatório, least-used, cost-optimized)
+- **Cotas Business do Codex** — Monitoramento de cota de workspace Business/Team direto no dashboard
+
+</details>
+
+<details>
+<summary><b>🔌 2. "Preciso usar múltiplos provedores, mas cada um tem uma API diferente"</b></summary>
+
+OpenAI usa um formato, Claude (Anthropic) usa outro, Gemini usa outro. Se o dev quer testar modelos de provedores diferentes ou fazer fallback entre eles, precisa reconfigurar SDKs, trocar endpoints e lidar com formatos incompatíveis. Provedores customizados (FriendLI, NIM) também têm endpoints não padronizados.
+
+**Como o OmniRoute resolve isso:**
+
+- **Endpoint Unificado** — Um único `http://localhost:20128/v1` serve como proxy para 36+ provedores
+- **Tradução de Formato** — Conversão automática e transparente: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
+- **Sanitização de Resposta** — Remove campos fora do padrão (`x_groq`, `usage_breakdown`, `service_tier`) que quebram OpenAI SDK v1.83+
+- **Normalização de Roles** — Converte `developer` → `system` para provedores não-OpenAI; `system` → `user` para GLM/ERNIE
+- **Extração de Tags Think** — Extrai blocos `<think>` de modelos como DeepSeek R1 para `reasoning_content` padronizado
+- **Saída Estruturada no Gemini** — Conversão automática de `json_schema` → `responseMimeType`/`responseSchema`
+- **`stream` padrão `false`** — Alinha com a especificação OpenAI e evita SSE inesperado em SDKs Python/Rust/Go
+
+</details>
+
+<details>
+<summary><b>🌐 3. "Meu provedor de IA bloqueia minha região/país"</b></summary>
+
+Provedores como OpenAI/Codex bloqueiam acesso em determinadas regiões. Usuários recebem erros como `unsupported_country_region_territory` durante OAuth e conexões de API. Isso é especialmente frustrante para desenvolvedores de países emergentes.
+
+**Como o OmniRoute resolve isso:**
+
+- **Config de Proxy em 3 Níveis** — Proxy configurável em nível global (todo tráfego), por provedor e por conexão/chave
+- **Badges de Proxy por Cor** — Indicadores visuais: 🟢 proxy global, 🟡 proxy do provedor, 🔵 proxy da conexão, sempre mostrando o IP
+- **Troca de Token OAuth via Proxy** — O fluxo OAuth também passa pelo proxy, resolvendo `unsupported_country_region_territory`
+- **Teste de Conexão via Proxy** — Testes usam o proxy configurado (sem bypass direto)
+- **Suporte SOCKS5** — Suporte completo a proxy SOCKS5 para roteamento de saída
+- **Spoofing de Impressão TLS** — Fingerprint TLS estilo navegador via `wreq-js` para contornar detecção de bot
+
+</details>
+
+<details>
+<summary><b>🆓 4. "Quero usar IA para programar, mas não tenho dinheiro"</b></summary>
+
+Nem todo mundo pode pagar $20–200/mês em assinaturas de IA. Estudantes, devs de países emergentes, hobistas e freelancers precisam de acesso a modelos de qualidade com custo zero.
+
+**Como o OmniRoute resolve isso:**
+
+- **Provedores Gratuitos nativos** — Suporte nativo a provedores 100% free: iFlow (8 modelos ilimitados), Qwen (3 ilimitados), Kiro (Claude grátis), Gemini CLI (180K/mês grátis)
+- **Combos Apenas Gratuitos** — Cadeia `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/mês com zero downtime
+- **Créditos Gratuitos NVIDIA NIM** — 1000 créditos free integrados
+- **Estratégia Cost Optimized** — Estratégia que escolhe automaticamente o provedor mais barato disponível
+
+</details>
+
+<details>
+<summary><b>🔒 5. "Preciso proteger meu gateway de IA contra acesso não autorizado"</b></summary>
+
+Ao expor um gateway de IA na rede (LAN, VPS, Docker), qualquer pessoa com o endereço pode consumir tokens/cota do desenvolvedor. Sem proteção, as APIs ficam vulneráveis a uso indevido, prompt injection e abuso.
+
+**Como o OmniRoute resolve isso:**
+
+- **Gestão de API Keys** — Geração, rotação e escopo por provedor com página dedicada em `/dashboard/api-manager`
+- **Permissões por Modelo** — Restringe chaves a modelos específicos (`openai/*`, padrões wildcard), com toggle Allow All/Restrict
+- **Proteção de Endpoint de API** — Exige chave para `/v1/models` e bloqueia provedores específicos da listagem
+- **Auth Guard + CSRF Protection** — Todas as rotas do dashboard protegidas com middleware `withAuth` + tokens CSRF
+- **Rate Limiter** — Limite por IP com janelas configuráveis
+- **Filtragem por IP** — Allowlist/blocklist para controle de acesso
+- **Proteção contra Prompt Injection** — Sanitização contra padrões maliciosos
+- **Criptografia AES-256-GCM** — Credenciais criptografadas em repouso
+
+</details>
+
+<details>
+<summary><b>🛑 6. "Meu provedor caiu e eu perdi meu fluxo de programação"</b></summary>
+
+Provedores de IA podem ficar instáveis, retornar erro 5xx ou atingir limites temporários de taxa. Se o dev depende de um único provedor, ele é interrompido. Sem circuit breaker, retries repetidos podem derrubar a aplicação.
+
+**Como o OmniRoute resolve isso:**
+
+- **Circuit Breaker por modelo** — Abre/fecha automaticamente com limiares e cooldown configuráveis (Closed/Open/Half-Open)
+- **Exponential Backoff** — Atrasos progressivos de retry
+- **Anti-Thundering Herd** — Proteção com mutex + semáforo contra tempestade de retries concorrentes
+- **Cadeias de Fallback em Combo** — Se o primário falhar, avança automaticamente na cadeia sem intervenção
+- **Circuit Breaker de Combo** — Desativa automaticamente provedores com falha dentro da cadeia
+- **Health Dashboard** — Monitoramento de uptime, estados de breaker, lockouts, estatísticas de cache e latência p50/p95/p99
+
+</details>
+
+<details>
+<summary><b>🔧 7. "Configurar cada ferramenta de IA é tedioso e repetitivo"</b></summary>
+
+Desenvolvedores usam Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Cada ferramenta pede configuração diferente (endpoint, chave, modelo). Reconfigurar ao trocar de provedor ou modelo é perda de tempo.
+
+**Como o OmniRoute resolve isso:**
+
+- **Dashboard de Ferramentas CLI** — Página dedicada com setup em 1 clique para Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity e Cline
+- **Gerador de Config do GitHub Copilot** — Gera `chatLanguageModels.json` para VS Code com seleção em lote de modelos
+- **Onboarding Wizard** — Fluxo guiado de 4 etapas para novos usuários
+- **Um endpoint para todos os modelos** — Configure `http://localhost:20128/v1` uma vez e acesse 36+ provedores
+
+</details>
+
+<details>
+<summary><b>🔑 8. "Gerenciar tokens OAuth de múltiplos provedores é um caos"</b></summary>
+
+Claude Code, Codex, Gemini CLI e Copilot usam OAuth 2.0 com tokens que expiram. Devs precisam reautenticar o tempo todo e lidar com erros como `client_secret is missing`, `redirect_uri_mismatch` e falhas em servidores remotos. OAuth em LAN/VPS é especialmente problemático.
+
+**Como o OmniRoute resolve isso:**
+
+- **Auto Token Refresh** — Tokens OAuth renovados em background antes da expiração
+- **OAuth 2.0 (PKCE) nativo** — Fluxo automático para Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen e iFlow
+- **OAuth Multi-Conta** — Múltiplas contas por provedor via extração de JWT/ID token
+- **Correções OAuth LAN/Remoto** — Detecção de IP privado para `redirect_uri` + modo manual de URL para servidores remotos
+- **OAuth atrás de Nginx** — Usa `window.location.origin` para compatibilidade com reverse proxy
+- **Guia de OAuth Remoto** — Passo a passo para credenciais Google Cloud em VPS/Docker
+
+</details>
+
+<details>
+<summary><b>📊 9. "Não sei quanto estou gastando nem onde"</b></summary>
+
+Desenvolvedores usam vários provedores pagos, mas não têm visão unificada de gastos. Cada provedor tem seu dashboard de billing, sem consolidação. Custos inesperados podem se acumular.
+
+**Como o OmniRoute resolve isso:**
+
+- **Dashboard de Analytics de Custo** — Rastreamento de custo por token e gestão de orçamento por provedor
+- **Limites de Orçamento por Tier** — Teto de gasto por tier que aciona fallback automático
+- **Configuração de Preço por Modelo** — Preços configuráveis por modelo
+- **Estatísticas de Uso por API Key** — Contagem de requests e timestamp de último uso por chave
+- **Analytics Dashboard** — Cards, gráfico de uso por modelo e tabela de provedores com taxa de sucesso e latência
+
+</details>
+
+<details>
+<summary><b>🐛 10. "Não consigo diagnosticar erros e problemas nas chamadas de IA"</b></summary>
+
+Quando uma chamada falha, o dev não sabe se foi rate limit, token expirado, formato incorreto ou erro do provedor. Logs ficam fragmentados em terminais diferentes. Sem observabilidade, debug vira tentativa e erro.
+
+**Como o OmniRoute resolve isso:**
+
+- **Dashboard de Logs Unificado** — 4 abas: Request Logs, Proxy Logs, Audit Logs e Console
+- **Visualizador de Console** — Viewer em tempo real estilo terminal com níveis por cor, auto-scroll, busca e filtros
+- **Proxy Logs em SQLite** — Logs persistentes que sobrevivem a reinícios do servidor
+- **Playground do Tradutor** — 4 modos de debug: Playground (tradução), Chat Tester (round-trip), Test Bench (lote), Live Monitor (tempo real)
+- **Telemetria de Request** — Latência p50/p95/p99 + rastreamento por X-Request-Id
+- **Logging em Arquivo com Rotação** — Interceptador de console grava tudo em JSON com rotação por tamanho
+
+</details>
+
+<details>
+<summary><b>🏗️ 11. "Implantar e manter o gateway é complexo"</b></summary>
+
+Instalar, configurar e manter um proxy de IA em ambientes diferentes (local, VPS, Docker, cloud) exige muito trabalho. Problemas como caminhos hardcoded, `EACCES` em diretórios, conflito de portas e build cross-platform aumentam a fricção.
+
+**Como o OmniRoute resolve isso:**
+
+- **Instalação global via npm** — `npm install -g omniroute && omniroute` e pronto
+- **Docker Multi-Platform** — AMD64 + ARM64 nativo (Apple Silicon, AWS Graviton, Raspberry Pi)
+- **Perfis Docker Compose** — `base` (sem ferramentas CLI) e `cli` (com Claude Code, Codex, OpenClaw)
+- **App Desktop Electron** — App nativo para Windows/macOS/Linux com bandeja, auto-start e modo offline
+- **Modo de Porta Separada** — API e Dashboard em portas distintas para cenários avançados (reverse proxy, rede de containers)
+- **Cloud Sync** — Sincronização de configuração entre dispositivos via Cloudflare Workers
+- **Backups de DB** — Backup automático, restauração, export e import de todas as configurações
+
+</details>
+
+<details>
+<summary><b>🌍 12. "A interface é só em inglês e meu time não fala inglês"</b></summary>
+
+Times em países não anglófonos, especialmente na América Latina, Ásia e Europa, sofrem com interfaces só em inglês. A barreira de idioma reduz adoção e aumenta erros de configuração.
+
+**Como o OmniRoute resolve isso:**
+
+- **i18n do Dashboard — 30 idiomas** — Mais de 500 chaves traduzidas, incluindo árabe, búlgaro, dinamarquês, alemão, espanhol, finlandês, francês, hebraico, hindi, húngaro, indonésio, italiano, japonês, coreano, malaio, holandês, norueguês, polonês, português (PT/BR), romeno, russo, eslovaco, sueco, tailandês, ucraniano, vietnamita, chinês, filipino e inglês
+- **Suporte RTL** — Suporte right-to-left para árabe e hebraico
+- **READMEs multilíngues** — 30 traduções completas de documentação
+- **Seletor de Idioma** — Ícone de globo no header para troca em tempo real
+
+</details>
+
+<details>
+<summary><b>🔄 13. "Preciso de mais do que chat: embeddings, imagens, áudio"</b></summary>
+
+IA não é só chat completion. Devs precisam gerar imagens, transcrever áudio, criar embeddings para RAG, reranquear documentos e moderar conteúdo. Cada API tem endpoint e formato diferentes.
+
+**Como o OmniRoute resolve isso:**
+
+- **Embeddings** — `/v1/embeddings` com 6 provedores e 9+ modelos
+- **Geração de Imagem** — `/v1/images/generations` com 10 provedores e 20+ modelos (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)
+- **Texto para Vídeo** — `/v1/videos/generations` com ComfyUI (AnimateDiff, SVD) e SD WebUI
+- **Texto para Música** — `/v1/music/generations` com ComfyUI (Stable Audio Open, MusicGen)
+- **Transcrição de Áudio** — `/v1/audio/transcriptions` com Whisper + Nvidia NIM, HuggingFace e Qwen3
+- **Texto para Fala (TTS)** — `/v1/audio/speech` com ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise e Qwen3
+- **Moderações** — `/v1/moderations` para checagens de segurança de conteúdo
+- **Reranking** — `/v1/rerank` para relevância de documentos
+- **Responses API** — Suporte completo a `/v1/responses` para Codex
+
+</details>
+
+<details>
+<summary><b>🧪 14. "Não tenho como testar e comparar qualidade entre modelos"</b></summary>
+
+Desenvolvedores querem saber qual modelo é melhor para cada caso de uso (código, tradução, raciocínio), mas comparar manualmente é lento. Não existem ferramentas integradas de avaliação na maioria das stacks.
+
+**Como o OmniRoute resolve isso:**
+
+- **Avaliações de LLM** — Golden set com 10 casos pré-carregados cobrindo saudação, matemática, geografia, geração de código, conformidade JSON, tradução, markdown e recusa de conteúdo inseguro
+- **4 Estratégias de Match** — `exact`, `contains`, `regex`, `custom` (função JS)
+- **Test Bench do Playground do Tradutor** — Testes em lote com múltiplas entradas/saídas esperadas e comparação entre provedores
+- **Chat Tester** — Round-trip completo com renderização visual da resposta
+- **Live Monitor** — Stream em tempo real de todas as requisições que passam pelo proxy
+
+</details>
+
+<details>
+<summary><b>📈 15. "Preciso escalar sem perder performance"</b></summary>
+
+À medida que o volume cresce, sem cache as mesmas perguntas geram custos duplicados. Sem idempotência, requisições duplicadas desperdiçam processamento. Também é necessário respeitar rate limits por provedor.
+
+**Como o OmniRoute resolve isso:**
+
+- **Cache Semântico** — Cache em duas camadas (assinatura + semântico) para reduzir custo e latência
+- **Idempotência de Request** — Janela de deduplicação de 5s para requisições idênticas
+- **Detecção de Rate Limit** — Rastreamento por provedor de RPM, intervalo mínimo e concorrência máxima
+- **Rate Limits Editáveis** — Padrões configuráveis em Settings → Resilience com persistência
+- **Cache de Validação de API Key** — Cache em 3 camadas para performance em produção
+- **Health Dashboard com Telemetria** — Latência p50/p95/p99, estatísticas de cache e uptime
+
+</details>
+
+<details>
+<summary><b>🤖 16. "Quero controlar o comportamento dos modelos globalmente"</b></summary>
+
+Desenvolvedores podem querer todas as respostas em um idioma específico, com tom específico ou com limite de tokens de raciocínio. Configurar isso em cada ferramenta/requisição é impraticável.
+
+**Como o OmniRoute resolve isso:**
+
+- **Injeção de System Prompt** — Prompt global aplicado a todas as requisições
+- **Validação de Thinking Budget** — Controle de alocação de tokens de raciocínio por requisição (passthrough, auto, custom, adaptive)
+- **6 Estratégias de Roteamento** — Estratégias globais que definem como as requisições são distribuídas
+- **Wildcard Router** — Padrões `provider/*` roteiam dinamicamente para qualquer provedor
+- **Toggle de Combo** — Ativa/desativa combos diretamente no dashboard
+- **Toggle de Provedor** — Ativa/desativa todas as conexões de um provedor com um clique
+- **Provedores Bloqueados** — Exclui provedores específicos da listagem de `/v1/models`
+
+</details>
+
+<details>
+<summary><b>🧰 17. "Preciso de ferramentas MCP como capacidades de primeira classe do produto"</b></summary>
+
+Muitos gateways de IA expõem MCP apenas como detalhe de implementação oculto. Times precisam de uma camada operacional visível e gerenciável.
+
+**Como o OmniRoute resolve isso:**
+
+- MCP aparece no menu do dashboard e na aba de protocolos em Endpoint
+- Página dedicada de gestão MCP com processo, ferramentas, escopos e auditoria
+- Quick-start embutido para `omniroute --mcp` e onboarding de clientes
+
+</details>
+
+<details>
+<summary><b>🧠 18. "Preciso de orquestração A2A com caminhos síncronos + streaming"</b></summary>
+
+Fluxos de agentes precisam de respostas diretas e também de execuções longas com streaming e controle de ciclo de vida.
+
+**Como o OmniRoute resolve isso:**
+
+- Endpoint A2A JSON-RPC (`POST /a2a`) com `message/send` e `message/stream`
+- Streaming SSE com propagação de estado terminal
+- APIs de ciclo de vida de tarefas para `tasks/get` e `tasks/cancel`
+
+</details>
+
+<details>
+<summary><b>🛰️ 19. "Preciso de saúde real do processo MCP, não status estimado"</b></summary>
+
+Times operacionais precisam saber se o MCP está realmente ativo, não apenas se uma API está respondendo.
+
+**Como o OmniRoute resolve isso:**
+
+- Arquivo de heartbeat em runtime com PID, timestamps, transporte, quantidade de ferramentas e modo de escopo
+- API de status MCP combinando heartbeat + atividade recente
+- Cards de status na UI para processo/uptime/frescor do heartbeat
+
+</details>
+
+<details>
+<summary><b>📋 20. "Preciso de execução auditável das ferramentas MCP"</b></summary>
+
+Quando ferramentas alteram configuração ou disparam ações operacionais, os times precisam de rastreabilidade forense.
+
+**Como o OmniRoute resolve isso:**
+
+- Auditoria de chamadas MCP baseada em SQLite
+- Filtros por ferramenta, sucesso/falha, chave de API e paginação
+- Tabela de auditoria no dashboard + endpoints de métricas para automação
+
+</details>
+
+<details>
+<summary><b>🔐 21. "Preciso de permissões MCP por escopo para cada integração"</b></summary>
+
+Clientes diferentes devem operar com privilégio mínimo por categoria de ferramenta.
+
+**Como o OmniRoute resolve isso:**
+
+- 9 escopos MCP granulares para controle de acesso às ferramentas
+- Aplicação de escopo e visibilidade na UI de gestão MCP
+- Postura segura por padrão para operações sensíveis
+
+</details>
+
+<details>
+<summary><b>⚙️ 22. "Preciso de controles operacionais sem redeploy"</b></summary>
+
+Times precisam de mudanças rápidas em runtime durante incidentes e picos de custo.
+
+**Como o OmniRoute resolve isso:**
+
+- Troca de ativação de combo direto no dashboard de MCP
+- Aplicação de perfis de resiliência via pacotes de política prontos
+- Reset de circuit breaker no mesmo painel operacional
+
+</details>
+
+<details>
+<summary><b>🔄 23. "Preciso de visibilidade ao vivo do ciclo de vida A2A e cancelamento"</b></summary>
+
+Sem visibilidade de lifecycle, incidentes de tarefas ficam difíceis de investigar e corrigir.
+
+**Como o OmniRoute resolve isso:**
+
+- Listagem/filtragem de tarefas por estado/skill com paginação
+- Drill-down de metadados, eventos e artefatos da tarefa
+- Endpoint de cancelamento + ação de UI com confirmação
+
+</details>
+
+<details>
+<summary><b>🌊 24. "Preciso de métricas de streams ativos para carga A2A"</b></summary>
+
+Fluxos em streaming exigem visão operacional de concorrência e conexões ativas.
+
+**Como o OmniRoute resolve isso:**
+
+- Contadores de streams ativos integrados ao status A2A
+- Timestamp da última tarefa e contagens por estado
+- Cards no dashboard A2A para monitoramento operacional em tempo real
+
+</details>
+
+<details>
+<summary><b>🪪 25. "Preciso de descoberta padrão de agente para clientes"</b></summary>
+
+Clientes externos e orquestradores precisam de metadados legíveis por máquina para onboarding automático.
+
+**Como o OmniRoute resolve isso:**
+
+- Agent Card exposto em `/.well-known/agent.json`
+- Capacidades e skills exibidas na UI de gestão
+- API de status A2A inclui metadados de descoberta para automação
+
+</details>
+
+<details>
+<summary><b>🧭 26. "Preciso de descobribilidade de protocolos na experiência do produto"</b></summary>
+
+Se os usuários não encontram superfícies de protocolo, adoção e qualidade de suporte caem.
+
+**Como o OmniRoute resolve isso:**
+
+- Entradas MCP e A2A na sidebar
+- Aba Protocolos em Endpoint com quick-start e status
+- Links do overview para dashboards dedicados de gestão
+
+</details>
+
+<details>
+<summary><b>🧪 27. "Preciso de validação end-to-end de protocolo com clientes reais"</b></summary>
+
+Testes mockados não bastam para validar compatibilidade de protocolo antes do release.
+
+**Como o OmniRoute resolve isso:**
+
+- Suíte E2E que sobe a aplicação e usa transporte real do SDK MCP
+- Testes de cliente A2A para discovery, send, stream, get e cancel
+- Cross-check das validações com APIs de auditoria MCP e tarefas A2A
+
+</details>
+
+<details>
+<summary><b>📡 28. "Preciso de observabilidade unificada em todas as interfaces"</b></summary>
+
+Separar observabilidade por protocolo cria pontos cegos e aumenta o MTTR.
+
+**Como o OmniRoute resolve isso:**
+
+- Dashboards/logs/analytics unificados no mesmo produto
+- Saúde + auditoria + telemetria de requisição em OpenAI, MCP e A2A
+- APIs operacionais de status para automação
+
+</details>
+
+<details>
+<summary><b>💼 29. "Preciso de um runtime único para proxy + tools + orquestração de agentes"</b></summary>
+
+Manter vários serviços separados aumenta custo operacional e modos de falha.
+
+**Como o OmniRoute resolve isso:**
+
+- Proxy OpenAI-compatible, servidor MCP e servidor A2A na mesma stack
+- Autenticação, resiliência, armazenamento e observabilidade compartilhados
+- Modelo de políticas consistente em todas as superfícies de interação
+
+</details>
+
+<details>
+<summary><b>🚀 30. "Preciso entregar workflows agênticos sem sprawl de glue code"</b></summary>
+
+Times perdem velocidade quando precisam costurar múltiplos serviços e scripts ad hoc.
+
+**Como o OmniRoute resolve isso:**
+
+- Estratégia de endpoint unificada para clientes e agentes
+- UIs de gestão de protocolo e fluxos de validação/smoke embutidos
+- Base pronta para produção (segurança, logging, resiliência e backup)
+
+</details>
+
+### Exemplos de Playbooks (Casos de Uso Integrados)
+
+**Playbook A: Maximizar assinatura paga + backup barato**
+
+```txt
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6
+  2. glm/glm-4.7
+  3. if/kimi-k2-thinking
+
+Custo mensal: $20 + pequeno gasto de backup
+Resultado: qualidade maior, interrupção quase zero
+```
+
+**Playbook B: Stack de programação com custo zero**
+
+```txt
+Combo: "free-forever"
+  1. gc/gemini-3-flash
+  2. if/kimi-k2-thinking
+  3. qw/qwen3-coder-plus
+
+Custo mensal: $0
+Resultado: fluxo de coding gratuito e estável
+```
+
 ## ⚡ Início Rápido
 
 **1. Instale globalmente:**
@@ -247,6 +755,45 @@ docker compose --profile cli up -d
 
 ---
 
+---
+
+## 🖥️
+
+> 🆕 **NOVO!** O OmniRoute agora está disponível como **aplicativo desktop nativo** para Windows, macOS e Linux.
+
+Execute o OmniRoute como um aplicativo desktop autônomo — sem terminal, sem navegador, sem internet necessária para modelos locais. O app baseado em Electron inclui:
+
+- 🖥️ **Janela Nativa** — Janela dedicada com integração à bandeja do sistema
+- 🔄 **Iniciar Automaticamente** — Inicie o OmniRoute ao fazer login no sistema
+- 🔔 **Notificações Nativas** — Receba alertas sobre esgotamento de cota ou problemas
+- ⚡ **Instalação com Um Clique** — NSIS (Windows), DMG (macOS), AppImage (Linux)
+- 🌐 **Modo Offline** — Funciona totalmente offline com servidor embarcado
+
+### Início Rápido
+
+```bash
+# Modo desenvolvimento
+npm run electron:dev
+
+# Compilar para sua plataforma
+npm run electron:build         # Plataforma atual
+npm run electron:build:win     # Windows (.exe)
+npm run electron:build:mac     # macOS (.dmg) — x64 & arm64
+npm run electron:build:linux   # Linux (.AppImage)
+```
+
+### Bandeja do Sistema
+
+Quando minimizado, o OmniRoute fica na bandeja do sistema com ações rápidas:
+
+- Abrir dashboard
+- Alterar porta do servidor
+- Sair do aplicativo
+
+📖 Documentação completa: [`electron/README.md`](electron/README.md)
+
+---
+
 ## 💰 Preços Resumidos
 
 | Tier              | Provedor          | Custo                        | Reset de Cota     | Melhor Para             |
@@ -272,108 +819,71 @@ docker compose --profile cli up -d
 
 ---
 
-## 🎯 Casos de Uso
-
-### Caso 1: "Tenho assinatura Claude Pro"
-
-**Problema:** Cota expira sem uso, limites de taxa durante programação intensa
-
-```
-Combo: "maximize-claude"
-  1. cc/claude-opus-4-6        (usar assinatura ao máximo)
-  2. glm/glm-4.7               (backup barato quando a cota acabar)
-  3. if/kimi-k2-thinking       (fallback de emergência gratuito)
-
-Custo mensal: $20 (assinatura) + ~$5 (backup) = $25 total
-vs. $20 + bater em limites = frustração
-```
-
-### Caso 2: "Quero custo zero"
-
-**Problema:** Não pode pagar assinaturas, precisa de IA confiável para programar
-
-```
-Combo: "free-forever"
-  1. gc/gemini-3-flash         (180K grátis/mês)
-  2. if/kimi-k2-thinking       (ilimitado grátis)
-  3. qw/qwen3-coder-plus       (ilimitado grátis)
-
-Custo mensal: $0
-Qualidade: Modelos prontos para produção
-```
-
-### Caso 3: "Preciso programar 24/7, sem interrupções"
-
-**Problema:** Prazos apertados, não pode ter tempo de inatividade
-
-```
-Combo: "always-on"
-  1. cc/claude-opus-4-6        (melhor qualidade)
-  2. cx/gpt-5.2-codex          (segunda assinatura)
-  3. glm/glm-4.7               (barato, reset diário)
-  4. minimax/MiniMax-M2.1      (mais barato, reset 5h)
-  5. if/kimi-k2-thinking       (gratuito ilimitado)
-
-Resultado: 5 camadas de fallback = zero tempo de inatividade
-```
-
-### Caso 4: "Quero IA GRATUITA no OpenClaw"
-
-**Problema:** Precisa de assistente de IA em aplicativos de mensagens, completamente gratuito
-
-```
-Combo: "openclaw-free"
-  1. if/glm-4.7                (ilimitado grátis)
-  2. if/minimax-m2.1           (ilimitado grátis)
-  3. if/kimi-k2-thinking       (ilimitado grátis)
-
-Custo mensal: $0
-Acesso via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-```
-
----
-
 ## 💡 Funcionalidades Principais
 
+### 🧭 Gestão MCP + A2A (Camada Operacional)
+
+A maioria dos gateways de IA expõe MCP/A2A apenas como endpoints “escondidos”. O OmniRoute traz operação de primeira classe para os dois protocolos:
+
+- **Descoberta na interface** — Entradas `MCP` e `A2A` na sidebar e aba `Protocolos` na página de Endpoint com quick-start e cartões de status.
+- **Painel operacional MCP** (`/dashboard/mcp`) — Status real do processo por heartbeat, inventário de ferramentas/scopes, auditoria com filtros e controles operacionais (trocar combo, aplicar perfil de resiliência, resetar breakers).
+- **Painel operacional A2A** (`/dashboard/a2a`) — Visão do agent card, ciclo de vida de tarefas por estado, contagem de streams ativos, drill-down/cancelamento de tasks e smoke tests de `message/send` e `message/stream`.
+- **APIs de monitoramento** — Endpoints `/api/mcp/*` e `/api/a2a/*` para status, tasks, auditoria e automações externas.
+
+Por que isso é relevante:
+
+- **Um runtime, três papéis**: router/proxy OpenAI-compatible + servidor de ferramentas MCP + servidor agente A2A.
+- **Governança unificada**: autenticação, auditoria e controles de resiliência compartilhados.
+- **Operação confiável**: times conseguem validar, monitorar e depurar comportamento dos protocolos sem sair do produto.
+
 ### 🧠 Roteamento e Inteligência
 
-| Funcionalidade                            | O que Faz                                                                       |
-| ----------------------------------------- | ------------------------------------------------------------------------------- |
-| 🎯 **Fallback Inteligente 4 Tiers**       | Auto-roteamento: Assinatura → API Key → Barato → Gratuito                       |
-| 📊 **Rastreamento de Cota em Tempo Real** | Contagem de tokens ao vivo + countdown de reset por provedor                    |
-| 🔄 **Tradução de Formato**                | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro transparente                           |
-| 👥 **Suporte Multi-Conta**                | Múltiplas contas por provedor com seleção inteligente                           |
-| 🔄 **Renovação Automática de Token**      | Tokens OAuth renovam automaticamente com retry                                  |
-| 🎨 **Combos Personalizados**              | 6 estratégias: fill-first, round-robin, p2c, random, least-used, cost-optimized |
-| 🧩 **Modelos Personalizados**             | Adicione qualquer ID de modelo a qualquer provedor                              |
-| 🌐 **Roteador Wildcard**                  | Roteie padrões `provider/*` para qualquer provedor dinamicamente                |
-| 🧠 **Budget de Raciocínio**               | Modos passthrough, auto, custom e adaptativo para modelos de raciocínio         |
-| 💬 **Injeção de System Prompt**           | System prompt global aplicado em todas as requisições                           |
-| 📄 **API Responses**                      | Suporte completo à API Responses da OpenAI (`/v1/responses`) para Codex         |
+| Funcionalidade                            | O que Faz                                                                          |
+| ----------------------------------------- | ---------------------------------------------------------------------------------- |
+| 🎯 **Fallback Inteligente 4 Tiers**       | Auto-roteamento: Assinatura → API Key → Barato → Gratuito                          |
+| 📊 **Rastreamento de Cota em Tempo Real** | Contagem de tokens ao vivo + countdown de reset por provedor                       |
+| 🔄 **Tradução de Formato**                | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro transparente                              |
+| 👥 **Suporte Multi-Conta**                | Múltiplas contas por provedor com seleção inteligente                              |
+| 🔄 **Renovação Automática de Token**      | Tokens OAuth renovam automaticamente com retry                                     |
+| 🎨 **Combos Personalizados**              | 6 estratégias: fill-first, round-robin, p2c, random, least-used, cost-optimized    |
+| 🧩 **Modelos Personalizados**             | Adicione qualquer ID de modelo a qualquer provedor                                 |
+| 🌐 **Roteador Wildcard**                  | Roteie padrões `provider/*` para qualquer provedor dinamicamente                   |
+| 🧠 **Budget de Raciocínio**               | Modos passthrough, auto, custom e adaptativo para modelos de raciocínio            |
+| <EFBFBD> **Aliases de Modelo**                   | Redireciona IDs de modelos depreciados para substitutos atuais (built-in + custom) |
+| ⚡ **Degradação em Background**           | Redireciona tarefas em background (títulos, resumos) para modelos mais baratos     |
+| <20>💬 **Injeção de System Prompt**          | System prompt global aplicado em todas as requisições                              |
+| 📄 **API Responses**                      | Suporte completo à API Responses da OpenAI (`/v1/responses`) para Codex            |
 
 ### 🎵 APIs Multi-Modal
 
-| Funcionalidade              | O que Faz                                            |
-| --------------------------- | ---------------------------------------------------- |
-| 🖼️ **Geração de Imagem**    | `/v1/images/generations` — 4 provedores, 9+ modelos  |
-| 📐 **Embeddings**           | `/v1/embeddings` — 6 provedores, 9+ modelos          |
-| 🎤 **Transcrição de Áudio** | `/v1/audio/transcriptions` — Compatível com Whisper  |
-| 🔊 **Texto para Fala**      | `/v1/audio/speech` — Síntese de áudio multi-provedor |
-| 🛡️ **Moderações**           | `/v1/moderations` — Verificações de segurança        |
-| 🔀 **Reranking**            | `/v1/rerank` — Reranking de relevância de documentos |
+| Funcionalidade              | O que Faz                                                                        |
+| --------------------------- | -------------------------------------------------------------------------------- |
+| 🖼️ **Geração de Imagem**    | `/v1/images/generations` — 10 provedores, 20+ modelos (cloud + local)            |
+| 📐 **Embeddings**           | `/v1/embeddings` — 6 provedores, 9+ modelos                                      |
+| 🎤 **Transcrição de Áudio** | `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3            |
+| 🔊 **Texto para Fala**      | `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3 |
+| 🎬 **Geração de Vídeo**     | `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD), SD WebUI                  |
+| 🎵 **Geração de Música**    | `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)                  |
+| 🛡️ **Moderações**           | `/v1/moderations` — Verificações de segurança                                    |
+| 🔀 **Reranking**            | `/v1/rerank` — Reranking de relevância de documentos                             |
 
 ### 🛡️ Resiliência e Segurança
 
-| Funcionalidade                     | O que Faz                                                             |
-| ---------------------------------- | --------------------------------------------------------------------- |
-| 🔌 **Circuit Breaker**             | Auto-abertura/fechamento por provedor com limites configuráveis       |
-| 🛡️ **Anti-Thundering Herd**        | Mutex + semáforo rate-limit para provedores com API key               |
-| 🧠 **Cache Semântico**             | Cache de duas camadas (assinatura + semântico) reduz custo e latência |
-| ⚡ **Idempotência de Requisição**  | Janela de dedup de 5s para requisições duplicadas                     |
-| 🔒 **Spoofing de Fingerprint TLS** | Bypass de detecção de bot via TLS com wreq-js                         |
-| 🌐 **Filtragem de IP**             | Allowlist/blocklist para controle de acesso à API                     |
-| 📊 **Rate Limits Editáveis**       | RPM, gap mínimo e concorrência máxima configuráveis                   |
-| 🛡 **Proteção de Endpoint API**    | Gateway de Auth + bloqueio de provedores para o endpoint `/models`    |
+| Funcionalidade                      | O que Faz                                                                     |
+| ----------------------------------- | ----------------------------------------------------------------------------- |
+| 🔌 **Circuit Breaker**              | Trip/recover por modelo com limites configuráveis                             |
+| 🎯 **Endpoint-Aware Models**        | Custom models declare supported endpoints + API format                        |
+| 🛡️ **Anti-Thundering Herd**         | Mutex + semáforo rate-limit para provedores com API key                       |
+| 🧠 **Cache Semântico**              | Cache de duas camadas (assinatura + semântico) reduz custo e latência         |
+| ⚡ **Idempotência de Requisição**   | Janela de dedup de 5s para requisições duplicadas                             |
+| 🔒 **Spoofing de Fingerprint TLS**  | Bypass de detecção de bot via TLS com wreq-js                                 |
+| 🌐 **Filtragem de IP**              | Allowlist/blocklist para controle de acesso à API                             |
+| 📊 **Rate Limits Editáveis**        | RPM, gap mínimo e concorrência máxima configuráveis                           |
+| 💾 **Persistência de Rate Limits**  | Limites aprendidos persistem via SQLite com debounce de 60s + 24h de validade |
+| 🔄 **Resiliência de Token Refresh** | Circuit breaker por provedor (5 falhas→30min) + timeout de 30s por tentativa  |
+| 🛡 **Proteção de Endpoint API**     | Gateway de Auth + bloqueio de provedores para o endpoint `/models`            |
+| 🔒 **Visibilidade de Proxy**        | Badges coloridos: 🟢 global, 🟡 provedor, 🔵 por-conexão com exibição de IP   |
+| 🌐 **Proxy em 3 Níveis**            | Configure proxies em nível global, por provedor ou por conexão                |
 
 ### 📊 Observabilidade e Analytics
 
@@ -399,7 +909,9 @@ Acesso via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 | 🧙 **Assistente de Configuração** | Setup guiado em 4 etapas para novos usuários                                      |
 | 🔧 **Dashboard CLI Tools**        | Configuração em um clique para Claude, Codex, Cline, OpenClaw, Kilo, Antigravity  |
 | 🔄 **Backups de DB**              | Backup, restauração, exportação e importação automática de todas as configurações |
-| 🌐 **Internacionalização**        | i18n completo com next-intl — suporte English + Português (Brasil)                |
+| 🌐 **Internacionalização**        | i18n completo com next-intl — suporte a 30 idiomas com RTL                        |
+| 🌍 **Seletor de Idioma**          | Ícone de globo no cabeçalho para troca entre 30 idiomas em tempo real             |
+| 📂 **Diretório de Dados Custom**  | Variável `DATA_DIR` para sobrescrever o caminho padrão `~/.omniroute`             |
 
 <details>
 <summary><b>📖 Detalhes das Funcionalidades</b></summary>
@@ -483,6 +995,29 @@ O OmniRoute inclui um poderoso Playground de Tradução integrado com **4 modos*
 
 ---
 
+## 🧪 Avaliações (Evals)
+
+OmniRoute inclui um framework de avaliação integrado para testar a qualidade de respostas de LLM contra um conjunto golden. Acesse via **Analytics → Evals** no dashboard.
+
+### Conjunto Golden Integrado
+
+O "OmniRoute Golden Set" pré-carregado contém 10 casos de teste cobrindo:
+
+- Saudações, matemática, geografia, geração de código
+- Conformidade de formato JSON, tradução, markdown
+- Recusa de segurança (conteúdo prejudicial), contagem, lógica booleana
+
+### Estratégias de Avaliação
+
+| Estratégia | Descrição                                      | Exemplo                          |
+| ---------- | ---------------------------------------------- | -------------------------------- |
+| `exact`    | Saída deve corresponder exatamente             | `"4"`                            |
+| `contains` | Saída deve conter substring (case-insensitive) | `"Paris"`                        |
+| `regex`    | Saída deve corresponder ao padrão regex        | `"1.*2.*3"`                      |
+| `custom`   | Função JS customizada retorna true/false       | `(output) => output.length > 10` |
+
+---
+
 ## 📖 Guia de Configuração
 
 <details>
@@ -763,97 +1298,6 @@ Configurações → Configuração de API:
 
 ---
 
-## 📊 Modelos Disponíveis
-
-<details>
-<summary><b>Ver todos os modelos disponíveis</b></summary>
-
-**Claude Code (`cc/`)** - Pro/Max:
-
-- `cc/claude-opus-4-6`
-- `cc/claude-sonnet-4-5-20250929`
-- `cc/claude-haiku-4-5-20251001`
-
-**Codex (`cx/`)** - Plus/Pro:
-
-- `cx/gpt-5.2-codex`
-- `cx/gpt-5.1-codex-max`
-
-**Gemini CLI (`gc/`)** - GRATUITO:
-
-- `gc/gemini-3-flash-preview`
-- `gc/gemini-2.5-pro`
-
-**GitHub Copilot (`gh/`)**:
-
-- `gh/gpt-5`
-- `gh/claude-4.5-sonnet`
-
-**NVIDIA NIM (`nvidia/`)** - Créditos GRATUITOS:
-
-- `nvidia/llama-3.3-70b-instruct`
-- `nvidia/mistral-7b-instruct`
-- 50+ mais modelos em [build.nvidia.com](https://build.nvidia.com)
-
-**GLM (`glm/`)** - $0.6/1M:
-
-- `glm/glm-4.7`
-
-**MiniMax (`minimax/`)** - $0.2/1M:
-
-- `minimax/MiniMax-M2.1`
-
-**iFlow (`if/`)** - GRATUITO:
-
-- `if/kimi-k2-thinking`
-- `if/qwen3-coder-plus`
-- `if/deepseek-r1`
-- `if/glm-4.7`
-- `if/minimax-m2`
-
-**Qwen (`qw/`)** - GRATUITO:
-
-- `qw/qwen3-coder-plus`
-- `qw/qwen3-coder-flash`
-
-**Kiro (`kr/`)** - GRATUITO:
-
-- `kr/claude-sonnet-4.5`
-- `kr/claude-haiku-4.5`
-
-**OpenRouter (`or/`)** - 100+ modelos:
-
-- `or/anthropic/claude-4-sonnet`
-- `or/google/gemini-2.5-pro`
-- Qualquer modelo de [openrouter.ai/models](https://openrouter.ai/models)
-
-</details>
-
----
-
-## 🧪 Avaliações (Evals)
-
-OmniRoute inclui um framework de avaliação integrado para testar a qualidade de respostas de LLM contra um conjunto golden. Acesse via **Analytics → Evals** no dashboard.
-
-### Conjunto Golden Integrado
-
-O "OmniRoute Golden Set" pré-carregado contém 10 casos de teste cobrindo:
-
-- Saudações, matemática, geografia, geração de código
-- Conformidade de formato JSON, tradução, markdown
-- Recusa de segurança (conteúdo prejudicial), contagem, lógica booleana
-
-### Estratégias de Avaliação
-
-| Estratégia | Descrição                                      | Exemplo                          |
-| ---------- | ---------------------------------------------- | -------------------------------- |
-| `exact`    | Saída deve corresponder exatamente             | `"4"`                            |
-| `contains` | Saída deve conter substring (case-insensitive) | `"Paris"`                        |
-| `regex`    | Saída deve corresponder ao padrão regex        | `"1.*2.*3"`                      |
-| `custom`   | Função JS customizada retorna true/false       | `(output) => output.length > 10` |
-
----
-
 ## 🐛 Solução de Problemas
 
 <details>
@@ -909,7 +1353,7 @@ O "OmniRoute Golden Set" pré-carregado contém 10 casos de teste cobrindo:
 
 ---
 
-## 🛠️ Stack Tecnológico
+## 🛠️
 
 - **Runtime**: Node.js 20+
 - **Linguagem**: TypeScript 5.9 — **100% TypeScript** em `src/` e `open-sse/` (v1.0.6)
@@ -961,7 +1405,7 @@ O "OmniRoute Golden Set" pré-carregado contém 10 casos de teste cobrindo:
 
 ---
 
-## 🗺️ Roadmap
+## 🗺️
 
 O OmniRoute tem **210+ funcionalidades planejadas** em múltiplas fases de desenvolvimento. Áreas principais:
 
@@ -986,18 +1430,6 @@ O OmniRoute tem **210+ funcionalidades planejadas** em múltiplas fases de desen
 
 ---
 
-## 📧 Suporte
-
-> 💬 **Participe da comunidade!** [Grupo WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Tire dúvidas, compartilhe dicas e fique atualizado.
-
-- **Website**: [omniroute.online](https://omniroute.online)
-- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **WhatsApp**: [Grupo da Comunidade](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Projeto Original**: [9router por decolua](https://github.com/decolua/9router)
-
----
-
 ## 👥 Contribuidores
 
 [![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)

README.ru.md

@@ -104,12 +104,41 @@ _Подключайте любую IDE или CLI-инструмент с AI ч
 
 [🌐 Сайт](https://omniroute.online) • [🚀 Быстрый старт](#-быстрый-старт) • [💡 Функции](#-основные-функции) • [📖 Документация](#-документация) • [💰 Цены](#-обзор-цен)
 
-🌐 **Доступно на:** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
+🌐 **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)
 
 </div>
 
 ---
 
+## 🖼️
+
+<div align="center">
+  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute" width="800"/>
+</div>
+
+---
+
+## 📸
+
+<details>
+<summary><b>...</b></summary>
+
+| #     | #                                        |
+| ----- | ---------------------------------------- |
+| **1** | ![1](docs/screenshots/01-providers.png)  |
+| **2** | ![2](docs/screenshots/02-combos.png)     |
+| **3** | ![3](docs/screenshots/03-analytics.png)  |
+| **4** | ![4](docs/screenshots/04-health.png)     |
+| **5** | ![5](docs/screenshots/05-translator.png) |
+| **6** | ![6](docs/screenshots/06-settings.png)   |
+| **7** | ![7](docs/screenshots/07-cli-tools.png)  |
+| **8** | ![8](docs/screenshots/08-usage.png)      |
+| **9** | ![9](docs/screenshots/09-endpoint.png)   |
+
+</details>
+
+---
+
 ## 🤔 Почему OmniRoute?
 
 **Перестаньте тратить деньги и упираться в лимиты:**
@@ -128,6 +157,18 @@ _Подключайте любую IDE или CLI-инструмент с AI ч
 
 ---
 
+## 📧 Поддержка
+
+> 💬 **Присоединяйтесь к сообществу!** [Группа WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Получайте помощь, делитесь советами и оставайтесь в курсе.
+
+- **Сайт**: [omniroute.online](https://omniroute.online)
+- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **WhatsApp**: [Группа сообщества](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+- **Оригинальный проект**: [9router от decolua](https://github.com/decolua/9router)
+
+---
+
 ## 🔄 Как это работает
 
 ```
@@ -157,6 +198,497 @@ _Подключайте любую IDE или CLI-инструмент с AI ч
 
 ---
 
+## 🎯 Что решает OmniRoute — 30 реальных проблем и вариантов использования
+
+> **Каждый разработчик, использующий инструменты искусственного интеллекта, ежедневно сталкивается с этими проблемами.** OmniRoute был создан для решения всех этих проблем — от перерасхода средств до региональных блоков, от нарушенных потоков OAuth до операций протокола и наблюдения за предприятием.
+
+<details>
+<summary><b>💸 1. «Я плачу за дорогую подписку, но меня все равно прерывают лимиты» </b></summary>
+
+Разработчики платят 20–200 долларов в месяц за Claude Pro, Codex Pro или GitHub Copilot. Даже при оплате квота имеет потолок — 5 часов использования, еженедельные лимиты или поминутные ограничения. В середине сеанса кодирования провайдер перестает отвечать, и разработчик теряет поток и производительность.
+
+**Как OmniRoute решает эту проблему:**
+
+- **Умный 4-уровневый резерв** — если квота подписки исчерпана, происходит автоматическое перенаправление на API-ключ → Дешево → Бесплатно без вмешательства вручную.
+- **Отслеживание квот в реальном времени** — показывает потребление токенов в режиме реального времени с обратным отсчетом сброса (5 часов, ежедневно, еженедельно).
+- **Поддержка нескольких учетных записей** — Несколько учетных записей у каждого провайдера с автоматическим циклическим перебором — когда один из них заканчивается, переключается на следующий
+- **Пользовательские комбинации** — Настраиваемые резервные цепочки с 6 стратегиями балансировки (сначала заполняемые, циклический, P2C, случайные, наименее используемые, с оптимизацией затрат)
+- **Бизнес-квоты Кодекса** — мониторинг квот рабочего пространства для бизнеса/команды непосредственно на панели управления.
+
+</details>
+
+<details>
+<summary><b>🔌 2. «Мне нужно использовать несколько поставщиков, но у каждого свой API» </b></summary>
+
+OpenAI использует один формат, Claude (Anthropic) — другой, Gemini — третий. Если разработчик хочет протестировать модели от разных поставщиков или использовать резервный вариант между ними, ему необходимо перенастроить SDK, изменить конечные точки, разобраться с несовместимыми форматами. Пользовательские поставщики (FriendLI, NIM) имеют нестандартные конечные точки модели.
+
+**Как OmniRoute решает эту проблему:**
+
+- **Единая конечная точка** — один `http://localhost:20128/v1` служит прокси для всех 36+ провайдеров.
+- **Перевод формата** — Автоматический и прозрачный: OpenAI ↔ Claude ↔ Gemini ↔ API ответов
+- **Очистка ответов** — удаляются нестандартные поля (`x_groq`, `usage_breakdown`, `service_tier`), которые нарушают OpenAI SDK v1.83+.
+- **Нормализация ролей** — преобразует `developer` в `system` для поставщиков, не поддерживающих OpenAI; `system` → `user` для GLM/ERNIE
+- **Think Tag Extraction** — извлекает блоки `<think>` из таких моделей, как DeepSeek R1, в стандартизированный `reasoning_content`.
+- **Структурированный вывод для Gemini** — автоматическое преобразование `json_schema` → `responseMimeType`/`responseSchema`.
+- **`stream` по умолчанию — `false`** — соответствует спецификации OpenAI, что позволяет избежать неожиданного SSE в SDK Python/Rust/Go.
+
+</details>
+
+<details>
+<summary><b>🌐 3. «Мой провайдер ИИ блокирует мой регион/страну» </b></summary>
+
+Такие провайдеры, как OpenAI/Codex, блокируют доступ из определенных географических регионов. Пользователи получают ошибки типа `unsupported_country_region_territory` во время подключений OAuth и API. Особенно это расстраивает разработчиков из развивающихся стран.
+
+**Как OmniRoute решает эту проблему:**
+
+- **3-уровневая конфигурация прокси** — настраиваемый прокси-сервер на трех уровнях: глобальный (весь трафик), для каждого провайдера (только один провайдер) и для каждого соединения/ключа.
+- **Значки прокси с цветной кодировкой** — Визуальные индикаторы: 🟢 глобальный прокси, 🟡 прокси-сервер провайдера, 🔵 прокси-сервер подключения, всегда показывающий IP-адрес.
+- **Обмен токенов OAuth через прокси** — поток OAuth также проходит через прокси, решая проблему `unsupported_country_region_territory`.
+- **Тесты подключения через прокси** — тесты подключения используют настроенный прокси-сервер (прямого обхода больше нет)
+- **Поддержка SOCKS5** — Полная поддержка прокси-сервера SOCKS5 для исходящей маршрутизации.
+- **Подмена отпечатка пальца TLS** — отпечаток TLS, подобный браузеру, через `wreq-js` для обхода обнаружения ботов.
+
+</details>
+
+<details>
+<summary><b>🆓 4. «Я хочу использовать ИИ для кодирования, но у меня нет денег» </b></summary>
+
+Не каждый может платить 20–200 долларов в месяц за подписку на ИИ. Студентам, разработчикам из развивающихся стран, любителям и фрилансерам нужен доступ к качественным моделям по нулевой цене.
+
+**Как OmniRoute решает эту проблему:**
+
+- **Встроенные провайдеры уровня бесплатного пользования** — Встроенная поддержка 100% бесплатных провайдеров: iFlow (8 моделей с неограниченным количеством пользователей), Qwen (3 модели с неограниченным количеством пользователей), Kiro (Claude бесплатно), Gemini CLI (180 тысяч в месяц бесплатно).
+- **Комбинации только бесплатно** — цепочка `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 долларов США в месяц без простоев.
+- **Бесплатные кредиты NVIDIA NIM** — интегрировано 1000 бесплатных кредитов.
+- **Стратегия оптимизации затрат** — стратегия маршрутизации, которая автоматически выбирает самого дешевого доступного провайдера.
+
+</details>
+
+<details>
+<summary><b>🔒 5. «Мне нужно защитить мой AI-шлюз от несанкционированного доступа» </b></summary>
+
+При предоставлении доступа к сети AI-шлюза (LAN, VPS, Docker) любой, у кого есть адрес, может использовать токены/квоту разработчика. Без защиты API уязвимы для неправильного использования, быстрого внедрения и злоупотреблений.
+
+**Как OmniRoute решает эту проблему:**
+
+- **Управление ключами API** — генерация, ротация и определение области действия для каждого поставщика с помощью специальной страницы `/dashboard/api-manager`.
+- **Разрешения на уровне модели** — Ограничьте использование ключей API определенными моделями (`openai/*`, шаблоны подстановочных знаков) с помощью переключателя Разрешить все/Ограничить.
+- **API Endpoint Protection** — требует ключ для `/v1/models` и блокирует определенных поставщиков из списка.
+- **Auth Guard + защита CSRF** — все маршруты информационной панели защищены промежуточным программным обеспечением `withAuth` + токенами CSRF.
+- **Ограничитель скорости** — ограничение скорости для каждого IP с помощью настраиваемых окон.
+- **IP-фильтрация** — список разрешенных/блокированных для контроля доступа.
+- **Prompt Injection Guard** — очистка от вредоносных шаблонов подсказок.
+- **Шифрование AES-256-GCM** — неактивные учетные данные зашифрованы.
+
+</details>
+
+<details>
+<summary><b>🛑 6. «Мой провайдер вышел из строя, и я потерял процесс кодирования» </b></summary>
+
+Поставщики ИИ могут работать нестабильно, возвращать ошибки 5xx или достигать временных ограничений скорости. Если разработчик зависит от одного провайдера, его работу прерывают. Без автоматических выключателей повторные попытки могут привести к сбою приложения.
+
+**Как OmniRoute решает эту проблему:**
+
+- **Выключатель для каждого поставщика** — автоматическое открытие/закрытие с настраиваемыми пороговыми значениями и временем восстановления (закрыто/открыто/полуоткрыто).
+- **Экспоненциальная задержка** – прогрессивная задержка повторных попыток.
+- **Anti-Thundering Herd** — Мьютекс + защита семафора от одновременных штормов повторных попыток.
+- **Комбо-резервные цепочки** — в случае сбоя основного поставщика автоматически проходит через цепочку без вмешательства.
+- **Комбо-выключатель** — автоматически отключает неисправных поставщиков в комбинированной цепочке.
+- **Панель работоспособности** — мониторинг работоспособности, состояния автоматических выключателей, блокировки, статистика кэша, задержка p50/p95/p99.
+
+</details>
+
+<details>
+<summary><b>🔧 7. «Настройка каждого инструмента искусственного интеллекта утомительна и повторяется» </b></summary>
+
+Разработчики используют Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Для каждого инструмента требуется своя конфигурация (конечная точка API, ключ, модель). Перенастройка при смене провайдера или модели — пустая трата времени.
+
+**Как OmniRoute решает эту проблему:**
+
+- **Панель инструментов CLI** — выделенная страница с настройкой в один клик Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline.
+- **Генератор конфигураций GitHub Copilot** — генерирует `chatLanguageModels.json` для кода VS с массовым выбором модели.
+- **Мастер адаптации** — пошаговая пошаговая настройка для начинающих пользователей.
+- **Одна конечная точка, все модели** — настройте `http://localhost:20128/v1` один раз и получите доступ к более чем 36 поставщикам услуг.
+
+</details>
+
+<details>
+<summary><b>🔑 8. «Управление токенами OAuth от нескольких провайдеров — это ад» </b></summary>
+
+Claude Code, Codex, Gemini CLI, Copilot — все используют OAuth 2.0 с токенами с истекающим сроком действия. Разработчикам необходимо постоянно проходить повторную аутентификацию, иметь дело с `client_secret is missing`, `redirect_uri_mismatch` и сбоями на удаленных серверах. OAuth в LAN/VPS особенно проблематичен.
+
+**Как OmniRoute решает эту проблему:**
+
+- **Автоматическое обновление токенов** — токены OAuth обновляются в фоновом режиме до истечения срока их действия.
+- **Встроенный OAuth 2.0 (PKCE)** — автоматический поток для Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow.
+- **OAuth с несколькими учетными записями** – несколько учетных записей для каждого провайдера посредством извлечения токена JWT/ID.
+- **OAuth LAN/Remote Fix** — обнаружение частного IP-адреса для `redirect_uri` + ручной режим URL-адреса для удаленных серверов.
+- **OAuth за Nginx** — использует `window.location.origin` для совместимости с обратным прокси-сервером.
+- **Руководство по удаленному OAuth** — пошаговое руководство по учетным данным Google Cloud на VPS/Docker.
+
+</details>
+
+<details>
+<summary><b>📊 9. «Я не знаю, сколько и куда я трачу» </b></summary>
+
+Разработчики используют нескольких платных поставщиков, но не имеют единого представления о расходах. У каждого провайдера есть своя панель выставления счетов, но единого представления нет. Неожиданные расходы могут накопиться.
+
+**Как OmniRoute решает эту проблему:**
+
+- **Панель анализа затрат** — отслеживание затрат на каждый токен и управление бюджетом для каждого поставщика.
+- **Ограничения бюджета на уровень** — потолок расходов на уровень, который запускает автоматический возврат к резервному варианту.
+- **Конфигурация цен на модель** — настраиваемые цены на модель.
+- **Статистика использования каждого ключа API** — количество запросов и временная метка последнего использования для каждого ключа.
+- **Панель аналитики** — карточки статистики, диаграмма использования модели, таблица поставщиков с показателями успеха и задержкой.
+
+</details>
+
+<details>
+<summary><b>🐛 10. «Я не могу диагностировать ошибки и проблемы в вызовах ИИ» </b></summary>
+
+Когда вызов завершается неудачей, разработчик не знает, было ли это ограничением скорости, сроком действия токена, неправильным форматом или ошибкой провайдера. Фрагментированные журналы на разных терминалах. Без наблюдаемости отладка осуществляется методом проб и ошибок.
+
+**Как OmniRoute решает эту проблему:**
+
+- **Панель управления унифицированными журналами** — 4 вкладки: журналы запросов, журналы прокси, журналы аудита, консоль.
+- **Консольный просмотр журнала** — просмотрщик в режиме терминала в режиме реального времени с уровнями с цветовой кодировкой, автоматической прокруткой, поиском и фильтрацией.
+- **Журналы прокси-сервера SQLite** — постоянные журналы, сохраняющиеся после перезапуска сервера.
+- **Площадка переводчика** — 4 режима отладки: Площадка (перевод формата), Тестер чата (туда и обратно), Тестовый стенд (пакетный), Мониторинг в реальном времени (в режиме реального времени).
+- **Запрос телеметрии** — задержка p50/p95/p99 + отслеживание X-Request-Id
+- **Журналирование на основе файлов с ротацией** — перехватчик консоли записывает все в журнал JSON с ротацией на основе размера.
+
+</details>
+
+<details>
+<summary><b>🏗️ 11. «Развертывание и обслуживание шлюза сложны» </b></summary>
+
+Установка, настройка и обслуживание прокси-сервера AI в различных средах (локальных, VPS, Docker, облаке) — трудоемкий процесс. Такие проблемы, как жестко запрограммированные пути, `EACCES` в каталогах, конфликты портов и кроссплатформенные сборки, добавляют проблем.
+
+**Как OmniRoute решает эту проблему:**
+
+- **глобальная установка npm** — `npm install -g omniroute && omniroute` — выполнено
+- **Мультиплатформенность Docker** — встроенная версия AMD64 + ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)
+- **Профили Docker Compose** — `base` (без инструментов CLI) и `cli` (с Claude Code, Codex, OpenClaw)
+- **Electron Desktop App** — собственное приложение для Windows/macOS/Linux с панелью задач, автозапуском и автономным режимом.
+- **Режим разделения портов** — API и панель мониторинга на отдельных портах для расширенных сценариев (обратный прокси-сервер, сеть контейнеров).
+- **Cloud Sync** — синхронизация конфигурации между устройствами через Cloudflare Workers.
+- **Резервные копии БД** — автоматическое резервное копирование, восстановление, экспорт и импорт всех настроек.
+
+</details>
+
+<details>
+<summary><b>🌍 12. «Интерфейс только на английском языке, и моя команда не говорит по-английски» </b></summary>
+
+Команды в неанглоязычных странах, особенно в Латинской Америке, Азии и Европе, испытывают трудности с интерфейсами только на английском языке. Языковые барьеры сокращают внедрение и увеличивают количество ошибок в конфигурации.
+
+**Как OmniRoute решает эту проблему:**
+
+- **Панель управления i18n — 30 языков** — Все более 500 клавиш переведены, включая арабский, болгарский, датский, немецкий, испанский, финский, французский, иврит, хинди, венгерский, индонезийский, итальянский, японский, корейский, малайский, голландский, норвежский, польский, португальский (PT/BR), румынский, русский, словацкий, шведский, тайский, украинский, вьетнамский, китайский, филиппинский, английский
+- **Поддержка RTL** — поддержка написания справа налево для арабского языка и иврита.
+- **Многоязычные файлы README** — 30 полных переводов документации.
+- **Выбор языка** — значок глобуса в заголовке для переключения в реальном времени.
+
+</details>
+
+<details>
+<summary><b>🔄 13. «Мне нужно больше, чем просто чат — мне нужны вложения, изображения, аудио»</b></summary>
+
+ИИ — это не просто завершение чата. Разработчикам необходимо генерировать изображения, расшифровывать аудио, создавать вложения для RAG, изменять ранжирование документов и модерировать контент. Каждый API имеет свою конечную точку и формат.
+
+**Как OmniRoute решает эту проблему:**
+
+- **Встраивания** — `/v1/embeddings` с 6 поставщиками и более чем 9 моделями.
+- **Генерация изображений** — `/v1/images/generations` с 10 поставщиками и более чем 20 моделями (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigradity, SD WebUI, ComfyUI)
+- **Преобразование текста в видео** — `/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/moderations` — Проверка безопасности контента.
+- **Реранжирование** — `/v1/rerank` — Изменение ранжирования релевантности документа.
+- **API ответов** — полная поддержка `/v1/responses` для Кодекса.
+
+</details>
+
+<details>
+<summary><b>🧪 14. «У меня нет возможности тестировать и сравнивать качество разных моделей» </b></summary>
+
+Разработчики хотят знать, какая модель лучше всего подходит для их варианта использования (код, перевод, рассуждения), но сравнивать вручную — это медленно. Интегрированных инструментов оценки не существует.
+
+**Как OmniRoute решает эту проблему:**
+
+- **Оценки LLM** — тестирование золотого набора с 10 предварительно загруженными вариантами, охватывающими приветствия, математику, географию, генерацию кода, соответствие JSON, перевод, уценку, отказ от безопасности.
+- **4 стратегии сопоставления** — `exact`, `contains`, `regex`, `custom` (функция JS)
+- **Тестовый стенд Translator Playground** — пакетное тестирование с несколькими входными данными и ожидаемыми результатами, сравнение между поставщиками.
+- **Тестер чата** — полный цикл с визуальным отображением ответов.
+- **Живой монитор** — поток всех запросов, проходящих через прокси, в реальном времени.
+
+</details>
+
+<details>
+<summary><b>📈 15. «Мне нужно масштабироваться без потери производительности» </b></summary>
+
+По мере роста объема запросов без кэширования одних и тех же вопросов возникают дублирующие затраты. Без идемпотентности дублирование запросов приводит к отходам обработки. Необходимо соблюдать ограничения по тарифам для каждого поставщика.
+
+**Как OmniRoute решает эту проблему:**
+
+- **Семантический кеш** — двухуровневый кеш (сигнатура + семантика) снижает стоимость и задержку.
+- **Request Idempotency** — окно дедупликации 5 с для идентичных запросов.
+- **Обнаружение ограничения скорости** — число оборотов в минуту для каждого провайдера, минимальный разрыв и максимальное одновременное отслеживание.
+- **Редактируемые ограничения скорости** — настраиваемые значения по умолчанию в меню «Настройки» → «Устойчивость с постоянством».
+- **Кэш проверки ключей API** — трехуровневый кеш для повышения производительности.
+- **Панель состояния с телеметрией** — задержка p50/p95/p99, статистика кэша, время безотказной работы.
+
+</details>
+
+<details>
+<summary><b>🤖 16. «Я хочу глобально контролировать поведение модели» </b></summary>
+
+Разработчики, которым нужны все ответы на определенном языке, с определенным тоном или которые хотят ограничить количество токенов рассуждения. Настраивать это в каждом инструменте/запросе непрактично.
+
+**Как OmniRoute решает эту проблему:**
+
+- **Внедрение системных подсказок** — глобальное приглашение применяется ко всем запросам.
+- **Продуманная проверка бюджета** — контроль распределения токенов для каждого запроса (сквозной, автоматический, пользовательский, адаптивный)
+- **6 стратегий маршрутизации** — глобальные стратегии, определяющие распределение запросов.
+- **Маршрутизатор с подстановочными знаками** — шаблоны `provider/*` динамически маршрутизируются к любому поставщику.
+- **Переключение/включение комбо** — переключение комбо непосредственно с панели управления.
+- **Переключение поставщика** — включение/отключение всех подключений к провайдеру одним щелчком мыши.
+- **Заблокированные поставщики** — исключить определенных поставщиков из списка `/v1/models`.
+
+</details>
+
+<details>
+<summary><b>🧰 17. «Мне нужны инструменты MCP как первоклассные возможности продукта» </b></summary>
+
+Многие шлюзы AI предоставляют MCP только как скрытую деталь реализации. Командам нужен видимый и управляемый операционный уровень.
+
+**Как OmniRoute решает эту проблему:**
+
+- MCP отображается на панели навигации панели управления и на вкладке протокола конечной точки.
+- Отдельная страница управления MCP с процессами, инструментами, объемами работ и аудитом.
+- Встроенное краткое руководство по `omniroute --mcp` и адаптации клиентов.
+
+</details>
+
+<details>
+<summary><b>🧠 18. «Мне нужна оркестровка A2A с путями задач синхронизации и потоковой передачи» </b></summary>
+
+Рабочие процессы агента требуют как прямых ответов, так и длительного потокового выполнения с контролем жизненного цикла.
+
+**Как OmniRoute решает эту проблему:**
+
+- Конечная точка A2A JSON-RPC (`POST /a2a`) с `message/send` и `message/stream`.
+- Потоковая передача SSE с распространением состояния терминала
+- API жизненного цикла задач для `tasks/get` и `tasks/cancel`.
+
+</details>
+
+<details>
+<summary><b>🛰️ 19. «Мне нужно реальное состояние процесса MCP, а не угаданный статус» </b></summary>
+
+Оперативным группам необходимо знать, действительно ли MCP работает, а не только доступен ли API.
+
+**Как OmniRoute решает эту проблему:**
+
+- Файл контрольного сигнала времени выполнения с PID, временными метками, транспортом, количеством инструментов и режимом области действия.
+- API статуса MCP, объединяющий пульс + недавнюю активность
+- Карты состояния пользовательского интерфейса для актуальности процессов, времени безотказной работы и пульса.
+
+</details>
+
+<details>
+<summary><b>📋 20. «Мне нужно проверяемое выполнение инструмента MCP» </b></summary>
+
+Когда инструменты изменяют конфигурацию или запускают действия операционной системы, командам необходима судебно-медицинская отслеживаемость.
+
+**Как OmniRoute решает эту проблему:**
+
+- Ведение журнала аудита на основе SQLite для вызовов инструментов MCP.
+- Фильтры по инструменту, успеху/неуспеху, ключу API и нумерации страниц.
+- Таблица аудита панели мониторинга + конечные точки статистики для автоматизации
+
+</details>
+
+<details>
+<summary><b>🔐 21. «Мне нужны ограниченные разрешения MCP для каждой интеграции» </b></summary>
+
+Разные клиенты должны иметь минимальный доступ к категориям инструментов.
+
+**Как OmniRoute решает эту проблему:**
+
+- 9 детальных областей MCP для контролируемого доступа к инструментам
+- Обеспечение соблюдения границ и видимость в пользовательском интерфейсе управления MCP.
+- Безопасное положение по умолчанию для рабочих инструментов.
+
+</details>
+
+<details>
+<summary><b>⚙️ 22. «Мне нужен оперативный контроль без передислокации» </b></summary>
+
+Командам необходимы быстрые изменения во время выполнения во время инцидентов или событий, связанных с затратами.
+
+**Как OmniRoute решает эту проблему:**
+
+- Переключение комбо-активации прямо с панели управления MCP.
+- Применение профилей устойчивости из предварительно определенных пакетов политик.
+- Сброс состояния автоматического выключателя с той же панели управления.
+
+</details>
+
+<details>
+<summary><b>🔄 23. «Мне нужна оперативная видимость и отмена жизненного цикла задачи A2A» </b></summary>
+
+Без прозрачности жизненного цикла инциденты с задачами становится трудно сортировать.
+
+**Как OmniRoute решает эту проблему:**
+
+- Список задач/фильтрация по состоянию/навыку с нумерацией страниц
+- Детализация метаданных задачи, событий и артефактов.
+- Конечная точка отмены задачи и действие пользовательского интерфейса с подтверждением.
+
+</details>
+
+<details>
+<summary><b>🌊 24. «Мне нужны метрики активного потока для загрузки A2A» </b></summary>
+
+Рабочие процессы потоковой передачи требуют оперативного понимания параллелизма и живых соединений.
+
+**Как OmniRoute решает эту проблему:**
+
+- Счетчики активных потоков интегрированы в статус A2A
+- Временная метка последней задачи и количество состояний
+- Карты информационной панели A2A для мониторинга операций в реальном времени.
+
+</details>
+
+<details>
+<summary><b>🪪 25. «Мне нужно стандартное обнаружение агента для клиентов» </b></summary>
+
+Внешним клиентам и оркестраторам для адаптации необходимы машиночитаемые метаданные.
+
+**Как OmniRoute решает эту проблему:**
+
+- Карта агента открыта по адресу `/.well-known/agent.json`.
+- Возможности и навыки, отображаемые в пользовательском интерфейсе управления.
+- API статуса A2A включает метаданные обнаружения для автоматизации.
+
+</details>
+
+<details>
+<summary><b>🧭 26. «Мне нужна возможность обнаружения протокола в UX продукта» </b></summary>
+
+Если пользователи не могут обнаружить поверхности протокола, качество внедрения и поддержки снижается.
+
+**Как OmniRoute решает эту проблему:**
+
+- Записи на боковой панели для MCP и A2A.
+- Вкладка «Протоколы» на странице конечной точки с быстрым запуском и статусом.
+- Ссылки из обзора на специальные панели управления.
+
+</details>
+
+<details>
+<summary><b>🧪 27. «Мне нужна сквозная проверка протокола с реальными клиентами» </b></summary>
+
+Пробных тестов недостаточно для проверки совместимости протокола перед выпуском.
+
+**Как OmniRoute решает эту проблему:**
+
+- Пакет E2E, который загружает приложение и использует настоящий клиентский транспорт MCP SDK.
+- Клиент A2A тестирует потоки обнаружения, отправки, потоковой передачи, получения и отмены.
+- Перекрестная проверка утверждений с помощью API-интерфейсов аудита MCP и задач A2A.
+
+</details>
+
+<details>
+<summary><b>📡 28. «Мне нужна унифицированная наблюдаемость на всех интерфейсах» </b></summary>
+
+Разделение наблюдаемости по протоколам создает «слепые зоны» и увеличивает MTTR.
+
+**Как OmniRoute решает эту проблему:**
+
+- Унифицированные дашборды/логи/аналитика в одном продукте
+- Здоровье + аудит + телеметрия запросов на уровнях OpenAI, MCP и A2A.
+- Операционные API для статуса и автоматизации
+
+</details>
+
+<details>
+<summary><b>💼 29. «Мне нужна одна среда выполнения для прокси + инструментов + оркестровки агентов» </b></summary>
+
+Запуск множества отдельных служб увеличивает эксплуатационные расходы и количество видов сбоев.
+
+**Как OmniRoute решает эту проблему:**
+
+- OpenAI-совместимый прокси, сервер MCP и сервер A2A в одном стеке
+- Общая аутентификация, устойчивость, хранилище данных и наблюдаемость.
+- Согласованная модель политики на всех поверхностях взаимодействия.
+
+</details>
+
+<details>
+<summary><b>🚀 30. «Мне нужно реализовать агентские рабочие процессы без разрастания связующего кода» </b></summary>
+
+Команды теряют скорость при объединении нескольких специальных сервисов и сценариев.
+
+**Как OmniRoute решает эту проблему:**
+
+- Единая стратегия конечных точек для клиентов и агентов
+- Встроенные пользовательские интерфейсы управления протоколами и пути проверки дыма.
+- Готовые к работе основы (безопасность, ведение журналов, отказоустойчивость, резервное копирование)
+
+</details>
+
+### Примеры сборников сценариев (интегрированные варианты использования)
+
+**Пособие А: максимальное использование платной подписки + дешевое резервное копирование**
+
+```txt
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6
+  2. glm/glm-4.7
+  3. if/kimi-k2-thinking
+
+Monthly cost: $20 + small backup spend
+Outcome: higher quality, near-zero interruption
+```
+
+**Пособие Б: стек кодирования с нулевой стоимостью**
+
+```txt
+Combo: "free-forever"
+  1. gc/gemini-3-flash
+  2. if/kimi-k2-thinking
+  3. qw/qwen3-coder-plus
+
+Monthly cost: $0
+Outcome: stable free coding workflow
+```
+
+**Пособие C: Всегда работающая резервная цепочка 24 часа в сутки, 7 дней в неделю**
+
+```txt
+Combo: "always-on"
+  1. cc/claude-opus-4-6
+  2. cx/gpt-5.2-codex
+  3. glm/glm-4.7
+  4. minimax/MiniMax-M2.1
+  5. if/kimi-k2-thinking
+
+Outcome: deep fallback depth for deadline-critical workloads
+```
+
+**Сборник D: Операции агента с помощью MCP + A2A**
+
+```txt
+1) Start MCP transport (`omniroute --mcp`) for tool-driven operations
+2) Run A2A tasks via `message/send` and `message/stream`
+3) Observe via /dashboard/mcp and /dashboard/a2a
+4) Control incidents with resilience profile + task cancellation
+```
+
+---
+
 ## ⚡ Быстрый старт
 
 **1. Установите глобально:**
@@ -247,6 +779,30 @@ docker compose --profile cli up -d
 
 ---
 
+---
+
+## 🖥️
+
+> 🆕 **НОВИНКА!** OmniRoute теперь доступен как **нативное настольное приложение** для Windows, macOS и Linux.
+
+- 🖥️ **Нативное Окно** — Выделенное окно с интеграцией в системный трей
+- 🔄 **Автозапуск** — Запуск OmniRoute при входе в систему
+- 🔔 **Нативные Уведомления** — Оповещения об исчерпании квоты
+- ⚡ **Установка в Один Клик** — NSIS (Windows), DMG (macOS), AppImage (Linux)
+- 🌐 **Оффлайн Режим** — Полностью работает без интернета
+
+```bash
+npm run electron:dev           # Режим разработки
+npm run electron:build         # Текущая платформа
+npm run electron:build:win     # Windows (.exe)
+npm run electron:build:mac     # macOS (.dmg)
+npm run electron:build:linux   # Linux (.AppImage)
+```
+
+📖 Полная документация: [`electron/README.md`](electron/README.md)
+
+---
+
 ## 💰 Обзор цен
 
 | Tier              | Провайдер         | Стоимость                     | Сброс квоты        | Лучше всего для                  |
@@ -272,67 +828,6 @@ docker compose --profile cli up -d
 
 ---
 
-## 🎯 Сценарии использования
-
-### Сценарий 1: «У меня подписка Claude Pro»
-
-**Проблема:** Квота истекает неиспользованной, лимиты скорости во время интенсивного программирования
-
-```
-Combo: "maximize-claude"
-  1. cc/claude-opus-4-6        (используйте подписку полностью)
-  2. glm/glm-4.7               (дешёвый бэкап при исчерпании квоты)
-  3. if/kimi-k2-thinking       (бесплатный аварийный fallback)
-
-Месячная стоимость: $20 (подписка) + ~$5 (бэкап) = $25 итого
-vs. $20 + упирание в лимиты = разочарование
-```
-
-### Сценарий 2: «Хочу нулевую стоимость»
-
-**Проблема:** Не может позволить подписки, нужен надёжный AI для программирования
-
-```
-Combo: "free-forever"
-  1. gc/gemini-3-flash         (180K бесплатно/мес)
-  2. if/kimi-k2-thinking       (неограниченно бесплатно)
-  3. qw/qwen3-coder-plus       (неограниченно бесплатно)
-
-Месячная стоимость: $0
-Качество: Модели готовые к продакшену
-```
-
-### Сценарий 3: «Мне нужно программировать 24/7, без перерывов»
-
-**Проблема:** Дедлайны, не может позволить простой
-
-```
-Combo: "always-on"
-  1. cc/claude-opus-4-6        (лучшее качество)
-  2. cx/gpt-5.2-codex          (вторая подписка)
-  3. glm/glm-4.7               (дешёвый, ежедневный сброс)
-  4. minimax/MiniMax-M2.1      (самый дешёвый, сброс 5ч)
-  5. if/kimi-k2-thinking       (бесплатно неограниченно)
-
-Результат: 5 уровней fallback = нулевой простой
-```
-
-### Сценарий 4: «Хочу БЕСПЛАТНЫЙ AI в OpenClaw»
-
-**Проблема:** Нужен AI-ассистент в мессенджерах, полностью бесплатно
-
-```
-Combo: "openclaw-free"
-  1. if/glm-4.7                (неограниченно бесплатно)
-  2. if/minimax-m2.1           (неограниченно бесплатно)
-  3. if/kimi-k2-thinking       (неограниченно бесплатно)
-
-Месячная стоимость: $0
-Доступ через: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-```
-
----
-
 ## 💡 Основные функции
 
 ### 🧠 Маршрутизация и интеллект
@@ -348,6 +843,8 @@ Combo: "openclaw-free"
 | 🧩 **Пользовательские модели**              | Добавьте любой ID модели к любому провайдеру                                  |
 | 🌐 **Wildcard-маршрутизатор**               | Маршрутизируйте паттерны `provider/*` к любому провайдеру динамически         |
 | 🧠 **Бюджет рассуждений**                   | Режимы passthrough, auto, custom и adaptive для моделей рассуждений           |
+| 🔀 **Model Aliases**                        | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
+| ⚡ **Background Degradation**               | Auto-route background tasks (titles, summaries) to cheaper models             |
 | 💬 **Инъекция System Prompt**               | Глобальный system prompt для всех запросов                                    |
 | 📄 **API Responses**                        | Полная поддержка OpenAI Responses API (`/v1/responses`) для Codex             |
 
@@ -364,15 +861,18 @@ Combo: "openclaw-free"
 
 ### 🛡️ Устойчивость и безопасность
 
-| Функция                          | Что делает                                                     |
-| -------------------------------- | -------------------------------------------------------------- |
-| 🔌 **Circuit Breaker**           | Авто-открытие/закрытие по провайдеру с настраиваемыми порогами |
-| 🛡️ **Anti-Thundering Herd**      | Mutex + семафор для API key провайдеров                        |
-| 🧠 **Семантический кеш**         | Двухуровневый кеш (сигнатура + семантика) снижает стоимость    |
-| ⚡ **Идемпотентность запросов**  | 5с окно дедупликации для дублирующихся запросов                |
-| 🔒 **Спуфинг TLS Fingerprint**   | Обход обнаружения ботов через wreq-js                          |
-| 🌐 **Фильтрация IP**             | Allowlist/blocklist для контроля доступа к API                 |
-| 📊 **Настраиваемые Rate Limits** | Настраиваемые RPM, минимальный интервал, макс. конкуррентность |
+| Функция                          | Что делает                                                                   |
+| -------------------------------- | ---------------------------------------------------------------------------- |
+| 🔌 **Circuit Breaker**           | Авто-открытие/закрытие по провайдеру с настраиваемыми порогами               |
+| 🎯 **Endpoint-Aware Models**     | Custom models declare supported endpoints + API format                       |
+| 🛡️ **Anti-Thundering Herd**      | Mutex + семафор для API key провайдеров                                      |
+| 🧠 **Семантический кеш**         | Двухуровневый кеш (сигнатура + семантика) снижает стоимость                  |
+| ⚡ **Идемпотентность запросов**  | 5с окно дедупликации для дублирующихся запросов                              |
+| 🔒 **Спуфинг TLS Fingerprint**   | Обход обнаружения ботов через wreq-js                                        |
+| 🌐 **Фильтрация IP**             | Allowlist/blocklist для контроля доступа к API                               |
+| 📊 **Настраиваемые Rate Limits** | Настраиваемые RPM, минимальный интервал, макс. конкуррентность               |
+| 💾 **Rate Limit Persistence**    | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
+| 🔄 **Token Refresh Resilience**  | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt       |
 
 ### 📊 Наблюдаемость и аналитика
 
@@ -472,6 +972,27 @@ Combo: "my-coding-stack"
 
 </details>
 
+## 🧪 Оценки (Evals)
+
+OmniRoute включает встроенный фреймворк оценки для тестирования качества ответов LLM по golden set. Доступ через **Analytics → Evals** в dashboard.
+
+### Встроенный Set
+
+Предзагруженный «OmniRoute Golden Set» содержит 10 тестов:
+
+- Приветствия, математика, география, генерация кода
+- Соответствие формату JSON, перевод, markdown
+- Отказ от небезопасного контента, подсчёт, булева логика
+
+### Стратегии оценки
+
+| Стратегия  | Описание                                              | Пример                           |
+| ---------- | ----------------------------------------------------- | -------------------------------- |
+| `exact`    | Вывод должен совпадать точно                          | `"4"`                            |
+| `contains` | Вывод должен содержать подстроку (без учёта регистра) | `"Paris"`                        |
+| `regex`    | Вывод должен соответствовать regex-паттерну           | `"1.*2.*3"`                      |
+| `custom`   | Пользовательская JS-функция возвращает true/false     | `(output) => output.length > 10` |
+
 ---
 
 ## 📖 Руководство по настройке
@@ -754,97 +1275,6 @@ Dashboard → CLI Tools → OpenClaw → Выбрать модель → При
 
 ---
 
-## 📊 Доступные модели
-
-<details>
-<summary><b>Посмотреть все доступные модели</b></summary>
-
-**Claude Code (`cc/`)** - Pro/Max:
-
-- `cc/claude-opus-4-6`
-- `cc/claude-sonnet-4-5-20250929`
-- `cc/claude-haiku-4-5-20251001`
-
-**Codex (`cx/`)** - Plus/Pro:
-
-- `cx/gpt-5.2-codex`
-- `cx/gpt-5.1-codex-max`
-
-**Gemini CLI (`gc/`)** - БЕСПЛАТНО:
-
-- `gc/gemini-3-flash-preview`
-- `gc/gemini-2.5-pro`
-
-**GitHub Copilot (`gh/`)**:
-
-- `gh/gpt-5`
-- `gh/claude-4.5-sonnet`
-
-**NVIDIA NIM (`nvidia/`)** - БЕСПЛАТНЫЕ кредиты:
-
-- `nvidia/llama-3.3-70b-instruct`
-- `nvidia/mistral-7b-instruct`
-- 50+ моделей на [build.nvidia.com](https://build.nvidia.com)
-
-**GLM (`glm/`)** - $0.6/1M:
-
-- `glm/glm-4.7`
-
-**MiniMax (`minimax/`)** - $0.2/1M:
-
-- `minimax/MiniMax-M2.1`
-
-**iFlow (`if/`)** - БЕСПЛАТНО:
-
-- `if/kimi-k2-thinking`
-- `if/qwen3-coder-plus`
-- `if/deepseek-r1`
-- `if/glm-4.7`
-- `if/minimax-m2`
-
-**Qwen (`qw/`)** - БЕСПЛАТНО:
-
-- `qw/qwen3-coder-plus`
-- `qw/qwen3-coder-flash`
-
-**Kiro (`kr/`)** - БЕСПЛАТНО:
-
-- `kr/claude-sonnet-4.5`
-- `kr/claude-haiku-4.5`
-
-**OpenRouter (`or/`)** - 100+ моделей:
-
-- `or/anthropic/claude-4-sonnet`
-- `or/google/gemini-2.5-pro`
-- Любая модель с [openrouter.ai/models](https://openrouter.ai/models)
-
-</details>
-
----
-
-## 🧪 Оценки (Evals)
-
-OmniRoute включает встроенный фреймворк оценки для тестирования качества ответов LLM по golden set. Доступ через **Analytics → Evals** в dashboard.
-
-### Встроенный Golden Set
-
-Предзагруженный «OmniRoute Golden Set» содержит 10 тестов:
-
-- Приветствия, математика, география, генерация кода
-- Соответствие формату JSON, перевод, markdown
-- Отказ от небезопасного контента, подсчёт, булева логика
-
-### Стратегии оценки
-
-| Стратегия  | Описание                                              | Пример                           |
-| ---------- | ----------------------------------------------------- | -------------------------------- |
-| `exact`    | Вывод должен совпадать точно                          | `"4"`                            |
-| `contains` | Вывод должен содержать подстроку (без учёта регистра) | `"Paris"`                        |
-| `regex`    | Вывод должен соответствовать regex-паттерну           | `"1.*2.*3"`                      |
-| `custom`   | Пользовательская JS-функция возвращает true/false     | `(output) => output.length > 10` |
-
----
-
 ## 🐛 Устранение неполадок
 
 <details>
@@ -900,7 +1330,7 @@ OmniRoute включает встроенный фреймворк оценки
 
 ---
 
-## 🛠️ Технологический стек
+## 🛠️
 
 - **Runtime**: Node.js 20+
 - **Язык**: TypeScript 5.9 — **100% TypeScript** в `src/` и `open-sse/` (v1.0.6)
@@ -931,17 +1361,7 @@ OmniRoute включает встроенный фреймворк оценки
 
 ---
 
-## 📧 Поддержка
-
-> 💬 **Присоединяйтесь к сообществу!** [Группа WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Получайте помощь, делитесь советами и оставайтесь в курсе.
-
-- **Сайт**: [omniroute.online](https://omniroute.online)
-- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **WhatsApp**: [Группа сообщества](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Оригинальный проект**: [9router от decolua](https://github.com/decolua/9router)
-
----
+## 🗺️
 
 ## 👥 Участники
 

README.zh-CN.md

@@ -104,12 +104,41 @@ _通过 OmniRoute 连接任何 AI 驱动的 IDE 或 CLI 工具 — 免费 API
 
 [🌐 网站](https://omniroute.online) • [🚀 快速开始](#-快速开始) • [💡 功能特性](#-核心功能) • [📖 文档](#-文档) • [💰 定价](#-定价概览)
 
-🌐 **多语言版本：** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
+🌐 **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)
 
 </div>
 
 ---
 
+## 🖼️
+
+<div align="center">
+  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute" width="800"/>
+</div>
+
+---
+
+## 📸
+
+<details>
+<summary><b>...</b></summary>
+
+| #     | #                                        |
+| ----- | ---------------------------------------- |
+| **1** | ![1](docs/screenshots/01-providers.png)  |
+| **2** | ![2](docs/screenshots/02-combos.png)     |
+| **3** | ![3](docs/screenshots/03-analytics.png)  |
+| **4** | ![4](docs/screenshots/04-health.png)     |
+| **5** | ![5](docs/screenshots/05-translator.png) |
+| **6** | ![6](docs/screenshots/06-settings.png)   |
+| **7** | ![7](docs/screenshots/07-cli-tools.png)  |
+| **8** | ![8](docs/screenshots/08-usage.png)      |
+| **9** | ![9](docs/screenshots/09-endpoint.png)   |
+
+</details>
+
+---
+
 ## 🤔 为什么选择 OmniRoute？
 
 **停止浪费金钱和遭遇限制：**
@@ -128,6 +157,18 @@ _通过 OmniRoute 连接任何 AI 驱动的 IDE 或 CLI 工具 — 免费 API
 
 ---
 
+## 📧 支持
+
+> 💬 **加入我们的社区！** [WhatsApp 群组](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — 获取帮助、分享技巧、了解最新动态。
+
+- **网站**: [omniroute.online](https://omniroute.online)
+- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **WhatsApp**: [社区群组](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+- **原始项目**: [decolua 的 9router](https://github.com/decolua/9router)
+
+---
+
 ## 🔄 工作原理
 
 ```
@@ -157,6 +198,497 @@ _通过 OmniRoute 连接任何 AI 驱动的 IDE 或 CLI 工具 — 免费 API
 
 ---
 
+## 🎯 OmniRoute 解决了什么 — 30 个真正的痛点和用例
+
+> **每个使用 AI 工具的开发人员每天都会面临这些问题。** OmniRoute 的构建是为了解决所有这些问题 - 从成本超支到区域封锁，从损坏的 OAuth 流程到协议操作和企业可观察性。
+
+<details>
+<summary><b>💸 1.“我支付了昂贵的订阅费用，但仍然受到限制的干扰”</b></summary>
+
+开发人员每月为 Claude Pro、Codex Pro 或 GitHub Copilot 支付 20-200 美元。即使付费，配额也有上限——5 小时的使用时间、每周限制或每分钟的费率限制。在编码会话中，提供商停止响应，开发人员失去流量和生产力。
+
+**OmniRoute 如何解决：**
+
+- **智能 4 层回退** — 如果订阅配额用完，自动重定向到 API 密钥 → 便宜 → 免费，零手动干预
+- **实时配额跟踪** — 实时显示代币消耗情况并重置倒计时（5 小时、每日、每周）
+- **多帐户支持** — 每个提供商有多个帐户，具有自动循环 — 当一个帐户用完时，切换到下一个帐户
+- **自定义组合** — 可定制的后备链，具有 6 种平衡策略（先填充、循环、P2C、随机、最少使用、成本优化）
+- **Codex Business Quotas** — 直接在仪表板中监控业务/团队工作空间配额
+
+</details>
+
+<details>
+<summary><b>🔌 2.“我需要使用多个提供程序，但每个提供程序都有不同的 API”</b></summary>
+
+OpenAI 使用一种格式，Claude（Anthropic）使用另一种格式，Gemini 使用另一种格式。如果开发人员想要测试来自不同提供商的模型或在它们之间进行回退，他们需要重新配置 SDK、更改端点、处理不兼容的格式。自定义提供程序（FriendLI、NIM）具有非标准模型端点。
+
+**OmniRoute 如何解决：**
+
+- **统一端点** — 单个 `http://localhost:20128/v1` 充当所有 36 个以上提供商的代理
+- **格式翻译** — 自动且透明：OpenAI ↔ Claude ↔ Gemini ↔ Responses API
+- **响应清理** — 删除破坏 OpenAI SDK v1.83+ 的非标准字段（`x_groq`、`usage_breakdown`、`service_tier`）
+- **角色标准化** — 对于非 OpenAI 提供商，将 `developer` → `system` 转换； `system` → `user` 适用于 GLM/ERNIE
+- **Think Tag Extraction** — 将 DeepSeek R1 等模型中的 `<think>` 块提取为标准化 `reasoning_content`
+- **Gemini 的结构化输出** — `json_schema` → `responseMimeType`/`responseSchema` 自动转换
+- **`stream` 默认为 `false`** — 与 OpenAI 规范保持一致，避免 Python/Rust/Go SDK 中出现意外的 SSE
+
+</details>
+
+<details>
+<summary><b>🌐 3.“我的人工智能提供商封锁了我的地区/国家”</b></summary>
+
+OpenAI/Codex 等提供商会阻止来自某些地理区域的访问。用户在 OAuth 和 API 连接期间收到类似 `unsupported_country_region_territory` 的错误。这对于发展中国家的开发商来说尤其令人沮丧。
+
+**OmniRoute 如何解决：**
+
+- **3 级代理配置** — 3 级可配置代理：全局（所有流量）、每个提供商（仅一个提供商）和每个连接/密钥
+- **颜色编码的代理徽章** — 视觉指示器：🟢 全局代理、🟡 提供商代理、🔵 连接代理，始终显示 IP
+- **通过代理进行 OAuth 令牌交换** — OAuth 流程也通过代理，解决了 `unsupported_country_region_territory`
+- **通过代理进行连接测试** — 连接测试使用配置的代理（不再直接绕过）
+- **SOCKS5 支持** — 对出站路由的完整 SOCKS5 代理支持
+- **TLS 指纹欺骗** — 通过 `wreq-js` 的类似浏览器的 TLS 指纹来绕过机器人检测
+
+</details>
+
+<details>
+<summary><b>🆓 4.“我想用AI编码，但我没有钱”</b></summary>
+
+并不是每个人都能每月支付 20-200 美元来订阅 AI。来自新兴国家的学生、开发人员、业余爱好者和自由职业者需要以零成本获得优质模型。
+
+**OmniRoute 如何解决：**
+
+- **内置免费层级提供商** — 对 100% 免费提供商的本机支持：iFlow（8 个无限型号）、Qwen（3 个无限型号）、Kiro（Claude 免费）、Gemini CLI（180K/月免费）
+- **仅限免费组合** — 链 `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 美元/月，零停机时间
+- **NVIDIA NIM 免费积分** — 集成 1000 个免费积分
+- **成本优化策略** — 自动选择最便宜的可用提供商的路由策略
+
+</details>
+
+<details>
+<summary><b>🔒 5.“我需要保护我的AI网关免遭未经授权的访问”</b></summary>
+
+当将人工智能网关暴露到网络（LAN、VPS、Docker）时，任何拥有该地址的人都可以消耗开发者的代币/配额。如果没有保护，API 很容易被误用、提示注入和滥用。
+
+**OmniRoute 如何解决：**
+
+- **API 密钥管理** — 使用专用的 `/dashboard/api-manager` 页面为每个提供商生成、轮换和范围界定
+- **模型级权限** — 将 API 密钥限制为特定模型（`openai/*`、通配符模式），并具有“允许全部”/“限制”切换功能
+- **API 端点保护** — 需要 `/v1/models` 的密钥并阻止列表中的特定提供商
+- **Auth Guard + CSRF 保护** — 所有仪表板路由均受 `withAuth` 中间件 + CSRF 令牌保护
+- **速率限制器** — 通过可配置窗口限制每个 IP 的速率
+- **IP 过滤** — 用于访问控制的允许列表/阻止列表
+- **Prompt Injection Guard** — 针对恶意提示模式的清理
+- **AES-256-GCM 加密** — 静态加密的凭证
+
+</details>
+
+<details>
+<summary><b>🛑 6.“我的提供商宕机了，我失去了编码流程”</b></summary>
+
+AI 提供商可能会变得不稳定、返回 5xx 错误或达到临时速率限制。如果开发人员依赖于单一提供商，他们就会受到干扰。如果没有断路器，重复重试可能会使应用程序崩溃。
+
+**OmniRoute 如何解决：**
+
+- **每个提供商的断路器** — 自动打开/关闭，具有可配置的阈值和冷却时间（关闭/打开/半打开）
+- **指数退避** — 渐进式重试延迟
+- **Anti-Thundering Herd** — 互斥锁 + 信号量保护，防止并发重试风暴
+- **组合后备链** — 如果主要提供商发生故障，则自动从该链中掉下来，无需干预
+- **组合断路器** — 自动禁用组合链中出现故障的提供商
+- **运行状况仪表板** — 正常运行时间监控、断路器状态、锁定、缓存统计、p50/p95/p99 延迟
+
+</details>
+
+<details>
+<summary><b>🔧 7. “配置每个AI工具都是繁琐且重复的”</b></summary>
+
+开发人员使用 Cursor、Claude Code、Codex CLI、OpenClaw、Gemini CLI、Kilo Code...每个工具都需要不同的配置（API 端点、密钥、模型）。切换提供商或模型时重新配置是浪费时间。
+
+**OmniRoute 如何解决：**
+
+- **CLI 工具仪表板** — 专用页面，可一键设置 Claude Code、Codex CLI、OpenClaw、Kilo Code、Antigravity、Cline
+- **GitHub Copilot 配置生成器** — 通过批量模型选择为 VS Code 生成 `chatLanguageModels.json`
+- **入门向导** — 为首次使用的用户提供 4 步设置指导
+- **一个端点，所有型号** — 配置 `http://localhost:20128/v1` 一次，访问 36 个以上提供商
+
+</details>
+
+<details>
+<summary><b>🔑 8.“管理来自多个提供商的 OAuth 令牌简直就是地狱”</b></summary>
+
+Claude Code、Codex、Gemini CLI、Copilot — 全部使用带有过期令牌的 OAuth 2.0。开发人员需要不断地重新进行身份验证，处理`client_secret is missing`、`redirect_uri_mismatch`以及远程服务器上的故障。 LAN/VPS 上的 OAuth 问题尤其严重。
+
+**OmniRoute 如何解决：**
+
+- **自动令牌刷新** — OAuth 令牌在过期前在后台刷新
+- **OAuth 2.0 (PKCE) 内置** — Claude Code、Codex、Gemini CLI、Copilot、Kiro、Qwen、iFlow 的自动流程
+- **多帐户 OAuth** — 每个提供商通过 JWT/ID 令牌提取多个帐户
+- **OAuth LAN/远程修复** — `redirect_uri` 的私有 IP 检测 + 远程服务器的手动 URL 模式
+- **Nginx 背后的 OAuth** — 使用 `window.location.origin` 实现反向代理兼容性
+- **远程 OAuth 指南** — VPS/Docker 上的 Google Cloud 凭据分步指南
+
+</details>
+
+<details>
+<summary><b>📊 9.“我不知道我花了多少钱或在哪里”</b></summary>
+
+开发商使用多个付费提供商，但对支出没有统一的看法。每个提供商都有自己的计费仪表板，但没有统一的视图。意外的成本可能会不断增加。
+
+**OmniRoute 如何解决：**
+
+- **成本分析仪表板** — 每个提供商的每个代币成本跟踪和预算管理
+- **每层预算限制** — 触发自动回退的每层支出上限
+- **按型号定价配置** — 每个型号的可配置价格
+- **每个 API 密钥的使用统计信息** — 每个密钥的请求计数和上次使用的时间戳
+- **分析仪表板** — 统计卡、模型使用图表、包含成功率和延迟的提供商表
+
+</details>
+
+<details>
+<summary><b>🐛 10.“我无法诊断人工智能调用中的错误和问题”</b></summary>
+
+当调用失败时，开发人员不知道这是否是速率限制、令牌过期、格式错误或提供商错误。跨不同终端的碎片日志。如果没有可观察性，调试就是反复试验。
+
+**OmniRoute 如何解决：**
+
+- **统一日志仪表板** — 4 个选项卡：请求日志、代理日志、审核日志、控制台
+- **控制台日志查看器** — 实时终端式查看器，具有颜色编码级别、自动滚动、搜索、过滤功能
+- **SQLite 代理日志** — 服务器重新启动后仍保留的持久日志
+- **Translator Playground** — 4 种调试模式：Playground（格式翻译）、Chat Tester（往返）、Test Bench（批量）、Live Monitor（实时）
+- **请求遥测** — p50/p95/p99 延迟 + X-Request-Id 跟踪
+- **基于文件的日志记录与旋转** — 控制台拦截器通过基于大小的旋转将所有内容捕获到 JSON 日志
+
+</details>
+
+<details>
+<summary><b>🏗️ 11.“部署和维护网关很复杂”</b></summary>
+
+跨不同环境（本地、VPS、Docker、云）安装、配置和维护 AI 代理是一项劳动密集型工作。硬编码路径、目录上的 `EACCES`、端口冲突和跨平台构建等问题会增加摩擦。
+
+**OmniRoute 如何解决：**
+
+- **npm 全局安装** — `npm install -g omniroute && omniroute` — 完成
+- **Docker 多平台** — AMD64 + ARM64 本机（Apple Silicon、AWS Graviton、Raspberry Pi）
+- **Docker Compose Profiles** — `base`（无 CLI 工具）和 `cli`（带有 Claude Code、Codex、OpenClaw）
+- **Electron 桌面应用程序** — 适用于 Windows/macOS/Linux 的本机应用程序，带系统托盘、自动启动、离线模式
+- **分割端口模式** — API 和仪表板位于单独的端口上，适用于高级场景（反向代理、容器网络）
+- **云同步** — 通过 Cloudflare Workers 跨设备配置同步
+- **数据库备份** — 自动备份、恢复、导出和导入所有设置
+
+</details>
+
+<details>
+<summary><b>🌍 12.“界面只有英文，我的团队不会说英语”</b></summary>
+
+非英语国家的团队，尤其是拉丁美洲、亚洲和欧洲的团队，在纯英文界面上遇到了困难。语言障碍会降低采用率并增加配置错误。
+
+**OmniRoute 如何解决：**
+
+- **仪表板 i18n — 30 种语言** — 所有 500 多个按键已翻译，包括阿拉伯语、保加利亚语、丹麦语、德语、西班牙语、芬兰语、法语、希伯来语、印地语、匈牙利语、印度尼西亚语、意大利语、日语、韩语、马来语、荷兰语、挪威语、波兰语、葡萄牙语（PT/BR）、罗马尼亚语、俄语、斯洛伐克语、瑞典语、泰语、乌克兰语、越南语、中文、菲律宾语、英语
+- **RTL 支持** — 从右到左支持阿拉伯语和希伯来语
+- **多语言自述文件** — 30 个完整的文档翻译
+- **语言选择器** — 标题中的地球图标用于实时切换
+
+</details>
+
+<details>
+<summary><b>🔄 13.“我需要的不仅仅是聊天 - 我需要嵌入、图像、音频”</b></summary>
+
+人工智能不仅仅是完成聊天。开发人员需要生成图像、转录音频、为 RAG 创建嵌入、重新排列文档以及审核内容。每个 API 都有不同的端点和格式。
+
+**OmniRoute 如何解决：**
+
+- **嵌入** — `/v1/embeddings` 具有 6 个提供商和 9 个以上模型
+- **图像生成** — `/v1/images/generations` 具有 10 个提供商和 20 多个模型（OpenAI、xAI、Together、Fireworks、Nebius、Hyperbolic、NanoBanana、Antigravity、SD WebUI、ComfyUI）
+- **文本到视频** — `/v1/videos/generations` — ComfyUI（AnimateDiff、SVD）和 SD WebUI
+- **文本转音乐** — `/v1/music/generations` — ComfyUI（稳定音频打开，MusicGen）
+- **音频转录** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM、HuggingFace、Qwen3
+- **文本转语音** — `/v1/audio/speech` — ElevenLabs、Nvidia NIM、HuggingFace、Coqui、Tortoise、Qwen3 以及现有提供商
+- **审核** — `/v1/moderations` — 内容安全检查
+- **重新排名** — `/v1/rerank` — 文档相关性重新排名
+- **响应 API** — 对 Codex 的完整 `/v1/responses` 支持
+
+</details>
+
+<details>
+<summary><b>🧪 14.“我无法测试和比较不同型号的质量”</b></summary>
+
+开发人员想知道哪种模型最适合他们的用例（代码、翻译、推理），但手动比较速度很慢。不存在集成的评估工具。
+
+**OmniRoute 如何解决：**
+
+- **LLM 评估** — 黄金套装测试，包含 10 个预加载案例，涵盖问候语、数学、地理、代码生成、JSON 合规性、翻译、降价、安全拒绝
+- **4种匹配策略** — `exact`、`contains`、`regex`、`custom`（JS函数）
+- **Translator Playground 测试台** — 使用多个输入和预期输出进行批量测试、跨提供商比较
+- **聊天测试器** — 带有视觉响应渲染的完整往返
+- **实时监控** — 流经代理的所有请求的实时流
+
+</details>
+
+<details>
+<summary><b>📈 15.“我需要在不损失性能的情况下进行扩展”</b></summary>
+
+随着请求量的增长，如果不缓存相同的问题，就会产生重复的成本。如果没有幂等性，重复的请求就会浪费处理。必须遵守每个提供商的速率限制。
+
+**OmniRoute 如何解决：**
+
+- **语义缓存** - 两层缓存（签名+语义）降低成本和延迟
+- **请求幂等性** — 相同请求的 5 秒重复数据删除窗口
+- **速率限制检测** — 每个提供商的 RPM、最小间隙和最大并发跟踪
+- **可编辑的速率限制** — 可在“设置”→“持久弹性”中配置默认值
+- **API 密钥验证缓存** — 用于提高生产性能的 3 层缓存
+- **带有遥测功能的运行状况仪表板** — p50/p95/p99 延迟、缓存统计数据、正常运行时间
+
+</details>
+
+<details>
+<summary><b>🤖 16.“我想全局控制模型行为”</b></summary>
+
+希望所有响应都以特定语言、特定语气或想要限制推理标记的开发人员。在每个工具/请求中配置此功能是不切实际的。
+
+**OmniRoute 如何解决：**
+
+- **系统提示注入** — 全局提示应用于所有请求
+- **思考预算验证** - 每个请求的推理令牌分配控制（直通、自动、自定义、自适应）
+- **6 种路由策略** — 确定如何分发请求的全局策略
+- **通配符路由器** — `provider/*` 模式动态路由到任何提供商
+- **组合启用/禁用切换** — 直接从仪表板切换组合
+- **提供商切换** — 一键启用/禁用提供商的所有连接
+- **阻止的提供商** — 从 `/v1/models` 列表中排除特定提供商
+
+</details>
+
+<details>
+<summary><b>🧰 17.“我需要MCP工具作为一流的产品能力”</b></summary>
+
+许多 AI 网关仅将 MCP 作为隐藏的实现细节公开。团队需要一个可见的、可管理的操作层。
+
+**OmniRoute 如何解决：**
+
+- MCP 显示在仪表板导航和端点协议选项卡中
+- 专用 MCP 管理页面，包含流程、工具、范围和审计
+- `omniroute --mcp` 和客户入门的内置快速启动
+
+</details>
+
+<details>
+<summary><b>🧠 18.“我需要具有同步+流任务路径的 A2A 编排”</b></summary>
+
+代理工作流程需要直接回复和具有生命周期控制的长时间运行的流式执行。
+
+**OmniRoute 如何解决：**
+
+- A2A JSON-RPC 端点 (`POST /a2a`) 与 `message/send` 和 `message/stream`
+- 具有终端状态传播的 SSE 流式传输
+- `tasks/get` 和 `tasks/cancel` 的任务生命周期 API
+
+</details>
+
+<details>
+<summary><b>🛰️ 19.“我需要真实的 MCP 进程运行状况，而不是猜测的状态”</b></summary>
+
+运营团队需要知道 MCP 是否确实存在，而不仅仅是 API 是否可访问。
+
+**OmniRoute 如何解决：**
+
+- 带有 PID、时间戳、传输、工具计数和范围模式的运行时心跳文件
+- MCP状态API结合心跳+最近的活动
+- 用于流程/正常运行时间/心跳新鲜度的 UI 状态卡
+
+</details>
+
+<details>
+<summary><b>📋 20.“我需要可审核的 MCP 工具执行”</b></summary>
+
+当工具改变配置或触发操作操作时，团队需要取证可追溯性。
+
+**OmniRoute 如何解决：**
+
+- SQLite 支持的 MCP 工具调用审核日志记录
+- 按工具、成功/失败、API 密钥和分页过滤
+- 仪表板审核表+自动化统计端点
+
+</details>
+
+<details>
+<summary><b>🔐 21.“每次集成我都需要范围内的 MCP 权限”</b></summary>
+
+不同的客户端应该具有对工具类别的最低权限访问权限。
+
+**OmniRoute 如何解决：**
+
+- 9 个粒度 MCP 范围，用于受控工具访问
+- MCP 管理 UI 中的范围执行和可见性
+- 操作工具的安全默认姿势
+
+</details>
+
+<details>
+<summary><b>⚙️ 22.“我需要操作控制而不重新部署”</b></summary>
+
+团队需要在事件或成本事件期间快速更改运行时。
+
+**OmniRoute 如何解决：**
+
+- 直接从 MCP 仪表板切换组合激活
+- 应用预定义策略包中的弹性配置文件
+- 从同一操作面板重置断路器状态
+
+</details>
+
+<details>
+<summary><b>🔄 23.“我需要实时 A2A 任务生命周期可见性和取消”</b></summary>
+
+如果没有生命周期可见性，任务事件就很难分类。
+
+**OmniRoute 如何解决：**
+
+- 任务列表/按状态/技能过滤并分页
+- 深入了解任务元数据、事件和工件
+- 任务取消端点和带有确认的 UI 操作
+
+</details>
+
+<details>
+<summary><b>🌊 24.“我需要 A2A 负载的活动流指标”</b></summary>
+
+流媒体工作流程需要对并发和实时连接的操作洞察。
+
+**OmniRoute 如何解决：**
+
+- 活动流计数器集成到 A2A 状态中
+- 最后任务时间戳和每个状态计数
+- 用于实时操作监控的 A2A 仪表板卡
+
+</details>
+
+<details>
+<summary><b>🪪 25.“我需要为客户发现标准代理”</b></summary>
+
+外部客户端和协调器需要机器可读的元数据来进行引导。
+
+**OmniRoute 如何解决：**
+
+- 特工卡暴露在`/.well-known/agent.json`
+- 管理 UI 中显示的能力和技能
+- A2A 状态 API 包括用于自动化的发现元数据
+
+</details>
+
+<details>
+<summary><b>🧭 26.“我需要产品 UX 中的协议可发现性”</b></summary>
+
+如果用户无法发现协议表面，采用和支持质量就会下降。
+
+**OmniRoute 如何解决：**
+
+- MCP 和 A2A 的侧边栏条目
+- 端点页面“协议”选项卡包含快速启动和状态
+- 从概述到专用管理仪表板的链接
+
+</details>
+
+<details>
+<summary><b>🧪 27.“我需要与真实客户端进行端到端协议验证”</b></summary>
+
+模拟测试不足以在发布前验证协议兼容性。
+
+**OmniRoute 如何解决：**
+
+- E2E 套件，可启动应用程序并使用真正的 MCP SDK 客户端传输
+- A2A 客户端测试发现、发送、流式传输、获取和取消流程
+- 针对 MCP 审计和 A2A 任务 API 交叉检查断言
+
+</details>
+
+<details>
+<summary><b>📡 28.“我需要跨所有接口的统一可观察性”</b></summary>
+
+按协议分割可观察性会产生盲点和更长的 MTTR。
+
+**OmniRoute 如何解决：**
+
+- 一个产品中的统一仪表板/日志/分析
+- 跨 OpenAI、MCP 和 A2A 层的运行状况 + 审计 + 请求遥测
+- 用于状态和自动化的操作 API
+
+</details>
+
+<details>
+<summary><b>💼 29.“我需要一个用于代理+工具+代理编排的运行时”</b></summary>
+
+运行许多单独的服务会增加运营成本和故障模式。
+
+**OmniRoute 如何解决：**
+
+- 兼容 OpenAI 的代理、MCP 服务器和 A2A 服务器位于一个堆栈中
+- 共享身份验证、弹性、数据存储和可观察性
+- 所有交互界面上一致的策略模型
+
+</details>
+
+<details>
+<summary><b>🚀 30.“我需要在没有胶水代码蔓延的情况下交付代理工作流程”</b></summary>
+
+拼接多个临时服务和脚本时，团队会失去速度。
+
+**OmniRoute 如何解决：**
+
+- 客户端和代理的统一端点策略
+- 内置协议管理 UI 和烟雾验证路径
+- 生产就绪的基础（安全性、日志记录、弹性、备份）
+
+</details>
+
+### 示例手册（集成用例）
+
+**剧本 A：最大化付费订阅 + 廉价备份**
+
+```txt
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6
+  2. glm/glm-4.7
+  3. if/kimi-k2-thinking
+
+Monthly cost: $20 + small backup spend
+Outcome: higher quality, near-zero interruption
+```
+
+**剧本 B：零成本编码堆栈**
+
+```txt
+Combo: "free-forever"
+  1. gc/gemini-3-flash
+  2. if/kimi-k2-thinking
+  3. qw/qwen3-coder-plus
+
+Monthly cost: $0
+Outcome: stable free coding workflow
+```
+
+**剧本 C：24/7 始终在线的后备链**
+
+```txt
+Combo: "always-on"
+  1. cc/claude-opus-4-6
+  2. cx/gpt-5.2-codex
+  3. glm/glm-4.7
+  4. minimax/MiniMax-M2.1
+  5. if/kimi-k2-thinking
+
+Outcome: deep fallback depth for deadline-critical workloads
+```
+
+**剧本 D：使用 MCP + A2A 的特工操作**
+
+```txt
+1) Start MCP transport (`omniroute --mcp`) for tool-driven operations
+2) Run A2A tasks via `message/send` and `message/stream`
+3) Observe via /dashboard/mcp and /dashboard/a2a
+4) Control incidents with resilience profile + task cancellation
+```
+
+---
+
 ## ⚡ 快速开始
 
 **1. 全局安装：**
@@ -247,6 +779,30 @@ docker compose --profile cli up -d
 
 ---
 
+---
+
+## 🖥️
+
+> 🆕 **全新！** OmniRoute 现已提供适用于 Windows、macOS 和 Linux 的**原生桌面应用程序**。
+
+- 🖥️ **原生窗口** — 专属应用窗口，集成系统托盘
+- 🔄 **自动启动** — 系统登录时启动 OmniRoute
+- 🔔 **原生通知** — 配额耗尽或提供商问题时收到提醒
+- ⚡ **一键安装** — NSIS (Windows)、DMG (macOS)、AppImage (Linux)
+- 🌐 **离线模式** — 内置服务器，完全离线工作
+
+```bash
+npm run electron:dev           # 开发模式
+npm run electron:build         # 当前平台
+npm run electron:build:win     # Windows (.exe)
+npm run electron:build:mac     # macOS (.dmg)
+npm run electron:build:linux   # Linux (.AppImage)
+```
+
+📖 完整文档：[`electron/README.md`](electron/README.md)
+
+---
+
 ## 💰 定价概览
 
 | 层级           | 提供商            | 费用                  | 配额重置        | 最适合       |
@@ -272,84 +828,25 @@ docker compose --profile cli up -d
 
 ---
 
-## 🎯 使用场景
-
-### 场景 1："我有 Claude Pro 订阅"
-
-**问题：** 配额未使用就过期，编程高峰期遇到速率限制
-
-```
-Combo: "maximize-claude"
-  1. cc/claude-opus-4-6        （充分使用订阅）
-  2. glm/glm-4.7               （配额用完时的便宜备用）
-  3. if/kimi-k2-thinking       （免费应急后备）
-
-每月成本：$20（订阅）+ ~$5（备用）= $25 总计
-对比：$20 + 遇到限制 = 受挫
-```
-
-### 场景 2："我想要零成本"
-
-**问题：** 无法承担订阅费用，需要可靠的 AI 编程
-
-```
-Combo: "free-forever"
-  1. gc/gemini-3-flash         （每月 180K 免费）
-  2. if/kimi-k2-thinking       （无限免费）
-  3. qw/qwen3-coder-plus       （无限免费）
-
-每月成本：$0
-质量：生产级模型
-```
-
-### 场景 3："我需要 24/7 编程，不中断"
-
-**问题：** 截止日期紧迫，不能有停机时间
-
-```
-Combo: "always-on"
-  1. cc/claude-opus-4-6        （最佳质量）
-  2. cx/gpt-5.2-codex          （第二个订阅）
-  3. glm/glm-4.7               （便宜，每日重置）
-  4. minimax/MiniMax-M2.1      （最便宜，5小时重置）
-  5. if/kimi-k2-thinking       （免费无限制）
-
-结果：5 层故障转移 = 零停机
-```
-
-### 场景 4："我想在 OpenClaw 中使用免费 AI"
-
-**问题：** 需要在消息应用中使用 AI 助手，完全免费
-
-```
-Combo: "openclaw-free"
-  1. if/glm-4.7                （无限免费）
-  2. if/minimax-m2.1           （无限免费）
-  3. if/kimi-k2-thinking       （无限免费）
-
-每月成本：$0
-访问方式：WhatsApp、Telegram、Slack、Discord、iMessage、Signal...
-```
-
----
-
 ## 💡 核心功能
 
 ### 🧠 路由与智能
 
-| 功能                      | 功能描述                                                                   |
-| ------------------------- | -------------------------------------------------------------------------- |
-| 🎯 **智能 4 层故障转移**  | 自动路由：订阅 → API Key → 低价 → 免费                                     |
-| 📊 **实时配额追踪**       | 实时 Token 计数 + 每个提供商的重置倒计时                                   |
-| 🔄 **格式转换**           | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro 无缝切换                          |
-| 👥 **多账号支持**         | 每个提供商多个账号，智能选择                                               |
-| 🔄 **自动令牌刷新**       | OAuth 令牌自动刷新并重试                                                   |
-| 🎨 **自定义组合**         | 6 种策略：fill-first、round-robin、p2c、random、least-used、cost-optimized |
-| 🧩 **自定义模型**         | 为任何提供商添加任何模型 ID                                                |
-| 🌐 **通配符路由**         | 动态路由 `provider/*` 模式到任何提供商                                     |
-| 🧠 **推理预算**           | passthrough、auto、custom 和 adaptive 模式用于推理模型                     |
-| 💬 **System Prompt 注入** | 全局 System Prompt 应用于所有请求                                          |
-| 📄 **Responses API**      | 完整支持 OpenAI Responses API (`/v1/responses`) 用于 Codex                 |
+| 功能                          | 功能描述                                                                      |
+| ----------------------------- | ----------------------------------------------------------------------------- |
+| 🎯 **智能 4 层故障转移**      | 自动路由：订阅 → API Key → 低价 → 免费                                        |
+| 📊 **实时配额追踪**           | 实时 Token 计数 + 每个提供商的重置倒计时                                      |
+| 🔄 **格式转换**               | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro 无缝切换                             |
+| 👥 **多账号支持**             | 每个提供商多个账号，智能选择                                                  |
+| 🔄 **自动令牌刷新**           | OAuth 令牌自动刷新并重试                                                      |
+| 🎨 **自定义组合**             | 6 种策略：fill-first、round-robin、p2c、random、least-used、cost-optimized    |
+| 🧩 **自定义模型**             | 为任何提供商添加任何模型 ID                                                   |
+| 🌐 **通配符路由**             | 动态路由 `provider/*` 模式到任何提供商                                        |
+| 🧠 **推理预算**               | passthrough、auto、custom 和 adaptive 模式用于推理模型                        |
+| 🔀 **Model Aliases**          | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
+| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models             |
+| 💬 **System Prompt 注入**     | 全局 System Prompt 应用于所有请求                                             |
+| 📄 **Responses API**          | 完整支持 OpenAI Responses API (`/v1/responses`) 用于 Codex                    |
 
 ### 🎵 多模态 API
 
@@ -364,15 +861,17 @@ Combo: "openclaw-free"
 
 ### 🛡️ 弹性与安全
 
-| 功能                  | 功能描述                               |
-| --------------------- | -------------------------------------- |
-| 🔌 **断路器**         | 每个提供商自动打开/关闭，可配置阈值    |
-| 🛡️ **反惊群**         | Mutex + 信号量限速用于 API Key 提供商  |
-| 🧠 **语义缓存**       | 两层缓存（签名 + 语义）降低成本和延迟  |
-| ⚡ **请求幂等性**     | 5 秒去重窗口防止重复请求               |
-| 🔒 **TLS 指纹伪装**   | 通过 wreq-js 绕过基于 TLS 的机器人检测 |
-| 🌐 **IP 过滤**        | 白名单/黑名单用于 API 访问控制         |
-| 📊 **可编辑速率限制** | 可配置的 RPM、最小间隔和最大并发       |
+| 功能                            | 功能描述                                                                     |
+| ------------------------------- | ---------------------------------------------------------------------------- |
+| 🔌 **断路器**                   | 每个提供商自动打开/关闭，可配置阈值                                          |
+| 🛡️ **反惊群**                   | Mutex + 信号量限速用于 API Key 提供商                                        |
+| 🧠 **语义缓存**                 | 两层缓存（签名 + 语义）降低成本和延迟                                        |
+| ⚡ **请求幂等性**               | 5 秒去重窗口防止重复请求                                                     |
+| 🔒 **TLS 指纹伪装**             | 通过 wreq-js 绕过基于 TLS 的机器人检测                                       |
+| 🌐 **IP 过滤**                  | 白名单/黑名单用于 API 访问控制                                               |
+| 📊 **可编辑速率限制**           | 可配置的 RPM、最小间隔和最大并发                                             |
+| 💾 **Rate Limit Persistence**   | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
+| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt       |
 
 ### 📊 可观察性与分析
 
@@ -472,6 +971,27 @@ Combo: "my-coding-stack"
 
 </details>
 
+## 🧪 评估 (Evals)
+
+OmniRoute 包含内置评估框架，用于针对黄金集测试 LLM 响应质量。通过仪表板中的 **Analytics → Evals** 访问。
+
+### 内置黄金集
+
+预加载的「OmniRoute Golden Set」包含 10 个测试用例：
+
+- 问候、数学、地理、代码生成
+- JSON 格式合规性、翻译、markdown
+- 安全拒绝（有害内容）、计数、布尔逻辑
+
+### 评估策略
+
+| 策略       | 描述                             | 示例                             |
+| ---------- | -------------------------------- | -------------------------------- |
+| `exact`    | 输出必须完全匹配                 | `"4"`                            |
+| `contains` | 输出必须包含子串（不区分大小写） | `"Paris"`                        |
+| `regex`    | 输出必须匹配正则表达式模式       | `"1.*2.*3"`                      |
+| `custom`   | 自定义 JS 函数返回 true/false    | `(output) => output.length > 10` |
+
 ---
 
 ## 📖 设置指南
@@ -754,97 +1274,6 @@ codex "your prompt"
 
 ---
 
-## 📊 可用模型
-
-<details>
-<summary><b>查看所有可用模型</b></summary>
-
-**Claude Code (`cc/`)** - Pro/Max:
-
-- `cc/claude-opus-4-6`
-- `cc/claude-sonnet-4-5-20250929`
-- `cc/claude-haiku-4-5-20251001`
-
-**Codex (`cx/`)** - Plus/Pro:
-
-- `cx/gpt-5.2-codex`
-- `cx/gpt-5.1-codex-max`
-
-**Gemini CLI (`gc/`)** - 免费:
-
-- `gc/gemini-3-flash-preview`
-- `gc/gemini-2.5-pro`
-
-**GitHub Copilot (`gh/`)**:
-
-- `gh/gpt-5`
-- `gh/claude-4.5-sonnet`
-
-**NVIDIA NIM (`nvidia/`)** - 免费积分:
-
-- `nvidia/llama-3.3-70b-instruct`
-- `nvidia/mistral-7b-instruct`
-- 50+ 更多模型在 [build.nvidia.com](https://build.nvidia.com)
-
-**GLM (`glm/`)** - $0.6/1M:
-
-- `glm/glm-4.7`
-
-**MiniMax (`minimax/`)** - $0.2/1M:
-
-- `minimax/MiniMax-M2.1`
-
-**iFlow (`if/`)** - 免费:
-
-- `if/kimi-k2-thinking`
-- `if/qwen3-coder-plus`
-- `if/deepseek-r1`
-- `if/glm-4.7`
-- `if/minimax-m2`
-
-**Qwen (`qw/`)** - 免费:
-
-- `qw/qwen3-coder-plus`
-- `qw/qwen3-coder-flash`
-
-**Kiro (`kr/`)** - 免费:
-
-- `kr/claude-sonnet-4.5`
-- `kr/claude-haiku-4.5`
-
-**OpenRouter (`or/`)** - 100+ 模型:
-
-- `or/anthropic/claude-4-sonnet`
-- `or/google/gemini-2.5-pro`
-- [openrouter.ai/models](https://openrouter.ai/models) 上的任何模型
-
-</details>
-
----
-
-## 🧪 评估 (Evals)
-
-OmniRoute 包含内置评估框架，用于针对黄金集测试 LLM 响应质量。通过仪表板中的 **Analytics → Evals** 访问。
-
-### 内置黄金集
-
-预加载的「OmniRoute Golden Set」包含 10 个测试用例：
-
-- 问候、数学、地理、代码生成
-- JSON 格式合规性、翻译、markdown
-- 安全拒绝（有害内容）、计数、布尔逻辑
-
-### 评估策略
-
-| 策略       | 描述                             | 示例                             |
-| ---------- | -------------------------------- | -------------------------------- |
-| `exact`    | 输出必须完全匹配                 | `"4"`                            |
-| `contains` | 输出必须包含子串（不区分大小写） | `"Paris"`                        |
-| `regex`    | 输出必须匹配正则表达式模式       | `"1.*2.*3"`                      |
-| `custom`   | 自定义 JS 函数返回 true/false    | `(output) => output.length > 10` |
-
----
-
 ## 🐛 故障排除
 
 <details>
@@ -900,7 +1329,7 @@ OmniRoute 包含内置评估框架，用于针对黄金集测试 LLM 响应质
 
 ---
 
-## 🛠️ 技术栈
+## 🛠️
 
 - **运行时**: Node.js 20+
 - **语言**: TypeScript 5.9 — `src/` 和 `open-sse/` 中 **100% TypeScript**（v1.0.6）
@@ -919,29 +1348,20 @@ OmniRoute 包含内置评估框架，用于针对黄金集测试 LLM 响应质
 
 ## 📖 文档
 
-| 文档                                | 描述                         |
-| ----------------------------------- | ---------------------------- |
-| [用户指南](docs/USER_GUIDE.md)      | 提供商、组合、CLI 集成、部署 |
-| [API 参考](docs/API_REFERENCE.md)   | 所有端点及示例               |
-| [故障排除](docs/TROUBLESHOOTING.md) | 常见问题和解决方案           |
-| [架构](docs/ARCHITECTURE.md)        | 系统架构和内部机制           |
-| [贡献指南](CONTRIBUTING.md)         | 开发设置和指南               |
-| [OpenAPI 规范](docs/openapi.yaml)   | OpenAPI 3.0 规范             |
-| [安全策略](SECURITY.md)             | 漏洞报告和安全实践           |
+| 文档                                | 描述                                                   |
+| ----------------------------------- | ------------------------------------------------------ |
+| 🎯 **Endpoint-Aware Models**        | Custom models declare supported endpoints + API format |
+| [用户指南](docs/USER_GUIDE.md)      | 提供商、组合、CLI 集成、部署                           |
+| [API 参考](docs/API_REFERENCE.md)   | 所有端点及示例                                         |
+| [故障排除](docs/TROUBLESHOOTING.md) | 常见问题和解决方案                                     |
+| [架构](docs/ARCHITECTURE.md)        | 系统架构和内部机制                                     |
+| [贡献指南](CONTRIBUTING.md)         | 开发设置和指南                                         |
+| [OpenAPI 规范](docs/openapi.yaml)   | OpenAPI 3.0 规范                                       |
+| [安全策略](SECURITY.md)             | 漏洞报告和安全实践                                     |
 
 ---
 
-## 📧 支持
-
-> 💬 **加入我们的社区！** [WhatsApp 群组](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — 获取帮助、分享技巧、了解最新动态。
-
-- **网站**: [omniroute.online](https://omniroute.online)
-- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **WhatsApp**: [社区群组](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **原始项目**: [decolua 的 9router](https://github.com/decolua/9router)
-
----
+## 🗺️
 
 ## 👥 贡献者
 

bin/mcp-server.mjs

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

bin/omniroute.mjs

@@ -7,20 +7,75 @@
  *   omniroute              Start the server (default port 20128)
  *   omniroute --port 3000  Start on custom port
  *   omniroute --no-open    Start without opening browser
+ *   omniroute --mcp        Start MCP server (stdio transport for IDEs)
  *   omniroute --help       Show help
  *   omniroute --version    Show version
  */
 
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { homedir, platform } from "node:os";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const ROOT = join(__dirname, "..");
 const APP_DIR = join(ROOT, "app");
 
+// ── Load .env file (for global npm install) ─────────────────
+function loadEnvFile() {
+  const envPaths = [];
+
+  // 1. DATA_DIR/.env if set
+  if (process.env.DATA_DIR) {
+    envPaths.push(join(process.env.DATA_DIR, ".env"));
+  }
+
+  // 2. ~/.omniroute/.env (default data dir)
+  const home = homedir();
+  if (home) {
+    if (platform() === "win32") {
+      const appData = process.env.APPDATA || join(home, "AppData", "Roaming");
+      envPaths.push(join(appData, "omniroute", ".env"));
+    } else {
+      envPaths.push(join(home, ".omniroute", ".env"));
+    }
+  }
+
+  // 3. ./.env (current working directory)
+  envPaths.push(join(process.cwd(), ".env"));
+
+  for (const envPath of envPaths) {
+    try {
+      if (existsSync(envPath)) {
+        const content = readFileSync(envPath, "utf-8");
+        for (const line of content.split("\n")) {
+          const trimmed = line.trim();
+          // Skip empty lines and comments
+          if (!trimmed || trimmed.startsWith("#")) continue;
+          const eqIdx = trimmed.indexOf("=");
+          if (eqIdx > 0) {
+            const key = trimmed.slice(0, eqIdx).trim();
+            const value = trimmed.slice(eqIdx + 1).trim();
+            // Don't override existing env vars
+            if (process.env[key] === undefined) {
+              // Remove surrounding quotes
+              process.env[key] = value.replace(/^["']|["']$/g, "");
+            }
+          }
+        }
+        console.log(`  \x1b[2m📋 Loaded env from ${envPath}\x1b[0m`);
+        return;
+      }
+    } catch {
+      // Ignore errors reading env files
+    }
+  }
+}
+
+loadEnvFile();
+
 // ── Parse args ─────────────────────────────────────────────
 const args = process.argv.slice(2);
 
@@ -30,18 +85,30 @@ if (args.includes("--help") || args.includes("-h")) {
 
   \x1b[1mUsage:\x1b[0m
     omniroute                 Start the server
-    omniroute --port <port>   Use custom port (default: 20128)
+    omniroute --port <port>   Use custom API port (default: 20128)
     omniroute --no-open       Don't open browser automatically
+    omniroute --mcp           Start MCP server (stdio transport for IDEs)
     omniroute --help          Show this help
     omniroute --version       Show version
 
+  \x1b[1mMCP Integration:\x1b[0m
+    The --mcp flag starts an MCP server over stdio, exposing OmniRoute
+    tools for AI agents in VS Code, Cursor, Claude Desktop, and Copilot.
+
+    Available tools: omniroute_get_health, omniroute_list_combos,
+    omniroute_check_quota, omniroute_route_request, and more.
+
+  \x1b[1mConfig:\x1b[0m
+    Loads .env from: ~/.omniroute/.env or ./.env
+    Memory limit: OMNIROUTE_MEMORY_MB (default: 512)
+
   \x1b[1mAfter starting:\x1b[0m
-    Dashboard:  http://localhost:<port>
-    API:        http://localhost:<port>/v1
+    Dashboard:  http://localhost:<dashboard-port>
+    API:        http://localhost:<api-port>/v1
 
   \x1b[1mConnect your tools:\x1b[0m
     Set your CLI tool (Cursor, Cline, Codex, etc.) to use:
-    \x1b[33mhttp://localhost:20128/v1\x1b[0m
+    \x1b[33mhttp://localhost:<api-port>/v1\x1b[0m
   `);
   process.exit(0);
 }
@@ -58,27 +125,48 @@ if (args.includes("--version") || args.includes("-v")) {
   process.exit(0);
 }
 
-// Parse --port
-let port = 20128;
+// ── MCP Server Mode ───────────────────────────────────────
+if (args.includes("--mcp")) {
+  try {
+    const { startMcpCli } = await import(join(ROOT, "bin", "mcp-server.mjs"));
+    await startMcpCli(ROOT);
+  } catch (err) {
+    console.error("\x1b[31m✖ Failed to start MCP server:\x1b[0m", err.message || err);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+function parsePort(value, fallback) {
+  const parsed = parseInt(String(value), 10);
+  return Number.isFinite(parsed) && parsed > 0 && parsed <= 65535 ? parsed : fallback;
+}
+
+// Parse --port (canonical/base port)
+let port = parsePort(process.env.PORT || "20128", 20128);
 const portIdx = args.indexOf("--port");
 if (portIdx !== -1 && args[portIdx + 1]) {
-  port = parseInt(args[portIdx + 1], 10);
-  if (isNaN(port)) {
+  const cliPort = parsePort(args[portIdx + 1], null);
+  if (cliPort === null) {
     console.error("\x1b[31m✖ Invalid port number\x1b[0m");
     process.exit(1);
   }
+  port = cliPort;
 }
 
+const apiPort = parsePort(process.env.API_PORT || String(port), port);
+const dashboardPort = parsePort(process.env.DASHBOARD_PORT || String(port), port);
+
 const noOpen = args.includes("--no-open");
 
 // ── Banner ─────────────────────────────────────────────────
 console.log(`
 \x1b[36m   ____                  _ ____              _
-  / __ \\                (_) __ \\            | |
- | |  | |_ __ ___  _ __ _| |__) |___  _   _| |_ ___
- | |  | | '_ \` _ \\| '_ \\ |  _  // _ \\| | | | __/ _ \\
- | |__| | | | | | | | | | | | \\ \\ (_) | |_| | ||  __/
-  \\____/|_| |_| |_|_| |_|_|_|  \\_\\___/ \\__,_|\\__\\___|
+   / __ \\                (_) __ \\            | |
+  | |  | |_ __ ___  _ __ _| |__) |___  _   _| |_ ___
+  | |  | | '_ \` _ \\| '_ \\ |  _  // _ \\| | | | __/ _ \\
+  | |__| | | | | | | | | | | | \\ \\ (_) | |_| | ||  __/
+   \\____/|_| |_| |_|_| |_|_|_|  \\_\\___/ \\__,_|\\__\\___|
 \x1b[0m`);
 
 // ── Node.js version check ──────────────────────────────────
@@ -108,14 +196,23 @@ if (!existsSync(serverJs)) {
 // ── Start server ───────────────────────────────────────────
 console.log(`  \x1b[2m⏳ Starting server...\x1b[0m\n`);
 
+// Sanitize memory limit — parseInt to prevent command injection (#150)
+const rawMemory = parseInt(process.env.OMNIROUTE_MEMORY_MB || "512", 10);
+const memoryLimit =
+  Number.isFinite(rawMemory) && rawMemory >= 64 && rawMemory <= 16384 ? rawMemory : 512;
+
 const env = {
   ...process.env,
-  PORT: String(port),
+  OMNIROUTE_PORT: String(port),
+  PORT: String(dashboardPort),
+  DASHBOARD_PORT: String(dashboardPort),
+  API_PORT: String(apiPort),
   HOSTNAME: "0.0.0.0",
   NODE_ENV: "production",
+  NODE_OPTIONS: `--max-old-space-size=${memoryLimit}`,
 };
 
-const server = spawn("node", [serverJs], {
+const server = spawn("node", [`--max-old-space-size=${memoryLimit}`, serverJs], {
   cwd: APP_DIR,
   env,
   stdio: "pipe",
@@ -168,16 +265,17 @@ process.on("SIGTERM", shutdown);
 
 // ── On ready ───────────────────────────────────────────────
 async function onReady() {
-  const url = `http://localhost:${port}`;
+  const dashboardUrl = `http://localhost:${dashboardPort}`;
+  const apiUrl = `http://localhost:${apiPort}`;
 
   console.log(`
   \x1b[32m✔ OmniRoute is running!\x1b[0m
 
-  \x1b[1m  Dashboard:\x1b[0m  ${url}
-  \x1b[1m  API Base:\x1b[0m   ${url}/v1
+  \x1b[1m  Dashboard:\x1b[0m  ${dashboardUrl}
+  \x1b[1m  API Base:\x1b[0m   ${apiUrl}/v1
 
   \x1b[2m  Point your CLI tool (Cursor, Cline, Codex) to:\x1b[0m
-  \x1b[33m  ${url}/v1\x1b[0m
+  \x1b[33m  ${apiUrl}/v1\x1b[0m
 
   \x1b[2m  Press Ctrl+C to stop\x1b[0m
   `);
@@ -185,7 +283,7 @@ async function onReady() {
   if (!noOpen) {
     try {
       const open = await import("open");
-      await open.default(url);
+      await open.default(dashboardUrl);
     } catch {
       // open is optional — if not available, just skip
     }

docker-compose.prod.yml

@@ -22,21 +22,19 @@ services:
     env_file: .env
     environment:
       - NODE_ENV=production
-      - PORT=20128
+      - PORT=${PORT:-20128}
+      - DASHBOARD_PORT=${DASHBOARD_PORT:-${PORT:-20128}}
+      - API_PORT=${API_PORT:-20129}
+      - API_HOST=${API_HOST:-0.0.0.0}
       - HOSTNAME=0.0.0.0
       - DATA_DIR=/app/data
     ports:
-      - "20130:20128"
+      - "${PROD_DASHBOARD_PORT:-20130}:${DASHBOARD_PORT:-${PORT:-20128}}"
+      - "${PROD_API_PORT:-20131}:${API_PORT:-20129}"
     volumes:
       - omniroute-prod-data:/app/data
     healthcheck:
-      test:
-        [
-          "CMD",
-          "node",
-          "-e",
-          "fetch('http://127.0.0.1:20128/api/settings').then(r=>{if(!r.ok)throw r.status}).catch(()=>process.exit(1))",
-        ]
+      test: ["CMD", "node", "healthcheck.mjs"]
       interval: 30s
       timeout: 5s
       retries: 3

docker-compose.yml

@@ -20,16 +20,14 @@ x-common: &common
   env_file: .env
   environment:
     - DATA_DIR=/app/data # Must match the volume mount below
+    - PORT=${PORT:-20128}
+    - DASHBOARD_PORT=${DASHBOARD_PORT:-${PORT:-20128}}
+    - API_PORT=${API_PORT:-20129}
+    - API_HOST=${API_HOST:-0.0.0.0}
   volumes:
     - omniroute-data:/app/data
   healthcheck:
-    test:
-      [
-        "CMD",
-        "node",
-        "-e",
-        "fetch('http://127.0.0.1:20128/api/settings').then(r=>{if(!r.ok)throw r.status}).catch(()=>process.exit(1))",
-      ]
+    test: ["CMD", "node", "healthcheck.mjs"]
     interval: 30s
     timeout: 5s
     retries: 3
@@ -45,7 +43,8 @@ services:
       target: runner-base
     image: omniroute:base
     ports:
-      - "${PORT:-20128}:20128"
+      - "${DASHBOARD_PORT:-${PORT:-20128}}:${DASHBOARD_PORT:-${PORT:-20128}}"
+      - "${API_PORT:-20129}:${API_PORT:-20129}"
     profiles:
       - base
 
@@ -58,7 +57,8 @@ services:
       target: runner-cli
     image: omniroute:cli
     ports:
-      - "${PORT:-20128}:20128"
+      - "${DASHBOARD_PORT:-${PORT:-20128}}:${DASHBOARD_PORT:-${PORT:-20128}}"
+      - "${API_PORT:-20129}:${API_PORT:-20129}"
     profiles:
       - cli
 
@@ -71,8 +71,14 @@ services:
       target: runner-base
     image: omniroute:base
     ports:
-      - "${PORT:-20128}:20128"
+      - "${DASHBOARD_PORT:-${PORT:-20128}}:${DASHBOARD_PORT:-${PORT:-20128}}"
+      - "${API_PORT:-20129}:${API_PORT:-20129}"
     environment:
+      - DATA_DIR=/app/data
+      - PORT=${PORT:-20128}
+      - DASHBOARD_PORT=${DASHBOARD_PORT:-${PORT:-20128}}
+      - API_PORT=${API_PORT:-20129}
+      - API_HOST=${API_HOST:-0.0.0.0}
       - CLI_MODE=host
       - CLI_EXTRA_PATHS=/host-local/bin:/host-node/bin
       - CLI_CONFIG_HOME=/host-home

docs/API_REFERENCE.md

@@ -1,5 +1,7 @@
 # API Reference
 
+🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md)
+
 Complete reference for all OmniRoute API endpoints.
 
 ---

docs/ARCHITECTURE.md

@@ -1,6 +1,8 @@
 # OmniRoute Architecture
 
-_Last updated: 2026-02-18_
+🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md)
+
+_Last updated: 2026-03-04_
 
 ## Executive Summary
 
@@ -79,8 +81,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]
@@ -142,7 +144,7 @@ Management domains:
 - Providers/connections: `src/app/api/providers*`
 - Provider nodes: `src/app/api/provider-nodes*`
 - Custom models: `src/app/api/provider-models` (GET/POST/DELETE)
-- Model catalog: `src/app/api/models/catalog` (GET)
+- Model catalog: `src/app/api/models/route.ts` (GET)
 - Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
 - OAuth: `src/app/api/oauth/*`
 - Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
@@ -223,18 +225,19 @@ OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
 ## 3) Persistence Layer
 
-Primary state DB:
+Primary state DB (SQLite):
 
-- `src/lib/localDb.ts`
-- file: `${DATA_DIR}/db.json` (or `$XDG_CONFIG_HOME/omniroute/db.json` when set, else `~/.omniroute/db.json`)
-- entities: providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
+- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL)
+- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers)
+- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`)
+- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
 
-Usage DB:
+Usage persistence:
 
-- `src/lib/usageDb.ts`
-- files: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
-- follows same base directory policy as `localDb` (`DATA_DIR`, then `XDG_CONFIG_HOME/omniroute` when set)
-- decomposed into focused sub-modules: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts`
+- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`)
+- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
+- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
+- legacy JSON files are migrated to SQLite by startup migrations when present
 
 Domain State DB (SQLite):
 
@@ -503,9 +506,9 @@ erDiagram
 
 Physical storage files:
 
-- main state: `${DATA_DIR}/db.json` (or `$XDG_CONFIG_HOME/omniroute/db.json` when set, else `~/.omniroute/db.json`)
-- usage stats: `${DATA_DIR}/usage.json`
-- request log lines: `${DATA_DIR}/log.txt`
+- primary runtime DB: `${DATA_DIR}/storage.sqlite`
+- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact)
+- structured call payload archives: `${DATA_DIR}/call_logs/`
 - optional translator/request debug sessions: `<repo>/logs/...`
 
 ## Deployment Topology
@@ -520,8 +523,8 @@ flowchart LR
     subgraph ContainerOrProcess[OmniRoute Runtime]
         Next[Next.js Server\nPORT=20128]
         Core[SSE Core + Executors]
-        MainDB[(db.json)]
-        UsageDB[(usage.json/log.txt)]
+        MainDB[(storage.sqlite)]
+        UsageDB[(usage tables + log artifacts)]
     end
 
     subgraph External[External Services]
@@ -548,7 +551,7 @@ flowchart LR
 - `src/app/api/providers*`: provider CRUD, validation, testing
 - `src/app/api/provider-nodes*`: custom compatible node management
 - `src/app/api/provider-models`: custom model management (CRUD)
-- `src/app/api/models/catalog`: full model catalog API (all types grouped by provider)
+- `src/app/api/models/route.ts`: model catalog API (aliases + custom models)
 - `src/app/api/oauth/*`: OAuth/device-code flows
 - `src/app/api/keys*`: local API key lifecycle
 - `src/app/api/models/alias`: alias management
@@ -580,8 +583,9 @@ flowchart LR
 
 ### Persistence
 
-- `src/lib/localDb.ts`: persistent config/state
-- `src/lib/usageDb.ts`: usage history and rolling request logs
+- `src/lib/db/*`: persistent config/state and domain persistence on SQLite
+- `src/lib/localDb.ts`: compatibility re-export for DB modules
+- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables
 
 ## Provider Executor Coverage (Strategy Pattern)
 
@@ -722,23 +726,23 @@ Files are written to `<repo>/logs/<session>/` for each request session.
 
 ## 5) Data Integrity
 
-- DB shape migration/repair for missing keys
-- corrupt JSON reset safeguards for localDb and usageDb
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
 ## Observability and Operational Signals
 
 Runtime visibility sources:
 
 - console logs from `src/sse/utils/logger.ts`
-- per-request usage aggregates in `usage.json`
-- textual request status log in `log.txt`
+- 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 secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
-- Initial password fallback (`INITIAL_PASSWORD`, default `123456`) must be overridden in real deployments
+- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning
 - API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format
 - Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level
 - Cloud sync endpoints rely on API key auth + machine id semantics
@@ -760,13 +764,13 @@ Environment variables actively used by code:
 
 ## Known Architectural Notes
 
-1. `usageDb` and `localDb` now share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.
-2. `/api/v1/route.ts` returns a static model list and is not the main models source used by `/v1/models`.
+1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.
+2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift.
 3. Request logger writes full headers/body when enabled; treat log directory as sensitive.
 4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability.
 5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency.
 6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates).
-7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:plan3`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`).
+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

docs/CODEBASE_DOCUMENTATION.md

@@ -1,5 +1,7 @@
 # omniroute — Codebase Documentation
 
+🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md)
+
 > A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router.
 
 ---

docs/FEATURES.md

@@ -1,5 +1,7 @@
 # OmniRoute — Dashboard Features Gallery
 
+🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md)
+
 Visual guide to every section of the OmniRoute dashboard.
 
 ---
@@ -46,7 +48,7 @@ Four modes for debugging API translations: **Playground** (format converter), **
 
 ## ⚙️ Settings
 
-General settings, system storage, backup management (export/import database), appearance (dark/light mode), security (includes API endpoint protection and custom provider blocking), routing, resilience, and advanced configuration.
+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.
 
 ![Settings Dashboard](screenshots/06-settings.png)
 
@@ -54,7 +56,7 @@ General settings, system storage, backup management (export/import database), ap
 
 ## 🔧 CLI Tools
 
-One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, and Antigravity.
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, and **GitHub Copilot** (config generator for `chatLanguageModels.json`).
 
 ![CLI Tools Dashboard](screenshots/07-cli-tools.png)
 
@@ -73,3 +75,19 @@ Real-time request logging with filtering by provider, model, account, and API ke
 Your unified API endpoint with capability breakdown: Chat Completions, Embeddings, Image Generation, Reranking, Audio Transcription, and registered API keys.
 
 ![Endpoint Dashboard](screenshots/09-endpoint.png)
+
+---
+
+## 🖥️ 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.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/RELEASE_CHECKLIST.md

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

docs/TROUBLESHOOTING.md

@@ -1,5 +1,7 @@
 # Troubleshooting
 
+🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md)
+
 Common problems and solutions for OmniRoute.
 
 ---
@@ -8,9 +10,11 @@ Common problems and solutions for OmniRoute.
 
 | Problem                       | Solution                                                           |
 | ----------------------------- | ------------------------------------------------------------------ |
-| First login not working       | Check `INITIAL_PASSWORD` in `.env` (default: `123456`)             |
+| 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)       |
 
 ---
 
@@ -116,8 +120,8 @@ curl http://localhost:20128/api/monitoring/health
 
 ### Runtime Storage
 
-- Main state: `${DATA_DIR}/db.json` (providers, combos, aliases, keys, settings)
-- Usage: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
+- 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`)
 
 ---
@@ -206,6 +210,41 @@ When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex
 
 ---
 
+## Optional RAG / LLM failure taxonomy (16 problems)
+
+Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong.
+
+In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself.
+
+If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers:
+
+- retrieval drift and broken context boundaries
+- empty or stale indexes and vector stores
+- embedding versus semantic mismatch
+- prompt assembly and context window issues
+- logic collapse and overconfident answers
+- long chain and agent coordination failures
+- multi agent memory and role drift
+- deployment and bootstrap ordering problems
+
+The idea is simple:
+
+1. When you investigate a bad response, capture:
+   - user task and request
+   - route or provider combo in OmniRoute
+   - any RAG context used downstream (retrieved documents, tool calls, etc)
+2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`).
+3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs.
+4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy.
+
+Full text and concrete recipes live here (MIT license, text only):
+
+[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
+
+You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute.
+
+---
+
 ## Still Stuck?
 
 - **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)

docs/USER_GUIDE.md

@@ -1,5 +1,7 @@
 # User Guide
 
+🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md)
+
 Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
 
 ---
@@ -316,6 +318,25 @@ Model: cc/claude-opus-4-6
 
 ## 🚀 Deployment
 
+### Global npm install (Recommended)
+
+```bash
+npm install -g omniroute
+
+# Create config directory
+mkdir -p ~/.omniroute
+
+# Create .env file (see .env.example)
+cp .env.example ~/.omniroute/.env
+
+# Start server
+omniroute
+# Or with custom port:
+omniroute --port 3000
+```
+
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
 ### VPS Deployment
 
 ```bash
@@ -335,6 +356,43 @@ npm run start
 # Or: pm2 start npm --name omniroute -- start
 ```
 
+### PM2 Deployment (Low Memory)
+
+For servers with limited RAM, use the memory limit option:
+
+```bash
+# With 512MB limit (default)
+pm2 start npm --name omniroute -- start
+
+# Or with custom memory limit
+OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
+
+# Or using ecosystem.config.js
+pm2 start ecosystem.config.js
+```
+
+Create `ecosystem.config.js`:
+
+```javascript
+module.exports = {
+  apps: [
+    {
+      name: "omniroute",
+      script: "npm",
+      args: "start",
+      env: {
+        NODE_ENV: "production",
+        OMNIROUTE_MEMORY_MB: "512",
+        JWT_SECRET: "your-secret",
+        INITIAL_PASSWORD: "your-password",
+      },
+      node_args: "--max-old-space-size=512",
+      max_memory_restart: "300M",
+    },
+  ],
+};
+```
+
 ### Docker
 
 ```bash
@@ -349,20 +407,23 @@ For host-integrated mode with CLI binaries, see the Docker section in the main d
 
 ### Environment Variables
 
-| Variable              | Default                              | Description                                             |
-| --------------------- | ------------------------------------ | ------------------------------------------------------- |
-| `JWT_SECRET`          | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**)           |
-| `INITIAL_PASSWORD`    | `123456`                             | First login password                                    |
-| `DATA_DIR`            | `~/.omniroute`                       | Data directory (db, usage, logs)                        |
-| `PORT`                | framework default                    | Service port (`20128` in examples)                      |
-| `HOSTNAME`            | framework default                    | Bind host (Docker defaults to `0.0.0.0`)                |
-| `NODE_ENV`            | runtime default                      | Set `production` for deploy                             |
-| `BASE_URL`            | `http://localhost:20128`             | Server-side internal base URL                           |
-| `CLOUD_URL`           | `https://omniroute.dev`              | Cloud sync endpoint base URL                            |
-| `API_KEY_SECRET`      | `endpoint-proxy-api-key-secret`      | HMAC secret for generated API keys                      |
-| `REQUIRE_API_KEY`     | `false`                              | Enforce Bearer API key on `/v1/*`                       |
-| `ENABLE_REQUEST_LOGS` | `false`                              | Enables request/response logs                           |
-| `AUTH_COOKIE_SECURE`  | `false`                              | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| Variable                  | Default                              | Description                                             |
+| ------------------------- | ------------------------------------ | ------------------------------------------------------- |
+| `JWT_SECRET`              | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**)           |
+| `INITIAL_PASSWORD`        | `123456`                             | First login password                                    |
+| `DATA_DIR`                | `~/.omniroute`                       | Data directory (db, usage, logs)                        |
+| `PORT`                    | framework default                    | Service port (`20128` in examples)                      |
+| `HOSTNAME`                | framework default                    | Bind host (Docker defaults to `0.0.0.0`)                |
+| `NODE_ENV`                | runtime default                      | Set `production` for deploy                             |
+| `BASE_URL`                | `http://localhost:20128`             | Server-side internal base URL                           |
+| `CLOUD_URL`               | `https://omniroute.dev`              | Cloud sync endpoint base URL                            |
+| `API_KEY_SECRET`          | `endpoint-proxy-api-key-secret`      | HMAC secret for generated API keys                      |
+| `REQUIRE_API_KEY`         | `false`                              | Enforce Bearer API key on `/v1/*`                       |
+| `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 the full environment variable reference, see the [README](../README.md).
 
@@ -694,3 +755,55 @@ Access via **Dashboard → Health**. Real-time system health overview with 6 car
 | **Latency Telemetry** | p50/p95/p99 latency aggregation per provider                |
 
 **Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
+
+## 🖥️ Desktop Application (Electron)
+
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Installation
+
+```bash
+# From the electron directory:
+cd electron
+npm install
+
+# Development mode (connect to running Next.js dev server):
+npm run dev
+
+# Production mode (uses standalone build):
+npm start
+```
+
+### Building Installers
+
+```bash
+cd electron
+npm run build          # Current platform
+npm run build:win      # Windows (.exe NSIS)
+npm run build:mac      # macOS (.dmg universal)
+npm run build:linux    # Linux (.AppImage)
+```
+
+Output → `electron/dist-electron/`
+
+### Key Features
+
+| Feature                     | Description                                          |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness**        | Polls server before showing window (no blank screen) |
+| **System Tray**             | Minimize to tray, change port, quit from tray menu   |
+| **Port Management**         | Change server port from tray (auto-restarts server)  |
+| **Content Security Policy** | Restrictive CSP via session headers                  |
+| **Single Instance**         | Only one app instance can run at a time              |
+| **Offline Mode**            | Bundled Next.js server works without internet        |
+
+### Environment Variables
+
+| Variable              | Default | Description                      |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT`      | `20128` | Server port                      |
+| `OMNIROUTE_MEMORY_MB` | `512`   | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)

docs/i18n/README.md

@@ -0,0 +1,12 @@
+# Multilingual Documentation
+
+This directory contains machine-assisted translations based on the English docs.
+
+- **API_REFERENCE.md**: 🇺🇸 [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)
+- **ARCHITECTURE.md**: 🇺🇸 [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)
+- **CODEBASE_DOCUMENTATION.md**: 🇺🇸 [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)
+- **FEATURES.md**: 🇺🇸 [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)
+- **TROUBLESHOOTING.md**: 🇺🇸 [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)
+- **USER_GUIDE.md**: 🇺🇸 [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)
+
+Generated on 2026-02-26.

docs/i18n/ar/API_REFERENCE.md

@@ -0,0 +1,441 @@
+# مرجع واجهة برمجة التطبيقات
+
+🌐 **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.
+
+---
+
+## جدول المحتويات
+
+- [Chat Completions](#chat-completions)
+- [Embeddings](#embeddings)
+- [Image Generation](#image-generation)
+- [List Models](#list-models)
+- [Compatibility Endpoints](#compatibility-endpoints)
+- [Semantic Cache](#semantic-cache)
+- [Dashboard & Management](#dashboard--management)
+- [Request Processing](#request-processing)
+- [Authentication](#authentication)
+
+---
+
+## إكمالات الدردشة
+
+```bash
+POST /v1/chat/completions
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "cc/claude-opus-4-6",
+  "messages": [
+    {"role": "user", "content": "Write a function to..."}
+  ],
+  "stream": true
+}
+```
+
+### رؤوس مخصصة
+
+| رأس                      | الاتجاه | الوصف                                       |
+| ------------------------ | ------- | ------------------------------------------- |
+| `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` إذا تم تتبع التقدم على            |
+
+---
+
+## التضمينات
+
+```bash
+POST /v1/embeddings
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "nebius/Qwen/Qwen3-Embedding-8B",
+  "input": "The food was delicious"
+}
+```
+
+مقدمو الخدمة المتاحون: Nebius، وOpenAI، وMistral، وTogether AI، وFireworks، وNVIDIA.
+
+```bash
+# List all embedding models
+GET /v1/embeddings
+```
+
+---
+
+## توليد الصور
+
+```bash
+POST /v1/images/generations
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "openai/dall-e-3",
+  "prompt": "A beautiful sunset over mountains",
+  "size": "1024x1024"
+}
+```
+
+الموفرون المتاحون: OpenAI (DALL-E)، xAI (Grok Image)، Together AI (FLUX)، Fireworks AI.
+
+```bash
+# List all image models
+GET /v1/images/generations
+```
+
+---
+
+## قائمة النماذج
+
+```bash
+GET /v1/models
+Authorization: Bearer your-api-key
+
+→ Returns all chat, embedding, and image models + combos in OpenAI format
+```
+
+---
+
+## نقاط نهاية التوافق
+
+| الطريقة  | المسار                      | تنسيق                 |
+| -------- | --------------------------- | --------------------- |
+| مشاركة   | `/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`              | أولاما                |
+
+### مسارات موفر مخصصة
+
+```bash
+POST /v1/providers/{provider}/chat/completions
+POST /v1/providers/{provider}/embeddings
+POST /v1/providers/{provider}/images/generations
+```
+
+تتم إضافة بادئة الموفر تلقائيًا في حالة فقدانها. تُرجع النماذج غير المتطابقة `400`.
+
+---
+
+## ذاكرة التخزين المؤقت الدلالية
+
+```bash
+# Get cache stats
+GET /api/cache
+
+# Clear all caches
+DELETE /api/cache
+```
+
+مثال الاستجابة:
+
+```json
+{
+  "semanticCache": {
+    "memorySize": 42,
+    "memoryMaxSize": 500,
+    "dbSize": 128,
+    "hitRate": 0.65
+  },
+  "idempotency": {
+    "activeKeys": 3,
+    "windowMs": 5000
+  }
+}
+```
+
+---
+
+## لوحة القيادة والإدارة
+
+### المصادقة
+
+| نقطة النهاية                  | الطريقة        | الوصف                    |
+| ----------------------------- | -------------- | ------------------------ |
+| `/api/auth/login`             | مشاركة         | تسجيل الدخول             |
+| `/api/auth/logout`            | مشاركة         | تسجيل الخروج             |
+| `/api/settings/require-login` | الحصول على/وضع | تبديل تسجيل الدخول مطلوب |
+
+### إدارة مقدمي الخدمة
+
+| نقطة النهاية                 | الطريقة            | الوصف                       |
+| ---------------------------- | ------------------ | --------------------------- |
+| `/api/providers`             | الحصول على/النشر   | قائمة / إنشاء مقدمي الخدمات |
+| `/api/providers/[id]`        | الحصول على/وضع/حذف | إدارة مزود                  |
+| `/api/providers/[id]/test`   | مشاركة             | اختبار اتصال الموفر         |
+| `/api/providers/[id]/models` | احصل على           | قائمة نماذج المزود          |
+| `/api/providers/validate`    | مشاركة             | التحقق من صحة تكوين الموفر  |
+| `/api/provider-nodes*`       | متنوع              | إدارة عقدة الموفر           |
+| `/api/provider-models`       | الحصول على/نشر/حذف | نماذج مخصصة                 |
+
+### تدفقات OAuth
+
+| نقطة النهاية                     | الطريقة | الوصف                    |
+| -------------------------------- | ------- | ------------------------ |
+| `/api/oauth/[provider]/[action]` | متنوع   | OAuth الخاص بموفر الخدمة |
+
+### التوجيه والتكوين
+
+| نقطة النهاية          | الطريقة          | الوصف                             |
+| --------------------- | ---------------- | --------------------------------- |
+| `/api/models/alias`   | الحصول على/النشر | الأسماء المستعارة للنموذج         |
+| `/api/models/catalog` | احصل على         | جميع الموديلات حسب المزود + النوع |
+| `/api/combos*`        | متنوع            | إدارة التحرير والسرد              |
+| `/api/keys*`          | متنوع            | إدارة مفاتيح API                  |
+| `/api/pricing`        | احصل على         | التسعير النموذجي                  |
+
+### الاستخدام والتحليلات
+
+| نقطة النهاية                | الطريقة  | الوصف                 |
+| --------------------------- | -------- | --------------------- |
+| `/api/usage/history`        | احصل على | تاريخ الاستخدام       |
+| `/api/usage/logs`           | احصل على | سجلات الاستخدام       |
+| `/api/usage/request-logs`   | احصل على | سجلات على مستوى الطلب |
+| `/api/usage/[connectionId]` | احصل على | الاستخدام لكل اتصال   |
+
+### الإعدادات
+
+| نقطة النهاية                    | الطريقة        | الوصف                                           |
+| ------------------------------- | -------------- | ----------------------------------------------- |
+| `/api/settings`                 | الحصول على/وضع | الإعدادات العامة                                |
+| `/api/settings/proxy`           | الحصول على/وضع | تكوين وكيل الشبكة                               |
+| `/api/settings/proxy/test`      | مشاركة         | اختبار اتصال الوكيل                             |
+| `/api/settings/ip-filter`       | الحصول على/وضع | القائمة المسموح بها/القائمة المحظورة لعناوين IP |
+| `/api/settings/thinking-budget` | الحصول على/وضع | الميزانية الرمزية المنطقية                      |
+| `/api/settings/system-prompt`   | الحصول على/وضع | موجه النظام العالمي                             |
+
+### المراقبة
+
+| نقطة النهاية             | الطريقة        | الوصف                               |
+| ------------------------ | -------------- | ----------------------------------- |
+| `/api/sessions`          | احصل على       | تتبع الجلسة النشطة                  |
+| `/api/rate-limits`       | احصل على       | حدود المعدل لكل حساب                |
+| `/api/monitoring/health` | احصل على       | فحص الصحة                           |
+| `/api/cache`             | الحصول على/حذف | إحصائيات ذاكرة التخزين المؤقت / مسح |
+
+### النسخ الاحتياطي والتصدير/الاستيراد
+
+| نقطة النهاية                | الطريقة  | الوصف                                              |
+| --------------------------- | -------- | -------------------------------------------------- |
+| `/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 |
+
+### المزامنة السحابية
+
+| نقطة النهاية           | الطريقة | الوصف                    |
+| ---------------------- | ------- | ------------------------ |
+| `/api/sync/cloud`      | متنوع   | عمليات المزامنة السحابية |
+| `/api/sync/initialize` | مشاركة  | تهيئة المزامنة           |
+| `/api/cloud/*`         | متنوع   | إدارة السحابة            |
+
+### أدوات سطر الأوامر
+
+| نقطة النهاية                       | الطريقة  | الوصف               |
+| ---------------------------------- | -------- | ------------------- |
+| `/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 العام |
+
+تتضمن استجابات واجهة سطر الأوامر: `installed`، `runnable`، `command`، `commandPath`، `runtimeMode`، `reason`.
+
+### المرونة وحدود الأسعار
+
+| نقطة النهاية            | الطريقة        | الوصف                                |
+| ----------------------- | -------------- | ------------------------------------ |
+| `/api/resilience`       | الحصول على/وضع | الحصول على/تحديث ملفات تعريف المرونة |
+| `/api/resilience/reset` | مشاركة         | إعادة ضبط قواطع الدائرة              |
+| `/api/rate-limits`      | احصل على       | حالة حد المعدل لكل حساب              |
+| `/api/rate-limit`       | احصل على       | تكوين حد المعدل العالمي              |
+
+### التقييم
+
+| نقطة النهاية | الطريقة          | الوصف                                 |
+| ------------ | ---------------- | ------------------------------------- |
+| `/api/evals` | الحصول على/النشر | قائمة مجموعات التقييم / تشغيل التقييم |
+
+### السياسات
+
+| نقطة النهاية    | الطريقة            | الوصف                |
+| --------------- | ------------------ | -------------------- |
+| `/api/policies` | الحصول على/نشر/حذف | إدارة سياسات التوجيه |
+
+###الامتثال
+
+| نقطة النهاية                | الطريقة  | الوصف                        |
+| --------------------------- | -------- | ---------------------------- |
+| `/api/compliance/audit-log` | احصل على | سجل تدقيق الامتثال (آخر رقم) |
+
+### v1beta (متوافق مع الجوزاء)
+
+| نقطة النهاية               | الطريقة  | الوصف                                  |
+| -------------------------- | -------- | -------------------------------------- |
+| `/v1beta/models`           | احصل على | قائمة النماذج بصيغة الجوزاء            |
+| `/v1beta/models/{...path}` | مشاركة   | الجوزاء `generateContent` نقطة النهاية |
+
+تعكس نقاط النهاية هذه تنسيق Gemini API للعملاء الذين يتوقعون توافق Gemini SDK الأصلي.
+
+### واجهات برمجة التطبيقات الداخلية / النظام
+
+| نقطة النهاية    | الطريقة  | الوصف                                              |
+| --------------- | -------- | -------------------------------------------------- |
+| `/api/init`     | احصل على | فحص تهيئة التطبيق (يستخدم عند التشغيل لأول مرة)    |
+| `/api/tags`     | احصل على | علامات النماذج المتوافقة مع Ollama (لعملاء Ollama) |
+| `/api/restart`  | مشاركة   | تشغيل إعادة تشغيل الخادم الرشيقة                   |
+| `/api/shutdown` | مشاركة   | تشغيل إيقاف تشغيل الخادم بشكل رشيق                 |
+
+> **ملاحظة:** يتم استخدام نقاط النهاية هذه داخليًا بواسطة النظام أو للتوافق مع عميل Ollama. لا يتم استدعاؤها عادة من قبل المستخدمين النهائيين.
+
+---
+
+## النسخ الصوتي
+
+```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+```
+
+قم بنسخ الملفات الصوتية باستخدام Deepgram أو AssemblyAI.
+
+**الطلب:**
+
+```bash
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+  -H "Authorization: Bearer your-api-key" \
+  -F "file=@recording.mp3" \
+  -F "model=deepgram/nova-3"
+```
+
+**الرد:**
+
+```json
+{
+  "text": "Hello, this is the transcribed audio content.",
+  "task": "transcribe",
+  "language": "en",
+  "duration": 12.5
+}
+```
+
+**الموفرون المدعمون:** `deepgram/nova-3`، `assemblyai/best`.
+
+**التنسيقات المدعومة:** `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`.
+
+---
+
+## التوافق مع أولاما
+
+بالنسبة للعملاء الذين يستخدمون تنسيق واجهة برمجة تطبيقات Olma:
+
+```bash
+# Chat endpoint (Ollama format)
+POST /v1/api/chat
+
+# Model listing (Ollama format)
+GET /api/tags
+```
+
+تتم ترجمة الطلبات تلقائيًا بين تنسيقات Ollama والتنسيقات الداخلية.
+
+---
+
+## القياس عن بعد
+
+```bash
+# Get latency telemetry summary (p50/p95/p99 per provider)
+GET /api/telemetry/summary
+```
+
+**الرد:**
+
+```json
+{
+  "providers": {
+    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
+    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
+  }
+}
+```
+
+---
+
+## الميزانية
+
+```bash
+# Get budget status for all API keys
+GET /api/usage/budget
+
+# Set or update a budget
+POST /api/usage/budget
+Content-Type: application/json
+
+{
+  "keyId": "key-123",
+  "limit": 50.00,
+  "period": "monthly"
+}
+```
+
+---
+
+## توفر النموذج
+
+```bash
+# Get real-time model availability across all providers
+GET /api/models/availability
+
+# Check availability for a specific model
+POST /api/models/availability
+Content-Type: application/json
+
+{
+  "model": "claude-sonnet-4-5-20250929"
+}
+```
+
+---
+
+## معالجة الطلب
+
+1. يرسل العميل طلبًا إلى `/v1/*`
+2. يستدعي معالج المسار `handleChat`، `handleEmbedding`، `handleAudioTranscription`، أو `handleImageGeneration`
+3. تم حل النموذج (المزود/النموذج المباشر أو الاسم المستعار/السرد)
+4. تم تحديد بيانات الاعتماد من قاعدة البيانات المحلية مع تصفية توفر الحساب
+5. للدردشة: `handleChatCore` — اكتشاف التنسيق، والترجمة، والتحقق من ذاكرة التخزين المؤقت، والتحقق من عدم الكفاءة
+6. يقوم منفذ الموفر بإرسال طلب المنبع
+7. تتم ترجمة الاستجابة مرة أخرى إلى تنسيق العميل (الدردشة) أو إعادتها كما هي (التضمينات/الصور/الصوت)
+8. تم تسجيل الاستخدام/التسجيل
+9. يتم تطبيق الإجراء الاحتياطي على الأخطاء وفقًا لقواعد التحرير والسرد
+
+مرجع البنية الكاملة: [link](ARCHITECTURE.md)
+
+---
+
+## المصادقة
+
+- تستخدم مسارات لوحة المعلومات (`/dashboard/*`) ملف تعريف الارتباط `auth_token`
+- يستخدم تسجيل الدخول تجزئة كلمة المرور المحفوظة؛ الرجوع إلى `INITIAL_PASSWORD`
+- `requireLogin` قابل للتبديل عبر `/api/settings/require-login`
+- تتطلب مسارات `/v1/*` بشكل اختياري مفتاح Bearer API عندما `REQUIRE_API_KEY=true`

docs/i18n/ar/ARCHITECTURE.md

@@ -0,0 +1,781 @@
+# العمارة OmniRoute
+
+🌐 **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 عبارة عن بوابة توجيه محلية تعمل بالذكاء الاصطناعي ولوحة معلومات مبنية على Next.js.
+فهو يوفر نقطة نهاية واحدة متوافقة مع OpenAI (`/v1/*`) ويوجه حركة المرور عبر العديد من موفري الخدمات الأولية مع الترجمة والاحتياط وتحديث الرمز المميز وتتبع الاستخدام.
+
+القدرات الأساسية:
+
+- سطح 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/`)
+
+نموذج وقت التشغيل الأساسي:
+
+- تقوم مسارات تطبيق Next.js ضمن `src/app/api/*` بتنفيذ كل من واجهات برمجة تطبيقات لوحة المعلومات وواجهات برمجة تطبيقات التوافق
+- نواة توجيه/SSE مشتركة في `src/sse/*` + `open-sse/*` تتعامل مع تنفيذ الموفر والترجمة والتدفق والرجوع والاستخدام
+
+## النطاق والحدود
+
+### في النطاق
+
+- وقت تشغيل البوابة المحلية
+- واجهات برمجة التطبيقات لإدارة لوحة المعلومات
+- مصادقة الموفر وتحديث الرمز المميز
+- طلب الترجمة وتدفق SSE
+- الحالة المحلية + استمرارية الاستخدام
+- تنسيق مزامنة سحابية اختيارية
+
+### خارج النطاق
+
+- تنفيذ الخدمة السحابية خلف `NEXT_PUBLIC_CLOUD_URL`
+- مزود مستوى جيش تحرير السودان/مستوى التحكم خارج العملية المحلية
+- ثنائيات CLI الخارجية نفسها (Claude CLI، Codex CLI، وما إلى ذلك)
+
+## سياق النظام عالي المستوى
+
+```mermaid
+flowchart LR
+    subgraph Clients[Developer Clients]
+        C1[Claude Code]
+        C2[Codex CLI]
+        C3[OpenClaw / Droid / Cline / Continue / Roo]
+        C4[Custom OpenAI-compatible clients]
+        BROWSER[Browser Dashboard]
+    end
+
+    subgraph Router[OmniRoute Local Process]
+        API[V1 Compatibility API\n/v1/*]
+        DASH[Dashboard + Management API\n/api/*]
+        CORE[SSE + Translation Core\nopen-sse + src/sse]
+        DB[(db.json)]
+        UDB[(usage.json + log.txt)]
+    end
+
+    subgraph Upstreams[Upstream Providers]
+        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity]
+        P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
+        P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
+    end
+
+    subgraph Cloud[Optional Cloud Sync]
+        CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL]
+    end
+
+    C1 --> API
+    C2 --> API
+    C3 --> API
+    C4 --> API
+    BROWSER --> DASH
+
+    API --> CORE
+    DASH --> DB
+    CORE --> DB
+    CORE --> UDB
+
+    CORE --> P1
+    CORE --> P2
+    CORE --> P3
+
+    DASH --> CLOUD
+```
+
+## مكونات وقت التشغيل الأساسية
+
+## 1) واجهة برمجة التطبيقات وطبقة التوجيه (مسارات تطبيق Next.js)
+
+الدلائل الرئيسية:
+
+- `src/app/api/v1/*` و`src/app/api/v1beta/*` لواجهات برمجة تطبيقات التوافق
+- `src/app/api/*` لواجهات برمجة التطبيقات للإدارة/التكوين
+- تتم إعادة الكتابة التالية في الخريطة `next.config.mjs` من `/v1/*` إلى `/api/v1/*`
+
+طرق التوافق الهامة:
+
+- `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/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/v1beta/models/route.ts`
+- `src/app/api/v1beta/models/[...path]/route.ts`
+
+مجالات الإدارة:
+
+- المصادقة/الإعدادات: `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)
+- 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)
+
+## 2) SSE + جوهر الترجمة
+
+وحدات التدفق الرئيسية:
+
+- الإدخال: `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`
+
+الخدمات (منطق الأعمال):
+
+- اختيار الحساب/تسجيل النقاط: `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`
+
+وحدات طبقة المجال:
+
+- توفر النموذج: `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 للسلاسل الاحتياطية، والميزانيات، وتاريخ التكلفة، وحالة الإغلاق، وقواطع الدائرة
+
+وحدات موفر OAuth (12 ملفًا فرديًا ضمن `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` — إعادة التصدير من الوحدات الفردية
+
+## 3) طبقة الثبات
+
+قاعدة بيانات الحالة الأساسية:
+
+- `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**
+
+قاعدة بيانات الاستخدام:
+
+- `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`
+
+قاعدة بيانات حالة المجال (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؛ تتم استعادة الحالة من قاعدة البيانات عند البداية الباردة
+
+## 4) المصادقة + الأسطح الأمنية
+
+- مصادقة ملف تعريف الارتباط للوحة المعلومات: `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` (قابل للتكوين لكل موفر أو عالمي)
+
+## 5) المزامنة السحابية
+
+- الحرف الأول للمجدول: `src/lib/initCloudSync.ts`، `src/shared/services/initializeCloudSync.ts`
+- المهمة الدورية: `src/shared/services/cloudSyncScheduler.ts`
+- مسار التحكم: `src/app/api/sync/cloud/route.ts`
+
+## دورة حياة الطلب (`/v1/chat/completions`)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as CLI/SDK Client
+    participant Route as /api/v1/chat/completions
+    participant Chat as src/sse/handlers/chat
+    participant Core as open-sse/handlers/chatCore
+    participant Model as Model Resolver
+    participant Auth as Credential Selector
+    participant Exec as Provider Executor
+    participant Prov as Upstream Provider
+    participant Stream as Stream Translator
+    participant Usage as usageDb
+
+    Client->>Route: POST /v1/chat/completions
+    Route->>Chat: handleChat(request)
+    Chat->>Model: parse/resolve model or combo
+
+    alt Combo model
+        Chat->>Chat: iterate combo models (handleComboChat)
+    end
+
+    Chat->>Auth: getProviderCredentials(provider)
+    Auth-->>Chat: active account + tokens/api key
+
+    Chat->>Core: handleChatCore(body, modelInfo, credentials)
+    Core->>Core: detect source format
+    Core->>Core: translate request to target format
+    Core->>Exec: execute(provider, transformedBody)
+    Exec->>Prov: upstream API call
+    Prov-->>Exec: SSE/JSON response
+    Exec-->>Core: response + metadata
+
+    alt 401/403
+        Core->>Exec: refreshCredentials()
+        Exec-->>Core: updated tokens
+        Core->>Exec: retry request
+    end
+
+    Core->>Stream: translate/normalize stream to client format
+    Stream-->>Client: SSE chunks / JSON response
+
+    Stream->>Usage: extract usage + persist history/log
+```
+
+## التحرير والسرد + التدفق الاحتياطي للحساب
+
+```mermaid
+flowchart TD
+    A[Incoming model string] --> B{Is combo name?}
+    B -- Yes --> C[Load combo models sequence]
+    B -- No --> D[Single model path]
+
+    C --> E[Try model N]
+    E --> F[Resolve provider/model]
+    D --> F
+
+    F --> G[Select account credentials]
+    G --> H{Credentials available?}
+    H -- No --> I[Return provider unavailable]
+    H -- Yes --> J[Execute request]
+
+    J --> K{Success?}
+    K -- Yes --> L[Return response]
+    K -- No --> M{Fallback-eligible error?}
+
+    M -- No --> N[Return error]
+    M -- Yes --> O[Mark account unavailable cooldown]
+    O --> P{Another account for provider?}
+    P -- Yes --> G
+    P -- No --> Q{In combo with next model?}
+    Q -- Yes --> E
+    Q -- No --> R[Return all unavailable]
+```
+
+يتم اتخاذ القرارات الاحتياطية بواسطة `open-sse/services/accountFallback.ts` باستخدام رموز الحالة والاستدلال على رسائل الخطأ.
+
+## دورة حياة OAuth Onboarding وتحديث الرمز المميز
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Dashboard UI
+    participant OAuth as /api/oauth/[provider]/[action]
+    participant ProvAuth as Provider Auth Server
+    participant DB as localDb
+    participant Test as /api/providers/[id]/test
+    participant Exec as Provider Executor
+
+    UI->>OAuth: GET authorize or device-code
+    OAuth->>ProvAuth: create auth/device flow
+    ProvAuth-->>OAuth: auth URL or device code payload
+    OAuth-->>UI: flow data
+
+    UI->>OAuth: POST exchange or poll
+    OAuth->>ProvAuth: token exchange/poll
+    ProvAuth-->>OAuth: access/refresh tokens
+    OAuth->>DB: createProviderConnection(oauth data)
+    OAuth-->>UI: success + connection id
+
+    UI->>Test: POST /api/providers/[id]/test
+    Test->>Exec: validate credentials / optional refresh
+    Exec-->>Test: valid or refreshed token info
+    Test->>DB: update status/tokens/errors
+    Test-->>UI: validation result
+```
+
+يتم تنفيذ التحديث أثناء حركة المرور المباشرة داخل `open-sse/handlers/chatCore.ts` عبر المنفذ `refreshCredentials()`.
+
+## دورة حياة المزامنة السحابية (تمكين / مزامنة / تعطيل)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Endpoint Page UI
+    participant Sync as /api/sync/cloud
+    participant DB as localDb
+    participant Cloud as External Cloud Sync
+    participant Claude as ~/.claude/settings.json
+
+    UI->>Sync: POST action=enable
+    Sync->>DB: set cloudEnabled=true
+    Sync->>DB: ensure API key exists
+    Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys)
+    Cloud-->>Sync: sync result
+    Sync->>Cloud: GET /{machineId}/v1/verify
+    Sync-->>UI: enabled + verification status
+
+    UI->>Sync: POST action=sync
+    Sync->>Cloud: POST /sync/{machineId}
+    Cloud-->>Sync: remote data
+    Sync->>DB: update newer local tokens/status
+    Sync-->>UI: synced
+
+    UI->>Sync: POST action=disable
+    Sync->>DB: set cloudEnabled=false
+    Sync->>Cloud: DELETE /sync/{machineId}
+    Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed)
+    Sync-->>UI: disabled
+```
+
+يتم تشغيل المزامنة الدورية بواسطة `CloudSyncScheduler` عند تمكين السحابة.
+
+## نموذج البيانات وخريطة التخزين
+
+```mermaid
+erDiagram
+    SETTINGS ||--o{ PROVIDER_CONNECTION : controls
+    PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider
+    PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage
+
+    SETTINGS {
+      boolean cloudEnabled
+      number stickyRoundRobinLimit
+      boolean requireLogin
+      string password_hash
+      string fallbackStrategy
+      json rateLimitDefaults
+      json providerProfiles
+    }
+
+    PROVIDER_CONNECTION {
+      string id
+      string provider
+      string authType
+      string name
+      number priority
+      boolean isActive
+      string apiKey
+      string accessToken
+      string refreshToken
+      string expiresAt
+      string testStatus
+      string lastError
+      string rateLimitedUntil
+      json providerSpecificData
+    }
+
+    PROVIDER_NODE {
+      string id
+      string type
+      string name
+      string prefix
+      string apiType
+      string baseUrl
+    }
+
+    MODEL_ALIAS {
+      string alias
+      string targetModel
+    }
+
+    COMBO {
+      string id
+      string name
+      string[] models
+    }
+
+    API_KEY {
+      string id
+      string name
+      string key
+      string machineId
+    }
+
+    USAGE_ENTRY {
+      string provider
+      string model
+      number prompt_tokens
+      number completion_tokens
+      string connectionId
+      string timestamp
+    }
+
+    CUSTOM_MODEL {
+      string id
+      string name
+      string providerId
+    }
+
+    PROXY_CONFIG {
+      string global
+      json providers
+    }
+
+    IP_FILTER {
+      string mode
+      string[] allowlist
+      string[] blocklist
+    }
+
+    THINKING_BUDGET {
+      string mode
+      number customBudget
+      string effortLevel
+    }
+
+    SYSTEM_PROMPT {
+      boolean enabled
+      string prompt
+      string position
+    }
+```
+
+ملفات التخزين المادية:
+
+- الحالة الرئيسية: `${DATA_DIR}/db.json` (أو `$XDG_CONFIG_HOME/omniroute/db.json` عند التعيين، وإلا `~/.omniroute/db.json`)
+- إحصائيات الاستخدام: `${DATA_DIR}/usage.json`
+- خطوط سجل الطلب: `${DATA_DIR}/log.txt`
+- جلسات تصحيح أخطاء المترجم/الطلب الاختيارية: `<repo>/logs/...`
+
+## طبولوجيا النشر
+
+```mermaid
+flowchart LR
+    subgraph LocalHost[Developer Host]
+        CLI[CLI Tools]
+        Browser[Dashboard Browser]
+    end
+
+    subgraph ContainerOrProcess[OmniRoute Runtime]
+        Next[Next.js Server\nPORT=20128]
+        Core[SSE Core + Executors]
+        MainDB[(db.json)]
+        UsageDB[(usage.json/log.txt)]
+    end
+
+    subgraph External[External Services]
+        Providers[AI Providers]
+        SyncCloud[Cloud Sync Service]
+    end
+
+    CLI --> Next
+    Browser --> Next
+    Next --> Core
+    Next --> MainDB
+    Core --> MainDB
+    Core --> UsageDB
+    Core --> Providers
+    Next --> SyncCloud
+```
+
+## تعيين الوحدة (القرار الحاسم)
+
+### وحدات المسار وواجهة برمجة التطبيقات
+
+- `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/sse/handlers/chat.ts`: تحليل الطلب، ومعالجة التحرير والسرد، وحلقة اختيار الحساب
+- `open-sse/handlers/chatCore.ts`: الترجمة، إرسال المنفذ، معالجة إعادة المحاولة/التحديث، إعداد الدفق
+- `open-sse/executors/*`: سلوك الشبكة والتنسيق الخاص بالموفر
+
+### سجل الترجمة ومحولات التنسيق
+
+- `open-sse/translator/index.ts`: تسجيل المترجم وتنسيقه
+- طلب المترجمين: `open-sse/translator/request/*`
+- مترجمو الرد: `open-sse/translator/response/*`
+- ثوابت التنسيق: `open-sse/translator/formats.ts`
+
+### المثابرة
+
+- `src/lib/localDb.ts`: التكوين/الحالة المستمرة
+- `src/lib/usageDb.ts`: سجل الاستخدام وسجلات الطلبات المتجددة
+
+## تغطية منفذي الخدمة (نمط الإستراتيجية)
+
+كل مزود لديه منفذ متخصص يمتد `BaseExecutor` (في `open-sse/executors/base.ts`)، والذي يوفر بناء عنوان URL، وإنشاء الرأس، وإعادة المحاولة مع التراجع الأسي، وخطافات تحديث بيانات الاعتماد، وطريقة التنسيق `execute()`.
+
+| المنفذ                | المزود (المقدمون)                                                                                                                                            | التعامل الخاص                                                          |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| `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                                  |
+
+يستخدم جميع الموفرين الآخرين (بما في ذلك العقد المتوافقة المخصصة) `DefaultExecutor`.
+
+## مصفوفة توافق الموفر
+
+| مقدم                                | تنسيق            | مصادقة                      | تيار            | غير دفق | تحديث الرمز المميز | واجهة برمجة تطبيقات الاستخدام |
+| ----------------------------------- | ---------------- | --------------------------- | --------------- | ------- | ------------------ | ----------------------------- |
+| كلود                                | كلود             | مفتاح API / OAuth           | ✅              | ✅      | ✅                 | ⚠️ المشرف فقط                 |
+| الجوزاء                             | الجوزاء          | مفتاح API / OAuth           | ✅              | ✅      | ✅                 | ⚠️ وحدة التحكم السحابية       |
+| الجوزاء CLI                         | الجوزاء-cli      | أووث                        | ✅              | ✅      | ✅                 | ⚠️ وحدة التحكم السحابية       |
+| مكافحة الجاذبية                     | ضد الجاذبية      | أووث                        | ✅              | ✅      | ✅                 | ✅ الحصة الكاملة API          |
+| أوبن آي                             | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
+| الدستور الغذائي                     | openai-responses | أووث                        | ✅ مجبور        | ❌      | ✅                 | ✅ حدود المعدل                |
+| جيثب مساعد الطيار                   | أوبيناي          | OAuth + رمز مساعد الطيار    | ✅              | ✅      | ✅                 | ✅ لقطات الحصص                |
+| المؤشر                              | المؤشر           | المجموع الاختباري المخصص    | ✅              | ✅      | ❌                 | ❌                            |
+| كيرو                                | كيرو             | AWS SSO OIDC                | ✅(ايفنت ستريم) | ❌      | ✅                 | ✅ حدود الاستخدام             |
+| كوين                                | أوبيناي          | أووث                        | ✅              | ✅      | ✅                 | ⚠️ حسب الطلب                  |
+| اي فلو                              | أوبيناي          | OAuth (أساسي)               | ✅              | ✅      | ✅                 | ⚠️ حسب الطلب                  |
+| اوبن راوتر                          | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
+| جي إل إم/كيمي/ميني ماكس             | كلود             | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
+| ديب سيك                             | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
+| جروك                                | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
+| xAI (جروك)                          | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
+| ميسترال                             | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
+| الحيرة                              | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
+| معا منظمة العفو الدولية             | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
+| الألعاب النارية منظمة العفو الدولية | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
+| المخيخ                              | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
+| كوهير                               | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
+| نفيديا نيم                          | أوبيناي          | مفتاح واجهة برمجة التطبيقات | ✅              | ✅      | ❌                 | ❌                            |
+
+## تنسيق تغطية الترجمة
+
+تتضمن تنسيقات المصدر المكتشفة ما يلي:
+
+- `openai`
+- `openai-responses`
+- `claude`
+- `gemini`
+
+تتضمن التنسيقات المستهدفة ما يلي:
+
+- دردشة/ردود OpenAI
+- كلود
+- الجوزاء/الجوزاء-CLI/الظرف المضاد للجاذبية
+- كيرو
+- المؤشر
+
+تستخدم الترجمات **OpenAI كتنسيق مركزي** — تمر جميع التحويلات عبر OpenAI كتنسيق وسيط:
+
+```
+Source Format → OpenAI (hub) → Target Format
+```
+
+يتم تحديد الترجمات ديناميكيًا استنادًا إلى شكل حمولة المصدر والتنسيق المستهدف للموفر.
+
+طبقات معالجة إضافية في مسار الترجمة:
+
+- **تطهير الاستجابة** — يزيل الحقول غير القياسية من استجابات تنسيق OpenAI (سواء المتدفقة أو غير المتدفقة) لضمان الامتثال الصارم لـ SDK
+- **تطبيع الدور** — تحويل `developer` → `system` للأهداف غير التابعة لـ OpenAI؛ يدمج `system` → `user` للنماذج التي ترفض دور النظام (GLM، ERNIE)
+- **فكر في استخراج العلامات** — يوزع كتل `<think>...</think>` من المحتوى إلى حقل `reasoning_content`
+- **الإخراج المنظم** — يحول OpenAI `response_format.json_schema` إلى `responseMimeType` + `responseSchema` الخاص بـ Gemini
+
+## نقاط نهاية واجهة برمجة التطبيقات المدعومة
+
+| نقطة النهاية                                       | تنسيق              | معالج                                                                     |
+| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------------- |
+| `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`             | نماذج مخصصة        | إدارة النماذج المخصصة لكل مزود                                            |
+
+## تجاوز المعالج
+
+يعترض معالج التجاوز (`open-sse/utils/bypassHandler.ts`) طلبات "الرمي" المعروفة من Claude CLI - أصوات التمهيد، واستخراج العناوين، وعدد الرموز المميزة - ويعيد **استجابة زائفة** دون استهلاك الرموز المميزة للموفر الرئيسي. يتم تشغيل هذا فقط عندما يحتوي `User-Agent` على `claude-cli`.
+
+## طلب خط أنابيب المسجل
+
+يوفر مسجل الطلب (`open-sse/utils/requestLogger.ts`) مسارًا لتسجيل تصحيح الأخطاء مكون من 7 مراحل، معطل افتراضيًا، وممكن عبر `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>/` لكل جلسة طلب.
+
+## أوضاع الفشل والمرونة
+
+## 1) توفر الحساب/المزود
+
+- فترة تباطؤ حساب الموفر عند حدوث أخطاء عابرة/معدل/مصادقة
+- احتياطي الحساب قبل فشل الطلب
+- نموذج التحرير والسرد الاحتياطي عند استنفاد مسار النموذج/المزود الحالي
+
+## 2) انتهاء صلاحية الرمز المميز
+
+- الفحص المسبق والتحديث مع إعادة المحاولة لموفري الخدمة القابلين للتحديث
+- 401/403 إعادة المحاولة بعد محاولة التحديث في المسار الأساسي
+
+## 3) سلامة الدفق
+
+- وحدة تحكم تيار قطع الاتصال
+- دفق الترجمة مع تدفق نهاية الدفق ومعالجة `[DONE]`
+- احتياطي تقدير الاستخدام عندما تكون البيانات الوصفية لاستخدام الموفر مفقودة
+
+## 4) تدهور المزامنة السحابية
+
+- ظهرت أخطاء المزامنة ولكن يستمر وقت التشغيل المحلي
+- يحتوي المجدول على منطق قادر على إعادة المحاولة، ولكن التنفيذ الدوري يستدعي حاليًا مزامنة المحاولة الواحدة بشكل افتراضي
+
+## 5) سلامة البيانات
+
+- ترحيل/إصلاح شكل قاعدة البيانات للمفاتيح المفقودة
+- ضمانات إعادة تعيين JSON الفاسدة لـ localDb وuseDb
+
+## إمكانية الملاحظة والإشارات التشغيلية
+
+مصادر رؤية وقت التشغيل:
+
+- سجلات وحدة التحكم من `src/sse/utils/logger.ts`
+- مجاميع الاستخدام لكل طلب في `usage.json`
+- سجل حالة الطلب النصي في `log.txt`
+- سجلات الطلب/الترجمة العميقة الاختيارية ضمن `logs/` عندما `ENABLE_REQUEST_LOGS=true`
+- نقاط نهاية استخدام لوحة المعلومات (`/api/usage/*`) لاستهلاك واجهة المستخدم
+
+## الحدود الحساسة للأمن
+
+- سر JWT (`JWT_SECRET`) يؤمن التحقق/التوقيع على ملف تعريف الارتباط لجلسة لوحة المعلومات
+- يجب تجاوز الاحتياطي الأولي لكلمة المرور (`INITIAL_PASSWORD`، الافتراضي `123456`) في عمليات النشر الحقيقية
+- سر HMAC لمفتاح API (`API_KEY_SECRET`) يؤمن تنسيق مفتاح API المحلي الذي تم إنشاؤه
+- تظل أسرار الموفر (مفاتيح/رموز واجهة برمجة التطبيقات) موجودة في قاعدة البيانات المحلية ويجب حمايتها على مستوى نظام الملفات
+- تعتمد نقاط نهاية المزامنة السحابية على مصادقة مفتاح API + دلالات معرف الجهاز
+
+## مصفوفة البيئة ووقت التشغيل
+
+متغيرات البيئة المستخدمة بشكل نشط بواسطة التعليمات البرمجية:
+
+- التطبيق/المصادقة: `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`
+
+## الملاحظات المعمارية المعروفة
+
+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، عشوائي، الأقل استخدامًا، تحسين التكلفة)، المرونة (حدود المعدل القابلة للتحرير، قاطع الدائرة، السياسات)، الذكاء الاصطناعي (ميزانية التفكير، موجه النظام، ذاكرة التخزين المؤقت السريعة)، المتقدم (الوكيل).
+
+## قائمة التحقق التشغيلية
+
+- البناء من المصدر: `npm run build`
+- إنشاء صورة Docker: `docker build -t omniroute .`
+- ابدأ الخدمة وتحقق:
+- `GET /api/settings`
+- `GET /api/v1/models`
+- يجب أن يكون عنوان URL الأساسي لهدف واجهة سطر الأوامر هو `http://<host>:20128/v1` عندما يكون `PORT=20128`

docs/i18n/ar/CODEBASE_DOCUMENTATION.md

@@ -0,0 +1,589 @@
+# الطريق الشامل - وثائق قاعدة التعليمات البرمجية
+
+🌐 **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** متعدد الموفرين.
+
+---
+
+## 1. ما هو الطريق الشامل؟
+
+omniroute هو **جهاز توجيه وكيل** يقع بين عملاء الذكاء الاصطناعي (Claude CLI، وCodex، وCursor IDE، وما إلى ذلك) وموفري الذكاء الاصطناعي (Anthropic، وGoogle، وOpenAI، وAWS، وGitHub، وما إلى ذلك). إنه يحل مشكلة واحدة كبيرة:
+
+> **يتحدث عملاء الذكاء الاصطناعي المختلفون "لغات" مختلفة (تنسيقات واجهة برمجة التطبيقات)، ويتوقع مقدمو خدمات الذكاء الاصطناعي المختلفون "لغات" مختلفة أيضًا. ** يترجم المسار الشامل بينهم تلقائيًا.
+
+فكر في الأمر وكأنه مترجم عالمي في الأمم المتحدة - يمكن لأي مندوب التحدث بأي لغة، ويقوم المترجم بتحويلها لأي مندوب آخر.
+
+---
+
+## 2. نظرة عامة على الهندسة المعمارية
+
+```mermaid
+graph LR
+    subgraph Clients
+        A[Claude CLI]
+        B[Codex]
+        C[Cursor IDE]
+        D[OpenAI-compatible]
+    end
+
+    subgraph omniroute
+        E[Handler Layer]
+        F[Translator Layer]
+        G[Executor Layer]
+        H[Services Layer]
+    end
+
+    subgraph Providers
+        I[Anthropic Claude]
+        J[Google Gemini]
+        K[OpenAI / Codex]
+        L[GitHub Copilot]
+        M[AWS Kiro]
+        N[Antigravity]
+        O[Cursor API]
+    end
+
+    A --> E
+    B --> E
+    C --> E
+    D --> E
+    E --> F
+    F --> G
+    G --> I
+    G --> J
+    G --> K
+    G --> L
+    G --> M
+    G --> N
+    G --> O
+    H -.-> E
+    H -.-> G
+```
+
+### المبدأ الأساسي: الترجمة المحورية
+
+تمر جميع ترجمة التنسيقات عبر **تنسيق OpenAI كمركز**:
+
+```
+Client Format → [OpenAI Hub] → Provider Format    (request)
+Provider Format → [OpenAI Hub] → Client Format    (response)
+```
+
+هذا يعني أنك تحتاج فقط إلى مترجمين **N** (واحد لكل تنسيق) بدلاً من **N²** (كل زوج).
+
+---
+
+## 3. هيكل المشروع
+
+```
+omniroute/
+├── open-sse/                  ← Core proxy library (portable, framework-agnostic)
+│   ├── index.js               ← Main entry point, exports everything
+│   ├── config/                ← Configuration & constants
+│   ├── executors/             ← Provider-specific request execution
+│   ├── handlers/              ← Request handling orchestration
+│   ├── services/              ← Business logic (auth, models, fallback, usage)
+│   ├── translator/            ← Format translation engine
+│   │   ├── request/           ← Request translators (8 files)
+│   │   ├── response/          ← Response translators (7 files)
+│   │   └── helpers/           ← Shared translation utilities (6 files)
+│   └── utils/                 ← Utility functions
+├── src/                       ← Application layer (Express/Worker runtime)
+│   ├── app/                   ← Web UI, API routes, middleware
+│   ├── lib/                   ← Database, auth, and shared library code
+│   ├── mitm/                  ← Man-in-the-middle proxy utilities
+│   ├── models/                ← Database models
+│   ├── shared/                ← Shared utilities (wrappers around open-sse)
+│   ├── sse/                   ← SSE endpoint handlers
+│   └── store/                 ← State management
+├── data/                      ← Runtime data (credentials, logs)
+│   └── provider-credentials.json   (external credentials override, gitignored)
+└── tester/                    ← Test utilities
+```
+
+---
+
+## 4. تفصيل الوحدة تلو الأخرى
+
+### 4.1 التكوين (`open-sse/config/`)
+
+**المصدر الوحيد للحقيقة** لجميع إعدادات الموفر.
+
+| ملف                           | الغرض                                                                                                                                                                                                                        |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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`             | تعريف المخطط لنماذج أولاما المحلية (الاسم، الحجم، العائلة، التكميم).                                                                                                                                                         |
+
+#### تدفق تحميل بيانات الاعتماد
+
+```mermaid
+flowchart TD
+    A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"]
+    B --> C{"data/provider-credentials.json\nexists?"}
+    C -->|Yes| D["credentialLoader reads JSON"]
+    C -->|No| E["Use hardcoded defaults"]
+    D --> F{"For each provider in JSON"}
+    F --> G{"Provider exists\nin PROVIDERS?"}
+    G -->|No| H["Log warning, skip"]
+    G -->|Yes| I{"Value is object?"}
+    I -->|No| J["Log warning, skip"]
+    I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"]
+    K --> F
+    H --> F
+    J --> F
+    F -->|Done| L["PROVIDERS ready with\nmerged credentials"]
+    E --> L
+```
+
+---
+
+### 4.2 المنفذون (`open-sse/executors/`)
+
+يقوم المنفذون بتغليف **المنطق الخاص بالمزود** باستخدام **نمط الإستراتيجية**. يتجاوز كل منفذ الأساليب الأساسية حسب الحاجة.
+
+```mermaid
+classDiagram
+    class BaseExecutor {
+        +buildUrl(model, stream, options)
+        +buildHeaders(credentials, stream, body)
+        +transformRequest(body, model, stream, credentials)
+        +execute(url, options)
+        +shouldRetry(status, error)
+        +refreshCredentials(credentials, log)
+    }
+
+    class DefaultExecutor {
+        +refreshCredentials()
+    }
+
+    class AntigravityExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +shouldRetry()
+        +refreshCredentials()
+    }
+
+    class CursorExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseResponse()
+        +generateChecksum()
+    }
+
+    class KiroExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseEventStream()
+        +refreshCredentials()
+    }
+
+    BaseExecutor <|-- DefaultExecutor
+    BaseExecutor <|-- AntigravityExecutor
+    BaseExecutor <|-- CursorExecutor
+    BaseExecutor <|-- KiroExecutor
+    BaseExecutor <|-- CodexExecutor
+    BaseExecutor <|-- GeminiCLIExecutor
+    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`       | —                                                   | المصنع: اسم موفر الخرائط ← فئة المنفذ، مع خيار احتياطي افتراضي                                                                                      |
+
+---
+
+### 4.3 المعالجات (`open-sse/handlers/`)
+
+**طبقة التنسيق** — تتولى تنسيق الترجمة والتنفيذ والتدفق ومعالجة الأخطاء.
+
+| ملف                   | الغرض                                                                                                                                                                                              |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chatCore.ts`         | ** المنسق المركزي ** (~ 600 سطر). يتعامل مع دورة حياة الطلب الكاملة: اكتشاف التنسيق ← الترجمة ← إرسال المنفذ ← استجابة التدفق/غير المتدفق ← تحديث الرمز المميز ← معالجة الأخطاء ← تسجيل الاستخدام. |
+| `responsesHandler.ts` | محول واجهة برمجة تطبيقات استجابات OpenAI: يحول تنسيق الردود ← إكمالات الدردشة ← يرسل إلى `chatCore` ← يحول SSE مرة أخرى إلى تنسيق الردود.                                                          |
+| `embeddings.ts`       | معالج إنشاء التضمين: يحل نموذج التضمين → الموفر، ويرسل إلى واجهة برمجة تطبيقات الموفر، ويعيد استجابة التضمين المتوافقة مع OpenAI. يدعم 6+ مقدمي الخدمات.                                           |
+| `imageGeneration.ts`  | معالج إنشاء الصور: يحل نموذج الصورة → الموفر، ويدعم الأوضاع المتوافقة مع OpenAI، وGemini-image (Antigravity)، والوضع الاحتياطي (Nebius). إرجاع صور base64 أو URL.                                  |
+
+#### دورة حياة الطلب (chatCore.ts)
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant chatCore
+    participant Translator
+    participant Executor
+    participant Provider
+
+    Client->>chatCore: Request (any format)
+    chatCore->>chatCore: Detect source format
+    chatCore->>chatCore: Check bypass patterns
+    chatCore->>chatCore: Resolve model & provider
+    chatCore->>Translator: Translate request (source → OpenAI → target)
+    chatCore->>Executor: Get executor for provider
+    Executor->>Executor: Build URL, headers, transform request
+    Executor->>Executor: Refresh credentials if needed
+    Executor->>Provider: HTTP fetch (streaming or non-streaming)
+
+    alt Streaming
+        Provider-->>chatCore: SSE stream
+        chatCore->>chatCore: Pipe through SSE transform stream
+        Note over chatCore: Transform stream translates<br/>each chunk: target → OpenAI → source
+        chatCore-->>Client: Translated SSE stream
+    else Non-streaming
+        Provider-->>chatCore: JSON response
+        chatCore->>Translator: Translate response
+        chatCore-->>Client: Translated JSON
+    end
+
+    alt Error (401, 429, 500...)
+        chatCore->>Executor: Retry with credential refresh
+        chatCore->>chatCore: Account fallback logic
+    end
+```
+
+---
+
+### 4.4 الخدمات (`open-sse/services/`)
+
+منطق الأعمال الذي يدعم المعالجات والمنفذين.
+
+| ملف                  | الغرض                                                                                                                                                                                                                                                                                           |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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-*`) لأزواج الموفر/النموذج الملموسة بناءً على التوفر والأولوية.                                                                                                                                                       |
+
+#### إلغاء البيانات المكررة لتحديث الرمز المميز
+
+```mermaid
+sequenceDiagram
+    participant R1 as Request 1
+    participant R2 as Request 2
+    participant Cache as refreshPromiseCache
+    participant OAuth as OAuth Provider
+
+    R1->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: No in-flight promise
+    Cache->>OAuth: Start refresh
+    R2->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: Found in-flight promise
+    Cache-->>R2: Return existing promise
+    OAuth-->>Cache: New access token
+    Cache-->>R1: New access token
+    Cache-->>R2: Same access token (shared)
+    Cache->>Cache: Delete cache entry
+```
+
+#### آلة الحالة الاحتياطية للحساب
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active
+    Active --> Error: Request fails (401/429/500)
+    Error --> Cooldown: Apply backoff
+    Cooldown --> Active: Cooldown expires
+    Active --> Active: Request succeeds (reset backoff)
+
+    state Error {
+        [*] --> ClassifyError
+        ClassifyError --> ShouldFallback: Rate limit / Auth / Transient
+        ClassifyError --> NoFallback: 400 Bad Request
+    }
+
+    state Cooldown {
+        [*] --> ExponentialBackoff
+        ExponentialBackoff: Level 0 = 1s
+        ExponentialBackoff: Level 1 = 2s
+        ExponentialBackoff: Level 2 = 4s
+        ExponentialBackoff: Max = 2min
+    }
+```
+
+#### سلسلة نماذج كومبو
+
+```mermaid
+flowchart LR
+    A["Request with\ncombo model"] --> B["Model A"]
+    B -->|"2xx Success"| C["Return response"]
+    B -->|"429/401/500"| D{"Fallback\neligible?"}
+    D -->|Yes| E["Model B"]
+    D -->|No| F["Return error"]
+    E -->|"2xx Success"| C
+    E -->|"429/401/500"| G{"Fallback\neligible?"}
+    G -->|Yes| H["Model C"]
+    G -->|No| F
+    H -->|"2xx Success"| C
+    H -->|"Fail"| I["All failed →\nReturn last status"]
+```
+
+---
+
+### مترجم 4.5 (`open-sse/translator/`)
+
+**محرك ترجمة التنسيق** باستخدام نظام إضافي للتسجيل الذاتي.
+
+####الهندسة المعمارية
+
+```mermaid
+graph TD
+    subgraph "Request Translation"
+        A["Claude → OpenAI"]
+        B["Gemini → OpenAI"]
+        C["Antigravity → OpenAI"]
+        D["OpenAI Responses → OpenAI"]
+        E["OpenAI → Claude"]
+        F["OpenAI → Gemini"]
+        G["OpenAI → Kiro"]
+        H["OpenAI → Cursor"]
+    end
+
+    subgraph "Response Translation"
+        I["Claude → OpenAI"]
+        J["Gemini → OpenAI"]
+        K["Kiro → OpenAI"]
+        L["Cursor → OpenAI"]
+        M["OpenAI → Claude"]
+        N["OpenAI → Antigravity"]
+        O["OpenAI → Responses"]
+    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`.                                                                                                                                                           |
+
+#### التصميم الرئيسي: المكونات الإضافية للتسجيل الذاتي
+
+```javascript
+// Each translator file calls register() on import:
+import { register } from "../index.js";
+register("claude", "openai", translateClaudeToOpenAI);
+
+// The index.js imports all translator files, triggering registration:
+import "./request/claude-to-openai.js"; // ← self-registers
+```
+
+---
+
+### 4.6 الأدوات المساعدة (`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 ثانية.                                                        |
+
+#### خط أنابيب تدفق SSE
+
+```mermaid
+flowchart TD
+    A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"]
+    B --> C["Buffer lines\n(split on newline)"]
+    C --> D["parseSSELine()\n(trim whitespace, parse JSON)"]
+    D --> E{"Mode?"}
+    E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"]
+    E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"]
+    F --> H["hasValuableContent()\nfilter empty chunks"]
+    G --> H
+    H -->|"Has content"| I["extractUsage()\ntrack token counts"]
+    H -->|"Empty"| J["Skip chunk"]
+    I --> K["formatSSE()\nserialize + clean perf_metrics"]
+    K --> L["TextEncoder\n(per-stream instance)"]
+    L --> M["Enqueue to\nclient stream"]
+
+    style A fill:#f9f,stroke:#333
+    style M fill:#9f9,stroke:#333
+```
+
+#### بنية جلسة مسجل الطلب
+
+```
+logs/
+└── claude_gemini_claude-sonnet_20260208_143045/
+    ├── 1_req_client.json      ← Raw client request
+    ├── 2_req_source.json      ← After initial conversion
+    ├── 3_req_openai.json      ← OpenAI intermediate format
+    ├── 4_req_target.json      ← Final target format
+    ├── 5_res_provider.txt     ← Provider SSE chunks (streaming)
+    ├── 5_res_provider.json    ← Provider response (non-streaming)
+    ├── 6_res_openai.txt       ← OpenAI intermediate chunks
+    ├── 7_res_client.txt       ← Client-facing SSE chunks
+    └── 6_error.json           ← Error details (if any)
+```
+
+---
+
+### 4.7 طبقة التطبيق (`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/`  | إدارة حالة التطبيق                                                                                      |
+
+#### مسارات API البارزة
+
+| الطريق                                        | طرق                | الغرض                                                                          |
+| --------------------------------------------- | ------------------ | ------------------------------------------------------------------------------ |
+| `/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`                            | احصل على           | حالة حد المعدل لكل حساب                                                        |
+
+---
+
+## 5. أنماط التصميم الرئيسية
+
+### 5.1 الترجمة المحورية والمتحدثة
+
+تتم ترجمة جميع التنسيقات من خلال **تنسيق OpenAI كمحور**. لا تتطلب إضافة موفر جديد سوى كتابة **زوج واحد** من المترجمين (من/إلى OpenAI)، وليس عدد N من المترجمين.
+
+### 5.2 نمط استراتيجية المنفذ
+
+كل مزود لديه فئة منفذة مخصصة ترث من `BaseExecutor`. يقوم المصنع في `executors/index.ts` باختيار المصنع المناسب في وقت التشغيل.
+
+### 5.3 نظام البرنامج المساعد للتسجيل الذاتي
+
+تسجل وحدات المترجم نفسها عند الاستيراد عبر `register()`. إن إضافة مترجم جديد يعني مجرد إنشاء ملف واستيراده.
+
+### 5.4 التراجع في الحساب مع التراجع الأسي
+
+عندما يقوم مقدم الخدمة بإرجاع 429/401/500، يمكن للنظام التبديل إلى الحساب التالي، مع تطبيق فترات التباطؤ الأسية (1ث → 2ث → 4ث → 2 دقيقة كحد أقصى).
+
+### 5.5 سلاسل نماذج كومبو
+
+يقوم "التحرير والسرد" بتجميع سلاسل `provider/model` متعددة. إذا فشل الأول، يتم الرجوع إلى التالي تلقائيًا.
+
+### 5.6 ترجمة متدفقة رائعة
+
+تحافظ ترجمة الاستجابة على الحالة عبر أجزاء SSE (تتبع كتلة التفكير، وتراكم استدعاءات الأداة، وفهرسة كتلة المحتوى) عبر آلية `initState()`.
+
+### 5.7 المخزن المؤقت لسلامة الاستخدام
+
+تتم إضافة مخزن مؤقت مكون من 2000 رمز مميز إلى الاستخدام المبلغ عنه لمنع العملاء من الوصول إلى حدود نافذة السياق بسبب الحمل الزائد من مطالبات النظام وترجمة التنسيق.
+
+---
+
+## 6. التنسيقات المدعومة
+
+| تنسيق                               | الاتجاه        | المعرف             |
+| ----------------------------------- | -------------- | ------------------ |
+| استكمالات الدردشة OpenAI            | المصدر + الهدف | `openai`           |
+| واجهة برمجة تطبيقات استجابات OpenAI | المصدر + الهدف | `openai-responses` |
+| أنثروبي كلود                        | المصدر + الهدف | `claude`           |
+| جوجل الجوزاء                        | المصدر + الهدف | `gemini`           |
+| جوجل الجوزاء CLI                    | الهدف فقط      | `gemini-cli`       |
+| مكافحة الجاذبية                     | المصدر + الهدف | `antigravity`      |
+| أوس كيرو                            | الهدف فقط      | `kiro`             |
+| المؤشر                              | الهدف فقط      | `cursor`           |
+
+---
+
+## 7. مقدمو الخدمة المدعومين
+
+| مقدم                      | طريقة المصادقة           | المنفذ          | الملاحظات الرئيسية                                        |
+| ------------------------- | ------------------------ | --------------- | --------------------------------------------------------- |
+| أنثروبي كلود              | مفتاح 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                | الافتراضي       | ديناميكي: أي نقطة نهاية متوافقة مع كلود                   |
+
+---
+
+## 8. ملخص تدفق البيانات
+
+### طلب البث
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor\nbuildUrl + buildHeaders"]
+    D --> E["fetch(providerURL)"]
+    E --> F["createSSEStream()\nTRANSLATE mode"]
+    F --> G["parseSSELine()"]
+    G --> H["translateResponse()\ntarget → OpenAI → source"]
+    H --> I["extractUsage()\n+ addBuffer"]
+    I --> J["formatSSE()"]
+    J --> K["Client receives\ntranslated SSE"]
+    K --> L["logUsage()\nsaveRequestUsage()"]
+```
+
+### طلب عدم البث
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor.execute()"]
+    D --> E["translateResponse()\ntarget → OpenAI → source"]
+    E --> F["Return JSON\nresponse"]
+```
+
+### تجاوز التدفق (كلود CLI)
+
+```mermaid
+flowchart LR
+    A["Claude CLI request"] --> B{"Match bypass\npattern?"}
+    B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"]
+    B -->|"No match"| D["Normal flow"]
+    C --> E["Translate to\nsource format"]
+    E --> F["Return without\ncalling provider"]
+```

docs/i18n/ar/FEATURES.md

@@ -0,0 +1,77 @@
+# 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.
+
+---
+
+## 🔌 مقدمو الخدمة
+
+إدارة اتصالات مزودي الذكاء الاصطناعي: موفري OAuth (Claude Code وCodex وGemini CLI) وموفري مفاتيح API (Groq وDeepSeek وOpenRouter) ومقدمي الخدمات المجانية (iFlow وQwen وKiro).
+
+![Providers Dashboard](screenshots/01-providers.png)
+
+---
+
+## 🎨 المجموعات
+
+أنشئ مجموعات توجيه النماذج باستخدام 6 إستراتيجيات: التعبئة أولاً، والتدوير الدائري، وقوة الاختيارين، والعشوائية، والأقل استخدامًا، والمُحسَّنة من حيث التكلفة. تقوم كل مجموعة بتسلسل نماذج متعددة مع الرجوع التلقائي.
+
+![Combos Dashboard](screenshots/02-combos.png)
+
+---
+
+## 📊تحليلات
+
+تحليلات استخدام شاملة مع استهلاك الرمز المميز، وتقديرات التكلفة، وخرائط النشاط، ومخططات التوزيع الأسبوعية، والتفاصيل لكل مزود.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
+
+---
+
+## 🏥 صحة النظام
+
+المراقبة في الوقت الفعلي: وقت التشغيل، والذاكرة، والإصدار، والنسب المئوية لزمن الوصول (p50/p95/p99)، وإحصائيات ذاكرة التخزين المؤقت، وحالات قاطع دائرة الموفر.
+
+![Health Dashboard](screenshots/04-health.png)
+
+---
+
+## 🔧 ملعب المترجم
+
+أربعة أوضاع لتصحيح أخطاء ترجمات واجهة برمجة التطبيقات: **ساحة اللعب** (محول التنسيق)، **اختبار الدردشة** (الطلبات المباشرة)، **منصة الاختبار** (اختبارات الدفعة)، و **المراقب المباشر** (البث في الوقت الفعلي).
+
+![Translator Playground](screenshots/05-translator.png)
+
+---
+
+## ⚙️ الإعدادات
+
+الإعدادات العامة، وتخزين النظام، وإدارة النسخ الاحتياطي (قاعدة بيانات التصدير/الاستيراد)، والمظهر (الوضع الداكن/الفاتح)، والأمان (يتضمن حماية نقطة نهاية واجهة برمجة التطبيقات وحظر الموفر المخصص)، والتوجيه، والمرونة، والتكوين المتقدم.
+
+![Settings Dashboard](screenshots/06-settings.png)
+
+---
+
+## 🔧 أدوات CLI
+
+تكوين بنقرة واحدة لأدوات ترميز الذكاء الاصطناعي: Claude Code، وCodex CLI، وGemini CLI، وOpenClaw، وKilo Code، وAntigravity.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+
+---
+
+## 📝 سجلات الطلب
+
+تسجيل الطلبات في الوقت الفعلي مع التصفية حسب الموفر والطراز والحساب ومفتاح واجهة برمجة التطبيقات. يعرض رموز الحالة واستخدام الرمز المميز ووقت الاستجابة وتفاصيل الاستجابة.
+
+![Usage Logs](screenshots/08-usage.png)
+
+---
+
+## 🌐 نقطة نهاية API
+
+نقطة نهاية واجهة برمجة التطبيقات الموحدة الخاصة بك مع تفاصيل الإمكانات: عمليات إكمال الدردشة والتضمين وإنشاء الصور وإعادة الترتيب والنسخ الصوتي ومفاتيح واجهة برمجة التطبيقات المسجلة.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)

docs/i18n/ar/TROUBLESHOOTING.md

@@ -0,0 +1,219 @@
+# استكشاف الأخطاء وإصلاحها
+
+🌐 **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.
+
+---
+
+## إصلاحات سريعة
+
+| مشكلة                             | الحل                                                              |
+| --------------------------------- | ----------------------------------------------------------------- |
+| تسجيل الدخول الأول لا يعمل        | تحقق من `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 لاستمرارية الإعدادات) |
+
+---
+
+## مشكلات المزود
+
+### "نموذج اللغة لم يقدم رسائل"
+
+**السبب:** استنفدت حصة الموفر.
+
+**الإصلاح:**
+
+1. تحقق من تعقب الحصص في لوحة القيادة
+2. استخدم مجموعة من المستويات الاحتياطية
+3. قم بالتبديل إلى الطبقة الأرخص/المجانية
+
+### تحديد المعدل
+
+**السبب:** استنفدت حصة الاشتراك.
+
+**الإصلاح:**
+
+- إضافة احتياطي: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- استخدم GLM/MiniMax كنسخة احتياطية رخيصة الثمن
+
+### انتهت صلاحية رمز OAuth
+
+يقوم OmniRoute بتحديث الرموز المميزة تلقائيًا. إذا استمرت المشكلات:
+
+1. لوحة المعلومات → الموفر → إعادة الاتصال
+2. قم بحذف وإعادة إضافة اتصال الموفر
+
+---
+
+## مشكلات السحابة
+
+### أخطاء المزامنة السحابية
+
+1. تحقق من نقاط `BASE_URL` لمثيلك قيد التشغيل (على سبيل المثال، `http://localhost:20128`)
+2. تحقق من نقاط `CLOUD_URL` إلى نقطة نهاية السحابة الخاصة بك (على سبيل المثال، `https://omniroute.dev`)
+3. حافظ على محاذاة قيم `NEXT_PUBLIC_*` مع القيم من جانب الخادم
+
+### السحابة `stream=false` تُرجع 500
+
+**العَرَض:** `Unexpected token 'd'...` على نقطة نهاية السحابة للمكالمات غير المتدفقة.
+
+**السبب:** يقوم المنبع بإرجاع حمولة SSE بينما يتوقع العميل JSON.
+
+**الحل البديل:** استخدم `stream=true` للمكالمات السحابية المباشرة. يتضمن وقت التشغيل المحلي SSE → JSON الاحتياطي.
+
+### تقول السحابة إنها متصلة ولكن "مفتاح واجهة برمجة التطبيقات غير صالح"
+
+1. قم بإنشاء مفتاح جديد من لوحة المعلومات المحلية (`/api/keys`)
+2. قم بتشغيل المزامنة السحابية: قم بتمكين السحابة → المزامنة الآن
+3. لا يزال بإمكان المفاتيح القديمة/غير المتزامنة إرجاع `401` على السحابة
+
+---
+
+## مشكلات عامل الميناء
+
+### تظهر أداة CLI غير مثبتة
+
+1. تحقق من حقول وقت التشغيل: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. بالنسبة للوضع المحمول: استخدم هدف الصورة `runner-cli` (CLIs المجمعة)
+3. بالنسبة لوضع تثبيت المضيف: قم بتعيين `CLI_EXTRA_PATHS` وتثبيت دليل حاوية المضيف للقراءة فقط
+4. إذا تم العثور على `installed=true` و`runnable=false`: ثنائي ولكن فشل التحقق من الصحة
+
+### التحقق السريع من وقت التشغيل
+
+```bash
+curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+```
+
+---
+
+## قضايا التكلفة
+
+### ارتفاع التكاليف
+
+1. تحقق من إحصائيات الاستخدام في لوحة المعلومات → الاستخدام
+2. قم بتبديل النموذج الأساسي إلى GLM/MiniMax
+3. استخدم الطبقة المجانية (Gemini CLI، iFlow) للمهام غير الحرجة
+4. قم بتعيين ميزانيات التكلفة لكل مفتاح واجهة برمجة التطبيقات: لوحة المعلومات ← مفاتيح واجهة برمجة التطبيقات ← الميزانية
+
+---
+
+## التصحيح
+
+### تمكين سجلات الطلبات
+
+قم بتعيين `ENABLE_REQUEST_LOGS=true` في ملف `.env` الخاص بك. تظهر السجلات ضمن الدليل `logs/`.
+
+### التحقق من صحة مقدم الخدمة
+
+```bash
+# Health dashboard
+http://localhost:20128/dashboard/health
+
+# API health check
+curl http://localhost:20128/api/monitoring/health
+```
+
+### تخزين وقت التشغيل
+
+- الحالة الرئيسية: `${DATA_DIR}/db.json` (المزودون، المجموعات، الأسماء المستعارة، المفاتيح، الإعدادات)
+- الاستخدام: `${DATA_DIR}/usage.json`، `${DATA_DIR}/log.txt`، `${DATA_DIR}/call_logs/`
+- سجلات الطلب: `<repo>/logs/...` (عندما `ENABLE_REQUEST_LOGS=true`)
+
+---
+
+## مشكلات قواطع الدائرة
+
+### الموفر عالق في الحالة المفتوحة
+
+عندما يكون قاطع دائرة الموفر مفتوحًا، يتم حظر الطلبات حتى تنتهي فترة التهدئة.
+
+**الإصلاح:**
+
+1. انتقل إلى **لوحة التحكم ← الإعدادات ← المرونة**
+2. تحقق من بطاقة قاطع الدائرة الكهربائية الخاصة بالمزود المتأثر
+3. انقر فوق **إعادة تعيين الكل** لمسح جميع القواطع، أو انتظر حتى تنتهي فترة التهدئة
+4. تحقق من أن الموفر متاح فعليًا قبل إعادة التعيين
+
+### يستمر المزود في تعطيل قاطع الدائرة
+
+إذا دخل مقدم الخدمة بشكل متكرر في الحالة المفتوحة:
+
+1. تحقق من **Dashboard → Health → Provider Health** لمعرفة نمط الفشل
+2. انتقل إلى **الإعدادات → المرونة → ملفات تعريف الموفر** وقم بزيادة حد الفشل
+3. تحقق مما إذا كان الموفر قد قام بتغيير حدود واجهة برمجة التطبيقات (API) أو طلب إعادة المصادقة
+4. قم بمراجعة القياس عن بعد لزمن الاستجابة - قد يتسبب زمن الاستجابة العالي في حدوث أعطال بسبب انتهاء المهلة
+
+---
+
+## مشكلات النسخ الصوتي
+
+### خطأ "نموذج غير مدعوم".
+
+- تأكد من أنك تستخدم البادئة الصحيحة: `deepgram/nova-3` أو `assemblyai/best`
+- تحقق من أن الموفر متصل في **لوحة التحكم ← الموفرون**
+
+### يعود النسخ فارغًا أو يفشل
+
+- تحقق من تنسيقات الصوت المدعومة: `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`
+- التحقق من أن حجم الملف يقع ضمن حدود الموفر (عادةً أقل من 25 ميجابايت)
+- التحقق من صلاحية مفتاح API الخاص بالموفر في بطاقة المزود
+
+---
+
+## تصحيح أخطاء المترجم
+
+استخدم **لوحة المعلومات → المترجم** لتصحيح مشكلات ترجمة التنسيق:
+
+| الوضع                | متى تستخدم                                                                         |
+| -------------------- | ---------------------------------------------------------------------------------- |
+| **ساحة اللعب**       | قارن تنسيقات الإدخال/الإخراج جنبًا إلى جنب — الصق طلبًا فاشلاً لترى كيف تتم ترجمته |
+| ** اختبار الدردشة ** | أرسل رسائل مباشرة وافحص حمولة الطلب/الاستجابة الكاملة بما في ذلك الرؤوس            |
+| ** مقعد الاختبار **  | قم بإجراء اختبارات مجمعة عبر مجموعات التنسيق للعثور على الترجمات المعطلة           |
+| **مراقبة حية**       | شاهد تدفق الطلبات في الوقت الفعلي للتعرف على مشكلات الترجمة المتقطعة               |
+
+### مشكلات التنسيق الشائعة
+
+- **لا تظهر علامات التفكير** — تحقق مما إذا كان الموفر المستهدف يدعم التفكير وإعداد ميزانية التفكير
+- **استدعاءات الأداة** — قد تؤدي بعض ترجمات التنسيق إلى إزالة الحقول غير المدعومة؛ تحقق في وضع الملعب
+- **مطالبة النظام مفقودة** — يتعامل نظام 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\_\_
+
+---
+
+## إعدادات المرونة
+
+### لا يتم تشغيل حد المعدل التلقائي
+
+- ينطبق حد المعدل التلقائي فقط على موفري مفاتيح واجهة برمجة التطبيقات (وليس OAuth/الاشتراك)
+- تحقق من أن **الإعدادات → المرونة → ملفات تعريف الموفر** تم تمكين حد المعدل التلقائي
+- تحقق مما إذا كان الموفر يعرض `429` رموز الحالة أو رؤوس `Retry-After`
+
+### ضبط التراجع الأسي
+
+تدعم ملفات تعريف الموفر هذه الإعدادات:
+
+- **التأخير الأساسي** — وقت الانتظار الأولي بعد الفشل الأول (الافتراضي: 1 ثانية)
+- **الحد الأقصى للتأخير** — الحد الأقصى لوقت الانتظار (الافتراضي: 30 ثانية)
+- **المضاعف** — مقدار زيادة التأخير لكل فشل متتالي (الافتراضي: 2x)
+
+### قطيع مضاد للرعد
+
+عندما تصل العديد من الطلبات المتزامنة إلى موفر محدود السعر، يستخدم OmniRoute تحديد المعدل التلقائي + mutex لإجراء تسلسل للطلبات ومنع حالات الفشل المتتالية. وهذا تلقائي لموفري مفاتيح API.
+
+---
+
+## هل مازلت عالقًا؟
+
+- **مشكلات GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **الهندسة المعمارية**: راجع [link](ARCHITECTURE.md) للحصول على التفاصيل الداخلية
+- **مرجع واجهة برمجة التطبيقات**: راجع [link](API_REFERENCE.md) لجميع نقاط النهاية
+- **لوحة معلومات الصحة**: تحقق من **لوحة المعلومات ← الصحة** لمعرفة حالة النظام في الوقت الفعلي
+- **المترجم**: استخدم **لوحة المعلومات ← المترجم** لتصحيح مشكلات التنسيق

docs/i18n/ar/USER_GUIDE.md

@@ -0,0 +1,698 @@
+# دليل المستخدم
+
+🌐 **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.
+
+---
+
+## جدول المحتويات
+
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
+
+## 💰 لمحة سريعة عن الأسعار
+
+| الطبقة                             | مقدم                                | التكلفة                | إعادة ضبط الحصص         | الأفضل لـ                              |
+| ---------------------------------- | ----------------------------------- | ---------------------- | ----------------------- | -------------------------------------- |
+| **💳الإشتراك**                     | كلود كود (برو)                      | 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                     | غير محدود               | كلود مجاني                             |
+
+**💡 نصيحة احترافية:** ابدأ مع مجموعة Gemini CLI (180 ألفًا مجانًا شهريًا) + مجموعة iFlow (مجانية غير محدودة) = تكلفة 0 دولار!
+
+---
+
+## 🎯 حالات الاستخدام
+
+### الحالة 1: "لدي اشتراك Claude Pro"
+
+**المشكلة:** تنتهي صلاحية الحصة غير المستخدمة، وحدود المعدل أثناء عملية الترميز المكثف
+
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6        (use subscription fully)
+  2. glm/glm-4.7               (cheap backup when quota out)
+  3. if/kimi-k2-thinking       (free emergency fallback)
+
+Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
+vs. $20 + hitting limits = frustration
+```
+
+### الحالة 2: "أريد تكلفة صفرية"
+
+**المشكلة:** لا أستطيع تحمل تكلفة الاشتراكات، وتحتاج إلى ترميز يعتمد على الذكاء الاصطناعي
+
+```
+Combo: "free-forever"
+  1. gc/gemini-3-flash         (180K free/month)
+  2. if/kimi-k2-thinking       (unlimited free)
+  3. qw/qwen3-coder-plus       (unlimited free)
+
+Monthly cost: $0
+Quality: Production-ready models
+```
+
+### الحالة 3: "أحتاج إلى تشفير على مدار 24 ساعة طوال أيام الأسبوع، دون انقطاع"
+
+**المشكلة:** المواعيد النهائية، لا أستطيع تحمل فترات التوقف عن العمل
+
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-6        (best quality)
+  2. cx/gpt-5.2-codex          (second subscription)
+  3. glm/glm-4.7               (cheap, resets daily)
+  4. minimax/MiniMax-M2.1      (cheapest, 5h reset)
+  5. if/kimi-k2-thinking       (free unlimited)
+
+Result: 5 layers of fallback = zero downtime
+Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
+```
+
+### الحالة 4: "أريد ذكاءً اصطناعيًا مجانيًا في OpenClaw"
+
+**المشكلة:** تحتاج إلى مساعد الذكاء الاصطناعي في تطبيقات المراسلة، مجانًا تمامًا
+
+```
+Combo: "openclaw-free"
+  1. if/glm-4.7                (unlimited free)
+  2. if/minimax-m2.1           (unlimited free)
+  3. if/kimi-k2-thinking       (unlimited free)
+
+Monthly cost: $0
+Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+```
+
+---
+
+## 📖 إعداد الموفر
+
+### 🔐 مقدمي الاشتراكات
+
+#### كلود كود (برو/ماكس)
+
+```bash
+Dashboard → Providers → Connect Claude Code
+→ OAuth login → Auto token refresh
+→ 5-hour + weekly quota tracking
+
+Models:
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**نصيحة احترافية:** استخدم Opus للمهام المعقدة، وSonnet للسرعة. OmniRoute يتتبع الحصة لكل نموذج!
+
+#### OpenAI Codex (Plus/Pro)
+
+```bash
+Dashboard → Providers → Connect Codex
+→ OAuth login (port 1455)
+→ 5-hour + weekly reset
+
+Models:
+  cx/gpt-5.2-codex
+  cx/gpt-5.1-codex-max
+```
+
+#### Gemini CLI (180 ألفًا شهريًا مجانًا!)
+
+```bash
+Dashboard → Providers → Connect Gemini CLI
+→ Google OAuth
+→ 180K completions/month + 1K/day
+
+Models:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**أفضل قيمة:** طبقة مجانية ضخمة! استخدم هذا قبل المستويات المدفوعة.
+
+#### مساعد جيثب
+
+```bash
+Dashboard → Providers → Connect GitHub
+→ OAuth via GitHub
+→ Monthly reset (1st of month)
+
+Models:
+  gh/gpt-5
+  gh/claude-4.5-sonnet
+  gh/gemini-3-pro
+```
+
+### 💰 مقدمو خدمات رخيصون
+
+#### GLM-4.7 (إعادة التعيين اليومي، 0.6 دولار/1 مليون)
+
+1. قم بالتسجيل: [Zhipu AI](https://open.bigmodel.cn/)
+2. احصل على مفتاح API من خطة الترميز
+3. لوحة المعلومات → إضافة مفتاح واجهة برمجة التطبيقات: الموفر: `glm`، مفتاح واجهة برمجة التطبيقات: `your-key`
+
+**الاستخدام:** `glm/glm-4.7` — **نصيحة احترافية:** توفر خطة البرمجة حصة 3× بتكلفة 1/7! إعادة الضبط يوميًا الساعة 10:00 صباحًا.
+
+#### MiniMax M2.1 (إعادة الضبط لمدة 5 ساعات، 0.20 دولار/1 مليون)
+
+1. قم بالتسجيل: [MiniMax](https://www.minimax.io/)
+2. احصل على مفتاح API → لوحة المعلومات → إضافة مفتاح API
+
+**الاستخدام:** `minimax/MiniMax-M2.1` — **نصيحة احترافية:** الخيار الأرخص للسياق الطويل (مليون رمز)!
+
+#### كيمي K2 (شقة بقيمة 9 دولارات في الشهر)
+
+1. الاشتراك: [Moonshot AI](https://platform.moonshot.ai/)
+2. احصل على مفتاح API → لوحة المعلومات → إضافة مفتاح API
+
+**الاستخدام:** `kimi/kimi-latest` — **نصيحة احترافية:** سعر ثابت قدره 9 دولارات شهريًا مقابل 10 ملايين رمز مميز = 0.90 دولارًا أمريكيًا/التكلفة الفعلية لمليون واحد!
+
+### 🆓 مقدمي الخدمة مجانًا
+
+#### iFlow (8 نماذج مجانية)
+
+```bash
+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 موديلات مجانية)
+
+```bash
+Dashboard → Connect Qwen → Device code auth → Unlimited usage
+
+Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
+```
+
+#### كيرو (كلود فري)
+
+```bash
+Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
+
+Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
+```
+
+---
+
+## 🎨 المجموعات
+
+### مثال 1: زيادة الاشتراك إلى الحد الأقصى → النسخ الاحتياطي الرخيص
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-6 (Subscription primary)
+  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
+  3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
+
+Use in CLI: premium-coding
+```
+
+### المثال 2: مجاني فقط (بدون تكلفة)
+
+```
+Name: free-combo
+Models:
+  1. gc/gemini-3-flash-preview (180K free/month)
+  2. if/kimi-k2-thinking (unlimited)
+  3. qw/qwen3-coder-plus (unlimited)
+
+Cost: $0 forever!
+```
+
+---
+
+## 🔧 تكامل CLI
+
+### بيئة تطوير متكاملة للمؤشر
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from omniroute dashboard]
+  Model: cc/claude-opus-4-6
+```
+
+### كلود كود
+
+تحرير `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-omniroute-api-key"
+}
+```
+
+### كوديكس سطر الأوامر
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-omniroute-api-key"
+codex "your prompt"
+```
+
+### OpenClaw
+
+تحرير `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": { "primary": "omniroute/if/glm-4.7" }
+    }
+  },
+  "models": {
+    "providers": {
+      "omniroute": {
+        "baseUrl": "http://localhost:20128/v1",
+        "apiKey": "your-omniroute-api-key",
+        "api": "openai-completions",
+        "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+      }
+    }
+  }
+}
+```
+
+**أو استخدم لوحة المعلومات:** أدوات CLI → OpenClaw → التكوين التلقائي
+
+### كلاين / متابعة / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-6
+```
+
+---
+
+## 🚀 النشر
+
+### نشر VPS
+
+```bash
+git clone https://github.com/diegosouzapw/OmniRoute.git
+cd OmniRoute && npm install && npm run build
+
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+export DATA_DIR="/var/lib/omniroute"
+export PORT="20128"
+export HOSTNAME="0.0.0.0"
+export NODE_ENV="production"
+export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
+export API_KEY_SECRET="endpoint-proxy-api-key-secret"
+
+npm run start
+# Or: pm2 start npm --name omniroute -- start
+```
+
+### عامل الميناء
+
+```bash
+# Build image (default = runner-cli with codex/claude/droid preinstalled)
+docker build -t omniroute:cli .
+
+# Portable mode (recommended)
+docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
+```
+
+بالنسبة للوضع المدمج مع المضيف مع ثنائيات CLI، راجع قسم Docker في المستندات الرئيسية.
+
+### متغيرات البيئة
+
+| متغير                 | الافتراضي                            | الوصف                                                            |
+| --------------------- | ------------------------------------ | ---------------------------------------------------------------- |
+| `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) |
+
+للحصول على مرجع متغير البيئة الكامل، راجع [README](../README.md).
+
+---
+
+## 📊 الموديلات المتوفرة
+
+<details>
+<summary><b>عرض جميع الموديلات المتاحة</b></summary>
+
+**كود كلود (`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`
+
+**Gemini CLI (`gc/`)** — مجانًا: `gc/gemini-3-flash-preview`، `gc/gemini-2.5-pro`
+
+**مساعد GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
+
+**GLM (`glm/`)** — 0.6 دولار/1 مليون: `glm/glm-4.7`
+
+**ميني ماكس (`minimax/`)** — 0.2 دولار/1 مليون: `minimax/MiniMax-M2.1`
+
+**iFlow (`if/`)** — مجانًا: `if/kimi-k2-thinking`، `if/qwen3-coder-plus`، `if/deepseek-r1`
+
+**كوين (`qw/`)** — مجانًا: `qw/qwen3-coder-plus`، `qw/qwen3-coder-flash`
+
+**كيرو (`kr/`)** — مجانًا: `kr/claude-sonnet-4.5`، `kr/claude-haiku-4.5`
+
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`، `ds/deepseek-reasoner`
+
+** جروك (`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`
+
+**ميسترال (`mistral/`)**: `mistral/mistral-large-2501`، `mistral/codestral-2501`
+
+**الحيرة (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+
+** معًا الذكاء الاصطناعي (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+
+**الذكاء الاصطناعي للألعاب النارية (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+
+** سيريبراس (`cerebras/`)**: `cerebras/llama-3.3-70b`
+
+**الترابط (`cohere/`)**: `cohere/command-r-plus-08-2024`
+
+** نفيديا نيم (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+</details>
+
+---
+
+## 🧩 ميزات متقدمة
+
+### نماذج مخصصة
+
+أضف أي معرف نموذج إلى أي مزود دون انتظار تحديث التطبيق:
+
+```bash
+# Via API
+curl -X POST http://localhost:20128/api/provider-models \
+  -H "Content-Type: application/json" \
+  -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}'
+
+# List: curl http://localhost:20128/api/provider-models?provider=openai
+# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
+```
+
+أو استخدم لوحة المعلومات: **المزودون → [الموفر] → النماذج المخصصة**.
+
+### مسارات موفر مخصصة
+
+توجيه الطلبات مباشرة إلى موفر محدد مع التحقق من صحة النموذج:
+
+```bash
+POST http://localhost:20128/v1/providers/openai/chat/completions
+POST http://localhost:20128/v1/providers/openai/embeddings
+POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
+
+تتم إضافة بادئة الموفر تلقائيًا في حالة فقدانها. تُرجع النماذج غير المتطابقة `400`.
+
+### تكوين وكيل الشبكة
+
+```bash
+# Set global proxy
+curl -X PUT http://localhost:20128/api/settings/proxy \
+  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
+
+# Per-provider proxy
+curl -X PUT http://localhost:20128/api/settings/proxy \
+  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
+
+# Test proxy
+curl -X POST http://localhost:20128/api/settings/proxy/test \
+  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
+```
+
+**الأسبقية:** خاص بالمفتاح ← خاص بالسرد والسرد ← خاص بالموفر ← عالمي ← البيئة.
+
+### واجهة برمجة تطبيقات الكتالوج النموذجي
+
+```bash
+curl http://localhost:20128/api/models/catalog
+```
+
+إرجاع النماذج المجمعة حسب الموفر مع الأنواع (`chat`، `embedding`، `image`).
+
+### المزامنة السحابية
+
+- موفري المزامنة والمجموعات والإعدادات عبر الأجهزة
+- مزامنة الخلفية التلقائية مع انتهاء المهلة + الفشل السريع
+- تفضيل جانب الخادم `BASE_URL`/`CLOUD_URL` في الإنتاج
+
+### LLM Gateway Intelligence (المرحلة 9)
+
+- **ذاكرة التخزين المؤقت الدلالية** — ذاكرة تخزين مؤقت تلقائية غير متدفقة، درجة الحرارة = 0 استجابات (تجاوز باستخدام `X-OmniRoute-No-Cache: true`)
+- **صلاحية الطلب** — إلغاء تكرار الطلبات خلال 5 ثوانٍ عبر رأس `Idempotency-Key` أو `X-Request-Id`
+- **تتبع التقدم** — الاشتراك في أحداث SSE `event: progress` عبر رأس `X-OmniRoute-Progress: true`
+
+---
+
+### ملعب المترجم
+
+الوصول عبر **لوحة المعلومات → المترجم**. تصحيح الأخطاء وتصور كيفية قيام OmniRoute بترجمة طلبات واجهة برمجة التطبيقات (API) بين مقدمي الخدمة.
+
+| الوضع                | الغرض                                                                         |
+| -------------------- | ----------------------------------------------------------------------------- |
+| **ساحة اللعب**       | حدد تنسيقات المصدر/الهدف، والصق طلبًا، وشاهد المخرجات المترجمة على الفور      |
+| ** اختبار الدردشة ** | أرسل رسائل الدردشة المباشرة من خلال الوكيل وافحص دورة الطلب/الاستجابة الكاملة |
+| ** مقعد الاختبار **  | قم بإجراء اختبارات مجمعة عبر مجموعات تنسيقات متعددة للتحقق من صحة الترجمة     |
+| **مراقبة حية**       | شاهد الترجمات في الوقت الفعلي أثناء تدفق الطلبات عبر الوكيل                   |
+
+**حالات الاستخدام:**
+
+- تصحيح سبب فشل مجموعة محددة من العميل/الموفر
+- التحقق من ترجمة علامات التفكير واستدعاءات الأدوات ومطالبات النظام بشكل صحيح
+- مقارنة اختلافات التنسيق بين تنسيقات OpenAI وClaude وGemini وResponsions API
+
+---
+
+### استراتيجيات التوجيه
+
+قم بالتكوين عبر **لوحة المعلومات → الإعدادات → التوجيه**.
+
+| استراتيجية               | الوصف                                                                                    |
+| ------------------------ | ---------------------------------------------------------------------------------------- |
+| ** املأ أولا **          | يستخدم الحسابات بترتيب الأولوية — يعالج الحساب الأساسي جميع الطلبات حتى تصبح غير متاحة   |
+| ** راوند روبن **         | للتنقل عبر جميع الحسابات بحد ثابت قابل للتكوين (الافتراضي: 3 مكالمات لكل حساب)           |
+| **P2C (قوة الاختيارين)** | يختار حسابين عشوائيين ويوجهك إلى الحساب الأكثر صحة - الأرصدة محملة بالوعي الصحي          |
+| **عشوائي**               | تحديد حساب عشوائيًا لكل طلب باستخدام خلط Fisher-Yates                                    |
+| **الأقل استخدامًا**      | التوجيهات إلى الحساب ذو الطابع الزمني الأقدم `lastUsedAt`، مع توزيع حركة المرور بالتساوي |
+| **التكلفة الأمثل**       | التوجيهات إلى الحساب ذي أقل قيمة أولوية، مع تحسين موفري الخدمة الأقل تكلفة               |
+
+#### الأسماء المستعارة لنموذج البدل
+
+قم بإنشاء أنماط أحرف البدل لإعادة تعيين أسماء النماذج:
+
+```
+Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-*               →  Target: gh/gpt-5.1-codex
+```
+
+تدعم أحرف البدل `*` (أي أحرف) و`?` (حرف واحد).
+
+#### سلاسل احتياطية
+
+تحديد السلاسل الاحتياطية العالمية التي تنطبق على جميع الطلبات:
+
+```
+Chain: production-fallback
+  1. cc/claude-opus-4-6
+  2. gh/gpt-5.1-codex
+  3. glm/glm-4.7
+```
+
+---
+
+### المرونة وقواطع الدائرة
+
+قم بالتكوين عبر **لوحة المعلومات → الإعدادات → المرونة**.
+
+تطبق OmniRoute المرونة على مستوى المزود من خلال أربعة مكونات:
+
+1. **ملفات تعريف الموفر** — التكوين لكل موفر لـ:
+   - عتبة الفشل (كم عدد حالات الفشل قبل الفتح)
+   - مدة التهدئة
+   - حساسية الكشف عن حد المعدل
+   - معلمات التراجع الأسي
+
+2. **حدود المعدل القابلة للتحرير** — الإعدادات الافتراضية على مستوى النظام قابلة للتكوين في لوحة المعلومات:
+   - **الطلبات في الدقيقة (RPM)** — الحد الأقصى للطلبات في الدقيقة لكل حساب
+   - **الحد الأدنى للوقت بين الطلبات** — الحد الأدنى للفجوة بالمللي ثانية بين الطلبات
+   - **الحد الأقصى للطلبات المتزامنة** — الحد الأقصى للطلبات المتزامنة لكل حساب
+   - انقر **تحرير** للتعديل، ثم **حفظ** أو **إلغاء**. تستمر القيم عبر واجهة برمجة تطبيقات المرونة.
+
+3. **قاطع الدائرة** — يتتبع حالات الفشل لكل مزود ويفتح الدائرة تلقائيًا عند الوصول إلى الحد الأدنى:
+   - **مغلق** (صحي) — تتدفق الطلبات بشكل طبيعي
+   - **مفتوح** — تم حظر الموفر مؤقتًا بعد الفشل المتكرر
+   - **HALF_OPEN** — اختبار ما إذا كان الموفر قد استعاد عافيته
+
+4. **السياسات والمعرفات المقفلة** — تعرض حالة قاطع الدائرة والمعرفات المقفلة مع إمكانية إلغاء القفل بالقوة.
+
+5. **الاكتشاف التلقائي لحدود المعدل** — يراقب الرؤوس `429` و`Retry-After` لتجنب الوصول إلى حدود معدل الموفر بشكل استباقي.
+
+**نصيحة احترافية:** استخدم زر **إعادة تعيين الكل** لمسح جميع قواطع الدائرة وفترات التباطؤ عندما يتعافى المزود من انقطاع الخدمة.
+
+---
+
+### تصدير / استيراد قاعدة البيانات
+
+إدارة النسخ الاحتياطية لقاعدة البيانات في **لوحة المعلومات → الإعدادات → النظام والتخزين**.
+
+| العمل                      | الوصف                                                                                                                                          |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **تصدير قاعدة البيانات**   | يقوم بتنزيل قاعدة بيانات SQLite الحالية كملف `.sqlite`                                                                                         |
+| **تصدير الكل (.tar.gz)**   | تنزيل أرشيف نسخ احتياطي كامل بما في ذلك: قاعدة البيانات، والإعدادات، والمجموعات، واتصالات الموفر (بدون بيانات اعتماد)، وبيانات تعريف مفتاح API |
+| **استيراد قاعدة البيانات** | قم بتحميل ملف `.sqlite` لاستبدال قاعدة البيانات الحالية. يتم إنشاء نسخة احتياطية للاستيراد المسبق تلقائيًا                                     |
+
+```bash
+# API: Export database
+curl -o backup.sqlite http://localhost:20128/api/db-backups/export
+
+# API: Export all (full archive)
+curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
+
+# API: Import database
+curl -X POST http://localhost:20128/api/db-backups/import \
+  -F "file=@backup.sqlite"
+```
+
+**التحقق من صحة الاستيراد:** يتم التحقق من صحة الملف المستورد للتأكد من سلامته (فحص براغما SQLite)، والجداول المطلوبة (`provider_connections`، `provider_nodes`، `combos`، `api_keys`)، والحجم (100 ميجابايت كحد أقصى).
+
+**حالات الاستخدام:**
+
+- ترحيل OmniRoute بين الأجهزة
+- إنشاء نسخ احتياطية خارجية للتعافي من الكوارث
+- مشاركة التكوينات بين أعضاء الفريق (تصدير الكل → مشاركة الأرشيف)
+
+---
+
+### لوحة تحكم الإعدادات
+
+يتم تنظيم صفحة الإعدادات في 5 علامات تبويب لسهولة التنقل:
+
+| علامة التبويب        | المحتويات                                                                                                                    |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| **الأمن**            | إعدادات تسجيل الدخول/كلمة المرور، والتحكم في الوصول إلى IP، ومصادقة API لـ `/models`، وحظر الموفر                            |
+| **التوجيه**          | استراتيجية التوجيه العالمية (6 خيارات)، والأسماء المستعارة لنماذج أحرف البدل، والسلاسل الاحتياطية، وافتراضيات التحرير والسرد |
+| **المرونة**          | ملفات تعريف الموفر، وحدود الأسعار القابلة للتحرير، وحالة قاطع الدائرة، والسياسات والمعرفات المقفلة                           |
+| **الذكاء الاصطناعي** | تكوين ميزانية التفكير، والحقن الفوري للنظام العالمي، وإحصائيات ذاكرة التخزين المؤقت السريعة                                  |
+| **متقدم**            | تكوين الوكيل العالمي (HTTP/SOCKS5)                                                                                           |
+
+---
+
+### إدارة التكاليف والميزانية
+
+الوصول عبر **لوحة التحكم ← التكاليف**.
+
+| علامة التبويب | الغرض                                                                                            |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| **الميزانية** | قم بتعيين حدود الإنفاق لكل مفتاح API باستخدام ميزانيات يومية/أسبوعية/شهرية وتتبع في الوقت الفعلي |
+| **التسعير**   | عرض وتحرير إدخالات تسعير النموذج - التكلفة لكل ألف رمز إدخال/إخراج لكل مزود                      |
+
+```bash
+# API: Set a budget
+curl -X POST http://localhost:20128/api/usage/budget \
+  -H "Content-Type: application/json" \
+  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
+
+# API: Get current budget status
+curl http://localhost:20128/api/usage/budget
+```
+
+**تتبع التكلفة:** يقوم كل طلب بتسجيل استخدام الرمز المميز وحساب التكلفة باستخدام جدول التسعير. عرض التفاصيل في **لوحة المعلومات → الاستخدام** حسب الموفر والطراز ومفتاح واجهة برمجة التطبيقات.
+
+---
+
+### النسخ الصوتي
+
+يدعم OmniRoute النسخ الصوتي عبر نقطة النهاية المتوافقة مع OpenAI:
+
+```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+
+# Example with curl
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+  -H "Authorization: Bearer your-api-key" \
+  -F "file=@audio.mp3" \
+  -F "model=deepgram/nova-3"
+```
+
+الموفرون المتاحون: **Deepgram** (`deepgram/`)، **AssemblyAI** (`assemblyai/`).
+
+تنسيقات الصوت المدعومة: `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`.
+
+---
+
+### استراتيجيات موازنة التحرير والسرد
+
+قم بتكوين التوازن لكل مجموعة في **لوحة المعلومات → المجموعات → إنشاء/تحرير → الإستراتيجية**.
+
+| استراتيجية          | الوصف                                                                                          |
+| ------------------- | ---------------------------------------------------------------------------------------------- |
+| **جولة روبن**       | يدور عبر النماذج بالتتابع                                                                      |
+| **الأولوية**        | يحاول دائمًا النموذج الأول؛ لا يعود إلا على الخطأ                                              |
+| **عشوائي**          | يختار نموذجًا عشوائيًا من المجموعة لكل طلب                                                     |
+| **المرجح**          | تعتمد المسارات بشكل متناسب على الأوزان المخصصة لكل نموذج                                       |
+| **الأقل استخدامًا** | التوجيهات إلى النموذج الذي يحتوي على أقل عدد من الطلبات الأخيرة (يستخدم مقاييس التحرير والسرد) |
+| **التكلفة الأمثل**  | الطرق إلى أرخص طراز متاح (يستخدم جدول التسعير)                                                 |
+
+يمكن ضبط إعدادات التحرير والسرد العامة في **لوحة المعلومات → الإعدادات → التوجيه → إعدادات التحرير والسرد الافتراضية**.
+
+---
+
+### لوحة المعلومات الصحية
+
+الوصول عبر **لوحة التحكم → الصحة**. نظرة عامة على صحة النظام في الوقت الحقيقي مع 6 بطاقات:
+
+| بطاقة                              | ما يظهر                                                        |
+| ---------------------------------- | -------------------------------------------------------------- |
+| **حالة النظام**                    | وقت التشغيل، الإصدار، استخدام الذاكرة، دليل البيانات           |
+| ** صحة المزود **                   | حالة قاطع الدائرة الكهربائية لكل مزود (مغلق/مفتوح/نصف مفتوح)   |
+| ** حدود المعدل **                  | فترات تهدئة حد المعدل النشط لكل حساب مع الوقت المتبقي          |
+| ** عمليات التأمين النشطة **        | تم حظر مقدمي الخدمة مؤقتًا بواسطة سياسة التأمين                |
+| ** ذاكرة التخزين المؤقت للتوقيع ** | إحصائيات إلغاء البيانات المكررة (المفاتيح النشطة، معدل الدخول) |
+| ** قياس زمن الوصول **              | p50/p95/p99 تجميع زمن الوصول لكل مزود                          |
+
+**نصيحة احترافية:** يتم تحديث صفحة الصحة تلقائيًا كل 10 ثوانٍ. استخدم بطاقة قاطع الدائرة لتحديد مقدمي الخدمة الذين يواجهون مشكلات.

docs/i18n/bg/API_REFERENCE.md

@@ -0,0 +1,441 @@
+# Справка за 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.
+
+---
+
+## Съдържание
+
+- [Chat Completions](#chat-completions)
+- [Embeddings](#embeddings)
+- [Image Generation](#image-generation)
+- [List Models](#list-models)
+- [Compatibility Endpoints](#compatibility-endpoints)
+- [Semantic Cache](#semantic-cache)
+- [Dashboard & Management](#dashboard--management)
+- [Request Processing](#request-processing)
+- [Authentication](#authentication)
+
+---
+
+## Завършвания на чат
+
+```bash
+POST /v1/chat/completions
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "cc/claude-opus-4-6",
+  "messages": [
+    {"role": "user", "content": "Write a function to..."}
+  ],
+  "stream": true
+}
+```
+
+### Персонализирани заглавки
+
+| Заглавка                 | Посока  | Описание                                   |
+| ------------------------ | ------- | ------------------------------------------ |
+| `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` ако проследяване на напредъка на |
+
+---
+
+## Вграждания
+
+```bash
+POST /v1/embeddings
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "nebius/Qwen/Qwen3-Embedding-8B",
+  "input": "The food was delicious"
+}
+```
+
+Налични доставчици: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+
+```bash
+# List all embedding models
+GET /v1/embeddings
+```
+
+---
+
+## Генериране на изображения
+
+```bash
+POST /v1/images/generations
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "openai/dall-e-3",
+  "prompt": "A beautiful sunset over mountains",
+  "size": "1024x1024"
+}
+```
+
+Налични доставчици: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+
+```bash
+# List all image models
+GET /v1/images/generations
+```
+
+---
+
+## Списък с модели
+
+```bash
+GET /v1/models
+Authorization: Bearer your-api-key
+
+→ Returns all chat, embedding, and image models + combos in OpenAI format
+```
+
+---
+
+## Крайни точки за съвместимост
+
+| Метод      | Път                         | Формат                     |
+| ---------- | --------------------------- | -------------------------- |
+| ПУБЛИКАЦИЯ | `/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`              | Олама                      |
+
+### Специализирани маршрути на доставчик
+
+```bash
+POST /v1/providers/{provider}/chat/completions
+POST /v1/providers/{provider}/embeddings
+POST /v1/providers/{provider}/images/generations
+```
+
+Префиксът на доставчика се добавя автоматично, ако липсва. Несъответстващите модели връщат `400`.
+
+---
+
+## Семантичен кеш
+
+```bash
+# Get cache stats
+GET /api/cache
+
+# Clear all caches
+DELETE /api/cache
+```
+
+Пример за отговор:
+
+```json
+{
+  "semanticCache": {
+    "memorySize": 42,
+    "memoryMaxSize": 500,
+    "dbSize": 128,
+    "hitRate": 0.65
+  },
+  "idempotency": {
+    "activeKeys": 3,
+    "windowMs": 5000
+  }
+}
+```
+
+---
+
+## Табло за управление и управление
+
+### Удостоверяване
+
+| Крайна точка                  | Метод         | Описание                           |
+| ----------------------------- | ------------- | ---------------------------------- |
+| `/api/auth/login`             | ПУБЛИКАЦИЯ    | Вход                               |
+| `/api/auth/logout`            | ПУБЛИКАЦИЯ    | Изход                              |
+| `/api/settings/require-login` | ВЗЕМИ/ПОСТАВИ | Изисква се превключване на влизане |
+
+### Управление на доставчика
+
+| Крайна точка                 | Метод                            | Описание                                 |
+| ---------------------------- | -------------------------------- | ---------------------------------------- |
+| `/api/providers`             | ВЗЕМЕТЕ/ПУБЛИКУВАЙТЕ             | Списък / създаване на доставчици         |
+| `/api/providers/[id]`        | ПОЛУЧАВАНЕ/ПОСТАВЯНЕ/ИЗТРИВАНЕ   | Управление на доставчик                  |
+| `/api/providers/[id]/test`   | ПУБЛИКАЦИЯ                       | Тествайте връзката с доставчик           |
+| `/api/providers/[id]/models` | ВЗЕМЕТЕ                          | Избройте модели на доставчици            |
+| `/api/providers/validate`    | ПУБЛИКАЦИЯ                       | Проверка на конфигурацията на доставчика |
+| `/api/provider-nodes*`       | Различни                         | Управление на възел на доставчик         |
+| `/api/provider-models`       | ПОЛУЧАВАНЕ/ПУБЛИКУВАНЕ/ИЗТРИВАНЕ | Персонализирани модели                   |
+
+### OAuth потоци
+
+| Крайна точка                     | Метод    | Описание                       |
+| -------------------------------- | -------- | ------------------------------ |
+| `/api/oauth/[provider]/[action]` | Различни | Специфичен за доставчика OAuth |
+
+### Маршрутизиране и конфигурация
+
+| Крайна точка          | Метод                | Описание                         |
+| --------------------- | -------------------- | -------------------------------- |
+| `/api/models/alias`   | ВЗЕМЕТЕ/ПУБЛИКУВАЙТЕ | Псевдоними на модели             |
+| `/api/models/catalog` | ВЗЕМЕТЕ              | Всички модели по доставчик + тип |
+| `/api/combos*`        | Различни             | Комбо управление                 |
+| `/api/keys*`          | Различни             | Управление на API ключове        |
+| `/api/pricing`        | ВЗЕМЕТЕ              | Моделна цена                     |
+
+### Използване и анализ
+
+| Крайна точка                | Метод   | Описание                |
+| --------------------------- | ------- | ----------------------- |
+| `/api/usage/history`        | ВЗЕМЕТЕ | История на използването |
+| `/api/usage/logs`           | ВЗЕМЕТЕ | Дневници за използване  |
+| `/api/usage/request-logs`   | ВЗЕМЕТЕ | Дневници на ниво заявка |
+| `/api/usage/[connectionId]` | ВЗЕМЕТЕ | Използване на връзка    |
+
+### Настройки
+
+| Крайна точка                    | Метод         | Описание                               |
+| ------------------------------- | ------------- | -------------------------------------- |
+| `/api/settings`                 | ВЗЕМИ/ПОСТАВИ | Общи настройки                         |
+| `/api/settings/proxy`           | ВЗЕМИ/ПОСТАВИ | Конфигурация на мрежов прокси          |
+| `/api/settings/proxy/test`      | ПУБЛИКАЦИЯ    | Тествайте прокси връзката              |
+| `/api/settings/ip-filter`       | ВЗЕМИ/ПОСТАВИ | Списък с разрешени/блокирани IP адреси |
+| `/api/settings/thinking-budget` | ВЗЕМИ/ПОСТАВИ | Бюджет на жетон за разсъждение         |
+| `/api/settings/system-prompt`   | ВЗЕМИ/ПОСТАВИ | Глобална системна подкана              |
+
+### Мониторинг
+
+| Крайна точка             | Метод                | Описание                      |
+| ------------------------ | -------------------- | ----------------------------- |
+| `/api/sessions`          | ВЗЕМЕТЕ              | Проследяване на активна сесия |
+| `/api/rate-limits`       | ВЗЕМЕТЕ              | Лимити за лихви по сметка     |
+| `/api/monitoring/health` | ВЗЕМЕТЕ              | Здравна проверка              |
+| `/api/cache`             | ПОЛУЧАВАНЕ/ИЗТРИВАНЕ | Кеш статистики / изчистване   |
+
+### Архивиране и експортиране/импортиране
+
+| Крайна точка                | Метод      | Описание                                         |
+| --------------------------- | ---------- | ------------------------------------------------ |
+| `/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 архив  |
+
+### Облачно синхронизиране
+
+| Крайна точка           | Метод      | Описание                           |
+| ---------------------- | ---------- | ---------------------------------- |
+| `/api/sync/cloud`      | Различни   | Операции за синхронизиране в облак |
+| `/api/sync/initialize` | ПУБЛИКАЦИЯ | Инициализиране на синхронизиране   |
+| `/api/cloud/*`         | Различни   | Облачно управление                 |
+
+### CLI инструменти
+
+| Крайна точка                       | Метод   | Описание               |
+| ---------------------------------- | ------- | ---------------------- |
+| `/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    |
+
+CLI отговорите включват: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
+
+### Устойчивост и ограничения на скоростта
+
+| Крайна точка            | Метод         | Описание                                      |
+| ----------------------- | ------------- | --------------------------------------------- |
+| `/api/resilience`       | ВЗЕМИ/ПОСТАВИ | Вземете/актуализирайте профили за устойчивост |
+| `/api/resilience/reset` | ПУБЛИКАЦИЯ    | Нулиране на прекъсвачи                        |
+| `/api/rate-limits`      | ВЗЕМЕТЕ       | Състояние на ограничение на лимита по сметка  |
+| `/api/rate-limit`       | ВЗЕМЕТЕ       | Конфигурация на глобален лимит на скоростта   |
+
+### Оценки
+
+| Крайна точка | Метод                | Описание                                |
+| ------------ | -------------------- | --------------------------------------- |
+| `/api/evals` | ВЗЕМЕТЕ/ПУБЛИКУВАЙТЕ | Избройте eval пакети / изпълнете оценка |
+
+### Политики
+
+| Крайна точка    | Метод                            | Описание                                  |
+| --------------- | -------------------------------- | ----------------------------------------- |
+| `/api/policies` | ПОЛУЧАВАНЕ/ПУБЛИКУВАНЕ/ИЗТРИВАНЕ | Управление на правилата за маршрутизиране |
+
+### Съответствие
+
+| Крайна точка                | Метод   | Описание                                           |
+| --------------------------- | ------- | -------------------------------------------------- |
+| `/api/compliance/audit-log` | ВЗЕМЕТЕ | Дневник за проверка на съответствието (последно N) |
+
+### v1beta (съвместим с Gemini)
+
+| Крайна точка               | Метод      | Описание                              |
+| -------------------------- | ---------- | ------------------------------------- |
+| `/v1beta/models`           | ВЗЕМЕТЕ    | Избройте модели във формат Gemini     |
+| `/v1beta/models/{...path}` | ПУБЛИКАЦИЯ | Gemini `generateContent` крайна точка |
+
+Тези крайни точки отразяват API формата на Gemini за клиенти, които очакват естествена съвместимост с Gemini SDK.
+
+### Вътрешен/системен API
+
+| Крайна точка    | Метод      | Описание                                                                       |
+| --------------- | ---------- | ------------------------------------------------------------------------------ |
+| `/api/init`     | ВЗЕМЕТЕ    | Проверка за инициализация на приложението (използва се при първото стартиране) |
+| `/api/tags`     | ВЗЕМЕТЕ    | Тагове за модели, съвместими с Ollama (за клиенти на Ollama)                   |
+| `/api/restart`  | ПУБЛИКАЦИЯ | Задейства грациозно рестартиране на сървъра                                    |
+| `/api/shutdown` | ПУБЛИКАЦИЯ | Задействайте грациозно изключване на сървъра                                   |
+
+> **Забележка:** Тези крайни точки се използват вътрешно от системата или за съвместимост с клиента Ollama. Те обикновено не се извикват от крайните потребители.
+
+---
+
+## Аудио транскрипция
+
+```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+```
+
+Транскрибирайте аудио файлове с помощта на Deepgram или AssemblyAI.
+
+**Заявка:**
+
+```bash
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+  -H "Authorization: Bearer your-api-key" \
+  -F "file=@recording.mp3" \
+  -F "model=deepgram/nova-3"
+```
+
+**Отговор:**
+
+```json
+{
+  "text": "Hello, this is the transcribed audio content.",
+  "task": "transcribe",
+  "language": "en",
+  "duration": 12.5
+}
+```
+
+**Поддържани доставчици:** `deepgram/nova-3`, `assemblyai/best`.
+
+**Поддържани формати:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+
+---
+
+## Съвместимост с Ollama
+
+За клиенти, които използват API формат на Ollama:
+
+```bash
+# Chat endpoint (Ollama format)
+POST /v1/api/chat
+
+# Model listing (Ollama format)
+GET /api/tags
+```
+
+Заявките се превеждат автоматично между Ollama и вътрешни формати.
+
+---
+
+## Телеметрия
+
+```bash
+# Get latency telemetry summary (p50/p95/p99 per provider)
+GET /api/telemetry/summary
+```
+
+**Отговор:**
+
+```json
+{
+  "providers": {
+    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
+    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
+  }
+}
+```
+
+---
+
+## Бюджет
+
+```bash
+# Get budget status for all API keys
+GET /api/usage/budget
+
+# Set or update a budget
+POST /api/usage/budget
+Content-Type: application/json
+
+{
+  "keyId": "key-123",
+  "limit": 50.00,
+  "period": "monthly"
+}
+```
+
+---
+
+## Наличност на модела
+
+```bash
+# Get real-time model availability across all providers
+GET /api/models/availability
+
+# Check availability for a specific model
+POST /api/models/availability
+Content-Type: application/json
+
+{
+  "model": "claude-sonnet-4-5-20250929"
+}
+```
+
+---
+
+## Обработка на заявка
+
+1. Клиентът изпраща заявка до `/v1/*`
+2. Обработчикът на маршрута извиква `handleChat`, `handleEmbedding`, `handleAudioTranscription` или `handleImageGeneration`
+3. Моделът е разрешен (директен доставчик/модел или псевдоним/комбо)
+4. Идентификационни данни, избрани от локална база данни с филтриране на наличността на акаунта
+5. За чат: `handleChatCore` — откриване на формат, превод, проверка на кеша, проверка на идемпотентност
+6. Изпълнителят на доставчика изпраща заявка нагоре по веригата
+7. Отговор, преведен обратно във формат на клиента (чат) или върнат такъв, какъвто е (вграждания/изображения/аудио)
+8. Записано използване/регистриране
+9. Резервният вариант се прилага при грешки според комбо правилата
+
+Пълна справка за архитектурата: [link](ARCHITECTURE.md)
+
+---
+
+## Удостоверяване
+
+- Маршрутите на таблото за управление (`/dashboard/*`) използват бисквитка `auth_token`
+- Входът използва запазен хеш на паролата; връщане към `INITIAL_PASSWORD`
+- `requireLogin` превключваем чрез `/api/settings/require-login`
+- `/v1/*` маршрутите по избор изискват Bearer API ключ, когато `REQUIRE_API_KEY=true`

docs/i18n/bg/ARCHITECTURE.md

@@ -0,0 +1,781 @@
+# Архитектура OmniRoute
+
+🌐 **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 е локален AI маршрутизиращ шлюз и табло за управление, изградено на Next.js.
+Той осигурява една крайна точка, съвместима с OpenAI (`/v1/*`) и маршрутизира трафика през множество доставчици нагоре по веригата с превод, резервен вариант, опресняване на токени и проследяване на използването.
+
+Основни възможности:
+
+- 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/`)
+
+Основен модел на изпълнение:
+
+- Маршрутите на приложението Next.js под `src/app/api/*` прилагат както API на таблото за управление, така и API за съвместимост
+- Споделено SSE/маршрутизиращо ядро в `src/sse/*` + `open-sse/*` обработва изпълнението на доставчика, превода, стрийминг, резервен вариант и използване
+
+## Обхват и граници
+
+### В обхват
+
+- Време за изпълнение на локален шлюз
+- API за управление на таблото
+- Удостоверяване на доставчика и опресняване на токена
+- Заявка за превод и SSE стрийминг
+- Локално състояние + постоянство на използване
+- Допълнителна синхронизация в облака
+
+### Извън обхвата
+
+- Внедряване на облачна услуга зад `NEXT_PUBLIC_CLOUD_URL`
+- SLA/контролна равнина на доставчика извън локалния процес
+- Самите външни CLI двоични файлове (Claude CLI, Codex CLI и т.н.)
+
+## Системен контекст на високо ниво
+
+```mermaid
+flowchart LR
+    subgraph Clients[Developer Clients]
+        C1[Claude Code]
+        C2[Codex CLI]
+        C3[OpenClaw / Droid / Cline / Continue / Roo]
+        C4[Custom OpenAI-compatible clients]
+        BROWSER[Browser Dashboard]
+    end
+
+    subgraph Router[OmniRoute Local Process]
+        API[V1 Compatibility API\n/v1/*]
+        DASH[Dashboard + Management API\n/api/*]
+        CORE[SSE + Translation Core\nopen-sse + src/sse]
+        DB[(db.json)]
+        UDB[(usage.json + log.txt)]
+    end
+
+    subgraph Upstreams[Upstream Providers]
+        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity]
+        P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
+        P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
+    end
+
+    subgraph Cloud[Optional Cloud Sync]
+        CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL]
+    end
+
+    C1 --> API
+    C2 --> API
+    C3 --> API
+    C4 --> API
+    BROWSER --> DASH
+
+    API --> CORE
+    DASH --> DB
+    CORE --> DB
+    CORE --> UDB
+
+    CORE --> P1
+    CORE --> P2
+    CORE --> P3
+
+    DASH --> CLOUD
+```
+
+## Основни компоненти по време на изпълнение
+
+## 1) API и слой за маршрутизиране (Маршрути на приложението Next.js)
+
+Основни директории:
+
+- `src/app/api/v1/*` и `src/app/api/v1beta/*` за API за съвместимост
+- `src/app/api/*` за API за управление/конфигуриране
+- Следващото пренаписване в `next.config.mjs` преобразува `/v1/*` в `/api/v1/*`
+
+Важни пътища за съвместимост:
+
+- `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/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/v1beta/models/route.ts`
+- `src/app/api/v1beta/models/[...path]/route.ts`
+
+Домейни за управление:
+
+- Удостоверяване/настройки: `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)
+- 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)
+
+## 2) SSE + ядро за превод
+
+Основни модули на потока:
+
+- Запис: `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`
+
+Услуги (бизнес логика):
+
+- Избор/точкуване на акаунт: `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`
+
+Модули на ниво домейн:
+
+- Наличност на модела: `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 за резервни вериги, бюджети, история на разходите, състояние на блокиране, прекъсвачи
+
+Модули за доставчик на OAuth (12 отделни файла под `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` — повторно експортиране от отделни модули
+
+## 3) Слой за устойчивост
+
+Основно състояние DB:
+
+- `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**
+
+DB за използване:
+
+- `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`
+
+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 при студен старт
+
+## 4) Удостоверяване + повърхности за сигурност
+
+- Удостоверяване на бисквитките на таблото за управление: `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` (конфигурируем за всеки доставчик или глобално)
+
+## 5) Синхронизиране в облак
+
+- Инициализация на планировчика: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
+- Периодична задача: `src/shared/services/cloudSyncScheduler.ts`
+- Контролен маршрут: `src/app/api/sync/cloud/route.ts`
+
+## Жизнен цикъл на заявка (`/v1/chat/completions`)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as CLI/SDK Client
+    participant Route as /api/v1/chat/completions
+    participant Chat as src/sse/handlers/chat
+    participant Core as open-sse/handlers/chatCore
+    participant Model as Model Resolver
+    participant Auth as Credential Selector
+    participant Exec as Provider Executor
+    participant Prov as Upstream Provider
+    participant Stream as Stream Translator
+    participant Usage as usageDb
+
+    Client->>Route: POST /v1/chat/completions
+    Route->>Chat: handleChat(request)
+    Chat->>Model: parse/resolve model or combo
+
+    alt Combo model
+        Chat->>Chat: iterate combo models (handleComboChat)
+    end
+
+    Chat->>Auth: getProviderCredentials(provider)
+    Auth-->>Chat: active account + tokens/api key
+
+    Chat->>Core: handleChatCore(body, modelInfo, credentials)
+    Core->>Core: detect source format
+    Core->>Core: translate request to target format
+    Core->>Exec: execute(provider, transformedBody)
+    Exec->>Prov: upstream API call
+    Prov-->>Exec: SSE/JSON response
+    Exec-->>Core: response + metadata
+
+    alt 401/403
+        Core->>Exec: refreshCredentials()
+        Exec-->>Core: updated tokens
+        Core->>Exec: retry request
+    end
+
+    Core->>Stream: translate/normalize stream to client format
+    Stream-->>Client: SSE chunks / JSON response
+
+    Stream->>Usage: extract usage + persist history/log
+```
+
+## Комбо + Резервен поток на акаунт
+
+```mermaid
+flowchart TD
+    A[Incoming model string] --> B{Is combo name?}
+    B -- Yes --> C[Load combo models sequence]
+    B -- No --> D[Single model path]
+
+    C --> E[Try model N]
+    E --> F[Resolve provider/model]
+    D --> F
+
+    F --> G[Select account credentials]
+    G --> H{Credentials available?}
+    H -- No --> I[Return provider unavailable]
+    H -- Yes --> J[Execute request]
+
+    J --> K{Success?}
+    K -- Yes --> L[Return response]
+    K -- No --> M{Fallback-eligible error?}
+
+    M -- No --> N[Return error]
+    M -- Yes --> O[Mark account unavailable cooldown]
+    O --> P{Another account for provider?}
+    P -- Yes --> G
+    P -- No --> Q{In combo with next model?}
+    Q -- Yes --> E
+    Q -- No --> R[Return all unavailable]
+```
+
+Резервните решения се управляват от `open-sse/services/accountFallback.ts` с помощта на кодове за състояние и евристика за съобщения за грешка.
+
+## Жизнен цикъл на внедряване на OAuth и опресняване на токени
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Dashboard UI
+    participant OAuth as /api/oauth/[provider]/[action]
+    participant ProvAuth as Provider Auth Server
+    participant DB as localDb
+    participant Test as /api/providers/[id]/test
+    participant Exec as Provider Executor
+
+    UI->>OAuth: GET authorize or device-code
+    OAuth->>ProvAuth: create auth/device flow
+    ProvAuth-->>OAuth: auth URL or device code payload
+    OAuth-->>UI: flow data
+
+    UI->>OAuth: POST exchange or poll
+    OAuth->>ProvAuth: token exchange/poll
+    ProvAuth-->>OAuth: access/refresh tokens
+    OAuth->>DB: createProviderConnection(oauth data)
+    OAuth-->>UI: success + connection id
+
+    UI->>Test: POST /api/providers/[id]/test
+    Test->>Exec: validate credentials / optional refresh
+    Exec-->>Test: valid or refreshed token info
+    Test->>DB: update status/tokens/errors
+    Test-->>UI: validation result
+```
+
+Опресняването по време на трафик на живо се изпълнява вътре в `open-sse/handlers/chatCore.ts` чрез изпълнител `refreshCredentials()`.
+
+## Жизнен цикъл на Cloud Sync (Активиране / Синхронизиране / Деактивиране)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Endpoint Page UI
+    participant Sync as /api/sync/cloud
+    participant DB as localDb
+    participant Cloud as External Cloud Sync
+    participant Claude as ~/.claude/settings.json
+
+    UI->>Sync: POST action=enable
+    Sync->>DB: set cloudEnabled=true
+    Sync->>DB: ensure API key exists
+    Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys)
+    Cloud-->>Sync: sync result
+    Sync->>Cloud: GET /{machineId}/v1/verify
+    Sync-->>UI: enabled + verification status
+
+    UI->>Sync: POST action=sync
+    Sync->>Cloud: POST /sync/{machineId}
+    Cloud-->>Sync: remote data
+    Sync->>DB: update newer local tokens/status
+    Sync-->>UI: synced
+
+    UI->>Sync: POST action=disable
+    Sync->>DB: set cloudEnabled=false
+    Sync->>Cloud: DELETE /sync/{machineId}
+    Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed)
+    Sync-->>UI: disabled
+```
+
+Периодичното синхронизиране се задейства от `CloudSyncScheduler`, когато облакът е активиран.
+
+## Модел на данни и карта за съхранение
+
+```mermaid
+erDiagram
+    SETTINGS ||--o{ PROVIDER_CONNECTION : controls
+    PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider
+    PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage
+
+    SETTINGS {
+      boolean cloudEnabled
+      number stickyRoundRobinLimit
+      boolean requireLogin
+      string password_hash
+      string fallbackStrategy
+      json rateLimitDefaults
+      json providerProfiles
+    }
+
+    PROVIDER_CONNECTION {
+      string id
+      string provider
+      string authType
+      string name
+      number priority
+      boolean isActive
+      string apiKey
+      string accessToken
+      string refreshToken
+      string expiresAt
+      string testStatus
+      string lastError
+      string rateLimitedUntil
+      json providerSpecificData
+    }
+
+    PROVIDER_NODE {
+      string id
+      string type
+      string name
+      string prefix
+      string apiType
+      string baseUrl
+    }
+
+    MODEL_ALIAS {
+      string alias
+      string targetModel
+    }
+
+    COMBO {
+      string id
+      string name
+      string[] models
+    }
+
+    API_KEY {
+      string id
+      string name
+      string key
+      string machineId
+    }
+
+    USAGE_ENTRY {
+      string provider
+      string model
+      number prompt_tokens
+      number completion_tokens
+      string connectionId
+      string timestamp
+    }
+
+    CUSTOM_MODEL {
+      string id
+      string name
+      string providerId
+    }
+
+    PROXY_CONFIG {
+      string global
+      json providers
+    }
+
+    IP_FILTER {
+      string mode
+      string[] allowlist
+      string[] blocklist
+    }
+
+    THINKING_BUDGET {
+      string mode
+      number customBudget
+      string effortLevel
+    }
+
+    SYSTEM_PROMPT {
+      boolean enabled
+      string prompt
+      string position
+    }
+```
+
+Файлове за физическо съхранение:
+
+- основно състояние: `${DATA_DIR}/db.json` (или `$XDG_CONFIG_HOME/omniroute/db.json`, когато е зададено, в противен случай `~/.omniroute/db.json`)
+- статистика за използване: `${DATA_DIR}/usage.json`
+- Редове на заявката: `${DATA_DIR}/log.txt`
+- незадължителни сесии за преводач/заявка за отстраняване на грешки: `<repo>/logs/...`
+
+## Топология на разполагане
+
+```mermaid
+flowchart LR
+    subgraph LocalHost[Developer Host]
+        CLI[CLI Tools]
+        Browser[Dashboard Browser]
+    end
+
+    subgraph ContainerOrProcess[OmniRoute Runtime]
+        Next[Next.js Server\nPORT=20128]
+        Core[SSE Core + Executors]
+        MainDB[(db.json)]
+        UsageDB[(usage.json/log.txt)]
+    end
+
+    subgraph External[External Services]
+        Providers[AI Providers]
+        SyncCloud[Cloud Sync Service]
+    end
+
+    CLI --> Next
+    Browser --> Next
+    Next --> Core
+    Next --> MainDB
+    Core --> MainDB
+    Core --> UsageDB
+    Core --> Providers
+    Next --> SyncCloud
+```
+
+## Съпоставяне на модул (критично за вземане на решения)
+
+### Модули за маршрут и API
+
+- `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/sse/handlers/chat.ts`: анализ на заявка, комбо обработка, цикъл за избор на акаунт
+- `open-sse/handlers/chatCore.ts`: превод, изпращане на изпълнителя, обработка на повторен опит/опресняване, настройка на потока
+- `open-sse/executors/*`: специфично за доставчика поведение на мрежата и формата
+
+### Регистър за преводи и конвертори на формати
+
+- `open-sse/translator/index.ts`: регистър на преводача и оркестрация
+- Заявка за преводачи: `open-sse/translator/request/*`
+- Преводачи на отговори: `open-sse/translator/response/*`
+- Константи на формата: `open-sse/translator/formats.ts`
+
+### Постоянство
+
+- `src/lib/localDb.ts`: постоянна конфигурация/състояние
+- `src/lib/usageDb.ts`: хронология на използването и регистрационни файлове на текущи заявки
+
+## Покритие на изпълнител на доставчик (стратегически модел)
+
+Всеки доставчик има специализиран изпълнител, разширяващ `BaseExecutor` (в `open-sse/executors/base.ts`), който осигурява изграждане на URL адрес, изграждане на заглавка, повторен опит с експоненциално забавяне, кукички за опресняване на идентификационни данни и метода за оркестрация `execute()`.
+
+| Изпълнител            | Доставчик(и)                                                                                                                                                 | Специална обработка                                                                 |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| `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 токен                                          |
+
+Всички други доставчици (включително персонализирани съвместими възли) използват `DefaultExecutor`.
+
+## Матрица за съвместимост на доставчика
+
+| Доставчик         | Формат          | Удостоверяване                 | Поток            | Непоточно | Опресняване на токена | 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 ключ                       | ✅               | ✅        | ❌                    | ❌                           |
+
+## Обхват на превод на формат
+
+Откритите изходни формати включват:
+
+- `openai`
+- `openai-responses`
+- `claude`
+- `gemini`
+
+Целевите формати включват:
+
+- OpenAI чат/Отговори
+- Клод
+- Gemini/Gemini-CLI/Антигравитационен плик
+- Киро
+- Курсор
+
+Преводите използват **OpenAI като хъб формат** — всички реализации преминават през OpenAI като междинен:
+
+```
+Source Format → OpenAI (hub) → Target Format
+```
+
+Преводите се избират динамично въз основа на формата на изходния полезен товар и целевия формат на доставчика.
+
+Допълнителни слоеве за обработка в тръбопровода за превод:
+
+- **Дефектификация на отговора** — Премахва нестандартните полета от отговорите във формат OpenAI (както стрийминг, така и без стрийминг), за да се гарантира стриктно съответствие с SDK
+- **Нормализиране на ролята** — Преобразува `developer` → `system` за цели, които не са OpenAI; обединява `system` → `user` за модели, които отхвърлят системната роля (GLM, ERNIE)
+- **Извличане на мислен етикет** — Анализира `<think>...</think>` блокове от съдържание в поле `reasoning_content`
+- **Структуриран изход** — Преобразува OpenAI `response_format.json_schema` в `responseMimeType` + `responseSchema` на Gemini
+
+## Поддържани API крайни точки
+
+| Крайна точка                                       | Формат                    | Манипулатор                                                        |
+| -------------------------------------------------- | ------------------------- | ------------------------------------------------------------------ |
+| `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`             | Персонализирани модели    | Персонализирано управление на модели за всеки доставчик            |
+
+## Обходен манипулатор
+
+Обходният манипулатор (`open-sse/utils/bypassHandler.ts`) прихваща известни заявки за „изхвърляне“ от Claude CLI — пингове за загряване, извличане на заглавия и преброяване на токени — и връща **фалшив отговор**, без да консумира токени на доставчика нагоре по веригата. Това се задейства само когато `User-Agent` съдържа `claude-cli`.
+
+## Тръбопровод за регистратор на заявки
+
+Регистраторът на заявки (`open-sse/utils/requestLogger.ts`) осигурява 7-етапен конвейер за регистриране на грешки, деактивиран по подразбиране, активиран чрез `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>/` за всяка сесия на заявка.
+
+## Режими на отказ и устойчивост
+
+## 1) Наличност на акаунт/доставчик
+
+- изчакване на акаунта на доставчика при преходни/скоростни/удостоверителни грешки
+- резервен акаунт преди неуспешна заявка
+- резервен комбиниран модел, когато пътят на текущия модел/доставчик е изчерпан
+
+## 2) Изтичане на токена
+
+- предварителна проверка и опресняване с повторен опит за опресняващи доставчици
+- 401/403 повторен опит след опит за опресняване в основния път
+
+## 3) Безопасност на потока
+
+- контролер на потоци, който се изключва
+- поток за превод с промиване в края на потока и обработка на `[DONE]`
+- резервна оценка на използването, когато липсват метаданни за използване на доставчика
+
+## 4) Влошаване на облачната синхронизация
+
+- появяват се грешки при синхронизиране, но локалното изпълнение продължава
+- планировчикът има логика с възможност за повторен опит, но периодичното изпълнение в момента извиква синхронизиране с един опит по подразбиране
+
+## 5) Цялост на данните
+
+- Миграция/поправка на DB форма за липсващи ключове
+- повредени предпазни мерки за нулиране на JSON за localDb и usageDb
+
+## Наблюдаемост и оперативни сигнали
+
+Източници на видимост по време на изпълнение:
+
+- регистрационни файлове на конзолата от `src/sse/utils/logger.ts`
+- агрегати за използване на заявка в `usage.json`
+- влизане на състоянието на текстова заявка `log.txt`
+- незадължителни дълбоки регистрационни файлове за заявка/превод под `logs/`, когато `ENABLE_REQUEST_LOGS=true`
+- крайни точки за използване на таблото за управление (`/api/usage/*`) за потребление на UI
+
+## Граници, чувствителни към сигурността
+
+- JWT тайна (`JWT_SECRET`) защитава проверката/подписването на бисквитките на таблото за управление
+- Първоначалната резервна парола (`INITIAL_PASSWORD`, по подразбиране `123456`) трябва да бъде заменена при реални внедрявания
+- API ключ HMAC secret (`API_KEY_SECRET`) защитава генерирания локален формат на API ключ
+- Тайните на доставчика (API ключове/токени) се съхраняват в локалната база данни и трябва да бъдат защитени на ниво файлова система
+- Крайните точки за синхронизиране в облак разчитат на удостоверяване на API ключ + семантика на идентификатор на машина
+
+## Околна среда и матрица за изпълнение
+
+Променливите на средата, използвани активно от кода:
+
+- Приложение/удостоверяване: `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`
+
+## Известни архитектурни бележки
+
+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 (мислещ бюджет, системна подкана, кеш за подкана), Разширени (прокси).
+
+## Контролен списък за оперативна проверка
+
+- Създаване от източник: `npm run build`
+- Изграждане на Docker изображение: `docker build -t omniroute .`
+- Стартирайте услугата и проверете:
+- `GET /api/settings`
+- `GET /api/v1/models`
+- CLI целеви базов URL трябва да бъде `http://<host>:20128/v1`, когато `PORT=20128`

docs/i18n/bg/CODEBASE_DOCUMENTATION.md

@@ -0,0 +1,589 @@
+# 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** прокси рутер с изкуствен интелект с множество доставчици.
+
+---
+
+## 1. Какво е omniroute?
+
+omniroute е **прокси рутер**, който се намира между AI клиенти (Claude CLI, Codex, Cursor IDE и др.) и AI доставчици (Anthropic, Google, OpenAI, AWS, GitHub и др.). Решава един голям проблем:
+
+> **Различните AI клиенти говорят различни „езици“ (API формати) и различните доставчици на AI също очакват различни „езици“.** omniroute превежда автоматично между тях.
+
+Мислете за това като за универсален преводач в Обединените нации - всеки делегат може да говори всеки език и преводачът го преобразува за всеки друг делегат.
+
+---
+
+## 2. Преглед на архитектурата
+
+```mermaid
+graph LR
+    subgraph Clients
+        A[Claude CLI]
+        B[Codex]
+        C[Cursor IDE]
+        D[OpenAI-compatible]
+    end
+
+    subgraph omniroute
+        E[Handler Layer]
+        F[Translator Layer]
+        G[Executor Layer]
+        H[Services Layer]
+    end
+
+    subgraph Providers
+        I[Anthropic Claude]
+        J[Google Gemini]
+        K[OpenAI / Codex]
+        L[GitHub Copilot]
+        M[AWS Kiro]
+        N[Antigravity]
+        O[Cursor API]
+    end
+
+    A --> E
+    B --> E
+    C --> E
+    D --> E
+    E --> F
+    F --> G
+    G --> I
+    G --> J
+    G --> K
+    G --> L
+    G --> M
+    G --> N
+    G --> O
+    H -.-> E
+    H -.-> G
+```
+
+### Основен принцип: Превод на централно ниво
+
+Всички преводи на формати преминават през **OpenAI формат като център**:
+
+```
+Client Format → [OpenAI Hub] → Provider Format    (request)
+Provider Format → [OpenAI Hub] → Client Format    (response)
+```
+
+Това означава, че имате нужда само от **N преводачи** (по един на формат) вместо от **N²** (всяка двойка).
+
+---
+
+## 3. Структура на проекта
+
+```
+omniroute/
+├── open-sse/                  ← Core proxy library (portable, framework-agnostic)
+│   ├── index.js               ← Main entry point, exports everything
+│   ├── config/                ← Configuration & constants
+│   ├── executors/             ← Provider-specific request execution
+│   ├── handlers/              ← Request handling orchestration
+│   ├── services/              ← Business logic (auth, models, fallback, usage)
+│   ├── translator/            ← Format translation engine
+│   │   ├── request/           ← Request translators (8 files)
+│   │   ├── response/          ← Response translators (7 files)
+│   │   └── helpers/           ← Shared translation utilities (6 files)
+│   └── utils/                 ← Utility functions
+├── src/                       ← Application layer (Express/Worker runtime)
+│   ├── app/                   ← Web UI, API routes, middleware
+│   ├── lib/                   ← Database, auth, and shared library code
+│   ├── mitm/                  ← Man-in-the-middle proxy utilities
+│   ├── models/                ← Database models
+│   ├── shared/                ← Shared utilities (wrappers around open-sse)
+│   ├── sse/                   ← SSE endpoint handlers
+│   └── store/                 ← State management
+├── data/                      ← Runtime data (credentials, logs)
+│   └── provider-credentials.json   (external credentials override, gitignored)
+└── tester/                    ← Test utilities
+```
+
+---
+
+## 4. Разбивка модул по модул
+
+### 4.1 Конфигурация (`open-sse/config/`)
+
+**Единственият източник на истина** за всички конфигурации на доставчика.
+
+| Файл                          | Цел                                                                                                                                                                                                                                                            |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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 (име, размер, семейство, квантуване).                                                                                                                                                                              |
+
+#### Поток на зареждане на идентификационни данни
+
+```mermaid
+flowchart TD
+    A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"]
+    B --> C{"data/provider-credentials.json\nexists?"}
+    C -->|Yes| D["credentialLoader reads JSON"]
+    C -->|No| E["Use hardcoded defaults"]
+    D --> F{"For each provider in JSON"}
+    F --> G{"Provider exists\nin PROVIDERS?"}
+    G -->|No| H["Log warning, skip"]
+    G -->|Yes| I{"Value is object?"}
+    I -->|No| J["Log warning, skip"]
+    I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"]
+    K --> F
+    H --> F
+    J --> F
+    F -->|Done| L["PROVIDERS ready with\nmerged credentials"]
+    E --> L
+```
+
+---
+
+### 4.2 Изпълнители (`open-sse/executors/`)
+
+Изпълнителите капсулират **специфична за доставчика логика**, използвайки **стратегически модел**. Всеки изпълнител замества основните методи, ако е необходимо.
+
+```mermaid
+classDiagram
+    class BaseExecutor {
+        +buildUrl(model, stream, options)
+        +buildHeaders(credentials, stream, body)
+        +transformRequest(body, model, stream, credentials)
+        +execute(url, options)
+        +shouldRetry(status, error)
+        +refreshCredentials(credentials, log)
+    }
+
+    class DefaultExecutor {
+        +refreshCredentials()
+    }
+
+    class AntigravityExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +shouldRetry()
+        +refreshCredentials()
+    }
+
+    class CursorExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseResponse()
+        +generateChecksum()
+    }
+
+    class KiroExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseEventStream()
+        +refreshCredentials()
+    }
+
+    BaseExecutor <|-- DefaultExecutor
+    BaseExecutor <|-- AntigravityExecutor
+    BaseExecutor <|-- CursorExecutor
+    BaseExecutor <|-- KiroExecutor
+    BaseExecutor <|-- CodexExecutor
+    BaseExecutor <|-- GeminiCLIExecutor
+    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`       | —                                          | Фабрика: картографира името на доставчика → клас изпълнител, с резервен вариант по подразбиране                                                                                       |
+
+---
+
+### 4.3 Манипулатори (`open-sse/handlers/`)
+
+**Слоят за оркестрация** — координира превода, изпълнението, поточното предаване и обработката на грешки.
+
+| Файл                  | Цел                                                                                                                                                                                                                                                     |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chatCore.ts`         | **Централен оркестратор** (~600 реда). Обработва пълния жизнен цикъл на заявката: откриване на формат → превод → изпращане на изпълнител → стрийминг/не-стрийминг отговор → опресняване на токена → обработка на грешки → регистриране на използването. |
+| `responsesHandler.ts` | Адаптер за API за отговори на OpenAI: преобразува формата на отговорите → Завършвания на чат → изпраща до `chatCore` → конвертира SSE обратно във формат на отговорите.                                                                                 |
+| `embeddings.ts`       | Манипулатор за генериране на вграждане: разрешава модел на вграждане → доставчик, изпраща до API на доставчика, връща съвместим с OpenAI отговор за вграждане. Поддържа 6+ доставчици.                                                                  |
+| `imageGeneration.ts`  | Манипулатор за генериране на изображения: разрешава модел на изображение → доставчик, поддържа режими, съвместими с OpenAI, Gemini-image (Антигравитация) и резервни (Nebius). Връща base64 или URL изображения.                                        |
+
+#### Жизнен цикъл на заявка (chatCore.ts)
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant chatCore
+    participant Translator
+    participant Executor
+    participant Provider
+
+    Client->>chatCore: Request (any format)
+    chatCore->>chatCore: Detect source format
+    chatCore->>chatCore: Check bypass patterns
+    chatCore->>chatCore: Resolve model & provider
+    chatCore->>Translator: Translate request (source → OpenAI → target)
+    chatCore->>Executor: Get executor for provider
+    Executor->>Executor: Build URL, headers, transform request
+    Executor->>Executor: Refresh credentials if needed
+    Executor->>Provider: HTTP fetch (streaming or non-streaming)
+
+    alt Streaming
+        Provider-->>chatCore: SSE stream
+        chatCore->>chatCore: Pipe through SSE transform stream
+        Note over chatCore: Transform stream translates<br/>each chunk: target → OpenAI → source
+        chatCore-->>Client: Translated SSE stream
+    else Non-streaming
+        Provider-->>chatCore: JSON response
+        chatCore->>Translator: Translate response
+        chatCore-->>Client: Translated JSON
+    end
+
+    alt Error (401, 429, 500...)
+        chatCore->>Executor: Retry with credential refresh
+        chatCore->>chatCore: Account fallback logic
+    end
+```
+
+---
+
+### 4.4 Услуги (`open-sse/services/`)
+
+Бизнес логика, която поддържа манипулаторите и изпълнителите.
+
+| Файл                 | Цел                                                                                                                                                                                                                                                                                                                                                                                                 |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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-*`) до конкретни двойки доставчик/модел въз основа на наличност и приоритет.                                                                                                                                                                                                                 |
+
+#### Дедупликация на опресняване на токени
+
+```mermaid
+sequenceDiagram
+    participant R1 as Request 1
+    participant R2 as Request 2
+    participant Cache as refreshPromiseCache
+    participant OAuth as OAuth Provider
+
+    R1->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: No in-flight promise
+    Cache->>OAuth: Start refresh
+    R2->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: Found in-flight promise
+    Cache-->>R2: Return existing promise
+    OAuth-->>Cache: New access token
+    Cache-->>R1: New access token
+    Cache-->>R2: Same access token (shared)
+    Cache->>Cache: Delete cache entry
+```
+
+#### Резервна държавна машина на акаунта
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active
+    Active --> Error: Request fails (401/429/500)
+    Error --> Cooldown: Apply backoff
+    Cooldown --> Active: Cooldown expires
+    Active --> Active: Request succeeds (reset backoff)
+
+    state Error {
+        [*] --> ClassifyError
+        ClassifyError --> ShouldFallback: Rate limit / Auth / Transient
+        ClassifyError --> NoFallback: 400 Bad Request
+    }
+
+    state Cooldown {
+        [*] --> ExponentialBackoff
+        ExponentialBackoff: Level 0 = 1s
+        ExponentialBackoff: Level 1 = 2s
+        ExponentialBackoff: Level 2 = 4s
+        ExponentialBackoff: Max = 2min
+    }
+```
+
+#### Комбиниран модел верига
+
+```mermaid
+flowchart LR
+    A["Request with\ncombo model"] --> B["Model A"]
+    B -->|"2xx Success"| C["Return response"]
+    B -->|"429/401/500"| D{"Fallback\neligible?"}
+    D -->|Yes| E["Model B"]
+    D -->|No| F["Return error"]
+    E -->|"2xx Success"| C
+    E -->|"429/401/500"| G{"Fallback\neligible?"}
+    G -->|Yes| H["Model C"]
+    G -->|No| F
+    H -->|"2xx Success"| C
+    H -->|"Fail"| I["All failed →\nReturn last status"]
+```
+
+---
+
+### 4.5 Преводач (`open-sse/translator/`)
+
+**Машината за превод на формати**, използваща саморегистрираща се плъгин система.
+
+#### Архитектура
+
+```mermaid
+graph TD
+    subgraph "Request Translation"
+        A["Claude → OpenAI"]
+        B["Gemini → OpenAI"]
+        C["Antigravity → OpenAI"]
+        D["OpenAI Responses → OpenAI"]
+        E["OpenAI → Claude"]
+        F["OpenAI → Gemini"]
+        G["OpenAI → Kiro"]
+        H["OpenAI → Cursor"]
+    end
+
+    subgraph "Response Translation"
+        I["Claude → OpenAI"]
+        J["Gemini → OpenAI"]
+        K["Kiro → OpenAI"]
+        L["Cursor → OpenAI"]
+        M["OpenAI → Claude"]
+        N["OpenAI → Antigravity"]
+        O["OpenAI → Responses"]
+    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`.                                                                                                                                                                                                 |
+
+#### Ключов дизайн: Саморегистриращи се добавки
+
+```javascript
+// Each translator file calls register() on import:
+import { register } from "../index.js";
+register("claude", "openai", translateClaudeToOpenAI);
+
+// The index.js imports all translator files, triggering registration:
+import "./request/claude-to-openai.js"; // ← self-registers
+```
+
+---
+
+### 4.6 Помощни средства (`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.                                                                                    |
+
+#### SSE Streaming Pipeline
+
+```mermaid
+flowchart TD
+    A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"]
+    B --> C["Buffer lines\n(split on newline)"]
+    C --> D["parseSSELine()\n(trim whitespace, parse JSON)"]
+    D --> E{"Mode?"}
+    E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"]
+    E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"]
+    F --> H["hasValuableContent()\nfilter empty chunks"]
+    G --> H
+    H -->|"Has content"| I["extractUsage()\ntrack token counts"]
+    H -->|"Empty"| J["Skip chunk"]
+    I --> K["formatSSE()\nserialize + clean perf_metrics"]
+    K --> L["TextEncoder\n(per-stream instance)"]
+    L --> M["Enqueue to\nclient stream"]
+
+    style A fill:#f9f,stroke:#333
+    style M fill:#9f9,stroke:#333
+```
+
+#### Структура на сесията на регистратора на заявка
+
+```
+logs/
+└── claude_gemini_claude-sonnet_20260208_143045/
+    ├── 1_req_client.json      ← Raw client request
+    ├── 2_req_source.json      ← After initial conversion
+    ├── 3_req_openai.json      ← OpenAI intermediate format
+    ├── 4_req_target.json      ← Final target format
+    ├── 5_res_provider.txt     ← Provider SSE chunks (streaming)
+    ├── 5_res_provider.json    ← Provider response (non-streaming)
+    ├── 6_res_openai.txt       ← OpenAI intermediate chunks
+    ├── 7_res_client.txt       ← Client-facing SSE chunks
+    └── 6_error.json           ← Error details (if any)
+```
+
+---
+
+### 4.7 Приложен слой (`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/`  | Управление на състоянието на приложението                                                                    |
+
+#### Известни API маршрути
+
+| Маршрут                                       | Методи                           | Цел                                                                                                     |
+| --------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `/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`                            | ВЗЕМЕТЕ                          | Състояние на ограничение на лимита по сметка                                                            |
+
+---
+
+## 5. Ключови модели на дизайн
+
+### 5.1 Hub-and-Spoke превод
+
+Всички формати се превеждат през **OpenAI формат като център**. Добавянето на нов доставчик изисква само писане на **една двойка** преводачи (към/от OpenAI), а не на N двойки.
+
+### 5.2 Модел на стратегия за изпълнител
+
+Всеки доставчик има специален клас изпълнител, наследен от `BaseExecutor`. Фабриката в `executors/index.ts` избира правилния по време на изпълнение.
+
+### 5.3 Саморегистрираща се плъгин система
+
+Модулите за преводач се регистрират при импортиране чрез `register()`. Добавянето на нов преводач е просто създаване на файл и импортирането му.
+
+### 5.4 Резервен акаунт с експоненциално отстъпление
+
+Когато доставчикът върне 429/401/500, системата може да превключи към следващия акаунт, прилагайки експоненциално охлаждане (1s → 2s → 4s → max 2min).
+
+### Комбинирани вериги за модели 5.5
+
+„Комбо“ групира множество низове `provider/model`. Ако първият не успее, автоматично се върнете към следващия.
+
+### 5.6 Поточен превод с пълно състояние
+
+Преводът на отговор поддържа състоянието в SSE блокове (проследяване на мислещ блок, натрупване на извикване на инструмент, индексиране на блок съдържание) чрез механизма `initState()`.
+
+### 5.7 Буфер за безопасност при използване
+
+Добавя се буфер от 2000 токена към отчетеното използване, за да се предотврати достигането на ограниченията на контекстните прозорци на клиентите поради натоварване от системни подкани и превод на формати.
+
+---
+
+## 6. Поддържани формати
+
+| Формат                    | Посока         | Идентификатор      |
+| ------------------------- | -------------- | ------------------ |
+| Завършвания на OpenAI чат | източник + цел | `openai`           |
+| OpenAI Responses API      | източник + цел | `openai-responses` |
+| Антропичен Клод           | източник + цел | `claude`           |
+| Google Gemini             | източник + цел | `gemini`           |
+| Google Gemini CLI         | само цел       | `gemini-cli`       |
+| Антигравитация            | източник + цел | `antigravity`      |
+| AWS Киро                  | само цел       | `kiro`             |
+| Курсор                    | само цел       | `cursor`           |
+
+---
+
+## 7. Поддържани доставчици
+
+| Доставчик                | Метод за удостоверяване          | Изпълнител      | Основни бележки                                    |
+| ------------------------ | -------------------------------- | --------------- | -------------------------------------------------- |
+| Антропичен Клод          | 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 |
+
+---
+
+## 8. Резюме на потока от данни
+
+### Заявка за поточно предаване
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor\nbuildUrl + buildHeaders"]
+    D --> E["fetch(providerURL)"]
+    E --> F["createSSEStream()\nTRANSLATE mode"]
+    F --> G["parseSSELine()"]
+    G --> H["translateResponse()\ntarget → OpenAI → source"]
+    H --> I["extractUsage()\n+ addBuffer"]
+    I --> J["formatSSE()"]
+    J --> K["Client receives\ntranslated SSE"]
+    K --> L["logUsage()\nsaveRequestUsage()"]
+```
+
+### Заявка без поточно предаване
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor.execute()"]
+    D --> E["translateResponse()\ntarget → OpenAI → source"]
+    E --> F["Return JSON\nresponse"]
+```
+
+### Байпасен поток (Claude CLI)
+
+```mermaid
+flowchart LR
+    A["Claude CLI request"] --> B{"Match bypass\npattern?"}
+    B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"]
+    B -->|"No match"| D["Normal flow"]
+    C --> E["Translate to\nsource format"]
+    E --> F["Return without\ncalling provider"]
+```

docs/i18n/bg/FEATURES.md

@@ -0,0 +1,77 @@
+# 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.
+
+---
+
+## 🔌 Доставчици
+
+Управлявайте връзките на доставчици на AI: OAuth доставчици (Claude Code, Codex, Gemini CLI), доставчици на API ключове (Groq, DeepSeek, OpenRouter) и безплатни доставчици (iFlow, Qwen, Kiro).
+
+![Providers Dashboard](screenshots/01-providers.png)
+
+---
+
+## 🎨 Комбота
+
+Създавайте комбинации за маршрутизиране на модели с 6 стратегии: първо попълване, кръгъл робин, мощност от два избора, произволна, най-малко използвана и оптимизирана по отношение на разходите. Всяка комбинация свързва няколко модела с автоматичен резервен вариант.
+
+![Combos Dashboard](screenshots/02-combos.png)
+
+---
+
+## 📊 Анализ
+
+Изчерпателни анализи на използването с потребление на токени, оценки на разходите, топлинни карти на активността, седмични диаграми на разпределение и разбивки по доставчик.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
+
+---
+
+## 🏥 Здраве на системата
+
+Мониторинг в реално време: време на работа, памет, версия, процентили на латентност (p50/p95/p99), статистика на кеша и състояния на прекъсвача на доставчика.
+
+![Health Dashboard](screenshots/04-health.png)
+
+---
+
+## 🔧 Площадка за преводачи
+
+Четири режима за отстраняване на грешки в API преводи: **Playground** (конвертор на формати), **Chat Tester** (заявки на живо), **Test Bench** (пакетни тестове) и **Live Monitor** (поток в реално време).
+
+![Translator Playground](screenshots/05-translator.png)
+
+---
+
+## ⚙️ Настройки
+
+Общи настройки, системно съхранение, управление на архивиране (база данни за експортиране/импортиране), външен вид (тъмен/светъл режим), сигурност (включва защита на крайна точка на API и блокиране на потребителски доставчик), маршрутизиране, устойчивост и разширена конфигурация.
+
+![Settings Dashboard](screenshots/06-settings.png)
+
+---
+
+## 🔧 CLI инструменти
+
+Конфигурация с едно щракване за инструменти за кодиране на AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code и Antigravity.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+
+---
+
+## 📝 Регистри за заявки
+
+Регистриране на заявки в реално време с филтриране по доставчик, модел, акаунт и API ключ. Показва кодове за състояние, използване на токени, латентност и подробности за отговора.
+
+![Usage Logs](screenshots/08-usage.png)
+
+---
+
+## 🌐 Крайна точка на API
+
+Вашата унифицирана крайна точка на API с разбивка на възможностите: завършвания на чат, вграждания, генериране на изображения, прекласиране, аудио транскрипция и регистрирани ключове за API.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)

docs/i18n/bg/TROUBLESHOOTING.md

@@ -0,0 +1,219 @@
+# Отстраняване на неизправности
+
+🌐 **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.
+
+---
+
+## Бързи поправки
+
+| Проблем                                           | Решение                                                                        |
+| ------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Първото влизане не работи                         | Проверете `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 схема за постоянство на настройките) |
+
+---
+
+## Проблеми с доставчика
+
+### „Езиковият модел не предостави съобщения“
+
+**Причина:** Квотата на доставчика е изчерпана.
+
+**Коригиране:**
+
+1. Проверете инструмента за проследяване на квоти на таблото за управление
+2. Използвайте комбо с резервни нива
+3. Преминете към по-евтино/безплатно ниво
+
+### Ограничаване на скоростта
+
+**Причина:** Абонаментната квота е изчерпана.
+
+**Коригиране:**
+
+- Добавете резервен вариант: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Използвайте GLM/MiniMax като евтино резервно копие
+
+### OAuth Token е изтекъл
+
+OmniRoute автоматично опреснява токените. Ако проблемите продължават:
+
+1. Табло → Доставчик → Свързване отново
+2. Изтрийте и добавете отново връзката с доставчика
+
+---
+
+## Проблеми с облака
+
+### Грешки при синхронизиране в облак
+
+1. Проверете дали `BASE_URL` сочи към вашия работещ екземпляр (напр. `http://localhost:20128`)
+2. Проверете `CLOUD_URL` точки към вашата крайна точка в облака (напр. `https://omniroute.dev`)
+3. Поддържайте стойностите на `NEXT_PUBLIC_*` в съответствие със стойностите от страна на сървъра
+
+### Cloud `stream=false` Връща 500
+
+**Симптом:** `Unexpected token 'd'...` в крайна точка на облака за обаждания без поточно предаване.
+
+**Причина:** Upstream връща SSE полезен товар, докато клиентът очаква JSON.
+
+**Заобиколно решение:** Използвайте `stream=true` за директни обаждания в облака. Локалното време на изпълнение включва резервен SSE→JSON.
+
+### Облакът казва Свързан, но „Невалиден API ключ“
+
+1. Създайте нов ключ от локалното табло за управление (`/api/keys`)
+2. Стартирайте облачна синхронизация: Активирайте Облак → Синхронизирай сега
+3. Старите/несинхронизирани ключове все още могат да връщат `401` в облака
+
+---
+
+## Проблеми с Docker
+
+### CLI инструментът показва, че не е инсталиран
+
+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`: двоичен файл е намерен, но проверката на състоянието е неуспешна
+
+### Бързо валидиране по време на изпълнение
+
+```bash
+curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+```
+
+---
+
+## Проблеми с разходите
+
+### Високи разходи
+
+1. Проверете статистическите данни за употреба в Табло → Използване
+2. Превключете основния модел на GLM/MiniMax
+3. Използвайте безплатно ниво (Gemini CLI, iFlow) за некритични задачи
+4. Задайте бюджети за разходи за API ключ: Табло за управление → API ключове → Бюджет
+
+---
+
+## Отстраняване на грешки
+
+### Активиране на регистрационните файлове на заявките
+
+Задайте `ENABLE_REQUEST_LOGS=true` във вашия `.env` файл. Дневниците се появяват в директорията `logs/`.
+
+### Проверете здравето на доставчика
+
+```bash
+# Health dashboard
+http://localhost:20128/dashboard/health
+
+# API health check
+curl http://localhost:20128/api/monitoring/health
+```
+
+### Съхранение по време на изпълнение
+
+- Основно състояние: `${DATA_DIR}/db.json` (доставчици, комбинации, псевдоними, ключове, настройки)
+- Използване: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
+- Регистрации за заявки: `<repo>/logs/...` (когато `ENABLE_REQUEST_LOGS=true`)
+
+---
+
+## Проблеми с прекъсвача
+
+### Доставчикът остана в ОТВОРЕНО състояние
+
+Когато прекъсвачът на доставчика е ОТВОРЕЕН, заявките се блокират, докато изтече времето за охлаждане.
+
+**Коригиране:**
+
+1. Отидете на **Табло → Настройки → Устойчивост**
+2. Проверете картата на прекъсвача на засегнатия доставчик
+3. Щракнете върху **Нулиране на всички**, за да изчистите всички прекъсвачи, или изчакайте времето за охлаждане да изтече
+4. Уверете се, че доставчикът действително е наличен, преди да нулирате
+
+### Доставчикът продължава да изключва прекъсвача
+
+Ако доставчик многократно влиза в ОТВОРЕНО състояние:
+
+1. Проверете **Табло → Здраве → Здраве на доставчика** за модела на повреда
+2. Отидете на **Настройки → Устойчивост → Профили на доставчици** и увеличете прага на отказ
+3. Проверете дали доставчикът е променил ограниченията на API или изисква повторно удостоверяване
+4. Прегледайте телеметрията за латентност — високата латентност може да причини грешки, базирани на изчакване
+
+---
+
+## Проблеми с аудио транскрипцията
+
+### Грешка „Неподдържан модел“.
+
+- Уверете се, че използвате правилния префикс: `deepgram/nova-3` или `assemblyai/best`
+- Проверете дали доставчикът е свързан в **Табло → Доставчици**
+
+### Транскрипцията се връща празна или е неуспешна
+
+- Проверете поддържаните аудио формати: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Уверете се, че размерът на файла е в границите на доставчика (обикновено < 25MB)
+- Проверете валидността на API ключа на доставчика в картата на доставчика
+
+---
+
+## Отстраняване на грешки на преводача
+
+Използвайте **Табло за управление → Преводач** за отстраняване на грешки при проблеми с превода на формат:
+
+| Режим               | Кога да използвате                                                                                        |
+| ------------------- | --------------------------------------------------------------------------------------------------------- |
+| **Детска площадка** | Сравнете входно/изходните формати един до друг — поставете неуспешна заявка, за да видите как се превежда |
+| **Чат тестер**      | Изпращайте съобщения на живо и проверявайте пълния полезен товар на заявка/отговор, включително заглавки  |
+| **Тестова стенда**  | Изпълнете пакетни тестове в комбинации от формати, за да откриете кои преводи са нарушени                 |
+| **Монитор на живо** | Гледайте потока на заявките в реално време, за да уловите периодични проблеми с превода                   |
+
+### Често срещани проблеми с формата
+
+- **Мислещите етикети не се появяват** — Проверете дали целевият доставчик поддържа мисленето и настройката на бюджета за мислене
+- **Отпадане на извикванията на инструменти** — Някои преводи на формати може да премахнат неподдържаните полета; потвърдете в режим 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
+
+---
+
+## Настройки за устойчивост
+
+### Автоматичното ограничение на скоростта не се задейства
+
+- Автоматичното ограничение на скоростта се прилага само за доставчици на API ключове (не OAuth/абонамент)
+- Уверете се, че **Настройки → Устойчивост → Профили на доставчици** има активиран автоматичен лимит на скоростта
+- Проверете дали доставчикът връща `429` кодове за състояние или `Retry-After` заглавки
+
+### Настройване на експоненциално забавяне
+
+Профилите на доставчика поддържат тези настройки:
+
+- **Базово забавяне** — Първоначално време на изчакване след първата повреда (по подразбиране: 1s)
+- **Максимално забавяне** — Максимално ограничение на времето за изчакване (по подразбиране: 30 секунди)
+- **Множител** — Колко да се увеличи закъснението за последователен отказ (по подразбиране: 2x)
+
+### Анти-гръмотевично стадо
+
+Когато много едновременни заявки попаднат на доставчик с ограничена скорост, OmniRoute използва mutex + автоматично ограничаване на скоростта, за да сериализира заявките и да предотврати каскадни грешки. Това е автоматично за доставчиците на API ключове.
+
+---
+
+## Все още сте заседнали?
+
+- **Проблеми с GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Архитектура**: Вижте [link](ARCHITECTURE.md) за вътрешни подробности
+- **API Reference**: Вижте [link](API_REFERENCE.md) за всички крайни точки
+- **Табло за управление на здравето**: Проверете **Табло за управление → Здраве** за състоянието на системата в реално време
+- **Преводач**: Използвайте **Табло за управление → Преводач** за отстраняване на грешки при проблеми с формата

docs/i18n/bg/USER_GUIDE.md

@@ -0,0 +1,698 @@
+# Ръководство за потребителя
+
+🌐 **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.
+
+---
+
+## Съдържание
+
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
+
+## 💰 Ценообразуването с един поглед
+
+| Ниво               | Доставчик         | Цена                  | Нулиране на квота       | Най-добро за              |
+| ------------------ | ----------------- | --------------------- | ----------------------- | ------------------------- |
+| **💳 АБОНАМЕНТ**   | 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                    | Неограничен             | Клод безплатно            |
+
+**💡 Професионален съвет:** Започнете с Gemini CLI (180K безплатно/месец) + iFlow (неограничено безплатно) комбинация = $0 цена!
+
+---
+
+## 🎯 Случаи на употреба
+
+### Случай 1: „Имам абонамент за Claude Pro“
+
+**Проблем:** Квотата изтича неизползвана, ограничения на скоростта по време на тежко кодиране
+
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6        (use subscription fully)
+  2. glm/glm-4.7               (cheap backup when quota out)
+  3. if/kimi-k2-thinking       (free emergency fallback)
+
+Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
+vs. $20 + hitting limits = frustration
+```
+
+### Случай 2: „Искам нулеви разходи“
+
+**Проблем:** Не мога да си позволя абонаменти, имам нужда от надеждно AI кодиране
+
+```
+Combo: "free-forever"
+  1. gc/gemini-3-flash         (180K free/month)
+  2. if/kimi-k2-thinking       (unlimited free)
+  3. qw/qwen3-coder-plus       (unlimited free)
+
+Monthly cost: $0
+Quality: Production-ready models
+```
+
+### Случай 3: „Имам нужда от кодиране 24/7, без прекъсвания“
+
+**Проблем:** Крайни срокове, не мога да си позволя престой
+
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-6        (best quality)
+  2. cx/gpt-5.2-codex          (second subscription)
+  3. glm/glm-4.7               (cheap, resets daily)
+  4. minimax/MiniMax-M2.1      (cheapest, 5h reset)
+  5. if/kimi-k2-thinking       (free unlimited)
+
+Result: 5 layers of fallback = zero downtime
+Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
+```
+
+### Случай 4: „Искам БЕЗПЛАТЕН AI в OpenClaw“
+
+**Проблем:** Имате нужда от AI асистент в приложенията за съобщения, напълно безплатно
+
+```
+Combo: "openclaw-free"
+  1. if/glm-4.7                (unlimited free)
+  2. if/minimax-m2.1           (unlimited free)
+  3. if/kimi-k2-thinking       (unlimited free)
+
+Monthly cost: $0
+Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+```
+
+---
+
+## 📖 Настройка на доставчик
+
+### 🔐 Доставчици на абонаменти
+
+#### Claude Code (Pro/Max)
+
+```bash
+Dashboard → Providers → Connect Claude Code
+→ OAuth login → Auto token refresh
+→ 5-hour + weekly quota tracking
+
+Models:
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**Професионален съвет:** Използвайте Opus за сложни задачи, Sonnet за скорост. OmniRoute проследява квота за модел!
+
+#### OpenAI Codex (Plus/Pro)
+
+```bash
+Dashboard → Providers → Connect Codex
+→ OAuth login (port 1455)
+→ 5-hour + weekly reset
+
+Models:
+  cx/gpt-5.2-codex
+  cx/gpt-5.1-codex-max
+```
+
+#### Gemini CLI (БЕЗПЛАТНО 180K/месец!)
+
+```bash
+Dashboard → Providers → Connect Gemini CLI
+→ Google OAuth
+→ 180K completions/month + 1K/day
+
+Models:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**Най-добра стойност:** Огромно безплатно ниво! Използвайте това преди платените нива.
+
+#### Копилот на GitHub
+
+```bash
+Dashboard → Providers → Connect GitHub
+→ OAuth via GitHub
+→ Monthly reset (1st of month)
+
+Models:
+  gh/gpt-5
+  gh/claude-4.5-sonnet
+  gh/gemini-3-pro
+```
+
+### 💰 Евтини доставчици
+
+#### GLM-4.7 (Ежедневно нулиране, $0,6/1 млн.)
+
+1. Регистрирайте се: [Zhipu AI](https://open.bigmodel.cn/)
+2. Вземете API ключ от Coding Plan
+3. Табло → Добавяне на API ключ: Доставчик: `glm`, API ключ: `your-key`
+
+**Използване:** `glm/glm-4.7` — **Професионален съвет:** Планът за кодиране предлага 3× квота на цена 1/7! Нулирайте всеки ден в 10:00 ч.
+
+#### MiniMax M2.1 (5 часа нулиране, $0,20/1 млн.)
+
+1. Регистрирайте се: [MiniMax](https://www.minimax.io/)
+2. Вземете API ключ → Табло → Добавете API ключ
+
+**Използване:** `minimax/MiniMax-M2.1` — **Професионален съвет:** Най-евтината опция за дълъг контекст (1M токени)!
+
+#### Kimi K2 ($9/месец фиксиран)
+
+1. Абонирайте се: [Moonshot AI](https://platform.moonshot.ai/)
+2. Вземете API ключ → Табло → Добавете API ключ
+
+**Използване:** `kimi/kimi-latest` — **Професионален съвет:** Фиксирани $9/месец за 10 милиона токена = $0,90/1 милион ефективна цена!
+
+### 🆓 БЕЗПЛАТНИ доставчици
+
+#### iFlow (8 БЕЗПЛАТНИ модела)
+
+```bash
+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 БЕЗПЛАТНИ модела)
+
+```bash
+Dashboard → Connect Qwen → Device code auth → Unlimited usage
+
+Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
+```
+
+#### Киро (Клод БЕЗПЛАТНО)
+
+```bash
+Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
+
+Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
+```
+
+---
+
+## 🎨 Комбота
+
+### Пример 1: Увеличаване на абонамента → Евтино архивиране
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-6 (Subscription primary)
+  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
+  3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
+
+Use in CLI: premium-coding
+```
+
+### Пример 2: Само безплатно (нулева цена)
+
+```
+Name: free-combo
+Models:
+  1. gc/gemini-3-flash-preview (180K free/month)
+  2. if/kimi-k2-thinking (unlimited)
+  3. qw/qwen3-coder-plus (unlimited)
+
+Cost: $0 forever!
+```
+
+---
+
+## 🔧 CLI интеграция
+
+### Курсор IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from omniroute dashboard]
+  Model: cc/claude-opus-4-6
+```
+
+### Клод Код
+
+Редактиране на `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-omniroute-api-key"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-omniroute-api-key"
+codex "your prompt"
+```
+
+### OpenClaw
+
+Редактиране на `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": { "primary": "omniroute/if/glm-4.7" }
+    }
+  },
+  "models": {
+    "providers": {
+      "omniroute": {
+        "baseUrl": "http://localhost:20128/v1",
+        "apiKey": "your-omniroute-api-key",
+        "api": "openai-completions",
+        "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+      }
+    }
+  }
+}
+```
+
+**Или използвайте таблото за управление:** CLI инструменти → OpenClaw → Автоматично конфигуриране
+
+### Cline / Продължи / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-6
+```
+
+---
+
+## 🚀 Внедряване
+
+### Внедряване на VPS
+
+```bash
+git clone https://github.com/diegosouzapw/OmniRoute.git
+cd OmniRoute && npm install && npm run build
+
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+export DATA_DIR="/var/lib/omniroute"
+export PORT="20128"
+export HOSTNAME="0.0.0.0"
+export NODE_ENV="production"
+export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
+export API_KEY_SECRET="endpoint-proxy-api-key-secret"
+
+npm run start
+# Or: pm2 start npm --name omniroute -- start
+```
+
+### Докер
+
+```bash
+# Build image (default = runner-cli with codex/claude/droid preinstalled)
+docker build -t omniroute:cli .
+
+# Portable mode (recommended)
+docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
+```
+
+За интегриран в хост режим с двоични файлове на CLI вижте раздела Docker в основните документи.
+
+### Променливи на средата
+
+| Променлива            | По подразбиране                        | Описание                                                                     |
+| --------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| `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 обратен прокси) |
+
+За пълната справка за променливите на средата вижте [README](../README.md).
+
+---
+
+## 📊 Налични модели
+
+<details>
+<summary><b>Вижте всички налични модели</b></summary>
+
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+
+**Gemini CLI (`gc/`)** — БЕЗПЛАТНО: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
+
+**GLM (`glm/`)** — $0,6/1 млн.: `glm/glm-4.7`
+
+**MiniMax (`minimax/`)** — $0,2/1 млн.: `minimax/MiniMax-M2.1`
+
+**iFlow (`if/`)** — БЕЗПЛАТНО: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+
+**Qwen (`qw/`)** — БЕЗПЛАТНО: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+
+**Киро (`kr/`)** — БЕЗПЛАТНО: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
+
+**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`
+
+**Мистрал (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
+
+**Недоумение (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+
+**Заедно AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+
+**Фойерверки AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
+
+**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
+
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+</details>
+
+---
+
+## 🧩 Разширени функции
+
+### Персонализирани модели
+
+Добавете всеки ID на модел към всеки доставчик, без да чакате актуализация на приложението:
+
+```bash
+# Via API
+curl -X POST http://localhost:20128/api/provider-models \
+  -H "Content-Type: application/json" \
+  -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}'
+
+# List: curl http://localhost:20128/api/provider-models?provider=openai
+# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
+```
+
+Или използвайте таблото за управление: **Доставчици → [Доставчик] → Персонализирани модели**.
+
+### Специализирани маршрути на доставчик
+
+Насочвайте заявките директно към конкретен доставчик с валидиране на модела:
+
+```bash
+POST http://localhost:20128/v1/providers/openai/chat/completions
+POST http://localhost:20128/v1/providers/openai/embeddings
+POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
+
+Префиксът на доставчика се добавя автоматично, ако липсва. Несъответстващите модели връщат `400`.
+
+### Конфигурация на мрежов прокси
+
+```bash
+# Set global proxy
+curl -X PUT http://localhost:20128/api/settings/proxy \
+  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
+
+# Per-provider proxy
+curl -X PUT http://localhost:20128/api/settings/proxy \
+  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
+
+# Test proxy
+curl -X POST http://localhost:20128/api/settings/proxy/test \
+  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
+```
+
+**Приоритет:** Специфичен за ключ → Специфичен за комбинация → Специфичен за доставчик → Глобален → Среда.
+
+### API за каталог на модели
+
+```bash
+curl http://localhost:20128/api/models/catalog
+```
+
+Връща модели, групирани по доставчик с типове (`chat`, `embedding`, `image`).
+
+### Облачно синхронизиране
+
+- Синхронизиране на доставчици, комбинации и настройки на всички устройства
+- Автоматична фонова синхронизация с изчакване + бързо отказване
+- Предпочитане на сървъра `BASE_URL`/`CLOUD_URL` в производството
+
+### LLM Gateway Intelligence (Фаза 9)
+
+- **Семантичен кеш** — Автоматично кешира нестрийминг, температура=0 отговори (заобикаляне с `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Дедупликира заявките в рамките на 5s чрез `Idempotency-Key` или `X-Request-Id` заглавка
+- **Проследяване на напредъка** — Включване на SSE `event: progress` събития чрез `X-OmniRoute-Progress: true` заглавка
+
+---
+
+### Площадка за преводачи
+
+Достъп чрез **Табло → Преводач**. Отстранете грешки и визуализирайте как OmniRoute превежда API заявки между доставчици.
+
+| Режим               | Цел                                                                                                  |
+| ------------------- | ---------------------------------------------------------------------------------------------------- |
+| **Детска площадка** | Изберете изходни/целеви формати, поставете заявка и незабавно вижте преведения резултат              |
+| **Чат тестер**      | Изпращайте чат съобщения на живо през проксито и проверявайте пълния цикъл на заявка/отговор         |
+| **Тестова стенда**  | Изпълнете групови тестове в множество комбинации от формати, за да проверите правилността на превода |
+| **Монитор на живо** | Гледайте преводи в реално време, докато заявките преминават през проксито                            |
+
+**Случаи на употреба:**
+
+- Отстраняване на грешки защо конкретна комбинация клиент/доставчик е неуспешна
+- Проверете дали мислещите тагове, извикванията на инструменти и системните подкани се превеждат правилно
+- Сравнете разликите във форматите между форматите OpenAI, Claude, Gemini и Responses API
+
+---
+
+### Стратегии за маршрутизиране
+
+Конфигурирайте чрез **Табло → Настройки → Маршрутизация**.
+
+| Стратегия                    | Описание                                                                                                       |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| **Първо попълване**          | Използва акаунти в приоритетен ред — основният акаунт обработва всички заявки, докато стане недостъпен         |
+| **Round Robin**              | Преминава през всички акаунти с конфигурируем лепкав лимит (по подразбиране: 3 обаждания на акаунт)            |
+| **P2C (Сила на два избора)** | Избира 2 произволни акаунта и маршрути към по-здравословния — балансира натоварването с осъзнаване на здравето |
+| **Произволно**               | Произволно избира акаунт за всяка заявка чрез разбъркване на Fisher-Yates                                      |
+| **Най-малко използвани**     | Насочва към акаунта с най-стария `lastUsedAt` времеви печат, разпределяйки трафика равномерно                  |
+| **Оптимизирани разходи**     | Маршрути към акаунта с най-ниска стойност на приоритет, оптимизиране за доставчици с най-ниска цена            |
+
+#### Псевдоними на модели със заместващи символи
+
+Създайте шаблони със заместващи знаци, за да пренасочите имената на моделите:
+
+```
+Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-*               →  Target: gh/gpt-5.1-codex
+```
+
+Заместващите знаци поддържат `*` (всякакви знаци) и `?` (единичен знак).
+
+#### Резервни вериги
+
+Дефинирайте глобални резервни вериги, които се прилагат за всички заявки:
+
+```
+Chain: production-fallback
+  1. cc/claude-opus-4-6
+  2. gh/gpt-5.1-codex
+  3. glm/glm-4.7
+```
+
+---
+
+### Устойчивост и прекъсвачи
+
+Конфигурирайте чрез **Табло → Настройки → Устойчивост**.
+
+OmniRoute прилага устойчивост на ниво доставчик с четири компонента:
+
+1. **Профили на доставчици** — Конфигурация за всеки доставчик за:
+   - Праг на повреда (колко повреда преди отваряне)
+   - Продължителност на изчакване
+   - Чувствителност на откриване на ограничение на скоростта
+   - Параметри на експоненциално забавяне
+
+2. **Редактируеми ограничения на скоростта** — Настройки по подразбиране на системно ниво, които могат да се конфигурират в таблото за управление:
+   - **Заявки в минута (RPM)** — Максимален брой заявки в минута за акаунт
+   - **Минимално време между заявките** — Минимална разлика в милисекунди между заявките
+   - **Максимални едновременни заявки** — Максимални едновременни заявки за акаунт
+   - Щракнете върху **Редактиране**, за да промените, след това върху **Запазване** или **Отказ**. Стойностите се запазват чрез API за устойчивост.
+
+3. **Прекъсвач на веригата** — Проследява повреди на доставчик и автоматично отваря веригата при достигане на праг:
+   - **ЗАТВОРЕНО** (здравословно) — Заявките протичат нормално
+   - **OPEN** — Доставчикът е временно блокиран след повтарящи се повреди
+   - **HALF_OPEN** — Тестване дали доставчикът се е възстановил
+
+4. **Правила и заключени идентификатори** — Показва състоянието на прекъсвача и заключените идентификатори с възможност за принудително отключване.
+
+5. **Автоматично откриване на ограничение на скоростта** — Наблюдава заглавките `429` и `Retry-After`, за да избегне проактивно достигане на ограниченията на скоростта на доставчика.
+
+**Професионален съвет:** Използвайте бутона **Нулиране на всички**, за да изчистите всички прекъсвачи и изчаквания, когато доставчикът се възстанови от прекъсване.
+
+---
+
+### Експорт/импорт на база данни
+
+Управлявайте резервни копия на бази данни в **Табло → Настройки → Система и съхранение**.
+
+| Действие                             | Описание                                                                                                                                          |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Експортиране на база данни**       | Изтегля текущата база данни SQLite като `.sqlite` файл                                                                                            |
+| **Експортиране на всички (.tar.gz)** | Изтегля пълен резервен архив, включително: база данни, настройки, комбинации, връзки с доставчик (без идентификационни данни), API ключ метаданни |
+| **Импортиране на база данни**        | Качете файл `.sqlite`, за да замените текущата база данни. Автоматично се създава резервно копие преди импортиране                                |
+
+```bash
+# API: Export database
+curl -o backup.sqlite http://localhost:20128/api/db-backups/export
+
+# API: Export all (full archive)
+curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
+
+# API: Import database
+curl -X POST http://localhost:20128/api/db-backups/import \
+  -F "file=@backup.sqlite"
+```
+
+**Проверка на импортиране:** Импортираният файл се валидира за цялост (проверка на SQLite pragma), необходими таблици (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) и размер (макс. 100MB).
+
+**Случаи на употреба:**
+
+- Мигрирайте OmniRoute между машини
+- Създаване на външни резервни копия за възстановяване след бедствие
+- Споделяне на конфигурации между членовете на екипа (експортиране на всички → споделяне на архив)
+
+---
+
+### Табло за управление на настройките
+
+Страницата с настройки е организирана в 5 раздела за лесна навигация:
+
+| Раздел             | Съдържание                                                                                                                                          |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Сигурност**      | Настройки за вход/парола, IP контрол на достъпа, API удостоверяване за `/models` и блокиране на доставчик                                           |
+| **Маршрутизиране** | Стратегия за глобално маршрутизиране (6 опции), псевдоними на модели със заместващи символи, резервни вериги, комбинирани настройки по подразбиране |
+| **Устойчивост**    | Профили на доставчици, редактируеми лимити на скоростта, състояние на прекъсвача, политики и заключени идентификатори                               |
+| **AI**             | Обмисляне на конфигурация на бюджета, инжектиране на глобална система, статистика на бързия кеш                                                     |
+| **Разширено**      | Глобална прокси конфигурация (HTTP/SOCKS5)                                                                                                          |
+
+---
+
+### Управление на разходите и бюджета
+
+Достъп чрез **Табло → Разходи**.
+
+| Раздел     | Цел                                                                                                            |
+| ---------- | -------------------------------------------------------------------------------------------------------------- |
+| **Бюджет** | Задайте лимити на разходите за API ключ с дневни/седмични/месечни бюджети и проследяване в реално време        |
+| **Цени**   | Преглеждайте и редактирайте записи за ценообразуване на модела — цена за 1K входно/изходни токени на доставчик |
+
+```bash
+# API: Set a budget
+curl -X POST http://localhost:20128/api/usage/budget \
+  -H "Content-Type: application/json" \
+  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
+
+# API: Get current budget status
+curl http://localhost:20128/api/usage/budget
+```
+
+**Проследяване на разходите:** Всяка заявка регистрира използването на токени и изчислява разходите с помощта на таблицата с цените. Вижте разбивки в **Табло за управление → Използване** по доставчик, модел и API ключ.
+
+---
+
+### Аудио транскрипция
+
+OmniRoute поддържа аудио транскрипция чрез OpenAI-съвместима крайна точка:
+
+```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+
+# Example with curl
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+  -H "Authorization: Bearer your-api-key" \
+  -F "file=@audio.mp3" \
+  -F "model=deepgram/nova-3"
+```
+
+Налични доставчици: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
+
+Поддържани аудио формати: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+
+---
+
+### Комбинирани стратегии за балансиране
+
+Конфигурирайте балансирането за комбо в **Табло за управление → Комбота → Създаване/Редактиране → Стратегия**.
+
+| Стратегия                    | Описание                                                                         |
+| ---------------------------- | -------------------------------------------------------------------------------- |
+| **Round-Robin**              | Върти се през моделите последователно                                            |
+| **Приоритет**                | Винаги пробва първия модел; връща се само при грешка                             |
+| **Произволно**               | Избира произволен модел от комбинацията за всяка заявка                          |
+| **Претеглено**               | Маршрути пропорционално въз основа на зададени тегла за модел                    |
+| **Най-малко използвани**     | Насочва към модела с най-малко скорошни заявки (използва комбинирани показатели) |
+| **Оптимизиран за разходите** | Маршрути до най-евтиния наличен модел (използва ценова таблица)                  |
+
+Глобалните настройки по подразбиране на комбинацията могат да бъдат зададени в **Табло → Настройки → Маршрут → Настройки по подразбиране на комбинация**.
+
+---
+
+### Здравно табло
+
+Достъп чрез **Табло → Здраве**. Преглед на здравето на системата в реално време с 6 карти:
+
+| Карта                        | Какво показва                                                              |
+| ---------------------------- | -------------------------------------------------------------------------- |
+| **Състояние на системата**   | Време на работа, версия, използване на паметта, директория с данни         |
+| **Здраве на доставчика**     | Състояние на прекъсвача за всеки доставчик (затворен/отворен/полуотворен)  |
+| **Ограничения на скоростта** | Активен лимит на изчакване за акаунт с оставащо време                      |
+| **Активни блокировки**       | Доставчици, временно блокирани от политиката за блокиране                  |
+| **Кеш на подписа**           | Статистика на кеша за дедупликация (активни ключове, процент на попадения) |
+| **Телеметрия за забавяне**   | p50/p95/p99 агрегиране на латентност за доставчик                          |
+
+**Професионален съвет:** Страницата Health се опреснява автоматично на всеки 10 секунди. Използвайте картата на прекъсвача, за да идентифицирате кои доставчици имат проблеми.

docs/i18n/da/API_REFERENCE.md

@@ -0,0 +1,441 @@
+# 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.
+
+---
+
+## Indholdsfortegnelse
+
+- [Chat Completions](#chat-completions)
+- [Embeddings](#embeddings)
+- [Image Generation](#image-generation)
+- [List Models](#list-models)
+- [Compatibility Endpoints](#compatibility-endpoints)
+- [Semantic Cache](#semantic-cache)
+- [Dashboard & Management](#dashboard--management)
+- [Request Processing](#request-processing)
+- [Authentication](#authentication)
+
+---
+
+## Chatafslutninger
+
+```bash
+POST /v1/chat/completions
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "cc/claude-opus-4-6",
+  "messages": [
+    {"role": "user", "content": "Write a function to..."}
+  ],
+  "stream": true
+}
+```
+
+### Brugerdefinerede overskrifter
+
+| 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å                |
+
+---
+
+## Indlejringer
+
+```bash
+POST /v1/embeddings
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "nebius/Qwen/Qwen3-Embedding-8B",
+  "input": "The food was delicious"
+}
+```
+
+Tilgængelige udbydere: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+
+```bash
+# List all embedding models
+GET /v1/embeddings
+```
+
+---
+
+## Billedgenerering
+
+```bash
+POST /v1/images/generations
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "openai/dall-e-3",
+  "prompt": "A beautiful sunset over mountains",
+  "size": "1024x1024"
+}
+```
+
+Tilgængelige udbydere: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+
+```bash
+# List all image models
+GET /v1/images/generations
+```
+
+---
+
+## Liste over modeller
+
+```bash
+GET /v1/models
+Authorization: Bearer your-api-key
+
+→ Returns all chat, embedding, and image models + combos in OpenAI format
+```
+
+---
+
+## Kompatibilitetsslutpunkter
+
+| Metode | Sti                         | Format                 |
+| ------ | --------------------------- | ---------------------- |
+| POST   | `/v1/chat/completions`      | OpenAI                 |
+| POST   | `/v1/messages`              | Antropisk              |
+| POST   | `/v1/responses`             | OpenAI-svar            |
+| 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 |
+| POST   | `/v1/api/chat`              | Ollama                 |
+
+### Dedikerede udbyderruter
+
+```bash
+POST /v1/providers/{provider}/chat/completions
+POST /v1/providers/{provider}/embeddings
+POST /v1/providers/{provider}/images/generations
+```
+
+Udbyderpræfikset tilføjes automatisk, hvis det mangler. Umatchede modeller returnerer `400`.
+
+---
+
+## Semantisk cache
+
+```bash
+# Get cache stats
+GET /api/cache
+
+# Clear all caches
+DELETE /api/cache
+```
+
+Eksempel på svar:
+
+```json
+{
+  "semanticCache": {
+    "memorySize": 42,
+    "memoryMaxSize": 500,
+    "dbSize": 128,
+    "hitRate": 0.65
+  },
+  "idempotency": {
+    "activeKeys": 3,
+    "windowMs": 5000
+  }
+}
+```
+
+---
+
+## Dashboard & Management
+
+### Godkendelse
+
+| 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 |
+
+### Udbyderstyring
+
+| 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    |
+
+### OAuth-flows
+
+| Slutpunkt                        | Metode      | Beskrivelse           |
+| -------------------------------- | ----------- | --------------------- |
+| `/api/oauth/[provider]/[action]` | Forskellige | Udbyderspecifik 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                        |
+
+### Brug og analyse
+
+| 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         |
+
+### Indstillinger
+
+| 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                 |
+
+### Overvågning
+
+| 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   |
+
+### Sikkerhedskopiering og eksport/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       |
+
+### Cloud Sync
+
+| Slutpunkt              | Metode      | Beskrivelse                      |
+| ---------------------- | ----------- | -------------------------------- |
+| `/api/sync/cloud`      | Forskellige | Cloud-synkroniseringsoperationer |
+| `/api/sync/initialize` | POST        | Initialiser synkronisering       |
+| `/api/cloud/*`         | Forskellige | Cloud management                 |
+
+### CLI-værktøjer
+
+| 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 |
+
+CLI-svar inkluderer: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
+
+### Modstandsdygtighed og satsgrænser
+
+| 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 |
+
+### Evals
+
+| Slutpunkt    | Metode   | Beskrivelse                         |
+| ------------ | -------- | ----------------------------------- |
+| `/api/evals` | GET/POST | Liste eval suiter / køre evaluering |
+
+### Politikker
+
+| Slutpunkt       | Metode        | Beskrivelse                   |
+| --------------- | ------------- | ----------------------------- |
+| `/api/policies` | GET/POST/SLET | Administrer routingpolitikker |
+
+### Overholdelse
+
+| Slutpunkt                   | Metode | Beskrivelse                          |
+| --------------------------- | ------ | ------------------------------------ |
+| `/api/compliance/audit-log` | FÅ     | Overholdelsesrevisionslog (sidste N) |
+
+### v1beta (Gemini-kompatibel)
+
+| Slutpunkt                  | Metode | Beskrivelse                        |
+| -------------------------- | ------ | ---------------------------------- |
+| `/v1beta/models`           | FÅ     | Vis modeller i Gemini-format       |
+| `/v1beta/models/{...path}` | POST   | Gemini `generateContent` slutpunkt |
+
+Disse endepunkter afspejler Geminis API-format for klienter, der forventer indbygget Gemini SDK-kompatibilitet.
+
+### Interne / System API'er
+
+| 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                              |
+
+> **Bemærk:** Disse endepunkter bruges internt af systemet eller til Ollama-klientkompatibilitet. De kaldes typisk ikke af slutbrugere.
+
+---
+
+## Lydtransskription
+
+```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+```
+
+Transskriber lydfiler ved hjælp af Deepgram eller AssemblyAI.
+
+**Forespørgsel:**
+
+```bash
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+  -H "Authorization: Bearer your-api-key" \
+  -F "file=@recording.mp3" \
+  -F "model=deepgram/nova-3"
+```
+
+**Svar:**
+
+```json
+{
+  "text": "Hello, this is the transcribed audio content.",
+  "task": "transcribe",
+  "language": "en",
+  "duration": 12.5
+}
+```
+
+**Understøttede udbydere:** `deepgram/nova-3`, `assemblyai/best`.
+
+**Understøttede formater:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+
+---
+
+## Ollama-kompatibilitet
+
+For klienter, der bruger Ollamas API-format:
+
+```bash
+# Chat endpoint (Ollama format)
+POST /v1/api/chat
+
+# Model listing (Ollama format)
+GET /api/tags
+```
+
+Forespørgsler oversættes automatisk mellem Ollama og interne formater.
+
+---
+
+## Telemetri
+
+```bash
+# Get latency telemetry summary (p50/p95/p99 per provider)
+GET /api/telemetry/summary
+```
+
+**Svar:**
+
+```json
+{
+  "providers": {
+    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
+    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
+  }
+}
+```
+
+---
+
+## Budget
+
+```bash
+# Get budget status for all API keys
+GET /api/usage/budget
+
+# Set or update a budget
+POST /api/usage/budget
+Content-Type: application/json
+
+{
+  "keyId": "key-123",
+  "limit": 50.00,
+  "period": "monthly"
+}
+```
+
+---
+
+## Modeltilgængelighed
+
+```bash
+# Get real-time model availability across all providers
+GET /api/models/availability
+
+# Check availability for a specific model
+POST /api/models/availability
+Content-Type: application/json
+
+{
+  "model": "claude-sonnet-4-5-20250929"
+}
+```
+
+---
+
+## Anmodningsbehandling
+
+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
+
+Fuld arkitekturreference: [link](ARCHITECTURE.md)
+
+---
+
+## Godkendelse
+
+- 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`

docs/i18n/da/ARCHITECTURE.md

@@ -0,0 +1,781 @@
+# OmniRoute-arkitektur
+
+🌐 **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_
+
+## Resumé
+
+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.
+
+Kerneegenskaber:
+
+- 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/`)
+
+Primær runtime model:
+
+- 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
+
+## Omfang og grænser
+
+### I omfang
+
+- Lokal gateway køretid
+- Dashboard management API'er
+- Udbydergodkendelse og tokenopdatering
+- Anmod om oversættelse og SSE-streaming
+- Lokal stat + vedvarende brug
+- Valgfri skysynkroniseringsorkestrering
+
+### Uden for anvendelsesområde
+
+- 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.)
+
+## Systemkontekst på højt niveau
+
+```mermaid
+flowchart LR
+    subgraph Clients[Developer Clients]
+        C1[Claude Code]
+        C2[Codex CLI]
+        C3[OpenClaw / Droid / Cline / Continue / Roo]
+        C4[Custom OpenAI-compatible clients]
+        BROWSER[Browser Dashboard]
+    end
+
+    subgraph Router[OmniRoute Local Process]
+        API[V1 Compatibility API\n/v1/*]
+        DASH[Dashboard + Management API\n/api/*]
+        CORE[SSE + Translation Core\nopen-sse + src/sse]
+        DB[(db.json)]
+        UDB[(usage.json + log.txt)]
+    end
+
+    subgraph Upstreams[Upstream Providers]
+        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity]
+        P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
+        P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
+    end
+
+    subgraph Cloud[Optional Cloud Sync]
+        CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL]
+    end
+
+    C1 --> API
+    C2 --> API
+    C3 --> API
+    C4 --> API
+    BROWSER --> DASH
+
+    API --> CORE
+    DASH --> DB
+    CORE --> DB
+    CORE --> UDB
+
+    CORE --> P1
+    CORE --> P2
+    CORE --> P3
+
+    DASH --> CLOUD
+```
+
+## Core Runtime Components
+
+## 1) API og Routing Layer (Next.js App Routes)
+
+Hovedmapper:
+
+- `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/*`
+
+Vigtige kompatibilitetsruter:
+
+- `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/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/v1beta/models/route.ts`
+- `src/app/api/v1beta/models/[...path]/route.ts`
+
+Ledelsesdomæner:
+
+- 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)
+- 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)
+- 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)
+
+## 2) SSE + Oversættelseskerne
+
+Hovedflowmoduler:
+
+- 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`
+
+Tjenester (forretningslogik):
+
+- 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`
+- Wildcard model routing: `open-sse/services/wildcardRouter.ts`
+- Satsgrænsestyring: `open-sse/services/rateLimitManager.ts`
+- Afbryder: `open-sse/services/circuitBreaker.ts`
+
+Domænelagsmoduler:
+
+- Modeltilgængelighed: `src/lib/domain/modelAvailability.ts`
+- Omkostningsregler/budgetter: `src/lib/domain/costRules.ts`
+- Fallback-politik: `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
+
+OAuth-udbydermoduler (12 individuelle filer 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
+
+## 3) Persistens-lag
+
+Primær tilstand DB:
+
+- `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**
+
+Brug DB:
+
+- `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`
+
+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
+
+## 4) Auth + Sikkerhedsoverflader
+
+- 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)
+
+## 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`
+
+## Anmod om livscyklus (`/v1/chat/completions`)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as CLI/SDK Client
+    participant Route as /api/v1/chat/completions
+    participant Chat as src/sse/handlers/chat
+    participant Core as open-sse/handlers/chatCore
+    participant Model as Model Resolver
+    participant Auth as Credential Selector
+    participant Exec as Provider Executor
+    participant Prov as Upstream Provider
+    participant Stream as Stream Translator
+    participant Usage as usageDb
+
+    Client->>Route: POST /v1/chat/completions
+    Route->>Chat: handleChat(request)
+    Chat->>Model: parse/resolve model or combo
+
+    alt Combo model
+        Chat->>Chat: iterate combo models (handleComboChat)
+    end
+
+    Chat->>Auth: getProviderCredentials(provider)
+    Auth-->>Chat: active account + tokens/api key
+
+    Chat->>Core: handleChatCore(body, modelInfo, credentials)
+    Core->>Core: detect source format
+    Core->>Core: translate request to target format
+    Core->>Exec: execute(provider, transformedBody)
+    Exec->>Prov: upstream API call
+    Prov-->>Exec: SSE/JSON response
+    Exec-->>Core: response + metadata
+
+    alt 401/403
+        Core->>Exec: refreshCredentials()
+        Exec-->>Core: updated tokens
+        Core->>Exec: retry request
+    end
+
+    Core->>Stream: translate/normalize stream to client format
+    Stream-->>Client: SSE chunks / JSON response
+
+    Stream->>Usage: extract usage + persist history/log
+```
+
+## Combo + Account Fallback Flow
+
+```mermaid
+flowchart TD
+    A[Incoming model string] --> B{Is combo name?}
+    B -- Yes --> C[Load combo models sequence]
+    B -- No --> D[Single model path]
+
+    C --> E[Try model N]
+    E --> F[Resolve provider/model]
+    D --> F
+
+    F --> G[Select account credentials]
+    G --> H{Credentials available?}
+    H -- No --> I[Return provider unavailable]
+    H -- Yes --> J[Execute request]
+
+    J --> K{Success?}
+    K -- Yes --> L[Return response]
+    K -- No --> M{Fallback-eligible error?}
+
+    M -- No --> N[Return error]
+    M -- Yes --> O[Mark account unavailable cooldown]
+    O --> P{Another account for provider?}
+    P -- Yes --> G
+    P -- No --> Q{In combo with next model?}
+    Q -- Yes --> E
+    Q -- No --> R[Return all unavailable]
+```
+
+Fallback-beslutninger er drevet af `open-sse/services/accountFallback.ts` ved hjælp af statuskoder og fejlmeddelelsesheuristik.
+
+## OAuth Onboarding og Token Refresh Lifecycle
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Dashboard UI
+    participant OAuth as /api/oauth/[provider]/[action]
+    participant ProvAuth as Provider Auth Server
+    participant DB as localDb
+    participant Test as /api/providers/[id]/test
+    participant Exec as Provider Executor
+
+    UI->>OAuth: GET authorize or device-code
+    OAuth->>ProvAuth: create auth/device flow
+    ProvAuth-->>OAuth: auth URL or device code payload
+    OAuth-->>UI: flow data
+
+    UI->>OAuth: POST exchange or poll
+    OAuth->>ProvAuth: token exchange/poll
+    ProvAuth-->>OAuth: access/refresh tokens
+    OAuth->>DB: createProviderConnection(oauth data)
+    OAuth-->>UI: success + connection id
+
+    UI->>Test: POST /api/providers/[id]/test
+    Test->>Exec: validate credentials / optional refresh
+    Exec-->>Test: valid or refreshed token info
+    Test->>DB: update status/tokens/errors
+    Test-->>UI: validation result
+```
+
+Opdatering under live-trafik udføres inde i `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
+
+## Cloud Sync Lifecycle (Aktiver / Synkroniser / Deaktiver)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Endpoint Page UI
+    participant Sync as /api/sync/cloud
+    participant DB as localDb
+    participant Cloud as External Cloud Sync
+    participant Claude as ~/.claude/settings.json
+
+    UI->>Sync: POST action=enable
+    Sync->>DB: set cloudEnabled=true
+    Sync->>DB: ensure API key exists
+    Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys)
+    Cloud-->>Sync: sync result
+    Sync->>Cloud: GET /{machineId}/v1/verify
+    Sync-->>UI: enabled + verification status
+
+    UI->>Sync: POST action=sync
+    Sync->>Cloud: POST /sync/{machineId}
+    Cloud-->>Sync: remote data
+    Sync->>DB: update newer local tokens/status
+    Sync-->>UI: synced
+
+    UI->>Sync: POST action=disable
+    Sync->>DB: set cloudEnabled=false
+    Sync->>Cloud: DELETE /sync/{machineId}
+    Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed)
+    Sync-->>UI: disabled
+```
+
+Periodisk synkronisering udløses af `CloudSyncScheduler`, når skyen er aktiveret.
+
+## Datamodel og lagerkort
+
+```mermaid
+erDiagram
+    SETTINGS ||--o{ PROVIDER_CONNECTION : controls
+    PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider
+    PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage
+
+    SETTINGS {
+      boolean cloudEnabled
+      number stickyRoundRobinLimit
+      boolean requireLogin
+      string password_hash
+      string fallbackStrategy
+      json rateLimitDefaults
+      json providerProfiles
+    }
+
+    PROVIDER_CONNECTION {
+      string id
+      string provider
+      string authType
+      string name
+      number priority
+      boolean isActive
+      string apiKey
+      string accessToken
+      string refreshToken
+      string expiresAt
+      string testStatus
+      string lastError
+      string rateLimitedUntil
+      json providerSpecificData
+    }
+
+    PROVIDER_NODE {
+      string id
+      string type
+      string name
+      string prefix
+      string apiType
+      string baseUrl
+    }
+
+    MODEL_ALIAS {
+      string alias
+      string targetModel
+    }
+
+    COMBO {
+      string id
+      string name
+      string[] models
+    }
+
+    API_KEY {
+      string id
+      string name
+      string key
+      string machineId
+    }
+
+    USAGE_ENTRY {
+      string provider
+      string model
+      number prompt_tokens
+      number completion_tokens
+      string connectionId
+      string timestamp
+    }
+
+    CUSTOM_MODEL {
+      string id
+      string name
+      string providerId
+    }
+
+    PROXY_CONFIG {
+      string global
+      json providers
+    }
+
+    IP_FILTER {
+      string mode
+      string[] allowlist
+      string[] blocklist
+    }
+
+    THINKING_BUDGET {
+      string mode
+      number customBudget
+      string effortLevel
+    }
+
+    SYSTEM_PROMPT {
+      boolean enabled
+      string prompt
+      string position
+    }
+```
+
+Fysiske lagerfiler:
+
+- 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/...`
+
+## Implementeringstopologi
+
+```mermaid
+flowchart LR
+    subgraph LocalHost[Developer Host]
+        CLI[CLI Tools]
+        Browser[Dashboard Browser]
+    end
+
+    subgraph ContainerOrProcess[OmniRoute Runtime]
+        Next[Next.js Server\nPORT=20128]
+        Core[SSE Core + Executors]
+        MainDB[(db.json)]
+        UsageDB[(usage.json/log.txt)]
+    end
+
+    subgraph External[External Services]
+        Providers[AI Providers]
+        SyncCloud[Cloud Sync Service]
+    end
+
+    CLI --> Next
+    Browser --> Next
+    Next --> Core
+    Next --> MainDB
+    Core --> MainDB
+    Core --> UsageDB
+    Core --> Providers
+    Next --> SyncCloud
+```
+
+## Modulkortlægning (beslutningskritisk)
+
+### Rute- og API-moduler
+
+- `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/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)
+
+### Routing og udførelseskerne
+
+- `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
+
+### Oversættelsesregister og formatkonvertere
+
+- `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`
+
+### Vedholdenhed
+
+- `src/lib/localDb.ts`: vedvarende konfiguration/tilstand
+- `src/lib/usageDb.ts`: brugshistorik og rullende anmodningslogfiler
+
+## Udbyder Eksekutør Dækning (Strategimønster)
+
+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.
+
+| 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                                |
+
+Alle andre udbydere (inklusive brugerdefinerede kompatible noder) bruger `DefaultExecutor`.
+
+## Udbyderkompatibilitetsmatrix
+
+| 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             | ✅               | ✅          | ❌            | ❌                   |
+
+## Format oversættelsesdækning
+
+Detekterede kildeformater omfatter:
+
+- `openai`
+- `openai-responses`
+- `claude`
+- `gemini`
+
+Målformater omfatter:
+
+- OpenAI chat/svar
+- Claude
+- Gemini/Gemini-CLI/Antigravity kuvert
+- Kiro
+- Markør
+
+Oversættelser bruger **OpenAI som hub-format** - alle konverteringer går gennem OpenAI som mellemliggende:
+
+```
+Source Format → OpenAI (hub) → Target Format
+```
+
+Oversættelser vælges dynamisk baseret på kildens nyttelastform og udbyderens målformat.
+
+Yderligere behandlingslag i oversættelsespipelinen:
+
+- **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`
+
+## Understøttede API-endepunkter
+
+| 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                           |
+
+## 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`.
+
+## Anmod om Logger Pipeline
+
+Anmodningsloggeren (`open-sse/utils/requestLogger.ts`) giver en 7-trins debug-logningspipeline, deaktiveret som standard, aktiveret 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.
+
+## Fejltilstande og modstandsdygtighed
+
+## 1) Konto/udbyder tilgængelighed
+
+- 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
+
+## 2) Tokens udløb
+
+- Forhåndstjek og opdater med genforsøg for udbydere, der kan opdateres
+- 401/403 forsøg igen efter opdateringsforsøg i kernestien
+
+## 3) Strømsikkerhed
+
+- afbrydelsesbevidst streamcontroller
+- translationsstream med end-of-stream flush og `[DONE]` håndtering
+- forbrugsestimeret fallback, når udbyderens brugsmetadata mangler
+
+## 4) Cloud Sync-forringelse
+
+- 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
+
+## 5) Dataintegritet
+
+- DB shape migration/reparation for manglende nøgler
+- korrupte JSON-nulstillingsbeskyttelsesforanstaltninger for localDb og usageDb
+
+## Observerbarhed og operationelle signaler
+
+Kilder til synlighed ved kørsel:
+
+- 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
+
+## Sikkerhedsfølsomme grænser
+
+- 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
+
+## Miljø og Runtime Matrix
+
+Miljøvariabler aktivt brugt af kode:
+
+- 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`
+
+## Kendte arkitektoniske noter
+
+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).
+
+## Tjekliste for operationel verifikation
+
+- Byg fra kilde: `npm run build`
+- Byg Docker-billede: `docker build -t omniroute .`
+- Start service og bekræft:
+- `GET /api/settings`
+- `GET /api/v1/models`
+- CLI-målbasis-URL skal være `http://<host>:20128/v1`, når `PORT=20128`

docs/i18n/da/CODEBASE_DOCUMENTATION.md

@@ -0,0 +1,589 @@
+# 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.
+
+---
+
+## 1. Hvad er omniroute?
+
+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:
+
+> **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.
+
+---
+
+## 2. Arkitekturoversigt
+
+```mermaid
+graph LR
+    subgraph Clients
+        A[Claude CLI]
+        B[Codex]
+        C[Cursor IDE]
+        D[OpenAI-compatible]
+    end
+
+    subgraph omniroute
+        E[Handler Layer]
+        F[Translator Layer]
+        G[Executor Layer]
+        H[Services Layer]
+    end
+
+    subgraph Providers
+        I[Anthropic Claude]
+        J[Google Gemini]
+        K[OpenAI / Codex]
+        L[GitHub Copilot]
+        M[AWS Kiro]
+        N[Antigravity]
+        O[Cursor API]
+    end
+
+    A --> E
+    B --> E
+    C --> E
+    D --> E
+    E --> F
+    F --> G
+    G --> I
+    G --> J
+    G --> K
+    G --> L
+    G --> M
+    G --> N
+    G --> O
+    H -.-> E
+    H -.-> G
+```
+
+### Kerneprincip: Hub-and-Speake-oversættelse
+
+Al formatoversættelse passerer gennem **OpenAI-formatet som 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).
+
+---
+
+## 3. Projektstruktur
+
+```
+omniroute/
+├── open-sse/                  ← Core proxy library (portable, framework-agnostic)
+│   ├── index.js               ← Main entry point, exports everything
+│   ├── config/                ← Configuration & constants
+│   ├── executors/             ← Provider-specific request execution
+│   ├── handlers/              ← Request handling orchestration
+│   ├── services/              ← Business logic (auth, models, fallback, usage)
+│   ├── translator/            ← Format translation engine
+│   │   ├── request/           ← Request translators (8 files)
+│   │   ├── response/          ← Response translators (7 files)
+│   │   └── helpers/           ← Shared translation utilities (6 files)
+│   └── utils/                 ← Utility functions
+├── src/                       ← Application layer (Express/Worker runtime)
+│   ├── app/                   ← Web UI, API routes, middleware
+│   ├── lib/                   ← Database, auth, and shared library code
+│   ├── mitm/                  ← Man-in-the-middle proxy utilities
+│   ├── models/                ← Database models
+│   ├── shared/                ← Shared utilities (wrappers around open-sse)
+│   ├── sse/                   ← SSE endpoint handlers
+│   └── store/                 ← State management
+├── data/                      ← Runtime data (credentials, logs)
+│   └── provider-credentials.json   (external credentials override, gitignored)
+└── tester/                    ← Test utilities
+```
+
+---
+
+## 4. Modul-for-modul-opdeling
+
+### 4.1 Config (`open-sse/config/`)
+
+Den **enkelte kilde til sandhed** for alle udbyderkonfigurationer.
+
+| 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).                                                                                                                                                   |
+
+#### Credential Loading Flow
+
+```mermaid
+flowchart TD
+    A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"]
+    B --> C{"data/provider-credentials.json\nexists?"}
+    C -->|Yes| D["credentialLoader reads JSON"]
+    C -->|No| E["Use hardcoded defaults"]
+    D --> F{"For each provider in JSON"}
+    F --> G{"Provider exists\nin PROVIDERS?"}
+    G -->|No| H["Log warning, skip"]
+    G -->|Yes| I{"Value is object?"}
+    I -->|No| J["Log warning, skip"]
+    I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"]
+    K --> F
+    H --> F
+    J --> F
+    F -->|Done| L["PROVIDERS ready with\nmerged credentials"]
+    E --> L
+```
+
+---
+
+### 4.2 Eksekutører (`open-sse/executors/`)
+
+Eksekutører indkapsler **udbyderspecifik logik** ved hjælp af **Strategy Pattern**. Hver executor tilsidesætter basismetoder efter behov.
+
+```mermaid
+classDiagram
+    class BaseExecutor {
+        +buildUrl(model, stream, options)
+        +buildHeaders(credentials, stream, body)
+        +transformRequest(body, model, stream, credentials)
+        +execute(url, options)
+        +shouldRetry(status, error)
+        +refreshCredentials(credentials, log)
+    }
+
+    class DefaultExecutor {
+        +refreshCredentials()
+    }
+
+    class AntigravityExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +shouldRetry()
+        +refreshCredentials()
+    }
+
+    class CursorExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseResponse()
+        +generateChecksum()
+    }
+
+    class KiroExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseEventStream()
+        +refreshCredentials()
+    }
+
+    BaseExecutor <|-- DefaultExecutor
+    BaseExecutor <|-- AntigravityExecutor
+    BaseExecutor <|-- CursorExecutor
+    BaseExecutor <|-- KiroExecutor
+    BaseExecutor <|-- CodexExecutor
+    BaseExecutor <|-- GeminiCLIExecutor
+    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                                                                  |
+
+---
+
+### 4.3 Håndtere (`open-sse/handlers/`)
+
+**Orkestreringslaget** — koordinerer oversættelse, udførelse, streaming og fejlhåndtering.
+
+| 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.                                    |
+
+#### Anmod om livscyklus (chatCore.ts)
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant chatCore
+    participant Translator
+    participant Executor
+    participant Provider
+
+    Client->>chatCore: Request (any format)
+    chatCore->>chatCore: Detect source format
+    chatCore->>chatCore: Check bypass patterns
+    chatCore->>chatCore: Resolve model & provider
+    chatCore->>Translator: Translate request (source → OpenAI → target)
+    chatCore->>Executor: Get executor for provider
+    Executor->>Executor: Build URL, headers, transform request
+    Executor->>Executor: Refresh credentials if needed
+    Executor->>Provider: HTTP fetch (streaming or non-streaming)
+
+    alt Streaming
+        Provider-->>chatCore: SSE stream
+        chatCore->>chatCore: Pipe through SSE transform stream
+        Note over chatCore: Transform stream translates<br/>each chunk: target → OpenAI → source
+        chatCore-->>Client: Translated SSE stream
+    else Non-streaming
+        Provider-->>chatCore: JSON response
+        chatCore->>Translator: Translate response
+        chatCore-->>Client: Translated JSON
+    end
+
+    alt Error (401, 429, 500...)
+        chatCore->>Executor: Retry with credential refresh
+        chatCore->>chatCore: Account fallback logic
+    end
+```
+
+---
+
+### 4.4 Tjenester (`open-sse/services/`)
+
+Forretningslogik, der understøtter behandlerne og udførerne.
+
+| 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.                                                                                                                                                                                                       |
+
+#### Token Refresh Deduplication
+
+```mermaid
+sequenceDiagram
+    participant R1 as Request 1
+    participant R2 as Request 2
+    participant Cache as refreshPromiseCache
+    participant OAuth as OAuth Provider
+
+    R1->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: No in-flight promise
+    Cache->>OAuth: Start refresh
+    R2->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: Found in-flight promise
+    Cache-->>R2: Return existing promise
+    OAuth-->>Cache: New access token
+    Cache-->>R1: New access token
+    Cache-->>R2: Same access token (shared)
+    Cache->>Cache: Delete cache entry
+```
+
+#### Account Fallback State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active
+    Active --> Error: Request fails (401/429/500)
+    Error --> Cooldown: Apply backoff
+    Cooldown --> Active: Cooldown expires
+    Active --> Active: Request succeeds (reset backoff)
+
+    state Error {
+        [*] --> ClassifyError
+        ClassifyError --> ShouldFallback: Rate limit / Auth / Transient
+        ClassifyError --> NoFallback: 400 Bad Request
+    }
+
+    state Cooldown {
+        [*] --> ExponentialBackoff
+        ExponentialBackoff: Level 0 = 1s
+        ExponentialBackoff: Level 1 = 2s
+        ExponentialBackoff: Level 2 = 4s
+        ExponentialBackoff: Max = 2min
+    }
+```
+
+#### Kombi-modelkæde
+
+```mermaid
+flowchart LR
+    A["Request with\ncombo model"] --> B["Model A"]
+    B -->|"2xx Success"| C["Return response"]
+    B -->|"429/401/500"| D{"Fallback\neligible?"}
+    D -->|Yes| E["Model B"]
+    D -->|No| F["Return error"]
+    E -->|"2xx Success"| C
+    E -->|"429/401/500"| G{"Fallback\neligible?"}
+    G -->|Yes| H["Model C"]
+    G -->|No| F
+    H -->|"2xx Success"| C
+    H -->|"Fail"| I["All failed →\nReturn last status"]
+```
+
+---
+
+### 4.5 Oversætter (`open-sse/translator/`)
+
+**formatoversættelsesmotoren** ved hjælp af et selvregistrerende plugin-system.
+
+#### Arkitektur
+
+```mermaid
+graph TD
+    subgraph "Request Translation"
+        A["Claude → OpenAI"]
+        B["Gemini → OpenAI"]
+        C["Antigravity → OpenAI"]
+        D["OpenAI Responses → OpenAI"]
+        E["OpenAI → Claude"]
+        F["OpenAI → Gemini"]
+        G["OpenAI → Kiro"]
+        H["OpenAI → Cursor"]
+    end
+
+    subgraph "Response Translation"
+        I["Claude → OpenAI"]
+        J["Gemini → OpenAI"]
+        K["Kiro → OpenAI"]
+        L["Cursor → OpenAI"]
+        M["OpenAI → Claude"]
+        N["OpenAI → Antigravity"]
+        O["OpenAI → Responses"]
+    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`.                                                                                                                                                                          |
+
+#### Nøgledesign: Selvregistrerende plugins
+
+```javascript
+// Each translator file calls register() on import:
+import { register } from "../index.js";
+register("claude", "openai", translateClaudeToOpenAI);
+
+// The index.js imports all translator files, triggering registration:
+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.                                            |
+
+#### SSE Streaming Pipeline
+
+```mermaid
+flowchart TD
+    A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"]
+    B --> C["Buffer lines\n(split on newline)"]
+    C --> D["parseSSELine()\n(trim whitespace, parse JSON)"]
+    D --> E{"Mode?"}
+    E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"]
+    E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"]
+    F --> H["hasValuableContent()\nfilter empty chunks"]
+    G --> H
+    H -->|"Has content"| I["extractUsage()\ntrack token counts"]
+    H -->|"Empty"| J["Skip chunk"]
+    I --> K["formatSSE()\nserialize + clean perf_metrics"]
+    K --> L["TextEncoder\n(per-stream instance)"]
+    L --> M["Enqueue to\nclient stream"]
+
+    style A fill:#f9f,stroke:#333
+    style M fill:#9f9,stroke:#333
+```
+
+#### Anmod om loggersessionsstruktur
+
+```
+logs/
+└── claude_gemini_claude-sonnet_20260208_143045/
+    ├── 1_req_client.json      ← Raw client request
+    ├── 2_req_source.json      ← After initial conversion
+    ├── 3_req_openai.json      ← OpenAI intermediate format
+    ├── 4_req_target.json      ← Final target format
+    ├── 5_res_provider.txt     ← Provider SSE chunks (streaming)
+    ├── 5_res_provider.json    ← Provider response (non-streaming)
+    ├── 6_res_openai.txt       ← OpenAI intermediate chunks
+    ├── 7_res_client.txt       ← Client-facing SSE chunks
+    └── 6_error.json           ← Error details (if any)
+```
+
+---
+
+### 4.7 applikationslag (`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                                       |
+
+#### Bemærkelsesværdige API-ruter
+
+| 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                                                                             |
+
+---
+
+## 5. Nøgledesignmønstre
+
+### 5.1 Hub-and-Speake-oversættelse
+
+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.
+
+### 5.2 Eksekutørstrategimønster
+
+Hver udbyder har en dedikeret eksekveringsklasse, der arver fra `BaseExecutor`. Fabrikken i `executors/index.ts` vælger den rigtige ved kørsel.
+
+### 5.3 Selvregistrerende 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.
+
+### 5.4 Account Fallback med eksponentiel 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).
+
+### 5.5 Combo modelkæder
+
+En "combo" grupperer flere `provider/model` strenge. Hvis den første fejler, går du automatisk tilbage til den næste.
+
+### 5.6 Stateful streaming-oversættelse
+
+Svaroversættelse opretholder tilstand på tværs af SSE-chunks (tænkebloksporing, akkumulering af værktøjsopkald, indholdsblokindeksering) via `initState()`-mekanismen.
+
+### 5.7 Sikkerhedsbuffer for brug
+
+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.
+
+---
+
+## 6. Understøttede formater
+
+| 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`           |
+
+---
+
+## 7. Understøttede udbydere
+
+| 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  |
+
+---
+
+## 8. Oversigt over dataflow
+
+### Streaminganmodning
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor\nbuildUrl + buildHeaders"]
+    D --> E["fetch(providerURL)"]
+    E --> F["createSSEStream()\nTRANSLATE mode"]
+    F --> G["parseSSELine()"]
+    G --> H["translateResponse()\ntarget → OpenAI → source"]
+    H --> I["extractUsage()\n+ addBuffer"]
+    I --> J["formatSSE()"]
+    J --> K["Client receives\ntranslated SSE"]
+    K --> L["logUsage()\nsaveRequestUsage()"]
+```
+
+### Ikke-streamende anmodning
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor.execute()"]
+    D --> E["translateResponse()\ntarget → OpenAI → source"]
+    E --> F["Return JSON\nresponse"]
+```
+
+### Bypass Flow (Claude CLI)
+
+```mermaid
+flowchart LR
+    A["Claude CLI request"] --> B{"Match bypass\npattern?"}
+    B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"]
+    B -->|"No match"| D["Normal flow"]
+    C --> E["Translate to\nsource format"]
+    E --> F["Return without\ncalling provider"]
+```

docs/i18n/da/FEATURES.md

@@ -0,0 +1,77 @@
+# 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.
+
+---
+
+## 🔌 Udbydere
+
+Administrer AI-udbyderforbindelser: OAuth-udbydere (Claude Code, Codex, Gemini CLI), API-nøgleudbydere (Groq, DeepSeek, OpenRouter) og gratis udbydere (iFlow, Qwen, Kiro).
+
+![Providers Dashboard](screenshots/01-providers.png)
+
+---
+
+## 🎨 Kombinationer
+
+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.
+
+![Combos Dashboard](screenshots/02-combos.png)
+
+---
+
+## 📊 Analyse
+
+Omfattende brugsanalyse med token-forbrug, omkostningsestimater, aktivitetsvarmekort, ugentlige distributionsdiagrammer og opdelinger pr. udbyder.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
+
+---
+
+## 🏥 Systemsundhed
+
+Overvågning i realtid: oppetid, hukommelse, version, latency percentiler (p50/p95/p99), cache-statistik og udbyderens afbrydertilstande.
+
+![Health Dashboard](screenshots/04-health.png)
+
+---
+
+## 🔧 Oversætterlegeplads
+
+Fire tilstande til fejlfinding af API-oversættelser: **Playground** (formatkonverter), **Chat Tester** (live-anmodninger), **Test Bench** (batchtest) og **Live Monitor** (streaming i realtid).
+
+![Translator Playground](screenshots/05-translator.png)
+
+---
+
+## ⚙️ Indstillinger
+
+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.
+
+![Settings Dashboard](screenshots/06-settings.png)
+
+---
+
+## 🔧 CLI-værktøjer
+
+Et-klik-konfiguration til AI-kodningsværktøjer: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code og Antigravity.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+
+---
+
+## 📝 Anmodningslogs
+
+Logning af anmodninger i realtid med filtrering efter udbyder, model, konto og API-nøgle. Viser statuskoder, tokenbrug, latenstid og svardetaljer.
+
+![Usage Logs](screenshots/08-usage.png)
+
+---
+
+## 🌐 API-endepunkt
+
+Dit forenede API-slutpunkt med kapacitetsopdeling: Chatfuldførelser, indlejringer, billedgenerering, omrangering, lydtransskription og registrerede API-nøgler.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)

docs/i18n/da/TROUBLESHOOTING.md

@@ -0,0 +1,219 @@
+# 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.
+
+---
+
+## Hurtige rettelser
+
+| 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)         |
+
+---
+
+## Udbyderproblemer
+
+### "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
+
+---
+
+## Skyproblemer
+
+### Cloud Sync-fejl
+
+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
+
+### Cloud `stream=false` Returnerer 500
+
+**Symptom:** `Unexpected token 'd'...` på cloud-endepunkt til ikke-streamingopkald.
+
+**Årsag:** Upstream returnerer SSE-nyttelast, mens klienten forventer JSON.
+
+**Løsning:** Brug `stream=true` til direkte skyopkald. Lokal kørselstid inkluderer SSE→JSON fallback.
+
+### Cloud siger tilsluttet, men "Ugyldig API-nøgle"
+
+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
+
+---
+
+## Docker-problemer
+
+### CLI-værktøj viser ikke installeret
+
+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
+
+### Hurtig runtime-validering
+
+```bash
+curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+```
+
+---
+
+## Omkostningsproblemer
+
+### Høje omkostninger
+
+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
+
+---
+
+## Fejlretning
+
+### Aktiver anmodningslogfiler
+
+Indstil `ENABLE_REQUEST_LOGS=true` i din `.env` fil. Logfiler vises under biblioteket `logs/`.
+
+### Tjek udbyderens helbred
+
+```bash
+# Health dashboard
+http://localhost:20128/dashboard/health
+
+# API health check
+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`)
+
+---
+
+## Circuit Breaker Problemer
+
+### Udbyder sidder fast i ÅBEN tilstand
+
+Når en udbyders afbryder er ÅBEN, blokeres anmodninger, indtil nedkølingen udløber.
+
+**Ret:**
+
+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
+
+### Udbyderen bliver ved med at udløse strømafbryderen
+
+Hvis en udbyder gentagne gange går i ÅBEN tilstand:
+
+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
+
+---
+
+## Problemer med lydtransskription
+
+### "Ikke-understøttet model" fejl
+
+- 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**
+
+### Transskription returnerer tom eller mislykkes
+
+- 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
+
+---
+
+## Oversætter-fejlretning
+
+Brug **Dashboard → Oversætter** til at fejlfinde problemer med formatoversættelse:
+
+| 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                                      |
+
+### Almindelige formatproblemer
+
+- **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`
+
+---
+
+## Resiliensindstillinger
+
+### Automatisk hastighedsgrænse udløses ikke
+
+- 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
+
+### Tuning eksponentiel backoff
+
+Udbyderprofiler understøtter disse indstillinger:
+
+- **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)
+
+### Anti-tordenbesætning
+
+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.
+
+---
+
+## Stadig fast?
+
+- **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

docs/i18n/da/USER_GUIDE.md

@@ -0,0 +1,698 @@
+# 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.
+
+---
+
+## Indholdsfortegnelse
+
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
+
+## 💰 Prissætning på et øjeblik
+
+| 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              |
+
+**💡 Pro-tip:** Start med Gemini CLI (180K gratis/måned) + iFlow (ubegrænset gratis) combo = $0 omkostninger!
+
+---
+
+## 🎯 Use Cases
+
+### Case 1: "Jeg har Claude Pro-abonnement"
+
+**Problem:** Kvoten udløber ubrugt, satsgrænser under tung kodning
+
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6        (use subscription fully)
+  2. glm/glm-4.7               (cheap backup when quota out)
+  3. if/kimi-k2-thinking       (free emergency fallback)
+
+Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
+vs. $20 + hitting limits = frustration
+```
+
+### Case 2: "Jeg vil have nul omkostninger"
+
+**Problem:** Har ikke råd til abonnementer, har brug for pålidelig AI-kodning
+
+```
+Combo: "free-forever"
+  1. gc/gemini-3-flash         (180K free/month)
+  2. if/kimi-k2-thinking       (unlimited free)
+  3. qw/qwen3-coder-plus       (unlimited free)
+
+Monthly cost: $0
+Quality: Production-ready models
+```
+
+### Case 3: "Jeg har brug for 24/7 kodning, ingen afbrydelser"
+
+**Problem:** Deadlines, har ikke råd til nedetid
+
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-6        (best quality)
+  2. cx/gpt-5.2-codex          (second subscription)
+  3. glm/glm-4.7               (cheap, resets daily)
+  4. minimax/MiniMax-M2.1      (cheapest, 5h reset)
+  5. if/kimi-k2-thinking       (free unlimited)
+
+Result: 5 layers of fallback = zero downtime
+Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
+```
+
+### Case 4: "Jeg vil have GRATIS AI i OpenClaw"
+
+**Problem:** Har brug for AI-assistent i beskedapps, helt gratis
+
+```
+Combo: "openclaw-free"
+  1. if/glm-4.7                (unlimited free)
+  2. if/minimax-m2.1           (unlimited free)
+  3. if/kimi-k2-thinking       (unlimited free)
+
+Monthly cost: $0
+Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+```
+
+---
+
+## 📖 Udbyderopsætning
+
+### 🔐 Abonnementsudbydere
+
+#### Claude Code (Pro/Max)
+
+```bash
+Dashboard → Providers → Connect Claude Code
+→ OAuth login → Auto token refresh
+→ 5-hour + weekly quota tracking
+
+Models:
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**Prof tip:** Brug Opus til komplekse opgaver, Sonnet for hurtighed. OmniRoute sporer kvote pr. model!
+
+#### OpenAI Codex (Plus/Pro)
+
+```bash
+Dashboard → Providers → Connect Codex
+→ OAuth login (port 1455)
+→ 5-hour + weekly reset
+
+Models:
+  cx/gpt-5.2-codex
+  cx/gpt-5.1-codex-max
+```
+
+#### Gemini CLI (GRATIS 180K/måned!)
+
+```bash
+Dashboard → Providers → Connect Gemini CLI
+→ Google OAuth
+→ 180K completions/month + 1K/day
+
+Models:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**Bedste værdi:** Kæmpe gratis niveau! Brug dette før betalte niveauer.
+
+#### GitHub Copilot
+
+```bash
+Dashboard → Providers → Connect GitHub
+→ OAuth via GitHub
+→ Monthly reset (1st of month)
+
+Models:
+  gh/gpt-5
+  gh/claude-4.5-sonnet
+  gh/gemini-3-pro
+```
+
+### 💰 Billige udbydere
+
+#### GLM-4.7 (Daglig nulstilling, $0,6/1 mio.)
+
+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`
+
+**Brug:** `glm/glm-4.7` — **Prof tip:** Kodningsplan tilbyder 3× kvote til 1/7 pris! Nulstil dagligt 10:00.
+
+#### MiniMax M2.1 (5 timers nulstilling, $0,20/1 mio.)
+
+1. Tilmeld dig: [MiniMax](https://www.minimax.io/)
+2. Hent API-nøgle → Dashboard → Tilføj API-nøgle
+
+**Brug:** `minimax/MiniMax-M2.1` — **Prof tip:** Billigste mulighed for lang sammenhæng (1M tokens)!
+
+#### Kimi K2 ($9/måned lejlighed)
+
+1. Abonner: [Moonshot AI](https://platform.moonshot.ai/)
+2. Hent API-nøgle → Dashboard → Tilføj API-nøgle
+
+**Brug:** `kimi/kimi-latest` — **Prof tip:** Fast $9/måned for 10M tokens = $0,90/1M effektive omkostninger!
+
+### 🆓 GRATIS udbydere
+
+#### iFlow (8 GRATIS modeller)
+
+```bash
+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)
+
+```bash
+Dashboard → Connect Qwen → Device code auth → Unlimited usage
+
+Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
+```
+
+#### Kiro (Claude GRATIS)
+
+```bash
+Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
+
+Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
+```
+
+---
+
+## 🎨 Kombinationer
+
+### Eksempel 1: Maksimer abonnement → Billig backup
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-6 (Subscription primary)
+  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
+  3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
+
+Use in CLI: premium-coding
+```
+
+### Eksempel 2: Kun gratis (nul omkostninger)
+
+```
+Name: free-combo
+Models:
+  1. gc/gemini-3-flash-preview (180K free/month)
+  2. if/kimi-k2-thinking (unlimited)
+  3. qw/qwen3-coder-plus (unlimited)
+
+Cost: $0 forever!
+```
+
+---
+
+## 🔧 CLI-integration
+
+### Markør IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from omniroute dashboard]
+  Model: cc/claude-opus-4-6
+```
+
+### Claude Code
+
+Rediger `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-omniroute-api-key"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-omniroute-api-key"
+codex "your prompt"
+```
+
+### OpenClaw
+
+Rediger `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": { "primary": "omniroute/if/glm-4.7" }
+    }
+  },
+  "models": {
+    "providers": {
+      "omniroute": {
+        "baseUrl": "http://localhost:20128/v1",
+        "apiKey": "your-omniroute-api-key",
+        "api": "openai-completions",
+        "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+      }
+    }
+  }
+}
+```
+
+**Eller brug Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Fortsæt / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-6
+```
+
+---
+
+## 🚀 Implementering
+
+### VPS-implementering
+
+```bash
+git clone https://github.com/diegosouzapw/OmniRoute.git
+cd OmniRoute && npm install && npm run build
+
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+export DATA_DIR="/var/lib/omniroute"
+export PORT="20128"
+export HOSTNAME="0.0.0.0"
+export NODE_ENV="production"
+export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
+export API_KEY_SECRET="endpoint-proxy-api-key-secret"
+
+npm run start
+# Or: pm2 start npm --name omniroute -- start
+```
+
+### Docker
+
+```bash
+# Build image (default = runner-cli with codex/claude/droid preinstalled)
+docker build -t omniroute:cli .
+
+# Portable mode (recommended)
+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.
+
+### Miljøvariabler
+
+| 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) |
+
+For den fulde reference til miljøvariablen, se [README](../README.md).
+
+---
+
+## 📊 Tilgængelige modeller
+
+<details>
+<summary><b>Se alle tilgængelige modeller</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`
+
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
+
+**GLM (`glm/`)** — 0,6 USD/1 mio.: `glm/glm-4.7`
+
+**MiniMax (`minimax/`)** — $0,2/1 mio.: `minimax/MiniMax-M2.1`
+
+**iFlow (`if/`)** — GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+
+**Qwen (`qw/`)** — GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+
+**Kiro (`kr/`)** — GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
+
+**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`
+
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
+
+**Forvirring (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
+
+**Kohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
+
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+</details>
+
+---
+
+## 🧩 Avancerede funktioner
+
+### Brugerdefinerede modeller
+
+Tilføj ethvert model-id til enhver udbyder uden at vente på en appopdatering:
+
+```bash
+# Via API
+curl -X POST http://localhost:20128/api/provider-models \
+  -H "Content-Type: application/json" \
+  -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}'
+
+# List: curl http://localhost:20128/api/provider-models?provider=openai
+# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
+```
+
+Eller brug Dashboard: **Udbydere → [Udbyder] → Brugerdefinerede modeller**.
+
+### Dedikerede udbyderruter
+
+Rut anmodninger direkte til en specifik udbyder med modelvalidering:
+
+```bash
+POST http://localhost:20128/v1/providers/openai/chat/completions
+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`.
+
+### Konfiguration af netværksproxy
+
+```bash
+# Set global proxy
+curl -X PUT http://localhost:20128/api/settings/proxy \
+  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
+
+# Per-provider proxy
+curl -X PUT http://localhost:20128/api/settings/proxy \
+  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
+
+# Test proxy
+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ø.
+
+### Model Catalog API
+
+```bash
+curl http://localhost:20128/api/models/catalog
+```
+
+Returnerer modeller grupperet efter udbyder med typer (`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
+
+### LLM Gateway Intelligence (fase 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
+
+---
+
+### Oversætter Legeplads
+
+Adgang via **Dashboard → Oversætter**. Fejlfind og visualiser, hvordan OmniRoute oversætter API-anmodninger mellem udbydere.
+
+| 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                          |
+
+**Brugstilfælde:**
+
+- 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
+
+---
+
+### Routingstrategier
+
+Konfigurer via **Dashboard → Indstillinger → 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              |
+
+#### Wildcard-modelaliaser
+
+Opret jokertegnmønstre for at omdanne modelnavne:
+
+```
+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).
+
+#### Fallback-kæder
+
+Definer globale reservekæder, der gælder på tværs af alle anmodninger:
+
+```
+Chain: production-fallback
+  1. cc/claude-opus-4-6
+  2. gh/gpt-5.1-codex
+  3. glm/glm-4.7
+```
+
+---
+
+### Modstandsdygtighed og strømafbrydere
+
+Konfigurer via **Dashboard → Indstillinger → Resiliens**.
+
+OmniRoute implementerer modstandsdygtighed på udbyderniveau med fire komponenter:
+
+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
+
+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.
+
+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
+
+4. **Politik og låste identifikatorer** — Viser strømafbryderstatus og låste identifikatorer med tvangsoplåsningsfunktion.
+
+5. **Automatisk registrering af hastighedsgrænse** — Overvåger `429` og `Retry-After` overskrifter for proaktivt at undgå at ramme udbyderens satsgrænser.
+
+**Prof tip:** Brug knappen **Nulstil alle** til at rydde alle strømafbrydere og nedkøling, når en udbyder kommer sig efter en fejl.
+
+---
+
+### Databaseeksport/import
+
+Administrer databasesikkerhedskopier i **Dashboard → Indstillinger → System og lager**.
+
+| 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                                                   |
+
+```bash
+# API: Export database
+curl -o backup.sqlite http://localhost:20128/api/db-backups/export
+
+# API: Export all (full archive)
+curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
+
+# API: Import database
+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).
+
+**Brugstilfælde:**
+
+- Migrer OmniRoute mellem maskiner
+- Opret eksterne sikkerhedskopier til katastrofegendannelse
+- Del konfigurationer mellem teammedlemmer (eksporter alle → del arkiv)
+
+---
+
+### Indstillinger Dashboard
+
+Indstillingssiden er organiseret i 5 faner for nem 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)                                                                  |
+
+---
+
+### Omkostninger og budgetstyring
+
+Adgang via **Dashboard → Omkostninger**.
+
+| 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                     |
+
+```bash
+# API: Set a budget
+curl -X POST http://localhost:20128/api/usage/budget \
+  -H "Content-Type: application/json" \
+  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
+
+# API: Get current budget status
+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.
+
+---
+
+### Lydtransskription
+
+OmniRoute understøtter lydtransskription via det OpenAI-kompatible slutpunkt:
+
+```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+
+# Example with curl
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+  -H "Authorization: Bearer your-api-key" \
+  -F "file=@audio.mp3" \
+  -F "model=deepgram/nova-3"
+```
+
+Tilgængelige udbydere: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
+
+Understøttede lydformater: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+
+---
+
+### Kombinationsbalanceringsstrategier
+
+Konfigurer balancering pr. kombination i **Dashboard → Combos → Opret/Rediger → Strategi**.
+
+| 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)                 |
+
+Globale kombinationsstandarder kan indstilles i **Dashboard → Indstillinger → Routing → Combo-standarder**.
+
+---
+
+### Sundhedsdashboard
+
+Adgang via **Dashboard → Health**. Oversigt over systemets tilstand i realtid med 6 kort:
+
+| 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               |
+
+**Prof tip:** Sundhedssiden opdateres automatisk hvert 10. sekund. Brug afbryderkortet til at identificere, hvilke udbydere der oplever problemer.

docs/i18n/de/API_REFERENCE.md

@@ -0,0 +1,442 @@
+# 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.
+
+---
+
+## Inhaltsverzeichnis
+
+- [Chat Completions](#chat-completions)
+- [Embeddings](#embeddings)
+- [Image Generation](#image-generation)
+- [List Models](#list-models)
+- [Compatibility Endpoints](#compatibility-endpoints)
+- [Semantic Cache](#semantic-cache)
+- [Dashboard & Management](#dashboard--management)
+- [Request Processing](#request-processing)
+- [Authentication](#authentication)
+
+---
+
+## Chat-Abschlüsse
+
+```bash
+POST /v1/chat/completions
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "cc/claude-opus-4-6",
+  "messages": [
+    {"role": "user", "content": "Write a function to..."}
+  ],
+  "stream": true
+}
+```
+
+### Benutzerdefinierte Header
+
+| 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    |
+
+---
+
+## Einbettungen
+
+```bash
+POST /v1/embeddings
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "nebius/Qwen/Qwen3-Embedding-8B",
+  "input": "The food was delicious"
+}
+```
+
+Verfügbare Anbieter: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+
+```bash
+# List all embedding models
+GET /v1/embeddings
+```
+
+---
+
+## Bildgenerierung
+
+```bash
+POST /v1/images/generations
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "openai/dall-e-3",
+  "prompt": "A beautiful sunset over mountains",
+  "size": "1024x1024"
+}
+```
+
+Verfügbare Anbieter: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+
+```bash
+# List all image models
+GET /v1/images/generations
+```
+
+---
+
+## Modelle auflisten
+
+```bash
+GET /v1/models
+Authorization: Bearer your-api-key
+
+→ Returns all chat, embedding, and image models + combos in OpenAI format
+```
+
+---
+
+## Kompatibilitätsendpunkte
+
+| 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                      |
+
+### Dedizierte Anbieterrouten
+
+```bash
+POST /v1/providers/{provider}/chat/completions
+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.
+
+---
+
+## Semantischer Cache
+
+```bash
+# Get cache stats
+GET /api/cache
+
+# Clear all caches
+DELETE /api/cache
+```
+
+Antwortbeispiel:
+
+```json
+{
+  "semanticCache": {
+    "memorySize": 42,
+    "memoryMaxSize": 500,
+    "dbSize": 128,
+    "hitRate": 0.65
+  },
+  "idempotency": {
+    "activeKeys": 3,
+    "windowMs": 5000
+  }
+}
+```
+
+---
+
+## Dashboard und Verwaltung
+
+### Authentifizierung
+
+| Endpunkt                      | Methode | Beschreibung                      |
+| ----------------------------- | ------- | --------------------------------- |
+| `/api/auth/login`             | POST    | Anmelden                          |
+| `/api/auth/logout`            | POST    | Abmelden                          |
+| `/api/settings/require-login` | GET/PUT | Anmeldung erforderlich umschalten |
+
+### Anbieterverwaltung
+
+| 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        |
+
+### OAuth-Flows
+
+| Endpunkt                         | Methode      | Beschreibung               |
+| -------------------------------- | ------------ | -------------------------- |
+| `/api/oauth/[provider]/[action]` | Verschiedene | Anbieterspezifisches OAuth |
+
+### Routing & Konfig
+
+| 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                     |
+
+### Nutzung und Analyse
+
+| 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           |
+
+### Einstellungen
+
+| 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       |
+
+### Überwachung
+
+| 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 |
+
+### Sichern und Exportieren/Importieren
+
+| 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          |
+
+### Cloud-Synchronisierung
+
+| Endpunkt               | Methode      | Beschreibung                    |
+| ---------------------- | ------------ | ------------------------------- |
+| `/api/sync/cloud`      | Verschiedene | Cloud-Synchronisierungsvorgänge |
+| `/api/sync/initialize` | POST         | Synchronisierung initialisieren |
+| `/api/cloud/*`         | Verschiedene | Cloud-Management                |
+
+### 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 |
+
+Zu den CLI-Antworten gehören: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
+
+### Belastbarkeit und Ratenbeschränkungen
+
+| 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 |
+
+### Bewertungen
+
+| Endpunkt     | Methode  | Beschreibung                                         |
+| ------------ | -------- | ---------------------------------------------------- |
+| `/api/evals` | GET/POST | Evaluierungssuiten auflisten / Evaluierung ausführen |
+
+### Richtlinien
+
+| Endpunkt        | Methode         | Beschreibung                  |
+| --------------- | --------------- | ----------------------------- |
+| `/api/policies` | GET/POST/DELETE | Routing-Richtlinien verwalten |
+
+### Compliance
+
+| Endpunkt                    | Methode | Beschreibung                           |
+| --------------------------- | ------- | -------------------------------------- |
+| `/api/compliance/audit-log` | GET     | Compliance-Audit-Protokoll (letztes N) |
+
+### v1beta (Gemini-kompatibel)
+
+| Endpunkt                   | Methode | Beschreibung                       |
+| -------------------------- | ------- | ---------------------------------- |
+| `/v1beta/models`           | GET     | Modelle im Gemini-Format auflisten |
+| `/v1beta/models/{...path}` | POST    | Gemini `generateContent` Endpunkt  |
+
+Diese Endpunkte spiegeln das API-Format von Gemini für Kunden wider, die native Gemini SDK-Kompatibilität erwarten.
+
+### Interne/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                             |
+
+> **Hinweis:** Diese Endpunkte werden intern vom System oder für die Ollama-Client-Kompatibilität verwendet. Sie werden normalerweise nicht von Endbenutzern aufgerufen.
+
+---
+
+## Audiotranskription
+
+```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+```
+
+Transkribieren Sie Audiodateien mit Deepgram oder AssemblyAI.
+
+**Anfrage:**
+
+```bash
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+  -H "Authorization: Bearer your-api-key" \
+  -F "file=@recording.mp3" \
+  -F "model=deepgram/nova-3"
+```
+
+**Antwort:**
+
+```json
+{
+  "text": "Hello, this is the transcribed audio content.",
+  "task": "transcribe",
+  "language": "en",
+  "duration": 12.5
+}
+```
+
+**Unterstützte Anbieter:** `deepgram/nova-3`, `assemblyai/best`.
+
+**Unterstützte Formate:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+
+---
+
+## Ollama-Kompatibilität
+
+Für Kunden, die das API-Format von Ollama verwenden:
+
+```bash
+# Chat endpoint (Ollama format)
+POST /v1/api/chat
+
+# Model listing (Ollama format)
+GET /api/tags
+```
+
+Anfragen werden automatisch zwischen Ollama und internen Formaten übersetzt.
+
+---
+
+## Telemetrie
+
+```bash
+# Get latency telemetry summary (p50/p95/p99 per provider)
+GET /api/telemetry/summary
+```
+
+**Antwort:**
+
+```json
+{
+  "providers": {
+    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
+    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
+  }
+}
+```
+
+---
+
+## Budget
+
+```bash
+# Get budget status for all API keys
+GET /api/usage/budget
+
+# Set or update a budget
+POST /api/usage/budget
+Content-Type: application/json
+
+{
+  "keyId": "key-123",
+  "limit": 50.00,
+  "period": "monthly"
+}
+```
+
+---
+
+## Modellverfügbarkeit
+
+```bash
+# Get real-time model availability across all providers
+GET /api/models/availability
+
+# Check availability for a specific model
+POST /api/models/availability
+Content-Type: application/json
+
+{
+  "model": "claude-sonnet-4-5-20250929"
+}
+```
+
+---
+
+## Bearbeitung der Anfrage
+
+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
+
+Vollständige Architekturreferenz: [link](ARCHITECTURE.md)
+
+---
+
+## Authentifizierung
+
+– 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`

docs/i18n/de/ARCHITECTURE.md

@@ -0,0 +1,783 @@
+# OmniRoute-Architektur
+
+🌐 **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_
+
+## Zusammenfassung
+
+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.
+
+Kernkompetenzen:
+
+- 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/`)
+
+Primäres Laufzeitmodell:
+
+– 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
+
+## Umfang und Grenzen
+
+### Im Geltungsbereich
+
+- 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
+
+### Außerhalb des Gültigkeitsbereichs
+
+- 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.)
+
+## Systemkontext auf hoher Ebene
+
+```mermaid
+flowchart LR
+    subgraph Clients[Developer Clients]
+        C1[Claude Code]
+        C2[Codex CLI]
+        C3[OpenClaw / Droid / Cline / Continue / Roo]
+        C4[Custom OpenAI-compatible clients]
+        BROWSER[Browser Dashboard]
+    end
+
+    subgraph Router[OmniRoute Local Process]
+        API[V1 Compatibility API\n/v1/*]
+        DASH[Dashboard + Management API\n/api/*]
+        CORE[SSE + Translation Core\nopen-sse + src/sse]
+        DB[(db.json)]
+        UDB[(usage.json + log.txt)]
+    end
+
+    subgraph Upstreams[Upstream Providers]
+        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity]
+        P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
+        P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
+    end
+
+    subgraph Cloud[Optional Cloud Sync]
+        CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL]
+    end
+
+    C1 --> API
+    C2 --> API
+    C3 --> API
+    C4 --> API
+    BROWSER --> DASH
+
+    API --> CORE
+    DASH --> DB
+    CORE --> DB
+    CORE --> UDB
+
+    CORE --> P1
+    CORE --> P2
+    CORE --> P3
+
+    DASH --> CLOUD
+```
+
+## Kernlaufzeitkomponenten
+
+## 1) API und Routing-Ebene (Next.js App Routes)
+
+Hauptverzeichnisse:
+
+- `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
+
+Wichtige Kompatibilitätsrouten:
+
+- `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/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/v1beta/models/route.ts`
+- `src/app/api/v1beta/models/[...path]/route.ts`
+
+Verwaltungsdomänen:
+
+- 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)
+- 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)
+- 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)
+
+## 2) SSE + Übersetzungskern
+
+Hauptflussmodule:
+
+- 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`
+
+Dienste (Geschäftslogik):
+
+- 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`
+
+Module der Domänenschicht:
+
+- 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
+
+OAuth-Provider-Module (12 einzelne Dateien unter `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
+
+## 3) Persistenzschicht
+
+Primärer Zustands-DB:
+
+- `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**
+
+Nutzungs-DB:
+
+- `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`
+
+Domain State DB (SQLite):
+
+– `src/lib/db/domainState.ts` – CRUD-Operationen für den Domänenstatus
+
+- 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) Authentifizierung + Sicherheitsoberflächen
+
+- 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-Synchronisierung
+
+- 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`)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as CLI/SDK Client
+    participant Route as /api/v1/chat/completions
+    participant Chat as src/sse/handlers/chat
+    participant Core as open-sse/handlers/chatCore
+    participant Model as Model Resolver
+    participant Auth as Credential Selector
+    participant Exec as Provider Executor
+    participant Prov as Upstream Provider
+    participant Stream as Stream Translator
+    participant Usage as usageDb
+
+    Client->>Route: POST /v1/chat/completions
+    Route->>Chat: handleChat(request)
+    Chat->>Model: parse/resolve model or combo
+
+    alt Combo model
+        Chat->>Chat: iterate combo models (handleComboChat)
+    end
+
+    Chat->>Auth: getProviderCredentials(provider)
+    Auth-->>Chat: active account + tokens/api key
+
+    Chat->>Core: handleChatCore(body, modelInfo, credentials)
+    Core->>Core: detect source format
+    Core->>Core: translate request to target format
+    Core->>Exec: execute(provider, transformedBody)
+    Exec->>Prov: upstream API call
+    Prov-->>Exec: SSE/JSON response
+    Exec-->>Core: response + metadata
+
+    alt 401/403
+        Core->>Exec: refreshCredentials()
+        Exec-->>Core: updated tokens
+        Core->>Exec: retry request
+    end
+
+    Core->>Stream: translate/normalize stream to client format
+    Stream-->>Client: SSE chunks / JSON response
+
+    Stream->>Usage: extract usage + persist history/log
+```
+
+## Combo + Konto-Fallback-Flow
+
+```mermaid
+flowchart TD
+    A[Incoming model string] --> B{Is combo name?}
+    B -- Yes --> C[Load combo models sequence]
+    B -- No --> D[Single model path]
+
+    C --> E[Try model N]
+    E --> F[Resolve provider/model]
+    D --> F
+
+    F --> G[Select account credentials]
+    G --> H{Credentials available?}
+    H -- No --> I[Return provider unavailable]
+    H -- Yes --> J[Execute request]
+
+    J --> K{Success?}
+    K -- Yes --> L[Return response]
+    K -- No --> M{Fallback-eligible error?}
+
+    M -- No --> N[Return error]
+    M -- Yes --> O[Mark account unavailable cooldown]
+    O --> P{Another account for provider?}
+    P -- Yes --> G
+    P -- No --> Q{In combo with next model?}
+    Q -- Yes --> E
+    Q -- No --> R[Return all unavailable]
+```
+
+Fallback-Entscheidungen werden von `open-sse/services/accountFallback.ts` mithilfe von Statuscodes und Fehlermeldungsheuristiken gesteuert.
+
+## OAuth-Onboarding und Token-Aktualisierungslebenszyklus
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Dashboard UI
+    participant OAuth as /api/oauth/[provider]/[action]
+    participant ProvAuth as Provider Auth Server
+    participant DB as localDb
+    participant Test as /api/providers/[id]/test
+    participant Exec as Provider Executor
+
+    UI->>OAuth: GET authorize or device-code
+    OAuth->>ProvAuth: create auth/device flow
+    ProvAuth-->>OAuth: auth URL or device code payload
+    OAuth-->>UI: flow data
+
+    UI->>OAuth: POST exchange or poll
+    OAuth->>ProvAuth: token exchange/poll
+    ProvAuth-->>OAuth: access/refresh tokens
+    OAuth->>DB: createProviderConnection(oauth data)
+    OAuth-->>UI: success + connection id
+
+    UI->>Test: POST /api/providers/[id]/test
+    Test->>Exec: validate credentials / optional refresh
+    Exec-->>Test: valid or refreshed token info
+    Test->>DB: update status/tokens/errors
+    Test-->>UI: validation result
+```
+
+Die Aktualisierung während des Live-Verkehrs wird in `open-sse/handlers/chatCore.ts` über den Executor `refreshCredentials()` ausgeführt.
+
+## Cloud-Sync-Lebenszyklus (Aktivieren/Synchronisieren/Deaktivieren)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Endpoint Page UI
+    participant Sync as /api/sync/cloud
+    participant DB as localDb
+    participant Cloud as External Cloud Sync
+    participant Claude as ~/.claude/settings.json
+
+    UI->>Sync: POST action=enable
+    Sync->>DB: set cloudEnabled=true
+    Sync->>DB: ensure API key exists
+    Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys)
+    Cloud-->>Sync: sync result
+    Sync->>Cloud: GET /{machineId}/v1/verify
+    Sync-->>UI: enabled + verification status
+
+    UI->>Sync: POST action=sync
+    Sync->>Cloud: POST /sync/{machineId}
+    Cloud-->>Sync: remote data
+    Sync->>DB: update newer local tokens/status
+    Sync-->>UI: synced
+
+    UI->>Sync: POST action=disable
+    Sync->>DB: set cloudEnabled=false
+    Sync->>Cloud: DELETE /sync/{machineId}
+    Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed)
+    Sync-->>UI: disabled
+```
+
+Die regelmäßige Synchronisierung wird durch `CloudSyncScheduler` ausgelöst, wenn die Cloud aktiviert ist.
+
+## Datenmodell und Speicherzuordnung
+
+```mermaid
+erDiagram
+    SETTINGS ||--o{ PROVIDER_CONNECTION : controls
+    PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider
+    PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage
+
+    SETTINGS {
+      boolean cloudEnabled
+      number stickyRoundRobinLimit
+      boolean requireLogin
+      string password_hash
+      string fallbackStrategy
+      json rateLimitDefaults
+      json providerProfiles
+    }
+
+    PROVIDER_CONNECTION {
+      string id
+      string provider
+      string authType
+      string name
+      number priority
+      boolean isActive
+      string apiKey
+      string accessToken
+      string refreshToken
+      string expiresAt
+      string testStatus
+      string lastError
+      string rateLimitedUntil
+      json providerSpecificData
+    }
+
+    PROVIDER_NODE {
+      string id
+      string type
+      string name
+      string prefix
+      string apiType
+      string baseUrl
+    }
+
+    MODEL_ALIAS {
+      string alias
+      string targetModel
+    }
+
+    COMBO {
+      string id
+      string name
+      string[] models
+    }
+
+    API_KEY {
+      string id
+      string name
+      string key
+      string machineId
+    }
+
+    USAGE_ENTRY {
+      string provider
+      string model
+      number prompt_tokens
+      number completion_tokens
+      string connectionId
+      string timestamp
+    }
+
+    CUSTOM_MODEL {
+      string id
+      string name
+      string providerId
+    }
+
+    PROXY_CONFIG {
+      string global
+      json providers
+    }
+
+    IP_FILTER {
+      string mode
+      string[] allowlist
+      string[] blocklist
+    }
+
+    THINKING_BUDGET {
+      string mode
+      number customBudget
+      string effortLevel
+    }
+
+    SYSTEM_PROMPT {
+      boolean enabled
+      string prompt
+      string position
+    }
+```
+
+Physische Speicherdateien:
+
+- 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/...`
+
+## Bereitstellungstopologie
+
+```mermaid
+flowchart LR
+    subgraph LocalHost[Developer Host]
+        CLI[CLI Tools]
+        Browser[Dashboard Browser]
+    end
+
+    subgraph ContainerOrProcess[OmniRoute Runtime]
+        Next[Next.js Server\nPORT=20128]
+        Core[SSE Core + Executors]
+        MainDB[(db.json)]
+        UsageDB[(usage.json/log.txt)]
+    end
+
+    subgraph External[External Services]
+        Providers[AI Providers]
+        SyncCloud[Cloud Sync Service]
+    end
+
+    CLI --> Next
+    Browser --> Next
+    Next --> Core
+    Next --> MainDB
+    Core --> MainDB
+    Core --> UsageDB
+    Core --> Providers
+    Next --> SyncCloud
+```
+
+## Modulzuordnung (entscheidungskritisch)
+
+### Routen- und API-Module
+
+- `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)
+
+### Routing- und Ausführungskern
+
+- `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
+
+### Übersetzungsregister und Formatkonverter
+
+- `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`
+
+### Beharrlichkeit
+
+- `src/lib/localDb.ts`: persistente Konfiguration/Status
+- `src/lib/usageDb.ts`: Nutzungsverlauf und fortlaufende Anforderungsprotokolle
+
+## Provider Executor Coverage (Strategiemuster)
+
+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.
+
+| 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                                 |
+
+Alle anderen Anbieter (einschließlich benutzerdefinierter kompatibler Knoten) verwenden `DefaultExecutor`.
+
+## Anbieterkompatibilitätsmatrix
+
+| 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                | ✅               | ✅           | ❌                   | ❌                             |
+
+## Übersetzungsabdeckung im Format
+
+Zu den erkannten Quellformaten gehören:
+
+- `openai`
+- `openai-responses`
+- `claude`
+- `gemini`
+
+Zu den Zielformaten gehören:
+
+- OpenAI-Chat/Antworten
+- Claude
+- Gemini/Gemini-CLI/Antigravity-Umschlag
+- Kiro
+- Cursor
+
+Übersetzungen verwenden **OpenAI als Hub-Format** – alle Konvertierungen durchlaufen OpenAI als Zwischenformat:
+
+```
+Source Format → OpenAI (hub) → Target Format
+```
+
+Übersetzungen werden dynamisch basierend auf der Form der Quellnutzlast und dem Zielformat des Anbieters ausgewählt.
+
+Zusätzliche Verarbeitungsebenen in der Übersetzungspipeline:
+
+- **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`
+
+## Unterstützte API-Endpunkte
+
+| 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                  |
+
+## 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.
+
+## Logger-Pipeline anfordern
+
+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:
+
+```
+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.
+
+## Fehlermodi und Belastbarkeit
+
+## 1) Konto-/Anbieterverfügbarkeit
+
+- Abklingzeit des Anbieterkontos bei vorübergehenden/Raten-/Authentifizierungsfehlern
+- Konto-Fallback vor fehlgeschlagener Anfrage
+- Combo-Modell-Fallback, wenn der aktuelle Modell-/Anbieterpfad erschöpft ist
+
+## 2) Token-Ablauf
+
+- Vorabprüfung und Aktualisierung mit erneutem Versuch für aktualisierbare Anbieter
+  – 401/403-Wiederholungsversuch nach Aktualisierungsversuch im Kernpfad
+
+## 3) Stream-Sicherheit
+
+- Trennungsfähiger Stream-Controller
+  – Übersetzungsstream mit End-of-Stream-Flush und `[DONE]`-Behandlung
+- Fallback der Nutzungsschätzung, wenn Metadaten zur Anbieternutzung fehlen
+
+## 4) Verschlechterung der Cloud-Synchronisierung
+
+– 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
+
+## 5) Datenintegrität
+
+- DB-Shape-Migration/Reparatur für fehlende Schlüssel
+- Schutzmaßnahmen zum Zurücksetzen beschädigter JSON-Dateien für localDb und useDb
+
+## Beobachtbarkeit und Betriebssignale
+
+Quellen für die Laufzeitsichtbarkeit:
+
+– Konsolenprotokolle von `src/sse/utils/logger.ts`
+– Nutzungsaggregate pro Anfrage in `usage.json`
+
+- 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
+
+## Sicherheitsrelevante Grenzen
+
+– 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
+
+## Umgebungs- und Laufzeitmatrix
+
+Vom Code aktiv verwendete Umgebungsvariablen:
+
+- 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`
+
+## Bekannte architektonische Hinweise
+
+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).
+
+## 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:
+- `GET /api/settings`
+- `GET /api/v1/models`
+  – Die Basis-URL des CLI-Ziels sollte `http://<host>:20128/v1` sein, wenn `PORT=20128`

docs/i18n/de/CODEBASE_DOCUMENTATION.md

@@ -0,0 +1,589 @@
+# 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**.
+
+---
+
+## 1. Was ist Omniroute?
+
+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:
+
+> **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.
+
+---
+
+## 2. Architekturübersicht
+
+```mermaid
+graph LR
+    subgraph Clients
+        A[Claude CLI]
+        B[Codex]
+        C[Cursor IDE]
+        D[OpenAI-compatible]
+    end
+
+    subgraph omniroute
+        E[Handler Layer]
+        F[Translator Layer]
+        G[Executor Layer]
+        H[Services Layer]
+    end
+
+    subgraph Providers
+        I[Anthropic Claude]
+        J[Google Gemini]
+        K[OpenAI / Codex]
+        L[GitHub Copilot]
+        M[AWS Kiro]
+        N[Antigravity]
+        O[Cursor API]
+    end
+
+    A --> E
+    B --> E
+    C --> E
+    D --> E
+    E --> F
+    F --> G
+    G --> I
+    G --> J
+    G --> K
+    G --> L
+    G --> M
+    G --> N
+    G --> O
+    H -.-> E
+    H -.-> G
+```
+
+### Grundprinzip: Hub-and-Spoke-Übersetzung
+
+Die gesamte Formatübersetzung erfolgt über das **OpenAI-Format als 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.
+
+---
+
+## 3. Projektstruktur
+
+```
+omniroute/
+├── open-sse/                  ← Core proxy library (portable, framework-agnostic)
+│   ├── index.js               ← Main entry point, exports everything
+│   ├── config/                ← Configuration & constants
+│   ├── executors/             ← Provider-specific request execution
+│   ├── handlers/              ← Request handling orchestration
+│   ├── services/              ← Business logic (auth, models, fallback, usage)
+│   ├── translator/            ← Format translation engine
+│   │   ├── request/           ← Request translators (8 files)
+│   │   ├── response/          ← Response translators (7 files)
+│   │   └── helpers/           ← Shared translation utilities (6 files)
+│   └── utils/                 ← Utility functions
+├── src/                       ← Application layer (Express/Worker runtime)
+│   ├── app/                   ← Web UI, API routes, middleware
+│   ├── lib/                   ← Database, auth, and shared library code
+│   ├── mitm/                  ← Man-in-the-middle proxy utilities
+│   ├── models/                ← Database models
+│   ├── shared/                ← Shared utilities (wrappers around open-sse)
+│   ├── sse/                   ← SSE endpoint handlers
+│   └── store/                 ← State management
+├── data/                      ← Runtime data (credentials, logs)
+│   └── provider-credentials.json   (external credentials override, gitignored)
+└── tester/                    ← Test utilities
+```
+
+---
+
+## 4. Aufschlüsselung nach Modulen
+
+### 4.1 Konfiguration (`open-sse/config/`)
+
+Die **Single Source of Truth** für die gesamte Anbieterkonfiguration.
+
+| 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).                                                                                                                                                                               |
+
+#### Ladevorgang für Anmeldeinformationen
+
+```mermaid
+flowchart TD
+    A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"]
+    B --> C{"data/provider-credentials.json\nexists?"}
+    C -->|Yes| D["credentialLoader reads JSON"]
+    C -->|No| E["Use hardcoded defaults"]
+    D --> F{"For each provider in JSON"}
+    F --> G{"Provider exists\nin PROVIDERS?"}
+    G -->|No| H["Log warning, skip"]
+    G -->|Yes| I{"Value is object?"}
+    I -->|No| J["Log warning, skip"]
+    I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"]
+    K --> F
+    H --> F
+    J --> F
+    F -->|Done| L["PROVIDERS ready with\nmerged credentials"]
+    E --> L
+```
+
+---
+
+### 4.2 Ausführende (`open-sse/executors/`)
+
+Ausführende kapseln **anbieterspezifische Logik** mithilfe des **Strategiemusters**. Jeder Executor überschreibt bei Bedarf Basismethoden.
+
+```mermaid
+classDiagram
+    class BaseExecutor {
+        +buildUrl(model, stream, options)
+        +buildHeaders(credentials, stream, body)
+        +transformRequest(body, model, stream, credentials)
+        +execute(url, options)
+        +shouldRetry(status, error)
+        +refreshCredentials(credentials, log)
+    }
+
+    class DefaultExecutor {
+        +refreshCredentials()
+    }
+
+    class AntigravityExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +shouldRetry()
+        +refreshCredentials()
+    }
+
+    class CursorExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseResponse()
+        +generateChecksum()
+    }
+
+    class KiroExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseEventStream()
+        +refreshCredentials()
+    }
+
+    BaseExecutor <|-- DefaultExecutor
+    BaseExecutor <|-- AntigravityExecutor
+    BaseExecutor <|-- CursorExecutor
+    BaseExecutor <|-- KiroExecutor
+    BaseExecutor <|-- CodexExecutor
+    BaseExecutor <|-- GeminiCLIExecutor
+    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                                                                       |
+
+---
+
+### 4.3 Handler (`open-sse/handlers/`)
+
+Die **Orchestrierungsebene** – koordiniert Übersetzung, Ausführung, Streaming und Fehlerbehandlung.
+
+| 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.                                                                      |
+
+#### Anforderungslebenszyklus (chatCore.ts)
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant chatCore
+    participant Translator
+    participant Executor
+    participant Provider
+
+    Client->>chatCore: Request (any format)
+    chatCore->>chatCore: Detect source format
+    chatCore->>chatCore: Check bypass patterns
+    chatCore->>chatCore: Resolve model & provider
+    chatCore->>Translator: Translate request (source → OpenAI → target)
+    chatCore->>Executor: Get executor for provider
+    Executor->>Executor: Build URL, headers, transform request
+    Executor->>Executor: Refresh credentials if needed
+    Executor->>Provider: HTTP fetch (streaming or non-streaming)
+
+    alt Streaming
+        Provider-->>chatCore: SSE stream
+        chatCore->>chatCore: Pipe through SSE transform stream
+        Note over chatCore: Transform stream translates<br/>each chunk: target → OpenAI → source
+        chatCore-->>Client: Translated SSE stream
+    else Non-streaming
+        Provider-->>chatCore: JSON response
+        chatCore->>Translator: Translate response
+        chatCore-->>Client: Translated JSON
+    end
+
+    alt Error (401, 429, 500...)
+        chatCore->>Executor: Retry with credential refresh
+        chatCore->>chatCore: Account fallback logic
+    end
+```
+
+---
+
+### 4.4 Dienste (`open-sse/services/`)
+
+Geschäftslogik, die die Handler und Ausführenden unterstützt.
+
+| 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.                                                                                                                                                                                                                                |
+
+#### Token-Aktualisierungsdeduplizierung
+
+```mermaid
+sequenceDiagram
+    participant R1 as Request 1
+    participant R2 as Request 2
+    participant Cache as refreshPromiseCache
+    participant OAuth as OAuth Provider
+
+    R1->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: No in-flight promise
+    Cache->>OAuth: Start refresh
+    R2->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: Found in-flight promise
+    Cache-->>R2: Return existing promise
+    OAuth-->>Cache: New access token
+    Cache-->>R1: New access token
+    Cache-->>R2: Same access token (shared)
+    Cache->>Cache: Delete cache entry
+```
+
+#### Konto-Fallback-Zustandsmaschine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active
+    Active --> Error: Request fails (401/429/500)
+    Error --> Cooldown: Apply backoff
+    Cooldown --> Active: Cooldown expires
+    Active --> Active: Request succeeds (reset backoff)
+
+    state Error {
+        [*] --> ClassifyError
+        ClassifyError --> ShouldFallback: Rate limit / Auth / Transient
+        ClassifyError --> NoFallback: 400 Bad Request
+    }
+
+    state Cooldown {
+        [*] --> ExponentialBackoff
+        ExponentialBackoff: Level 0 = 1s
+        ExponentialBackoff: Level 1 = 2s
+        ExponentialBackoff: Level 2 = 4s
+        ExponentialBackoff: Max = 2min
+    }
+```
+
+#### Combo-Modellkette
+
+```mermaid
+flowchart LR
+    A["Request with\ncombo model"] --> B["Model A"]
+    B -->|"2xx Success"| C["Return response"]
+    B -->|"429/401/500"| D{"Fallback\neligible?"}
+    D -->|Yes| E["Model B"]
+    D -->|No| F["Return error"]
+    E -->|"2xx Success"| C
+    E -->|"429/401/500"| G{"Fallback\neligible?"}
+    G -->|Yes| H["Model C"]
+    G -->|No| F
+    H -->|"2xx Success"| C
+    H -->|"Fail"| I["All failed →\nReturn last status"]
+```
+
+---
+
+### 4.5 Übersetzer (`open-sse/translator/`)
+
+Die **Formatübersetzungs-Engine** verwendet ein selbstregistrierendes Plugin-System.
+
+#### Architektur
+
+```mermaid
+graph TD
+    subgraph "Request Translation"
+        A["Claude → OpenAI"]
+        B["Gemini → OpenAI"]
+        C["Antigravity → OpenAI"]
+        D["OpenAI Responses → OpenAI"]
+        E["OpenAI → Claude"]
+        F["OpenAI → Gemini"]
+        G["OpenAI → Kiro"]
+        H["OpenAI → Cursor"]
+    end
+
+    subgraph "Response Translation"
+        I["Claude → OpenAI"]
+        J["Gemini → OpenAI"]
+        K["Kiro → OpenAI"]
+        L["Cursor → OpenAI"]
+        M["OpenAI → Claude"]
+        N["OpenAI → Antigravity"]
+        O["OpenAI → Responses"]
+    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`.                                                                                                                                                                                                          |
+
+#### Schlüsseldesign: Selbstregistrierende Plugins
+
+```javascript
+// Each translator file calls register() on import:
+import { register } from "../index.js";
+register("claude", "openai", translateClaudeToOpenAI);
+
+// The index.js imports all translator files, triggering registration:
+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.                  |
+
+#### SSE-Streaming-Pipeline
+
+```mermaid
+flowchart TD
+    A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"]
+    B --> C["Buffer lines\n(split on newline)"]
+    C --> D["parseSSELine()\n(trim whitespace, parse JSON)"]
+    D --> E{"Mode?"}
+    E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"]
+    E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"]
+    F --> H["hasValuableContent()\nfilter empty chunks"]
+    G --> H
+    H -->|"Has content"| I["extractUsage()\ntrack token counts"]
+    H -->|"Empty"| J["Skip chunk"]
+    I --> K["formatSSE()\nserialize + clean perf_metrics"]
+    K --> L["TextEncoder\n(per-stream instance)"]
+    L --> M["Enqueue to\nclient stream"]
+
+    style A fill:#f9f,stroke:#333
+    style M fill:#9f9,stroke:#333
+```
+
+#### Logger-Sitzungsstruktur anfordern
+
+```
+logs/
+└── claude_gemini_claude-sonnet_20260208_143045/
+    ├── 1_req_client.json      ← Raw client request
+    ├── 2_req_source.json      ← After initial conversion
+    ├── 3_req_openai.json      ← OpenAI intermediate format
+    ├── 4_req_target.json      ← Final target format
+    ├── 5_res_provider.txt     ← Provider SSE chunks (streaming)
+    ├── 5_res_provider.json    ← Provider response (non-streaming)
+    ├── 6_res_openai.txt       ← OpenAI intermediate chunks
+    ├── 7_res_client.txt       ← Client-facing SSE chunks
+    └── 6_error.json           ← Error details (if any)
+```
+
+---
+
+### 4.7 Anwendungsschicht (`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                                                          |
+
+#### Bemerkenswerte API-Routen
+
+| 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                                                                    |
+
+---
+
+## 5. Wichtige Designmuster
+
+### 5.1 Hub-and-Spoke-Übersetzung
+
+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.
+
+### 5.2 Executor-Strategiemuster
+
+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.
+
+### 5.3 Selbstregistrierendes Plugin-System
+
+Übersetzermodule registrieren sich beim Import über `register()`. Beim Hinzufügen eines neuen Übersetzers wird lediglich eine Datei erstellt und importiert.
+
+### 5.4 Konto-Fallback mit exponentiellem 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.).
+
+### 5.5 Combo-Modellketten
+
+Eine „Kombination“ gruppiert mehrere `provider/model`-Strings. Wenn der erste fehlschlägt, wird automatisch auf den nächsten zurückgegriffen.
+
+### 5.6 Stateful Streaming-Übersetzung
+
+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.
+
+### 5.7 Nutzungssicherheitspuffer
+
+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.
+
+---
+
+## 6. Unterstützte Formate
+
+| 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`           |
+
+---
+
+## 7. Unterstützte Anbieter
+
+| 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                 |
+
+---
+
+## 8. Zusammenfassung des Datenflusses
+
+### Streaming-Anfrage
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor\nbuildUrl + buildHeaders"]
+    D --> E["fetch(providerURL)"]
+    E --> F["createSSEStream()\nTRANSLATE mode"]
+    F --> G["parseSSELine()"]
+    G --> H["translateResponse()\ntarget → OpenAI → source"]
+    H --> I["extractUsage()\n+ addBuffer"]
+    I --> J["formatSSE()"]
+    J --> K["Client receives\ntranslated SSE"]
+    K --> L["logUsage()\nsaveRequestUsage()"]
+```
+
+### Nicht-Streaming-Anfrage
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor.execute()"]
+    D --> E["translateResponse()\ntarget → OpenAI → source"]
+    E --> F["Return JSON\nresponse"]
+```
+
+### Bypass-Flow (Claude CLI)
+
+```mermaid
+flowchart LR
+    A["Claude CLI request"] --> B{"Match bypass\npattern?"}
+    B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"]
+    B -->|"No match"| D["Normal flow"]
+    C --> E["Translate to\nsource format"]
+    E --> F["Return without\ncalling provider"]
+```

docs/i18n/de/FEATURES.md

@@ -0,0 +1,77 @@
+# 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.
+
+---
+
+## 🔌 Anbieter
+
+Verwalten Sie KI-Anbieterverbindungen: OAuth-Anbieter (Claude Code, Codex, Gemini CLI), API-Schlüsselanbieter (Groq, DeepSeek, OpenRouter) und kostenlose Anbieter (iFlow, Qwen, Kiro).
+
+![Providers Dashboard](screenshots/01-providers.png)
+
+---
+
+## 🎨 Kombinationen
+
+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.
+
+![Combos Dashboard](screenshots/02-combos.png)
+
+---
+
+## 📊 Analytik
+
+Umfassende Nutzungsanalysen mit Token-Verbrauch, Kostenschätzungen, Aktivitäts-Heatmaps, wöchentlichen Verteilungsdiagrammen und Aufschlüsselungen pro Anbieter.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
+
+---
+
+## 🏥 Systemgesundheit
+
+Echtzeitüberwachung: Betriebszeit, Speicher, Version, Latenzperzentile (p50/p95/p99), Cache-Statistiken und Leistungsschalterzustände des Anbieters.
+
+![Health Dashboard](screenshots/04-health.png)
+
+---
+
+## 🔧 Übersetzerspielplatz
+
+Vier Modi zum Debuggen von API-Übersetzungen: **Playground** (Formatkonverter), **Chat Tester** (Live-Anfragen), **Test Bench** (Batch-Tests) und **Live Monitor** (Echtzeit-Stream).
+
+![Translator Playground](screenshots/05-translator.png)
+
+---
+
+## ⚙️ Einstellungen
+
+Allgemeine Einstellungen, Systemspeicher, Backup-Management (Datenbank exportieren/importieren), Erscheinungsbild (Dunkel-/Hellmodus), Sicherheit (einschließlich API-Endpunktschutz und benutzerdefinierter Anbieterblockierung), Routing, Ausfallsicherheit und erweiterte Konfiguration.
+
+![Settings Dashboard](screenshots/06-settings.png)
+
+---
+
+## 🔧 CLI-Tools
+
+Ein-Klick-Konfiguration für KI-Codierungstools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code und Antigravity.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+
+---
+
+## 📝 Protokolle anfordern
+
+Echtzeit-Anfrageprotokollierung mit Filterung nach Anbieter, Modell, Konto und API-Schlüssel. Zeigt Statuscodes, Token-Nutzung, Latenz und Antwortdetails an.
+
+![Usage Logs](screenshots/08-usage.png)
+
+---
+
+## 🌐 API-Endpunkt
+
+Ihr einheitlicher API-Endpunkt mit Aufschlüsselung der Funktionen: Chat-Abschlüsse, Einbettungen, Bildgenerierung, Reranking, Audiotranskription und registrierte API-Schlüssel.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)

docs/i18n/de/TROUBLESHOOTING.md

@@ -0,0 +1,221 @@
+# 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.
+
+---
+
+## Schnelle Lösungen
+
+| 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)    |
+
+---
+
+## Anbieterprobleme
+
+### „Sprachmodell hat keine Nachrichten bereitgestellt“
+
+**Ursache:** Anbieterkontingent erschöpft.
+
+**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
+
+### Ratenbegrenzung
+
+**Ursache:** Das Abonnementkontingent ist erschöpft.
+
+**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
+
+### OAuth-Token abgelaufen
+
+OmniRoute aktualisiert Token automatisch. Wenn die Probleme weiterhin bestehen:
+
+1. Dashboard → Anbieter → Erneut verbinden
+2. Löschen Sie die Anbieterverbindung und fügen Sie sie erneut hinzu
+
+---
+
+## Cloud-Probleme
+
+### Cloud-Synchronisierungsfehler
+
+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
+
+### Cloud `stream=false` Gibt 500 zurück
+
+**Symptom:** `Unexpected token 'd'...` am Cloud-Endpunkt für Nicht-Streaming-Anrufe.
+
+**Ursache:** Upstream gibt SSE-Nutzdaten zurück, während der Client JSON erwartet.
+
+**Problemumgehung:** Verwenden Sie `stream=true` für Cloud-Direktaufrufe. Die lokale Laufzeit umfasst SSE→JSON-Fallback.
+
+### Cloud sagt verbunden, aber „Ungültiger API-Schlüssel“
+
+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
+
+---
+
+## Docker-Probleme
+
+### CLI-Tool wird als „Nicht installiert“ angezeigt
+
+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
+
+### Schnelle Laufzeitvalidierung
+
+```bash
+curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+```
+
+---
+
+## Kostenprobleme
+
+### Hohe Kosten
+
+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
+
+---
+
+## Debuggen
+
+### Anforderungsprotokolle aktivieren
+
+Legen Sie `ENABLE_REQUEST_LOGS=true` in Ihrer `.env`-Datei fest. Protokolle werden im Verzeichnis `logs/` angezeigt.
+
+### Überprüfen Sie den Zustand des Anbieters
+
+```bash
+# Health dashboard
+http://localhost:20128/dashboard/health
+
+# API health check
+curl http://localhost:20128/api/monitoring/health
+```
+
+### Laufzeitspeicher
+
+- 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`)
+
+---
+
+## Probleme mit Leistungsschaltern
+
+### Provider bleibt im OPEN-Zustand hängen
+
+Wenn der Leistungsschalter eines Anbieters OFFEN ist, werden Anfragen blockiert, bis die Abklingzeit abgelaufen ist.
+
+**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
+
+### Der Anbieter löst weiterhin den Schutzschalter aus
+
+Wenn ein Anbieter wiederholt in den OPEN-Zustand wechselt:
+
+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
+
+---
+
+## Probleme mit der Audiotranskription
+
+### Fehler „Nicht unterstütztes Modell“.
+
+– Stellen Sie sicher, dass Sie das richtige Präfix verwenden: `deepgram/nova-3` oder `assemblyai/best`
+
+- Überprüfen Sie, ob der Anbieter unter **Dashboard → Anbieter** verbunden ist.
+
+### 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
+
+---
+
+## Übersetzer-Debugging
+
+Verwenden Sie **Dashboard → Übersetzer**, um Formatübersetzungsprobleme zu beheben:
+
+| 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                                  |
+
+### Häufige Formatprobleme
+
+- **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
+
+---
+
+## Resilienzeinstellungen
+
+### Automatische Ratenbegrenzung wird nicht ausgelöst
+
+– Die automatische Ratenbegrenzung gilt nur für API-Schlüsselanbieter (nicht OAuth/Abonnement).
+
+- Ü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
+
+### Optimierung des exponentiellen Backoffs
+
+Anbieterprofile unterstützen diese Einstellungen:
+
+- **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-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.
+
+---
+
+## Immer noch nicht weitergekommen?
+
+- **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

docs/i18n/de/USER_GUIDE.md

@@ -0,0 +1,698 @@
+# 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.
+
+---
+
+## Inhaltsverzeichnis
+
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
+
+## 💰 Preise im Überblick
+
+| 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                     |
+
+**💡 Profi-Tipp:** Beginnen Sie mit der Kombination Gemini CLI (180.000 kostenlos/Monat) + iFlow (unbegrenzt kostenlos) = 0 $ Kosten!
+
+---
+
+## 🎯 Anwendungsfälle
+
+### Fall 1: „Ich habe ein Claude Pro-Abonnement“
+
+**Problem:** Kontingent läuft ungenutzt ab, Ratenbegrenzungen bei intensiver Codierung
+
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6        (use subscription fully)
+  2. glm/glm-4.7               (cheap backup when quota out)
+  3. if/kimi-k2-thinking       (free emergency fallback)
+
+Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
+vs. $20 + hitting limits = frustration
+```
+
+### Fall 2: „Ich möchte Nullkosten“
+
+**Problem:** Ich kann mir keine Abonnements leisten und brauche zuverlässige KI-Codierung
+
+```
+Combo: "free-forever"
+  1. gc/gemini-3-flash         (180K free/month)
+  2. if/kimi-k2-thinking       (unlimited free)
+  3. qw/qwen3-coder-plus       (unlimited free)
+
+Monthly cost: $0
+Quality: Production-ready models
+```
+
+### Fall 3: „Ich brauche 24/7-Codierung, keine Unterbrechungen“
+
+**Problem:** Fristen, ich kann mir Ausfallzeiten nicht leisten
+
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-6        (best quality)
+  2. cx/gpt-5.2-codex          (second subscription)
+  3. glm/glm-4.7               (cheap, resets daily)
+  4. minimax/MiniMax-M2.1      (cheapest, 5h reset)
+  5. if/kimi-k2-thinking       (free unlimited)
+
+Result: 5 layers of fallback = zero downtime
+Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
+```
+
+### Fall 4: „Ich möchte KOSTENLOSE KI in OpenClaw“
+
+**Problem:** Benötigen Sie einen KI-Assistenten in Messaging-Apps, völlig kostenlos
+
+```
+Combo: "openclaw-free"
+  1. if/glm-4.7                (unlimited free)
+  2. if/minimax-m2.1           (unlimited free)
+  3. if/kimi-k2-thinking       (unlimited free)
+
+Monthly cost: $0
+Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+```
+
+---
+
+## 📖 Anbieter-Setup
+
+### 🔐 Abonnementanbieter
+
+#### Claude Code (Pro/Max)
+
+```bash
+Dashboard → Providers → Connect Claude Code
+→ OAuth login → Auto token refresh
+→ 5-hour + weekly quota tracking
+
+Models:
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**Profi-Tipp:** Verwenden Sie Opus für komplexe Aufgaben, Sonnet für Geschwindigkeit. OmniRoute verfolgt das Kontingent pro Modell!
+
+#### OpenAI Codex (Plus/Pro)
+
+```bash
+Dashboard → Providers → Connect Codex
+→ OAuth login (port 1455)
+→ 5-hour + weekly reset
+
+Models:
+  cx/gpt-5.2-codex
+  cx/gpt-5.1-codex-max
+```
+
+#### Gemini CLI (KOSTENLOS 180.000/Monat!)
+
+```bash
+Dashboard → Providers → Connect Gemini CLI
+→ Google OAuth
+→ 180K completions/month + 1K/day
+
+Models:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**Bester Wert:** Riesiges kostenloses Kontingent! Verwenden Sie dies vor kostenpflichtigen Stufen.
+
+#### GitHub-Copilot
+
+```bash
+Dashboard → Providers → Connect GitHub
+→ OAuth via GitHub
+→ Monthly reset (1st of month)
+
+Models:
+  gh/gpt-5
+  gh/claude-4.5-sonnet
+  gh/gemini-3-pro
+```
+
+### 💰 Günstige Anbieter
+
+#### GLM-4.7 (Täglicher Reset, 0,6 $/1 Mio.)
+
+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`
+
+**Verwendung:** `glm/glm-4.7` — **Profi-Tipp:** Coding Plan bietet 3× Kontingent zu 1/7 Kosten! Täglich um 10:00 Uhr zurückgesetzt.
+
+#### MiniMax M2.1 (5 Stunden Zurücksetzen, 0,20 $/1 Mio.)
+
+1. Registrieren Sie sich: [MiniMax](https://www.minimax.io/)
+2. API-Schlüssel abrufen → Dashboard → API-Schlüssel hinzufügen
+
+**Verwendung:** `minimax/MiniMax-M2.1` – **Profi-Tipp:** Günstigste Option für langen Kontext (1 Mio. Token)!
+
+#### Kimi K2 (9 $/Monat pauschal)
+
+1. Abonnieren: [Moonshot AI](https://platform.moonshot.ai/)
+2. API-Schlüssel abrufen → Dashboard → API-Schlüssel hinzufügen
+
+**Verwendung:** `kimi/kimi-latest` — **Profi-Tipp:** Feste 9 $/Monat für 10 Mio. Token = 0,90 $/1 Mio. effektive Kosten!
+
+### 🆓 KOSTENLOSE Anbieter
+
+#### iFlow (8 KOSTENLOSE Modelle)
+
+```bash
+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)
+
+```bash
+Dashboard → Connect Qwen → Device code auth → Unlimited usage
+
+Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
+```
+
+#### Kiro (Claude KOSTENLOS)
+
+```bash
+Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
+
+Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
+```
+
+---
+
+## 🎨 Kombinationen
+
+### Beispiel 1: Abonnement maximieren → Günstiges Backup
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-6 (Subscription primary)
+  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
+  3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
+
+Use in CLI: premium-coding
+```
+
+### Beispiel 2: Nur kostenlos (kostenlos)
+
+```
+Name: free-combo
+Models:
+  1. gc/gemini-3-flash-preview (180K free/month)
+  2. if/kimi-k2-thinking (unlimited)
+  3. qw/qwen3-coder-plus (unlimited)
+
+Cost: $0 forever!
+```
+
+---
+
+## 🔧 CLI-Integration
+
+### Cursor-IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from omniroute dashboard]
+  Model: cc/claude-opus-4-6
+```
+
+### Claude Code
+
+Bearbeiten Sie `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-omniroute-api-key"
+}
+```
+
+### Codex-CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-omniroute-api-key"
+codex "your prompt"
+```
+
+### OpenClaw
+
+Bearbeiten Sie `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": { "primary": "omniroute/if/glm-4.7" }
+    }
+  },
+  "models": {
+    "providers": {
+      "omniroute": {
+        "baseUrl": "http://localhost:20128/v1",
+        "apiKey": "your-omniroute-api-key",
+        "api": "openai-completions",
+        "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+      }
+    }
+  }
+}
+```
+
+**Oder verwenden Sie Dashboard:** CLI-Tools → OpenClaw → Auto-config
+
+### Cline / Weiter / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-6
+```
+
+---
+
+## 🚀 Bereitstellung
+
+### VPS-Bereitstellung
+
+```bash
+git clone https://github.com/diegosouzapw/OmniRoute.git
+cd OmniRoute && npm install && npm run build
+
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+export DATA_DIR="/var/lib/omniroute"
+export PORT="20128"
+export HOSTNAME="0.0.0.0"
+export NODE_ENV="production"
+export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
+export API_KEY_SECRET="endpoint-proxy-api-key-secret"
+
+npm run start
+# Or: pm2 start npm --name omniroute -- start
+```
+
+### Docker
+
+```bash
+# Build image (default = runner-cli with codex/claude/droid preinstalled)
+docker build -t omniroute:cli .
+
+# Portable mode (recommended)
+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.
+
+### Umgebungsvariablen
+
+| 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) |
+
+Die vollständige Umgebungsvariablenreferenz finden Sie im [README](../README.md).
+
+---
+
+## 📊 Verfügbare Modelle
+
+<details>
+<summary><b>Alle verfügbaren Modelle anzeigen</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/`)** – KOSTENLOS: `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`
+
+**MiniMax (`minimax/`)** – 0,2 $/1 Mio.: `minimax/MiniMax-M2.1`
+
+**iFlow (`if/`)** – KOSTENLOS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+
+**Qwen (`qw/`)** – KOSTENLOS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+
+**Kiro (`kr/`)** – KOSTENLOS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
+
+**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`
+
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
+
+**Perplexität (`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`
+
+**Großhirn (`cerebras/`)**: `cerebras/llama-3.3-70b`
+
+**Zusammenhang (`cohere/`)**: `cohere/command-r-plus-08-2024`
+
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+</details>
+
+---
+
+## 🧩 Erweiterte Funktionen
+
+### Benutzerdefinierte Modelle
+
+Fügen Sie jedem Anbieter eine beliebige Modell-ID hinzu, ohne auf ein App-Update warten zu müssen:
+
+```bash
+# Via API
+curl -X POST http://localhost:20128/api/provider-models \
+  -H "Content-Type: application/json" \
+  -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}'
+
+# List: curl http://localhost:20128/api/provider-models?provider=openai
+# 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**.
+
+### Dedizierte Anbieterrouten
+
+Leiten Sie Anfragen mit Modellvalidierung direkt an einen bestimmten Anbieter weiter:
+
+```bash
+POST http://localhost:20128/v1/providers/openai/chat/completions
+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.
+
+### Netzwerk-Proxy-Konfiguration
+
+```bash
+# Set global proxy
+curl -X PUT http://localhost:20128/api/settings/proxy \
+  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
+
+# Per-provider proxy
+curl -X PUT http://localhost:20128/api/settings/proxy \
+  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
+
+# Test proxy
+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.
+
+### Modellkatalog-API
+
+```bash
+curl http://localhost:20128/api/models/catalog
+```
+
+Gibt nach Anbieter gruppierte Modelle mit Typen (`chat`, `embedding`, `image`) zurück.
+
+### Cloud-Synchronisierung
+
+- 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
+
+### 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
+
+---
+
+### Übersetzerspielplatz
+
+Zugriff über **Dashboard → Übersetzer**. Debuggen und visualisieren Sie, wie OmniRoute API-Anfragen zwischen Anbietern übersetzt.
+
+| 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                                  |
+
+**Anwendungsfälle:**
+
+- 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
+
+---
+
+### Routing-Strategien
+
+Konfigurieren Sie über **Dashboard → Einstellungen → 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                     |
+
+#### Wildcard-Modellaliase
+
+Erstellen Sie Platzhaltermuster, um Modellnamen neu zuzuordnen:
+
+```
+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).
+
+#### Fallback-Ketten
+
+Definieren Sie globale Fallback-Ketten, die für alle Anfragen gelten:
+
+```
+Chain: production-fallback
+  1. cc/claude-opus-4-6
+  2. gh/gpt-5.1-codex
+  3. glm/glm-4.7
+```
+
+---
+
+### Belastbarkeit und Leistungsschalter
+
+Konfigurieren Sie über **Dashboard → Einstellungen → Resilienz**.
+
+OmniRoute implementiert Resilienz auf Anbieterebene mit vier Komponenten:
+
+1. **Anbieterprofile** – Konfiguration pro Anbieter für:
+   - Fehlerschwelle (wie viele Fehler vor dem Öffnen)
+   - Abklingdauer
+   - Empfindlichkeit der Grenzfrequenzerkennung
+   - Exponentielle Backoff-Parameter
+
+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.
+
+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
+
+4. **Richtlinien und Sperrkennungen** – Zeigt den Status des Leistungsschalters und die Sperrkennungen mit der Möglichkeit zum erzwungenen Entsperren an.
+
+5. **Automatische Erkennung von Ratenbegrenzungen** – Überwacht die Header `429` und `Retry-After`, um proaktiv zu vermeiden, dass die Ratenbegrenzungen der Anbieter erreicht werden.
+
+**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.
+
+---
+
+### Datenbankexport/-import
+
+Verwalten Sie Datenbanksicherungen unter **Dashboard → Einstellungen → System & Speicher**.
+
+| 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                                                |
+
+```bash
+# API: Export database
+curl -o backup.sqlite http://localhost:20128/api/db-backups/export
+
+# API: Export all (full archive)
+curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
+
+# API: Import database
+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.
+
+**Anwendungsfälle:**
+
+- OmniRoute zwischen Maschinen migrieren
+- Erstellen Sie externe Backups für die Notfallwiederherstellung
+- Konfigurationen zwischen Teammitgliedern teilen (alle exportieren → Archiv teilen)
+
+---
+
+### Einstellungs-Dashboard
+
+Die Einstellungsseite ist zur einfachen Navigation in 5 Registerkarten unterteilt:
+
+| 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)                                                                         |
+
+---
+
+### Kosten- und Budgetmanagement
+
+Zugang über **Dashboard → Kosten**.
+
+| 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         |
+
+```bash
+# API: Set a budget
+curl -X POST http://localhost:20128/api/usage/budget \
+  -H "Content-Type: application/json" \
+  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
+
+# API: Get current budget status
+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.
+
+---
+
+### Audiotranskription
+
+OmniRoute unterstützt die Audiotranskription über den OpenAI-kompatiblen Endpunkt:
+
+```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+
+# Example with curl
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+  -H "Authorization: Bearer your-api-key" \
+  -F "file=@audio.mp3" \
+  -F "model=deepgram/nova-3"
+```
+
+Verfügbare Anbieter: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
+
+Unterstützte Audioformate: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+
+---
+
+### Combo-Balancing-Strategien
+
+Konfigurieren Sie die Balance pro Combo unter **Dashboard → Combos → Erstellen/Bearbeiten → Strategie**.
+
+| 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)                  |
+
+Globale Combo-Standards können unter **Dashboard → Einstellungen → Routing → Combo-Standards** festgelegt werden.
+
+---
+
+### Gesundheits-Dashboard
+
+Zugriff über **Dashboard → Gesundheit**. Echtzeit-Übersicht über den Systemzustand mit 6 Karten:
+
+| 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                                |
+
+**Profi-Tipp:** Die Gesundheitsseite wird alle 10 Sekunden automatisch aktualisiert. Verwenden Sie die Leistungsschalterkarte, um zu ermitteln, bei welchen Anbietern Probleme auftreten.

docs/i18n/es/API_REFERENCE.md

@@ -0,0 +1,441 @@
+# 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.
+
+---
+
+## Tabla de contenidos
+
+- [Chat Completions](#chat-completions)
+- [Embeddings](#embeddings)
+- [Image Generation](#image-generation)
+- [List Models](#list-models)
+- [Compatibility Endpoints](#compatibility-endpoints)
+- [Semantic Cache](#semantic-cache)
+- [Dashboard & Management](#dashboard--management)
+- [Request Processing](#request-processing)
+- [Authentication](#authentication)
+
+---
+
+## Finalizaciones de chat
+
+```bash
+POST /v1/chat/completions
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "cc/claude-opus-4-6",
+  "messages": [
+    {"role": "user", "content": "Write a function to..."}
+  ],
+  "stream": true
+}
+```
+
+### Encabezados personalizados
+
+| 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 |
+
+---
+
+## Incrustaciones
+
+```bash
+POST /v1/embeddings
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "nebius/Qwen/Qwen3-Embedding-8B",
+  "input": "The food was delicious"
+}
+```
+
+Proveedores disponibles: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+
+```bash
+# List all embedding models
+GET /v1/embeddings
+```
+
+---
+
+## Generación de imágenes
+
+```bash
+POST /v1/images/generations
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "openai/dall-e-3",
+  "prompt": "A beautiful sunset over mountains",
+  "size": "1024x1024"
+}
+```
+
+Proveedores disponibles: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+
+```bash
+# List all image models
+GET /v1/images/generations
+```
+
+---
+
+## Listar modelos
+
+```bash
+GET /v1/models
+Authorization: Bearer your-api-key
+
+→ Returns all chat, embedding, and image models + combos in OpenAI format
+```
+
+---
+
+## Puntos finales de compatibilidad
+
+| 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á                   |
+
+### Rutas de proveedores dedicadas
+
+```bash
+POST /v1/providers/{provider}/chat/completions
+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`.
+
+---
+
+## Caché semántico
+
+```bash
+# Get cache stats
+GET /api/cache
+
+# Clear all caches
+DELETE /api/cache
+```
+
+Ejemplo de respuesta:
+
+```json
+{
+  "semanticCache": {
+    "memorySize": 42,
+    "memoryMaxSize": 500,
+    "dbSize": 128,
+    "hitRate": 0.65
+  },
+  "idempotency": {
+    "activeKeys": 3,
+    "windowMs": 5000
+  }
+}
+```
+
+---
+
+## Panel de control y gestión
+
+### Autenticación
+
+| 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 |
+
+### Gestión de proveedores
+
+| 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              |
+
+### Flujos de OAuth
+
+| Punto final                      | Método | Descripción                    |
+| -------------------------------- | ------ | ------------------------------ |
+| `/api/oauth/[provider]/[action]` | Varios | OAuth específico del proveedor |
+
+### Enrutamiento y configuración
+
+| 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                     |
+
+### Uso y análisis
+
+| 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               |
+
+### Configuración
+
+| 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                |
+
+### Monitoreo
+
+| 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 |
+
+### Copia de seguridad y exportación/importación
+
+| 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 |
+
+### Sincronización en la nube
+
+| 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                       |
+
+### Herramientas CLI
+
+| 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 |
+
+Las respuestas de CLI incluyen: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
+
+### Resiliencia y límites de tasas
+
+| 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    |
+
+### Evaluaciones
+
+| Punto final  | Método           | Descripción                                        |
+| ------------ | ---------------- | -------------------------------------------------- |
+| `/api/evals` | OBTENER/PUBLICAR | Listar conjuntos de evaluación/ejecutar evaluación |
+
+### Políticas
+
+| Punto final     | Método                    | Descripción                           |
+| --------------- | ------------------------- | ------------------------------------- |
+| `/api/policies` | OBTENER/PUBLICAR/ELIMINAR | Administrar políticas de enrutamiento |
+
+### Cumplimiento
+
+| Punto final                 | Método  | Descripción                                      |
+| --------------------------- | ------- | ------------------------------------------------ |
+| `/api/compliance/audit-log` | OBTENER | Registro de auditoría de cumplimiento (última N) |
+
+### v1beta (Compatible con Gemini)
+
+| Punto final                | Método   | Descripción                           |
+| -------------------------- | -------- | ------------------------------------- |
+| `/v1beta/models`           | OBTENER  | Listar modelos en formato Gemini      |
+| `/v1beta/models/{...path}` | PUBLICAR | Géminis `generateContent` punto final |
+
+Estos puntos finales reflejan el formato API de Gemini para clientes que esperan compatibilidad nativa con el SDK de Gemini.
+
+### API internas/del sistema
+
+| 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                                             |
+
+> **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.
+
+---
+
+## Transcripción de audio
+
+```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+```
+
+Transcribe archivos de audio usando Deepgram o AssemblyAI.
+
+**Solicitud:**
+
+```bash
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+  -H "Authorization: Bearer your-api-key" \
+  -F "file=@recording.mp3" \
+  -F "model=deepgram/nova-3"
+```
+
+**Respuesta:**
+
+```json
+{
+  "text": "Hello, this is the transcribed audio content.",
+  "task": "transcribe",
+  "language": "en",
+  "duration": 12.5
+}
+```
+
+**Proveedores admitidos:** `deepgram/nova-3`, `assemblyai/best`.
+
+**Formatos admitidos:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+
+---
+
+## Compatibilidad con Ollama
+
+Para clientes que utilizan el formato API de Ollama:
+
+```bash
+# Chat endpoint (Ollama format)
+POST /v1/api/chat
+
+# Model listing (Ollama format)
+GET /api/tags
+```
+
+Las solicitudes se traducen automáticamente entre Ollama y los formatos internos.
+
+---
+
+## Telemetría
+
+```bash
+# Get latency telemetry summary (p50/p95/p99 per provider)
+GET /api/telemetry/summary
+```
+
+**Respuesta:**
+
+```json
+{
+  "providers": {
+    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
+    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
+  }
+}
+```
+
+---
+
+## Presupuesto
+
+```bash
+# Get budget status for all API keys
+GET /api/usage/budget
+
+# Set or update a budget
+POST /api/usage/budget
+Content-Type: application/json
+
+{
+  "keyId": "key-123",
+  "limit": 50.00,
+  "period": "monthly"
+}
+```
+
+---
+
+## Disponibilidad del modelo
+
+```bash
+# Get real-time model availability across all providers
+GET /api/models/availability
+
+# Check availability for a specific model
+POST /api/models/availability
+Content-Type: application/json
+
+{
+  "model": "claude-sonnet-4-5-20250929"
+}
+```
+
+---
+
+## Procesamiento de solicitudes
+
+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.
+
+Referencia de arquitectura completa: [link](ARCHITECTURE.md)
+
+---
+
+## Autenticación
+
+- 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`

docs/i18n/es/ARCHITECTURE.md

@@ -0,0 +1,781 @@
+# Arquitectura OmniRoute
+
+🌐 **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_
+
+## Resumen ejecutivo
+
+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.
+
+Capacidades principales:
+
+- 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/`)
+
+Modelo de tiempo de ejecución principal:
+
+- 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.
+
+## Alcance y límites
+
+### En alcance
+
+- 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
+
+### Fuera de alcance
+
+- 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.)
+
+## Contexto del sistema de alto nivel
+
+```mermaid
+flowchart LR
+    subgraph Clients[Developer Clients]
+        C1[Claude Code]
+        C2[Codex CLI]
+        C3[OpenClaw / Droid / Cline / Continue / Roo]
+        C4[Custom OpenAI-compatible clients]
+        BROWSER[Browser Dashboard]
+    end
+
+    subgraph Router[OmniRoute Local Process]
+        API[V1 Compatibility API\n/v1/*]
+        DASH[Dashboard + Management API\n/api/*]
+        CORE[SSE + Translation Core\nopen-sse + src/sse]
+        DB[(db.json)]
+        UDB[(usage.json + log.txt)]
+    end
+
+    subgraph Upstreams[Upstream Providers]
+        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity]
+        P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
+        P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
+    end
+
+    subgraph Cloud[Optional Cloud Sync]
+        CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL]
+    end
+
+    C1 --> API
+    C2 --> API
+    C3 --> API
+    C4 --> API
+    BROWSER --> DASH
+
+    API --> CORE
+    DASH --> DB
+    CORE --> DB
+    CORE --> UDB
+
+    CORE --> P1
+    CORE --> P2
+    CORE --> P3
+
+    DASH --> CLOUD
+```
+
+## Componentes principales del tiempo de ejecución
+
+## 1) API y capa de enrutamiento (rutas de la aplicación Next.js)
+
+Directorios principales:
+
+- `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/*`
+
+Rutas de compatibilidad importantes:
+
+- `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/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/v1beta/models/route.ts`
+- `src/app/api/v1beta/models/[...path]/route.ts`
+
+Dominios de gestión:
+
+- 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)
+- 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)
+
+## 2) SSE + Núcleo de traducción
+
+Módulos de flujo principales:
+
+- 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`
+
+Servicios (lógica de negocios):
+
+- 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`
+
+Módulos de capa de dominio:
+
+- 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
+
+Módulos del proveedor OAuth (12 archivos individuales bajo `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
+
+## 3) Capa de persistencia
+
+BD de estado primario:
+
+- `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**
+
+Base de datos de uso:
+
+- `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`
+
+Base de datos de estado de dominio (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.
+
+## 4) Autenticación + Superficies de seguridad
+
+- 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)
+
+## 5) Sincronización en la nube
+
+- 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`
+
+## Solicitar ciclo de vida (`/v1/chat/completions`)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as CLI/SDK Client
+    participant Route as /api/v1/chat/completions
+    participant Chat as src/sse/handlers/chat
+    participant Core as open-sse/handlers/chatCore
+    participant Model as Model Resolver
+    participant Auth as Credential Selector
+    participant Exec as Provider Executor
+    participant Prov as Upstream Provider
+    participant Stream as Stream Translator
+    participant Usage as usageDb
+
+    Client->>Route: POST /v1/chat/completions
+    Route->>Chat: handleChat(request)
+    Chat->>Model: parse/resolve model or combo
+
+    alt Combo model
+        Chat->>Chat: iterate combo models (handleComboChat)
+    end
+
+    Chat->>Auth: getProviderCredentials(provider)
+    Auth-->>Chat: active account + tokens/api key
+
+    Chat->>Core: handleChatCore(body, modelInfo, credentials)
+    Core->>Core: detect source format
+    Core->>Core: translate request to target format
+    Core->>Exec: execute(provider, transformedBody)
+    Exec->>Prov: upstream API call
+    Prov-->>Exec: SSE/JSON response
+    Exec-->>Core: response + metadata
+
+    alt 401/403
+        Core->>Exec: refreshCredentials()
+        Exec-->>Core: updated tokens
+        Core->>Exec: retry request
+    end
+
+    Core->>Stream: translate/normalize stream to client format
+    Stream-->>Client: SSE chunks / JSON response
+
+    Stream->>Usage: extract usage + persist history/log
+```
+
+## Combo + Flujo alternativo de cuenta
+
+```mermaid
+flowchart TD
+    A[Incoming model string] --> B{Is combo name?}
+    B -- Yes --> C[Load combo models sequence]
+    B -- No --> D[Single model path]
+
+    C --> E[Try model N]
+    E --> F[Resolve provider/model]
+    D --> F
+
+    F --> G[Select account credentials]
+    G --> H{Credentials available?}
+    H -- No --> I[Return provider unavailable]
+    H -- Yes --> J[Execute request]
+
+    J --> K{Success?}
+    K -- Yes --> L[Return response]
+    K -- No --> M{Fallback-eligible error?}
+
+    M -- No --> N[Return error]
+    M -- Yes --> O[Mark account unavailable cooldown]
+    O --> P{Another account for provider?}
+    P -- Yes --> G
+    P -- No --> Q{In combo with next model?}
+    Q -- Yes --> E
+    Q -- No --> R[Return all unavailable]
+```
+
+Las decisiones alternativas están impulsadas por `open-sse/services/accountFallback.ts` utilizando códigos de estado y heurísticas de mensajes de error.
+
+## Incorporación de OAuth y ciclo de vida de actualización de tokens
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Dashboard UI
+    participant OAuth as /api/oauth/[provider]/[action]
+    participant ProvAuth as Provider Auth Server
+    participant DB as localDb
+    participant Test as /api/providers/[id]/test
+    participant Exec as Provider Executor
+
+    UI->>OAuth: GET authorize or device-code
+    OAuth->>ProvAuth: create auth/device flow
+    ProvAuth-->>OAuth: auth URL or device code payload
+    OAuth-->>UI: flow data
+
+    UI->>OAuth: POST exchange or poll
+    OAuth->>ProvAuth: token exchange/poll
+    ProvAuth-->>OAuth: access/refresh tokens
+    OAuth->>DB: createProviderConnection(oauth data)
+    OAuth-->>UI: success + connection id
+
+    UI->>Test: POST /api/providers/[id]/test
+    Test->>Exec: validate credentials / optional refresh
+    Exec-->>Test: valid or refreshed token info
+    Test->>DB: update status/tokens/errors
+    Test-->>UI: validation result
+```
+
+La actualización durante el tráfico en vivo se ejecuta dentro de `open-sse/handlers/chatCore.ts` a través del ejecutor `refreshCredentials()`.
+
+## Ciclo de vida de sincronización en la nube (activar/sincronizar/desactivar)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Endpoint Page UI
+    participant Sync as /api/sync/cloud
+    participant DB as localDb
+    participant Cloud as External Cloud Sync
+    participant Claude as ~/.claude/settings.json
+
+    UI->>Sync: POST action=enable
+    Sync->>DB: set cloudEnabled=true
+    Sync->>DB: ensure API key exists
+    Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys)
+    Cloud-->>Sync: sync result
+    Sync->>Cloud: GET /{machineId}/v1/verify
+    Sync-->>UI: enabled + verification status
+
+    UI->>Sync: POST action=sync
+    Sync->>Cloud: POST /sync/{machineId}
+    Cloud-->>Sync: remote data
+    Sync->>DB: update newer local tokens/status
+    Sync-->>UI: synced
+
+    UI->>Sync: POST action=disable
+    Sync->>DB: set cloudEnabled=false
+    Sync->>Cloud: DELETE /sync/{machineId}
+    Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed)
+    Sync-->>UI: disabled
+```
+
+La sincronización periódica la activa `CloudSyncScheduler` cuando la nube está habilitada.
+
+## Modelo de datos y mapa de almacenamiento
+
+```mermaid
+erDiagram
+    SETTINGS ||--o{ PROVIDER_CONNECTION : controls
+    PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider
+    PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage
+
+    SETTINGS {
+      boolean cloudEnabled
+      number stickyRoundRobinLimit
+      boolean requireLogin
+      string password_hash
+      string fallbackStrategy
+      json rateLimitDefaults
+      json providerProfiles
+    }
+
+    PROVIDER_CONNECTION {
+      string id
+      string provider
+      string authType
+      string name
+      number priority
+      boolean isActive
+      string apiKey
+      string accessToken
+      string refreshToken
+      string expiresAt
+      string testStatus
+      string lastError
+      string rateLimitedUntil
+      json providerSpecificData
+    }
+
+    PROVIDER_NODE {
+      string id
+      string type
+      string name
+      string prefix
+      string apiType
+      string baseUrl
+    }
+
+    MODEL_ALIAS {
+      string alias
+      string targetModel
+    }
+
+    COMBO {
+      string id
+      string name
+      string[] models
+    }
+
+    API_KEY {
+      string id
+      string name
+      string key
+      string machineId
+    }
+
+    USAGE_ENTRY {
+      string provider
+      string model
+      number prompt_tokens
+      number completion_tokens
+      string connectionId
+      string timestamp
+    }
+
+    CUSTOM_MODEL {
+      string id
+      string name
+      string providerId
+    }
+
+    PROXY_CONFIG {
+      string global
+      json providers
+    }
+
+    IP_FILTER {
+      string mode
+      string[] allowlist
+      string[] blocklist
+    }
+
+    THINKING_BUDGET {
+      string mode
+      number customBudget
+      string effortLevel
+    }
+
+    SYSTEM_PROMPT {
+      boolean enabled
+      string prompt
+      string position
+    }
+```
+
+Archivos de almacenamiento físico:
+
+- 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/...`
+
+## Topología de implementación
+
+```mermaid
+flowchart LR
+    subgraph LocalHost[Developer Host]
+        CLI[CLI Tools]
+        Browser[Dashboard Browser]
+    end
+
+    subgraph ContainerOrProcess[OmniRoute Runtime]
+        Next[Next.js Server\nPORT=20128]
+        Core[SSE Core + Executors]
+        MainDB[(db.json)]
+        UsageDB[(usage.json/log.txt)]
+    end
+
+    subgraph External[External Services]
+        Providers[AI Providers]
+        SyncCloud[Cloud Sync Service]
+    end
+
+    CLI --> Next
+    Browser --> Next
+    Next --> Core
+    Next --> MainDB
+    Core --> MainDB
+    Core --> UsageDB
+    Core --> Providers
+    Next --> SyncCloud
+```
+
+## Mapeo de módulos (de decisión crítica)
+
+### Módulos de ruta y API
+
+- `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)
+
+### Núcleo de enrutamiento y ejecución
+
+- `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
+
+### Registro de traducción y convertidores de formato
+
+- `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`
+
+### Persistencia
+
+- `src/lib/localDb.ts`: configuración/estado persistente
+- `src/lib/usageDb.ts`: historial de uso y registros continuos de solicitudes
+
+## Cobertura del Ejecutor del Proveedor (Patrón de Estrategia)
+
+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()`.
+
+| 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                                              |
+
+Todos los demás proveedores (incluidos los nodos compatibles personalizados) utilizan `DefaultExecutor`.
+
+## Matriz de compatibilidad de proveedores
+
+| 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                          | ✅                          | ✅              | ❌                     | ❌                        |
+
+## Cobertura de traducción de formato
+
+Los formatos de origen detectados incluyen:
+
+- `openai`
+- `openai-responses`
+- `claude`
+- `gemini`
+
+Los formatos de destino incluyen:
+
+- Chat/Respuestas de OpenAI
+- Claudio
+- Géminis/Gemini-CLI/sobre antigravedad
+  -Kiro
+- Cursores
+
+Las traducciones utilizan **OpenAI como formato central**; todas las conversiones pasan por OpenAI como formato intermedio:
+
+```
+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.
+
+Capas de procesamiento adicionales en el proceso de traducción:
+
+- **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.
+
+## Puntos finales API compatibles
+
+| 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                  |
+
+## Controlador de omisión
+
+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`.
+
+## Solicitar canalización de registro
+
+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`:
+
+```
+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.
+
+## Modos de falla y resiliencia
+
+## 1) Disponibilidad de cuenta/proveedor
+
+- 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
+
+## 2) Caducidad del token
+
+- 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
+
+## 3) Seguridad de la transmisión
+
+- 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
+
+## 4) Degradación de la sincronización en la nube
+
+- 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.
+
+## 5) Integridad de los datos
+
+- Migración/reparación de forma de base de datos por claves faltantes
+- salvaguardias de restablecimiento de JSON corruptas para localDb y useDb
+
+## Observabilidad y señales operativas
+
+Fuentes de visibilidad en tiempo de ejecución:
+
+- 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
+
+## Límites sensibles a la seguridad
+
+- 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
+
+## Matriz de entorno y tiempo de ejecución
+
+Variables de entorno utilizadas activamente por el código:
+
+- 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`
+
+## Notas arquitectónicas conocidas
+
+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).
+
+## Lista de verificación de verificación operativa
+
+- Compilación desde la fuente: `npm run build`
+- Crear imagen de Docker: `docker build -t omniroute .`
+- Iniciar el servicio y verificar:
+- `GET /api/settings`
+- `GET /api/v1/models`
+- La URL base de destino de CLI debe ser `http://<host>:20128/v1` cuando `PORT=20128`

docs/i18n/es/CODEBASE_DOCUMENTATION.md

@@ -0,0 +1,589 @@
+# 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**.
+
+---
+
+## 1. ¿Qué es omniruta?
+
+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:
+
+> **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.
+
+---
+
+## 2. Descripción general de la arquitectura
+
+```mermaid
+graph LR
+    subgraph Clients
+        A[Claude CLI]
+        B[Codex]
+        C[Cursor IDE]
+        D[OpenAI-compatible]
+    end
+
+    subgraph omniroute
+        E[Handler Layer]
+        F[Translator Layer]
+        G[Executor Layer]
+        H[Services Layer]
+    end
+
+    subgraph Providers
+        I[Anthropic Claude]
+        J[Google Gemini]
+        K[OpenAI / Codex]
+        L[GitHub Copilot]
+        M[AWS Kiro]
+        N[Antigravity]
+        O[Cursor API]
+    end
+
+    A --> E
+    B --> E
+    C --> E
+    D --> E
+    E --> F
+    F --> G
+    G --> I
+    G --> J
+    G --> K
+    G --> L
+    G --> M
+    G --> N
+    G --> O
+    H -.-> E
+    H -.-> G
+```
+
+### Principio básico: traducción radial
+
+Toda la traducción de formatos pasa a través del **formato OpenAI como centro**:
+
+```
+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).
+
+---
+
+## 3. Estructura del proyecto
+
+```
+omniroute/
+├── open-sse/                  ← Core proxy library (portable, framework-agnostic)
+│   ├── index.js               ← Main entry point, exports everything
+│   ├── config/                ← Configuration & constants
+│   ├── executors/             ← Provider-specific request execution
+│   ├── handlers/              ← Request handling orchestration
+│   ├── services/              ← Business logic (auth, models, fallback, usage)
+│   ├── translator/            ← Format translation engine
+│   │   ├── request/           ← Request translators (8 files)
+│   │   ├── response/          ← Response translators (7 files)
+│   │   └── helpers/           ← Shared translation utilities (6 files)
+│   └── utils/                 ← Utility functions
+├── src/                       ← Application layer (Express/Worker runtime)
+│   ├── app/                   ← Web UI, API routes, middleware
+│   ├── lib/                   ← Database, auth, and shared library code
+│   ├── mitm/                  ← Man-in-the-middle proxy utilities
+│   ├── models/                ← Database models
+│   ├── shared/                ← Shared utilities (wrappers around open-sse)
+│   ├── sse/                   ← SSE endpoint handlers
+│   └── store/                 ← State management
+├── data/                      ← Runtime data (credentials, logs)
+│   └── provider-credentials.json   (external credentials override, gitignored)
+└── tester/                    ← Test utilities
+```
+
+---
+
+## 4. Desglose módulo por módulo
+
+### 4.1 Configuración (`open-sse/config/`)
+
+La **única fuente de verdad** para todas las configuraciones de proveedores.
+
+| 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).                                                                                                                                                                          |
+
+#### Flujo de carga de credenciales
+
+```mermaid
+flowchart TD
+    A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"]
+    B --> C{"data/provider-credentials.json\nexists?"}
+    C -->|Yes| D["credentialLoader reads JSON"]
+    C -->|No| E["Use hardcoded defaults"]
+    D --> F{"For each provider in JSON"}
+    F --> G{"Provider exists\nin PROVIDERS?"}
+    G -->|No| H["Log warning, skip"]
+    G -->|Yes| I{"Value is object?"}
+    I -->|No| J["Log warning, skip"]
+    I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"]
+    K --> F
+    H --> F
+    J --> F
+    F -->|Done| L["PROVIDERS ready with\nmerged credentials"]
+    E --> L
+```
+
+---
+
+### 4.2 Ejecutores (`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.
+
+```mermaid
+classDiagram
+    class BaseExecutor {
+        +buildUrl(model, stream, options)
+        +buildHeaders(credentials, stream, body)
+        +transformRequest(body, model, stream, credentials)
+        +execute(url, options)
+        +shouldRetry(status, error)
+        +refreshCredentials(credentials, log)
+    }
+
+    class DefaultExecutor {
+        +refreshCredentials()
+    }
+
+    class AntigravityExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +shouldRetry()
+        +refreshCredentials()
+    }
+
+    class CursorExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseResponse()
+        +generateChecksum()
+    }
+
+    class KiroExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseEventStream()
+        +refreshCredentials()
+    }
+
+    BaseExecutor <|-- DefaultExecutor
+    BaseExecutor <|-- AntigravityExecutor
+    BaseExecutor <|-- CursorExecutor
+    BaseExecutor <|-- KiroExecutor
+    BaseExecutor <|-- CodexExecutor
+    BaseExecutor <|-- GeminiCLIExecutor
+    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                                                                     |
+
+---
+
+### 4.3 Controladores (`open-sse/handlers/`)
+
+La **capa de orquestación**: coordina la traducción, la ejecución, la transmisión y el manejo de errores.
+
+| 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.                                                 |
+
+#### Solicitar ciclo de vida (chatCore.ts)
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant chatCore
+    participant Translator
+    participant Executor
+    participant Provider
+
+    Client->>chatCore: Request (any format)
+    chatCore->>chatCore: Detect source format
+    chatCore->>chatCore: Check bypass patterns
+    chatCore->>chatCore: Resolve model & provider
+    chatCore->>Translator: Translate request (source → OpenAI → target)
+    chatCore->>Executor: Get executor for provider
+    Executor->>Executor: Build URL, headers, transform request
+    Executor->>Executor: Refresh credentials if needed
+    Executor->>Provider: HTTP fetch (streaming or non-streaming)
+
+    alt Streaming
+        Provider-->>chatCore: SSE stream
+        chatCore->>chatCore: Pipe through SSE transform stream
+        Note over chatCore: Transform stream translates<br/>each chunk: target → OpenAI → source
+        chatCore-->>Client: Translated SSE stream
+    else Non-streaming
+        Provider-->>chatCore: JSON response
+        chatCore->>Translator: Translate response
+        chatCore-->>Client: Translated JSON
+    end
+
+    alt Error (401, 429, 500...)
+        chatCore->>Executor: Retry with credential refresh
+        chatCore->>chatCore: Account fallback logic
+    end
+```
+
+---
+
+### 4.4 Servicios (`open-sse/services/`)
+
+Lógica de negocios que soporta a los manejadores y ejecutores.
+
+| 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.                                                                                                                                                                                                                       |
+
+#### Deduplicación de actualización de tokens
+
+```mermaid
+sequenceDiagram
+    participant R1 as Request 1
+    participant R2 as Request 2
+    participant Cache as refreshPromiseCache
+    participant OAuth as OAuth Provider
+
+    R1->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: No in-flight promise
+    Cache->>OAuth: Start refresh
+    R2->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: Found in-flight promise
+    Cache-->>R2: Return existing promise
+    OAuth-->>Cache: New access token
+    Cache-->>R1: New access token
+    Cache-->>R2: Same access token (shared)
+    Cache->>Cache: Delete cache entry
+```
+
+#### Máquina de estado de reserva de cuenta
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active
+    Active --> Error: Request fails (401/429/500)
+    Error --> Cooldown: Apply backoff
+    Cooldown --> Active: Cooldown expires
+    Active --> Active: Request succeeds (reset backoff)
+
+    state Error {
+        [*] --> ClassifyError
+        ClassifyError --> ShouldFallback: Rate limit / Auth / Transient
+        ClassifyError --> NoFallback: 400 Bad Request
+    }
+
+    state Cooldown {
+        [*] --> ExponentialBackoff
+        ExponentialBackoff: Level 0 = 1s
+        ExponentialBackoff: Level 1 = 2s
+        ExponentialBackoff: Level 2 = 4s
+        ExponentialBackoff: Max = 2min
+    }
+```
+
+#### Cadena de modelo combinado
+
+```mermaid
+flowchart LR
+    A["Request with\ncombo model"] --> B["Model A"]
+    B -->|"2xx Success"| C["Return response"]
+    B -->|"429/401/500"| D{"Fallback\neligible?"}
+    D -->|Yes| E["Model B"]
+    D -->|No| F["Return error"]
+    E -->|"2xx Success"| C
+    E -->|"429/401/500"| G{"Fallback\neligible?"}
+    G -->|Yes| H["Model C"]
+    G -->|No| F
+    H -->|"2xx Success"| C
+    H -->|"Fail"| I["All failed →\nReturn last status"]
+```
+
+---
+
+### 4.5 Traductor (`open-sse/translator/`)
+
+El **motor de traducción de formatos** que utiliza un sistema de complementos de registro automático.
+
+#### Arquitectura
+
+```mermaid
+graph TD
+    subgraph "Request Translation"
+        A["Claude → OpenAI"]
+        B["Gemini → OpenAI"]
+        C["Antigravity → OpenAI"]
+        D["OpenAI Responses → OpenAI"]
+        E["OpenAI → Claude"]
+        F["OpenAI → Gemini"]
+        G["OpenAI → Kiro"]
+        H["OpenAI → Cursor"]
+    end
+
+    subgraph "Response Translation"
+        I["Claude → OpenAI"]
+        J["Gemini → OpenAI"]
+        K["Kiro → OpenAI"]
+        L["Cursor → OpenAI"]
+        M["OpenAI → Claude"]
+        N["OpenAI → Antigravity"]
+        O["OpenAI → Responses"]
+    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`.                                                                                                                                                                                                     |
+
+#### Diseño de claves: complementos de registro automático
+
+```javascript
+// Each translator file calls register() on import:
+import { register } from "../index.js";
+register("claude", "openai", translateClaudeToOpenAI);
+
+// The index.js imports all translator files, triggering registration:
+import "./request/claude-to-openai.js"; // ← self-registers
+```
+
+---
+
+### 4.6 Utilidades (`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.                                                                               |
+
+#### Tubería de transmisión de SSE
+
+```mermaid
+flowchart TD
+    A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"]
+    B --> C["Buffer lines\n(split on newline)"]
+    C --> D["parseSSELine()\n(trim whitespace, parse JSON)"]
+    D --> E{"Mode?"}
+    E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"]
+    E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"]
+    F --> H["hasValuableContent()\nfilter empty chunks"]
+    G --> H
+    H -->|"Has content"| I["extractUsage()\ntrack token counts"]
+    H -->|"Empty"| J["Skip chunk"]
+    I --> K["formatSSE()\nserialize + clean perf_metrics"]
+    K --> L["TextEncoder\n(per-stream instance)"]
+    L --> M["Enqueue to\nclient stream"]
+
+    style A fill:#f9f,stroke:#333
+    style M fill:#9f9,stroke:#333
+```
+
+#### Solicitar estructura de sesión del registrador
+
+```
+logs/
+└── claude_gemini_claude-sonnet_20260208_143045/
+    ├── 1_req_client.json      ← Raw client request
+    ├── 2_req_source.json      ← After initial conversion
+    ├── 3_req_openai.json      ← OpenAI intermediate format
+    ├── 4_req_target.json      ← Final target format
+    ├── 5_res_provider.txt     ← Provider SSE chunks (streaming)
+    ├── 5_res_provider.json    ← Provider response (non-streaming)
+    ├── 6_res_openai.txt       ← OpenAI intermediate chunks
+    ├── 7_res_client.txt       ← Client-facing SSE chunks
+    └── 6_error.json           ← Error details (if any)
+```
+
+---
+
+### 4.7 Capa de aplicación (`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                                                                   |
+
+#### Rutas API notables
+
+| 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                                                                        |
+
+---
+
+## 5. Patrones de diseño clave
+
+### 5.1 Traducción radial
+
+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.
+
+### 5.2 Patrón de estrategia del ejecutor
+
+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.
+
+### 5.3 Sistema de complementos de autorregistro
+
+Los módulos traductores se registran al importar a través de `register()`. Agregar un nuevo traductor es simplemente crear un archivo e importarlo.
+
+### 5.4 Reserva de cuenta con retroceso exponencial
+
+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).
+
+### 5.5 Cadenas de modelos combinados
+
+Un "combo" agrupa varias cadenas `provider/model`. Si el primero falla, se pasa automáticamente al siguiente.
+
+### 5.6 Traducción de transmisión con estado
+
+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()`.
+
+### 5.7 Búfer de seguridad de uso
+
+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.
+
+---
+
+## 6. Formatos admitidos
+
+| 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`           |
+
+---
+
+## 7. Proveedores admitidos
+
+| 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           |
+
+---
+
+## 8. Resumen del flujo de datos
+
+### Solicitud de transmisión
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor\nbuildUrl + buildHeaders"]
+    D --> E["fetch(providerURL)"]
+    E --> F["createSSEStream()\nTRANSLATE mode"]
+    F --> G["parseSSELine()"]
+    G --> H["translateResponse()\ntarget → OpenAI → source"]
+    H --> I["extractUsage()\n+ addBuffer"]
+    I --> J["formatSSE()"]
+    J --> K["Client receives\ntranslated SSE"]
+    K --> L["logUsage()\nsaveRequestUsage()"]
+```
+
+### Solicitud sin transmisión
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor.execute()"]
+    D --> E["translateResponse()\ntarget → OpenAI → source"]
+    E --> F["Return JSON\nresponse"]
+```
+
+### Flujo de derivación (Claude CLI)
+
+```mermaid
+flowchart LR
+    A["Claude CLI request"] --> B{"Match bypass\npattern?"}
+    B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"]
+    B -->|"No match"| D["Normal flow"]
+    C --> E["Translate to\nsource format"]
+    E --> F["Return without\ncalling provider"]
+```

docs/i18n/es/FEATURES.md

@@ -0,0 +1,77 @@
+# 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.
+
+---
+
+## 🔌 Proveedores
+
+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).
+
+![Providers Dashboard](screenshots/01-providers.png)
+
+---
+
+## 🎨Combinaciones
+
+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.
+
+![Combos Dashboard](screenshots/02-combos.png)
+
+---
+
+## 📊 Análisis
+
+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.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
+
+---
+
+## 🏥 Salud del sistema
+
+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.
+
+![Health Dashboard](screenshots/04-health.png)
+
+---
+
+## 🔧 Patio de juegos del traductor
+
+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).
+
+![Translator Playground](screenshots/05-translator.png)
+
+---
+
+## ⚙️ Configuración
+
+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.
+
+![Settings Dashboard](screenshots/06-settings.png)
+
+---
+
+## 🔧 Herramientas CLI
+
+Configuración con un clic para herramientas de codificación de IA: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code y Antigravity.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+
+---
+
+## 📝 Solicitar registros
+
+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.
+
+![Usage Logs](screenshots/08-usage.png)
+
+---
+
+## 🌐 Punto final API
+
+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.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)

docs/i18n/es/TROUBLESHOOTING.md

@@ -0,0 +1,219 @@
+# Solución de problemas
+
+🌐 **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)
+
+Problemas comunes y soluciones para OmniRoute.
+
+---
+
+## Soluciones rápidas
+
+| Problema                                   | Solución                                                                                       |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| El primer inicio de sesión no funciona     | Marque `INITIAL_PASSWORD` en `.env` (predeterminado: `123456`)                                 |
+| El panel se abre en el puerto incorrecto   | Establecer `PORT=20128` y `NEXT_PUBLIC_BASE_URL=http://localhost:20128`                        |
+| No hay registros de solicitudes en `logs/` | Establecer `ENABLE_REQUEST_LOGS=true`                                                          |
+| EACCES: permiso denegado                   | Establezca `DATA_DIR=/path/to/writable/dir` para anular `~/.omniroute`                         |
+| La estrategia de enrutamiento no se guarda | Actualización a v1.4.11+ (corrección del esquema Zod para la persistencia de la configuración) |
+
+---
+
+## Problemas con el proveedor
+
+### "El modelo de idioma no proporcionó mensajes"
+
+**Causa:** Cuota de proveedor agotada.
+
+**Arreglo:**
+
+1. Verifique el rastreador de cuotas del panel
+2. Utilice un combo con niveles alternativos
+3. Cambiar al nivel más barato/gratuito
+
+### Limitación de velocidad
+
+**Causa:** Cuota de suscripción agotada.
+
+**Arreglo:**
+
+- Agregar respaldo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Utilice GLM/MiniMax como copia de seguridad económica
+
+### El token de OAuth ha caducado
+
+OmniRoute actualiza automáticamente los tokens. Si los problemas persisten:
+
+1. Panel de control → Proveedor → Reconectar
+2. Eliminar y volver a agregar la conexión del proveedor.
+
+---
+
+## Problemas con la nube
+
+### Errores de sincronización en la nube
+
+1. Verifique que `BASE_URL` apunte a su instancia en ejecución (por ejemplo, `http://localhost:20128`)
+2. Verifique que `CLOUD_URL` apunte a su punto final en la nube (por ejemplo, `https://omniroute.dev`).
+3. Mantenga los valores `NEXT_PUBLIC_*` alineados con los valores del lado del servidor
+
+### Nube `stream=false` Devuelve 500
+
+**Síntoma:** `Unexpected token 'd'...` en el punto final de la nube para llamadas que no son de transmisión.
+
+**Causa:** Upstream devuelve la carga útil SSE mientras que el cliente espera JSON.
+
+**Solución alternativa:** Utilice `stream=true` para llamadas directas en la nube. El tiempo de ejecución local incluye el respaldo SSE → JSON.
+
+### La nube dice Conectada pero "Clave API no válida"
+
+1. Cree una clave nueva desde el panel local (`/api/keys`)
+2. Ejecute la sincronización en la nube: Habilitar nube → Sincronizar ahora
+3. Las claves antiguas o no sincronizadas aún pueden devolver `401` en la nube
+
+---
+
+## Problemas con Docker
+
+### La herramienta CLI muestra no instalada
+
+1. Verifique los campos de tiempo de ejecución: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. Para el modo portátil: use el destino de imagen `runner-cli` (CLI incluidas)
+3. Para el modo de montaje del host: configure `CLI_EXTRA_PATHS` y monte el directorio bin del host como de solo lectura
+4. Si `installed=true` y `runnable=false`: se encontró el binario pero falló la verificación de estado
+
+### Validación rápida del tiempo de ejecución
+
+```bash
+curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+```
+
+---
+
+## Problemas de costos
+
+### Altos costos
+
+1. Verifique las estadísticas de uso en Panel → Uso
+2. Cambie el modelo principal a GLM/MiniMax
+3. Utilice el nivel gratuito (Gemini CLI, iFlow) para tareas no críticas
+4. Establezca presupuestos de costos por clave API: Panel → Claves API → Presupuesto
+
+---
+
+## Depuración
+
+### Habilitar registros de solicitudes
+
+Establezca `ENABLE_REQUEST_LOGS=true` en su archivo `.env`. Los registros aparecen en el directorio `logs/`.
+
+### Verificar el estado del proveedor
+
+```bash
+# Health dashboard
+http://localhost:20128/dashboard/health
+
+# API health check
+curl http://localhost:20128/api/monitoring/health
+```
+
+### Almacenamiento en tiempo de ejecución
+
+- Estado principal: `${DATA_DIR}/db.json` (proveedores, combos, alias, claves, configuraciones)
+- Uso: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
+- Solicitar registros: `<repo>/logs/...` (cuando `ENABLE_REQUEST_LOGS=true`)
+
+---
+
+## Problemas con el disyuntor
+
+### Proveedor atascado en estado ABIERTO
+
+Cuando el disyuntor de un proveedor está ABIERTO, las solicitudes se bloquean hasta que expire el tiempo de reutilización.
+
+**Arreglo:**
+
+1. Vaya a **Panel → Configuración → Resiliencia**
+2. Verifique la tarjeta del disyuntor del proveedor afectado.
+3. Haga clic en **Restablecer todo** para borrar todos los interruptores o espere a que expire el tiempo de reutilización.
+4. Verifique que el proveedor esté realmente disponible antes de restablecer
+
+### El proveedor sigue disparando el disyuntor
+
+Si un proveedor ingresa repetidamente al estado ABIERTO:
+
+1. Marque **Panel → Estado → Estado del proveedor** para ver el patrón de error.
+2. Vaya a **Configuración → Resiliencia → Perfiles de proveedores** y aumente el umbral de falla.
+3. Verifique si el proveedor ha cambiado los límites de API o requiere una nueva autenticación.
+4. Revise la telemetría de latencia: una latencia alta puede causar fallas basadas en el tiempo de espera
+
+---
+
+## Problemas de transcripción de audio
+
+### Error "Modelo no compatible"
+
+- Asegúrate de estar usando el prefijo correcto: `deepgram/nova-3` o `assemblyai/best`
+- Verifique que el proveedor esté conectado en **Panel → Proveedores**
+
+### La transcripción vuelve vacía o falla
+
+- Verifique los formatos de audio admitidos: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Verifique que el tamaño del archivo esté dentro de los límites del proveedor (normalmente < 25 MB)
+- Verifique la validez de la clave API del proveedor en la tarjeta del proveedor
+
+---
+
+## Depuración del traductor
+
+Utilice **Panel → Traductor** para depurar problemas de traducción de formato:
+
+| Modo                       | Cuándo utilizar                                                                                               |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| **Parque infantil**        | Compare formatos de entrada/salida uno al lado del otro: pegue una solicitud fallida para ver cómo se traduce |
+| **Probador de chat**       | Envíe mensajes en vivo e inspeccione la carga útil completa de solicitud/respuesta, incluidos los encabezados |
+| **Banco de pruebas**       | Ejecute pruebas por lotes en combinaciones de formatos para encontrar qué traducciones no funcionan           |
+| **Monitorización en vivo** | Observe el flujo de solicitudes en tiempo real para detectar problemas de traducción intermitentes            |
+
+### Problemas comunes de formato
+
+- **Las etiquetas de pensamiento no aparecen**: compruebe si el proveedor objetivo apoya el pensamiento y la configuración del presupuesto de pensamiento.
+- **Caídas de llamadas a herramientas**: algunas traducciones de formatos pueden eliminar campos no admitidos; verificar en modo Patio de Juegos
+- **Falta el mensaje del sistema**: Claude y Gemini manejan los mensajes del sistema de manera diferente; comprobar la salida de la traducción
+- **El SDK devuelve una cadena sin formato en lugar de un objeto** — Corregido en v1.1.0: el desinfectante de respuesta ahora elimina los campos no estándar (`x_groq`, `usage_breakdown`, etc.) que causan fallas de validación de Pydantic en el SDK de OpenAI
+- **GLM/ERNIE rechaza el rol `system`** — Corregido en v1.1.0: el normalizador de roles fusiona automáticamente los mensajes del sistema con mensajes de usuario para modelos incompatibles
+- **`developer` rol no reconocido** — Corregido en v1.1.0: convertido automáticamente a `system` para proveedores que no son OpenAI
+- **`json_schema` no funciona con Gemini** — Corregido en v1.1.0: `response_format` ahora se convierte a `responseMimeType` + `responseSchema` de Gemini
+
+---
+
+## Configuración de resiliencia
+
+### El límite de velocidad automático no se activa
+
+- El límite de velocidad automático solo se aplica a los proveedores de claves API (no a OAuth/suscripción)
+- Verifique que **Configuración → Resiliencia → Perfiles de proveedores** tenga habilitado el límite de tasa automática
+- Compruebe si el proveedor devuelve códigos de estado `429` o encabezados `Retry-After`
+
+### Ajuste del retroceso exponencial
+
+Los perfiles de proveedor admiten estas configuraciones:
+
+- **Retraso base**: tiempo de espera inicial después del primer fallo (predeterminado: 1 s)
+- **Retraso máximo**: límite máximo de tiempo de espera (predeterminado: 30 segundos)
+- **Multiplicador**: cuánto aumentar el retraso por falla consecutiva (predeterminado: 2x)
+
+### Manada anti-truenos
+
+Cuando muchas solicitudes simultáneas llegan a un proveedor de velocidad limitada, OmniRoute utiliza mutex + limitación de velocidad automática para serializar solicitudes y evitar fallas en cascada. Esto es automático para los proveedores de claves API.
+
+---
+
+## ¿Sigues atascado?
+
+- **Problemas de GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Arquitectura**: consulte [link](ARCHITECTURE.md) para obtener detalles internos
+- **Referencia de API**: consulte [link](API_REFERENCE.md) para conocer todos los puntos finales
+- **Panel de estado**: marque **Panel → Salud** para ver el estado del sistema en tiempo real
+- **Traductor**: use **Panel → Traductor** para depurar problemas de formato

docs/i18n/es/USER_GUIDE.md

@@ -0,0 +1,698 @@
+# Guía del usuario
+
+🌐 **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)
+
+Guía completa para configurar proveedores, crear combos, integrar herramientas CLI e implementar OmniRoute.
+
+---
+
+## Tabla de contenidos
+
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
+
+## 💰 Precios de un vistazo
+
+| Nivel              | Proveedor              | Costo                | Restablecer cuota             | Mejor para                  |
+| ------------------ | ---------------------- | -------------------- | ----------------------------- | --------------------------- |
+| **💳 SUSCRIPCIÓN** | Código Claude (Pro)    | $20/mes              | 5h + weekly                   | Ya suscrito                 |
+|                    | Códice (Plus/Pro)      | $20-200/mes          | 5h + semanales                | Usuarios de OpenAI          |
+|                    | Géminis CLI            | **GRATIS**           | 180K/mes + 1K/día             | ¡Todos!                     |
+|                    | Copiloto de GitHub     | $10-19/mes           | Mensual                       | Usuarios de GitHub          |
+| **🔑 CLAVE API**   | Búsqueda profunda      | Pago por uso         | Ninguno                       | Razonamiento barato         |
+|                    | Groq                   | Pago por uso         | Ninguno                       | Inferencia ultrarrápida     |
+|                    | xAI (Grok)             | Pago por uso         | Ninguno                       | Grok 4 razonamiento         |
+|                    | Mistral                | Pago por uso         | Ninguno                       | Modelos alojados en la UE   |
+|                    | Perplejidad            | Pago por uso         | Ninguno                       | Búsqueda aumentada          |
+|                    | Juntos IA              | Pago por uso         | Ninguno                       | Modelos de código abierto   |
+|                    | Fuegos artificiales AI | Pago por uso         | Ninguno                       | Imágenes de flujo rápido    |
+|                    | Cerebras               | Pago por uso         | None                          | Velocidad a escala de oblea |
+|                    | Coherir                | Pago por uso         | Ninguno                       | Comando R+ TRAPO            |
+|                    | NIM de NVIDIA          | Pago por uso         | Ninguno                       | Modelos empresariales       |
+| **💰 BARATO**      | GLM-4.7                | 0,6 dólares/1 millón | Todos los días a las 10 a. m. | Respaldo presupuestario     |
+|                    | MiniMax M2.1           | 0,2 dólares/1 millón | 5 horas rodantes              | Opción más barata           |
+|                    | Kimi K2                | $9/mes fijo          | 10 millones de tokens/mes     | Costo predecible            |
+| **🆓 GRATIS**      | iFlujo                 | $0                   | Ilimitado                     | 8 modelos gratis            |
+|                    | Qwen                   | $0                   | Ilimitado                     | 3 modelos gratis            |
+|                    | kiro                   | $0                   | Ilimitado                     | Claudio libre               |
+
+**💡 Consejo profesional:** Comience con el combo Gemini CLI (180 000 gratis/mes) + iFlow (ilimitado y gratis) = ¡Costo de $0!
+
+---
+
+## 🎯 Casos de uso
+
+### Caso 1: "Tengo una suscripción a Claude Pro"
+
+**Problema:** La cuota vence sin usarse, la tasa se limita durante la codificación intensa
+
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6        (use subscription fully)
+  2. glm/glm-4.7               (cheap backup when quota out)
+  3. if/kimi-k2-thinking       (free emergency fallback)
+
+Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
+vs. $20 + hitting limits = frustration
+```
+
+### Caso 2: "Quiero coste cero"
+
+**Problema:** No puedo permitirme suscripciones, necesito codificación de IA confiable
+
+```
+Combo: "free-forever"
+  1. gc/gemini-3-flash         (180K free/month)
+  2. if/kimi-k2-thinking       (unlimited free)
+  3. qw/qwen3-coder-plus       (unlimited free)
+
+Monthly cost: $0
+Quality: Production-ready models
+```
+
+### Caso 3: "Necesito codificación 24 horas al día, 7 días a la semana, sin interrupciones"
+
+**Problema:** Plazos, no puedo permitirme el tiempo de inactividad
+
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-6        (best quality)
+  2. cx/gpt-5.2-codex          (second subscription)
+  3. glm/glm-4.7               (cheap, resets daily)
+  4. minimax/MiniMax-M2.1      (cheapest, 5h reset)
+  5. if/kimi-k2-thinking       (free unlimited)
+
+Result: 5 layers of fallback = zero downtime
+Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
+```
+
+### Caso 4: "Quiero IA GRATIS en OpenClaw"
+
+**Problema:** Necesita asistente de IA en aplicaciones de mensajería, completamente gratis
+
+```
+Combo: "openclaw-free"
+  1. if/glm-4.7                (unlimited free)
+  2. if/minimax-m2.1           (unlimited free)
+  3. if/kimi-k2-thinking       (unlimited free)
+
+Monthly cost: $0
+Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+```
+
+---
+
+## 📖 Configuración del proveedor
+
+### 🔐 Proveedores de suscripción
+
+#### Código Claude (Pro/Max)
+
+```bash
+Dashboard → Providers → Connect Claude Code
+→ OAuth login → Auto token refresh
+→ 5-hour + weekly quota tracking
+
+Models:
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**Consejo profesional:** Utilice Opus para tareas complejas y Sonnet para mayor velocidad. ¡OmniRoute realiza un seguimiento de la cuota por modelo!
+
+#### Códice OpenAI (Plus/Pro)
+
+```bash
+Dashboard → Providers → Connect Codex
+→ OAuth login (port 1455)
+→ 5-hour + weekly reset
+
+Models:
+  cx/gpt-5.2-codex
+  cx/gpt-5.1-codex-max
+```
+
+#### Gemini CLI (¡180K GRATIS/mes!)
+
+```bash
+Dashboard → Providers → Connect Gemini CLI
+→ Google OAuth
+→ 180K completions/month + 1K/day
+
+Models:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**Mejor valor:** ¡Enorme nivel gratuito! Utilice esto antes de los niveles pagos.
+
+#### Copiloto de GitHub
+
+```bash
+Dashboard → Providers → Connect GitHub
+→ OAuth via GitHub
+→ Monthly reset (1st of month)
+
+Models:
+  gh/gpt-5
+  gh/claude-4.5-sonnet
+  gh/gemini-3-pro
+```
+
+### 💰 Proveedores baratos
+
+#### GLM-4.7 (Restablecimiento diario, $0,6/1 millón)
+
+1. Regístrate: [Zhipu AI](https://open.bigmodel.cn/)
+2. Obtenga la clave API del plan de codificación
+3. Panel de control → Agregar clave API: Proveedor: `glm`, Clave API: `your-key`
+
+**Uso:** `glm/glm-4.7` — **Consejo profesional:** ¡El plan de codificación ofrece 3 × cuota a 1/7 de costo! Reiniciar diariamente a las 10:00 a.m.
+
+#### MiniMax M2.1 (reinicio de 5 h, $0,20/1 millón)
+
+1. Regístrate: [MiniMax](https://www.minimax.io/)
+2. Obtener clave API → Panel → Agregar clave API
+
+**Uso:** `minimax/MiniMax-M2.1` — **Consejo profesional:** ¡La opción más barata para contexto largo (1 millón de tokens)!
+
+#### Kimi K2 ($9/mes fijo)
+
+1. Suscríbete: [Moonshot AI](https://platform.moonshot.ai/)
+2. Obtener clave API → Panel → Agregar clave API
+
+**Uso:** `kimi/kimi-latest` — **Consejo profesional:** ¡Fijo $9/mes por 10 millones de tokens = $0,90/1 millón de costo efectivo!
+
+### 🆓 Proveedores GRATIS
+
+#### iFlow (8 modelos GRATIS)
+
+```bash
+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 modelos GRATIS)
+
+```bash
+Dashboard → Connect Qwen → Device code auth → Unlimited usage
+
+Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
+```
+
+#### Kiro (Claude GRATIS)
+
+```bash
+Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
+
+Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
+```
+
+---
+
+## 🎨Combinaciones
+
+### Ejemplo 1: Maximizar la suscripción → Copia de seguridad económica
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-6 (Subscription primary)
+  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
+  3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
+
+Use in CLI: premium-coding
+```
+
+### Ejemplo 2: Solo gratuito (coste cero)
+
+```
+Name: free-combo
+Models:
+  1. gc/gemini-3-flash-preview (180K free/month)
+  2. if/kimi-k2-thinking (unlimited)
+  3. qw/qwen3-coder-plus (unlimited)
+
+Cost: $0 forever!
+```
+
+---
+
+## 🔧 Integración CLI
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from omniroute dashboard]
+  Model: cc/claude-opus-4-6
+```
+
+### Código Claude
+
+Editar `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-omniroute-api-key"
+}
+```
+
+### CLI del Códice
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-omniroute-api-key"
+codex "your prompt"
+```
+
+### Garra Abierta
+
+Editar `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": { "primary": "omniroute/if/glm-4.7" }
+    }
+  },
+  "models": {
+    "providers": {
+      "omniroute": {
+        "baseUrl": "http://localhost:20128/v1",
+        "apiKey": "your-omniroute-api-key",
+        "api": "openai-completions",
+        "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+      }
+    }
+  }
+}
+```
+
+**O use el Panel:** Herramientas CLI → OpenClaw → Configuración automática
+
+### Cline / Continuar / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-6
+```
+
+---
+
+## 🚀 Implementación
+
+### Implementación de VPS
+
+```bash
+git clone https://github.com/diegosouzapw/OmniRoute.git
+cd OmniRoute && npm install && npm run build
+
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+export DATA_DIR="/var/lib/omniroute"
+export PORT="20128"
+export HOSTNAME="0.0.0.0"
+export NODE_ENV="production"
+export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
+export API_KEY_SECRET="endpoint-proxy-api-key-secret"
+
+npm run start
+# Or: pm2 start npm --name omniroute -- start
+```
+
+### acoplador
+
+```bash
+# Build image (default = runner-cli with codex/claude/droid preinstalled)
+docker build -t omniroute:cli .
+
+# Portable mode (recommended)
+docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
+```
+
+Para el modo integrado en el host con binarios CLI, consulte la sección Docker en los documentos principales.
+
+### Variables de entorno
+
+| Variables             | Predeterminado                              | Descripción                                                              |
+| --------------------- | ------------------------------------------- | ------------------------------------------------------------------------ |
+| `JWT_SECRET`          | `omniroute-default-secret-change-me`        | Secreto de firma de JWT (**cambio en producción**)                       |
+| `INITIAL_PASSWORD`    | `123456`                                    | Primera contraseña de inicio de sesión                                   |
+| `DATA_DIR`            | `~/.omniroute`                              | Directorio de datos (db, uso, registros)                                 |
+| `PORT`                | marco predeterminado                        | Puerto de servicio (`20128` en ejemplos)                                 |
+| `HOSTNAME`            | marco predeterminado                        | Vincular host (Docker por defecto es `0.0.0.0`)                          |
+| `NODE_ENV`            | valor predeterminado de tiempo de ejecución | Establecer `production` para implementación                              |
+| `BASE_URL`            | `http://localhost:20128`                    | URL base interna del lado del servidor                                   |
+| `CLOUD_URL`           | `https://omniroute.dev`                     | URL base del punto final de sincronización en la nube                    |
+| `API_KEY_SECRET`      | `endpoint-proxy-api-key-secret`             | Secreto HMAC para claves API generadas                                   |
+| `REQUIRE_API_KEY`     | `false`                                     | Aplicar la clave API de portador en `/v1/*`                              |
+| `ENABLE_REQUEST_LOGS` | `false`                                     | Habilita registros de solicitud/respuesta                                |
+| `AUTH_COOKIE_SECURE`  | `false`                                     | Forzar cookie de autenticación `Secure` (detrás del proxy inverso HTTPS) |
+
+Para obtener la referencia completa de las variables de entorno, consulte [README](../README.md).
+
+---
+
+## 📊 Modelos disponibles
+
+<details>
+<summary><b>Ver todos los modelos disponibles</b></summary>
+
+**Código Claude (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+
+**Códice (`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`
+
+**Copilot de GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
+
+**GLM (`glm/`)** — 0,6 $/1 millón: `glm/glm-4.7`
+
+**MiniMax (`minimax/`)** — $0,2/1 millón: `minimax/MiniMax-M2.1`
+
+**iFlow (`if/`)** — GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+
+**Qwen (`qw/`)** — GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+
+**Kiro (`kr/`)** — GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+
+** Búsqueda profunda (`ds/`) **: `ds/deepseek-chat`, `ds/deepseek-reasoner`
+
+**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`
+
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
+
+**Perplejidad (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+
+**Juntos AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+
+**Fuegos artificiales AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
+
+**Coherir (`cohere/`)**: `cohere/command-r-plus-08-2024`
+
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+</details>
+
+---
+
+## 🧩 Funciones avanzadas
+
+### Modelos personalizados
+
+Agregue cualquier ID de modelo a cualquier proveedor sin esperar una actualización de la aplicación:
+
+```bash
+# Via API
+curl -X POST http://localhost:20128/api/provider-models \
+  -H "Content-Type: application/json" \
+  -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}'
+
+# List: curl http://localhost:20128/api/provider-models?provider=openai
+# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
+```
+
+O utilice el Panel de control: **Proveedores → [Proveedor] → Modelos personalizados**.
+
+### Rutas de proveedores dedicadas
+
+Enrutar solicitudes directamente a un proveedor específico con validación de modelo:
+
+```bash
+POST http://localhost:20128/v1/providers/openai/chat/completions
+POST http://localhost:20128/v1/providers/openai/embeddings
+POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
+
+El prefijo del proveedor se agrega automáticamente si falta. Los modelos no coincidentes devuelven `400`.
+
+### Configuración del proxy de red
+
+```bash
+# Set global proxy
+curl -X PUT http://localhost:20128/api/settings/proxy \
+  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
+
+# Per-provider proxy
+curl -X PUT http://localhost:20128/api/settings/proxy \
+  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
+
+# Test proxy
+curl -X POST http://localhost:20128/api/settings/proxy/test \
+  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
+```
+
+**Precedencia:** Específico de clave → Específico de combo → Específico de proveedor → Global → Entorno.
+
+### API del catálogo de modelos
+
+```bash
+curl http://localhost:20128/api/models/catalog
+```
+
+Devuelve modelos agrupados por proveedor con tipos (`chat`, `embedding`, `image`).
+
+### Sincronización en la nube
+
+- Sincronizar proveedores, combos y configuraciones entre dispositivos
+- Sincronización automática en segundo plano con tiempo de espera + falla rápida
+- Prefiere `BASE_URL`/`CLOUD_URL` del lado del servidor en producción
+
+### LLM Gateway Intelligence (Fase 9)
+
+- **Caché semántica**: cachés automáticos sin transmisión, temperatura = 0 respuestas (omitir con `X-OmniRoute-No-Cache: true`)
+- **Idempotencia de solicitud**: deduplica solicitudes en 5 segundos a través del encabezado `Idempotency-Key` o `X-Request-Id`
+- **Seguimiento del progreso**: suscripción a eventos SSE `event: progress` a través del encabezado `X-OmniRoute-Progress: true`
+
+---
+
+### Patio de juegos del traductor
+
+Acceda a través de **Panel → Traductor**. Depure y visualice cómo OmniRoute traduce las solicitudes de API entre proveedores.
+
+| Modo                       | Propósito                                                                                                      |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| **Parque infantil**        | Seleccione formatos de origen/destino, pegue una solicitud y vea el resultado traducido al instante            |
+| **Probador de chat**       | Envíe mensajes de chat en vivo a través del proxy e inspeccione el ciclo completo de solicitud/respuesta       |
+| **Banco de pruebas**       | Ejecute pruebas por lotes en múltiples combinaciones de formatos para verificar la corrección de la traducción |
+| **Monitorización en vivo** | Vea traducciones en tiempo real a medida que las solicitudes fluyen a través del proxy                         |
+
+**Casos de uso:**
+
+- Depurar por qué falla una combinación específica de cliente/proveedor
+- Verificar que las etiquetas de pensamiento, las llamadas a herramientas y las indicaciones del sistema se traduzcan correctamente
+- Compare las diferencias de formato entre los formatos OpenAI, Claude, Gemini y Responses API
+
+---
+
+### Estrategias de enrutamiento
+
+Configure a través de **Panel → Configuración → Enrutamiento**.
+
+| Estrategia                      | Descripción                                                                                                          |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| **Llene primero**               | Utiliza cuentas en orden de prioridad: la cuenta principal maneja todas las solicitudes hasta que no esté disponible |
+| **Round Robin**                 | Recorre todas las cuentas con un límite fijo configurable (predeterminado: 3 llamadas por cuenta)                    |
+| **P2C (Poder de dos opciones)** | Elige 2 cuentas al azar y ruta hacia la más saludable: los saldos se cargan con conciencia de la salud               |
+| **Aleatorio**                   | Selecciona aleatoriamente una cuenta para cada solicitud mediante la reproducción aleatoria de Fisher-Yates          |
+| **Menos usado**                 | Rutas a la cuenta con la marca de tiempo `lastUsedAt` más antigua, distribuyendo el tráfico de manera uniforme       |
+| **Costo optimizado**            | Rutas a la cuenta con el valor de prioridad más bajo, optimizando para proveedores de menor costo                    |
+
+#### Alias de modelo comodín
+
+Cree patrones comodín para reasignar nombres de modelos:
+
+```
+Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-*               →  Target: gh/gpt-5.1-codex
+```
+
+Los comodines admiten `*` (cualquier carácter) y `?` (un solo carácter).
+
+#### Cadenas de respaldo
+
+Defina cadenas de respaldo globales que se apliquen a todas las solicitudes:
+
+```
+Chain: production-fallback
+  1. cc/claude-opus-4-6
+  2. gh/gpt-5.1-codex
+  3. glm/glm-4.7
+```
+
+---
+
+### Resiliencia y disyuntores
+
+Configure a través de **Panel → Configuración → Resiliencia**.
+
+OmniRoute implementa resiliencia a nivel de proveedor con cuatro componentes:
+
+1. **Perfiles de proveedor**: configuración por proveedor para:
+   - Umbral de fallas (cuántas fallas antes de abrir)
+   - Duración del tiempo de recuperación
+   - Sensibilidad de detección de límite de velocidad
+   - Parámetros de retroceso exponencial
+
+2. **Límites de tarifas editables**: valores predeterminados a nivel del sistema configurables en el panel:
+   - **Solicitudes por minuto (RPM)**: solicitudes máximas por minuto por cuenta
+   - **Tiempo mínimo entre solicitudes**: intervalo mínimo en milisegundos entre solicitudes
+   - **Máximo de solicitudes simultáneas**: máximo de solicitudes simultáneas por cuenta
+   - Haga clic en **Editar** para modificar y luego en **Guardar** o **Cancelar**. Los valores persisten a través de la API de resiliencia.
+
+3. **Disyuntor**: realiza un seguimiento de las fallas por proveedor y abre automáticamente el circuito cuando se alcanza un umbral:
+   - **CERRADO** (En buen estado): las solicitudes fluyen normalmente
+   - **ABIERTO**: el proveedor está bloqueado temporalmente después de fallas repetidas
+   - **HALF_OPEN** — Probando si el proveedor se ha recuperado
+
+4. **Políticas e identificadores bloqueados**: muestra el estado del disyuntor y los identificadores bloqueados con capacidad de desbloqueo forzado.
+
+5. **Detección automática de límite de tasa**: monitorea los encabezados `429` y `Retry-After` para evitar de manera proactiva alcanzar los límites de tasa del proveedor.
+
+**Consejo profesional:** Utilice el botón **Restablecer todo** para borrar todos los disyuntores y tiempos de reutilización cuando un proveedor se recupera de una interrupción.
+
+---
+
+### Exportación/Importación de base de datos
+
+Administre las copias de seguridad de la base de datos en **Panel → Configuración → Sistema y almacenamiento**.
+
+| Acción                      | Descripción                                                                                                                                                                         |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Exportar base de datos**  | Descarga la base de datos SQLite actual como un archivo `.sqlite`                                                                                                                   |
+| **Exportar todo (.tar.gz)** | Descarga un archivo de copia de seguridad completo que incluye: base de datos, configuraciones, combinaciones, conexiones de proveedores (sin credenciales), metadatos de clave API |
+| **Importar base de datos**  | Cargue un archivo `.sqlite` para reemplazar la base de datos actual. Se crea automáticamente una copia de seguridad previa a la importación                                         |
+
+```bash
+# API: Export database
+curl -o backup.sqlite http://localhost:20128/api/db-backups/export
+
+# API: Export all (full archive)
+curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
+
+# API: Import database
+curl -X POST http://localhost:20128/api/db-backups/import \
+  -F "file=@backup.sqlite"
+```
+
+**Validación de importación:** Se valida la integridad del archivo importado (verificación de pragma de SQLite), las tablas requeridas (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) y el tamaño (máximo 100 MB).
+
+**Casos de uso:**
+
+- Migrar OmniRoute entre máquinas
+- Crear copias de seguridad externas para la recuperación de desastres.
+- Compartir configuraciones entre los miembros del equipo (exportar todo → compartir archivo)
+
+---
+
+### Panel de configuración
+
+La página de configuración está organizada en 5 pestañas para facilitar la navegación:
+
+| Pestaña          | Contenidos                                                                                                                        |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **Seguridad**    | Configuración de inicio de sesión/contraseña, control de acceso IP, autenticación API para `/models` y bloqueo de proveedores     |
+| **Enrutamiento** | Estrategia de enrutamiento global (6 opciones), alias de modelos comodín, cadenas de respaldo, valores predeterminados combinados |
+| **Resiliencia**  | Perfiles de proveedores, límites de tarifas editables, estado de los disyuntores, políticas e identificadores bloqueados          |
+| **IA**           | Pensando en la configuración del presupuesto, inyección de avisos del sistema global, estadísticas de caché de avisos             |
+| **Avanzado**     | Configuración de proxy global (HTTP/SOCKS5)                                                                                       |
+
+---
+
+### Gestión de costes y presupuesto
+
+Acceso a través de **Panel → Costos**.
+
+| Pestaña         | Propósito                                                                                                           |
+| --------------- | ------------------------------------------------------------------------------------------------------------------- |
+| **Presupuesto** | Establezca límites de gasto por clave API con presupuestos diarios/semanales/mensuales y seguimiento en tiempo real |
+| **Precios**     | Ver y editar entradas de precios de modelos: costo por 1.000 tokens de entrada/salida por proveedor                 |
+
+```bash
+# API: Set a budget
+curl -X POST http://localhost:20128/api/usage/budget \
+  -H "Content-Type: application/json" \
+  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
+
+# API: Get current budget status
+curl http://localhost:20128/api/usage/budget
+```
+
+**Seguimiento de costos:** Cada solicitud registra el uso del token y calcula el costo utilizando la tabla de precios. Vea desgloses en **Panel → Uso** por proveedor, modelo y clave API.
+
+---
+
+### Transcripción de audio
+
+OmniRoute admite la transcripción de audio a través del punto final compatible con OpenAI:
+
+```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+
+# Example with curl
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+  -H "Authorization: Bearer your-api-key" \
+  -F "file=@audio.mp3" \
+  -F "model=deepgram/nova-3"
+```
+
+Proveedores disponibles: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
+
+Formatos de audio admitidos: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+
+---
+
+### Estrategias de equilibrio combinadas
+
+Configure el equilibrio por combo en **Panel → Combos → Crear/Editar → Estrategia**.
+
+| Estrategia                 | Descripción                                                                                  |
+| -------------------------- | -------------------------------------------------------------------------------------------- |
+| **Todos contra todos**     | Gira a través de modelos secuencialmente                                                     |
+| **Prioridad**              | Siempre prueba el primer modelo; retrocede sólo en caso de error                             |
+| **Aleatorio**              | Elige un modelo aleatorio del combo para cada solicitud                                      |
+| **Ponderado**              | Rutas proporcionalmente en función de los pesos asignados por modelo                         |
+| **Menos usado**            | Rutas al modelo con la menor cantidad de solicitudes recientes (utiliza métricas combinadas) |
+| **Optimización de costos** | Rutas al modelo más barato disponible (utiliza tabla de precios)                             |
+
+Los valores predeterminados combinados globales se pueden configurar en **Panel → Configuración → Enrutamiento → Valores predeterminados combinados**.
+
+---
+
+### Panel de salud
+
+Accede a través de **Panel → Salud**. Descripción general del estado del sistema en tiempo real con 6 tarjetas:
+
+| Tarjeta                    | Lo que muestra                                                                    |
+| -------------------------- | --------------------------------------------------------------------------------- |
+| **Estado del sistema**     | Tiempo de actividad, versión, uso de memoria, directorio de datos                 |
+| **Salud del proveedor**    | Estado del disyuntor por proveedor (cerrado/abierto/medio abierto)                |
+| **Límites de tarifas**     | Tiempos de reutilización del límite de tasa activa por cuenta con tiempo restante |
+| **Bloqueos activos**       | Proveedores bloqueados temporalmente por la política de bloqueo                   |
+| **Caché de firma**         | Estadísticas de caché de deduplicación (claves activas, tasa de aciertos)         |
+| **Telemetría de latencia** | Agregación de latencia p50/p95/p99 por proveedor                                  |
+
+**Consejo profesional:** La página Salud se actualiza automáticamente cada 10 segundos. Utilice la tarjeta del disyuntor para identificar qué proveedores están experimentando problemas.

docs/i18n/fi/API_REFERENCE.md

@@ -0,0 +1,441 @@
+# API-viite
+
+🌐 **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)
+
+Täydellinen viite kaikille OmniRoute API -päätepisteille.
+
+---
+
+## Sisällysluettelo
+
+- [Chat Completions](#chat-completions)
+- [Embeddings](#embeddings)
+- [Image Generation](#image-generation)
+- [List Models](#list-models)
+- [Compatibility Endpoints](#compatibility-endpoints)
+- [Semantic Cache](#semantic-cache)
+- [Dashboard & Management](#dashboard--management)
+- [Request Processing](#request-processing)
+- [Authentication](#authentication)
+
+---
+
+## Chatin valmistuminen
+
+```bash
+POST /v1/chat/completions
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "cc/claude-opus-4-6",
+  "messages": [
+    {"role": "user", "content": "Write a function to..."}
+  ],
+  "stream": true
+}
+```
+
+### Mukautetut otsikot
+
+| Otsikko                  | Suunta  | Kuvaus                                    |
+| ------------------------ | ------- | ----------------------------------------- |
+| `X-OmniRoute-No-Cache`   | Pyyntö  | Aseta `true` ohittaaksesi välimuistin     |
+| `X-OmniRoute-Progress`   | Pyyntö  | Aseta arvoon `true` edistymistapahtumille |
+| `Idempotency-Key`        | Pyyntö  | Dedup-avain (5s ikkuna)                   |
+| `X-Request-Id`           | Pyyntö  | Vaihtoehtoinen dedup-avain                |
+| `X-OmniRoute-Cache`      | Vastaus | `HIT` tai `MISS` (ei suoratoistoa)        |
+| `X-OmniRoute-Idempotent` | Vastaus | `true` jos kopiointi poistetaan           |
+| `X-OmniRoute-Progress`   | Vastaus | `enabled` jos edistymisen seuranta on     |
+
+---
+
+## Upotukset
+
+```bash
+POST /v1/embeddings
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "nebius/Qwen/Qwen3-Embedding-8B",
+  "input": "The food was delicious"
+}
+```
+
+Saatavilla olevat toimittajat: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+
+```bash
+# List all embedding models
+GET /v1/embeddings
+```
+
+---
+
+## Kuvan luominen
+
+```bash
+POST /v1/images/generations
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "openai/dall-e-3",
+  "prompt": "A beautiful sunset over mountains",
+  "size": "1024x1024"
+}
+```
+
+Saatavilla olevat toimittajat: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+
+```bash
+# List all image models
+GET /v1/images/generations
+```
+
+---
+
+## Listaa mallit
+
+```bash
+GET /v1/models
+Authorization: Bearer your-api-key
+
+→ Returns all chat, embedding, and image models + combos in OpenAI format
+```
+
+---
+
+## Yhteensopivuuden päätepisteet
+
+| Menetelmä | Polku                       | Muoto                        |
+| --------- | --------------------------- | ---------------------------- |
+| POST      | `/v1/chat/completions`      | OpenAI                       |
+| POST      | `/v1/messages`              | Antrooppinen                 |
+| POST      | `/v1/responses`             | OpenAI-vastaukset            |
+| POST      | `/v1/embeddings`            | OpenAI                       |
+| POST      | `/v1/images/generations`    | OpenAI                       |
+| HANKI     | `/v1/models`                | OpenAI                       |
+| POST      | `/v1/messages/count_tokens` | Antrooppinen                 |
+| HANKI     | `/v1beta/models`            | Kaksoset                     |
+| POST      | `/v1beta/models/{...path}`  | Kaksoset generoivat sisältöä |
+| POST      | `/v1/api/chat`              | Ollama                       |
+
+### Palveluntarjoajan reitit
+
+```bash
+POST /v1/providers/{provider}/chat/completions
+POST /v1/providers/{provider}/embeddings
+POST /v1/providers/{provider}/images/generations
+```
+
+Palveluntarjoajan etuliite lisätään automaattisesti, jos se puuttuu. Yhteensopimattomat mallit palauttavat `400`.
+
+---
+
+## Semanttinen välimuisti
+
+```bash
+# Get cache stats
+GET /api/cache
+
+# Clear all caches
+DELETE /api/cache
+```
+
+Vastausesimerkki:
+
+```json
+{
+  "semanticCache": {
+    "memorySize": 42,
+    "memoryMaxSize": 500,
+    "dbSize": 128,
+    "hitRate": 0.65
+  },
+  "idempotency": {
+    "activeKeys": 3,
+    "windowMs": 5000
+  }
+}
+```
+
+---
+
+## Kojelauta ja hallinta
+
+### Todennus
+
+| Päätepiste                    | Menetelmä | Kuvaus                               |
+| ----------------------------- | --------- | ------------------------------------ |
+| `/api/auth/login`             | POST      | Kirjaudu                             |
+| `/api/auth/logout`            | POST      | Kirjaudu ulos                        |
+| `/api/settings/require-login` | GET/PUT   | Vaihda sisäänkirjautuminen vaaditaan |
+
+### Palveluntarjoajan hallinta
+
+| Päätepiste                   | Menetelmä           | Kuvaus                                   |
+| ---------------------------- | ------------------- | ---------------------------------------- |
+| `/api/providers`             | HANKI/LÄHETÄ        | Luettelo / luo palveluntarjoajat         |
+| `/api/providers/[id]`        | GET/PUT/DELETE      | Hallinnoi palveluntarjoajaa              |
+| `/api/providers/[id]/test`   | POST                | Testaa palveluntarjoajan yhteyttä        |
+| `/api/providers/[id]/models` | HANKI               | Luettelo tarjoajan mallit                |
+| `/api/providers/validate`    | POST                | Tarkista palveluntarjoajan konfiguraatio |
+| `/api/provider-nodes*`       | Erilaisia ​​        | Palveluntarjoajan solmuhallinta          |
+| `/api/provider-models`       | HANKI/LÄHETÄ/POISTA | Räätälöidyt mallit                       |
+
+### OAuth-kulkuja
+
+| Päätepiste                       | Menetelmä    | Kuvaus                          |
+| -------------------------------- | ------------ | ------------------------------- |
+| `/api/oauth/[provider]/[action]` | Erilaisia ​​ | Palveluntarjoajakohtainen OAuth |
+
+### Reititys ja konfigurointi
+
+| Päätepiste            | Menetelmä    | Kuvaus                                    |
+| --------------------- | ------------ | ----------------------------------------- |
+| `/api/models/alias`   | HANKI/LÄHETÄ | Mallialiakset                             |
+| `/api/models/catalog` | HANKI        | Kaikki mallit toimittajan + tyypin mukaan |
+| `/api/combos*`        | Erilaisia ​​ | Yhdistelmähallinta                        |
+| `/api/keys*`          | Erilaisia ​​ | API-avainten hallinta                     |
+| `/api/pricing`        | HANKI        | Mallin hinnoittelu                        |
+
+### Käyttö ja analyysi
+
+| Päätepiste                  | Menetelmä | Kuvaus                 |
+| --------------------------- | --------- | ---------------------- |
+| `/api/usage/history`        | HANKI     | Käyttöhistoria         |
+| `/api/usage/logs`           | HANKI     | Käyttölokit            |
+| `/api/usage/request-logs`   | HANKI     | Pyyntötason lokit      |
+| `/api/usage/[connectionId]` | HANKI     | Yhteyskohtainen käyttö |
+
+### Asetukset
+
+| Päätepiste                      | Menetelmä | Kuvaus                             |
+| ------------------------------- | --------- | ---------------------------------- |
+| `/api/settings`                 | GET/PUT   | Yleiset asetukset                  |
+| `/api/settings/proxy`           | GET/PUT   | Verkon välityspalvelimen asetukset |
+| `/api/settings/proxy/test`      | POST      | Testaa välityspalvelinyhteyttä     |
+| `/api/settings/ip-filter`       | GET/PUT   | IP-sallitut/estolistat             |
+| `/api/settings/thinking-budget` | GET/PUT   | Perustelujen merkkibudjetti        |
+| `/api/settings/system-prompt`   | GET/PUT   | Globaali järjestelmäkehote         |
+
+### Valvonta
+
+| Päätepiste               | Menetelmä    | Kuvaus                        |
+| ------------------------ | ------------ | ----------------------------- |
+| `/api/sessions`          | HANKI        | Aktiivinen istunnon seuranta  |
+| `/api/rate-limits`       | HANKI        | Tilikohtaiset korkorajat      |
+| `/api/monitoring/health` | HANKI        | Terveystarkastus              |
+| `/api/cache`             | HANKI/POISTA | Välimuistitilastot / tyhjennä |
+
+### Varmuuskopiointi ja vienti/tuonti
+
+| Päätepiste                  | Menetelmä | Kuvaus                                           |
+| --------------------------- | --------- | ------------------------------------------------ |
+| `/api/db-backups`           | HANKI     | Luettelo käytettävissä olevista varmuuskopioista |
+| `/api/db-backups`           | PUT       | Luo manuaalinen varmuuskopio                     |
+| `/api/db-backups`           | POST      | Palauta tietystä varmuuskopiosta                 |
+| `/api/db-backups/export`    | HANKI     | Lataa tietokanta .sqlite-tiedostona              |
+| `/api/db-backups/import`    | POST      | Lataa .sqlite-tiedosto korvataksesi tietokannan  |
+| `/api/db-backups/exportAll` | HANKI     | Lataa koko varmuuskopio .tar.gz-arkistona        |
+
+### Cloud Sync
+
+| Päätepiste             | Menetelmä    | Kuvaus                     |
+| ---------------------- | ------------ | -------------------------- |
+| `/api/sync/cloud`      | Erilaisia ​​ | Pilvisynkronointitoiminnot |
+| `/api/sync/initialize` | POST         | Alusta synkronointi        |
+| `/api/cloud/*`         | Erilaisia ​​ | Pilvihallinta              |
+
+### CLI-työkalut
+
+| Päätepiste                         | Menetelmä | Kuvaus              |
+| ---------------------------------- | --------- | ------------------- |
+| `/api/cli-tools/claude-settings`   | HANKI     | Claude CLI tila     |
+| `/api/cli-tools/codex-settings`    | HANKI     | Codex CLI -tila     |
+| `/api/cli-tools/droid-settings`    | HANKI     | Droidin CLI-tila    |
+| `/api/cli-tools/openclaw-settings` | HANKI     | OpenClaw CLI tila   |
+| `/api/cli-tools/runtime/[toolId]`  | HANKI     | Yleinen CLI-ajoaika |
+
+CLI-vastauksia ovat: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
+
+### Resilience & Rate Limits
+
+| Päätepiste              | Menetelmä | Kuvaus                            |
+| ----------------------- | --------- | --------------------------------- |
+| `/api/resilience`       | GET/PUT   | Hanki/päivitä joustavuusprofiilit |
+| `/api/resilience/reset` | POST      | Nollaa katkaisijat                |
+| `/api/rate-limits`      | HANKI     | Tilikohtaisen koron rajan tila    |
+| `/api/rate-limit`       | HANKI     | Yleisen nopeusrajan määritys      |
+
+### Evals
+
+| Päätepiste   | Menetelmä    | Kuvaus                                  |
+| ------------ | ------------ | --------------------------------------- |
+| `/api/evals` | HANKI/LÄHETÄ | Listaa eval-sviitit / suorita arviointi |
+
+### Käytännöt
+
+| Päätepiste      | Menetelmä           | Kuvaus                      |
+| --------------- | ------------------- | --------------------------- |
+| `/api/policies` | HANKI/LÄHETÄ/POISTA | Hallitse reitityskäytäntöjä |
+
+### Vaatimustenmukaisuus
+
+| Päätepiste                  | Menetelmä | Kuvaus                                             |
+| --------------------------- | --------- | -------------------------------------------------- |
+| `/api/compliance/audit-log` | HANKI     | Vaatimustenmukaisuuden tarkastusloki (viimeinen N) |
+
+### v1beta (Gemini-yhteensopiva)
+
+| Päätepiste                 | Menetelmä | Kuvaus                              |
+| -------------------------- | --------- | ----------------------------------- |
+| `/v1beta/models`           | HANKI     | Listaa mallit Gemini-muodossa       |
+| `/v1beta/models/{...path}` | POST      | Gemini `generateContent` päätepiste |
+
+Nämä päätepisteet heijastavat Geminin API-muotoa asiakkaille, jotka odottavat natiivi Gemini SDK -yhteensopivuutta.
+
+### Sisäiset / järjestelmäsovellusliittymät
+
+| Päätepiste      | Menetelmä | Kuvaus                                                             |
+| --------------- | --------- | ------------------------------------------------------------------ |
+| `/api/init`     | HANKI     | Sovelluksen alustuksen tarkistus (käytetty ensimmäisellä kerralla) |
+| `/api/tags`     | HANKI     | Ollama-yhteensopivat mallitunnisteet (Ollama-asiakkaille)          |
+| `/api/restart`  | POST      | Käynnistä siro palvelimen uudelleenkäynnistys                      |
+| `/api/shutdown` | POST      | Laukaise siro palvelimen sammutus                                  |
+
+> **Huomaa:** Näitä päätepisteitä käytetään sisäisesti järjestelmässä tai Ollama-asiakasyhteensopivuuden vuoksi. Loppukäyttäjät eivät yleensä soita niihin.
+
+---
+
+## Äänen transkriptio
+
+```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+```
+
+Literoi äänitiedostot Deepgramilla tai AssemblyAI:lla.
+
+**Pyyntö:**
+
+```bash
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+  -H "Authorization: Bearer your-api-key" \
+  -F "file=@recording.mp3" \
+  -F "model=deepgram/nova-3"
+```
+
+**Vastaus:**
+
+```json
+{
+  "text": "Hello, this is the transcribed audio content.",
+  "task": "transcribe",
+  "language": "en",
+  "duration": 12.5
+}
+```
+
+**Tuetut palveluntarjoajat:** `deepgram/nova-3`, `assemblyai/best`.
+
+**Tuetut muodot:** `mp3`, `wav`, `m4a`, `flac`, `ogg`,
+
+---
+
+## Ollama-yhteensopivuus
+
+Asiakkaille, jotka käyttävät Ollaman API-muotoa:
+
+```bash
+# Chat endpoint (Ollama format)
+POST /v1/api/chat
+
+# Model listing (Ollama format)
+GET /api/tags
+```
+
+Pyynnöt käännetään automaattisesti Ollaman ja sisäisten muotojen välillä.
+
+---
+
+## Telemetria
+
+```bash
+# Get latency telemetry summary (p50/p95/p99 per provider)
+GET /api/telemetry/summary
+```
+
+**Vastaus:**
+
+```json
+{
+  "providers": {
+    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
+    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
+  }
+}
+```
+
+---
+
+## Budjetti
+
+```bash
+# Get budget status for all API keys
+GET /api/usage/budget
+
+# Set or update a budget
+POST /api/usage/budget
+Content-Type: application/json
+
+{
+  "keyId": "key-123",
+  "limit": 50.00,
+  "period": "monthly"
+}
+```
+
+---
+
+## Mallin saatavuus
+
+```bash
+# Get real-time model availability across all providers
+GET /api/models/availability
+
+# Check availability for a specific model
+POST /api/models/availability
+Content-Type: application/json
+
+{
+  "model": "claude-sonnet-4-5-20250929"
+}
+```
+
+---
+
+## Pyynnön käsittely
+
+1. Asiakas lähettää pyynnön osoitteeseen `/v1/*`
+2. Reitinkäsittelijän kutsut `handleChat`, `handleEmbedding`, `handleAudioTranscription` tai `handleImageGeneration`
+3. Malli on ratkaistu (suora toimittaja/malli tai alias/yhdistelmä)
+4. Tunnustiedot on valittu paikallisesta tietokannasta tilin saatavuussuodatuksella
+5. Chat: `handleChatCore` — muodon tunnistus, käännös, välimuistin tarkistus, idempotenssin tarkistus
+6. Palveluntarjoajan toteuttaja lähettää alkupään pyynnön
+7. Vastaus käännetty takaisin asiakasmuotoon (chat) tai palautettu sellaisenaan (upotukset/kuvat/ääni)
+8. Käyttö/loki kirjattu
+9. Varmennus koskee virheitä yhdistelmäsääntöjen mukaisesti
+
+Koko arkkitehtuuriviite: [link](ARCHITECTURE.md)
+
+---
+
+## Todennus
+
+- Hallintapaneelireitit (`/dashboard/*`) käyttävät `auth_token` evästettä
+- Kirjautuminen käyttää tallennettua salasanahajautusta; varaa `INITIAL_PASSWORD`
+- `requireLogin` vaihdettavissa kautta `/api/settings/require-login`
+- `/v1/*` reitit vaativat valinnaisesti Bearer API -avaimen, kun `REQUIRE_API_KEY=true`

docs/i18n/fi/ARCHITECTURE.md

@@ -0,0 +1,781 @@
+# OmniRoute-arkkitehtuuri
+
+🌐 **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)
+
+_Viimeksi päivitetty: 2026-02-18_
+
+## Tiivistelmä
+
+OmniRoute on paikallinen AI-reititysyhdyskäytävä ja kojelauta, joka on rakennettu Next.js:lle.
+Se tarjoaa yhden OpenAI-yhteensopivan päätepisteen (`/v1/*`) ja reitittää liikenteen useiden alkupään palveluntarjoajien kesken kääntämisen, varaosion, tunnuksen päivityksen ja käytön seurannan avulla.
+
+Ydinominaisuudet:
+
+- OpenAI-yhteensopiva API-pinta CLI:lle/työkaluille (28 toimittajaa)
+- Pyydä/vastaa käännös palveluntarjoajan eri formaattien välillä
+- Mallin yhdistelmävara (usean mallin sarja)
+- Tilitason varatoiminto (usea tili palveluntarjoajaa kohti)
+- OAuth + API-avain tarjoajan yhteyden hallinta
+- Upotus sukupolvi `/v1/embeddings`:n kautta (6 toimittajaa, 9 mallia)
+- Kuvien luominen `/v1/images/generations`:n kautta (4 toimittajaa, 9 mallia)
+- Ajattele tagien jäsentämistä (`<think>...</think>`) päättelymalleille
+- Vastauksen desinfiointi tiukan OpenAI SDK -yhteensopivuuden takaamiseksi
+- Roolien normalisointi (kehittäjä→järjestelmä, järjestelmä→käyttäjä) palveluntarjoajien välistä yhteensopivuutta varten
+- Strukturoitu lähdön muunnos (json_schema → Gemini responseSchema)
+- Paikallinen pysyvyys tarjoajille, avaimille, aliaksille, yhdistelmille, asetuksille, hinnoittelulle
+- Käytön/kustannusten seuranta ja pyyntöjen kirjaaminen
+- Valinnainen pilvisynkronointi usean laitteen/tilan synkronointiin
+- IP-sallitut / estolistat API-käyttöoikeuksien hallinnassa
+- Ajatteleva budjetin hallinta (passthrough/auto/mukautettu/adaptiivinen)
+- Globaali järjestelmän nopea ruiskutus
+- Istunnon seuranta ja sormenjäljet
+- Tilikohtainen tehostettu hintarajoitus tarjoajakohtaisilla profiileilla
+- Katkaisijakuvio palveluntarjoajan joustavuuden parantamiseksi
+- Ukkosta estävä laumasuoja mutex-lukolla
+- Allekirjoituspohjainen pyyntöjen duplikoinnin välimuisti
+- Verkkotunnustaso: mallin saatavuus, hintasäännöt, varakäytäntö, lukituskäytäntö
+- Verkkotunnuksen tilan pysyvyys (SQLite-kirjoitusvälimuisti varauksille, budjeteille, lukituksille, katkaisimille)
+- Käytäntömoottori keskitettyä pyyntöjen arviointia varten (sulku → budjetti → vara)
+- Pyydä telemetriaa p50/p95/p99-latenssiaggregaatiolla
+- Korrelaatiotunnus (X-Request-Id) päästä päähän -jäljitykseen
+- Vaatimustenmukaisuuden tarkastuksen kirjaaminen ja opt-out API-avaimella
+- Eval-kehys LLM-laadunvarmistukseen
+- Joustavan käyttöliittymän kojelauta, jossa on reaaliaikainen katkaisijatila
+- Modulaariset OAuth-palveluntarjoajat (12 yksittäistä moduulia alla `src/lib/oauth/providers/`)
+
+Ensisijainen suoritusaikamalli:
+
+- Next.js-sovellusreitit `src/app/api/*` -sovelluksessa toteuttavat sekä hallintapaneelin sovellusliittymiä että yhteensopivuussovellusliittymiä
+- Jaettu SSE/reititysydin kohteissa `src/sse/*` + `open-sse/*` hoitaa palveluntarjoajan suorittamisen, käännöksen, suoratoiston, varatoiminnon ja käytön
+
+## Laajuus ja rajat
+
+### Soveltamisalalla
+
+- Paikallisen yhdyskäytävän suoritusaika
+- Kojelaudan hallintasovellusliittymät
+- Palveluntarjoajan todennus ja tunnuksen päivitys
+- Pyydä käännöstä ja SSE-suoratoistoa
+- Paikallinen tila + käytön pysyvyys
+- Valinnainen pilvisynkronointiorkesteri
+
+### Soveltamisalan ulkopuolella
+
+- Pilvipalvelun toteutus `NEXT_PUBLIC_CLOUD_URL`:n takana
+- Palveluntarjoajan SLA/ohjaustaso paikallisen prosessin ulkopuolella
+- Itse ulkoiset CLI-binaarit (Claude CLI, Codex CLI jne.)
+
+## Korkean tason järjestelmäkonteksti
+
+```mermaid
+flowchart LR
+    subgraph Clients[Developer Clients]
+        C1[Claude Code]
+        C2[Codex CLI]
+        C3[OpenClaw / Droid / Cline / Continue / Roo]
+        C4[Custom OpenAI-compatible clients]
+        BROWSER[Browser Dashboard]
+    end
+
+    subgraph Router[OmniRoute Local Process]
+        API[V1 Compatibility API\n/v1/*]
+        DASH[Dashboard + Management API\n/api/*]
+        CORE[SSE + Translation Core\nopen-sse + src/sse]
+        DB[(db.json)]
+        UDB[(usage.json + log.txt)]
+    end
+
+    subgraph Upstreams[Upstream Providers]
+        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity]
+        P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
+        P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
+    end
+
+    subgraph Cloud[Optional Cloud Sync]
+        CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL]
+    end
+
+    C1 --> API
+    C2 --> API
+    C3 --> API
+    C4 --> API
+    BROWSER --> DASH
+
+    API --> CORE
+    DASH --> DB
+    CORE --> DB
+    CORE --> UDB
+
+    CORE --> P1
+    CORE --> P2
+    CORE --> P3
+
+    DASH --> CLOUD
+```
+
+## Suorituksenaikaiset ydinkomponentit
+
+## 1) API ja reitityskerros (Next.js App Routes)
+
+Päähakemistot:
+
+- `src/app/api/v1/*` ja `src/app/api/v1beta/*` yhteensopiville sovellusliittymille
+- `src/app/api/*` hallinta-/määrityssovellusliittymille
+- Seuraavaksi kirjoitetaan uudelleen `next.config.mjs` kartassa `/v1/*` arvoon `/api/v1/*`
+
+Tärkeitä yhteensopivuusreittejä:
+
+- `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` - sisältää mukautettuja malleja, joissa on `custom: true`
+- `src/app/api/v1/embeddings/route.ts` - upottaminen (6 palveluntarjoajaa)
+- `src/app/api/v1/images/generations/route.ts` — kuvan luominen (4+ tarjoajaa, mukaan lukien Antigravity/Nebius)
+- `src/app/api/v1/messages/count_tokens/route.ts`
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` - palveluntarjoajakohtainen keskustelu
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` – omat palveluntarjoajakohtaiset upotukset
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` – palveluntarjoajakohtaiset kuvat
+- `src/app/api/v1beta/models/route.ts`
+- `src/app/api/v1beta/models/[...path]/route.ts`
+
+Hallintoverkkotunnukset:
+
+- Todennus/asetukset: `src/app/api/auth/*`, `src/app/api/settings/*`
+- Palveluntarjoajat/yhteydet: `src/app/api/providers*`
+- Palveluntarjoajan solmut: `src/app/api/provider-nodes*`
+- Mukautetut mallit: `src/app/api/provider-models` (GET/POST/DELETE)
+- Malliluettelo: `src/app/api/models/catalog` (GET)
+- Välityspalvelimen kokoonpano: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
+- OAuth: `src/app/api/oauth/*`
+- Avaimet/aliakset/kombot/hinnoittelu: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
+- Käyttö: `src/app/api/usage/*`
+- Synkronointi/pilvi: `src/app/api/sync/*`, `src/app/api/cloud/*`
+- CLI-työkalujen avustajat: `src/app/api/cli-tools/*`
+- IP-suodatin: `src/app/api/settings/ip-filter` (GET/PUT)
+- Arvioitu budjetti: `src/app/api/settings/thinking-budget` (GET/PUT)
+- Järjestelmäkehote: `src/app/api/settings/system-prompt` (GET/PUT)
+- Istunnot: `src/app/api/sessions` (GET)
+- Hintarajoitukset: `src/app/api/rate-limits` (GET)
+- Joustavuus: `src/app/api/resilience` (GET/PATCH) – palveluntarjoajan profiilit, katkaisija, nopeusrajoitustila
+- Kestävyyden nollaus: `src/app/api/resilience/reset` (POST) - nollaa katkaisijat + jäähdytys
+- Välimuistitilastot: `src/app/api/cache/stats` (GET/DELETE)
+- Mallin saatavuus: `src/app/api/models/availability` (GET/POST)
+- Telemetria: `src/app/api/telemetry/summary` (GET)
+- Budjetti: `src/app/api/usage/budget` (GET/POST)
+- Varaketjut: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Vaatimustenmukaisuustarkastus: `src/app/api/compliance/audit-log` (GET)
+- Arvot: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
+- Käytännöt: `src/app/api/policies` (GET/POST)
+
+## 2) SSE + Käännösydin
+
+Päävirtausmoduulit:
+
+- Merkintä: `src/sse/handlers/chat.ts`
+- Ydinorkesteri: `open-sse/handlers/chatCore.ts`
+- Palveluntarjoajan suoritussovittimet: `open-sse/executors/*`
+- Muototunnistuksen/palveluntarjoajan määritykset: `open-sse/services/provider.ts`
+- Mallin jäsennys/selvitys: `src/sse/services/model.ts`, `open-sse/services/model.ts`
+- Tilin varalogiikka: `open-sse/services/accountFallback.ts`
+- Käännösrekisteri: `open-sse/translator/index.ts`
+- Suoratoistomuunnokset: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Käytön purkaminen/normalisointi: `open-sse/utils/usageTracking.ts`
+- Think tag -jäsennin: `open-sse/utils/thinkTagParser.ts`
+- Upotuskäsittelijä: `open-sse/handlers/embeddings.ts`
+- Upotuspalveluntarjoajan rekisteri: `open-sse/config/embeddingRegistry.ts`
+- Kuvanluontikäsittelijä: `open-sse/handlers/imageGeneration.ts`
+- Kuvantarjoajan rekisteri: `open-sse/config/imageRegistry.ts`
+- Vastauksen desinfiointi: `open-sse/handlers/responseSanitizer.ts`
+- Roolin normalisointi: `open-sse/services/roleNormalizer.ts`
+
+Palvelut (liiketoimintalogiikka):
+
+- Tilin valinta/pisteytys: `open-sse/services/accountSelector.ts`
+- Kontekstin elinkaarihallinta: `open-sse/services/contextManager.ts`
+- IP-suodattimen valvonta: `open-sse/services/ipFilter.ts`
+- Istunnon seuranta: `open-sse/services/sessionManager.ts`
+- Pyydä kopioiden poistoa: `open-sse/services/signatureCache.ts`
+- Järjestelmäkehotteen lisäys: `open-sse/services/systemPrompt.ts`
+- Ajatteleva budjetin hallinta: `open-sse/services/thinkingBudget.ts`
+- Jokerimerkkimallin reititys: `open-sse/services/wildcardRouter.ts`
+- Hintarajoitusten hallinta: `open-sse/services/rateLimitManager.ts`
+- Katkaisija: `open-sse/services/circuitBreaker.ts`
+
+Domain-kerroksen moduulit:
+
+- Mallin saatavuus: `src/lib/domain/modelAvailability.ts`
+- Kustannussäännöt/budjetit: `src/lib/domain/costRules.ts`
+- Varakäytäntö: `src/lib/domain/fallbackPolicy.ts`
+- Yhdistelmäratkaisu: `src/lib/domain/comboResolver.ts`
+- Lukituskäytäntö: `src/lib/domain/lockoutPolicy.ts`
+- Käytäntömoottori: `src/domain/policyEngine.ts` — keskitetty lukitus → budjetti → varaarviointi
+- Virhekoodiluettelo: `src/lib/domain/errorCodes.ts`
+- Pyynnön tunnus: `src/lib/domain/requestId.ts`
+- Noudon aikakatkaisu: `src/lib/domain/fetchTimeout.ts`
+- Pyydä telemetriaa: `src/lib/domain/requestTelemetry.ts`
+- Vaatimustenmukaisuus/tarkastus: `src/lib/domain/compliance/index.ts`
+- Eval juoksija: `src/lib/domain/evalRunner.ts`
+- Verkkotunnuksen tilan pysyvyys: `src/lib/db/domainState.ts` — SQLite CRUD varaketjuille, budjeteille, kustannushistorialle, lukitustilalle, katkaisimille
+
+OAuth-palveluntarjoajan moduulit (12 yksittäistä tiedostoa kohdassa `src/lib/oauth/providers/`):
+
+- Rekisterihakemisto: `src/lib/oauth/providers/index.ts`
+- Yksittäiset palveluntarjoajat: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, ,\_1 `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
+- Ohut kääre: `src/lib/oauth/providers.ts` - jälleenvienti yksittäisistä moduuleista
+
+## 3) Pysyvyyskerros
+
+Ensisijainen tila DB:
+
+- `src/lib/localDb.ts`
+- tiedosto: `${DATA_DIR}/db.json` (tai `$XDG_CONFIG_HOME/omniroute/db.json`, kun se on asetettu, muuten `~/.omniroute/db.json`)
+- entiteetit: providerConnections, providerNodes, mallialiakset, yhdistelmät, apiKeys, asetukset, hinnoittelu, **customModels**, **proxyConfig**, **ipFilter**, **thhinkingBudget**, **systemPrompt**
+
+DB:n käyttö:
+
+- `src/lib/usageDb.ts`
+- tiedostot: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
+- noudattaa samaa perushakemistokäytäntöä kuin `localDb` (`DATA_DIR`, sitten `XDG_CONFIG_HOME/omniroute`, kun se on asetettu)
+- jaettu kohdistetuiksi alamoduuleiksi: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts`
+
+Domain State DB (SQLite):
+
+- `src/lib/db/domainState.ts` - CRUD-toiminnot toimialueen tilassa
+- Taulukot (luotu `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`,
+- Kirjoitusvälimuistin malli: muistissa olevat kartat ovat arvovaltaisia ajon aikana; mutaatiot kirjoitetaan synkronisesti SQLiten kanssa; tila palautetaan DB:stä kylmäkäynnistyksen yhteydessä
+
+## 4) Auth + Security Surfaces
+
+- Hallintapaneelin evästeiden todennus: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
+- API-avaimen luominen/vahvistus: `src/shared/utils/apiKey.ts`
+- Palveluntarjoajan salaisuudet säilyivät `providerConnections` tiedoissa
+- Lähtevän välityspalvelimen tuki `open-sse/utils/proxyFetch.ts` (env vars) ja `open-sse/utils/networkProxy.ts` (määritettävä palveluntarjoajakohtaisesti tai globaali) kautta
+
+## 5) Cloud Sync
+
+- Aikataulun aloitus: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
+- Säännöllinen tehtävä: `src/shared/services/cloudSyncScheduler.ts`
+- Ohjausreitti: `src/app/api/sync/cloud/route.ts`
+
+## Pyynnön elinkaari (`/v1/chat/completions`)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as CLI/SDK Client
+    participant Route as /api/v1/chat/completions
+    participant Chat as src/sse/handlers/chat
+    participant Core as open-sse/handlers/chatCore
+    participant Model as Model Resolver
+    participant Auth as Credential Selector
+    participant Exec as Provider Executor
+    participant Prov as Upstream Provider
+    participant Stream as Stream Translator
+    participant Usage as usageDb
+
+    Client->>Route: POST /v1/chat/completions
+    Route->>Chat: handleChat(request)
+    Chat->>Model: parse/resolve model or combo
+
+    alt Combo model
+        Chat->>Chat: iterate combo models (handleComboChat)
+    end
+
+    Chat->>Auth: getProviderCredentials(provider)
+    Auth-->>Chat: active account + tokens/api key
+
+    Chat->>Core: handleChatCore(body, modelInfo, credentials)
+    Core->>Core: detect source format
+    Core->>Core: translate request to target format
+    Core->>Exec: execute(provider, transformedBody)
+    Exec->>Prov: upstream API call
+    Prov-->>Exec: SSE/JSON response
+    Exec-->>Core: response + metadata
+
+    alt 401/403
+        Core->>Exec: refreshCredentials()
+        Exec-->>Core: updated tokens
+        Core->>Exec: retry request
+    end
+
+    Core->>Stream: translate/normalize stream to client format
+    Stream-->>Client: SSE chunks / JSON response
+
+    Stream->>Usage: extract usage + persist history/log
+```
+
+## Yhdistelmä + tilin varavirta
+
+```mermaid
+flowchart TD
+    A[Incoming model string] --> B{Is combo name?}
+    B -- Yes --> C[Load combo models sequence]
+    B -- No --> D[Single model path]
+
+    C --> E[Try model N]
+    E --> F[Resolve provider/model]
+    D --> F
+
+    F --> G[Select account credentials]
+    G --> H{Credentials available?}
+    H -- No --> I[Return provider unavailable]
+    H -- Yes --> J[Execute request]
+
+    J --> K{Success?}
+    K -- Yes --> L[Return response]
+    K -- No --> M{Fallback-eligible error?}
+
+    M -- No --> N[Return error]
+    M -- Yes --> O[Mark account unavailable cooldown]
+    O --> P{Another account for provider?}
+    P -- Yes --> G
+    P -- No --> Q{In combo with next model?}
+    Q -- Yes --> E
+    Q -- No --> R[Return all unavailable]
+```
+
+Varapäätökset tehdään `open-sse/services/accountFallback.ts`:n avulla tilakoodeja ja virheviestiheuristiikkaa käyttämällä.
+
+## OAuthin käyttöönotto ja tunnuksen päivityksen elinkaari
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Dashboard UI
+    participant OAuth as /api/oauth/[provider]/[action]
+    participant ProvAuth as Provider Auth Server
+    participant DB as localDb
+    participant Test as /api/providers/[id]/test
+    participant Exec as Provider Executor
+
+    UI->>OAuth: GET authorize or device-code
+    OAuth->>ProvAuth: create auth/device flow
+    ProvAuth-->>OAuth: auth URL or device code payload
+    OAuth-->>UI: flow data
+
+    UI->>OAuth: POST exchange or poll
+    OAuth->>ProvAuth: token exchange/poll
+    ProvAuth-->>OAuth: access/refresh tokens
+    OAuth->>DB: createProviderConnection(oauth data)
+    OAuth-->>UI: success + connection id
+
+    UI->>Test: POST /api/providers/[id]/test
+    Test->>Exec: validate credentials / optional refresh
+    Exec-->>Test: valid or refreshed token info
+    Test->>DB: update status/tokens/errors
+    Test-->>UI: validation result
+```
+
+Päivitys reaaliaikaisen liikenteen aikana suoritetaan `open-sse/handlers/chatCore.ts` -suorittimen `refreshCredentials()` sisällä.
+
+## Cloud Sync -elinkaari (Ota käyttöön / Synkronoi / Poista käytöstä)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Endpoint Page UI
+    participant Sync as /api/sync/cloud
+    participant DB as localDb
+    participant Cloud as External Cloud Sync
+    participant Claude as ~/.claude/settings.json
+
+    UI->>Sync: POST action=enable
+    Sync->>DB: set cloudEnabled=true
+    Sync->>DB: ensure API key exists
+    Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys)
+    Cloud-->>Sync: sync result
+    Sync->>Cloud: GET /{machineId}/v1/verify
+    Sync-->>UI: enabled + verification status
+
+    UI->>Sync: POST action=sync
+    Sync->>Cloud: POST /sync/{machineId}
+    Cloud-->>Sync: remote data
+    Sync->>DB: update newer local tokens/status
+    Sync-->>UI: synced
+
+    UI->>Sync: POST action=disable
+    Sync->>DB: set cloudEnabled=false
+    Sync->>Cloud: DELETE /sync/{machineId}
+    Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed)
+    Sync-->>UI: disabled
+```
+
+Jaksottaisen synkronoinnin käynnistää `CloudSyncScheduler`, kun pilvi on käytössä.
+
+## Tietomalli ja tallennuskartta
+
+```mermaid
+erDiagram
+    SETTINGS ||--o{ PROVIDER_CONNECTION : controls
+    PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider
+    PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage
+
+    SETTINGS {
+      boolean cloudEnabled
+      number stickyRoundRobinLimit
+      boolean requireLogin
+      string password_hash
+      string fallbackStrategy
+      json rateLimitDefaults
+      json providerProfiles
+    }
+
+    PROVIDER_CONNECTION {
+      string id
+      string provider
+      string authType
+      string name
+      number priority
+      boolean isActive
+      string apiKey
+      string accessToken
+      string refreshToken
+      string expiresAt
+      string testStatus
+      string lastError
+      string rateLimitedUntil
+      json providerSpecificData
+    }
+
+    PROVIDER_NODE {
+      string id
+      string type
+      string name
+      string prefix
+      string apiType
+      string baseUrl
+    }
+
+    MODEL_ALIAS {
+      string alias
+      string targetModel
+    }
+
+    COMBO {
+      string id
+      string name
+      string[] models
+    }
+
+    API_KEY {
+      string id
+      string name
+      string key
+      string machineId
+    }
+
+    USAGE_ENTRY {
+      string provider
+      string model
+      number prompt_tokens
+      number completion_tokens
+      string connectionId
+      string timestamp
+    }
+
+    CUSTOM_MODEL {
+      string id
+      string name
+      string providerId
+    }
+
+    PROXY_CONFIG {
+      string global
+      json providers
+    }
+
+    IP_FILTER {
+      string mode
+      string[] allowlist
+      string[] blocklist
+    }
+
+    THINKING_BUDGET {
+      string mode
+      number customBudget
+      string effortLevel
+    }
+
+    SYSTEM_PROMPT {
+      boolean enabled
+      string prompt
+      string position
+    }
+```
+
+Fyysiset tallennustiedostot:
+
+- päätila: `${DATA_DIR}/db.json` (tai `$XDG_CONFIG_HOME/omniroute/db.json`, kun se on asetettu, muuten `~/.omniroute/db.json`)
+- käyttötilastot: `${DATA_DIR}/usage.json`
+- pyyntölokin rivit: `${DATA_DIR}/log.txt`
+- valinnainen kääntäjä/pyydä virheenkorjausistuntoja: `<repo>/logs/...`
+
+## Käyttöönoton topologia
+
+```mermaid
+flowchart LR
+    subgraph LocalHost[Developer Host]
+        CLI[CLI Tools]
+        Browser[Dashboard Browser]
+    end
+
+    subgraph ContainerOrProcess[OmniRoute Runtime]
+        Next[Next.js Server\nPORT=20128]
+        Core[SSE Core + Executors]
+        MainDB[(db.json)]
+        UsageDB[(usage.json/log.txt)]
+    end
+
+    subgraph External[External Services]
+        Providers[AI Providers]
+        SyncCloud[Cloud Sync Service]
+    end
+
+    CLI --> Next
+    Browser --> Next
+    Next --> Core
+    Next --> MainDB
+    Core --> MainDB
+    Core --> UsageDB
+    Core --> Providers
+    Next --> SyncCloud
+```
+
+## Moduulikartoitus (päätöskriittinen)
+
+### Reitti- ja API-moduulit
+
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: yhteensopivuussovellusliittymät
+- `src/app/api/v1/providers/[provider]/*`: omat palveluntarjoajakohtaiset reitit (chat, upotukset, kuvat)
+- `src/app/api/providers*`: palveluntarjoajan CRUD, validointi, testaus
+- `src/app/api/provider-nodes*`: mukautettu yhteensopiva solmuhallinta
+- `src/app/api/provider-models`: mukautetun mallin hallinta (CRUD)
+- `src/app/api/models/catalog`: täydellinen malliluettelosovellusliittymä (kaikki tyypit ryhmitelty tarjoajan mukaan)
+- `src/app/api/oauth/*`: OAuth-/laitekoodivirrat
+- `src/app/api/keys*`: paikallisen API-avaimen elinkaari
+- `src/app/api/models/alias`: aliaksen hallinta
+- `src/app/api/combos*`: varayhdistelmähallinta
+- `src/app/api/pricing`: hinnoittelun ohitukset kustannuslaskennassa
+- `src/app/api/settings/proxy`: välityspalvelimen määritys (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: lähtevän välityspalvelimen yhteystesti (POST)
+- `src/app/api/usage/*`: käyttö- ja lokisovellusliittymät
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: pilvisynkronointi ja pilveen suuntautuvat apulaiset
+- `src/app/api/cli-tools/*`: paikalliset CLI-asetusten kirjoittajat/tarkistajat
+- `src/app/api/settings/ip-filter`: IP-sallittu/estolista (GET/PUT)
+- `src/app/api/settings/thinking-budget`: ajattelutunnuksen budjettimääritys (GET/PUT)
+- `src/app/api/settings/system-prompt`: yleinen järjestelmäkehote (GET/PUT)
+- `src/app/api/sessions`: aktiivisen istunnon luettelo (GET)
+- `src/app/api/rate-limits`: tilikohtainen korkorajoitustila (GET)
+
+### Reititys- ja suoritusydin
+
+- `src/sse/handlers/chat.ts`: pyynnön jäsennys, yhdistelmäkäsittely, tilin valintasilmukka
+- `open-sse/handlers/chatCore.ts`: käännös, suorittajan lähettäminen, uudelleenyritysten/päivitysten käsittely, streamin määritys
+- `open-sse/executors/*`: palveluntarjoajakohtainen verkko- ja muotokäyttäytyminen
+
+### Käännösrekisteri ja muotomuuntimet
+
+- `open-sse/translator/index.ts`: kääntäjän rekisteri ja orkestrointi
+- Pyydä kääntäjiä: `open-sse/translator/request/*`
+- Vastausten kääntäjät: `open-sse/translator/response/*`
+- Muotovakiot: `open-sse/translator/formats.ts`
+
+### Pysyvyys
+
+- `src/lib/localDb.ts`: pysyvä kokoonpano/tila
+- `src/lib/usageDb.ts`: käyttöhistoria ja rullaavat pyyntölokit
+
+## Palveluntarjoajan kattavuus (strategiamalli)
+
+Jokaisella palveluntarjoajalla on erikoistunut suorittaja, joka laajentaa `BaseExecutor` (kohdassa `open-sse/executors/base.ts`), joka tarjoaa URL-osoitteen rakentamisen, otsikon rakentamisen, uudelleenyrityksen eksponentiaalisella perääntymisellä, valtuustietojen päivityskoukut ja `execute()`-orkesterimenetelmän.
+
+| Toteuttaja            | Palveluntarjoaja(t)                                                                                                                                           | Erikoiskäsittely                                                                      |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `DefaultExecutor`     | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, ilotulitus, Cerebras, Cohere, NVIDIA | Dynaaminen URL-/otsikkomääritykset tarjoajakohtaisesti                                |
+| `AntigravityExecutor` | Google Antigravity                                                                                                                                            | Mukautetut projekti-/istuntotunnukset, Yritä uudelleen jäsentämisen jälkeen           |
+| `CodexExecutor`       | OpenAI Codex                                                                                                                                                  | Syöttää järjestelmäohjeita, pakottaa päättelyponnistuksen                             |
+| `CursorExecutor`      | Kohdistin IDE                                                                                                                                                 | ConnectRPC-protokolla, Protobuf-koodaus, pyynnön allekirjoitus tarkistussumman kautta |
+| `GithubExecutor`      | GitHub Copilot                                                                                                                                                | Copilot-tunnuksen päivitys, VSC-koodia jäljittelevät otsikot                          |
+| `KiroExecutor`        | AWS CodeWhisperer/Kiro                                                                                                                                        | AWS EventStream binaarimuoto → SSE-muunnos                                            |
+| `GeminiCLIExecutor`   | Gemini CLI                                                                                                                                                    | Google OAuth -tunnuksen päivitysjakso                                                 |
+
+Kaikki muut palveluntarjoajat (mukaan lukien mukautetut yhteensopivat solmut) käyttävät `DefaultExecutor`.
+
+## Tarjoajan yhteensopivuusmatriisi
+
+| Palveluntarjoaja | Muoto             | Auth                      | Striimaa             | Ei-stream | Token Refresh | Käyttösovellusliittymä      |
+| ---------------- | ----------------- | ------------------------- | -------------------- | --------- | ------------- | --------------------------- |
+| Claude           | claude            | API-avain / OAuth         | ✅                   | ✅        | ✅            | ⚠️ Vain järjestelmänvalvoja |
+| Kaksoset         | kaksoset          | API-avain / OAuth         | ✅                   | ✅        | ✅            | ⚠️ Cloud Console            |
+| Gemini CLI       | gemini-cli        | OAuth                     | ✅                   | ✅        | ✅            | ⚠️ Cloud Console            |
+| Antigravitaatio  | antigravitaatio   | OAuth                     | ✅                   | ✅        | ✅            | ✅ Full quota API           |
+| OpenAI           | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
+| Codex            | openai-vastaukset | OAuth                     | ✅ pakotettu         | ❌        | ✅            | ✅ Hintarajat               |
+| GitHub Copilot   | openai            | OAuth + Copilot Token     | ✅                   | ✅        | ✅            | ✅ Kiintiön tilannekuvat    |
+| Kursori          | kohdistin         | Mukautettu tarkistussumma | ✅                   | ✅        | ❌            | ❌                          |
+| Kiro             | kiro              | AWS SSO OIDC              | ✅ (TapahtumaStream) | ❌        | ✅            | ✅ Käyttörajoitukset        |
+| Qwen             | openai            | OAuth                     | ✅                   | ✅        | ✅            | ⚠️ Pyynnöstä                |
+| iFlow            | openai            | OAuth (Perus)             | ✅                   | ✅        | ✅            | ⚠️ Pyynnöstä                |
+| OpenRouter       | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
+| GLM/Kimi/MiniMax | claude            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
+| DeepSeek         | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
+| Groq             | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
+| xAI (Grok)       | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
+| Mistral          | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
+| Hämmennys        | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
+| Yhdessä AI       | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
+| Ilotulitus AI    | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
+| Aivot            | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
+| Cohere           | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
+| NVIDIA NIM       | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
+
+## Käännösten muoto
+
+Havaittuja lähdemuotoja ovat:
+
+- `openai`
+- `openai-responses`
+- `claude`
+- `gemini`
+
+Kohdemuotoja ovat:
+
+- OpenAI chat / vastaukset
+- Claude
+- Gemini/Gemini-CLI/Antigravity-kuori
+- Kiro
+- Kursori
+
+Käännöksissä käytetään keskitinmuotona **OpenAI-muotoa** — kaikki konversiot menevät OpenAI:n kautta välimuotona:
+
+```
+Source Format → OpenAI (hub) → Target Format
+```
+
+Käännökset valitaan dynaamisesti lähteen hyötykuorman muodon ja toimittajan kohdemuodon perusteella.
+
+Muut käsittelytasot käännösputkessa:
+
+- **Vastausten puhdistaminen** – Poistaa standardista poikkeavat kentät OpenAI-muotoisista vastauksista (sekä suoratoistosta että ei-suoratoistosta) varmistaakseen tiukan SDK-yhteensopivuuden
+- **Roolin normalisointi** — Muuntaa `developer` → `system` muille kuin OpenAI-kohteille; yhdistää `system` → `user` malleille, jotka hylkäävät järjestelmäroolin (GLM, ERNIE)
+- **Ajattele tunnisteen purkamista** — jäsentää `<think>...</think>` lohkoa sisällöstä kenttään `reasoning_content`
+- **Strukturoitu tulos** — Muuntaa OpenAI `response_format.json_schema` Geminin `responseMimeType` + `responseSchema`
+
+## Tuetut API-päätepisteet
+
+| Päätepiste                                         | Muoto                        | Käsittelijä                                           |
+| -------------------------------------------------- | ---------------------------- | ----------------------------------------------------- |
+| `POST /v1/chat/completions`                        | OpenAI Chat                  | `src/sse/handlers/chat.ts`                            |
+| `POST /v1/messages`                                | Claude Viestit               | Sama käsittelijä (tunnistettu automaattisesti)        |
+| `POST /v1/responses`                               | OpenAI-vastaukset            | `open-sse/handlers/responsesHandler.ts`               |
+| `POST /v1/embeddings`                              | OpenAI Embeddings            | `open-sse/handlers/embeddings.ts`                     |
+| `GET /v1/embeddings`                               | Malliluettelo                | API reitti                                            |
+| `POST /v1/images/generations`                      | OpenAI-kuvat                 | `open-sse/handlers/imageGeneration.ts`                |
+| `GET /v1/images/generations`                       | Malliluettelo                | API reitti                                            |
+| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat                  | Palveluntarjoajakohtainen mallin validointi           |
+| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings            | Palveluntarjoajakohtainen mallin validointi           |
+| `POST /v1/providers/{provider}/images/generations` | OpenAI-kuvat                 | Palveluntarjoajakohtainen mallin validointi           |
+| `POST /v1/messages/count_tokens`                   | Claude Token Count           | API reitti                                            |
+| `GET /v1/models`                                   | OpenAI-mallien luettelo      | API-reitti (chat + upotus + kuva + mukautetut mallit) |
+| `GET /api/models/catalog`                          | Luettelo                     | Kaikki mallit ryhmitelty tarjoajan + tyypin mukaan    |
+| `POST /v1beta/models/*:streamGenerateContent`      | Gemini syntyperäinen         | API reitti                                            |
+| `GET/PUT/DELETE /api/settings/proxy`               | Välityspalvelimen kokoonpano | Verkon välityspalvelimen määritykset                  |
+| `POST /api/settings/proxy/test`                    | Välityspalvelinyhteydet      | Välityspalvelimen kunto/yhteystestin päätepiste       |
+| `GET/POST/DELETE /api/provider-models`             | Mukautetut mallit            | Mukautetun mallin hallinta toimittajaa kohden         |
+
+## Ohituskäsittelijä
+
+Ohituskäsittelijä (`open-sse/utils/bypassHandler.ts`) sieppaa Claude CLI:n tunnetut "poistopyynnöt" – lämmittelypingit, otsikon poiminnot ja tunnukset - ja palauttaa **väärennetyn vastauksen** kuluttamatta ylävirran toimittajatunnuksia. Tämä käynnistyy vain, kun `User-Agent` sisältää `claude-cli`.
+
+## Pyydä Logger Pipeline
+
+Pyyntöloggeri (`open-sse/utils/requestLogger.ts`) tarjoaa 7-vaiheisen virheenkorjauslokiputken, joka on oletuksena poistettu käytöstä ja otettu käyttöön `ENABLE_REQUEST_LOGS=true`:n kautta:
+
+```
+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
+```
+
+Tiedostot kirjoitetaan osoitteeseen `<repo>/logs/<session>/` jokaista pyyntöistuntoa varten.
+
+## Vikatilat ja joustavuus
+
+## 1) Tilin/palveluntarjoajan saatavuus
+
+- Palveluntarjoajan tilin jäähtyminen ohimenevien / nopeus / todennusvirheiden vuoksi
+- tilin varaosa ennen epäonnistunutta pyyntöä
+- Yhdistelmämallin palautus, kun nykyisen mallin/palveluntarjoajan polku on käytetty loppuun
+
+## 2) Tokenin vanheneminen
+
+- esitarkista ja päivitä yrittämällä uudelleen päivitettävien palveluntarjoajien kohdalla
+- 401/403 yritä uudelleen päivitysyrityksen jälkeen ydinpolulla
+
+## 3) Stream Safety
+
+- irrotettava stream-ohjain
+- käännösvirta streamin lopun huuhtelemalla ja `[DONE]` käsittelyllä
+- käyttöarvion varavaihtoehto, kun palveluntarjoajan käytön metatiedot puuttuvat
+
+## 4) Pilvisynkronoinnin heikkeneminen
+
+- Synkronointivirheet tulevat esiin, mutta paikallinen suoritusaika jatkuu
+- ajastimessa on uudelleenyrityslogiikka, mutta säännöllinen suoritus tällä hetkellä kutsuu oletusarvoisesti yhden yrityksen synkronointia
+
+## 5) Tietojen eheys
+
+- DB-muodon siirto/korjaus puuttuviin avaimiin
+- Vioittuneet JSON-nollaussuojat localDb:lle ja usageDb:lle
+
+## Havaittavuus ja toimintasignaalit
+
+Ajonaikaisen näkyvyyden lähteet:
+
+- konsolin lokit lähteestä `src/sse/utils/logger.ts`
+- pyyntökohtaiset käyttöaggregaatit kohteessa `usage.json`
+- tekstimuotoisen pyynnön tilakirjautuminen `log.txt`
+- valinnaiset syväpyyntö-/käännöslokit kohdassa `logs/`, kun `ENABLE_REQUEST_LOGS=true`
+- hallintapaneelin käytön päätepisteet (`/api/usage/*`) käyttöliittymän käyttöä varten
+
+## Turvallisuusherkät rajat
+
+- JWT-salaisuus (`JWT_SECRET`) suojaa hallintapaneelin istunnon evästeen vahvistuksen/allekirjoituksen
+- Alkuperäinen salasana (`INITIAL_PASSWORD`, oletus `123456`) on ohitettava todellisissa käyttöönotoissa
+- API-avaimen HMAC-salaisuus (`API_KEY_SECRET`) suojaa luodun paikallisen API-avainmuodon
+- Tarjoajan salaisuudet (API-avaimet/tunnisteet) säilyvät paikallisessa tietokannassa, ja ne tulee suojata tiedostojärjestelmätasolla
+- Pilvisynkronoinnin päätepisteet perustuvat API-avaimen todennus + konetunnuksen semantiikkaan
+
+## Ympäristö ja suoritusaikamatriisi
+
+Koodin aktiivisesti käyttämät ympäristömuuttujat:
+
+- Sovellus/todennus: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Tallennustila: `DATA_DIR`
+- Yhteensopivan solmun käyttäytyminen: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
+- Valinnainen tallennuspohjan ohitus (Linux/macOS, kun `DATA_DIR` ei ole asetettu): `XDG_CONFIG_HOME`
+- Suojaustiivistys: `API_KEY_SECRET`, `MACHINE_ID_SALT`
+- Kirjautuminen: `ENABLE_REQUEST_LOGS`
+- Synkronointi/pilvi-URL-osoite: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
+- Lähtevä välityspalvelin: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` ja pienillä kirjaimilla kirjoitetut versiot
+- SOCKS5-ominaisuusliput: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
+- Alusta/ajonaikaiset apuohjelmat (ei sovelluskohtaiset asetukset): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+
+## Tunnettuja arkkitehtonisia huomautuksia
+
+1. `usageDb` ja `localDb` jakavat nyt saman perushakemistokäytännön (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) vanhan tiedoston siirron kanssa.
+2. `/api/v1/route.ts` palauttaa staattisen malliluettelon, eikä se ole `/v1/models`:n käyttämä päämallien lähde.
+3. Pyyntöloggeri kirjoittaa täydet otsikot/runko, kun se on käytössä; käsittele lokihakemistoa arkaluontoisena.
+4. Pilven toiminta riippuu oikeasta `NEXT_PUBLIC_BASE_URL`- ja pilvipäätepisteen saavutettavuudesta.
+5. Hakemisto `open-sse/` julkaistaan ​​`@omniroute/open-sse` **npm-työtilapaketina**. Lähdekoodi tuo sen `@omniroute/open-sse/...`:n kautta (ratkaisi Next.js `transpilePackages`). Tämän asiakirjan tiedostopolut käyttävät edelleen hakemistonimeä `open-sse/` johdonmukaisuuden vuoksi.
+6. Hallintapaneelin kaaviot käyttävät **Uudelleenkaavioita** (SVG-pohjainen) helppokäyttöisten, interaktiivisten analytiikkavisualisoinnit (mallien käyttöpalkkikaaviot, toimittajien erittelytaulukot onnistumisprosentteineen) varten.
+7. E2E-testeissä käytetään **Playwrightia** (`tests/e2e/`), suoritetaan `npm run test:e2e`:n kautta. Yksikkötesteissä käytetään **Node.js-testirunneria** (`tests/unit/`), suoritetaan `npm run test:plan3`:n kautta. Lähdekoodi kohdassa `src/` on **TypeScript** (`.ts`/`.tsx`); `open-sse/`-työtila pysyy JavaScriptina (`.js`).
+8. Asetukset-sivu on järjestetty viiteen välilehteen: Suojaus, Reititys (6 globaalia strategiaa: täytä ensin, round-robin, p2c, satunnainen, vähiten käytetty, kustannusoptimoitu), Resilience (muokattavat nopeusrajoitukset, katkaisija, käytännöt), AI (ajattelubudjetti, järjestelmäkehote, kehote välimuisti), Advanced (välityspalvelin).
+
+## Toimintavarmennusten tarkistuslista
+
+- Koonti lähteestä: `npm run build`
+- Rakenna Docker-kuva: `docker build -t omniroute .`
+- Aloita huolto ja varmista:
+- `GET /api/settings`
+- `GET /api/v1/models`
+- CLI-kohteen perus-URL-osoitteen tulee olla `http://<host>:20128/v1`, kun `PORT=20128`

docs/i18n/fi/CODEBASE_DOCUMENTATION.md

@@ -0,0 +1,589 @@
+# omniroute — Codebase-dokumentaatio
+
+🌐 **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)
+
+> Kattava, aloittelijaystävällinen opas **omniroute** usean palveluntarjoajan AI-välityspalvelimen reitittimeen.
+
+---
+
+## 1. Mikä on omniroute?
+
+omniroute on **välityspalvelinreititin**, joka sijaitsee AI-asiakkaiden (Claude CLI, Codex, Cursor IDE jne.) ja tekoälypalvelujen tarjoajien (Anthropic, Google, OpenAI, AWS, GitHub jne.) välillä. Se ratkaisee yhden suuren ongelman:
+
+> **Eri AI-asiakkaat puhuvat eri "kieliä" (API-muotoja), ja eri tekoälypalveluntarjoajat odottavat myös erilaisia "kieliä".** Omniroute kääntää niiden välillä automaattisesti.
+
+Ajattele sitä kuin yleinen kääntäjä Yhdistyneissä Kansakunnissa – jokainen edustaja voi puhua mitä tahansa kieltä, ja kääntäjä muuntaa sen kenelle tahansa muulle edustajalle.
+
+---
+
+## 2. Arkkitehtuurin yleiskatsaus
+
+```mermaid
+graph LR
+    subgraph Clients
+        A[Claude CLI]
+        B[Codex]
+        C[Cursor IDE]
+        D[OpenAI-compatible]
+    end
+
+    subgraph omniroute
+        E[Handler Layer]
+        F[Translator Layer]
+        G[Executor Layer]
+        H[Services Layer]
+    end
+
+    subgraph Providers
+        I[Anthropic Claude]
+        J[Google Gemini]
+        K[OpenAI / Codex]
+        L[GitHub Copilot]
+        M[AWS Kiro]
+        N[Antigravity]
+        O[Cursor API]
+    end
+
+    A --> E
+    B --> E
+    C --> E
+    D --> E
+    E --> F
+    F --> G
+    G --> I
+    G --> J
+    G --> K
+    G --> L
+    G --> M
+    G --> N
+    G --> O
+    H -.-> E
+    H -.-> G
+```
+
+### Keskeinen periaate: Keskittimen ja puheen käännös
+
+Kaikki muotojen käännökset kulkevat **OpenAI-muodon kautta keskittimenä**:
+
+```
+Client Format → [OpenAI Hub] → Provider Format    (request)
+Provider Format → [OpenAI Hub] → Client Format    (response)
+```
+
+Tämä tarkoittaa, että tarvitset vain **N kääntäjää** (yksi per muoto) **N²** (jokainen pari) sijaan.
+
+---
+
+## 3. Projektin rakenne
+
+```
+omniroute/
+├── open-sse/                  ← Core proxy library (portable, framework-agnostic)
+│   ├── index.js               ← Main entry point, exports everything
+│   ├── config/                ← Configuration & constants
+│   ├── executors/             ← Provider-specific request execution
+│   ├── handlers/              ← Request handling orchestration
+│   ├── services/              ← Business logic (auth, models, fallback, usage)
+│   ├── translator/            ← Format translation engine
+│   │   ├── request/           ← Request translators (8 files)
+│   │   ├── response/          ← Response translators (7 files)
+│   │   └── helpers/           ← Shared translation utilities (6 files)
+│   └── utils/                 ← Utility functions
+├── src/                       ← Application layer (Express/Worker runtime)
+│   ├── app/                   ← Web UI, API routes, middleware
+│   ├── lib/                   ← Database, auth, and shared library code
+│   ├── mitm/                  ← Man-in-the-middle proxy utilities
+│   ├── models/                ← Database models
+│   ├── shared/                ← Shared utilities (wrappers around open-sse)
+│   ├── sse/                   ← SSE endpoint handlers
+│   └── store/                 ← State management
+├── data/                      ← Runtime data (credentials, logs)
+│   └── provider-credentials.json   (external credentials override, gitignored)
+└── tester/                    ← Test utilities
+```
+
+---
+
+## 4. Erittely moduulilta
+
+### 4.1 Config (`open-sse/config/`)
+
+**yksi totuuden lähde** kaikille palveluntarjoajan määrityksille.
+
+| Tiedosto                      | Tarkoitus                                                                                                                                                                                                                                                            |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `constants.ts`                | `PROVIDERS`-objekti, jossa on perus-URL-osoitteet, OAuth-tunnistetiedot (oletukset), otsikot ja oletusarvoiset järjestelmäkehotteet jokaiselle palveluntarjoajalle. Määrittää myös `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` ja `SKIP_PATTERNS`. |
+| `credentialLoader.ts`         | Lataa ulkoiset valtuustiedot kohteesta `data/provider-credentials.json` ja yhdistää ne kovakoodattujen oletusarvojen päälle dokumentissa `PROVIDERS`. Pitää salaisuudet poissa lähteen hallinnasta säilyttäen samalla yhteensopivuuden taaksepäin.                   |
+| `providerModels.ts`           | Keskitetty mallirekisteri: karttatoimittajan aliakset → mallitunnukset. Toiminnot, kuten `getModels()`, `getProviderByAlias()`.                                                                                                                                      |
+| `codexInstructions.ts`        | Codex-pyyntöihin lisätyt järjestelmäohjeet (muokkausrajoitukset, hiekkalaatikkosäännöt, hyväksymiskäytännöt).                                                                                                                                                        |
+| `defaultThinkingSignature.ts` | Oletusarvoiset "ajattelevat" allekirjoitukset Claude- ja Gemini-malleille.                                                                                                                                                                                           |
+| `ollamaModels.ts`             | Kaaviomäärittely paikallisille Ollama-malleille (nimi, koko, perhe, kvantisointi).                                                                                                                                                                                   |
+
+#### Tunnistetietojen latausvirta
+
+```mermaid
+flowchart TD
+    A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"]
+    B --> C{"data/provider-credentials.json\nexists?"}
+    C -->|Yes| D["credentialLoader reads JSON"]
+    C -->|No| E["Use hardcoded defaults"]
+    D --> F{"For each provider in JSON"}
+    F --> G{"Provider exists\nin PROVIDERS?"}
+    G -->|No| H["Log warning, skip"]
+    G -->|Yes| I{"Value is object?"}
+    I -->|No| J["Log warning, skip"]
+    I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"]
+    K --> F
+    H --> F
+    J --> F
+    F -->|Done| L["PROVIDERS ready with\nmerged credentials"]
+    E --> L
+```
+
+---
+
+### 4.2 Toimeenpanijat (`open-sse/executors/`)
+
+Toteuttajat kapseloivat **palveluntarjoajakohtaisen logiikan** käyttämällä **strategiamallia**. Jokainen suorittaja ohittaa perusmenetelmät tarpeen mukaan.
+
+```mermaid
+classDiagram
+    class BaseExecutor {
+        +buildUrl(model, stream, options)
+        +buildHeaders(credentials, stream, body)
+        +transformRequest(body, model, stream, credentials)
+        +execute(url, options)
+        +shouldRetry(status, error)
+        +refreshCredentials(credentials, log)
+    }
+
+    class DefaultExecutor {
+        +refreshCredentials()
+    }
+
+    class AntigravityExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +shouldRetry()
+        +refreshCredentials()
+    }
+
+    class CursorExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseResponse()
+        +generateChecksum()
+    }
+
+    class KiroExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseEventStream()
+        +refreshCredentials()
+    }
+
+    BaseExecutor <|-- DefaultExecutor
+    BaseExecutor <|-- AntigravityExecutor
+    BaseExecutor <|-- CursorExecutor
+    BaseExecutor <|-- KiroExecutor
+    BaseExecutor <|-- CodexExecutor
+    BaseExecutor <|-- GeminiCLIExecutor
+    BaseExecutor <|-- GithubExecutor
+```
+
+| Toteuttaja       | Palveluntarjoaja                           | Keskeiset erikoisalat                                                                                                                             |
+| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `base.ts`        | —                                          | Abstrakti pohja: URL-osoitteiden rakentaminen, otsikot, uudelleenyrityslogiikka, tunnistetietojen päivitys                                        |
+| `default.ts`     | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Yleinen OAuth-tunnuksen päivitys vakiopalveluntarjoajille                                                                                         |
+| `antigravity.ts` | Google Cloud Code                          | Projektin/istunnon tunnuksen luominen, usean URL-osoitteen varaosa, mukautettu uudelleenjäsennysyritys virheilmoituksista ("reset after 2t7m23s") |
+| `cursor.ts`      | Kohdistin IDE                              | **Monimutkaisin**: SHA-256-tarkistussumman todennus, Protobuf-pyynnön koodaus, binaarinen EventStream → SSE-vastauksen jäsennys                   |
+| `codex.ts`       | OpenAI Codex                               | Lisää järjestelmäkäskyjä, hallitsee ajattelutasoja, poistaa ei-tuetut parametrit                                                                  |
+| `gemini-cli.ts`  | Google Gemini CLI                          | Muokatun URL-osoitteen rakentaminen (`streamGenerateContent`), Google OAuth -tunnuksen päivitys                                                   |
+| `github.ts`      | GitHub Copilot                             | Kaksoistunnistejärjestelmä (GitHub OAuth + Copilot-tunnus), VSCode-otsikon matkiminen                                                             |
+| `kiro.ts`        | AWS CodeWhisperer                          | AWS EventStream binäärijäsennys, AMZN-tapahtumakehykset, tunnuksen arviointi                                                                      |
+| `index.ts`       | —                                          | Tehdas: karttojen toimittajan nimi → suorittajaluokka, oletusarvolla                                                                              |
+
+---
+
+### 4.3 Käsittelijät (`open-sse/handlers/`)
+
+**orkestrointikerros** — koordinoi käännöstä, suoritusta, suoratoistoa ja virheiden käsittelyä.
+
+| Tiedosto              | Tarkoitus                                                                                                                                                                                                              |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chatCore.ts`         | **Keskiorkesteri** (~600 riviä). Käsittelee koko pyynnön elinkaaren: muodon tunnistus → käännös → suorittimen lähettäminen → suoratoisto/ei-suoratoistovaste → tunnuksen päivitys → virheiden käsittely → käytön loki. |
+| `responsesHandler.ts` | Sovitin OpenAI:n Responses API:lle: muuntaa vastausmuodon → Chat Completions → lähettää osoitteeseen `chatCore` → muuntaa SSE:n takaisin Responses-muotoon.                                                            |
+| `embeddings.ts`       | Upottamisen sukupolven käsittelijä: ratkaisee upotusmallin → toimittaja, lähettää palveluntarjoajan API:lle, palauttaa OpenAI-yhteensopivan upotusvastauksen. Tukee 6+ palveluntarjoajia.                              |
+| `imageGeneration.ts`  | Kuvanluontikäsittelijä: ratkaisee kuvamallin → palveluntarjoajan, tukee OpenAI-yhteensopivia, Gemini-image- (Antigravity) ja backback (Nebius) -tiloja. Palauttaa base64- tai URL-kuvat.                               |
+
+#### Pyydä elinkaarta (chatCore.ts)
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant chatCore
+    participant Translator
+    participant Executor
+    participant Provider
+
+    Client->>chatCore: Request (any format)
+    chatCore->>chatCore: Detect source format
+    chatCore->>chatCore: Check bypass patterns
+    chatCore->>chatCore: Resolve model & provider
+    chatCore->>Translator: Translate request (source → OpenAI → target)
+    chatCore->>Executor: Get executor for provider
+    Executor->>Executor: Build URL, headers, transform request
+    Executor->>Executor: Refresh credentials if needed
+    Executor->>Provider: HTTP fetch (streaming or non-streaming)
+
+    alt Streaming
+        Provider-->>chatCore: SSE stream
+        chatCore->>chatCore: Pipe through SSE transform stream
+        Note over chatCore: Transform stream translates<br/>each chunk: target → OpenAI → source
+        chatCore-->>Client: Translated SSE stream
+    else Non-streaming
+        Provider-->>chatCore: JSON response
+        chatCore->>Translator: Translate response
+        chatCore-->>Client: Translated JSON
+    end
+
+    alt Error (401, 429, 500...)
+        chatCore->>Executor: Retry with credential refresh
+        chatCore->>chatCore: Account fallback logic
+    end
+```
+
+---
+
+### 4.4 Palvelut (`open-sse/services/`)
+
+Liiketoimintalogiikka, joka tukee käsittelijöitä ja toimeenpanijoita.
+
+| Tiedosto             | Tarkoitus                                                                                                                                                                                                                                                                                                                                                                |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `provider.ts`        | **Muodon tunnistus** (`detectFormat`): analysoi pyyntörunkorakenteen tunnistaakseen Claude-/OpenAI-/Gemini-/Antigravity-/Responses-muodot (sisältää Clauden `max_tokens`-heuristiikan). Myös: URL-osoitteiden rakentaminen, otsikon rakentaminen, ajatteluasetusten normalisointi. Tukee dynaamisia palveluntarjoajia `openai-compatible-*` ja `anthropic-compatible-*`. |
+| `model.ts`           | Mallin merkkijonon jäsennys (`claude/model-name` → `{provider: "claude", model: "model-name"}`), aliaksen tarkkuus törmäystunnistuksen kanssa, syötteen puhdistus (hylkää polun läpikulku/ohjausmerkit) ja mallitietojen resoluutio asynkronisen aliaksen hakijan tuella.                                                                                                |
+| `accountFallback.ts` | Rate-limit käsittely: eksponentiaalinen backoff (1s → 2s → 4s → max 2min), tilin jäähtymisen hallinta, virheluokitus (jotka virheet laukaisevat varauksen tai eivät).                                                                                                                                                                                                    |
+| `tokenRefresh.ts`    | OAuth-tunnuksen päivitys **jokaiselle palveluntarjoajalle**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Sisältää lennon aikana tapahtuvan lupauksen poistamisen välimuistin ja uudelleenyrityksen eksponentiaalisella peruutuksella.                                              |
+| `combo.ts`           | **Yhdistelmämallit**: varamallien ketjut. Jos malli A epäonnistuu varautumiskelpoisen virheen vuoksi, kokeile mallia B, sitten C jne. Palauttaa todelliset ylävirran tilakoodit.                                                                                                                                                                                         |
+| `usage.ts`           | Hakee kiintiö-/käyttötiedot palveluntarjoajan sovellusliittymistä (GitHub Copilot -kiintiöt, Antigravity-mallikiintiöt, Codexin nopeusrajoitukset, Kiron käyttöerittelyt, Claude-asetukset).                                                                                                                                                                             |
+| `accountSelector.ts` | Älykäs tilin valinta pisteytysalgoritmilla: ottaa huomioon prioriteetin, terveydentilan, kiertorajan sijainnin ja jäähtymistilan valitakseen optimaalisen tilin kullekin pyynnölle.                                                                                                                                                                                      |
+| `contextManager.ts`  | Pyynnön kontekstin elinkaaren hallinta: luo ja seuraa pyyntökohtaisia ​​kontekstiobjekteja metatiedoilla (pyyntötunnus, aikaleimat, palveluntarjoajan tiedot) virheenkorjausta ja lokia varten.                                                                                                                                                                          |
+| `ipFilter.ts`        | IP-pohjainen pääsynhallinta: tukee sallittu- ja estolistatiloja. Vahvistaa asiakkaan IP-osoitteen määritettyjen sääntöjen mukaan ennen API-pyyntöjen käsittelemistä.                                                                                                                                                                                                     |
+| `sessionManager.ts`  | Istuntoseuranta asiakkaan sormenjälkien avulla: seuraa aktiivisia istuntoja hajautettujen asiakastunnisteiden avulla, valvoo pyyntöjen määrää ja tarjoaa istuntomittareita.                                                                                                                                                                                              |
+| `signatureCache.ts`  | Pyynnön allekirjoituspohjainen deduplikoinnin välimuisti: estää päällekkäiset pyynnöt tallentamalla välimuistiin viimeaikaiset pyyntöjen allekirjoitukset ja palauttamalla välimuistissa olevat vastaukset identtisille pyynnöille tietyn aikaikkunan sisällä.                                                                                                           |
+| `systemPrompt.ts`    | Yleinen järjestelmäkehotteen lisäys: liittää kaikkien pyyntöjen edelle tai liittää määritettävän järjestelmäkehotteen palveluntarjoajakohtaisen yhteensopivuuden käsittelyn avulla.                                                                                                                                                                                      |
+| `thinkingBudget.ts`  | Päättelytunnisteen budjetin hallinta: tukee läpivienti-, automaatti- (kaistaleiden ajattelukonfiguraatio), mukautettua (kiinteä budjetti) ja mukautuva (monimutkaisuusskaalaus) -tiloja ajattelun/päättelyn hallintaan.                                                                                                                                                  |
+| `wildcardRouter.ts`  | Jokerimerkkimallin reititys: ratkaisee jokerimerkkimallit (esim. `*/claude-*`) konkreettisiksi toimittaja/malli-pareiksi saatavuuden ja prioriteetin perusteella.                                                                                                                                                                                                        |
+
+#### Token Refresh Deduplication
+
+```mermaid
+sequenceDiagram
+    participant R1 as Request 1
+    participant R2 as Request 2
+    participant Cache as refreshPromiseCache
+    participant OAuth as OAuth Provider
+
+    R1->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: No in-flight promise
+    Cache->>OAuth: Start refresh
+    R2->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: Found in-flight promise
+    Cache-->>R2: Return existing promise
+    OAuth-->>Cache: New access token
+    Cache-->>R1: New access token
+    Cache-->>R2: Same access token (shared)
+    Cache->>Cache: Delete cache entry
+```
+
+#### Tilin varatilakone
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active
+    Active --> Error: Request fails (401/429/500)
+    Error --> Cooldown: Apply backoff
+    Cooldown --> Active: Cooldown expires
+    Active --> Active: Request succeeds (reset backoff)
+
+    state Error {
+        [*] --> ClassifyError
+        ClassifyError --> ShouldFallback: Rate limit / Auth / Transient
+        ClassifyError --> NoFallback: 400 Bad Request
+    }
+
+    state Cooldown {
+        [*] --> ExponentialBackoff
+        ExponentialBackoff: Level 0 = 1s
+        ExponentialBackoff: Level 1 = 2s
+        ExponentialBackoff: Level 2 = 4s
+        ExponentialBackoff: Max = 2min
+    }
+```
+
+#### Yhdistelmämalliketju
+
+```mermaid
+flowchart LR
+    A["Request with\ncombo model"] --> B["Model A"]
+    B -->|"2xx Success"| C["Return response"]
+    B -->|"429/401/500"| D{"Fallback\neligible?"}
+    D -->|Yes| E["Model B"]
+    D -->|No| F["Return error"]
+    E -->|"2xx Success"| C
+    E -->|"429/401/500"| G{"Fallback\neligible?"}
+    G -->|Yes| H["Model C"]
+    G -->|No| F
+    H -->|"2xx Success"| C
+    H -->|"Fail"| I["All failed →\nReturn last status"]
+```
+
+---
+
+### 4.5 Kääntäjä (`open-sse/translator/`)
+
+**muotojen käännösmoottori**, joka käyttää itse rekisteröivää laajennusjärjestelmää.
+
+#### Arkkitehtuuri
+
+```mermaid
+graph TD
+    subgraph "Request Translation"
+        A["Claude → OpenAI"]
+        B["Gemini → OpenAI"]
+        C["Antigravity → OpenAI"]
+        D["OpenAI Responses → OpenAI"]
+        E["OpenAI → Claude"]
+        F["OpenAI → Gemini"]
+        G["OpenAI → Kiro"]
+        H["OpenAI → Cursor"]
+    end
+
+    subgraph "Response Translation"
+        I["Claude → OpenAI"]
+        J["Gemini → OpenAI"]
+        K["Kiro → OpenAI"]
+        L["Cursor → OpenAI"]
+        M["OpenAI → Claude"]
+        N["OpenAI → Antigravity"]
+        O["OpenAI → Responses"]
+    end
+```
+
+| Hakemisto    | Tiedostot   | Kuvaus                                                                                                                                                                                                                                                 |
+| ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `request/`   | 8 kääntäjää | Muunna pyyntörungot muotojen välillä. Jokainen tiedosto rekisteröi itse itsensä tuonnin yhteydessä `register(from, to, fn)`:n kautta.                                                                                                                  |
+| `response/`  | 7 kääntäjää | Muunna suoratoistovastauspalat muotojen välillä. Käsittelee SSE-tapahtumatyyppejä, ajattelulohkoja, työkalukutsuja.                                                                                                                                    |
+| `helpers/`   | 6 avustajaa | Jaetut apuohjelmat: `claudeHelper` (järjestelmäkehotteen purkaminen, ajattelukonfiguraatio), `geminiHelper` (osien/sisällön kartoitus), `openaiHelper` (muotosuodatus), `toolCallHelper`), \_TOK-sukupolvi_EN_1, vastaus puuttuu `responsesApiHelper`. |
+| `index.ts`   | —           | Käännöskone: `translateRequest()`, `translateResponse()`, tilanhallinta, rekisteri.                                                                                                                                                                    |
+| `formats.ts` | —           | Muotovakiot: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`_, \_\_EN_92_NI, _.                                                                                                                                                          |
+
+#### Avainsuunnittelu: Itserekisteröityvät laajennukset
+
+```javascript
+// Each translator file calls register() on import:
+import { register } from "../index.js";
+register("claude", "openai", translateClaudeToOpenAI);
+
+// The index.js imports all translator files, triggering registration:
+import "./request/claude-to-openai.js"; // ← self-registers
+```
+
+---
+
+### 4.6 Utilis (`open-sse/utils/`)
+
+| Tiedosto           | Tarkoitus                                                                                                                                                                                                                                                                                             |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `error.ts`         | Virhevastausten rakentaminen (OpenAI-yhteensopiva muoto), ylävirran virheen jäsennys, Antigravitaatio-uudelleenyritysten poimiminen virheilmoituksista, SSE-virheiden suoratoisto.                                                                                                                    |
+| `stream.ts`        | **SSE Transform Stream** — suoratoiston ydinputki. Kaksi tilaa: `TRANSLATE` (täysmuotoinen käännös) ja `PASSTHROUGH` (normalisoi + pura käyttö). Käsittelee osien puskuroinnin, käyttöarvioinnin ja sisällön pituuden seurannan. Virtakohtaiset enkooderi/dekooderiinstanssit välttävät jaetun tilan. |
+| `streamHelpers.ts` | Matalan tason SSE-apuohjelmat: `parseSSELine` (välilyöntejä sietävä), `hasValuableContent` (suodattaa tyhjät osat OpenAI:lle/Claudelle/Geminille), `fixInvalidId`, `fixInvalidId`, `perf_metrics` puhdistus).                                                                                         |
+| `usageTracking.ts` | Tokenin käytön poiminta mistä tahansa muodosta (Claude/OpenAI/Gemini/Responses), arvio erillisillä työkalu/viestin char-per-token-suhteilla, puskurin lisäys (2000 merkkiä turvamarginaali), muotokohtainen kenttäsuodatus, konsolin kirjaaminen ANSI-väreillä.                                       |
+| `requestLogger.ts` | Tiedostopohjainen pyyntöjen kirjaaminen (osallistu osoitteen `ENABLE_REQUEST_LOGS=true` kautta). Luo istuntokansioita numeroiduilla tiedostoilla: `1_req_client.json` → `7_res_client.txt`. Kaikki I/O on async (fire-and-forget). Peittää herkät otsikot.                                            |
+| `bypassHandler.ts` | Kaappaa tiettyjä malleja Claude CLI:stä (otsikon poimiminen, lämmittely, laskenta) ja palauttaa vääriä vastauksia soittamatta palveluntarjoajille. Tukee sekä suoratoistoa että ei-suoratoistoa. Tarkoituksella rajoitettu Claude CLI:n soveltamisalaan.                                              |
+| `networkProxy.ts`  | Ratkaisee tietyn palveluntarjoajan lähtevän välityspalvelimen URL-osoitteen etusijalla: palveluntarjoajakohtainen määritys → globaali määritys → ympäristömuuttujat (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Tukee `NO_PROXY` poissulkemista. Välimuistin konfiguraatio 30 sekuntia.                 |
+
+#### SSE Streaming Pipeline
+
+```mermaid
+flowchart TD
+    A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"]
+    B --> C["Buffer lines\n(split on newline)"]
+    C --> D["parseSSELine()\n(trim whitespace, parse JSON)"]
+    D --> E{"Mode?"}
+    E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"]
+    E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"]
+    F --> H["hasValuableContent()\nfilter empty chunks"]
+    G --> H
+    H -->|"Has content"| I["extractUsage()\ntrack token counts"]
+    H -->|"Empty"| J["Skip chunk"]
+    I --> K["formatSSE()\nserialize + clean perf_metrics"]
+    K --> L["TextEncoder\n(per-stream instance)"]
+    L --> M["Enqueue to\nclient stream"]
+
+    style A fill:#f9f,stroke:#333
+    style M fill:#9f9,stroke:#333
+```
+
+#### Pyydä Loggerin istuntorakennetta
+
+```
+logs/
+└── claude_gemini_claude-sonnet_20260208_143045/
+    ├── 1_req_client.json      ← Raw client request
+    ├── 2_req_source.json      ← After initial conversion
+    ├── 3_req_openai.json      ← OpenAI intermediate format
+    ├── 4_req_target.json      ← Final target format
+    ├── 5_res_provider.txt     ← Provider SSE chunks (streaming)
+    ├── 5_res_provider.json    ← Provider response (non-streaming)
+    ├── 6_res_openai.txt       ← OpenAI intermediate chunks
+    ├── 7_res_client.txt       ← Client-facing SSE chunks
+    └── 6_error.json           ← Error details (if any)
+```
+
+---
+
+### 4.7 Sovelluskerros (`src/`)
+
+| Hakemisto     | Tarkoitus                                                                               |
+| ------------- | --------------------------------------------------------------------------------------- |
+| `src/app/`    | Verkkokäyttöliittymä, API-reitit, Express-väliohjelmisto, OAuth-soittojen käsittelijät  |
+| `src/lib/`    | Tietokannan käyttöoikeus (`localDb.ts`, `usageDb.ts`), todennus, jaettu                 |
+| `src/mitm/`   | Man-in-the-middle-välityspalvelinapuohjelmat palveluntarjoajan liikenteen sieppaamiseen |
+| `src/models/` | Tietokantamallin määritelmät                                                            |
+| `src/shared/` | Open-sse-funktioiden kääreet (tarjoaja, virta, virhe jne.)                              |
+| `src/sse/`    | SSE-päätepisteen käsittelijät, jotka yhdistävät avoimen SS-kirjaston Express-reiteille  |
+| `src/store/`  | Sovellustilan hallinta                                                                  |
+
+#### Merkittäviä API-reitit
+
+| Reitti                                        | Menetelmät          | Tarkoitus                                                                                       |
+| --------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------- |
+| `/api/provider-models`                        | HANKI/LÄHETÄ/POISTA | CRUD mukautetuille malleille toimittajakohtaisesti                                              |
+| `/api/models/catalog`                         | HANKI               | Koottu luettelo kaikista malleista (chat, upotus, kuva, mukautettu) ryhmitelty tarjoajan mukaan |
+| `/api/settings/proxy`                         | GET/PUT/DELETE      | Hierarkkinen lähtevän välityspalvelimen määritys (`global/providers/combos/keys`)               |
+| `/api/settings/proxy/test`                    | POST                | Vahvistaa välityspalvelinyhteyden ja palauttaa julkisen IP-osoitteen/latenssin                  |
+| `/v1/providers/[provider]/chat/completions`   | POST                | Palveluntarjoajakohtaiset keskustelut ja mallin vahvistus                                       |
+| `/v1/providers/[provider]/embeddings`         | POST                | Palveluntarjoajakohtaiset upotukset mallin vahvistuksella                                       |
+| `/v1/providers/[provider]/images/generations` | POST                | Palveluntarjoajakohtainen kuvien luominen mallin tarkistuksen kanssa                            |
+| `/api/settings/ip-filter`                     | GET/PUT             | IP-sallittujen/estoluetteloiden hallinta                                                        |
+| `/api/settings/thinking-budget`               | GET/PUT             | Päättelytunnuksen budjetin määritys (passthrough/auto/custom/adaptive)                          |
+| `/api/settings/system-prompt`                 | GET/PUT             | Globaali järjestelmän pikainjektio kaikkiin pyyntöihin                                          |
+| `/api/sessions`                               | HANKI               | Aktiivisen istunnon seuranta ja mittarit                                                        |
+| `/api/rate-limits`                            | HANKI               | Tilikohtaisen koron rajan tila                                                                  |
+
+---
+
+## 5. Key Design Patterns
+
+### 5.1 Hub-and-Spoke -käännös
+
+Kaikki muodot käännetään **OpenAI-muodon kautta keskittimenä**. Uuden palveluntarjoajan lisääminen edellyttää vain **yksi parin** kirjoittamista (OpenAI:lle/OpenAI:sta), ei N paria.
+
+### 5.2 Toteuttajastrategiamalli
+
+Jokaisella palveluntarjoajalla on oma suorittajaluokka, joka perii `BaseExecutor`. Tehdas kohteessa `executors/index.ts` valitsee oikean suorituksen aikana.
+
+### 5.3 Itserekisteröivä laajennusjärjestelmä
+
+Kääntäjämoduulit rekisteröivät itsensä tuontia varten osoitteessa `register()`. Uuden kääntäjän lisääminen on vain tiedoston luomista ja sen tuomista.
+
+### 5.4 Tilin palautus eksponentiaalisella backoffilla
+
+Kun palveluntarjoaja palauttaa numeron 429/401/500, järjestelmä voi siirtyä seuraavalle tilille käyttämällä eksponentiaalisia viilennyksiä (1 s → 2 s → 4 s → max 2 min).
+
+### 5.5 yhdistelmämalliketjut
+
+"Yhdistelmä" ryhmittelee useita `provider/model` merkkijonoja. Jos ensimmäinen epäonnistuu, palaa automaattisesti seuraavaan.
+
+### 5.6 Tilallinen suoratoistokäännös
+
+Vastauskäännös säilyttää tilan SSE-paloissa (ajattelulohkojen seuranta, työkalukutsujen kerääminen, sisältölohkojen indeksointi) `initState()`-mekanismin kautta.
+
+### 5.7 Käyttöturvapuskuri
+
+Raportoituun käyttöön lisätään 2 000 tunnuksen puskuri, joka estää asiakkaita saavuttamasta kontekstiikkunan rajoja järjestelmäkehotteiden ja muotojen käännöksen aiheuttaman ylimääräisen rasituksen vuoksi.
+
+---
+
+## 6. Tuetut muodot
+
+| Muoto                                  | Suunta        | Tunniste           |
+| -------------------------------------- | ------------- | ------------------ |
+| OpenAI-keskustelun loppuun saattaminen | lähde + kohde | `openai`           |
+| OpenAI Responses API                   | lähde + kohde | `openai-responses` |
+| Antrooppinen Claude                    | lähde + kohde | `claude`           |
+| Google Gemini                          | lähde + kohde | `gemini`           |
+| Google Gemini CLI                      | vain kohde    | `gemini-cli`       |
+| Antigravitaatio                        | lähde + kohde | `antigravity`      |
+| AWS Kiro                               | vain kohde    | `kiro`             |
+| Kursori                                | vain kohde    | `cursor`           |
+
+---
+
+## 7. Tuetut palveluntarjoajat
+
+| Palveluntarjoaja         | Todennusmenetelmä         | Toteuttaja      | Tärkeimmät huomautukset                                    |
+| ------------------------ | ------------------------- | --------------- | ---------------------------------------------------------- |
+| Antrooppinen Claude      | API-avain tai OAuth       | Oletus          | Käyttää `x-api-key`-otsikkoa                               |
+| Google Gemini            | API-avain tai OAuth       | Oletus          | Käyttää `x-goog-api-key`-otsikkoa                          |
+| Google Gemini CLI        | OAuth                     | GeminiCLI       | Käyttää `streamGenerateContent` päätepistettä              |
+| Antigravitaatio          | OAuth                     | Antigravitaatio | Usean URL-osoitteen varaosa, mukautettu jäsennys uudelleen |
+| OpenAI                   | API-avain                 | Oletus          | Vakiosiirtotodennus                                        |
+| Codex                    | OAuth                     | Codex           | Ruiskuttaa järjestelmäohjeita, hallitsee ajattelua         |
+| GitHub Copilot           | OAuth + Copilot-tunnus    | Github          | Kaksoistunnus, VSCode-otsikkoa jäljittelevä                |
+| Kiro (AWS)               | AWS SSO OIDC tai Social   | Kiro            | Binäärinen EventStream-jäsennys                            |
+| Kohdistin IDE            | Tarkistussumma auth       | Kursori         | Protobuf-koodaus, SHA-256-tarkistussummat                  |
+| Qwen                     | OAuth                     | Oletus          | Vakiotodennus                                              |
+| iFlow                    | OAuth (Perus + siirtotie) | Oletus          | Dual auth otsikko                                          |
+| OpenRouter               | API-avain                 | Oletus          | Vakiosiirtotodennus                                        |
+| GLM, Kimi, MiniMax       | API-avain                 | Oletus          | Claude-yhteensopiva, käytä `x-api-key`                     |
+| `openai-compatible-*`    | API-avain                 | Oletus          | Dynaaminen: mikä tahansa OpenAI-yhteensopiva päätepiste    |
+| `anthropic-compatible-*` | API-avain                 | Oletus          | Dynaaminen: mikä tahansa Claude-yhteensopiva päätepiste    |
+
+---
+
+## 8. Tietovirran yhteenveto
+
+### Suoratoistopyyntö
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor\nbuildUrl + buildHeaders"]
+    D --> E["fetch(providerURL)"]
+    E --> F["createSSEStream()\nTRANSLATE mode"]
+    F --> G["parseSSELine()"]
+    G --> H["translateResponse()\ntarget → OpenAI → source"]
+    H --> I["extractUsage()\n+ addBuffer"]
+    I --> J["formatSSE()"]
+    J --> K["Client receives\ntranslated SSE"]
+    K --> L["logUsage()\nsaveRequestUsage()"]
+```
+
+### Ei-suoratoistopyyntö
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor.execute()"]
+    D --> E["translateResponse()\ntarget → OpenAI → source"]
+    E --> F["Return JSON\nresponse"]
+```
+
+### Ohitusvirtaus (Claude CLI)
+
+```mermaid
+flowchart LR
+    A["Claude CLI request"] --> B{"Match bypass\npattern?"}
+    B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"]
+    B -->|"No match"| D["Normal flow"]
+    C --> E["Translate to\nsource format"]
+    E --> F["Return without\ncalling provider"]
+```

docs/i18n/fi/FEATURES.md

@@ -0,0 +1,77 @@
+# OmniRoute — Kojelaudan ominaisuuksien galleria
+
+🌐 **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)
+
+Visuaalinen opas OmniRoute-hallintapaneelin jokaiseen osioon.
+
+---
+
+## 🔌 Palveluntarjoajat
+
+Hallinnoi AI-palveluntarjoajan yhteyksiä: OAuth-palveluntarjoajat (Claude Code, Codex, Gemini CLI), API-avaintoimittajat (Groq, DeepSeek, OpenRouter) ja ilmaiset palveluntarjoajat (iFlow, Qwen, Kiro).
+
+![Providers Dashboard](screenshots/01-providers.png)
+
+---
+
+## 🎨 Yhdistelmät
+
+Luo mallin reitityskomboja kuudella strategialla: täytä ensin, round-robin, kahden valinnan teho, satunnainen, vähiten käytetty ja kustannusoptimoitu. Jokainen yhdistelmä ketjuttaa useita malleja automaattisella varalla.
+
+![Combos Dashboard](screenshots/02-combos.png)
+
+---
+
+## 📊 Analytiikka
+
+Kattava käyttöanalytiikka tunnuksen kulutuksella, kustannusarvioilla, aktiivisuuslämpökartoilla, viikoittaisilla jakelukaavioilla ja palveluntarjoajakohtaisilla erittelyillä.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
+
+---
+
+## 🏥 Järjestelmän terveys
+
+Reaaliaikainen seuranta: käyttöaika, muisti, versio, latenssiprosenttipisteet (p50/p95/p99), välimuistitilastot ja palveluntarjoajan katkaisijan tilat.
+
+![Health Dashboard](screenshots/04-health.png)
+
+---
+
+## 🔧 Kääntäjän leikkikenttä
+
+Neljä tilaa API-käännösten virheenkorjaukseen: **Playground** (muodonmuunnin), **Chat Tester** (livepyynnöt), **Test Bench** (erätestit) ja **Live Monitor** (reaaliaikainen suoratoisto).
+
+![Translator Playground](screenshots/05-translator.png)
+
+---
+
+## ⚙️ Asetukset
+
+Yleiset asetukset, järjestelmän tallennus, varmuuskopioiden hallinta (vienti/tuonti tietokanta), ulkonäkö (tumma/vaalea tila), suojaus (sisältää API-päätepisteiden suojauksen ja mukautetun palveluntarjoajan eston), reititys, joustavuus ja edistyneet asetukset.
+
+![Settings Dashboard](screenshots/06-settings.png)
+
+---
+
+## 🔧 CLI-työkalut
+
+Yhden napsautuksen konfigurointi AI-koodaustyökaluille: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code ja Antigravity.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+
+---
+
+## 📝 Pyyntölokit
+
+Reaaliaikainen pyyntöjen kirjaaminen suodatuksella palveluntarjoajan, mallin, tilin ja API-avaimen mukaan. Näyttää tilakoodit, tunnuksen käytön, viiveen ja vastaustiedot.
+
+![Usage Logs](screenshots/08-usage.png)
+
+---
+
+## 🌐 API-päätepiste
+
+Yhdistetty API-päätepisteesi ominaisuuksien erittelyllä: keskustelujen loppuunsaattaminen, upotukset, kuvien luominen, uudelleensijoitus, äänen transkriptio ja rekisteröidyt API-avaimet.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)

docs/i18n/fi/TROUBLESHOOTING.md

@@ -0,0 +1,219 @@
+# Vianetsintä
+
+🌐 **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)
+
+OmniRouten yleisiä ongelmia ja ratkaisuja.
+
+---
+
+## Pikakorjauksia
+
+| Ongelma                            | Ratkaisu                                                                    |
+| ---------------------------------- | --------------------------------------------------------------------------- |
+| Ensimmäinen kirjautuminen ei toimi | Tarkista `INITIAL_PASSWORD` kohteessa `.env` (oletus: `123456`)             |
+| Kojelauta avautuu väärään porttiin | Aseta `PORT=20128` ja `NEXT_PUBLIC_BASE_URL=http://localhost:20128`         |
+| Ei pyyntölokeja alle `logs/`       | Aseta `ENABLE_REQUEST_LOGS=true`                                            |
+| EACCES: lupa evätty                | Aseta `DATA_DIR=/path/to/writable/dir` ohittamaan `~/.omniroute`            |
+| Reititysstrategia ei tallennu      | Päivitys versioon 1.4.11+ (Zod-skeeman korjaus asetusten pysyvyyttä varten) |
+
+---
+
+## Palveluntarjoajan ongelmat
+
+### "Kielimalli ei antanut viestejä"
+
+**Syy:** Palveluntarjoajan kiintiö käytetty.
+
+**Korjaa:**
+
+1. Tarkista kojelaudan kiintiöiden seuranta
+2. Käytä yhdistelmää varatasoilla
+3. Vaihda halvempaan/ilmaiseen tasoon
+
+### Hintarajoitus
+
+**Syy:** Tilauskiintiö käytetty.
+
+**Korjaa:**
+
+- Lisää vara: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Käytä GLM/MiniMaxia halvana varmuuskopiona
+
+### OAuth-tunnus vanhentunut
+
+OmniRoute päivittää tunnukset automaattisesti. Jos ongelmat jatkuvat:
+
+1. Kojelauta → Palveluntarjoaja → Yhdistä uudelleen
+2. Poista ja lisää palveluntarjoajan yhteys uudelleen
+
+---
+
+## Pilviongelmat
+
+### Pilven synkronointivirheet
+
+1. Vahvista `BASE_URL` pistettä käynnissä olevaan esiintymääsi (esim. `http://localhost:20128`)
+2. Vahvista `CLOUD_URL` pistettä pilvipäätepisteeseesi (esim. `https://omniroute.dev`)
+3. Pidä `NEXT_PUBLIC_*`-arvot kohdakkain palvelinpuolen arvojen kanssa
+
+### Pilvi `stream=false` Palauttaa 500
+
+**Oire:** `Unexpected token 'd'...` pilvipäätepisteessä muille kuin suoratoistopuheluille.
+
+**Syy:** Upstream palauttaa SSE-hyötykuorman, kun asiakas odottaa JSONia.
+
+**Ratkaisu:** Käytä `stream=true` pilvisuorapuheluihin. Paikallinen suoritusaika sisältää SSE→JSON-varavaihtoehdon.
+
+### Cloud sanoo Yhdistetty, mutta "Virheellinen API-avain"
+
+1. Luo uusi avain paikallisesta hallintapaneelista (`/api/keys`)
+2. Suorita pilvisynkronointi: Ota pilvi käyttöön → Synkronoi nyt
+3. Vanhat/synkronoimattomat avaimet voivat edelleen palauttaa `401` pilvessä
+
+---
+
+## Docker-ongelmat
+
+### CLI-työkalu näyttää, ettei sitä ole asennettu
+
+1. Tarkista suoritusaikakentät: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. Kannettava tila: käytä kuvakohdetta `runner-cli` (yhdistetyt CLI:t)
+3. Isäntäliitostila: aseta `CLI_EXTRA_PATHS` ja liitä isäntälokerohakemisto vain luku -muotoiseksi
+4. Jos `installed=true` ja `runnable=false`: binaari löytyi, mutta kuntotarkastus epäonnistui
+
+### Nopea ajonaikainen validointi
+
+```bash
+curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+```
+
+---
+
+## Kustannusongelmat
+
+### Korkeat kustannukset
+
+1. Tarkista käyttötilastot kohdassa Dashboard → Usage
+2. Vaihda ensisijaiseksi malliksi GLM/MiniMax
+3. Käytä ilmaista tasoa (Gemini CLI, iFlow) ei-kriittisiin tehtäviin
+4. Aseta kustannusbudjetit API-avainta kohti: Dashboard → API Keys → Budget
+
+---
+
+## Virheenkorjaus
+
+### Ota pyyntölokit käyttöön
+
+Aseta `ENABLE_REQUEST_LOGS=true` tiedostossasi `.env`. Lokit näkyvät hakemistossa `logs/`.
+
+### Tarkista palveluntarjoajan kunto
+
+```bash
+# Health dashboard
+http://localhost:20128/dashboard/health
+
+# API health check
+curl http://localhost:20128/api/monitoring/health
+```
+
+### Ajonaikainen tallennus
+
+- Päätila: `${DATA_DIR}/db.json` (palveluntarjoajat, yhdistelmät, aliakset, avaimet, asetukset)
+- Käyttö: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
+- Pyyntölokit: `<repo>/logs/...` (kun `ENABLE_REQUEST_LOGS=true`)
+
+---
+
+## Virtakatkaisijaongelmat
+
+### Palveluntarjoaja jumissa OPEN-tilassa
+
+Kun palveluntarjoajan katkaisija on AUKI, pyynnöt estetään, kunnes jäähdytys päättyy.
+
+**Korjaa:**
+
+1. Siirry kohtaan **Käyttöpaneeli → Asetukset → Resilience**
+2. Tarkista asianomaisen palveluntarjoajan katkaisijakortti
+3. Napsauta **Nollaa kaikki** tyhjentääksesi kaikki katkaisijat tai odota jäähdytysajan päättymistä
+4. Varmista, että palveluntarjoaja on todella saatavilla, ennen kuin nollaat
+
+### Palveluntarjoaja laukeaa jatkuvasti katkaisijan
+
+Jos palveluntarjoaja siirtyy toistuvasti OPEN-tilaan:
+
+1. Tarkista vikakuvio kohdasta **Dashboard → Health → Provider Health**
+2. Siirry kohtaan **Settings → Resilience → Provider Profiles** ja nosta vikakynnystä.
+3. Tarkista, onko palveluntarjoaja muuttanut API-rajoja tai vaatiiko todennuksen uudelleen
+4. Tarkista viiveen telemetria — korkea latenssi voi aiheuttaa aikakatkaisuun perustuvia virheitä
+
+---
+
+## Äänen transkriptioongelmat
+
+### "Ei tuettu malli" -virhe
+
+- Varmista, että käytät oikeaa etuliitettä: `deepgram/nova-3` tai `assemblyai/best`
+- Varmista, että palveluntarjoaja on yhdistetty kohdassa **Dashboard → Providers**
+
+### Transkriptio palautetaan tyhjänä tai epäonnistuu
+
+- Tarkista tuetut äänimuodot: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Varmista, että tiedostokoko on palveluntarjoajan rajoissa (yleensä < 25 Mt)
+- Tarkista palveluntarjoajan API-avaimen voimassaolo toimittajakortista
+
+---
+
+## Kääntäjän virheenkorjaus
+
+Käytä **Käyttöpaneeli → Kääntäjä** muotojen käännösongelmien korjaamiseen:
+
+| Tila                      | Milloin käyttää                                                                                         |
+| ------------------------- | ------------------------------------------------------------------------------------------------------- |
+| **Leikkikenttä**          | Vertaa syöttö-/tulostusmuotoja rinnakkain – liitä epäonnistunut pyyntö nähdäksesi, miten se käännetään  |
+| **Pikaviestien testaaja** | Lähetä reaaliaikaisia ​​viestejä ja tarkasta koko pyynnön/vastauksen hyötykuorma, mukaan lukien otsikot |
+| **Testipenkki**           | Suorita erätestejä muotoyhdistelmille selvittääksesi, mitkä käännökset ovat rikki                       |
+| **Live Monitor**          | Tarkkaile reaaliaikaista pyyntövirtaa havaitaksesi ajoittaiset käännösongelmat                          |
+
+### Yleisiä muotoongelmia
+
+- **Ajattelevat tunnisteet eivät näy** — Tarkista, tukeeko kohdetoimittaja ajattelua ja ajattelun budjettiasetusta
+- **Työkalukutsujen pudottaminen** — Jotkin muotokäännökset voivat poistaa ei-tuetut kentät. vahvista leikkikenttätilassa
+- **Järjestelmäkehote puuttuu** — Claude ja Gemini kahvajärjestelmä kehottaa eri tavalla; tarkista käännöstulos
+- **SDK palauttaa raakamerkkijonon objektin sijaan** — Korjattu versiossa 1.1.0: vastauspuhdistin poistaa nyt epästandardit kentät (`x_groq`, `usage_breakdown` jne.), jotka aiheuttavat OpenAI SDK Pydantic -tarkistusvirheitä
+- **GLM/ERNIE hylkää roolin `system`** — Korjattu versiossa 1.1.0: roolin normalisoija yhdistää automaattisesti järjestelmäviestit käyttäjän viesteiksi yhteensopimattomissa malleissa
+- **`developer` roolia ei tunnistettu** - Korjattu versiossa 1.1.0: muunnetaan automaattisesti muotoon `system` muille kuin OpenAI-palveluntarjoajille
+- **`json_schema` ei toimi Geminin kanssa** — Korjattu versiossa 1.1.0: `response_format` muunnetaan nyt Geminin `responseMimeType` + `responseSchema`
+
+---
+
+## Kestävyysasetukset
+
+### Automaattinen nopeusrajoitus ei laukea
+
+- Automaattinen nopeusrajoitus koskee vain API-avainten toimittajia (ei OAuth-tilausta)
+- Varmista, että **Asetukset → Resilienssi → Palveluntarjoajan profiilit** on automaattinen rajoitus käytössä
+- Tarkista, palauttaako palveluntarjoaja `429`-tilakoodit tai `Retry-After`-otsikot
+
+### Viritys eksponentiaalisesti
+
+Palveluntarjoajan profiilit tukevat näitä asetuksia:
+
+- **Perusviive** — Ensimmäinen odotusaika ensimmäisen epäonnistumisen jälkeen (oletus: 1 s)
+- **Maksimiviive** - Odotusajan enimmäisraja (oletus: 30 s)
+- **Kerroin** — Kuinka paljon viivettä lisätään peräkkäistä vikaa kohti (oletus: 2x)
+
+### Ukkosta estävä lauma
+
+Kun monet samanaikaiset pyynnöt osuvat nopeusrajoitettuun palveluntarjoajaan, OmniRoute käyttää mutex + automaattista nopeuden rajoitusta sarjoittamaan pyynnöt ja estämään peräkkäiset epäonnistumiset. Tämä on automaattinen API-avainten tarjoajille.
+
+---
+
+## Vieläkö jumissa?
+
+- **GitHub-ongelmat**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Arkkitehtuuri**: Katso sisäiset tiedot kohdasta [link](ARCHITECTURE.md)
+- **API-viite**: Katso kaikki päätepisteet kohdasta [link](API_REFERENCE.md)
+- **Health Dashboard**: Tarkista järjestelmän reaaliaikainen tila kohdasta **Dashboard → Health**
+- **Kääntäjä**: Käytä **Käyttöpaneeli → Kääntäjä** muotoongelmien korjaamiseen

docs/i18n/fi/USER_GUIDE.md

@@ -0,0 +1,698 @@
+# Käyttöopas
+
+🌐 **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)
+
+Täydellinen opas palveluntarjoajien määrittämiseen, yhdistelmien luomiseen, CLI-työkalujen integrointiin ja OmniRouten käyttöönottoon.
+
+---
+
+## Sisällysluettelo
+
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
+
+## 💰 Hinnoittelu yhdellä silmäyksellä
+
+| Taso             | Palveluntarjoaja  | Kustannukset         | Kiintiön nollaus       | Paras                      |
+| ---------------- | ----------------- | -------------------- | ---------------------- | -------------------------- |
+| **💳 TILAUS**    | Claude Code (Pro) | 20 dollaria/kk       | 5h + viikoittain       | jo tilattu                 |
+|                  | Codex (Plus/Pro)  | 20-200 $/kk          | 5h + viikoittain       | OpenAI-käyttäjät           |
+|                  | Gemini CLI        | **ILMAINEN**         | 180 tk/kk + 1 tk/päivä | Kaikki!                    |
+|                  | GitHub Copilot    | 10-19 $/kk           | Kuukausittain          | GitHub-käyttäjät           |
+| **🔑 API-AVAIN** | DeepSeek          | Maksu per käyttö     | Ei yhtään              | Halpa perustelu            |
+|                  | Groq              | Maksu per käyttö     | Ei yhtään              | Erittäin nopea johtopäätös |
+|                  | xAI (Grok)        | Maksu per käyttö     | Ei yhtään              | Grok 4 perustelut          |
+|                  | Mistral           | Maksu per käyttö     | Ei yhtään              | EU:n isännöimät mallit     |
+|                  | Hämmennys         | Maksu per käyttö     | Ei yhtään              | Haku-lisätty               |
+|                  | Yhdessä AI        | Maksu per käyttö     | Ei yhtään              | Avoimen lähdekoodin mallit |
+|                  | Ilotulitus AI     | Maksu per käyttö     | Ei yhtään              | Nopeat FLUX-kuvat          |
+|                  | Aivot             | Maksu per käyttö     | Ei yhtään              | Kiekon mittakaavanopeus    |
+|                  | Cohere            | Maksu per käyttö     | Ei yhtään              | Komento R+ RAG             |
+|                  | NVIDIA NIM        | Maksu per käyttö     | Ei yhtään              | Yritysmallit               |
+| **💰 EDULLISET** | GLM-4.7           | 0,6 $/1 milj.        | Päivittäin klo 10      | Budjetin varmuuskopio      |
+|                  | MiniMax M2.1      | 0,2 $/1 milj.        | 5 tunnin rullaus       | Halvin vaihtoehto          |
+|                  | Kimi K2           | 9 dollaria/kk asunto | 10 milj. rahakkeita/kk | Ennustettavat kustannukset |
+| **🆓 ILMAINEN**  | iFlow             | 0 dollaria           | Rajoittamaton          | 8 mallia ilmaiseksi        |
+|                  | Qwen              | 0 dollaria           | Rajoittamaton          | 3 mallia ilmaiseksi        |
+|                  | Kiro              | 0 dollaria           | Rajoittamaton          | Claude ilmaiseksi          |
+
+**💡 Pro-vinkki:** Aloita Gemini CLI:llä (180 000 ilmaista kuukaudessa) + iFlow (rajoittamaton ilmainen) -yhdistelmä = 0 dollarin hinta!
+
+---
+
+## 🎯 Käyttökotelot
+
+### Tapaus 1: "Minulla on Claude Pro -tilaus"
+
+**Ongelma:** Kiintiö vanhenee käyttämättä, nopeusrajoitukset raskaan koodauksen aikana
+
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6        (use subscription fully)
+  2. glm/glm-4.7               (cheap backup when quota out)
+  3. if/kimi-k2-thinking       (free emergency fallback)
+
+Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
+vs. $20 + hitting limits = frustration
+```
+
+### Tapaus 2: "Haluan ilman kustannuksia"
+
+**Ongelma:** Ei ole varaa tilauksiin, tarvitaan luotettavaa tekoälykoodausta
+
+```
+Combo: "free-forever"
+  1. gc/gemini-3-flash         (180K free/month)
+  2. if/kimi-k2-thinking       (unlimited free)
+  3. qw/qwen3-coder-plus       (unlimited free)
+
+Monthly cost: $0
+Quality: Production-ready models
+```
+
+### Tapaus 3: "Tarvitsen 24/7-koodausta, ei keskeytyksiä"
+
+**Ongelma:** Määräajat, seisokkeihin ei ole varaa
+
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-6        (best quality)
+  2. cx/gpt-5.2-codex          (second subscription)
+  3. glm/glm-4.7               (cheap, resets daily)
+  4. minimax/MiniMax-M2.1      (cheapest, 5h reset)
+  5. if/kimi-k2-thinking       (free unlimited)
+
+Result: 5 layers of fallback = zero downtime
+Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
+```
+
+### Tapaus 4: "Haluan ILMAISTA tekoälyä OpenClawissa"
+
+**Ongelma:** Tarvitset AI-avustajan viestisovelluksissa, täysin ilmainen
+
+```
+Combo: "openclaw-free"
+  1. if/glm-4.7                (unlimited free)
+  2. if/minimax-m2.1           (unlimited free)
+  3. if/kimi-k2-thinking       (unlimited free)
+
+Monthly cost: $0
+Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+```
+
+---
+
+## 📖 Palveluntarjoajan asetukset
+
+### 🔐 Tilauspalveluntarjoajat
+
+#### Claude Code (Pro/Max)
+
+```bash
+Dashboard → Providers → Connect Claude Code
+→ OAuth login → Auto token refresh
+→ 5-hour + weekly quota tracking
+
+Models:
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**Provinkki:** Käytä Opusta monimutkaisiin tehtäviin ja Sonnetia nopeutta varten. OmniRoute jäljityskiintiö mallia kohden!
+
+#### OpenAI Codex (Plus/Pro)
+
+```bash
+Dashboard → Providers → Connect Codex
+→ OAuth login (port 1455)
+→ 5-hour + weekly reset
+
+Models:
+  cx/gpt-5.2-codex
+  cx/gpt-5.1-codex-max
+```
+
+#### Gemini CLI (ILMAINEN 180 000/kk!)
+
+```bash
+Dashboard → Providers → Connect Gemini CLI
+→ Google OAuth
+→ 180K completions/month + 1K/day
+
+Models:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**Paras hinta-laatusuhde:** Valtava ilmainen taso! Käytä tätä ennen maksettuja tasoja.
+
+#### GitHub Copilot
+
+```bash
+Dashboard → Providers → Connect GitHub
+→ OAuth via GitHub
+→ Monthly reset (1st of month)
+
+Models:
+  gh/gpt-5
+  gh/claude-4.5-sonnet
+  gh/gemini-3-pro
+```
+
+### 💰 Halvat palveluntarjoajat
+
+#### GLM-4.7 (päivittäinen nollaus, 0,6 $/1 milj.)
+
+1. Rekisteröidy: [Zhipu AI](https://open.bigmodel.cn/)
+2. Hanki API-avain Coding Planista
+3. Hallintapaneeli → Lisää API-avain: Palveluntarjoaja: `glm`, API-avain: `your-key`
+
+**Käytä:** `glm/glm-4.7` — **Provinkki:** Koodaussuunnitelma tarjoaa 3× kiintiön 1/7 hinnalla! Nollaa päivittäin klo 10.00.
+
+#### MiniMax M2.1 (5 h nollaus, 0,20 $/1 milj.)
+
+1. Rekisteröidy: [MiniMax](https://www.minimax.io/)
+2. Hanki API-avain → Dashboard → Add API Key
+
+**Käytä:** `minimax/MiniMax-M2.1` — **Ammattilaisen vinkki:** Halvin vaihtoehto pitkälle kontekstille (1 milj. merkkiä)!
+
+#### Kimi K2 (9 dollaria/kk asunto)
+
+1. Tilaa: [Moonshot AI](https://platform.moonshot.ai/)
+2. Hanki API-avain → Dashboard → Add API Key
+
+**Käyttö:** `kimi/kimi-latest` — **Ammattilaisen vinkki:** Kiinteä 9 dollaria kuukaudessa 10 miljoonalle rahakkeelle = 0,90 dollaria / 1 miljoona todellista hintaa!
+
+### 🆓 ILMAISIA palveluntarjoajia
+
+#### iFlow (8 ILMAISTA mallia)
+
+```bash
+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 ILMAISTA mallia)
+
+```bash
+Dashboard → Connect Qwen → Device code auth → Unlimited usage
+
+Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
+```
+
+#### Kiro (Claude ILMAINEN)
+
+```bash
+Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
+
+Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
+```
+
+---
+
+## 🎨 Yhdistelmät
+
+### Esimerkki 1: Maksimoi tilaus → Halpa varmuuskopio
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-6 (Subscription primary)
+  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
+  3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
+
+Use in CLI: premium-coding
+```
+
+### Esimerkki 2: Vain ilmainen (nollahinta)
+
+```
+Name: free-combo
+Models:
+  1. gc/gemini-3-flash-preview (180K free/month)
+  2. if/kimi-k2-thinking (unlimited)
+  3. qw/qwen3-coder-plus (unlimited)
+
+Cost: $0 forever!
+```
+
+---
+
+## 🔧 CLI-integraatio
+
+### Kohdistimen IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from omniroute dashboard]
+  Model: cc/claude-opus-4-6
+```
+
+### Claude Code
+
+Muokkaa `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-omniroute-api-key"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-omniroute-api-key"
+codex "your prompt"
+```
+
+### OpenClaw
+
+Muokkaa `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": { "primary": "omniroute/if/glm-4.7" }
+    }
+  },
+  "models": {
+    "providers": {
+      "omniroute": {
+        "baseUrl": "http://localhost:20128/v1",
+        "apiKey": "your-omniroute-api-key",
+        "api": "openai-completions",
+        "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+      }
+    }
+  }
+}
+```
+
+**Tai käytä Dashboardia:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-6
+```
+
+---
+
+## 🚀 Käyttöönotto
+
+### VPS-käyttöönotto
+
+```bash
+git clone https://github.com/diegosouzapw/OmniRoute.git
+cd OmniRoute && npm install && npm run build
+
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+export DATA_DIR="/var/lib/omniroute"
+export PORT="20128"
+export HOSTNAME="0.0.0.0"
+export NODE_ENV="production"
+export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
+export API_KEY_SECRET="endpoint-proxy-api-key-secret"
+
+npm run start
+# Or: pm2 start npm --name omniroute -- start
+```
+
+### Docker
+
+```bash
+# Build image (default = runner-cli with codex/claude/droid preinstalled)
+docker build -t omniroute:cli .
+
+# Portable mode (recommended)
+docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
+```
+
+Katso isäntäintegroitu tila CLI-binaarien kanssa pääasiakirjojen Docker-osiosta.
+
+### Ympäristömuuttujat
+
+| Muuttuja              | Oletus                               | Kuvaus                                                                     |
+| --------------------- | ------------------------------------ | -------------------------------------------------------------------------- |
+| `JWT_SECRET`          | `omniroute-default-secret-change-me` | JWT:n allekirjoitussalaisuus (**muutos tuotannossa**)                      |
+| `INITIAL_PASSWORD`    | `123456`                             | Ensimmäisen kirjautumisen salasana                                         |
+| `DATA_DIR`            | `~/.omniroute`                       | Tietohakemisto (db, käyttö, lokit)                                         |
+| `PORT`                | oletuskehys                          | Huoltoportti (`20128` esimerkeissä)                                        |
+| `HOSTNAME`            | oletuskehys                          | Sido isäntä (Dockerin oletusarvo on `0.0.0.0`)                             |
+| `NODE_ENV`            | ajonaikainen oletus                  | Aseta `production` käyttöönottoa varten                                    |
+| `BASE_URL`            | `http://localhost:20128`             | Palvelinpuolen sisäinen perus-URL                                          |
+| `CLOUD_URL`           | `https://omniroute.dev`              | Pilvisynkronoinnin päätepisteen perus-URL                                  |
+| `API_KEY_SECRET`      | `endpoint-proxy-api-key-secret`      | Luotujen API-avaimien HMAC-salaisuus                                       |
+| `REQUIRE_API_KEY`     | `false`                              | Pakota Bearer API-avain `/v1/*`                                            |
+| `ENABLE_REQUEST_LOGS` | `false`                              | Ottaa käyttöön pyyntö-/vastauslokit                                        |
+| `AUTH_COOKIE_SECURE`  | `false`                              | Pakota `Secure` todennuseväste (HTTPS-käänteisen välityspalvelimen takana) |
+
+Täydellinen ympäristömuuttujaviittaus on kohdassa [README](../README.md).
+
+---
+
+## 📊 Saatavilla olevat mallit
+
+<details>
+<summary><b>Näytä kaikki saatavilla olevat mallit</b></summary>
+
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+
+**Koodi (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+
+**Gemini CLI (`gc/`)** – ILMAISEKSI: `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 milj.: `glm/glm-4.7`
+
+**MiniMax (`minimax/`)** – 0,2 $/1 milj.: `minimax/MiniMax-M2.1`
+
+**iFlow (`if/`)** – ILMAISEKSI: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+
+**Qwen (`qw/`)** – ILMAISEKSI: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+
+**Kiro (`kr/`)** – ILMAISEKSI: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
+
+**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`
+
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
+
+**Epäselvyys (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+
+**Yhdessä AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+
+**Ilotulitus AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+
+**Aivot (`cerebras/`)**: `cerebras/llama-3.3-70b`
+
+**Yhdenmukainen (`cohere/`)**: `cohere/command-r-plus-08-2024`
+
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+</details>
+
+---
+
+## 🧩 Lisäominaisuudet
+
+### Mukautetut mallit
+
+Lisää mikä tahansa mallitunnus mille tahansa palveluntarjoajalle odottamatta sovelluspäivitystä:
+
+```bash
+# Via API
+curl -X POST http://localhost:20128/api/provider-models \
+  -H "Content-Type: application/json" \
+  -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}'
+
+# List: curl http://localhost:20128/api/provider-models?provider=openai
+# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
+```
+
+Tai käytä Dashboardia: **Providers → [Provider] → Custom Models**.
+
+### Palveluntarjoajan reitit
+
+Reititä pyynnöt suoraan tietylle palveluntarjoajalle mallin validoinnilla:
+
+```bash
+POST http://localhost:20128/v1/providers/openai/chat/completions
+POST http://localhost:20128/v1/providers/openai/embeddings
+POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
+
+Palveluntarjoajan etuliite lisätään automaattisesti, jos se puuttuu. Yhteensopimattomat mallit palauttavat `400`.
+
+### Verkkovälityspalvelimen asetukset
+
+```bash
+# Set global proxy
+curl -X PUT http://localhost:20128/api/settings/proxy \
+  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
+
+# Per-provider proxy
+curl -X PUT http://localhost:20128/api/settings/proxy \
+  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
+
+# Test proxy
+curl -X POST http://localhost:20128/api/settings/proxy/test \
+  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
+```
+
+**Ensisijaisuus:** Avainkohtainen → Yhdistelmäkohtainen → Palveluntarjoajakohtainen → Globaali → Ympäristö.
+
+### Model Catalog API
+
+```bash
+curl http://localhost:20128/api/models/catalog
+```
+
+Palauttaa mallit ryhmiteltyinä tarjoajan mukaan tyypeillä (`chat`, `embedding`, `image`).
+
+### Cloud Sync
+
+- Synkronoi palveluntarjoajat, yhdistelmät ja asetukset eri laitteiden välillä
+- Automaattinen taustasynkronointi aikakatkaisulla + Fast Fast
+- Valitse palvelinpuolen `BASE_URL`/`CLOUD_URL` tuotannossa
+
+### LLM Gateway Intelligence (vaihe 9)
+
+- **Semanttinen välimuisti** — Tallentaa automaattisesti välimuistiin ei-suoratoistoa, lämpötila = 0 vastausta (ohita `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** – Poistaa pyyntöjen päällekkäisyydet 5 sekunnissa `Idempotency-Key`- tai `X-Request-Id`-otsikon kautta
+- **Edistyksen seuranta** — Ota SSE `event: progress` -tapahtumat käyttöön `X-OmniRoute-Progress: true`-otsikon kautta
+
+---
+
+### Kääntäjän leikkikenttä
+
+Pääsy **Dashboard → Kääntäjän** kautta. Tee virheenkorjaus ja visualisoi, kuinka OmniRoute kääntää API-pyynnöt palveluntarjoajien välillä.
+
+| Tila                      | Tarkoitus                                                                                |
+| ------------------------- | ---------------------------------------------------------------------------------------- |
+| **Leikkikenttä**          | Valitse lähde-/kohdemuodot, liitä pyyntö ja näet käännetyn tulosteen välittömästi        |
+| **Pikaviestien testaaja** | Lähetä live-chat-viestejä välityspalvelimen kautta ja tarkista koko pyyntö-/vastausjakso |
+| **Testipenkki**           | Suorita erätestejä useille muotoyhdistelmille varmistaaksesi käännöksen oikeellisuuden   |
+| **Live Monitor**          | Katso reaaliaikaisia ​​käännöksiä, kun pyynnöt kulkevat välityspalvelimen kautta         |
+
+**Käyttötapaukset:**
+
+- Selvitä, miksi tietty asiakas/toimittaja-yhdistelmä epäonnistuu
+- Varmista, että ajattelutunnisteet, työkalukutsut ja järjestelmäkehotteet käännetään oikein
+- Vertaa muotoeroja OpenAI-, Claude-, Gemini- ja Responses API -muotojen välillä
+
+---
+
+### Reititysstrategiat
+
+Määritä kohdasta **Kojelauta → Asetukset → Reititys**.
+
+| Strategia                      | Kuvaus                                                                                                                |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| **Täytä ensin**                | Käyttää tilejä tärkeysjärjestyksessä — ensisijainen tili käsittelee kaikki pyynnöt, kunnes ne eivät ole käytettävissä |
+| **Round Robin**                | Selaa kaikki tilit, joilla on määritettävissä oleva rajoitus (oletus: 3 puhelua tiliä kohden)                         |
+| **P2C (Kahden valinnan teho)** | Valitsee 2 satunnaista tiliä ja reitit terveempään tiliin – tasapainottaa kuormituksen terveystietoisuuden kanssa     |
+| **Satunnainen**                | Valitsee satunnaisesti tilin kullekin pyynnölle käyttämällä Fisher-Yates shuffle                                      |
+| **Vähiten käytetty**           | Reitit tilille, jolla on vanhin `lastUsedAt` aikaleima, jakaen liikenteen tasaisesti                                  |
+| **Kustannusoptimoitu**         | Reitit tilille, jolla on alhaisin prioriteettiarvo, optimointi edullisimpien palveluntarjoajien mukaan                |
+
+#### Jokerimerkkimallin aliakset
+
+Luo jokerimerkkikuvioita mallien nimien yhdistämiseksi uudelleen:
+
+```
+Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-*               →  Target: gh/gpt-5.1-codex
+```
+
+Jokerimerkit tukevat `*` (kaikki merkit) ja `?` (yksi merkki).
+
+#### Varaketjut
+
+Määritä maailmanlaajuiset varaketjut, jotka koskevat kaikkia pyyntöjä:
+
+```
+Chain: production-fallback
+  1. cc/claude-opus-4-6
+  2. gh/gpt-5.1-codex
+  3. glm/glm-4.7
+```
+
+---
+
+### Kestävyys ja katkaisijat
+
+Määritä kohdasta **Kojelauta → Asetukset → Resilience**.
+
+OmniRoute toteuttaa toimittajatason joustavuutta neljällä osalla:
+
+1. **Toimittajan profiilit** — Palveluntarjoajakohtainen määritys:
+   - Vikakynnys (kuinka monta vikaa ennen avaamista)
+   - Jäähdytyskesto
+   - Nopeusrajan tunnistusherkkyys
+   - Eksponentiaaliset peruutusparametrit
+
+2. **Muokattavat nopeusrajoitukset** — Järjestelmätason oletusasetukset, jotka voidaan määrittää kojelaudassa:
+   - **Pyynnöt minuutissa (RPM)** – Pyyntöjen enimmäismäärä minuutissa per tili
+   - **Pyyntöjen välinen vähimmäisaika** - pyyntöjen välinen vähimmäisero millisekunteina
+   - **Samanaikaisten pyyntöjen enimmäismäärä** — Samanaikaisten pyyntöjen enimmäismäärä tiliä kohden
+   - Napsauta **Muokkaa** muokataksesi ja sitten **Tallenna** tai **Peruuta**. Arvot säilyvät resilience API:n kautta.
+
+3. **Circuit Breaker** – Seuraa vikoja palveluntarjoajakohtaisesti ja avaa piirin automaattisesti, kun kynnys saavutetaan:
+   - **SULJETTU** (terve) — Pyynnöt kulkevat normaalisti
+   - **AUKI** — Palveluntarjoaja on tilapäisesti estetty toistuvien vikojen jälkeen
+   - **HALF_OPEN** — Testataan, onko palveluntarjoaja palautunut
+
+4. **Policies & Locked Identifiers** — Näyttää katkaisijan tilan ja lukitut tunnisteet, joissa on pakko-avaaminen.
+
+5. **Automaattinen nopeusrajoituksen tunnistus** — Valvoo `429`- ja `Retry-After`-otsikoita välttääkseen ennakoivasti palveluntarjoajan nopeusrajojen ylittymisen.
+
+**Ammattilaisen vinkki:** Käytä **Nollaa kaikki** -painiketta tyhjentääksesi kaikki katkaisijat ja jäähdytykset, kun palveluntarjoaja toipuu katkosta.
+
+---
+
+### Tietokannan vienti/tuonti
+
+Hallitse tietokannan varmuuskopioita kohdassa **Käyttöpaneeli → Asetukset → Järjestelmä ja tallennus**.
+
+| Toiminta                 | Kuvaus                                                                                                                                                         |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Vie tietokanta**       | Lataa nykyisen SQLite-tietokannan `.sqlite`-tiedostona                                                                                                         |
+| **Vie kaikki (.tar.gz)** | Lataa täyden varmuuskopioarkiston, joka sisältää: tietokannan, asetukset, yhdistelmät, palveluntarjoajan yhteydet (ei tunnistetietoja), API-avaimen metatiedot |
+| **Tuo tietokanta**       | Lataa `.sqlite`-tiedosto nykyisen tietokannan tilalle. Tuontia edeltävä varmuuskopio luodaan automaattisesti                                                   |
+
+```bash
+# API: Export database
+curl -o backup.sqlite http://localhost:20128/api/db-backups/export
+
+# API: Export all (full archive)
+curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
+
+# API: Import database
+curl -X POST http://localhost:20128/api/db-backups/import \
+  -F "file=@backup.sqlite"
+```
+
+**Tuonnin vahvistus:** Tuodun tiedoston eheys (SQLite pragma check), vaaditut taulukot (`provider_connections`, `provider_nodes`, `combos`, ) ja koko 0 (0 MB) tarkistetaan.
+
+**Käyttötapaukset:**
+
+- Siirrä OmniRoute koneiden välillä
+- Luo ulkoisia varmuuskopioita katastrofipalautusta varten
+- Jaa kokoonpanot tiimin jäsenten välillä (vie kaikki → jaa arkisto)
+
+---
+
+### Asetukset Dashboard
+
+Asetussivu on järjestetty viiteen välilehteen navigoinnin helpottamiseksi:
+
+| Välilehti         | Sisältö                                                                                                         |
+| ----------------- | --------------------------------------------------------------------------------------------------------------- |
+| **Turvallisuus**  | Kirjautumis-/salasana-asetukset, IP-käytön valvonta, API-todennus kohteelle `/models` ja palveluntarjoajan esto |
+| **Reititys**      | Globaali reititysstrategia (6 vaihtoehtoa), jokerimerkkimallien aliakset, varaketjut, yhdistelmäoletukset       |
+| **Kestävyys**     | Palveluntarjoajan profiilit, muokattavat nopeusrajoitukset, katkaisijan tila, käytännöt ja lukitut tunnisteet   |
+| **AI**            | Ajatteleva budjettimäärittely, globaali järjestelmäkehote, nopea välimuistitilastot                             |
+| **Lisäasetukset** | Yleiset välityspalvelimen asetukset (HTTP/SOCKS5)                                                               |
+
+---
+
+### Kustannukset ja budjetin hallinta
+
+Pääsy kohdasta **Käyttöpaneeli → Kulut**.
+
+| Välilehti       | Tarkoitus                                                                                                       |
+| --------------- | --------------------------------------------------------------------------------------------------------------- |
+| **Budjetti**    | Aseta kulutusrajat API-avaimelle päivä-/viikko-/kuukausibudjeteilla ja reaaliaikaisella seurannalla             |
+| **Hinnoittelu** | Tarkastele ja muokkaa mallin hinnoittelumerkintöjä – hinta per 1 000 syöttö-/tulostustunnusta toimittajaa kohti |
+
+```bash
+# API: Set a budget
+curl -X POST http://localhost:20128/api/usage/budget \
+  -H "Content-Type: application/json" \
+  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
+
+# API: Get current budget status
+curl http://localhost:20128/api/usage/budget
+```
+
+**Kustannusten seuranta:** Jokainen pyyntö kirjaa tunnuksen käytön ja laskee kustannukset hinnoittelutaulukon avulla. Näytä erittelyt kohdassa **Käyttöpaneeli → Käyttö** tarjoajan, mallin ja API-avaimen mukaan.
+
+---
+
+### Äänen transkriptio
+
+OmniRoute tukee äänen transkriptiota OpenAI-yhteensopivan päätepisteen kautta:
+
+```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+
+# Example with curl
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+  -H "Authorization: Bearer your-api-key" \
+  -F "file=@audio.mp3" \
+  -F "model=deepgram/nova-3"
+```
+
+Saatavilla olevat palveluntarjoajat: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
+
+Tuetut äänimuodot: `mp3`, `wav`, `m4a`, `flac`, `ogg`,
+
+---
+
+### Yhdistelmätasapainotusstrategiat
+
+Määritä yhdistelmäkohtainen tasapainotus kohdassa **Käyttöpaneeli → Yhdistelmät → Luo/muokkaa → Strategia**.
+
+| Strategia              | Kuvaus                                                                                   |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| **Round-Robin**        | Pyörii mallien välillä peräkkäin                                                         |
+| **Etusija**            | Kokeilee aina ensimmäistä mallia; palautuu vain virheen yhteydessä                       |
+| **Satunnainen**        | Valitsee satunnaisen mallin yhdistelmästä jokaiselle pyynnölle                           |
+| **Painotettu**         | Reitit suhteellisesti mallikohtaisten painojen perusteella                               |
+| **Vähiten käytetty**   | Reitit malliin, jolla on vähiten viimeaikaisia ​​pyyntöjä (käyttää yhdistelmämittareita) |
+| **Kustannusoptimoitu** | Reitit halvimpaan saatavilla olevaan malliin (käyttää hinnoittelutaulukkoa)              |
+
+Yleiset yhdistelmäoletukset voidaan asettaa kohdassa **Kojelauta → Asetukset → Reititys → Yhdistelmäoletukset**.
+
+---
+
+### Terveyden hallintapaneeli
+
+Pääsy kohdasta **Dashboard → Health**. Reaaliaikainen järjestelmän kunnon yleiskatsaus 6 kortilla:
+
+| Kortti                      | Mitä se näyttää                                                                      |
+| --------------------------- | ------------------------------------------------------------------------------------ |
+| **Järjestelmän tila**       | Käyttöaika, versio, muistin käyttö, tietohakemisto                                   |
+| **Tarjoajan terveys**       | Palveluntarjoajakohtainen katkaisijan tila (suljettu/auki/puoliauki)                 |
+| **Rate Limits**             | Aktiivisen nopeuden rajan viilennyksiä tiliä kohti jäljellä olevan ajan kanssa       |
+| **Aktiiviset lukitukset**   | Palveluntarjoajat, jotka on tilapäisesti estetty lukituskäytännön vuoksi             |
+| **Allekirjoitusvälimuisti** | Päällekkäisyyden poistamisen välimuistitilastot (aktiiviset avaimet, osumaprosentti) |
+| **Viiveen telemetria**      | p50/p95/p99 latenssin yhteenlaskettu palveluntarjoajakohtainen                       |
+
+**Provinkki:** Terveys-sivu päivittyy automaattisesti 10 sekunnin välein. Käytä katkaisijakorttia tunnistaaksesi, millä palveluntarjoajilla on ongelmia.

docs/i18n/fr/API_REFERENCE.md

@@ -0,0 +1,441 @@
+# Référence 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)
+
+Référence complète pour tous les points de terminaison de l'API OmniRoute.
+
+---
+
+## Table des matières
+
+- [Chat Completions](#chat-completions)
+- [Embeddings](#embeddings)
+- [Image Generation](#image-generation)
+- [List Models](#list-models)
+- [Compatibility Endpoints](#compatibility-endpoints)
+- [Semantic Cache](#semantic-cache)
+- [Dashboard & Management](#dashboard--management)
+- [Request Processing](#request-processing)
+- [Authentication](#authentication)
+
+---
+
+## Fins de chat
+
+```bash
+POST /v1/chat/completions
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "cc/claude-opus-4-6",
+  "messages": [
+    {"role": "user", "content": "Write a function to..."}
+  ],
+  "stream": true
+}
+```
+
+### En-têtes personnalisés
+
+| En-tête                  | Itinéraire | Descriptif                                           |
+| ------------------------ | ---------- | ---------------------------------------------------- |
+| `X-OmniRoute-No-Cache`   | Demande    | Défini sur `true` pour contourner le cache           |
+| `X-OmniRoute-Progress`   | Demande    | Défini sur `true` pour les événements de progression |
+| `Idempotency-Key`        | Demande    | Clé de déduplication (fenêtre 5s)                    |
+| `X-Request-Id`           | Demande    | Clé de déduplication alternative                     |
+| `X-OmniRoute-Cache`      | Réponse    | `HIT` ou `MISS` (sans streaming)                     |
+| `X-OmniRoute-Idempotent` | Réponse    | `true` si dédupliqué                                 |
+| `X-OmniRoute-Progress`   | Réponse    | `enabled` si le suivi des progrès est activé         |
+
+---
+
+## Intégrations
+
+```bash
+POST /v1/embeddings
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "nebius/Qwen/Qwen3-Embedding-8B",
+  "input": "The food was delicious"
+}
+```
+
+Fournisseurs disponibles : Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+
+```bash
+# List all embedding models
+GET /v1/embeddings
+```
+
+---
+
+## Génération d'images
+
+```bash
+POST /v1/images/generations
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "openai/dall-e-3",
+  "prompt": "A beautiful sunset over mountains",
+  "size": "1024x1024"
+}
+```
+
+Fournisseurs disponibles : OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+
+```bash
+# List all image models
+GET /v1/images/generations
+```
+
+---
+
+## Liste des modèles
+
+```bash
+GET /v1/models
+Authorization: Bearer your-api-key
+
+→ Returns all chat, embedding, and image models + combos in OpenAI format
+```
+
+---
+
+## Points de terminaison de compatibilité
+
+| Méthode | Chemin                      | Formater                   |
+| ------- | --------------------------- | -------------------------- |
+| POSTER  | `/v1/chat/completions`      | OpenAI                     |
+| POSTER  | `/v1/messages`              | Anthropique                |
+| POSTER  | `/v1/responses`             | Réponses OpenAI            |
+| POSTER  | `/v1/embeddings`            | OpenAI                     |
+| POSTER  | `/v1/images/generations`    | OpenAI                     |
+| OBTENIR | `/v1/models`                | OpenAI                     |
+| POSTER  | `/v1/messages/count_tokens` | Anthropique                |
+| OBTENIR | `/v1beta/models`            | Gémeaux                    |
+| POSTER  | `/v1beta/models/{...path}`  | Gémeaux générer du contenu |
+| POSTER  | `/v1/api/chat`              | Ollama                     |
+
+### Itinéraires de fournisseurs dédiés
+
+```bash
+POST /v1/providers/{provider}/chat/completions
+POST /v1/providers/{provider}/embeddings
+POST /v1/providers/{provider}/images/generations
+```
+
+Le préfixe du fournisseur est ajouté automatiquement s'il est manquant. Les modèles incompatibles renvoient `400`.
+
+---
+
+## Cache sémantique
+
+```bash
+# Get cache stats
+GET /api/cache
+
+# Clear all caches
+DELETE /api/cache
+```
+
+Exemple de réponse :
+
+```json
+{
+  "semanticCache": {
+    "memorySize": 42,
+    "memoryMaxSize": 500,
+    "dbSize": 128,
+    "hitRate": 0.65
+  },
+  "idempotency": {
+    "activeKeys": 3,
+    "windowMs": 5000
+  }
+}
+```
+
+---
+
+## Tableau de bord et gestion
+
+### Authentification
+
+| Point de terminaison          | Méthode        | Descriptif                    |
+| ----------------------------- | -------------- | ----------------------------- |
+| `/api/auth/login`             | POSTER         | Connexion                     |
+| `/api/auth/logout`            | POSTER         | Déconnexion                   |
+| `/api/settings/require-login` | OBTENIR/METTRE | Basculer la connexion requise |
+
+### Gestion des fournisseurs
+
+| Point de terminaison         | Méthode                  | Descriptif                              |
+| ---------------------------- | ------------------------ | --------------------------------------- |
+| `/api/providers`             | OBTENIR/POST             | Lister/créer des prestataires           |
+| `/api/providers/[id]`        | OBTENIR/METTRE/SUPPRIMER | Gérer un fournisseur                    |
+| `/api/providers/[id]/test`   | POSTER                   | Connexion du fournisseur de test        |
+| `/api/providers/[id]/models` | OBTENIR                  | Liste des modèles de fournisseurs       |
+| `/api/providers/validate`    | POSTER                   | Valider la configuration du fournisseur |
+| `/api/provider-nodes*`       | Divers                   | Gestion des nœuds de fournisseur        |
+| `/api/provider-models`       | OBTENIR/POST/DELETE      | Modèles personnalisés                   |
+
+### Flux OAuth
+
+| Point de terminaison             | Méthode | Descriptif                      |
+| -------------------------------- | ------- | ------------------------------- |
+| `/api/oauth/[provider]/[action]` | Divers  | OAuth spécifique au fournisseur |
+
+### Routage et configuration
+
+| Point de terminaison  | Méthode      | Descriptif                              |
+| --------------------- | ------------ | --------------------------------------- |
+| `/api/models/alias`   | OBTENIR/POST | Alias ​​du modèle                       |
+| `/api/models/catalog` | OBTENIR      | Tous les modèles par fournisseur + type |
+| `/api/combos*`        | Divers       | Gestion des combos                      |
+| `/api/keys*`          | Divers       | Gestion des clés API                    |
+| `/api/pricing`        | OBTENIR      | Tarification du modèle                  |
+
+### Utilisation et analyses
+
+| Point de terminaison        | Méthode | Descriptif                       |
+| --------------------------- | ------- | -------------------------------- |
+| `/api/usage/history`        | OBTENIR | Historique d'utilisation         |
+| `/api/usage/logs`           | OBTENIR | Journaux d'utilisation           |
+| `/api/usage/request-logs`   | OBTENIR | Journaux au niveau de la demande |
+| `/api/usage/[connectionId]` | OBTENIR | Utilisation par connexion        |
+
+### Paramètres
+
+| Point de terminaison            | Méthode        | Descriptif                               |
+| ------------------------------- | -------------- | ---------------------------------------- |
+| `/api/settings`                 | OBTENIR/METTRE | Paramètres généraux                      |
+| `/api/settings/proxy`           | OBTENIR/METTRE | Configuration du proxy réseau            |
+| `/api/settings/proxy/test`      | POSTER         | Tester la connexion proxy                |
+| `/api/settings/ip-filter`       | OBTENIR/METTRE | Liste d'autorisation/liste de blocage IP |
+| `/api/settings/thinking-budget` | OBTENIR/METTRE | Budget symbolique de raisonnement        |
+| `/api/settings/system-prompt`   | OBTENIR/METTRE | Invite système globale                   |
+
+### Surveillance
+
+| Point de terminaison     | Méthode           | Descriptif                      |
+| ------------------------ | ----------------- | ------------------------------- |
+| `/api/sessions`          | OBTENIR           | Suivi de session active         |
+| `/api/rate-limits`       | OBTENIR           | Limites de taux par compte      |
+| `/api/monitoring/health` | OBTENIR           | Bilan de santé                  |
+| `/api/cache`             | OBTENIR/SUPPRIMER | Statistiques du cache / effacer |
+
+### Sauvegarde et exportation/importation
+
+| Point de terminaison        | Méthode | Descriptif                                                       |
+| --------------------------- | ------- | ---------------------------------------------------------------- |
+| `/api/db-backups`           | OBTENIR | Liste des sauvegardes disponibles                                |
+| `/api/db-backups`           | METTRE  | Créer une sauvegarde manuelle                                    |
+| `/api/db-backups`           | POSTER  | Restaurer à partir d'une sauvegarde spécifique                   |
+| `/api/db-backups/export`    | OBTENIR | Télécharger la base de données sous forme de fichier .sqlite     |
+| `/api/db-backups/import`    | POSTER  | Téléchargez le fichier .sqlite pour remplacer la base de données |
+| `/api/db-backups/exportAll` | OBTENIR | Télécharger la sauvegarde complète sous forme d'archive .tar.gz  |
+
+### Synchronisation avec le cloud
+
+| Point de terminaison   | Méthode | Descriptif                          |
+| ---------------------- | ------- | ----------------------------------- |
+| `/api/sync/cloud`      | Divers  | Opérations de synchronisation cloud |
+| `/api/sync/initialize` | POSTER  | Initialiser la synchronisation      |
+| `/api/cloud/*`         | Divers  | Gestion du cloud                    |
+
+### Outils CLI
+
+| Point de terminaison               | Méthode | Descriptif                 |
+| ---------------------------------- | ------- | -------------------------- |
+| `/api/cli-tools/claude-settings`   | OBTENIR | Statut CLI de Claude       |
+| `/api/cli-tools/codex-settings`    | OBTENIR | Statut CLI du Codex        |
+| `/api/cli-tools/droid-settings`    | OBTENIR | Statut de la CLI du droïde |
+| `/api/cli-tools/openclaw-settings` | OBTENIR | Statut de la CLI OpenClaw  |
+| `/api/cli-tools/runtime/[toolId]`  | OBTENIR | Exécution CLI générique    |
+
+Les réponses CLI incluent : `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
+
+### Résilience et limites de taux
+
+| Point de terminaison    | Méthode        | Descriptif                                      |
+| ----------------------- | -------------- | ----------------------------------------------- |
+| `/api/resilience`       | OBTENIR/METTRE | Obtenir/mettre à jour les profils de résilience |
+| `/api/resilience/reset` | POSTER         | Réinitialiser les disjoncteurs                  |
+| `/api/rate-limits`      | OBTENIR        | Statut de limite de débit par compte            |
+| `/api/rate-limit`       | OBTENIR        | Configuration de la limite de débit globale     |
+
+### Évaluations
+
+| Point de terminaison | Méthode      | Descriptif                                                |
+| -------------------- | ------------ | --------------------------------------------------------- |
+| `/api/evals`         | OBTENIR/POST | Répertorier les suites d'évaluation/exécuter l'évaluation |
+
+### Politiques
+
+| Point de terminaison | Méthode             | Descriptif                      |
+| -------------------- | ------------------- | ------------------------------- |
+| `/api/policies`      | OBTENIR/POST/DELETE | Gérer les politiques de routage |
+
+### Conformité
+
+| Point de terminaison        | Méthode | Descriptif                                |
+| --------------------------- | ------- | ----------------------------------------- |
+| `/api/compliance/audit-log` | OBTENIR | Journal d'audit de conformité (dernier N) |
+
+### v1beta (compatible Gemini)
+
+| Point de terminaison       | Méthode | Descriptif                                    |
+| -------------------------- | ------- | --------------------------------------------- |
+| `/v1beta/models`           | OBTENIR | Liste des modèles au format Gemini            |
+| `/v1beta/models/{...path}` | POSTER  | Point de terminaison Gemini `generateContent` |
+
+Ces points de terminaison reflètent le format API de Gemini pour les clients qui attendent une compatibilité native avec le SDK Gemini.
+
+### API internes/système
+
+| Point de terminaison | Méthode | Descriptif                                                                                 |
+| -------------------- | ------- | ------------------------------------------------------------------------------------------ |
+| `/api/init`          | OBTENIR | Vérification de l'initialisation de l'application (utilisée lors de la première exécution) |
+| `/api/tags`          | OBTENIR | Balises de modèle compatibles Ollama (pour les clients Ollama)                             |
+| `/api/restart`       | POSTER  | Déclencher un redémarrage progressif du serveur                                            |
+| `/api/shutdown`      | POSTER  | Déclencher l'arrêt progressif du serveur                                                   |
+
+> **Remarque :** Ces points de terminaison sont utilisés en interne par le système ou pour la compatibilité du client Ollama. Ils ne sont généralement pas appelés par les utilisateurs finaux.
+
+---
+
+## Transcription audio
+
+```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+```
+
+Transcrivez des fichiers audio à l'aide de Deepgram ou AssemblyAI.
+
+**Demande :**
+
+```bash
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+  -H "Authorization: Bearer your-api-key" \
+  -F "file=@recording.mp3" \
+  -F "model=deepgram/nova-3"
+```
+
+**Réponse :**
+
+```json
+{
+  "text": "Hello, this is the transcribed audio content.",
+  "task": "transcribe",
+  "language": "en",
+  "duration": 12.5
+}
+```
+
+**Fournisseurs pris en charge :** `deepgram/nova-3`, `assemblyai/best`.
+
+**Formats pris en charge :** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
+
+---
+
+## Compatibilité Ollama
+
+Pour les clients qui utilisent le format API d'Ollama :
+
+```bash
+# Chat endpoint (Ollama format)
+POST /v1/api/chat
+
+# Model listing (Ollama format)
+GET /api/tags
+```
+
+Les demandes sont automatiquement traduites entre Ollama et les formats internes.
+
+---
+
+## Télémétrie
+
+```bash
+# Get latency telemetry summary (p50/p95/p99 per provider)
+GET /api/telemetry/summary
+```
+
+**Réponse :**
+
+```json
+{
+  "providers": {
+    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
+    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
+  }
+}
+```
+
+---
+
+## Budget
+
+```bash
+# Get budget status for all API keys
+GET /api/usage/budget
+
+# Set or update a budget
+POST /api/usage/budget
+Content-Type: application/json
+
+{
+  "keyId": "key-123",
+  "limit": 50.00,
+  "period": "monthly"
+}
+```
+
+---
+
+## Disponibilité du modèle
+
+```bash
+# Get real-time model availability across all providers
+GET /api/models/availability
+
+# Check availability for a specific model
+POST /api/models/availability
+Content-Type: application/json
+
+{
+  "model": "claude-sonnet-4-5-20250929"
+}
+```
+
+---
+
+## Traitement des demandes
+
+1. Le client envoie la demande à `/v1/*`
+2. Le gestionnaire de route appelle `handleChat`, `handleEmbedding`, `handleAudioTranscription` ou `handleImageGeneration`
+3. Le modèle est résolu (fournisseur/modèle direct ou alias/combo)
+4. Informations d'identification sélectionnées dans la base de données locale avec filtrage de la disponibilité des comptes
+5. Pour le chat : `handleChatCore` — détection de format, traduction, vérification du cache, vérification de l'idempotence
+6. L'exécuteur du fournisseur envoie une requête en amont
+7. Réponse traduite au format client (chat) ou renvoyée telle quelle (intégrations/images/audio)
+8. Utilisation/journalisation enregistrée
+9. Le repli s'applique aux erreurs selon les règles de combo
+
+Référence complète de l'architecture : [link](ARCHITECTURE.md)
+
+---
+
+## Authentification
+
+- Les itinéraires du tableau de bord (`/dashboard/*`) utilisent le cookie `auth_token`
+- La connexion utilise le hachage du mot de passe enregistré ; retour à `INITIAL_PASSWORD`
+- `requireLogin` basculable via `/api/settings/require-login`
+- Les routes `/v1/*` nécessitent éventuellement une clé API Bearer lorsque `REQUIRE_API_KEY=true`

docs/i18n/fr/ARCHITECTURE.md

@@ -0,0 +1,781 @@
+# Architecture OmniRoute
+
+🌐 **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)
+
+_Dernière mise à jour : 2026-02-18_
+
+## Résumé
+
+OmniRoute est une passerelle de routage d'IA locale et un tableau de bord construit sur Next.js.
+Il fournit un seul point de terminaison compatible OpenAI (`/v1/*`) et achemine le trafic vers plusieurs fournisseurs en amont avec traduction, secours, actualisation des jetons et suivi de l'utilisation.
+
+Capacités de base :
+
+- Surface API compatible OpenAI pour CLI/outils (28 fournisseurs)
+- Traduction des requêtes/réponses dans tous les formats de fournisseurs
+- Modèle de repli combo (séquence multi-modèles)
+- Repli au niveau du compte (multi-comptes par fournisseur)
+- Gestion des connexions du fournisseur de clé OAuth + API
+- Génération d'embarquement via `/v1/embeddings` (6 fournisseurs, 9 modèles)
+- Génération d'images via `/v1/images/generations` (4 fournisseurs, 9 modèles)
+- Pensez à l'analyse des balises (`<think>...</think>`) pour les modèles de raisonnement
+- Désinfection des réponses pour une compatibilité stricte avec le SDK OpenAI
+- Normalisation des rôles (développeur → système, système → utilisateur) pour une compatibilité entre fournisseurs
+- Conversion de sortie structurée (json_schema → Gemini ResponseSchema)
+- Persistance locale pour les fournisseurs, les clés, les alias, les combos, les paramètres, les prix
+- Suivi de l'utilisation/des coûts et journalisation des demandes
+- Synchronisation cloud en option pour la synchronisation multi-appareils/états
+- Liste d'autorisation/liste de blocage IP pour le contrôle d'accès aux API
+- Penser la gestion budgétaire (passthrough/auto/custom/adaptatif)
+  -Injection rapide du système global
+- Suivi de session et prise d'empreintes digitales
+- Limitation de débit améliorée par compte avec des profils spécifiques au fournisseur
+- Modèle de disjoncteur pour la résilience du fournisseur
+- Protection de troupeau anti-tonnerre avec verrouillage mutex
+- Cache de déduplication de requêtes basé sur les signatures
+- Couche domaine : disponibilité du modèle, règles de coûts, politique de repli, politique de verrouillage
+- Persistance de l'état du domaine (cache en écriture SQLite pour les solutions de repli, les budgets, les verrouillages, les disjoncteurs)
+- Moteur de politique pour l'évaluation centralisée des demandes (verrouillage → budget → repli)
+- Demande de télémétrie avec agrégation de latence p50/p95/p99
+- ID de corrélation (X-Request-Id) pour le traçage de bout en bout
+- Journalisation d'audit de conformité avec désinscription par clé API
+- Cadre d'évaluation pour l'assurance qualité LLM
+- Tableau de bord de l'interface utilisateur de résilience avec l'état du disjoncteur en temps réel
+- Fournisseurs OAuth modulaires (12 modules individuels sous `src/lib/oauth/providers/`)
+
+Modèle d'exécution principal :
+
+- Les routes d'application Next.js sous `src/app/api/*` implémentent à la fois les API de tableau de bord et les API de compatibilité
+- Un noyau SSE/routage partagé dans `src/sse/*` + `open-sse/*` gère l'exécution, la traduction, le streaming, le repli et l'utilisation du fournisseur.
+
+## Portée et limites
+
+### Dans le champ d'application
+
+- Runtime de la passerelle locale
+- API de gestion des tableaux de bord
+- Authentification du fournisseur et actualisation du jeton
+- Demander une traduction et un streaming SSE
+- État local + persistance d'utilisation
+- Orchestration de synchronisation cloud en option
+
+### Hors de portée
+
+- Implémentation du service cloud derrière `NEXT_PUBLIC_CLOUD_URL`
+- SLA/plan de contrôle du fournisseur en dehors du processus local
+- Les binaires CLI externes eux-mêmes (Claude CLI, Codex CLI, etc.)
+
+## Contexte système de haut niveau
+
+```mermaid
+flowchart LR
+    subgraph Clients[Developer Clients]
+        C1[Claude Code]
+        C2[Codex CLI]
+        C3[OpenClaw / Droid / Cline / Continue / Roo]
+        C4[Custom OpenAI-compatible clients]
+        BROWSER[Browser Dashboard]
+    end
+
+    subgraph Router[OmniRoute Local Process]
+        API[V1 Compatibility API\n/v1/*]
+        DASH[Dashboard + Management API\n/api/*]
+        CORE[SSE + Translation Core\nopen-sse + src/sse]
+        DB[(db.json)]
+        UDB[(usage.json + log.txt)]
+    end
+
+    subgraph Upstreams[Upstream Providers]
+        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity]
+        P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
+        P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
+    end
+
+    subgraph Cloud[Optional Cloud Sync]
+        CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL]
+    end
+
+    C1 --> API
+    C2 --> API
+    C3 --> API
+    C4 --> API
+    BROWSER --> DASH
+
+    API --> CORE
+    DASH --> DB
+    CORE --> DB
+    CORE --> UDB
+
+    CORE --> P1
+    CORE --> P2
+    CORE --> P3
+
+    DASH --> CLOUD
+```
+
+## Composants d'exécution de base
+
+## 1) API et couche de routage (routes de l'application Next.js)
+
+Principaux répertoires :
+
+- `src/app/api/v1/*` et `src/app/api/v1beta/*` pour les API de compatibilité
+- `src/app/api/*` pour les API de gestion/configuration
+- Les réécritures suivantes dans `next.config.mjs` mappent `/v1/*` à `/api/v1/*`
+
+Itinéraires de compatibilité importants :
+
+- `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` — inclut des modèles personnalisés avec `custom: true`
+- `src/app/api/v1/embeddings/route.ts` — génération d'intégration (6 fournisseurs)
+- `src/app/api/v1/images/generations/route.ts` — génération d'images (4+ fournisseurs dont Antigravity/Nebius)
+- `src/app/api/v1/messages/count_tokens/route.ts`
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — chat dédié par fournisseur
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — intégrations dédiées par fournisseur
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — images dédiées par fournisseur
+- `src/app/api/v1beta/models/route.ts`
+- `src/app/api/v1beta/models/[...path]/route.ts`
+
+Domaines de gestion :
+
+- Authentification/paramètres : `src/app/api/auth/*`, `src/app/api/settings/*`
+- Fournisseurs/connexions : `src/app/api/providers*`
+- Nœuds fournisseurs : `src/app/api/provider-nodes*`
+- Modèles personnalisés : `src/app/api/provider-models` (GET/POST/DELETE)
+- Catalogue de modèles : `src/app/api/models/catalog` (GET)
+- Configuration proxy : `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
+  -OAuth : `src/app/api/oauth/*`
+- Clés/alias/combos/tarification : `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
+- Utilisation : `src/app/api/usage/*`
+- Synchronisation/cloud : `src/app/api/sync/*`, `src/app/api/cloud/*`
+- Aides à l'outillage CLI : `src/app/api/cli-tools/*`
+- Filtre IP : `src/app/api/settings/ip-filter` (GET/PUT)
+- Budget de réflexion : `src/app/api/settings/thinking-budget` (GET/PUT)
+- Invite système : `src/app/api/settings/system-prompt` (GET/PUT)
+- Séances : `src/app/api/sessions` (GET)
+- Limites de débit : `src/app/api/rate-limits` (GET)
+- Résilience : `src/app/api/resilience` (GET/PATCH) — profils de fournisseur, disjoncteur, état limite de débit
+- Réinitialisation de la résilience : `src/app/api/resilience/reset` (POST) – réinitialisation des disjoncteurs + temps de recharge
+- Statistiques du cache : `src/app/api/cache/stats` (GET/DELETE)
+- Disponibilité du modèle : `src/app/api/models/availability` (GET/POST)
+- Télémétrie : `src/app/api/telemetry/summary` (GET)
+  -Budget : `src/app/api/usage/budget` (GET/POST)
+- Chaînes de secours : `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Audit de conformité : `src/app/api/compliance/audit-log` (GET)
+- Évaluations : `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
+- Politiques : `src/app/api/policies` (GET/POST)
+
+## 2) SSE + noyau de traduction
+
+Principaux modules de flux :
+
+- Entrée : `src/sse/handlers/chat.ts`
+- Orchestration de base : `open-sse/handlers/chatCore.ts`
+- Adaptateurs d'exécution du fournisseur : `open-sse/executors/*`
+- Détection de format/configuration du fournisseur : `open-sse/services/provider.ts`
+- Analyse/résolution du modèle : `src/sse/services/model.ts`, `open-sse/services/model.ts`
+- Logique de repli du compte : `open-sse/services/accountFallback.ts`
+- Registre de traduction : `open-sse/translator/index.ts`
+- Transformations de flux : `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Extraction/normalisation d'utilisation : `open-sse/utils/usageTracking.ts`
+- Pensez à l'analyseur de balises : `open-sse/utils/thinkTagParser.ts`
+- Gestionnaire d'intégration : `open-sse/handlers/embeddings.ts`
+- Registre des fournisseurs d'intégration : `open-sse/config/embeddingRegistry.ts`
+- Gestionnaire de génération d'images : `open-sse/handlers/imageGeneration.ts`
+- Registre du fournisseur d'images : `open-sse/config/imageRegistry.ts`
+- Désinfection de la réponse : `open-sse/handlers/responseSanitizer.ts`
+- Normalisation des rôles : `open-sse/services/roleNormalizer.ts`
+
+Services (logique métier) :
+
+- Sélection/notation du compte : `open-sse/services/accountSelector.ts`
+- Gestion du cycle de vie du contexte : `open-sse/services/contextManager.ts`
+- Application du filtre IP : `open-sse/services/ipFilter.ts`
+- Suivi de session : `open-sse/services/sessionManager.ts`
+- Demande de déduplication : `open-sse/services/signatureCache.ts`
+- Injection rapide du système : `open-sse/services/systemPrompt.ts`
+- Penser la gestion budgétaire : `open-sse/services/thinkingBudget.ts`
+- Routage du modèle générique : `open-sse/services/wildcardRouter.ts`
+- Gestion des limites de débit : `open-sse/services/rateLimitManager.ts`
+- Disjoncteur : `open-sse/services/circuitBreaker.ts`
+
+Modules de couche de domaine :
+
+- Disponibilité du modèle : `src/lib/domain/modelAvailability.ts`
+- Règles de coûts/budgets : `src/lib/domain/costRules.ts`
+- Politique de repli : `src/lib/domain/fallbackPolicy.ts`
+- Résolveur combiné : `src/lib/domain/comboResolver.ts`
+- Politique de verrouillage : `src/lib/domain/lockoutPolicy.ts`
+- Moteur de politique : `src/domain/policyEngine.ts` — verrouillage centralisé → budget → évaluation de secours
+- Catalogue de codes d'erreur : `src/lib/domain/errorCodes.ts`
+- ID de la demande : `src/lib/domain/requestId.ts`
+- Délai d'expiration de la récupération : `src/lib/domain/fetchTimeout.ts`
+- Demande de télémétrie : `src/lib/domain/requestTelemetry.ts`
+- Conformité/audit : `src/lib/domain/compliance/index.ts`
+- Coureur d'évaluation : `src/lib/domain/evalRunner.ts`
+- Persistance de l'état du domaine : `src/lib/db/domainState.ts` — SQLite CRUD pour les chaînes de secours, les budgets, l'historique des coûts, l'état de verrouillage, les disjoncteurs
+
+Modules du fournisseur OAuth (12 fichiers individuels sous `src/lib/oauth/providers/`) :
+
+- Index du registre : `src/lib/oauth/providers/index.ts`
+- Fournisseurs individuels : `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`
+- Wrapper mince : `src/lib/oauth/providers.ts` — réexportations à partir de modules individuels
+
+## 3) Couche de persistance
+
+Base de données d'état primaire :
+
+- `src/lib/localDb.ts`
+- fichier : `${DATA_DIR}/db.json` (ou `$XDG_CONFIG_HOME/omniroute/db.json` lorsqu'il est défini, sinon `~/.omniroute/db.json`)
+- entités : ProviderConnections, ProvideNodes, modelAliases, combos, apiKeys, paramètres, tarification, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
+
+Base de données d'utilisation :
+
+- `src/lib/usageDb.ts`
+- fichiers : `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
+- suit la même politique de répertoire de base que `localDb` (`DATA_DIR`, puis `XDG_CONFIG_HOME/omniroute` lorsqu'il est défini)
+- décomposé en sous-modules ciblés : `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts`
+
+Base de données d'état du domaine (SQLite) :
+
+- `src/lib/db/domainState.ts` — Opérations CRUD pour l'état du domaine
+- Tables (créées dans `src/lib/db/core.ts`) : `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
+- Modèle de cache en écriture : les cartes en mémoire font autorité au moment de l'exécution ; les mutations sont écrites de manière synchrone dans SQLite ; l'état est restauré à partir de la base de données lors d'un démarrage à froid
+
+## 4) Surfaces d'authentification + sécurité
+
+- Authentification des cookies du tableau de bord : `src/proxy.ts`, `src/app/api/auth/login/route.ts`
+- Génération/vérification de clé API : `src/shared/utils/apiKey.ts`
+- Les secrets du fournisseur ont persisté dans les entrées `providerConnections`
+- Prise en charge du proxy sortant via `open-sse/utils/proxyFetch.ts` (vars d'environnement) et `open-sse/utils/networkProxy.ts` (configurable par fournisseur ou global)
+
+## 5) Synchronisation dans le cloud
+
+- Initialisation du planificateur : `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
+- Tâche périodique : `src/shared/services/cloudSyncScheduler.ts`
+- Itinéraire de contrôle : `src/app/api/sync/cloud/route.ts`
+
+## Cycle de vie des demandes (`/v1/chat/completions`)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as CLI/SDK Client
+    participant Route as /api/v1/chat/completions
+    participant Chat as src/sse/handlers/chat
+    participant Core as open-sse/handlers/chatCore
+    participant Model as Model Resolver
+    participant Auth as Credential Selector
+    participant Exec as Provider Executor
+    participant Prov as Upstream Provider
+    participant Stream as Stream Translator
+    participant Usage as usageDb
+
+    Client->>Route: POST /v1/chat/completions
+    Route->>Chat: handleChat(request)
+    Chat->>Model: parse/resolve model or combo
+
+    alt Combo model
+        Chat->>Chat: iterate combo models (handleComboChat)
+    end
+
+    Chat->>Auth: getProviderCredentials(provider)
+    Auth-->>Chat: active account + tokens/api key
+
+    Chat->>Core: handleChatCore(body, modelInfo, credentials)
+    Core->>Core: detect source format
+    Core->>Core: translate request to target format
+    Core->>Exec: execute(provider, transformedBody)
+    Exec->>Prov: upstream API call
+    Prov-->>Exec: SSE/JSON response
+    Exec-->>Core: response + metadata
+
+    alt 401/403
+        Core->>Exec: refreshCredentials()
+        Exec-->>Core: updated tokens
+        Core->>Exec: retry request
+    end
+
+    Core->>Stream: translate/normalize stream to client format
+    Stream-->>Client: SSE chunks / JSON response
+
+    Stream->>Usage: extract usage + persist history/log
+```
+
+## Combo + Flux de repli du compte
+
+```mermaid
+flowchart TD
+    A[Incoming model string] --> B{Is combo name?}
+    B -- Yes --> C[Load combo models sequence]
+    B -- No --> D[Single model path]
+
+    C --> E[Try model N]
+    E --> F[Resolve provider/model]
+    D --> F
+
+    F --> G[Select account credentials]
+    G --> H{Credentials available?}
+    H -- No --> I[Return provider unavailable]
+    H -- Yes --> J[Execute request]
+
+    J --> K{Success?}
+    K -- Yes --> L[Return response]
+    K -- No --> M{Fallback-eligible error?}
+
+    M -- No --> N[Return error]
+    M -- Yes --> O[Mark account unavailable cooldown]
+    O --> P{Another account for provider?}
+    P -- Yes --> G
+    P -- No --> Q{In combo with next model?}
+    Q -- Yes --> E
+    Q -- No --> R[Return all unavailable]
+```
+
+Les décisions de secours sont pilotées par `open-sse/services/accountFallback.ts` à l'aide de codes d'état et d'heuristiques de messages d'erreur.
+
+## Cycle de vie de l'intégration OAuth et de l'actualisation des jetons
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Dashboard UI
+    participant OAuth as /api/oauth/[provider]/[action]
+    participant ProvAuth as Provider Auth Server
+    participant DB as localDb
+    participant Test as /api/providers/[id]/test
+    participant Exec as Provider Executor
+
+    UI->>OAuth: GET authorize or device-code
+    OAuth->>ProvAuth: create auth/device flow
+    ProvAuth-->>OAuth: auth URL or device code payload
+    OAuth-->>UI: flow data
+
+    UI->>OAuth: POST exchange or poll
+    OAuth->>ProvAuth: token exchange/poll
+    ProvAuth-->>OAuth: access/refresh tokens
+    OAuth->>DB: createProviderConnection(oauth data)
+    OAuth-->>UI: success + connection id
+
+    UI->>Test: POST /api/providers/[id]/test
+    Test->>Exec: validate credentials / optional refresh
+    Exec-->>Test: valid or refreshed token info
+    Test->>DB: update status/tokens/errors
+    Test-->>UI: validation result
+```
+
+L'actualisation pendant le trafic en direct est exécutée dans `open-sse/handlers/chatCore.ts` via l'exécuteur `refreshCredentials()`.
+
+## Cycle de vie de Cloud Sync (Activer/Sync/Désactiver)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Endpoint Page UI
+    participant Sync as /api/sync/cloud
+    participant DB as localDb
+    participant Cloud as External Cloud Sync
+    participant Claude as ~/.claude/settings.json
+
+    UI->>Sync: POST action=enable
+    Sync->>DB: set cloudEnabled=true
+    Sync->>DB: ensure API key exists
+    Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys)
+    Cloud-->>Sync: sync result
+    Sync->>Cloud: GET /{machineId}/v1/verify
+    Sync-->>UI: enabled + verification status
+
+    UI->>Sync: POST action=sync
+    Sync->>Cloud: POST /sync/{machineId}
+    Cloud-->>Sync: remote data
+    Sync->>DB: update newer local tokens/status
+    Sync-->>UI: synced
+
+    UI->>Sync: POST action=disable
+    Sync->>DB: set cloudEnabled=false
+    Sync->>Cloud: DELETE /sync/{machineId}
+    Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed)
+    Sync-->>UI: disabled
+```
+
+La synchronisation périodique est déclenchée par `CloudSyncScheduler` lorsque le cloud est activé.
+
+## Modèle de données et carte de stockage
+
+```mermaid
+erDiagram
+    SETTINGS ||--o{ PROVIDER_CONNECTION : controls
+    PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider
+    PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage
+
+    SETTINGS {
+      boolean cloudEnabled
+      number stickyRoundRobinLimit
+      boolean requireLogin
+      string password_hash
+      string fallbackStrategy
+      json rateLimitDefaults
+      json providerProfiles
+    }
+
+    PROVIDER_CONNECTION {
+      string id
+      string provider
+      string authType
+      string name
+      number priority
+      boolean isActive
+      string apiKey
+      string accessToken
+      string refreshToken
+      string expiresAt
+      string testStatus
+      string lastError
+      string rateLimitedUntil
+      json providerSpecificData
+    }
+
+    PROVIDER_NODE {
+      string id
+      string type
+      string name
+      string prefix
+      string apiType
+      string baseUrl
+    }
+
+    MODEL_ALIAS {
+      string alias
+      string targetModel
+    }
+
+    COMBO {
+      string id
+      string name
+      string[] models
+    }
+
+    API_KEY {
+      string id
+      string name
+      string key
+      string machineId
+    }
+
+    USAGE_ENTRY {
+      string provider
+      string model
+      number prompt_tokens
+      number completion_tokens
+      string connectionId
+      string timestamp
+    }
+
+    CUSTOM_MODEL {
+      string id
+      string name
+      string providerId
+    }
+
+    PROXY_CONFIG {
+      string global
+      json providers
+    }
+
+    IP_FILTER {
+      string mode
+      string[] allowlist
+      string[] blocklist
+    }
+
+    THINKING_BUDGET {
+      string mode
+      number customBudget
+      string effortLevel
+    }
+
+    SYSTEM_PROMPT {
+      boolean enabled
+      string prompt
+      string position
+    }
+```
+
+Fichiers de stockage physique :
+
+- état principal : `${DATA_DIR}/db.json` (ou `$XDG_CONFIG_HOME/omniroute/db.json` lorsqu'il est défini, sinon `~/.omniroute/db.json`)
+- statistiques d'utilisation : `${DATA_DIR}/usage.json`
+- lignes de journal de demande : `${DATA_DIR}/log.txt`
+- sessions facultatives de débogage de traduction/demande : `<repo>/logs/...`
+
+## Topologie de déploiement
+
+```mermaid
+flowchart LR
+    subgraph LocalHost[Developer Host]
+        CLI[CLI Tools]
+        Browser[Dashboard Browser]
+    end
+
+    subgraph ContainerOrProcess[OmniRoute Runtime]
+        Next[Next.js Server\nPORT=20128]
+        Core[SSE Core + Executors]
+        MainDB[(db.json)]
+        UsageDB[(usage.json/log.txt)]
+    end
+
+    subgraph External[External Services]
+        Providers[AI Providers]
+        SyncCloud[Cloud Sync Service]
+    end
+
+    CLI --> Next
+    Browser --> Next
+    Next --> Core
+    Next --> MainDB
+    Core --> MainDB
+    Core --> UsageDB
+    Core --> Providers
+    Next --> SyncCloud
+```
+
+## Cartographie des modules (critique en matière de décision)
+
+### Modules de routage et d'API
+
+- `src/app/api/v1/*`, `src/app/api/v1beta/*` : API de compatibilité
+- `src/app/api/v1/providers/[provider]/*` : routes dédiées par fournisseur (chat, intégrations, images)
+- `src/app/api/providers*` : fournisseur CRUD, validation, tests
+- `src/app/api/provider-nodes*` : gestion des nœuds compatibles personnalisés
+- `src/app/api/provider-models` : gestion de modèles personnalisés (CRUD)
+- `src/app/api/models/catalog` : API de catalogue de modèles complet (tous les types regroupés par fournisseur)
+- `src/app/api/oauth/*` : flux OAuth/code de périphérique
+- `src/app/api/keys*` : cycle de vie de la clé API locale
+- `src/app/api/models/alias` : gestion des alias
+- `src/app/api/combos*` : gestion des combos de repli
+- `src/app/api/pricing` : remplacements de prix pour le calcul des coûts
+- `src/app/api/settings/proxy` : configuration du proxy (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test` : test de connectivité proxy sortant (POST)
+- `src/app/api/usage/*` : API d'utilisation et de logs
+- `src/app/api/sync/*` + `src/app/api/cloud/*` : synchronisation cloud et assistants orientés cloud
+- `src/app/api/cli-tools/*` : rédacteurs/vérificateurs de configuration CLI locaux
+- `src/app/api/settings/ip-filter` : liste autorisée/liste de blocage IP (GET/PUT)
+- `src/app/api/settings/thinking-budget` : configuration du budget des jetons de réflexion (GET/PUT)
+- `src/app/api/settings/system-prompt` : invite système globale (GET/PUT)
+- `src/app/api/sessions` : listing des sessions actives (GET)
+- `src/app/api/rate-limits` : statut de limite de débit par compte (GET)
+
+### Noyau de routage et d'exécution
+
+- `src/sse/handlers/chat.ts` : analyse des requêtes, gestion des combos, boucle de sélection de compte
+- `open-sse/handlers/chatCore.ts` : traduction, envoi de l'exécuteur, gestion des nouvelles tentatives/actualisations, configuration du flux
+- `open-sse/executors/*` : comportement de réseau et de format spécifique au fournisseur
+
+### Registre de traduction et convertisseurs de format
+
+- `open-sse/translator/index.ts` : registre et orchestration des traducteurs
+- Demander des traducteurs : `open-sse/translator/request/*`
+- Traducteurs de réponse : `open-sse/translator/response/*`
+- Constantes de format : `open-sse/translator/formats.ts`
+
+### Persistance
+
+- `src/lib/localDb.ts` : configuration/état persistant
+- `src/lib/usageDb.ts` : historique d'utilisation et journaux de requêtes glissantes
+
+## Couverture de l'exécuteur du fournisseur (modèle de stratégie)
+
+Chaque fournisseur dispose d'un exécuteur spécialisé étendant `BaseExecutor` (dans `open-sse/executors/base.ts`), qui fournit la création d'URL, la construction d'en-tête, les nouvelles tentatives avec interruption exponentielle, les points d'ancrage d'actualisation des informations d'identification et la méthode d'orchestration `execute()`.
+
+| Exécuteur testamentaire | Fournisseur(s)                                                                                                                                               | Manutention spéciale                                                                |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| `DefaultExecutor`       | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Configuration dynamique d'URL/d'en-tête par fournisseur                             |
+| `AntigravityExecutor`   | Google Antigravité                                                                                                                                           | ID de projet/session personnalisés, analyse réessayée après                         |
+| `CodexExecutor`         | Codex OpenAI                                                                                                                                                 | Injecte des instructions système, force un effort de raisonnement                   |
+| `CursorExecutor`        | Curseur IDE                                                                                                                                                  | Protocole ConnectRPC, encodage Protobuf, signature de demande via somme de contrôle |
+| `GithubExecutor`        | Copilote GitHub                                                                                                                                              | Actualisation du jeton Copilot, en-têtes imitant VSCode                             |
+| `KiroExecutor`          | AWS CodeWhisperer/Kiro                                                                                                                                       | Format binaire AWS EventStream → conversion SSE                                     |
+| `GeminiCLIExecutor`     | CLI Gémeaux                                                                                                                                                  | Cycle d'actualisation du jeton Google OAuth                                         |
+
+Tous les autres fournisseurs (y compris les nœuds compatibles personnalisés) utilisent le `DefaultExecutor`.
+
+## Matrice de compatibilité des fournisseurs
+
+| Fournisseur           | Formater          | Authentification                | Flux             | Hors flux | Actualisation des jetons | API d'utilisation            |
+| --------------------- | ----------------- | ------------------------------- | ---------------- | --------- | ------------------------ | ---------------------------- |
+| Claude                | Claude            | Clé API/OAuth                   | ✅               | ✅        | ✅                       | ⚠️ Administrateur uniquement |
+| Gémeaux               | Gémeaux           | Clé API/OAuth                   | ✅               | ✅        | ✅                       | ⚠️Console Cloud              |
+| CLI Gémeaux           | gemini-cli        | OAuth                           | ✅               | ✅        | ✅                       | ⚠️Console Cloud              |
+| Antigravité           | antigravité       | OAuth                           | ✅               | ✅        | ✅                       | ✅ API de quota complet      |
+| OpenAI                | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
+| Codex                 | réponses ouvertes | OAuth                           | ✅ forcé         | ❌        | ✅                       | ✅ Limites de taux           |
+| Copilote GitHub       | ouvert            | OAuth + Jeton Copilot           | ✅               | ✅        | ✅                       | ✅ Instantanés de quotas     |
+| Curseur               | curseur           | Somme de contrôle personnalisée | ✅               | ✅        | ❌                       | ❌                           |
+| Kiro                  | Kiro              | AWS SSO OIDC                    | ✅ (EventStream) | ❌        | ✅                       | ✅ Limites d'utilisation     |
+| Qwen                  | ouvert            | OAuth                           | ✅               | ✅        | ✅                       | ⚠️ Par demande               |
+| iFlow                 | ouvert            | OAuth (de base)                 | ✅               | ✅        | ✅                       | ⚠️ Par demande               |
+| OuvrirRouter          | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
+| GLM/Kimi/MiniMax      | Claude            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
+| Recherche profonde    | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
+| Groq                  | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
+| xAI (Grok)            | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
+| Mistral               | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
+| Perplexité            | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
+| Ensemble IA           | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
+| IA de feux d'artifice | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
+| Cérébraux             | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
+| Cohérer               | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
+| NIM NVIDIA            | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
+
+## Format de couverture de traduction
+
+Les formats sources détectés incluent :
+
+- `openai`
+- `openai-responses`
+- `claude`
+- `gemini`
+
+Les formats cibles incluent :
+
+- Discussion/Réponses OpenAI
+  -Claude
+- Enveloppe Gemini/Gemini-CLI/Antigravité
+  -Kiro
+- Curseur
+
+Les traductions utilisent **OpenAI comme format hub** — toutes les conversions passent par OpenAI comme intermédiaire :
+
+```
+Source Format → OpenAI (hub) → Target Format
+```
+
+Les traductions sont sélectionnées dynamiquement en fonction de la forme de la charge utile source et du format cible du fournisseur.
+
+Couches de traitement supplémentaires dans le pipeline de traduction :
+
+- **Désinfection des réponses** — Supprime les champs non standard des réponses au format OpenAI (à la fois en streaming et hors streaming) pour garantir une stricte conformité au SDK.
+- **Normalisation des rôles** — Convertit `developer` → `system` pour les cibles non OpenAI ; fusionne `system` → `user` pour les modèles qui rejettent le rôle système (GLM, ERNIE)
+- **Think tag extraction** — Analyse les blocs `<think>...</think>` du contenu dans le champ `reasoning_content`
+- **Sortie structurée** — Convertit OpenAI `response_format.json_schema` en `responseMimeType` + `responseSchema` de Gemini
+
+## Points de terminaison d'API pris en charge
+
+| Point de terminaison                               | Formater                 | Gestionnaire                                                      |
+| -------------------------------------------------- | ------------------------ | ----------------------------------------------------------------- |
+| `POST /v1/chat/completions`                        | Chat OpenAI              | `src/sse/handlers/chat.ts`                                        |
+| `POST /v1/messages`                                | Messages de Claude       | Même gestionnaire (détecté automatiquement)                       |
+| `POST /v1/responses`                               | Réponses OpenAI          | `open-sse/handlers/responsesHandler.ts`                           |
+| `POST /v1/embeddings`                              | Intégrations OpenAI      | `open-sse/handlers/embeddings.ts`                                 |
+| `GET /v1/embeddings`                               | Liste des modèles        | Itinéraire API                                                    |
+| `POST /v1/images/generations`                      | Images OpenAI            | `open-sse/handlers/imageGeneration.ts`                            |
+| `GET /v1/images/generations`                       | Liste des modèles        | Itinéraire API                                                    |
+| `POST /v1/providers/{provider}/chat/completions`   | Chat OpenAI              | Dédié par fournisseur avec validation du modèle                   |
+| `POST /v1/providers/{provider}/embeddings`         | Intégrations OpenAI      | Dédié par fournisseur avec validation du modèle                   |
+| `POST /v1/providers/{provider}/images/generations` | Images OpenAI            | Dédié par fournisseur avec validation du modèle                   |
+| `POST /v1/messages/count_tokens`                   | Compte de jetons Claude  | Itinéraire API                                                    |
+| `GET /v1/models`                                   | Liste des modèles OpenAI | Route API (chat + intégration + image + modèles personnalisés)    |
+| `GET /api/models/catalog`                          | Catalogue                | Tous les modèles regroupés par fournisseur + type                 |
+| `POST /v1beta/models/*:streamGenerateContent`      | Natif des Gémeaux        | Itinéraire API                                                    |
+| `GET/PUT/DELETE /api/settings/proxy`               | Configuration du proxy   | Configuration du proxy réseau                                     |
+| `POST /api/settings/proxy/test`                    | Connectivité proxy       | Point de terminaison du test d’intégrité/de connectivité du proxy |
+| `GET/POST/DELETE /api/provider-models`             | Modèles personnalisés    | Gestion de modèles personnalisés par fournisseur                  |
+
+## Gestionnaire de contournement
+
+Le gestionnaire de contournement (`open-sse/utils/bypassHandler.ts`) intercepte les requêtes « jetables » connues de Claude CLI (pings d'échauffement, extractions de titres et nombre de jetons) et renvoie une **fausse réponse** sans consommer de jetons du fournisseur en amont. Ceci est déclenché uniquement lorsque `User-Agent` contient `claude-cli`.
+
+## Demander un pipeline d'enregistreur
+
+L'enregistreur de requêtes (`open-sse/utils/requestLogger.ts`) fournit un pipeline de journalisation de débogage en 7 étapes, désactivé par défaut, activé 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
+```
+
+Les fichiers sont écrits dans `<repo>/logs/<session>/` pour chaque session de demande.
+
+## Modes de défaillance et résilience
+
+## 1) Disponibilité du compte/fournisseur
+
+- Temps de recharge du compte du fournisseur en cas d'erreurs transitoires/taux/auth.
+- repli du compte avant l'échec de la demande
+- repli du modèle combiné lorsque le chemin modèle/fournisseur actuel est épuisé
+
+## 2) Expiration du jeton
+
+- pré-vérification et actualisation avec nouvelle tentative pour les fournisseurs actualisables
+- Nouvelle tentative 401/403 après tentative d'actualisation dans le chemin principal
+
+## 3) Sécurité des flux
+
+- contrôleur de flux prenant en charge la déconnexion
+- flux de traduction avec vidage de fin de flux et gestion `[DONE]`
+- repli de l'estimation de l'utilisation lorsque les métadonnées d'utilisation du fournisseur sont manquantes
+
+## 4) Dégradation de la synchronisation cloud
+
+- des erreurs de synchronisation apparaissent mais l'exécution locale continue
+- le planificateur a une logique capable de réessayer, mais l'exécution périodique appelle actuellement une synchronisation à tentative unique par défaut
+
+## 5) Intégrité des données
+
+- Migration/réparation de forme de base de données pour les clés manquantes
+- protections de réinitialisation JSON corrompues pour localDb et usageDb
+
+## Observabilité et signaux opérationnels
+
+Sources de visibilité d'exécution :
+
+- Journaux de console de `src/sse/utils/logger.ts`
+- agrégats d'utilisation par requête dans `usage.json`
+- Journal d'état de la demande textuelle dans `log.txt`
+- Journaux facultatifs de requêtes/traductions approfondies sous `logs/` lorsque `ENABLE_REQUEST_LOGS=true`
+- points de terminaison d'utilisation du tableau de bord (`/api/usage/*`) pour la consommation de l'interface utilisateur
+
+## Limites sensibles à la sécurité
+
+- Le secret JWT (`JWT_SECRET`) sécurise la vérification/signature des cookies de session du tableau de bord
+- Le mot de passe initial de secours (`INITIAL_PASSWORD`, par défaut `123456`) doit être remplacé dans les déploiements réels
+- Le secret de la clé API HMAC (`API_KEY_SECRET`) sécurise le format de clé API locale généré
+- Les secrets du fournisseur (clés/jetons API) sont conservés dans la base de données locale et doivent être protégés au niveau du système de fichiers
+- Les points de terminaison de synchronisation dans le cloud s'appuient sur l'authentification par clé API + la sémantique de l'identifiant de la machine
+
+## Matrice d'environnement et d'exécution
+
+Variables d'environnement activement utilisées par le code :
+
+- Application/authentification : `JWT_SECRET`, `INITIAL_PASSWORD`
+- Stockage : `DATA_DIR`
+- Comportement du nœud compatible : `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
+- Remplacement facultatif de la base de stockage (Linux/macOS lorsque `DATA_DIR` n'est pas défini) : `XDG_CONFIG_HOME`
+- Hachage de sécurité : `API_KEY_SECRET`, `MACHINE_ID_SALT`
+- Journalisation : `ENABLE_REQUEST_LOGS`
+- URL de synchronisation/cloud : `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
+- Proxy sortant : `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` et variantes minuscules
+- Indicateurs de fonctionnalité SOCKS5 : `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
+- Aides de plate-forme/d'exécution (pas de configuration spécifique à l'application) : `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+
+## Notes architecturales connues
+
+1. `usageDb` et `localDb` partagent désormais la même stratégie de répertoire de base (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) avec la migration des fichiers existants.
+2. `/api/v1/route.ts` renvoie une liste de modèles statiques et n'est pas la source principale de modèles utilisée par `/v1/models`.
+3. L'enregistreur de requêtes écrit les en-têtes/corps complets lorsqu'il est activé ; traiter le répertoire des journaux comme sensible.
+4. Le comportement du cloud dépend de l'exactitude du `NEXT_PUBLIC_BASE_URL` et de l'accessibilité du point de terminaison du cloud.
+5. Le répertoire `open-sse/` est publié en tant que `@omniroute/open-sse` **package d'espace de travail npm**. Le code source l'importe via `@omniroute/open-sse/...` (résolu par Next.js `transpilePackages`). Les chemins de fichiers dans ce document utilisent toujours le nom de répertoire `open-sse/` par souci de cohérence.
+6. Les graphiques du tableau de bord utilisent **Recharts** (basé sur SVG) pour des visualisations analytiques accessibles et interactives (graphiques à barres d'utilisation du modèle, tableaux de répartition des fournisseurs avec taux de réussite).
+7. Les tests E2E utilisent **Playwright** (`tests/e2e/`), exécutés via `npm run test:e2e`. Les tests unitaires utilisent **l'exécuteur de test Node.js** (`tests/unit/`), exécutés via `npm run test:plan3`. Le code source sous `src/` est **TypeScript** (`.ts`/`.tsx`) ; l'espace de travail `open-sse/` reste JavaScript (`.js`).
+8. La page Paramètres est organisée en 5 onglets : Sécurité, Routage (6 stratégies globales : remplissage en premier, round-robin, p2c, aléatoire, moins utilisé, coût optimisé), Résilience (limites de débit modifiables, disjoncteur, politiques), IA (budget de réflexion, invite système, cache d'invite), Avancé (proxy).
+
+## Liste de contrôle de vérification opérationnelle
+
+- Construire à partir des sources : `npm run build`
+- Créer une image Docker : `docker build -t omniroute .`
+- Démarrez le service et vérifiez :
+- `GET /api/settings`
+- `GET /api/v1/models`
+- L'URL de base cible CLI doit être `http://<host>:20128/v1` lorsque `PORT=20128`

docs/i18n/fr/CODEBASE_DOCUMENTATION.md

@@ -0,0 +1,589 @@
+# omniroute — Documentation de base de code
+
+🌐 **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)
+
+> Un guide complet et convivial pour les débutants sur le routeur proxy IA multifournisseur **omniroute**.
+
+---
+
+## 1. Qu'est-ce qu'omniroute ?
+
+omniroute est un **routeur proxy** qui se situe entre les clients IA (Claude CLI, Codex, Cursor IDE, etc.) et les fournisseurs d'IA (Anthropic, Google, OpenAI, AWS, GitHub, etc.). Cela résout un gros problème :
+
+> **Différents clients d'IA parlent différentes « langues » (formats API), et différents fournisseurs d'IA s'attendent également à des « langues » différentes.** omniroute traduit automatiquement entre eux.
+
+Considérez-le comme un traducteur universel aux Nations Unies : n'importe quel délégué peut parler n'importe quelle langue, et le traducteur la convertit pour n'importe quel autre délégué.
+
+---
+
+## 2. Présentation de l'architecture
+
+```mermaid
+graph LR
+    subgraph Clients
+        A[Claude CLI]
+        B[Codex]
+        C[Cursor IDE]
+        D[OpenAI-compatible]
+    end
+
+    subgraph omniroute
+        E[Handler Layer]
+        F[Translator Layer]
+        G[Executor Layer]
+        H[Services Layer]
+    end
+
+    subgraph Providers
+        I[Anthropic Claude]
+        J[Google Gemini]
+        K[OpenAI / Codex]
+        L[GitHub Copilot]
+        M[AWS Kiro]
+        N[Antigravity]
+        O[Cursor API]
+    end
+
+    A --> E
+    B --> E
+    C --> E
+    D --> E
+    E --> F
+    F --> G
+    G --> I
+    G --> J
+    G --> K
+    G --> L
+    G --> M
+    G --> N
+    G --> O
+    H -.-> E
+    H -.-> G
+```
+
+### Principe de base : traduction en étoile
+
+Toutes les traductions de format passent par le **format OpenAI comme hub** :
+
+```
+Client Format → [OpenAI Hub] → Provider Format    (request)
+Provider Format → [OpenAI Hub] → Client Format    (response)
+```
+
+Cela signifie que vous n'avez besoin que de **N traducteurs** (un par format) au lieu de **N²** (chaque paire).
+
+---
+
+## 3. Structure du projet
+
+```
+omniroute/
+├── open-sse/                  ← Core proxy library (portable, framework-agnostic)
+│   ├── index.js               ← Main entry point, exports everything
+│   ├── config/                ← Configuration & constants
+│   ├── executors/             ← Provider-specific request execution
+│   ├── handlers/              ← Request handling orchestration
+│   ├── services/              ← Business logic (auth, models, fallback, usage)
+│   ├── translator/            ← Format translation engine
+│   │   ├── request/           ← Request translators (8 files)
+│   │   ├── response/          ← Response translators (7 files)
+│   │   └── helpers/           ← Shared translation utilities (6 files)
+│   └── utils/                 ← Utility functions
+├── src/                       ← Application layer (Express/Worker runtime)
+│   ├── app/                   ← Web UI, API routes, middleware
+│   ├── lib/                   ← Database, auth, and shared library code
+│   ├── mitm/                  ← Man-in-the-middle proxy utilities
+│   ├── models/                ← Database models
+│   ├── shared/                ← Shared utilities (wrappers around open-sse)
+│   ├── sse/                   ← SSE endpoint handlers
+│   └── store/                 ← State management
+├── data/                      ← Runtime data (credentials, logs)
+│   └── provider-credentials.json   (external credentials override, gitignored)
+└── tester/                    ← Test utilities
+```
+
+---
+
+## 4. Répartition module par module
+
+### 4.1 Configuration (`open-sse/config/`)
+
+La **source unique de vérité** pour toutes les configurations de fournisseurs.
+
+| Fichier                       | Objectif                                                                                                                                                                                                                                                                  |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `constants.ts`                | Objet `PROVIDERS` avec les URL de base, les informations d'identification OAuth (par défaut), les en-têtes et les invites système par défaut pour chaque fournisseur. Définit également `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` et `SKIP_PATTERNS`. |
+| `credentialLoader.ts`         | Charge les informations d'identification externes de `data/provider-credentials.json` et les fusionne avec les valeurs par défaut codées en dur dans `PROVIDERS`. Garde les secrets hors du contrôle des sources tout en conservant la compatibilité ascendante.          |
+| `providerModels.ts`           | Registre central des modèles : mappe les alias des fournisseurs → les ID de modèle. Fonctionne comme `getModels()`, `getProviderByAlias()`.                                                                                                                               |
+| `codexInstructions.ts`        | Instructions système injectées dans les requêtes Codex (contraintes d'édition, règles sandbox, politiques d'approbation).                                                                                                                                                 |
+| `defaultThinkingSignature.ts` | Signatures « pensées » par défaut pour les modèles Claude et Gemini.                                                                                                                                                                                                      |
+| `ollamaModels.ts`             | Définition de schéma pour les modèles Ollama locaux (nom, taille, famille, quantification).                                                                                                                                                                               |
+
+#### Flux de chargement des informations d'identification
+
+```mermaid
+flowchart TD
+    A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"]
+    B --> C{"data/provider-credentials.json\nexists?"}
+    C -->|Yes| D["credentialLoader reads JSON"]
+    C -->|No| E["Use hardcoded defaults"]
+    D --> F{"For each provider in JSON"}
+    F --> G{"Provider exists\nin PROVIDERS?"}
+    G -->|No| H["Log warning, skip"]
+    G -->|Yes| I{"Value is object?"}
+    I -->|No| J["Log warning, skip"]
+    I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"]
+    K --> F
+    H --> F
+    J --> F
+    F -->|Done| L["PROVIDERS ready with\nmerged credentials"]
+    E --> L
+```
+
+---
+
+### 4.2 Exécuteurs (`open-sse/executors/`)
+
+Les exécuteurs encapsulent la **logique spécifique au fournisseur** à l'aide du **Modèle de stratégie**. Chaque exécuteur remplace les méthodes de base selon les besoins.
+
+```mermaid
+classDiagram
+    class BaseExecutor {
+        +buildUrl(model, stream, options)
+        +buildHeaders(credentials, stream, body)
+        +transformRequest(body, model, stream, credentials)
+        +execute(url, options)
+        +shouldRetry(status, error)
+        +refreshCredentials(credentials, log)
+    }
+
+    class DefaultExecutor {
+        +refreshCredentials()
+    }
+
+    class AntigravityExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +shouldRetry()
+        +refreshCredentials()
+    }
+
+    class CursorExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseResponse()
+        +generateChecksum()
+    }
+
+    class KiroExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseEventStream()
+        +refreshCredentials()
+    }
+
+    BaseExecutor <|-- DefaultExecutor
+    BaseExecutor <|-- AntigravityExecutor
+    BaseExecutor <|-- CursorExecutor
+    BaseExecutor <|-- KiroExecutor
+    BaseExecutor <|-- CodexExecutor
+    BaseExecutor <|-- GeminiCLIExecutor
+    BaseExecutor <|-- GithubExecutor
+```
+
+| Exécuteur testamentaire | Fournisseur                                 | Spécialisations clés                                                                                                                                               |
+| ----------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `base.ts`               | —                                           | Base abstraite : création d'URL, en-têtes, logique de nouvelle tentative, actualisation des informations d'identification                                          |
+| `default.ts`            | Claude, Gémeaux, OpenAI, GLM, Kimi, MiniMax | Actualisation du jeton OAuth générique pour les fournisseurs standards                                                                                             |
+| `antigravity.ts`        | Code Google Cloud                           | Génération d'ID de projet/session, secours multi-URL, nouvelle tentative d'analyse personnalisée à partir des messages d'erreur ("réinitialisation après 2h7m23s") |
+| `cursor.ts`             | Curseur IDE                                 | **Le plus complexe** : authentification par somme de contrôle SHA-256, encodage de requête Protobuf, EventStream binaire → analyse de réponse SSE                  |
+| `codex.ts`              | Codex OpenAI                                | Injecte les instructions système, gère les niveaux de réflexion, supprime les paramètres non pris en charge                                                        |
+| `gemini-cli.ts`         | CLI Google Gemini                           | Création d'URL personnalisées (`streamGenerateContent`), actualisation du jeton Google OAuth                                                                       |
+| `github.ts`             | Copilote GitHub                             | Système à double jeton (GitHub OAuth + jeton Copilot), imitation d'en-tête VSCode                                                                                  |
+| `kiro.ts`               | AWS CodeWhisperer                           | Analyse binaire AWS EventStream, cadres d'événements AMZN, estimation de jetons                                                                                    |
+| `index.ts`              | —                                           | Factory : nom du fournisseur de cartes → classe d'exécuteur, avec solution de secours par défaut                                                                   |
+
+---
+
+### 4.3 Gestionnaires (`open-sse/handlers/`)
+
+La **couche d'orchestration** : coordonne la traduction, l'exécution, le streaming et la gestion des erreurs.
+
+| Fichier               | Objectif                                                                                                                                                                                                                                                                   |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chatCore.ts`         | **Orchestrateur central** (~600 lignes). Gère le cycle de vie complet de la demande : détection du format → traduction → répartition de l'exécuteur → réponse en streaming/non-streaming → actualisation du jeton → gestion des erreurs → journalisation de l'utilisation. |
+| `responsesHandler.ts` | Adaptateur pour l'API Responses d'OpenAI : convertit le format des réponses → Fins de discussion → envoie à `chatCore` → reconvertit SSE au format de réponses.                                                                                                            |
+| `embeddings.ts`       | Gestionnaire de génération d'intégration : résout le modèle d'intégration → fournisseur, envoi à l'API du fournisseur, renvoie la réponse d'intégration compatible OpenAI. Prend en charge plus de 6 fournisseurs.                                                         |
+| `imageGeneration.ts`  | Gestionnaire de génération d'images : résout le modèle d'image → fournisseur, prend en charge les modes compatibles OpenAI, Gemini-image (Antigravity) et de secours (Nebius). Renvoie des images base64 ou URL.                                                           |
+
+#### Cycle de vie des requêtes (chatCore.ts)
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant chatCore
+    participant Translator
+    participant Executor
+    participant Provider
+
+    Client->>chatCore: Request (any format)
+    chatCore->>chatCore: Detect source format
+    chatCore->>chatCore: Check bypass patterns
+    chatCore->>chatCore: Resolve model & provider
+    chatCore->>Translator: Translate request (source → OpenAI → target)
+    chatCore->>Executor: Get executor for provider
+    Executor->>Executor: Build URL, headers, transform request
+    Executor->>Executor: Refresh credentials if needed
+    Executor->>Provider: HTTP fetch (streaming or non-streaming)
+
+    alt Streaming
+        Provider-->>chatCore: SSE stream
+        chatCore->>chatCore: Pipe through SSE transform stream
+        Note over chatCore: Transform stream translates<br/>each chunk: target → OpenAI → source
+        chatCore-->>Client: Translated SSE stream
+    else Non-streaming
+        Provider-->>chatCore: JSON response
+        chatCore->>Translator: Translate response
+        chatCore-->>Client: Translated JSON
+    end
+
+    alt Error (401, 429, 500...)
+        chatCore->>Executor: Retry with credential refresh
+        chatCore->>chatCore: Account fallback logic
+    end
+```
+
+---
+
+### 4.4 Services (`open-sse/services/`)
+
+Logique métier qui prend en charge les gestionnaires et les exécuteurs.
+
+| Fichier              | Objectif                                                                                                                                                                                                                                                                                                                                                                                                       |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider.ts`        | **Détection de format** (`detectFormat`) : analyse la structure du corps de la requête pour identifier les formats Claude/OpenAI/Gemini/Antigravity/Responses (inclut l'heuristique `max_tokens` pour Claude). Aussi : création d'URL, création d'en-têtes, réflexion sur la normalisation de la configuration. Prend en charge les fournisseurs dynamiques `openai-compatible-*` et `anthropic-compatible-*`. |
+| `model.ts`           | Analyse de chaîne de modèle (`claude/model-name` → `{provider: "claude", model: "model-name"}`), résolution d'alias avec détection de collision, désinfection des entrées (rejette les caractères de parcours/contrôle de chemin) et résolution d'informations de modèle avec prise en charge du getter d'alias asynchrone.                                                                                    |
+| `accountFallback.ts` | Gestion des limites de débit : interruption exponentielle (1s → 2s → 4s → max 2min), gestion du temps de recharge du compte, classification des erreurs (quelles erreurs déclenchent le repli ou non).                                                                                                                                                                                                         |
+| `tokenRefresh.ts`    | Actualisation du jeton OAuth pour **chaque fournisseur** : Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (double jeton OAuth + Copilot), Kiro (AWS SSO OIDC + Social Auth). Inclut un cache de déduplication de promesses en cours et une nouvelle tentative avec une interruption exponentielle.                                                                                           |
+| `combo.ts`           | **Modèles combo** : chaînes de modèles de secours. Si le modèle A échoue avec une erreur éligible au repli, essayez le modèle B, puis C, etc. Renvoie les codes d'état en amont réels.                                                                                                                                                                                                                         |
+| `usage.ts`           | Récupère les données de quota/utilisation des API du fournisseur (quotas GitHub Copilot, quotas du modèle Antigravity, limites de débit du Codex, répartitions d'utilisation de Kiro, paramètres Claude).                                                                                                                                                                                                      |
+| `accountSelector.ts` | Sélection intelligente des comptes avec algorithme de notation : prend en compte la priorité, l'état de santé, la position du tourniquet et l'état du temps de recharge pour choisir le compte optimal pour chaque demande.                                                                                                                                                                                    |
+| `contextManager.ts`  | Gestion du cycle de vie du contexte de demande : crée et suit des objets de contexte par demande avec des métadonnées (ID de demande, horodatages, informations sur le fournisseur) pour le débogage et la journalisation.                                                                                                                                                                                     |
+| `ipFilter.ts`        | Contrôle d'accès basé sur IP : prend en charge les modes liste d'autorisation et liste de blocage. Valide l'adresse IP du client par rapport aux règles configurées avant de traiter les requêtes API.                                                                                                                                                                                                         |
+| `sessionManager.ts`  | Suivi des sessions avec empreintes digitales des clients : suit les sessions actives à l'aide d'identifiants client hachés, surveille le nombre de demandes et fournit des métriques de session.                                                                                                                                                                                                               |
+| `signatureCache.ts`  | Cache de déduplication basé sur les signatures de requête : évite les requêtes en double en mettant en cache les signatures de requêtes récentes et en renvoyant les réponses mises en cache pour les requêtes identiques dans une fenêtre de temps.                                                                                                                                                           |
+| `systemPrompt.ts`    | Injection d’invite système globale : ajoute ou ajoute une invite système configurable à toutes les requêtes, avec gestion de la compatibilité par fournisseur.                                                                                                                                                                                                                                                 |
+| `thinkingBudget.ts`  | Gestion du budget des jetons de raisonnement : prend en charge les modes passthrough, automatique (configuration de réflexion en bande), personnalisé (budget fixe) et adaptatif (à l'échelle de la complexité) pour contrôler les jetons de réflexion/raisonnement.                                                                                                                                           |
+| `wildcardRouter.ts`  | Routage de modèles de modèles génériques : résout les modèles de caractères génériques (par exemple, `*/claude-*`) en paires fournisseur/modèle concrètes en fonction de la disponibilité et de la priorité.                                                                                                                                                                                                   |
+
+#### Déduplication d'actualisation des jetons
+
+```mermaid
+sequenceDiagram
+    participant R1 as Request 1
+    participant R2 as Request 2
+    participant Cache as refreshPromiseCache
+    participant OAuth as OAuth Provider
+
+    R1->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: No in-flight promise
+    Cache->>OAuth: Start refresh
+    R2->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: Found in-flight promise
+    Cache-->>R2: Return existing promise
+    OAuth-->>Cache: New access token
+    Cache-->>R1: New access token
+    Cache-->>R2: Same access token (shared)
+    Cache->>Cache: Delete cache entry
+```
+
+#### Machine d'état de secours du compte
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active
+    Active --> Error: Request fails (401/429/500)
+    Error --> Cooldown: Apply backoff
+    Cooldown --> Active: Cooldown expires
+    Active --> Active: Request succeeds (reset backoff)
+
+    state Error {
+        [*] --> ClassifyError
+        ClassifyError --> ShouldFallback: Rate limit / Auth / Transient
+        ClassifyError --> NoFallback: 400 Bad Request
+    }
+
+    state Cooldown {
+        [*] --> ExponentialBackoff
+        ExponentialBackoff: Level 0 = 1s
+        ExponentialBackoff: Level 1 = 2s
+        ExponentialBackoff: Level 2 = 4s
+        ExponentialBackoff: Max = 2min
+    }
+```
+
+#### Chaîne de modèles combo
+
+```mermaid
+flowchart LR
+    A["Request with\ncombo model"] --> B["Model A"]
+    B -->|"2xx Success"| C["Return response"]
+    B -->|"429/401/500"| D{"Fallback\neligible?"}
+    D -->|Yes| E["Model B"]
+    D -->|No| F["Return error"]
+    E -->|"2xx Success"| C
+    E -->|"429/401/500"| G{"Fallback\neligible?"}
+    G -->|Yes| H["Model C"]
+    G -->|No| F
+    H -->|"2xx Success"| C
+    H -->|"Fail"| I["All failed →\nReturn last status"]
+```
+
+---
+
+### 4.5 Traducteur (`open-sse/translator/`)
+
+Le **moteur de traduction de format** utilisant un système de plugin d'auto-enregistrement.
+
+#### Architecture
+
+```mermaid
+graph TD
+    subgraph "Request Translation"
+        A["Claude → OpenAI"]
+        B["Gemini → OpenAI"]
+        C["Antigravity → OpenAI"]
+        D["OpenAI Responses → OpenAI"]
+        E["OpenAI → Claude"]
+        F["OpenAI → Gemini"]
+        G["OpenAI → Kiro"]
+        H["OpenAI → Cursor"]
+    end
+
+    subgraph "Response Translation"
+        I["Claude → OpenAI"]
+        J["Gemini → OpenAI"]
+        K["Kiro → OpenAI"]
+        L["Cursor → OpenAI"]
+        M["OpenAI → Claude"]
+        N["OpenAI → Antigravity"]
+        O["OpenAI → Responses"]
+    end
+```
+
+| Annuaire     | Fichiers      | Descriptif                                                                                                                                                                                                                                                                                   |
+| ------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request/`   | 8 traducteurs | Convertissez les corps de requête entre les formats. Chaque fichier s'auto-enregistre via `register(from, to, fn)` lors de l'importation.                                                                                                                                                    |
+| `response/`  | 7 traducteurs | Convertissez les morceaux de réponse en streaming entre les formats. Gère les types d’événements SSE, les blocs de réflexion et les appels d’outils.                                                                                                                                         |
+| `helpers/`   | 6 aides       | Utilitaires partagés : `claudeHelper` (extraction d'invite système, configuration de réflexion), `geminiHelper` (mapping parties/contenu), `openaiHelper` (filtrage de format), `toolCallHelper` (génération d'ID, injection de réponse manquante), `maxTokensHelper`, `responsesApiHelper`. |
+| `index.ts`   | —             | Moteur de traduction : `translateRequest()`, `translateResponse()`, gestion des états, registre.                                                                                                                                                                                             |
+| `formats.ts` | —             | Constantes de format : `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`.                                                                                                                                                                                    |
+
+#### Conception des clés : plugins à enregistrement automatique
+
+```javascript
+// Each translator file calls register() on import:
+import { register } from "../index.js";
+register("claude", "openai", translateClaudeToOpenAI);
+
+// The index.js imports all translator files, triggering registration:
+import "./request/claude-to-openai.js"; // ← self-registers
+```
+
+---
+
+### 4.6 Utilitaires (`open-sse/utils/`)
+
+| Fichier            | Objectif                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `error.ts`         | Création de réponses aux erreurs (format compatible OpenAI), analyse des erreurs en amont, extraction du temps de nouvelle tentative Antigravity à partir des messages d'erreur, streaming d'erreurs SSE.                                                                                                                                                   |
+| `stream.ts`        | **SSE Transform Stream** : le pipeline de streaming principal. Deux modes : `TRANSLATE` (traduction plein format) et `PASSTHROUGH` (normaliser + extraire l'utilisation). Gère la mise en mémoire tampon des blocs, l'estimation de l'utilisation et le suivi de la longueur du contenu. Les instances d'encodeur/décodeur par flux évitent l'état partagé. |
+| `streamHelpers.ts` | Utilitaires SSE de bas niveau : `parseSSELine` (tolérant les espaces), `hasValuableContent` (filtre les morceaux vides pour OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (sérialisation SSE sensible au format avec nettoyage `perf_metrics`).                                                                                                        |
+| `usageTracking.ts` | Extraction de l'utilisation des jetons à partir de n'importe quel format (Claude/OpenAI/Gemini/Responses), estimation avec des ratios outil/message séparés par jeton, ajout de tampon (marge de sécurité de 2000 jetons), filtrage de champs spécifiques au format, journalisation de la console avec couleurs ANSI.                                       |
+| `requestLogger.ts` | Journalisation des demandes basées sur des fichiers (opt-in via `ENABLE_REQUEST_LOGS=true`). Crée des dossiers de session avec des fichiers numérotés : `1_req_client.json` → `7_res_client.txt`. Toutes les E/S sont asynchrones (tirer et oublier). Masque les en-têtes sensibles.                                                                        |
+| `bypassHandler.ts` | Intercepte les modèles spécifiques de Claude CLI (extraction de titre, échauffement, décompte) et renvoie de fausses réponses sans appeler aucun fournisseur. Prend en charge le streaming et le non-streaming. Intentionnellement limité à la portée Claude CLI.                                                                                           |
+| `networkProxy.ts`  | Résout l'URL du proxy sortant pour un fournisseur donné avec la priorité : configuration spécifique au fournisseur → configuration globale → variables d'environnement (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Prend en charge les exclusions `NO_PROXY`. Met en cache la configuration pendant 30 s.                                                     |
+
+#### Pipeline de diffusion SSE
+
+```mermaid
+flowchart TD
+    A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"]
+    B --> C["Buffer lines\n(split on newline)"]
+    C --> D["parseSSELine()\n(trim whitespace, parse JSON)"]
+    D --> E{"Mode?"}
+    E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"]
+    E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"]
+    F --> H["hasValuableContent()\nfilter empty chunks"]
+    G --> H
+    H -->|"Has content"| I["extractUsage()\ntrack token counts"]
+    H -->|"Empty"| J["Skip chunk"]
+    I --> K["formatSSE()\nserialize + clean perf_metrics"]
+    K --> L["TextEncoder\n(per-stream instance)"]
+    L --> M["Enqueue to\nclient stream"]
+
+    style A fill:#f9f,stroke:#333
+    style M fill:#9f9,stroke:#333
+```
+
+#### Structure de la session de l'enregistreur de requêtes
+
+```
+logs/
+└── claude_gemini_claude-sonnet_20260208_143045/
+    ├── 1_req_client.json      ← Raw client request
+    ├── 2_req_source.json      ← After initial conversion
+    ├── 3_req_openai.json      ← OpenAI intermediate format
+    ├── 4_req_target.json      ← Final target format
+    ├── 5_res_provider.txt     ← Provider SSE chunks (streaming)
+    ├── 5_res_provider.json    ← Provider response (non-streaming)
+    ├── 6_res_openai.txt       ← OpenAI intermediate chunks
+    ├── 7_res_client.txt       ← Client-facing SSE chunks
+    └── 6_error.json           ← Error details (if any)
+```
+
+---
+
+### 4.7 Couche d'application (`src/`)
+
+| Annuaire      | Objectif                                                                                              |
+| ------------- | ----------------------------------------------------------------------------------------------------- |
+| `src/app/`    | Interface utilisateur Web, routes API, middleware express, gestionnaires de rappel OAuth              |
+| `src/lib/`    | Accès à la base de données (`localDb.ts`, `usageDb.ts`), authentification, partagé                    |
+| `src/mitm/`   | Utilitaires proxy Man-in-the-middle pour intercepter le trafic des fournisseurs                       |
+| `src/models/` | Définitions du modèle de base de données                                                              |
+| `src/shared/` | Wrappers autour des fonctions open-sse (fournisseur, flux, erreur, etc.)                              |
+| `src/sse/`    | Gestionnaires de points de terminaison SSE qui connectent la bibliothèque open-sse aux routes Express |
+| `src/store/`  | Gestion de l'état des applications                                                                    |
+
+#### Routes API notables
+
+| Itinéraire                                    | Méthodes                 | Objectif                                                                                                |
+| --------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `/api/provider-models`                        | OBTENIR/POST/DELETE      | CRUD pour les modèles personnalisés par fournisseur                                                     |
+| `/api/models/catalog`                         | OBTENIR                  | Catalogue agrégé de tous les modèles (chat, intégration, image, personnalisé) regroupés par fournisseur |
+| `/api/settings/proxy`                         | OBTENIR/METTRE/SUPPRIMER | Configuration du proxy sortant hiérarchique (`global/providers/combos/keys`)                            |
+| `/api/settings/proxy/test`                    | POSTER                   | Valide la connectivité proxy et renvoie l'adresse IP/latence publique                                   |
+| `/v1/providers/[provider]/chat/completions`   | POSTER                   | Compléments de chat dédiés par fournisseur avec validation du modèle                                    |
+| `/v1/providers/[provider]/embeddings`         | POSTER                   | Intégrations dédiées par fournisseur avec validation du modèle                                          |
+| `/v1/providers/[provider]/images/generations` | POSTER                   | Génération d'images dédiée par fournisseur avec validation du modèle                                    |
+| `/api/settings/ip-filter`                     | OBTENIR/METTRE           | Gestion des listes autorisées/bloquées IP                                                               |
+| `/api/settings/thinking-budget`               | OBTENIR/METTRE           | Configuration du budget du jeton de raisonnement (passthrough/auto/custom/adaptatif)                    |
+| `/api/settings/system-prompt`                 | OBTENIR/METTRE           | Injection rapide du système global pour toutes les demandes                                             |
+| `/api/sessions`                               | OBTENIR                  | Suivi et métriques des sessions actives                                                                 |
+| `/api/rate-limits`                            | OBTENIR                  | Statut de limite de débit par compte                                                                    |
+
+---
+
+## 5. Modèles de conception clés
+
+### 5.1 Traduction en étoile
+
+Tous les formats sont traduits via le **format OpenAI comme hub**. L'ajout d'un nouveau fournisseur ne nécessite que l'écriture d'**une paire** de traducteurs (vers/depuis OpenAI), et non de N paires.
+
+### 5.2 Modèle de stratégie de l'exécuteur
+
+Chaque fournisseur dispose d'une classe d'exécuteur dédiée héritant de `BaseExecutor`. L'usine dans `executors/index.ts` sélectionne la bonne au moment de l'exécution.
+
+### 5.3 Système de plugin d'auto-enregistrement
+
+Les modules de traduction s'enregistrent eux-mêmes lors de l'importation via `register()`. Ajouter un nouveau traducteur consiste simplement à créer un fichier et à l'importer.
+
+### 5.4 Repli de compte avec intervalle exponentiel
+
+Lorsqu'un fournisseur renvoie 429/401/500, le système peut passer au compte suivant, en appliquant des temps de recharge exponentiels (1s → 2s → 4s → max 2min).
+
+### 5.5 Chaînes de modèles combinés
+
+Un "combo" regroupe plusieurs chaînes `provider/model`. Si le premier échoue, revenez automatiquement au suivant.
+
+### 5.6 Traduction en continu avec état
+
+La traduction des réponses maintient l'état dans les morceaux SSE (suivi des blocs de réflexion, accumulation d'appels d'outils, indexation des blocs de contenu) via le mécanisme `initState()`.
+
+### 5.7 Tampon de sécurité d'utilisation
+
+Un tampon de 2 000 jetons est ajouté à l'utilisation signalée pour empêcher les clients d'atteindre les limites de la fenêtre contextuelle en raison de la surcharge des invites système et de la traduction du format.
+
+---
+
+## 6. Formats pris en charge
+
+| Formater                   | Itinéraire       | Identifiant        |
+| -------------------------- | ---------------- | ------------------ |
+| Achèvements du chat OpenAI | source + cible   | `openai`           |
+| API de réponses OpenAI     | source + cible   | `openai-responses` |
+| Claude Anthropique         | source + cible   | `claude`           |
+| Google Gémeaux             | source + cible   | `gemini`           |
+| CLI Google Gemini          | cible uniquement | `gemini-cli`       |
+| Antigravité                | source + cible   | `antigravity`      |
+| AWSKiro                    | cible uniquement | `kiro`             |
+| Curseur                    | cible uniquement | `cursor`           |
+
+---
+
+## 7. Fournisseurs pris en charge
+
+| Fournisseur              | Méthode d'authentification               | Exécuteur testamentaire | Notes clés                                                                |
+| ------------------------ | ---------------------------------------- | ----------------------- | ------------------------------------------------------------------------- |
+| Claude Anthropique       | Clé API ou OAuth                         | Par défaut              | Utilise l'en-tête `x-api-key`                                             |
+| Google Gémeaux           | Clé API ou OAuth                         | Par défaut              | Utilise l'en-tête `x-goog-api-key`                                        |
+| CLI Google Gemini        | OAuth                                    | GémeauxCLI              | Utilise le point de terminaison `streamGenerateContent`                   |
+| Antigravité              | OAuth                                    | Antigravité             | Solution de secours multi-URL, nouvelle tentative d'analyse personnalisée |
+| OpenAI                   | Clé API                                  | Par défaut              | Authentification du porte-étendard                                        |
+| Codex                    | OAuth                                    | Codex                   | Injecte les instructions système, gère la réflexion                       |
+| Copilote GitHub          | OAuth + jeton Copilot                    | GitHub                  | Double jeton, en-tête VSCode imitant                                      |
+| Kiro (AWS)               | AWS SSO OIDC ou Social                   | Kiro                    | Analyse binaire d'EventStream                                             |
+| Curseur IDE              | Authentification de la somme de contrôle | Curseur                 | Encodage Protobuf, sommes de contrôle SHA-256                             |
+| Qwen                     | OAuth                                    | Par défaut              | Authentification standard                                                 |
+| iFlow                    | OAuth (Basique + Porteur)                | Par défaut              | En-tête à double authentification                                         |
+| OuvrirRouter             | Clé API                                  | Par défaut              | Authentification du porte-étendard                                        |
+| GLM, Kimi, MiniMax       | Clé API                                  | Par défaut              | Compatible Claude, utilisez `x-api-key`                                   |
+| `openai-compatible-*`    | Clé API                                  | Par défaut              | Dynamique : tout point de terminaison compatible OpenAI                   |
+| `anthropic-compatible-*` | Clé API                                  | Par défaut              | Dynamique : tout point de terminaison compatible Claude                   |
+
+---
+
+## 8. Résumé du flux de données
+
+### Demande de diffusion en continu
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor\nbuildUrl + buildHeaders"]
+    D --> E["fetch(providerURL)"]
+    E --> F["createSSEStream()\nTRANSLATE mode"]
+    F --> G["parseSSELine()"]
+    G --> H["translateResponse()\ntarget → OpenAI → source"]
+    H --> I["extractUsage()\n+ addBuffer"]
+    I --> J["formatSSE()"]
+    J --> K["Client receives\ntranslated SSE"]
+    K --> L["logUsage()\nsaveRequestUsage()"]
+```
+
+### Demande sans streaming
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor.execute()"]
+    D --> E["translateResponse()\ntarget → OpenAI → source"]
+    E --> F["Return JSON\nresponse"]
+```
+
+### Flux de contournement (Claude CLI)
+
+```mermaid
+flowchart LR
+    A["Claude CLI request"] --> B{"Match bypass\npattern?"}
+    B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"]
+    B -->|"No match"| D["Normal flow"]
+    C --> E["Translate to\nsource format"]
+    E --> F["Return without\ncalling provider"]
+```

docs/i18n/fr/FEATURES.md

@@ -0,0 +1,77 @@
+# OmniRoute — Galerie des fonctionnalités du tableau de bord
+
+🌐 **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)
+
+Guide visuel de chaque section du tableau de bord OmniRoute.
+
+---
+
+## 🔌 Fournisseurs
+
+Gérez les connexions des fournisseurs d'IA : fournisseurs OAuth (Claude Code, Codex, Gemini CLI), fournisseurs de clés API (Groq, DeepSeek, OpenRouter) et fournisseurs gratuits (iFlow, Qwen, Kiro).
+
+![Providers Dashboard](screenshots/01-providers.png)
+
+---
+
+## 🎨Combinaisons
+
+Créez des combinaisons de routage de modèles avec 6 stratégies : remplissage en premier, round-robin, puissance de deux choix, aléatoire, moins utilisé et coût optimisé. Chaque combo enchaîne plusieurs modèles avec un repli automatique.
+
+![Combos Dashboard](screenshots/02-combos.png)
+
+---
+
+## 📊 Analyses
+
+Analyses d'utilisation complètes avec consommation de jetons, estimations de coûts, cartes thermiques d'activité, graphiques de distribution hebdomadaire et répartitions par fournisseur.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
+
+---
+
+## 🏥 Santé du système
+
+Surveillance en temps réel : disponibilité, mémoire, version, centiles de latence (p50/p95/p99), statistiques du cache et états des disjoncteurs du fournisseur.
+
+![Health Dashboard](screenshots/04-health.png)
+
+---
+
+## 🔧 Terrain de jeu des traducteurs
+
+Quatre modes de débogage des traductions d'API : **Playground** (convertisseur de format), **Chat Tester** (requêtes en direct), **Test Bench** (tests par lots) et **Live Monitor** (flux en temps réel).
+
+![Translator Playground](screenshots/05-translator.png)
+
+---
+
+## ⚙️ Paramètres
+
+Paramètres généraux, stockage système, gestion des sauvegardes (base de données d'exportation/importation), apparence (mode sombre/clair), sécurité (inclut la protection des points de terminaison API et le blocage des fournisseurs personnalisés), le routage, la résilience et la configuration avancée.
+
+![Settings Dashboard](screenshots/06-settings.png)
+
+---
+
+## 🔧 Outils CLI
+
+Configuration en un clic pour les outils de codage d'IA : Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code et Antigravity.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+
+---
+
+## 📝 Demander des journaux
+
+Journalisation des demandes en temps réel avec filtrage par fournisseur, modèle, compte et clé API. Affiche les codes d'état, l'utilisation des jetons, la latence et les détails de la réponse.
+
+![Usage Logs](screenshots/08-usage.png)
+
+---
+
+## 🌐 Point de terminaison de l'API
+
+Votre point de terminaison d'API unifié avec répartition des capacités : achèvements de chat, intégrations, génération d'images, reclassement, transcription audio et clés API enregistrées.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)