chore(release): v3.3.7 — OpenCode config fix, i18n keys fix

Fix cloudflared quick tunnel startup in Docker

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

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

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

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

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

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

.agents/workflows/deploy-vps.md

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

.agents/workflows/generate-release.md

@@ -4,16 +4,36 @@ description: Create a new release, bump version up to 1.x.10 threshold, update c
 
 # Generate Release Workflow
 
-Bump version, finalize CHANGELOG, commit, tag, push, publish to npm, and create GitHub release.
+Bump version, finalize CHANGELOG, commit, open a **PR to main** and wait for user confirmation before tagging, publishing, and deploying.
 
 > **VERSION RULE: Always use PATCH bumps (2.x.y → 2.x.y+1)**
 > NEVER use `npm version minor` or `npm version major`.
 > Always use: `npm version patch --no-git-tag-version`
 > The threshold rule: when `y` reaches 10, bump to `2.(x+1).0` — e.g. `2.1.10` → `2.2.0`.
 
-## Steps
+---
 
-### 1. Determine new version
+## ⚠️ Two-Phase Flow
+
+```
+Phase 1 (automated): bump → docs → i18n → commit → push → open PR
+  ↕  🛑 STOP: Notify user, wait for PR confirmation
+Phase 2 (post-merge): tag → publish → GitHub release → Docker → deploy
+```
+
+**NEVER push directly to main or create tags before the user confirms the PR.**
+
+---
+
+## Phase 1: Pre-Merge
+
+### 1. Create release branch
+
+```bash
+git checkout -b release/v2.x.y
+```
+
+### 2. Determine new version
 
 Check current version in `package.json` and increment the **patch** number only:
 
@@ -27,12 +47,28 @@ Version format: `2.x.y` — examples:
 - `2.1.9` → `2.1.10` (patch)
 - `2.1.10` → `2.2.0` (minor threshold — do manually with `sed`)
 
-```bash
-# ALWAYS use patch:
-npm version patch --no-git-tag-version
-```
+> **⚠️ ATOMIC COMMIT RULE — Version bump MUST happen before committing feature files.**
+>
+> **CORRECT order:**
+>
+> 1. `npm version patch --no-git-tag-version` ← bump first
+> 2. implement features / fix bugs
+> 3. `git add -A && git commit -m "chore(release): v2.x.y — all changes in ONE commit"`
+>
+> **OR if features are already staged:**
+>
+> 1. implement features (do NOT commit yet)
+> 2. `npm version patch --no-git-tag-version` ← bump before committing
+> 3. `git add -A && git commit -m "chore(release): v2.x.y — all changes in ONE commit"`
+>
+> **NEVER do this (creates version mismatch in git history):**
+>
+> - ~~commit features → then bump version → commit package.json separately~~
+>
+> This ensures that `git show v2.x.y` always contains both code changes and the version bump together.
+> The GitHub release tag will point to a commit that includes ALL changes for that version.
 
-### 2. Regenerate lock file (REQUIRED after version bump)
+### 3. Regenerate lock file (REQUIRED after version bump)
 
 **Mandatory** — skipping causes `@swc/helpers` lock mismatch and CI failures:
 
@@ -40,7 +76,7 @@ npm version patch --no-git-tag-version
 npm install
 ```
 
-### 3. Finalize CHANGELOG.md
+### 4. Finalize CHANGELOG.md
 
 Replace `[Unreleased]` header with the new version and date.
 Keep an empty `## [Unreleased]` section above it.
@@ -53,58 +89,179 @@ Keep an empty `## [Unreleased]` section above it.
 ## [2.x.y] — YYYY-MM-DD
 ```
 
-### 4. Update openapi.yaml version ⚠️ MANDATORY
+### 5. Update openapi.yaml version ⚠️ MANDATORY
 
 > **CI will fail** if `docs/openapi.yaml` version ≠ `package.json` version (`check:docs-sync` enforces this).
 
 // turbo
 
 ```bash
-VERSION=$(node -p "require('./package.json').version") && sed -i "s/  version: .*/  version: $VERSION/" docs/openapi.yaml && echo "✓ openapi.yaml → $VERSION"
+VERSION=$(node -p "require('./package.json').version")
+sed -i "s/  version: .*/  version: $VERSION/" docs/openapi.yaml
+echo "✓ openapi.yaml → $VERSION"
+
+for dir in electron open-sse; do
+  if [ -d "$dir" ] && [ -f "$dir/package.json" ]; then
+    (cd "$dir" && npm version "$VERSION" --no-git-tag-version --allow-same-version > /dev/null)
+    echo "✓ $dir/package.json → $VERSION"
+  fi
+done
+# Re-run install to assert the workspace lockfile is updated
+npm install
 ```
 
-### 5. Stage, commit, and tag
+### 6. Update README.md and i18n docs
+
+Run `/update-docs` workflow steps to:
+
+- Update feature table rows in `README.md`
+- Sync changes to all 29 language `docs/i18n/*/README.md` files
+- Update `docs/FEATURES.md` if Settings section changed
+
+### 7. Run tests
+
+// turbo
+
+```bash
+npm test
+```
+
+All tests must pass before creating the PR.
+
+### 8. Stage, commit, and push
 
 // turbo-all
 
 ```bash
-git add package.json package-lock.json CHANGELOG.md docs/openapi.yaml
+git add -A
 git commit -m "chore(release): v2.x.y — summary of changes"
+git push origin release/v2.x.y
+```
+
+### 9. Open PR to main
+
+```bash
+gh pr create \
+  --repo diegosouzapw/OmniRoute \
+  --base main \
+  --head release/v2.x.y \
+  --title "chore(release): v2.x.y — summary" \
+  --body "## 🚀 Release v2.x.y
+
+### Changes
+...
+
+### Tests
+- X/X tests pass
+
+### ⚠️ After merging: run Phase 2 steps to tag, publish, and deploy."
+```
+
+### 10. 🛑 STOP — Notify User & Await PR Confirmation
+
+**This is a mandatory stop point.** Use `notify_user` with `BlockedOnUser: true`:
+
+Inform the user:
+
+- PR URL
+- Summary of changes
+- Test results
+- List of files changed
+
+**DO NOT proceed to Phase 2 until the user confirms the PR looks good and merges it.**
+
+---
+
+## Phase 2: Post-Merge (only after user confirms)
+
+> Run these steps only AFTER the user has merged the PR.
+
+### 11. Pull main and create tag
+
+```bash
+git checkout main
+git pull origin main
 git tag -a v2.x.y -m "Release v2.x.y"
 ```
 
-### 6. Push to GitHub
+### 12. Push tag to GitHub
 
 ```bash
-git push origin main --tags
+git push origin --tags
 ```
 
-### 7. Create GitHub release
+### 13. Create GitHub release
 
 ```bash
 gh release create v2.x.y --title "v2.x.y — summary" --notes "..."
 ```
 
-### 8. Deploy to VPS (if requested)
+### 14. 🐳 Trigger Docker Hub build (MANDATORY — keep npm and Docker in sync)
 
-See `/deploy-vps` workflow for Akamai VPS or use npm for local VPS:
+> **CRITICAL**: Docker Hub and npm MUST always publish the same version.
+> The Docker image is built automatically via GitHub Actions when a new tag is pushed.
+> After pushing the tag in step 11-12, **verify the workflow runs**:
 
 ```bash
-ssh root@<VPS_IP> "npm install -g omniroute@2.x.y && pm2 restart omniroute"
+# Verify the Docker workflow triggered
+gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 3
+
+# Wait for the Docker build to complete (usually 5–10 min)
+gh run watch --repo diegosouzapw/OmniRoute
+
+# After completion, verify on Docker Hub:
+# https://hub.docker.com/r/diegosouzapw/omniroute/tags
 ```
 
+If the Docker build was not triggered automatically, trigger it manually:
+
+```bash
+gh workflow run docker-publish.yml --repo diegosouzapw/OmniRoute --ref v2.x.y
+```
+
+### 15. Deploy to BOTH VPS environments (MANDATORY)
+
+> Always deploy to **both** environments after every release.
+> See `/deploy-vps` workflow for detailed steps.
+
+```bash
+# Build and pack locally
+cd /home/diegosouzapw/dev/proxys/9router && npm run build:cli && npm pack --ignore-scripts
+
+# Deploy to LOCAL VPS (192.168.0.15)
+scp omniroute-*.tgz root@192.168.0.15:/tmp/
+ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && pm2 restart omniroute && pm2 save"
+
+# Deploy to AKAMAI VPS (69.164.221.35)
+scp omniroute-*.tgz root@69.164.221.35:/tmp/
+ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && pm2 restart omniroute && pm2 save"
+
+# Verify both
+curl -s -o /dev/null -w "LOCAL:  HTTP %{http_code}\n" http://192.168.0.15:20128/
+curl -s -o /dev/null -w "AKAMAI: HTTP %{http_code}\n" http://69.164.221.35:20128/
+```
+
+### 16. Clean up release branch
+
+```bash
+git branch -d release/v2.x.y
+```
+
+---
+
 ## Notes
 
 - Always run `/update-docs` BEFORE this workflow (ensures CHANGELOG and README are current)
 - The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`
 - After npm publish, verify with `npm info omniroute version`
 - Lock file sync errors are caused by skipping `npm install` after version bump
+- Use `gh auth switch -u diegosouzapw` if git push fails with wrong account
 
 ## Known CI Pitfalls
 
 | CI failure                                                                | Cause                                                    | Fix                                                                    |
 | ------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `[docs-sync] FAIL - OpenAPI version differs from package.json`            | Skipped step 4 — `docs/openapi.yaml` version not updated | Run step 4 (`sed -i ...`) and commit                                   |
+| `[docs-sync] FAIL - OpenAPI version differs from package.json`            | Skipped step 5 — `docs/openapi.yaml` version not updated | Run step 5 (`sed -i ...`) and commit                                   |
 | `[docs-sync] FAIL - CHANGELOG.md first section must be "## [Unreleased]"` | `## [Unreleased]` missing or not at top of CHANGELOG     | Add `## [Unreleased]\n\n---\n` before the first versioned `## [x.y.z]` |
 | Electron Linux `.deb` build fails (`FpmTarget` error)                     | `fpm` Ruby gem not installed on `ubuntu-latest` runner   | Already fixed in `electron-release.yml` (`gem install fpm` step)       |
 | Docker Hub `502 error writing layer blob`                                 | Transient Docker Hub network error during ARM64 push     | Re-run the Docker publish workflow; no code change needed              |

.agents/workflows/resolve-issues.md

@@ -19,11 +19,21 @@ This workflow fetches all open issues from the project's GitHub repository, clas
 
 ### 2. Fetch All Open Issues
 
-// turbo
+// turbo-all
 
-- 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)
+**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. You MUST use the two-step approach below to guarantee **all** issues are fetched.
+
+**Step 2a — Get Issue numbers only** (small output, never truncated):
+
+- Run: `gh issue list --repo <owner>/<repo> --state open --limit 500 --json number --jq '.[].number'`
+- This outputs one issue number per line. Count them and confirm total.
+
+**Step 2b — Fetch full metadata for each Issue** (one call per issue):
+
+- For each issue number from step 2a, run:
+  `gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author`
+- You may batch these into parallel calls (up to 4 at a time).
+- Sort by oldest first (FIFO).
 
 ### 3. Classify Each Issue
 

.agents/workflows/review-discussions.md

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

.agents/workflows/review-prs.md

@@ -18,13 +18,35 @@ This workflow fetches all open PRs from the project's GitHub repository, perform
 
 ### 2. Fetch Open Pull Requests
 
-- Navigate to `https://github.com/<owner>/<repo>/pulls` and scrape all open PRs
+// turbo-all
+
+**⚠️ CRITICAL**: The JSON output of `gh pr list` can be truncated by the tool, silently hiding PRs. You MUST use the two-step approach below to guarantee **all** PRs are fetched.
+
+**Step 2a — Get PR numbers only** (small output, never truncated):
+
+- Run: `gh pr list --repo <owner>/<repo> --state open --limit 500 --json number --jq '.[].number'`
+- This outputs one PR number per line. Count them and confirm total.
+
+**Step 2b — Fetch full metadata for each PR** (one call per PR):
+
+- For each PR number from step 2a, run:
+  `gh pr view <NUMBER> --repo <owner>/<repo> --json number,title,author,headRefName,body,createdAt,additions,deletions,files`
+- You may batch these into parallel calls (up to 4 at a time).
+
+**Step 2c — Fetch diffs for each PR** (one call per PR, saved to /tmp):
+
+- For each PR number, run:
+  `gh pr diff <NUMBER> --repo <owner>/<repo> > /tmp/pr<NUMBER>.diff`
+- Then read each diff file with `view_file`.
+
 - 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)
 
+**Verification**: Confirm the count of PRs analyzed matches the count from step 2a before proceeding.
+
 ### 3. Analyze Each PR — For each open PR, perform the following analysis:
 
 #### 3a. Feature Assessment

.agents/workflows/update-docs.md

@@ -56,13 +56,13 @@ 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
+README.ja.md README.ko.md README.zh-CN.md README.phi.md README.cs.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}/
+docs/i18n/{ar,bg,cs,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
 ```
 

.env.example

@@ -40,6 +40,7 @@ MACHINE_ID_SALT=endpoint-proxy-salt
 ENABLE_REQUEST_LOGS=false
 AUTH_COOKIE_SECURE=false
 REQUIRE_API_KEY=false
+ALLOW_API_KEY_REVEAL=false
 
 # Input Sanitizer (FASE-01 — prompt injection & PII protection)
 # INPUT_SANITIZER_ENABLED=true
@@ -142,10 +143,32 @@ 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
+QWEN_USER_AGENT=QwenCode/0.12.3 (linux; x64)
 CURSOR_USER_AGENT=connect-es/1.6.1
 GEMINI_CLI_USER_AGENT=google-api-nodejs-client/9.15.1
 
+# ─────────────────────────────────────────────────────────────────────────────
+# CLI Fingerprint Compatibility (optional — match native CLI binary signatures)
+# ─────────────────────────────────────────────────────────────────────────────
+# When enabled, OmniRoute reorders HTTP headers and JSON body fields to match
+# the exact signature of official CLI tools, reducing account flagging risk.
+# Your proxy IP is preserved — you get both stealth AND IP masking.
+#
+# Enable per-provider:
+# CLI_COMPAT_CODEX=1
+# CLI_COMPAT_CLAUDE=1
+# CLI_COMPAT_GITHUB=1
+# CLI_COMPAT_ANTIGRAVITY=1
+# CLI_COMPAT_KIRO=1
+# CLI_COMPAT_CURSOR=1
+# CLI_COMPAT_KIMI_CODING=1
+# CLI_COMPAT_KILOCODE=1
+# CLI_COMPAT_CLINE=1
+# CLI_COMPAT_QWEN=1
+#
+# Or enable for all providers at once:
+# CLI_COMPAT_ALL=1
+
 # API Key Providers (Phase 1 + Phase 4)
 # Add via Dashboard → Providers → Add API Key, or set here
 # DEEPSEEK_API_KEY=
@@ -166,6 +189,8 @@ GEMINI_CLI_USER_AGENT=google-api-nodejs-client/9.15.1
 # Timeout settings
 # FETCH_TIMEOUT_MS=120000
 # STREAM_IDLE_TIMEOUT_MS=60000
+# API bridge timeout for /v1 proxy requests (default: 30000)
+# API_BRIDGE_PROXY_TIMEOUT_MS=120000
 
 # CORS configuration (default: * allows all origins)
 # CORS_ORIGINS=*

.github/ISSUE_TEMPLATE/bug_report.yml

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

.github/ISSUE_TEMPLATE/config.yml

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

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,70 @@
+name: Feature Request
+description: Suggest a new feature or improvement for OmniRoute
+title: "[Feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please describe the problem you're trying to solve and how you'd like it to work.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Use Case
+      description: "What problem does this feature solve? Why do you need it?"
+      placeholder: "I'm trying to ... but currently ..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: "How would you like this to work?"
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: "Have you considered any workarounds or alternative approaches?"
+    validations:
+      required: false
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: "Which part of OmniRoute does this relate to?"
+      multiple: true
+      options:
+        - Dashboard / UI
+        - Proxy / Routing
+        - Provider Support
+        - CLI Tools Integration
+        - OAuth / Authentication
+        - Analytics / Usage Tracking
+        - Docker / Deployment
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: provider
+    attributes:
+      label: Related Provider(s)
+      description: "If this relates to specific providers, list them."
+      placeholder: "e.g. Antigravity, OpenRouter, Ollama"
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: "Any other context, mockups, or references."
+    validations:
+      required: false

.github/workflows/ci.yml

@@ -18,8 +18,8 @@ jobs:
     name: Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: 22
           cache: npm
@@ -36,8 +36,8 @@ jobs:
     name: Security Audit
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: 22
           cache: npm
@@ -55,8 +55,8 @@ jobs:
       matrix:
         node-version: [20, 22]
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
           cache: npm
@@ -74,8 +74,8 @@ jobs:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
           cache: npm
@@ -90,8 +90,8 @@ jobs:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: 22
           cache: npm
@@ -109,8 +109,8 @@ jobs:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: 22
           cache: npm
@@ -129,8 +129,8 @@ jobs:
       INITIAL_PASSWORD: ci-test-password-for-integration
       DATA_DIR: /tmp/omniroute-ci
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: 22
           cache: npm
@@ -145,8 +145,8 @@ jobs:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: 22
           cache: npm

.github/workflows/docker-publish.yml

@@ -1,11 +1,21 @@
 name: Publish to Docker Hub
 
 on:
+  push:
+    branches:
+      - main
   release:
     types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version tag to build (e.g. 2.6.0)"
+        required: true
+        type: string
 
 permissions:
   contents: read
+  packages: write
 
 jobs:
   docker:
@@ -15,7 +25,9 @@ jobs:
       IMAGE_NAME: diegosouzapw/omniroute
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/v{0}', inputs.version) || '' }}
 
       - name: Set up QEMU (for multi-arch builds)
         uses: docker/setup-qemu-action@v3
@@ -24,21 +36,32 @@ jobs:
         uses: docker/setup-buildx-action@v3
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v4
+        uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      - name: Extract version from release tag
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract version from release tag or input
         id: version
         run: |
-          VERSION="${GITHUB_REF_NAME}"
-          VERSION="${VERSION#v}"
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION="${{ inputs.version }}"
+          else
+            VERSION="${GITHUB_REF_NAME}"
+            VERSION="${VERSION#v}"
+          fi
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
           echo "Publishing Docker image: $IMAGE_NAME:$VERSION"
 
       - name: Build and push multi-arch image
-        uses: docker/build-push-action@v7
+        uses: docker/build-push-action@v6
         with:
           context: .
           target: runner-base
@@ -47,6 +70,8 @@ jobs:
           tags: |
             ${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }}
             ${{ env.IMAGE_NAME }}:latest
+            ghcr.io/diegosouzapw/omniroute:${{ steps.version.outputs.version }}
+            ghcr.io/diegosouzapw/omniroute:latest
           cache-from: type=gha
           cache-to: type=gha,mode=max
           no-cache: false
@@ -58,7 +83,7 @@ jobs:
           docker buildx imagetools inspect "${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }}"
 
       - name: Update Docker Hub description
-        uses: peter-evans/dockerhub-description@v5
+        uses: peter-evans/dockerhub-description@v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}

.github/workflows/electron-release.yml

@@ -13,6 +13,8 @@ on:
 
 permissions:
   contents: write
+  id-token: write
+  packages: write
 
 jobs:
   validate:
@@ -22,7 +24,7 @@ jobs:
       version: ${{ steps.validate.outputs.version }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
@@ -70,16 +72,16 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4
 
       - name: Setup Node.js
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v4
         with:
           node-version: 22
           cache: npm
 
       - name: Cache node_modules
-        uses: actions/cache@v5
+        uses: actions/cache@v4
         with:
           path: node_modules
           key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
@@ -146,7 +148,7 @@ jobs:
           fi
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v4
         with:
           name: electron-${{ matrix.platform }}
           path: release-assets/
@@ -157,12 +159,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
       - name: Download all artifacts
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@v4
         with:
           path: release-assets
           merge-multiple: true
@@ -201,3 +203,13 @@ jobs:
             release-assets/*.source.zip
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-npm:
+    name: Publish to npm
+    needs: [validate, release]
+    uses: ./.github/workflows/npm-publish.yml
+    with:
+      version: ${{ needs.validate.outputs.version }}
+      tag: latest
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/npm-publish.yml

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

.github/workflows/sync-upstream.yml

@@ -0,0 +1,43 @@
+name: Sync Upstream
+
+on:
+  schedule:
+    # Run every 6 hours
+    - cron: '0 */6 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  sync:
+    name: Sync with upstream
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Fetch upstream
+        run: |
+          git remote add upstream https://github.com/diegosouzapw/OmniRoute.git || true
+          git fetch upstream
+          git fetch origin
+
+      - name: Sync main branch
+        run: |
+          git checkout main
+          git merge upstream/main --no-edit || {
+            echo "Merge conflict detected. Manual intervention required."
+            exit 1
+          }
+
+      - name: Push changes
+        run: git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/tombii/OmniRoute.git main

.gitignore

@@ -55,6 +55,8 @@ logs/*
 # analysis directories (generated, not tracked)
 .analysis/
 antigravity-manager-analysis/
+.sisyphus/
+.plans/
 
 # docs (allow specific tracked files)
 docs/*
@@ -87,6 +89,7 @@ docs/*
 !docs/MCP-SERVER.md
 !docs/CLI-TOOLS.md
 
+
 # open-sse tests
 open-sse/test/*
 
@@ -109,6 +112,7 @@ app.log
 
 # Backup directories
 app.__qa_backup/
+.app-build-backup-*/
 
 # Production standalone build (created by scripts/prepublish.mjs)
 # Conflicts with Next.js App Router detection in dev (root app/ shadows src/app/)
@@ -128,3 +132,6 @@ vscode-extension/
 *.sqlite-shm
 *.sqlite-wal
 *.sqlite-journal
+
+# Compiled npm-package build artifact (not source, should not be in git)
+/app

.husky/pre-commit

@@ -1 +1,3 @@
 npx lint-staged
+node scripts/check-docs-sync.mjs
+npm run test:unit

.npmignore

@@ -3,6 +3,11 @@ data/
 **/data/
 **/db.json
 
+# VS Code extension test runtime (large binary, not needed in npm package)
+app/vscode-extension/
+**/data/
+**/db.json
+
 # Source code (pre-built app/ is published instead)
 src/
 open-sse/
@@ -42,3 +47,12 @@ AGENTS.md
 # Build artifacts (pre-built goes inside app/)
 .next/
 node_modules/
+
+# Ignore large binary files and other build directories
+*.tgz
+*.AppImage
+*.deb
+*.rpm
+electron/
+app/electron/
+app/vscode-extension/

AGENTS.md

@@ -49,19 +49,22 @@ but the real logic lives in `src/lib/db/`.
 
 Translation between provider formats: `open-sse/translator/`
 
+**Upstream model extra headers** (`compatByProtocol` / custom models): merged in executors after default auth; **same header name replaces** the executor value (e.g. custom `Authorization` overrides Bearer). In `open-sse/handlers/chatCore.ts`, the primary request merges headers for **both** the client model id and `resolveModelAlias(clientModel)` (resolved id wins on key conflicts). **T5 intra-family fallback** recomputes headers using only the fallback model id and `resolveModelAlias(fallback)` so sibling models do not inherit another model’s headers. Forbidden header names live in `src/shared/constants/upstreamHeaders.ts` — keep sanitize (`models.ts`), Zod (`schemas.ts`), and unit tests aligned when editing that list.
+
 ### MCP Server (`open-sse/mcp-server/`)
 
 16 tools for AI agent control via **3 transport modes**:
+
 - **stdio** — Local IDE integration (Claude Desktop, Cursor, VS Code)
 - **SSE** — Remote Server-Sent Events at `/api/mcp/sse`
 - **Streamable HTTP** — Modern bidirectional HTTP at `/api/mcp/stream`
 
 HTTP transports run in-process via `httpTransport.ts` singleton using `WebStandardStreamableHTTPServerTransport`.
 
-| Category   | Tools                                                                                                                     |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------- |
-| Essential  | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog` |
-| Advanced   | `simulate_route`, `set_budget_guard`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot` |
+| Category  | Tools                                                                                                                                                                |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Essential | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`                               |
+| Advanced  | `simulate_route`, `set_budget_guard`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot` |
 
 - Scoped authorization (9 scopes), audit logging, Zod schemas
 - IDE configs for Claude Desktop, Cursor, VS Code Copilot
@@ -79,25 +82,26 @@ Agent-to-Agent v0.3 protocol:
 ### Auto-Combo Engine (`open-sse/services/autoCombo/`)
 
 Self-healing routing optimization:
+
 - 6-factor scoring, 4 mode packs, bandit exploration
 - Progressive cooldown, probe-based re-admission
 
 ### Dashboard (`src/app/(dashboard)/`)
 
-| Page                         | Description                                                    |
-| ---------------------------- | -------------------------------------------------------------- |
-| `/dashboard`                 | Home with quick start, provider overview                       |
-| `/dashboard/endpoint`        | **Endpoints** (tabbed): Endpoint Proxy, MCP, A2A, API Endpoints |
-| `/dashboard/providers`       | Provider management and connections                            |
-| `/dashboard/combos`          | Combo configurations with routing strategies                   |
-| `/dashboard/logs`            | Request, Proxy, Audit, Console logs (tabbed)                   |
-| `/dashboard/analytics`       | Usage analytics and evaluations                                |
-| `/dashboard/costs`           | Cost tracking and breakdown                                    |
-| `/dashboard/health`          | Uptime, circuit breakers, latency                              |
-| `/dashboard/cli-tools`       | CLI tool integrations (Claude, Codex, Antigravity, etc.)       |
-| `/dashboard/media`           | Image, Video, Music generation playground                      |
-| `/dashboard/settings`        | System settings with multiple tabs                             |
-| `/dashboard/api-manager`     | API key management with model permissions                      |
+| Page                     | Description                                                     |
+| ------------------------ | --------------------------------------------------------------- |
+| `/dashboard`             | Home with quick start, provider overview                        |
+| `/dashboard/endpoint`    | **Endpoints** (tabbed): Endpoint Proxy, MCP, A2A, API Endpoints |
+| `/dashboard/providers`   | Provider management and connections                             |
+| `/dashboard/combos`      | Combo configurations with routing strategies                    |
+| `/dashboard/logs`        | Request, Proxy, Audit, Console logs (tabbed)                    |
+| `/dashboard/analytics`   | Usage analytics and evaluations                                 |
+| `/dashboard/costs`       | Cost tracking and breakdown                                     |
+| `/dashboard/health`      | Uptime, circuit breakers, latency                               |
+| `/dashboard/cli-tools`   | CLI tool integrations (Claude, Codex, Antigravity, etc.)        |
+| `/dashboard/media`       | Image, Video, Music generation playground                       |
+| `/dashboard/settings`    | System settings with multiple tabs                              |
+| `/dashboard/api-manager` | API key management with model permissions                       |
 
 ### OAuth & Tokens (`src/lib/oauth/`)
 

CONTRIBUTING.md

@@ -114,6 +114,7 @@ npm run test:fixes        # Fix verification tests
 
 # With coverage
 npm run test:coverage
+npm run coverage:report
 
 # E2E tests (requires Playwright)
 npm run test:e2e
@@ -123,7 +124,13 @@ npm run lint
 npm run check
 ```
 
-Current test status: **368+ unit tests** covering:
+Coverage notes:
+
+- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**`
+- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run
+- `npm run test:coverage:legacy` preserves the older metric for historical comparison
+
+Current test status: **968+ unit tests** covering:
 
 - Provider translators and format conversion
 - Rate limiting, circuit breaker, and resilience

COVERAGE_PLAN.md

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

Dockerfile

@@ -1,13 +1,17 @@
 FROM node:22-bookworm-slim AS builder
 WORKDIR /app
 
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends libsecret-1-0 ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
+
 COPY package*.json ./
 COPY scripts/postinstall.mjs ./scripts/postinstall.mjs
 COPY scripts/native-binary-compat.mjs ./scripts/native-binary-compat.mjs
 RUN if [ -f package-lock.json ]; then npm ci --no-audit --no-fund; else npm install --no-audit --no-fund; fi
 
 COPY . ./
-RUN mkdir -p /app/data && npm run build
+RUN mkdir -p /app/data && npm run build -- --webpack
 
 FROM node:22-bookworm-slim AS runner-base
 WORKDIR /app
@@ -25,6 +29,9 @@ ENV NODE_OPTIONS="--max-old-space-size=256"
 
 # Data directory inside Docker — must match the volume mount in docker-compose.yml
 ENV DATA_DIR=/app/data
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends libsecret-1-0 ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
 RUN mkdir -p /app/data
 
 COPY --from=builder /app/public ./public
@@ -32,6 +39,11 @@ COPY --from=builder /app/.next/static ./.next/static
 COPY --from=builder /app/.next/standalone ./
 # Explicitly copy @swc/helpers — not always traced by standalone output but needed at runtime
 COPY --from=builder /app/node_modules/@swc/helpers ./node_modules/@swc/helpers
+# Explicitly copy pino transport dependencies — pino spawns a worker that requires
+# pino-abstract-transport at runtime; Next.js standalone trace does not capture it (#449)
+COPY --from=builder /app/node_modules/pino-abstract-transport ./node_modules/pino-abstract-transport
+COPY --from=builder /app/node_modules/pino-pretty ./node_modules/pino-pretty
+COPY --from=builder /app/node_modules/split2 ./node_modules/split2
 COPY --from=builder /app/scripts/run-standalone.mjs ./run-standalone.mjs
 COPY --from=builder /app/scripts/runtime-env.mjs ./runtime-env.mjs
 COPY --from=builder /app/scripts/bootstrap-env.mjs ./bootstrap-env.mjs
@@ -48,7 +60,7 @@ FROM runner-base AS runner-cli
 
 # Install system dependencies required by openclaw (git+ssh references).
 RUN apt-get update \
-  && apt-get install -y --no-install-recommends git ca-certificates \
+  && apt-get install -y --no-install-recommends git ca-certificates docker.io docker-compose \
   && rm -rf /var/lib/apt/lists/* \
   && git config --system url."https://github.com/".insteadOf "ssh://git@github.com/"
 

README.md

@@ -2,16 +2,18 @@
 
 ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
 
-_Your universal API proxy — one endpoint, 36+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
 
-**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • MCP Server • A2A Protocol • 100% TypeScript**
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
 
 ---
 
 <div align="center">
 
 [![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
+[![npm downloads](https://img.shields.io/npm/dm/omniroute?color=cb3837&logo=npm&label=npm%20downloads)](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)
+[![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute?logo=docker&color=2496ED&label=docker%20pulls)](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)
@@ -20,7 +22,29 @@ _Your universal API proxy — one endpoint, 36+ providers, zero downtime. Now wi
 
 </div>
 
-🌐 **Available in:** 🇺🇸 [English](README.md) | 🇧🇷 [Português (Brasil)](docs/i18n/pt-BR/README.md) | 🇪🇸 [Español](docs/i18n/es/README.md) | 🇫🇷 [Français](docs/i18n/fr/README.md) | 🇮🇹 [Italiano](docs/i18n/it/README.md) | 🇷🇺 [Русский](docs/i18n/ru/README.md) | 🇨🇳 [中文 (简体)](docs/i18n/zh-CN/README.md) | 🇩🇪 [Deutsch](docs/i18n/de/README.md) | 🇮🇳 [हिन्दी](docs/i18n/in/README.md) | 🇹🇭 [ไทย](docs/i18n/th/README.md) | 🇺🇦 [Українська](docs/i18n/uk-UA/README.md) | 🇸🇦 [العربية](docs/i18n/ar/README.md) | 🇯🇵 [日本語](docs/i18n/ja/README.md) | 🇻🇳 [Tiếng Việt](docs/i18n/vi/README.md) | 🇧🇬 [Български](docs/i18n/bg/README.md) | 🇩🇰 [Dansk](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [Magyar](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonesia](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nederlands](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugal)](docs/i18n/pt/README.md) | 🇷🇴 [Română](docs/i18n/ro/README.md) | 🇵🇱 [Polski](docs/i18n/pl/README.md) | 🇸🇰 [Slovenčina](docs/i18n/sk/README.md) | 🇸🇪 [Svenska](docs/i18n/sv/README.md) | 🇵🇭 [Filipino](docs/i18n/phi/README.md)
+🌐 **Available in:** 🇺🇸 [English](README.md) | 🇧🇷 [Português (Brasil)](docs/i18n/pt-BR/README.md) | 🇪🇸 [Español](docs/i18n/es/README.md) | 🇫🇷 [Français](docs/i18n/fr/README.md) | 🇮🇹 [Italiano](docs/i18n/it/README.md) | 🇷🇺 [Русский](docs/i18n/ru/README.md) | 🇨🇳 [中文 (简体)](docs/i18n/zh-CN/README.md) | 🇩🇪 [Deutsch](docs/i18n/de/README.md) | 🇮🇳 [हिन्दी](docs/i18n/in/README.md) | 🇹🇭 [ไทย](docs/i18n/th/README.md) | 🇺🇦 [Українська](docs/i18n/uk-UA/README.md) | 🇸🇦 [العربية](docs/i18n/ar/README.md) | 🇯🇵 [日本語](docs/i18n/ja/README.md) | 🇻🇳 [Tiếng Việt](docs/i18n/vi/README.md) | 🇧🇬 [Български](docs/i18n/bg/README.md) | 🇩🇰 [Dansk](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [Magyar](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonesia](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nederlands](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugal)](docs/i18n/pt/README.md) | 🇷🇴 [Română](docs/i18n/ro/README.md) | 🇵🇱 [Polski](docs/i18n/pl/README.md) | 🇸🇰 [Slovenčina](docs/i18n/sk/README.md) | 🇸🇪 [Svenska](docs/i18n/sv/README.md) | 🇵🇭 [Filipino](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area                         | Change                                                                                                                                                                    |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security**       | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation                                                                               |
+| ✅ **Route Validation**      | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes                                                             |
+| 🐛 **omniModel Tag Leak**    | Internal `<omniModel>` tags no longer leak to clients in SSE streaming responses (#585)                                                                                   |
+| 🔑 **Registered Keys API**   | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons**        | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain                                                                                          |
+| 🔄 **Model Auto-Sync**       | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers                                                                |
+| 🌐 **OpenCode Zen/Go**       | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor`                                                                     |
+| 🐛 **Gemini CLI OAuth**      | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error)                                                                        |
+| 🐛 **OpenCode config**       | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME`                                                                                                     |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection                                                                                                   |
+| 🐛 **Codex/Claude loop**     | `tool_result` blocks now converted to text to stop infinite loops                                                                                                         |
+| 🐛 **Login redirect**        | Login no longer freezes after skipping password setup                                                                                                                     |
+| 🐛 **Windows paths**         | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically                                                                                                      |
 
 ---
 
@@ -234,7 +258,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If
 
 **How OmniRoute solves it:**
 
-- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 36+ providers
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
@@ -268,10 +292,10 @@ Not everyone can pay $20–200/month for AI subscriptions. Students, devs from e
 
 **How OmniRoute solves it:**
 
-- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (8 unlimited models), Qwen (3 unlimited models), Kiro (Claude for free), Gemini CLI (180K/month free)
+- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)
 - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/<model>` prefix
 - **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime
-- **NVIDIA NIM Free Credits** — 1000 free credits integrated
+- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)
 - **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider
 
 </details>
@@ -320,7 +344,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code..
 - **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
+- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 67+ providers
 
 </details>
 
@@ -702,6 +726,22 @@ Outcome: deep fallback depth for deadline-critical workloads
 
 ---
 
+## 🆓 Start Free — Zero Configuration Cost
+
+> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.
+
+| Step | Action                                             | Providers Unlocked                                                 |
+| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |
+| 1    | Connect **Kiro** (AWS Builder ID OAuth)            | Claude Sonnet 4.5, Haiku 4.5 — **unlimited**                       |
+| 2    | Connect **iFlow** (Google OAuth)                   | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3    | Connect **Qwen** (Device Code)                     | qwen3-coder-plus, qwen3-coder-flash... — **unlimited**             |
+| 4    | Connect **Gemini CLI** (Google OAuth)              | gemini-3-flash, gemini-2.5-pro — **180K/mo free**                  |
+| 5    | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically                       |
+
+**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.
+
+> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).
+
 ## ⚡ Quick Start
 
 ### 1) Install and run
@@ -711,6 +751,14 @@ npm install -g omniroute
 omniroute
 ```
 
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g   # Select all packages → approve
+> omniroute
+> ```
+
 Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
 
 | Command                 | Description                                                 |
@@ -828,6 +876,44 @@ docker compose --profile base up -d
 docker compose --profile cli up -d
 ```
 
+Dashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.
+
+Notes:
+
+- Quick Tunnel URLs are temporary and change after every restart.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.
+- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.
+
+**Using Docker Compose with Caddy (HTTPS Auto-TLS):**
+
+OmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.
+
+```yaml
+services:
+  omniroute:
+    image: diegosouzapw/omniroute:latest
+    container_name: omniroute
+    restart: unless-stopped
+    volumes:
+      - omniroute-data:/app/data
+    environment:
+      - PORT=20128
+      - NEXT_PUBLIC_BASE_URL=https://your-domain.com
+
+  caddy:
+    image: caddy:latest
+    container_name: caddy
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128
+
+volumes:
+  omniroute-data:
+```
+
 | Image                    | Tag      | Size   | Description           |
 | ------------------------ | -------- | ------ | --------------------- |
 | `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |
@@ -874,34 +960,223 @@ When minimized, OmniRoute lives in your system tray with quick actions:
 
 ## 💰 Pricing at a Glance
 
-| Tier                | Provider          | Cost                    | Quota Reset      | Best For             |
-| ------------------- | ----------------- | ----------------------- | ---------------- | -------------------- |
-| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo                  | 5h + weekly      | Already subscribed   |
-|                     | Codex (Plus/Pro)  | $20-200/mo              | 5h + weekly      | OpenAI users         |
-|                     | Gemini CLI        | **FREE**                | 180K/mo + 1K/day | Everyone!            |
-|                     | GitHub Copilot    | $10-19/mo               | Monthly          | GitHub users         |
-| **🔑 API KEY**      | NVIDIA NIM        | **FREE** (1000 credits) | One-time         | Free tier testing    |
-|                     | DeepSeek          | Pay-per-use             | None             | Best price/quality   |
-|                     | Groq              | Free tier + paid        | Rate limited     | Ultra-fast inference |
-|                     | xAI (Grok)        | Pay-per-use             | None             | Grok models          |
-|                     | Mistral           | Free tier + paid        | Rate limited     | European AI          |
-|                     | OpenRouter        | Pay-per-use             | None             | 100+ models          |
-| **💰 CHEAP**        | GLM-4.7           | $0.6/1M                 | Daily 10AM       | Budget backup        |
-|                     | MiniMax M2.1      | $0.2/1M                 | 5-hour rolling   | Cheapest option      |
-|                     | Kimi K2           | $9/mo flat              | 10M tokens/mo    | Predictable cost     |
-| **🆓 FREE**         | iFlow             | $0                      | Unlimited        | 8 models free        |
-|                     | Qwen              | $0                      | Unlimited        | 3 models free        |
-|                     | Kiro              | $0                      | Unlimited        | Claude free          |
+| Tier                | Provider                    | Cost                      | Quota Reset      | Best For                          |
+| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |
+| **💳 SUBSCRIPTION** | Claude Code (Pro)           | $20/mo                    | 5h + weekly      | Already subscribed                |
+|                     | Codex (Plus/Pro)            | $20-200/mo                | 5h + weekly      | OpenAI users                      |
+|                     | Gemini CLI                  | **FREE**                  | 180K/mo + 1K/day | Everyone!                         |
+|                     | GitHub Copilot              | $10-19/mo                 | Monthly          | GitHub users                      |
+| **🔑 API KEY**      | NVIDIA NIM                  | **FREE** (dev forever)    | ~40 RPM          | 70+ open models                   |
+|                     | Cerebras                    | **FREE** (1M tok/day)     | 60K TPM / 30 RPM | World's fastest                   |
+|                     | Groq                        | **FREE** (30 RPM)         | 14.4K RPD        | Ultra-fast Llama/Gemma            |
+|                     | DeepSeek V3.2               | $0.27/$1.10 per 1M        | None             | Best price/quality reasoning      |
+|                     | xAI Grok-4 Fast             | **$0.20/$0.50 per 1M** 🆕 | None             | Fastest + tool calling, ultralow  |
+|                     | xAI Grok-4 (standard)       | $0.20/$1.50 per 1M 🆕     | None             | Reasoning flagship from xAI       |
+|                     | Mistral                     | Free trial + paid         | Rate limited     | European AI                       |
+|                     | OpenRouter                  | Pay-per-use               | None             | 100+ models aggr.                 |
+| **💰 CHEAP**        | GLM-5 (via Z.AI) 🆕         | $0.5/1M                   | Daily 10AM       | 128K output, newest flagship      |
+|                     | GLM-4.7                     | $0.6/1M                   | Daily 10AM       | Budget backup                     |
+|                     | MiniMax M2.5 🆕             | $0.3/1M input             | 5-hour rolling   | Reasoning + agentic tasks         |
+|                     | MiniMax M2.1                | $0.2/1M                   | 5-hour rolling   | Cheapest option                   |
+|                     | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use               | None             | Direct Moonshot API access        |
+|                     | Kimi K2                     | $9/mo flat                | 10M tokens/mo    | Predictable cost                  |
+| **🆓 FREE**         | iFlow                       | **$0**                    | Unlimited        | 5 models unlimited                |
+|                     | Qwen                        | **$0**                    | Unlimited        | 4 models unlimited                |
+|                     | Kiro                        | **$0**                    | Unlimited        | Claude Sonnet/Haiku (AWS Builder) |
+|                     | LongCat Flash-Lite 🆕       | **$0** (50M tok/day 🔥)   | 1 RPS            | Largest free quota on Earth       |
+|                     | Pollinations AI 🆕          | **$0** (no key needed)    | 1 req/15s        | GPT-5, Claude, DeepSeek, Llama 4  |
+|                     | Cloudflare Workers AI 🆕    | **$0** (10K Neurons/day)  | ~150 resp/day    | 50+ models, global edge           |
+|                     | Scaleway AI 🆕              | **$0** (1M tokens total)  | Rate limited     | EU/GDPR, Qwen3 235B, Llama 70B    |
 
-**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost!
+> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.
+
+**💡 $0 Combo Stack — The Complete Free Setup:**
+
+```
+# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever
+Kiro (kr/)             → Claude Sonnet/Haiku UNLIMITED
+iFlow (if/)            → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED
+LongCat Lite (lc/)     → LongCat-Flash-Lite — 50M tokens/day 🔥
+Pollinations (pol/)    → GPT-5, Claude, DeepSeek, Llama 4 — no key needed
+Qwen (qw/)             → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED
+Gemini (gemini/)       → Gemini 2.5 Flash — 1,500 req/day free API key
+Cloudflare AI (cf/)    → Llama 70B, Gemma 3, Mistral — 10K Neurons/day
+Scaleway (scw/)        → Qwen3 235B, Llama 70B — 1M free tokens (EU)
+Groq (groq/)           → Llama/Gemma ultra-fast — 14.4K req/day
+NVIDIA NIM (nvidia/)   → 70+ open models — 40 RPM forever
+Cerebras (cerebras/)   → Llama/Qwen world-fastest — 1M tok/day
+```
+
+**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.
 
 ---
 
+---
+
+## 🆓 Free Models — What You Actually Get
+
+> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.
+
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
+
+| Model               | Prefix | Limit         | Rate Limit            |
+| ------------------- | ------ | ------------- | --------------------- |
+| `claude-sonnet-4.5` | `kr/`  | **Unlimited** | No reported daily cap |
+| `claude-haiku-4.5`  | `kr/`  | **Unlimited** | No reported daily cap |
+| `claude-opus-4.6`   | `kr/`  | **Unlimited** | Latest Opus via Kiro  |
+
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
+
+| Model              | Prefix | Limit         | Rate Limit      |
+| ------------------ | ------ | ------------- | --------------- |
+| `kimi-k2-thinking` | `if/`  | **Unlimited** | No reported cap |
+| `qwen3-coder-plus` | `if/`  | **Unlimited** | No reported cap |
+| `deepseek-r1`      | `if/`  | **Unlimited** | No reported cap |
+| `minimax-m2.1`     | `if/`  | **Unlimited** | No reported cap |
+| `kimi-k2`          | `if/`  | **Unlimited** | No reported cap |
+
+### 🟡 QWEN MODELS (Device Code Auth)
+
+| Model               | Prefix | Limit         | Rate Limit          |
+| ------------------- | ------ | ------------- | ------------------- |
+| `qwen3-coder-plus`  | `qw/`  | **Unlimited** | No reported cap     |
+| `qwen3-coder-flash` | `qw/`  | **Unlimited** | No reported cap     |
+| `qwen3-coder-next`  | `qw/`  | **Unlimited** | No reported cap     |
+| `vision-model`      | `qw/`  | **Unlimited** | Multimodal (images) |
+
+### 🟣 GEMINI CLI (Google OAuth)
+
+| Model                    | Prefix | Limit                       | Rate Limit    |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/`  | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro`         | `gc/`  | 180K/month (shared pool)    | High quality  |
+
+### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)
+
+| Tier       | Daily Limit  | Rate Limit  | Notes                                                  |
+| ---------- | ------------ | ----------- | ------------------------------------------------------ |
+| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |
+
+Popular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`
+
+### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)
+
+| Tier | Daily Limit       | Rate Limit       | Notes                                       |
+| ---- | ----------------- | ---------------- | ------------------------------------------- |
+| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |
+
+Available free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`
+
+### 🔴 GROQ (Free API Key — console.groq.com)
+
+| Tier | Daily Limit   | Rate Limit       | Notes                                     |
+| ---- | ------------- | ---------------- | ----------------------------------------- |
+| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |
+
+Available free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`
+
+### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕
+
+| Model                         | Prefix | Daily Free Quota  | Notes                   |
+| ----------------------------- | ------ | ----------------- | ----------------------- |
+| `LongCat-Flash-Lite`          | `lc/`  | **50M tokens** 💥 | Largest free quota ever |
+| `LongCat-Flash-Chat`          | `lc/`  | 500K tokens       | Multi-turn chat         |
+| `LongCat-Flash-Thinking`      | `lc/`  | 500K tokens       | Reasoning / CoT         |
+| `LongCat-Flash-Thinking-2601` | `lc/`  | 500K tokens       | Jan 2026 version        |
+| `LongCat-Flash-Omni-2603`     | `lc/`  | 500K tokens       | Multimodal              |
+
+> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.
+
+### 🟢 POLLINATIONS AI (No API Key Required) 🆕
+
+| Model      | Prefix | Rate Limit | Provider Behind    |
+| ---------- | ------ | ---------- | ------------------ |
+| `openai`   | `pol/` | 1 req/15s  | GPT-5              |
+| `claude`   | `pol/` | 1 req/15s  | Anthropic Claude   |
+| `gemini`   | `pol/` | 1 req/15s  | Google Gemini      |
+| `deepseek` | `pol/` | 1 req/15s  | DeepSeek V3        |
+| `llama`    | `pol/` | 1 req/15s  | Meta Llama 4 Scout |
+| `mistral`  | `pol/` | 1 req/15s  | Mistral AI         |
+
+> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.
+
+### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕
+
+| Tier | Daily Neurons | Equivalent Usage                        | Notes                   |
+| ---- | ------------- | --------------------------------------- | ----------------------- |
+| Free | **10,000**    | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |
+
+Popular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`
+
+> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.
+
+### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕
+
+| Tier | Free Quota    | Location     | Notes                               |
+| ---- | ------------- | ------------ | ----------------------------------- |
+| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |
+
+Available free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`
+
+> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).
+
+> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**
+>
+> ```
+> Kiro (kr/)             → Claude Sonnet/Haiku UNLIMITED
+> iFlow (if/)            → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED
+> LongCat Lite (lc/)     → LongCat-Flash-Lite — 50M tokens/day 🔥
+> Pollinations (pol/)    → GPT-5, Claude, DeepSeek, Llama 4 — no key needed
+> Qwen (qw/)             → qwen3-coder models UNLIMITED
+> Gemini (gemini/)       → Gemini 2.5 Flash — 1,500 req/day free
+> Cloudflare AI (cf/)    → 50+ models — 10K Neurons/day
+> Scaleway (scw/)        → Qwen3 235B, Llama 70B — 1M free tokens (EU)
+> Groq (groq/)           → Llama/Gemma — 14.4K req/day ultra-fast
+> NVIDIA NIM (nvidia/)   → 70+ open models — 40 RPM forever
+> Cerebras (cerebras/)   → Llama/Qwen world-fastest — 1M tok/day
+> ```
+
+## 🎙️ Free Transcription Combo
+
+> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.
+
+| Provider          | Free Credits           | Best Model                                   | Rate Limit                   |
+| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |
+| 🟢 **Deepgram**   | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages      | No RPM limit on free credits |
+| 🔵 **AssemblyAI** | **$50 free** (signup)  | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |
+| 🔴 **Groq**       | **Free forever**       | `whisper-large-v3` — OpenAI Whisper          | 30 RPM (rate limited)        |
+
+**Suggested combo in `/dashboard/combos`:**
+
+```
+Name: free-transcription
+Strategy: Priority
+Nodes:
+  [1] deepgram/nova-3          → uses $200 free first
+  [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out
+  [3] groq/whisper-large-v3    → free forever, emergency fallback
+```
+
+Then in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.
+
 ## 💡 Key Features
 
 OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 
-### 🚀 New in v2.0.9+ — Playground, CLI Fingerprints & ACP
+### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)
+
+| Feature                              | What It Does                                                                                |
+| ------------------------------------ | ------------------------------------------------------------------------------------------- |
+| ⚡ **Grok-4 Fast Family**            | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash)         |
+| 🧠 **GLM-5 via Z.AI**                | 128K output context, $0.5/1M — newest flagship from the GLM family                          |
+| 🔮 **MiniMax M2.5**                  | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1                       |
+| 🎯 **toolCalling Flag per Model**    | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models   |
+| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content  |
+| 📊 **Benchmark-Driven Fallbacks**    | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |
+| 🔁 **Request Deduplication**         | Content-hash based dedup window — multi-agent safe, prevents duplicate charges              |
+| 🔌 **Pluggable RouterStrategy**      | Extensible `RouterStrategy` interface — add custom routing logic as plugins                 |
+
+### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP
 
 | Feature                                    | What It Does                                                                                                                                                                                                                            |
 | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -931,33 +1206,38 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 
 ### 🧠 Routing & Intelligence
 
-| Feature                            | What It Does                                                          |
-| ---------------------------------- | --------------------------------------------------------------------- |
-| 🎯 **Smart 4-Tier Fallback**       | Auto-route: Subscription → API Key → Cheap → Free                     |
-| 📊 **Real-Time Quota Tracking**    | Live token count + reset countdown per provider                       |
-| 🔄 **Format Translation**          | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions     |
-| 👥 **Multi-Account Support**       | Multiple accounts per provider with intelligent selection             |
-| 🔄 **Auto Token Refresh**          | OAuth tokens refresh automatically with retry                         |
-| 🎨 **Custom Combos**               | 6 balancing strategies + fallback chain control                       |
-| 🌐 **Wildcard Router**             | `provider/*` dynamic routing                                          |
-| 🧠 **Thinking Budget Controls**    | Passthrough, auto, custom, and adaptive reasoning limits              |
-| 🔀 **Model Aliases**               | Built-in + custom model aliasing and migration safety                 |
-| ⚡ **Background Degradation**      | Route low-priority background tasks to cheaper models                 |
-| 💬 **System Prompt Injection**     | Global behavior controls applied consistently                         |
-| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |
+| Feature                            | What It Does                                                             |
+| ---------------------------------- | ------------------------------------------------------------------------ |
+| 🎯 **Smart 4-Tier Fallback**       | Auto-route: Subscription → API Key → Cheap → Free                        |
+| 📊 **Real-Time Quota Tracking**    | Live token count + reset countdown per provider                          |
+| 🔄 **Format Translation**          | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions        |
+| 👥 **Multi-Account Support**       | Multiple accounts per provider with intelligent selection                |
+| 🔄 **Auto Token Refresh**          | OAuth tokens refresh automatically with retry                            |
+| 🎨 **Custom Combos**               | 6 balancing strategies + fallback chain control                          |
+| 🌐 **Wildcard Router**             | `provider/*` dynamic routing                                             |
+| 🧠 **Thinking Budget Controls**    | Passthrough, auto, custom, and adaptive reasoning limits                 |
+| 🔀 **Model Aliases**               | Built-in + custom model aliasing and migration safety                    |
+| ⚡ **Background Degradation**      | Route low-priority background tasks to cheaper models                    |
+| 🧪 **Task-Aware Smart Routing**    | Auto-select model by content type (coding/vision/analysis/summarization) |
+| 🔄 **A2A Agent Workflows**         | Deterministic FSM orchestrator for stateful multi-step agent executions  |
+| 🔀 **Adaptive Routing**            | Dynamic strategy override based on token volume and prompt complexity    |
+| 🎲 **Provider Diversity**          | Shannon entropy scoring balancing auto-combo traffic distribution        |
+| 💬 **System Prompt Injection**     | Global behavior controls applied consistently                            |
+| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows    |
 
 ### 🎵 Multi-Modal APIs
 
-| Feature                    | What It Does                                                  |
-| -------------------------- | ------------------------------------------------------------- |
-| 🖼️ **Image Generation**    | `/v1/images/generations` with cloud and local backends        |
-| 📐 **Embeddings**          | `/v1/embeddings` for search and RAG pipelines                 |
-| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` (Whisper and additional providers) |
-| 🔊 **Text-to-Speech**      | `/v1/audio/speech` (multiple engines/providers)               |
-| 🎬 **Video Generation**    | `/v1/videos/generations` (ComfyUI + SD WebUI workflows)       |
-| 🎵 **Music Generation**    | `/v1/music/generations` (ComfyUI workflows)                   |
-| 🛡️ **Moderations**         | `/v1/moderations` safety checks                               |
-| 🔀 **Reranking**           | `/v1/rerank` for relevance scoring                            |
+| Feature                    | What It Does                                                                                                                                                               |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🖼️ **Image Generation**    | `/v1/images/generations` with cloud and local backends                                                                                                                     |
+| 📐 **Embeddings**          | `/v1/embeddings` for search and RAG pipelines                                                                                                                              |
+| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
+| 🔊 **Text-to-Speech**      | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages          |
+| 🎬 **Video Generation**    | `/v1/videos/generations` (ComfyUI + SD WebUI workflows)                                                                                                                    |
+| 🎵 **Music Generation**    | `/v1/music/generations` (ComfyUI workflows)                                                                                                                                |
+| 🛡️ **Moderations**         | `/v1/moderations` safety checks                                                                                                                                            |
+| 🔀 **Reranking**           | `/v1/rerank` for relevance scoring                                                                                                                                         |
+| 🔍 **Web Search** 🆕       | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache                                                               |
 
 ### 🛡️ Resilience, Security & Governance
 
@@ -972,34 +1252,45 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 | 🔏 **CLI Fingerprint Matching**     | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
 | 🌐 **IP Filtering**                 | Allowlist/blocklist control for exposed deployments                                    |
 | 📊 **Editable Rate Limits**         | Configurable global/provider-level limits with persistence                             |
+| 📉 **Graceful Degradation**         | Multi-layer capability fallbacks protecting core gateway operations                    |
+| 📜 **Config Audit Trail**           | Diff-based change tracking preventing operational drift with simple rollbacks          |
+| ⏳ **Provider Health Sync**         | Proactive token expiration monitoring triggering alerts before authorization failures  |
+| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically   |
 | 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls                               |
+| 👁️ **Scoped API Key Reveal** 🆕     | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL`                                 |
 | 🛡️ **Protected `/models`**          | Optional auth gating and provider hiding for model catalog                             |
 
 ### 📊 Observability & Analytics
 
-| Feature                         | What It Does                                          |
-| ------------------------------- | ----------------------------------------------------- |
-| 📝 **Request + Proxy Logging**  | Full request/response and proxy logging               |
-| 📋 **Unified Logs Dashboard**   | Request, proxy, audit, and console views in one page  |
-| 🔍 **Request Telemetry**        | p50/p95/p99 latency and request tracing               |
-| 🏥 **Health Dashboard**         | Uptime, breaker states, lockouts, cache stats         |
-| 💰 **Cost Tracking**            | Budget controls and per-model pricing visibility      |
-| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views         |
-| 🧪 **Evaluation Framework**     | Golden set testing with configurable match strategies |
+| Feature                          | What It Does                                          |
+| -------------------------------- | ----------------------------------------------------- |
+| 📝 **Request + Proxy Logging**   | Full request/response and proxy logging               |
+| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI  |
+| 📋 **Unified Logs Dashboard**    | Request, proxy, audit, and console views in one page  |
+| 🔍 **Request Telemetry**         | p50/p95/p99 latency and request tracing               |
+| 🏥 **Health Dashboard**          | Uptime, breaker states, lockouts, cache stats         |
+| 💰 **Cost Tracking**             | Budget controls and per-model pricing visibility      |
+| 📈 **Analytics Visualizations**  | Model/provider usage insights and trend views         |
+| 🧪 **Evaluation Framework**      | Golden set testing with configurable match strategies |
+| 📡 **Live Diagnostics** 🆕       | Semantic cache bypass for accurate combo live testing |
 
 ### ☁️ Deployment & Platform
 
-| Feature                       | What It Does                                             |
-| ----------------------------- | -------------------------------------------------------- |
-| 🌐 **Deploy Anywhere**        | Localhost, VPS, Docker, Cloud environments               |
-| 💾 **Cloud Sync**             | Configuration sync via cloud worker                      |
-| 🔄 **Backup/Restore**         | Export/import and disaster recovery flows                |
-| 🧙 **Onboarding Wizard**      | First-run guided setup                                   |
-| 🔧 **CLI Tools Dashboard**    | One-click setup for popular coding tools                 |
-| 🎮 **Model Playground**       | Test any provider/model/endpoint from the dashboard      |
-| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |
-| 🌐 **i18n (30 languages)**    | Full dashboard + docs language support with RTL coverage |
-| 📂 **Custom Data Directory**  | `DATA_DIR` override for storage location                 |
+| Feature                       | What It Does                                              |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere**        | Localhost, VPS, Docker, Cloud environments                |
+| 🚇 **Cloudflare Tunnel** 🆕   | One-click Quick Tunnel integration from the dashboard     |
+| 💾 **Cloud Sync**             | Configuration sync via cloud worker                       |
+| 🔄 **Backup/Restore**         | Export/import and disaster recovery flows                 |
+| 🧙 **Onboarding Wizard**      | First-run guided setup                                    |
+| 🔧 **CLI Tools Dashboard**    | One-click setup for popular coding tools                  |
+| 🎮 **Model Playground**       | Test any provider/model/endpoint from the dashboard       |
+| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security  |
+| 🌐 **i18n (30 languages)**    | Full dashboard + docs language support with RTL coverage  |
+| 🧹 **Clear All Models**       | One-click model list clearing in provider details         |
+| 👁️ **Sidebar Controls** 🆕    | Hide components and integrations from Appearance Settings |
+| 📋 **Issue Templates**        | Standardized GitHub templates for bugs and features       |
+| 📂 **Custom Data Directory**  | `DATA_DIR` override for storage location                  |
 
 ### Feature Deep Dive
 
@@ -1165,6 +1456,23 @@ Models:
   cx/gpt-5.1-codex-max
 ```
 
+#### Codex Account Limit Management (5h + Weekly)
+
+Each Codex account now has policy toggles in `Dashboard -> Providers`:
+
+- `5h` (ON/OFF): enforce the 5-hour window threshold policy.
+- `Weekly` (ON/OFF): enforce the weekly window threshold policy.
+- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.
+- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.
+- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.
+
+Scenarios:
+
+- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.
+- `5h OFF` + `Weekly ON`: only weekly usage can block the account.
+- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.
+- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).
+
 ### Gemini CLI (FREE 180K/month!)
 
 ```bash
@@ -1197,7 +1505,7 @@ Models:
 <details>
 <summary><b>🔑 API Key Providers</b></summary>
 
-### NVIDIA NIM (FREE 1000 credits!)
+### NVIDIA NIM (FREE developer access — 70+ models)
 
 1. Sign up: [build.nvidia.com](https://build.nvidia.com)
 2. Get free API key (1000 inference credits included)
@@ -1276,7 +1584,7 @@ Models:
 <details>
 <summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>
 
-### iFlow (8 FREE models)
+### iFlow (5 FREE models via OAuth)
 
 ```bash
 Dashboard → Connect iFlow
@@ -1291,7 +1599,7 @@ Models:
   if/deepseek-r1
 ```
 
-### Qwen (3 FREE models)
+### Qwen (4 FREE models via Device Code)
 
 ```bash
 Dashboard → Connect Qwen
@@ -1694,6 +2002,8 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
 
 ---
 
+</details>
+
 ## 🛠️ Tech Stack
 
 <details>
@@ -1788,17 +2098,9 @@ gh release create v2.0.0 --title "v2.0.0" --generate-notes
 
 ## 📊 Star History
 
-<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
- </picture>
-</a>
+## Stargazers over time
 
-> 📈 **[View live star history on star-history.com](https://star-history.com/#diegosouzapw/OmniRoute&Date)** — The embedded chart may be cached. Click the link for real-time data.
-
----
+## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)
 
 ## 🙏 Acknowledgments
 

bin/omniroute.mjs

@@ -116,10 +116,8 @@ if (args.includes("--help") || args.includes("-h")) {
 
 if (args.includes("--version") || args.includes("-v")) {
   try {
-    const pkg = await import(join(ROOT, "package.json"), {
-      with: { type: "json" },
-    });
-    console.log(pkg.default.version);
+    const { version } = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+    console.log(version);
   } catch {
     console.log("unknown");
   }
@@ -189,8 +187,27 @@ const serverJs = join(APP_DIR, "server.js");
 
 if (!existsSync(serverJs)) {
   console.error("\x1b[31m✖ Server not found at:\x1b[0m", serverJs);
-  console.error("  This usually means the package was not built correctly.");
-  console.error("  Try reinstalling: npm install -g omniroute");
+  console.error("  The package may not have been built correctly.");
+  console.error("");
+  // (#492) Detect common non-standard Node managers that cause this issue
+  const nodeExec = process.execPath || "";
+  const isMise = nodeExec.includes("mise") || nodeExec.includes(".local/share/mise");
+  const isNvm = nodeExec.includes(".nvm") || nodeExec.includes("nvm");
+  if (isMise) {
+    console.error(
+      "  \x1b[33m⚠ mise detected:\x1b[0m If you installed via `npm install -g omniroute`,"
+    );
+    console.error("    try: \x1b[36mnpx omniroute@latest\x1b[0m  (downloads a fresh copy)");
+    console.error("    or:  \x1b[36mmise exec -- npx omniroute\x1b[0m");
+  } else if (isNvm) {
+    console.error(
+      "  \x1b[33m⚠ nvm detected:\x1b[0m Try reinstalling after loading the correct Node version:"
+    );
+    console.error("    \x1b[36mnvm use --lts && npm install -g omniroute\x1b[0m");
+  } else {
+    console.error("  Try: \x1b[36mnpm install -g omniroute\x1b[0m  (reinstall)");
+    console.error("  Or:  \x1b[36mnpx omniroute@latest\x1b[0m");
+  }
   process.exit(1);
 }
 

docker-compose.prod.yml

@@ -16,7 +16,7 @@ services:
     container_name: omniroute-prod
     build:
       context: .
-      target: runner-base
+      target: runner-cli
     image: omniroute:prod
     restart: unless-stopped
     env_file: .env

docker-compose.yml

@@ -59,6 +59,11 @@ services:
     ports:
       - "${DASHBOARD_PORT:-${PORT:-20128}}:${DASHBOARD_PORT:-${PORT:-20128}}"
       - "${API_PORT:-20129}:${API_PORT:-20129}"
+    volumes:
+      - omniroute-data:/app/data
+      - /var/run/docker.sock:/var/run/docker.sock
+      - /usr/libexec/docker/cli-plugins:/usr/libexec/docker/cli-plugins:ro
+      - ${AUTO_UPDATE_HOST_REPO_DIR:-.}:/workspace/omniroute:rw
     profiles:
       - cli
 

docs/API_REFERENCE.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) | 🇨🇿 [Čeština](i18n/cs/API_REFERENCE.md)
 
 Complete reference for all OmniRoute API endpoints.
 
@@ -38,15 +38,20 @@ Content-Type: application/json
 
 ### Custom Headers
 
-| Header                   | Direction | Description                       |
-| ------------------------ | --------- | --------------------------------- |
-| `X-OmniRoute-No-Cache`   | Request   | Set to `true` to bypass cache     |
-| `X-OmniRoute-Progress`   | Request   | Set to `true` for progress events |
-| `Idempotency-Key`        | Request   | Dedup key (5s window)             |
-| `X-Request-Id`           | Request   | Alternative dedup key             |
-| `X-OmniRoute-Cache`      | Response  | `HIT` or `MISS` (non-streaming)   |
-| `X-OmniRoute-Idempotent` | Response  | `true` if deduplicated            |
-| `X-OmniRoute-Progress`   | Response  | `enabled` if progress tracking on |
+| Header                   | Direction | Description                                      |
+| ------------------------ | --------- | ------------------------------------------------ |
+| `X-OmniRoute-No-Cache`   | Request   | Set to `true` to bypass cache                    |
+| `X-OmniRoute-Progress`   | Request   | Set to `true` for progress events                |
+| `X-Session-Id`           | Request   | Sticky session key for external session affinity |
+| `x_session_id`           | Request   | Underscore variant also accepted (direct HTTP)   |
+| `Idempotency-Key`        | Request   | Dedup key (5s window)                            |
+| `X-Request-Id`           | Request   | Alternative dedup key                            |
+| `X-OmniRoute-Cache`      | Response  | `HIT` or `MISS` (non-streaming)                  |
+| `X-OmniRoute-Idempotent` | Response  | `true` if deduplicated                           |
+| `X-OmniRoute-Progress`   | Response  | `enabled` if progress tracking on                |
+| `X-OmniRoute-Session-Id` | Response  | Effective session ID used by OmniRoute           |
+
+> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers on;`.
 
 ---
 
@@ -137,10 +142,10 @@ The provider prefix is auto-added if missing. Mismatched models return `400`.
 
 ```bash
 # Get cache stats
-GET /api/cache
+GET /api/cache/stats
 
 # Clear all caches
-DELETE /api/cache
+DELETE /api/cache/stats
 ```
 
 Response example:
@@ -211,23 +216,23 @@ Response example:
 
 ### Settings
 
-| Endpoint                        | Method  | Description            |
-| ------------------------------- | ------- | ---------------------- |
-| `/api/settings`                 | GET/PUT | General settings       |
-| `/api/settings/proxy`           | GET/PUT | Network proxy config   |
-| `/api/settings/proxy/test`      | POST    | Test proxy connection  |
-| `/api/settings/ip-filter`       | GET/PUT | IP allowlist/blocklist |
-| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget |
-| `/api/settings/system-prompt`   | GET/PUT | Global system prompt   |
+| Endpoint                        | Method        | Description            |
+| ------------------------------- | ------------- | ---------------------- |
+| `/api/settings`                 | GET/PUT/PATCH | General settings       |
+| `/api/settings/proxy`           | GET/PUT       | Network proxy config   |
+| `/api/settings/proxy/test`      | POST          | Test proxy connection  |
+| `/api/settings/ip-filter`       | GET/PUT       | IP allowlist/blocklist |
+| `/api/settings/thinking-budget` | GET/PUT       | Reasoning token budget |
+| `/api/settings/system-prompt`   | GET/PUT       | Global system prompt   |
 
 ### Monitoring
 
-| Endpoint                 | Method     | Description             |
-| ------------------------ | ---------- | ----------------------- |
-| `/api/sessions`          | GET        | Active session tracking |
-| `/api/rate-limits`       | GET        | Per-account rate limits |
-| `/api/monitoring/health` | GET        | Health check            |
-| `/api/cache`             | GET/DELETE | Cache stats / clear     |
+| Endpoint                 | Method     | Description                                                                                          |
+| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------- |
+| `/api/sessions`          | GET        | Active session tracking                                                                              |
+| `/api/rate-limits`       | GET        | Per-account rate limits                                                                              |
+| `/api/monitoring/health` | GET        | Health check + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) |
+| `/api/cache/stats`       | GET/DELETE | Cache stats / clear                                                                                  |
 
 ### Backup & Export/Import
 
@@ -248,6 +253,13 @@ Response example:
 | `/api/sync/initialize` | POST    | Initialize sync       |
 | `/api/cloud/*`         | Various | Cloud management      |
 
+### Tunnels
+
+| Endpoint                   | Method | Description                                                             |
+| -------------------------- | ------ | ----------------------------------------------------------------------- |
+| `/api/tunnels/cloudflared` | GET    | Read Cloudflare Quick Tunnel install/runtime status for the dashboard   |
+| `/api/tunnels/cloudflared` | POST   | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) |
+
 ### CLI Tools
 
 | Endpoint                           | Method | Description         |
@@ -272,12 +284,12 @@ GET response includes `agents[]` (id, name, binary, version, installed, protocol
 
 ### Resilience & Rate Limits
 
-| Endpoint                | Method  | Description                     |
-| ----------------------- | ------- | ------------------------------- |
-| `/api/resilience`       | GET/PUT | Get/update resilience profiles  |
-| `/api/resilience/reset` | POST    | Reset circuit breakers          |
-| `/api/rate-limits`      | GET     | Per-account rate limit status   |
-| `/api/rate-limit`       | GET     | Global rate limit configuration |
+| Endpoint                | Method    | Description                     |
+| ----------------------- | --------- | ------------------------------- |
+| `/api/resilience`       | GET/PATCH | Get/update resilience profiles  |
+| `/api/resilience/reset` | POST      | Reset circuit breakers          |
+| `/api/rate-limits`      | GET       | Per-account rate limit status   |
+| `/api/rate-limit`       | GET       | Global rate limit configuration |
 
 ### Evals
 

docs/ARCHITECTURE.md

@@ -1,8 +1,8 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) | 🇨🇿 [Čeština](i18n/cs/ARCHITECTURE.md)
 
-_Last updated: 2026-03-04_
+_Last updated: 2026-03-28_
 
 ## Executive Summary
 
@@ -65,6 +65,26 @@ Primary runtime model:
 - Provider SLA/control plane outside local process
 - External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
 
+## Dashboard Surface (Current)
+
+Main pages under `src/app/(dashboard)/dashboard/`:
+
+- `/dashboard` — quick start + provider overview
+- `/dashboard/endpoint` — endpoint proxy + MCP + A2A + API endpoint tabs
+- `/dashboard/providers` — provider connections and credentials
+- `/dashboard/combos` — combo strategies, templates, model routing rules
+- `/dashboard/costs` — cost aggregation and pricing visibility
+- `/dashboard/analytics` — usage analytics and evaluations
+- `/dashboard/limits` — quota/rate controls
+- `/dashboard/cli-tools` — CLI onboarding, runtime detection, config generation
+- `/dashboard/agents` — detected ACP agents + custom agent registration
+- `/dashboard/media` — image/video/music playground
+- `/dashboard/search-tools` — search provider testing and history
+- `/dashboard/health` — uptime, circuit breakers, rate limits
+- `/dashboard/logs` — request/proxy/audit/console logs
+- `/dashboard/settings` — system settings tabs (general, routing, combo defaults, etc.)
+- `/dashboard/api-manager` — API key lifecycle and model permissions
+
 ## High-Level System Context
 
 ```mermaid
@@ -254,8 +274,9 @@ Domain State DB (SQLite):
 
 ## 5) Cloud Sync
 
-- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
+- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
 - Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Periodic task: `src/shared/services/modelSyncScheduler.ts`
 - Control route: `src/app/api/sync/cloud/route.ts`
 
 ## Request Lifecycle (`/v1/chat/completions`)
@@ -335,7 +356,7 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics.
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run.
 
 ## OAuth Onboarding and Token Refresh Lifecycle
 
@@ -735,10 +756,18 @@ Runtime visibility sources:
 
 - console logs from `src/sse/utils/logger.ts`
 - per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true`
 - textual request status log in `log.txt` (optional/compat)
 - optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true`
 - dashboard usage endpoints (`/api/usage/*`) for UI consumption
 
+Detailed request payload capture stores up to four JSON payload stages per routed call:
+
+- raw request received from the client
+- translated request actually sent upstream
+- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata
+- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form
+
 ## Security-Sensitive Boundaries
 
 - JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing

docs/CLI-TOOLS.md

@@ -9,7 +9,7 @@ cost tracking, model switching, and request logging across every tool.
 ## How It Works
 
 ```
-Claude / Codex / Gemini CLI / OpenCode / Cline / KiloCode / Continue / Kiro CLI
+Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot
            │
            ▼  (all point to OmniRoute)
     http://YOUR_SERVER:20128/v1
@@ -27,21 +27,38 @@ Claude / Codex / Gemini CLI / OpenCode / Cline / KiloCode / Continue / Kiro CLI
 
 ---
 
-## Supported Tools
+## Supported Tools (Dashboard Source of Truth)
 
-| Tool             | Command             | Type              | Install Method |
-| ---------------- | ------------------- | ----------------- | -------------- |
-| **Claude Code**  | `claude`            | CLI               | npm            |
-| **OpenAI Codex** | `codex`             | CLI               | npm            |
-| **Gemini CLI**   | `gemini`            | CLI               | npm            |
-| **OpenCode**     | `opencode`          | CLI               | npm            |
-| **Cline**        | `cline`             | CLI + VS Code ext | npm            |
-| **KiloCode**     | `kilocode` / `kilo` | CLI + VS Code ext | npm            |
-| **Continue**     | guide-based         | VS Code ext       | VS Code        |
-| **Kiro CLI**     | `kiro-cli`          | CLI               | curl installer |
-| **Cursor**       | `cursor`            | Desktop app       | Download       |
-| **Droid**        | web-based           | Built-in agent    | OmniRoute      |
-| **OpenClaw**     | web-based           | Built-in agent    | OmniRoute      |
+The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`.
+Current list (v3.0.0-rc.16):
+
+| Tool             | ID            | Command      | Setup Mode | Install Method |
+| ---------------- | ------------- | ------------ | ---------- | -------------- |
+| **Claude Code**  | `claude`      | `claude`     | env        | npm            |
+| **OpenAI Codex** | `codex`       | `codex`      | custom     | npm            |
+| **Factory Droid**| `droid`       | `droid`      | custom     | bundled/CLI    |
+| **OpenClaw**     | `openclaw`    | `openclaw`   | custom     | bundled/CLI    |
+| **Cursor**       | `cursor`      | app          | guide      | desktop app    |
+| **Cline**        | `cline`       | `cline`      | custom     | npm            |
+| **Kilo Code**    | `kilo`        | `kilocode`   | custom     | npm            |
+| **Continue**     | `continue`    | extension    | guide      | VS Code        |
+| **Antigravity**  | `antigravity` | internal     | mitm       | OmniRoute      |
+| **GitHub Copilot**| `copilot`    | extension    | custom     | VS Code        |
+| **OpenCode**     | `opencode`    | `opencode`   | guide      | npm            |
+| **Kiro AI**      | `kiro`        | app/cli      | mitm       | desktop/CLI    |
+
+### CLI fingerprint sync (Agents + Settings)
+
+`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`.
+This keeps provider IDs aligned with CLI cards and legacy IDs.
+
+| CLI ID | Fingerprint Provider ID |
+| ------ | ----------------------- |
+| `kilo` | `kilocode`              |
+| `copilot` | `github`             |
+| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID |
+
+Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`.
 
 ---
 
@@ -67,9 +84,6 @@ npm install -g @anthropic-ai/claude-code
 # OpenAI Codex
 npm install -g @openai/codex
 
-# Gemini CLI (Google)
-npm install -g @google/gemini-cli
-
 # OpenCode
 npm install -g opencode-ai
 
@@ -77,7 +91,7 @@ npm install -g opencode-ai
 npm install -g cline
 
 # KiloCode
-npm install -g kilecode
+npm install -g kilocode
 
 # Kiro CLI (Amazon — requires curl + unzip)
 apt-get install -y unzip   # on Debian/Ubuntu
@@ -90,7 +104,6 @@ export PATH="$HOME/.local/bin:$PATH"   # add to ~/.bashrc
 ```bash
 claude --version     # 2.x.x
 codex --version      # 0.x.x
-gemini --version     # 0.x.x
 opencode --version   # x.x.x
 cline --version      # 2.x.x
 kilocode --version   # x.x.x (or: kilo --version)
@@ -153,21 +166,6 @@ EOF
 
 ---
 
-### Gemini CLI
-
-```bash
-mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF
-{
-  "apiKey": "sk-your-omniroute-key",
-  "baseUrl": "http://localhost:20128/v1"
-}
-EOF
-```
-
-**Test:** `gemini "hello"`
-
----
-
 ### OpenCode
 
 ```bash
@@ -324,17 +322,16 @@ They run as internal routes and use OmniRoute's model routing automatically.
 OMNIROUTE_URL="http://localhost:20128/v1"
 OMNIROUTE_KEY="sk-your-omniroute-key"
 
-npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode
+npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode
 
 # Kiro CLI
 apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash
 
 # Write configs
-mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue
+mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue
 
 cat > ~/.claude/settings.json   <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}"
 cat > ~/.codex/config.yaml      <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL"
-cat > ~/.gemini/settings.json   <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}"
 cat >> ~/.bashrc << EOF
 export OPENAI_BASE_URL="$OMNIROUTE_URL"
 export OPENAI_API_KEY="$OMNIROUTE_KEY"

docs/CODEBASE_DOCUMENTATION.md

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

docs/FEATURES.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) | 🇨🇿 [Čeština](i18n/cs/FEATURES.md)
 
 Visual guide to every section of the OmniRoute dashboard.
 
@@ -8,7 +8,7 @@ Visual guide to every section of the OmniRoute dashboard.
 
 ## 🔌 Providers
 
-Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro).
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
 
 ![Providers Dashboard](screenshots/01-providers.png)
 
@@ -63,11 +63,11 @@ Customizable color themes for the entire dashboard. Choose from 7 preset colors
 Comprehensive settings panel with tabs:
 
 - **General** — System storage, backup management (export/import database)
-- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
 - **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
 - **Routing** — Model aliases, background task degradation
-- **Resilience** — Rate limit persistence, circuit breaker tuning
-- **Advanced** — Configuration overrides
+- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring
+- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
 
 ![Settings Dashboard](screenshots/06-settings.png)
 
@@ -108,7 +108,7 @@ Real-time request logging with filtering by provider, model, account, and API ke
 
 ## 🌐 API Endpoint
 
-Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access.
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
 
 ![Endpoint Dashboard](screenshots/09-endpoint.png)
 
@@ -138,5 +138,6 @@ Key features:
 - Single-instance lock
 - Auto-update on restart
 - Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
 
 📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/MCP-SERVER.md

@@ -43,7 +43,7 @@ See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot,
 | `omniroute_simulate_route`         | Dry-run routing simulation with fallback tree   |
 | `omniroute_set_budget_guard`       | Session budget with degrade/block/alert actions |
 | `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset   |
-| `omniroute_test_combo`             | Live-test all models in a combo                 |
+| `omniroute_test_combo`             | Live-test all models in a combo via a real upstream request |
 | `omniroute_get_provider_metrics`   | Detailed metrics for one provider               |
 | `omniroute_best_combo_for_task`    | Task-fitness recommendation with alternatives   |
 | `omniroute_explain_route`          | Explain a past routing decision                 |

docs/TROUBLESHOOTING.md

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

docs/USER_GUIDE.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) | 🇨🇿 [Čeština](i18n/cs/USER_GUIDE.md)
 
 Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
 
@@ -405,25 +405,127 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat
 
 For host-integrated mode with CLI binaries, see the Docker section in the main docs.
 
+### Void Linux (xbps-src)
+
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+<details>
+<summary><b>View xbps-src template</b></summary>
+
+```bash
+# Template file for 'omniroute'
+pkgname=omniroute
+version=3.2.4
+revision=1
+hostmakedepends="nodejs python3 make"
+depends="openssl"
+short_desc="Universal AI gateway with smart routing for multiple LLM providers"
+maintainer="zenobit <zenobit@disroot.org>"
+license="MIT"
+homepage="https://github.com/diegosouzapw/OmniRoute"
+distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
+checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
+system_accounts="_omniroute"
+omniroute_homedir="/var/lib/omniroute"
+export NODE_ENV=production
+export npm_config_engine_strict=false
+export npm_config_loglevel=error
+export npm_config_fund=false
+export npm_config_audit=false
+
+do_build() {
+	# Determine target CPU arch for node-gyp
+	local _gyp_arch
+	case "$XBPS_TARGET_MACHINE" in
+		aarch64*) _gyp_arch=arm64 ;;
+		armv7*|armv6*) _gyp_arch=arm ;;
+		i686*) _gyp_arch=ia32 ;;
+		*) _gyp_arch=x64 ;;
+	esac
+
+	# 1) Install all deps – skip scripts
+	NODE_ENV=development npm ci --ignore-scripts
+
+	# 2) Build the Next.js standalone bundle
+	npm run build
+
+	# 3) Copy static assets into standalone
+	cp -r .next/static .next/standalone/.next/static
+	[ -d public ] && cp -r public .next/standalone/public || true
+
+	# 4) Compile better-sqlite3 native binding
+	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+
+	# 5) Place the compiled binding into the standalone bundle
+	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+	mkdir -p "$_bs3_release"
+	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+
+	# 6) Remove arch-specific sharp bundles
+	rm -rf .next/standalone/node_modules/@img
+
+	# 7) Copy pino runtime deps omitted by Next.js static analysis:
+	for _mod in pino-abstract-transport split2 process-warning; do
+		cp -r "node_modules/$_mod" .next/standalone/node_modules/
+	done
+}
+
+do_check() {
+	npm run test:unit
+}
+
+do_install() {
+	vmkdir usr/lib/omniroute/.next
+	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+
+	# Prevent removal of empty Next.js app router dirs by the post-install hook
+	for _d in \
+		.next/standalone/.next/server/app/dashboard \
+		.next/standalone/.next/server/app/dashboard/settings \
+		.next/standalone/.next/server/app/dashboard/providers; do
+		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+	done
+
+	cat > "${WRKDIR}/omniroute" <<'EOF'
+#!/bin/sh
+export PORT="${PORT:-20128}"
+export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
+export LOG_TO_FILE="${LOG_TO_FILE:-false}"
+mkdir -p "${DATA_DIR}"
+exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
+EOF
+	vbin "${WRKDIR}/omniroute"
+}
+
+post_install() {
+	vlicense LICENSE
+}
+```
+
+</details>
+
 ### Environment Variables
 
-| Variable                  | Default                              | Description                                             |
-| ------------------------- | ------------------------------------ | ------------------------------------------------------- |
-| `JWT_SECRET`              | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**)           |
-| `INITIAL_PASSWORD`        | `123456`                             | First login password                                    |
-| `DATA_DIR`                | `~/.omniroute`                       | Data directory (db, usage, logs)                        |
-| `PORT`                    | framework default                    | Service port (`20128` in examples)                      |
-| `HOSTNAME`                | framework default                    | Bind host (Docker defaults to `0.0.0.0`)                |
-| `NODE_ENV`                | runtime default                      | Set `production` for deploy                             |
-| `BASE_URL`                | `http://localhost:20128`             | Server-side internal base URL                           |
-| `CLOUD_URL`               | `https://omniroute.dev`              | Cloud sync endpoint base URL                            |
-| `API_KEY_SECRET`          | `endpoint-proxy-api-key-secret`      | HMAC secret for generated API keys                      |
-| `REQUIRE_API_KEY`         | `false`                              | Enforce Bearer API key on `/v1/*`                       |
-| `ENABLE_REQUEST_LOGS`     | `false`                              | Enables request/response logs                           |
-| `AUTH_COOKIE_SECURE`      | `false`                              | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
-| `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                              |
+| Variable                  | Default                              | Description                                                      |
+| ------------------------- | ------------------------------------ | ---------------------------------------------------------------- |
+| `JWT_SECRET`              | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**)                    |
+| `INITIAL_PASSWORD`        | `123456`                             | First login password                                             |
+| `DATA_DIR`                | `~/.omniroute`                       | Data directory (db, usage, logs)                                 |
+| `PORT`                    | framework default                    | Service port (`20128` in examples)                               |
+| `HOSTNAME`                | framework default                    | Bind host (Docker defaults to `0.0.0.0`)                         |
+| `NODE_ENV`                | runtime default                      | Set `production` for deploy                                      |
+| `BASE_URL`                | `http://localhost:20128`             | Server-side internal base URL                                    |
+| `CLOUD_URL`               | `https://omniroute.dev`              | Cloud sync endpoint base URL                                     |
+| `API_KEY_SECRET`          | `endpoint-proxy-api-key-secret`      | HMAC secret for generated API keys                               |
+| `REQUIRE_API_KEY`         | `false`                              | Enforce Bearer API key on `/v1/*`                                |
+| `ALLOW_API_KEY_REVEAL`    | `false`                              | Allow Api Manager to copy full API keys on demand                |
+| `ENABLE_REQUEST_LOGS`     | `false`                              | Enables request/response logs                                    |
+| `AUTH_COOKIE_SECURE`      | `false`                              | Force `Secure` auth cookie (behind HTTPS reverse proxy)          |
+| `CLOUDFLARED_BIN`         | unset                                | Use an existing `cloudflared` binary instead of managed download |
+| `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).
 
@@ -538,6 +640,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`).
 - Automatic background sync with timeout + fail-fast
 - Prefer server-side `BASE_URL`/`CLOUD_URL` in production
 
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
 ### LLM Gateway Intelligence (Phase 9)
 
 - **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
@@ -578,6 +688,22 @@ Configure via **Dashboard → Settings → Routing**.
 | **Least Used**                 | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly        |
 | **Cost Optimized**             | Routes to the account with the lowest priority value, optimizing for lowest-cost providers       |
 
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
+X-Session-Id: your-session-key
+```
+
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
+
+If you use Nginx and send underscore-form headers, enable:
+
+```nginx
+underscores_in_headers on;
+```
+
 #### Wildcard Model Aliases
 
 Create wildcard patterns to remap model names:
@@ -667,10 +793,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \
 
 ### Settings Dashboard
 
-The settings page is organized into 5 tabs for easy navigation:
+The settings page is organized into 6 tabs for easy navigation:
 
 | Tab            | Contents                                                                                       |
 | -------------- | ---------------------------------------------------------------------------------------------- |
+| **General**    | System storage tools, appearance settings, theme controls, and per-item sidebar visibility     |
 | **Security**   | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking      |
 | **Routing**    | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults   |
 | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |

docs/VM_DEPLOYMENT_GUIDE.md

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

docs/adr/0001-proxy-registry-limit-generalization.md

@@ -0,0 +1,46 @@
+# ADR-0001: Proxy Registry + Usage Control Generalization
+
+Date: 2026-03-17
+Status: Accepted
+
+## Context
+
+OmniRoute sudah punya:
+
+- Proxy assignment berbasis config-map (`global`, `providers`, `combos`, `keys`).
+- Quota-aware selection khusus provider tertentu (notably `codex`).
+
+Gap utama:
+
+- Proxy belum menjadi aset reusable yang bisa di-manage sebagai entitas (metadata, where-used, safe delete).
+- Usage policy belum konsisten lintas provider.
+- Error contract API belum seragam untuk endpoint manajemen.
+
+## Decision
+
+1. Tambah **Proxy Registry** sebagai domain baru di DB (`proxy_registry`, `proxy_assignments`).
+2. Pertahankan kompatibilitas assignment lama (fallback ke `proxyConfig` lama).
+3. Resolver runtime pakai prioritas:
+   - account -> provider -> global (registry)
+   - fallback ke legacy resolver jika registry belum ada assignment
+4. Wajib redaction kredensial di output list registry default.
+5. Standarkan error JSON untuk endpoint manajemen proxy agar konsisten dan punya `requestId`.
+
+## Consequences
+
+Positif:
+
+- Proxy reusable dan bisa dilacak pemakaiannya.
+- Safe delete bisa ditegakkan (409 saat masih dipakai).
+- Migrasi bertahap tanpa breaking change runtime.
+
+Negatif:
+
+- Ada dual-source sementara (registry + legacy config) sampai migrasi selesai.
+- Butuh endpoint assignment tambahan dan pemetaan scope yang konsisten.
+
+## Follow-up
+
+- Migrasi UI provider/account dari input raw proxy ke selector registry.
+- Tambah health telemetry per proxy dan alerting.
+- Generalisasi usage control ke provider lain melalui interface policy yang sama.

docs/adr/0002-api-error-contract-management-endpoints.md

@@ -0,0 +1,32 @@
+# ADR-0002: Error Contract for Management Endpoints
+
+Date: 2026-03-17
+Status: Accepted
+
+## Decision
+
+Management endpoints (proxy config, proxy registry, and proxy assignments) return a uniform error body:
+
+```json
+{
+  "error": {
+    "message": "Human-readable summary",
+    "type": "invalid_request | not_found | conflict | server_error",
+    "details": {}
+  },
+  "requestId": "uuid"
+}
+```
+
+## Status Mapping
+
+- 400: invalid request / validation failure
+- 404: resource not found
+- 409: resource conflict (for example, proxy still assigned)
+- 500: unexpected server error
+
+## Notes
+
+- `requestId` is mandatory for log correlation.
+- `details` is optional and only used for safe validation details.
+- Sensitive secrets (proxy credentials, tokens) must never appear in `message` or `details`.

docs/adr/0003-security-checklist-proxy-limits.md

@@ -0,0 +1,16 @@
+# ADR-0003: Security Checklist for Proxy Registry and Usage Controls
+
+Date: 2026-03-17
+Status: Accepted
+
+## Checklist
+
+- Validate all management payloads with Zod.
+- Reject malformed scope assignment updates with status 400.
+- Reject deleting an in-use proxy with status 409 unless forced.
+- Never expose proxy username/password in list responses by default.
+- Never log raw credentials or token values.
+- Keep error responses free from internal stack traces.
+- Protect management endpoints with existing auth middleware policy.
+- Audit mutating operations: create/update/delete/assign/migrate.
+- Ensure resolver fallback to legacy config while migration is in transition.

docs/i18n/README.md

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

docs/i18n/ar/FEATURES.md

@@ -1,20 +1,18 @@
-🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/FEATURES.md) · 🇪🇸 [es](../es/FEATURES.md) · 🇫🇷 [fr](../fr/FEATURES.md) · 🇩🇪 [de](../de/FEATURES.md) · 🇮🇹 [it](../it/FEATURES.md) · 🇷🇺 [ru](../ru/FEATURES.md) · 🇨🇳 [zh-CN](../zh-CN/FEATURES.md) · 🇯🇵 [ja](../ja/FEATURES.md) · 🇰🇷 [ko](../ko/FEATURES.md) · 🇸🇦 [ar](../ar/FEATURES.md) · 🇮🇳 [in](../in/FEATURES.md) · 🇹🇭 [th](../th/FEATURES.md) · 🇻🇳 [vi](../vi/FEATURES.md) · 🇮🇩 [id](../id/FEATURES.md) · 🇲🇾 [ms](../ms/FEATURES.md) · 🇳🇱 [nl](../nl/FEATURES.md) · 🇵🇱 [pl](../pl/FEATURES.md) · 🇸🇪 [sv](../sv/FEATURES.md) · 🇳🇴 [no](../no/FEATURES.md) · 🇩🇰 [da](../da/FEATURES.md) · 🇫🇮 [fi](../fi/FEATURES.md) · 🇵🇹 [pt](../pt/FEATURES.md) · 🇷🇴 [ro](../ro/FEATURES.md) · 🇭🇺 [hu](../hu/FEATURES.md) · 🇧🇬 [bg](../bg/FEATURES.md) · 🇸🇰 [sk](../sk/FEATURES.md) · 🇺🇦 [uk-UA](../uk-UA/FEATURES.md) · 🇮🇱 [he](../he/FEATURES.md) · 🇵🇭 [phi](../phi/FEATURES.md)
+# OmniRoute — Dashboard Features Gallery (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md)
+
+> 🇺🇸 [English](../../../docs/FEATURES.md)
 
 ---
 
-# 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.
 
 ---
 
 ## 🔌 Providers
 
-Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro).
-
-- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` (free "Light usage" tier); use `ollamacloud/<model>` prefix
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
 
 ![Providers Dashboard](screenshots/01-providers.png)
 
@@ -69,7 +67,7 @@ Customizable color themes for the entire dashboard. Choose from 7 preset colors
 Comprehensive settings panel with tabs:
 
 - **General** — System storage, backup management (export/import database)
-- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
 - **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
 - **Routing** — Model aliases, background task degradation
 - **Resilience** — Rate limit persistence, circuit breaker tuning
@@ -144,5 +142,6 @@ Key features:
 - Single-instance lock
 - Auto-update on restart
 - Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
 
 📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/ar/USER_GUIDE.md

@@ -1,11 +1,11 @@
-🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/USER_GUIDE.md) · 🇪🇸 [es](../es/USER_GUIDE.md) · 🇫🇷 [fr](../fr/USER_GUIDE.md) · 🇩🇪 [de](../de/USER_GUIDE.md) · 🇮🇹 [it](../it/USER_GUIDE.md) · 🇷🇺 [ru](../ru/USER_GUIDE.md) · 🇨🇳 [zh-CN](../zh-CN/USER_GUIDE.md) · 🇯🇵 [ja](../ja/USER_GUIDE.md) · 🇰🇷 [ko](../ko/USER_GUIDE.md) · 🇸🇦 [ar](../ar/USER_GUIDE.md) · 🇮🇳 [in](../in/USER_GUIDE.md) · 🇹🇭 [th](../th/USER_GUIDE.md) · 🇻🇳 [vi](../vi/USER_GUIDE.md) · 🇮🇩 [id](../id/USER_GUIDE.md) · 🇲🇾 [ms](../ms/USER_GUIDE.md) · 🇳🇱 [nl](../nl/USER_GUIDE.md) · 🇵🇱 [pl](../pl/USER_GUIDE.md) · 🇸🇪 [sv](../sv/USER_GUIDE.md) · 🇳🇴 [no](../no/USER_GUIDE.md) · 🇩🇰 [da](../da/USER_GUIDE.md) · 🇫🇮 [fi](../fi/USER_GUIDE.md) · 🇵🇹 [pt](../pt/USER_GUIDE.md) · 🇷🇴 [ro](../ro/USER_GUIDE.md) · 🇭🇺 [hu](../hu/USER_GUIDE.md) · 🇧🇬 [bg](../bg/USER_GUIDE.md) · 🇸🇰 [sk](../sk/USER_GUIDE.md) · 🇺🇦 [uk-UA](../uk-UA/USER_GUIDE.md) · 🇮🇱 [he](../he/USER_GUIDE.md) · 🇵🇭 [phi](../phi/USER_GUIDE.md)
+# User Guide (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) · 🇧🇷 [pt-BR](../pt-BR/USER_GUIDE.md) · 🇪🇸 [es](../es/USER_GUIDE.md) · 🇫🇷 [fr](../fr/USER_GUIDE.md) · 🇩🇪 [de](../de/USER_GUIDE.md) · 🇮🇹 [it](../it/USER_GUIDE.md) · 🇷🇺 [ru](../ru/USER_GUIDE.md) · 🇨🇳 [zh-CN](../zh-CN/USER_GUIDE.md) · 🇯🇵 [ja](../ja/USER_GUIDE.md) · 🇰🇷 [ko](../ko/USER_GUIDE.md) · 🇸🇦 [ar](../ar/USER_GUIDE.md) · 🇮🇳 [in](../in/USER_GUIDE.md) · 🇹🇭 [th](../th/USER_GUIDE.md) · 🇻🇳 [vi](../vi/USER_GUIDE.md) · 🇮🇩 [id](../id/USER_GUIDE.md) · 🇲🇾 [ms](../ms/USER_GUIDE.md) · 🇳🇱 [nl](../nl/USER_GUIDE.md) · 🇵🇱 [pl](../pl/USER_GUIDE.md) · 🇸🇪 [sv](../sv/USER_GUIDE.md) · 🇳🇴 [no](../no/USER_GUIDE.md) · 🇩🇰 [da](../da/USER_GUIDE.md) · 🇫🇮 [fi](../fi/USER_GUIDE.md) · 🇵🇹 [pt](../pt/USER_GUIDE.md) · 🇷🇴 [ro](../ro/USER_GUIDE.md) · 🇭🇺 [hu](../hu/USER_GUIDE.md) · 🇧🇬 [bg](../bg/USER_GUIDE.md) · 🇸🇰 [sk](../sk/USER_GUIDE.md) · 🇺🇦 [uk-UA](../uk-UA/USER_GUIDE.md) · 🇮🇱 [he](../he/USER_GUIDE.md) · 🇵🇭 [phi](../phi/USER_GUIDE.md)
+
+> 🇺🇸 [English](../../USER_GUIDE.md)
 
 ---
 
-# User Guide
-
-🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md)
-
 Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
 
 ---
@@ -409,6 +409,106 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat
 
 For host-integrated mode with CLI binaries, see the Docker section in the main docs.
 
+### Void Linux (xbps-src)
+
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+<details>
+<summary><b>View xbps-src template</b></summary>
+
+```bash
+# Template file for 'omniroute'
+pkgname=omniroute
+version=3.2.4
+revision=1
+hostmakedepends="nodejs python3 make"
+depends="openssl"
+short_desc="Universal AI gateway with smart routing for multiple LLM providers"
+maintainer="zenobit <zenobit@disroot.org>"
+license="MIT"
+homepage="https://github.com/diegosouzapw/OmniRoute"
+distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
+checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
+system_accounts="_omniroute"
+omniroute_homedir="/var/lib/omniroute"
+export NODE_ENV=production
+export npm_config_engine_strict=false
+export npm_config_loglevel=error
+export npm_config_fund=false
+export npm_config_audit=false
+
+do_build() {
+	# Determine target CPU arch for node-gyp
+	local _gyp_arch
+	case "$XBPS_TARGET_MACHINE" in
+		aarch64*) _gyp_arch=arm64 ;;
+		armv7*|armv6*) _gyp_arch=arm ;;
+		i686*) _gyp_arch=ia32 ;;
+		*) _gyp_arch=x64 ;;
+	esac
+
+	# 1) Install all deps – skip scripts
+	NODE_ENV=development npm ci --ignore-scripts
+
+	# 2) Build the Next.js standalone bundle
+	npm run build
+
+	# 3) Copy static assets into standalone
+	cp -r .next/static .next/standalone/.next/static
+	[ -d public ] && cp -r public .next/standalone/public || true
+
+	# 4) Compile better-sqlite3 native binding
+	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+
+	# 5) Place the compiled binding into the standalone bundle
+	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+	mkdir -p "$_bs3_release"
+	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+
+	# 6) Remove arch-specific sharp bundles
+	rm -rf .next/standalone/node_modules/@img
+
+	# 7) Copy pino runtime deps omitted by Next.js static analysis:
+	for _mod in pino-abstract-transport split2 process-warning; do
+		cp -r "node_modules/$_mod" .next/standalone/node_modules/
+	done
+}
+
+do_check() {
+	npm run test:unit
+}
+
+do_install() {
+	vmkdir usr/lib/omniroute/.next
+	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+
+	# Prevent removal of empty Next.js app router dirs by the post-install hook
+	for _d in \
+		.next/standalone/.next/server/app/dashboard \
+		.next/standalone/.next/server/app/dashboard/settings \
+		.next/standalone/.next/server/app/dashboard/providers; do
+		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+	done
+
+	cat > "${WRKDIR}/omniroute" <<'EOF'
+#!/bin/sh
+export PORT="${PORT:-20128}"
+export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
+export LOG_TO_FILE="${LOG_TO_FILE:-false}"
+mkdir -p "${DATA_DIR}"
+exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
+EOF
+	vbin "${WRKDIR}/omniroute"
+}
+
+post_install() {
+	vlicense LICENSE
+}
+```
+
+</details>
+
 ### Environment Variables
 
 | Variable                  | Default                              | Description                                             |
@@ -582,6 +682,22 @@ Configure via **Dashboard → Settings → Routing**.
 | **Least Used**                 | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly        |
 | **Cost Optimized**             | Routes to the account with the lowest priority value, optimizing for lowest-cost providers       |
 
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
+X-Session-Id: your-session-key
+```
+
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
+
+If you use Nginx and send underscore-form headers, enable:
+
+```nginx
+underscores_in_headers on;
+```
+
 #### Wildcard Model Aliases
 
 Create wildcard patterns to remap model names:
@@ -766,7 +882,7 @@ Access via **Dashboard → Health**. Real-time system health overview with 6 car
 
 OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
 
-### Installation
+### تثبيت
 
 ```bash
 # From the electron directory:

docs/i18n/ar/VM_DEPLOYMENT_GUIDE.md

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

docs/i18n/ar/docs/FEATURES.md

@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+![Providers Dashboard](screenshots/01-providers.png)
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+![Combos Dashboard](screenshots/02-combos.png)
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+![Health Dashboard](screenshots/04-health.png)
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+![Translator Playground](screenshots/05-translator.png)
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring
+- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
+
+![Settings Dashboard](screenshots/06-settings.png)
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+![Usage Logs](screenshots/08-usage.png)
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/bg/FEATURES.md

@@ -1,20 +1,18 @@
-🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/FEATURES.md) · 🇪🇸 [es](../es/FEATURES.md) · 🇫🇷 [fr](../fr/FEATURES.md) · 🇩🇪 [de](../de/FEATURES.md) · 🇮🇹 [it](../it/FEATURES.md) · 🇷🇺 [ru](../ru/FEATURES.md) · 🇨🇳 [zh-CN](../zh-CN/FEATURES.md) · 🇯🇵 [ja](../ja/FEATURES.md) · 🇰🇷 [ko](../ko/FEATURES.md) · 🇸🇦 [ar](../ar/FEATURES.md) · 🇮🇳 [in](../in/FEATURES.md) · 🇹🇭 [th](../th/FEATURES.md) · 🇻🇳 [vi](../vi/FEATURES.md) · 🇮🇩 [id](../id/FEATURES.md) · 🇲🇾 [ms](../ms/FEATURES.md) · 🇳🇱 [nl](../nl/FEATURES.md) · 🇵🇱 [pl](../pl/FEATURES.md) · 🇸🇪 [sv](../sv/FEATURES.md) · 🇳🇴 [no](../no/FEATURES.md) · 🇩🇰 [da](../da/FEATURES.md) · 🇫🇮 [fi](../fi/FEATURES.md) · 🇵🇹 [pt](../pt/FEATURES.md) · 🇷🇴 [ro](../ro/FEATURES.md) · 🇭🇺 [hu](../hu/FEATURES.md) · 🇧🇬 [bg](../bg/FEATURES.md) · 🇸🇰 [sk](../sk/FEATURES.md) · 🇺🇦 [uk-UA](../uk-UA/FEATURES.md) · 🇮🇱 [he](../he/FEATURES.md) · 🇵🇭 [phi](../phi/FEATURES.md)
+# OmniRoute — Dashboard Features Gallery (Български)
+
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md)
+
+> 🇺🇸 [English](../../../docs/FEATURES.md)
 
 ---
 
-# 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.
 
 ---
 
 ## 🔌 Providers
 
-Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro).
-
-- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` (free "Light usage" tier); use `ollamacloud/<model>` prefix
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
 
 ![Providers Dashboard](screenshots/01-providers.png)
 
@@ -69,7 +67,7 @@ Customizable color themes for the entire dashboard. Choose from 7 preset colors
 Comprehensive settings panel with tabs:
 
 - **General** — System storage, backup management (export/import database)
-- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
 - **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
 - **Routing** — Model aliases, background task degradation
 - **Resilience** — Rate limit persistence, circuit breaker tuning
@@ -144,5 +142,6 @@ Key features:
 - Single-instance lock
 - Auto-update on restart
 - Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
 
 📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/bg/USER_GUIDE.md

@@ -1,11 +1,11 @@
-🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/USER_GUIDE.md) · 🇪🇸 [es](../es/USER_GUIDE.md) · 🇫🇷 [fr](../fr/USER_GUIDE.md) · 🇩🇪 [de](../de/USER_GUIDE.md) · 🇮🇹 [it](../it/USER_GUIDE.md) · 🇷🇺 [ru](../ru/USER_GUIDE.md) · 🇨🇳 [zh-CN](../zh-CN/USER_GUIDE.md) · 🇯🇵 [ja](../ja/USER_GUIDE.md) · 🇰🇷 [ko](../ko/USER_GUIDE.md) · 🇸🇦 [ar](../ar/USER_GUIDE.md) · 🇮🇳 [in](../in/USER_GUIDE.md) · 🇹🇭 [th](../th/USER_GUIDE.md) · 🇻🇳 [vi](../vi/USER_GUIDE.md) · 🇮🇩 [id](../id/USER_GUIDE.md) · 🇲🇾 [ms](../ms/USER_GUIDE.md) · 🇳🇱 [nl](../nl/USER_GUIDE.md) · 🇵🇱 [pl](../pl/USER_GUIDE.md) · 🇸🇪 [sv](../sv/USER_GUIDE.md) · 🇳🇴 [no](../no/USER_GUIDE.md) · 🇩🇰 [da](../da/USER_GUIDE.md) · 🇫🇮 [fi](../fi/USER_GUIDE.md) · 🇵🇹 [pt](../pt/USER_GUIDE.md) · 🇷🇴 [ro](../ro/USER_GUIDE.md) · 🇭🇺 [hu](../hu/USER_GUIDE.md) · 🇧🇬 [bg](../bg/USER_GUIDE.md) · 🇸🇰 [sk](../sk/USER_GUIDE.md) · 🇺🇦 [uk-UA](../uk-UA/USER_GUIDE.md) · 🇮🇱 [he](../he/USER_GUIDE.md) · 🇵🇭 [phi](../phi/USER_GUIDE.md)
+# User Guide (Български)
+
+🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) · 🇧🇷 [pt-BR](../pt-BR/USER_GUIDE.md) · 🇪🇸 [es](../es/USER_GUIDE.md) · 🇫🇷 [fr](../fr/USER_GUIDE.md) · 🇩🇪 [de](../de/USER_GUIDE.md) · 🇮🇹 [it](../it/USER_GUIDE.md) · 🇷🇺 [ru](../ru/USER_GUIDE.md) · 🇨🇳 [zh-CN](../zh-CN/USER_GUIDE.md) · 🇯🇵 [ja](../ja/USER_GUIDE.md) · 🇰🇷 [ko](../ko/USER_GUIDE.md) · 🇸🇦 [ar](../ar/USER_GUIDE.md) · 🇮🇳 [in](../in/USER_GUIDE.md) · 🇹🇭 [th](../th/USER_GUIDE.md) · 🇻🇳 [vi](../vi/USER_GUIDE.md) · 🇮🇩 [id](../id/USER_GUIDE.md) · 🇲🇾 [ms](../ms/USER_GUIDE.md) · 🇳🇱 [nl](../nl/USER_GUIDE.md) · 🇵🇱 [pl](../pl/USER_GUIDE.md) · 🇸🇪 [sv](../sv/USER_GUIDE.md) · 🇳🇴 [no](../no/USER_GUIDE.md) · 🇩🇰 [da](../da/USER_GUIDE.md) · 🇫🇮 [fi](../fi/USER_GUIDE.md) · 🇵🇹 [pt](../pt/USER_GUIDE.md) · 🇷🇴 [ro](../ro/USER_GUIDE.md) · 🇭🇺 [hu](../hu/USER_GUIDE.md) · 🇧🇬 [bg](../bg/USER_GUIDE.md) · 🇸🇰 [sk](../sk/USER_GUIDE.md) · 🇺🇦 [uk-UA](../uk-UA/USER_GUIDE.md) · 🇮🇱 [he](../he/USER_GUIDE.md) · 🇵🇭 [phi](../phi/USER_GUIDE.md)
+
+> 🇺🇸 [English](../../USER_GUIDE.md)
 
 ---
 
-# User Guide
-
-🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md)
-
 Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
 
 ---
@@ -409,6 +409,106 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat
 
 For host-integrated mode with CLI binaries, see the Docker section in the main docs.
 
+### Void Linux (xbps-src)
+
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+<details>
+<summary><b>View xbps-src template</b></summary>
+
+```bash
+# Template file for 'omniroute'
+pkgname=omniroute
+version=3.2.4
+revision=1
+hostmakedepends="nodejs python3 make"
+depends="openssl"
+short_desc="Universal AI gateway with smart routing for multiple LLM providers"
+maintainer="zenobit <zenobit@disroot.org>"
+license="MIT"
+homepage="https://github.com/diegosouzapw/OmniRoute"
+distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
+checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
+system_accounts="_omniroute"
+omniroute_homedir="/var/lib/omniroute"
+export NODE_ENV=production
+export npm_config_engine_strict=false
+export npm_config_loglevel=error
+export npm_config_fund=false
+export npm_config_audit=false
+
+do_build() {
+	# Determine target CPU arch for node-gyp
+	local _gyp_arch
+	case "$XBPS_TARGET_MACHINE" in
+		aarch64*) _gyp_arch=arm64 ;;
+		armv7*|armv6*) _gyp_arch=arm ;;
+		i686*) _gyp_arch=ia32 ;;
+		*) _gyp_arch=x64 ;;
+	esac
+
+	# 1) Install all deps – skip scripts
+	NODE_ENV=development npm ci --ignore-scripts
+
+	# 2) Build the Next.js standalone bundle
+	npm run build
+
+	# 3) Copy static assets into standalone
+	cp -r .next/static .next/standalone/.next/static
+	[ -d public ] && cp -r public .next/standalone/public || true
+
+	# 4) Compile better-sqlite3 native binding
+	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+
+	# 5) Place the compiled binding into the standalone bundle
+	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+	mkdir -p "$_bs3_release"
+	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+
+	# 6) Remove arch-specific sharp bundles
+	rm -rf .next/standalone/node_modules/@img
+
+	# 7) Copy pino runtime deps omitted by Next.js static analysis:
+	for _mod in pino-abstract-transport split2 process-warning; do
+		cp -r "node_modules/$_mod" .next/standalone/node_modules/
+	done
+}
+
+do_check() {
+	npm run test:unit
+}
+
+do_install() {
+	vmkdir usr/lib/omniroute/.next
+	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+
+	# Prevent removal of empty Next.js app router dirs by the post-install hook
+	for _d in \
+		.next/standalone/.next/server/app/dashboard \
+		.next/standalone/.next/server/app/dashboard/settings \
+		.next/standalone/.next/server/app/dashboard/providers; do
+		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+	done
+
+	cat > "${WRKDIR}/omniroute" <<'EOF'
+#!/bin/sh
+export PORT="${PORT:-20128}"
+export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
+export LOG_TO_FILE="${LOG_TO_FILE:-false}"
+mkdir -p "${DATA_DIR}"
+exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
+EOF
+	vbin "${WRKDIR}/omniroute"
+}
+
+post_install() {
+	vlicense LICENSE
+}
+```
+
+</details>
+
 ### Environment Variables
 
 | Variable                  | Default                              | Description                                             |
@@ -582,6 +682,22 @@ Configure via **Dashboard → Settings → Routing**.
 | **Least Used**                 | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly        |
 | **Cost Optimized**             | Routes to the account with the lowest priority value, optimizing for lowest-cost providers       |
 
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
+X-Session-Id: your-session-key
+```
+
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
+
+If you use Nginx and send underscore-form headers, enable:
+
+```nginx
+underscores_in_headers on;
+```
+
 #### Wildcard Model Aliases
 
 Create wildcard patterns to remap model names:
@@ -766,7 +882,7 @@ Access via **Dashboard → Health**. Real-time system health overview with 6 car
 
 OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
 
-### Installation
+### Инсталиране
 
 ```bash
 # From the electron directory:

docs/i18n/bg/VM_DEPLOYMENT_GUIDE.md

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

docs/i18n/bg/docs/FEATURES.md

@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Български)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+![Providers Dashboard](screenshots/01-providers.png)
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+![Combos Dashboard](screenshots/02-combos.png)
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+![Health Dashboard](screenshots/04-health.png)
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+![Translator Playground](screenshots/05-translator.png)
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring
+- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
+
+![Settings Dashboard](screenshots/06-settings.png)
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+![Usage Logs](screenshots/08-usage.png)
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/cs/A2A-SERVER.md

@@ -0,0 +1,196 @@
+# Dokumentace k serveru OmniRoute A2A
+
+> Protokol Agent-to-Agent v0.3 — OmniRoute jako inteligentní směrovací agent
+
+## Objevování agentů
+
+```bash
+curl http://localhost:20128/.well-known/agent.json
+```
+
+Vrátí kartu agenta popisující schopnosti, dovednosti a požadavky na ověřování OmniRoute.
+
+---
+
+## Ověřování
+
+Všechny požadavky `/a2a` vyžadují klíč API zadaný prostřednictvím hlavičky `Authorization` :
+
+```
+Authorization: Bearer YOUR_OMNIROUTE_API_KEY
+```
+
+Pokud na serveru není nakonfigurován žádný klíč API, ověřování se obejde.
+
+---
+
+## Metody JSON-RPC 2.0
+
+### `message/send` — synchronní spuštění
+
+Odešle zprávu dovednosti a čeká na úplnou odpověď.
+
+```bash
+curl -X POST http://localhost:20128/a2a \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_KEY" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "message/send",
+    "params": {
+      "skill": "smart-routing",
+      "messages": [{"role": "user", "content": "Write a hello world in Python"}],
+      "metadata": {"model": "auto", "combo": "fast-coding"}
+    }
+  }'
+```
+
+**Odpověď:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "result": {
+    "task": { "id": "uuid", "state": "completed" },
+    "artifacts": [{ "type": "text", "content": "..." }],
+    "metadata": {
+      "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)",
+      "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" },
+      "resilience_trace": [
+        { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." }
+      ],
+      "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" }
+    }
+  }
+}
+```
+
+### `message/stream` — SSE streamování
+
+Stejné jako `message/send` , ale vrací události odeslané serverem pro streamování v reálném čase.
+
+```bash
+curl -N -X POST http://localhost:20128/a2a \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_KEY" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "message/stream",
+    "params": {
+      "skill": "smart-routing",
+      "messages": [{"role": "user", "content": "Explain quantum computing"}]
+    }
+  }'
+```
+
+**Události SSE:**
+
+```
+data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}}
+
+: heartbeat 2026-03-03T17:00:00Z
+
+data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}}
+```
+
+### `tasks/get` — Dotaz na stav úlohy
+
+```bash
+curl -X POST http://localhost:20128/a2a \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_KEY" \
+  -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}'
+```
+
+### `tasks/cancel` — Zrušit úkol
+
+```bash
+curl -X POST http://localhost:20128/a2a \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_KEY" \
+  -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}'
+```
+
+---
+
+## Dostupné dovednosti
+
+Dovednost | Popis
+:-- | :--
+`smart-routing` | Směruje výzvy prostřednictvím inteligentního kanálu OmniRoute. Vrací odpověď s vysvětlením směrování, náklady a trasou odolnosti.
+`quota-management` | Odpovídá na dotazy v přirozeném jazyce týkající se kvót poskytovatelů, navrhuje bezplatné kombinace a poskytuje hodnocení kvót.
+
+---
+
+## Životní cyklus úkolu
+
+```
+submitted → working → completed
+                    → failed
+                    → cancelled
+```
+
+- Úkoly vyprší po 5 minutách (konfigurovatelné)
+- Stavy terminálu: `completed` , `failed` , `cancelled`
+- Záznam událostí sleduje každý přechod stavu
+
+---
+
+## Chybové kódy
+
+Kód | Význam
+:-- | :--
+-32700 | Chyba při analýze (neplatný JSON)
+-32600 | Neplatný požadavek / Neautorizovaný
+-32601 | Metoda nebo dovednost nenalezena
+-32602 | Neplatné parametry
+-32603 | Interní chyba
+
+---
+
+## Příklady integrace
+
+### Python (požadavky)
+
+```python
+import requests
+
+resp = requests.post("http://localhost:20128/a2a", json={
+    "jsonrpc": "2.0", "id": "1",
+    "method": "message/send",
+    "params": {
+        "skill": "smart-routing",
+        "messages": [{"role": "user", "content": "Hello"}]
+    }
+}, headers={"Authorization": "Bearer YOUR_KEY"})
+
+result = resp.json()["result"]
+print(result["artifacts"][0]["content"])
+print(result["metadata"]["routing_explanation"])
+```
+
+### TypeScript (načtení)
+
+```typescript
+const resp = await fetch("http://localhost:20128/a2a", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    Authorization: "Bearer YOUR_KEY",
+  },
+  body: JSON.stringify({
+    jsonrpc: "2.0",
+    id: "1",
+    method: "message/send",
+    params: {
+      skill: "smart-routing",
+      messages: [{ role: "user", content: "Hello" }],
+    },
+  }),
+});
+const { result } = await resp.json();
+console.log(result.metadata.routing_explanation);
+```

docs/i18n/cs/API_REFERENCE.md

@@ -0,0 +1,453 @@
+# Referenční informace k API
+
+🌐 **Jazyky:** 🇺🇸 [angličtina](API_REFERENCE.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [maďarština](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonésie](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nizozemsko](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](i18n/phi/API_REFERENCE.md) | 🇨🇿 [Čeština](i18n/cs/API_REFERENCE.md)
+
+Kompletní referenční příručka pro všechny koncové body rozhraní OmniRoute API.
+
+---
+
+## Obsah
+
+- [Dokončení chatu](#chat-completions)
+- [Vložení](#embeddings)
+- [Generování obrázků](#image-generation)
+- [Seznam modelů](#list-models)
+- [Koncové body kompatibility](#compatibility-endpoints)
+- [Sémantická mezipaměť](#semantic-cache)
+- [Řídicí panel a správa](#dashboard--management)
+- [Zpracování žádosti](#request-processing)
+- [Ověřování](#authentication)
+
+---
+
+## Dokončení chatu
+
+```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
+}
+```
+
+### Vlastní záhlaví
+
+| Záhlaví                  | Směr    | Popis                                             |
+| ------------------------ | ------- | ------------------------------------------------- |
+| `X-OmniRoute-No-Cache`   | Žádost  | Nastavením na `true` se vynechá mezipaměť         |
+| `X-OmniRoute-Progress`   | Žádost  | Nastaveno na `true` pro události průběhu          |
+| `Idempotency-Key`        | Žádost  | Klíč pro deduplikaci (okno 5 s)                   |
+| `X-Request-Id`           | Žádost  | Alternativní klíč pro odstranění duplicitních dat |
+| `X-OmniRoute-Cache`      | Odpověď | `HIT` or `MISS` (nestreamované)                   |
+| `X-OmniRoute-Idempotent` | Odpověď | `true` , pokud je odstraněna duplikace            |
+| `X-OmniRoute-Progress`   | Odpověď | `enabled` pokud je zapnuto sledování průběhu      |
+
+> Poznámka Nginx: pokud spoléháte na hlavičky s podtržítkem (například `x_session_id`), povolte `underscores_in_headers on;`.
+
+---
+
+## Vložení
+
+```bash
+POST /v1/embeddings
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "nebius/Qwen/Qwen3-Embedding-8B",
+  "input": "The food was delicious"
+}
+```
+
+Dostupní poskytovatelé: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+
+```bash
+# List all embedding models
+GET /v1/embeddings
+```
+
+---
+
+## Generování obrázků
+
+```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"
+}
+```
+
+Dostupní poskytovatelé: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+
+```bash
+# List all image models
+GET /v1/images/generations
+```
+
+---
+
+## Seznam modelů
+
+```bash
+GET /v1/models
+Authorization: Bearer your-api-key
+
+→ Returns all chat, embedding, and image models + combos in OpenAI format
+```
+
+---
+
+## Koncové body kompatibility
+
+| Metoda | Cesta                       | Formát                |
+| ------ | --------------------------- | --------------------- |
+| POST   | `/v1/chat/completions`      | OpenAI                |
+| POST   | `/v1/messages`              | Anthropic             |
+| POST   | `/v1/responses`             | Reakce OpenAI         |
+| POST   | `/v1/embeddings`            | OpenAI                |
+| POST   | `/v1/images/generations`    | OpenAI                |
+| GET    | `/v1/models`                | OpenAI                |
+| POST   | `/v1/messages/count_tokens` | Anthropic             |
+| GET    | `/v1beta/models`            | Blíženci              |
+| POST   | `/v1beta/models/{...path}`  | Gemini generuje obsah |
+| POST   | `/v1/api/chat`              | Ollama                |
+
+### Vyhrazené trasy poskytovatelů
+
+```bash
+POST /v1/providers/{provider}/chat/completions
+POST /v1/providers/{provider}/embeddings
+POST /v1/providers/{provider}/images/generations
+```
+
+Pokud chybí prefix poskytovatele, automaticky se přidá. Neshodné modely vrátí chybu `400` .
+
+---
+
+## Sémantická mezipaměť
+
+```bash
+# Get cache stats
+GET /api/cache
+
+# Clear all caches
+DELETE /api/cache
+```
+
+Příklad odpovědi:
+
+```json
+{
+  "semanticCache": {
+    "memorySize": 42,
+    "memoryMaxSize": 500,
+    "dbSize": 128,
+    "hitRate": 0.65
+  },
+  "idempotency": {
+    "activeKeys": 3,
+    "windowMs": 5000
+  }
+}
+```
+
+---
+
+## Řídicí panel a správa
+
+### Ověřování
+
+| Koncový bod                   | Metoda  | Popis                           |
+| ----------------------------- | ------- | ------------------------------- |
+| `/api/auth/login`             | POST    | Přihlášení                      |
+| `/api/auth/logout`            | POST    | Odhlásit se                     |
+| `/api/settings/require-login` | GET/PUT | Vyžaduje se přepnutí přihlášení |
+
+### Správa poskytovatelů
+
+| Koncový bod                  | Metoda          | Popis                             |
+| ---------------------------- | --------------- | --------------------------------- |
+| `/api/providers`             | GET/POST        | Seznam / vytvoření poskytovatelů  |
+| `/api/providers/[id]`        | GET/PUT/DELETE  | Správa poskytovatele              |
+| `/api/providers/[id]/test`   | POST            | Testovací připojení poskytovatele |
+| `/api/providers/[id]/models` | GET             | Seznam modelů poskytovatelů       |
+| `/api/providers/validate`    | POST            | Ověření konfigurace poskytovatele |
+| `/api/provider-nodes*`       | Různé           | Správa uzlů poskytovatelů         |
+| `/api/provider-models`       | GET/POST/DELETE | Vlastní modely                    |
+
+### Toky OAuth
+
+| Koncový bod                      | Metoda | Popis                              |
+| -------------------------------- | ------ | ---------------------------------- |
+| `/api/oauth/[provider]/[action]` | Různé  | OAuth specifický pro poskytovatele |
+
+### Směrování a konfigurace
+
+| Koncový bod           | Metoda   | Popis                                     |
+| --------------------- | -------- | ----------------------------------------- |
+| `/api/models/alias`   | GET/POST | Aliasy modelů                             |
+| `/api/models/catalog` | GET      | Všechny modely podle poskytovatele + typu |
+| `/api/combos*`        | Různé    | Správa kombinací                          |
+| `/api/keys*`          | Různé    | Správa klíčů API                          |
+| `/api/pricing`        | GET      | Cena modelu                               |
+
+### Využití a analýzy
+
+| Koncový bod                 | Metoda | Popis                         |
+| --------------------------- | ------ | ----------------------------- |
+| `/api/usage/history`        | GET    | Historie používání            |
+| `/api/usage/logs`           | GET    | Protokoly používání           |
+| `/api/usage/request-logs`   | GET    | Protokoly na úrovni požadavků |
+| `/api/usage/[connectionId]` | GET    | Využití na připojení          |
+
+### Nastavení
+
+| Koncový bod                     | Metoda  | Popis                                  |
+| ------------------------------- | ------- | -------------------------------------- |
+| `/api/settings`                 | GET/PUT | Obecná nastavení                       |
+| `/api/settings/proxy`           | GET/PUT | Konfigurace síťového proxy serveru     |
+| `/api/settings/proxy/test`      | POST    | Testovací připojení k proxy serveru    |
+| `/api/settings/ip-filter`       | GET/PUT | Seznam povolených/blokovaných IP adres |
+| `/api/settings/thinking-budget` | GET/PUT | Zdůvodnění rozpočtu tokenů             |
+| `/api/settings/system-prompt`   | GET/PUT | Globální systémový výzva               |
+
+### Monitorování
+
+| Koncový bod              | Metoda     | Popis                           |
+| ------------------------ | ---------- | ------------------------------- |
+| `/api/sessions`          | GET        | Sledování aktivních relací      |
+| `/api/rate-limits`       | GET        | Limity sazeb na účet            |
+| `/api/monitoring/health` | GET        | Kontrola stavu                  |
+| `/api/cache`             | GET/DELETE | Statistiky mezipaměti / vymazat |
+
+### Zálohování a export/import
+
+| Koncový bod                 | Metoda | Popis                                          |
+| --------------------------- | ------ | ---------------------------------------------- |
+| `/api/db-backups`           | GET    | Seznam dostupných záloh                        |
+| `/api/db-backups`           | DÁT    | Vytvořte ruční zálohu                          |
+| `/api/db-backups`           | POST   | Obnovení z konkrétní zálohy                    |
+| `/api/db-backups/export`    | GET    | Stáhnout databázi jako soubor .sqlite          |
+| `/api/db-backups/import`    | POST   | Nahrajte soubor .sqlite pro nahrazení databáze |
+| `/api/db-backups/exportAll` | GET    | Stáhnout plnou zálohu jako archiv .tar.gz      |
+
+### Synchronizace s cloudem
+
+| Koncový bod            | Metoda | Popis                           |
+| ---------------------- | ------ | ------------------------------- |
+| `/api/sync/cloud`      | Různé  | Operace synchronizace s cloudem |
+| `/api/sync/initialize` | POST   | Inicializovat synchronizaci     |
+| `/api/cloud/*`         | Různé  | Správa cloudu                   |
+
+### Nástroje CLI
+
+| Koncový bod                        | Metoda | Popis                                    |
+| ---------------------------------- | ------ | ---------------------------------------- |
+| `/api/cli-tools/claude-settings`   | GET    | Stav Clauda CLI                          |
+| `/api/cli-tools/codex-settings`    | GET    | Stav příkazového řádku Codexu            |
+| `/api/cli-tools/droid-settings`    | GET    | Stav příkazového řádku Droidu            |
+| `/api/cli-tools/openclaw-settings` | GET    | Stav rozhraní příkazového řádku OpenClaw |
+| `/api/cli-tools/runtime/[toolId]`  | GET    | Generické běhové prostředí CLI           |
+
+Mezi odpovědi CLI patří: `installed` , `runnable` , `command` , `commandPath` , `runtimeMode` , `reason` .
+
+### Agenti ACP
+
+| Koncový bod       | Metoda  | Popis                                                                         |
+| ----------------- | ------- | ----------------------------------------------------------------------------- |
+| `/api/acp/agents` | GET     | Zobrazit seznam všech detekovaných agentů (vestavěných + vlastních) se stavem |
+| `/api/acp/agents` | POST    | Přidat vlastního agenta nebo obnovit mezipaměť detekce                        |
+| `/api/acp/agents` | VYMAZAT | Odebrání vlastního agenta podle parametru dotazu `id`                         |
+
+Odpověď GET obsahuje `agents[]` (id, name, binary, version, installed, protocol, isCustom) a `summary` (total, installed, notFound, builtIn, custom).
+
+### Odolnost a limity rychlosti
+
+| Koncový bod             | Metoda  | Popis                                   |
+| ----------------------- | ------- | --------------------------------------- |
+| `/api/resilience`       | GET/PUT | Získání/aktualizace profilů odolnosti   |
+| `/api/resilience/reset` | POST    | Resetujte jističe                       |
+| `/api/rate-limits`      | GET     | Stav limitu sazby na účet               |
+| `/api/rate-limit`       | GET     | Konfigurace globálního limitu rychlosti |
+
+### Evals
+
+| Koncový bod  | Metoda   | Popis                                  |
+| ------------ | -------- | -------------------------------------- |
+| `/api/evals` | GET/POST | Vypsat eval sady / spustit vyhodnocení |
+
+### Zásady
+
+| Koncový bod     | Metoda          | Popis                    |
+| --------------- | --------------- | ------------------------ |
+| `/api/policies` | GET/POST/DELETE | Správa směrovacích zásad |
+
+### Dodržování
+
+| Koncový bod                 | Metoda | Popis                              |
+| --------------------------- | ------ | ---------------------------------- |
+| `/api/compliance/audit-log` | GET    | Protokol auditu shody (poslední N) |
+
+### v1beta (kompatibilní s Gemini)
+
+| Koncový bod                | Metoda | Popis                                |
+| -------------------------- | ------ | ------------------------------------ |
+| `/v1beta/models`           | GET    | Seznam modelů ve formátu Gemini      |
+| `/v1beta/models/{...path}` | POST   | Koncový bod Gemini `generateContent` |
+
+Tyto koncové body zrcadlí formát API Gemini pro klienty, kteří očekávají nativní kompatibilitu sady Gemini SDK.
+
+### Interní / systémová API
+
+| Koncový bod     | Metoda | Popis                                                           |
+| --------------- | ------ | --------------------------------------------------------------- |
+| `/api/init`     | GET    | Kontrola inicializace aplikace (používá se při prvním spuštění) |
+| `/api/tags`     | GET    | Tagy modelů kompatibilní s Ollamou (pro klienty Ollamy)         |
+| `/api/restart`  | POST   | Spustit řádný restart serveru                                   |
+| `/api/shutdown` | POST   | Spustit řádné vypnutí serveru                                   |
+
+> **Poznámka:** Tyto koncové body používá interně systém nebo pro kompatibilitu s klienty Ollama. Koncoví uživatelé je obvykle nevolají.
+
+---
+
+## Přepis zvuku
+
+```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+```
+
+Přepisujte zvukové soubory pomocí Deepgramu nebo AssemblyAI.
+
+**Žádost:**
+
+```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"
+```
+
+**Odpověď:**
+
+```json
+{
+  "text": "Hello, this is the transcribed audio content.",
+  "task": "transcribe",
+  "language": "en",
+  "duration": 12.5
+}
+```
+
+**Podporovaní poskytovatelé:** `deepgram/nova-3` , `assemblyai/best` .
+
+**Podporované formáty:** `mp3` , `wav` , `m4a` , `flac` , `ogg` , `webm` .
+
+---
+
+## Kompatibilita s Ollamou
+
+Pro klienty, kteří používají formát API od Ollamy:
+
+```bash
+# Chat endpoint (Ollama format)
+POST /v1/api/chat
+
+# Model listing (Ollama format)
+GET /api/tags
+```
+
+Požadavky jsou automaticky překládány mezi formátem Ollama a interním formátem.
+
+---
+
+## Telemetrie
+
+```bash
+# Get latency telemetry summary (p50/p95/p99 per provider)
+GET /api/telemetry/summary
+```
+
+**Odpověď:**
+
+```json
+{
+  "providers": {
+    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
+    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
+  }
+}
+```
+
+---
+
+## Rozpočet
+
+```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"
+}
+```
+
+---
+
+## Dostupnost modelu
+
+```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"
+}
+```
+
+---
+
+## Zpracování žádosti
+
+1. Klient odesílá požadavek na `/v1/*`
+2. Obslužná rutina trasy volá `handleChat` , `handleEmbedding` , `handleAudioTranscription` nebo `handleImageGeneration`
+3. Model je vyřešen (přímý poskytovatel/model nebo alias/kombinace)
+4. Přihlašovací údaje vybrané z lokální databáze s filtrováním dostupnosti účtů
+5. Pro chat: `handleChatCore` — detekce formátu, překlad, kontrola mezipaměti, kontrola idempotence
+6. Prováděcí program poskytovatele odesílá požadavek nadřazenému serveru
+7. Odpověď přeložena zpět do klientského formátu (chat) nebo vrácena tak, jak je (vložené prvky/obrázky/zvuk)
+8. Zaznamenáno použití/protokolování
+9. Záložní metoda se použije na chyby podle pravidel kombinace.
+
+Úplný referenční popis architektury: [`ARCHITECTURE.md`](ARCHITECTURE.md)
+
+---
+
+## Ověřování
+
+- Trasy dashboardu ( `/dashboard/*` ) používají soubor cookie `auth_token`
+- Přihlášení používá uložený hash hesla; záložní nastavení je `INITIAL_PASSWORD`
+- `requireLogin` lze přepínat přes `/api/settings/require-login`
+- Trasy `/v1/*` volitelně vyžadují klíč API nosiče, pokud `REQUIRE_API_KEY=true`

docs/i18n/cs/ARCHITECTURE.md

@@ -0,0 +1,782 @@
+# Architektura OmniRoute
+
+🌐 **Jazyky:** 🇺🇸 [angličtina](ARCHITECTURE.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [maďarština](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonésie](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nizozemsko](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](i18n/phi/ARCHITECTURE.md) | 🇨🇿 [Čeština](i18n/cs/ARCHITECTURE.md)
+
+_Poslední aktualizace: 2026-03-04_
+
+## Shrnutí pro manažery
+
+OmniRoute je lokální směrovací brána a dashboard s umělou inteligencí postavený na Next.js. Poskytuje jeden koncový bod kompatibilní s OpenAI ( `/v1/*` ) a směruje provoz napříč několika upstreamovými poskytovateli s překladem, záložními funkcemi, obnovou tokenů a sledováním využití.
+
+Základní schopnosti:
+
+- API prostředí kompatibilní s OpenAI pro CLI/nástroje (28 poskytovatelů)
+- Překlad požadavků/odpovědí napříč formáty poskytovatelů
+- Záložní kombinace modelů (sekvence s více modely)
+- Záložní řešení na úrovni účtu (více účtů na poskytovatele)
+- Správa připojení poskytovatele OAuth + API klíčů
+- Generování embeddingů pomocí `/v1/embeddings` (6 poskytovatelů, 9 modelů)
+- Generování obrázků pomocí `/v1/images/generations` (4 poskytovatelé, 9 modelů)
+- Pro modely uvažování zvažte analýzu tagů ( `<think>...</think>` ).
+- Sanitizace odpovědí pro striktní kompatibilitu s OpenAI SDK
+- Normalizace rolí (vývojář→systém, systém→uživatel) pro kompatibilitu mezi poskytovateli
+- Konverze strukturovaného výstupu (json_schema → Gemini responseSchema)
+- Lokální perzistence pro poskytovatele, klíče, aliasy, kombinace, nastavení, ceny
+- Sledování využití/nákladů a protokolování požadavků
+- Volitelná cloudová synchronizace pro synchronizaci více zařízení/stavů
+- Seznam povolených/blokovaných IP adres pro řízení přístupu k API
+- Řízení rozpočtu (průchozí/automatické/vlastní/adaptivní)
+- Globální systémová výzva k vložení
+- Sledování relací a otisky prstů
+- Vylepšené omezení sazeb pro jednotlivé účty s profily specifickými pro poskytovatele
+- Vzor jističů pro odolnost poskytovatele
+- Ochrana stáda proti hromům s uzamčením mutexů
+- Mezipaměť pro deduplikaci požadavků založená na podpisech
+- Vrstva domény: dostupnost modelu, pravidla nákladů, záložní politika, politika blokování
+- Perzistence stavu domény (mezipaměť SQLite pro zápis pro záložní funkce, rozpočty, uzamčení, jističe)
+- Modul zásad pro centralizované vyhodnocování požadavků (uzamčení → rozpočet → záložní)
+- Vyžádat telemetrii s agregací latence p50/p95/p99
+- Korelační ID (X-Request-Id) pro trasování typu end-to-end
+- Protokolování auditu shody s předpisy s možností odhlášení pro každý klíč API
+- Evaluační rámec pro zajištění kvality LLM
+- Řídicí panel uživatelského rozhraní Resilience se stavem jističe v reálném čase
+- Modulární poskytovatelé OAuth (12 jednotlivých modulů v adresáři `src/lib/oauth/providers/` )
+
+Primární běhový model:
+
+- Trasy aplikace Next.js v `src/app/api/*` implementují jak API dashboardů, tak i API kompatibility.
+- Sdílené jádro SSE/routing v `src/sse/*` + `open-sse/*` zvládá spouštění poskytovatelů, překlad, streamování, záložní operace a využití.
+
+## Rozsah a hranice
+
+### V rozsahu
+
+- Běhové prostředí lokální brány
+- Rozhraní API pro správu řídicích panelů
+- Ověřování poskytovatele a aktualizace tokenu
+- Žádost o překlad a streamování SSE
+- Lokální stav + perzistence využití
+- Volitelná orchestrace synchronizace s cloudem
+
+### Mimo rozsah
+
+- Implementace cloudové služby za `NEXT_PUBLIC_CLOUD_URL`
+- SLA/řídicí rovina poskytovatele mimo lokální proces
+- Samotné externí binární soubory CLI (Claude CLI, Codex CLI atd.)
+
+## Kontext systému na vysoké úrovni
+
+```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[(storage.sqlite)]
+        UDB[(usage tables + log artifacts)]
+    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
+```
+
+## Základní běhové komponenty
+
+## 1) API a směrovací vrstva (trasy aplikací Next.js)
+
+Hlavní adresáře:
+
+- `src/app/api/v1/*` a `src/app/api/v1beta/*` pro rozhraní API pro zajištění kompatibility
+- `src/app/api/*` pro API pro správu/konfiguraci
+- Další přepisy v `next.config.mjs` mapují `/v1/*` na `/api/v1/*`
+
+Důležité způsoby kompatibility:
+
+- `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` — obsahuje vlastní modely s `custom: true`
+- `src/app/api/v1/embeddings/route.ts` — generování embeddingů (6 poskytovatelů)
+- `src/app/api/v1/images/generations/route.ts` — generování obrázků (4+ poskytovatelů včetně Antigravity/Nebius)
+- `src/app/api/v1/messages/count_tokens/route.ts`
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — vyhrazený chat pro jednotlivé poskytovatele
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — vyhrazená vkládání pro jednotlivé poskytovatele
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — vyhrazené obrazy pro jednotlivé poskytovatele
+- `src/app/api/v1beta/models/route.ts`
+- `src/app/api/v1beta/models/[...path]/route.ts`
+
+Domény správy:
+
+- Auth/settings: `src/app/api/auth/*` , `src/app/api/settings/*`
+- Poskytovatelé/připojení: `src/app/api/providers*`
+- Uzly poskytovatele: `src/app/api/provider-nodes*`
+- Vlastní modely: `src/app/api/provider-models` (GET/POST/DELETE)
+- Katalog modelů: `src/app/api/models/route.ts` (GET)
+- Konfigurace proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
+- OAuth: `src/app/api/oauth/*`
+- Klíče/aliasy/kombinace/ceny: `src/app/api/keys*` , `src/app/api/models/alias` , `src/app/api/combos*` , `src/app/api/pricing`
+- Použití: `src/app/api/usage/*`
+- Synchronizace/cloud: `src/app/api/sync/*` , `src/app/api/cloud/*`
+- Pomocné nástroje pro CLI: `src/app/api/cli-tools/*`
+- IP filtr: `src/app/api/settings/ip-filter` (GET/PUT)
+- Rozpočet pro myšlení: `src/app/api/settings/thinking-budget` (GET/PUT)
+- Systémový příkaz: `src/app/api/settings/system-prompt` (GET/PUT)
+- Relace: `src/app/api/sessions` (GET)
+- Limity rychlosti: `src/app/api/rate-limits` (GET)
+- Odolnost: `src/app/api/resilience` (GET/PATCH) — profily poskytovatelů, jistič, stav limitu rychlosti
+- Reset odolnosti: `src/app/api/resilience/reset` (POST) — reset jističů + doby zchlazení
+- Statistiky mezipaměti: `src/app/api/cache/stats` (GET/DELETE)
+- Dostupnost modelu: `src/app/api/models/availability` (GET/POST)
+- Telemetrie: `src/app/api/telemetry/summary` (GET)
+- Rozpočet: `src/app/api/usage/budget` (GET/POST)
+- Záložní řetězce: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Audit shody: `src/app/api/compliance/audit-log` (GET)
+- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
+- Zásady: `src/app/api/policies` (GET/POST)
+
+## 2) SSE + Překladatelské jádro
+
+Hlavní moduly toku:
+
+- Záznam: `src/sse/handlers/chat.ts`
+- Orchestrace jádra: `open-sse/handlers/chatCore.ts`
+- Adaptéry pro spuštění poskytovatelů: `open-sse/executors/*`
+- Detekce formátu/konfigurace poskytovatele: `open-sse/services/provider.ts`
+- Analýza/řešení modelu: `src/sse/services/model.ts` , `open-sse/services/model.ts`
+- Logika záložního účtu: `open-sse/services/accountFallback.ts`
+- Registr překladů: `open-sse/translator/index.ts`
+- Transformace streamů: `open-sse/utils/stream.ts` , `open-sse/utils/streamHandler.ts`
+- Extrakce/normalizace využití: `open-sse/utils/usageTracking.ts`
+- Analyzátor tagů Think: `open-sse/utils/thinkTagParser.ts`
+- Obslužná rutina pro vkládání: `open-sse/handlers/embeddings.ts`
+- Registr poskytovatelů vkládání: `open-sse/config/embeddingRegistry.ts`
+- Obslužná rutina generování obrázků: `open-sse/handlers/imageGeneration.ts`
+- Registr poskytovatelů obrázků: `open-sse/config/imageRegistry.ts`
+- Sanitizace odpovědí: `open-sse/handlers/responseSanitizer.ts`
+- Normalizace rolí: `open-sse/services/roleNormalizer.ts`
+
+Služby (obchodní logika):
+
+- Výběr/skórování účtu: `open-sse/services/accountSelector.ts`
+- Správa životního cyklu kontextu: `open-sse/services/contextManager.ts`
+- Vynucení filtrování IP adres: `open-sse/services/ipFilter.ts`
+- Sledování relací: `open-sse/services/sessionManager.ts`
+- Požadavek na deduplikaci: `open-sse/services/signatureCache.ts`
+- Vložení systémového promptu: `open-sse/services/systemPrompt.ts`
+- Řízení rozpočtu v duchu myšlenek: `open-sse/services/thinkingBudget.ts`
+- Směrování pomocí modelu zástupných znaků: `open-sse/services/wildcardRouter.ts`
+- Správa limitů rychlosti: `open-sse/services/rateLimitManager.ts`
+- Jistič: `open-sse/services/circuitBreaker.ts`
+
+Moduly doménové vrstvy:
+
+- Dostupnost modelu: `src/lib/domain/modelAvailability.ts`
+- Pravidla/rozpočty nákladů: `src/lib/domain/costRules.ts`
+- Záložní zásady: `src/lib/domain/fallbackPolicy.ts`
+- Kombinovaný resolver: `src/lib/domain/comboResolver.ts`
+- Zásady uzamčení: `src/lib/domain/lockoutPolicy.ts`
+- Modul zásad: `src/domain/policyEngine.ts` — centralizované uzamčení → rozpočet → vyhodnocení záložního režimu
+- Katalog chybových kódů: `src/lib/domain/errorCodes.ts`
+- ID požadavku: `src/lib/domain/requestId.ts`
+- Časový limit načtení: `src/lib/domain/fetchTimeout.ts`
+- Požadovat telemetrii: `src/lib/domain/requestTelemetry.ts`
+- Shoda/audit: `src/lib/domain/compliance/index.ts`
+- Zkušební běžec: `src/lib/domain/evalRunner.ts`
+- Perzistence stavu domény: `src/lib/db/domainState.ts` — SQLite CRUD pro záložní řetězce, rozpočty, historii nákladů, stav uzamčení, jističe
+
+Moduly poskytovatelů OAuth (12 jednotlivých souborů v adresáři `src/lib/oauth/providers/` ):
+
+- Index registru: `src/lib/oauth/providers/index.ts`
+- Jednotliví poskytovatelé: `claude.ts` , `codex.ts` , `gemini.ts` , `antigravity.ts` , `iflow.ts` , `qwen.ts` , `kimi-coding.ts` , `github.ts` , `kiro.ts` , `cursor.ts` , `kilocode.ts` , `cline.ts`
+- Thin wrapper: `src/lib/oauth/providers.ts` — reexporty z jednotlivých modulů
+
+## 3) Vrstva perzistence
+
+Primární stavová databáze (SQLite):
+
+- Základní infrastruktura: `src/lib/db/core.ts` (better-sqlite3, migrace, WAL)
+- Reexportní fasáda: `src/lib/localDb.ts` (tenká vrstva kompatibility pro volající)
+- soubor: `${DATA_DIR}/storage.sqlite` (nebo `$XDG_CONFIG_HOME/omniroute/storage.sqlite` pokud je nastaveno, jinak `~/.omniroute/storage.sqlite` )
+- entity (tabulky + jmenné prostory KV): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels** , **proxyConfig** , **ipFilter** , **thinkingBudget** , **systemPrompt**
+
+Trvalost používání:
+
+- fasáda: `src/lib/usageDb.ts` (dekomponované moduly v `src/lib/usage/*` )
+- SQLite tabulky v `storage.sqlite` : `usage_history` , `call_logs` , `proxy_logs`
+- Volitelné artefakty souborů zůstávají pro účely kompatibility/ladění ( `${DATA_DIR}/log.txt` , `${DATA_DIR}/call_logs/` , `<repo>/logs/...` )
+- Starší soubory JSON jsou migrovány do SQLite při migracích při spuštění, pokud jsou k dispozici.
+
+Databáze stavu domény (SQLite):
+
+- `src/lib/db/domainState.ts` — CRUD operace pro stav domény
+- Tabulky (vytvořené v `src/lib/db/core.ts` ): `domain_fallback_chains` , `domain_budgets` , `domain_cost_history` , `domain_lockout_state` , `domain_circuit_breakers`
+- Vzor mezipaměti pro zápis: mapy v paměti jsou autoritativní za běhu; mutace se zapisují synchronně do SQLite; stav se obnovuje z databáze při studeném startu.
+
+## 4) Ověřovací a bezpečnostní povrchy
+
+- Autorizace souborů cookie v dashboardu: `src/proxy.ts` , `src/app/api/auth/login/route.ts`
+- Generování/ověření klíče API: `src/shared/utils/apiKey.ts`
+- Tajné kódy poskytovatele přetrvávaly v položkách `providerConnections`
+- Podpora odchozí proxy přes `open-sse/utils/proxyFetch.ts` (proměnné prostředí) a `open-sse/utils/networkProxy.ts` (konfigurovatelné pro jednotlivé poskytovatele nebo globálně)
+
+## 5) Synchronizace s cloudem
+
+- Inicializace plánovače: `src/lib/initCloudSync.ts` , `src/shared/services/initializeCloudSync.ts`
+- Periodická úloha: `src/shared/services/cloudSyncScheduler.ts`
+- Řídicí trasa: `src/app/api/sync/cloud/route.ts`
+
+## Životní cyklus požadavku ( `/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
+```
+
+## Kombinovaný + záložní proces pro účet
+
+```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]
+```
+
+Rozhodnutí o záložních metodách jsou řízena souborem `open-sse/services/accountFallback.ts` s využitím stavových kódů a heuristik chybových zpráv.
+
+## Životní cyklus aktualizace OAuth a onboardingu tokenu
+
+```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
+```
+
+Obnovení během živého provozu se provádí uvnitř `open-sse/handlers/chatCore.ts` pomocí exekutoru `refreshCredentials()` .
+
+## Životní cyklus synchronizace s cloudem (Povolit / Synchronizovat / Zakázat)
+
+```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
+```
+
+Pravidelnou synchronizaci spouští `CloudSyncScheduler` , když je povolen cloud.
+
+## Datový model a mapa úložiště
+
+```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
+    }
+```
+
+Soubory fyzického úložiště:
+
+- primární běhová databáze: `${DATA_DIR}/storage.sqlite`
+- řádky protokolu požadavku: `${DATA_DIR}/log.txt` (artefakt kompatibility/ladění)
+- Archivy strukturovaných dat volání: `${DATA_DIR}/call_logs/`
+- volitelné relace překladače/vyžádání ladění: `<repo>/logs/...`
+
+## Topologie nasazení
+
+```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[(storage.sqlite)]
+        UsageDB[(usage tables + log artifacts)]
+    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
+```
+
+## Mapování modulů (kritické pro rozhodnutí)
+
+### Moduly tras a API
+
+- `src/app/api/v1/*` , `src/app/api/v1beta/*` : API pro zajištění kompatibility
+- `src/app/api/v1/providers/[provider]/*` : vyhrazené trasy pro jednotlivé poskytovatele (chat, vkládání, obrázky)
+- `src/app/api/providers*` : CRUD poskytovatele, validace, testování
+- `src/app/api/provider-nodes*` : správa uzlů kompatibilních s vlastními nástroji
+- `src/app/api/provider-models` : správa vlastních modelů (CRUD)
+- `src/app/api/models/route.ts` : API katalogu modelů (aliasy + vlastní modely)
+- `src/app/api/oauth/*` : Toky OAuth/kódu zařízení
+- `src/app/api/keys*` : životní cyklus lokálního klíče API
+- `src/app/api/models/alias` : správa aliasů
+- `src/app/api/combos*` : správa záložních kombinací
+- `src/app/api/pricing` : přepsání cen pro výpočet nákladů
+- `src/app/api/settings/proxy` : konfigurace proxy (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test` : test připojení odchozí proxy (POST)
+- `src/app/api/usage/*` : API pro použití a protokoly
+- `src/app/api/sync/*` + `src/app/api/cloud/*` : synchronizace s cloudem a pomocníci pro práci s cloudem
+- `src/app/api/cli-tools/*` : lokální programy pro zápis/kontrolu konfigurace CLI
+- `src/app/api/settings/ip-filter` : Seznam povolených/blokovaných IP adres (GET/PUT)
+- `src/app/api/settings/thinking-budget` : konfigurace rozpočtu tokenu thinking (GET/PUT)
+- `src/app/api/settings/system-prompt` : globální systémový příkaz (GET/PUT)
+- `src/app/api/sessions` : výpis aktivních relací (GET)
+- `src/app/api/rate-limits` : stav limitu rychlosti pro účet (GET)
+
+### Směrovací a spouštěcí jádro
+
+- `src/sse/handlers/chat.ts` : parsování požadavků, zpracování kombinací, smyčka výběru účtu
+- `open-sse/handlers/chatCore.ts` : překlad, odeslání exekutoru, zpracování opakování/obnovení, nastavení streamu
+- `open-sse/executors/*` : chování sítě a formátu specifické pro poskytovatele
+
+### Registr překladů a převodníky formátů
+
+- `open-sse/translator/index.ts` : registr a orchestrace překladačů
+- Žádost o překladatele: `open-sse/translator/request/*`
+- Překladače odpovědí: `open-sse/translator/response/*`
+- Formátovací konstanty: `open-sse/translator/formats.ts`
+
+### Perzistence
+
+- `src/lib/db/*` : perzistentní ukládání konfigurace/stavu a domény v SQLite
+- `src/lib/localDb.ts` : reexport kompatibility pro databázové moduly
+- `src/lib/usageDb.ts` : fasáda historie použití/záznamů volání nad tabulkami SQLite
+
+## Pokrytí poskytovatele a vykonavatele (strategický vzorec)
+
+Každý poskytovatel má specializovaný exekutor rozšiřující `BaseExecutor` (v `open-sse/executors/base.ts` ), který zajišťuje vytváření URL adres, konstrukci hlaviček, opakování s exponenciálním odkladem, hooky pro obnovení pověření a orchestrační metodu `execute()` .
+
+| Vykonavatel           | Poskytovatel(é)                                                                                                                                              | Speciální manipulace                                                                     |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `DefaultExecutor`     | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Konfigurace dynamické adresy URL/záhlaví pro každého poskytovatele                       |
+| `AntigravityExecutor` | Google Antigravity                                                                                                                                           | Vlastní ID projektů/relací, analýza Opakování po                                         |
+| `CodexExecutor`       | OpenAI Codex                                                                                                                                                 | Vkládá systémové instrukce, vynucuje úsilí k uvažování                                   |
+| `CursorExecutor`      | IDE kurzoru                                                                                                                                                  | Protokol ConnectRPC, kódování Protobuf, podepisování požadavků pomocí kontrolního součtu |
+| `GithubExecutor`      | GitHub Copilot                                                                                                                                               | Aktualizace tokenu Copilot, hlavičky napodobující VSCode                                 |
+| `KiroExecutor`        | AWS CodeWhisperer/Kiro                                                                                                                                       | Binární formát AWS EventStream → konverze SSE                                            |
+| `GeminiCLIExecutor`   | Gemini CLI                                                                                                                                                   | Cyklus obnovy tokenu Google OAuth                                                        |
+
+Všichni ostatní poskytovatelé (včetně uzlů kompatibilních s vlastními funkcemi) používají `DefaultExecutor` .
+
+## Matice kompatibility poskytovatelů
+
+| Poskytovatel                   | Formát          | Autorizace                         | Proud                | Nestreamované | Obnovení tokenu | API pro použití             |
+| ------------------------------ | --------------- | ---------------------------------- | -------------------- | ------------- | --------------- | --------------------------- |
+| Claude                         | Claude          | Klíč API / OAuth                   | ✅                   | ✅            | ✅              | ⚠️ Pouze pro administrátory |
+| Blíženci                       | Blíženci        | Klíč API / OAuth                   | ✅                   | ✅            | ✅              | ⚠️ Cloudová konzole         |
+| Gemini CLI                     | gemini-cli      | OAuth                              | ✅                   | ✅            | ✅              | ⚠️ Cloudová konzole         |
+| Antigravity                    | antigravitace   | OAuth                              | ✅                   | ✅            | ✅              | ✅ Plná kvóta API           |
+| OpenAI                         | otevřeno        | Klíč API                           | ✅                   | ✅            | ❌              | ❌                          |
+| Kodex                          | openai-odpovědi | OAuth                              | ✅ vynucený          | ❌            | ✅              | ✅ Limity sazeb             |
+| GitHub Copilot                 | otevřeno        | OAuth + token Copilota             | ✅                   | ✅            | ✅              | ✅ Snímky kvót              |
+| Kurzor                         | kurzor          | Vlastní kontrolní součet           | ✅                   | ✅            | ❌              | ❌                          |
+| Kiro                           | Kiro            | OIDC pro jednotné přihlašování AWS | ✅ (Stream událostí) | ❌            | ✅              | ✅ Limity použití           |
+| Qwen                           | otevřeno        | OAuth                              | ✅                   | ✅            | ✅              | ⚠️ Na vyžádání              |
+| iFlow                          | otevřeno        | OAuth (základní)                   | ✅                   | ✅            | ✅              | ⚠️ Na vyžádání              |
+| OpenRouter                     | otevřeno        | Klíč API                           | ✅                   | ✅            | ❌              | ❌                          |
+| GLM/Kimi/MiniMax               | Claude          | Klíč API                           | ✅                   | ✅            | ❌              | ❌                          |
+| Hluboké vyhledávání            | otevřeno        | Klíč API                           | ✅                   | ✅            | ❌              | ❌                          |
+| Groq                           | otevřeno        | Klíč API                           | ✅                   | ✅            | ❌              | ❌                          |
+| xAI (Grok)                     | otevřeno        | Klíč API                           | ✅                   | ✅            | ❌              | ❌                          |
+| Mistral                        | otevřeno        | Klíč API                           | ✅                   | ✅            | ❌              | ❌                          |
+| Zmatek                         | otevřeno        | Klíč API                           | ✅                   | ✅            | ❌              | ❌                          |
+| Společně s umělou inteligencí  | otevřeno        | Klíč API                           | ✅                   | ✅            | ❌              | ❌                          |
+| Ohňostroj s umělou inteligencí | otevřeno        | Klíč API                           | ✅                   | ✅            | ❌              | ❌                          |
+| Mozky                          | otevřeno        | Klíč API                           | ✅                   | ✅            | ❌              | ❌                          |
+| Soudržný                       | otevřeno        | Klíč API                           | ✅                   | ✅            | ❌              | ❌                          |
+| NVIDIA NIM                     | otevřeno        | Klíč API                           | ✅                   | ✅            | ❌              | ❌                          |
+
+## Pokrytí překladů formátů
+
+Mezi detekované zdrojové formáty patří:
+
+- `openai`
+- `openai-responses`
+- `claude`
+- `gemini`
+
+Cílové formáty zahrnují:
+
+- Chat/Odpovědi v OpenAI
+- Claude
+- Obálka Gemini/Gemini-CLI/Antigravity
+- Kiro
+- Kurzor
+
+Překlady používají **jako ústřední formát OpenAI** – všechny konverze procházejí OpenAI jako zprostředkovatel:
+
+```
+Source Format → OpenAI (hub) → Target Format
+```
+
+Překlady jsou vybírány dynamicky na základě tvaru zdrojového datového obsahu a formátu cílového poskytovatele.
+
+Další vrstvy zpracování v překladovém kanálu:
+
+- **Sanitizace odpovědí** – Odstraňuje nestandardní pole z odpovědí ve formátu OpenAI (streamovaných i nestreamovaných), aby byla zajištěna přísná shoda se SDK.
+- **Normalizace rolí** — Převádí `developer` → `system` pro cíle mimo OpenAI; slučuje `system` → `user` pro modely, které odmítají systémovou roli (GLM, ERNIE)
+- **Extrakce tagu Think** — Analyzuje bloky `<think>...</think>` z obsahu do pole `reasoning_content`
+- **Strukturovaný výstup** — Převede OpenAI `response_format.json_schema` na `responseMimeType` + `responseSchema` z Gemini.
+
+## Podporované koncové body API
+
+| Koncový bod                                        | Formát                    | Psovod                                                  |
+| -------------------------------------------------- | ------------------------- | ------------------------------------------------------- |
+| `POST /v1/chat/completions`                        | Chat s OpenAI             | `src/sse/handlers/chat.ts`                              |
+| `POST /v1/messages`                                | Claude Messages           | Stejný obslužný program (automaticky detekováno)        |
+| `POST /v1/responses`                               | Reakce OpenAI             | `open-sse/handlers/responsesHandler.ts`                 |
+| `POST /v1/embeddings`                              | Vkládání OpenAI           | `open-sse/handlers/embeddings.ts`                       |
+| `GET /v1/embeddings`                               | Seznam modelů             | Trasa API                                               |
+| `POST /v1/images/generations`                      | Obrázky OpenAI            | `open-sse/handlers/imageGeneration.ts`                  |
+| `GET /v1/images/generations`                       | Seznam modelů             | Trasa API                                               |
+| `POST /v1/providers/{provider}/chat/completions`   | Chat s OpenAI             | Vyhrazené pro každého poskytovatele s ověřováním modelu |
+| `POST /v1/providers/{provider}/embeddings`         | Vkládání OpenAI           | Vyhrazené pro každého poskytovatele s ověřováním modelu |
+| `POST /v1/providers/{provider}/images/generations` | Obrázky OpenAI            | Vyhrazené pro každého poskytovatele s ověřováním modelu |
+| `POST /v1/messages/count_tokens`                   | Počet žetonů Claude       | Trasa API                                               |
+| `GET /v1/models`                                   | Seznam modelů OpenAI      | Trasa API (chat + vkládání + obrázek + vlastní modely)  |
+| `GET /api/models/catalog`                          | Katalog                   | Všechny modely seskupené podle poskytovatele + typu     |
+| `POST /v1beta/models/*:streamGenerateContent`      | Rodák z Blíženců          | Trasa API                                               |
+| `GET/PUT/DELETE /api/settings/proxy`               | Konfigurace proxy serveru | Konfigurace síťového proxy serveru                      |
+| `POST /api/settings/proxy/test`                    | Připojení proxy serveru   | Koncový bod testu stavu/připojení proxy serveru         |
+| `GET/POST/DELETE /api/provider-models`             | Vlastní modely            | Správa vlastních modelů pro každého poskytovatele       |
+
+## Obejít obslužnou rutinu
+
+Obslužná rutina bypassu ( `open-sse/utils/bypassHandler.ts` ) zachycuje známé „throwaway“ požadavky z Claude CLI – warmup pingy, extrakce titulků a počty tokenů – a vrací **falešnou odpověď** bez spotřebování tokenů upstreamového poskytovatele. Toto se spustí pouze tehdy, když `User-Agent` obsahuje `claude-cli` .
+
+## Kanál protokolování požadavků
+
+Záznamník požadavků ( `open-sse/utils/requestLogger.ts` ) poskytuje 7stupňový kanál protokolování ladění, ve výchozím nastavení zakázaný a povolený pomocí `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
+```
+
+Soubory se zapisují do `<repo>/logs/<session>/` pro každou relaci požadavku.
+
+## Způsoby selhání a odolnost
+
+## 1) Dostupnost účtu/poskytovatele
+
+- Doba ochlazování účtu poskytovatele při přechodných chybách/chybách rychlosti/autentizace
+- záložní účet před selháním požadavku
+- záložní kombinovaný model, když je aktuální cesta modelu/poskytovatele vyčerpána
+
+## 2) Platnost tokenu
+
+- předběžná kontrola a obnovení s opakovaným pokusem o obnovení poskytovatelů
+- Opakování 401/403 po pokusu o obnovení v hlavní cestě
+
+## 3) Bezpečnost streamu
+
+- streamovací řadič s vědomím odpojení
+- překladový proud s vyprázdněním konce proudu a zpracováním `[DONE]`
+- Záložní odhad využití, když chybí metadata využití poskytovatele
+
+## 4) Zhoršení cloudové synchronizace
+
+- Zobrazují se chyby synchronizace, ale lokální běhové prostředí pokračuje.
+- Plánovač má logiku umožňující opakování, ale periodické provádění v současné době ve výchozím nastavení volá synchronizaci s jedním pokusem.
+
+## 5) Integrita dat
+
+- Migrace schématu SQLite a automatické aktualizace hooků při spuštění
+- Cesta kompatibility migrace starší verze JSON → SQLite
+
+## Pozorovatelnost a provozní signály
+
+Zdroje viditelnosti za běhu:
+
+- protokoly konzole ze `src/sse/utils/logger.ts`
+- Agregace využití na požadavek v SQLite ( `usage_history` , `call_logs` , `proxy_logs` )
+- textový stav požadavku přihlášení `log.txt` (volitelné/kompatibilní)
+- volitelné hluboké protokoly požadavků/překladů v `logs/` pokud `ENABLE_REQUEST_LOGS=true`
+- Koncové body použití dashboardu ( `/api/usage/*` ) pro spotřebu v uživatelském rozhraní
+
+## Hranice citlivé z hlediska zabezpečení
+
+- Tajný kód JWT ( `JWT_SECRET` ) zajišťuje ověřování/podepisování souborů cookie relace dashboardu.
+- Počáteční bootstrap hesla ( `INITIAL_PASSWORD` ) by měl být explicitně nakonfigurován pro zřizování při prvním spuštění.
+- Tajný klíč API HMAC ( `API_KEY_SECRET` ) zabezpečuje formát vygenerovaného lokálního klíče API.
+- Tajné klíče/tokeny poskytovatele (klíče/tokeny API) jsou uloženy v lokální databázi a měly by být chráněny na úrovni souborového systému.
+- Koncové body synchronizace cloudu se spoléhají na sémantiku ověřování klíče API + ID počítače.
+
+## Matice prostředí a běhového prostředí
+
+Proměnné prostředí aktivně používané kódem:
+
+- Aplikace/autentizace: `JWT_SECRET` , `INITIAL_PASSWORD`
+- Úložiště: `DATA_DIR`
+- Chování kompatibilního uzlu: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
+- Volitelné přepsání úložné základny (Linux/macOS, když `DATA_DIR` není nastaveno): `XDG_CONFIG_HOME`
+- Bezpečnostní hashování: `API_KEY_SECRET` , `MACHINE_ID_SALT`
+- Protokolování: `ENABLE_REQUEST_LOGS`
+- Synchronizace/cloudové URL: `NEXT_PUBLIC_BASE_URL` , `NEXT_PUBLIC_CLOUD_URL`
+- Odchozí proxy: `HTTP_PROXY` , `HTTPS_PROXY` , `ALL_PROXY` , `NO_PROXY` a varianty s malými písmeny
+- Příznaky funkcí SOCKS5: `ENABLE_SOCKS5_PROXY` , `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
+- Pomocníci pro platformu/běhové prostředí (ne konfigurace specifická pro aplikaci): `APPDATA` , `NODE_ENV` , `PORT` , `HOSTNAME`
+
+## Známé architektonické poznámky
+
+1. `usageDb` a `localDb` sdílejí stejnou základní adresářovou politiku ( `DATA_DIR` -&gt; `XDG_CONFIG_HOME/omniroute` -&gt; `~/.omniroute` ) se starší migrací souborů.
+2. `/api/v1/route.ts` deleguje na stejný jednotný nástroj pro tvorbu katalogů, který používá `/api/v1/models` ( `src/app/api/v1/models/catalog.ts` ), aby se zabránilo sémantickému posunu.
+3. Pokud je povoleno, zaznamenávač požadavků zapisuje celé záhlaví/tělo; adresář protokolu je považován za citlivý.
+4. Chování cloudu závisí na správné adrese `NEXT_PUBLIC_BASE_URL` a dosažitelnosti cloudového koncového bodu.
+5. Adresář `open-sse/` je publikován jako **balíček npm workspace** `@omniroute/open-sse` . Zdrojový kód jej importuje přes `@omniroute/open-sse/...` (vyřešeno pomocí `transpilePackages` v Next.js). Cesty k souborům v tomto dokumentu stále používají název adresáře `open-sse/` pro účely konzistence.
+6. Grafy v dashboardu používají **Recharts** (založené na SVG) pro přístupné a interaktivní vizualizace analytiky (sloupcové grafy využití modelu, tabulky s rozpisem poskytovatelů s mírou úspěšnosti).
+7. E2E testy používají **Playwright** ( `tests/e2e/` ), spouštěné pomocí `npm run test:e2e` . Unit testy používají **Node.js test runner** ( `tests/unit/` ), spouštěné pomocí `npm run test:unit` . Zdrojový kód pod `src/` je **TypeScript** ( `.ts` / `.tsx` ); pracovní prostor `open-sse/` zůstává JavaScript ( `.js` ).
+8. Stránka nastavení je uspořádána do 5 záložek: Zabezpečení, Směrování (6 globálních strategií: fill-first, round robin, p2c, náhodné, nejméně používané, nákladově optimalizované), Odolnost (upravitelné limity rychlosti, jistič, zásady), AI (rozpočet promyšlený, systémový výzva, mezipaměť výzev), Pokročilé (proxy).
+
+## Kontrolní seznam provozního ověření
+
+- Sestavení ze zdroje: `npm run build`
+- Sestavení obrazu Dockeru: `docker build -t omniroute .`
+- Spusťte službu a ověřte:
+- `GET /api/settings`
+- `GET /api/v1/models`
+- Základní URL cíle CLI by měla být `http://<host>:20128/v1` , pokud `PORT=20128`

docs/i18n/cs/AUTO-COMBO.md

@@ -0,0 +1,63 @@
+# OmniRoute Auto-Combo Engine
+
+> Samosprávné řetězce modelů s adaptivním bodováním
+
+## Jak to funguje
+
+Systém Auto-Combo dynamicky vybírá nejlepšího poskytovatele/model pro každý požadavek pomocí **6faktorové skórovací funkce** :
+
+Faktor | Hmotnost | Popis
+:-- | :-- | :--
+Kvóta | 0,20 | Zbývající kapacita [0..1]
+Zdraví | 0,25 | Jistič: ZAVŘENO=1,0, POLOVINA=0,5, OTEVŘENO=0,0
+Náklady na fakturu | 0,20 | Inverzní náklady (levnější = vyšší skóre)
+LatencyInv | 0,15 | Inverzní latence p95 (rychlejší = vyšší)
+TaskFit | 0,10 | Skóre zdatnost modelu × typu úlohy
+Stabilita | 0,10 | Nízká variabilita latence/chyb
+
+## Balíčky módů
+
+Balíček | Soustředit | Hmotnost klíče
+:-- | :-- | :--
+🚀 **Rychlé odeslání** | Rychlost | latenceInv: 0,35
+💰 **Úspora nákladů** | Ekonomika | Náklady na účet: 0,40
+🎯 **Kvalita na prvním místě** | Nejlepší model | taskFit: 0,40
+📡 **Vhodné pro offline použití** | Dostupnost | kvóta: 0,40
+
+## Samoléčení
+
+- **Dočasné vyloučení** : Skóre < 0,2 → vyloučeno na 5 minut (postupné oddlužování, max. 30 minut)
+- **Upozornění na jistič** : OTEVŘENO → automatické vyloučení; POLOVIČNÍ OTEVŘENO → požadavky sondy
+- **Režim incidentu** : >50% OTEVŘENO → deaktivovat průzkum, maximalizovat stabilitu
+- **Obnova po zchlazení** : Po vyloučení je první požadavek „sonda“ se zkráceným časovým limitem.
+
+## Průzkum banditů
+
+5 % požadavků (konfigurovatelných) je směrováno k náhodným poskytovatelům k prozkoumání. V režimu incidentu je toto nastavení zakázáno.
+
+## API
+
+```bash
+# Create auto-combo
+curl -X POST http://localhost:20128/api/combos/auto \
+  -H "Content-Type: application/json" \
+  -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}'
+
+# List auto-combos
+curl http://localhost:20128/api/combos/auto
+```
+
+## Úkol Fitness
+
+Více než 30 modelů hodnocených v 6 typech úkolů ( `coding` , `review` , `planning` , `analysis` , `debugging` , `documentation` ). Podporuje zástupné znaky (např. `*-coder` → vysoké skóre kódování).
+
+## Soubory
+
+Soubor | Účel
+:-- | :--
+`open-sse/services/autoCombo/scoring.ts` | Skórovací funkce a normalizace poolu
+`open-sse/services/autoCombo/taskFitness.ts` | Vyhledávání vhodnosti modelu × úkolu
+`open-sse/services/autoCombo/engine.ts` | Logika výběru, bandita, rozpočtový strop
+`open-sse/services/autoCombo/selfHealing.ts` | Vyloučení, sondy, režim incidentu
+`open-sse/services/autoCombo/modePacks.ts` | 4 hmotnostní profily
+`src/app/api/combos/auto/route.ts` | REST API

docs/i18n/cs/CHANGELOG.md

@@ -0,0 +1,715 @@
+# Seznam změn
+
+## [Nevydané]
+
+---
+
+## [2.7.8] — 18. 3. 2026
+
+> Sprint: Chyba ukládání rozpočtu + funkce kombinovaného agenta v uživatelském rozhraní + oprava zabezpečení tagu omniModel.
+
+### 🐛 Opravy chyb
+
+- **fix(budget)** : „Uložit limity“ již nevrací chybu 422 — `warningThreshold` se nyní správně odesílá jako zlomek (0–1) místo procenta (0–100) (#451)
+- **oprava(kombinace)** : interní tag mezipaměti `<omniModel>` je nyní odstraněn před přeposíláním požadavků poskytovatelům, čímž se zabrání přerušení relace mezipaměti (#454)
+
+### ✨ Funkce
+
+- **feat(combos)** : Do modálního okna pro vytváření/úpravy komb přidána sekce Funkce agenta – zpřístupnění přepsání `system_message` , `tool_filter_regex` a `context_cache_protection` přímo z dashboardu (#454)
+
+---
+
+## [2.7.7] — 18. 3. 2026
+
+> Sprint: Pád Dockeru pino, oprava workeru Codex CLI responses, synchronizace zámků balíčků.
+
+### 🐛 Opravy chyb
+
+- **oprava(docker)** : `pino-abstract-transport` a `pino-pretty` jsou nyní explicitně kopírovány ve fázi Docker Runner — Samostatné trasování Next.js tyto závislosti peerů přehlíží, což způsobuje pád `Cannot find module pino-abstract-transport` při spuštění (#449)
+- **fix(responses)** : Odstranění `initTranslators()` z trasy `/v1/responses` — worker Next.js `the worker has exited` uncaughtException při požadavcích Codex CLI (#450)
+
+### 🔧 Údržba
+
+- **chore(deps)** : `package-lock.json` je nyní commitován při každém upgradu verze, aby se zajistilo, že Docker `npm ci` použije přesné verze závislostí.
+
+---
+
+## [2.7.5] — 18. 3. 2026
+
+> Sprint: Vylepšení uživatelského rozhraní a oprava kontroly stavu rozhraní Windows CLI.
+
+### 🐛 Opravy chyb
+
+- **fix(ux)** : Zobrazit na přihlašovací stránce nápovědu k výchozímu heslu — noví uživatelé nyní pod polem pro zadání hesla vidí `"Default password: 123456"` (#437)
+- **fix(cli)** : Claude CLI a další nástroje nainstalované npm jsou nyní správně detekovány jako spustitelné ve Windows — spawn používá `shell:true` k rozpoznání `.cmd` wrapperů přes PATHEXT (#447)
+
+---
+
+## [2.7.4] — 18. 3. 2026
+
+> Sprint: Panel vyhledávacích nástrojů, opravy i18n, limity Copilota, oprava validace Serperu.
+
+### 🚀 Vlastnosti
+
+- **feat(search)** : Přidáno hřiště pro vyhledávání (10. koncový bod), stránka s nástroji pro vyhledávání s porovnáním poskytovatelů/kanálovým přeřazením/historií vyhledávání, lokální směrování pro přeřazení, ochrana autorizace ve vyhledávacím API (#443 od @Regis-RCR)
+    - Nová trasa: `/dashboard/search-tools`
+    - Položka postranního panelu v sekci Ladění
+    - `GET /api/search/providers` a `GET /api/search/stats` s ochranou autorizace
+    - Lokální směrování provider_nodes pro `/v1/rerank`
+    - 30+ klíčů i18n ve vyhledávacím jmenném prostoru
+
+### 🐛 Opravy chyb
+
+- **fix(search)** : Oprava normalizátoru Brave News (vracel 0 výsledků), vynucení zkrácení max_results po normalizaci, oprava URL pro načítání stránek z koncových bodů (#443 od @Regis-RCR)
+- **fix(analytics)** : Lokalizace popisků dnů/dat v analytických nástrojích — nahrazení pevně zakódovaných portugalských řetězců pomocí `Intl.DateTimeFormat(locale)` (#444 od @hijak)
+- **oprava(copilot)** : Oprava zobrazení typu účtu GitHub Copilot, filtrování zavádějících řádků neomezených kvót z dashboardu limitů (#445 od @hijak)
+- **oprava(poskytovatelé)** : Zastavit odmítání platných klíčů Serper API – odpovědi jiné než 4xx považovat za platné ověřování (#446 od @hijak)
+
+---
+
+## [2.7.3] — 18. 3. 2026
+
+> Sprint: Oprava záložní kvóty pro přímé API Codexu.
+
+### 🐛 Opravy chyb
+
+- **oprava(codex)** : Blokování týdenních vyčerpávajících účtů v přímém záložním rozhraní API (#440)
+    - Porovnávání prefixů `resolveQuotaWindow()` : `"weekly"` nyní odpovídá klíčům mezipaměti `"weekly (7d)"`
+    - `applyCodexWindowPolicy()` správně vynucuje přepínání `useWeekly` / `use5h`
+    - 4 nové regresní testy (celkem 766)
+
+---
+
+## [2.7.2] — 18. 3. 2026
+
+> Sprint: Opravy kontrastu uživatelského rozhraní v režimu Light.
+
+### 🐛 Opravy chyb
+
+- **fix(logs)** : Oprava kontrastu světelného režimu v protokolech požadavků, tlačítek filtrů a kombinovaného odznaku (#378)
+    - Tlačítka filtrů Chyba/Úspěch/Kombinace jsou nyní čitelná i ve světlém režimu.
+    - Odznak kombinované řady používá ve světlém režimu silnější fialovou barvu
+
+---
+
+## [2.7.1] — 17. 3. 2026
+
+> Sprint: Sjednocené směrování webového vyhledávání (POST /v1/search) s 5 poskytovateli + opravy zabezpečení Next.js 16.1.7 (6 CVE).
+
+### ✨ Nové funkce
+
+- **feat(search)** : Sjednocené směrování webového vyhledávání — `POST /v1/search` s 5 poskytovateli (Serper, Brave, Perplexity, Exa, Tavily)
+    - Automatické přepnutí napříč poskytovateli, více než 6 500 bezplatných vyhledávání/měsíc
+    - Mezipaměť v paměti se slučováním požadavků (konfigurovatelné TTL)
+    - Dashboard: Karta Analytika vyhledávání v `/dashboard/analytics` s rozpisem poskytovatelů, mírou zásahů do mezipaměti a sledováním nákladů
+    - Nové API: `GET /api/v1/search/analytics` pro statistiky vyhledávacích požadavků
+    - Migrace databáze: sloupec `request_type` v `call_logs` pro sledování požadavků mimo chat
+    - Ověření Zod ( `v1SearchSchema` ), chráněné autorizací, náklady zaznamenány pomocí `recordCost()`
+
+### 🔒 Bezpečnost
+
+- **deps** : Next.js 16.1.6 → 16.1.7 — opravuje 6 CVE:
+    - **Kritické** : CVE-2026-29057 (pašování HTTP požadavků přes http-proxy)
+    - **Vysoká** : CVE-2026-27977, CVE-2026-27978 (WebSocket + akce serveru)
+    - **Médium** : CVE-2026-27979, CVE-2026-27980, CVE-2026-jcc7
+
+### 📁 Nové soubory
+
+Soubor | Účel
+--- | ---
+`open-sse/handlers/search.ts` | Vyhledávací obslužná rutina s routováním 5 poskytovatelů
+`open-sse/config/searchRegistry.ts` | Registr poskytovatelů (autorizace, náklady, kvóta, TTL)
+`open-sse/services/searchCache.ts` | Mezipaměť v paměti se slučováním požadavků
+`src/app/api/v1/search/route.ts` | Trasa Next.js (POST + GET)
+`src/app/api/v1/search/analytics/route.ts` | API pro statistiky vyhledávání
+`src/app/(dashboard)/dashboard/analytics/SearchAnalyticsTab.tsx` | Karta analytického panelu
+`src/lib/db/migrations/007_search_request_type.sql` | Migrace databáze
+`tests/unit/search-registry.test.mjs` | 277 řádků jednotkových testů
+
+---
+
+## [2.7.0] — 17. 3. 2026
+
+> Sprint: Funkce inspirované ClawRouterem – příznak volání toolCalling, vícejazyčná detekce záměru, benchmarkem řízený fallback, deduplikace požadavků, plugin RouterStrategy, ceny Grok-4 Fast + GLM-5 + MiniMax M2.5 + Kimi K2.5.
+
+### ✨ Nové modely a ceny
+
+- **feat. (ceny)** : xAI Grok-4 Fast — `$0.20/$0.50 per 1M tokens` , latence 1143 ms p50, podpora volání nástrojů
+- **feat. (ceny)** : xAI Grok-4 (standardní) — `$0.20/$1.50 per 1M tokens` , což je důvodem k odmítnutí.
+- **výkon (ceny)** : GLM-5 přes Z.AI — `$0.5/1M` , 128 tisíc výstupních kontextů
+- **výkon (ceny)** : MiniMax M2.5 — `$0.30/1M input` , uvažování + agentní úkoly
+- **feat.(ceny)** : DeepSeek V3.2 — aktualizované ceny `$0.27/$1.10 per 1M`
+- **výkon (cena)** : Kimi K2.5 přes Moonshot API — přímý přístup k Moonshot API
+- **feat(providers)** : Přidán poskytovatel Z.AI (alias `zai` ) — rodina GLM-5 s výstupem 128K
+
+### 🧠 Směrovací inteligence
+
+- **feat(registry)** : příznak `toolCalling` pro každý model v registru poskytovatelů – kombinace nyní mohou preferovat/vyžadovat modely s možností volání nástrojů
+- **feat(scoring)** : Detekce vícejazyčného záměru pro skórování AutoCombo — skriptové/jazykové vzory PT/ZH/ES/AR ovlivňují výběr modelu podle kontextu požadavku
+- **feat(fallback)** : Řetězce záložních metod řízené benchmarky — skutečná data o latenci (p50 z `comboMetrics` ) používaná k dynamickému přeskupení priorit záložních metod
+- **feat(dedup)** : Vyžádání deduplikace pomocí content-hash — 5sekundové okno idempotence zabraňuje duplicitním voláním poskytovatele v opakovaném pokusu o odeslání klientům
+- **feat(router)** : Připojitelné rozhraní `RouterStrategy` v `autoCombo/routerStrategy.ts` — lze vložit vlastní logiku směrování bez úpravy jádra
+
+### 🔧 Vylepšení serveru MCP
+
+- **feat(mcp)** : 2 nová pokročilá schémata nástrojů: `omniroute_get_provider_metrics` (p50/p95/p99 na poskytovatele) a `omniroute_explain_route` (vysvětlení rozhodnutí o směrování)
+- **feat(mcp)** : Aktualizovány rozsahy autorizace nástroje MCP – přidán rozsah `metrics:read` pro nástroje pro metriky poskytovatelů
+- **feat(mcp)** : `omniroute_best_combo_for_task` nyní akceptuje parametr `languageHint` pro vícejazyčné směrování
+
+### 📊 Pozorovatelnost
+
+- **feat(metrics)** : Soubor `comboMetrics.ts` rozšířen o sledování percentilů latence v reálném čase pro každého poskytovatele/účet.
+- **feat(health)** : Rozhraní Health API ( `/api/monitoring/health` ) nyní vrací pole `p50Latency` a `errorRate` pro každého poskytovatele.
+- **feat(usage)** : Migrace historie použití pro sledování latence pro jednotlivé modely
+
+### 🗄️ Migrace databází
+
+- **feat(migrations)** : Nový sloupec `latency_p50` v tabulce `combo_metrics` — nulový, bezpečný pro stávající uživatele
+
+### 🐛 Opravy chyb / Uzavření
+
+- **close(#411)** : rozlišení hašovaných modulů better-sqlite3 ve Windows — opraveno ve verzi 2.6.10 (f02c5b5)
+- **close(#409)** : Dokončení chatu GitHub Copilot selhává u modelů Claude při připojení souborů – opraveno ve verzi 2.6.9 (838f1d6)
+- **close(#405)** : Duplikát #411 – vyřešeno
+
+## [2.6.10] — 17. 3. 2026
+
+> Oprava pro Windows: stažení předkompilovaného better-sqlite3 bez node-gyp/Pythonu/MSVC (#426).
+
+### 🐛 Opravy chyb
+
+- **fix(install/#426)** : Ve Windows dříve selhával příkaz `npm install -g omniroute` s `better_sqlite3.node is not a valid Win32 application` , protože přiložený nativní binární soubor byl zkompilován pro Linux. Přidává **strategii 1.5** do `scripts/postinstall.mjs` : používá `@mapbox/node-pre-gyp install --fallback-to-build=false` (přiloženo v rámci `better-sqlite3` ) ke stažení správného předkompilovaného binárního souboru pro aktuální OS/arch bez nutnosti použití jakýchkoli nástrojů pro sestavení (žádný node-gyp, žádný Python, žádný MSVC). Vrací se k `npm rebuild` pouze v případě, že stahování selže. Přidává chybové zprávy specifické pro platformu s jasnými pokyny k ruční opravě.
+
+---
+
+## [2.6.9] — 17. 3. 2026
+
+> Opravy CI (t11 s libovolným rozpočtem), oprava chyby č. 409 (souborové přílohy přes Copilot+Claude), korekce pracovního postupu vydání.
+
+### 🐛 Opravy chyb
+
+- **fix(ci)** : Odstranění slova „any“ z komentářů v `openai-responses.ts` a `chatCore.ts` , které neprošly kontrolou rozpočtu t11 `\bany\b` (falešně pozitivní výsledek z počítání regexů v komentářích).
+- **oprava(chatCore)** : Normalizovat nepodporované typy částí obsahu před přeposláním poskytovatelům (#409 — Kurzor odesílá `{type:"file"}` když jsou připojeny soubory `.md` ; Copilot a další poskytovatelé kompatibilní s OpenAI odmítají s "type musí být buď 'image_url', nebo 'text'"; oprava převádí bloky `file` / `document` na `text` a odstraňuje neznámé typy)
+
+### 🔧 Pracovní postup
+
+- **chore(generate-release)** : Přidat pravidlo pro atomický commit — navýšení verze ( `npm version patch` ) MUSÍ proběhnout před commitem souborů funkcí, aby se zajistilo, že tag vždy ukazuje na commit obsahující všechny změny verzí dohromady.
+
+---
+
+## [2.6.8] — 17. 3. 2026
+
+> Sprint: Kombinace jako agent (systémový příkaz + filtr nástrojů), ochrana kontextového ukládání do mezipaměti, automatická aktualizace, podrobné protokoly, MITM Kiro IDE.
+
+### 🗄️ Migrace databází (bez nutnosti aktualizace – bezpečné pro stávající uživatele)
+
+- **005_combo_agent_fields.sql** : `ALTER TABLE combos ADD COLUMN system_message TEXT DEFAULT NULL` , `tool_filter_regex TEXT DEFAULT NULL` , `context_cache_protection INTEGER DEFAULT 0`
+- **006_detailed_request_logs.sql** : Nová tabulka `request_detail_logs` s triggerem kruhového bufferu s 500 záznamy, možnost přihlášení přes přepínač nastavení
+
+### ✨ Funkce
+
+- **feat(combo)** : Přepsání systémových zpráv pro Combo (#399 — pole `system_message` nahrazuje nebo vkládá systémový výzvu před přesměrováním poskytovateli)
+- **feat(combo)** : Regulární výraz filtru nástrojů pro každou kombinaci (#399 — `tool_filter_regex` uchovává pouze nástroje odpovídající vzoru; podporuje formáty OpenAI + Anthropic)
+- **feat(combo)** : Ochrana před ukládáním do mezipaměti kontextu (#401 — `context_cache_protection` označuje odpovědi s `<omniModel>provider/model</omniModel>` a modelem pins pro zajištění kontinuity relace)
+- **feat(settings)** : Automatická aktualizace přes Nastavení (#320 — `GET /api/system/version` + `POST /api/system/update` — kontroluje registr npm a aktualizuje na pozadí s restartem pm2)
+- **feat(logs)** : Podrobné protokoly požadavků (#378 — zachycuje kompletní těla procesů ve 4 fázích: požadavek klienta, přeložený požadavek, odpověď poskytovatele, odpověď klienta — přepínání přihlášení, ořezávání na 64 kB, kruhová vyrovnávací paměť s 500 záznamy)
+- **feat(mitm)** : Profil MITM Kiro IDE (#336 — `src/mitm/targets/kiro.ts` cílí na api.anthropic.com, znovu využívá stávající infrastrukturu MITM)
+
+---
+
+## [2.6.7] — 17. 3. 2026
+
+> Sprint: Vylepšení SSE, rozšíření lokálních provider_nodes, registr proxy, opravy Claude passthrough.
+
+### ✨ Funkce
+
+- **feat(health)** : Kontrola stavu lokálních `provider_nodes` na pozadí s exponenciálním zpožděním (30s→300s) a `Promise.allSettled` pro zamezení blokování (#423, @Regis-RCR)
+- **feat(embeddings)** : Směrování `/v1/embeddings` do lokálních uzlů `provider_nodes` — `buildDynamicEmbeddingProvider()` s ověřením názvu hostitele (#422, @Regis-RCR)
+- **feat(audio)** : Směrování TTS/STT do lokálních `provider_nodes` — `buildDynamicAudioProvider()` s ochranou SSRF (#416, @Regis-RCR)
+- **feat(proxy)** : Registr proxy, API pro správu a zobecnění limitů kvót (#429, @Regis-RCR)
+
+### 🐛 Opravy chyb
+
+- **fix(sse)** : Odstranění polí specifických pro Claude ( `metadata` , `anthropic_version` ), pokud je cíl kompatibilní s OpenAI (#421, @prakersh)
+- **fix(sse)** : Extrahuje využití Claude SSE ( `input_tokens` , `output_tokens` , cache tokeny) v režimu průchozího streamu (#420, @prakersh)
+- **fix(sse)** : Generování záložního `call_id` pro volání nástrojů s chybějícími/prázdnými ID (#419, @prakersh)
+- **oprava(sse)** : Průchod mezi Claudey a Claudey — přední tělo zcela nedotčeno, bez opětovného překladu (#418, @prakersh)
+- **fix(sse)** : Filtrovat osiřelé položky `tool_result` po zhuštění kontextu Claude Code, aby se zabránilo chybám 400 (#417, @prakersh)
+- **fix(sse)** : Přeskočit volání nástrojů s prázdnými názvy v překladači Responses API, aby se zabránilo nekonečným smyčkám `placeholder_tool` (#415, @prakersh)
+- **fix(sse)** : Odstranění prázdných bloků textového obsahu před překladem (#427, @prakersh)
+- **fix(api)** : Přidáno `refreshable: true` do testovací konfigurace Claude OAuth (#428, @prakersh)
+
+### 📦 Závislosti
+
+- Zvýšení `vitest` , `@vitest/*` a související devDependencies (#414, @dependabot)
+
+---
+
+## [2.6.6] — 17. 3. 2026
+
+> Oprava: Kompatibilita s Turbopackem/Dockerem — odebrání protokolu `node:` ze všech importů `src/` .
+
+### 🐛 Opravy chyb
+
+- **fix(build)** : Z příkazů `import` v 17 souborech v `src/` byl odstraněn prefix `node:` protocol. Importy `node:fs` , `node:path` , `node:url` , `node:os` atd. způsobovaly, že `Ecmascript file had an error` v sestaveních Turbopack (Next.js 15 Docker) a při upgradech ze starších globálních instalací npm. Dotčené soubory: `migrationRunner.ts` , `core.ts` , `backup.ts` , `prompts.ts` , `dataPaths.ts` a 12 dalších v `src/app/api/` a `src/lib/` .
+- **chore(workflow)** : Aktualizován `generate-release.md` , aby synchronizace Docker Hubu a nasazení duálního VPS zahrnovaly **povinné** kroky v každé verzi.
+
+---
+
+## [2.6.5] — 17. 3. 2026
+
+> Sprint: filtrování parametrů modelu uvažování, oprava chyby 404 lokálního poskytovatele, poskytovatel Kilo Gateway, vylepšení závislostí.
+
+### ✨ Nové funkce
+
+- **feat(api)** : Přidán **Kilo Gateway** ( `api.kilo.ai` ) jako nový poskytovatel API klíčů (alias `kg` ) — více než 335 modelů, 6 bezplatných modelů, 3 modely automatického směrování ( `kilo-auto/frontier` , `kilo-auto/balanced` , `kilo-auto/free` ). Průchozí modely podporovány přes endpoint `/api/gateway/models` . (PR #408 od @Regis-RCR)
+
+### 🐛 Opravy chyb
+
+- **fix(sse)** : Odstranění nepodporovaných parametrů pro modely uvažování (o1, o1-mini, o1-pro, o3, o3-mini). Modely v rodině `o1` / `o3` odmítají `temperature` , `top_p` , `frequency_penalty` , `presence_penalty` , `logprobs` , `top_logprobs` a `n` s HTTP 400. Parametry jsou nyní odstraňovány na vrstvě `chatCore` před přeposíláním. Používá deklarativní pole `unsupportedParams` pro každý model a předpočítanou mapu O(1) pro vyhledávání. (PR #412 od @Regis-RCR)
+- **fix(sse)** : Kód 404 lokálního poskytovatele nyní vede k **uzamčení pouze modelu (5 sekund)** namísto uzamčení na úrovni připojení (2 minuty). Když lokální inferenční backend (Ollama, LM Studio, oMLX) vrátí kód 404 pro neznámý model, připojení zůstane aktivní a ostatní modely okamžitě pokračují v práci. Také opravuje již existující chybu, kdy `model` nebyl předán funkci `markAccountUnavailable()` . Lokální poskytovatelé detekováni pomocí názvu hostitele ( `localhost` , `127.0.0.1` , `::1` , rozšiřitelné pomocí proměnné prostředí `LOCAL_HOSTNAMES` ). (PR #410 od @Regis-RCR)
+
+### 📦 Závislosti
+
+- `better-sqlite3` 12.6.2 → 12.8.0
+- `undici` 7.24.2 → 7.24.4
+- `https-proxy-agent` 7 → 8
+- `agent-base` 7 → 8
+
+---
+
+## [2.6.4] — 17. 3. 2026
+
+### 🐛 Opravy chyb
+
+- **fix(providers)** : Odstraněny neexistující názvy modelů u 5 poskytovatelů:
+    - **gemini / gemini-cli** : odstraněny `gemini-3.1-pro/flash` a `gemini-3-*-preview` (neexistují v Google API v1beta); nahrazeny `gemini-2.5-pro` , `gemini-2.5-flash` , `gemini-2.0-flash` , `gemini-1.5-pro/flash`
+    - **antigravity** : odstraněny `gemini-3.1-pro-high/low` a `gemini-3-flash` (neplatné interní aliasy); nahrazeny skutečnými modely z verze 2.x
+    - **github (Copilot)** : odstraněny `gemini-3-flash-preview` a `gemini-3-pro-preview` ; nahrazeny `gemini-2.5-flash`
+    - **nvidia** : opraveno `nvidia/llama-3.3-70b-instruct` → `meta/llama-3.3-70b-instruct` (NVIDIA NIM používá pro modely Meta jmenný prostor `meta/` /); přidány `nvidia/llama-3.1-70b-instruct` a `nvidia/llama-3.1-405b-instruct`
+- **fix(db/combo)** : Aktualizováno `free-stack` combo na vzdálené databázi: odstraněno `qw/qwen3-coder-plus` (prošlý obnovovací token), opraveno `nvidia/llama-3.3-70b-instruct` → `nvidia/meta/llama-3.3-70b-instruct` , opraveno `gemini/gemini-3.1-flash` → `gemini/gemini-2.5-flash` , přidáno `if/deepseek-v3.2`
+
+---
+
+## [2.6.3] — 16. 3. 2026
+
+> Sprint: hash-strip zod/pino zapečený do build pipeline, přidán syntetický poskytovatel, opravena cesta VPS PM2.
+
+### 🐛 Opravy chyb
+
+- **fix(build)** : Turbopack hash-strip se nyní spouští při **kompilaci** pro VŠECHNY balíčky — nejen `better-sqlite3` . Krok 5.6 v `prepublish.mjs` prochází každý `.js` v `app/.next/server/` a odstraňuje 16znakovou hexadecimální příponu z jakékoli hashované `require()` . Opravuje `zod-dcb22c...` , `pino-...` atd. MODULE_NOT_FOUND u globálních instalací npm. Zavírá #398.
+- **Oprava (nasazení)** : PM2 na obou VPS ukazoval na zastaralé adresáře git-clone. V globálním balíčku npm překonfigurováno na `app/server.js` . Aktualizován pracovní postup `/deploy-vps` pro použití `npm pack + scp` (registr npm odmítá balíčky o velikosti 299 MB).
+
+### ✨ Funkce
+
+- **feat(provider)** : Synthetic ( [synthetic.new](https://synthetic.new) ) — inference kompatibilní s OpenAI zaměřená na soukromí. `passthroughModels: true` pro dynamický katalog modelů HuggingFace. Počáteční modely: Kimi K2.5, MiniMax M2.5, GLM 4.7, DeepSeek V3.2. (PR #404 od @Regis-RCR)
+
+### 📋 Problémy uzavřeny
+
+- **zavřít #398** : regrese hashování npm — opraveno hashováním při kompilaci v prepublish
+- **triáž č. 324** : Snímek obrazovky s chybou bez kroků – požadovány podrobnosti o reprodukci
+
+---
+
+## [2.6.2] — 16. 3. 2026
+
+> Sprint: hashování modulů kompletně opraveno, sloučeny 2 PR (filtr Anthropic tools + vlastní cesty k endpointům), přidán poskytovatel Alibaba Cloud DashScope, uzavřeny 3 zastaralé problémy.
+
+### 🐛 Opravy chyb
+
+- **fix(build)** : Rozšířeno hashování `externals` webpacku tak, aby zahrnovalo VŠECHNY `serverExternalPackages` , nejen `better-sqlite3` . Next.js 16 Turbopack hashuje `zod` , `pino` a všechny ostatní externí balíčky serveru do názvů jako `zod-dcb22c6336e0bc69` , které za běhu v `node_modules` neexistují. HASH_PATTERN regex catch-all nyní odstraňuje 16znakovou příponu a vrací se k základnímu názvu balíčku. Také přidána `NEXT_PRIVATE_BUILD_WORKER=0` v `prepublish.mjs` pro posílení režimu webpacku a následné skenování po sestavení, které hlásí všechny zbývající hashované reference. (#396, #398, PR #403)
+- **fix(chat)** : Názvy nástrojů v anthropic formátu ( `tool.name` bez wrapperu `.function` ) byly tiše vynechány filtrem prázdných názvů zavedeným v bodě #346. LiteLLM proxyuje požadavky s prefixem `anthropic/` ve formátu Anthropic Messages API, což způsobuje filtrování všech nástrojů a Anthropic vrací chybu `400: tool_choice.any may only be specified while providing tools` . Opraveno návratem k `tool.name` , když chybí `tool.function.name` . Přidáno 8 regresních jednotkových testů. (PR #397)
+
+### ✨ Funkce
+
+- **feat(api)** : Vlastní cesty koncových bodů pro uzly poskytovatelů kompatibilní s OpenAI — konfigurace `chatPath` a `modelsPath` pro každý uzel (např. `/v4/chat/completions` ) v uživatelském rozhraní pro připojení poskytovatele. Zahrnuje migraci databáze ( `003_provider_node_custom_paths.sql` ) a sanitizaci cesty URL (bez `..` traversal, musí začínat znakem `/` ). (PR #400)
+- **feat(provider)** : Alibaba Cloud DashScope přidán jako poskytovatel kompatibilní s OpenAI. Mezinárodní endpoint: `dashscope-intl.aliyuncs.com/compatible-mode/v1` . 12 modelů: `qwen-max` , `qwen-plus` , `qwen-turbo` , `qwen3-coder-plus/flash` , `qwq-plus` , `qwq-32b` , `qwen3-32b` , `qwen3-235b-a22b` . Autorizace: Nosný API klíč.
+
+### 📋 Problémy uzavřeny
+
+- **zavřít #323** : Chyba připojení Cline `[object Object]` – opraveno ve verzi 2.3.7; uživateli bylo doručeno pokyny k upgradu z verze 2.2.9
+- **zavřít #337** : Sledování úvěru Kiro — implementováno ve verzi 2.5.5 (#381); odkázalo uživatele na Dashboard → Použití
+- **triage #402** : Poškozený soubor ARM64 macOS DMG – požadovaná verze macOS, přesná chyba a doporučené alternativní řešení `xattr -d com.apple.quarantine`
+
+---
+
+## [2.6.1] — 15. 3. 2026
+
+> Kritická oprava při spuštění: Globální instalace npm v2.6.0 havarovaly s chybou 500 kvůli chybě hashování názvů modulů Turbopack/webpack v instrumentačním hooku Next.js 16.
+
+### 🐛 Opravy chyb
+
+- **fix(build)** : Vynutit, aby byl `better-sqlite3` vždy vyžadován přesným názvem balíčku v balíčku webpack server. Next.js 16 zkompiloval instrumentační hook do samostatného chunku a vygeneroval `require('better-sqlite3-<hash>')` — hashovaný název modulu, který neexistuje v `node_modules` — přestože byl balíček uveden v `serverExternalPackages` . Do konfigurace webpacku serveru byla přidána explicitní funkce `externals` , takže bundler vždy vygeneruje `require('better-sqlite3')` , čímž se vyřeší `500 Internal Server Error` při spuštění čistých globálních instalací. (#394, PR #395)
+
+### 🔧 CI
+
+- **ci** : Do `npm-publish.yml` přidána `workflow_dispatch` se zabezpečením synchronizace verzí pro manuální spouštěče (#392).
+- **ci** : Přidán `workflow_dispatch` do `docker-publish.yml` , aktualizovány akce GitHubu na nejnovější verze (#392)
+
+---
+
+## [2.6.0] - 15. 3. 2026
+
+> Sprint řešení problémů: Opraveny 4 chyby, vylepšeno uživatelské rozhraní protokolů, přidáno sledování kreditů Kiro.
+
+### 🐛 Opravy chyb
+
+- **oprava(média)** : ComfyUI a SD WebUI se již nezobrazují v seznamu poskytovatelů na stránce Média, pokud nejsou nakonfigurovány — při připojení načtou `/api/providers` a skryjí lokální poskytovatele bez připojení (#390)
+- **oprava(auth)** : Round-robin již po zpoždění znovu nevybírá účty s omezenou rychlostí ihned – `backoffLevel` se nyní používá jako primární třídicí klíč v rotaci LRU (#340)
+- **oprava(oauth)** : iFlow (a další poskytovatelé, kteří přesměrovávají na své vlastní uživatelské rozhraní) již nenechávají modální okno OAuth zaseknuté na „Čekání na autorizaci“ – detektor zavřených vyskakovacích oken automaticky přechází do režimu ručního zadávání URL (#344)
+- **oprava(logy)** : Tabulka protokolů požadavků je nyní čitelná ve světlém režimu – stavové odznaky, počty tokenů a kombinované tagy používají adaptivní `dark:` barevné třídy (#378)
+
+### ✨ Funkce
+
+- **feat(kiro)** : Do fetcheru využití přidáno sledování kreditů Kiro — dotazy `getUserCredits` z endpointu AWS CodeWhisperer (#337)
+
+### 🛠 Domácí práce
+
+- **chore(tests)** : Zarovnání `test:plan3` , `test:fixes` , `test:security` pro použití stejného zavaděče `tsx/esm` jako u `npm test` – eliminuje falešně negativní výsledky rozlišení modulů v cílených bězích (PR #386)
+
+---
+
+## [2.5.9] - 15. 3. 2026
+
+> Oprava nativní passthrough Codexu + posílení validace těla trasy.
+
+### 🐛 Opravy chyb
+
+- **fix(codex)** : Zachovává nativní průchod Responses API pro klienty Codexu – zabraňuje zbytečným mutacím překladu (PR #387)
+- **fix(api)** : Ověřování těl požadavků na trasách pro stanovení cen/synchronizaci a směrování úloh – zabraňuje pádům způsobeným chybně formátovanými vstupy (PR #388)
+- **fix(auth)** : Tajné hodnoty JWT přetrvávají i po restartech pomocí `src/lib/db/secrets.ts` — eliminuje chyby 401 po restartu PM2 (PR #388)
+
+---
+
+## [2.5.8] - 15. 3. 2026
+
+> Oprava sestavení: obnovení připojení VPS přerušeného nedokončeným publikováním v2.5.7.
+
+### 🐛 Opravy chyb
+
+- **oprava(build)** : `scripts/prepublish.mjs` se stále používají, zastaralý příznak `--webpack` způsobuje tiché selhání samostatného sestavení Next.js — publikování npm dokončeno bez `app/server.js` , což narušuje nasazení VPS
+
+---
+
+## [2.5.7] - 15. 3. 2026
+
+> Opravy chyb při zpracování v Media Playground.
+
+### 🐛 Opravy chyb
+
+- **oprava(média)** : Přepis „Vyžadován klíč API“ falešně pozitivní, pokud zvuk neobsahuje žádnou řeč (hudba, ticho) – nyní se místo toho zobrazuje „Není detekována žádná řeč“
+- **oprava(media)** : `upstreamErrorResponse` v `audioTranscription.ts` a `audioSpeech.ts` nyní vrací správný JSON ( `{error:{message}}` ), což umožňuje správnou detekci chyb přihlašovacích údajů 401/403 v MediaPageClient
+- **oprava(média)** : `parseApiError` nyní zpracovává pole `err_msg` v Deepgramu a detekuje `"api key"` v chybových zprávách pro přesnou klasifikaci chyb přihlašovacích údajů.
+
+---
+
+## [2.5.6] - 15. 3. 2026
+
+> Kritické opravy zabezpečení/autentizace: OAuth v Antigravity nefunkční + relace JWT ztraceny po restartu.
+
+### 🐛 Opravy chyb
+
+- **fix(oauth) #384** : Antigravity Google OAuth nyní správně odesílá `client_secret` do koncového bodu tokenu. Záložní volbou pro `ANTIGRAVITY_OAUTH_CLIENT_SECRET` byl prázdný řetězec, což je chyba – `client_secret` tedy nebyl v požadavku nikdy zahrnut, což způsobovalo chyby `"client_secret is missing"` u všech uživatelů bez vlastní proměnné prostředí. Zavírá #383.
+- **fix(auth) #385** : `JWT_SECRET` je nyní ukládán do SQLite ( `namespace='secrets'` ) při první generaci a znovu načten při následných spuštěních. Dříve byl při každém spuštění procesu generován nový náhodný tajný klíč, který po jakémkoli restartu nebo upgradu zneplatňoval všechny existující soubory cookie/relace. Ovlivňuje `JWT_SECRET` i `API_KEY_SECRET` . Zavírá #382.
+
+---
+
+## [2.5.5] - 15. 3. 2026
+
+> Oprava odstranění duplicitních dat v seznamu modelů, posílení samostatného sestavení Electronu a sledování kreditů Kiro.
+
+### 🐛 Opravy chyb
+
+- **fix(models) #380** : `GET /api/models` nyní zahrnuje aliasy poskytovatelů při sestavování filtru aktivního poskytovatele — modely pro `claude` (alias `cc` ) a `github` (alias `gh` ) se vždy zobrazovaly bez ohledu na to, zda bylo nakonfigurováno připojení, protože klíče `PROVIDER_MODELS` jsou aliasy, ale připojení k databázi jsou uložena pod ID poskytovatelů. Opraveno rozšířením každého aktivního ID poskytovatele o jeho alias pomocí `PROVIDER_ID_TO_ALIAS` . Zavírá #353.
+- **fix(electron) #379** : Nové `scripts/prepare-electron-standalone.mjs` připraví vyhrazený balíček `/.next/electron-standalone` před zabalením Electronu. Pokud je `node_modules` symbolický odkaz, dojde k ukončení s chybou (electron-builder by na sestavovací stroj odeslal běhovou závislost). Multiplatformní sanitizace cest pomocí `path.basename` . Od @kfiramar.
+
+### ✨ Nové funkce
+
+- **feat(kiro) #381** : Sledování zůstatku kreditů Kiro — koncový bod využití nyní vrací data o kreditech pro Kiro účty voláním `codewhisperer.us-east-1.amazonaws.com/getUserCredits` (stejný koncový bod, který Kiro IDE používá interně). Vrací zbývající kredity, celkový limit, datum obnovení a úroveň předplatného. Uzavírá #337.
+
+## [2.5.4] - 15. 3. 2026
+
+> Oprava spouštění loggeru, oprava zabezpečení přihlašovacího bootstrapu a vylepšení spolehlivosti vývojářského HMR. Zlepšení infrastruktury CI.
+
+### 🐛 Opravy chyb (PR #374, #375, #376 od @kfiramar)
+
+- **oprava(logger) #376** : Obnovit cestu k protokolovacímu modulu pino transport — `formatters.level` v kombinaci s `transport.targets` je odmítnut modulem pino. Konfigurace založené na transportu nyní odstraňují formátovač úrovní pomocí funkce `getTransportCompatibleConfig()` . Také opravuje numerické mapování úrovní v `/api/logs/console` : `30→info, 40→warn, 50→error` (bylo posunuto o jednu).
+- **oprava(login) #375** : Přihlašovací stránka se nyní bootuje z veřejného endpointu `/api/settings/require-login` namísto chráněného `/api/settings` . V nastaveních chráněných heslem dostávala stránka předběžného ověřování chybu 401 a zbytečně se vracela k bezpečným výchozím hodnotám. Veřejná trasa nyní vrací všechna bootstrapová metadata ( `requireLogin` , `hasPassword` , `setupComplete` ) s konzervativní fallback chybou 200.
+- **oprava(dev) #374** : Přidání `localhost` a `127.0.0.1` do `allowedDevOrigins` v `next.config.mjs` — HMR websocket byl blokován při přístupu k aplikaci přes loopback adresu, což opakovaně produkovalo varování cross-origin.
+
+### 🔧 CI a infrastruktura
+
+- **Oprava chyb ESLint OOM** : `eslint.config.mjs` nyní ignoruje `vscode-extension/**` , `electron/**` , `docs/**` , `app/.next/**` a `clipr/**` — ESLint havaroval s chybou JS haldy OOM skenováním binárních blobů a kompilovaných chunků VS Code.
+- **Oprava jednotkového testu** : Z 2 testovacích souborů byl odstraněn zastaralý `ALTER TABLE provider_connections ADD COLUMN "group"` – sloupec je nyní součástí základního schématu (přidáno v #373), což způsobovalo `SQLITE_ERROR: duplicate column name` při každém spuštění CI.
+- **Pre-commit hook** : Do `.husky/pre-commit` přidán `npm run test:unit` — unit testy nyní blokují poškozené commity dříve, než se dostanou do CI.
+
+## [2.5.3] - 14. 3. 2026
+
+> Opravy kritických chyb: migrace schématu databáze, načítání spouštěcího prostředí, mazání chyb poskytovatele a oprava popisků i18n. Vylepšení kvality kódu nad každým PR.
+
+### 🐛 Opravy chyb (PR #369, #371, #372, #373 od @kfiramar)
+
+- **oprava(db) #373** : Přidání sloupce `provider_connections.group` do základního schématu + migrace zpětného doplnění pro existující databáze — sloupec byl použit ve všech dotazech, ale chyběl v definici schématu
+- **fix(i18n) #371** : Nahrazení neexistujícího klíče `t("deleteConnection")` existujícím `providers.delete` — oprava `MISSING_MESSAGE: providers.deleteConnection` na stránce s podrobnostmi o poskytovateli
+- **oprava(auth) #372** : Vymazat zastaralá chybová metadata ( `errorCode` , `lastErrorType` , `lastErrorSource` ) z účtů poskytovatelů po skutečném zotavení – dříve se obnovené účty zobrazovaly jako selhané
+- **oprava(startup) #369** : Sjednocení načítání env napříč `npm run start` , `run-standalone.mjs` a Electron s ohledem na prioritu `DATA_DIR/.env → ~/.omniroute/.env → ./.env` — zabránění generování nového `STORAGE_ENCRYPTION_KEY` přes existující šifrovanou databázi
+
+### 🔧 Kvalita kódu
+
+- Zdokumentované vzory `result.success` vs. `response?.ok` v `auth.ts` (oba úmyslné, nyní vysvětlené)
+- Normalizované `overridePath?.trim()` v `electron/main.js` pro shodu s `bootstrap-env.mjs`
+- Přidán komentář k objednávce sloučení `preferredEnv` při spuštění Electronu
+
+> Oprava kvót pro účty Codex s automatickou rotací, rychlým přepínáním úrovní, modelem gpt-5.4 a označením analytických nástrojů.
+
+### ✨ Nové funkce (PR #366, #367, #368)
+
+- **Zásady kvót Codexu (PR #366)** : Okno kvóty 5 hodin/týden pro účet se přepíná v dashboardu poskytovatele. Účty jsou automaticky přeskočeny, když povolená okna dosáhnou prahové hodnoty 90 %, a znovu povoleny po `resetAt` . Zahrnuje `quotaCache.ts` s vedlejším efektem pro získávání statusu zdarma.
+- **Přepínání rychlé úrovně Codexu (PR #367)** : Dashboard → Nastavení → Úroveň služeb Codexu. Přepínání ve výchozím nastavení vkládá `service_tier: "flex"` pouze pro požadavky Codexu, což snižuje náklady o ~80 %. Celý stack: karta UI + koncový bod API + exekutor + překladač + obnovení po spuštění.
+- **Model gpt-5.4 (PR #368)** : Přidává `cx/gpt-5.4` a `codex/gpt-5.4` do registru modelů Codex. Regresní test je součástí.
+
+### 🐛 Opravy chyb
+
+- **oprava č. 356** : Analytické grafy (Nejlepší poskytovatel, Podle účtu, Rozdělení poskytovatelů) nyní zobrazují lidsky čitelné názvy/štítky poskytovatelů namísto nezpracovaných interních ID u poskytovatelů kompatibilních s OpenAI.
+
+> Hlavní vydání: strategie striktně náhodného směrování, řízení přístupu k klíčům API, skupiny připojení, synchronizace externích cen a opravy kritických chyb pro modely myšlení, kombinované testování a validaci názvů nástrojů.
+
+### ✨ Nové funkce (PR #363 a #365)
+
+- **Strategie striktně náhodného směrování** : Fisher-Yatesův náhodný balíček s garancí neopakování a serializací mutexů pro souběžné požadavky. Nezávislé balíčky pro každé kombo a providera.
+- **Řízení přístupu ke klíčům API** : `allowedConnections` (omezení připojení, která může klíč používat), `is_active` (povolení/zakázání klíče s kódem 403), `accessSchedule` (řízení přístupu na základě času), přepínání `autoResolve` , přejmenování klíčů pomocí PATCH.
+- **Skupiny připojení** : Seskupování připojení poskytovatelů podle prostředí. Harmonické zobrazení na stránce Limity s perzistencí localStorage a inteligentním automatickým přepínáním.
+- **Synchronizace externích cen (LiteLLM)** : 3stupňové rozlišení cen (uživatelské přepsání → synchronizace → výchozí hodnoty). Možnost přihlášení přes `PRICING_SYNC_ENABLED=true` . Nástroj MCP `omniroute_sync_pricing` . 23 nových testů.
+- **i18n** : 30 jazyků aktualizováno strategií striktní náhodnosti, řetězce pro správu klíčů API. pt-BR plně přeloženo.
+
+### 🐛 Opravy chyb
+
+- **Oprava č. 355** : Časový limit nečinnosti streamu zvýšen z 60 s na 300 s – zabraňuje přerušení modelů s rozšířeným myšlením (claude-opus-4-6, o3 atd.) během dlouhých fází uvažování. Konfigurovatelné pomocí `STREAM_IDLE_TIMEOUT_MS` .
+- **Oprava č. 350** : Kombinovaný test nyní obchází `REQUIRE_API_KEY=true` pomocí interní hlavičky a univerzálně používá formát kompatibilní s OpenAI. Časový limit prodloužen z 15 s na 20 s.
+- **oprava #346** : Nástroje s prázdným `function.name` (přeposláno Claudem Code) jsou nyní filtrovány předtím, než je obdrží upstreamoví poskytovatelé, čímž se zabrání chybám „Neplatný vstup[N].name: prázdný řetězec“.
+
+### 🗑️ Uzavřené problémy
+
+- **#341** : Sekce ladění odstraněna – nahrazena je `/dashboard/logs` a `/dashboard/health` .
+
+> Podpora API Key Round-Robin pro nastavení poskytovatelů s více klíči a potvrzení již zavedeného směrování zástupných znaků a rolování oken kvót.
+
+### ✨ Nové funkce
+
+- **Round-Robin klíčů API (T07)** : Připojení poskytovatelů nyní mohou obsahovat více klíčů API (Upravit připojení → Další klíče API). Požadavky rotují round-robin mezi primárními a dalšími klíči pomocí `providerSpecificData.extraApiKeys[]` . Klíče jsou uchovávány v paměti indexované pro každé připojení – nejsou nutné žádné změny schématu databáze.
+
+### 📝 Již implementováno (potvrzeno auditem)
+
+- **Směrování modelu s wildcard znaky (T13)** : soubor `wildcardRouter.ts` s porovnáváním zástupných znaků ve stylu glob ( `gpt*` , `claude-?-sonnet` atd.) je již integrován do `model.ts` s hodnocením specificity.
+- **Posunování okna kvót (T08)** : `accountFallback.ts:isModelLocked()` již automaticky posouvá okno vpřed – pokud `Date.now() > entry.until` , zámek se okamžitě smaže (žádné blokování zastaralých funkcí).
+
+> Vylepšení uživatelského rozhraní, doplnění strategií směrování a elegantní zpracování chyb pro omezení využití.
+
+### ✨ Nové funkce
+
+- **Strategie směrování Fill-First a P2C** : Do výběru kombinované strategie přidány strategie `fill-first` (vyčerpání kvóty před přesunem) a `p2c` (výběr Power-of-Two-Choices s nízkou latencí) s kompletními panely s pokyny a barevně odlišenými odznaky.
+- **Přednastavené modely Free Stack** : Vytvoření kombinace pomocí šablony Free Stack nyní automaticky vyplní 7 nejlepších modelů bezplatných poskytovatelů ve své třídě (Gemini CLI, Kiro, iFlow×2, Qwen, NVIDIA NIM, Groq). Uživatelé stačí aktivovat poskytovatele a ihned získají kombinaci 0 $/měsíc.
+- **Širší kombo modální okno** : Modální okno pro vytvoření/úpravu komba nyní používá `max-w-4xl` pro pohodlnou úpravu velkých komb.
+
+### 🐛 Opravy chyb
+
+- **Stránka s limity HTTP 500 pro Codex a GitHub** : `getCodexUsage()` a `getGitHubUsage()` nyní vracejí uživatelsky přívětivou zprávu, když poskytovatel vrátí 401/403 (vypršelý token), místo aby vyvolaly chybu 500 na stránce s limity.
+- **Falešně pozitivní MaintenanceBanner** : Banner již při načítání stránky falešně nezobrazuje „Server je nedostupný“. Opraveno okamžitým voláním `checkHealth()` při připojení a odstraněním zastaralého uzavření `show` -state.
+- **Popisky ikon poskytovatele** : Tlačítka s ikonami pro úpravu (tužka) a odstranění v řádku připojení poskytovatele nyní obsahují nativní HTML popisky – všech 6 ikon akcí je nyní samodokumentovaných.
+
+> Několik vylepšení z analýzy problémů komunity, podpora nových poskytovatelů, opravy chyb pro sledování tokenů, směrování modelů a spolehlivost streamování.
+
+### ✨ Nové funkce
+
+- **Inteligentní směrování s ohledem na úlohy (T05)** : Automatický výběr modelu na základě typu obsahu požadavku — kódování → deepseek-chat, analýza → gemini-2.5-pro, vision → gpt-4o, sumarizace → gemini-2.5-flash. Konfigurovatelné v Nastavení. Nové API `GET/PUT/POST /api/settings/task-routing` .
+- **Poskytovatel HuggingFace** : Přidán HuggingFace Router jako poskytovatel kompatibilní s OpenAI s Llama 3.1 70B/8B, Qwen 2.5 72B, Mistral 7B, Phi-3.5 Mini.
+- **Poskytovatel Vertex AI** : Přidán poskytovatel Vertex AI (Google Cloud) s Gemini 2.5 Pro/Flash, Gemma 2 27B, Claude přes Vertex.
+- **Nahrávání souborů do Playgroundu** : Nahrávání zvuku pro přepis, nahrávání obrázků pro modely vidění (automatická detekce podle názvu modelu), inline vykreslování obrázků pro výsledky generování obrázků.
+- **Vizuální zpětná vazba při výběru modelu** : Již přidané modely v kombinovaném výběru nyní zobrazují zelený odznak ✓ – zabraňuje záměně duplicitních modelů.
+- **Kompatibilita s Qwen (PR #352)** : Aktualizováno nastavení otisků uživatelského agenta a rozhraní CLI pro kompatibilitu s poskytovateli Qwen.
+- **Správa stavu round-robin (PR #349)** : Vylepšená logika round-robin pro zpracování vyloučených účtů a správné udržování stavu rotace.
+- **Uživatelská zkušenost se schránkou (PR #360)** : Vylepšené operace se schránkou s možností zálohování pro nezabezpečené kontexty; vylepšení normalizace nástroje Claude.
+
+### 🐛 Opravy chyb
+
+- **Oprava č. 302 – OpenAI SDK stream=False zanechává tool_calls** : T01 Accept header negotiation již nevynucuje streamování, pokud je `body.stream` explicitně `false` . Způsobovalo to tiché zanechávání tool_calls při použití OpenAI Python SDK v režimu bez streamování.
+- **Oprava č. 73 — Claude Haiku směrován do OpenAI bez prefixu poskytovatele** : modely `claude-*` odeslané bez prefixu poskytovatele nyní správně směrují k poskytovateli `antigravity` (antropickému). Přidána také heuristika `gemini-*` / `gemma-*` → `gemini` .
+- **Oprava č. 74 – Počet tokenů je pro streamování Antigravity/Claude vždy 0** : Událost SSE `message_start` , která obsahuje `input_tokens` nebyla analyzována funkcí `extractUsage()` , což způsobovalo pokles všech počtů vstupních tokenů. Sledování vstupních/výstupních tokenů nyní funguje správně pro streamované odpovědi.
+- **Oprava č. 180 – Duplikáty importovaných modelů bez zpětné vazby** : `ModelSelectModal` nyní zobrazuje ✓ zelené zvýraznění u modelů, které jsou již v kombinaci, takže je zřejmé, že jsou již přidány.
+- **Chyby generování mediálních stránek** : Výsledky obrázků se nyní vykreslují jako tagy `<img>` místo nezpracovaného JSON. Výsledky přepisu se zobrazují jako čitelný text. Chyby přihlašovacích údajů zobrazují oranžový banner místo tiché chyby.
+- **Tlačítko pro obnovení tokenu na stránce poskytovatele** : Pro poskytovatele OAuth bylo přidáno uživatelské rozhraní pro ruční obnovení tokenu.
+
+### 🔧 Vylepšení
+
+- **Registr poskytovatelů** : Do `providerRegistry.ts` a `providers.ts` (frontend) přidány prvky HuggingFace a Vertex AI.
+- **Čtení mezipaměti** : Nový `src/lib/db/readCache.ts` pro efektivní ukládání do mezipaměti čtení databáze.
+- **Mezipaměť kvót** : Vylepšená mezipaměť kvót s vyřazením na základě TTL.
+
+### 📦 Závislosti
+
+- `dompurify` → 3.3.3 (PR #347)
+- `undici` → 7.24.2 (PR #348, #361)
+- `docker/setup-qemu-action` → v4 (PR #342)
+- `docker/setup-buildx-action` → v4 (PR #343)
+
+### 📁 Nové soubory
+
+Soubor | Účel
+--- | ---
+`open-sse/services/taskAwareRouter.ts` | Logika směrování s ohledem na úlohy (7 typů úloh)
+`src/app/api/settings/task-routing/route.ts` | API pro konfiguraci směrování úloh
+`src/app/api/providers/[id]/refresh/route.ts` | Ruční aktualizace tokenu OAuth
+`src/lib/db/readCache.ts` | Efektivní mezipaměť pro čtení databáze
+`src/shared/utils/clipboard.ts` | Zpevněná schránka s funkcí
+
+## [2.4.1] - 13. 3. 2026
+
+### 🐛 Oprava
+
+- **Modální okno s kombinacemi: Šablona Volný zásobník viditelná a výrazná** – Šablona Volný zásobník byla skrytá (4. v mřížce se 3 sloupci). Opraveno: přesunuto na pozici 1, přepnuto na mřížku 2x2, takže jsou viditelné všechny 4 šablony, zelený okraj + zvýraznění odznaku ZDARMA.
+
+## [2.4.0] - 13. 3. 2026
+
+> **Hlavní vydání** – ekosystém Free Stack, přepracované transkripční hřiště, více než 44 poskytovatelů, komplexní dokumentace k bezplatné úrovni a vylepšení uživatelského rozhraní napříč všemi oblastmi.
+
+### ✨ Funkce
+
+- **Kombinace: Šablona Free Stack** — Nová 4. šablona „Free Stack (0 $)“ využívající round-robin napříč Kiro + iFlow + Qwen + Gemini CLI. Při prvním použití doporučuje předpřipravenou kombinaci s nulovými náklady.
+- **Média/Přepis: Deepgram jako výchozí** – Deepgram (Nova 3, 200 dolarů zdarma) je nyní výchozím poskytovatelem přepisu. AssemblyAI (50 dolarů zdarma) a Groq Whisper (navždy zdarma) jsou zobrazeny s odznaky bezplatného kreditu.
+- **README: Sekce „Začít zdarma“** – Nová tabulka s 5 kroky v předběžném souboru README, která ukazuje, jak nastavit umělou inteligenci s nulovými náklady během několika minut.
+- **README: Kombinace bezplatného přepisu** – Nová sekce s návrhem kombinací Deepgram/AssemblyAI/Groq a informacemi o bezplatném kreditu pro každého poskytovatele.
+- **providers.ts: příznak hasFree** — NVIDIA NIM, Cerebras a Groq označené odznakem hasFree a freeNote pro uživatelské rozhraní poskytovatelů.
+- **i18n: klíče templateFreeStack** — kombinovaná šablona Free Stack přeložená a synchronizovaná do všech 30 jazyků.
+
+## [2.3.16] - 13. 3. 2026
+
+### 📖 Dokumentace
+
+- **README: 44+ poskytovatelů** — Všechny 3 výskyty výrazu „36+ poskytovatelů“ byly aktualizovány na „44+“, což odráží skutečný počet kódové základny (44 poskytovatelů v souboru providers.ts).
+- **README: Nová sekce „🆓 Bezplatné modely – Co skutečně získáte“** – Přidána tabulka 7 poskytovatelů s limity rychlosti pro každý model pro: Kiro (Claude neomezeně přes AWS Builder ID), iFlow (5 modelů neomezeně), Qwen (4 modely neomezeně), Gemini CLI (180K/měsíc), NVIDIA NIM (~40 RPM dev-forever), Cerebras (1M tok/den / 60K TPM), Groq (30 RPM / 14.4K RPD). Zahrnuje doporučení pro kombinaci /usr/bin/bash Ultimate Free Stack.
+- **Soubor README: Aktualizace cenové tabulky** – přidán Cerebras do úrovně API KEY, opravena změna NVIDIA z „1000 kreditů“ na „navždy zdarma pro vývojáře“, aktualizovány počty a názvy modelů iFlow/Qwen
+- **README: Modely iFlow 8→5** (s názvy: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2)
+- **README: Modely Qwen 3→4** (s názvy: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model)
+
+## [2.3.15] - 13. 3. 2026
+
+### ✨ Funkce
+
+- **Panel automatických kombinací (priorita úrovně)** : Přidána `🏷️ Tier` jako 7. faktor bodování v zobrazení rozpisu faktorů `/dashboard/auto-combo` – nyní je viditelných všech 7 faktorů bodování automatických kombinací.
+- **i18n — sekce autoCombo** : Pro panel Auto-Combo bylo přidáno 20 nových překladových klíčů ( `title` , `status` , `modePack` , `providerScores` , `factorTierPriority` atd.) do všech 30 jazykových souborů.
+
+## [2.3.14] - 13. 3. 2026
+
+### 🐛 Opravy chyb
+
+- **iFlow OAuth (#339)** : Obnoven platný výchozí `clientSecret` – dříve to byl prázdný řetězec, který při každém pokusu o připojení způsoboval chybu „Chybné přihlašovací údaje klienta“. Veřejné přihlašovací údaje jsou nyní výchozím záložním nastavením (lze je přepsat pomocí proměnné prostředí `IFLOW_OAUTH_CLIENT_SECRET` ).
+- **MITM server nenalezen (#335)** : `prepublish.mjs` nyní kompiluje `src/mitm/*.ts` do JavaScriptu pomocí `tsc` před zkopírováním do npm balíčku. Dříve se kopírovaly pouze nezpracované soubory `.ts` – což znamenalo, že `server.js` nikdy neexistoval v globálních instalacích npm/Volta.
+- **Chybí projectId v GeminiCLI (#338)** : Namísto vyvolání hardwarové chyby 500, když v uložených přihlašovacích údajích chybí `projectId` (např. po restartu Dockeru), OmniRoute nyní zaznamená varování a pokusí se o požadavek – vrátí smysluplnou chybu na straně poskytovatele místo pádu OmniRoute.
+- **Neshoda verzí balíčku Electron (#323)** : Synchronizována verze `electron/package.json` s verzí `2.3.13` (dříve `2.0.13` ), takže binární verze pro stolní počítače odpovídá balíčku npm.
+
+### ✨ Nové modely (#334)
+
+- **Kiro** : `claude-sonnet-4` , `claude-opus-4.6` , `deepseek-v3.2` , `minimax-m2.1` , `qwen3-coder-next` , `auto`
+- **Kodex** : `gpt5.4`
+
+### 🔧 Vylepšení
+
+- **Bodové hodnocení (API + validace)** : Do schématu Zod `ScoringWeights` a trasy API `combos/auto` přidána `tierPriority` (váha `0.05` ) – 7. faktor bodování je nyní plně akceptován rozhraním REST API a ověřován na vstupu. Váha `stability` upravena z `0.10` na `0.05` , aby celkový součet zůstal `1.0` .
+
+### ✨ Nové funkce
+
+- **Víceúrovňové bodování kvót (automatické kombinování)** : Přidána `tierPriority` jako 7. faktor bodování – účty s úrovněmi Ultra/Pro jsou nyní upřednostňovány před úrovněmi Free, pokud jsou ostatní faktory stejné. Nová volitelná pole `accountTier` a `quotaResetIntervalSecs` u `ProviderCandidate` . Všechny 4 balíčky režimů byly aktualizovány ( `ship-fast` , `cost-saver` , `quality-first` , `offline-friendly` ).
+- **Záložní model v rámci rodiny (T5)** : Pokud model není k dispozici (404/400/403), OmniRoute se nyní automaticky vrátí k sourozeneckým modelům ze stejné rodiny, než vrátí chybu ( `modelFamilyFallback.ts` ).
+- **Konfigurovatelný časový limit API Bridge** : Proměnná prostředí `API_BRIDGE_PROXY_TIMEOUT_MS` umožňuje operátorům ladit časový limit proxy (výchozí hodnota 30 s). Opravuje chyby 504 při pomalých odezvách upstreamu. (#332)
+- **Historie hvězd** : Widget star-history.com byl ve všech 30 souborech README nahrazen widgetem starchart.cc ( `?variant=adaptive` ) – přizpůsobuje se světlému/tmavému tématu a aktualizacím v reálném čase.
+
+### 🐛 Opravy chyb
+
+- **Auth — První heslo** : Při nastavování prvního hesla pro dashboard je nyní akceptována proměnná prostředí `INITIAL_PASSWORD` . Používá `timingSafeEqual` pro porovnávání v konstantním čase, čímž se zabraňuje útokům na časování. (#333)
+- **Zkrácení souboru README** : Opraven chybějící uzavírací tag `</details>` v sekci Řešení problémů, který způsoboval, že GitHub zastavil vykreslování všeho pod ním (Tech Stack, Dokumentace, Plán, Přispěvatelé).
+- **Instalace pnpm** : Z `package.json` byl odstraněn redundantní přepis `@swc/helpers` , který kolidoval s přímou závislostí a způsoboval chyby `EOVERRIDE` na pnpm. Přidána konfigurace `pnpm.onlyBuiltDependencies` .
+- **Vložení cesty do CLI (T12)** : V `cliRuntime.ts` byl přidán validátor `isSafePath()` pro blokování procházení cesty a metaznaků shellu v proměnných prostředí `CLI_*_BIN` .
+- **CI** : Po odstranění přepsání byl obnoven `package-lock.json` pro opravu chyb `npm ci` v akcích GitHubu.
+
+### 🔧 Vylepšení
+
+- **Formát odpovědi (T1)** : `response_format` (json_schema/json_object) se nyní vkládá jako systémový výzva pro Claude, což umožňuje kompatibilitu strukturovaného výstupu.
+- **429 Opakování (T2)** : Opakování odpovědí 429 v rámci URL (2× pokusy s 2s zpožděním) před návratem k další URL.
+- **Záhlaví rozhraní příkazového řádku Gemini (T3)** : Přidány záhlaví otisků prstů `User-Agent` a `X-Goog-Api-Client` pro kompatibilitu s rozhraním příkazového řádku Gemini.
+- **Cenový katalog (T9)** : Přidány ceníky pro `deepseek-3.1` , `deepseek-3.2` a `qwen3-coder-next` .
+
+### 📁 Nové soubory
+
+Soubor | Účel
+--- | ---
+`open-sse/services/modelFamilyFallback.ts` | Definice modelových rodin a logika záložních řešení v rámci rodiny
+
+### Opraveno
+
+- **KiloCode** : časový limit kontroly stavu kilocode již byl opraven ve verzi 2.3.11.
+- **OpenCode** : Přidání opencode do registru cliRuntime s 15sekundovým časovým limitem pro kontrolu stavu
+- **OpenClaw / Cursor** : Prodloužení časového limitu kontroly stavu na 15 sekund pro varianty s pomalým startem.
+- **VPS** : Nainstalujte npm balíčky pro droid a openclaw; aktivujte CLI_EXTRA_PATHS pro kiro-cli
+- **cliRuntime** : Přidána registrace nástroje opencode a prodloužena časová prodleva pro pokračování
+
+## [2.3.11] - 12. 3. 2026
+
+### Opraveno
+
+- **KiloCode healthcheck** : Zvýšení `healthcheckTimeoutMs` z 4000 ms na 15000 ms — kilocode při spuštění vykreslí banner s logem ASCII, což v prostředích s pomalým/studeným startem způsobí chybu `healthcheck_failed`
+
+## [2.3.10] - 12. 3. 2026
+
+### Opraveno
+
+- **Lint** : Oprava chyby `check:any-budget:t11` — nahrazení `as any` za `as Record<string, unknown>` v OAuthModal.tsx (3 výskyty)
+
+### Dokumenty
+
+- **CLI-TOOLS.md** : Kompletní průvodce všemi 11 nástroji CLI (claude, codex, gemini, opencode, cline, kilocode, continue, kiro-cli, cursor, droid, openclaw)
+- **i18n** : CLI-TOOLS.md synchronizovaný do 30 jazyků s přeloženým názvem a úvodem
+
+## [2.3.8] - 12. 3. 2026
+
+## [2.3.9] - 12. 3. 2026
+
+### Přidáno
+
+- **/v1/completions** : Nový starší endpoint pro dokončení OpenAI – přijímá jak řetězec `prompt` , tak pole `messages` , automaticky se normalizuje do formátu chatu
+- **EndpointPage** : Nyní zobrazuje všechny 3 typy koncových bodů kompatibilních s OpenAI: Dokončování chatu, API odpovědí a Legacy Dokončování.
+- **i18n** : Přidán `completionsLegacy/completionsLegacyDesc` do 30 jazykových souborů.
+
+### Opraveno
+
+- **OAuthModal** : Oprava zobrazení objektu `[object Object]` u všech chyb připojení OAuth – správně extrahovat `.message` z objektů odpovědí na chyby ve všech 3 `throw new Error(data.error)` (exchange, device-code, authorize)
+- Ovlivňuje Cline, Codex, GitHub, Qwen, Kiro a všechny ostatní poskytovatele OAuth.
+
+## [2.3.7] - 12. 3. 2026
+
+### Opraveno
+
+- **Cline OAuth** : Před dekódování base64 přidána `decodeURIComponent` , aby autorizační kódy kódované pomocí URL z URL zpětného volání byly správně analyzovány, opraveny chyby „neplatný nebo vypršený autorizační kód“ ve vzdálených instalacích (LAN IP).
+- **Cline OAuth** : `mapTokens` nyní vyplňuje `name = firstName + lastName || email` , takže účty Cline zobrazují skutečná uživatelská jména místo „Account #ID“.
+- **Názvy účtů OAuth** : Všechny toky výměny OAuth (exchange, poll, poll-callback) nyní normalizují `name = email` pokud název chybí, takže každý účet OAuth zobrazuje svůj e-mail jako zobrazovaný popisek v dashboardu Poskytovatelé.
+- **Názvy účtů OAuth** : V souboru `db/providers.ts` byla odstraněna sekvenční záložní možnost „Účet N“ – účty bez e-mailu/jména nyní používají stabilní popisek založený na ID pomocí `getAccountDisplayName()` namísto sekvenčního čísla, které se mění při smazání účtů.
+
+## [2.3.6] - 12. 3. 2026
+
+### Opraveno
+
+- **Dávkový test poskytovatele** : Opraveno schéma Zod pro akceptování `providerId: null` (frontend odesílá null pro režimy bez poskytovatele); nesprávně vracelo „Neplatný požadavek“ pro všechny dávkové testy.
+- **Modální okno testování poskytovatele** : Opraveno zobrazení `[object Object]` normalizací objektů chyb API na řetězce před vykreslením v `setTestResults` a `ProviderTestResultsView`
+- **i18n** : Do `en.json` přidány chybějící klíče `cliTools.toolDescriptions.opencode` , `cliTools.toolDescriptions.kiro` , `cliTools.guides.opencode` , `cliTools.guides.kiro`
+- **i18n** : Synchronizováno chybějící 1111 klíčů ve všech 29 souborech v neanglických jazycích s použitím anglických hodnot jako záložních hodnot.
+
+## [2.3.5] - 11. 3. 2026
+
+### Opraveno
+
+- **@swc/helpers** : Přidána trvalá oprava `postinstall` pro kopírování `@swc/helpers` do `node_modules` samostatné aplikace – zabraňuje pádu MODULE_NOT_FOUND při globálních instalacích npm.
+
+## [2.3.4] - 10. 3. 2026
+
+### Přidáno
+
+- Integrace více poskytovatelů a vylepšení dashboardu

docs/i18n/cs/CLI-TOOLS.md

@@ -0,0 +1,344 @@
+# Průvodce nastavením nástrojů CLI — OmniRoute
+
+Tato příručka vysvětluje, jak nainstalovat a nakonfigurovat všechny podporované nástroje CLI pro kódování umělé inteligence
+tak, aby **OmniRoute** fungoval jako jednotný backend, což vám umožní centralizovanou správu klíčů,
+sledování nákladů, přepínání modelů a protokolování požadavků napříč všemi nástroji.
+
+---
+
+## Jak to funguje
+
+```
+Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot
+            │
+            ▼  (všechny ukazují na OmniRoute)
+    http://VASE_SERVER:20128/v1
+            │
+            ▼  (OmniRoute směruje ke správnému poskytovateli)
+     Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...
+```
+
+**Výhody:**
+
+- Jeden API klíč pro správu všech nástrojů
+- Sledování nákladů napříč všemi CLI v dashboardu
+- Přepínání modelů bez nutnosti překonfigurování každého nástroje
+- Funguje lokálně i na vzdálených serverech (VPS)
+
+---
+
+## Podporované nástroje (Zdroj pravdy v dashboardu)
+
+Karty dashboardu v `/dashboard/cli-tools` jsou generovány z `src/shared/constants/cliTools.ts`.
+Aktuální seznam (v3.0.0-rc.16):
+
+| Nástroj            | ID            | Příkaz       | Režim nastavení | Metoda instalace |
+| ------------------ | ------------- | ------------ | --------------- | ---------------- |
+| **Claude Code**    | `claude`      | `claude`     | env             | npm              |
+| **OpenAI Codex**   | `codex`       | `codex`      | custom          | npm              |
+| **Factory Droid**  | `droid`       | `droid`      | custom          | bundled/CLI      |
+| **OpenClaw**       | `openclaw`    | `openclaw`   | custom          | bundled/CLI      |
+| **Cursor**         | `cursor`      | aplikace     | guide           | desktop app      |
+| **Cline**          | `cline`       | `cline`      | custom          | npm              |
+| **Kilo Code**      | `kilo`        | `kilocode`   | custom          | npm              |
+| **Continue**       | `continue`    | rozšíření    | guide           | VS Code          |
+| **Antigravity**    | `antigravity` | interní      | mitm            | OmniRoute        |
+| **GitHub Copilot** | `copilot`     | rozšíření    | custom          | VS Code          |
+| **OpenCode**       | `opencode`    | `opencode`   | guide           | npm              |
+| **Kiro AI**        | `kiro`        | aplikace/CLI | mitm            | desktop/CLI      |
+
+### Synchronizace otisků CLI (Agenti + Nastavení)
+
+`/dashboard/agents` a `Nastavení > CLI Otisk` používají `src/shared/constants/cliCompatProviders.ts`.
+To udržuje ID poskytovatelů v souladu s kartami CLI a staršími ID.
+
+| CLI ID                                                                                               | ID poskytovatele otisku |
+| ---------------------------------------------------------------------------------------------------- | ----------------------- |
+| `kilo`                                                                                               | `kilocode`              |
+| `copilot`                                                                                            | `github`                |
+| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | stejné ID               |
+
+Starší ID jsou stále přijímána pro kompatibilitu: `copilot`, `kimi-coding`, `qwen`.
+
+---
+
+## Krok 1 — Získejte OmniRoute API klíč
+
+1. Otevřete OmniRoute dashboard → **Správce API** (`/dashboard/api-manager`)
+2. Klikněte na **Vytvořit API klíč**
+3. Dejte mu název (např. `cli-tools`) a vyberte všechna oprávnění
+4. Zkopírujte klíč — budete ho potřebovat pro každý CLI níže
+
+> Váš klíč vypadá takto: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`
+
+---
+
+## Krok 2 — Nainstalujte nástroje CLI
+
+Všechny nástroje založené na npm vyžadují Node.js 18+:
+
+```bash
+# Claude Code (Anthropic)
+npm install -g @anthropic-ai/claude-code
+
+# OpenAI Codex
+npm install -g @openai/codex
+
+# OpenCode
+npm install -g opencode-ai
+
+# Cline
+npm install -g cline
+
+# KiloCode
+npm install -g kilocode
+
+# Kiro CLI (Amazon — vyžaduje curl + unzip)
+apt-get install -y unzip   # na Debian/Ubuntu
+curl -fsSL https://cli.kiro.dev/install | bash
+export PATH="$HOME/.local/bin:$PATH"   # přidat do ~/.bashrc
+```
+
+**Ověření:**
+
+```bash
+claude --version     # 2.x.x
+codex --version      # 0.x.x
+opencode --version   # x.x.x
+cline --version      # 2.x.x
+kilocode --version   # x.x.x (nebo: kilo --version)
+kiro-cli --version   # 1.x.x
+```
+
+---
+
+## Krok 3 — Nastavte globální proměnné prostředí
+
+Přidejte do `~/.bashrc` (nebo `~/.zshrc`), pak spusťte `source ~/.bashrc`:
+
+```bash
+# OmniRoute Univerzální koncový bod
+export OPENAI_BASE_URL="http://localhost:20128/v1"
+export OPENAI_API_KEY="sk-vase-omniroute-klic"
+export ANTHROPIC_BASE_URL="http://localhost:20128/v1"
+export ANTHROPIC_API_KEY="sk-vase-omniroute-klic"
+export GEMINI_BASE_URL="http://localhost:20128/v1"
+export GEMINI_API_KEY="sk-vase-omniroute-klic"
+```
+
+> Pro **vzdálený server** nahraďte `localhost:20128` IP adresou nebo doménou serveru,
+> např. `http://192.168.0.15:20128`.
+
+---
+
+## Krok 4 — Nakonfigurujte každý nástroj
+
+### Claude Code
+
+```bash
+# Via CLI:
+claude config set --global api-base-url http://localhost:20128/v1
+
+# Nebo vytvořte ~/.claude/settings.json:
+mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF
+{
+  "apiBaseUrl": "http://localhost:20128/v1",
+  "apiKey": "sk-vase-omniroute-klic"
+}
+EOF
+```
+
+**Test:** `claude "say hello"`
+
+---
+
+### OpenAI Codex
+
+```bash
+mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF
+model: auto
+apiKey: sk-vase-omniroute-klic
+apiBaseUrl: http://localhost:20128/v1
+EOF
+```
+
+**Test:** `codex "what is 2+2?"`
+
+---
+
+### OpenCode
+
+```bash
+mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF
+[provider.openai]
+base_url = "http://localhost:20128/v1"
+api_key = "sk-vase-omniroute-klic"
+EOF
+```
+
+**Test:** `opencode`
+
+---
+
+### Cline (CLI nebo VS Code)
+
+**Režim CLI:**
+
+```bash
+mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF
+{
+  "apiProvider": "openai",
+  "openAiBaseUrl": "http://localhost:20128/v1",
+  "openAiApiKey": "sk-vase-omniroute-klic"
+}
+EOF
+```
+
+**Režim VS Code:**
+Nastavení rozšíření Cline → API Provider: `OpenAI Compatible` → Base URL: `http://localhost:20128/v1`
+
+Nebo použijte OmniRoute dashboard → **CLI Nástroje → Cline → Použít konfiguraci**.
+
+---
+
+### KiloCode (CLI nebo VS Code)
+
+**Režim CLI:**
+
+```bash
+kilocode --api-base http://localhost:20128/v1 --api-key sk-vase-omniroute-klic
+```
+
+**Nastavení VS Code:**
+
+```json
+{
+  "kilo-code.openAiBaseUrl": "http://localhost:20128/v1",
+  "kilo-code.apiKey": "sk-vase-omniroute-klic"
+}
+```
+
+Nebo použijte OmniRoute dashboard → **CLI Nástroje → KiloCode → Použít konfiguraci**.
+
+---
+
+### Continue (Rozšíření VS Code)
+
+Upravte `~/.continue/config.yaml`:
+
+```yaml
+models:
+  - name: OmniRoute
+    provider: openai
+    model: auto
+    apiBase: http://localhost:20128/v1
+    apiKey: sk-vase-omniroute-klic
+    default: true
+```
+
+Po úpravě restartujte VS Code.
+
+---
+
+### Kiro CLI (Amazon)
+
+```bash
+# Přihlaste se ke svému AWS/Kiro účtu:
+kiro-cli login
+
+# CLI používá vlastní autentifikaci — OmniRoute není potřeba jako backend pro samotný Kiro CLI.
+# Používejte kiro-cli společně s OmniRoute pro ostatní nástroje.
+kiro-cli status
+```
+
+---
+
+### Cursor (Desktop aplikace)
+
+> **Poznámka:** Cursor směruje požadavky přes svůj cloud. Pro integraci s OmniRoute,
+> povolte **Cloud Endpoint** v nastavení OmniRoute a použijte vaši veřejnou doménu.
+
+Via GUI: **Settings → Models → OpenAI API Key**
+
+- Base URL: `https://vase-domena.com/v1`
+- API Key: váš OmniRoute klíč
+
+---
+
+## Automatická konfigurace v dashboardu
+
+OmniRoute dashboard automatizuje konfiguraci většiny nástrojů:
+
+1. Jděte na `http://localhost:20128/dashboard/cli-tools`
+2. Rozbalte libovolnou kartu nástroje
+3. Vyberte svůj API klíč z rozbalovacího seznamu
+4. Klikněte na **Použít konfiguraci** (pokud je nástroj detekován jako nainstalovaný)
+5. Nebo ručně zkopírujte vygenerovaný konfigurační snippet
+
+---
+
+## Vestavěný agenti: Droid & OpenClaw
+
+**Droid** a **OpenClaw** jsou AI agenti vestavění přímo do OmniRoute — není potřeba žádná instalace.
+Běží jako interní trasy a automaticky používají směrování modelů OmniRoute.
+
+- Přístup: `http://localhost:20128/dashboard/agents`
+- Konfigurace: stejné kombinace a poskytovatelé jako všechny ostatní nástroje
+- Není potřeba API klíč ani instalace CLI
+
+---
+
+## Dostupné API koncové body
+
+| Koncový bod                | Popis                                   | Použití pro                           |
+| -------------------------- | --------------------------------------- | ------------------------------------- |
+| `/v1/chat/completions`     | Standardní chat (všichni poskytovatelé) | Všechny moderní nástroje              |
+| `/v1/responses`            | Responses API (formát OpenAI)           | Codex, agentní workflowy              |
+| `/v1/completions`          | Legacy textové dokončení                | Starší nástroje používající `prompt:` |
+| `/v1/embeddings`           | Textové vložení                         | RAG, vyhledávání                      |
+| `/v1/images/generations`   | Generování obrázků                      | DALL-E, Flux, atd.                    |
+| `/v1/audio/speech`         | Text-to-speech                          | ElevenLabs, OpenAI TTS                |
+| `/v1/audio/transcriptions` | Speech-to-text                          | Deepgram, AssemblyAI                  |
+
+---
+
+## Řešení problémů
+
+| Chyba                         | Příčina                 | Oprava                                                   |
+| ----------------------------- | ----------------------- | -------------------------------------------------------- |
+| `Connection refused`          | OmniRoute neběží        | `pm2 start omniroute`                                    |
+| `401 Unauthorized`            | Špatný API klíč         | Zkontrolujte v `/dashboard/api-manager`                  |
+| `No combo configured`         | Žádná aktivní kombinace | Nastavte v `/dashboard/combos`                           |
+| `invalid model`               | Model není v katalogu   | Použijte `auto` nebo zkontrolujte `/dashboard/providers` |
+| CLI zobrazuje "not installed" | Binárka není v PATH     | Zkontrolujte `which <příkaz>`                            |
+| `kiro-cli: not found`         | Není v PATH             | `export PATH="$HOME/.local/bin:$PATH"`                   |
+
+---
+
+## Rychlý skript pro nastavení (jeden příkaz)
+
+```bash
+# Nainstalujte všechny CLI a nakonfigurujte pro OmniRoute (nahraďte svým klíčem a URL serveru)
+OMNIROUTE_URL="http://localhost:20128/v1"
+OMNIROUTE_KEY="sk-vase-omniroute-klic"
+
+npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode
+
+# Kiro CLI
+apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash
+
+# Zápis konfigurací
+mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue
+
+cat > ~/.claude/settings.json   <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}"
+cat > ~/.codex/config.yaml      <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL"
+cat >> ~/.bashrc << EOF
+export OPENAI_BASE_URL="$OMNIROUTE_URL"
+export OPENAI_API_KEY="$OMNIROUTE_KEY"
+export ANTHROPIC_BASE_URL="$OMNIROUTE_URL"
+export ANTHROPIC_API_KEY="$OMNIROUTE_KEY"
+EOF
+
+source ~/.bashrc
+echo "✅ Všechny CLI nainstalovány a nakonfigurovány pro OmniRoute"
+```

docs/i18n/cs/CODEBASE_DOCUMENTATION.md

@@ -0,0 +1,589 @@
+# omniroute — Dokumentace kódové základny
+
+🌐 **Jazyky:** 🇺🇸 [angličtina](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [maďarština](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonésie](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nizozemsko](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](i18n/phi/CODEBASE_DOCUMENTATION.md) | 🇨🇿 [Čeština](i18n/cs/CODEBASE_DOCUMENTATION.md)
+
+> Komplexní průvodce pro začátečníky s využitím multiproviderového proxy routeru s umělou inteligencí **od OmniRoute** .
+
+---
+
+## 1. Co je to omniroute?
+
+Omniroute je **proxy router** , který se nachází mezi klienty umělé inteligence (Claude CLI, Codex, Cursor IDE atd.) a poskytovateli umělé inteligence (Anthropic, Google, OpenAI, AWS, GitHub atd.). Řeší jeden velký problém:
+
+> **Různí klienti AI hovoří různými „jazyky“ (formáty API) a různí poskytovatelé AI také očekávají různé „jazyky“.** Omniroute mezi nimi automaticky překládá.
+
+Představte si to jako univerzálního překladatele v Organizaci spojených národů – kterýkoli delegát může mluvit jakýmkoli jazykem a překladatel ho pro kteréhokoli jiného delegáta převede.
+
+---
+
+## 2. Přehled architektury
+
+```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
+```
+
+### Základní princip: Překlad typu „hub-and-spoke“
+
+Veškerý překlad formátů prochází **formátem OpenAI jako centrem** :
+
+```
+Client Format → [OpenAI Hub] → Provider Format    (request)
+Provider Format → [OpenAI Hub] → Client Format    (response)
+```
+
+To znamená, že potřebujete pouze **N překladačů** (jeden na formát) místo **N²** (každý pár).
+
+---
+
+## 3. Struktura projektu
+
+```
+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. Rozdělení podle modulů
+
+### 4.1 Konfigurace ( `open-sse/config/` )
+
+Jediný **zdroj pravdivých informací** pro všechny konfigurace poskytovatelů.
+
+| Soubor                        | Účel                                                                                                                                                                                                                                                         |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `constants.ts`                | Objekt `PROVIDERS` se základními URL adresami, přihlašovacími údaji OAuth (výchozí), záhlavími a výchozími systémovými výzvami pro každého poskytovatele. Definuje také `HTTP_STATUS` , `ERROR_TYPES` , `COOLDOWN_MS` , `BACKOFF_CONFIG` a `SKIP_PATTERNS` . |
+| `credentialLoader.ts`         | Načte externí přihlašovací údaje z `data/provider-credentials.json` a sloučí je s pevně zakódovanými výchozími hodnotami v `PROVIDERS` . Uchovává tajné údaje mimo kontrolu zdrojového kódu a zároveň zachovává zpětnou kompatibilitu.                       |
+| `providerModels.ts`           | Centrální registr modelů: mapuje aliasy poskytovatelů → ID modelů. Funkce jako `getModels()` , `getProviderByAlias()` .                                                                                                                                      |
+| `codexInstructions.ts`        | Systémové instrukce vložené do požadavků Codexu (omezení úprav, pravidla sandboxu, zásady schvalování).                                                                                                                                                      |
+| `defaultThinkingSignature.ts` | Výchozí „myšlenkové“ podpisy pro modely Claude a Gemini.                                                                                                                                                                                                     |
+| `ollamaModels.ts`             | Definice schématu pro lokální Ollama modely (název, velikost, rodina, kvantizace).                                                                                                                                                                           |
+
+#### Postup načítání přihlašovacích údajů
+
+```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 Vykonavatelé ( `open-sse/executors/` )
+
+Prováděcí metody zapouzdřují **logiku specifickou pro poskytovatele** pomocí **vzoru strategie** . Každý prováděcí metody podle potřeby přepisují základní metody.
+
+```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
+```
+
+| Vykonavatel      | Poskytovatel                               | Klíčové specializace                                                                                                                 |
+| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `base.ts`        | —                                          | Abstraktní základ: tvorba URL adres, hlavičky, logika opakování, aktualizace přihlašovacích údajů                                    |
+| `default.ts`     | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Aktualizace generického tokenu OAuth pro standardní poskytovatele                                                                    |
+| `antigravity.ts` | Kód Google Cloud                           | Generování ID projektu/relace, záložní více URL adres, vlastní analýza opakovaných pokusů z chybových zpráv („reset po 2h7m23s“)     |
+| `cursor.ts`      | IDE kurzoru                                | **Nejsložitější** : autorizace kontrolního součtu SHA-256, kódování požadavků Protobuf, analýza binárních EventStream → SSE odpovědí |
+| `codex.ts`       | OpenAI Codex                               | Vkládá systémové instrukce, spravuje úrovně myšlení, odstraňuje nepodporované parametry                                              |
+| `gemini-cli.ts`  | Google Gemini CLI                          | Vytvoření vlastní URL adresy ( `streamGenerateContent` ), aktualizace tokenu Google OAuth                                            |
+| `github.ts`      | GitHub Copilot                             | Systém duálních tokenů (GitHub OAuth + Copilot token), napodobování hlaviček VSCode                                                  |
+| `kiro.ts`        | AWS CodeWhisperer                          | Binární parsování AWS EventStream, rámce událostí AMZN, odhad tokenů                                                                 |
+| `index.ts`       | —                                          | Továrna: název poskytovatele map → třída exekutoru s výchozím záložním nastavením                                                    |
+
+---
+
+### 4.3 Obslužné rutiny ( `open-sse/handlers/` )
+
+**Orchestrační vrstva** – koordinuje překlad, provádění, streamování a zpracování chyb.
+
+| Soubor                | Účel                                                                                                                                                                                                                                   |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chatCore.ts`         | **Centrální orchestrátor** (~600 řádků). Zvládá kompletní životní cyklus požadavku: detekce formátu → překlad → odeslání exekutoru → streamovaná/nestreamovaná odpověď → aktualizace tokenu → zpracování chyb → protokolování využití. |
+| `responsesHandler.ts` | Adaptér pro OpenAI Responses API: převádí formát odpovědí → Dokončení chatu → odesílá do `chatCore` → převádí SSE zpět do formátu odpovědí.                                                                                            |
+| `embeddings.ts`       | Obslužná rutina generování embeddingu: řeší model embeddingu → poskytovatele, odesílá do API poskytovatele, vrací odpověď na embedding kompatibilní s OpenAI. Podporuje 6+ poskytovatelů.                                              |
+| `imageGeneration.ts`  | Obslužná rutina generování obrázků: řeší model obrázku → poskytovatele, podporuje režimy kompatibilní s OpenAI, Gemini-image (Antigravity) a fallback (Nebius). Vrací obrázky v base64 nebo URL.                                       |
+
+#### Životní cyklus požadavku (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 Služby ( `open-sse/services/` )
+
+Obchodní logika, která podporuje obslužné rutiny a vykonavatele.
+
+| Soubor               | Účel                                                                                                                                                                                                                                                                                                                                                             |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider.ts`        | **Detekce formátu** ( `detectFormat` ): analyzuje strukturu těla požadavku a identifikuje formáty Claude/OpenAI/Gemini/Antigravity/Responses (včetně heuristiky `max_tokens` pro Claude). Dále: tvorba URL, tvorba hlaviček, normalizace konfigurace thinking. Podporuje dynamické poskytovatele kompatibilní `openai-compatible-*` a `anthropic-compatible-*` . |
+| `model.ts`           | Analýza řetězců modelu ( `claude/model-name` → `{provider: "claude", model: "model-name"}` ), rozlišení aliasů s detekcí kolizí, sanitizace vstupu (odmítá průchod cestou/řídicí znaky) a rozlišení informací o modelu s podporou asynchronních metod pro získávání aliasů.                                                                                      |
+| `accountFallback.ts` | Ovládání limitů rychlosti: exponenciální upomínka (1 s → 2 s → 4 s → max. 2 min), správa doby zpoždění účtu, klasifikace chyb (které chyby spouštějí fallback a které ne).                                                                                                                                                                                       |
+| `tokenRefresh.ts`    | Aktualizace tokenu OAuth pro **všechny poskytovatele** : Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (duální token OAuth + Copilot), Kiro (AWS SSO OIDC + sociální ověřování). Zahrnuje mezipaměť deduplikace promise za provozu a opakování s exponenciálním zpožděním.                                                                    |
+| `combo.ts`           | **Kombinované modely** : řetězce záložních modelů. Pokud model A selže s chybou způsobilou pro záložní model, zkuste model B, poté C atd. Vrací skutečné stavové kódy upstreamu.                                                                                                                                                                                 |
+| `usage.ts`           | Načítá data o kvótách/využití z API poskytovatelů (kvóty GitHub Copilot, kvóty modelu Antigravity, limity rychlosti Codexu, rozpisy využití Kiro, nastavení Claude).                                                                                                                                                                                             |
+| `accountSelector.ts` | Inteligentní výběr účtu s algoritmem bodování: pro výběr optimálního účtu pro každý požadavek se zohledňuje priorita, zdravotní stav, pozice v systému round robin a stav ochlazování.                                                                                                                                                                           |
+| `contextManager.ts`  | Správa životního cyklu kontextu požadavku: vytváří a sleduje objekty kontextu pro každý požadavek s metadaty (ID požadavku, časová razítka, informace o poskytovateli) pro ladění a protokolování.                                                                                                                                                               |
+| `ipFilter.ts`        | Řízení přístupu založené na IP adrese: podporuje režimy povolených seznamů a blokovaných seznamů. Před zpracováním požadavků API ověřuje IP adresu klienta podle nakonfigurovaných pravidel.                                                                                                                                                                     |
+| `sessionManager.ts`  | Sledování relací s otisky prstů klientů: sleduje aktivní relace pomocí hašovaných identifikátorů klientů, monitoruje počty požadavků a poskytuje metriky relací.                                                                                                                                                                                                 |
+| `signatureCache.ts`  | Mezipaměť deduplikace na základě signatur požadavků: zabraňuje duplicitním požadavkům ukládáním nedávných signatur požadavků do mezipaměti a vrácením odpovědí z mezipaměti pro identické požadavky v rámci časového okna.                                                                                                                                       |
+| `systemPrompt.ts`    | Globální vložení systémového výzvy: přidá konfigurovatelnou systémovou výzvu ke všem požadavkům s možností kompatibility pro jednotlivé poskytovatele.                                                                                                                                                                                                           |
+| `thinkingBudget.ts`  | Správa rozpočtu tokenů uvažování: podporuje režimy průchodu, automatický (konfigurace strip thinking), vlastní (pevný rozpočet) a adaptivní (měřítko složitosti) pro řízení tokenů myšlení/uvažování.                                                                                                                                                            |
+| `wildcardRouter.ts`  | Směrování podle vzorů zástupných znaků: rozpoznává vzory zástupných znaků (např. `*/claude-*` ) na konkrétní páry poskytovatel/model na základě dostupnosti a priority.                                                                                                                                                                                          |
+
+#### Deduplikace obnovení tokenů
+
+```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
+```
+
+#### Záložní stavový automat účtu
+
+```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
+    }
+```
+
+#### Řetězec kombinovaných modelů
+
+```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 Překladač ( `open-sse/translator/` )
+
+**Modul pro překlad formátů** využívající systém samoregistrujících se pluginů.
+
+#### Architektura
+
+```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
+```
+
+| Adresář      | Soubory        | Popis                                                                                                                                                                                                                                                                     |
+| ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request/`   | 8 překladatelů | Převod těl požadavků mezi formáty. Každý soubor se při importu sám zaregistruje pomocí `register(from, to, fn)` .                                                                                                                                                         |
+| `response/`  | 7 překladatelů | Převádí bloky odpovědí streamovaných dat mezi formáty. Zpracovává typy událostí SSE, myšlenkové bloky a volání nástrojů.                                                                                                                                                  |
+| `helpers/`   | 6 pomocníků    | Sdílené utility: `claudeHelper` (extrakce systémových prompts, thinking config), `geminiHelper` (mapování částí/obsahu), `openaiHelper` (filtrování formátů), `toolCallHelper` (generování ID, vkládání chybějících odpovědí), `maxTokensHelper` , `responsesApiHelper` . |
+| `index.ts`   | —              | Překladový engine: `translateRequest()` , `translateResponse()` , správa stavu, registr.                                                                                                                                                                                  |
+| `formats.ts` | —              | Formátovací konstanty: `OPENAI` , `CLAUDE` , `GEMINI` , `ANTIGRAVITY` , `KIRO` , `CURSOR` , `OPENAI_RESPONSES` .                                                                                                                                                          |
+
+#### Klíčový design: Samoregistrující se pluginy
+
+```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 Nástroje ( `open-sse/utils/` )
+
+| Soubor             | Účel                                                                                                                                                                                                                                                                                                                    |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `error.ts`         | Vytváření chybové odezvy (formát kompatibilní s OpenAI), parsování chyb v upstreamu, extrakce doby opakování Antigravity z chybových zpráv, streamování chyb SSE.                                                                                                                                                       |
+| `stream.ts`        | **SSE Transform Stream** — základní streamovací kanál. Dva režimy: `TRANSLATE` (plný překlad formátu) a `PASSTHROUGH` (normalizace + extrakce využití). Zpracovává ukládání bloků do vyrovnávací paměti, odhad využití a sledování délky obsahu. Instance kodéru/dekodéru pro každý stream se vyhýbají sdílenému stavu. |
+| `streamHelpers.ts` | Nízkoúrovňové utility SSE: `parseSSELine` (tolerantní k bílým znakům), `hasValuableContent` (filtruje prázdné segmenty pro OpenAI/Claude/Gemini), `fixInvalidId` , `formatSSE` (serializace SSE s ohledem na formát s čištěním `perf_metrics` ).                                                                        |
+| `usageTracking.ts` | Extrakce využití tokenů z libovolného formátu (Claude/OpenAI/Gemini/Responses), odhad s oddělenými poměry znaků na token pro jednotlivé nástroje/zprávy, přidání vyrovnávací paměti (bezpečnostní rezerva 2000 tokenů), filtrování polí specifických pro formát, protokolování konzole s barvami ANSI.                  |
+| `requestLogger.ts` | Protokolování požadavků na základě souborů (přihlášení pomocí `ENABLE_REQUEST_LOGS=true` ). Vytváří složky relací s očíslovanými soubory: `1_req_client.json` → `7_res_client.txt` . Veškeré I/O operace jsou asynchronní (aktivní a zapomenutý). Maskuje citlivé hlavičky.                                             |
+| `bypassHandler.ts` | Zachycuje specifické vzory z Claude CLI (extrakce názvu, zahřívání, počet) a vrací falešné odpovědi bez volání jakéhokoli poskytovatele. Podporuje streamování i nestreamování. Záměrně omezeno na rozsah Claude CLI.                                                                                                   |
+| `networkProxy.ts`  | Rozpozná URL odchozí proxy pro daného poskytovatele s prioritou: konfigurace specifická pro poskytovatele → globální konfigurace → proměnné prostředí ( `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` ). Podporuje výjimky `NO_PROXY` . Ukládá konfiguraci do mezipaměti po dobu 30 sekund.                                |
+
+#### Streamovací kanál 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
+```
+
+#### Struktura relace protokolování požadavků
+
+```
+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 Aplikační vrstva ( `src/` )
+
+| Adresář       | Účel                                                                                              |
+| ------------- | ------------------------------------------------------------------------------------------------- |
+| `src/app/`    | Webové uživatelské rozhraní, trasy API, middleware Express, obslužné rutiny zpětných volání OAuth |
+| `src/lib/`    | Přístup k databázi ( `localDb.ts` , `usageDb.ts` ), ověřování, sdílení                            |
+| `src/mitm/`   | Nástroje proxy typu „man-in-the-middle“ pro zachycení provozu poskytovatelů                       |
+| `src/models/` | Definice modelů databáze                                                                          |
+| `src/shared/` | Obálky kolem funkcí open-sse (provider, stream, error atd.)                                       |
+| `src/sse/`    | Obslužné rutiny koncových bodů SSE, které propojují knihovnu open-sse s trasami Express           |
+| `src/store/`  | Správa stavu aplikací                                                                             |
+
+#### Významné trasy API
+
+| Trasa                                         | Metody          | Účel                                                                                             |
+| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------ |
+| `/api/provider-models`                        | GET/POST/DELETE | CRUD pro vlastní modely na poskytovatele                                                         |
+| `/api/models/catalog`                         | GET             | Agregovaný katalog všech modelů (chat, embedding, image, custom) seskupených podle poskytovatele |
+| `/api/settings/proxy`                         | GET/PUT/DELETE  | Konfigurace hierarchické odchozí proxy ( `global/providers/combos/keys` )                        |
+| `/api/settings/proxy/test`                    | POST            | Ověřuje připojení proxy a vrací veřejnou IP adresu/latenci                                       |
+| `/v1/providers/[provider]/chat/completions`   | POST            | Vyhrazené dokončování chatu pro jednotlivé poskytovatele s ověřováním modelu                     |
+| `/v1/providers/[provider]/embeddings`         | POST            | Vyhrazené vkládání pro jednotlivé poskytovatele s ověřováním modelu                              |
+| `/v1/providers/[provider]/images/generations` | POST            | Vyhrazené generování obrázků pro každého poskytovatele s ověřováním modelu                       |
+| `/api/settings/ip-filter`                     | GET/PUT         | Správa povolených/blokovaných IP adres                                                           |
+| `/api/settings/thinking-budget`               | GET/PUT         | Konfigurace rozpočtu tokenů zdůvodnění (průchozí/automatická/vlastní/adaptivní)                  |
+| `/api/settings/system-prompt`                 | GET/PUT         | Globální vložení systémového promptu pro všechny požadavky                                       |
+| `/api/sessions`                               | GET             | Sledování a metriky aktivních relací                                                             |
+| `/api/rate-limits`                            | GET             | Stav limitu sazby na účet                                                                        |
+
+---
+
+## 5. Klíčové návrhové vzory
+
+### 5.1 Překlad typu Hub-and-Spoke
+
+Všechny formáty se překládají prostřednictvím **formátu OpenAI jako ústředny** . Přidání nového poskytovatele vyžaduje napsání pouze **jednoho páru** překladačů (do/z OpenAI), nikoli N párů.
+
+### 5.2 Vzor strategie exekutora
+
+Každý poskytovatel má vyhrazenou třídu exekutoru, která dědí z `BaseExecutor` . Továrna v `executors/index.ts` vybere ten správný za běhu.
+
+### 5.3 Systém samoregistračních pluginů
+
+Moduly překladače se při importu registrují pomocí `register()` . Přidání nového překladače znamená pouze vytvoření souboru a jeho import.
+
+### 5.4 Záložní účet s exponenciálním oddlužením
+
+Když poskytovatel vrátí 429/401/500, systém může přepnout na další účet s exponenciálním zpožděním (1s → 2s → 4s → max. 2min).
+
+### 5.5 Kombinované modelové řetězy
+
+„Kombinace“ seskupuje více řetězců `provider/model` . Pokud první selže, automaticky se vrátí k dalšímu.
+
+### 5.6 Stavový streamovací překlad
+
+Překlad odpovědí udržuje stav napříč bloky SSE (sledování myšlenkových bloků, akumulace volání nástrojů, indexování bloků obsahu) prostřednictvím mechanismu `initState()` .
+
+### 5.7 Bezpečnostní vyrovnávací paměť pro použití
+
+K hlášenému využití je přidána vyrovnávací paměť o kapacitě 2000 tokenů, aby se zabránilo tomu, že klienti dosáhnou limitů kontextového okna v důsledku režijních nákladů systémových výzev a překladu formátu.
+
+---
+
+## 6. Podporované formáty
+
+| Formát                  | Směr        | Identifikátor      |
+| ----------------------- | ----------- | ------------------ |
+| OpenAI Chat Completions | zdroj + cíl | `openai`           |
+| OpenAI Responses API    | zdroj + cíl | `openai-responses` |
+| Anthropic Claude        | zdroj + cíl | `claude`           |
+| Google Gemini           | zdroj + cíl | `gemini`           |
+| Google Gemini CLI       | jen cíl     | `gemini-cli`       |
+| Antigravity             | zdroj + cíl | `antigravity`      |
+| AWS Kiro                | jen cíl     | `kiro`             |
+| Cursor                  | jen cíl     | `cursor`           |
+
+---
+
+## 7. Podporovaní poskytovatelé
+
+| Poskytovatel             | Metoda ověřování         | Vykonavatel | Klíčové poznámky                             |
+| ------------------------ | ------------------------ | ----------- | -------------------------------------------- |
+| Anthropic Claude         | API klíč nebo OAuth      | Výchozí     | Používá hlavičku `x-api-key`                 |
+| Google Gemini            | API klíč nebo OAuth      | Výchozí     | Používá hlavičku `x-goog-api-key`            |
+| Google Gemini CLI        | OAuth                    | GeminiCLI   | Používá koncový bod `streamGenerateContent`  |
+| Antigravity              | OAuth                    | Antigravity | Záložní více URL, analýza opakovaných pokusů |
+| OpenAI                   | API klíč                 | Výchozí     | Autorizace standardního nosiče               |
+| Codex                    | OAuth                    | Codex       | Vkládá systémové instrukce, řídí myšlení     |
+| GitHub Copilot           | OAuth + Copilot token    | Github      | Duální token, napodobování záhlaví VSCode    |
+| Kiro (AWS)               | AWS SSO OIDC nebo Social | Kiro        | Analýza binárního EventStreamu               |
+| Cursor IDE               | Checksum auth            | Cursor      | Kódování Protobuf, kontrolní součty SHA-256  |
+| Qwen                     | OAuth                    | Výchozí     | Standardní ověřování                         |
+| iFlow                    | OAuth (Basic + Bearer)   | Výchozí     | Duální hlavička pro autorizaci               |
+| OpenRouter               | API klíč                 | Výchozí     | Autorizace standardního nosiče               |
+| GLM, Kimi, MiniMax       | API klíč                 | Výchozí     | Kompatibilní s Claude, použijte `x-api-key`  |
+| `openai-compatible-*`    | API klíč                 | Výchozí     | Dynamické: jakýkoli OpenAI kompatibilní      |
+| `anthropic-compatible-*` | API klíč                 | Výchozí     | Dynamické: jakýkoli Claude kompatibilní      |
+
+---
+
+## 8. Souhrn datového toku
+
+### Žádost o streamování
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor\nbuildUrl + buildHeaders"]
+    D --> E["fetch(providerURL)"]
+    E --> F["createSSEStream()\nTRANSLATE mode"]
+    F --> G["parseSSELine()"]
+    G --> H["translateResponse()\ntarget → OpenAI → source"]
+    H --> I["extractUsage()\n+ addBuffer"]
+    I --> J["formatSSE()"]
+    J --> K["Client receives\ntranslated SSE"]
+    K --> L["logUsage()\nsaveRequestUsage()"]
+```
+
+### Žádost o nestreamování
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor.execute()"]
+    D --> E["translateResponse()\ntarget → OpenAI → source"]
+    E --> F["Return JSON\nresponse"]
+```
+
+### Obtokový tok (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/cs/CONTRIBUTING.md

@@ -0,0 +1,273 @@
+# Přispívání k OmniRoute
+
+Děkujeme za váš zájem o přispění! Tato příručka obsahuje vše, co potřebujete k zahájení.
+
+---
+
+## Nastavení vývoje
+
+### Předpoklady
+
+- **Node.js** 20+ (doporučeno: 22 LTS)
+- **npm** 10+
+- **Git**
+
+### Klonovat a instalovat
+
+```bash
+git clone https://github.com/diegosouzapw/OmniRoute.git
+cd OmniRoute
+npm install
+```
+
+### Proměnné prostředí
+
+```bash
+# Create your .env from the template
+cp .env.example .env
+
+# Generate required secrets
+echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env
+echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env
+```
+
+Klíčové proměnné pro vývoj:
+
+Proměnná | Výchozí nastavení pro vývoj | Popis
+--- | --- | ---
+`PORT` | `3000` | Port serveru
+`NEXT_PUBLIC_BASE_URL` | `http://localhost:3000` | Základní URL pro frontend
+`JWT_SECRET` | (vygenerovat výše) | Tajemství podpisu JWT
+`INITIAL_PASSWORD` | `123456` | První přihlašovací heslo
+`ENABLE_REQUEST_LOGS` | `false` | Povolit protokoly požadavků na ladění
+
+### Spuštěno lokálně
+
+```bash
+# Development mode (hot reload)
+npm run dev
+
+# Production build
+npm run build
+npm run start
+
+# Common port configuration
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+```
+
+Výchozí adresy URL:
+
+- **Dashboard** : `http://localhost:3000/dashboard`
+- **API** : `http://localhost:3000/v1`
+
+---
+
+## Pracovní postup Gitu
+
+> ⚠️ **NIKDY se necommitujte přímo do `main` .** Vždy používejte větve feature.
+
+```bash
+git checkout -b feat/your-feature-name
+# ... make changes ...
+git commit -m "feat: describe your change"
+git push -u origin feat/your-feature-name
+# Open a Pull Request on GitHub
+```
+
+### Pojmenování poboček
+
+Předpona | Účel
+--- | ---
+`feat/` | Nové funkce
+`fix/` | Opravy chyb
+`refactor/` | Restrukturalizace kódu
+`docs/` | Změny dokumentace
+`test/` | Doplnění/opravy testů
+`chore/` | Nástroje, CI, závislosti
+
+### Zprávy o potvrzení
+
+Postupujte podle [konvenčních commitů](https://www.conventionalcommits.org/) :
+
+```
+feat: add circuit breaker for provider calls
+fix: resolve JWT secret validation edge case
+docs: update SECURITY.md with PII protection
+test: add observability unit tests
+refactor(db): consolidate rate limit tables
+```
+
+Rozsahy: `db` , `sse` , `oauth` , `dashboard` , `api` , `cli` , `docker` , `ci` .
+
+---
+
+## Spouštění testů
+
+```bash
+# All unit tests
+npm test
+npm run test:unit
+
+# Specific test suites
+npm run test:security     # Security tests
+npm run test:fixes        # Fix verification tests
+
+# With coverage
+npm run test:coverage
+
+# E2E tests (requires Playwright)
+npm run test:e2e
+
+# Lint + format check
+npm run lint
+npm run check
+```
+
+Aktuální stav testování: **368+ jednotkových testů** zahrnujících:
+
+- Poskytovatelé překladů a konverze formátů
+- Omezení rychlosti, jistič a odolnost
+- Sémantická mezipaměť, idempotence, sledování průběhu
+- Databázové operace a schéma
+- Toky a ověřování OAuth
+- Ověření koncového bodu API
+
+---
+
+## Styl kódu
+
+- **ESLint** — Spustí `npm run lint` před commitem
+- **Hezčí** – Automaticky naformátováno pomocí `lint-staged` při commitu
+- **TypeScript** — Veškerý kód `src/` používá `.ts` / `.tsx` ; dokument s TSDoc ( `@param` , `@returns` , `@throws` )
+- **No `eval()`** — ESLint vynucuje `no-eval` , `no-implied-eval` , `no-new-func`
+- **Ověření Zod** — Použití schémat Zod pro ověřování vstupu API
+
+---
+
+## Struktura projektu
+
+```
+src/                        # TypeScript (.ts / .tsx)
+├── app/                    # Next.js App Router
+│   ├── (dashboard)/        # Dashboard pages (.tsx)
+│   ├── api/                # API routes (.ts)
+│   └── login/              # Auth pages (.tsx)
+├── domain/                 # Domain types and response helpers (.ts)
+├── lib/                    # Core business logic (.ts)
+│   ├── db/                 # SQLite database layer
+│   ├── oauth/              # OAuth services per provider
+│   ├── cacheLayer.ts       # LRU cache
+│   ├── semanticCache.ts    # Semantic response cache
+│   ├── idempotencyLayer.ts # Request deduplication
+│   └── localDb.ts          # Settings facade (LowDB for config, SQLite for domain data)
+├── shared/
+│   ├── components/         # React components (.tsx)
+│   ├── middleware/          # Correlation IDs, etc.
+│   ├── utils/              # Circuit breaker, sanitizer, etc.
+│   └── validation/         # Zod schemas
+└── sse/                    # SSE chat handlers (.ts)
+
+open-sse/                   # @omniroute/open-sse workspace (JavaScript)
+├── handlers/               # chatCore.js — main request handler
+├── services/               # Rate limit, fallback
+├── translators/            # Format converters (OpenAI ↔ Claude ↔ Gemini)
+└── utils/                  # Progress tracker, stream helpers
+
+tests/
+├── unit/                   # Node.js test runner (.test.mjs)
+└── e2e/                    # Playwright tests
+
+docs/                       # Documentation
+├── USER_GUIDE.md           # Provider setup, CLI integration
+├── API_REFERENCE.md        # All endpoints
+├── TROUBLESHOOTING.md      # Common issues
+├── ARCHITECTURE.md         # System architecture
+└── adr/                    # Architecture Decision Records
+```
+
+---
+
+## Přidání nového poskytovatele
+
+### Krok 1: Služba OAuth (pokud používáte OAuth)
+
+Vytvořte `src/lib/oauth/services/your-provider.ts` rozšiřující `OAuthService` :
+
+```typescript
+import { OAuthService } from "../OAuthService";
+
+export class YourProviderService extends OAuthService {
+  constructor() {
+    super({
+      name: "your-provider",
+      authUrl: "https://provider.com/oauth/authorize",
+      tokenUrl: "https://provider.com/oauth/token",
+      clientId: "...",
+      scopes: ["..."],
+    });
+  }
+}
+```
+
+### Krok 2: Registrace poskytovatele
+
+Přidat do `src/lib/oauth/providers.ts` :
+
+```typescript
+import { YourProviderService } from "./services/your-provider";
+// Add to the providers map
+```
+
+### Krok 3: Přidání konstant
+
+Přidejte konstanty poskytovatele do `src/lib/providerConstants.ts` :
+
+- Předpona poskytovatele (např. `yp/` )
+- Výchozí modely
+- Informace o cenách
+
+### Krok 4: Přidání překladače (pokud se nejedná o formát OpenAI)
+
+Pokud poskytovatel používá vlastní formát API, vytvořte překladač v `open-sse/translators/` .
+
+### Krok 5: Přidání časového limitu
+
+Přidejte konfiguraci časového limitu požadavku do `src/shared/utils/requestTimeout.ts` .
+
+### Krok 6: Přidání testů
+
+Pište jednotkové testy v `tests/unit/` které pokrývají minimálně:
+
+- Registrace poskytovatele
+- Překlad žádostí/odpovědí
+- Ošetření chyb
+
+---
+
+## Kontrolní seznam žádostí o natažení
+
+- [ ] Testy prošly ( `npm test` )
+- [ ] Průchody pro linting ( `npm run lint` )
+- [ ] Sestavení proběhlo úspěšně ( `npm run build` )
+- [ ] Pro nové veřejné funkce a rozhraní přidány typy TypeScript
+- [ ] Žádné pevně zakódované tajné kódy ani záložní hodnoty
+- [ ] Aktualizován CHANGELOG (pokud se změna týká uživatele)
+- [ ] Aktualizovaná dokumentace (pokud je to relevantní)
+
+---
+
+## Uvolnění
+
+Když je vytvořena nová verze GitHubu (např. `v0.4.0` ), balíček je **automaticky publikován do npm** prostřednictvím akcí GitHubu:
+
+```bash
+gh release create v0.4.0 --title "v0.4.0" --generate-notes
+```
+
+---
+
+## Získání pomoci
+
+- **Architektura** : Viz [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
+- **Problémy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **ADR** : Viz `docs/adr/`

docs/i18n/cs/FEATURES.md

@@ -0,0 +1,143 @@
+# OmniRoute — Galerie funkcí řídicího panelu
+
+🌐 **Jazyky:** 🇺🇸 [angličtina](FEATURES.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [maďarština](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonésie](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nizozemsko](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](i18n/phi/FEATURES.md) | 🇨🇿 [Čeština](i18n/cs/FEATURES.md)
+
+Vizuální průvodce všemi částmi ovládacího panelu OmniRoute.
+
+---
+
+## 🔌 Poskytovatelé
+
+Spravujte připojení poskytovatelů AI: poskytovatelé OAuth (Claude Code, Codex, Gemini CLI), poskytovatelé klíčů API (Groq, DeepSeek, OpenRouter) a bezplatní poskytovatelé (iFlow, Qwen, Kiro). Účty Kiro zahrnují sledování zůstatku kreditů – zbývající kredity, celkový limit a datum obnovení jsou viditelné v Dashboard → Usage.
+
+![Dashboard poskytovatelů](screenshots/01-providers.png)
+
+---
+
+## 🎨 Kombinace
+
+Vytvářejte kombinace směrování modelů pomocí 6 strategií: prioritní, vážená, kruhová, náhodná, nejméně používaná a nákladově optimalizovaná. Každá kombinace řetězí více modelů s automatickým přepínáním mezi nimi a zahrnuje rychlé šablony a kontroly připravenosti.
+
+![Dashboard kombinací](screenshots/02-combos.png)
+
+---
+
+## 📊 Analytika
+
+Komplexní analýzy využití se spotřebou tokenů, odhady nákladů, mapami aktivit, týdenními distribučními grafy a rozpisy podle jednotlivých poskytovatelů.
+
+![Analytický řídicí panel](screenshots/03-analytics.png)
+
+---
+
+## 🏥 Stav systému
+
+Monitorování v reálném čase: dostupnost, paměť, verze, percentily latence (p50/p95/p99), statistiky mezipaměti a stavy jističů poskytovatelů.
+
+![Dashboard zdraví](screenshots/04-health.png)
+
+---
+
+## 🔧 Překladatelské hřiště
+
+Čtyři režimy pro ladění překladů API: **Playground** (převodník formátů), **Chat Tester** (živé požadavky), **Test Bench** (dávkové testy) a **Live Monitor** (stream v reálném čase).
+
+![Hřiště překladatelů](screenshots/05-translator.png)
+
+---
+
+## 🎮 Modelové hřiště *(v2.0.9+)*
+
+Otestujte libovolný model přímo z řídicího panelu. Vyberte poskytovatele, model a koncový bod, pište výzvy pomocí editoru Monaco, streamujte odpovědi v reálném čase, přerušte stream a zobrazte metriky časování.
+
+---
+
+## 🎨 Témata *(v2.0.5+)*
+
+Přizpůsobitelná barevná témata pro celý dashboard. Vyberte si ze 7 přednastavených barev (korálová, modrá, červená, zelená, fialová, oranžová, azurová) nebo si vytvořte vlastní téma výběrem libovolné hexadecimální barvy. Podporuje světlý, tmavý a systémový režim.
+
+---
+
+## ⚙️ Nastavení
+
+Komplexní panel nastavení s kartami:
+
+- **Obecné** – Systémové úložiště, správa záloh (export/import databáze)
+- **Vzhled** – Výběr motivu (tmavý/světlý/systémový), přednastavené barevné motivy a vlastní barvy, viditelnost protokolu stavu
+- **Zabezpečení** — ochrana koncových bodů API, blokování vlastních poskytovatelů, filtrování IP adres, informace o relaci
+- **Směrování** — Aliasy modelů, degradace úloh na pozadí
+- **Odolnost** — Perzistence omezení rychlosti, ladění jističe
+- **Pokročilé** – Přepsání konfigurace
+
+![Ovládací panel nastavení](screenshots/06-settings.png)
+
+---
+
+## 🔧 Nástroje CLI
+
+Konfigurace nástrojů pro kódování s umělou inteligencí jedním kliknutím: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor a Factory Droid. Nabízí automatické použití/resetování konfigurace, profily připojení a mapování modelů.
+
+![Řídicí panel nástrojů CLI](screenshots/07-cli-tools.png)
+
+---
+
+## 🤖 Agenti CLI *(v2.0.11+)*
+
+Ovládací panel pro vyhledávání a správu agentů CLI. Zobrazuje mřížku 14 vestavěných agentů (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) s:
+
+- **Stav instalace** — Nainstalováno / Nenalezeno s detekcí verze
+- **Odznaky protokolů** – stdio, HTTP atd.
+- **Vlastní agenti** — Registrace libovolného nástroje CLI pomocí formuláře (název, binární soubor, verze příkazu, argumenty spawn)
+- **Porovnávání otisků prstů v příkazovém řádku** – Přepínání pro jednotlivé poskytovatele pro porovnávání nativních podpisů požadavků v příkazovém řádku, čímž se snižuje riziko zablokování a zároveň se zachovává IP adresa proxy.
+
+---
+
+## 🖼️ Média *(v2.0.3+)*
+
+Generujte obrázky, videa a hudbu z řídicího panelu. Podporuje OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open a MusicGen.
+
+---
+
+## 📝 Vyžádat si protokoly
+
+Protokolování požadavků v reálném čase s filtrováním podle poskytovatele, modelu, účtu a klíče API. Zobrazuje stavové kódy, využití tokenů, latenci a podrobnosti o odpovědi.
+
+![Protokoly používání](screenshots/08-usage.png)
+
+---
+
+## 🌐 Koncový bod API
+
+Váš jednotný koncový bod API s rozpisem funkcí: Dokončování chatu, API odpovědí, vkládání, generování obrázků, změna pořadí, přepis zvuku, převod textu na řeč, moderování a registrované klíče API. Podpora cloudového proxy pro vzdálený přístup.
+
+![Dashboard koncového bodu](screenshots/09-endpoint.png)
+
+---
+
+## 🔑 Správa klíčů API
+
+Vytvářejte, upravujte rozsah a rušte klíče API. Každý klíč lze omezit na konkrétní modely/poskytovatele s plným přístupem nebo oprávněním pouze pro čtení. Vizuální správa klíčů se sledováním využití.
+
+---
+
+## 📋 Záznam auditu
+
+Sledování administrativních akcí s filtrováním podle typu akce, aktéra, cíle, IP adresy a časového razítka. Úplná historie bezpečnostních událostí.
+
+---
+
+## 🖥️ Desktopová aplikace
+
+Desktopová aplikace Native Electron pro Windows, macOS a Linux. Spouštějte OmniRoute jako samostatnou aplikaci s integrací do systémové lišty, podporou offline, automatickými aktualizacemi a instalací jedním kliknutím.
+
+Klíčové vlastnosti:
+
+- Dotazování připravenosti serveru (žádná prázdná obrazovka při studeném startu)
+- Systémový panel se správou portů
+- Zásady zabezpečení obsahu
+- Jednoinstanční zámek
+- Automatická aktualizace při restartu
+- Podmíněné uživatelské rozhraní pro platformu (semafory pro macOS, výchozí záhlaví okna pro Windows/Linux)
+- Zpevněné balení buildů Electron — symbolicky odkazované `node_modules` v samostatném balíčku jsou detekovány a odmítnuty před balením, čímž se zabrání závislosti na buildovacím stroji za běhu (v2.5.5+)
+
+📖 Úplnou dokumentaci naleznete v [`electron/README.md`](../electron/README.md) .

docs/i18n/cs/MCP-SERVER.md

@@ -0,0 +1,83 @@
+# Dokumentace k serveru OmniRoute MCP
+
+> Server protokolu kontextu modelu s 16 inteligentními nástroji
+
+## Instalace
+
+OmniRoute MCP je integrovaný. Spusťte ho pomocí:
+
+```bash
+omniroute --mcp
+```
+
+Nebo prostřednictvím open-sse transportu:
+
+```bash
+# HTTP streamable transport (port 20130)
+omniroute --dev  # MCP auto-starts on /mcp endpoint
+```
+
+## Konfigurace IDE
+
+Viz [konfigurace IDE](integrations/ide-configs.md) pro nastavení Antigravity, Cursoru, Copilota a Claude Desktopu.
+
+---
+
+## Základní nástroje (8)
+
+Nástroj | Popis
+:-- | :--
+`omniroute_get_health` | Stav brány, jističe, provozuschopnost
+`omniroute_list_combos` | Všechny nakonfigurované kombinace s modely
+`omniroute_get_combo_metrics` | Metriky výkonu pro konkrétní kombinaci
+`omniroute_switch_combo` | Přepnout aktivní kombinaci podle ID/jména
+`omniroute_check_quota` | Stav kvóty pro jednotlivé poskytovatele nebo všechny
+`omniroute_route_request` | Odeslání dokončení chatu přes OmniRoute
+`omniroute_cost_report` | Analýza nákladů za určité časové období
+`omniroute_list_models_catalog` | Kompletní katalog modelů s funkcemi
+
+## Pokročilé nástroje (8)
+
+Nástroj | Popis
+:-- | :--
+`omniroute_simulate_route` | Simulace trasování na dryru s fallback stromem
+`omniroute_set_budget_guard` | Rozpočet relace s akcemi degradace/blokování/upozornění
+`omniroute_set_resilience_profile` | Použít konzervativní/vyvážený/agresivní předvolbu
+`omniroute_test_combo` | Živé testování všech modelů v kombinaci
+`omniroute_get_provider_metrics` | Podrobné metriky pro jednoho poskytovatele
+`omniroute_best_combo_for_task` | Doporučení pro splnění úkolu a jeho vhodnosti s alternativami
+`omniroute_explain_route` | Vysvětlete minulé rozhodnutí o trase
+`omniroute_get_session_snapshot` | Stav celé relace: náklady, tokeny, chyby
+
+## Ověřování
+
+Nástroje MCP jsou ověřovány pomocí rozsahů klíčů API. Každý nástroj vyžaduje specifické rozsahy:
+
+Rozsah | Nástroje
+:-- | :--
+`read:health` | get_health, get_provider_metrics
+`read:combos` | seznam_kombinací, získání_kombinovaných_metrik
+`write:combos` | přepínač_kombinace
+`read:quota` | check_quote
+`write:route` | požadavek_trasy, simulace_trasy, testovací_kombinace
+`read:usage` | zpráva_o_nákladech, získání_snímku_relace, vysvětlení_trasy
+`write:config` | set_budget_guard, set_resilience_profile
+`read:models` | seznam_modelů_katalog, nejlepší_kombinace_pro_úkol
+
+## Protokolování auditu
+
+Každé volání nástroje je zaznamenáno do `mcp_tool_audit` s touto funkcí:
+
+- Název nástroje, argumenty, výsledek
+- Trvání (ms), úspěch/neúspěch
+- Haš klíče API, časové razítko
+
+## Soubory
+
+Soubor | Účel
+:-- | :--
+`open-sse/mcp-server/server.ts` | Vytvoření MCP serveru + 16 registrací nástrojů
+`open-sse/mcp-server/transport.ts` | Stdio + HTTP transport
+`open-sse/mcp-server/auth.ts` | Ověření klíče API + rozsahu
+`open-sse/mcp-server/audit.ts` | Protokolování auditu volání nástrojů
+`open-sse/mcp-server/tools/advancedTools.ts` | 8 pokročilých manipulátorů s nástroji

docs/i18n/cs/RELEASE_CHECKLIST.md

@@ -0,0 +1,33 @@
+# Kontrolní seznam vydání
+
+Tento kontrolní seznam použijte před označením nebo publikováním nové verze OmniRoute.
+
+## Verze a seznam změn
+
+1. Navýšit verzi `package.json` ( `xyz` ) ve větvi release.
+2. Přesunout poznámky k vydání z `## [Unreleased]` v `CHANGELOG.md` do sekce s datem vydání:
+    - `## [x.y.z] — YYYY-MM-DD`
+3. Ponechte `## [Unreleased]` jako první sekci changelogu pro nadcházející práci.
+4. Ujistěte se, že nejnovější sekce semver v `CHANGELOG.md` je rovna verzi `package.json` .
+
+## Dokumentace API
+
+1. Aktualizace `docs/openapi.yaml` :
+    - Soubor `info.version` se musí rovnat verzi `package.json` .
+2. Ověřte příklady koncových bodů, pokud se změnily smlouvy API.
+
+## Dokumentace k běhovému prostředí
+
+1. Projděte si `docs/ARCHITECTURE.md` , zda nedochází k posunu v úložišti/běhovém prostředí.
+2. Projděte si soubor `docs/TROUBLESHOOTING.md` , kde naleznete informace o proměnné prostředí a provozním posunu.
+3. Aktualizujte lokalizovanou dokumentaci, pokud se zdrojová dokumentace výrazně změnila.
+
+## Automatická kontrola
+
+Před otevřením PR spusťte lokálně ochranu synchronizace:
+
+```bash
+npm run check:docs-sync
+```
+
+CI také spouští tuto kontrolu v `.github/workflows/ci.yml` (úloha lint).

docs/i18n/cs/SECURITY.md

@@ -0,0 +1,169 @@
+# Bezpečnostní zásady
+
+## Hlášení zranitelností
+
+Pokud v OmniRoute objevíte bezpečnostní zranitelnost, nahlaste ji prosím zodpovědně:
+
+1. **NEOTVÍREJTE** veřejný problém na GitHubu
+2. Používejte [bezpečnostní doporučení GitHubu](https://github.com/diegosouzapw/OmniRoute/security/advisories/new)
+3. Zahrňte: popis, kroky reprodukce a potenciální dopad
+
+## Časová osa odezvy
+
+Fáze | Cíl
+--- | ---
+Potvrzení | 48 hodin
+Triáž a posouzení | 5 pracovních dnů
+Vydání záplaty | 14 pracovních dnů (kritické)
+
+## Podporované verze
+
+Verze | Stav podpory
+--- | ---
+1.0.x | ✅ Aktivní
+0.8.x | ✅ Bezpečnost
+< 0,8,0 | ❌ Nepodporováno
+
+---
+
+## Bezpečnostní architektura
+
+OmniRoute implementuje vícevrstvý bezpečnostní model:
+
+```
+Request → CORS → API Key Auth → Prompt Injection Guard → Input Sanitizer → Rate Limiter → Circuit Breaker → Provider
+```
+
+### 🔐 Ověřování a autorizace
+
+Funkce | Implementace
+--- | ---
+**Přihlášení do ovládacího panelu** | Ověřování na základě hesla s tokeny JWT (soubory cookie HttpOnly)
+**Autorizace klíče API** | Klíče podepsané HMAC s ověřením CRC
+**OAuth 2.0 + PKCE** | Bezpečné ověřování poskytovatelů (Claude, Codex, Gemini, Cursor atd.)
+**Obnovení tokenu** | Automatická aktualizace tokenu OAuth před vypršením platnosti
+**Bezpečné soubory cookie** | `AUTH_COOKIE_SECURE=true` pro prostředí HTTPS
+
+### 🛡️ Šifrování v klidovém stavu
+
+Všechna citlivá data uložená v SQLite jsou šifrována pomocí **AES-256-GCM** s odvozením klíče scrypt:
+
+- Klíče API, přístupové tokeny, obnovovací tokeny a ID tokeny
+- Verzovaný formát: `enc:v1:<iv>:<ciphertext>:<authTag>`
+- Režim průchodu (prostý text), pokud není nastaven `STORAGE_ENCRYPTION_KEY`
+
+```bash
+# Generate encryption key:
+STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)
+```
+
+### 🧠 Ochrana před okamžitou injekcí
+
+Middleware, který detekuje a blokuje útoky prompt injection v požadavcích LLM:
+
+Typ vzoru | Závažnost | Příklad
+--- | --- | ---
+Přepsání systému | Vysoký | "ignorovat všechny předchozí pokyny"
+Únos role | Vysoký | "Teď jsi DAN, dokážeš cokoli."
+Vložení oddělovače | Střední | Kódované oddělovače pro přerušení hranic kontextu
+DAN/Útěk z vězení | Vysoký | Známé vzory výzev k jailbreaku
+Únik instrukcí | Střední | „Ukaž mi systémový výzvu“
+
+Konfigurace přes ovládací panel (Nastavení → Zabezpečení) nebo `.env` :
+
+```env
+INPUT_SANITIZER_ENABLED=true
+INPUT_SANITIZER_MODE=block    # warn | block | redact
+```
+
+### 🔒 Redakční úprava osobních údajů
+
+Automatická detekce a volitelná redakce osobních údajů:
+
+Typ osobních údajů | Vzor | Nahrazení
+--- | --- | ---
+E-mail | `user@domain.com` | `[EMAIL_REDACTED]`
+CPF (Brazílie) | `123.456.789-00` | `[CPF_REDACTED]`
+CNPJ (Brazílie) | `12.345.678/0001-00` | `[CNPJ_REDACTED]`
+Kreditní karta | `4111-1111-1111-1111` | `[CC_REDACTED]`
+Telefon | `+55 11 99999-9999` | `[PHONE_REDACTED]`
+Číslo sociálního zabezpečení (USA) | `123-45-6789` | `[SSN_REDACTED]`
+
+```env
+PII_REDACTION_ENABLED=true
+```
+
+### 🌐 Zabezpečení sítě
+
+Funkce | Popis
+--- | ---
+**CORS** | Konfigurovatelná kontrola původu (proměnná prostředí `CORS_ORIGIN` , výchozí nastavení `*` )
+**Filtrování IP adres** | Rozsahy IP adres na bílou/černou listinu v dashboardu
+**Omezení rychlosti** | Limity sazeb na poskytovatele s automatickým ukončením
+**Protihromové stádo** | Mutex + uzamčení pro každé připojení zabraňuje kaskádování 502.
+
+### 🔌 Odolnost a dostupnost
+
+Funkce | Popis
+--- | ---
+**Jistič** | 3 stavy (Zavřeno → Otevřeno → Polootevřeno) na poskytovatele, trvalé uložení v SQLite
+**Žádost o idempotenci** | 5sekundové okno pro odstranění duplicitních požadavků
+**Exponenciální odklon** | Automatické opakování s rostoucím zpožděním
+**Dashboard zdraví** | Monitorování stavu poskytovatele v reálném čase
+
+### 📋 Dodržování předpisů
+
+Funkce | Popis
+--- | ---
+**Uchovávání protokolů** | Automatické čištění po `LOG_RETENTION_DAYS`
+**Odhlášení bez ukládání protokolů** | Příznak `noLog` pro každý klíč API zakazuje protokolování požadavků.
+**Protokol auditu** | Administrativní akce sledované v tabulce `audit_log`
+
+---
+
+## Požadované proměnné prostředí
+
+Všechny tajné kódy musí být nastaveny před spuštěním serveru. Server **rychle selže** , pokud chybí nebo jsou slabé.
+
+```bash
+# REQUIRED — server will not start without these:
+JWT_SECRET=$(openssl rand -base64 48)     # min 32 chars
+API_KEY_SECRET=$(openssl rand -hex 32)    # min 16 chars
+
+# RECOMMENDED — enables encryption at rest:
+STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)
+```
+
+Server aktivně odmítá známé slabé hodnoty, jako například `changeme` , `secret` nebo `password` .
+
+---
+
+## Zabezpečení Dockeru
+
+- Použití uživatele bez oprávnění root v produkčním prostředí
+- Připojte tajné kódy jako svazky jen pro čtení
+- Nikdy nekopírujte soubory `.env` do imagí Dockeru
+- Použití `.dockerignore` k vyloučení citlivých souborů
+- Nastavit `AUTH_COOKIE_SECURE=true` při připojení za HTTPS
+
+```bash
+docker run -d \
+  --name omniroute \
+  --restart unless-stopped \
+  --read-only \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  -e JWT_SECRET="$(openssl rand -base64 48)" \
+  -e API_KEY_SECRET="$(openssl rand -hex 32)" \
+  -e STORAGE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \
+  diegosouzapw/omniroute:latest
+```
+
+---
+
+## Závislosti
+
+- Pravidelně spouštějte `npm audit`
+- Udržujte závislosti aktualizované
+- Projekt používá pro kontroly před commitem `husky` + `lint-staged`
+- CI pipeline spouští bezpečnostní pravidla ESLint při každém odeslání.

docs/i18n/cs/TROUBLESHOOTING.md

@@ -0,0 +1,254 @@
+# Odstraňování problémů
+
+🌐 **Jazyky:** 🇺🇸 [angličtina](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [maďarština](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonésie](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nizozemsko](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](i18n/phi/TROUBLESHOOTING.md) | 🇨🇿 [Čeština](i18n/cs/TROUBLESHOOTING.md)
+
+Běžné problémy a řešení pro OmniRoute.
+
+---
+
+## Rychlé opravy
+
+Problém | Řešení
+--- | ---
+První přihlášení nefunguje | Nastavit `INITIAL_PASSWORD` v `.env` (bez pevně zakódovaného výchozího nastavení)
+Dashboard se otevírá na nesprávném portu | Nastavte `PORT=20128` a `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
+Žádné protokoly požadavků v sekci `logs/` | Nastavte `ENABLE_REQUEST_LOGS=true`
+PŘÍSTUP: povolení zamítnuto | Nastavením `DATA_DIR=/path/to/writable/dir` přepíšete `~/.omniroute`
+Strategie směrování se neukládá | Aktualizace na v1.4.11+ (oprava schématu Zod pro perzistenci nastavení)
+
+---
+
+## Problémy s poskytovateli
+
+### "Jazykový model neposkytoval zprávy"
+
+**Příčina:** Vyčerpání kvóty poskytovatele.
+
+**Opravit:**
+
+1. Zkontrolujte sledovač kvót na řídicím panelu
+2. Použijte kombinaci se záložními úrovněmi
+3. Přepnout na levnější/bezplatnou úroveň
+
+### Omezení rychlosti
+
+**Příčina:** Vyčerpání kvóty předplatného.
+
+**Opravit:**
+
+- Přidat záložní variantu: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Použijte GLM/MiniMax jako levnou zálohu
+
+### Platnost tokenu OAuth vypršela
+
+OmniRoute automaticky obnovuje tokeny. Pokud problémy přetrvávají:
+
+1. Ovládací panel → Poskytovatel → Znovu připojit
+2. Odstranění a opětovné přidání připojení poskytovatele
+
+---
+
+## Problémy s cloudem
+
+### Chyby synchronizace s cloudem
+
+1. Ověřte, zda `BASE_URL` odkazuje na vaši spuštěnou instanci (např. `http://localhost:20128` )
+2. Ověřte, zda `CLOUD_URL` odkazuje na váš cloudový koncový bod (např. `https://omniroute.dev` ).
+3. Udržujte hodnoty `NEXT_PUBLIC_*` zarovnané s hodnotami na straně serveru.
+
+### Cloud `stream=false` Vrací 500
+
+**Příznak:** `Unexpected token 'd'...` na cloudovém koncovém bodu pro nestreamovaná volání.
+
+**Příčina:** Upstream vrací datovou část SSE, zatímco klient očekává JSON.
+
+**Řešení:** Pro přímá volání z cloudu použijte `stream=true` . Lokální běhové prostředí zahrnuje záložní SSE→JSON.
+
+### Cloud hlásí připojení, ale „neplatný klíč API“.
+
+1. Vytvořte nový klíč z lokálního dashboardu ( `/api/keys` )
+2. Spuštění synchronizace s cloudem: Povolit cloud → Synchronizovat nyní
+3. Staré/nesynchronizované klíče mohou v cloudu stále vracet `401`
+
+---
+
+## Problémy s Dockerem
+
+### Nástroj CLI se zobrazuje jako nenainstalovaný
+
+1. Zkontrolujte běhová pole: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. Pro přenosný režim: použijte cílový soubor image `runner-cli` (dodávané CLI)
+3. Pro režim připojení hostitele: nastavte `CLI_EXTRA_PATHS` a připojte adresář hostitele bin jako pouze pro čtení.
+4. Pokud `installed=true` a `runnable=false` : binární soubor byl nalezen, ale kontrola stavu selhala.
+
+### Rychlé ověření za běhu
+
+```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}'
+```
+
+---
+
+## Problémy s náklady
+
+### Vysoké náklady
+
+1. Zkontrolujte statistiky využití v sekci Nástěnka → Využití
+2. Přepnout primární model na GLM/MiniMax
+3. Pro nekritické úlohy použijte bezplatnou úroveň (Gemini CLI, iFlow).
+4. Nastavení rozpočtů nákladů pro každý klíč API: Dashboard → API klíče → Rozpočet
+
+---
+
+## Ladění
+
+### Povolit protokoly požadavků
+
+V souboru `.env` nastavte `ENABLE_REQUEST_LOGS=true` . Protokoly se zobrazují v adresáři `logs/` .
+
+### Zkontrolujte stav poskytovatele
+
+```bash
+# Health dashboard
+http://localhost:20128/dashboard/health
+
+# API health check
+curl http://localhost:20128/api/monitoring/health
+```
+
+### Runtimové úložiště
+
+- Hlavní stav: `${DATA_DIR}/storage.sqlite` (poskytovatelé, kombinace, aliasy, klíče, nastavení)
+- Použití: SQLite tabulky v `storage.sqlite` ( `usage_history` , `call_logs` , `proxy_logs` ) + volitelné `${DATA_DIR}/log.txt` a `${DATA_DIR}/call_logs/`
+- Záznamy požadavků: `<repo>/logs/...` (pokud `ENABLE_REQUEST_LOGS=true` )
+
+---
+
+## Problémy s jističi
+
+### Poskytovatel uvízl ve stavu OPEN (OTEVŘENO)
+
+Pokud je jistič poskytovatele VYPNUTÝ, požadavky jsou blokovány, dokud neuplyne doba ochlazování.
+
+**Opravit:**
+
+1. Přejděte do **nabídky Ovládací panel → Nastavení → Odolnost**
+2. Zkontrolujte kartu jističe u dotčeného poskytovatele
+3. Kliknutím na **Obnovit vše** vynulujete všechny jističe nebo počkejte, až vyprší doba zpoždění.
+4. Před resetováním ověřte, zda je poskytovatel skutečně dostupný.
+
+### Poskytovatel neustále vypíná jistič
+
+Pokud poskytovatel opakovaně přechází do stavu OTEVŘENO:
+
+1. Zkontrolujte **v části Dashboard → Stav → Stav poskytovatele** vzorec selhání.
+2. Přejděte do **Nastavení → Odolnost → Profily poskytovatelů** a zvyšte prahovou hodnotu selhání.
+3. Zkontrolujte, zda poskytovatel změnil limity API nebo vyžaduje opětovné ověření.
+4. Zkontrolujte telemetrii latence – vysoká latence může způsobit selhání z důvodu časového limitu.
+
+---
+
+## Problémy s přepisem zvuku
+
+### Chyba „Nepodporovaný model“
+
+- Ujistěte se, že používáte správný prefix: `deepgram/nova-3` nebo `assemblyai/best`
+- Ověřte, zda je poskytovatel připojen v **nabídce Dashboard → Poskytovatelé.**
+
+### Přepis vrací prázdný výsledek nebo selže
+
+- Zkontrolujte podporované zvukové formáty: `mp3` , `wav` , `m4a` , `flac` , `ogg` , `webm`
+- Ověřte, zda je velikost souboru v rámci limitů poskytovatele (obvykle &lt; 25 MB)
+- Zkontrolujte platnost klíče API poskytovatele v kartě poskytovatele
+
+---
+
+## Ladění překladače
+
+Pro ladění problémů s překladem formátu použijte **Dashboard → Translator** :
+
+Režim | Kdy použít
+--- | ---
+**Dětské hřiště** | Porovnejte vstupní/výstupní formáty vedle sebe – vložte neúspěšný požadavek a podívejte se, jak se přeloží
+**Tester chatu** | Odesílejte živé zprávy a kontrolujte kompletní datovou část požadavků/odpovědí včetně záhlaví
+**Zkušební stolice** | Spusťte dávkové testy napříč kombinacemi formátů a zjistěte, které překlady jsou poškozené.
+**Živý monitor** | Sledujte tok požadavků v reálném čase a zachyťte občasné problémy s překladem
+
+### Běžné problémy s formátováním
+
+- **Štítky myšlení se nezobrazují** – Zkontrolujte, zda cílový poskytovatel podporuje myšlení a nastavení rozpočtu myšlení.
+- **Volání nástrojů se vynechávají** – Některé překlady formátů mohou odstranit nepodporovaná pole; ověřte v režimu Playground.
+- **Chybí systémová výzva** – Claude a Gemini zpracovávají systémové výzvy odlišně; zkontrolujte překlad výstupu
+- **SDK vrací nezpracovaný řetězec místo objektu** – Opraveno ve verzi 1.1.0: sanitizér odpovědí nyní odstraňuje nestandardní pole ( `x_groq` , `usage_breakdown` atd.), která způsobují selhání validace OpenAI SDK v Pydantic.
+- **GLM/ERNIE odmítá `system` roli** — Opraveno ve verzi 1.1.0: normalizátor rolí automaticky slučoval systémové zprávy s uživatelskými zprávami pro nekompatibilní modely.
+- **role `developer` nebyla rozpoznána** – Opraveno ve verzi 1.1.0: automaticky převedeno na `system` pro poskytovatele, kteří nepoužívají OpenAI
+- **`json_schema` nefunguje s Gemini** — Opraveno ve verzi 1.1.0: `response_format` se nyní převádí na `responseMimeType` + `responseSchema` z Gemini.
+
+---
+
+## Nastavení odolnosti
+
+### Automatické omezení rychlosti se nespouští
+
+- Automatické omezení rychlosti se vztahuje pouze na poskytovatele klíčů API (ne na OAuth/předplatné)
+- Ověřte **Nastavení → Odolnost → Profily poskytovatelů** mají povoleno automatické omezení rychlosti
+- Zkontrolujte, zda poskytovatel vrací stavové kódy `429` nebo hlavičky `Retry-After`
+
+### Ladění exponenciálního poklesu
+
+Profily poskytovatelů podporují tato nastavení:
+
+- **Základní zpoždění** — Počáteční doba čekání po prvním selhání (výchozí: 1 s)
+- **Max. zpoždění** — Maximální doba čekání (výchozí: 30 s)
+- **Násobitel** — O kolik se má zvýšit zpoždění za každou po sobě jdoucí chybu (výchozí: 2x)
+
+### Stádo proti hromům
+
+Když se na poskytovatele s omezenou rychlostí odesílá mnoho souběžných požadavků, OmniRoute použije mutex + automatické omezení rychlosti k serializaci požadavků a zabránění kaskádovým selháním. Toto je automatické pro poskytovatele klíčů API.
+
+---
+
+## Volitelná taxonomie selhání RAG / LLM (16 problémů)
+
+Někteří uživatelé OmniRoute umisťují bránu před RAG nebo agent stacky. V těchto nastaveních je běžné vidět zvláštní vzorec: OmniRoute vypadá v pořádku (poskytovatelé aktivní, profily směrování v pořádku, žádná upozornění na limity rychlosti), ale konečná odpověď je stále nesprávná.
+
+V praxi tyto incidenty obvykle pocházejí z následného RAG kanálu, nikoli ze samotné brány.
+
+Pokud chcete sdílenou slovní zásobu pro popis těchto selhání, můžete použít WFGY ProblemMap, externí textový zdroj s licencí MIT, který definuje šestnáct opakujících se vzorců selhání RAG / LLM. Na obecné úrovni zahrnuje:
+
+- drift vyhledávání a narušené hranice kontextu
+- prázdné nebo zastaralé indexy a vektorové úložiště
+- vkládání versus sémantický nesoulad
+- problémy s assembly promptu a kontextovým oknem
+- logický kolaps a přehnaně sebevědomé odpovědi
+- selhání dlouhého řetězce a koordinace agentů
+- paměť více agentů a posun rolí
+- problémy s nasazením a objednáváním bootstrapů
+
+Myšlenka je jednoduchá:
+
+1. Při vyšetřování špatné odpovědi zaznamenejte:
+    - úkol a požadavek uživatele
+    - Kombinace trasy nebo poskytovatele v OmniRoute
+    - jakýkoli kontext RAG použitý v následných fázích (načtené dokumenty, volání nástrojů atd.)
+2. Namapujte incident na jedno nebo dvě čísla z WFGY ProblemMap ( `No.1` … `No.16` ).
+3. Uložte číslo do vlastního řídicího panelu, runbooku nebo sledovače incidentů vedle protokolů OmniRoute.
+4. Pro rozhodnutí, zda je potřeba změnit RAG stack, retriever nebo směrovací strategii, použijte odpovídající stránku WFGY.
+
+Plný text a konkrétní recepty naleznete zde (licence MIT, pouze text):
+
+[Soubor README pro mapu problémů WFGY](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
+
+Tuto část můžete ignorovat, pokud za OmniRoute nespouštěte RAG ani agenty.
+
+---
+
+## Stále v koncích?
+
+- **Problémy s GitHubem** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Architektura** : Viz [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) pro interní podrobnosti
+- **Referenční informace k API** : Všechny koncové body naleznete v [`docs/API_REFERENCE.md`](API_REFERENCE.md)
+- **Panel stavu** : Zkontrolujte **Panel stavu, kde** najdete stav systému v reálném čase.
+- **Překladač** : Použijte **Dashboard → Překladač** k ladění problémů s formátem

docs/i18n/cs/USER_GUIDE.md

@@ -0,0 +1,808 @@
+# Uživatelská příručka
+
+🌐 **Jazyky:** 🇺🇸 [angličtina](USER_GUIDE.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [maďarština](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonésie](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nizozemsko](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](i18n/phi/USER_GUIDE.md) | 🇨🇿 [Čeština](i18n/cs/USER_GUIDE.md)
+
+Kompletní průvodce konfigurací poskytovatelů, vytvářením kombinací, integrací nástrojů CLI a nasazením OmniRoute.
+
+---
+
+## Obsah
+
+- [Ceny v kostce](#-pricing-at-a-glance)
+- [Případy použití](#-use-cases)
+- [Nastavení poskytovatele](#-provider-setup)
+- [Integrace s rozhraním CLI](#-cli-integration)
+- [Nasazení](#-deployment)
+- [Dostupné modely](#-available-models)
+- [Pokročilé funkce](#-advanced-features)
+
+---
+
+## 💰 Přehled cen
+
+| Úroveň            | Poskytovatel      | Náklady          | Obnovení kvóty      | Nejlepší pro               |
+| ----------------- | ----------------- | ---------------- | ------------------- | -------------------------- |
+| **💳 PŘEDPLATNÉ** | Claude Code (pro) | 20 USD měsíc     | 5h + týdně          | Již přihlášené             |
+|                   | Kodex (Plus/Pro)  | 20–200 USD/měsíc | 5h + týdně          | Uživatele OpenAI           |
+|                   | Gemini CLI        | **ZDARMA**       | 180K/mo + 1K/den    | Každého!                   |
+|                   | GitHub Copilot    | 10–19 USD/měsíc  | Měsíční             | Uživatele GitHubu          |
+| **🔑 KLÍČ API**   | DeepSeek          | Dle užití        | Žádné               | Laciné uvažování           |
+|                   | Groq              | Dle užití        | Žádné               | Ultrarychlá inference      |
+|                   | xAI (Grok)        | Dle užití        | Žádné               | Grok 4 uvažování           |
+|                   | Mistral           | Dle užití        | Žádné               | Modely hostované v EU      |
+|                   | Perplexity        | Dle užití        | Žádné               | Rozšířené vyhledávání      |
+|                   | Together AI       | Dle užití        | Žádné               | Open Source modely         |
+|                   | Fireworks AI      | Dle užití        | Žádné               | Rychlé FLUX obrázky        |
+|                   | Cerebras          | Dle užití        | Žádné               | Rychlost destičkového čipu |
+|                   | Cohere            | Dle užití        | Žádné               | Command R+ RAG             |
+|                   | NVIDIA NIM        | Dle užití        | Žádné               | Podnikové modely           |
+| **💰 LEVNÉ**      | GLM-4.7           | $0.6/1M          | Denně 10:00         | Levná záloha               |
+|                   | MiniMax M2.1      | $0.2/1M          | 5hodinové válcování | Nejlevnější varianta       |
+|                   | Kimi K2           | 9 USD měsíc      | 10M tokens/měsíc    | Předvídatelné náklady      |
+| **🆓 ZDARMA**     | iFlow             | $0               | Neomezený           | 8 modelů zdarma            |
+|                   | Qwen              | $0               | Neomezený           | 3 modely zdarma            |
+|                   | Kiro              | $0               | Neomezený           | Claude zdarma              |
+
+**💡 Pro Tip:** Začněte s kombinací Gemini CLI (180K zdarma/měsíc) + iFlow (neomezeně zdarma) = $0!
+
+---
+
+## 🎯 Případy použití
+
+### Případ 1: „Mám předplatné Claude Pro“
+
+**Problém:** Kvóta vyprší, nevyužitá, limity rychlosti během náročného kódování
+
+```
+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
+```
+
+### Případ 2: „Chci nulové náklady“
+
+**Problém:** Nemůžu si dovolit předplatné, potřebuji spolehlivé kódování s využitím umělé inteligence
+
+```
+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
+```
+
+### Případ 3: „Potřebuji kódování 24 hodin denně, 7 dní v týdnu, bez přerušení“
+
+**Problém:** Termíny, nemůžeme si dovolit prostoje
+
+```
+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)
+```
+
+### Případ 4: „Chci BEZPLATNOU AI v OpenClaw“
+
+**Problém:** Potřebujete asistenta s umělou inteligencí v aplikacích pro zasílání zpráv, zcela zdarma
+
+```
+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...
+```
+
+---
+
+## 📖 Nastavení poskytovatele
+
+### 🔐 Poskytovatelé předplatného
+
+#### 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
+```
+
+**Tip pro profesionály:** Pro složité úkoly používejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvótu pro každý 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 (ZDARMA 180 000/měsíc!)
+
+```bash
+Dashboard → Providers → Connect Gemini CLI
+→ Google OAuth
+→ 180K completions/month + 1K/day
+
+Models:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**Nejlepší hodnota:** Obrovská bezplatná úroveň! Použijte ji před placenými úrovněmi.
+
+#### 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
+```
+
+### 💰 Levní poskytovatelé
+
+#### GLM-4.7 (Denní reset, 0,6 USD/1 milion)
+
+1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)
+2. Získejte klíč API z kódovacího plánu
+3. Nástěnka → Přidat klíč API: Poskytovatel: `glm` , klíč API: `your-key`
+
+**Použití:** `glm/glm-4.7` — **Tip pro profesionály:** Coding Plan nabízí 3× kvótu za cenu 1/7! Resetovat denně v 10:00.
+
+#### MiniMax M2.1 (5h reset, 0,20 $/1 milion)
+
+1. Registrace: [MiniMax](https://www.minimax.io/)
+2. Získat API klíč → Dashboard → Přidat API klíč
+
+**Použití:** `minimax/MiniMax-M2.1` — **Tip pro profesionály:** Nejlevnější varianta pro dlouhý kontext (1 milion tokenů)!
+
+#### Kimi K2 (paušální poplatek 9 dolarů měsíčně)
+
+1. Odebírat: [Moonshot AI](https://platform.moonshot.ai/)
+2. Získat API klíč → Dashboard → Přidat API klíč
+
+**Použití:** `kimi/kimi-latest` — **Tip pro profesionály:** Fixní cena 9 $/měsíc za 10 milionů tokenů = efektivní náklady 0,90 $/1 milion!
+
+### 🆓 Poskytovatelé ZDARMA
+
+#### iFlow (8 modelů ZDARMA)
+
+```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 modely ZDARMA)
+
+```bash
+Dashboard → Connect Qwen → Device code auth → Unlimited usage
+
+Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
+```
+
+#### Kiro (Claude ZDARMA)
+
+```bash
+Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
+
+Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
+```
+
+---
+
+## 🎨 Kombinace
+
+### Příklad 1: Maximalizace předplatného → Levné zálohování
+
+```
+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
+```
+
+### Příklad 2: Pouze zdarma (nulové náklady)
+
+```
+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!
+```
+
+---
+
+## 🔧 Integrace s rozhraním příkazového řádku
+
+### IDE kurzoru
+
+```
+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
+
+Upravit `~/.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
+
+Upravit `~/.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" }]
+      }
+    }
+  }
+}
+```
+
+**Nebo použijte Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Pokračovat / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-6
+```
+
+---
+
+## 🚀 Nasazení
+
+### Globální instalace npm (doporučeno)
+
+```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
+```
+
+CLI automaticky načte `.env` z adresáře `~/.omniroute/.env` nebo `./.env` .
+
+### Nasazení 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
+```
+
+### Nasazení PM2 (málo paměti)
+
+Pro servery s omezenou pamětí RAM použijte možnost omezení paměti:
+
+```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
+```
+
+Vytvořte soubor `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",
+    },
+  ],
+};
+```
+
+### Přístavní dělník
+
+```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
+```
+
+Informace o režimu integrovaném s hostitelem s binárními soubory CLI naleznete v části Docker v hlavní dokumentaci.
+
+### Proměnné prostředí
+
+| Proměnná                  | Výchozí                              | Popis                                                              |
+| ------------------------- | ------------------------------------ | ------------------------------------------------------------------ |
+| `JWT_SECRET`              | `omniroute-default-secret-change-me` | Tajný klíč podpisu JWT ( **změna v produkčním prostředí** )        |
+| `INITIAL_PASSWORD`        | `123456`                             | První přihlašovací heslo                                           |
+| `DATA_DIR`                | `~/.omniroute`                       | Datový adresář (db, využití, protokoly)                            |
+| `PORT`                    | výchozí nastavení rámce              | Servisní port ( `20128` v příkladech)                              |
+| `HOSTNAME`                | výchozí nastavení rámce              | Vázat hostitele (Docker má výchozí hodnotu `0.0.0.0` )             |
+| `NODE_ENV`                | výchozí nastavení za běhu            | Nastavení `production` pro nasazení                                |
+| `BASE_URL`                | `http://localhost:20128`             | Interní základní URL na straně serveru                             |
+| `CLOUD_URL`               | `https://omniroute.dev`              | Základní adresa URL koncového bodu synchronizace s cloudem         |
+| `API_KEY_SECRET`          | `endpoint-proxy-api-key-secret`      | Tajný klíč HMAC pro generované klíče API                           |
+| `REQUIRE_API_KEY`         | `false`                              | Vynutit klíč rozhraní Bearer API na `/v1/*`                        |
+| `ENABLE_REQUEST_LOGS`     | `false`                              | Povoluje protokolování požadavků/odpovědí                          |
+| `AUTH_COOKIE_SECURE`      | `false`                              | Vynutit soubor cookie `Secure` ověřování (za reverzní proxy HTTPS) |
+| `OMNIROUTE_MEMORY_MB`     | `512`                                | Limit haldy Node.js v MB                                           |
+| `PROMPT_CACHE_MAX_SIZE`   | `50`                                 | Maximální počet položek mezipaměti výzev                           |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100`                                | Maximální počet položek sémantické mezipaměti                      |
+
+Úplný přehled proměnných prostředí naleznete v souboru [README](../README.md) .
+
+---
+
+## 📊 Dostupné modely
+
+<details>
+<summary><b>Zobrazit všechny dostupné modely</b></summary>
+</details>
+
+**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/` )** — ZDARMA: `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 milion: `glm/glm-4.7`
+
+**MiniMax ( `minimax/` )** — 0,2 USD/1 milion: `minimax/MiniMax-M2.1`
+
+**iFlow ( `if/` )** — ZDARMA: `if/kimi-k2-thinking` , `if/qwen3-coder-plus` , `if/deepseek-r1`
+
+**Qwen ( `qw/` )** — ZDARMA: `qw/qwen3-coder-plus` , `qw/qwen3-coder-flash`
+
+**Kiro ( `kr/` )** — ZDARMA: `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`
+
+**Zmatek ( `pplx/` )** : `pplx/sonar-pro` , `pplx/sonar`
+
+**Společně AI ( `together/` )** : `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+
+**Umělá inteligence pro ohňostroje ( `fireworks/` )** : `fireworks/accounts/fireworks/models/deepseek-v3p1`
+
+**Cerebras ( `cerebras/` )** : `cerebras/llama-3.3-70b`
+
+**Soudržnost ( `cohere/` )** : `cohere/command-r-plus-08-2024`
+
+**NVIDIA NIM ( `nvidia/` )** : `nvidia/nvidia/llama-3.3-70b-instruct`
+
+---
+
+## 🧩 Pokročilé funkce
+
+### Vlastní modely
+
+Přidejte libovolné ID modelu k libovolnému poskytovateli bez čekání na aktualizaci aplikace:
+
+```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"
+```
+
+Nebo použijte Dashboard: **Poskytovatelé → [Poskytovatel] → Vlastní modely** .
+
+### Vyhrazené trasy poskytovatelů
+
+Směrování požadavků přímo ke konkrétnímu poskytovateli s validací modelu:
+
+```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
+```
+
+Pokud chybí prefix poskytovatele, automaticky se přidá. Neshodné modely vrátí chybu `400` .
+
+### Konfigurace síťového proxy serveru
+
+```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"}}'
+```
+
+**Priorita:** Specifická pro klíč → Specifická pro kombinaci → Specifická pro poskytovatele → Globální → Prostředí.
+
+### API katalogu modelů
+
+```bash
+curl http://localhost:20128/api/models/catalog
+```
+
+Vrátí modely seskupené podle poskytovatele s typy ( `chat` , `embedding` , `image` ).
+
+### Synchronizace s cloudem
+
+- Synchronizace poskytovatelů, kombinací a nastavení napříč zařízeními
+- Automatická synchronizace na pozadí s časovým limitem + rychlá ochrana proti selhání
+- V produkčním prostředí preferovat `BASE_URL` / `CLOUD_URL` na straně serveru
+
+### LLM Gateway Intelligence (fáze 9)
+
+- **Sémantická mezipaměť** — Automaticky ukládá do mezipaměti nestreamované odpovědi s teplotou 0 (obejde se pomocí `X-OmniRoute-No-Cache: true` )
+- **Request Idempotency** — Deduplikuje požadavky do 5 sekund pomocí hlavičky `Idempotency-Key` nebo `X-Request-Id`
+- **Sledování průběhu** — `event: progress` prostřednictvím záhlaví `X-OmniRoute-Progress: true`
+
+---
+
+### Hřiště překladatelů
+
+Přístup přes **Dashboard → Translator** . Ladění a vizualizace toho, jak OmniRoute překládá požadavky API mezi poskytovateli.
+
+| Režim                | Účel                                                                                        |
+| -------------------- | ------------------------------------------------------------------------------------------- |
+| **Dětské hřiště**    | Vyberte zdrojový/cílový formát, vložte požadavek a okamžitě si prohlédněte přeložený výstup |
+| **Tester chatu**     | Odesílejte zprávy živého chatu přes proxy a kontrolujte celý cyklus požadavku/odpovědi      |
+| **Zkušební stolice** | Spusťte dávkové testy napříč různými kombinacemi formátů pro ověření správnosti překladu    |
+| **Živý monitor**     | Sledujte překlady v reálném čase, jak požadavky procházejí proxy serverem                   |
+
+**Případy použití:**
+
+- Ladění, proč selhává určitá kombinace klienta/poskytovatele
+- Ověřte, zda se tagy myšlení, volání nástrojů a systémové výzvy správně překládají.
+- Porovnejte rozdíly ve formátech OpenAI, Claude, Gemini a Responses API
+
+---
+
+### Strategie směrování
+
+Konfigurace přes **Dashboard → Nastavení → Routing** .
+
+| Strategie                    | Popis                                                                                             |
+| ---------------------------- | ------------------------------------------------------------------------------------------------- |
+| **Nejprve vyplňte**          | Používá účty podle priority – primární účet zpracovává všechny požadavky, dokud není k dispozici. |
+| **Round Robin**              | Cykluje mezi všemi účty s nastavitelným trvalým limitem (výchozí: 3 volání na účet)               |
+| **P2C (Síla dvou možností)** | Vybere 2 náhodné účty a nasměruje je k tomu zdravějšímu – vyvažuje zátěž s povědomím o zdraví     |
+| **Náhodný**                  | Náhodně vybere účet pro každý požadavek pomocí Fisher-Yatesova náhodného výběru.                  |
+| **Nejméně používané**        | Směruje k účtu s nejstarším časovým razítkem `lastUsedAt` a rovnoměrně rozděluje provoz.          |
+| **Optimalizované náklady**   | Směruje k účtu s nejnižší prioritou a optimalizuje pro poskytovatele s nejnižšími náklady.        |
+
+#### Aliasy zástupných znaků modelů
+
+Vytvořte zástupné znaky pro přemapování názvů modelů:
+
+```
+Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-*               →  Target: gh/gpt-5.1-codex
+```
+
+Zástupné znaky podporují `*` (libovolný znak) a `?` (jeden znak).
+
+#### Záložní řetězce
+
+Definujte globální záložní řetězce, které platí pro všechny požadavky:
+
+```
+Chain: production-fallback
+  1. cc/claude-opus-4-6
+  2. gh/gpt-5.1-codex
+  3. glm/glm-4.7
+```
+
+---
+
+### Odolnost a jističe
+
+Konfigurace přes **Dashboard → Settings → Resilience** .
+
+OmniRoute implementuje odolnost na úrovni poskytovatele se čtyřmi komponentami:
+
+1. **Profily poskytovatelů** – Konfigurace pro jednotlivé poskytovatele pro:
+   - Práh selhání (počet selhání před otevřením)
+   - Doba zchlazení
+   - Citlivost detekce limitu frekvence
+   - Exponenciální backoff parametry
+
+2. **Upravitelné limity rychlosti** – Výchozí nastavení na úrovni systému konfigurovatelná na řídicím panelu:
+   - **Požadavky za minutu (RPM)** — Maximální počet požadavků za minutu na účet
+   - **Minimální doba mezi požadavky** — Minimální mezera v milisekundách mezi požadavky
+   - **Max. počet souběžných požadavků** — Maximální počet souběžných požadavků na účet
+   - Klikněte na **Upravit** pro úpravu a poté **na Uložit** nebo **Zrušit** . Hodnoty se ukládají prostřednictvím rozhraní API pro odolnost.
+
+3. **Jistič** – Sleduje poruchy u jednotlivých poskytovatelů a automaticky rozpojuje obvod, když je dosaženo prahové hodnoty:
+   - **ZAVŘENO** (v pořádku) – Požadavky probíhají normálně.
+   - **OTEVŘENO** — Poskytovatel je dočasně zablokován po opakovaných selháních
+   - **HALF_OPEN** — Testování, zda se poskytovatel zotavil
+
+4. **Zásady a uzamčené identifikátory** – Zobrazuje stav jističe a uzamčené identifikátory s možností vynuceného odemčení.
+
+5. **Automatická detekce limitu rychlosti** – Monitoruje záhlaví `429` a `Retry-After` , aby se proaktivně zabránilo dosažení limitů rychlosti poskytovatele.
+
+**Tip pro profesionály:** Pomocí tlačítka **Obnovit vše** vymažete všechny jističe a doby ochlazování, když se poskytovatel zotaví z výpadku.
+
+---
+
+### Export / import databáze
+
+Správa záloh databáze se provádí v **nabídce Ovládací panel → Nastavení → Systém a úložiště** .
+
+| Akce                         | Popis                                                                                                                                      |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Exportovat databázi**      | Stáhne aktuální databázi SQLite jako soubor `.sqlite`                                                                                      |
+| **Exportovat vše (.tar.gz)** | Stáhne kompletní zálohu včetně: databáze, nastavení, kombinací, připojení k poskytovatelům (bez přihlašovacích údajů) a metadat klíče API. |
+| **Importovat databázi**      | Nahrajte soubor `.sqlite` , který nahradí aktuální databázi. Záloha před importem se vytvoří automaticky.                                  |
+
+```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"
+```
+
+**Ověření importu:** Importovaný soubor je ověřen z hlediska integrity (kontrola pragma SQLite), požadovaných tabulek ( `provider_connections` , `provider_nodes` , `combos` , `api_keys` ) a velikosti (max. 100 MB).
+
+**Případy použití:**
+
+- Migrace OmniRoute mezi počítači
+- Vytvořte externí zálohy pro zotavení po havárii
+- Sdílení konfigurací mezi členy týmu (exportovat vše → sdílet archiv)
+
+---
+
+### Ovládací panel nastavení
+
+Stránka nastavení je pro snadnou navigaci uspořádána do 5 záložek:
+
+| Záložka               | Obsah                                                                                                            |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **Zabezpečení**       | Nastavení přihlášení/hesla, řízení přístupu k IP adrese, autorizace API pro `/models` a blokování poskytovatelů  |
+| **Směrování**         | Globální strategie směrování (6 možností), aliasy zástupných znaků, záložní řetězce, kombinované výchozí hodnoty |
+| **Odolnost**          | Profily poskytovatelů, upravitelné limity sazeb, stav jističů, zásady a uzamčené identifikátory                  |
+| **Umělá inteligence** | Konfigurace rozpočtu promyšleného projektu, globální vkládání promptu do systému, statistiky mezipaměti promptu  |
+| **Moderní**           | Globální konfigurace proxy (HTTP/SOCKS5)                                                                         |
+
+---
+
+### Správa nákladů a rozpočtu
+
+Přístup přes **Dashboard → Náklady** .
+
+| Záložka      | Účel                                                                                                        |
+| ------------ | ----------------------------------------------------------------------------------------------------------- |
+| **Rozpočet** | Nastavte limity útrat pro každý klíč API s denními/týdenními/měsíčními rozpočty a sledováním v reálném čase |
+| **Ceny**     | Zobrazení a úprava cenových položek modelu – cena za 1000 vstupních/výstupních tokenů na poskytovatele      |
+
+```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
+```
+
+**Sledování nákladů:** Každý požadavek zaznamenává využití tokenů a vypočítává náklady pomocí ceníkové tabulky. Rozdělení si můžete prohlédnout v **sekci Dashboard → Využití** podle poskytovatele, modelu a klíče API.
+
+---
+
+### Přepis zvuku
+
+OmniRoute podporuje přepis zvuku prostřednictvím koncového bodu kompatibilního s 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"
+```
+
+Dostupní poskytovatelé: **Deepgram** ( `deepgram/` ), **AssemblyAI** ( `assemblyai/` ).
+
+Podporované zvukové formáty: `mp3` , `wav` , `m4a` , `flac` , `ogg` , `webm` .
+
+---
+
+### Strategie kombinovaného vyvažování
+
+Nastavte vyvažování jednotlivých kombinací v **nabídce Dashboard → Kombinace → Vytvořit/Upravit → Strategie** .
+
+| Strategie                             | Popis                                                                                 |
+| ------------------------------------- | ------------------------------------------------------------------------------------- |
+| **Round-Robin**                       | Postupně prochází modely                                                              |
+| **Přednost**                          | Vždy se pokusí o první model; vrací se pouze v případě chyby.                         |
+| **Náhodný**                           | Pro každý požadavek vybere náhodný model z komba                                      |
+| **Vážené**                            | Trasy proporcionálně na základě přiřazených vah pro každý model                       |
+| **Nejméně používané**                 | Směruje k modelu s nejmenším počtem nedávných požadavků (používá kombinované metriky) |
+| **Optimalizované z hlediska nákladů** | Trasy k nejlevnějšímu dostupnému modelu (používá ceník)                               |
+
+Globální výchozí hodnoty kombinací lze nastavit v **nabídce Dashboard → Settings → Routing → Combo Defaults** .
+
+---
+
+### Dashboard zdraví
+
+Přístup přes **Dashboard → Stav** . Přehled stavu systému v reálném čase se 6 kartami:
+
+| Karta                    | Co to ukazuje                                                      |
+| ------------------------ | ------------------------------------------------------------------ |
+| **Stav systému**         | Doba provozuschopnosti, verze, využití paměti, datový adresář      |
+| **Zdraví poskytovatelů** | Stav jističe podle dodavatele (Zapnuto/Vypnuto/Napůl vypnuto)      |
+| **Limity sazeb**         | Aktivní limit rychlosti cooldownů na účet se zbývajícím časem      |
+| **Aktivní výluky**       | Poskytovatelé dočasně blokovaní politikou uzamčení                 |
+| **Mezipaměť podpisů**    | Statistiky mezipaměti pro deduplikaci (aktivní klíče, míra zásahů) |
+| **Telemetrie latence**   | Agregace latence p50/p95/p99 na poskytovatele                      |
+
+**Tip pro profesionály:** Stránka Zdraví se automaticky obnovuje každých 10 sekund. Pomocí karty jističe můžete zjistit, kteří poskytovatelé mají problémy.
+
+---
+
+## 🖥️ Desktopová aplikace (Electron)
+
+OmniRoute je k dispozici jako nativní desktopová aplikace pro Windows, macOS a Linux.
+
+### Instalace
+
+```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
+```
+
+### Instalatéři budov
+
+```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)
+```
+
+Výstup → `electron/dist-electron/`
+
+### Klíčové vlastnosti
+
+| Funkce                        | Popis                                                                |
+| ----------------------------- | -------------------------------------------------------------------- |
+| **Připravenost serveru**      | Před zobrazením okna se dotazuje server (žádná prázdná obrazovka)    |
+| **Systémový zásobník**        | Minimalizovat do zásobníku, změnit port, ukončit menu v zásobníku    |
+| **Správa přístavů**           | Změna portu serveru z panelu úloh (automatické restartování serveru) |
+| **Zásady zabezpečení obsahu** | Omezující CSP prostřednictvím záhlaví relace                         |
+| **Jedna instance**            | V daném okamžiku může běžet pouze jedna instance aplikace            |
+| **Offline režim**             | Dodávaný server Next.js funguje bez internetu                        |
+
+### Proměnné prostředí
+
+| Proměnná              | Výchozí | Popis                             |
+| --------------------- | ------- | --------------------------------- |
+| `OMNIROUTE_PORT`      | `20128` | Port serveru                      |
+| `OMNIROUTE_MEMORY_MB` | `512`   | Limit haldy Node.js (64–16384 MB) |
+
+📖 Úplná dokumentace: [`electron/README.md`](../electron/README.md)

docs/i18n/cs/VM_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,401 @@
+# Průvodce nasazením OmniRoute na VM s Cloudflare
+
+🌐 **Jazyky:** 🇺🇸 [English](VM_DEPLOYMENT_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/VM_DEPLOYMENT_GUIDE.md) | 🇪🇸 [Español](i18n/es/VM_DEPLOYMENT_GUIDE.md) | 🇫🇷 [Français](i18n/fr/VM_DEPLOYMENT_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/VM_DEPLOYMENT_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/VM_DEPLOYMENT_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/VM_DEPLOYMENT_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/VM_DEPLOYMENT_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/VM_DEPLOYMENT_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/VM_DEPLOYMENT_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/VM_DEPLOYMENT_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/VM_DEPLOYMENT_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/VM_DEPLOYMENT_GUIDE.md) | 🇧🇬 [Български](i18n/bg/VM_DEPLOYMENT_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/VM_DEPLOYMENT_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/VM_DEPLOYMENT_GUIDE.md) | 🇮🇱 [עברית](i18n/he/VM_DEPLOYMENT_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/VM_DEPLOYMENT_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/VM_DEPLOYMENT_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/VM_DEPLOYMENT_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/VM_DEPLOYMENT_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/VM_DEPLOYMENT_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/VM_DEPLOYMENT_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/VM_DEPLOYMENT_GUIDE.md) | 🇷🇴 [Română](i18n/ro/VM_DEPLOYMENT_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/VM_DEPLOYMENT_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/VM_DEPLOYMENT_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/VM_DEPLOYMENT_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/VM_DEPLOYMENT_GUIDE.md) | 🇨🇿 [Čeština](i18n/cs/VM_DEPLOYMENT_GUIDE.md)
+
+Kompletní průvodce instalací a konfigurací OmniRoute na virtuálním stroji (VPS) se správou domény prostřednictvím Cloudflare.
+
+---
+
+## Předpoklady
+
+| Položka      | Minimální                   | Doporučeno       |
+| ------------ | --------------------------- | ---------------- |
+| **Procesor** | 1 virtuální procesor        | 2 vCPU           |
+| **RAM**      | 1 GB                        | 2 GB             |
+| **Disk**     | 10GB SSD                    | 25GB SSD         |
+| **CPU**      | Ubuntu 22.04 LTS            | Ubuntu 24.04 LTS |
+| **Doména**   | Zaregistrována v Cloudflare | —                |
+| **Docker**   | Docker Engine 24+           | Docker 27+       |
+
+**Testovaní poskytovatelé**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail.
+
+---
+
+## 1. Konfigurace virtuálního počítače
+
+### 1.1 Vytvořit ihned
+
+Žádný preferovaný poskytovatel VPS:
+
+- Vyberte si Ubuntu 24.04 LTS
+- Vyberte minimální plán (1 vCPU / 1 GB RAM)
+- Nastavte silné heslo pro root nebo konfiguraci SSH klíče
+- Poznamenejte si **veřejnou IP** (např.: `203.0.113.10`)
+
+### 1.2 Připojení přes SSH
+
+```bash
+ssh root@203.0.113.10
+```
+
+### 1.3 Aktualizace systému
+
+```bash
+apt update && apt upgrade -y
+```
+
+### 1.4 Instalace Dockeru
+
+```bash
+# Nainstalovat závislosti
+apt install -y ca-certificates curl gnupg
+
+# Přidat oficiální Docker repository
+install -m 0755 -d /etc/apt/keyrings
+curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+chmod a+r /etc/apt/keyrings/docker.gpg
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
+apt update
+apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
+```
+
+### 1.5 Instalace nginxu
+
+```bash
+apt install -y nginx
+```
+
+### 1.6 Konfigurace firewallu (UFW)
+
+```bash
+ufw default deny incoming
+ufw default allow outgoing
+ufw allow 22/tcp    # SSH
+ufw allow 80/tcp    # HTTP (redirect)
+ufw allow 443/tcp   # HTTPS
+ufw enable
+```
+
+> **Tip**: Pro maximální zabezpečení omezte porty 80 a 443 pouze na IP Cloudflare. Viz sekce [Pokročilé zabezpečení](#pokrocilé-zabezpečení).
+
+---
+
+## 2. Instalace OmniRoute
+
+### 2.1 Vytvořit konfigurační adresář
+
+```bash
+mkdir -p /opt/omniroute
+```
+
+### 2.2 Vytvořit soubor s proměnnými prostředí
+
+```bash
+cat > /opt/omniroute/.env << 'EOF'
+# === Bezpečnost ===
+JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY
+INITIAL_PASSWORD=YourSecurePassword123!
+API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY
+STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY
+STORAGE_ENCRYPTION_KEY_VERSION=v1
+MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT
+
+# === App ===
+PORT=20128
+NODE_ENV=production
+HOSTNAME=0.0.0.0
+DATA_DIR=/app/data
+STORAGE_DRIVER=sqlite
+ENABLE_REQUEST_LOGS=true
+AUTH_COOKIE_SECURE=false
+REQUIRE_API_KEY=false
+
+# === Doména (změňte na vaši doménu) ===
+BASE_URL=https://llms.vasedomena.com
+NEXT_PUBLIC_BASE_URL=https://llms.vasedomena.com
+
+# === Cloud Sync (opcional) ===
+# CLOUD_URL=https://cloud.omniroute.online
+# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online
+EOF
+```
+
+> ⚠️ **DŮLEŽITÉ**: Vygenerujte jedinečné tajné klíče! Použijte `openssl rand -hex 32` pro každý klíč.
+
+### 2.3 Spuštění kontejneru
+
+```bash
+docker pull diegosouzapw/omniroute:latest
+
+docker run -d \
+  --name omniroute \
+  --restart unless-stopped \
+  --env-file /opt/omniroute/.env \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+### 2.4 Verificar se está rodando
+
+```bash
+docker ps | grep omniroute
+docker logs omniroute --tail 20
+```
+
+Vývojový příklad: `[DB] SQLite database ready` a `listening on port 20128` .
+
+---
+
+## 3. Konfigurace nginx (reverzní proxy)
+
+### 3.1 Vygenerovat SSL certifikát (Cloudflare Origin)
+
+Cloudflare nic neřeší:
+
+1. Používá **SSL/TLS → Origin Server**
+2. Klikněte na **Vytvořit certifikát**
+3. Ponechte výchozí nastavení (15 let, \*.vasedomena.com)
+4. Zkopírujte nebo zkopírujte **certifikát původu** a **soukromý klíč**
+
+```bash
+mkdir -p /etc/nginx/ssl
+
+# Vložit certifikát
+nano /etc/nginx/ssl/origin.crt
+
+# Colar a chave privada
+nano /etc/nginx/ssl/origin.key
+
+chmod 600 /etc/nginx/ssl/origin.key
+```
+
+### 3.2 Konfigurace nginxu
+
+```bash
+cat > /etc/nginx/sites-available/omniroute << 'NGINX'
+# Default server — bloqueia acesso direto por IP
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    listen 443 ssl default_server;
+    listen [::]:443 ssl default_server;
+    ssl_certificate     /etc/nginx/ssl/origin.crt;
+    ssl_certificate_key /etc/nginx/ssl/origin.key;
+    server_name _;
+    return 444;
+}
+
+# OmniRoute — HTTPS
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    server_name llms.vasedomena.com;  # Změňte na vaši doménu
+
+    ssl_certificate     /etc/nginx/ssl/origin.crt;
+    ssl_certificate_key /etc/nginx/ssl/origin.key;
+    ssl_protocols TLSv1.2 TLSv1.3;
+
+    client_max_body_size 100M;
+
+    location / {
+        proxy_pass http://127.0.0.1:20128;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket support
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+
+        # SSE (Server-Sent Events) — streaming AI responses
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 300s;
+        proxy_send_timeout 300s;
+    }
+}
+
+# HTTP → HTTPS redirect
+server {
+    listen 80;
+    listen [::]:80;
+    server_name llms.vasedomena.com;
+    return 301 https://$server_name$request_uri;
+}
+NGINX
+```
+
+### 3.3 Ativar a testování
+
+```bash
+# Remover config padrão
+rm -f /etc/nginx/sites-enabled/default
+
+# Ativar OmniRoute
+ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute
+
+# Testar e recarregar
+nginx -t && systemctl reload nginx
+```
+
+---
+
+## 4. Konfigurace DNS v Cloudflare
+
+### 4.1 Další DNS registr
+
+V dashboardu Cloudflare → DNS:
+
+| Typ | Jméno  | Obsah                                           | Proxy    |
+| --- | ------ | ----------------------------------------------- | -------- |
+| A   | `llms` | `203.0.113.10` (IP adresa virtuálního počítače) | ✅ Proxy |
+
+### 4.2 Konfigurace SSL
+
+Em **SSL/TLS → Přehled** :
+
+- Režim: **Plný (Přísný)**
+
+V **SSL/TLS → Edge Certificates**:
+
+- Vždy používat HTTPS: ✅ Zapnuto
+- Minimální verze TLS: TLS 1.2
+- Automatické přepisování HTTPS: ✅ Zapnuto
+
+### 4.3 Testar
+
+```bash
+curl -sI https://llms.vasedomena.com/health
+# Deve retornar HTTP/2 200
+```
+
+---
+
+## 5. Operace a údržba
+
+### Aktualizovat na novou verzi
+
+```bash
+docker pull diegosouzapw/omniroute:latest
+docker stop omniroute && docker rm omniroute
+docker run -d --name omniroute --restart unless-stopped \
+  --env-file /opt/omniroute/.env \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+### Verzovní protokoly
+
+```bash
+docker logs -f omniroute          # Živý stream
+docker logs omniroute --tail 50   # Últimas 50 linhas
+```
+
+### Ruční zálohování banky
+
+```bash
+# Kopírovat data z volume do hostitele
+docker cp omniroute:/app/data ./backup-$(date +%F)
+
+# Ou comprimir todo o volume
+docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
+  alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data
+```
+
+### Obnovení zálohy
+
+```bash
+docker stop omniroute
+docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
+  alpine sh -c "rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /"
+docker start omniroute
+```
+
+---
+
+## 6. Pokročilá bezpečnost
+
+### Omezte přístup k IP Cloudflare
+
+```bash
+cat > /etc/nginx/cloudflare-ips.conf << 'CF'
+# Cloudflare IPv4 ranges — aktualizovat pravidelně
+# https://www.cloudflare.com/ips-v4/
+set_real_ip_from 173.245.48.0/20;
+set_real_ip_from 103.21.244.0/22;
+set_real_ip_from 103.22.200.0/22;
+set_real_ip_from 103.31.4.0/22;
+set_real_ip_from 141.101.64.0/18;
+set_real_ip_from 108.162.192.0/18;
+set_real_ip_from 190.93.240.0/20;
+set_real_ip_from 188.114.96.0/20;
+set_real_ip_from 197.234.240.0/22;
+set_real_ip_from 198.41.128.0/17;
+set_real_ip_from 162.158.0.0/15;
+set_real_ip_from 104.16.0.0/13;
+set_real_ip_from 104.24.0.0/14;
+set_real_ip_from 172.64.0.0/13;
+set_real_ip_from 131.0.72.0/22;
+real_ip_header CF-Connecting-IP;
+CF
+```
+
+Přidat do `nginx.conf` do bloku `http {}`:
+
+```nginx
+include /etc/nginx/cloudflare-ips.conf;
+```
+
+### Nainstalujte fail2ban
+
+```bash
+apt install -y fail2ban
+systemctl enable fail2ban
+systemctl start fail2ban
+
+# Verificar status
+fail2ban-client status sshd
+```
+
+### Bloquear accesso direto na port do Docker
+
+```bash
+# Zamezit přímému externímu přístupu k portu 20128
+iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP
+iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT
+
+# Persistir as regras
+apt install -y iptables-persistent
+netfilter-persistent save
+```
+
+---
+
+## 7. Nasazení cloudového pracovníka (volitelné)
+
+Vzdálený přístup přes Cloudflare Workers (zde exponovat diretament VM):
+
+```bash
+# No repositório local
+cd omnirouteCloud
+npm install
+npx wrangler login
+npx wrangler deploy
+```
+
+Dokumenty jsou kompletní pro [omnirouteCloud/README.md](../omnirouteCloud/README.md) .
+
+---
+
+## Přehled portů
+
+| Port  | Služba      | Přístup                                  |
+| ----- | ----------- | ---------------------------------------- |
+| 22    | SSH         | Veřejné (s fail2ban)                     |
+| 80    | nginx HTTP  | Přesměrování → HTTPS                     |
+| 443   | nginx HTTPS | Prostřednictvím proxy serveru Cloudflare |
+| 20128 | OmniRoute   | Někdy na localhostu (přes nginx)         |

docs/i18n/cs/adr/0001-proxy-registry-limit-generalization.md

@@ -0,0 +1,45 @@
+# ADR-0001: Zobecnění registru proxy serverů + kontroly využití
+
+Datum: 17. 3. 2026 Stav: Přijato
+
+## Kontext
+
+OmniRoute je užitečný:
+
+- Přiřazení proxy na základě konfigurační mapy ( `global` , `providers` , `combos` , `keys` ).
+- Výběr s ohledem na kvóty poskytovatele khusus tertentu (zejména `codex` ).
+
+Mezera utama:
+
+- Proxy belum menjadi asset opakovaně použitelný jang bisa di-manage sebagai entitas (metadata, kde se používají, bezpečné smazání).
+- Zásady použití belum konsisten lintas provider.
+- Chybová smlouva API belum seragam untuk manajemen endpoint manajemen.
+
+## Rozhodnutí
+
+1. Tambah **Proxy Registry** sebegai domény baru di DB ( `proxy_registry` , `proxy_assignments` ).
+2. Stálá kompatibilita přiřazení lama (záložní lama `proxyConfig` ).
+3. Priority pakai runtime modulu Resolver:
+    - účet -> poskytovatel -> globální (registr)
+    - záložní ke legacy resolver jika registry belum ada přiřazení
+4. Výchozí registr výstupního seznamu Wajib redaction kredensial di.
+5. Standarkan error JSON unuk endpoint manajemen proxy agar konsisten dan punya `requestId` .
+
+## Důsledky
+
+Pozitivní:
+
+- Opakovaně použitelný proxy server.
+- Bezpečné odstranění bisa ditegakkan (409 saat masih dipakai).
+- Migrasi bertahap tanpa prolomení runtime změn.
+
+Negativní:
+
+- Ada dual-source sementara (registr + starší konfigurace) sampai migrasi selesai.
+- Ale přiřazení koncových bodů tambahan a pemetaan rozsah a rozsah.
+
+## Následná opatření
+
+- Poskytovatel uživatelského rozhraní Migrasi/účet umožňuje zadat nezpracovaný registr selektoru proxy serveru.
+- Telemetrie zdraví Tambah na proxy a upozornění.
+- Všeobecná kontrola používání ke poskytovateli lain melalui interface policy yang sama.

docs/i18n/cs/adr/0002-api-error-contract-management-endpoints.md

@@ -0,0 +1,31 @@
+# ADR-0002: Chybová smlouva pro koncové body správy
+
+Datum: 17. 3. 2026 Stav: Přijato
+
+## Rozhodnutí
+
+Koncové body správy (konfigurace proxy, registr proxy a přiřazení proxy) vracejí jednotné tělo chyby:
+
+```json
+{
+  "error": {
+    "message": "Human-readable summary",
+    "type": "invalid_request | not_found | conflict | server_error",
+    "details": {}
+  },
+  "requestId": "uuid"
+}
+```
+
+## Mapování stavu
+
+- 400: neplatný požadavek / selhání ověření
+- 404: zdroj nenalezen
+- 409: konflikt zdrojů (například proxy stále přiřazen)
+- 500: neočekávaná chyba serveru
+
+## Poznámky
+
+- `requestId` je povinný pro korelaci protokolů.
+- `details` je volitelné a používá se pouze pro bezpečné ověření detailů.
+- Citlivé tajné informace (přihlašovací údaje proxy, tokeny) se nikdy nesmí objevit ve `message` ani v `details` .

docs/i18n/cs/adr/0003-security-checklist-proxy-limits.md

@@ -0,0 +1,15 @@
+# ADR-0003: Kontrolní seznam zabezpečení pro registr proxy a kontroly používání
+
+Datum: 17. 3. 2026 Stav: Přijato
+
+## Kontrolní seznam
+
+- Ověřte všechny datové části správy pomocí Zodu.
+- Odmítnout aktualizace chybně formátovaného přiřazení rozsahu se stavem 400.
+- Odmítnout smazání používané proxy se stavem 409, pokud to není vynuceno.
+- Ve výchozím nastavení nikdy nezobrazovat uživatelské jméno/heslo proxy v odpovědích seznamu.
+- Nikdy nezaznamenávejte nezpracované přihlašovací údaje ani hodnoty tokenů.
+- Udržujte chybové odpovědi bez interních trasování zásobníku.
+- Chraňte koncové body správy pomocí stávajících zásad middlewaru pro ověřování.
+- Auditovat mutující operace: vytvořit/aktualizovat/smazat/přiřadit/migraci.
+- Zajistěte, aby se resolver během přechodu vrátil k původní konfiguraci.

docs/i18n/cs/electron/README.md

@@ -0,0 +1,254 @@
+# Aplikace OmniRoute Electron pro stolní počítače
+
+Tento adresář obsahuje obalovou aplikaci Electron pro desktopovou aplikaci OmniRoute.
+
+## Architektura (v1.6.4)
+
+```
+electron/
+├── main.js          # Main process — window, tray, server lifecycle, CSP, IPC
+├── preload.js       # Preload script — secure IPC bridge with disposer pattern
+├── package.json     # Electron-specific dependencies & electron-builder config
+├── types.d.ts       # TypeScript definitions (AppInfo, ServerStatus, ElectronAPI)
+└── assets/          # Application icons and resources
+
+src/shared/hooks/
+└── useElectron.ts   # React hooks — useSyncExternalStore, zero re-renders
+```
+
+## Klíčová rozhodnutí o designu
+
+Rozhodnutí | Odůvodnění
+--- | ---
+dotazování `waitForServer()` | Zabraňuje zobrazení prázdné obrazovky při studeném startu — před načtením se ozve `http://localhost:PORT`
+`stdio: 'pipe'` | Zachycuje stdout/stderr serveru pro logování + detekci připravenosti ( `inherit` )
+Vzor drtiče odpadu | `onServerStatus()` vrací `() => void` pro přesné vyčištění listeneru (ne `removeAllListeners` )
+`useSyncExternalStore` | Nulové renderování pro `useIsElectron()` — žádný cyklus `useState` + `useEffect`
+CSP prostřednictvím záhlaví relace | `Content-Security-Policy` omezuje `script-src` , `connect-src` atd. dle osvědčených postupů Electron.
+Podmíněný titulek pro platformu | `titleBarStyle: 'hiddenInset'` pouze v systému macOS; `default` ve Windows/Linuxu
+
+## Rozvoj
+
+### Předpoklady
+
+1. Nejprve sestavte aplikaci Next.js:
+
+```bash
+npm run build
+```
+
+1. Instalace závislostí Electronu:
+
+```bash
+cd electron
+npm install
+```
+
+### Spuštěno ve vývoji
+
+1. Spusťte vývojový server Next.js:
+
+```bash
+npm run dev
+```
+
+1. V jiném terminálu spusťte Electron:
+
+```bash
+cd electron
+npm run dev
+```
+
+### Spuštění v produkčním režimu
+
+1. Sestavení Next.js v samostatném režimu:
+
+```bash
+npm run build
+```
+
+1. Spuštění elektronu:
+
+```bash
+cd electron
+npm start
+```
+
+## Budova
+
+### Sestavení pro aktuální platformu
+
+```bash
+cd electron
+npm run build
+```
+
+### Vytvořte pro specifické platformy
+
+```bash
+# Windows
+npm run build:win
+
+# macOS (x64 + arm64)
+npm run build:mac
+
+# Linux
+npm run build:linux
+```
+
+## Výstup
+
+Vytvořené aplikace jsou umístěny v `dist-electron/` :
+
+- Windows: `.exe` instalační program (NSIS) + přenosný `.exe`
+- macOS: instalační soubor `.dmg` (Intel + Apple Silicon)
+- Linux: `.AppImage`
+
+## Instalace
+
+### macOS
+
+1. Stáhněte si nejnovější soubor `.dmg` ze stránky [Verze](https://github.com/diegosouzapw/OmniRoute/releases) .
+2. Otevřete soubor `.dmg` .
+3. Přetáhněte `OmniRoute.app` do složky Aplikace.
+4. Spustit z Aplikací.
+
+> ⚠️ **Poznámka:** Aplikace zatím není podepsána certifikátem Apple Developer. Pokud macOS aplikaci blokuje, spusťte:
+>
+> ```bash
+> xattr -cr /Applications/OmniRoute.app
+> ```
+>
+> Nebo klikněte pravým tlačítkem myši na aplikaci → Otevřít → Otevřít (pro obejití Gatekeeperu při prvním spuštění).
+
+### Windows
+
+**Instalační program (doporučeno):**
+
+1. Stáhněte si `OmniRoute.Setup.*.exe` z [Releases](https://github.com/diegosouzapw/OmniRoute/releases) .
+2. Spusťte instalační program.
+3. Spuštění z nabídky Start nebo zástupce na ploše.
+
+**Přenosné (bez instalace):**
+
+1. Stáhněte si soubor `OmniRoute.exe` ze [sekce Vydání](https://github.com/diegosouzapw/OmniRoute/releases) .
+2. Spouštět přímo z libovolné složky.
+
+### Linux
+
+1. Stáhněte si soubor `.AppImage` ze [sekce Releases](https://github.com/diegosouzapw/OmniRoute/releases) .
+2. Udělejte z něj spustitelný soubor:
+    ```bash
+    chmod +x OmniRoute-*.AppImage
+    ```
+3. Běh:
+    ```bash
+    ./OmniRoute-*.AppImage
+    ```
+
+## Funkce
+
+- **Připravenost serveru** – Před zobrazením okna čeká na kontrolu stavu
+- **Systémový zásobník** — Minimalizace do systémového zásobníku s rychlými akcemi (otevřít, změnit port, ukončit)
+- **Správa portů** — Změna portu z nabídky v systémové liště (server se automaticky restartuje)
+- **Ovládací prvky oken** — Vlastní minimalizace, maximalizace, zavření přes IPC
+- **Zásady zabezpečení obsahu** – Omezující CSP prostřednictvím záhlaví relací
+- **Offline podpora** — Samostatný server Next.js v balíčku
+- **Jedna instance** – V daném okamžiku může běžet pouze jedna instance aplikace.
+
+## Konfigurace
+
+### Proměnné prostředí
+
+Proměnná | Výchozí | Popis
+--- | --- | ---
+`OMNIROUTE_PORT` | `20128` | Port serveru
+`OMNIROUTE_MEMORY_MB` | `512` | Limit haldy Node.js (64–16384 MB)
+`NODE_ENV` | `production` | Nastavit na `development` pro vývojářský režim
+
+### Vlastní ikona
+
+Umístěte ikony do `assets/` :
+
+- `icon.ico` — ikona Windows (256×256)
+- `icon.icns` — balíček ikon pro macOS
+- `icon.png` — Linux/obecné použití (512×512)
+- `tray-icon.png` — Ikona na systémové liště (16×16 nebo 32×32)
+
+## Kanály IPC
+
+### Vyvolání (Renderer → Hlavní, asynchronní)
+
+Kanál | Vrácení zboží | Popis
+--- | --- | ---
+`get-app-info` | `AppInfo` | Název aplikace, verze, platforma, isDev, port
+`open-external` | `void` | Otevřít URL ve výchozím prohlížeči (pouze http/https)
+`get-data-dir` | `string` | Získat cestu k adresáři userData
+`restart-server` | `{ success }` | Zastavení + restart serveru (časový limit 5 s + SIGKILL)
+
+### Odeslat (Renderer → Hlavní, spustit a zapomenout)
+
+Kanál | Popis
+--- | ---
+`window-minimize` | Minimalizovat okno
+`window-maximize` | Přepnout maximalizaci/obnovení
+`window-close` | Zavřít okno (minimalizovat do zásobníku)
+
+### Příjem (Hlavní → Renderer, události)
+
+Kanál | Užitečné zatížení | Vydáno, když
+--- | --- | ---
+`server-status` | `ServerStatus` | Server se spouští, zastavuje, dochází k chybám nebo se restartuje
+`port-changed` | `number` | Změna portu přes menu zásobníku
+
+> **Poznámka** : Posluchače vracejí funkce pro přesné čištění. Viz hooky `useServerStatus` a `usePortChanged` .
+
+## Zabezpečení
+
+Funkce | Implementace
+--- | ---
+Izolace kontextu | `contextIsolation: true` — renderer nemůže přistupovat k Node.js
+Integrace uzlů | `nodeIntegration: false` — v rendereru není `require()`
+Bílý seznam IPC | Názvy kanálů ověřené při předběžném načítání pomocí `safeInvoke` / `safeSend` / `safeOn`
+Ověření URL adresy | `shell.openExternal()` povoluje pouze protokoly `http:` / `https:`
+CSP | Záhlaví `Content-Security-Policy` nastavené pomocí `session.webRequest.onHeadersReceived`
+Zabezpečení webu | `webSecurity: true` – vynucena politika stejného původu
+
+## React Hooky
+
+Háček | Vrácení zboží | Popis
+--- | --- | ---
+`useIsElectron()` | `boolean` | Detekce nulového renderování pomocí `useSyncExternalStore`
+`useElectronAppInfo()` | `{ appInfo, loading, error }` | Informace o aplikaci z hlavního procesu
+`useDataDir()` | `{ dataDir, loading, error }` | Adresář uživatelských dat
+`useWindowControls()` | `{ minimize, maximize, close }` | Akce ovládání oken
+`useOpenExternal()` | `{ openExternal }` | Otevřít URL adresy v prohlížeči
+`useServerControls()` | `{ restart, restarting }` | Řízení restartu serveru
+`useServerStatus(cb)` | Drtič odpadu | Poslouchejte události stavu serveru
+`usePortChanged(cb)` | Drtič odpadu | Poslouchejte události změny portu
+
+## Odstraňování problémů
+
+### Aplikace se nespustí
+
+1. Zkontrolujte, zda je port 20128 dostupný: `lsof -i :20128`
+2. Zkontrolujte protokoly konzole pro prefix `[Electron]`
+3. Ověřte, zda výstup sestavení existuje v souboru `.next/standalone`
+
+### Bílá obrazovka
+
+1. Ověření existence buildu Next.js – čekání na připravenost serveru maximálně 30 sekund
+2. Zkontrolujte výstup protokolů `[Server]` a `[Server:err]`
+3. Hledání porušení CSP v konzoli pro vývojáře
+
+### Selhání sestavení
+
+Ujistěte se, že máte nainstalované nástroje pro sestavení:
+
+- Windows: Nástroje pro sestavení ve Visual Studiu
+- macOS: Nástroje příkazového řádku Xcode
+- Linux: `build-essential` , `libsecret-1-dev`
+
+## Licence
+
+MIT

docs/i18n/cs/i18n/README.md

@@ -0,0 +1,26 @@
+# Vícejazyčná dokumentace
+
+Tento adresář obsahuje strojově asistované překlady založené na anglické dokumentaci.
+
+- **API_REFERENCE.md** : 🇺🇸 [Česky](../API_REFERENCE.md) | 🇧🇷 [Português (Brazílie)](./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) | 🇩🇰 [Dánsko](./da/API_REFERENCE.md) | 🇫🇮 [Suomi](./fi/API_REFERENCE.md) | 🇮🇱 [עברית](./he/API_REFERENCE.md) | 🇭🇺 [maďarština](./hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonésie](./id/API_REFERENCE.md) | 🇰🇷 [한국어](./ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](./ms/API_REFERENCE.md) | 🇳🇱 [Nizozemsko](./nl/API_REFERENCE.md) | 🇳🇴 [Norsk](./no/API_REFERENCE.md) | 🇵🇹 [Português (Portugalsko)](./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) | 🇵🇭 [Filipínec](./phi/API_REFERENCE.md) | 🇨🇿 [Čeština](./cs/API_REFERENCE.md)
+
+- **ARCHITECTURE.md** : 🇺🇸 [anglicky](../ARCHITECTURE.md) | 🇧🇷 [Português (Brazílie)](./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) | 🇩🇰 [Dánsko](./da/ARCHITECTURE.md) | 🇫🇮 [Suomi](./fi/ARCHITECTURE.md) | 🇮🇱 [עברית](./he/ARCHITECTURE.md) | 🇭🇺 [maďarština](./hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonésie](./id/ARCHITECTURE.md) | 🇰🇷 [한국어](./ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](./ms/ARCHITECTURE.md) | 🇳🇱 [Nizozemsko](./nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](./no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugalsko)](./pt/ARCHITECTURE.md) | 🇷🇴 [Română](./ro/ARCHITECTURE.md) | 🇵🇱 [Polski](./pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](./sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](./sv/ARCHITECTURE.md) | 🇵🇭 [Filipínec](./phi/ARCHITECTURE.md) | 🇨🇿 [Čeština](./cs/ARCHITECTURE.md)
+
+- **CODEBASE_DOCUMENTATION.md** : 🇺🇸 [anglicky](../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brazílie)](./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) | 🇩🇰 [Dánsko](./da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](./fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](./he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [maďarština](./hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonésie](./id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](./ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](./ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nizozemsko](./nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](./no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugalsko)](./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) | 🇵🇭 [Filipínec](./phi/CODEBASE_DOCUMENTATION.md) | 🇨🇿 [Čeština](./cs/CODEBASE_DOCUMENTATION.md)
+
+- **FEATURES.md** : 🇺🇸 [anglicky](../FEATURES.md) | 🇧🇷 [Português (Brazílie)](./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) | 🇩🇰 [Dánsko](./da/FEATURES.md) | 🇫🇮 [Suomi](./fi/FEATURES.md) | 🇮🇱 [עברית](./he/FEATURES.md) | 🇭🇺 [maďarština](./hu/FEATURES.md) | 🇮🇩 [Bahasa Indonésie](./id/FEATURES.md) | 🇰🇷 [한국어](./ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](./ms/FEATURES.md) | 🇳🇱 [Nizozemsko](./nl/FEATURES.md) | 🇳🇴 [Norsk](./no/FEATURES.md) | 🇵🇹 [Português (Portugalsko)](./pt/FEATURES.md) | 🇷🇴 [Română](./ro/FEATURES.md) | 🇵🇱 [Polski](./pl/FEATURES.md) | 🇸🇰 [Slovenčina](./sk/FEATURES.md) | 🇸🇪 [Svenska](./sv/FEATURES.md) | 🇵🇭 [Filipínec](./phi/FEATURES.md) | 🇨🇿 [Čeština](./cs/FEATURES.md)
+
+- **TOUBLESHOOTING.md** : 🇺🇸 [anglicky](../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brazílie)](./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) | 🇩🇰 [Dánsko](./da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](./fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](./he/TROUBLESHOOTING.md) | 🇭🇺 [maďarština](./hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonésie](./id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](./ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](./ms/TROUBLESHOOTING.md) | 🇳🇱 [Nizozemsko](./nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](./no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugalsko)](./pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](./ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](./pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](./sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](./sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipínec](./phi/TROUBLESHOOTING.md) | 🇨🇿 [Čeština](./cs/TROUBLESHOOTING.md)
+
+- **USER_GUIDE.md** : 🇺🇸 [anglicky](../USER_GUIDE.md) | 🇧🇷 [Português (Brazílie)](./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) | 🇩🇰 [Dánsko](./da/USER_GUIDE.md) | 🇫🇮 [Suomi](./fi/USER_GUIDE.md) | 🇮🇱 [עברית](./he/USER_GUIDE.md) | 🇭🇺 [maďarština](./hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonésie](./id/USER_GUIDE.md) | 🇰🇷 [한국어](./ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](./ms/USER_GUIDE.md) | 🇳🇱 [Nizozemsko](./nl/USER_GUIDE.md) | 🇳🇴 [Norsk](./no/USER_GUIDE.md) | 🇵🇹 [Português (Portugalsko)](./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) | 🇵🇭 [Filipínec](./phi/USER_GUIDE.md) | 🇨🇿 [Čeština](./cs/USER_GUIDE.md)
+
+## Nedávná poznámka: Zásady limitů pro účty Codex
+
+Dokumentace nyní zahrnuje chování zásad kvót na úrovni účtu Codex:
+
+- Přepínání pro jednotlivé účty: `5h` a `Weekly` (ZAP/VYP).
+- Zásady prahových hodnot: povolené okno dosahující >=90 % označuje účet jako nezpůsobilý k výběru.
+- Automatická rotace: provoz se přesune na další způsobilý účet Codex.
+- Automatické opětovné použití: účet se opět stane způsobilým po úspěšném `resetAt` poskytovatele.
+
+Vygenerováno 26. února 2026.

docs/i18n/cs/open-sse/mcp-server/README.md

@@ -0,0 +1,587 @@
+# Server OmniRoute MCP
+
+> **Server protokolu modelového kontextu** , který zpřístupňuje inteligenci brány OmniRoute jako **16 nástrojů** pro agenty umělé inteligence.
+
+Server MCP umožňuje libovolnému agentovi umělé inteligence (Claude Desktop, Cursor, VS Code Copilot, vlastním agentům) programově **monitorovat, řídit a optimalizovat** bránu umělé inteligence OmniRoute.
+
+---
+
+## Architektura
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                         AI Agent / IDE                           │
+│          (Claude Desktop, Cursor, VS Code, Custom)               │
+└──────────────────────┬───────────────────────────────────────────┘
+                       │  MCP Protocol (stdio or HTTP)
+                       ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                      OmniRoute MCP Server                        │
+│  ┌──────────────┐  ┌─────────────────┐  ┌────────────────────┐  │
+│  │ Scope        │  │  16 MCP Tools   │  │   Audit Logger     │  │
+│  │ Enforcement  │──│  (Phase 1 + 2)  │──│   (SHA-256/SQLite) │  │
+│  └──────────────┘  └────────┬────────┘  └────────────────────┘  │
+└─────────────────────────────┼────────────────────────────────────┘
+                              │  HTTP (internal)
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                    OmniRoute Gateway (port 20128)                 │
+│        /v1/chat/completions  /api/combos  /api/usage  ...        │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Rychlý start
+
+### 1. Proměnné prostředí
+
+```bash
+# Required: OmniRoute base URL
+export OMNIROUTE_BASE_URL="http://localhost:20128"
+
+# Optional: API key for authenticated access
+export OMNIROUTE_API_KEY="your-api-key"
+
+# Optional: Scope enforcement (default: disabled)
+export OMNIROUTE_MCP_ENFORCE_SCOPES="true"
+export OMNIROUTE_MCP_SCOPES="read:health,read:combos,read:quota,read:usage,read:models,execute:completions,write:combos,write:budget,write:resilience"
+```
+
+### 2. Transport stdio (integrace IDE)
+
+Přidejte do konfigurace klienta MCP:
+
+**Claude Desktop** ( `claude_desktop_config.json` ):
+
+```json
+{
+  "mcpServers": {
+    "omniroute": {
+      "command": "node",
+      "args": ["path/to/9router/open-sse/mcp-server/server.ts"],
+      "env": {
+        "OMNIROUTE_BASE_URL": "http://localhost:20128",
+        "OMNIROUTE_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+**Cursor** ( `.cursor/mcp.json` ):
+
+```json
+{
+  "mcpServers": {
+    "omniroute": {
+      "command": "npx",
+      "args": ["tsx", "open-sse/mcp-server/server.ts"],
+      "env": {
+        "OMNIROUTE_BASE_URL": "http://localhost:20128"
+      }
+    }
+  }
+}
+```
+
+**VS Code** ( `.vscode/settings.json` ):
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "omniroute": {
+        "command": "npx",
+        "args": ["tsx", "open-sse/mcp-server/server.ts"],
+        "env": {
+          "OMNIROUTE_BASE_URL": "http://localhost:20128"
+        }
+      }
+    }
+  }
+}
+```
+
+### 3. Spuštění přes CLI
+
+```bash
+# Direct start (stdio)
+npx tsx open-sse/mcp-server/server.ts
+
+# Or via OmniRoute CLI
+omniroute --mcp
+```
+
+---
+
+## Referenční informace o nástrojích
+
+### Fáze 1: Základní nástroje (8)
+
+# | Nástroj | Rozsahy | Popis
+--- | --- | --- | ---
+1 | `omniroute_get_health` | `read:health` | Stav brány, dostupnost, paměť, jističe, limity rychlosti, statistiky mezipaměti
+2 | `omniroute_list_combos` | `read:combos` | Vypsat všechny kombinace (modelové řetězce) se strategiemi a volitelnými metrikami
+3 | `omniroute_get_combo_metrics` | `read:combos` | Metriky výkonu pro konkrétní kombinaci
+4 | `omniroute_switch_combo` | `write:combos` | Aktivace nebo deaktivace komba pro směrování
+5 | `omniroute_check_quota` | `read:quota` | Zbývající kvóta API na poskytovatele se stavem tokenu
+6 | `omniroute_route_request` | `execute:completions` | Odeslat dokončení chatu pomocí inteligentního směrování
+7 | `omniroute_cost_report` | `read:usage` | Zpráva o nákladech podle období (relace/den/týden/měsíc) s rozpisem podle poskytovatele
+8 | `omniroute_list_models_catalog` | `read:models` | Seznam všech dostupných modelů od různých poskytovatelů s funkcemi a cenami
+
+### Fáze 2: Pokročilé nástroje (8)
+
+# | Nástroj | Rozsahy | Popis
+--- | --- | --- | ---
+9 | `omniroute_simulate_route` | `read:health` , `read:combos` | Simulace trasy na dryru zobrazující záložní strom a odhadované náklady
+10 | `omniroute_set_budget_guard` | `write:budget` | Nastavit rozpočet relace s akcí při překročení: `degrade` , `block` nebo `alert`
+11 | `omniroute_set_resilience_profile` | `write:resilience` | Použijte profil odolnosti: `aggressive` , `balanced` nebo `conservative`
+12 | `omniroute_test_combo` | `execute:completions` , `read:combos` | Otestujte každého poskytovatele v kombinaci se skutečným výzvou a nahlaste latenci/náklady
+13 | `omniroute_get_provider_metrics` | `read:health` | Metriky pro jednotlivé poskytovatele s percentily latence (p50/p95/p99), jistič
+14 | `omniroute_best_combo_for_task` | `read:combos` , `read:health` | Doporučení kombinací podle typu úkolu s využitím umělé inteligence s omezeními rozpočtu/latence
+15 | `omniroute_explain_route` | `read:health` , `read:usage` | Vysvětlete, proč byl požadavek směrován k poskytovateli (faktory hodnocení, záložní metody)
+16 | `omniroute_get_session_snapshot` | `read:usage` | Snímek celého relace: náklady, tokeny, top modely, chyby, stav rozpočtu
+
+---
+
+## Příklady klientů
+
+### Python — Kompletní pracovní postup agenta
+
+```python
+"""
+OmniRoute MCP Client — Python example using the mcp SDK.
+Install: pip install mcp
+"""
+import asyncio
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+async def main():
+    server = StdioServerParameters(
+        command="npx",
+        args=["tsx", "open-sse/mcp-server/server.ts"],
+        env={
+            "OMNIROUTE_BASE_URL": "http://localhost:20128",
+            "OMNIROUTE_API_KEY": "your-key",
+        },
+    )
+
+    async with stdio_client(server) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            # 1. Check gateway health
+            health = await session.call_tool("omniroute_get_health", {})
+            print("Health:", health.content[0].text)
+
+            # 2. List available combos with metrics
+            combos = await session.call_tool("omniroute_list_combos", {
+                "includeMetrics": True
+            })
+            print("Combos:", combos.content[0].text)
+
+            # 3. Find the best combo for a coding task
+            best = await session.call_tool("omniroute_best_combo_for_task", {
+                "taskType": "coding",
+                "budgetConstraint": 0.50,
+                "latencyConstraint": 5000,
+            })
+            print("Best combo:", best.content[0].text)
+
+            # 4. Set a session budget guard
+            budget = await session.call_tool("omniroute_set_budget_guard", {
+                "maxCost": 1.00,
+                "action": "degrade",
+                "degradeToTier": "cheap",
+            })
+            print("Budget guard:", budget.content[0].text)
+
+            # 5. Route a request through intelligent pipeline
+            response = await session.call_tool("omniroute_route_request", {
+                "model": "claude-sonnet-4",
+                "messages": [
+                    {"role": "user", "content": "Write a Python hello world"}
+                ],
+                "role": "coding",
+            })
+            print("Response:", response.content[0].text)
+
+            # 6. Get the session snapshot
+            snapshot = await session.call_tool("omniroute_get_session_snapshot", {})
+            print("Session:", snapshot.content[0].text)
+
+asyncio.run(main())
+```
+
+### TypeScript — Programový agent
+
+```typescript
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+async function main() {
+  const transport = new StdioClientTransport({
+    command: "npx",
+    args: ["tsx", "open-sse/mcp-server/server.ts"],
+    env: {
+      OMNIROUTE_BASE_URL: "http://localhost:20128",
+      OMNIROUTE_API_KEY: "your-key",
+    },
+  });
+
+  const client = new Client({ name: "my-agent", version: "1.0.0" });
+  await client.connect(transport);
+
+  // Check quota before deciding which model to use
+  const quota = await client.callTool({
+    name: "omniroute_check_quota",
+    arguments: { provider: "claude" },
+  });
+  console.log("Claude quota:", quota.content);
+
+  // Simulate the route before actually calling
+  const simulation = await client.callTool({
+    name: "omniroute_simulate_route",
+    arguments: {
+      model: "claude-sonnet-4",
+      promptTokenEstimate: 2000,
+    },
+  });
+  console.log("Route simulation:", simulation.content);
+
+  // Send the actual request
+  const result = await client.callTool({
+    name: "omniroute_route_request",
+    arguments: {
+      model: "claude-sonnet-4",
+      messages: [{ role: "user", content: "Explain async/await" }],
+    },
+  });
+  console.log("Result:", result.content);
+
+  // Cost report
+  const costs = await client.callTool({
+    name: "omniroute_cost_report",
+    arguments: { period: "session" },
+  });
+  console.log("Costs:", costs.content);
+
+  await client.close();
+}
+
+main();
+```
+
+### Go — HTTP klient
+
+```go
+package main
+
+import (
+    "bytes"
+    "encoding/json"
+    "fmt"
+    "io"
+    "net/http"
+)
+
+// Simplified direct-API approach (bypass MCP, hit OmniRoute APIs directly)
+// Useful if you don't need MCP protocol framing.
+
+func callTool(baseURL, tool string, args map[string]any) (string, error) {
+    // MCP tools map to OmniRoute APIs:
+    endpoints := map[string]string{
+        "health": "/api/monitoring/health",
+        "combos": "/api/combos",
+        "quota":  "/api/usage/quota",
+        "models": "/v1/models",
+    }
+
+    url := baseURL + endpoints[tool]
+    resp, err := http.Get(url)
+    if err != nil {
+        return "", err
+    }
+    defer resp.Body.Close()
+    body, _ := io.ReadAll(resp.Body)
+    return string(body), nil
+}
+
+func routeRequest(baseURL, model, prompt string) (string, error) {
+    payload := map[string]any{
+        "model": model,
+        "messages": []map[string]string{
+            {"role": "user", "content": prompt},
+        },
+        "stream": false,
+    }
+    data, _ := json.Marshal(payload)
+
+    resp, err := http.Post(
+        baseURL+"/v1/chat/completions",
+        "application/json",
+        bytes.NewReader(data),
+    )
+    if err != nil {
+        return "", err
+    }
+    defer resp.Body.Close()
+    body, _ := io.ReadAll(resp.Body)
+    return string(body), nil
+}
+
+func main() {
+    base := "http://localhost:20128"
+
+    health, _ := callTool(base, "health", nil)
+    fmt.Println("Health:", health)
+
+    result, _ := routeRequest(base, "auto", "Hello from Go!")
+    fmt.Println("Result:", result)
+}
+```
+
+---
+
+## Případy použití
+
+### 🔄 Případ použití 1: Agent pro automatické ozdravování
+
+Agent, který monitoruje stav OmniRoute a automaticky přepíná kombinace, když se stav poskytovatelů zhorší.
+
+```python
+async def auto_healing_loop(session):
+    """Monitor health and react to provider issues."""
+    while True:
+        # Check health
+        health = await session.call_tool("omniroute_get_health", {})
+        data = json.loads(health.content[0].text)
+
+        # Find providers with open circuit breakers
+        broken = [
+            cb for cb in data["circuitBreakers"]
+            if cb["state"] == "OPEN"
+        ]
+
+        if broken:
+            # Switch to a different resilience profile
+            await session.call_tool("omniroute_set_resilience_profile", {
+                "profile": "conservative"
+            })
+
+            # Find best alternative combo
+            best = await session.call_tool("omniroute_best_combo_for_task", {
+                "taskType": "coding"
+            })
+            best_data = json.loads(best.content[0].text)
+            combo_id = best_data["recommendedCombo"]["id"]
+
+            # Activate it
+            await session.call_tool("omniroute_switch_combo", {
+                "comboId": combo_id, "active": True
+            })
+            print(f"⚠️ Auto-healed: switched to {combo_id}")
+
+        await asyncio.sleep(30)  # Check every 30 seconds
+```
+
+### 💰 Případ užití 2: Programovací agent s ohledem na rozpočet
+
+Agent, který sleduje náklady v reálném čase a při blížícím se vyčerpání rozpočtu přechází na levnější modely.
+
+```python
+async def budget_aware_coding(session, task: str, max_budget: float):
+    """Complete a coding task within a budget."""
+    # Set budget guard
+    await session.call_tool("omniroute_set_budget_guard", {
+        "maxCost": max_budget,
+        "action": "degrade",
+        "degradeToTier": "cheap",
+    })
+
+    # Simulate first to estimate cost
+    sim = await session.call_tool("omniroute_simulate_route", {
+        "model": "claude-sonnet-4",
+        "promptTokenEstimate": len(task.split()) * 2,
+    })
+    sim_data = json.loads(sim.content[0].text)
+    estimated_cost = sim_data["fallbackTree"]["bestCaseCost"]
+    print(f"Estimated cost: ${estimated_cost:.4f}")
+
+    # Send request
+    result = await session.call_tool("omniroute_route_request", {
+        "model": "claude-sonnet-4",
+        "messages": [{"role": "user", "content": task}],
+        "role": "coding",
+    })
+
+    # Check remaining budget
+    snapshot = await session.call_tool("omniroute_get_session_snapshot", {})
+    snap_data = json.loads(snapshot.content[0].text)
+    print(f"Session cost: ${snap_data['costTotal']:.4f}")
+    if snap_data.get("budgetGuard"):
+        print(f"Budget remaining: ${snap_data['budgetGuard']['remaining']:.4f}")
+
+    return json.loads(result.content[0].text)["response"]["content"]
+```
+
+### 🧪 Případ použití 3: Kombinovaný benchmarkingový agent
+
+Agent, který pravidelně porovnává všechna komba a hlásí nejrychlejší/nejlevnější.
+
+```python
+async def benchmark_combos(session):
+    """Benchmark all enabled combos and rank them."""
+    combos = await session.call_tool("omniroute_list_combos", {
+        "includeMetrics": True,
+    })
+    combo_list = json.loads(combos.content[0].text)["combos"]
+
+    results = []
+    for combo in combo_list:
+        if not combo["enabled"]:
+            continue
+
+        test = await session.call_tool("omniroute_test_combo", {
+            "comboId": combo["id"],
+            "testPrompt": "Return the number 42.",
+        })
+        test_data = json.loads(test.content[0].text)
+        results.append({
+            "combo": combo["name"],
+            "fastest": test_data["summary"]["fastestProvider"],
+            "cheapest": test_data["summary"]["cheapestProvider"],
+            "success_rate": f'{test_data["summary"]["successful"]}/{test_data["summary"]["totalProviders"]}',
+        })
+
+    print("📊 Combo Benchmark Results:")
+    for r in results:
+        print(f"  {r['combo']}: fastest={r['fastest']}, cheapest={r['cheapest']}, success={r['success_rate']}")
+```
+
+### 🔍 Případ použití 4: Agent pro ladění po smrti
+
+Agent, který vysvětluje, proč byl požadavek směrován ke konkrétnímu poskytovateli.
+
+```typescript
+async function debugRouting(client: Client, requestId: string) {
+  // Explain the routing decision
+  const explanation = await client.callTool({
+    name: "omniroute_explain_route",
+    arguments: { requestId },
+  });
+  const data = JSON.parse(explanation.content[0].text);
+
+  console.log(`Request ${requestId}:`);
+  console.log(`  Provider: ${data.decision.providerSelected}`);
+  console.log(`  Model: ${data.decision.modelUsed}`);
+  console.log(`  Score: ${data.decision.score}`);
+  console.log(`  Factors:`);
+  for (const factor of data.decision.factors) {
+    console.log(`    ${factor.name}: ${factor.value} (weight: ${factor.weight})`);
+  }
+  if (data.decision.fallbacksTriggered.length > 0) {
+    console.log(`  Fallbacks triggered:`);
+    for (const fb of data.decision.fallbacksTriggered) {
+      console.log(`    ${fb.provider}: ${fb.reason}`);
+    }
+  }
+}
+```
+
+### 📋 Případ použití 5: Agent pro vyhledávání modelů
+
+Agent, který vyhledává nejlevnější modely pro danou funkci.
+
+```python
+async def find_cheapest_models(session, capability="chat"):
+    """Find the cheapest available models for a capability."""
+    catalog = await session.call_tool("omniroute_list_models_catalog", {
+        "capability": capability,
+    })
+    models = json.loads(catalog.content[0].text)["models"]
+
+    # Filter available models with pricing
+    priced = [
+        m for m in models
+        if m["status"] == "available" and m.get("pricing")
+    ]
+    priced.sort(key=lambda m: m["pricing"]["inputPerMillion"] or float("inf"))
+
+    print(f"💡 Cheapest {capability} models:")
+    for m in priced[:5]:
+        input_cost = m["pricing"]["inputPerMillion"] or 0
+        output_cost = m["pricing"]["outputPerMillion"] or 0
+        print(f"  {m['id']} ({m['provider']}): ${input_cost}/M in, ${output_cost}/M out")
+```
+
+---
+
+## Zabezpečení a vynucování rozsahu
+
+Server MCP podporuje **detailní vynucování rozsahu** pro prostředí s více klienty:
+
+Rozsah | Nástroje
+--- | ---
+`read:health` | `get_health` , `simulate_route` , `get_provider_metrics` , `best_combo_for_task` , `explain_route`
+`read:combos` | `list_combos` , `get_combo_metrics` , `simulate_route` , `best_combo_for_task` , `test_combo`
+`read:quota` | `check_quota`
+`read:usage` | `cost_report` , `explain_route` , `get_session_snapshot`
+`read:models` | `list_models_catalog`
+`write:combos` | `switch_combo`
+`write:budget` | `set_budget_guard`
+`write:resilience` | `set_resilience_profile`
+`execute:completions` | `route_request` , `test_combo`
+
+**Rozsahy zástupných znaků:** Použijte `read:*` pro udělení všech rozsahů pro čtení nebo `*` pro plný přístup.
+
+---
+
+## Protokolování auditu
+
+Každé volání nástroje je zaznamenáno do tabulky SQLite `mcp_tool_audit` :
+
+- **Vstup:** SHA-256 hash (nikdy neukládá nezpracované výzvy)
+- **Výstup:** Zkráceno na 200 znaků
+- **Metadata:** Název nástroje, doba trvání, úspěch/chyba, ID klíče API
+
+Přístup k auditním datům prostřednictvím:
+
+```typescript
+import { getRecentAuditEntries, getAuditStats } from "./audit";
+
+const entries = await getRecentAuditEntries(50);
+const stats = await getAuditStats();
+// stats: { totalCalls, successRate, avgDurationMs, topTools }
+```
+
+---
+
+## Struktura souboru
+
+```
+mcp-server/
+├── server.ts              # MCP server setup, essential tool handlers, entry point
+├── index.ts               # Barrel export
+├── audit.ts               # SQLite audit logger (SHA-256 input hashing)
+├── scopeEnforcement.ts    # Fine-grained scope enforcement
+├── schemas/
+│   ├── tools.ts           # Zod schemas for all 16 tools (input/output/scopes)
+│   ├── a2a.ts             # A2A protocol types (Agent Card, Task, JSON-RPC)
+│   ├── audit.ts           # Audit & routing decision types + hash helpers
+│   └── index.ts           # Schema barrel export
+├── tools/
+│   └── advancedTools.ts   # Phase 2 tool handlers (8 advanced tools)
+└── __tests__/
+    ├── essentialTools.test.ts
+    ├── advancedTools.test.ts
+    └── a2aLifecycle.test.ts
+```
+
+---
+
+## Licence
+
+Součást [OmniRoute](https://github.com/diegosouzapw/OmniRoute) — licence MIT.

docs/i18n/da/FEATURES.md

@@ -1,20 +1,18 @@
-🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/FEATURES.md) · 🇪🇸 [es](../es/FEATURES.md) · 🇫🇷 [fr](../fr/FEATURES.md) · 🇩🇪 [de](../de/FEATURES.md) · 🇮🇹 [it](../it/FEATURES.md) · 🇷🇺 [ru](../ru/FEATURES.md) · 🇨🇳 [zh-CN](../zh-CN/FEATURES.md) · 🇯🇵 [ja](../ja/FEATURES.md) · 🇰🇷 [ko](../ko/FEATURES.md) · 🇸🇦 [ar](../ar/FEATURES.md) · 🇮🇳 [in](../in/FEATURES.md) · 🇹🇭 [th](../th/FEATURES.md) · 🇻🇳 [vi](../vi/FEATURES.md) · 🇮🇩 [id](../id/FEATURES.md) · 🇲🇾 [ms](../ms/FEATURES.md) · 🇳🇱 [nl](../nl/FEATURES.md) · 🇵🇱 [pl](../pl/FEATURES.md) · 🇸🇪 [sv](../sv/FEATURES.md) · 🇳🇴 [no](../no/FEATURES.md) · 🇩🇰 [da](../da/FEATURES.md) · 🇫🇮 [fi](../fi/FEATURES.md) · 🇵🇹 [pt](../pt/FEATURES.md) · 🇷🇴 [ro](../ro/FEATURES.md) · 🇭🇺 [hu](../hu/FEATURES.md) · 🇧🇬 [bg](../bg/FEATURES.md) · 🇸🇰 [sk](../sk/FEATURES.md) · 🇺🇦 [uk-UA](../uk-UA/FEATURES.md) · 🇮🇱 [he](../he/FEATURES.md) · 🇵🇭 [phi](../phi/FEATURES.md)
+# OmniRoute — Dashboard Features Gallery (Dansk)
+
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md)
+
+> 🇺🇸 [English](../../../docs/FEATURES.md)
 
 ---
 
-# 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.
 
 ---
 
 ## 🔌 Providers
 
-Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro).
-
-- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` (free "Light usage" tier); use `ollamacloud/<model>` prefix
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
 
 ![Providers Dashboard](screenshots/01-providers.png)
 
@@ -69,7 +67,7 @@ Customizable color themes for the entire dashboard. Choose from 7 preset colors
 Comprehensive settings panel with tabs:
 
 - **General** — System storage, backup management (export/import database)
-- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
 - **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
 - **Routing** — Model aliases, background task degradation
 - **Resilience** — Rate limit persistence, circuit breaker tuning
@@ -144,5 +142,6 @@ Key features:
 - Single-instance lock
 - Auto-update on restart
 - Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
 
 📖 See [`electron/README.md`](../electron/README.md) for full documentation.