feat(release): v1.8.0 — empty tool_use.name validation, Windows electron fix

fix: Windows electron release — collect portable exe by pattern

.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/implement-features.md

@@ -0,0 +1,131 @@
+---
+description: Analyze open feature request issues, implement viable ones on dedicated branches, and respond to authors
+---
+
+# /implement-features — Feature Request Implementation Workflow
+
+## Overview
+
+Fetches open feature request issues, analyzes each against the current codebase, implements viable ones on dedicated branches, and responds to authors with results. Does NOT merge to main — leaves branches for author validation.
+
+## Steps
+
+### 1. Identify the Repository
+
+// turbo
+
+- Run: `git -C <project_root> remote get-url origin` to extract owner/repo
+
+### 2. Fetch Open Feature Request Issues
+
+// turbo
+
+- Run: `gh issue list --repo <owner>/<repo> --state open --limit 50 --json number,title,labels,body,comments,createdAt,author`
+- Filter for issues that are feature requests (label `enhancement`/`feature`, or body describes new functionality, or previously classified as feature request)
+- Sort by oldest first
+
+### 3. Analyze Each Feature Request
+
+For each feature request issue, perform a **two-level analysis**:
+
+#### Level 1 — Viability Assessment
+
+Ask yourself:
+
+- Does this feature align with the project's goals and architecture?
+- Is the request technically feasible with the current codebase?
+- Does it duplicate existing functionality?
+- Would it introduce breaking changes or security risks?
+- Is there enough detail to implement it?
+
+**Verdict options:**
+
+1. ✅ **VIABLE** — Makes sense, enough detail to implement → Go to Level 2
+2. ❓ **NEEDS MORE INFO** — Good idea but insufficient detail → Post comment asking for specifics
+3. ❌ **NOT VIABLE** — Doesn't fit the project or is fundamentally flawed → Post comment explaining why, close issue
+
+#### Level 2 — Implementation (only for VIABLE features)
+
+1. **Research** — Read all related source files to understand the current architecture
+2. **Design** — Plan the implementation, filling gaps in the original request
+3. **Create branch** — Name format: `feat/issue-<NUMBER>-<short-slug>`
+   ```bash
+   git checkout main
+   git pull origin main
+   git checkout -b feat/issue-<NUMBER>-<short-slug>
+   ```
+4. **Implement** — Build the complete solution following project patterns
+5. **Build** — Run `npm run build` to verify compilation
+6. **Commit** — Commit with: `feat: <description> (#<NUMBER>)`
+7. **Push** — Push the branch: `git push -u origin feat/issue-<NUMBER>-<short-slug>`
+8. **Return to main** — `git checkout main`
+
+### 4. Respond to Authors
+
+#### For VIABLE (implemented) features:
+
+// turbo
+Post a comment on the issue:
+
+````markdown
+## ✅ Feature Implemented!
+
+Hi @<author>! We've analyzed your request and implemented it on a dedicated branch.
+
+**Branch:** `feat/issue-<NUMBER>-<short-slug>`
+
+### What was implemented:
+
+- <bullet list of what was done>
+
+### How to try it:
+
+```bash
+git fetch origin
+git checkout feat/issue-<NUMBER>-<short-slug>
+npm install && npm run dev
+```
+````
+
+### Next steps:
+
+1. **Test it** — Please verify it works as you expected
+2. **Want to improve it?** — You're welcome to contribute! Just:
+   ```bash
+   git checkout feat/issue-<NUMBER>-<short-slug>
+   # Make your improvements
+   git add -A && git commit -m "improve: <your changes>"
+   git push origin feat/issue-<NUMBER>-<short-slug>
+   ```
+   Then open a Pull Request from your branch to `main` 🎉
+3. **Not quite right?** — Let us know in this issue what needs to change
+
+Looking forward to your feedback! 🚀
+
+```
+
+#### For NEEDS MORE INFO:
+// turbo
+Post a comment asking for specific missing details needed to implement, e.g.:
+- "Could you describe the exact behavior when X happens?"
+- "Which API endpoints should be affected?"
+- "Should this apply to all providers or only specific ones?"
+
+Add the context of WHY you need each piece of information.
+
+#### For NOT VIABLE:
+// turbo
+Post a polite comment explaining why the feature doesn't fit at this time:
+- If the idea is decent but timing is wrong: "This is an interesting idea, but it doesn't align with our current priorities. Feel free to open a new issue with more details if you'd like us to reconsider."
+- If fundamentally flawed: Explain the technical or architectural reasons why it won't work, suggest alternatives if possible.
+- Close the issue after posting the comment.
+
+### 5. Summary Report
+Present a summary report to the user via `notify_user`:
+
+| Issue | Title | Verdict | Branch / Action |
+|---|---|---|---|
+| #N | Title | ✅ Implemented | `feat/issue-N-slug` |
+| #N | Title | ❓ Needs Info | Comment posted |
+| #N | Title | ❌ Not Viable | Closed with explanation |
+```

.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

@@ -0,0 +1,120 @@
+---
+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, 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
+
+### 1. Identify the GitHub Repository
+
+// turbo
+
+- Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
+- Parse the owner and repo name from the URL
+
+### 2. Fetch All Open Issues
+
+// turbo
+
+- Run: `gh issue list --repo <owner>/<repo> --state open --limit 100 --json number,title,labels,body,comments,createdAt,author`
+- Parse the JSON output to get a list of all open issues
+- Sort by oldest first (FIFO)
+
+### 3. Classify Each Issue
+
+For each issue, determine its type:
+
+- **Bug** — Has `bug` label, or body contains error messages, stack traces, "doesn't work", "broken", "crash", "error"
+- **Feature Request** — Has `enhancement`/`feature` label, or body describes new functionality
+- **Question** — Has `question` label, or is asking "how to" something
+- **Other** — Anything else
+
+Focus ONLY on **Bugs** for resolution. Feature requests and questions should be skipped with a note in the final report.
+
+### 4. Analyze Each Bug — For each bug issue:
+
+#### 4a. Check Information Sufficiency
+
+Verify the issue contains enough information to reproduce and fix:
+
+- [ ] Clear description of the problem
+- [ ] Steps to reproduce
+- [ ] Error messages or logs
+- [ ] Expected vs actual behavior
+
+#### 4b. If Information Is INSUFFICIENT
+
+Call the `/issue-triage` workflow (located at `~/.gemini/antigravity/global_workflows/issue-triage.md`):
+// turbo
+
+- Post a comment asking for more details using `gh issue comment`
+- Add `needs-info` label using `gh issue edit`
+- Mark this issue as **DEFERRED** and move to the next one
+
+#### 4c. If Information Is SUFFICIENT
+
+Proceed with resolution:
+
+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. Generate Report & Wait for Validation
+
+Present a summary report to the user via `notify_user` with `BlockedOnUser: true`:
+
+| 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   |
+
+> **⚠️ 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.
+
+- 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
+
+### 6. Commit & Push Fix Branch (only after user approval)
+
+After the user validates:
+
+- 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`
+
+### 7. 🛑 WAIT — Notify User & Await PR Verification
+
+**This is a mandatory stop point.** Use `notify_user` with `BlockedOnUser: true`:
+
+- 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**
+
+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

@@ -0,0 +1,145 @@
+---
+description: Analyze open Pull Requests from the project's GitHub repository, generate a critical report, and optionally implement approved changes
+---
+
+# /review-prs — PR Review & Analysis Workflow
+
+## 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. **All improvements are committed on top of the PR branch** and the user must verify before merge.
+
+## Steps
+
+### 1. Identify the GitHub Repository
+
+- Read `package.json` to get the repository URL, or use the git remote origin URL
+  // turbo
+- Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
+
+### 2. Fetch Open Pull Requests
+
+- Navigate to `https://github.com/<owner>/<repo>/pulls` and scrape all open PRs
+- For each open PR, collect:
+  - PR number, title, author, branch, number of commits, date
+  - PR description/body
+  - Files changed (diff)
+  - Existing review comments (from bots or humans)
+
+### 3. Analyze Each PR — For each open PR, perform the following analysis:
+
+#### 3a. Feature Assessment
+
+- **Does it make sense?** Evaluate if the feature fills a real gap or solves a valid problem
+- **Alignment** — Check if it aligns with the project's architecture and roadmap
+- **Complexity** — Assess if the scope is reasonable or if it should be split
+
+#### 3b. Code Quality Review
+
+- Check for code duplication
+- Evaluate error handling patterns (consistent with existing codebase?)
+- Check naming conventions and code style
+- Verify TypeScript types (any `any` usage, missing types?)
+
+#### 3c. Security Review
+
+- Check for missing authentication/authorization on new endpoints
+- Check for injection vulnerabilities (URL params, SQL, XSS)
+- Verify input validation on all user-controlled data
+- Check for hardcoded secrets or credentials
+
+#### 3d. Architecture Review
+
+- Does the change follow existing patterns?
+- Are there any breaking changes to public APIs?
+- Is the database schema affected? Migration needed?
+- Impact on performance (N+1 queries, missing indexes?)
+
+#### 3e. Test Coverage
+
+- Does the PR include tests?
+- 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
+- **Improvements/Benefits** — Numbered list with impact level (HIGH/MEDIUM/LOW)
+- **Risks & Issues** — Categorized as CRITICAL / IMPORTANT / MINOR
+- **Scoring Table** — Rate across: Feature Relevance, Code Quality, Security, Robustness, Tests
+- **Verdict** — Ready to merge? With mandatory vs optional fixes
+- **Next Steps** — What will happen if approved
+
+### 5. Present to User
+
+- Show the report via `notify_user` with `BlockedOnUser: true`
+- Wait for user decision:
+  - **Approved** → Proceed to step 6
+  - **Approved with changes** → Implement the fixes and corrections before merging
+  - **Rejected** → Close the PR or leave a review comment
+
+### 6. Implementation (if approved)
+
+- 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
+- Push the updated branch: `git push origin <branch-name>`
+
+### 7. 🛑 WAIT — Notify User & Await PR Verification
+
+**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/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

@@ -0,0 +1,38 @@
+name: Deploy to VPS
+
+on:
+  workflow_run:
+    workflows: ["Publish to Docker Hub"]
+    types: [completed]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    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: Deploy via SSH
+        uses: appleboy/ssh-action@v1
+        with:
+          host: ${{ secrets.VPS_HOST }}
+          username: ${{ secrets.VPS_USER }}
+          key: ${{ secrets.VPS_SSH_KEY }}
+          port: 22
+          timeout: 30s
+          script: |
+            echo "=== Updating OmniRoute ==="
+            npm install -g omniroute@latest 2>&1
+            INSTALLED_VERSION=$(omniroute --version 2>/dev/null || echo "unknown")
+            echo "Installed version: $INSTALLED_VERSION"
+
+            echo "=== Restarting PM2 ==="
+            pm2 restart omniroute || pm2 start omniroute --name omniroute -- --port 20128
+            pm2 save
+
+            echo "=== Health Check ==="
+            sleep 3
+            curl -sf http://localhost:20128/api/settings > /dev/null && echo "✅ OmniRoute is healthy" || echo "❌ Health check failed"
+            echo "=== Deploy complete ==="

.github/workflows/docker-publish.yml

@@ -8,9 +8,65 @@ permissions:
   contents: read
 
 jobs:
-  docker:
-    name: Build & Push Docker Image
+  build:
+    name: Build (${{ matrix.platform }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            platform_pair: linux-amd64
+            runner: ubuntu-latest
+          - platform: linux/arm64
+            platform_pair: linux-arm64
+            runner: ubuntu-24.04-arm
+    env:
+      IMAGE_NAME: diegosouzapw/omniroute
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          target: runner-base
+          platforms: ${{ matrix.platform }}
+          outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=omniroute-runner-base-${{ matrix.platform_pair }}
+          cache-to: type=gha,mode=max,scope=omniroute-runner-base-${{ matrix.platform_pair }}
+
+      - name: Export digest
+        run: |
+          mkdir -p "${{ runner.temp }}/digests"
+          digest="${{ steps.build.outputs.digest }}"
+          touch "${{ runner.temp }}/digests/${digest#sha256:}"
+
+      - name: Upload digest
+        uses: actions/upload-artifact@v7
+        with:
+          name: digests-${{ matrix.platform_pair }}
+          path: ${{ runner.temp }}/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  merge:
+    name: Merge manifest and publish tags
     runs-on: ubuntu-latest
+    needs: build
+    env:
+      IMAGE_NAME: diegosouzapw/omniroute
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -23,8 +79,12 @@ jobs:
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
           echo "Publishing Docker image version: $VERSION"
 
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+      - name: Download digests
+        uses: actions/download-artifact@v8
+        with:
+          path: ${{ runner.temp }}/digests
+          pattern: digests-*
+          merge-multiple: true
 
       - name: Login to Docker Hub
         uses: docker/login-action@v3
@@ -32,18 +92,20 @@ jobs:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      - name: Build and push
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          target: runner-base
-          push: true
-          tags: |
-            diegosouzapw/omniroute:${{ steps.version.outputs.version }}
-            diegosouzapw/omniroute:latest
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-          platforms: linux/amd64
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Create manifest list and push
+        working-directory: ${{ runner.temp }}/digests
+        run: |
+          docker buildx imagetools create \
+            -t "${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }}" \
+            -t "${{ env.IMAGE_NAME }}:latest" \
+            $(printf '${{ env.IMAGE_NAME }}@sha256:%s ' *)
+
+      - name: Inspect image
+        run: |
+          docker buildx imagetools inspect "${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }}"
 
       - name: Update Docker Hub description
         uses: peter-evans/dockerhub-description@v5

.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
@@ -74,6 +74,8 @@ docs/*
 !docs/VM_DEPLOYMENT_GUIDE.md
 !docs/FEATURES.md
 !docs/screenshots/
+!docs/i18n/
+!docs/i18n/**
 
 # open-sse tests
 open-sse/test/*
@@ -95,3 +97,19 @@ security-analysis/
 # Deploy workflow (contains sensitive VPS credentials)
 .agent/workflows/deploy.md
 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/

CHANGELOG.md

@@ -7,6 +7,648 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [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
+>
+> Color-coded proxy badges, provider-level proxy configuration, CLI tools page fix, and EACCES fix for restricted environments.
+
+### ✨ New Features
+
+- **Color-Coded Proxy Badges** — Each provider connection now shows its proxy status with color-coded badges: 🟢 green (global proxy), 🟡 amber (provider-level proxy), 🔵 blue (per-connection proxy). Badge always displays the proxy IP/host
+- **Provider-Level Proxy Button** — New "Provider Proxy" button in the Connections header of each provider detail page. Allows configuring a proxy that applies to all connections of that provider
+- **Proxy IP Display** — The proxy badge now always shows the proxy host/IP address for quick identification
+
+### 🐛 Bug Fixes
+
+- **CLI Tools Page Stuck in Loading** — Fixed the `/api/cli-tools/status` endpoint hanging indefinitely when binary checks stall on VPS. Added 5s server-side timeout per tool and 8s client-side AbortController timeout (#cli-tools-hang)
+- **EACCES on Restricted Home Directories** — Fixed crash when `~/.omniroute` directory cannot be created due to permission issues. Now gracefully warns and suggests using the `DATA_DIR` environment variable (#133)
+
+---
+
+> ### 🌐 Full Internationalization (i18n) + Multi-Account Fix
+>
+> Complete dashboard i18n migration with next-intl, supporting English and Portuguese (Brazil). Fixes production build issues and enables multiple Codex accounts from the same workspace.
+
+### ✨ New Features
+
+- **Full Dashboard Internationalization** — Complete i18n migration of 21+ pages and components using `next-intl`. Every dashboard string is now translatable with full EN and PT-BR support. Includes language selector (globe icon) in the header for real-time language switching
+- **Portuguese (Brazil) Translation** — Complete `pt-BR.json` translation file with 500+ keys covering all pages: Home, Providers, Settings, Combos, Analytics, Costs, Logs, Health, CLI Tools, Endpoint, API Manager, and Onboarding
+- **Language Selector Component** — New `LanguageSelector` component in the header with flag icons and dropdown for switching between 🇺🇸 English and 🇧🇷 Português
+
+### 🐛 Bug Fixes
+
+- **Multiple Codex Accounts from Same Workspace** — Fixed deduplication logic in `createProviderConnection` that prevented adding multiple OpenAI Pro Business accounts from the same Team workspace. Now uses compound check (workspaceId + email) instead of workspaceId-only, allowing separate connections per user
+- **Production Build — Crypto Import** — Fixed `instrumentation.ts` using `eval('require')('crypto')` to bypass webpack's static analysis that blocked the Node.js crypto module in the bundled instrumentation file
+- **Production Build — Translation Scope** — Fixed sub-components `ProviderOverviewCard` and `ProviderModelsModal` in `HomePageClient.tsx` that referenced parent-scope translation hooks. Each sub-component now has its own `useTranslations()` call
+- **Production Build — app/ Directory Conflict** — Resolved Next.js 16 confusing the production `app/` directory (server build output) with the `src/app/` app router directory, which caused "missing root layout" build failures
+
+### 📄 i18n Pages Migrated
+
+Home, Endpoint, API Manager, Providers (list + detail + new), Combos, Logs, Costs, Analytics, Health, CLI Tools, Settings (General, Security, Routing, Session, IP Filter, Compliance, Fallback Chains, Thinking Budget, Policies, Pricing, Resilience, Advanced), Onboarding Wizard, Audit Log, Usage
+
+---
+
+## [1.4.7] — 2026-02-25
+
+> ### 🐛 Bugfix — Antigravity Model Prefix & Version Sync
+>
+> Fixes model name sent to Antigravity upstream API containing `antigravity/` prefix, causing 400 errors for non-opus models. Also syncs package-lock.json version.
+
+### 🐛 Bug Fixes
+
+- **Antigravity Model Prefix Stripping** — Model names sent to the Antigravity upstream API (Google Cloud Code) now have any `provider/` prefix defensively stripped. Previously, models like `antigravity/gemini-3-flash` were sent with the prefix intact, causing 400 errors from the upstream API. Only `claude-opus-4-6-thinking` worked because its routing path differed. Fix applied in 3 locations: `antigravity.ts` executor, and both `wrapInCloudCodeEnvelope` and `wrapInCloudCodeEnvelopeForClaude` in the translator
+- **Package-lock.json Version Sync** — Fixed `package-lock.json` being stuck at `1.4.3` while `package.json` was at `1.4.6`, which prevented npm from publishing the correct version and caused the VPS deploy to stay on the old version
+
+---
+
+## [1.4.6] — 2026-02-25
+
+> ### ✨ Community Release — Security Fix, Multi-Platform Docker, Model Updates & Plus Tier
+>
+> Enforces API key model restrictions across all endpoints, adds ARM64 Docker support, updates model registry for latest AI models, and introduces Plus tier in ProviderLimits.
+
+### 🔒 Security
+
+- **API Key Model Restrictions Enforced** — `isModelAllowedForKey()` was never called, allowing API keys with `allowedModels` restrictions to access any model. Created centralized `enforceApiKeyPolicy()` middleware and wired it into all `/v1/*` endpoints (chat, embeddings, images, audio, moderations, rerank). Supports exact match, prefix match (`openai/*`), and wildcard patterns ([#130](https://github.com/diegosouzapw/OmniRoute/issues/130), [PR #131](https://github.com/diegosouzapw/OmniRoute/pull/131) by [@ersintarhan](https://github.com/ersintarhan))
+- **ApiKeyMetadata Type Safety** — Replaced `any` types with proper `ApiKeyMetadata` interface in the policy middleware. Added error logging in catch blocks for metadata fetch and budget check failures
+
+### ✨ New Features
+
+- **Docker Multi-Platform Builds** — Restructured Docker CI workflow to support both `linux/amd64` and `linux/arm64` using native runners and digest-based manifest merging. ARM64 users (Apple Silicon, AWS Graviton, Raspberry Pi) can now run OmniRoute natively ([PR #127](https://github.com/diegosouzapw/OmniRoute/pull/127) by [@npmSteven](https://github.com/npmSteven))
+- **Plus Tier in ProviderLimits** — Added "Plus" as a separate category in the ProviderLimits dashboard, distinguishing Plus/Paid plans from Pro plans with proper ranking and filtering ([PR #126](https://github.com/diegosouzapw/OmniRoute/pull/126) by [@nyatoru](https://github.com/nyatoru))
+
+### 🔧 Improvements
+
+- **Model Registry Updates** — Updated provider registry, usage tracking, CLI tools config, and pricing for latest AI models: added Claude Sonnet 4.6, Gemini 3.1 Pro (High/Low), GPT OSS 120B Medium; removed deprecated Claude 4.5 variants and Gemini 2.5 Flash ([PR #128](https://github.com/diegosouzapw/OmniRoute/pull/128) by [@nyatoru](https://github.com/nyatoru))
+- **Model ID Consistency** — Fixed `claude-sonnet-4-6-thinking` → `claude-sonnet-4-6` mismatch in `importantModels` to match the provider registry
+
+---
+
+## [1.4.5] — 2026-02-24
+
+> ### 🐛 Bugfix Release — Claude Code OAuth & OAuth Proxy Routing
+>
+> Fixes Claude Code OAuth failures on remote deployments and routes all OAuth token exchanges through configured proxy.
+
+### 🐛 Bug Fixes
+
+- **Claude Code OAuth** — Fixed `400 Bad Request` on remote deployments by using Anthropic's registered `redirect_uri` (`https://platform.claude.com/oauth/code/callback`) instead of the dynamic server URL. Added missing OAuth scopes (`user:sessions:claude_code`, `user:mcp_servers`) to match the official Claude CLI. Configurable via `CLAUDE_CODE_REDIRECT_URI` env var ([#124](https://github.com/diegosouzapw/OmniRoute/issues/124))
+- **OAuth Token Exchange Through Proxy** — OAuth token exchange during new connection setup now routes through the configured proxy (provider-level → global → direct), fixing `unsupported_country_region_territory` errors for region-restricted providers like OpenAI Codex ([#119](https://github.com/diegosouzapw/OmniRoute/issues/119))
+
+---
+
+## [1.4.4] — 2026-02-24
+
+> ### ✨ Feature Release — Custom Provider Models in /v1/models
+>
+> Compatible provider models are now saved to the customModels database, making them visible via `/v1/models` for all OpenAI-compatible clients.
+
+### ✨ New Features
+
+- **Custom Provider Model Persistence** — Compatible provider models (manual or imported) are now saved to the `customModels` database so they appear in `/v1/models` listing for clients like Cursor, Cline, Antigravity, and Claude Code ([PR #122](https://github.com/diegosouzapw/OmniRoute/pull/122) by [@nyatoru](https://github.com/nyatoru))
+- **Provider Models API** — New `/api/provider-models` endpoint (GET/POST/DELETE) for managing custom model entries with full authentication via `isAuthenticated`
+- **Unified Model Deletion** — New `handleDeleteModel` removes models from both alias configuration and `customModels` database, preventing orphaned entries
+- **Provider Node Prefix Resolution** — `getModelInfo` refactored to use provider node prefixes for accurate custom provider model resolution
+
+### 🔒 Security
+
+- **Authentication on Provider Models API** — All `/api/provider-models` endpoints require API key or JWT session authentication via shared `isAuthenticated` utility
+- **URL Parameter Injection Fix** — Applied `encodeURIComponent` to all user-controlled URL parameters (`providerStorageAlias`, `providerId`) to prevent query string injection attacks
+- **Shared Auth Utility** — Authentication logic extracted to `@/shared/utils/apiAuth.ts`, eliminating code duplication across `/api/models/alias` and `/api/provider-models`
+
+### 🔧 Improvements
+
+- **Toast Notifications** — Replaced blocking `alert()` calls with non-blocking `notify.error`/`notify.success` toast notifications matching the project's notification system
+- **Transactional Save** — Model persistence is now transactional: database save must succeed before alias creation, preventing inconsistent state
+- **Consistent Error Handling** — All model operations (add, import, delete) now provide user-facing error/success feedback via toast notifications
+- **ComboFormModal Matching** — Improved provider node matching by ID or prefix for combo model selection
+
+---
+
+## [1.4.3] — 2026-02-23
+
+### 🐛 Bug Fix
+
+- **OAuth LAN Access** — Fixed OAuth flow for remote/LAN IP access (`192.168.x.x`). Previously, LAN IPs incorrectly used popup mode, leading to a broken redirect loop. Now defaults to manual callback URL input mode for non-localhost access
+
+---
+
+## [1.4.2] — 2026-02-23
+
+### 🐛 Bug Fix
+
+- **OAuth Token Refresh** — Fixed `client_secret is missing` error for Google-based OAuth providers (Antigravity, Gemini, Gemini CLI, iFlow). Desktop/CLI OAuth secrets are now hardcoded as defaults since Next.js inlined empty strings at build time.
+
+---
+
+## [1.4.1] — 2026-02-23
+
+### 🔧 Improvements
+
+- **Endpoint Page Cleanup** — Removed redundant API Key Management section from Endpoint page (now fully managed in the dedicated API Manager page)
+- **CI/CD** — Added `deploy-vps.yml` workflow for automatic VPS deployment on new releases
+
+---
+
+## [1.4.0] — 2026-02-23
+
+> ### ✨ Feature Release — Dedicated API Key Manager with Model Permissions
+>
+> Community-contributed API Key Manager page with model-level access control, enhanced with usage statistics, key status indicators, and improved UX.
+
+### ✨ New Features
+
+- **Dedicated API Key Manager** — New `/dashboard/api-manager` page for managing API keys, extracted from the Endpoint page. Includes create, delete, and permissions management with a clean table UI ([PR #118](https://github.com/diegosouzapw/OmniRoute/pull/118) by [@nyatoru](https://github.com/nyatoru))
+- **Model-Level API Key Permissions** — Restrict API keys to specific models using `allowed_models` with wildcard pattern support (e.g., `openai/*`). Toggle between "Allow All" and "Restrict" modes with an intuitive provider-grouped model selector
+- **API Key Validation Cache** — 3-tier caching layer (validation, metadata, permission) reduces database hits on every request, with automatic cache invalidation on key changes
+- **Usage Statistics Per Key** — Each API key shows total request count and last used timestamp, with a stats summary dashboard (total keys, restricted keys, total requests, models available)
+- **Key Status Indicators** — Color-coded lock/unlock icons and copy buttons on each key row for quick identification of restricted vs unrestricted keys
+
+### 🔧 Improvements
+
+- **Endpoint Page Simplified** — API key management removed from Endpoint page and replaced with a prominent link to the API Manager
+- **Sidebar Navigation** — New "API Manager" entry with `vpn_key` icon in the sidebar
+- **Prepared Statements** — API key database operations now use cached prepared statements for better performance
+- **Input Validation** — XSS-safe sanitization and regex validation for key names; ID format validation for API calls
+
+---
+
+## [1.3.1] — 2026-02-23
+
+> ### 🐛 Bugfix Release — Proxy Connection Tests & Compatible Provider Display
+>
+> Fixes provider connection tests bypassing configured proxy and improves compatible provider display in the request logger.
+
+### 🐛 Bug Fixes
+
+- **Connection Tests Now Use Proxy** — Provider connection tests (`Test Connection` button) now route through the configured proxy (key → combo → provider → global → direct), matching the behavior of real API calls. Previously, `fetch()` was called directly, bypassing the proxy entirely ([#119](https://github.com/diegosouzapw/OmniRoute/issues/119))
+- **Compatible Provider Display in Logs** — OpenAI/Anthropic compatible providers now show friendly labels (`OAI-COMPAT`, `ANT-COMPAT`) instead of raw UUID-based IDs in the request logger's provider column, dropdown, and quick filters ([#113](https://github.com/diegosouzapw/OmniRoute/issues/113))
+
+### 🧪 Tests
+
+- **Connection Test Unit Tests** — 26 new test cases covering error classification logic, token expiry detection, and provider display label resolution
+
+---
+
+## [1.3.0] — 2026-02-23
+
+> ### ✨ Feature Release — iFlow Fix, Health Check Logs Toggle, Kilocode Models & Model Deduplication
+>
+> Community-driven release with iFlow HMAC-SHA256 signature support, health check log management, expanded Kilocode model list, and model deduplication on the dashboard.
+
+### ✨ New Features
+
+- **Hide Health Check Logs** — New toggle in Settings → Appearance to suppress verbose `[HealthCheck]` messages from the server console. Uses a 30-second cache to minimize database reads with request coalescing for concurrent calls ([PR #111](https://github.com/diegosouzapw/OmniRoute/pull/111) by [@nyatoru](https://github.com/nyatoru))
+- **Kilocode Custom Models Endpoint** — Added `modelsUrl` support in `RegistryEntry` for providers with non-standard model endpoints. Expanded Kilocode model list from 8 to 26 models including Qwen3, GPT-5, Claude 3 Haiku, Gemini 2.5, DeepSeek V3, Llama 4, and more ([PR #115](https://github.com/diegosouzapw/OmniRoute/pull/115) by [@benzntech](https://github.com/benzntech))
+
+### 🐛 Bug Fixes
+
+- **iFlow 406 Error** — Created dedicated `IFlowExecutor` with HMAC-SHA256 signature support (`session-id`, `x-iflow-timestamp`, `x-iflow-signature` headers). The iFlow provider was previously using the default executor which lacked the required signature headers, causing 406 errors ([#114](https://github.com/diegosouzapw/OmniRoute/issues/114))
+- **Duplicate Models in Endpoint Lists** — Filtered out parent models (`!m.parent`) from all model categorization and count logic on the Endpoint page. Provider modal lists also exclude duplicates ([PR #112](https://github.com/diegosouzapw/OmniRoute/pull/112) by [@nyatoru](https://github.com/nyatoru))
+
+### 🧪 Tests
+
+- **IFlowExecutor Unit Tests** — 11 new test cases covering HMAC-SHA256 signature generation, header building, URL construction, body passthrough, and executor registry integration
+
+---
+
+## [1.2.0] — 2026-02-22
+
+> ### ✨ Feature Release — Dashboard Session Auth for Models Endpoint
+>
+> Dashboard users can now access `/v1/models` via their existing session when API key auth is required.
+
+### ✨ New Features
+
+- **JWT Session Auth Fallback** — When `requireAuthForModels` is enabled, the `/v1/models` endpoint now accepts both API key (Bearer token) for external clients **and** the dashboard JWT session cookie (`auth_token`), allowing logged-in dashboard users to view models without needing an explicit API key ([PR #110](https://github.com/diegosouzapw/OmniRoute/pull/110) by [@nyatoru](https://github.com/nyatoru))
+
+### 🔧 Improvements
+
+- **401 instead of 404** — Authentication failures on `/v1/models` now return `401 Unauthorized` with a structured JSON error body (OpenAI-compatible format) instead of a generic `404 Not Found`, improving debuggability for API clients
+- **Simplified auth logic** — Refactored the JWT cookie verification to reuse the same pattern as `apiAuth.ts`, removing redundant same-origin detection (~60 lines) since the `sameSite:lax` + `httpOnly` cookie flags already provide equivalent CSRF protection
+
+---
+
+## [1.1.1] — 2026-02-22
+
+> ### 🐛 Bugfix Release — API Key Creation & Codex Team Plan Quotas
+>
+> Fixes API key creation crash when `API_KEY_SECRET` is not set and adds Code Review rate limit window to Codex quota display.
+
+### 🐛 Bug Fixes
+
+- **API Key Creation** — Added deterministic fallback for `API_KEY_SECRET` to prevent `crypto.createHmac` crash when the environment variable is not configured. Keys created without the secret are insecure (warned at startup) but the application no longer crashes ([#108](https://github.com/diegosouzapw/OmniRoute/issues/108))
+- **Codex Code Review Quota** — Added parsing of the third rate limit window (`code_review_rate_limit`) from the ChatGPT usage API, supporting Plus/Pro/Team plan differences. The dashboard now displays all three quota bars: Session (5h), Weekly, and Code Review ([#106](https://github.com/diegosouzapw/OmniRoute/issues/106))
+
+---
+
+## [1.1.0] — 2026-02-21
+
+> ### 🐛 Bugfix Release — OAuth Client Secret and Codex Business Quotas
+>
+> Fixes missing remote-server OAuth configurations and adds ChatGPT Business account quota monitoring.
+
+### 🐛 Bug Fixes
+
+- **OAuth Client Secret** — Omitted explicitly empty `client_secret` parameters to resolve token exchange connection rejection on remote servers missing environment variables for Antigravity, Gemini and iFlow ([#103](https://github.com/diegosouzapw/OmniRoute/issues/103))
+- **Codex Business Quotas** — Automatically fetches the appropriate ChatGPT workspace to unlock the 5-hour Business usage limits directly inside the Quota tab and mapped `BIZ` string variant perfectly ([#101](https://github.com/diegosouzapw/OmniRoute/issues/101))
+
+---
+
 ## [1.0.10] — 2026-02-21
 
 > ### 🐛 Bugfix — Multi-Account Support for Qwen
@@ -244,7 +886,7 @@ New environment variables:
 
 ---
 
-## [1.1.0] — 2026-02-18
+## [1.0.1] — 2026-02-18
 
 > ### 🔧 API Compatibility & SDK Hardening
 >
@@ -424,11 +1066,33 @@ 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
+[1.4.4]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.4.4
+[1.4.3]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.4.3
+[1.4.2]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.4.2
+[1.4.1]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.4.1
+[1.4.0]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.4.0
+[1.3.1]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.3.1
+[1.3.0]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.3.0
+[1.2.0]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.2.0
+[1.1.1]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.1.1
 [1.0.7]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.0.7
 [1.0.6]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.0.6
 [1.0.5]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.0.5
 [1.0.4]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.0.4
 [1.1.0]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.1.0
+[1.0.1]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.0.1
 [1.0.3]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.0.3
 [1.0.2]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.0.2
 [1.0.0]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v1.0.0

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.de.md

@@ -104,7 +104,7 @@ _Verbinde jedes KI-gesteuerte IDE- oder CLI-Tool über OmniRoute — kostenloses
 
 [🌐 Website](https://omniroute.online) • [🚀 Schnellstart](#-schnellstart) • [💡 Funktionen](#-hauptfunktionen) • [📖 Doku](#-dokumentation) • [💰 Preise](#-preisübersicht)
 
-🌐 **Verfügbar 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)
+🌐 **Verfügbar 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>
 
@@ -157,6 +157,263 @@ Ergebnis: Nie aufhören zu programmieren, minimale Kosten
 
 ---
 
+## 🎯 What OmniRoute Solves — 16 Real Pain Points
+
+> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to zero observability.
+
+<details>
+<summary><b>💸 1. "I pay for an expensive subscription but still get interrupted by limits"</b></summary>
+
+Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.
+
+**How OmniRoute solves it:**
+
+- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention
+- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly)
+- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next
+- **Custom Combos** — Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized)
+- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
+
+</details>
+
+<details>
+<summary><b>🔌 2. "I need to use multiple providers but each has a different API"</b></summary>
+
+OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.
+
+**How OmniRoute solves it:**
+
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 36+ providers
+- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
+- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+
+- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE
+- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`
+- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion
+- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs
+
+</details>
+
+<details>
+<summary><b>🌐 3. "My AI provider blocks my region/country"</b></summary>
+
+Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.
+
+**How OmniRoute solves it:**
+
+- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key
+- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP
+- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`
+- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)
+- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing
+- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection
+
+</details>
+
+<details>
+<summary><b>🆓 4. "I want to use AI for coding but I have no money"</b></summary>
+
+Not everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.
+
+**How OmniRoute solves it:**
+
+- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (8 unlimited models), Qwen (3 unlimited models), Kiro (Claude for free), Gemini CLI (180K/month free)
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime
+- **NVIDIA NIM Free Credits** — 1000 free credits integrated
+- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider
+
+</details>
+
+<details>
+<summary><b>🔒 5. "I need to protect my AI gateway from unauthorized access"</b></summary>
+
+When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.
+
+**How OmniRoute solves it:**
+
+- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page
+- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle
+- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing
+- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens
+- **Rate Limiter** — Per-IP rate limiting with configurable windows
+- **IP Filtering** — Allowlist/blocklist for access control
+- **Prompt Injection Guard** — Sanitization against malicious prompt patterns
+- **AES-256-GCM Encryption** — Credentials encrypted at rest
+
+</details>
+
+<details>
+<summary><b>🛑 6. "My provider went down and I lost my coding flow"</b></summary>
+
+AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.
+
+**How OmniRoute solves it:**
+
+- **Circuit Breaker per-provider** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open)
+- **Exponential Backoff** — Progressive retry delays
+- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms
+- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention
+- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain
+- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
+
+</details>
+
+<details>
+<summary><b>🔧 7. "Configuring each AI tool is tedious and repetitive"</b></summary>
+
+Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.
+
+**How OmniRoute solves it:**
+
+- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
+- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection
+- **Onboarding Wizard** — Guided 4-step setup for first-time users
+- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 36+ providers
+
+</details>
+
+<details>
+<summary><b>🔑 8. "Managing OAuth tokens from multiple providers is hell"</b></summary>
+
+Claude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.
+
+**How OmniRoute solves it:**
+
+- **Auto Token Refresh** — OAuth tokens refresh in background before expiration
+- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow
+- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction
+- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers
+- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility
+- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker
+
+</details>
+
+<details>
+<summary><b>📊 9. "I don't know how much I'm spending or where"</b></summary>
+
+Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.
+
+**How OmniRoute solves it:**
+
+- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider
+- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback
+- **Per-Model Pricing Configuration** — Configurable prices per model
+- **Usage Statistics Per API Key** — Request count and last-used timestamp per key
+- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency
+
+</details>
+
+<details>
+<summary><b>🐛 10. "I can't diagnose errors and problems in AI calls"</b></summary>
+
+When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.
+
+**How OmniRoute solves it:**
+
+- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console
+- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter
+- **SQLite Proxy Logs** — Persistent logs that survive server restarts
+- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)
+- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing
+- **File-Based Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation
+
+</details>
+
+<details>
+<summary><b>🏗️ 11. "Deploying and maintaining the gateway is complex"</b></summary>
+
+Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.
+
+**How OmniRoute solves it:**
+
+- **npm global install** — `npm install -g omniroute && omniroute` — done
+- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)
+- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)
+- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode
+- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)
+- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers
+- **DB Backups** — Automatic backup, restore, export and import of all settings
+
+</details>
+
+<details>
+<summary><b>🌍 12. "The interface is English-only and my team doesn't speak English"</b></summary>
+
+Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.
+
+**How OmniRoute solves it:**
+
+- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English
+- **RTL Support** — Right-to-left support for Arabic and Hebrew
+- **Multi-Language READMEs** — 30 complete documentation translations
+- **Language Selector** — Globe icon in header for real-time switching
+
+</details>
+
+<details>
+<summary><b>🔄 13. "I need more than chat — I need embeddings, images, audio"</b></summary>
+
+AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.
+
+**How OmniRoute solves it:**
+
+- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models
+- **Image Generation** — `/v1/images/generations` with 4 providers and 9+ models
+- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper-compatible
+- **Text-to-Speech** — `/v1/audio/speech` — Multi-provider audio synthesis
+- **Moderations** — `/v1/moderations` — Content safety checks
+- **Reranking** — `/v1/rerank` — Document relevance reranking
+- **Responses API** — Full `/v1/responses` support for Codex
+
+</details>
+
+<details>
+<summary><b>🧪 14. "I have no way to test and compare quality across models"</b></summary>
+
+Developers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.
+
+**How OmniRoute solves it:**
+
+- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal
+- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)
+- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison
+- **Chat Tester** — Full round-trip with visual response rendering
+- **Live Monitor** — Real-time stream of all requests flowing through the proxy
+
+</details>
+
+<details>
+<summary><b>📈 15. "I need to scale without losing performance"</b></summary>
+
+As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.
+
+**How OmniRoute solves it:**
+
+- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency
+- **Request Idempotency** — 5s deduplication window for identical requests
+- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking
+- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence
+- **API Key Validation Cache** — 3-tier cache for production performance
+- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
+
+</details>
+
+<details>
+<summary><b>🤖 16. "I want to control model behavior globally"</b></summary>
+
+Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.
+
+**How OmniRoute solves it:**
+
+- **System Prompt Injection** — Global prompt applied to all requests
+- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)
+- **6 Routing Strategies** — Global strategies that determine how requests are distributed
+- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
+- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Provider Toggle** — Enable/disable all connections for a provider with one click
+- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
+
+</details>
+
 ## ⚡ Schnellstart
 
 **1. Global installieren:**
@@ -247,6 +504,30 @@ docker compose --profile cli up -d
 
 ---
 
+---
+
+## 🖥️ Desktop-App — Offline & Immer Aktiv
+
+> 🆕 **NEU!** OmniRoute ist jetzt als **native Desktop-Anwendung** für Windows, macOS und Linux verfügbar.
+
+- 🖥️ **Natives Fenster** — Dediziertes App-Fenster mit System-Tray-Integration
+- 🔄 **Autostart** — OmniRoute beim Systemstart starten
+- 🔔 **Native Benachrichtigungen** — Warnungen bei Kontingent-Erschöpfung
+- ⚡ **Ein-Klick-Installation** — NSIS (Windows), DMG (macOS), AppImage (Linux)
+- 🌐 **Offline-Modus** — Funktioniert vollständig offline mit integriertem Server
+
+```bash
+npm run electron:dev           # Entwicklungsmodus
+npm run electron:build         # Aktuelle Plattform
+npm run electron:build:win     # Windows (.exe)
+npm run electron:build:mac     # macOS (.dmg)
+npm run electron:build:linux   # Linux (.AppImage)
+```
+
+📖 Vollständige Dokumentation: [`electron/README.md`](electron/README.md)
+
+---
+
 ## 💰 Preisübersicht
 
 | Tier             | Anbieter          | Kosten                       | Kontingent-Reset    | Am besten für           |
@@ -272,67 +553,6 @@ docker compose --profile cli up -d
 
 ---
 
-## 🎯 Anwendungsfälle
-
-### Fall 1: „Ich habe ein Claude Pro Abo"
-
-**Problem:** Kontingent verfällt ungenutzt, Rate-Limits während intensivem Programmieren
-
-```
-Combo: "maximize-claude"
-  1. cc/claude-opus-4-6        (Abo voll ausnutzen)
-  2. glm/glm-4.7               (günstiges Backup bei erschöpftem Kontingent)
-  3. if/kimi-k2-thinking       (kostenloser Notfall-Fallback)
-
-Monatliche Kosten: $20 (Abo) + ~$5 (Backup) = $25 gesamt
-vs. $20 + an Limits stoßen = Frustration
-```
-
-### Fall 2: „Ich will null Kosten"
-
-**Problem:** Kann sich Abos nicht leisten, braucht zuverlässige KI zum Programmieren
-
-```
-Combo: "free-forever"
-  1. gc/gemini-3-flash         (180K gratis/Monat)
-  2. if/kimi-k2-thinking       (unbegrenzt gratis)
-  3. qw/qwen3-coder-plus       (unbegrenzt gratis)
-
-Monatliche Kosten: $0
-Qualität: Produktionsreife Modelle
-```
-
-### Fall 3: „Ich muss 24/7 programmieren, ohne Unterbrechungen"
-
-**Problem:** Enge Deadlines, kann sich keine Ausfallzeit leisten
-
-```
-Combo: "always-on"
-  1. cc/claude-opus-4-6        (beste Qualität)
-  2. cx/gpt-5.2-codex          (zweites Abo)
-  3. glm/glm-4.7               (günstig, täglicher Reset)
-  4. minimax/MiniMax-M2.1      (günstigste, 5h Reset)
-  5. if/kimi-k2-thinking       (unbegrenzt kostenlos)
-
-Ergebnis: 5 Fallback-Ebenen = null Ausfallzeit
-```
-
-### Fall 4: „Ich will KOSTENLOSE KI in OpenClaw"
-
-**Problem:** Braucht KI-Assistenz in Messaging-Apps, komplett kostenlos
-
-```
-Combo: "openclaw-free"
-  1. if/glm-4.7                (unbegrenzt kostenlos)
-  2. if/minimax-m2.1           (unbegrenzt kostenlos)
-  3. if/kimi-k2-thinking       (unbegrenzt kostenlos)
-
-Monatliche Kosten: $0
-Zugang über: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-```
-
----
-
 ## 💡 Hauptfunktionen
 
 ### 🧠 Routing & Intelligenz
@@ -348,6 +568,8 @@ Zugang über: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 | 🧩 **Benutzerdefinierte Modelle**    | Jede Modell-ID zu jedem Anbieter hinzufügen                                    |
 | 🌐 **Wildcard-Router**               | `provider/*` Muster dynamisch an jeden Anbieter routen                         |
 | 🧠 **Reasoning-Budget**              | Passthrough, auto, custom und adaptive Modi für Reasoning-Modelle              |
+| 🔀 **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 Injection**       | Globaler System Prompt für alle Anfragen                                       |
 | 📄 **API Responses**                 | Volle Unterstützung der OpenAI Responses API (`/v1/responses`) für Codex       |
 
@@ -364,15 +586,17 @@ Zugang über: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 
 ### 🛡️ Resilienz & Sicherheit
 
-| Funktion                        | Was es macht                                                         |
-| ------------------------------- | -------------------------------------------------------------------- |
-| 🔌 **Circuit Breaker**          | Auto-Öffnung/-Schließung pro Anbieter mit konfigurierbaren Schwellen |
-| 🛡️ **Anti-Thundering Herd**     | Mutex + Semaphor Rate-Limit für API-Key-Anbieter                     |
-| 🧠 **Semantischer Cache**       | Zwei-Ebenen-Cache (Signatur + Semantik) senkt Kosten und Latenz      |
-| ⚡ **Anfrage-Idempotenz**       | 5s Dedup-Fenster für doppelte Anfragen                               |
-| 🔒 **TLS-Fingerprint-Spoofing** | Bot-Erkennung umgehen via wreq-js                                    |
-| 🌐 **IP-Filterung**             | Allowlist/Blocklist für API-Zugriffskontrolle                        |
-| 📊 **Editierbare Rate-Limits**  | Konfigurierbare RPM, minimaler Abstand, max. Konkurrenz              |
+| Funktion                        | Was es macht                                                                 |
+| ------------------------------- | ---------------------------------------------------------------------------- |
+| 🔌 **Circuit Breaker**          | Auto-Öffnung/-Schließung pro Anbieter mit konfigurierbaren Schwellen         |
+| 🛡️ **Anti-Thundering Herd**     | Mutex + Semaphor Rate-Limit für API-Key-Anbieter                             |
+| 🧠 **Semantischer Cache**       | Zwei-Ebenen-Cache (Signatur + Semantik) senkt Kosten und Latenz              |
+| ⚡ **Anfrage-Idempotenz**       | 5s Dedup-Fenster für doppelte Anfragen                                       |
+| 🔒 **TLS-Fingerprint-Spoofing** | Bot-Erkennung umgehen via wreq-js                                            |
+| 🌐 **IP-Filterung**             | Allowlist/Blocklist für API-Zugriffskontrolle                                |
+| 📊 **Editierbare Rate-Limits**  | Konfigurierbare RPM, minimaler Abstand, max. Konkurrenz                      |
+| 💾 **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       |
 
 ### 📊 Observability & Analytics
 
@@ -474,6 +698,67 @@ Nahtlose Übersetzung zwischen Formaten:
 
 ---
 
+## 🎯 Anwendungsfälle
+
+### Fall 1: „Ich habe ein Claude Pro Abo"
+
+**Problem:** Kontingent verfällt ungenutzt, Rate-Limits während intensivem Programmieren
+
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6        (Abo voll ausnutzen)
+  2. glm/glm-4.7               (günstiges Backup bei erschöpftem Kontingent)
+  3. if/kimi-k2-thinking       (kostenloser Notfall-Fallback)
+
+Monatliche Kosten: $20 (Abo) + ~$5 (Backup) = $25 gesamt
+vs. $20 + an Limits stoßen = Frustration
+```
+
+### Fall 2: „Ich will null Kosten"
+
+**Problem:** Kann sich Abos nicht leisten, braucht zuverlässige KI zum Programmieren
+
+```
+Combo: "free-forever"
+  1. gc/gemini-3-flash         (180K gratis/Monat)
+  2. if/kimi-k2-thinking       (unbegrenzt gratis)
+  3. qw/qwen3-coder-plus       (unbegrenzt gratis)
+
+Monatliche Kosten: $0
+Qualität: Produktionsreife Modelle
+```
+
+### Fall 3: „Ich muss 24/7 programmieren, ohne Unterbrechungen"
+
+**Problem:** Enge Deadlines, kann sich keine Ausfallzeit leisten
+
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-6        (beste Qualität)
+  2. cx/gpt-5.2-codex          (zweites Abo)
+  3. glm/glm-4.7               (günstig, täglicher Reset)
+  4. minimax/MiniMax-M2.1      (günstigste, 5h Reset)
+  5. if/kimi-k2-thinking       (unbegrenzt kostenlos)
+
+Ergebnis: 5 Fallback-Ebenen = null Ausfallzeit
+```
+
+### Fall 4: „Ich will KOSTENLOSE KI in OpenClaw"
+
+**Problem:** Braucht KI-Assistenz in Messaging-Apps, komplett kostenlos
+
+```
+Combo: "openclaw-free"
+  1. if/glm-4.7                (unbegrenzt kostenlos)
+  2. if/minimax-m2.1           (unbegrenzt kostenlos)
+  3. if/kimi-k2-thinking       (unbegrenzt kostenlos)
+
+Monatliche Kosten: $0
+Zugang über: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+```
+
+---
+
 ## 📖 Einrichtungsanleitung
 
 <details>
@@ -754,74 +1039,6 @@ Einstellungen → API-Konfiguration:
 
 ---
 
-## 📊 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`
-
-**NVIDIA NIM (`nvidia/`)** - KOSTENLOSE Credits:
-
-- `nvidia/llama-3.3-70b-instruct`
-- `nvidia/mistral-7b-instruct`
-- 50+ weitere Modelle auf [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/`)** - KOSTENLOS:
-
-- `if/kimi-k2-thinking`
-- `if/qwen3-coder-plus`
-- `if/deepseek-r1`
-- `if/glm-4.7`
-- `if/minimax-m2`
-
-**Qwen (`qw/`)** - KOSTENLOS:
-
-- `qw/qwen3-coder-plus`
-- `qw/qwen3-coder-flash`
-
-**Kiro (`kr/`)** - KOSTENLOS:
-
-- `kr/claude-sonnet-4.5`
-- `kr/claude-haiku-4.5`
-
-**OpenRouter (`or/`)** - 100+ Modelle:
-
-- `or/anthropic/claude-4-sonnet`
-- `or/google/gemini-2.5-pro`
-- Jedes Modell von [openrouter.ai/models](https://openrouter.ai/models)
-
-</details>
-
----
-
 ## 🧪 Evaluierungen (Evals)
 
 OmniRoute enthält ein integriertes Evaluierungs-Framework zum Testen der LLM-Antwortqualität gegen ein Golden Set. Zugang über **Analytics → Evals** im Dashboard.

README.es.md

@@ -104,7 +104,7 @@ _Conecta cualquier IDE o herramienta CLI con IA a través de OmniRoute — gatew
 
 [🌐 Website](https://omniroute.online) • [🚀 Inicio Rápido](#-inicio-rápido) • [💡 Características](#-características-principales) • [📖 Docs](#-documentación) • [💰 Precios](#-precios-resumidos)
 
-🌐 **Disponible en:** [English](README.md) | [Português](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>
 
@@ -157,6 +157,263 @@ Resultado: Nunca dejes de programar, costo mínimo
 
 ---
 
+## 🎯 What OmniRoute Solves — 16 Real Pain Points
+
+> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to zero observability.
+
+<details>
+<summary><b>💸 1. "I pay for an expensive subscription but still get interrupted by limits"</b></summary>
+
+Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.
+
+**How OmniRoute solves it:**
+
+- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention
+- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly)
+- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next
+- **Custom Combos** — Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized)
+- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
+
+</details>
+
+<details>
+<summary><b>🔌 2. "I need to use multiple providers but each has a different API"</b></summary>
+
+OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.
+
+**How OmniRoute solves it:**
+
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 36+ providers
+- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
+- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+
+- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE
+- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`
+- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion
+- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs
+
+</details>
+
+<details>
+<summary><b>🌐 3. "My AI provider blocks my region/country"</b></summary>
+
+Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.
+
+**How OmniRoute solves it:**
+
+- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key
+- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP
+- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`
+- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)
+- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing
+- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection
+
+</details>
+
+<details>
+<summary><b>🆓 4. "I want to use AI for coding but I have no money"</b></summary>
+
+Not everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.
+
+**How OmniRoute solves it:**
+
+- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (8 unlimited models), Qwen (3 unlimited models), Kiro (Claude for free), Gemini CLI (180K/month free)
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime
+- **NVIDIA NIM Free Credits** — 1000 free credits integrated
+- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider
+
+</details>
+
+<details>
+<summary><b>🔒 5. "I need to protect my AI gateway from unauthorized access"</b></summary>
+
+When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.
+
+**How OmniRoute solves it:**
+
+- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page
+- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle
+- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing
+- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens
+- **Rate Limiter** — Per-IP rate limiting with configurable windows
+- **IP Filtering** — Allowlist/blocklist for access control
+- **Prompt Injection Guard** — Sanitization against malicious prompt patterns
+- **AES-256-GCM Encryption** — Credentials encrypted at rest
+
+</details>
+
+<details>
+<summary><b>🛑 6. "My provider went down and I lost my coding flow"</b></summary>
+
+AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.
+
+**How OmniRoute solves it:**
+
+- **Circuit Breaker per-provider** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open)
+- **Exponential Backoff** — Progressive retry delays
+- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms
+- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention
+- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain
+- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
+
+</details>
+
+<details>
+<summary><b>🔧 7. "Configuring each AI tool is tedious and repetitive"</b></summary>
+
+Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.
+
+**How OmniRoute solves it:**
+
+- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
+- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection
+- **Onboarding Wizard** — Guided 4-step setup for first-time users
+- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 36+ providers
+
+</details>
+
+<details>
+<summary><b>🔑 8. "Managing OAuth tokens from multiple providers is hell"</b></summary>
+
+Claude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.
+
+**How OmniRoute solves it:**
+
+- **Auto Token Refresh** — OAuth tokens refresh in background before expiration
+- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow
+- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction
+- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers
+- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility
+- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker
+
+</details>
+
+<details>
+<summary><b>📊 9. "I don't know how much I'm spending or where"</b></summary>
+
+Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.
+
+**How OmniRoute solves it:**
+
+- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider
+- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback
+- **Per-Model Pricing Configuration** — Configurable prices per model
+- **Usage Statistics Per API Key** — Request count and last-used timestamp per key
+- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency
+
+</details>
+
+<details>
+<summary><b>🐛 10. "I can't diagnose errors and problems in AI calls"</b></summary>
+
+When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.
+
+**How OmniRoute solves it:**
+
+- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console
+- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter
+- **SQLite Proxy Logs** — Persistent logs that survive server restarts
+- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)
+- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing
+- **File-Based Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation
+
+</details>
+
+<details>
+<summary><b>🏗️ 11. "Deploying and maintaining the gateway is complex"</b></summary>
+
+Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.
+
+**How OmniRoute solves it:**
+
+- **npm global install** — `npm install -g omniroute && omniroute` — done
+- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)
+- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)
+- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode
+- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)
+- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers
+- **DB Backups** — Automatic backup, restore, export and import of all settings
+
+</details>
+
+<details>
+<summary><b>🌍 12. "The interface is English-only and my team doesn't speak English"</b></summary>
+
+Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.
+
+**How OmniRoute solves it:**
+
+- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English
+- **RTL Support** — Right-to-left support for Arabic and Hebrew
+- **Multi-Language READMEs** — 30 complete documentation translations
+- **Language Selector** — Globe icon in header for real-time switching
+
+</details>
+
+<details>
+<summary><b>🔄 13. "I need more than chat — I need embeddings, images, audio"</b></summary>
+
+AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.
+
+**How OmniRoute solves it:**
+
+- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models
+- **Image Generation** — `/v1/images/generations` with 4 providers and 9+ models
+- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper-compatible
+- **Text-to-Speech** — `/v1/audio/speech` — Multi-provider audio synthesis
+- **Moderations** — `/v1/moderations` — Content safety checks
+- **Reranking** — `/v1/rerank` — Document relevance reranking
+- **Responses API** — Full `/v1/responses` support for Codex
+
+</details>
+
+<details>
+<summary><b>🧪 14. "I have no way to test and compare quality across models"</b></summary>
+
+Developers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.
+
+**How OmniRoute solves it:**
+
+- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal
+- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)
+- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison
+- **Chat Tester** — Full round-trip with visual response rendering
+- **Live Monitor** — Real-time stream of all requests flowing through the proxy
+
+</details>
+
+<details>
+<summary><b>📈 15. "I need to scale without losing performance"</b></summary>
+
+As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.
+
+**How OmniRoute solves it:**
+
+- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency
+- **Request Idempotency** — 5s deduplication window for identical requests
+- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking
+- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence
+- **API Key Validation Cache** — 3-tier cache for production performance
+- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
+
+</details>
+
+<details>
+<summary><b>🤖 16. "I want to control model behavior globally"</b></summary>
+
+Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.
+
+**How OmniRoute solves it:**
+
+- **System Prompt Injection** — Global prompt applied to all requests
+- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)
+- **6 Routing Strategies** — Global strategies that determine how requests are distributed
+- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
+- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Provider Toggle** — Enable/disable all connections for a provider with one click
+- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
+
+</details>
+
 ## ⚡ Inicio Rápido
 
 **1. Instala globalmente:**
@@ -247,6 +504,34 @@ docker compose --profile cli up -d
 
 ---
 
+---
+
+## 🖥️ Aplicación de Escritorio — Sin Conexión y Siempre Activo
+
+> 🆕 **¡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 +557,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 +572,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 +590,17 @@ 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                |
+| 🛡️ **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
 
@@ -474,6 +702,67 @@ Traducción transparente entre formatos:
 
 ---
 
+## 🎯 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...
+```
+
+---
+
 ## 📖 Guía de Configuración
 
 <details>
@@ -754,74 +1043,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.

README.fr.md

@@ -104,7 +104,7 @@ _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>
 
@@ -157,6 +157,263 @@ Résultat : Ne jamais arrêter de coder, coût minimal
 
 ---
 
+## 🎯 What OmniRoute Solves — 16 Real Pain Points
+
+> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to zero observability.
+
+<details>
+<summary><b>💸 1. "I pay for an expensive subscription but still get interrupted by limits"</b></summary>
+
+Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.
+
+**How OmniRoute solves it:**
+
+- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention
+- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly)
+- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next
+- **Custom Combos** — Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized)
+- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
+
+</details>
+
+<details>
+<summary><b>🔌 2. "I need to use multiple providers but each has a different API"</b></summary>
+
+OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.
+
+**How OmniRoute solves it:**
+
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 36+ providers
+- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
+- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+
+- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE
+- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`
+- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion
+- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs
+
+</details>
+
+<details>
+<summary><b>🌐 3. "My AI provider blocks my region/country"</b></summary>
+
+Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.
+
+**How OmniRoute solves it:**
+
+- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key
+- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP
+- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`
+- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)
+- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing
+- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection
+
+</details>
+
+<details>
+<summary><b>🆓 4. "I want to use AI for coding but I have no money"</b></summary>
+
+Not everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.
+
+**How OmniRoute solves it:**
+
+- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (8 unlimited models), Qwen (3 unlimited models), Kiro (Claude for free), Gemini CLI (180K/month free)
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime
+- **NVIDIA NIM Free Credits** — 1000 free credits integrated
+- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider
+
+</details>
+
+<details>
+<summary><b>🔒 5. "I need to protect my AI gateway from unauthorized access"</b></summary>
+
+When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.
+
+**How OmniRoute solves it:**
+
+- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page
+- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle
+- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing
+- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens
+- **Rate Limiter** — Per-IP rate limiting with configurable windows
+- **IP Filtering** — Allowlist/blocklist for access control
+- **Prompt Injection Guard** — Sanitization against malicious prompt patterns
+- **AES-256-GCM Encryption** — Credentials encrypted at rest
+
+</details>
+
+<details>
+<summary><b>🛑 6. "My provider went down and I lost my coding flow"</b></summary>
+
+AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.
+
+**How OmniRoute solves it:**
+
+- **Circuit Breaker per-provider** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open)
+- **Exponential Backoff** — Progressive retry delays
+- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms
+- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention
+- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain
+- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
+
+</details>
+
+<details>
+<summary><b>🔧 7. "Configuring each AI tool is tedious and repetitive"</b></summary>
+
+Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.
+
+**How OmniRoute solves it:**
+
+- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
+- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection
+- **Onboarding Wizard** — Guided 4-step setup for first-time users
+- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 36+ providers
+
+</details>
+
+<details>
+<summary><b>🔑 8. "Managing OAuth tokens from multiple providers is hell"</b></summary>
+
+Claude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.
+
+**How OmniRoute solves it:**
+
+- **Auto Token Refresh** — OAuth tokens refresh in background before expiration
+- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow
+- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction
+- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers
+- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility
+- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker
+
+</details>
+
+<details>
+<summary><b>📊 9. "I don't know how much I'm spending or where"</b></summary>
+
+Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.
+
+**How OmniRoute solves it:**
+
+- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider
+- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback
+- **Per-Model Pricing Configuration** — Configurable prices per model
+- **Usage Statistics Per API Key** — Request count and last-used timestamp per key
+- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency
+
+</details>
+
+<details>
+<summary><b>🐛 10. "I can't diagnose errors and problems in AI calls"</b></summary>
+
+When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.
+
+**How OmniRoute solves it:**
+
+- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console
+- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter
+- **SQLite Proxy Logs** — Persistent logs that survive server restarts
+- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)
+- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing
+- **File-Based Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation
+
+</details>
+
+<details>
+<summary><b>🏗️ 11. "Deploying and maintaining the gateway is complex"</b></summary>
+
+Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.
+
+**How OmniRoute solves it:**
+
+- **npm global install** — `npm install -g omniroute && omniroute` — done
+- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)
+- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)
+- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode
+- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)
+- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers
+- **DB Backups** — Automatic backup, restore, export and import of all settings
+
+</details>
+
+<details>
+<summary><b>🌍 12. "The interface is English-only and my team doesn't speak English"</b></summary>
+
+Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.
+
+**How OmniRoute solves it:**
+
+- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English
+- **RTL Support** — Right-to-left support for Arabic and Hebrew
+- **Multi-Language READMEs** — 30 complete documentation translations
+- **Language Selector** — Globe icon in header for real-time switching
+
+</details>
+
+<details>
+<summary><b>🔄 13. "I need more than chat — I need embeddings, images, audio"</b></summary>
+
+AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.
+
+**How OmniRoute solves it:**
+
+- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models
+- **Image Generation** — `/v1/images/generations` with 4 providers and 9+ models
+- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper-compatible
+- **Text-to-Speech** — `/v1/audio/speech` — Multi-provider audio synthesis
+- **Moderations** — `/v1/moderations` — Content safety checks
+- **Reranking** — `/v1/rerank` — Document relevance reranking
+- **Responses API** — Full `/v1/responses` support for Codex
+
+</details>
+
+<details>
+<summary><b>🧪 14. "I have no way to test and compare quality across models"</b></summary>
+
+Developers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.
+
+**How OmniRoute solves it:**
+
+- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal
+- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)
+- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison
+- **Chat Tester** — Full round-trip with visual response rendering
+- **Live Monitor** — Real-time stream of all requests flowing through the proxy
+
+</details>
+
+<details>
+<summary><b>📈 15. "I need to scale without losing performance"</b></summary>
+
+As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.
+
+**How OmniRoute solves it:**
+
+- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency
+- **Request Idempotency** — 5s deduplication window for identical requests
+- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking
+- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence
+- **API Key Validation Cache** — 3-tier cache for production performance
+- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
+
+</details>
+
+<details>
+<summary><b>🤖 16. "I want to control model behavior globally"</b></summary>
+
+Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.
+
+**How OmniRoute solves it:**
+
+- **System Prompt Injection** — Global prompt applied to all requests
+- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)
+- **6 Routing Strategies** — Global strategies that determine how requests are distributed
+- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
+- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Provider Toggle** — Enable/disable all connections for a provider with one click
+- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
+
+</details>
+
 ## ⚡ Démarrage rapide
 
 **1. Installer globalement :**
@@ -247,6 +504,32 @@ docker compose --profile cli up -d
 
 ---
 
+---
+
+## 🖥️ Application Bureau — Hors Ligne et Toujours Actif
+
+> 🆕 **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 +555,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 +570,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 +588,17 @@ 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           |
+| 🛡️ **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
 
@@ -474,6 +700,67 @@ Traduction transparente entre les formats :
 
 ---
 
+## 🎯 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...
+```
+
+---
+
 ## 📖 Guide de configuration
 
 <details>
@@ -754,74 +1041,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.

README.it.md

@@ -104,7 +104,7 @@ _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>
 
@@ -157,6 +157,263 @@ Risultato: Non smettere mai di programmare, costo minimo
 
 ---
 
+## 🎯 What OmniRoute Solves — 16 Real Pain Points
+
+> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to zero observability.
+
+<details>
+<summary><b>💸 1. "I pay for an expensive subscription but still get interrupted by limits"</b></summary>
+
+Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.
+
+**How OmniRoute solves it:**
+
+- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention
+- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly)
+- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next
+- **Custom Combos** — Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized)
+- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
+
+</details>
+
+<details>
+<summary><b>🔌 2. "I need to use multiple providers but each has a different API"</b></summary>
+
+OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.
+
+**How OmniRoute solves it:**
+
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 36+ providers
+- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
+- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+
+- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE
+- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`
+- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion
+- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs
+
+</details>
+
+<details>
+<summary><b>🌐 3. "My AI provider blocks my region/country"</b></summary>
+
+Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.
+
+**How OmniRoute solves it:**
+
+- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key
+- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP
+- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`
+- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)
+- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing
+- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection
+
+</details>
+
+<details>
+<summary><b>🆓 4. "I want to use AI for coding but I have no money"</b></summary>
+
+Not everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.
+
+**How OmniRoute solves it:**
+
+- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (8 unlimited models), Qwen (3 unlimited models), Kiro (Claude for free), Gemini CLI (180K/month free)
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime
+- **NVIDIA NIM Free Credits** — 1000 free credits integrated
+- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider
+
+</details>
+
+<details>
+<summary><b>🔒 5. "I need to protect my AI gateway from unauthorized access"</b></summary>
+
+When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.
+
+**How OmniRoute solves it:**
+
+- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page
+- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle
+- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing
+- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens
+- **Rate Limiter** — Per-IP rate limiting with configurable windows
+- **IP Filtering** — Allowlist/blocklist for access control
+- **Prompt Injection Guard** — Sanitization against malicious prompt patterns
+- **AES-256-GCM Encryption** — Credentials encrypted at rest
+
+</details>
+
+<details>
+<summary><b>🛑 6. "My provider went down and I lost my coding flow"</b></summary>
+
+AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.
+
+**How OmniRoute solves it:**
+
+- **Circuit Breaker per-provider** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open)
+- **Exponential Backoff** — Progressive retry delays
+- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms
+- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention
+- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain
+- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
+
+</details>
+
+<details>
+<summary><b>🔧 7. "Configuring each AI tool is tedious and repetitive"</b></summary>
+
+Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.
+
+**How OmniRoute solves it:**
+
+- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
+- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection
+- **Onboarding Wizard** — Guided 4-step setup for first-time users
+- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 36+ providers
+
+</details>
+
+<details>
+<summary><b>🔑 8. "Managing OAuth tokens from multiple providers is hell"</b></summary>
+
+Claude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.
+
+**How OmniRoute solves it:**
+
+- **Auto Token Refresh** — OAuth tokens refresh in background before expiration
+- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow
+- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction
+- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers
+- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility
+- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker
+
+</details>
+
+<details>
+<summary><b>📊 9. "I don't know how much I'm spending or where"</b></summary>
+
+Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.
+
+**How OmniRoute solves it:**
+
+- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider
+- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback
+- **Per-Model Pricing Configuration** — Configurable prices per model
+- **Usage Statistics Per API Key** — Request count and last-used timestamp per key
+- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency
+
+</details>
+
+<details>
+<summary><b>🐛 10. "I can't diagnose errors and problems in AI calls"</b></summary>
+
+When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.
+
+**How OmniRoute solves it:**
+
+- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console
+- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter
+- **SQLite Proxy Logs** — Persistent logs that survive server restarts
+- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)
+- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing
+- **File-Based Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation
+
+</details>
+
+<details>
+<summary><b>🏗️ 11. "Deploying and maintaining the gateway is complex"</b></summary>
+
+Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.
+
+**How OmniRoute solves it:**
+
+- **npm global install** — `npm install -g omniroute && omniroute` — done
+- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)
+- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)
+- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode
+- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)
+- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers
+- **DB Backups** — Automatic backup, restore, export and import of all settings
+
+</details>
+
+<details>
+<summary><b>🌍 12. "The interface is English-only and my team doesn't speak English"</b></summary>
+
+Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.
+
+**How OmniRoute solves it:**
+
+- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English
+- **RTL Support** — Right-to-left support for Arabic and Hebrew
+- **Multi-Language READMEs** — 30 complete documentation translations
+- **Language Selector** — Globe icon in header for real-time switching
+
+</details>
+
+<details>
+<summary><b>🔄 13. "I need more than chat — I need embeddings, images, audio"</b></summary>
+
+AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.
+
+**How OmniRoute solves it:**
+
+- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models
+- **Image Generation** — `/v1/images/generations` with 4 providers and 9+ models
+- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper-compatible
+- **Text-to-Speech** — `/v1/audio/speech` — Multi-provider audio synthesis
+- **Moderations** — `/v1/moderations` — Content safety checks
+- **Reranking** — `/v1/rerank` — Document relevance reranking
+- **Responses API** — Full `/v1/responses` support for Codex
+
+</details>
+
+<details>
+<summary><b>🧪 14. "I have no way to test and compare quality across models"</b></summary>
+
+Developers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.
+
+**How OmniRoute solves it:**
+
+- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal
+- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)
+- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison
+- **Chat Tester** — Full round-trip with visual response rendering
+- **Live Monitor** — Real-time stream of all requests flowing through the proxy
+
+</details>
+
+<details>
+<summary><b>📈 15. "I need to scale without losing performance"</b></summary>
+
+As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.
+
+**How OmniRoute solves it:**
+
+- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency
+- **Request Idempotency** — 5s deduplication window for identical requests
+- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking
+- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence
+- **API Key Validation Cache** — 3-tier cache for production performance
+- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
+
+</details>
+
+<details>
+<summary><b>🤖 16. "I want to control model behavior globally"</b></summary>
+
+Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.
+
+**How OmniRoute solves it:**
+
+- **System Prompt Injection** — Global prompt applied to all requests
+- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)
+- **6 Routing Strategies** — Global strategies that determine how requests are distributed
+- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
+- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Provider Toggle** — Enable/disable all connections for a provider with one click
+- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
+
+</details>
+
 ## ⚡ Avvio Rapido
 
 **1. Installa globalmente:**
@@ -247,6 +504,30 @@ docker compose --profile cli up -d
 
 ---
 
+---
+
+## 🖥️ Desktop App — Offline & Always-On
+
+> 🆕 **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 +553,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 +568,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 +586,17 @@ 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                 |
+| 🛡️ **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
 
@@ -474,6 +698,67 @@ Traduzione trasparente tra formati:
 
 ---
 
+## 🎯 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...
+```
+
+---
+
 ## 📖 Guida alla Configurazione
 
 <details>
@@ -754,74 +1039,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.

README.md

@@ -7,7 +7,21 @@
 
 _Your universal API proxy — one endpoint, 36+ providers, zero downtime._
 
-**Chat Completions • Embeddings • Image Generation • Audio • Reranking • 100% TypeScript**
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • 100% TypeScript**
+
+---
+
+[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
+[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)
+[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)
+[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+
+[🌐 Website](https://omniroute.online) • [🚀 Quick Start](#-quick-start) • [💡 Features](#-key-features) • [📖 Docs](#-documentation) • [💰 Pricing](#-pricing-at-a-glance) • [💬 WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+
+🌐 **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>
 
 ---
 
@@ -18,7 +32,7 @@ _Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway f
   <table>
     <tr>
       <td align="center" width="110">
-        <a href="https://github.com/cline/cline">
+        <a href="https://github.com/openclaw/openclaw">
           <img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
           <b>OpenClaw</b>
         </a><br/>
@@ -96,17 +110,15 @@ _Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway f
 
 ---
 
-[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
-[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)
-[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)
-[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
 
-[🌐 Website](https://omniroute.online) • [🚀 Quick Start](#-quick-start) • [💡 Features](#-key-features) • [📖 Docs](#-documentation) • [💰 Pricing](#-pricing-at-a-glance) • [💬 WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
 
-🌐 **Available 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)
-
-</div>
+- **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**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
 
 ---
 
@@ -157,6 +169,267 @@ Result: Never stop coding, minimal cost
 
 ---
 
+## 🎯 What OmniRoute Solves — 16 Real Pain Points
+
+> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to zero observability.
+
+<details>
+<summary><b>💸 1. "I pay for an expensive subscription but still get interrupted by limits"</b></summary>
+
+Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.
+
+**How OmniRoute solves it:**
+
+- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention
+- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly)
+- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next
+- **Custom Combos** — Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized)
+- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
+
+</details>
+
+<details>
+<summary><b>🔌 2. "I need to use multiple providers but each has a different API"</b></summary>
+
+OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.
+
+**How OmniRoute solves it:**
+
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 36+ providers
+- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
+- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+
+- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE
+- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`
+- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion
+- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs
+
+</details>
+
+<details>
+<summary><b>🌐 3. "My AI provider blocks my region/country"</b></summary>
+
+Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.
+
+**How OmniRoute solves it:**
+
+- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key
+- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP
+- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`
+- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)
+- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing
+- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection
+
+</details>
+
+<details>
+<summary><b>🆓 4. "I want to use AI for coding but I have no money"</b></summary>
+
+Not everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.
+
+**How OmniRoute solves it:**
+
+- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (8 unlimited models), Qwen (3 unlimited models), Kiro (Claude for free), Gemini CLI (180K/month free)
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime
+- **NVIDIA NIM Free Credits** — 1000 free credits integrated
+- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider
+
+</details>
+
+<details>
+<summary><b>🔒 5. "I need to protect my AI gateway from unauthorized access"</b></summary>
+
+When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.
+
+**How OmniRoute solves it:**
+
+- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page
+- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle
+- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing
+- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens
+- **Rate Limiter** — Per-IP rate limiting with configurable windows
+- **IP Filtering** — Allowlist/blocklist for access control
+- **Prompt Injection Guard** — Sanitization against malicious prompt patterns
+- **AES-256-GCM Encryption** — Credentials encrypted at rest
+
+</details>
+
+<details>
+<summary><b>🛑 6. "My provider went down and I lost my coding flow"</b></summary>
+
+AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.
+
+**How OmniRoute solves it:**
+
+- **Circuit Breaker per-provider** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open)
+- **Exponential Backoff** — Progressive retry delays
+- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms
+- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention
+- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain
+- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
+
+</details>
+
+<details>
+<summary><b>🔧 7. "Configuring each AI tool is tedious and repetitive"</b></summary>
+
+Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.
+
+**How OmniRoute solves it:**
+
+- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
+- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection
+- **Onboarding Wizard** — Guided 4-step setup for first-time users
+- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 36+ providers
+
+</details>
+
+<details>
+<summary><b>🔑 8. "Managing OAuth tokens from multiple providers is hell"</b></summary>
+
+Claude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.
+
+**How OmniRoute solves it:**
+
+- **Auto Token Refresh** — OAuth tokens refresh in background before expiration
+- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow
+- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction
+- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers
+- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility
+- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker
+
+</details>
+
+<details>
+<summary><b>📊 9. "I don't know how much I'm spending or where"</b></summary>
+
+Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.
+
+**How OmniRoute solves it:**
+
+- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider
+- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback
+- **Per-Model Pricing Configuration** — Configurable prices per model
+- **Usage Statistics Per API Key** — Request count and last-used timestamp per key
+- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency
+
+</details>
+
+<details>
+<summary><b>🐛 10. "I can't diagnose errors and problems in AI calls"</b></summary>
+
+When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.
+
+**How OmniRoute solves it:**
+
+- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console
+- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter
+- **SQLite Proxy Logs** — Persistent logs that survive server restarts
+- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)
+- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing
+- **File-Based Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation
+
+</details>
+
+<details>
+<summary><b>🏗️ 11. "Deploying and maintaining the gateway is complex"</b></summary>
+
+Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.
+
+**How OmniRoute solves it:**
+
+- **npm global install** — `npm install -g omniroute && omniroute` — done
+- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)
+- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)
+- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode
+- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)
+- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers
+- **DB Backups** — Automatic backup, restore, export and import of all settings
+
+</details>
+
+<details>
+<summary><b>🌍 12. "The interface is English-only and my team doesn't speak English"</b></summary>
+
+Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.
+
+**How OmniRoute solves it:**
+
+- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English
+- **RTL Support** — Right-to-left support for Arabic and Hebrew
+- **Multi-Language READMEs** — 30 complete documentation translations
+- **Language Selector** — Globe icon in header for real-time switching
+
+</details>
+
+<details>
+<summary><b>🔄 13. "I need more than chat — I need embeddings, images, audio"</b></summary>
+
+AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.
+
+**How OmniRoute solves it:**
+
+- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models
+- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)
+- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI
+- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)
+- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3
+- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, + existing providers
+- **Moderations** — `/v1/moderations` — Content safety checks
+- **Reranking** — `/v1/rerank` — Document relevance reranking
+- **Responses API** — Full `/v1/responses` support for Codex
+
+</details>
+
+<details>
+<summary><b>🧪 14. "I have no way to test and compare quality across models"</b></summary>
+
+Developers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.
+
+**How OmniRoute solves it:**
+
+- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal
+- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)
+- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison
+- **Chat Tester** — Full round-trip with visual response rendering
+- **Live Monitor** — Real-time stream of all requests flowing through the proxy
+
+</details>
+
+<details>
+<summary><b>📈 15. "I need to scale without losing performance"</b></summary>
+
+As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.
+
+**How OmniRoute solves it:**
+
+- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency
+- **Request Idempotency** — 5s deduplication window for identical requests
+- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking
+- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence
+- **API Key Validation Cache** — 3-tier cache for production performance
+- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
+
+</details>
+
+<details>
+<summary><b>🤖 16. "I want to control model behavior globally"</b></summary>
+
+Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.
+
+**How OmniRoute solves it:**
+
+- **System Prompt Injection** — Global prompt applied to all requests
+- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)
+- **6 Routing Strategies** — Global strategies that determine how requests are distributed
+- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
+- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Provider Toggle** — Enable/disable all connections for a provider with one click
+- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
+
+</details>
+
+---
+
 ## ⚡ Quick Start
 
 **1. Install globally:**
@@ -168,12 +441,22 @@ omniroute
 
 🎉 Dashboard opens at `http://localhost:20128`
 
-| Command                 | Description                       |
-| ----------------------- | --------------------------------- |
-| `omniroute`             | Start server (default port 20128) |
-| `omniroute --port 3000` | Use custom port                   |
-| `omniroute --no-open`   | Don't auto-open browser           |
-| `omniroute --help`      | Show help                         |
+| Command                 | Description                                                 |
+| ----------------------- | ----------------------------------------------------------- |
+| `omniroute`             | Start server (`PORT=20128`, API and dashboard on same port) |
+| `omniroute --port 3000` | Set canonical/API port to 3000                              |
+| `omniroute --no-open`   | Don't auto-open browser                                     |
+| `omniroute --help`      | Show help                                                   |
+
+Optional split-port mode:
+
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API:       http://localhost:20128/v1
+# Dashboard: http://localhost:20129
+```
+
+When ports are split, the API port serves only OpenAI-compatible routes (`/v1`, `/chat/completions`, `/responses`, `/models`, `/codex/*`).
 
 **2. Connect a FREE provider:**
 
@@ -195,7 +478,7 @@ Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
 ```bash
 cp .env.example .env
 npm install
-PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
 ```
 
 ---
@@ -247,6 +530,43 @@ docker compose --profile cli up -d
 
 ---
 
+## 🖥️ Desktop App — Offline & Always-On
+
+> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.
+
+Run OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:
+
+- 🖥️ **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
+
+### Quick Start
+
+```bash
+# Development mode
+npm run electron:dev
+
+# Build for your platform
+npm run electron:build         # Current platform
+npm run electron:build:win     # Windows (.exe)
+npm run electron:build:mac     # macOS (.dmg) — x64 & arm64
+npm run electron:build:linux   # Linux (.AppImage)
+```
+
+### System Tray
+
+When minimized, OmniRoute lives in your system tray with quick actions:
+
+- Open dashboard
+- Change server port
+- Quit application
+
+📖 Full documentation: [`electron/README.md`](electron/README.md)
+
+---
+
 ## 💰 Pricing at a Glance
 
 | Tier                | Provider          | Cost                    | Quota Reset      | Best For             |
@@ -272,67 +592,6 @@ docker compose --profile cli up -d
 
 ---
 
-## 🎯 Use Cases
-
-### Case 1: "I have Claude Pro subscription"
-
-**Problem:** Quota expires unused, rate limits during heavy coding
-
-```
-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: "I want zero cost"
-
-**Problem:** Can't afford subscriptions, need reliable AI coding
-
-```
-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: "I need 24/7 coding, no interruptions"
-
-**Problem:** Deadlines, can't afford downtime
-
-```
-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
-```
-
-### Case 4: "I want FREE AI in OpenClaw"
-
-**Problem:** Need AI assistant in messaging apps, completely free
-
-```
-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...
-```
-
----
-
 ## 💡 Key Features
 
 ### 🧠 Core Routing & Intelligence
@@ -348,32 +607,40 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 | 🧩 **Custom Models**            | Add any model ID to any provider                                               |
 | 🌐 **Wildcard Router**          | Route `provider/*` patterns to any provider dynamically                        |
 | 🧠 **Thinking Budget**          | Passthrough, auto, custom, and adaptive modes for reasoning models             |
+| 🔀 **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 Injection**  | Global system prompt applied across all requests                               |
 | 📄 **Responses API**            | Full OpenAI Responses API (`/v1/responses`) support for Codex                  |
 
 ### 🎵 Multi-Modal APIs
 
-| Feature                    | What It Does                                        |
-| -------------------------- | --------------------------------------------------- |
-| 🖼️ **Image Generation**    | `/v1/images/generations` — 4 providers, 9+ models   |
-| 📐 **Embeddings**          | `/v1/embeddings` — 6 providers, 9+ models           |
-| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — Whisper-compatible     |
-| 🔊 **Text-to-Speech**      | `/v1/audio/speech` — Multi-provider audio synthesis |
-| 🛡️ **Moderations**         | `/v1/moderations` — Content safety checks           |
-| 🔀 **Reranking**           | `/v1/rerank` — Document relevance reranking         |
+| Feature                    | What It Does                                                                     |
+| -------------------------- | -------------------------------------------------------------------------------- |
+| 🖼️ **Image Generation**    | `/v1/images/generations` — 10 providers, 20+ models (cloud + local)              |
+| 📐 **Embeddings**          | `/v1/embeddings` — 6 providers, 9+ models                                        |
+| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3            |
+| 🔊 **Text-to-Speech**      | `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3 |
+| 🎬 **Video Generation**    | `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD), SD WebUI                  |
+| 🎵 **Music Generation**    | `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)                  |
+| 🛡️ **Moderations**         | `/v1/moderations` — Content safety checks                                        |
+| 🔀 **Reranking**           | `/v1/rerank` — Document relevance reranking                                      |
 
 ### 🛡️ Resilience & Security
 
-| Feature                         | What It Does                                                  |
-| ------------------------------- | ------------------------------------------------------------- |
-| 🔌 **Circuit Breaker**          | Auto-open/close per-provider with configurable thresholds     |
-| 🛡️ **Anti-Thundering Herd**     | Mutex + semaphore rate-limit for API key providers            |
-| 🧠 **Semantic Cache**           | Two-tier cache (signature + semantic) reduces cost & latency  |
-| ⚡ **Request Idempotency**      | 5s dedup window for duplicate requests                        |
-| 🔒 **TLS Fingerprint Spoofing** | Bypass TLS-based bot detection via wreq-js                    |
-| 🌐 **IP Filtering**             | Allowlist/blocklist for API access control                    |
-| 📊 **Editable Rate Limits**     | Configurable RPM, min gap, and max concurrent at system level |
-| 🛡 **API Endpoint Protection**  | Auth gating + provider blocking for the `/models` endpoint    |
+| Feature                         | What It Does                                                                  |
+| ------------------------------- | ----------------------------------------------------------------------------- |
+| 🔌 **Circuit Breaker**          | Auto-open/close per-provider with configurable thresholds                     |
+| 🛡️ **Anti-Thundering Herd**     | Mutex + semaphore rate-limit for API key providers                            |
+| 🧠 **Semantic Cache**           | Two-tier cache (signature + semantic) reduces cost & latency                  |
+| ⚡ **Request Idempotency**      | 5s dedup window for duplicate requests                                        |
+| 🔒 **TLS Fingerprint Spoofing** | Bypass TLS-based bot detection via wreq-js                                    |
+| 🌐 **IP Filtering**             | Allowlist/blocklist for API access control                                    |
+| 📊 **Editable Rate Limits**     | Configurable RPM, min gap, and max concurrent at system level                 |
+| 💾 **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        |
+| 🛡 **API Endpoint Protection**  | Auth gating + provider blocking for the `/models` endpoint                    |
+| 🔒 **Proxy Visibility**         | Color-coded badges: 🟢 global, 🟡 provider, 🔵 per-connection with IP display |
+| 🌐 **3-Level Proxy Config**     | Configure proxies at global, per-provider, or per-connection level            |
 
 ### 📊 Observability & Analytics
 
@@ -393,14 +660,17 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 
 ### ☁️ Deployment & Sync
 
-| Feature                    | What It Does                                                          |
-| -------------------------- | --------------------------------------------------------------------- |
-| 💾 **Cloud Sync**          | Sync config across devices via Cloudflare Workers                     |
-| 🌐 **Deploy Anywhere**     | Localhost, VPS, Docker, Cloudflare Workers                            |
-| 🔑 **API Key Management**  | Generate, rotate, and scope API keys per provider                     |
-| 🧙 **Onboarding Wizard**   | 4-step guided setup for first-time users                              |
-| 🔧 **CLI Tools Dashboard** | One-click configure Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **DB Backups**          | Automatic backup, restore, export & import for all settings           |
+| Feature                      | What It Does                                                          |
+| ---------------------------- | --------------------------------------------------------------------- |
+| 💾 **Cloud Sync**            | Sync config across devices via Cloudflare Workers                     |
+| 🌐 **Deploy Anywhere**       | Localhost, VPS, Docker, Cloudflare Workers                            |
+| 🔑 **API Key Management**    | Generate, rotate, and scope API keys per provider                     |
+| 🧙 **Onboarding Wizard**     | 4-step guided setup for first-time users                              |
+| 🔧 **CLI Tools Dashboard**   | One-click configure Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
+| 🔄 **DB Backups**            | Automatic backup, restore, export & import for all settings           |
+| 🌐 **Internationalization**  | Full i18n with next-intl — 30 languages including RTL support         |
+| 🌍 **Language Selector**     | Globe icon in header for real-time switching between 30 languages     |
+| 📂 **Custom Data Directory** | `DATA_DIR` env var to override default `~/.omniroute` storage path    |
 
 <details>
 <summary><b>📖 Feature Details</b></summary>
@@ -488,6 +758,67 @@ OmniRoute includes a powerful built-in Translator Playground with **4 modes** fo
 
 ---
 
+## 🎯 Use Cases
+
+### Case 1: "I have Claude Pro subscription"
+
+**Problem:** Quota expires unused, rate limits during heavy coding
+
+```
+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: "I want zero cost"
+
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
+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: "I need 24/7 coding, no interruptions"
+
+**Problem:** Deadlines, can't afford downtime
+
+```
+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
+```
+
+### Case 4: "I want FREE AI in OpenClaw"
+
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
+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...
+```
+
+---
+
 ## 📖 Setup Guide
 
 <details>
@@ -764,73 +1095,46 @@ Settings → API Configuration:
   Model: if/kimi-k2-thinking
 ```
 
-</details>
+### OpenCode
 
----
+**Step 1:** Add OmniRoute as a custom provider:
 
-## 📊 Available Models
+```bash
+opencode
+/connect
+# Select "Other" → Enter ID: "omniroute" → Enter your OmniRoute API key
+```
 
-<details>
-<summary><b>View all available models</b></summary>
+**Step 2:** Create/edit `opencode.json` in your project root:
 
-**Claude Code (`cc/`)** - Pro/Max:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "omniroute": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "OmniRoute",
+      "options": {
+        "baseURL": "http://localhost:20128/v1"
+      },
+      "models": {
+        "cc/claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" },
+        "gg/gemini-2.5-pro": { "name": "Gemini 2.5 Pro" },
+        "if/kimi-k2-thinking": { "name": "Kimi K2 (Free)" }
+      }
+    }
+  }
+}
+```
 
-- `cc/claude-opus-4-6`
-- `cc/claude-sonnet-4-5-20250929`
-- `cc/claude-haiku-4-5-20251001`
+**Step 3:** Select the model in OpenCode:
 
-**Codex (`cx/`)** - Plus/Pro:
+```bash
+/models
+# Select any OmniRoute model from the list
+```
 
-- `cx/gpt-5.2-codex`
-- `cx/gpt-5.1-codex-max`
-
-**Gemini CLI (`gc/`)** - FREE:
-
-- `gc/gemini-3-flash-preview`
-- `gc/gemini-2.5-pro`
-
-**GitHub Copilot (`gh/`)**:
-
-- `gh/gpt-5`
-- `gh/claude-4.5-sonnet`
-
-**NVIDIA NIM (`nvidia/`)** - FREE credits:
-
-- `nvidia/llama-3.3-70b-instruct`
-- `nvidia/mistral-7b-instruct`
-- 50+ more models on [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/`)** - FREE:
-
-- `if/kimi-k2-thinking`
-- `if/qwen3-coder-plus`
-- `if/deepseek-r1`
-- `if/glm-4.7`
-- `if/minimax-m2`
-
-**Qwen (`qw/`)** - FREE:
-
-- `qw/qwen3-coder-plus`
-- `qw/qwen3-coder-flash`
-
-**Kiro (`kr/`)** - FREE:
-
-- `kr/claude-sonnet-4.5`
-- `kr/claude-haiku-4.5`
-
-**OpenRouter (`or/`)** - 100+ models:
-
-- `or/anthropic/claude-4-sonnet`
-- `or/google/gemini-2.5-pro`
-- Any model from [openrouter.ai/models](https://openrouter.ai/models)
+> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.
 
 </details>
 
@@ -859,13 +1163,67 @@ The pre-loaded "OmniRoute Golden Set" contains 10 test cases covering:
 
 ---
 
-## 🔐 OAuth em Servidor Remoto (Remote OAuth Setup)
+## 🐛 Troubleshooting
+
+<details>
+<summary><b>Click to expand troubleshooting guide</b></summary>
+
+**"Language model did not provide messages"**
+
+- Provider quota exhausted → Check dashboard quota tracker
+- Solution: Use combo fallback or switch to cheaper tier
+
+**Rate limiting**
+
+- Subscription quota out → Fallback to GLM/MiniMax
+- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+
+**OAuth token expired**
+
+- Auto-refreshed by OmniRoute
+- If issues persist: Dashboard → Provider → Reconnect
+
+**High costs**
+
+- Check usage stats in Dashboard → Costs
+- Switch primary model to GLM/MiniMax
+- Use free tier (Gemini CLI, iFlow) for non-critical tasks
+
+**Dashboard/API ports are wrong**
+
+- `PORT` is the canonical base port (and API port by default)
+- `API_PORT` overrides only OpenAI-compatible API listener
+- `DASHBOARD_PORT` overrides only dashboard/Next.js listener
+- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)
+
+**Cloud sync errors**
+
+- Verify `BASE_URL` points to your running instance
+- Verify `CLOUD_URL` points to your expected cloud endpoint
+- Keep `NEXT_PUBLIC_*` values aligned with server-side values
+
+**First login not working**
+
+- Check `INITIAL_PASSWORD` in `.env`
+- If unset, fallback password is `123456`
+
+**No request logs**
+
+- Set `ENABLE_REQUEST_LOGS=true` in `.env`
+
+**Connection test shows "Invalid" for OpenAI-compatible providers**
+
+- Many providers don't expose a `/models` endpoint
+- OmniRoute v1.0.6+ includes fallback validation via chat completions
+- Ensure base URL includes `/v1` suffix
+
+### 🔐 OAuth em Servidor Remoto (Remote OAuth Setup)
 
 <a name="oauth-em-servidor-remoto"></a>
 
 > **⚠️ IMPORTANTE para usuários com OmniRoute em VPS/Docker/servidor remoto**
 
-### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?
+#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?
 
 Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.
 
@@ -875,7 +1233,7 @@ As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `lo
 Error 400: redirect_uri_mismatch
 ```
 
-### Solução: Configure suas próprias credenciais OAuth
+#### Solução: Configure suas próprias credenciais OAuth
 
 Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.
 
@@ -938,7 +1296,7 @@ Agora o Google redirecionará corretamente para `https://seu-servidor.com/callba
 
 ---
 
-### Workaround temporário (sem configurar credenciais próprias)
+#### Workaround temporário (sem configurar credenciais próprias)
 
 Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:
 
@@ -950,66 +1308,13 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
 
 > Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
 
----
-
-## 🐛 Troubleshooting
-
-<details>
-<summary><b>Click to expand troubleshooting guide</b></summary>
-
-**"Language model did not provide messages"**
-
-- Provider quota exhausted → Check dashboard quota tracker
-- Solution: Use combo fallback or switch to cheaper tier
-
-**Rate limiting**
-
-- Subscription quota out → Fallback to GLM/MiniMax
-- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-
-**OAuth token expired**
-
-- Auto-refreshed by OmniRoute
-- If issues persist: Dashboard → Provider → Reconnect
-
-**High costs**
-
-- Check usage stats in Dashboard → Costs
-- Switch primary model to GLM/MiniMax
-- Use free tier (Gemini CLI, iFlow) for non-critical tasks
-
-**Dashboard opens on wrong port**
-
-- Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
-
-**Cloud sync errors**
-
-- Verify `BASE_URL` points to your running instance
-- Verify `CLOUD_URL` points to your expected cloud endpoint
-- Keep `NEXT_PUBLIC_*` values aligned with server-side values
-
-**First login not working**
-
-- Check `INITIAL_PASSWORD` in `.env`
-- If unset, fallback password is `123456`
-
-**No request logs**
-
-- Set `ENABLE_REQUEST_LOGS=true` in `.env`
-
-**Connection test shows "Invalid" for OpenAI-compatible providers**
-
-- Many providers don't expose a `/models` endpoint
-- OmniRoute v1.0.6+ includes fallback validation via chat completions
-- Ensure base URL includes `/v1` suffix
-
 </details>
 
 ---
 
 ## 🛠️ Tech Stack
 
-- **Runtime**: Node.js 20+
+- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)
 - **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (v1.0.6)
 - **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
 - **Database**: LowDB (JSON) + SQLite (domain state + proxy logs)
@@ -1084,18 +1389,6 @@ OmniRoute has **210+ features planned** across multiple development phases. Here
 
 ---
 
-## 📧 Support
-
-> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-
-- **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**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
-
----
-
 ## 👥 Contributors
 
 [![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
@@ -1150,3 +1443,4 @@ MIT License - see [LICENSE](LICENSE) for details.
   <br/>
   <sub><a href="https://omniroute.online">omniroute.online</a></sub>
 </div>
+<!-- GitHub Discussions enabled for community Q&A -->

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,7 +104,7 @@ _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>
 
@@ -157,6 +157,265 @@ Resultado: Nunca pare de programar, custo mínimo
 
 ---
 
+## 🎯 What OmniRoute Solves — 16 Real Pain Points
+
+> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to zero observability.
+
+<details>
+<summary><b>💸 1. "I pay for an expensive subscription but still get interrupted by limits"</b></summary>
+
+Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.
+
+**How OmniRoute solves it:**
+
+- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention
+- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly)
+- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next
+- **Custom Combos** — Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized)
+- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
+
+</details>
+
+<details>
+<summary><b>🔌 2. "I need to use multiple providers but each has a different API"</b></summary>
+
+OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.
+
+**How OmniRoute solves it:**
+
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 36+ providers
+- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
+- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+
+- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE
+- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`
+- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion
+- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs
+
+</details>
+
+<details>
+<summary><b>🌐 3. "My AI provider blocks my region/country"</b></summary>
+
+Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.
+
+**How OmniRoute solves it:**
+
+- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key
+- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP
+- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`
+- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)
+- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing
+- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection
+
+</details>
+
+<details>
+<summary><b>🆓 4. "I want to use AI for coding but I have no money"</b></summary>
+
+Not everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.
+
+**How OmniRoute solves it:**
+
+- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (8 unlimited models), Qwen (3 unlimited models), Kiro (Claude for free), Gemini CLI (180K/month free)
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime
+- **NVIDIA NIM Free Credits** — 1000 free credits integrated
+- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider
+
+</details>
+
+<details>
+<summary><b>🔒 5. "I need to protect my AI gateway from unauthorized access"</b></summary>
+
+When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.
+
+**How OmniRoute solves it:**
+
+- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page
+- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle
+- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing
+- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens
+- **Rate Limiter** — Per-IP rate limiting with configurable windows
+- **IP Filtering** — Allowlist/blocklist for access control
+- **Prompt Injection Guard** — Sanitization against malicious prompt patterns
+- **AES-256-GCM Encryption** — Credentials encrypted at rest
+
+</details>
+
+<details>
+<summary><b>🛑 6. "My provider went down and I lost my coding flow"</b></summary>
+
+AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.
+
+**How OmniRoute solves it:**
+
+- **Circuit Breaker per-provider** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open)
+- **Exponential Backoff** — Progressive retry delays
+- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms
+- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention
+- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain
+- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
+
+</details>
+
+<details>
+<summary><b>🔧 7. "Configuring each AI tool is tedious and repetitive"</b></summary>
+
+Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.
+
+**How OmniRoute solves it:**
+
+- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
+- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection
+- **Onboarding Wizard** — Guided 4-step setup for first-time users
+- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 36+ providers
+
+</details>
+
+<details>
+<summary><b>🔑 8. "Managing OAuth tokens from multiple providers is hell"</b></summary>
+
+Claude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.
+
+**How OmniRoute solves it:**
+
+- **Auto Token Refresh** — OAuth tokens refresh in background before expiration
+- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow
+- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction
+- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers
+- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility
+- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker
+
+</details>
+
+<details>
+<summary><b>📊 9. "I don't know how much I'm spending or where"</b></summary>
+
+Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.
+
+**How OmniRoute solves it:**
+
+- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider
+- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback
+- **Per-Model Pricing Configuration** — Configurable prices per model
+- **Usage Statistics Per API Key** — Request count and last-used timestamp per key
+- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency
+
+</details>
+
+<details>
+<summary><b>🐛 10. "I can't diagnose errors and problems in AI calls"</b></summary>
+
+When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.
+
+**How OmniRoute solves it:**
+
+- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console
+- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter
+- **SQLite Proxy Logs** — Persistent logs that survive server restarts
+- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)
+- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing
+- **File-Based Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation
+
+</details>
+
+<details>
+<summary><b>🏗️ 11. "Deploying and maintaining the gateway is complex"</b></summary>
+
+Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.
+
+**How OmniRoute solves it:**
+
+- **npm global install** — `npm install -g omniroute && omniroute` — done
+- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)
+- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)
+- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode
+- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)
+- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers
+- **DB Backups** — Automatic backup, restore, export and import of all settings
+
+</details>
+
+<details>
+<summary><b>🌍 12. "The interface is English-only and my team doesn't speak English"</b></summary>
+
+Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.
+
+**How OmniRoute solves it:**
+
+- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English
+- **RTL Support** — Right-to-left support for Arabic and Hebrew
+- **Multi-Language READMEs** — 30 complete documentation translations
+- **Language Selector** — Globe icon in header for real-time switching
+
+</details>
+
+<details>
+<summary><b>🔄 13. "I need more than chat — I need embeddings, images, audio"</b></summary>
+
+AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.
+
+**How OmniRoute solves it:**
+
+- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models
+- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)
+- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI
+- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)
+- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3
+- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3
+- **Moderations** — `/v1/moderations` — Content safety checks
+- **Reranking** — `/v1/rerank` — Document relevance reranking
+- **Responses API** — Full `/v1/responses` support for Codex
+
+</details>
+
+<details>
+<summary><b>🧪 14. "I have no way to test and compare quality across models"</b></summary>
+
+Developers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.
+
+**How OmniRoute solves it:**
+
+- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal
+- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)
+- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison
+- **Chat Tester** — Full round-trip with visual response rendering
+- **Live Monitor** — Real-time stream of all requests flowing through the proxy
+
+</details>
+
+<details>
+<summary><b>📈 15. "I need to scale without losing performance"</b></summary>
+
+As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.
+
+**How OmniRoute solves it:**
+
+- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency
+- **Request Idempotency** — 5s deduplication window for identical requests
+- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking
+- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence
+- **API Key Validation Cache** — 3-tier cache for production performance
+- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
+
+</details>
+
+<details>
+<summary><b>🤖 16. "I want to control model behavior globally"</b></summary>
+
+Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.
+
+**How OmniRoute solves it:**
+
+- **System Prompt Injection** — Global prompt applied to all requests
+- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)
+- **6 Routing Strategies** — Global strategies that determine how requests are distributed
+- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
+- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Provider Toggle** — Enable/disable all connections for a provider with one click
+- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
+
+</details>
+
 ## ⚡ Início Rápido
 
 **1. Instale globalmente:**
@@ -247,6 +506,45 @@ docker compose --profile cli up -d
 
 ---
 
+---
+
+## 🖥️ Aplicativo Desktop — Offline e Sempre Ativo
+
+> 🆕 **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 +570,55 @@ 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
 
 ### 🧠 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            |
+| � **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     |
+| �💬 **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**              | 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                           |
+| 💾 **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,6 +644,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 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>
@@ -482,6 +730,67 @@ O OmniRoute inclui um poderoso Playground de Tradução integrado com **4 modos*
 
 ---
 
+## 🎯 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...
+```
+
+---
+
 ## 📖 Guia de Configuração
 
 <details>
@@ -762,74 +1071,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.

README.ru.md

@@ -104,7 +104,7 @@ _Подключайте любую 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>
 
@@ -157,6 +157,263 @@ _Подключайте любую IDE или CLI-инструмент с AI ч
 
 ---
 
+## 🎯 What OmniRoute Solves — 16 Real Pain Points
+
+> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to zero observability.
+
+<details>
+<summary><b>💸 1. "I pay for an expensive subscription but still get interrupted by limits"</b></summary>
+
+Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.
+
+**How OmniRoute solves it:**
+
+- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention
+- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly)
+- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next
+- **Custom Combos** — Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized)
+- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
+
+</details>
+
+<details>
+<summary><b>🔌 2. "I need to use multiple providers but each has a different API"</b></summary>
+
+OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.
+
+**How OmniRoute solves it:**
+
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 36+ providers
+- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
+- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+
+- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE
+- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`
+- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion
+- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs
+
+</details>
+
+<details>
+<summary><b>🌐 3. "My AI provider blocks my region/country"</b></summary>
+
+Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.
+
+**How OmniRoute solves it:**
+
+- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key
+- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP
+- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`
+- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)
+- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing
+- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection
+
+</details>
+
+<details>
+<summary><b>🆓 4. "I want to use AI for coding but I have no money"</b></summary>
+
+Not everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.
+
+**How OmniRoute solves it:**
+
+- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (8 unlimited models), Qwen (3 unlimited models), Kiro (Claude for free), Gemini CLI (180K/month free)
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime
+- **NVIDIA NIM Free Credits** — 1000 free credits integrated
+- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider
+
+</details>
+
+<details>
+<summary><b>🔒 5. "I need to protect my AI gateway from unauthorized access"</b></summary>
+
+When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.
+
+**How OmniRoute solves it:**
+
+- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page
+- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle
+- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing
+- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens
+- **Rate Limiter** — Per-IP rate limiting with configurable windows
+- **IP Filtering** — Allowlist/blocklist for access control
+- **Prompt Injection Guard** — Sanitization against malicious prompt patterns
+- **AES-256-GCM Encryption** — Credentials encrypted at rest
+
+</details>
+
+<details>
+<summary><b>🛑 6. "My provider went down and I lost my coding flow"</b></summary>
+
+AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.
+
+**How OmniRoute solves it:**
+
+- **Circuit Breaker per-provider** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open)
+- **Exponential Backoff** — Progressive retry delays
+- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms
+- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention
+- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain
+- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
+
+</details>
+
+<details>
+<summary><b>🔧 7. "Configuring each AI tool is tedious and repetitive"</b></summary>
+
+Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.
+
+**How OmniRoute solves it:**
+
+- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
+- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection
+- **Onboarding Wizard** — Guided 4-step setup for first-time users
+- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 36+ providers
+
+</details>
+
+<details>
+<summary><b>🔑 8. "Managing OAuth tokens from multiple providers is hell"</b></summary>
+
+Claude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.
+
+**How OmniRoute solves it:**
+
+- **Auto Token Refresh** — OAuth tokens refresh in background before expiration
+- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow
+- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction
+- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers
+- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility
+- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker
+
+</details>
+
+<details>
+<summary><b>📊 9. "I don't know how much I'm spending or where"</b></summary>
+
+Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.
+
+**How OmniRoute solves it:**
+
+- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider
+- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback
+- **Per-Model Pricing Configuration** — Configurable prices per model
+- **Usage Statistics Per API Key** — Request count and last-used timestamp per key
+- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency
+
+</details>
+
+<details>
+<summary><b>🐛 10. "I can't diagnose errors and problems in AI calls"</b></summary>
+
+When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.
+
+**How OmniRoute solves it:**
+
+- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console
+- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter
+- **SQLite Proxy Logs** — Persistent logs that survive server restarts
+- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)
+- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing
+- **File-Based Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation
+
+</details>
+
+<details>
+<summary><b>🏗️ 11. "Deploying and maintaining the gateway is complex"</b></summary>
+
+Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.
+
+**How OmniRoute solves it:**
+
+- **npm global install** — `npm install -g omniroute && omniroute` — done
+- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)
+- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)
+- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode
+- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)
+- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers
+- **DB Backups** — Automatic backup, restore, export and import of all settings
+
+</details>
+
+<details>
+<summary><b>🌍 12. "The interface is English-only and my team doesn't speak English"</b></summary>
+
+Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.
+
+**How OmniRoute solves it:**
+
+- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English
+- **RTL Support** — Right-to-left support for Arabic and Hebrew
+- **Multi-Language READMEs** — 30 complete documentation translations
+- **Language Selector** — Globe icon in header for real-time switching
+
+</details>
+
+<details>
+<summary><b>🔄 13. "I need more than chat — I need embeddings, images, audio"</b></summary>
+
+AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.
+
+**How OmniRoute solves it:**
+
+- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models
+- **Image Generation** — `/v1/images/generations` with 4 providers and 9+ models
+- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper-compatible
+- **Text-to-Speech** — `/v1/audio/speech` — Multi-provider audio synthesis
+- **Moderations** — `/v1/moderations` — Content safety checks
+- **Reranking** — `/v1/rerank` — Document relevance reranking
+- **Responses API** — Full `/v1/responses` support for Codex
+
+</details>
+
+<details>
+<summary><b>🧪 14. "I have no way to test and compare quality across models"</b></summary>
+
+Developers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.
+
+**How OmniRoute solves it:**
+
+- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal
+- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)
+- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison
+- **Chat Tester** — Full round-trip with visual response rendering
+- **Live Monitor** — Real-time stream of all requests flowing through the proxy
+
+</details>
+
+<details>
+<summary><b>📈 15. "I need to scale without losing performance"</b></summary>
+
+As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.
+
+**How OmniRoute solves it:**
+
+- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency
+- **Request Idempotency** — 5s deduplication window for identical requests
+- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking
+- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence
+- **API Key Validation Cache** — 3-tier cache for production performance
+- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
+
+</details>
+
+<details>
+<summary><b>🤖 16. "I want to control model behavior globally"</b></summary>
+
+Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.
+
+**How OmniRoute solves it:**
+
+- **System Prompt Injection** — Global prompt applied to all requests
+- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)
+- **6 Routing Strategies** — Global strategies that determine how requests are distributed
+- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
+- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Provider Toggle** — Enable/disable all connections for a provider with one click
+- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
+
+</details>
+
 ## ⚡ Быстрый старт
 
 **1. Установите глобально:**
@@ -247,6 +504,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 +553,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 +568,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 +586,17 @@ 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**           | Авто-открытие/закрытие по провайдеру с настраиваемыми порогами               |
+| 🛡️ **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       |
 
 ### 📊 Наблюдаемость и аналитика
 
@@ -474,6 +698,67 @@ Combo: "my-coding-stack"
 
 ---
 
+## 🎯 Сценарии использования
+
+### Сценарий 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...
+```
+
+---
+
 ## 📖 Руководство по настройке
 
 <details>
@@ -754,74 +1039,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.

README.zh-CN.md

@@ -104,7 +104,7 @@ _通过 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>
 
@@ -157,6 +157,263 @@ _通过 OmniRoute 连接任何 AI 驱动的 IDE 或 CLI 工具 — 免费 API
 
 ---
 
+## 🎯 What OmniRoute Solves — 16 Real Pain Points
+
+> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to zero observability.
+
+<details>
+<summary><b>💸 1. "I pay for an expensive subscription but still get interrupted by limits"</b></summary>
+
+Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.
+
+**How OmniRoute solves it:**
+
+- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention
+- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly)
+- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next
+- **Custom Combos** — Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized)
+- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
+
+</details>
+
+<details>
+<summary><b>🔌 2. "I need to use multiple providers but each has a different API"</b></summary>
+
+OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.
+
+**How OmniRoute solves it:**
+
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 36+ providers
+- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
+- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+
+- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE
+- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`
+- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion
+- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs
+
+</details>
+
+<details>
+<summary><b>🌐 3. "My AI provider blocks my region/country"</b></summary>
+
+Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.
+
+**How OmniRoute solves it:**
+
+- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key
+- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP
+- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`
+- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)
+- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing
+- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection
+
+</details>
+
+<details>
+<summary><b>🆓 4. "I want to use AI for coding but I have no money"</b></summary>
+
+Not everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.
+
+**How OmniRoute solves it:**
+
+- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (8 unlimited models), Qwen (3 unlimited models), Kiro (Claude for free), Gemini CLI (180K/month free)
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime
+- **NVIDIA NIM Free Credits** — 1000 free credits integrated
+- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider
+
+</details>
+
+<details>
+<summary><b>🔒 5. "I need to protect my AI gateway from unauthorized access"</b></summary>
+
+When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.
+
+**How OmniRoute solves it:**
+
+- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page
+- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle
+- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing
+- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens
+- **Rate Limiter** — Per-IP rate limiting with configurable windows
+- **IP Filtering** — Allowlist/blocklist for access control
+- **Prompt Injection Guard** — Sanitization against malicious prompt patterns
+- **AES-256-GCM Encryption** — Credentials encrypted at rest
+
+</details>
+
+<details>
+<summary><b>🛑 6. "My provider went down and I lost my coding flow"</b></summary>
+
+AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.
+
+**How OmniRoute solves it:**
+
+- **Circuit Breaker per-provider** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open)
+- **Exponential Backoff** — Progressive retry delays
+- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms
+- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention
+- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain
+- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
+
+</details>
+
+<details>
+<summary><b>🔧 7. "Configuring each AI tool is tedious and repetitive"</b></summary>
+
+Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.
+
+**How OmniRoute solves it:**
+
+- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
+- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection
+- **Onboarding Wizard** — Guided 4-step setup for first-time users
+- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 36+ providers
+
+</details>
+
+<details>
+<summary><b>🔑 8. "Managing OAuth tokens from multiple providers is hell"</b></summary>
+
+Claude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.
+
+**How OmniRoute solves it:**
+
+- **Auto Token Refresh** — OAuth tokens refresh in background before expiration
+- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow
+- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction
+- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers
+- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility
+- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker
+
+</details>
+
+<details>
+<summary><b>📊 9. "I don't know how much I'm spending or where"</b></summary>
+
+Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.
+
+**How OmniRoute solves it:**
+
+- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider
+- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback
+- **Per-Model Pricing Configuration** — Configurable prices per model
+- **Usage Statistics Per API Key** — Request count and last-used timestamp per key
+- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency
+
+</details>
+
+<details>
+<summary><b>🐛 10. "I can't diagnose errors and problems in AI calls"</b></summary>
+
+When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.
+
+**How OmniRoute solves it:**
+
+- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console
+- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter
+- **SQLite Proxy Logs** — Persistent logs that survive server restarts
+- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)
+- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing
+- **File-Based Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation
+
+</details>
+
+<details>
+<summary><b>🏗️ 11. "Deploying and maintaining the gateway is complex"</b></summary>
+
+Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.
+
+**How OmniRoute solves it:**
+
+- **npm global install** — `npm install -g omniroute && omniroute` — done
+- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)
+- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)
+- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode
+- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)
+- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers
+- **DB Backups** — Automatic backup, restore, export and import of all settings
+
+</details>
+
+<details>
+<summary><b>🌍 12. "The interface is English-only and my team doesn't speak English"</b></summary>
+
+Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.
+
+**How OmniRoute solves it:**
+
+- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English
+- **RTL Support** — Right-to-left support for Arabic and Hebrew
+- **Multi-Language READMEs** — 30 complete documentation translations
+- **Language Selector** — Globe icon in header for real-time switching
+
+</details>
+
+<details>
+<summary><b>🔄 13. "I need more than chat — I need embeddings, images, audio"</b></summary>
+
+AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.
+
+**How OmniRoute solves it:**
+
+- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models
+- **Image Generation** — `/v1/images/generations` with 4 providers and 9+ models
+- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper-compatible
+- **Text-to-Speech** — `/v1/audio/speech` — Multi-provider audio synthesis
+- **Moderations** — `/v1/moderations` — Content safety checks
+- **Reranking** — `/v1/rerank` — Document relevance reranking
+- **Responses API** — Full `/v1/responses` support for Codex
+
+</details>
+
+<details>
+<summary><b>🧪 14. "I have no way to test and compare quality across models"</b></summary>
+
+Developers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.
+
+**How OmniRoute solves it:**
+
+- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal
+- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)
+- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison
+- **Chat Tester** — Full round-trip with visual response rendering
+- **Live Monitor** — Real-time stream of all requests flowing through the proxy
+
+</details>
+
+<details>
+<summary><b>📈 15. "I need to scale without losing performance"</b></summary>
+
+As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.
+
+**How OmniRoute solves it:**
+
+- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency
+- **Request Idempotency** — 5s deduplication window for identical requests
+- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking
+- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence
+- **API Key Validation Cache** — 3-tier cache for production performance
+- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
+
+</details>
+
+<details>
+<summary><b>🤖 16. "I want to control model behavior globally"</b></summary>
+
+Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.
+
+**How OmniRoute solves it:**
+
+- **System Prompt Injection** — Global prompt applied to all requests
+- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)
+- **6 Routing Strategies** — Global strategies that determine how requests are distributed
+- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
+- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Provider Toggle** — Enable/disable all connections for a provider with one click
+- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
+
+</details>
+
 ## ⚡ 快速开始
 
 **1. 全局安装：**
@@ -247,6 +504,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 +553,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 +586,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       |
 
 ### 📊 可观察性与分析
 
@@ -474,6 +698,67 @@ Combo: "my-coding-stack"
 
 ---
 
+## 🎯 使用场景
+
+### 场景 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...
+```
+
+---
+
 ## 📖 设置指南
 
 <details>
@@ -754,74 +1039,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** 访问。

bin/omniroute.mjs

@@ -12,15 +12,69 @@
  */
 
 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 +84,22 @@ 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 --help          Show this help
     omniroute --version       Show version
 
+  \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,40 +116,58 @@ if (args.includes("--version") || args.includes("-v")) {
   process.exit(0);
 }
 
-// Parse --port
-let port = 20128;
+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 ──────────────────────────────────
+const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+if (nodeMajor >= 24) {
+  console.warn(`\x1b[33m  ⚠  Warning: You are running Node.js ${process.versions.node}.
+     OmniRoute uses better-sqlite3, a native addon that does not yet
+     have compatible prebuilt binaries for Node.js 24+.
+     You may experience errors like "is not a valid Win32 application"
+     or "NODE_MODULE_VERSION mismatch".
+
+     Recommended: use Node.js 22 LTS (or 20 LTS).
+     Workaround:  npm rebuild better-sqlite3\x1b[0m
+`);
+}
+
 // ── Resolve server entry ───────────────────────────────────
 const serverJs = join(APP_DIR, "server.js");
 
 if (!existsSync(serverJs)) {
-  console.error(
-    "\x1b[31m✖ Server not found at:\x1b[0m",
-    serverJs,
-  );
-  console.error(
-    "  This usually means the package was not built correctly.",
-  );
+  console.error("\x1b[31m✖ Server not found at:\x1b[0m", serverJs);
+  console.error("  This usually means the package was not built correctly.");
   console.error("  Try reinstalling: npm install -g omniroute");
   process.exit(1);
 }
@@ -99,14 +175,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",
@@ -119,7 +204,10 @@ server.stdout.on("data", (data) => {
   process.stdout.write(text);
 
   // Detect server ready
-  if (!started && (text.includes("Ready") || text.includes("started") || text.includes("listening"))) {
+  if (
+    !started &&
+    (text.includes("Ready") || text.includes("started") || text.includes("listening"))
+  ) {
     started = true;
     onReady();
   }
@@ -156,16 +244,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
   `);
@@ -173,7 +262,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,5 +1,7 @@
 # OmniRoute Architecture
 
+🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md)
+
 _Last updated: 2026-02-18_
 
 ## Executive Summary

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/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.
 
 ---
@@ -11,6 +13,8 @@ Common problems and solutions for OmniRoute.
 | First login not working       | Check `INITIAL_PASSWORD` in `.env` (default: `123456`)             |
 | Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` |
 | No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true`                                     |
+| 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)       |
 
 ---
 
@@ -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-tasks/01-home.md

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

docs/i18n-tasks/02-analytics.md

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

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

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

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

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

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

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

docs/i18n-tasks/06-combos.md

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

docs/i18n-tasks/07-costs.md

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

docs/i18n-tasks/08-endpoint.md

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

docs/i18n-tasks/09-health.md

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

docs/i18n-tasks/10-limits.md

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

docs/i18n-tasks/11-logs.md

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

docs/i18n-tasks/12-onboarding.md

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

docs/i18n-tasks/13-providers.md

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

docs/i18n-tasks/14-settings.md

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

docs/i18n-tasks/15-translator.md

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

docs/i18n-tasks/16-usage.md

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

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

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

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

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

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

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

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

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

docs/i18n-tasks/21-landing.md

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

docs/i18n-tasks/22-docs.md

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

docs/i18n-tasks/23-legal.md

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

docs/i18n-tasks/README.md

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

docs/i18n/README.md

@@ -0,0 +1,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`