Merge pull request #1033 from diegosouzapw/release/v3.5.3

chore(release): v3.5.3 — Core Resilience, i18n Sync & Preflight Enhancements

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

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

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

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

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

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

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

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

.agents/workflows/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,55 @@ 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
+> **🔴 SINGLE BRANCH RULE**: The `release/vX.Y.Z` branch is the **ONLY** development branch for the entire release cycle. ALL work — bug fixes, feature implementations, PR integrations, issue resolutions — MUST be committed directly on this branch. Never create separate `fix/`, `feat/`, or topic branches. When running `/resolve-issues`, `/implement-features`, or `/review-prs`, always work on the current release branch.
 
-### 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 0: Security Verification (MANDATORY)
+
+Before creating the release, you must ensure the codebase and supply chain are secure and free of known vulnerabilities.
+
+1. **Run Local Dependencies Audit:**
+
+   ```bash
+   npm audit
+   ```
+
+   _Fix any `high` or `critical` vulnerabilities identified._
+
+2. **Check GitHub CodeQL & Dependabot Alerts:**
+   Navigate to the repository's **Security** tab on GitHub, or use the project's `vulnerability-scanner` skill to analyze active alerts. Ensure all static analysis findings (e.g., prototype pollution, insecure randomness, ReDoS, shell injections) are addressed and logically committed on a target branch.
+
+---
+
+## Phase 1: Pre-Merge
+
+### 1. Create release branch
+
+```bash
+git checkout -b release/v2.x.y
+```
+
+### 2. Determine new version
 
 Check current version in `package.json` and increment the **patch** number only:
 
@@ -27,12 +66,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 +95,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,45 +108,172 @@ Keep an empty `## [Unreleased]` section above it.
 ## [2.x.y] — YYYY-MM-DD
 ```
 
-### 4. Update openapi.yaml version
+### 5. Update openapi.yaml version ⚠️ MANDATORY
+
+> **CI will fail** if `docs/openapi.yaml` version ≠ `package.json` version (`check:docs-sync` enforces this).
+
+// turbo
 
 ```bash
-sed -i 's/version: OLD/version: NEW/' docs/openapi.yaml
+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 tag -a v2.x.y -m "Release v2.x.y"
+git push origin release/v2.x.y
 ```
 
-### 6. Push to GitHub
+### 9. Open PR to main
 
 ```bash
-git push origin main --tags
+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."
 ```
 
-### 7. Create GitHub release
+### 10. 🛑 STOP — Notify User & Await PR Confirmation
+
+**This is a mandatory stop point.** Use `notify_user` with `BlockedOnUser: true`:
+
+Inform the user:
+
+- PR URL
+- Summary of changes
+- Test results
+- List of files changed
+
+**DO NOT proceed to Phase 2 until the user confirms the PR looks good and merges it.**
+
+---
+
+## Phase 2: Post-Merge (only after user confirms)
+
+> Run these steps only AFTER the user has merged the PR.
+
+### 11. Create Git Tag and GitHub Release (MANDATORY)
+
+// turbo
 
 ```bash
-gh release create v2.x.y --title "v2.x.y — summary" --notes "..."
+git checkout main
+git pull origin main
+VERSION=$(node -p "require('./package.json').version")
+git tag -a "v$VERSION" -m "Release v$VERSION"
+git push origin --tags
+gh release create "v$VERSION" --title "v$VERSION" --notes "OmniRoute v$VERSION Release" --target main
 ```
 
-### 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 && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
+
+# Deploy to LOCAL VPS (192.168.0.15)
+scp omniroute-*.tgz root@192.168.0.15:/tmp/
+ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
+
+# Deploy to AKAMAI VPS (69.164.221.35)
+scp omniroute-*.tgz root@69.164.221.35:/tmp/
+ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Akamai done'"
+
+# Verify both
+curl -s -o /dev/null -w "LOCAL:  HTTP %{http_code}\n" http://192.168.0.15:20128/
+curl -s -o /dev/null -w "AKAMAI: HTTP %{http_code}\n" http://69.164.221.35:20128/
+```
+
+### 16. Clean up release branch
+
+```bash
+git branch -d release/v2.x.y
+```
+
+---
+
 ## Notes
 
 - Always run `/update-docs` BEFORE this workflow (ensures CHANGELOG and README are current)
 - The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`
 - After npm publish, verify with `npm info omniroute version`
 - Lock file sync errors are caused by skipping `npm install` after version bump
+- Use `gh auth switch -u diegosouzapw` if git push fails with wrong account
+
+## Known CI Pitfalls
+
+| CI failure                                                                | Cause                                                    | Fix                                                                    |
+| ------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `[docs-sync] FAIL - OpenAPI version differs from package.json`            | Skipped step 5 — `docs/openapi.yaml` version not updated | Run step 5 (`sed -i ...`) and commit                                   |
+| `[docs-sync] FAIL - CHANGELOG.md first section must be "## [Unreleased]"` | `## [Unreleased]` missing or not at top of CHANGELOG     | Add `## [Unreleased]\n\n---\n` before the first versioned `## [x.y.z]` |
+| Electron Linux `.deb` build fails (`FpmTarget` error)                     | `fpm` Ruby gem not installed on `ubuntu-latest` runner   | Already fixed in `electron-release.yml` (`gem install fpm` step)       |
+| Docker Hub `502 error writing layer blob`                                 | Transient Docker Hub network error during ARM64 push     | Re-run the Docker publish workflow; no code change needed              |

.agents/workflows/implement-features.md

@@ -6,7 +6,9 @@ description: Analyze open feature request issues, implement viable ones on dedic
 
 ## Overview
 
-Fetches open feature request issues, analyzes each against the current codebase, implements viable ones on dedicated branches, and responds to authors with results. Does NOT merge to main — leaves branches for author validation.
+Fetches open feature request issues, analyzes each against the current codebase, implements viable ones **on the current release branch** (`release/vX.Y.Z`), and responds to authors with results. Does NOT merge to main — the release branch is later merged via PR.
+
+> **BRANCH RULE**: All work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `feat/` branches. If no release branch exists yet, create one first using `/generate-release` Phase 1 steps 1–5.
 
 ## Steps
 
@@ -16,15 +18,48 @@ Fetches open feature request issues, analyzes each against the current codebase,
 
 - Run: `git -C <project_root> remote get-url origin` to extract owner/repo
 
-### 2. Fetch Open Feature Request Issues
+### 2. Ensure Release Branch Exists
 
 // turbo
 
-- Run: `gh issue list --repo <owner>/<repo> --state open --limit 50 --json number,title,labels,body,comments,createdAt,author`
-- Filter for issues that are feature requests (label `enhancement`/`feature`, or body describes new functionality, or previously classified as feature request)
-- Sort by oldest first
+Before doing any work, ensure you are on the current release branch:
 
-### 3. Analyze Each Feature Request
+```bash
+# Check current branch
+git branch --show-current
+
+# If on main, determine next version and create the release branch
+VERSION=$(node -p "require('./package.json').version")
+NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
+git checkout -b release/v$NEXT
+npm version patch --no-git-tag-version
+npm install
+```
+
+If already on a `release/vX.Y.Z` branch, continue working there.
+
+### 3. Fetch Open Feature Request Issues
+
+// turbo-all
+
+**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues and their comments. You MUST use the two-step approach below to guarantee **all** feature requests and their full conversations are fetched.
+
+**Step 3a — Get Issue numbers only** (small output, never truncated):
+
+- Run: `gh issue list --repo <owner>/<repo> --state open --labels "enhancement" --limit 500 --json number --jq '.[].number'`
+- (Also run the same for `--labels "feature"` if they are separated, or filter all open issues if labels are not strictly used).
+- This outputs one issue number per line. Count them and confirm total.
+
+**Step 3b — Fetch full metadata & conversations for each Issue** (one call per issue):
+
+- For each issue number from step 3a, run:
+  `gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author`
+- Read not just the body, but **ALL comments (`comments` array)** completely to understand the full context, agreements, and restrictions discussed by the community.
+- You may batch these into parallel calls (up to 4 at a time).
+- Filter for issues that are feature requests (if not already filtered by label).
+- Sort by oldest first.
+
+### 4. Analyze Each Feature Request
 
 For each feature request issue, perform a **two-level analysis**:
 
@@ -46,21 +81,16 @@ Ask yourself:
 
 #### Level 2 — Implementation (only for VIABLE features)
 
+> **⚠️ ALL implementation happens on the release branch.**
+
 1. **Research** — Read all related source files to understand the current architecture
 2. **Design** — Plan the implementation, filling gaps in the original request
-3. **Create branch** — Name format: `feat/issue-<NUMBER>-<short-slug>`
-   ```bash
-   git checkout main
-   git pull origin main
-   git checkout -b feat/issue-<NUMBER>-<short-slug>
-   ```
-4. **Implement** — Build the complete solution following project patterns
-5. **Build** — Run `npm run build` to verify compilation
-6. **Commit** — Commit with: `feat: <description> (#<NUMBER>)`
-7. **Push** — Push the branch: `git push -u origin feat/issue-<NUMBER>-<short-slug>`
-8. **Return to main** — `git checkout main`
+3. **Implement** — Build the complete solution following project patterns, **on the release branch**
+4. **Build** — Run `npm run build` to verify compilation
+5. **Commit** — Commit with: `feat: <description> (#<NUMBER>)`
+6. **Continue** — Move to the next feature (do not switch branches)
 
-### 4. Respond to Authors
+### 5. Respond to Authors
 
 #### For VIABLE (implemented) features:
 
@@ -70,9 +100,9 @@ Post a comment on the issue:
 ````markdown
 ## ✅ Feature Implemented!
 
-Hi @<author>! We've analyzed your request and implemented it on a dedicated branch.
+Hi @<author>! We've analyzed your request and implemented it.
 
-**Branch:** `feat/issue-<NUMBER>-<short-slug>`
+**Branch:** `release/vX.Y.Z` (upcoming release)
 
 ### What was implemented:
 
@@ -82,31 +112,24 @@ Hi @<author>! We've analyzed your request and implemented it on a dedicated bran
 
 ```bash
 git fetch origin
-git checkout feat/issue-<NUMBER>-<short-slug>
+git checkout release/vX.Y.Z
 npm install && npm run dev
 ```
-````
 
 ### Next steps:
 
 1. **Test it** — Please verify it works as you expected
-2. **Want to improve it?** — You're welcome to contribute! Just:
-   ```bash
-   git checkout feat/issue-<NUMBER>-<short-slug>
-   # Make your improvements
-   git add -A && git commit -m "improve: <your changes>"
-   git push origin feat/issue-<NUMBER>-<short-slug>
-   ```
-   Then open a Pull Request from your branch to `main` 🎉
+2. **Want to improve it?** — Feel free to open a follow-up PR targeting `release/vX.Y.Z`
 3. **Not quite right?** — Let us know in this issue what needs to change
 
-Looking forward to your feedback! 🚀
-
-```
+This will be included in the next release. Looking forward to your feedback! 🚀
+````
 
 #### For NEEDS MORE INFO:
+
 // turbo
 Post a comment asking for specific missing details needed to implement, e.g.:
+
 - "Could you describe the exact behavior when X happens?"
 - "Which API endpoints should be affected?"
 - "Should this apply to all providers or only specific ones?"
@@ -114,18 +137,28 @@ Post a comment asking for specific missing details needed to implement, e.g.:
 Add the context of WHY you need each piece of information.
 
 #### For NOT VIABLE:
+
 // turbo
 Post a polite comment explaining why the feature doesn't fit at this time:
+
 - If the idea is decent but timing is wrong: "This is an interesting idea, but it doesn't align with our current priorities. Feel free to open a new issue with more details if you'd like us to reconsider."
 - If fundamentally flawed: Explain the technical or architectural reasons why it won't work, suggest alternatives if possible.
 - Close the issue after posting the comment.
 
-### 5. Summary Report
+### 6. Finalize & Push
+
+After implementing all viable features:
+
+1. **Update CHANGELOG.md** on the release branch with all new feature entries
+2. Push the release branch: `git push origin release/vX.Y.Z`
+3. Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)
+
+### 7. Summary Report
+
 Present a summary report to the user via `notify_user`:
 
-| Issue | Title | Verdict | Branch / Action |
-|---|---|---|---|
-| #N | Title | ✅ Implemented | `feat/issue-N-slug` |
-| #N | Title | ❓ Needs Info | Comment posted |
-| #N | Title | ❌ Not Viable | Closed with explanation |
-```
+| Issue | Title | Verdict        | Action                  |
+| ----- | ----- | -------------- | ----------------------- |
+| #N    | Title | ✅ Implemented | Committed on release/vX |
+| #N    | Title | ❓ Needs Info  | Comment posted          |
+| #N    | Title | ❌ Not Viable  | Closed with explanation |

.agents/workflows/resolve-issues.md

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

.agents/workflows/review-discussions.md

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

.agents/workflows/review-prs.md

@@ -6,7 +6,9 @@ description: Analyze open Pull Requests from the project's GitHub repository, ge
 
 ## Overview
 
-This workflow fetches all open PRs from the project's GitHub repository, performs a critical analysis of each one, generates a detailed report, and waits for user approval before proceeding with implementation. **All improvements are committed on top of the PR branch** and the user must verify before merge.
+This workflow fetches all open PRs from the project's GitHub repository, performs a critical analysis of each one, generates a detailed report, and waits for user approval before proceeding with implementation. **All improvements are committed on the current release branch** (`release/vX.Y.Z`).
+
+> **BRANCH RULE**: All work MUST happen on the current `release/vX.Y.Z` branch. Never create separate feature or fix branches. If no release branch exists yet, create one first using `/generate-release` Phase 1 steps 1–5.
 
 ## Steps
 
@@ -16,51 +18,94 @@ This workflow fetches all open PRs from the project's GitHub repository, perform
   // turbo
 - Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
 
-### 2. Fetch Open Pull Requests
+### 2. Ensure Release Branch Exists
+
+// turbo
+
+Before doing any work, ensure you are on the current release branch:
+
+```bash
+# Check current branch
+git branch --show-current
+
+# If on main, determine next version and create the release branch
+VERSION=$(node -p "require('./package.json').version")
+# Bump patch: e.g. 3.3.11 → 3.3.12
+NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
+git checkout -b release/v$NEXT
+npm version patch --no-git-tag-version
+npm install
+```
+
+If already on a `release/vX.Y.Z` branch, continue working there.
+
+### 3. Fetch Open Pull Requests
+
+// turbo-all
+
+**⚠️ CRITICAL**: The JSON output of `gh pr list` can be truncated by the tool, silently hiding PRs. You MUST use the two-step approach below to guarantee **all** PRs are fetched.
+
+**Step 3a — Get PR numbers only** (small output, never truncated):
+
+- Run: `gh pr list --repo <owner>/<repo> --state open --limit 500 --json number --jq '.[].number'`
+- This outputs one PR number per line. Count them and confirm total.
+
+**Step 3b — Fetch full metadata for each PR** (one call per PR):
+
+- For each PR number from step 3a, run:
+  `gh pr view <NUMBER> --repo <owner>/<repo> --json number,title,author,headRefName,body,createdAt,additions,deletions,files`
+- You may batch these into parallel calls (up to 4 at a time).
+
+**Step 3c — Fetch diffs for each PR** (one call per PR, saved to /tmp):
+
+- For each PR number, run:
+  `gh pr diff <NUMBER> --repo <owner>/<repo> > /tmp/pr<NUMBER>.diff`
+- Then read each diff file with `view_file`.
 
-- Navigate to `https://github.com/<owner>/<repo>/pulls` and scrape all open PRs
 - For each open PR, collect:
   - PR number, title, author, branch, number of commits, date
   - PR description/body
   - Files changed (diff)
   - Existing review comments (from bots or humans)
 
-### 3. Analyze Each PR — For each open PR, perform the following analysis:
+**Verification**: Confirm the count of PRs analyzed matches the count from step 3a before proceeding.
 
-#### 3a. Feature Assessment
+### 4. Analyze Each PR — For each open PR, perform the following analysis:
+
+#### 4a. Feature Assessment
 
 - **Does it make sense?** Evaluate if the feature fills a real gap or solves a valid problem
 - **Alignment** — Check if it aligns with the project's architecture and roadmap
 - **Complexity** — Assess if the scope is reasonable or if it should be split
 
-#### 3b. Code Quality Review
+#### 4b. Code Quality Review
 
 - Check for code duplication
 - Evaluate error handling patterns (consistent with existing codebase?)
 - Check naming conventions and code style
 - Verify TypeScript types (any `any` usage, missing types?)
 
-#### 3c. Security Review
+#### 4c. Security Review
 
 - Check for missing authentication/authorization on new endpoints
 - Check for injection vulnerabilities (URL params, SQL, XSS)
 - Verify input validation on all user-controlled data
 - Check for hardcoded secrets or credentials
 
-#### 3d. Architecture Review
+#### 4d. Architecture Review
 
 - Does the change follow existing patterns?
 - Are there any breaking changes to public APIs?
 - Is the database schema affected? Migration needed?
 - Impact on performance (N+1 queries, missing indexes?)
 
-#### 3e. Test Coverage
+#### 4e. Test Coverage
 
 - Does the PR include tests?
 - Are edge cases covered?
 - Would existing tests break?
 
-#### 3f. Cross-Layer (Global) Analysis
+#### 4f. Cross-Layer (Global) Analysis
 
 Perform a **global impact assessment** to verify whether the PR changes are complete across all layers of the application:
 
@@ -75,7 +120,7 @@ Perform a **global impact assessment** to verify whether the PR changes are comp
 - **Cross-cutting concerns**: Check shared layers (types, DTOs, validation schemas, routes, middleware) for completeness
 - **Document gaps** — If missing layers are detected, list them as **IMPORTANT** issues in the report with concrete suggestions for what should be added
 
-### 4. Generate Report — Create a markdown report for each PR including:
+### 5. Generate Report — Create a markdown report for each PR including:
 
 - **PR Summary** — What it does, files affected, commit count
 - **Improvements/Benefits** — Numbered list with impact level (HIGH/MEDIUM/LOW)
@@ -84,62 +129,71 @@ Perform a **global impact assessment** to verify whether the PR changes are comp
 - **Verdict** — Ready to merge? With mandatory vs optional fixes
 - **Next Steps** — What will happen if approved
 
-### 5. Present to User
+### 6. Present to User
 
 - Show the report via `notify_user` with `BlockedOnUser: true`
 - Wait for user decision:
-  - **Approved** → Proceed to step 6
+  - **Approved** → Proceed to step 7
   - **Approved with changes** → Implement the fixes and corrections before merging
   - **Rejected** → Close the PR or leave a review comment
 
-### 6. Implementation (if approved)
+### 7. Pre-Merge Fixes & CI Green-Lighting (if approved)
 
-- Checkout the PR branch: `gh pr checkout <NUMBER>`
-- Implement any required fixes identified in the analysis
-- If the Cross-Layer Analysis (3f) identified missing frontend/backend counterparts, implement them
-- **Commit improvements on top of the PR branch** with descriptive commit messages
-- Run the project's test suite to verify nothing breaks
+> **⚠️ Fixes should be pushed back to the PR branch before merging.** We want the PR itself to be green and fully valid before it integrates.
+
+- **Sync latest fixes:** Merge `main` or the current `release` branch into the PR branch so the PR inherits any latest CI or integration test fixes (preventing false-positive failures).
+- **Implement improvements:** Apply the required fixes identified in the analysis directly on the PR branch (e.g., adding missing API routes, fixing SSRF, applying comments from other agents).
+- **Pushing changes to PR branches:**
+
+  ```bash
+  # Checkout the PR locally
+  gh pr checkout <NUMBER>
+
+  # Apply fixes, commit your changes
+  git commit -m "chore: apply review suggestions and missing layers"
+
+  # Attempt to push directly to the PR branch
+  git push
+  ```
+
+- **Fallback (For external forks without maintainer edit access):**
+  If `git push` fails because the PR comes from an external fork without write access, you MUST:
+  1. Create a new branch ending in `-fix` (e.g., `checkout -b fix-pr-<NUMBER>`).
+  2. Push your branch to the main repo (`git push origin fix-pr-<NUMBER>`).
+  3. Create a Pull Request targeting the contributor's repository and branch (use `gh pr create --repo <contributor-repo> --base <contributor-branch> --head diegosouzapw:fix-pr-<NUMBER>`).
+  4. Once they accept our PR into their branch, their original PR to our `main` will automatically update and become green.
+
+- Run the project's test suite locally to verify nothing breaks:
   // turbo
 - Run: `npm test` or equivalent test command
-- Build the project to verify compilation
-  // turbo
-- Run: `npm run build` or equivalent build command
-- Push the updated branch: `git push origin <branch-name>`
 
-### 7. 🛑 WAIT — Notify User & Await PR Verification
+### 8. Merge & Integrate
 
-**This is a mandatory stop point.** Use `notify_user` with `BlockedOnUser: true`:
+- Once the PR is green (you can check with `gh pr status`), proceed to merge the PR into the current release branch (`release/vX.Y.Z`).
 
-- Inform the user that the PR has been **improved and pushed**, and is **awaiting their verification**
-- Include:
-  - PR number and URL
-  - Summary of improvements/fixes applied
-  - Build/test status
-  - List of files changed
-- **DO NOT merge, generate releases, or deploy until the user confirms**
-
-Wait for the user to respond:
-
-- **User confirms** → Proceed to step 8
-- **User requests more changes** → Apply changes, push to the same branch, notify again
-- **User rejects** → Leave a review comment and stop
-
-### 8. Thank the Contributor
+  ```bash
+  gh pr merge <NUMBER> --repo <owner>/<repo>
+  ```
 
 - Post a **thank-you comment** on the PR via the GitHub API
 - The message should:
   - Thank the author by name/username for their contribution
   - Briefly mention what the PR accomplishes and any improvements applied
+  - Note it will be included in the upcoming release
   - Be friendly, professional, and encouraging
-- Example: _"Thanks @author for this great contribution! 🎉 The [feature/fix] is now merged and will be part of the next release. We appreciate your effort!"_
+- Example: _"Thanks @author for this great contribution! 🎉 The [feature/fix] has been integrated into the release/vX.Y.Z branch and will be part of the next release. We appreciate your effort!"_
 
-### 9. Merge & Release (only after user confirms PR)
+### 9. Close the Original PR
 
-After the user confirms the PR:
+- Close the original PR with a comment explaining it was integrated into the release branch:
+  ```bash
+  gh pr close <NUMBER> --repo <owner>/<repo> --comment "Integrated into release/vX.Y.Z. Will be released as part of v3.X.Y. Thank you!"
+  ```
 
-1. **Merge** the PR into main (local merge with `--no-ff` or via `gh pr merge`)
-2. **Push** to main: `git push origin main`
-3. **Clean up** the feature branch: `git branch -d <branch-name>`
-4. **Update CHANGELOG.md** with the new feature/fix
-5. Run the `/generate-release` workflow (at `.agents/workflows/generate-release.md`) to bump version, tag, and publish
-6. Deploy to local VPS: `ssh root@192.168.0.15 "npm install -g omniroute@<VERSION> && pm2 restart omniroute"`
+### 10. Continue or Finalize
+
+After processing all approved PRs:
+
+- If more PRs remain, go back to step 7
+- When all PRs are processed, **update CHANGELOG.md** on the release branch with all new entries
+- Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)

.agents/workflows/update-docs.md

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

.agents/workflows/version-bump.md

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

.dockerignore

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

.env.example

@@ -18,9 +18,11 @@ STORAGE_DRIVER=sqlite
 # Generate with: openssl rand -hex 32
 STORAGE_ENCRYPTION_KEY=
 STORAGE_ENCRYPTION_KEY_VERSION=v1
-LOG_RETENTION_DAYS=90
+APP_LOG_RETENTION_DAYS=90
+CALL_LOG_RETENTION_DAYS=90
 SQLITE_MAX_SIZE_MB=2048
 SQLITE_CLEAN_LEGACY_FILES=true
+DISABLE_SQLITE_AUTO_BACKUP=false
 
 # Recommended runtime variables
 # Canonical/base port (keeps backward compatibility)
@@ -37,9 +39,10 @@ INSTANCE_NAME=omniroute
 
 # Recommended security and ops variables
 MACHINE_ID_SALT=endpoint-proxy-salt
-ENABLE_REQUEST_LOGS=false
 AUTH_COOKIE_SECURE=false
 REQUIRE_API_KEY=false
+ALLOW_API_KEY_REVEAL=false
+PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70
 
 # Input Sanitizer (FASE-01 — prompt injection & PII protection)
 # INPUT_SANITIZER_ENABLED=true
@@ -127,8 +130,8 @@ GEMINI_CLI_OAUTH_CLIENT_SECRET=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
 # CODEX_OAUTH_CLIENT_ID=
 # CODEX_OAUTH_CLIENT_SECRET=
 # QWEN_OAUTH_CLIENT_ID=
-# IFLOW_OAUTH_CLIENT_ID=
-IFLOW_OAUTH_CLIENT_SECRET=4Z3YjXycVsQvyGF1etiNlIBB4RsqSDtW
+# QODER_OAUTH_CLIENT_ID=
+QODER_OAUTH_CLIENT_SECRET=4Z3YjXycVsQvyGF1etiNlIBB4RsqSDtW
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Provider User-Agent Overrides (optional — customize per-provider UA headers)
@@ -141,11 +144,33 @@ CODEX_USER_AGENT=codex-cli/0.92.0 (Windows 10.0.26100; x64)
 GITHUB_USER_AGENT=GitHubCopilotChat/0.26.7
 ANTIGRAVITY_USER_AGENT=antigravity/1.104.0 darwin/arm64
 KIRO_USER_AGENT=AWS-SDK-JS/3.0.0 kiro-ide/1.0.0
-IFLOW_USER_AGENT=iFlow-Cli
-QWEN_USER_AGENT=google-api-nodejs-client/9.15.1
+QODER_USER_AGENT=Qoder-Cli
+QWEN_USER_AGENT=QwenCode/0.12.3 (linux; x64)
 CURSOR_USER_AGENT=connect-es/1.6.1
 GEMINI_CLI_USER_AGENT=google-api-nodejs-client/9.15.1
 
+# ─────────────────────────────────────────────────────────────────────────────
+# CLI Fingerprint Compatibility (optional — match native CLI binary signatures)
+# ─────────────────────────────────────────────────────────────────────────────
+# When enabled, OmniRoute reorders HTTP headers and JSON body fields to match
+# the exact signature of official CLI tools, reducing account flagging risk.
+# Your proxy IP is preserved — you get both stealth AND IP masking.
+#
+# Enable per-provider:
+# CLI_COMPAT_CODEX=1
+# CLI_COMPAT_CLAUDE=1
+# CLI_COMPAT_GITHUB=1
+# CLI_COMPAT_ANTIGRAVITY=1
+# CLI_COMPAT_KIRO=1
+# CLI_COMPAT_CURSOR=1
+# CLI_COMPAT_KIMI_CODING=1
+# CLI_COMPAT_KILOCODE=1
+# CLI_COMPAT_CLINE=1
+# CLI_COMPAT_QWEN=1
+#
+# Or enable for all providers at once:
+# CLI_COMPAT_ALL=1
+
 # API Key Providers (Phase 1 + Phase 4)
 # Add via Dashboard → Providers → Add API Key, or set here
 # DEEPSEEK_API_KEY=
@@ -164,19 +189,35 @@ GEMINI_CLI_USER_AGENT=google-api-nodejs-client/9.15.1
 # Provider keys above (openai, mistral, together, fireworks, nvidia) also work for embeddings
 
 # Timeout settings
-# FETCH_TIMEOUT_MS=120000
-# STREAM_IDLE_TIMEOUT_MS=60000
+# REQUEST_TIMEOUT_MS=600000
+# STREAM_IDLE_TIMEOUT_MS=600000
+# Advanced timeout overrides (optional)
+# FETCH_TIMEOUT_MS=600000
+# FETCH_HEADERS_TIMEOUT_MS=600000
+# FETCH_BODY_TIMEOUT_MS=600000
+# FETCH_CONNECT_TIMEOUT_MS=30000
+# FETCH_KEEPALIVE_TIMEOUT_MS=4000
+# TLS_CLIENT_TIMEOUT_MS=600000
+# API bridge timeout for /v1 proxy requests (default: 30000)
+# API_BRIDGE_PROXY_TIMEOUT_MS=600000
+# API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS=600000
+# API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS=60000
+# API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS=5000
+# API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS=0
 
 # CORS configuration (default: * allows all origins)
 # CORS_ORIGINS=*
 
 # Logging
-# LOG_LEVEL=info
-# LOG_FORMAT=text
-LOG_TO_FILE=true
-# LOG_FILE_PATH=logs/application/app.log
-# LOG_MAX_FILE_SIZE=50M
-# LOG_RETENTION_DAYS=7
+# APP_LOG_LEVEL=info
+# APP_LOG_FORMAT=text
+APP_LOG_TO_FILE=true
+# APP_LOG_FILE_PATH=logs/application/app.log
+# APP_LOG_MAX_FILE_SIZE=50M
+# APP_LOG_RETENTION_DAYS=7
+# APP_LOG_MAX_FILES=20
+# CALL_LOG_RETENTION_DAYS=7
+# CALL_LOG_MAX_ENTRIES=10000
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Memory Optimization (Low-RAM configurations)
@@ -195,6 +236,4 @@ LOG_TO_FILE=true
 # SEMANTIC_CACHE_TTL_MS=1800000
 
 # In-memory log buffers
-# PROXY_LOG_MAX_ENTRIES=200
-# CALL_LOGS_MAX=200
 # STREAM_HISTORY_MAX=50

.github/CODEOWNERS

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

.github/ISSUE_TEMPLATE/bug_report.yml

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

.github/ISSUE_TEMPLATE/config.yml

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

.github/ISSUE_TEMPLATE/feature_request.yml

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

.github/ISSUE_TEMPLATE/test_coverage_task.yml

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

.github/copilot-instructions.md

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

.github/pull_request_template.md

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

.github/workflows/ci.yml

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

.github/workflows/deploy-vps.yml

@@ -6,6 +6,9 @@ on:
     types: [completed]
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   deploy:
     if: >-

.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:
@@ -16,29 +26,42 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/v{0}', inputs.version) || '' }}
 
       - name: Set up QEMU (for multi-arch builds)
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Login to Docker Hub
-        uses: docker/login-action@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:
@@ -79,7 +81,7 @@ jobs:
           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/
@@ -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:
@@ -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 }}

.gitignore

@@ -5,6 +5,12 @@
 omnirouteCloud/
 omnirouteSite/
 
+# Root-level underscore-prefixed directories (private/draft — never commit)
+/_*/
+
+# Draft features documentation (internal only)
+docs/new-features/
+
 # dependencies
 node_modules/
 /.pnp
@@ -14,9 +20,12 @@ node_modules/
 !.yarn/plugins
 !.yarn/releases
 !.yarn/versions
+.data/
+.next-playwright/
 
 # testing
 coverage/
+coverage**
 
 # next.js
 .next/
@@ -50,11 +59,14 @@ next-env.d.ts
 
 # data and logs
 data/
+.data/
 logs/*
 
 # analysis directories (generated, not tracked)
 .analysis/
 antigravity-manager-analysis/
+.sisyphus/
+.plans/
 
 # docs (allow specific tracked files)
 docs/*
@@ -85,6 +97,9 @@ docs/*
 !docs/A2A-SERVER.md
 !docs/AUTO-COMBO.md
 !docs/MCP-SERVER.md
+!docs/CLI-TOOLS.md
+!docs/COVERAGE_PLAN.md
+
 
 # open-sse tests
 open-sse/test/*
@@ -108,6 +123,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/)
@@ -127,3 +143,21 @@ vscode-extension/
 *.sqlite-shm
 *.sqlite-wal
 *.sqlite-journal
+
+# Compiled npm-package build artifact (not source, should not be in git)
+/app
+
+# IDEA
+.idea/
+
+# Local OpenCode agent config
+.config/
+
+# Empty/dangling files
+typescript
+
+# Gemini Antigravity agent data
+.gemini/
+
+# Superpowers plans/specs (internal tooling, not project code)
+docs/superpowers/

.husky/pre-commit

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

.husky/pre-push

@@ -0,0 +1 @@
+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/
@@ -21,14 +26,19 @@ scripts/
 .github/
 .husky/
 .vscode/
+.agents/
 .env*
 eslint.config.mjs
 prettier.config.mjs
 postcss.config.mjs
 next.config.mjs
 tsconfig.json
+tsconfig.typecheck-core.json
+tsconfig.typecheck-noimplicit-core.json
 playwright.config.ts
+vitest.config.ts
 next-env.d.ts
+llm.txt
 
 # Docker
 docker-compose*.yml
@@ -36,9 +46,24 @@ Dockerfile
 .dockerignore
 
 # Misc
-restart.sh
 AGENTS.md
+bun.lock
 
 # Build artifacts (pre-built goes inside app/)
 .next/
 node_modules/
+
+# Ignore large binary files and other build directories
+*.tgz
+*.AppImage
+*.deb
+*.rpm
+electron/
+app/electron/
+app/vscode-extension/
+
+# Subprojects
+clipr/
+omnirouteCloud/
+omnirouteSite/
+vscode-extension/

.omc/project-memory.json

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

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

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

.playwright-mcp/console-2026-04-04T08-03-37-016Z.log

@@ -0,0 +1 @@
+[   32698ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ http://localhost:20130/dashboard/usage?_rsc=18t7j:0

.playwright-mcp/page-2026-04-04T08-03-38-145Z.yml

@@ -0,0 +1,158 @@
+- generic [active] [ref=e1]:
+    - link "Skip to content" [ref=e2] [cursor=pointer]:
+        - /url: "#main-content"
+    - generic [ref=e3]:
+        - complementary [ref=e5]:
+            - link "Skip to content" [ref=e6] [cursor=pointer]:
+                - /url: "#main-content"
+            - link "OmniRoute v3.5.0" [ref=e12] [cursor=pointer]:
+                - /url: /dashboard
+                - img [ref=e14]
+                - generic [ref=e26]:
+                    - heading "OmniRoute" [level=1] [ref=e27]
+                    - generic [ref=e28]: v3.5.0
+            - navigation "Main navigation" [ref=e29]:
+                - generic [ref=e30]:
+                    - link "home Home" [ref=e31] [cursor=pointer]:
+                        - /url: /dashboard
+                        - generic [ref=e32]: home
+                        - generic [ref=e33]: Home
+                    - link "api Endpoints" [ref=e34] [cursor=pointer]:
+                        - /url: /dashboard/endpoint
+                        - generic [ref=e35]: api
+                        - generic [ref=e36]: Endpoints
+                    - link "vpn_key API Manager" [ref=e37] [cursor=pointer]:
+                        - /url: /dashboard/api-manager
+                        - generic [ref=e38]: vpn_key
+                        - generic [ref=e39]: API Manager
+                    - link "dns Providers" [ref=e40] [cursor=pointer]:
+                        - /url: /dashboard/providers
+                        - generic [ref=e41]: dns
+                        - generic [ref=e42]: Providers
+                    - link "layers Combos" [ref=e43] [cursor=pointer]:
+                        - /url: /dashboard/combos
+                        - generic [ref=e44]: layers
+                        - generic [ref=e45]: Combos
+                    - link "auto_awesome Auto Combo" [ref=e46] [cursor=pointer]:
+                        - /url: /dashboard/auto-combo
+                        - generic [ref=e47]: auto_awesome
+                        - generic [ref=e48]: Auto Combo
+                    - link "account_balance_wallet Costs" [ref=e49] [cursor=pointer]:
+                        - /url: /dashboard/costs
+                        - generic [ref=e50]: account_balance_wallet
+                        - generic [ref=e51]: Costs
+                    - link "analytics Analytics" [ref=e52] [cursor=pointer]:
+                        - /url: /dashboard/analytics
+                        - generic [ref=e53]: analytics
+                        - generic [ref=e54]: Analytics
+                    - link "tune Limits & Quotas" [ref=e55] [cursor=pointer]:
+                        - /url: /dashboard/limits
+                        - generic [ref=e56]: tune
+                        - generic [ref=e57]: Limits & Quotas
+                    - link "cached Cache" [ref=e58] [cursor=pointer]:
+                        - /url: /dashboard/cache
+                        - generic [ref=e59]: cached
+                        - generic [ref=e60]: Cache
+                    - link "perm_media Media" [ref=e61] [cursor=pointer]:
+                        - /url: /dashboard/cache/media
+                        - generic [ref=e62]: perm_media
+                        - generic [ref=e63]: Media
+                - generic [ref=e64]:
+                    - paragraph [ref=e65]: CLI
+                    - link "terminal Tools" [ref=e66] [cursor=pointer]:
+                        - /url: /dashboard/cli-tools
+                        - generic [ref=e67]: terminal
+                        - generic [ref=e68]: Tools
+                    - link "smart_toy Agents" [ref=e69] [cursor=pointer]:
+                        - /url: /dashboard/agents
+                        - generic [ref=e70]: smart_toy
+                        - generic [ref=e71]: Agents
+                    - link "psychology Memory" [ref=e72] [cursor=pointer]:
+                        - /url: /dashboard/memory
+                        - generic [ref=e73]: psychology
+                        - generic [ref=e74]: Memory
+                    - link "auto_fix_high Skills" [ref=e75] [cursor=pointer]:
+                        - /url: /dashboard/skills
+                        - generic [ref=e76]: auto_fix_high
+                        - generic [ref=e77]: Skills
+                - generic [ref=e78]:
+                    - paragraph [ref=e79]: System
+                    - link "health_and_safety Health" [ref=e80] [cursor=pointer]:
+                        - /url: /dashboard/health
+                        - generic [ref=e81]: health_and_safety
+                        - generic [ref=e82]: Health
+                    - link "description Logs" [ref=e83] [cursor=pointer]:
+                        - /url: /dashboard/logs
+                        - generic [ref=e84]: description
+                        - generic [ref=e85]: Logs
+                    - link "history Audit Log" [ref=e86] [cursor=pointer]:
+                        - /url: /dashboard/audit
+                        - generic [ref=e87]: history
+                        - generic [ref=e88]: Audit Log
+                    - link "settings Settings" [ref=e89] [cursor=pointer]:
+                        - /url: /dashboard/settings
+                        - generic [ref=e90]: settings
+                        - generic [ref=e91]: Settings
+                - generic [ref=e92]:
+                    - paragraph [ref=e93]: Help
+                    - link "menu_book Docs" [ref=e94] [cursor=pointer]:
+                        - /url: /docs
+                        - generic [ref=e95]: menu_book
+                        - generic [ref=e96]: Docs
+                    - link "bug_report Issues" [ref=e97] [cursor=pointer]:
+                        - /url: https://github.com/diegosouzapw/OmniRoute/issues
+                        - generic [ref=e98]: bug_report
+                        - generic [ref=e99]: Issues
+            - generic [ref=e100]:
+                - button "restart_alt Restart" [ref=e101]:
+                    - generic: restart_alt
+                    - text: Restart
+                - button "power_settings_new Shutdown" [ref=e102]:
+                    - generic: power_settings_new
+                    - text: Shutdown
+        - main [ref=e103]:
+            - generic [ref=e104]:
+                - button "menu" [ref=e106]:
+                    - generic: menu
+                - generic [ref=e107]:
+                    - button "🇺🇸 EN expand_more" [ref=e109]:
+                        - generic [ref=e110]: 🇺🇸
+                        - generic [ref=e111]: EN
+                        - generic: expand_more
+                    - button "Switch to dark mode" [ref=e112]:
+                        - generic: dark_mode
+                    - button "logout" [ref=e113]:
+                        - generic: logout
+            - generic [ref=e115]:
+                - navigation "Breadcrumb" [ref=e116]:
+                    - link "Dashboard" [ref=e118] [cursor=pointer]:
+                        - /url: /dashboard
+                    - generic [ref=e119]:
+                        - generic [ref=e120]: ›
+                        - generic [ref=e121]: Onboarding
+                - generic [ref=e123]:
+                    - generic [ref=e124]:
+                        - generic [ref=e126]: "1"
+                        - generic [ref=e129]: "2"
+                        - generic [ref=e132]: "3"
+                        - generic [ref=e135]: "4"
+                        - generic [ref=e138]: "5"
+                    - generic [ref=e139]:
+                        - generic [ref=e140]:
+                            - generic [ref=e141]: waving_hand
+                            - heading "Welcome" [level=2] [ref=e142]
+                        - generic [ref=e144]:
+                            - paragraph [ref=e145]: OmniRoute is your local AI API proxy. It routes requests to multiple AI providers with load balancing, failover, and usage tracking.
+                            - generic [ref=e146]:
+                                - generic [ref=e147]:
+                                    - generic [ref=e148]: swap_horiz
+                                    - text: Multi-Provider
+                                - generic [ref=e149]:
+                                    - generic [ref=e150]: monitoring
+                                    - text: Usage Tracking
+                                - generic [ref=e151]:
+                                    - generic [ref=e152]: shield
+                                    - text: API Key Mgmt
+                        - button "Get Started" [ref=e155] [cursor=pointer]
+                    - button "Skip wizard entirely" [ref=e157] [cursor=pointer]
+    - alert [ref=e158]

.playwright-mcp/page-2026-04-04T08-04-46-313Z.yml

@@ -0,0 +1,132 @@
+- generic [active] [ref=e1]:
+    - link "Skip to content" [ref=e2] [cursor=pointer]:
+        - /url: "#main-content"
+    - generic [ref=e3]:
+        - complementary [ref=e5]:
+            - link "Skip to content" [ref=e6] [cursor=pointer]:
+                - /url: "#main-content"
+            - link "OmniRoute v3.5.0" [ref=e12] [cursor=pointer]:
+                - /url: /dashboard
+                - img [ref=e14]
+                - generic [ref=e26]:
+                    - heading "OmniRoute" [level=1] [ref=e27]
+                    - generic [ref=e28]: v3.5.0
+            - navigation "Main navigation" [ref=e29]:
+                - generic [ref=e30]:
+                    - link "home Home" [ref=e31] [cursor=pointer]:
+                        - /url: /dashboard
+                        - generic [ref=e32]: home
+                        - generic [ref=e33]: Home
+                    - link "api Endpoints" [ref=e34] [cursor=pointer]:
+                        - /url: /dashboard/endpoint
+                        - generic [ref=e35]: api
+                        - generic [ref=e36]: Endpoints
+                    - link "vpn_key API Manager" [ref=e37] [cursor=pointer]:
+                        - /url: /dashboard/api-manager
+                        - generic [ref=e38]: vpn_key
+                        - generic [ref=e39]: API Manager
+                    - link "dns Providers" [ref=e40] [cursor=pointer]:
+                        - /url: /dashboard/providers
+                        - generic [ref=e41]: dns
+                        - generic [ref=e42]: Providers
+                    - link "layers Combos" [ref=e43] [cursor=pointer]:
+                        - /url: /dashboard/combos
+                        - generic [ref=e44]: layers
+                        - generic [ref=e45]: Combos
+                    - link "auto_awesome Auto Combo" [ref=e46] [cursor=pointer]:
+                        - /url: /dashboard/auto-combo
+                        - generic [ref=e47]: auto_awesome
+                        - generic [ref=e48]: Auto Combo
+                    - link "account_balance_wallet Costs" [ref=e49] [cursor=pointer]:
+                        - /url: /dashboard/costs
+                        - generic [ref=e50]: account_balance_wallet
+                        - generic [ref=e51]: Costs
+                    - link "analytics Analytics" [ref=e52] [cursor=pointer]:
+                        - /url: /dashboard/analytics
+                        - generic [ref=e53]: analytics
+                        - generic [ref=e54]: Analytics
+                    - link "tune Limits & Quotas" [ref=e55] [cursor=pointer]:
+                        - /url: /dashboard/limits
+                        - generic [ref=e56]: tune
+                        - generic [ref=e57]: Limits & Quotas
+                    - link "cached Cache" [ref=e58] [cursor=pointer]:
+                        - /url: /dashboard/cache
+                        - generic [ref=e59]: cached
+                        - generic [ref=e60]: Cache
+                    - link "perm_media Media" [ref=e61] [cursor=pointer]:
+                        - /url: /dashboard/cache/media
+                        - generic [ref=e62]: perm_media
+                        - generic [ref=e63]: Media
+                - generic [ref=e64]:
+                    - paragraph [ref=e65]: CLI
+                    - link "terminal Tools" [ref=e66] [cursor=pointer]:
+                        - /url: /dashboard/cli-tools
+                        - generic [ref=e67]: terminal
+                        - generic [ref=e68]: Tools
+                    - link "smart_toy Agents" [ref=e69] [cursor=pointer]:
+                        - /url: /dashboard/agents
+                        - generic [ref=e70]: smart_toy
+                        - generic [ref=e71]: Agents
+                    - link "psychology Memory" [ref=e72] [cursor=pointer]:
+                        - /url: /dashboard/memory
+                        - generic [ref=e73]: psychology
+                        - generic [ref=e74]: Memory
+                    - link "auto_fix_high Skills" [ref=e75] [cursor=pointer]:
+                        - /url: /dashboard/skills
+                        - generic [ref=e76]: auto_fix_high
+                        - generic [ref=e77]: Skills
+                - generic [ref=e78]:
+                    - paragraph [ref=e79]: System
+                    - link "health_and_safety Health" [ref=e80] [cursor=pointer]:
+                        - /url: /dashboard/health
+                        - generic [ref=e81]: health_and_safety
+                        - generic [ref=e82]: Health
+                    - link "description Logs" [ref=e83] [cursor=pointer]:
+                        - /url: /dashboard/logs
+                        - generic [ref=e84]: description
+                        - generic [ref=e85]: Logs
+                    - link "history Audit Log" [ref=e86] [cursor=pointer]:
+                        - /url: /dashboard/audit
+                        - generic [ref=e87]: history
+                        - generic [ref=e88]: Audit Log
+                    - link "settings Settings" [ref=e89] [cursor=pointer]:
+                        - /url: /dashboard/settings
+                        - generic [ref=e90]: settings
+                        - generic [ref=e91]: Settings
+                - generic [ref=e92]:
+                    - paragraph [ref=e93]: Help
+                    - link "menu_book Docs" [ref=e94] [cursor=pointer]:
+                        - /url: /docs
+                        - generic [ref=e95]: menu_book
+                        - generic [ref=e96]: Docs
+                    - link "bug_report Issues" [ref=e97] [cursor=pointer]:
+                        - /url: https://github.com/diegosouzapw/OmniRoute/issues
+                        - generic [ref=e98]: bug_report
+                        - generic [ref=e99]: Issues
+            - generic [ref=e100]:
+                - button "restart_alt Restart" [ref=e101]:
+                    - generic: restart_alt
+                    - text: Restart
+                - button "power_settings_new Shutdown" [ref=e102]:
+                    - generic: power_settings_new
+                    - text: Shutdown
+        - main [ref=e103]:
+            - generic [ref=e104]:
+                - button "menu" [ref=e106]:
+                    - generic: menu
+                - generic [ref=e107]:
+                    - button "🇺🇸 EN expand_more" [ref=e109]:
+                        - generic [ref=e110]: 🇺🇸
+                        - generic [ref=e111]: EN
+                        - generic: expand_more
+                    - button "Switch to dark mode" [ref=e112]:
+                        - generic: dark_mode
+                    - button "logout" [ref=e113]:
+                        - generic: logout
+            - navigation "Breadcrumb" [ref=e116]:
+                - link "Dashboard" [ref=e118] [cursor=pointer]:
+                    - /url: /dashboard
+                - generic [ref=e119]:
+                    - generic [ref=e120]: ›
+                    - generic [ref=e121]: Providers
+    - alert [ref=e135]

AGENTS.md

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

CONTRIBUTING.md

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

Dockerfile

@@ -1,12 +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
@@ -24,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
@@ -31,8 +39,14 @@ COPY --from=builder /app/.next/static ./.next/static
 COPY --from=builder /app/.next/standalone ./
 # Explicitly copy @swc/helpers — not always traced by standalone output but needed at runtime
 COPY --from=builder /app/node_modules/@swc/helpers ./node_modules/@swc/helpers
+# Explicitly copy pino transport dependencies — pino spawns a worker that requires
+# pino-abstract-transport at runtime; Next.js standalone trace does not capture it (#449)
+COPY --from=builder /app/node_modules/pino-abstract-transport ./node_modules/pino-abstract-transport
+COPY --from=builder /app/node_modules/pino-pretty ./node_modules/pino-pretty
+COPY --from=builder /app/node_modules/split2 ./node_modules/split2
 COPY --from=builder /app/scripts/run-standalone.mjs ./run-standalone.mjs
 COPY --from=builder /app/scripts/runtime-env.mjs ./runtime-env.mjs
+COPY --from=builder /app/scripts/bootstrap-env.mjs ./bootstrap-env.mjs
 COPY --from=builder /app/scripts/healthcheck.mjs ./healthcheck.mjs
 
 EXPOSE 20128
@@ -46,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/"
 

SECURITY.md

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

audit_results.json

@@ -0,0 +1,203 @@
+{
+  "auditReportVersion": 2,
+  "vulnerabilities": {
+    "next": {
+      "name": "next",
+      "severity": "high",
+      "isDirect": true,
+      "via": [
+        {
+          "source": 1112592,
+          "name": "next",
+          "dependency": "next",
+          "title": "Next.js self-hosted applications vulnerable to DoS via Image Optimizer remotePatterns configuration",
+          "url": "https://github.com/advisories/GHSA-9g9p-9gw9-jx7f",
+          "severity": "moderate",
+          "cwe": ["CWE-400", "CWE-770"],
+          "cvss": {
+            "score": 5.9,
+            "vectorString": "CVSS:3.1/AV:N/AC:H/PR:N/UI:N/S:U/C:N/I:N/A:H"
+          },
+          "range": ">=15.6.0-canary.0 <16.1.5"
+        },
+        {
+          "source": 1112646,
+          "name": "next",
+          "dependency": "next",
+          "title": "Next.js HTTP request deserialization can lead to DoS when using insecure React Server Components",
+          "url": "https://github.com/advisories/GHSA-h25m-26qc-wcjf",
+          "severity": "high",
+          "cwe": ["CWE-400", "CWE-502"],
+          "cvss": {
+            "score": 7.5,
+            "vectorString": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H"
+          },
+          "range": ">=16.0.0-beta.0 <16.0.11"
+        },
+        {
+          "source": 1112990,
+          "name": "next",
+          "dependency": "next",
+          "title": "Next.js has Unbounded Memory Consumption via PPR Resume Endpoint ",
+          "url": "https://github.com/advisories/GHSA-5f7q-jpqc-wp7h",
+          "severity": "moderate",
+          "cwe": ["CWE-400", "CWE-409", "CWE-770"],
+          "cvss": {
+            "score": 5.9,
+            "vectorString": "CVSS:3.1/AV:N/AC:H/PR:N/UI:N/S:U/C:N/I:N/A:H"
+          },
+          "range": ">=16.0.0-beta.0 <16.1.5"
+        },
+        {
+          "source": 1114898,
+          "name": "next",
+          "dependency": "next",
+          "title": "Next.js: HTTP request smuggling in rewrites",
+          "url": "https://github.com/advisories/GHSA-ggv3-7p47-pfv8",
+          "severity": "moderate",
+          "cwe": ["CWE-444"],
+          "cvss": {
+            "score": 0,
+            "vectorString": null
+          },
+          "range": ">=16.0.0-beta.0 <16.1.7"
+        },
+        {
+          "source": 1114941,
+          "name": "next",
+          "dependency": "next",
+          "title": "Next.js: Unbounded next/image disk cache growth can exhaust storage",
+          "url": "https://github.com/advisories/GHSA-3x4c-7xq6-9pq8",
+          "severity": "moderate",
+          "cwe": ["CWE-400"],
+          "cvss": {
+            "score": 0,
+            "vectorString": null
+          },
+          "range": ">=16.0.0-beta.0 <16.1.7"
+        },
+        {
+          "source": 1114942,
+          "name": "next",
+          "dependency": "next",
+          "title": "Next.js: Unbounded postponed resume buffering can lead to DoS",
+          "url": "https://github.com/advisories/GHSA-h27x-g6w4-24gq",
+          "severity": "moderate",
+          "cwe": ["CWE-770"],
+          "cvss": {
+            "score": 0,
+            "vectorString": null
+          },
+          "range": ">=16.0.1 <16.1.7"
+        },
+        {
+          "source": 1114943,
+          "name": "next",
+          "dependency": "next",
+          "title": "Next.js: null origin can bypass Server Actions CSRF checks",
+          "url": "https://github.com/advisories/GHSA-mq59-m269-xvcx",
+          "severity": "moderate",
+          "cwe": ["CWE-352"],
+          "cvss": {
+            "score": 0,
+            "vectorString": null
+          },
+          "range": ">=16.0.1 <16.1.7"
+        },
+        {
+          "source": 1115360,
+          "name": "next",
+          "dependency": "next",
+          "title": "Next.js: null origin can bypass dev HMR websocket CSRF checks",
+          "url": "https://github.com/advisories/GHSA-jcc7-9wpm-mj36",
+          "severity": "low",
+          "cwe": ["CWE-1385"],
+          "cvss": {
+            "score": 0,
+            "vectorString": null
+          },
+          "range": ">=16.0.1 <16.1.7"
+        }
+      ],
+      "effects": [],
+      "range": "15.6.0-canary.0 - 16.1.6",
+      "nodes": ["node_modules/next"],
+      "fixAvailable": {
+        "name": "next",
+        "version": "16.2.2",
+        "isSemVerMajor": false
+      }
+    },
+    "vite": {
+      "name": "vite",
+      "severity": "high",
+      "isDirect": false,
+      "via": [
+        {
+          "source": 1116007,
+          "name": "vite",
+          "dependency": "vite",
+          "title": "Vite Vulnerable to Path Traversal in Optimized Deps `.map` Handling",
+          "url": "https://github.com/advisories/GHSA-4w7w-66w2-5vf9",
+          "severity": "moderate",
+          "cwe": ["CWE-22", "CWE-200"],
+          "cvss": {
+            "score": 0,
+            "vectorString": null
+          },
+          "range": ">=8.0.0 <=8.0.4"
+        },
+        {
+          "source": 1116009,
+          "name": "vite",
+          "dependency": "vite",
+          "title": "Vite: `server.fs.deny` bypassed with queries",
+          "url": "https://github.com/advisories/GHSA-v2wj-q39q-566r",
+          "severity": "high",
+          "cwe": ["CWE-180", "CWE-284"],
+          "cvss": {
+            "score": 0,
+            "vectorString": null
+          },
+          "range": ">=8.0.0 <=8.0.4"
+        },
+        {
+          "source": 1116012,
+          "name": "vite",
+          "dependency": "vite",
+          "title": "Vite Vulnerable to Arbitrary File Read via Vite Dev Server WebSocket",
+          "url": "https://github.com/advisories/GHSA-p9ff-h696-f583",
+          "severity": "high",
+          "cwe": ["CWE-200", "CWE-306"],
+          "cvss": {
+            "score": 0,
+            "vectorString": null
+          },
+          "range": ">=8.0.0 <=8.0.4"
+        }
+      ],
+      "effects": [],
+      "range": "8.0.0 - 8.0.4",
+      "nodes": ["node_modules/vite"],
+      "fixAvailable": true
+    }
+  },
+  "metadata": {
+    "vulnerabilities": {
+      "info": 0,
+      "low": 0,
+      "moderate": 0,
+      "high": 2,
+      "critical": 0,
+      "total": 2
+    },
+    "dependencies": {
+      "prod": 407,
+      "dev": 485,
+      "optional": 154,
+      "peer": 480,
+      "peerOptional": 0,
+      "total": 1455
+    }
+  }
+}

bin/omniroute.mjs

@@ -17,6 +17,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir, platform } from "node:os";
+import { isNativeBinaryCompatible } from "../scripts/native-binary-compat.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -115,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");
   }
@@ -188,8 +187,50 @@ const serverJs = join(APP_DIR, "server.js");
 
 if (!existsSync(serverJs)) {
   console.error("\x1b[31m✖ Server not found at:\x1b[0m", serverJs);
-  console.error("  This usually means the package was not built correctly.");
-  console.error("  Try reinstalling: npm install -g omniroute");
+  console.error("  The package may not have been built correctly.");
+  console.error("");
+  // (#492) Detect common non-standard Node managers that cause this issue
+  const nodeExec = process.execPath || "";
+  const isMise = nodeExec.includes("mise") || nodeExec.includes(".local/share/mise");
+  const isNvm = nodeExec.includes(".nvm") || nodeExec.includes("nvm");
+  if (isMise) {
+    console.error(
+      "  \x1b[33m⚠ mise detected:\x1b[0m If you installed via `npm install -g omniroute`,"
+    );
+    console.error("    try: \x1b[36mnpx omniroute@latest\x1b[0m  (downloads a fresh copy)");
+    console.error("    or:  \x1b[36mmise exec -- npx omniroute\x1b[0m");
+  } else if (isNvm) {
+    console.error(
+      "  \x1b[33m⚠ nvm detected:\x1b[0m Try reinstalling after loading the correct Node version:"
+    );
+    console.error("    \x1b[36mnvm use --lts && npm install -g omniroute\x1b[0m");
+  } else {
+    console.error("  Try: \x1b[36mnpm install -g omniroute\x1b[0m  (reinstall)");
+    console.error("  Or:  \x1b[36mnpx omniroute@latest\x1b[0m");
+  }
+  process.exit(1);
+}
+
+// ── Pre-flight: verify better-sqlite3 native binary ───────
+// Verify the binary's actual target platform/arch before trusting dlopen.
+// This avoids the macOS false positive where a bundled linux-x64 addon can
+// appear to load even though the runtime will fail when better-sqlite3 starts.
+const sqliteBinary = join(
+  APP_DIR,
+  "node_modules",
+  "better-sqlite3",
+  "build",
+  "Release",
+  "better_sqlite3.node"
+);
+if (existsSync(sqliteBinary) && !isNativeBinaryCompatible(sqliteBinary)) {
+  console.error(
+    "\x1b[31m✖ better-sqlite3 native module is incompatible with this platform.\x1b[0m"
+  );
+  console.error(`  Run: cd ${APP_DIR} && npm rebuild better-sqlite3`);
+  if (platform() === "darwin") {
+    console.error("  If build tools are missing: xcode-select --install");
+  }
   process.exit(1);
 }
 

bin/reset-password.mjs

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

dbsetup.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process'
+
+const env = { ...process.env }
+
+await exec('npx next build --experimental-build-mode generate')
+
+// launch application
+await exec(process.argv.slice(2).join(' '))
+
+function exec(command) {
+  const child = spawn(command, { shell: true, stdio: 'inherit', env })
+  return new Promise((resolve, reject) => {
+    child.on('exit', code => {
+      if (code === 0) {
+        resolve()
+      } else {
+        reject(new Error(`${command} failed rc=${code}`))
+      }
+    })
+  })
+}

debug-handles.mjs

@@ -0,0 +1,17 @@
+import process from "node:process";
+import fs from "node:fs";
+
+setTimeout(() => {
+  const activeHandles = process._getActiveHandles();
+  console.log("ACTIVE HANDLES: " + activeHandles.length);
+  activeHandles.forEach((handle, i) => {
+    console.log(`Handle ${i}:`, handle?.constructor?.name);
+    // if it's a timer or socket, let's see more
+    if (handle?.constructor?.name === "Timeout") {
+      console.log("  Timer wrapper:", handle?._onTimeout?.toString().slice(0, 50));
+    }
+  });
+  process.exit(1);
+}, 2000);
+
+await import("./tests/integration/chat-pipeline.test.mjs");

debug-sockets.mjs

@@ -0,0 +1,14 @@
+import process from "node:process";
+import("./tests/integration/chat-pipeline.test.mjs").then((mod) => {
+  setTimeout(() => {
+    const activeHandles = process._getActiveHandles();
+    console.log("ACTIVE HANDLES: " + activeHandles.length);
+    activeHandles.forEach((handle, i) => {
+      console.log(`Handle ${i}:`, handle?.constructor?.name);
+      if (handle?.constructor?.name === "Socket") {
+        console.log("Socket ports:", handle?.localPort, handle?.remotePort);
+      }
+    });
+    process.exit(1);
+  }, 15000);
+});

debug2.log

@@ -0,0 +1,339 @@
+TAP version 13
+# Subtest: Chat Pipeline — handleSingleModelChat decomposition
+    # Subtest: should define resolveModelOrError helper
+    ok 1 - should define resolveModelOrError helper
+      ---
+      duration_ms: 2.870676
+      type: 'test'
+      ...
+    # Subtest: should define checkPipelineGates helper
+    ok 2 - should define checkPipelineGates helper
+      ---
+      duration_ms: 0.539959
+      type: 'test'
+      ...
+    # Subtest: should define executeChatWithBreaker helper
+    ok 3 - should define executeChatWithBreaker helper
+      ---
+      duration_ms: 0.540611
+      type: 'test'
+      ...
+    # Subtest: should keep cost accounting in the core chat pipeline
+    ok 4 - should keep cost accounting in the core chat pipeline
+      ---
+      duration_ms: 0.583888
+      type: 'test'
+      ...
+    # Subtest: handleSingleModelChat should use resolveModelOrError
+    ok 5 - handleSingleModelChat should use resolveModelOrError
+      ---
+      duration_ms: 0.395358
+      type: 'test'
+      ...
+    # Subtest: handleSingleModelChat should use checkPipelineGates
+    ok 6 - handleSingleModelChat should use checkPipelineGates
+      ---
+      duration_ms: 0.725771
+      type: 'test'
+      ...
+    # Subtest: handleSingleModelChat should use executeChatWithBreaker
+    ok 7 - handleSingleModelChat should use executeChatWithBreaker
+      ---
+      duration_ms: 0.384009
+      type: 'test'
+      ...
+    # Subtest: chatCore should record cost for both non-streaming and streaming responses
+    ok 8 - chatCore should record cost for both non-streaming and streaming responses
+      ---
+      duration_ms: 0.717301
+      type: 'test'
+      ...
+    1..8
+ok 1 - Chat Pipeline — handleSingleModelChat decomposition
+  ---
+  duration_ms: 12.510313
+  type: 'suite'
+  ...
+# Subtest: Chat Pipeline — combo fallback support
+    # Subtest: should import handleComboChat
+    ok 1 - should import handleComboChat
+      ---
+      duration_ms: 0.683569
+      type: 'test'
+      ...
+    # Subtest: should delegate to handleSingleModelChat for each combo model
+    ok 2 - should delegate to handleSingleModelChat for each combo model
+      ---
+      duration_ms: 0.903143
+      type: 'test'
+      ...
+    # Subtest: should check model availability before attempting combo models
+    ok 3 - should check model availability before attempting combo models
+      ---
+      duration_ms: 0.37494
+      type: 'test'
+      ...
+    1..3
+ok 2 - Chat Pipeline — combo fallback support
+  ---
+  duration_ms: 2.526966
+  type: 'suite'
+  ...
+# Subtest: Chat Pipeline — circuit breaker integration
+    # Subtest: should import CircuitBreakerOpenError
+    ok 1 - should import CircuitBreakerOpenError
+      ---
+      duration_ms: 0.500942
+      type: 'test'
+      ...
+    # Subtest: should handle CircuitBreakerOpenError with retry-after
+    ok 2 - should handle CircuitBreakerOpenError with retry-after
+      ---
+      duration_ms: 0.262275
+      type: 'test'
+      ...
+    # Subtest: should reject requests when circuit is open
+    ok 3 - should reject requests when circuit is open
+      ---
+      duration_ms: 0.399071
+      type: 'test'
+      ...
+    1..3
+ok 3 - Chat Pipeline — circuit breaker integration
+  ---
+  duration_ms: 1.532005
+  type: 'suite'
+  ...
+# Subtest: DI Container — container.ts
+    # Subtest: should export a container singleton
+    ok 1 - should export a container singleton
+      ---
+      duration_ms: 293.16418
+      type: 'test'
+      ...
+    # Subtest: should register and resolve a custom service
+    ok 2 - should register and resolve a custom service
+      ---
+      duration_ms: 9.047061
+      type: 'test'
+      ...
+    # Subtest: should return cached singleton on repeated resolve
+    ok 3 - should return cached singleton on repeated resolve
+      ---
+      duration_ms: 2.700355
+      type: 'test'
+      ...
+    # Subtest: should throw on resolving unregistered service
+    ok 4 - should throw on resolving unregistered service
+      ---
+      duration_ms: 3.280776
+      type: 'test'
+      ...
+    # Subtest: should have default registrations
+    ok 5 - should have default registrations
+      ---
+      duration_ms: 2.960963
+      type: 'test'
+      ...
+    # Subtest: should support re-registration (overwrite)
+    ok 6 - should support re-registration (overwrite)
+      ---
+      duration_ms: 2.683065
+      type: 'test'
+      ...
+    1..6
+ok 4 - DI Container — container.ts
+  ---
+  duration_ms: 314.82733
+  type: 'suite'
+  ...
+# [Plugins] Registered "test-logger" (priority: 10, enabled: true)
+# Subtest: Plugin Architecture — plugins/index.ts
+    # Subtest: should register and list plugins
+    ok 1 - should register and list plugins
+      ---
+      duration_ms: 7.470741
+      type: 'test'
+      ...
+# [Plugins] Registered "low" (priority: 200, enabled: true)
+# [Plugins] Registered "high" (priority: 1, enabled: true)
+# [Plugins] Registered "mid" (priority: 50, enabled: true)
+    # Subtest: should sort plugins by priority
+    ok 2 - should sort plugins by priority
+      ---
+      duration_ms: 3.51882
+      type: 'test'
+      ...
+# [Plugins] Registered "first" (priority: 1, enabled: true)
+# [Plugins] Registered "second" (priority: 2, enabled: true)
+    # Subtest: should run onRequest hooks in order
+    ok 3 - should run onRequest hooks in order
+      ---
+      duration_ms: 2.940782
+      type: 'test'
+      ...
+# [Plugins] Registered "blocker" (priority: 1, enabled: true)
+# [Plugins] Registered "never-runs" (priority: 2, enabled: true)
+# [Plugins] Request blocked by "blocker"
+    # Subtest: should support request blocking
+    ok 4 - should support request blocking
+      ---
+      duration_ms: 3.293988
+      type: 'test'
+      ...
+# [Plugins] Registered "toggle-me" (priority: 100, enabled: true)
+    # Subtest: should enable/disable plugins at runtime
+    ok 5 - should enable/disable plugins at runtime
+      ---
+      duration_ms: 2.784824
+      type: 'test'
+      ...
+# [Plugins] Registered "removable" (priority: 100, enabled: true)
+    # Subtest: should unregister plugins
+    ok 6 - should unregister plugins
+      ---
+      duration_ms: 2.608295
+      type: 'test'
+      ...
+# [Plugins] Registered "response-modifier" (priority: 100, enabled: true)
+    # Subtest: should run onResponse hooks
+    ok 7 - should run onResponse hooks
+      ---
+      duration_ms: 2.746361
+      type: 'test'
+      ...
+# [Plugins] Registered "error-handler" (priority: 100, enabled: true)
+# [Plugins] Error recovered by "error-handler"
+    # Subtest: should run onError hooks and allow recovery
+    ok 8 - should run onError hooks and allow recovery
+      ---
+      duration_ms: 2.899465
+      type: 'test'
+      ...
+    # Subtest: should return null from onError if no recovery
+    ok 9 - should return null from onError if no recovery
+      ---
+      duration_ms: 2.313171
+      type: 'test'
+      ...
+    1..9
+ok 5 - Plugin Architecture — plugins/index.ts
+  ---
+  duration_ms: 31.770504
+  type: 'suite'
+  ...
+# Subtest: Prompt Template Versioning — prompts.ts module existence
+    # Subtest: prompts.ts should exist
+    ok 1 - prompts.ts should exist
+      ---
+      duration_ms: 0.369635
+      type: 'test'
+      ...
+    # Subtest: should export CRUD functions
+    ok 2 - should export CRUD functions
+      ---
+      duration_ms: 0.391134
+      type: 'test'
+      ...
+    # Subtest: should define PromptTemplate interface
+    ok 3 - should define PromptTemplate interface
+      ---
+      duration_ms: 0.333598
+      type: 'test'
+      ...
+    # Subtest: should use content hashing for deduplication
+    ok 4 - should use content hashing for deduplication
+      ---
+      duration_ms: 0.31716
+      type: 'test'
+      ...
+    1..4
+ok 6 - Prompt Template Versioning — prompts.ts module existence
+  ---
+  duration_ms: 1.752975
+  type: 'suite'
+  ...
+# Subtest: Eval Scheduler — scheduler.ts module existence
+    # Subtest: scheduler.ts should exist
+    ok 1 - scheduler.ts should exist
+      ---
+      duration_ms: 0.347059
+      type: 'test'
+      ...
+    # Subtest: should export scheduling functions
+    ok 2 - should export scheduling functions
+      ---
+      duration_ms: 0.582836
+      type: 'test'
+      ...
+    # Subtest: should define ScheduledEval and EvalRunResult types
+    ok 3 - should define ScheduledEval and EvalRunResult types
+      ---
+      duration_ms: 0.459196
+      type: 'test'
+      ...
+    # Subtest: should have pluggable output provider
+    ok 4 - should have pluggable output provider
+      ---
+      duration_ms: 0.310267
+      type: 'test'
+      ...
+    1..4
+ok 7 - Eval Scheduler — scheduler.ts module existence
+  ---
+  duration_ms: 1.961338
+  type: 'suite'
+  ...
+# Subtest: Migration System — files exist
+    # Subtest: migrationRunner.ts should exist
+    ok 1 - migrationRunner.ts should exist
+      ---
+      duration_ms: 0.381312
+      type: 'test'
+      ...
+    # Subtest: 001_initial_schema.sql should exist
+    ok 2 - 001_initial_schema.sql should exist
+      ---
+      duration_ms: 0.248336
+      type: 'test'
+      ...
+    # Subtest: core.ts should reference migration runner
+    ok 3 - core.ts should reference migration runner
+      ---
+      duration_ms: 0.542947
+      type: 'test'
+      ...
+    1..3
+ok 8 - Migration System — files exist
+  ---
+  duration_ms: 1.448447
+  type: 'suite'
+  ...
+# Subtest: CORS — centralized configuration
+    # Subtest: shared/utils/cors.ts should exist
+    ok 1 - shared/utils/cors.ts should exist
+      ---
+      duration_ms: 0.374376
+      type: 'test'
+      ...
+    # Subtest: should export CORS_HEADERS and CORS_ORIGIN
+    ok 2 - should export CORS_HEADERS and CORS_ORIGIN
+      ---
+      duration_ms: 0.390035
+      type: 'test'
+      ...
+    1..2
+ok 9 - CORS — centralized configuration
+  ---
+  duration_ms: 0.962465
+  type: 'suite'
+  ...
+1..9
+# tests 42
+# suites 9
+# pass 42
+# fail 0
+# cancelled 0
+# skipped 0
+# todo 0
+# duration_ms 869.387894

docker-compose.prod.yml

@@ -16,9 +16,10 @@ services:
     container_name: omniroute-prod
     build:
       context: .
-      target: runner-base
+      target: runner-cli
     image: omniroute:prod
     restart: unless-stopped
+    stop_grace_period: 40s
     env_file: .env
     environment:
       - NODE_ENV=production

docker-compose.yml

@@ -6,11 +6,14 @@
 #    base  → minimal image, no CLI tools
 #    cli   → CLIs installed inside the container (portable)
 #    host  → runner-base + host-mounted CLI binaries (Linux-first)
+#    cliproxyapi → CLIProxyAPI sidecar on port 8317
 #
 #  Usage:
 #    docker compose --profile base up -d
 #    docker compose --profile cli up -d
 #    docker compose --profile host up -d
+#    docker compose --profile cliproxyapi up -d
+#    docker compose --profile cli --profile cliproxyapi up -d
 #
 #  Before first run, copy .env.example → .env and edit your secrets.
 # ──────────────────────────────────────────────────────────────────────
@@ -59,6 +62,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
 
@@ -104,6 +112,30 @@ services:
     profiles:
       - host
 
+  # ── Profile: cliproxyapi (CLIProxyAPI as sidecar) ─────────────────
+  cliproxyapi:
+    container_name: cliproxyapi
+    image: ghcr.io/router-for-me/cliproxyapi:v6.9.7
+    restart: unless-stopped
+    ports:
+      - "${CLIPROXYAPI_PORT:-8317}:${CLIPROXYAPI_PORT:-8317}"
+    volumes:
+      - cliproxyapi-data:/root/.cli-proxy-api
+    environment:
+      - PORT=${CLIPROXYAPI_PORT:-8317}
+      - HOST=0.0.0.0
+    healthcheck:
+      test:
+        ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:${CLIPROXYAPI_PORT:-8317}/v1/models"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    profiles:
+      - cliproxyapi
+
 volumes:
   omniroute-data:
     name: omniroute-data
+  cliproxyapi-data:
+    name: cliproxyapi-data

docs/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
@@ -86,7 +106,7 @@ flowchart LR
     end
 
     subgraph Upstreams[Upstream Providers]
-        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity]
+        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/GitHub/Kiro/Cursor/Antigravity]
         P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
         P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
     end
@@ -220,7 +240,7 @@ Domain layer modules:
 OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
 - Registry index: `src/lib/oauth/providers/index.ts`
-- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
+- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `qoder.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
 - Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
 ## 3) Persistence Layer
@@ -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
 
@@ -593,7 +614,7 @@ Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/
 
 | Executor              | Provider(s)                                                                                                                                                  | Special Handling                                                     |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
-| `DefaultExecutor`     | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider                               |
+| `DefaultExecutor`     | OpenAI, Claude, Gemini, Qwen, Qoder, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider                               |
 | `AntigravityExecutor` | Google Antigravity                                                                                                                                           | Custom project/session IDs, Retry-After parsing                      |
 | `CodexExecutor`       | OpenAI Codex                                                                                                                                                 | Injects system instructions, forces reasoning effort                 |
 | `CursorExecutor`      | Cursor IDE                                                                                                                                                   | ConnectRPC protocol, Protobuf encoding, request signing via checksum |
@@ -617,7 +638,7 @@ All other providers (including custom compatible nodes) use the `DefaultExecutor
 | Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
 | Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
 | Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
-| iFlow            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Qoder            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
 | OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
@@ -665,25 +686,25 @@ Additional processing layers in the translation pipeline:
 
 ## Supported API Endpoints
 
-| Endpoint                                           | Format             | Handler                                              |
-| -------------------------------------------------- | ------------------ | ---------------------------------------------------- |
-| `POST /v1/chat/completions`                        | OpenAI Chat        | `src/sse/handlers/chat.ts`                           |
-| `POST /v1/messages`                                | Claude Messages    | Same handler (auto-detected)                         |
-| `POST /v1/responses`                               | OpenAI Responses   | `open-sse/handlers/responsesHandler.ts`              |
-| `POST /v1/embeddings`                              | OpenAI Embeddings  | `open-sse/handlers/embeddings.ts`                    |
-| `GET /v1/embeddings`                               | Model listing      | API route                                            |
-| `POST /v1/images/generations`                      | OpenAI Images      | `open-sse/handlers/imageGeneration.ts`               |
-| `GET /v1/images/generations`                       | Model listing      | API route                                            |
-| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat        | Dedicated per-provider with model validation         |
-| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings  | Dedicated per-provider with model validation         |
-| `POST /v1/providers/{provider}/images/generations` | OpenAI Images      | Dedicated per-provider with model validation         |
-| `POST /v1/messages/count_tokens`                   | Claude Token Count | API route                                            |
-| `GET /v1/models`                                   | OpenAI Models list | API route (chat + embedding + image + custom models) |
-| `GET /api/models/catalog`                          | Catalog            | All models grouped by provider + type                |
-| `POST /v1beta/models/*:streamGenerateContent`      | Gemini native      | API route                                            |
-| `GET/PUT/DELETE /api/settings/proxy`               | Proxy Config       | Network proxy configuration                          |
-| `POST /api/settings/proxy/test`                    | Proxy Connectivity | Proxy health/connectivity test endpoint              |
-| `GET/POST/DELETE /api/provider-models`             | Custom Models      | Custom model management per provider                 |
+| Endpoint                                           | Format             | Handler                                                             |
+| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------- |
+| `POST /v1/chat/completions`                        | OpenAI Chat        | `src/sse/handlers/chat.ts`                                          |
+| `POST /v1/messages`                                | Claude Messages    | Same handler (auto-detected)                                        |
+| `POST /v1/responses`                               | OpenAI Responses   | `open-sse/handlers/responsesHandler.ts`                             |
+| `POST /v1/embeddings`                              | OpenAI Embeddings  | `open-sse/handlers/embeddings.ts`                                   |
+| `GET /v1/embeddings`                               | Model listing      | API route                                                           |
+| `POST /v1/images/generations`                      | OpenAI Images      | `open-sse/handlers/imageGeneration.ts`                              |
+| `GET /v1/images/generations`                       | Model listing      | API route                                                           |
+| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat        | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings  | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/images/generations` | OpenAI Images      | Dedicated per-provider with model validation                        |
+| `POST /v1/messages/count_tokens`                   | Claude Token Count | API route                                                           |
+| `GET /v1/models`                                   | OpenAI Models list | API route (chat + embedding + image + custom models)                |
+| `GET /api/models/catalog`                          | Catalog            | All models grouped by provider + type                               |
+| `POST /v1beta/models/*:streamGenerateContent`      | Gemini native      | API route                                                           |
+| `GET/PUT/DELETE /api/settings/proxy`               | Proxy Config       | Network proxy configuration                                         |
+| `POST /api/settings/proxy/test`                    | Proxy Connectivity | Proxy health/connectivity test endpoint                             |
+| `GET/POST/DELETE /api/provider-models`             | Provider Models    | Provider model metadata backing custom and managed available models |
 
 ## Bypass Handler
 
@@ -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

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

docs/CODEBASE_DOCUMENTATION.md

@@ -1,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.
 
@@ -267,7 +267,7 @@ Business logic that supports the handlers and executors.
 | `provider.ts`        | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. |
 | `model.ts`           | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support.                                                                             |
 | `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not).                                                                                                                                                                         |
-| `tokenRefresh.ts`    | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff.                                                                       |
+| `tokenRefresh.ts`    | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, Qoder, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff.                                                                       |
 | `combo.ts`           | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes.                                                                                                                                                                          |
 | `usage.ts`           | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings).                                                                                                                                                                              |
 | `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request.                                                                                                                                                              |
@@ -539,7 +539,7 @@ A 2000-token buffer is added to reported usage to prevent clients from hitting c
 | Kiro (AWS)               | AWS SSO OIDC or Social | Kiro        | Binary EventStream parsing                    |
 | Cursor IDE               | Checksum auth          | Cursor      | Protobuf encoding, SHA-256 checksums          |
 | Qwen                     | OAuth                  | Default     | Standard auth                                 |
-| iFlow                    | OAuth (Basic + Bearer) | Default     | Dual auth header                              |
+| Qoder                    | OAuth (Basic + Bearer) | Default     | Dual auth header                              |
 | OpenRouter               | API key                | Default     | Standard Bearer auth                          |
 | GLM, Kimi, MiniMax       | API key                | Default     | Claude-compatible, use `x-api-key`            |
 | `openai-compatible-*`    | API key                | Default     | Dynamic: any OpenAI-compatible endpoint       |

docs/COVERAGE_PLAN.md

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

docs/FEATURES.md

@@ -1,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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
 
 ![Providers Dashboard](screenshots/01-providers.png)
 
@@ -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/FLY_IO_DEPLOYMENT_GUIDE.md

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

docs/I18N.md

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

docs/MCP-SERVER.md

@@ -38,16 +38,16 @@ See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot,
 
 ## Advanced Tools (8)
 
-| Tool                               | Description                                     |
-| :--------------------------------- | :---------------------------------------------- |
-| `omniroute_simulate_route`         | Dry-run routing simulation with fallback tree   |
-| `omniroute_set_budget_guard`       | Session budget with degrade/block/alert actions |
-| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset   |
-| `omniroute_test_combo`             | Live-test all models in a combo                 |
-| `omniroute_get_provider_metrics`   | Detailed metrics for one provider               |
-| `omniroute_best_combo_for_task`    | Task-fitness recommendation with alternatives   |
-| `omniroute_explain_route`          | Explain a past routing decision                 |
-| `omniroute_get_session_snapshot`   | Full session state: costs, tokens, errors       |
+| Tool                               | Description                                                 |
+| :--------------------------------- | :---------------------------------------------------------- |
+| `omniroute_simulate_route`         | Dry-run routing simulation with fallback tree               |
+| `omniroute_set_budget_guard`       | Session budget with degrade/block/alert actions             |
+| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset               |
+| `omniroute_test_combo`             | Live-test all models in a combo via a real upstream request |
+| `omniroute_get_provider_metrics`   | Detailed metrics for one provider                           |
+| `omniroute_best_combo_for_task`    | Task-fitness recommendation with alternatives               |
+| `omniroute_explain_route`          | Explain a past routing decision                             |
+| `omniroute_get_session_snapshot`   | Full session state: costs, tokens, errors                   |
 
 ## Authentication
 

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.
 
@@ -97,7 +97,7 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
 
 1. Check usage stats in Dashboard → Usage
 2. Switch primary model to GLM/MiniMax
-3. Use free tier (Gemini CLI, iFlow) for non-critical tasks
+3. Use free tier (Gemini CLI, Qoder) for non-critical tasks
 4. Set cost budgets per API key: Dashboard → API Keys → Budget
 
 ---

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.
 
@@ -39,11 +39,11 @@ Complete guide for configuring providers, creating combos, integrating CLI tools
 | **💰 CHEAP**        | GLM-4.7           | $0.6/1M     | Daily 10AM       | Budget backup        |
 |                     | MiniMax M2.1      | $0.2/1M     | 5-hour rolling   | Cheapest option      |
 |                     | Kimi K2           | $9/mo flat  | 10M tokens/mo    | Predictable cost     |
-| **🆓 FREE**         | iFlow             | $0          | Unlimited        | 8 models free        |
+| **🆓 FREE**         | Qoder             | $0          | Unlimited        | 8 models free        |
 |                     | Qwen              | $0          | Unlimited        | 3 models free        |
 |                     | Kiro              | $0          | Unlimited        | Claude free          |
 
-**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost!
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
 
 ---
 
@@ -164,7 +164,7 @@ Dashboard → Providers → Connect GitHub
 Models:
   gh/gpt-5
   gh/claude-4.5-sonnet
-  gh/gemini-3-pro
+  gh/gemini-3.1-pro-preview
 ```
 
 ### 💰 Cheap Providers
@@ -193,10 +193,10 @@ Models:
 
 ### 🆓 FREE Providers
 
-#### iFlow (8 FREE models)
+#### Qoder (8 FREE models)
 
 ```bash
-Dashboard → Connect iFlow → OAuth login → Unlimited usage
+Dashboard → Connect Qoder → OAuth login → Unlimited usage
 
 Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1
 ```
@@ -405,25 +405,130 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat
 
 For host-integrated mode with CLI binaries, see the Docker section in the main docs.
 
+### Void Linux (xbps-src)
+
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+<details>
+<summary><b>View xbps-src template</b></summary>
+
+```bash
+# Template file for 'omniroute'
+pkgname=omniroute
+version=3.2.4
+revision=1
+hostmakedepends="nodejs python3 make"
+depends="openssl"
+short_desc="Universal AI gateway with smart routing for multiple LLM providers"
+maintainer="zenobit <zenobit@disroot.org>"
+license="MIT"
+homepage="https://github.com/diegosouzapw/OmniRoute"
+distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
+checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
+system_accounts="_omniroute"
+omniroute_homedir="/var/lib/omniroute"
+export NODE_ENV=production
+export npm_config_engine_strict=false
+export npm_config_loglevel=error
+export npm_config_fund=false
+export npm_config_audit=false
+
+do_build() {
+	# Determine target CPU arch for node-gyp
+	local _gyp_arch
+	case "$XBPS_TARGET_MACHINE" in
+		aarch64*) _gyp_arch=arm64 ;;
+		armv7*|armv6*) _gyp_arch=arm ;;
+		i686*) _gyp_arch=ia32 ;;
+		*) _gyp_arch=x64 ;;
+	esac
+
+	# 1) Install all deps – skip scripts
+	NODE_ENV=development npm ci --ignore-scripts
+
+	# 2) Build the Next.js standalone bundle
+	npm run build
+
+	# 3) Copy static assets into standalone
+	cp -r .next/static .next/standalone/.next/static
+	[ -d public ] && cp -r public .next/standalone/public || true
+
+	# 4) Compile better-sqlite3 native binding
+	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+
+	# 5) Place the compiled binding into the standalone bundle
+	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+	mkdir -p "$_bs3_release"
+	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+
+	# 6) Remove arch-specific sharp bundles
+	rm -rf .next/standalone/node_modules/@img
+
+	# 7) Copy pino runtime deps omitted by Next.js static analysis:
+	for _mod in pino-abstract-transport split2 process-warning; do
+		cp -r "node_modules/$_mod" .next/standalone/node_modules/
+	done
+}
+
+do_check() {
+	npm run test:unit
+}
+
+do_install() {
+	vmkdir usr/lib/omniroute/.next
+	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+
+	# Prevent removal of empty Next.js app router dirs by the post-install hook
+	for _d in \
+		.next/standalone/.next/server/app/dashboard \
+		.next/standalone/.next/server/app/dashboard/settings \
+		.next/standalone/.next/server/app/dashboard/providers; do
+		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+	done
+
+	cat > "${WRKDIR}/omniroute" <<'EOF'
+#!/bin/sh
+export PORT="${PORT:-20128}"
+export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
+export 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                                                         |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70`                                 | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP`            | `false`                              | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work                |
+| `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                                          |
+| `CLOUDFLARED_PROTOCOL`                  | `http2`                              | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`)                                          |
+| `OMNIROUTE_MEMORY_MB`                   | `512`                                | Node.js heap limit in MB                                                                                  |
+| `PROMPT_CACHE_MAX_SIZE`                 | `50`                                 | Max prompt cache entries                                                                                  |
+| `SEMANTIC_CACHE_MAX_SIZE`               | `100`                                | Max semantic cache entries                                                                                |
 
 For the full environment variable reference, see the [README](../README.md).
 
@@ -446,7 +551,7 @@ For the full environment variable reference, see the [README](../README.md).
 
 **MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
 
-**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
 
 **Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
 
@@ -494,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \
 
 Or use Dashboard: **Providers → [Provider] → Custom Models**.
 
+Notes:
+
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
+
 ### Dedicated Provider Routes
 
 Route requests directly to a specific provider with model validation:
@@ -538,6 +648,17 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`).
 - Automatic background sync with timeout + fail-fast
 - Prefer server-side `BASE_URL`/`CLOUD_URL` in production
 
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
 ### LLM Gateway Intelligence (Phase 9)
 
 - **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
@@ -578,6 +699,22 @@ Configure via **Dashboard → Settings → Routing**.
 | **Least Used**                 | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly        |
 | **Cost Optimized**             | Routes to the account with the lowest priority value, optimizing for lowest-cost providers       |
 
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
+X-Session-Id: your-session-key
+```
+
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
+
+If you use Nginx and send underscore-form headers, enable:
+
+```nginx
+underscores_in_headers on;
+```
+
 #### Wildcard Model Aliases
 
 Create wildcard patterns to remap model names:
@@ -637,11 +774,11 @@ OmniRoute implements provider-level resilience with four components:
 
 Manage database backups in **Dashboard → Settings → System & Storage**.
 
-| Action                   | Description                                                                                                                    |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
-| **Export Database**      | Downloads the current SQLite database as a `.sqlite` file                                                                      |
-| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
-| **Import Database**      | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created                          |
+| Action                   | Description                                                                                                                                    |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database**      | Downloads the current SQLite database as a `.sqlite` file                                                                                      |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata                 |
+| **Import Database**      | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
 
 ```bash
 # API: Export database
@@ -667,10 +804,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \
 
 ### Settings Dashboard
 
-The settings page is organized into 5 tabs for easy navigation:
+The settings page is organized into 6 tabs for easy navigation:
 
 | Tab            | Contents                                                                                       |
 | -------------- | ---------------------------------------------------------------------------------------------- |
+| **General**    | System storage tools, appearance settings, theme controls, and per-item sidebar visibility     |
 | **Security**   | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking      |
 | **Routing**    | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults   |
 | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |

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,13 +208,13 @@ server {
         # WebSocket support
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
+        proxy_set_header Connection “upgrade”;
 
         # SSE (Server-Sent Events) — streaming AI responses
         proxy_buffering off;
         proxy_cache off;
-        proxy_read_timeout 300s;
-        proxy_send_timeout 300s;
+        proxy_read_timeout 600s;
+        proxy_send_timeout 600s;
     }
 }
 
@@ -220,61 +222,65 @@ server {
 server {
     listen 80;
     listen [::]:80;
-    server_name llms.seudominio.com;
+    server_name llms.yourdomain.com;
     return 301 https://$server_name$request_uri;
 }
 NGINX
 ```
 
-### 3.3 Ativar e testar
+Keep reverse-proxy stream timeouts aligned with your OmniRoute timeout env vars. If you raise
+`FETCH_TIMEOUT_MS` / `STREAM_IDLE_TIMEOUT_MS`, raise `proxy_read_timeout` / `proxy_send_timeout`
+above the same threshold.
+
+### 3.3 Enable and Test
 
 ```bash
-# Remover config padrão
+# Remove default configuration
 rm -f /etc/nginx/sites-enabled/default
 
-# Ativar OmniRoute
+# Enable OmniRoute
 ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute
 
-# Testar e recarregar
+# Test and reload
 nginx -t && systemctl reload nginx
 ```
 
 ---
 
-## 4. Configurar Cloudflare DNS
+## 4. Configure Cloudflare DNS
 
-### 4.1 Adicionar registro DNS
+### 4.1 Add DNS record
 
-No painel da Cloudflare → DNS:
+In the Cloudflare dashboard → DNS:
 
-| Type | Name   | Content                   | Proxy      |
-| ---- | ------ | ------------------------- | ---------- |
-| A    | `llms` | `203.0.113.10` (IP da VM) | ✅ Proxied |
+| Type | Name   | Content                | Proxy      |
+| ---- | ------ | ---------------------- | ---------- |
+| A    | `llms` | `203.0.113.10` (VM IP) | ✅ Proxied |
 
-### 4.2 Configurar SSL
+### 4.2 Configure SSL
 
-Em **SSL/TLS → Overview**:
+Under **SSL/TLS → Overview**:
 
-- Modo: **Full (Strict)**
+- Mode: **Full (Strict)**
 
-Em **SSL/TLS → Edge Certificates**:
+Under **SSL/TLS → Edge Certificates**:
 
 - Always Use HTTPS: ✅ On
 - Minimum TLS Version: TLS 1.2
 - Automatic HTTPS Rewrites: ✅ On
 
-### 4.3 Testar
+### 4.3 Testing
 
 ```bash
 curl -sI https://llms.seudominio.com/health
-# Deve retornar HTTP/2 200
+# Should return HTTP/2 200
 ```
 
 ---
 
-## 5. Operações e Manutenção
+## 5. Operations and Maintenance
 
-### Atualizar para nova versão
+### Upgrade to a new version
 
 ```bash
 docker pull diegosouzapw/omniroute:latest
@@ -286,42 +292,42 @@ docker run -d --name omniroute --restart unless-stopped \
   diegosouzapw/omniroute:latest
 ```
 
-### Ver logs
+### View logs
 
 ```bash
-docker logs -f omniroute          # Stream em tempo real
-docker logs omniroute --tail 50   # Últimas 50 linhas
+docker logs -f omniroute          # Real-time stream
+docker logs omniroute --tail 50   # Last 50 lines
 ```
 
-### Backup manual do banco
+### Manual database backup
 
 ```bash
-# Copiar dados do volume para o host
+# Copy data from the volume to the host
 docker cp omniroute:/app/data ./backup-$(date +%F)
 
-# Ou comprimir todo o volume
+# Or compress the entire volume
 docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
   alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data
 ```
 
-### Restaurar de backup
+### Restore from backup
 
 ```bash
 docker stop omniroute
 docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
-  alpine sh -c "rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /"
+  alpine sh -c “rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /”
 docker start omniroute
 ```
 
 ---
 
-## 6. Segurança Avançada
+## 6. Advanced Security
 
-### Restringir nginx para Cloudflare IPs
+### Restrict nginx to Cloudflare IPs
 
 ```bash
-cat > /etc/nginx/cloudflare-ips.conf << 'CF'
-# Cloudflare IPv4 ranges — atualizar periodicamente
+cat > /etc/nginx/cloudflare-ips.conf << ‘CF’
+# Cloudflare IPv4 ranges — update periodically
 # https://www.cloudflare.com/ips-v4/
 set_real_ip_from 173.245.48.0/20;
 set_real_ip_from 103.21.244.0/22;
@@ -342,7 +348,7 @@ real_ip_header CF-Connecting-IP;
 CF
 ```
 
-Adicionar no `nginx.conf` dentro do bloco `http {}`:
+Add the following to `nginx.conf` inside the `http {}` block:
 
 ```nginx
 include /etc/nginx/cloudflare-ips.conf;
@@ -355,45 +361,45 @@ apt install -y fail2ban
 systemctl enable fail2ban
 systemctl start fail2ban
 
-# Verificar status
+# Check status
 fail2ban-client status sshd
 ```
 
-### Bloquear acesso direto na porta do Docker
+### Block direct access to the Docker port
 
 ```bash
-# Impedir acesso externo direto à porta 20128
+# Prevent direct external access to port 20128
 iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP
 iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT
 
-# Persistir as regras
+# Persist the rules
 apt install -y iptables-persistent
 netfilter-persistent save
 ```
 
 ---
 
-## 7. Deploy do Cloud Worker (Opcional)
+## 7. Deploy to Cloudflare Workers (Optional)
 
-Para acesso remoto via Cloudflare Workers (sem expor a VM diretamente):
+For remote access via Cloudflare Workers (without exposing the VM directly):
 
 ```bash
-# No repositório local
+# In the local repository
 cd omnirouteCloud
 npm install
 npx wrangler login
 npx wrangler deploy
 ```
 
-Ver documentação completa em [omnirouteCloud/README.md](../omnirouteCloud/README.md).
+See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md).
 
 ---
 
-## Resumo de Portas
+## Port Summary
 
-| Porta | Serviço     | Acesso                        |
-| ----- | ----------- | ----------------------------- |
-| 22    | SSH         | Público (com fail2ban)        |
-| 80    | nginx HTTP  | Redirect → HTTPS              |
-| 443   | nginx HTTPS | Via Cloudflare Proxy          |
-| 20128 | OmniRoute   | Somente localhost (via nginx) |
+| Port  | Service     | Access                     |
+| ----- | ----------- | -------------------------- |
+| 22    | SSH         | Public (with fail2ban)     |
+| 80    | nginx HTTP  | Redirect → HTTPS           |
+| 443   | nginx HTTPS | Via Cloudflare Proxy       |
+| 20128 | OmniRoute   | Localhost only (via nginx) |

docs/i18n/README.md

@@ -1,12 +1,38 @@
-# Multilingual Documentation
+# 🌐 Multilingual Documentation — 9router
 
-This directory contains machine-assisted translations based on the English docs.
+Translations of documentation into 32 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)
+- 🇮🇳 **हिन्दी** (`hi`): [Docs Root](./hi/README.md)
+- 🇮🇳 **हिन्दी (IN)** (`in`): [Docs Root](./in/README.md)
+- 🇹🇭 **ไทย** (`th`): [Docs Root](./th/README.md)
+- 🇻🇳 **Tiếng Việt** (`vi`): [Docs Root](./vi/README.md)
+- 🇮🇩 **Bahasa Indonesia** (`id`): [Docs Root](./id/README.md)
+- 🇲🇾 **Bahasa Melayu** (`ms`): [Docs Root](./ms/README.md)
+- 🇳🇱 **Nederlands** (`nl`): [Docs Root](./nl/README.md)
+- 🇵🇱 **Polski** (`pl`): [Docs Root](./pl/README.md)
+- 🇸🇪 **Svenska** (`sv`): [Docs Root](./sv/README.md)
+- 🇳🇴 **Norsk** (`no`): [Docs Root](./no/README.md)
+- 🇩🇰 **Dansk** (`da`): [Docs Root](./da/README.md)
+- 🇫🇮 **Suomi** (`fi`): [Docs Root](./fi/README.md)
+- 🇵🇹 **Português (Portugal)** (`pt`): [Docs Root](./pt/README.md)
+- 🇷🇴 **Română** (`ro`): [Docs Root](./ro/README.md)
+- 🇭🇺 **Magyar** (`hu`): [Docs Root](./hu/README.md)
+- 🇧🇬 **Български** (`bg`): [Docs Root](./bg/README.md)
+- 🇸🇰 **Slovenčina** (`sk`): [Docs Root](./sk/README.md)
+- 🇺🇦 **Українська** (`uk-UA`): [Docs Root](./uk-UA/README.md)
+- 🇮🇱 **עברית** (`he`): [Docs Root](./he/README.md)
+- 🇵🇭 **Filipino** (`phi`): [Docs Root](./phi/README.md)
+- 🇧🇷 **Português (Brasil)** (`pt-BR`): [Docs Root](./pt-BR/README.md)
+- 🇨🇿 **Čeština** (`cs`): [Docs Root](./cs/README.md)
+- 🇹🇷 **Türkçe** (`tr`): [Docs Root](./tr/README.md)

docs/i18n/ar/A2A-SERVER.md

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

docs/i18n/ar/API_REFERENCE.md

@@ -1,455 +0,0 @@
-🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/API_REFERENCE.md) · 🇪🇸 [es](../es/API_REFERENCE.md) · 🇫🇷 [fr](../fr/API_REFERENCE.md) · 🇩🇪 [de](../de/API_REFERENCE.md) · 🇮🇹 [it](../it/API_REFERENCE.md) · 🇷🇺 [ru](../ru/API_REFERENCE.md) · 🇨🇳 [zh-CN](../zh-CN/API_REFERENCE.md) · 🇯🇵 [ja](../ja/API_REFERENCE.md) · 🇰🇷 [ko](../ko/API_REFERENCE.md) · 🇸🇦 [ar](../ar/API_REFERENCE.md) · 🇮🇳 [in](../in/API_REFERENCE.md) · 🇹🇭 [th](../th/API_REFERENCE.md) · 🇻🇳 [vi](../vi/API_REFERENCE.md) · 🇮🇩 [id](../id/API_REFERENCE.md) · 🇲🇾 [ms](../ms/API_REFERENCE.md) · 🇳🇱 [nl](../nl/API_REFERENCE.md) · 🇵🇱 [pl](../pl/API_REFERENCE.md) · 🇸🇪 [sv](../sv/API_REFERENCE.md) · 🇳🇴 [no](../no/API_REFERENCE.md) · 🇩🇰 [da](../da/API_REFERENCE.md) · 🇫🇮 [fi](../fi/API_REFERENCE.md) · 🇵🇹 [pt](../pt/API_REFERENCE.md) · 🇷🇴 [ro](../ro/API_REFERENCE.md) · 🇭🇺 [hu](../hu/API_REFERENCE.md) · 🇧🇬 [bg](../bg/API_REFERENCE.md) · 🇸🇰 [sk](../sk/API_REFERENCE.md) · 🇺🇦 [uk-UA](../uk-UA/API_REFERENCE.md) · 🇮🇱 [he](../he/API_REFERENCE.md) · 🇵🇭 [phi](../phi/API_REFERENCE.md)
-
----
-
-# API Reference
-
-🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md)
-
-Complete reference for all OmniRoute API endpoints.
-
----
-
-## Table of Contents
-
-- [Chat Completions](#chat-completions)
-- [Embeddings](#embeddings)
-- [Image Generation](#image-generation)
-- [List Models](#list-models)
-- [Compatibility Endpoints](#compatibility-endpoints)
-- [Semantic Cache](#semantic-cache)
-- [Dashboard & Management](#dashboard--management)
-- [Request Processing](#request-processing)
-- [Authentication](#authentication)
-
----
-
-## Chat Completions
-
-```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
-}
-```
-
-### 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 |
-
----
-
-## Embeddings
-
-```bash
-POST /v1/embeddings
-Authorization: Bearer your-api-key
-Content-Type: application/json
-
-{
-  "model": "nebius/Qwen/Qwen3-Embedding-8B",
-  "input": "The food was delicious"
-}
-```
-
-Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
-
-```bash
-# List all embedding models
-GET /v1/embeddings
-```
-
----
-
-## Image Generation
-
-```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"
-}
-```
-
-Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
-
-```bash
-# List all image models
-GET /v1/images/generations
-```
-
----
-
-## List Models
-
-```bash
-GET /v1/models
-Authorization: Bearer your-api-key
-
-→ Returns all chat, embedding, and image models + combos in OpenAI format
-```
-
----
-
-## Compatibility Endpoints
-
-| Method | Path                        | Format                 |
-| ------ | --------------------------- | ---------------------- |
-| POST   | `/v1/chat/completions`      | OpenAI                 |
-| POST   | `/v1/messages`              | Anthropic              |
-| POST   | `/v1/responses`             | OpenAI Responses       |
-| POST   | `/v1/embeddings`            | OpenAI                 |
-| POST   | `/v1/images/generations`    | OpenAI                 |
-| GET    | `/v1/models`                | OpenAI                 |
-| POST   | `/v1/messages/count_tokens` | Anthropic              |
-| GET    | `/v1beta/models`            | Gemini                 |
-| POST   | `/v1beta/models/{...path}`  | Gemini generateContent |
-| POST   | `/v1/api/chat`              | Ollama                 |
-
-### Dedicated Provider Routes
-
-```bash
-POST /v1/providers/{provider}/chat/completions
-POST /v1/providers/{provider}/embeddings
-POST /v1/providers/{provider}/images/generations
-```
-
-The provider prefix is auto-added if missing. Mismatched models return `400`.
-
----
-
-## Semantic Cache
-
-```bash
-# Get cache stats
-GET /api/cache
-
-# Clear all caches
-DELETE /api/cache
-```
-
-Response example:
-
-```json
-{
-  "semanticCache": {
-    "memorySize": 42,
-    "memoryMaxSize": 500,
-    "dbSize": 128,
-    "hitRate": 0.65
-  },
-  "idempotency": {
-    "activeKeys": 3,
-    "windowMs": 5000
-  }
-}
-```
-
----
-
-## Dashboard & Management
-
-### Authentication
-
-| Endpoint                      | Method  | Description           |
-| ----------------------------- | ------- | --------------------- |
-| `/api/auth/login`             | POST    | Login                 |
-| `/api/auth/logout`            | POST    | Logout                |
-| `/api/settings/require-login` | GET/PUT | Toggle login required |
-
-### Provider Management
-
-| Endpoint                     | Method          | Description              |
-| ---------------------------- | --------------- | ------------------------ |
-| `/api/providers`             | GET/POST        | List / create providers  |
-| `/api/providers/[id]`        | GET/PUT/DELETE  | Manage a provider        |
-| `/api/providers/[id]/test`   | POST            | Test provider connection |
-| `/api/providers/[id]/models` | GET             | List provider models     |
-| `/api/providers/validate`    | POST            | Validate provider config |
-| `/api/provider-nodes*`       | Various         | Provider node management |
-| `/api/provider-models`       | GET/POST/DELETE | Custom models            |
-
-### OAuth Flows
-
-| Endpoint                         | Method  | Description             |
-| -------------------------------- | ------- | ----------------------- |
-| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth |
-
-### Routing & Config
-
-| Endpoint              | Method   | Description                   |
-| --------------------- | -------- | ----------------------------- |
-| `/api/models/alias`   | GET/POST | Model aliases                 |
-| `/api/models/catalog` | GET      | All models by provider + type |
-| `/api/combos*`        | Various  | Combo management              |
-| `/api/keys*`          | Various  | API key management            |
-| `/api/pricing`        | GET      | Model pricing                 |
-
-### Usage & Analytics
-
-| Endpoint                    | Method | Description          |
-| --------------------------- | ------ | -------------------- |
-| `/api/usage/history`        | GET    | Usage history        |
-| `/api/usage/logs`           | GET    | Usage logs           |
-| `/api/usage/request-logs`   | GET    | Request-level logs   |
-| `/api/usage/[connectionId]` | GET    | Per-connection usage |
-
-### Settings
-
-| Endpoint                        | Method  | Description            |
-| ------------------------------- | ------- | ---------------------- |
-| `/api/settings`                 | GET/PUT | General settings       |
-| `/api/settings/proxy`           | GET/PUT | Network proxy config   |
-| `/api/settings/proxy/test`      | POST    | Test proxy connection  |
-| `/api/settings/ip-filter`       | GET/PUT | IP allowlist/blocklist |
-| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget |
-| `/api/settings/system-prompt`   | GET/PUT | Global system prompt   |
-
-### Monitoring
-
-| Endpoint                 | Method     | Description             |
-| ------------------------ | ---------- | ----------------------- |
-| `/api/sessions`          | GET        | Active session tracking |
-| `/api/rate-limits`       | GET        | Per-account rate limits |
-| `/api/monitoring/health` | GET        | Health check            |
-| `/api/cache`             | GET/DELETE | Cache stats / clear     |
-
-### Backup & Export/Import
-
-| Endpoint                    | Method | Description                             |
-| --------------------------- | ------ | --------------------------------------- |
-| `/api/db-backups`           | GET    | List available backups                  |
-| `/api/db-backups`           | PUT    | Create a manual backup                  |
-| `/api/db-backups`           | POST   | Restore from a specific backup          |
-| `/api/db-backups/export`    | GET    | Download database as .sqlite file       |
-| `/api/db-backups/import`    | POST   | Upload .sqlite file to replace database |
-| `/api/db-backups/exportAll` | GET    | Download full backup as .tar.gz archive |
-
-### Cloud Sync
-
-| Endpoint               | Method  | Description           |
-| ---------------------- | ------- | --------------------- |
-| `/api/sync/cloud`      | Various | Cloud sync operations |
-| `/api/sync/initialize` | POST    | Initialize sync       |
-| `/api/cloud/*`         | Various | Cloud management      |
-
-### CLI Tools
-
-| Endpoint                           | Method | Description         |
-| ---------------------------------- | ------ | ------------------- |
-| `/api/cli-tools/claude-settings`   | GET    | Claude CLI status   |
-| `/api/cli-tools/codex-settings`    | GET    | Codex CLI status    |
-| `/api/cli-tools/droid-settings`    | GET    | Droid CLI status    |
-| `/api/cli-tools/openclaw-settings` | GET    | OpenClaw CLI status |
-| `/api/cli-tools/runtime/[toolId]`  | GET    | Generic CLI runtime |
-
-CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
-
-### ACP Agents
-
-| Endpoint          | Method | Description                                              |
-| ----------------- | ------ | -------------------------------------------------------- |
-| `/api/acp/agents` | GET    | List all detected agents (built-in + custom) with status |
-| `/api/acp/agents` | POST   | Add custom agent or refresh detection cache              |
-| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param                |
-
-GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom).
-
-### Resilience & Rate Limits
-
-| Endpoint                | Method  | Description                     |
-| ----------------------- | ------- | ------------------------------- |
-| `/api/resilience`       | GET/PUT | Get/update resilience profiles  |
-| `/api/resilience/reset` | POST    | Reset circuit breakers          |
-| `/api/rate-limits`      | GET     | Per-account rate limit status   |
-| `/api/rate-limit`       | GET     | Global rate limit configuration |
-
-### Evals
-
-| Endpoint     | Method   | Description                       |
-| ------------ | -------- | --------------------------------- |
-| `/api/evals` | GET/POST | List eval suites / run evaluation |
-
-### Policies
-
-| Endpoint        | Method          | Description             |
-| --------------- | --------------- | ----------------------- |
-| `/api/policies` | GET/POST/DELETE | Manage routing policies |
-
-### Compliance
-
-| Endpoint                    | Method | Description                   |
-| --------------------------- | ------ | ----------------------------- |
-| `/api/compliance/audit-log` | GET    | Compliance audit log (last N) |
-
-### v1beta (Gemini-Compatible)
-
-| Endpoint                   | Method | Description                       |
-| -------------------------- | ------ | --------------------------------- |
-| `/v1beta/models`           | GET    | List models in Gemini format      |
-| `/v1beta/models/{...path}` | POST   | Gemini `generateContent` endpoint |
-
-These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility.
-
-### Internal / System APIs
-
-| Endpoint        | Method | Description                                          |
-| --------------- | ------ | ---------------------------------------------------- |
-| `/api/init`     | GET    | Application initialization check (used on first run) |
-| `/api/tags`     | GET    | Ollama-compatible model tags (for Ollama clients)    |
-| `/api/restart`  | POST   | Trigger graceful server restart                      |
-| `/api/shutdown` | POST   | Trigger graceful server shutdown                     |
-
-> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users.
-
----
-
-## Audio Transcription
-
-```bash
-POST /v1/audio/transcriptions
-Authorization: Bearer your-api-key
-Content-Type: multipart/form-data
-```
-
-Transcribe audio files using Deepgram or AssemblyAI.
-
-**Request:**
-
-```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"
-```
-
-**Response:**
-
-```json
-{
-  "text": "Hello, this is the transcribed audio content.",
-  "task": "transcribe",
-  "language": "en",
-  "duration": 12.5
-}
-```
-
-**Supported providers:** `deepgram/nova-3`, `assemblyai/best`.
-
-**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-
----
-
-## Ollama Compatibility
-
-For clients that use Ollama's API format:
-
-```bash
-# Chat endpoint (Ollama format)
-POST /v1/api/chat
-
-# Model listing (Ollama format)
-GET /api/tags
-```
-
-Requests are automatically translated between Ollama and internal formats.
-
----
-
-## Telemetry
-
-```bash
-# Get latency telemetry summary (p50/p95/p99 per provider)
-GET /api/telemetry/summary
-```
-
-**Response:**
-
-```json
-{
-  "providers": {
-    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
-    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
-  }
-}
-```
-
----
-
-## Budget
-
-```bash
-# Get budget status for all API keys
-GET /api/usage/budget
-
-# Set or update a budget
-POST /api/usage/budget
-Content-Type: application/json
-
-{
-  "keyId": "key-123",
-  "limit": 50.00,
-  "period": "monthly"
-}
-```
-
----
-
-## Model Availability
-
-```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"
-}
-```
-
----
-
-## Request Processing
-
-1. Client sends request to `/v1/*`
-2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration`
-3. Model is resolved (direct provider/model or alias/combo)
-4. Credentials selected from local DB with account availability filtering
-5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check
-6. Provider executor sends upstream request
-7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio)
-8. Usage/logging recorded
-9. Fallback applies on errors according to combo rules
-
-Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md)
-
----
-
-## Authentication
-
-- Dashboard routes (`/dashboard/*`) use `auth_token` cookie
-- Login uses saved password hash; fallback to `INITIAL_PASSWORD`
-- `requireLogin` toggleable via `/api/settings/require-login`
-- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true`

docs/i18n/ar/AUTO-COMBO.md

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

docs/i18n/ar/CONTRIBUTING.md

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

docs/i18n/ar/FEATURES.md

@@ -1,148 +0,0 @@
-🌐 **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](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md)
-
-Visual guide to every section of the OmniRoute dashboard.
-
----
-
-## 🔌 Providers
-
-Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro).
-
-- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` (free "Light usage" tier); use `ollamacloud/<model>` prefix
-
-![Providers Dashboard](screenshots/01-providers.png)
-
----
-
-## 🎨 Combos
-
-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
-- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
-- **Routing** — Model aliases, background task degradation
-- **Resilience** — Rate limit persistence, circuit breaker tuning
-- **Advanced** — Configuration overrides
-
-![Settings Dashboard](screenshots/06-settings.png)
-
----
-
-## 🔧 CLI Tools
-
-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. Cloud proxy support for remote access.
-
-![Endpoint Dashboard](screenshots/09-endpoint.png)
-
----
-
-## 🔑 API Key Management
-
-Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
-
----
-
-## 📋 Audit Log
-
-Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
-
----
-
-## 🖥️ Desktop Application
-
-Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
-
-Key features:
-
-- Server readiness polling (no blank screen on cold start)
-- System tray with port management
-- Content Security Policy
-- Single-instance lock
-- Auto-update on restart
-- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
-
-📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/ar/MCP-SERVER.md

@@ -1,87 +0,0 @@
-🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/MCP-SERVER.md) · 🇪🇸 [es](../es/MCP-SERVER.md) · 🇫🇷 [fr](../fr/MCP-SERVER.md) · 🇩🇪 [de](../de/MCP-SERVER.md) · 🇮🇹 [it](../it/MCP-SERVER.md) · 🇷🇺 [ru](../ru/MCP-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/MCP-SERVER.md) · 🇯🇵 [ja](../ja/MCP-SERVER.md) · 🇰🇷 [ko](../ko/MCP-SERVER.md) · 🇸🇦 [ar](../ar/MCP-SERVER.md) · 🇮🇳 [in](../in/MCP-SERVER.md) · 🇹🇭 [th](../th/MCP-SERVER.md) · 🇻🇳 [vi](../vi/MCP-SERVER.md) · 🇮🇩 [id](../id/MCP-SERVER.md) · 🇲🇾 [ms](../ms/MCP-SERVER.md) · 🇳🇱 [nl](../nl/MCP-SERVER.md) · 🇵🇱 [pl](../pl/MCP-SERVER.md) · 🇸🇪 [sv](../sv/MCP-SERVER.md) · 🇳🇴 [no](../no/MCP-SERVER.md) · 🇩🇰 [da](../da/MCP-SERVER.md) · 🇫🇮 [fi](../fi/MCP-SERVER.md) · 🇵🇹 [pt](../pt/MCP-SERVER.md) · 🇷🇴 [ro](../ro/MCP-SERVER.md) · 🇭🇺 [hu](../hu/MCP-SERVER.md) · 🇧🇬 [bg](../bg/MCP-SERVER.md) · 🇸🇰 [sk](../sk/MCP-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/MCP-SERVER.md) · 🇮🇱 [he](../he/MCP-SERVER.md) · 🇵🇭 [phi](../phi/MCP-SERVER.md)
-
----
-
-# OmniRoute MCP Server Documentation
-
-> Model Context Protocol server with 16 intelligent tools
-
-## Installation
-
-OmniRoute MCP is built-in. Start it with:
-
-```bash
-omniroute --mcp
-```
-
-Or via the open-sse transport:
-
-```bash
-# HTTP streamable transport (port 20130)
-omniroute --dev  # MCP auto-starts on /mcp endpoint
-```
-
-## IDE Configuration
-
-See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup.
-
----
-
-## Essential Tools (8)
-
-| Tool                            | Description                              |
-| :------------------------------ | :--------------------------------------- |
-| `omniroute_get_health`          | Gateway health, circuit breakers, uptime |
-| `omniroute_list_combos`         | All configured combos with models        |
-| `omniroute_get_combo_metrics`   | Performance metrics for a specific combo |
-| `omniroute_switch_combo`        | Switch active combo by ID/name           |
-| `omniroute_check_quota`         | Quota status per provider or all         |
-| `omniroute_route_request`       | Send a chat completion through OmniRoute |
-| `omniroute_cost_report`         | Cost analytics for a time period         |
-| `omniroute_list_models_catalog` | Full model catalog with capabilities     |
-
-## Advanced Tools (8)
-
-| Tool                               | Description                                     |
-| :--------------------------------- | :---------------------------------------------- |
-| `omniroute_simulate_route`         | Dry-run routing simulation with fallback tree   |
-| `omniroute_set_budget_guard`       | Session budget with degrade/block/alert actions |
-| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset   |
-| `omniroute_test_combo`             | Live-test all models in a combo                 |
-| `omniroute_get_provider_metrics`   | Detailed metrics for one provider               |
-| `omniroute_best_combo_for_task`    | Task-fitness recommendation with alternatives   |
-| `omniroute_explain_route`          | Explain a past routing decision                 |
-| `omniroute_get_session_snapshot`   | Full session state: costs, tokens, errors       |
-
-## Authentication
-
-MCP tools are authenticated via API key scopes. Each tool requires specific scopes:
-
-| Scope          | Tools                                            |
-| :------------- | :----------------------------------------------- |
-| `read:health`  | get_health, get_provider_metrics                 |
-| `read:combos`  | list_combos, get_combo_metrics                   |
-| `write:combos` | switch_combo                                     |
-| `read:quota`   | check_quota                                      |
-| `write:route`  | route_request, simulate_route, test_combo        |
-| `read:usage`   | cost_report, get_session_snapshot, explain_route |
-| `write:config` | set_budget_guard, set_resilience_profile         |
-| `read:models`  | list_models_catalog, best_combo_for_task         |
-
-## Audit Logging
-
-Every tool call is logged to `mcp_tool_audit` with:
-
-- Tool name, arguments, result
-- Duration (ms), success/failure
-- API key hash, timestamp
-
-## Files
-
-| File                                         | Purpose                                     |
-| :------------------------------------------- | :------------------------------------------ |
-| `open-sse/mcp-server/server.ts`              | MCP server creation + 16 tool registrations |
-| `open-sse/mcp-server/transport.ts`           | Stdio + HTTP transport                      |
-| `open-sse/mcp-server/auth.ts`                | API key + scope validation                  |
-| `open-sse/mcp-server/audit.ts`               | Tool call audit logging                     |
-| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers                    |

docs/i18n/ar/RELEASE_CHECKLIST.md

@@ -1,37 +0,0 @@
-🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) · 🇪🇸 [es](../es/RELEASE_CHECKLIST.md) · 🇫🇷 [fr](../fr/RELEASE_CHECKLIST.md) · 🇩🇪 [de](../de/RELEASE_CHECKLIST.md) · 🇮🇹 [it](../it/RELEASE_CHECKLIST.md) · 🇷🇺 [ru](../ru/RELEASE_CHECKLIST.md) · 🇨🇳 [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) · 🇯🇵 [ja](../ja/RELEASE_CHECKLIST.md) · 🇰🇷 [ko](../ko/RELEASE_CHECKLIST.md) · 🇸🇦 [ar](../ar/RELEASE_CHECKLIST.md) · 🇮🇳 [in](../in/RELEASE_CHECKLIST.md) · 🇹🇭 [th](../th/RELEASE_CHECKLIST.md) · 🇻🇳 [vi](../vi/RELEASE_CHECKLIST.md) · 🇮🇩 [id](../id/RELEASE_CHECKLIST.md) · 🇲🇾 [ms](../ms/RELEASE_CHECKLIST.md) · 🇳🇱 [nl](../nl/RELEASE_CHECKLIST.md) · 🇵🇱 [pl](../pl/RELEASE_CHECKLIST.md) · 🇸🇪 [sv](../sv/RELEASE_CHECKLIST.md) · 🇳🇴 [no](../no/RELEASE_CHECKLIST.md) · 🇩🇰 [da](../da/RELEASE_CHECKLIST.md) · 🇫🇮 [fi](../fi/RELEASE_CHECKLIST.md) · 🇵🇹 [pt](../pt/RELEASE_CHECKLIST.md) · 🇷🇴 [ro](../ro/RELEASE_CHECKLIST.md) · 🇭🇺 [hu](../hu/RELEASE_CHECKLIST.md) · 🇧🇬 [bg](../bg/RELEASE_CHECKLIST.md) · 🇸🇰 [sk](../sk/RELEASE_CHECKLIST.md) · 🇺🇦 [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) · 🇮🇱 [he](../he/RELEASE_CHECKLIST.md) · 🇵🇭 [phi](../phi/RELEASE_CHECKLIST.md)
-
----
-
-# Release Checklist
-
-Use this checklist before tagging or publishing a new OmniRoute release.
-
-## Version and Changelog
-
-1. Bump `package.json` version (`x.y.z`) in the release branch.
-2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section:
-   - `## [x.y.z] — YYYY-MM-DD`
-3. Keep `## [Unreleased]` as the first changelog section for upcoming work.
-4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version.
-
-## API Docs
-
-1. Update `docs/openapi.yaml`:
-   - `info.version` must equal `package.json` version.
-2. Validate endpoint examples if API contracts changed.
-
-## Runtime Docs
-
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
-3. Update localized docs if source docs changed significantly.
-
-## Automated Check
-
-Run the sync guard locally before opening PR:
-
-```bash
-npm run check:docs-sync
-```
-
-CI also runs this check in `.github/workflows/ci.yml` (lint job).

docs/i18n/ar/SECURITY.md

@@ -0,0 +1,141 @@
+# Security Policy (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../SECURITY.md) · 🇪🇸 [es](../es/SECURITY.md) · 🇫🇷 [fr](../fr/SECURITY.md) · 🇩🇪 [de](../de/SECURITY.md) · 🇮🇹 [it](../it/SECURITY.md) · 🇷🇺 [ru](../ru/SECURITY.md) · 🇨🇳 [zh-CN](../zh-CN/SECURITY.md) · 🇯🇵 [ja](../ja/SECURITY.md) · 🇰🇷 [ko](../ko/SECURITY.md) · 🇸🇦 [ar](../ar/SECURITY.md) · 🇮🇳 [hi](../hi/SECURITY.md) · 🇮🇳 [in](../in/SECURITY.md) · 🇹🇭 [th](../th/SECURITY.md) · 🇻🇳 [vi](../vi/SECURITY.md) · 🇮🇩 [id](../id/SECURITY.md) · 🇲🇾 [ms](../ms/SECURITY.md) · 🇳🇱 [nl](../nl/SECURITY.md) · 🇵🇱 [pl](../pl/SECURITY.md) · 🇸🇪 [sv](../sv/SECURITY.md) · 🇳🇴 [no](../no/SECURITY.md) · 🇩🇰 [da](../da/SECURITY.md) · 🇫🇮 [fi](../fi/SECURITY.md) · 🇵🇹 [pt](../pt/SECURITY.md) · 🇷🇴 [ro](../ro/SECURITY.md) · 🇭🇺 [hu](../hu/SECURITY.md) · 🇧🇬 [bg](../bg/SECURITY.md) · 🇸🇰 [sk](../sk/SECURITY.md) · 🇺🇦 [uk-UA](../uk-UA/SECURITY.md) · 🇮🇱 [he](../he/SECURITY.md) · 🇵🇭 [phi](../phi/SECURITY.md) · 🇧🇷 [pt-BR](../pt-BR/SECURITY.md) · 🇨🇿 [cs](../cs/SECURITY.md) · 🇹🇷 [tr](../tr/SECURITY.md)
+
+---
+
+## Reporting Vulnerabilities
+
+إذا وجدت ثغرة أمنية في OmniRoute، فيرجى إمدادها بطريقة مختلفة:
+
+1.**لا**تفتح مشكلة عامة على GitHub 2. استخدم [GitHub Security Advisories](https://github.com/diegosouzapw/OmniRoute/security/advisories/new) 3. تشمل: الوصف، وخطوات الاستنساخ، والأثر للمناسب## Response Timeline
+
+| المرحلة        | الهدف                    |
+| -------------- | ------------------------ | --------- |
+| شكر وتقدير     | 48 ساعة                  |
+| الفرز والتقييم | 5 أيام عمل               |
+| الإصدار        | التعديل 14 يوم عمل (حرج) | # التغيير |
+
+| النسخة  | حالة الدعم   |
+| ------- | ------------ | -------------------- |
+| 3.4.x   | ✅ المشتريات |
+| 3.0.x   | ✅ الأمان    |
+| < 3.0.0 | ❌ غير مدعوم | ---## البنية الأمنية |
+
+تم تطبيق نموذج OmniRoute متعدد الأمان: `
+طلب ← CORS ← مصادقة مفتاح API ← منع الاشتراك الرسمي ← معقم الإدخال ← محدد المعدل ← قاطع ← الموفر`### 🔐 Authentication & Authorization
+
+| غرض                                    | التنفيذ                                                                        |
+| -------------------------------------- | ------------------------------------------------------------------------------ | ------------------------- |
+| **تسجيل الدخول إلى لوحة التحكم**       | اعتماد تعتمد على كلمة المرور باستخدام رموز JWT (ملفات تعريف الارتباط HttpOnly) |
+| **مصادقة مفتاح واجهة برمجة التطبيقات** | مفاتيح موقعة من HMAC مع التحقق من صحة CRC                                      |
+| **OAuth 2.0 + PKCE**                   | مصادقة الموفر المنشط (Claude، Codex، Gemini، Cursor، إلخ)                      |
+| **تحديث الرمز المميز**                 | التحديث التلقائي لرمز OAuth قبل انتهاء الصلاحية                                |
+| **ملفات تعريف الارتباط التنسيقة**      | `AUTH_COOKIE_SECURE=true` لبيئات HTTPS                                         |
+| **نطاقات MCP**                         | 10 نطاقات تفصيلية للتحكم في الوصول إلى أداة MCP                                | ### 🛡️ التشفير عند الراحة |
+
+يتم قراءة كافة التفاصيل المخزنة في SQLite باستخدام**AES-256-GCM**مع اشتقاق مفتاح التشفير:
+
+- لوحة مفاتيح برمجة التطبيقات، ورموز الوصول، ورموز التحديث، والرموز المعروفة
+- النسخة البرتغالية: `enc:v1:<iv>:<ciphertext>:<authTag>`
+- وضع العبور (نص عادي) عندما لا يتم تعيين `STORAGE_ENCRYPTION_KEY````bash
+
+# إنشاء مفتاح التشفير:
+
+STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)```
+
+### 🧠 Prompt Injection Guard
+
+بسبب الوسيطة التي تكتشف وتمنع الهجمات الرابعة في طلبات LLM:
+
+| نوع النمط           | دان   | مثال                             |
+| ------------------- | ----- | -------------------------------- |
+| تجاوز النظام        | عالية | " تجاهل كافة التعليمات السابقة"  |
+| اختطاف الدور        | عالية | "أنت الآن دان، يمكنك فعل أي شيء" |
+| لغرض الشفاء         | مي    | فواصل مشفرة لكسر نطاق السياقة    |
+| دان/الهروب من السجن | عالية | أسباب مطالبة الهروب من السجن     |
+| تسرب التعليمات      | مي    | "أرني متشوق النظام الخاص بك"     |
+
+قم بالتكوين عبر معلومات اللوحة (الإعدادات → الأمان) أو `.env`:`env
+INPUT_SANITIZER_ENABLED=صحيح
+INPUT_SANITIZER_MODE=block # تحذير | كتلة | تنقيح`
+
+### 🔒 PII Redaction
+
+الكشف التلقائي والتنقيح الاختياري لمعلومات التعريف الشخصية:
+
+| نوع معلومات تحديد الهوية الشخصية    | نمط                   | الاستبدال          |
+| ----------------------------------- | --------------------- | ------------------ | ------ |
+| البريد الإلكتروني                   | `user@domain.com`     | `[EMAIL_REDACTED]` |
+| CPF (البرازيل)                      | `123.456.789-00`      | `[CPF_REDACTED]`   |
+| CNPJ (البرازيل)                     | `12.345.678/0001-00`  | `[CNPJ_REDACTED]`  |
+| بطاقة الائتمان                      | `4111-1111-1111-1111` | `[CC_REDACTED]`    |
+| هاتف                                | `+55 11 99999-9999`   | `[PHONE_REDACTED]` |
+| الضمان الاجتماعي (الولايات المتحدة) | `123-45-6789`         | `[SSN_REDACTED]`   | ```env |
+
+PII_REDACTION_ENABLED=true
+
+````
+
+### 🌐 Network Security
+
+| | الوصف |
+| ------------------------ | ---------------------------------------------------------------- |
+|**كورس**| أصلية قابلة للتكوين (`CORS_ORIGIN` env var، افتراضية `*`) |
+|**تصفية IP**| نطاقات IP المخصصة لها/القائمة المحظورة في لوحة المعلومات |
+|**تحديد المعدل**| حدود الحدود لكل الحدود بدقة تلقائية |
+|**القطيع الغذائي الرعد**| يمنع Mutex + القفل لكل اتصال 502s المتتالية |
+|**بصمة TLS**| انتحال بصمة TLS الشبيهة بالمتصفح الرئيسي لاكتشاف الروبوتات |
+|**بصمة سطر مود**| التنسيق/النص لكل موفر لمطابقة التوقيعات CLI الأصلية |### 🔌 متوافقة والتوافر
+
+| | الوصف |
+| ----------------------- | ------------------------------------------------------------------ |
+|**قاطع القراءات**| 3 حالات (مغلق → → مفتوح مفتوح) لكل، بسبب SQLite |
+|**طلب العجز**| نافذة dedup لمدة 5 ثواني للتحميلات المكررة |
+|**التراجع الأسي**| إعادة المحاولة الجديدة مع زيادة |
+|**لوحة المعلومات الصحية**| صحة لرعاية خدمة الوقت الحقيقي |### 📋 مراقبة كاملة
+
+| | الوصف |
+| ------------------ | ----------------------------------------------------------- |
+|**الاحتفاظ بالسجل**| التنظيف التلقائي بعد `CALL_LOG_RETENTION_DAYS` |
+|**إلغاء الاشتراك في عدم التسجيل**| تعمل علامة noLog لكل مفتاح API على تسجيل الطلبات |
+|**سجل التدقيق**| الإجراءات الإدارية التي تم تتبعها في جدول `audit_log` |
+|**تدقيق MCP**| تسجيل التدقيق التجاري من SQLite لجميع أدوات الاتصال MCP |
+|**التحقق من صحة زود**| تم التحقق من صحة جميع مدخلات واجهة برمجة التطبيقات (API) باستخدام مخططات Zod v4 عند تحميل الوحدة النموذجية |---## متغيرات البيئة المطلوبة
+
+يجب ضبط جميع الاستخدامات قبل إنشاء الضيوف. سوف يفشل العميل بسرعة**إذا كان مفقودًا أو ضعيف.```bash
+#مطلوب — لن يبدأ بدون ما يلي:
+JWT_SECRET=$(openssl rand -base64 48) # دقيقة 32 حرفًا
+API_KEY_SECRET=$(openssl rand -hex 32) # دقيقة 16 حرفًا
+
+#موصى به — يتيح التشفير في حالة عدم النشاط:
+STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)```
+
+يرفض المعلم تعلمياً القيم والضعيفة مثل `changeme` أو `secret` أو `password`.---## Docker Security
+
+- استخدم المستخدم غير جيجا في الإنتاج
+- منزل جبلار كمجلدات للقراءة فقط
+- لا تنسى أبدًا بنسخ ملفات `.env` إلى صور Docker
+- استخدام `.dockerignore` لاستبعاد الملفات الحساسة
+- اضبط `AUTH_COOKIE_SECURE=true` عندما يكون خلف HTTPS```bash
+تشغيل عامل الميناء -d \
+  --اسم الطريق الشامل \
+  --إعادة التشغيل ما لم تتوقف \
+  --للقراءة فقط \
+  -ص20128:20128\
+  -v بيانات المسار الشامل:/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```
+
+---
+
+## Dependencies
+
+- يسمح له بدقيق npm
+- حافظ على تحديثات التبعيات
+- يستخدم المشروع "husky" + "lint-staged" لفحوصات ما قبل التنفيذ
+- يقوم بخط أنابيب CI يسمح بمتطلبات أمان ESLint في كل خطوة
+- تم التحقق من صحة ثوابت الموفر عند تحميل الوحدة عبر Zod (`src/shared/validation/providerSchema.ts`)
+````

docs/i18n/ar/USER_GUIDE.md

@@ -1,813 +0,0 @@
-🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/USER_GUIDE.md) · 🇪🇸 [es](../es/USER_GUIDE.md) · 🇫🇷 [fr](../fr/USER_GUIDE.md) · 🇩🇪 [de](../de/USER_GUIDE.md) · 🇮🇹 [it](../it/USER_GUIDE.md) · 🇷🇺 [ru](../ru/USER_GUIDE.md) · 🇨🇳 [zh-CN](../zh-CN/USER_GUIDE.md) · 🇯🇵 [ja](../ja/USER_GUIDE.md) · 🇰🇷 [ko](../ko/USER_GUIDE.md) · 🇸🇦 [ar](../ar/USER_GUIDE.md) · 🇮🇳 [in](../in/USER_GUIDE.md) · 🇹🇭 [th](../th/USER_GUIDE.md) · 🇻🇳 [vi](../vi/USER_GUIDE.md) · 🇮🇩 [id](../id/USER_GUIDE.md) · 🇲🇾 [ms](../ms/USER_GUIDE.md) · 🇳🇱 [nl](../nl/USER_GUIDE.md) · 🇵🇱 [pl](../pl/USER_GUIDE.md) · 🇸🇪 [sv](../sv/USER_GUIDE.md) · 🇳🇴 [no](../no/USER_GUIDE.md) · 🇩🇰 [da](../da/USER_GUIDE.md) · 🇫🇮 [fi](../fi/USER_GUIDE.md) · 🇵🇹 [pt](../pt/USER_GUIDE.md) · 🇷🇴 [ro](../ro/USER_GUIDE.md) · 🇭🇺 [hu](../hu/USER_GUIDE.md) · 🇧🇬 [bg](../bg/USER_GUIDE.md) · 🇸🇰 [sk](../sk/USER_GUIDE.md) · 🇺🇦 [uk-UA](../uk-UA/USER_GUIDE.md) · 🇮🇱 [he](../he/USER_GUIDE.md) · 🇵🇭 [phi](../phi/USER_GUIDE.md)
-
----
-
-# User Guide
-
-🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md)
-
-Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
-
----
-
-## Table of Contents
-
-- [Pricing at a Glance](#-pricing-at-a-glance)
-- [Use Cases](#-use-cases)
-- [Provider Setup](#-provider-setup)
-- [CLI Integration](#-cli-integration)
-- [Deployment](#-deployment)
-- [Available Models](#-available-models)
-- [Advanced Features](#-advanced-features)
-
----
-
-## 💰 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**      | DeepSeek          | Pay per use | None             | Cheap reasoning      |
-|                     | Groq              | Pay per use | None             | Ultra-fast inference |
-|                     | xAI (Grok)        | Pay per use | None             | Grok 4 reasoning     |
-|                     | Mistral           | Pay per use | None             | EU-hosted models     |
-|                     | Perplexity        | Pay per use | None             | Search-augmented     |
-|                     | Together AI       | Pay per use | None             | Open-source models   |
-|                     | Fireworks AI      | Pay per use | None             | Fast FLUX images     |
-|                     | Cerebras          | Pay per use | None             | Wafer-scale speed    |
-|                     | Cohere            | Pay per use | None             | Command R+ RAG       |
-|                     | NVIDIA NIM        | Pay per use | None             | Enterprise models    |
-| **💰 CHEAP**        | GLM-4.7           | $0.6/1M     | Daily 10AM       | Budget backup        |
-|                     | MiniMax M2.1      | $0.2/1M     | 5-hour rolling   | Cheapest option      |
-|                     | Kimi K2           | $9/mo flat  | 10M tokens/mo    | Predictable cost     |
-| **🆓 FREE**         | iFlow             | $0          | Unlimited        | 8 models free        |
-|                     | Qwen              | $0          | Unlimited        | 3 models free        |
-|                     | Kiro              | $0          | Unlimited        | Claude free          |
-
-**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost!
-
----
-
-## 🎯 Use Cases
-
-### Case 1: "I have Claude Pro subscription"
-
-**Problem:** Quota expires unused, rate limits during heavy coding
-
-```
-Combo: "maximize-claude"
-  1. cc/claude-opus-4-6        (use subscription fully)
-  2. glm/glm-4.7               (cheap backup when quota out)
-  3. if/kimi-k2-thinking       (free emergency fallback)
-
-Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
-vs. $20 + hitting limits = frustration
-```
-
-### Case 2: "I want zero cost"
-
-**Problem:** Can't afford subscriptions, need reliable AI coding
-
-```
-Combo: "free-forever"
-  1. gc/gemini-3-flash         (180K free/month)
-  2. if/kimi-k2-thinking       (unlimited free)
-  3. qw/qwen3-coder-plus       (unlimited free)
-
-Monthly cost: $0
-Quality: Production-ready models
-```
-
-### Case 3: "I need 24/7 coding, no interruptions"
-
-**Problem:** Deadlines, can't afford downtime
-
-```
-Combo: "always-on"
-  1. cc/claude-opus-4-6        (best quality)
-  2. cx/gpt-5.2-codex          (second subscription)
-  3. glm/glm-4.7               (cheap, resets daily)
-  4. minimax/MiniMax-M2.1      (cheapest, 5h reset)
-  5. if/kimi-k2-thinking       (free unlimited)
-
-Result: 5 layers of fallback = zero downtime
-Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-```
-
-### Case 4: "I want FREE AI in OpenClaw"
-
-**Problem:** Need AI assistant in messaging apps, completely free
-
-```
-Combo: "openclaw-free"
-  1. if/glm-4.7                (unlimited free)
-  2. if/minimax-m2.1           (unlimited free)
-  3. if/kimi-k2-thinking       (unlimited free)
-
-Monthly cost: $0
-Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-```
-
----
-
-## 📖 Provider Setup
-
-### 🔐 Subscription Providers
-
-#### 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
-```
-
-**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per 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 (FREE 180K/month!)
-
-```bash
-Dashboard → Providers → Connect Gemini CLI
-→ Google OAuth
-→ 180K completions/month + 1K/day
-
-Models:
-  gc/gemini-3-flash-preview
-  gc/gemini-2.5-pro
-```
-
-**Best Value:** Huge free tier! Use this before paid tiers.
-
-#### 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
-```
-
-### 💰 Cheap Providers
-
-#### GLM-4.7 (Daily reset, $0.6/1M)
-
-1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)
-2. Get API key from Coding Plan
-3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`
-
-**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-
-#### MiniMax M2.1 (5h reset, $0.20/1M)
-
-1. Sign up: [MiniMax](https://www.minimax.io/)
-2. Get API key → Dashboard → Add API Key
-
-**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-
-#### Kimi K2 ($9/month flat)
-
-1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
-2. Get API key → Dashboard → Add API Key
-
-**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
-### 🆓 FREE Providers
-
-#### iFlow (8 FREE models)
-
-```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 FREE models)
-
-```bash
-Dashboard → Connect Qwen → Device code auth → Unlimited usage
-
-Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
-```
-
-#### Kiro (Claude FREE)
-
-```bash
-Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
-
-Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
-```
-
----
-
-## 🎨 Combos
-
-### Example 1: Maximize Subscription → Cheap Backup
-
-```
-Dashboard → Combos → Create New
-
-Name: premium-coding
-Models:
-  1. cc/claude-opus-4-6 (Subscription primary)
-  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
-  3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
-
-Use in CLI: premium-coding
-```
-
-### Example 2: Free-Only (Zero Cost)
-
-```
-Name: free-combo
-Models:
-  1. gc/gemini-3-flash-preview (180K free/month)
-  2. if/kimi-k2-thinking (unlimited)
-  3. qw/qwen3-coder-plus (unlimited)
-
-Cost: $0 forever!
-```
-
----
-
-## 🔧 CLI Integration
-
-### Cursor IDE
-
-```
-Settings → Models → Advanced:
-  OpenAI API Base URL: http://localhost:20128/v1
-  OpenAI API Key: [from omniroute dashboard]
-  Model: cc/claude-opus-4-6
-```
-
-### Claude Code
-
-Edit `~/.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
-
-Edit `~/.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" }]
-      }
-    }
-  }
-}
-```
-
-**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
-
-### Cline / Continue / RooCode
-
-```
-Provider: OpenAI Compatible
-Base URL: http://localhost:20128/v1
-API Key: [from dashboard]
-Model: cc/claude-opus-4-6
-```
-
----
-
-## 🚀 Deployment
-
-### Global npm install (Recommended)
-
-```bash
-npm install -g omniroute
-
-# Create config directory
-mkdir -p ~/.omniroute
-
-# Create .env file (see .env.example)
-cp .env.example ~/.omniroute/.env
-
-# Start server
-omniroute
-# Or with custom port:
-omniroute --port 3000
-```
-
-The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
-
-### VPS Deployment
-
-```bash
-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
-```
-
-### PM2 Deployment (Low Memory)
-
-For servers with limited RAM, use the memory limit option:
-
-```bash
-# With 512MB limit (default)
-pm2 start npm --name omniroute -- start
-
-# Or with custom memory limit
-OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
-
-# Or using ecosystem.config.js
-pm2 start ecosystem.config.js
-```
-
-Create `ecosystem.config.js`:
-
-```javascript
-module.exports = {
-  apps: [
-    {
-      name: "omniroute",
-      script: "npm",
-      args: "start",
-      env: {
-        NODE_ENV: "production",
-        OMNIROUTE_MEMORY_MB: "512",
-        JWT_SECRET: "your-secret",
-        INITIAL_PASSWORD: "your-password",
-      },
-      node_args: "--max-old-space-size=512",
-      max_memory_restart: "300M",
-    },
-  ],
-};
-```
-
-### Docker
-
-```bash
-# Build image (default = runner-cli with codex/claude/droid preinstalled)
-docker build -t omniroute:cli .
-
-# Portable mode (recommended)
-docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
-```
-
-For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-
-### 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                              |
-
-For the full environment variable reference, see the [README](../README.md).
-
----
-
-## 📊 Available Models
-
-<details>
-<summary><b>View all available models</b></summary>
-
-**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-
-**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-
-**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-
-**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-
-**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-
-**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-
-**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-
-**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-
-**Kiro (`kr/`)** — FREE: `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`
-
-**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-
-**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-
-**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-
-**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
-
-**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
-
-</details>
-
----
-
-## 🧩 Advanced Features
-
-### Custom Models
-
-Add any model ID to any provider without waiting for an app update:
-
-```bash
-# Via API
-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"
-```
-
-Or use Dashboard: **Providers → [Provider] → Custom Models**.
-
-### Dedicated Provider Routes
-
-Route requests directly to a specific provider with model validation:
-
-```bash
-POST http://localhost:20128/v1/providers/openai/chat/completions
-POST http://localhost:20128/v1/providers/openai/embeddings
-POST http://localhost:20128/v1/providers/fireworks/images/generations
-```
-
-The provider prefix is auto-added if missing. Mismatched models return `400`.
-
-### Network Proxy Configuration
-
-```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"}}'
-```
-
-**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
-
-### Model Catalog API
-
-```bash
-curl http://localhost:20128/api/models/catalog
-```
-
-Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-
-### Cloud Sync
-
-- Sync providers, combos, and settings across devices
-- Automatic background sync with timeout + fail-fast
-- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
-
-### LLM Gateway Intelligence (Phase 9)
-
-- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
-- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
-- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
-
----
-
-### Translator Playground
-
-Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-
-| Mode             | Purpose                                                                                |
-| ---------------- | -------------------------------------------------------------------------------------- |
-| **Playground**   | Select source/target formats, paste a request, and see the translated output instantly |
-| **Chat Tester**  | Send live chat messages through the proxy and inspect the full request/response cycle  |
-| **Test Bench**   | Run batch tests across multiple format combinations to verify translation correctness  |
-| **Live Monitor** | Watch real-time translations as requests flow through the proxy                        |
-
-**Use cases:**
-
-- Debug why a specific client/provider combination fails
-- Verify that thinking tags, tool calls, and system prompts translate correctly
-- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
-
----
-
-### Routing Strategies
-
-Configure via **Dashboard → Settings → Routing**.
-
-| Strategy                       | Description                                                                                      |
-| ------------------------------ | ------------------------------------------------------------------------------------------------ |
-| **Fill First**                 | Uses accounts in priority order — primary account handles all requests until unavailable         |
-| **Round Robin**                | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account)      |
-| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
-| **Random**                     | Randomly selects an account for each request using Fisher-Yates shuffle                          |
-| **Least Used**                 | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly        |
-| **Cost Optimized**             | Routes to the account with the lowest priority value, optimizing for lowest-cost providers       |
-
-#### Wildcard Model Aliases
-
-Create wildcard patterns to remap model names:
-
-```
-Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-*               →  Target: gh/gpt-5.1-codex
-```
-
-Wildcards support `*` (any characters) and `?` (single character).
-
-#### Fallback Chains
-
-Define global fallback chains that apply across all requests:
-
-```
-Chain: production-fallback
-  1. cc/claude-opus-4-6
-  2. gh/gpt-5.1-codex
-  3. glm/glm-4.7
-```
-
----
-
-### Resilience & Circuit Breakers
-
-Configure via **Dashboard → Settings → Resilience**.
-
-OmniRoute implements provider-level resilience with four components:
-
-1. **Provider Profiles** — Per-provider configuration for:
-   - Failure threshold (how many failures before opening)
-   - Cooldown duration
-   - Rate limit detection sensitivity
-   - Exponential backoff parameters
-
-2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
-   - **Requests Per Minute (RPM)** — Maximum requests per minute per account
-   - **Min Time Between Requests** — Minimum gap in milliseconds between requests
-   - **Max Concurrent Requests** — Maximum simultaneous requests per account
-   - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
-
-3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
-   - **CLOSED** (Healthy) — Requests flow normally
-   - **OPEN** — Provider is temporarily blocked after repeated failures
-   - **HALF_OPEN** — Testing if provider has recovered
-
-4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
-
-5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
-
-**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
-
----
-
-### Database Export / Import
-
-Manage database backups in **Dashboard → Settings → System & Storage**.
-
-| Action                   | Description                                                                                                                    |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
-| **Export Database**      | Downloads the current SQLite database as a `.sqlite` file                                                                      |
-| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
-| **Import Database**      | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created                          |
-
-```bash
-# API: Export database
-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"
-```
-
-**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-
-**Use Cases:**
-
-- Migrate OmniRoute between machines
-- Create external backups for disaster recovery
-- Share configurations between team members (export all → share archive)
-
----
-
-### Settings Dashboard
-
-The settings page is organized into 5 tabs for easy navigation:
-
-| Tab            | Contents                                                                                       |
-| -------------- | ---------------------------------------------------------------------------------------------- |
-| **Security**   | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking      |
-| **Routing**    | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults   |
-| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
-| **AI**         | Thinking budget configuration, global system prompt injection, prompt cache stats              |
-| **Advanced**   | Global proxy configuration (HTTP/SOCKS5)                                                       |
-
----
-
-### Costs & Budget Management
-
-Access via **Dashboard → Costs**.
-
-| Tab         | Purpose                                                                                  |
-| ----------- | ---------------------------------------------------------------------------------------- |
-| **Budget**  | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
-| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider       |
-
-```bash
-# API: Set a budget
-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
-```
-
-**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
-
----
-
-### Audio Transcription
-
-OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
-
-```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"
-```
-
-Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-
-Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-
----
-
-### Combo Balancing Strategies
-
-Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-
-| Strategy           | Description                                                              |
-| ------------------ | ------------------------------------------------------------------------ |
-| **Round-Robin**    | Rotates through models sequentially                                      |
-| **Priority**       | Always tries the first model; falls back only on error                   |
-| **Random**         | Picks a random model from the combo for each request                     |
-| **Weighted**       | Routes proportionally based on assigned weights per model                |
-| **Least-Used**     | Routes to the model with the fewest recent requests (uses combo metrics) |
-| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table)              |
-
-Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
-
----
-
-### Health Dashboard
-
-Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-
-| Card                  | What It Shows                                               |
-| --------------------- | ----------------------------------------------------------- |
-| **System Status**     | Uptime, version, memory usage, data directory               |
-| **Provider Health**   | Per-provider circuit breaker state (Closed/Open/Half-Open)  |
-| **Rate Limits**       | Active rate limit cooldowns per account with remaining time |
-| **Active Lockouts**   | Providers temporarily blocked by the lockout policy         |
-| **Signature Cache**   | Deduplication cache stats (active keys, hit rate)           |
-| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider                |
-
-**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
-
----
-
-## 🖥️ Desktop Application (Electron)
-
-OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
-
-### Installation
-
-```bash
-# From the electron directory:
-cd electron
-npm install
-
-# Development mode (connect to running Next.js dev server):
-npm run dev
-
-# Production mode (uses standalone build):
-npm start
-```
-
-### Building Installers
-
-```bash
-cd electron
-npm run build          # Current platform
-npm run build:win      # Windows (.exe NSIS)
-npm run build:mac      # macOS (.dmg universal)
-npm run build:linux    # Linux (.AppImage)
-```
-
-Output → `electron/dist-electron/`
-
-### Key Features
-
-| Feature                     | Description                                          |
-| --------------------------- | ---------------------------------------------------- |
-| **Server Readiness**        | Polls server before showing window (no blank screen) |
-| **System Tray**             | Minimize to tray, change port, quit from tray menu   |
-| **Port Management**         | Change server port from tray (auto-restarts server)  |
-| **Content Security Policy** | Restrictive CSP via session headers                  |
-| **Single Instance**         | Only one app instance can run at a time              |
-| **Offline Mode**            | Bundled Next.js server works without internet        |
-
-### Environment Variables
-
-| Variable              | Default | Description                      |
-| --------------------- | ------- | -------------------------------- |
-| `OMNIROUTE_PORT`      | `20128` | Server port                      |
-| `OMNIROUTE_MEMORY_MB` | `512`   | Node.js heap limit (64–16384 MB) |
-
-📖 Full documentation: [`electron/README.md`](../electron/README.md)

docs/i18n/ar/VM_DEPLOYMENT_GUIDE.md

@@ -1,403 +0,0 @@
-🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/VM_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../es/VM_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../fr/VM_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../de/VM_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../it/VM_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../ru/VM_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../zh-CN/VM_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../ja/VM_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../ko/VM_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../ar/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [in](../in/VM_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../th/VM_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../vi/VM_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../id/VM_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../ms/VM_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../nl/VM_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../pl/VM_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../sv/VM_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../no/VM_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../da/VM_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../fi/VM_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../pt/VM_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../ro/VM_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../hu/VM_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../bg/VM_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../sk/VM_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../uk-UA/VM_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../he/VM_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../phi/VM_DEPLOYMENT_GUIDE.md)
-
----
-
-# OmniRoute — Guia de Deploy em VM com Cloudflare
-
-Guia completo para instalar e configurar o OmniRoute em uma VM (VPS) com domínio gerenciado via Cloudflare.
-
----
-
-## Pré-Requisitos
-
-| Item        | Mínimo                   | Recomendado      |
-| ----------- | ------------------------ | ---------------- |
-| **CPU**     | 1 vCPU                   | 2 vCPU           |
-| **RAM**     | 1 GB                     | 2 GB             |
-| **Disco**   | 10 GB SSD                | 25 GB SSD        |
-| **SO**      | Ubuntu 22.04 LTS         | Ubuntu 24.04 LTS |
-| **Domínio** | Registrado no Cloudflare | —                |
-| **Docker**  | Docker Engine 24+        | Docker 27+       |
-
-**Providers testados**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail.
-
----
-
-## 1. Configurar a VM
-
-### 1.1 Criar a instância
-
-No seu provider de VPS preferido:
-
-- Escolha Ubuntu 24.04 LTS
-- Selecione o plano mínimo (1 vCPU / 1 GB RAM)
-- Defina uma senha forte para root ou configure SSH key
-- Anote o **IP público** (ex: `203.0.113.10`)
-
-### 1.2 Conectar via SSH
-
-```bash
-ssh root@203.0.113.10
-```
-
-### 1.3 Atualizar o sistema
-
-```bash
-apt update && apt upgrade -y
-```
-
-### 1.4 Instalar Docker
-
-```bash
-# Instalar dependências
-apt install -y ca-certificates curl gnupg
-
-# Adicionar repositório oficial do Docker
-install -m 0755 -d /etc/apt/keyrings
-curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
-chmod a+r /etc/apt/keyrings/docker.gpg
-echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
-apt update
-apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
-```
-
-### 1.5 Instalar nginx
-
-```bash
-apt install -y nginx
-```
-
-### 1.6 Configurar Firewall (UFW)
-
-```bash
-ufw default deny incoming
-ufw default allow outgoing
-ufw allow 22/tcp    # SSH
-ufw allow 80/tcp    # HTTP (redirect)
-ufw allow 443/tcp   # HTTPS
-ufw enable
-```
-
-> **Dica**: Para segurança máxima, restrinja as portas 80 e 443 apenas para IPs da Cloudflare. Veja a seção [Segurança Avançada](#segurança-avançada).
-
----
-
-## 2. Instalar o OmniRoute
-
-### 2.1 Criar diretório de configuração
-
-```bash
-mkdir -p /opt/omniroute
-```
-
-### 2.2 Criar arquivo de variáveis de ambiente
-
-```bash
-cat > /opt/omniroute/.env << 'EOF'
-# === Segurança ===
-JWT_SECRET=ALTERE-PARA-CHAVE-SECRETA-UNICA-64-CHARS
-INITIAL_PASSWORD=SuaSenhaSegura123!
-API_KEY_SECRET=ALTERE-PARA-OUTRA-CHAVE-SECRETA
-STORAGE_ENCRYPTION_KEY=ALTERE-PARA-TERCEIRA-CHAVE-SECRETA
-STORAGE_ENCRYPTION_KEY_VERSION=v1
-MACHINE_ID_SALT=ALTERE-PARA-SALT-UNICO
-
-# === App ===
-PORT=20128
-NODE_ENV=production
-HOSTNAME=0.0.0.0
-DATA_DIR=/app/data
-STORAGE_DRIVER=sqlite
-ENABLE_REQUEST_LOGS=true
-AUTH_COOKIE_SECURE=false
-REQUIRE_API_KEY=false
-
-# === Domain (altere para seu domínio) ===
-BASE_URL=https://llms.seudominio.com
-NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
-
-# === Cloud Sync (opcional) ===
-# CLOUD_URL=https://cloud.omniroute.online
-# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online
-EOF
-```
-
-> ⚠️ **IMPORTANTE**: Gere chaves secretas únicas! Use `openssl rand -hex 32` para cada chave.
-
-### 2.3 Iniciar o container
-
-```bash
-docker pull diegosouzapw/omniroute:latest
-
-docker run -d \
-  --name omniroute \
-  --restart unless-stopped \
-  --env-file /opt/omniroute/.env \
-  -p 20128:20128 \
-  -v omniroute-data:/app/data \
-  diegosouzapw/omniroute:latest
-```
-
-### 2.4 Verificar se está rodando
-
-```bash
-docker ps | grep omniroute
-docker logs omniroute --tail 20
-```
-
-Deve exibir: `[DB] SQLite database ready` e `listening on port 20128`.
-
----
-
-## 3. Configurar nginx (Reverse Proxy)
-
-### 3.1 Gerar certificado SSL (Cloudflare Origin)
-
-No painel da Cloudflare:
-
-1. Vá em **SSL/TLS → Origin Server**
-2. Clique **Create Certificate**
-3. Deixe os padrões (15 anos, \*.seudominio.com)
-4. Copie o **Origin Certificate** e a **Private Key**
-
-```bash
-mkdir -p /etc/nginx/ssl
-
-# Colar o certificado
-nano /etc/nginx/ssl/origin.crt
-
-# Colar a chave privada
-nano /etc/nginx/ssl/origin.key
-
-chmod 600 /etc/nginx/ssl/origin.key
-```
-
-### 3.2 Configuração do nginx
-
-```bash
-cat > /etc/nginx/sites-available/omniroute << 'NGINX'
-# Default server — bloqueia acesso direto por IP
-server {
-    listen 80 default_server;
-    listen [::]:80 default_server;
-    listen 443 ssl default_server;
-    listen [::]:443 ssl default_server;
-    ssl_certificate     /etc/nginx/ssl/origin.crt;
-    ssl_certificate_key /etc/nginx/ssl/origin.key;
-    server_name _;
-    return 444;
-}
-
-# OmniRoute — HTTPS
-server {
-    listen 443 ssl;
-    listen [::]:443 ssl;
-    server_name llms.seudominio.com;  # Altere para seu domínio
-
-    ssl_certificate     /etc/nginx/ssl/origin.crt;
-    ssl_certificate_key /etc/nginx/ssl/origin.key;
-    ssl_protocols TLSv1.2 TLSv1.3;
-
-    client_max_body_size 100M;
-
-    location / {
-        proxy_pass http://127.0.0.1:20128;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-
-        # WebSocket support
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-
-        # SSE (Server-Sent Events) — streaming AI responses
-        proxy_buffering off;
-        proxy_cache off;
-        proxy_read_timeout 300s;
-        proxy_send_timeout 300s;
-    }
-}
-
-# HTTP → HTTPS redirect
-server {
-    listen 80;
-    listen [::]:80;
-    server_name llms.seudominio.com;
-    return 301 https://$server_name$request_uri;
-}
-NGINX
-```
-
-### 3.3 Ativar e testar
-
-```bash
-# Remover config padrão
-rm -f /etc/nginx/sites-enabled/default
-
-# Ativar OmniRoute
-ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute
-
-# Testar e recarregar
-nginx -t && systemctl reload nginx
-```
-
----
-
-## 4. Configurar Cloudflare DNS
-
-### 4.1 Adicionar registro DNS
-
-No painel da Cloudflare → DNS:
-
-| Type | Name   | Content                   | Proxy      |
-| ---- | ------ | ------------------------- | ---------- |
-| A    | `llms` | `203.0.113.10` (IP da VM) | ✅ Proxied |
-
-### 4.2 Configurar SSL
-
-Em **SSL/TLS → Overview**:
-
-- Modo: **Full (Strict)**
-
-Em **SSL/TLS → Edge Certificates**:
-
-- Always Use HTTPS: ✅ On
-- Minimum TLS Version: TLS 1.2
-- Automatic HTTPS Rewrites: ✅ On
-
-### 4.3 Testar
-
-```bash
-curl -sI https://llms.seudominio.com/health
-# Deve retornar HTTP/2 200
-```
-
----
-
-## 5. Operações e Manutenção
-
-### Atualizar para nova versão
-
-```bash
-docker pull diegosouzapw/omniroute:latest
-docker stop omniroute && docker rm omniroute
-docker run -d --name omniroute --restart unless-stopped \
-  --env-file /opt/omniroute/.env \
-  -p 20128:20128 \
-  -v omniroute-data:/app/data \
-  diegosouzapw/omniroute:latest
-```
-
-### Ver logs
-
-```bash
-docker logs -f omniroute          # Stream em tempo real
-docker logs omniroute --tail 50   # Últimas 50 linhas
-```
-
-### Backup manual do banco
-
-```bash
-# Copiar dados do volume para o host
-docker cp omniroute:/app/data ./backup-$(date +%F)
-
-# Ou comprimir todo o volume
-docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
-  alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data
-```
-
-### Restaurar de backup
-
-```bash
-docker stop omniroute
-docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
-  alpine sh -c "rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /"
-docker start omniroute
-```
-
----
-
-## 6. Segurança Avançada
-
-### Restringir nginx para Cloudflare IPs
-
-```bash
-cat > /etc/nginx/cloudflare-ips.conf << 'CF'
-# Cloudflare IPv4 ranges — atualizar periodicamente
-# https://www.cloudflare.com/ips-v4/
-set_real_ip_from 173.245.48.0/20;
-set_real_ip_from 103.21.244.0/22;
-set_real_ip_from 103.22.200.0/22;
-set_real_ip_from 103.31.4.0/22;
-set_real_ip_from 141.101.64.0/18;
-set_real_ip_from 108.162.192.0/18;
-set_real_ip_from 190.93.240.0/20;
-set_real_ip_from 188.114.96.0/20;
-set_real_ip_from 197.234.240.0/22;
-set_real_ip_from 198.41.128.0/17;
-set_real_ip_from 162.158.0.0/15;
-set_real_ip_from 104.16.0.0/13;
-set_real_ip_from 104.24.0.0/14;
-set_real_ip_from 172.64.0.0/13;
-set_real_ip_from 131.0.72.0/22;
-real_ip_header CF-Connecting-IP;
-CF
-```
-
-Adicionar no `nginx.conf` dentro do bloco `http {}`:
-
-```nginx
-include /etc/nginx/cloudflare-ips.conf;
-```
-
-### Install fail2ban
-
-```bash
-apt install -y fail2ban
-systemctl enable fail2ban
-systemctl start fail2ban
-
-# Verificar status
-fail2ban-client status sshd
-```
-
-### Bloquear acesso direto na porta do Docker
-
-```bash
-# Impedir acesso externo direto à porta 20128
-iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP
-iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT
-
-# Persistir as regras
-apt install -y iptables-persistent
-netfilter-persistent save
-```
-
----
-
-## 7. Deploy do Cloud Worker (Opcional)
-
-Para acesso remoto via Cloudflare Workers (sem expor a VM diretamente):
-
-```bash
-# No repositório local
-cd omnirouteCloud
-npm install
-npx wrangler login
-npx wrangler deploy
-```
-
-Ver documentação completa em [omnirouteCloud/README.md](../omnirouteCloud/README.md).
-
----
-
-## Resumo de Portas
-
-| Porta | Serviço     | Acesso                        |
-| ----- | ----------- | ----------------------------- |
-| 22    | SSH         | Público (com fail2ban)        |
-| 80    | nginx HTTP  | Redirect → HTTPS              |
-| 443   | nginx HTTPS | Via Cloudflare Proxy          |
-| 20128 | OmniRoute   | Somente localhost (via nginx) |

docs/i18n/ar/docs/A2A-SERVER.md

@@ -0,0 +1,170 @@
+# OmniRoute A2A Server Documentation (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/A2A-SERVER.md) · 🇪🇸 [es](../../es/docs/A2A-SERVER.md) · 🇫🇷 [fr](../../fr/docs/A2A-SERVER.md) · 🇩🇪 [de](../../de/docs/A2A-SERVER.md) · 🇮🇹 [it](../../it/docs/A2A-SERVER.md) · 🇷🇺 [ru](../../ru/docs/A2A-SERVER.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/A2A-SERVER.md) · 🇯🇵 [ja](../../ja/docs/A2A-SERVER.md) · 🇰🇷 [ko](../../ko/docs/A2A-SERVER.md) · 🇸🇦 [ar](../../ar/docs/A2A-SERVER.md) · 🇮🇳 [hi](../../hi/docs/A2A-SERVER.md) · 🇮🇳 [in](../../in/docs/A2A-SERVER.md) · 🇹🇭 [th](../../th/docs/A2A-SERVER.md) · 🇻🇳 [vi](../../vi/docs/A2A-SERVER.md) · 🇮🇩 [id](../../id/docs/A2A-SERVER.md) · 🇲🇾 [ms](../../ms/docs/A2A-SERVER.md) · 🇳🇱 [nl](../../nl/docs/A2A-SERVER.md) · 🇵🇱 [pl](../../pl/docs/A2A-SERVER.md) · 🇸🇪 [sv](../../sv/docs/A2A-SERVER.md) · 🇳🇴 [no](../../no/docs/A2A-SERVER.md) · 🇩🇰 [da](../../da/docs/A2A-SERVER.md) · 🇫🇮 [fi](../../fi/docs/A2A-SERVER.md) · 🇵🇹 [pt](../../pt/docs/A2A-SERVER.md) · 🇷🇴 [ro](../../ro/docs/A2A-SERVER.md) · 🇭🇺 [hu](../../hu/docs/A2A-SERVER.md) · 🇧🇬 [bg](../../bg/docs/A2A-SERVER.md) · 🇸🇰 [sk](../../sk/docs/A2A-SERVER.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/A2A-SERVER.md) · 🇮🇱 [he](../../he/docs/A2A-SERVER.md) · 🇵🇭 [phi](../../phi/docs/A2A-SERVER.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/A2A-SERVER.md) · 🇨🇿 [cs](../../cs/docs/A2A-SERVER.md) · 🇹🇷 [tr](../../tr/docs/A2A-SERVER.md)
+
+---
+
+> بروتوكول وكيل إلى وكيل v0.3 — OmniRoute كوكيل توجيه ذكي## Agent Discovery```bash
+> curl http://localhost:20128/.well-known/agent.json
+
+````
+
+إرجاع بطاقة الوكيل التي تصف قدرات OmniRoute ومهاراتها ومتطلبات المصادقة.---## Authentication
+
+تتطلب جميع الطلبات `/a2a` مفتاح برمجة التطبيقات عبر رأس `الإعلان`:```
+التفويض: الحامل YOUR_OMNIROUTE_API_KEY```
+
+إذا لم يتم تكوين أي مفتاح API على الخادم، فسيتم تجاوز المصادقة.---
+
+## JSON-RPC 2.0 Methods
+
+### `message/send` — Synchronous Execution
+
+يرسل رسالة إلى المهارة وينتظر الرد الكامل.```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"}
+    }
+  }'
+````
+
+**إجابة:**`json
+{
+  "jsonrpc": "2.0",
+  "المعرف": "1"،
+  "النتيجة": {
+    "المهمة": { "المعرف": "uuid"، "الحالة": "مكتمل" }،
+    "المصنوعات": [{ "النوع": "نص"، "محتوى": "..." }]،
+    "البيانات الوصفية": {
+      "routing_explanation": "سونيتة claude مختارة عبر الموفر \"anthropic\" (زمن الوصول: 1200 مللي ثانية، التكلفة: 0.003 USD)"،
+      "cost_envelope": { "المقدرة": 0.005، "الفعلي": 0.003، "العملة": "USD" }،
+      ""resilience_trace": [
+        { "الحدث": "primary_selected"، "provider": "anthropic"، "timestamp": "..." }
+      ]،
+      "policy_verdict": { "مسموح": صحيح، "السبب": "ضمن حدود الميزانية والحصة" }
+    }
+  }
+}`
+
+### `message/stream` — SSE Streaming
+
+نفس `الرسالة/الإرسال` ولكنها تُرجع الأحداث المرسلة من الخادم للبث في الوقت الفعلي.```bash
+curl -N -X POST http://localhost:20128/a2a \
+ -H "Content-Type: application/json" \
+ -H "Authorization: Bearer YOUR_KEY" \
+ -d '{
+"jsonrpc": "2.0",
+"id": "1",
+"method": "message/stream",
+"params": {
+"skill": "smart-routing",
+"messages": [{"role": "user", "content": "Explain quantum computing"}]
+}
+}'
+
+````
+
+**أحداث SSE:**```
+البيانات: {"jsonrpc": "2.0"، "method": "message/stream"، "params": {"task": {"id": "..."، "state": "working"}، "chunk": {"type": "text"، "content": "..."}}}
+
+: نبضات القلب 2026-03-03T17:00:00Z
+
+البيانات: {"jsonrpc": "2.0"، "method": "message/stream"، "params": {"task": {"id": "..."، "state": "Completed"}، "بيانات التعريف": {...}}}```
+
+### `tasks/get` — Query Task Status
+
+```bash
+حليقة -X POST http://localhost:20128/a2a \
+  -H "نوع المحتوى: application/json" \
+  -H "التفويض: حامل YOUR_KEY" \
+  -d '{"jsonrpc": "2.0"، "id": "2"، "method": "tasks/get"، "params": {"taskId": "TASK_UUID"}}'```
+
+### `tasks/cancel` — Cancel a Task
+
+```bash
+حليقة -X POST http://localhost:20128/a2a \
+  -H "نوع المحتوى: application/json" \
+  -H "التفويض: حامل YOUR_KEY" \
+  -d '{"jsonrpc": "2.0"، "id": "3"، "method": "tasks/cancel"، "params": {"taskId": "TASK_UUID"}}'```
+
+---
+
+## Available Skills
+
+| مهارة | الوصف |
+| :----------------- | :------------------------------------------------------------------------------------------------------------------------------- |
+| `التوجيه الذكي` | تطالب الطرق عبر خط أنابيب OmniRoute الذكي. إرجاع الاستجابة مع شرح التوجيه والتكلفة وتتبع المرونة. |
+| `إدارة الحصص` | يجيب على استفسارات اللغة الطبيعية حول حصص الموفرين، ويقترح مجموعات مجانية، ويوفر تصنيفات الحصص.                      |---
+
+## Task Lifecycle
+
+````
+
+تم الإرسال ← العمل ← مكتمل
+→ فشل
+→ ألغيت```
+
+- تنتهي المهام بعد 5 دقائق (قابلة للتكوين)
+- حالات الوحدة الطرفية: "مكتمل"، "فشل"، "تم الإلغاء".
+- سجل الأحداث يتتبع كل انتقال للحالة---
+
+## Error Codes
+
+| الكود  | معنى                                 |
+| :----- | :----------------------------------- | --- |
+| -32700 | خطأ في التحليل (JSON غير صالح)       |
+| -32600 | طلب غير صالح / غير مصرح به           |
+| -32601 | لم يتم العثور على الطريقة أو المهارة |
+| -32602 | معلمات غير صالحة                     |
+| -32603 | خطأ داخلي                            | --- |
+
+## Integration Examples
+
+### Python (requests)
+
+````python
+طلبات الاستيراد
+
+resp = request.post("http://localhost:20128/a2a", json={
+    "jsonrpc": "2.0"، "id": "1"،
+    "الطريقة": "رسالة/إرسال"،
+    "المعلمات": {
+        "المهارة": "التوجيه الذكي"،
+        "messages": [{"role": "user", "content": "Hello"}]
+    }
+}, headers={"Authorization": "Bearer YOUR_KEY"})
+
+النتيجة = resp.json () ["النتيجة"]
+طباعة (نتيجة ["المصنوعات"] [0] ["المحتوى"])
+طباعة (نتيجة ["بيانات التعريف"] ["routing_explanation"])```
+
+### TypeScript (fetch)
+
+```typescript
+const resp = انتظار الجلب("http://localhost:20128/a2a", {
+  الطريقة: "POST"،
+  رؤوس: {
+    "نوع المحتوى": "application/json"،
+    التفويض: "الحامل YOUR_KEY"،
+  },
+  الجسم: JSON.stringify({
+    جسونربك: "2.0"،
+    المعرف: "1"،
+    الطريقة: "رسالة/إرسال"،
+    المعلمات: {
+      المهارة: "التوجيه الذكي"،
+      الرسائل: [{ الدور: "المستخدم"، المحتوى: "مرحبًا" }]،
+    },
+  }),
+});
+const { result } = انتظار resp.json();
+console.log(result.metadata.routing_explanation);```
+````

docs/i18n/ar/docs/API_REFERENCE.md

@@ -0,0 +1,388 @@
+# API Reference (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/API_REFERENCE.md) · 🇪🇸 [es](../../es/docs/API_REFERENCE.md) · 🇫🇷 [fr](../../fr/docs/API_REFERENCE.md) · 🇩🇪 [de](../../de/docs/API_REFERENCE.md) · 🇮🇹 [it](../../it/docs/API_REFERENCE.md) · 🇷🇺 [ru](../../ru/docs/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/API_REFERENCE.md) · 🇯🇵 [ja](../../ja/docs/API_REFERENCE.md) · 🇰🇷 [ko](../../ko/docs/API_REFERENCE.md) · 🇸🇦 [ar](../../ar/docs/API_REFERENCE.md) · 🇮🇳 [hi](../../hi/docs/API_REFERENCE.md) · 🇮🇳 [in](../../in/docs/API_REFERENCE.md) · 🇹🇭 [th](../../th/docs/API_REFERENCE.md) · 🇻🇳 [vi](../../vi/docs/API_REFERENCE.md) · 🇮🇩 [id](../../id/docs/API_REFERENCE.md) · 🇲🇾 [ms](../../ms/docs/API_REFERENCE.md) · 🇳🇱 [nl](../../nl/docs/API_REFERENCE.md) · 🇵🇱 [pl](../../pl/docs/API_REFERENCE.md) · 🇸🇪 [sv](../../sv/docs/API_REFERENCE.md) · 🇳🇴 [no](../../no/docs/API_REFERENCE.md) · 🇩🇰 [da](../../da/docs/API_REFERENCE.md) · 🇫🇮 [fi](../../fi/docs/API_REFERENCE.md) · 🇵🇹 [pt](../../pt/docs/API_REFERENCE.md) · 🇷🇴 [ro](../../ro/docs/API_REFERENCE.md) · 🇭🇺 [hu](../../hu/docs/API_REFERENCE.md) · 🇧🇬 [bg](../../bg/docs/API_REFERENCE.md) · 🇸🇰 [sk](../../sk/docs/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/API_REFERENCE.md) · 🇮🇱 [he](../../he/docs/API_REFERENCE.md) · 🇵🇭 [phi](../../phi/docs/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/API_REFERENCE.md) · 🇨🇿 [cs](../../cs/docs/API_REFERENCE.md) · 🇹🇷 [tr](../../tr/docs/API_REFERENCE.md)
+
+---
+
+مرجع كامل لجميع نهاية نقاط OmniRoute API.---## Table of Contents
+
+- [إكمالات الدردشة](#إكمالات الدردشة)
+- [التضمينات](#التضمينات)
+- [ إنشاء الصور ](#image-generation)
+- [قائمة التطورات](#list-models)
+- [نقاط نهاية التوافق](#نقاط نهاية التوافق)
+- [ذاكرة التخزين المؤقتة الدلالية](#ذاكرة التخزين المؤقتة الدلالية)
+- [لوحة التحكم والإدارة](#dashboard--management)
+- [معالجة الطلب](#request-processing)
+- [المصادقة](#المصادقة)---## Chat Completions
+
+```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
+}
+```
+
+### Custom Headers
+
+| رأس                      |      | الوصف                                        |
+| ------------------------ | ---- | -------------------------------------------- |
+| `X-OmniRoute-No-Cache`   | طلب  | اضبط على "صحيح" لتجاوز ذاكرة التخزين المؤقتة |
+| `X-OmniRoute-Progress`   | طلب  | اضبط على "صحيح" لأحداث التقدم                |
+| `معرف الاستماع X`        | طلب  | مفتاح جلسة لوجه الفعل                        |
+| `x_session_id`           | طلب  | يتم أيضًا قبول التكيف البيئي (HTTP)          |
+| `مفتاح العجز`            | طلب  | مفتاح Dedup (نافذة 5 ثواني)                  |
+| `معرف الطلب X`           | طلب  | مفتاح إلغاء الحذف الحذف                      |
+| `X-OmniRoute-Cache`      | الرد | `HIT` أو `MISS` (غير متدفق)                  |
+| `X-OmniRoute-Idempotent` | الرد | `صحيح` إذا تم إلغاء التكرار                  |
+| `X-OmniRoute-Progress`   | الرد | `ممكن تشغيل` في حالة تتبع التقدم             |
+| `معرف جلسة X-OmniRoute`  | الرد | الرقم التعريفي الفعال الذي يستخدمه OmniRoute |
+
+> لاحظ Nginx: إذا كنت تعتمد على التكييف الهوائي (على سبيل المثال `x_session_id`)، إلا بتمكين `الشرطات الكهربائية_in_headers on;`.---## Embeddings
+
+```bash
+POST /v1/embeddings
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "nebius/Qwen/Qwen3-Embedding-8B",
+  "input": "The food was delicious"
+}
+```
+
+مقدمو خدمة متاحون: Nebius، وOpenAI، وMistral، وTogether AI، وFireworks، وNVIDIA.```bash
+
+# قائمة بجميع نماذج التضمين
+
+الحصول على /v1/embeddings```
+
+---
+
+## Image Generation
+
+````bash
+ما بعد /v1/صور/أجيال
+التفويض: حامل مفتاح API الخاص بك
+نوع المحتوى: application/json
+
+{
+  "نموذج": "openai/dall-e-3"،
+  "prompt": "غروب الشمس الجميل فوق الجبال"،
+  "الحجم": "1024x1024"
+}```
+
+الموفرون المتاحون: OpenAI (DALL-E)، xAI (Grok Image)، Together AI (FLUX)، Fireworks AI.```bash
+# List all image models
+GET /v1/images/generations
+````
+
+---
+
+## List Models
+
+```bash
+GET /v1/models
+Authorization: Bearer your-api-key
+
+→ Returns all chat, embedding, and image models + combos in OpenAI format
+```
+
+---
+
+## Compatibility Endpoints
+
+| الطريقة  | المسار                      | التنسيق               |
+| -------- | --------------------------- | --------------------- | -------------------------------- |
+| مشاركة   | `/v1/chat/completions`      | أوبن آي               |
+| مشاركة   | `/v1/messages`              | انثروبى               |
+| مشاركة   | `/v1/الردود`                | ردود OpenAI           |
+| مشاركة   | `/v1/embeddings`            | أوبن آي               |
+| مشاركة   | `/v1/images/أجيال`          | أوبن آي               |
+| احصل على | `/v1/ النماذج`              | أوبن آي               |
+| مشاركة   | `/v1/messages/count_tokens` | انثروبى               |
+| احصل على | `/v1beta/models`            | الجوزاء               |
+| مشاركة   | `/v1beta/models/{...path}`  | الجوزاء توليد المحتوى |
+| مشاركة   | `/v1/api/chat`              | أولاما                | ### مسارات الموفر المخصصة```bash |
+
+POST /v1/providers/{provider}/chat/completions
+POST /v1/providers/{provider}/embeddings
+POST /v1/providers/{provider}/images/generations
+
+````
+
+تتم إضافة المبادئ الأصلية للمنتج الأصلي في حالة اشتعالها. الاستعلام عن الارتباطات غير المتطابقة "400".---## Semantic Cache
+
+```bash
+# Get cache stats
+GET /api/cache/stats
+
+# Clear all caches
+DELETE /api/cache/stats
+````
+
+المثال النموذجي:`json
+{
+  "ذاكرة التخزين المؤقت الدلالية": {
+    "حجم الذاكرة": 42،
+    "memoryMaxSize": 500،
+    "حجم ديسيبل": 128،
+    "معدل الإصابة": 0.65
+  },
+  "العجز": {
+    "المفاتيح النشطة": 3،
+    "windows": 5000
+  }
+}`
+
+---
+
+## Dashboard & Management
+
+### Authentication
+
+| نقطة النهاية                  | الطريقة        | الوصف                    |
+| ----------------------------- | -------------- | ------------------------ | ----------------------- |
+| `/api/auth/login`             | مشاركة         | تسجيل الدخول             |
+| `/api/auth/logout`            | مشاركة         | تسجيل الخروج             |
+| `/api/settings/require-login` | الحصول على/وضع | تبديل تسجيل الدخول مطلوب | ### Provider Management |
+
+| نقطة النهاية                 | الطريقة            | الوصف                       |
+| ---------------------------- | ------------------ | --------------------------- | --------------- |
+| `/api/providers`             | الحصول على/النشر   | قائمة / إنشاء مقدمي الخدمات |
+| `/api/providers/[id]`        | الحصول على/وضع/حذف | إدارة مزود                  |
+| `/api/providers/[id]/test`   | مشاركة             | اختبار اتصال الموفر         |
+| `/api/providers/[id]/models` | احصل على           | قائمة نماذج المزود          |
+| `/api/providers/validate`    | مشاركة             | التحقق من صحة تكوين الموفر  |
+| `/api/provider-nodes*`       | منوعه              | إدارة عقدة الموفر           |
+| `/api/provider-models`       | الحصول على/نشر/حذف | نماذج مخصصة                 | ### OAuth Flows |
+
+| نقطة النهاية                     | الطريقة | الوصف                    |
+| -------------------------------- | ------- | ------------------------ | -------------------- |
+| `/api/oauth/[provider]/[action]` | متنوع   | OAuth الخاص بموفر الخدمة | ### Routing & Config |
+
+| نقطة النهاية          | الطريقة          | الوصف                             |
+| --------------------- | ---------------- | --------------------------------- | --------------------- |
+| `/api/models/alias`   | الحصول على/النشر | الأسماء المستعارة للنموذج         |
+| `/api/models/catalog` | احصل على         | جميع الموديلات حسب المزود + النوع |
+| `/api/combos*`        | متنوع            | إدارة التحرير والسرد              |
+| `/api/keys*`          | متنوع            | إدارة مفاتيح API                  |
+| `/api/pricing`        | احصل على         | التسعير النموذجي                  | ### Usage & Analytics |
+
+| نقطة النهاية                | الطريقة  | الوصف                 |
+| --------------------------- | -------- | --------------------- | ------------ |
+| `/api/usage/history`        | احصل على | تاريخ الاستخدام       |
+| `/api/usage/logs`           | احصل على | سجلات الاستخدام       |
+| `/api/usage/request-logs`   | احصل على | سجلات على مستوى الطلب |
+| `/api/usage/[connectionId]` | احصل على | الاستخدام لكل اتصال   | ### Settings |
+
+| نقطة النهاية                    | الطريقة                | الوصف                                           |
+| ------------------------------- | ---------------------- | ----------------------------------------------- | -------------- |
+| `/api/settings`                 | الحصول على/وضع/التصحيح | الإعدادات العامة                                |
+| `/api/settings/proxy`           | الحصول على/وضع         | تكوين وكيل الشبكة                               |
+| `/api/settings/proxy/test`      | مشاركة                 | اختبار اتصال الوكيل                             |
+| `/api/settings/ip-filter`       | الحصول على/وضع         | القائمة المسموح بها/القائمة المحظورة لعناوين IP |
+| `/api/settings/thinking-budget` | الحصول على/وضع         | الميزانية الرمزية المنطقية                      |
+| `/api/settings/system-prompt`   | الحصول على/وضع         | موجه النظام العالمي                             | ### Monitoring |
+
+| نقطة النهاية             | الطريقة        | الوصف                                                                                              |
+| ------------------------ | -------------- | -------------------------------------------------------------------------------------------------- | -------------------------- |
+| `/api/sessions`          | احصل على       | تتبع الجلسة النشطة                                                                                 |
+| `/api/rate-limits`       | احصل على       | حدود المعدل لكل حساب                                                                               |
+| `/api/monitoring/health` | احصل على       | التحقق من الصحة + ملخص الموفر (`catalogCount`، `configuredCount`، `activeCount`، `monitoredCount`) |
+| `/api/cache/stats`       | الحصول على/حذف | إحصائيات ذاكرة التخزين المؤقت / مسح                                                                | ### Backup & Export/Import |
+
+| نقطة النهاية                | الطريقة  | الوصف                                              |
+| --------------------------- | -------- | -------------------------------------------------- | -------------- |
+| `/api/db-backups`           | احصل على | قائمة النسخ الاحتياطية المتاحة                     |
+| `/api/db-backups`           | ضع       | إنشاء نسخة احتياطية يدوية                          |
+| `/api/db-backups`           | مشاركة   | استعادة من نسخة احتياطية محددة                     |
+| `/api/db-backups/export`    | احصل على | تنزيل قاعدة البيانات كملف .sqlite                  |
+| `/api/db-backups/import`    | مشاركة   | قم بتحميل ملف .sqlite لاستبدال قاعدة البيانات      |
+| `/api/db-backups/exportAll` | احصل على | قم بتنزيل النسخة الاحتياطية الكاملة كأرشيف .tar.gz | ### Cloud Sync |
+
+| نقطة النهاية           | الطريقة | الوصف                    |
+| ---------------------- | ------- | ------------------------ | ----------- |
+| `/api/sync/cloud`      | متنوع   | عمليات المزامنة السحابية |
+| `/api/sync/initialize` | مشاركة  | تهيئة المزامنة           |
+| `/api/cloud/*`         | متنوع   | إدارة السحابة            | ### Tunnels |
+
+| نقطة النهاية               | الطريقة  | الوصف                                                         |
+| -------------------------- | -------- | ------------------------------------------------------------- | ------------- |
+| `/api/tunnels/cloudflared` | احصل على | اقرأ حالة تثبيت/تشغيل Cloudflare Quick Tunnel للوحة المعلومات |
+| `/api/tunnels/cloudflared` | مشاركة   | تمكين أو تعطيل نفق Cloudflare السريع (`الإجراء=تمكين/تعطيل`)  | ### CLI Tools |
+
+| نقطة النهاية                       | الطريقة  | الوصف               |
+| ---------------------------------- | -------- | ------------------- |
+| `/api/cli-tools/claude-settings`   | احصل على | حالة كلود CLI       |
+| `/api/cli-tools/codex-settings`    | احصل على | حالة Codex CLI      |
+| `/api/cli-tools/droid-settings`    | احصل على | حالة Droid CLI      |
+| `/api/cli-tools/openclaw-settings` | احصل على | حالة OpenClaw CLI   |
+| `/api/cli-tools/runtime/[toolId]`  | احصل على | وقت تشغيل CLI العام |
+
+تتضمن استجابات واجهة سطر الأوامر: `تم التثبيت`، و`القابل للتشغيل`، و`الأمر`، و`commandPath`، و`runtimeMode`، و`السبب`.### ACP Agents
+
+| نقطة النهاية      | الطريقة  | الوصف                                                          |
+| ----------------- | -------- | -------------------------------------------------------------- |
+| `/api/acp/agents` | احصل على | قم بإدراج جميع الوكلاء المكتشفين (المضمنين + المخصصين) بالحالة |
+| `/api/acp/agents` | مشاركة   | إضافة وكيل مخصص أو تحديث ذاكرة التخزين المؤقت للكشف            |
+| `/api/acp/agents` | حذف      | قم بإزالة وكيل مخصص بواسطة معلمة الاستعلام `id`                |
+
+تتضمن استجابة GET `الوكلاء []` (المعرف، الاسم، الثنائي، الإصدار، المثبت، البروتوكول، isCustom) و`الملخص` (الإجمالي، المثبت، غير موجود، مدمج، مخصص).### Resilience & Rate Limits
+
+| نقطة النهاية            | الطريقة            | الوصف                                |
+| ----------------------- | ------------------ | ------------------------------------ | --------- |
+| `/api/المرونة`          | الحصول على/التصحيح | الحصول على/تحديث ملفات تعريف المرونة |
+| `/api/resilience/reset` | مشاركة             | إعادة ضبط قواطع الدائرة              |
+| `/api/rate-limits`      | احصل على           | حالة حد المعدل لكل حساب              |
+| `/api/rate-limit`       | احصل على           | تكوين حد المعدل العالمي              | ### Evals |
+
+| نقطة النهاية | الطريقة          | الوصف                                 |
+| ------------ | ---------------- | ------------------------------------- | ------------ |
+| `/api/evals` | الحصول على/النشر | قائمة مجموعات التقييم / تشغيل التقييم | ### Policies |
+
+| نقطة النهاية    | الطريقة            | الوصف                |
+| --------------- | ------------------ | -------------------- | -------------- |
+| `/api/policies` | الحصول على/نشر/حذف | إدارة سياسات التوجيه | ### Compliance |
+
+| نقطة النهاية                | الطريقة  | الوصف                        |
+| --------------------------- | -------- | ---------------------------- | ------------------------------ |
+| `/api/compliance/audit-log` | احصل على | سجل تدقيق الامتثال (آخر رقم) | ### v1beta (Gemini-Compatible) |
+
+| نقطة النهاية               | الطريقة  | الوصف                                |
+| -------------------------- | -------- | ------------------------------------ |
+| `/v1beta/models`           | احصل على | قائمة النماذج بصيغة الجوزاء          |
+| `/v1beta/models/{...path}` | مشاركة   | الجوزاء `توليد المحتوى` نقطة النهاية |
+
+تعكس نقاط النهاية هذه تنسيق Gemini API للعملاء الذين يتوقعون توافق Gemini SDK الأصلي.### Internal / System APIs
+
+| نقطة النهاية    | الطريقة  | الوصف                                              |
+| --------------- | -------- | -------------------------------------------------- |
+| `/api/init`     | احصل على | فحص تهيئة التطبيق (يستخدم عند التشغيل لأول مرة)    |
+| `/api/tags`     | احصل على | علامات النماذج المتوافقة مع Ollama (لعملاء Ollama) |
+| `/api/restart`  | مشاركة   | تشغيل إعادة تشغيل الخادم الرشيقة                   |
+| `/api/shutdown` | مشاركة   | تشغيل إيقاف تشغيل الخادم بشكل رشيق                 |
+
+> **ملاحظة:**يتم استخدام نقاط النهاية هذه داخليًا بواسطة النظام أو للتوافق مع عميل Ollama. ولا يتم استدعاؤها عادة من قبل المستخدمين النهائيين.---
+
+## Audio Transcription
+
+````bash
+POST /v1/audio/transcriptions
+التفويض: حامل مفتاح API الخاص بك
+نوع المحتوى: بيانات متعددة الأجزاء/النموذج```
+
+قم بنسخ الملفات الصوتية باستخدام Deepgram أو AssemblyAI.
+
+**طلب:**```bash
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+  -H "Authorization: Bearer your-api-key" \
+  -F "file=@recording.mp3" \
+  -F "model=deepgram/nova-3"
+````
+
+**إجابة:**`json
+{
+  "text": "مرحبًا، هذا هو المحتوى الصوتي المكتوب.",
+  "مهمة": "نسخ"،
+  "اللغة": "ar"،
+  "المدة": 12.5
+}`
+
+**مقدمو الخدمة المدعومين:**`deepgram/nova-3`، `assemblyai/best`.
+
+**الصيغ المدعومة:**`mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`.---
+
+## Ollama Compatibility
+
+للعملاء الذين يستخدمون تنسيق واجهة برمجة تطبيقات Olma:```bash
+
+# Chat endpoint (Ollama format)
+
+POST /v1/api/chat
+
+# Model listing (Ollama format)
+
+GET /api/tags
+
+````
+
+ترجمة الطلبات الأصلية بين التنسيقات التنسيقات الداخلية.---## Telemetry
+
+```bash
+# Get latency telemetry summary (p50/p95/p99 per provider)
+GET /api/telemetry/summary
+````
+
+**إجابة:**`json
+{
+  "مقدمو الخدمات": {
+    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
+    "github": { "p50": 180، "p95": 620، "p99": 950، "count": 320 }
+  }
+}`
+
+---
+
+## Budget
+
+````bash
+# احصل على حالة الميزانية لجميع مفاتيح API
+الحصول على /api/usage/budget
+
+# تعيين أو تحديث الميزانية
+POST /api/usage/budget
+نوع المحتوى: application/json
+
+{
+  "معرف المفتاح": "مفتاح-123"،
+  "الحد": 50.00،
+  "الفترة": "الشهرية"
+}```
+
+---
+
+## Model Availability
+
+```bash
+# احصل على توفر النموذج في الوقت الفعلي عبر جميع مقدمي الخدمة
+الحصول على /api/models/availability
+
+# التحقق من توفر طراز معين
+POST /api/models/availability
+نوع المحتوى: application/json
+
+{
+  "نموذج": "كلود السوناتة-4-5-20250929"
+}```
+
+---
+
+## Request Processing
+
+1. يرسل العميل طلبًا إلى `/v1/*`
+2. يستدعي معالج المسار "handleChat"، أو "handleEmbedding"، أو "handleAudioTranscription"، أو "handleImageGeneration".
+3. تم حل النموذج (المزود/النموذج المباشر أو الاسم المستعار/السرد)
+4. تم تحديد بيانات الاعتماد من قاعدة البيانات المحلية مع تصفية توفر الحساب
+5. للدردشة: `handleChatCore` - اكتشاف التنسيق، والترجمة، والتحقق من ذاكرة التخزين المؤقت، والتحقق من الكفاءة
+6. يقوم منفذ الموفر بإرسال طلب المنبع
+7. تتم ترجمة الاستجابة مرة أخرى إلى تنسيق العميل (الدردشة) أو إعادتها كما هي (التضمينات/الصور/الصوت)
+8. تم تسجيل الاستخدام/التسجيل
+9. يتم تطبيق الإجراء الاحتياطي على الأخطاء وفقًا لقواعد التحرير والسرد
+
+مرجع البنية الكاملة: [`ARCHITECTURE.md`](ARCHITECTURE.md)---
+
+## Authentication
+
+- تستخدم مسارات لوحة المعلومات (`/dashboard/*`) ملف تعريف الارتباط `auth_token`
+- يستخدم تسجيل الدخول تجزئة كلمة المرور المحفوظة؛ الرجوع إلى `INITIAL_PASSWORD`
+- `requireLogin` قابل للتبديل عبر `/api/settings/require-login`
+- تتطلب المسارات `/v1/*` بشكل اختياري مفتاح Bearer API عندما يكون `REQUIRE_API_KEY=true`
+````

docs/i18n/ar/docs/ARCHITECTURE.md

@@ -0,0 +1,719 @@
+# OmniRoute Architecture (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/ARCHITECTURE.md) · 🇪🇸 [es](../../es/docs/ARCHITECTURE.md) · 🇫🇷 [fr](../../fr/docs/ARCHITECTURE.md) · 🇩🇪 [de](../../de/docs/ARCHITECTURE.md) · 🇮🇹 [it](../../it/docs/ARCHITECTURE.md) · 🇷🇺 [ru](../../ru/docs/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) · 🇯🇵 [ja](../../ja/docs/ARCHITECTURE.md) · 🇰🇷 [ko](../../ko/docs/ARCHITECTURE.md) · 🇸🇦 [ar](../../ar/docs/ARCHITECTURE.md) · 🇮🇳 [hi](../../hi/docs/ARCHITECTURE.md) · 🇮🇳 [in](../../in/docs/ARCHITECTURE.md) · 🇹🇭 [th](../../th/docs/ARCHITECTURE.md) · 🇻🇳 [vi](../../vi/docs/ARCHITECTURE.md) · 🇮🇩 [id](../../id/docs/ARCHITECTURE.md) · 🇲🇾 [ms](../../ms/docs/ARCHITECTURE.md) · 🇳🇱 [nl](../../nl/docs/ARCHITECTURE.md) · 🇵🇱 [pl](../../pl/docs/ARCHITECTURE.md) · 🇸🇪 [sv](../../sv/docs/ARCHITECTURE.md) · 🇳🇴 [no](../../no/docs/ARCHITECTURE.md) · 🇩🇰 [da](../../da/docs/ARCHITECTURE.md) · 🇫🇮 [fi](../../fi/docs/ARCHITECTURE.md) · 🇵🇹 [pt](../../pt/docs/ARCHITECTURE.md) · 🇷🇴 [ro](../../ro/docs/ARCHITECTURE.md) · 🇭🇺 [hu](../../hu/docs/ARCHITECTURE.md) · 🇧🇬 [bg](../../bg/docs/ARCHITECTURE.md) · 🇸🇰 [sk](../../sk/docs/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) · 🇮🇱 [he](../../he/docs/ARCHITECTURE.md) · 🇵🇭 [phi](../../phi/docs/ARCHITECTURE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) · 🇨🇿 [cs](../../cs/docs/ARCHITECTURE.md) · 🇹🇷 [tr](../../tr/docs/ARCHITECTURE.md)
+
+---
+
+_آخر تحديث: 2026-03-28_## الملخص التنفيذي
+
+OmniRoute عبارة عن بوابة توجيه نقطة تعمل بالذكاء الاصطناعي ولوحة معلومات مبنية على Next.js.
+وهو يوفر نقطة نهاية واحدة متوافقة مع OpenAI (`/v1/*`) ويوجه حركة المرور عبر العديد من الخدمات الموفري الأولية مع الترجمة والاحتياط وتحديث الرمز المميز وتتبع الاستخدام.
+
+التان الأساسية:
+
+- سطح API متوافق مع OpenAI لـ CLI/الأدوات (28 منتجًا)
+- ترجمة الطلب/الاستجابة عبر التنسيقات الموفر
+- نموذج بناء التحرير والسرد (سلسلة الارتباطات المتعددة)
+- موازنة حساب الحساب (حسابات متعددة لكل شخص)
+- إدارة اتصال موفر OAuth + API-key
+- إنشاء التضمين عبر `/v1/embeddings` (6 مقدمي خدمات، 9 نماذج)
+- إنشاء الصور عبر `/v1/images/Generation` (4 مقدمي خدمات، 9 نماذج)
+- فكر في تحليل العلامات (`<think>...</think>`) لنماذج الاستدلال
+- تحديد القيمة للتوافق مع OpenAI SDK
+- تطبيع الدور (المطور → النظام، النظام → المستخدم) للتوافق بين الموفرين
+- تحويل المنتج منظم (json_schema → Gemini ResponseSchema)
+- الثبات المحلي لمقدمي الخدمات والمفاتيح والأسماء المستعارة والمجموعات والإعدادات والتسعير
+- تتبع تكلفة/التكلفة وتسجيل الطلب
+- نوبات سحابية اختيارية للأجهزة/الحالة الثابتة
+- القائمة الخاصة بها/القائمة المحظورة لـ IP للتحكم في الوصول إلى واجهة برمجة التطبيقات
+- التفكير في إدارة الميزانية (العبور / التلقائي / المقصود / التكيفي)
+- هيكل البناء العالمي
+- تتبع البصمات
+- تحديد المحسن لكل حساب مع الملفات الشخصية الخاصة بالمزود
+- تقطع فاصل لمرونة المورد
+- حماية القطيع ضد الرعد مع موتكس
+- ذاكرة التخزين المؤقتة لإلغاء البيانات المكررة للطلبة المستندية للتوقيع
+- المجال: توفر النموذج، وقواعد التكلفة، والسياسة الاحتياطية، وسياسة فك الضغط
+- فرانسيسكوية المجال المجال (ذاكرة التخزين المؤقتة للكتاب في SQLite للاحتياطيات والميزانيات وفتح قواطع الضوء)
+- السياسة التي تحدد الطلب المركزي (التأمين → الميزانية → الاحتياطي)
+- طلب القياس عن بعد مع تجميع الكمون ص50/ص95/ص99
+- معرف الارتباط (X-Request-Id) للتتبع الشامل
+- تسجيل تدقيق كامل مع إلغاء الاشتراك لمفتاح API
+- إطار تقييمي وجودة LLM
+- لوحة تحكم واجهة المستخدم المرنة مع فاصل زمني في العمل
+- مفري OAuth المطاطيون (12 وحدة ضمن `src/lib/oauth/providers/`)
+
+وقت نموذج التشغيل الأساسي:
+
+- تقوم مسارات تطبيق Next.js ضمن `src/app/api/*` ولتتمكن كل من واجهات تطبيقات برمجة لوحة المعلومات وواجهات برمجة تطبيقات التوافق
+- نواة توجيه/SSE اشترك في `src/sse/*` + `open-sse/*` تمويل مع تنفيذ الموفر والترجمة والتدفق والرجوع والاستخدام## النطاق والحدود### In Scope
+
+- وقت تشغيل البوابة المحلية
+- واجهات برمجة التطبيقات المبتكرة للوحة المعلومات
+- مصادقة الموفر وتحديث الرمز المميز
+- طلب الترجمة و التدفق SSE
+- الحالة المحلية + استمرارية الاستخدام
+- نوبات سحابية اختيارية### خارج النطاق
+
+- تنفيذ خدمة السحابية خلف `NEXT_PUBLIC_CLOUD_URL`
+- مستوى تحرير السودان/مستوى التحكم خارج نطاق العمل
+- ثنائيات CLI الخارجية نفسها (Claude CLI، Codex CLI، وما إلى ذلك) ## سطح لوحة القيادة (الحالي)
+
+الصفحة الرئيسية ضمن `src/app/(dashboard)/dashboard/`:
+
+- `/dashboard` - بداية سريعة + نظرة عامة على الموفر
+- `/dashboard/endpoint` - وكيل نقطة النهاية + علامات نهاية نقطة النهاية MCP + A2A + API
+- `/dashboard/providers` - اتصالات الموفر وبيانات الاعتماد
+- `/dashboard/combos` - إستراتيجيات التحرير والسرد والقوالب وقواعد توجيه التطورات
+- `/dashboard/costs` - تجميع الأسعار ورؤية الأسعار
+- `/dashboard/analytics` - تحليلات تعاطيات البناء
+- `/dashboard/limits` - ضوابط الحصص/المعدلات
+- `/dashboard/cli-tools` - إعداد واجهة سطر مودم، والكشف عن وقت التشغيل، ويشمل ذلك
+- `/dashboard/agents` — تم ابتكار عملاء ACP + تسجيل عميل مخصص
+- `/dashboard/media` — ساحة لعب الصور/الفيديو/الموسيقى
+- `/dashboard/search-tools` - اختبار خريطة البحث
+- `/dashboard/health` - وقت التشغيل، قواطع الدائرة، حدود المعدل
+- `/dashboard/logs` - سجلات الطلب/الوكيل/التدقيق/وحدة التحكم
+- `/dashboard/settings` - علامات إعدادات النظام (عامة، توجيه، إعدادات التحرير والإعدادات البرمجية، إلخ.)
+- `/dashboard/api-manager` - دورة حياة مفتاح برمجة برمجة التطبيقات والأذونات النموذجية## سياق النظام عالي المستوى```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/Qoder/GitHub/Kiro/Cursor/Antigravity]
+          P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
+          P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
+      end
+
+      subgraph Cloud[Optional Cloud Sync]
+          CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL]
+      end
+
+      C1 --> API
+      C2 --> API
+      C3 --> API
+      C4 --> API
+      BROWSER --> DASH
+
+      API --> CORE
+      DASH --> DB
+      CORE --> DB
+      CORE --> UDB
+
+      CORE --> P1
+      CORE --> P2
+      CORE --> P3
+
+      DASH --> CLOUD
+
+````
+
+## Core Runtime Components
+
+## 1) API and Routing Layer (Next.js App Routes)
+
+الدلائل الرئيسية:
+
+- `src/app/api/v1/*` و `src/app/api/v1beta/*` لواجهات برمجة التطبيقات المتوافقة
+- `src/app/api/*` لواجهات برمجة تطبيقات للإدارة/التكوين
+- إعادة الكتابة التالية في الخريطة `next.config.mjs` `/v1/*` إلى `/api/v1/*`
+
+طرق التوافق:
+
+- `src/app/api/v1/chat/completions/route.ts`
+- `src/app/api/v1/messages/route.ts`
+- `src/app/api/v1/responses/route.ts`
+- `src/app/api/v1/models/route.ts` - تشمل نماذج مخصصة ذات `مخصصة: صحيح`
+- `src/app/api/v1/embeddings/route.ts` - إنشاء التضمين (6 مفري)
+- `src/app/api/v1/images/ Generations/route.ts` - إنشاء الصور (4+ موفري خدمات بما في ذلك Antigravity/Nebius)
+- `src/app/api/v1/messages/count_tokens/route.ts`
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` - دردشة مخصصة لكل المرشحين
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` - عمليات التضمين المخصصة لكل المجالات
+- `src/app/api/v1/providers/[provider]/images/ Generations/route.ts` - صور مخصصة لكل إطار
+- `src/app/api/v1beta/models/route.ts`
+- `src/app/api/v1beta/models/[...path]/route.ts`
+
+الفترات الإدارية:
+
+- المصادقة/الإعدادات: `src/app/api/auth/*`، `src/app/api/settings/*`
+- مقدمو الخدمة/الاتصالات: `src/app/api/providers*`
+- عقد الموفر: `src/app/api/provider-nodes*`
+- الروابط ذات الصلة: `src/app/api/provider-models` (GET/POST/DELETE)
+- كتالوج الارتباطات: `src/app/api/models/route.ts` (GET)
+- الوكيل التنفيذي: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
+- OAuth: `src/app/api/oauth/*`
+-لوحة المفاتيح/الأسماء المستعارة/المجموعات/التسعير: `src/app/api/keys*`، `src/app/api/models/alias`، `src/app/api/combos*`، `src/app/api/pricing`
+-استخدام: `src/app/api/usage/*`
+- الناقلات/السحابة: `src/app/api/sync/*`، `src/app/api/cloud/*`
+- مساعدي أدوات CLI: `src/app/api/cli-tools/*`
+- مرشح IP: `src/app/api/settings/ip-filter` (GET/PUT)
+- تكلفة التفكير: `src/app/api/settings/thinking-budget` (GET/PUT)
+- متشوق النظام: `src/app/api/settings/system-prompt` (GET/PUT)
+- الجلسات: `src/app/api/sessions` (GET)
+- النطاق المعدل: `src/app/api/rate-limits` (GET)
+- معطف: `src/app/api/resilience` (GET/PATCH) - ملفات تعريف الموفر، التفاضل والتكامل، حالة لا يمكن تعديلها
+- إعادة ضبط ضبط: `src/app/api/resilience/reset` (POST) - إعادة ضبط القواطع + تخفيف التهدئة
+- إحصائيات ذاكرة تخزين مؤقتة: `src/app/api/cache/stats` (GET/DELETE)
+- توفر النموذج: `src/app/api/models/availability` (GET/POST)
+- القياس عن بعد: `src/app/api/telemetry/summary` (GET)
+- الميزانية: `src/app/api/usage/budget` (GET/POST)
+- السلاسل الاحتياطية: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- تدقيق تماما: `src/app/api/compliance/audit-log` (GET)
+- التقييمات: `src/app/api/evals` (GET/POST)، `src/app/api/evals/[suiteId]` (GET)
+- للمزيد: `src/app/api/policies` (GET/POST)## 2) SSE + Translation Core
+
+وحدات السرعة الرئيسية:- الإدخال: `src/sse/handlers/chat.ts`
+- أريد الأساسي: `open-sse/handlers/chatCore.ts`
+- محولات تنفيذ الموفر: `open-sse/executors/*`
+- الاكتشاف الجديد/تكوين الموفر: `open-sse/services/provider.ts`
+- تحليل/حل النموذج: `src/sse/services/model.ts`، `open-sse/services/model.ts`
+- الحساب الاحتياطي للحساب: `open-sse/services/accountFallback.ts`
+- سجل الترجمة: `open-sse/translator/index.ts`
+- تحويلات الدفق: `open-sse/utils/stream.ts`، `open-sse/utils/streamHandler.ts`
+-الطلب/تطبيع الاستخدام: `open-sse/utils/usageTracking.ts`
+- فكر في محلل العناوين: `open-sse/utils/thinkTagParser.ts`
+-معالج التضمين: `open-sse/handlers/embeddings.ts`
+- سجل موفر التضمين: open-sse/config/embeddingRegistry.ts
+-معالج إنشاء الصور: `open-sse/handlers/imageGeneration.ts`
+- سجل موفر الصور: `open-sse/config/imageRegistry.ts`
+- تعريف القيمة: `open-sse/handlers/responseSanitizer.ts`
+- تطبيع الدور: `open-sse/services/roleNormalizer.ts`
+
+الخدمات (منطقة الأعمال):
+
+- اختيار الحساب/تسجيل النقاط: `open-sse/services/accountSelector.ts`
+- إدارة دورة حياة السياق: `open-sse/services/contextManager.ts`
+- فرض مرشح IP: `open-sse/services/ipFilter.ts`
+- تعقيب النظر: `open-sse/services/sessionManager.ts`
+-طلب إلغاء البيانات المكررة: `open-sse/services/signatureCache.ts`
+- البناء الكامل: `open-sse/services/systemPrompt.ts`
+- التفكير في إدارة الميزانية: `open-sse/services/thinkingBudget.ts`
+- توجيه نموذج حرف البدل: `open-sse/services/wildcardRouter.ts`
+- إدارة إلى حد التعديل: `open-sse/services/rateLimitManager.ts`
+- قاطع الدائرة: `open-sse/services/circuitBreaker.ts`
+
+وحدات المجال:
+
+- توفر النموذج: `src/lib/domain/modelAvailability.ts`
+- متطلبات/ميزانيات التكلفة: `src/lib/domain/costRules.ts`
+- السياسة الافتراضية: `src/lib/domain/fallbackPolicy.ts`
+- محلل التحرير والسرد: `src/lib/domain/comboResolver.ts`
+- تأمين التأمين: `src/lib/domain/lockoutPolicy.ts`
+- محرك السياسة: `src/domain/policyEngine.ts` - القفل المركزي ← الميزانية ← التقييم الاحتياطي
+- كتالوج الرموز لسبب: `src/lib/domain/errorCodes.ts`
+- معرف الطلب: `src/lib/domain/requestId.ts`
+- مهلة الجلب: `src/lib/domain/fetchTimeout.ts`
+-طلب القياس عن بعد: `src/lib/domain/requestTelemetry.ts`
+- شامل/الدقيق: `src/lib/domain/compliance/index.ts`
+- عداء التقييم: `src/lib/domain/evalRunner.ts`
+- دونية المجال المجال: `src/lib/db/domainState.ts` - SQLite CRUD للسلاسل الاحتياطية، والميزانيات، خسر التكلفة، وحالة القفل، وقواطع الضوء
+
+وحدات موفر OAuth (12 ملفًا فرديًا ضمن `src/lib/oauth/providers/`):
+
+- فهرس التسجيل: `src/lib/oauth/providers/index.ts`
+- مقدمو الخدمات الأشخاص: `claude.ts`، `codex.ts`، `gemini.ts`، `antigravity.ts`، `qode.ts`، `qwen.ts`، `kimi-coding.ts`، `github.ts`، `kiro.ts`، `cursor.ts`، `kilocode.ts`، `cline.ts`
+- طعام السباحة: `src/lib/oauth/providers.ts` - يُعاد تصديره من العناصر العناصر## 3) طبقة الثبات
+
+قاعدة بيانات الحالة الأساسية (SQLite):- المعرفة البشرية الأساسية: `src/lib/db/core.ts` (better-sqlite3، migrations، WAL)
+- واجهة إعادة التصدير: `src/lib/localDb.ts` (طبقة توافق مختلفة للمتصلين)
+- الملف: `${DATA_DIR}/storage.sqlite` (أو `$XDG_CONFIG_HOME/omniroute/storage.sqlite` عند الضرورة، وإلا `~/.omniroute/storage.sqlite`)
+- كيانات (الجداول + أسماء KV): ProvideConnections، وproviderNodes، وmodelAliases، والمجموعات، WapiKeys، والإعدادات، والتسعير،**customModels**،**proxyConfig**،**ipFilter**،**thinkingBudget**،**systemPrompt**
+
+بمرور الوقت الاستخدام:
+
+- الواجهة: `src/lib/usageDb.ts` (وحدات متحللة في `src/lib/usage/*`)
+- جداول SQLite في `storage.sqlite`: `usage_history`، `call_logs`، `proxy_logs`
+- تبرز عناصر الملف الاختياري للتوافق/تصحيح سبب (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
+- يتم رحيل ملفات JSON القديمة إلى SQLite عن طريق عمليات رحيل بدء التشغيل عند وجودها
+
+قاعدة بيانات المجال (SQLite):
+
+- `src/lib/db/domainState.ts` - عمليات إنتاج CRUD لحالة المجال
+- الجداول (التي تم تحديدها في `src/lib/db/core.ts`): `domain_fallback_chains`، `domain_budgets`، `domain_cost_history`، `domain_lockout_state`، `domain_circuit_breakers`.
+- نمط ذاكرة التخزين المؤقت للكتابة: قرص الاتصال موجود في الذاكرة الموثوقة في وقت التشغيل؛ تتم كتابة الطفرات بشكل متزامن إلى SQLite؛ يتم استعادة حالة قاعدة البيانات عند البداية الباردة ## 4) المصادقة + الأسطح الأمنية
+
+- مصادقة ملف تعريف الارتباط في لوحة المعلومات: `src/proxy.ts`، `src/app/api/auth/login/route.ts`
+- إنشاء/التحقق من مفتاح واجهة برمجة التطبيقات: `src/shared/utils/apiKey.ts`
+-أسرار الموفر في الخطوط "providerConnections".
+- دعم خارجي تمامًا عبر `open-sse/utils/proxyFetch.ts` (env vars) و`open-sse/utils/networkProxy.ts` (قابل للتكوين لكل المرشحين أو عالمي)## 5) Cloud Sync
+
+- جدولة init: `src/lib/initCloudSync.ts`، `src/shared/services/initializeCloudSync.ts`، `src/shared/services/modelSyncScheduler.ts`
+- أهم الأحداث: `src/shared/services/cloudSyncScheduler.ts`
+- أهم الأحداث: `src/shared/services/modelSyncScheduler.ts`
+- التحكم في المسار: `src/app/api/sync/cloud/route.ts`## دورة حياة الطلب (`/v1/chat/completions`)```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as CLI/SDK Client
+    participant Route as /api/v1/chat/completions
+    participant Chat as src/sse/handlers/chat
+    participant Core as open-sse/handlers/chatCore
+    participant Model as Model Resolver
+    participant Auth as Credential Selector
+    participant Exec as Provider Executor
+    participant Prov as Upstream Provider
+    participant Stream as Stream Translator
+    participant Usage as usageDb
+
+    Client->>Route: POST /v1/chat/completions
+    Route->>Chat: handleChat(request)
+    Chat->>Model: parse/resolve model or combo
+
+    alt Combo model
+        Chat->>Chat: iterate combo models (handleComboChat)
+    end
+
+    Chat->>Auth: getProviderCredentials(provider)
+    Auth-->>Chat: active account + tokens/api key
+
+    Chat->>Core: handleChatCore(body, modelInfo, credentials)
+    Core->>Core: detect source format
+    Core->>Core: translate request to target format
+    Core->>Exec: execute(provider, transformedBody)
+    Exec->>Prov: upstream API call
+    Prov-->>Exec: SSE/JSON response
+    Exec-->>Core: response + metadata
+
+    alt 401/403
+        Core->>Exec: refreshCredentials()
+        Exec-->>Core: updated tokens
+        Core->>Exec: retry request
+    end
+
+    Core->>Stream: translate/normalize stream to client format
+    Stream-->>Client: SSE chunks / JSON response
+
+    Stream->>Usage: extract usage + persist history/log
+````
+
+## Combo + Account Fallback Flow
+
+```mermaid
+flowchart TD
+    A[Incoming model string] --> B{Is combo name?}
+    B -- Yes --> C[Load combo models sequence]
+    B -- No --> D[Single model path]
+
+    C --> E[Try model N]
+    E --> F[Resolve provider/model]
+    D --> F
+
+    F --> G[Select account credentials]
+    G --> H{Credentials available?}
+    H -- No --> I[Return provider unavailable]
+    H -- Yes --> J[Execute request]
+
+    J --> K{Success?}
+    K -- Yes --> L[Return response]
+    K -- No --> M{Fallback-eligible error?}
+
+    M -- No --> N[Return error]
+    M -- Yes --> O[Mark account unavailable cooldown]
+    O --> P{Another account for provider?}
+    P -- Yes --> G
+    P -- No --> Q{In combo with next model?}
+    Q -- Yes --> E
+    Q -- No --> R[Return all unavailable]
+```
+
+يتم اتخاذ القرار الاحتياطي بواسطة `open-sse/services/accountFallback.ts` باستخدام رموز الحالة للاستدلال على رسائل الخطأ. تسهيل توجيه التشغيل والتنسيق بين الطرفين طوعًا للمساعدة في تقديم الطلبات: يتم التعامل مع 400s على نطاق الموفر مثل كتلة المحتوى الأول وفشل التحقق من صحة الدور على أنها فشل رئيسي للنموذج، لذا لا يزال لا يزال مطلوبًا التحرير والسرد التالي.## OAuth Onboarding and Token Refresh Lifecycle```mermaid
+sequenceDiagram
+autonumber
+participant UI as Dashboard UI
+participant OAuth as /api/oauth/[provider]/[action]
+participant ProvAuth as Provider Auth Server
+participant DB as localDb
+participant Test as /api/providers/[id]/test
+participant Exec as Provider Executor
+
+    UI->>OAuth: GET authorize or device-code
+    OAuth->>ProvAuth: create auth/device flow
+    ProvAuth-->>OAuth: auth URL or device code payload
+    OAuth-->>UI: flow data
+
+    UI->>OAuth: POST exchange or poll
+    OAuth->>ProvAuth: token exchange/poll
+    ProvAuth-->>OAuth: access/refresh tokens
+    OAuth->>DB: createProviderConnection(oauth data)
+    OAuth-->>UI: success + connection id
+
+    UI->>Test: POST /api/providers/[id]/test
+    Test->>Exec: validate credentials / optional refresh
+    Exec-->>Test: valid or refreshed token info
+    Test->>DB: update status/tokens/errors
+    Test-->>UI: validation result
+
+````
+
+يتم تنفيذ التحديث أثناء حركة التحرير المباشر داخل `open-sse/handlers/chatCore.ts` عبر المنفذ `refreshCredentials()`.## دورة حياة المزامنة السحابية (تمكين / مزامنة / تعطيل)```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Endpoint Page UI
+    participant Sync as /api/sync/cloud
+    participant DB as localDb
+    participant Cloud as External Cloud Sync
+    participant Claude as ~/.claude/settings.json
+
+    UI->>Sync: POST action=enable
+    Sync->>DB: set cloudEnabled=true
+    Sync->>DB: ensure API key exists
+    Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys)
+    Cloud-->>Sync: sync result
+    Sync->>Cloud: GET /{machineId}/v1/verify
+    Sync-->>UI: enabled + verification status
+
+    UI->>Sync: POST action=sync
+    Sync->>Cloud: POST /sync/{machineId}
+    Cloud-->>Sync: remote data
+    Sync->>DB: update newer local tokens/status
+    Sync-->>UI: synced
+
+    UI->>Sync: POST action=disable
+    Sync->>DB: set cloudEnabled=false
+    Sync->>Cloud: DELETE /sync/{machineId}
+    Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed)
+    Sync-->>UI: disabled
+````
+
+يتم تشغيل الدورية بواسطة "CloudSyncScheduler" عند السحابة.## نموذج البيانات وخريطة التخزين```mermaid
+erDiagram
+SETTINGS ||--o{ PROVIDER_CONNECTION : controls
+PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider
+PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage
+
+    SETTINGS {
+      boolean cloudEnabled
+      number stickyRoundRobinLimit
+      boolean requireLogin
+      string password_hash
+      string fallbackStrategy
+      json rateLimitDefaults
+      json providerProfiles
+    }
+
+    PROVIDER_CONNECTION {
+      string id
+      string provider
+      string authType
+      string name
+      number priority
+      boolean isActive
+      string apiKey
+      string accessToken
+      string refreshToken
+      string expiresAt
+      string testStatus
+      string lastError
+      string rateLimitedUntil
+      json providerSpecificData
+    }
+
+    PROVIDER_NODE {
+      string id
+      string type
+      string name
+      string prefix
+      string apiType
+      string baseUrl
+    }
+
+    MODEL_ALIAS {
+      string alias
+      string targetModel
+    }
+
+    COMBO {
+      string id
+      string name
+      string[] models
+    }
+
+    API_KEY {
+      string id
+      string name
+      string key
+      string machineId
+    }
+
+    USAGE_ENTRY {
+      string provider
+      string model
+      number prompt_tokens
+      number completion_tokens
+      string connectionId
+      string timestamp
+    }
+
+    CUSTOM_MODEL {
+      string id
+      string name
+      string providerId
+    }
+
+    PROXY_CONFIG {
+      string global
+      json providers
+    }
+
+    IP_FILTER {
+      string mode
+      string[] allowlist
+      string[] blocklist
+    }
+
+    THINKING_BUDGET {
+      string mode
+      number customBudget
+      string effortLevel
+    }
+
+    SYSTEM_PROMPT {
+      boolean enabled
+      string prompt
+      string position
+    }
+
+````
+
+ملفات الوضع المالي:
+
+- قاعدة بيانات وقت التشغيل الأساسي: `${DATA_DIR}/storage.sqlite`
+- أسطر سجل الطلب: `${DATA_DIR}/log.txt` (أداة متوافقة/تصحيح سبب)
+- أرشيفات استضافة المؤتمرات التنظيمية: `${DATA_DIR}/call_logs/`
+- مجموعات تصحيح الأخطاء المترجم/الطلب الاختيارية: `<repo>/logs/...`## Deployment Topology```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
+````
+
+## Module Mapping (Decision-Critical)
+
+### Route and API Modules
+
+- `src/app/api/v1/*`، `src/app/api/v1beta/*`: واجهات برمجة التطبيقات المتوافقة
+- `src/app/api/v1/providers/[provider]/*`: مسارات مخصصة لكل دليل (الدردشة والتضمينات والصور)
+- `src/app/api/providers*`: موفر CRUD، التحقق من الصحة، الاختبار
+- `src/app/api/provider-nodes*`: إدارة العقد المتوافقة المخصصة
+- `src/app/api/provider-models`: إدارة الارتباطات المخصصة (CRUD)
+- `src/app/api/models/route.ts`: برمجة تطبيقات كتالوج الارتباطات (الأسماء المستعارة + الارتباطات البديلة)
+- `src/app/api/oauth/*`: تدفقات رمز OAuth/الجهاز
+- `src/app/api/keys*`: دورة حياة مفتاح برمجة التطبيقات المحلية
+- `src/app/api/models/alias`: إدارة الأسماء المستعارة
+- `src/app/api/combos*`: إدارة التحرير والسرد الاحتياطي
+- `src/app/api/pricing`: تجاوزات التسعير لحساب التكلفة
+- `src/app/api/settings/proxy`: الصارم المعتمد (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: اختبار تشغيل الوكيل (POST)
+- `src/app/api/usage/*`: واجهات برمجة تطبيقات الاستخدام والسجلات
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: نوبات السحابية والمساعدون الذين يتحملون السحابة
+- `src/app/api/cli-tools/*`: كاتب/أداة الدما لتكوين CLI المحلي
+- `src/app/api/settings/ip-filter`: قائمة IP مخصصة لها/القائمة المبتكرة (GET/PUT)
+- `src/app/api/settings/thinking-budget`: الاختيار المناسب رمز التفكير (GET/PUT)
+- `src/app/api/settings/system-prompt`: موجه النظام العام (GET/PUT)
+- `src/app/api/sessions`: قائمة العناصر العضوية (GET)
+- `src/app/api/rate-limits`: حالة لا يمكن تعديلها لكل حساب (GET)### التوجيه والتنفيذ الأساسي
+
+- `src/sse/handlers/chat.ts`: تحليل الطلب، ومعالجة التحرير والسرد، حلقة الحساب
+- `open-sse/handlers/chatCore.ts`: الترجمة، المنفذ، إعادة المحاولة/التحديث، إعداد الدفق
+- `open-sse/executors/*`: التحكم الشبكة والتنسيق الخاص بالموفر### سجل الترجمة ومحولات التنسيق
+
+- `open-sse/translator/index.ts`: تسجيل المترجم وتنسيقه
+  -طلب المترجمين: `open-sse/translator/request/*`
+- مترجمو المصدر: `open-sse/translator/response/*`
+- ثوابت عادة: `open-sse/translator/formats.ts`### Persistence
+
+- `src/lib/db/*`: تفعيل/الحالة الفعالة واستمرارية المجال على SQLite
+- `src/lib/localDb.ts`: إعادة تصدير التوافق لوحدات قاعدة البيانات
+- `src/lib/usageDb.ts`: واجهة سجل/سجلات استخدامات المكالمات أعلى جداول SQLite## Provider Executor Coverage (Strategy Pattern)
+
+| يحتوي على كل موفر على منفذ تنفيذي متخصص لعدة `BaseExecutor` (في `open-sse/executors/base.ts`)، والذي يوفر بيانات إنشاء عنوان URL، ولكنه، جاهز المحاولة مع الأسيي، ومآثر تحديث الاعتماد، وطريقة استمرار `execute()`. | المنفذ                                                                                                                                                                  | المزود (المقدمون)                                                       | التعامل الخاص |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------- |
+| `المنفذ الافتراضي`                                                                                                                                                                                                  | أوبن إيه آي، كلود، جيميني، كوين، كيودر، أوبن روتر، جي إل إم، كيمي، ميني ماكس، ديب سيك، جروك، إكس آي آي، ميسترال، بيربليكسيتي، توغا، فاير ووركس، سيريبراس، كوهير، نفيديا | الاختيارية عنوان URL/الرأس الكيميائي لكل                                |
+| `منفذ مضاد للجغرافيا`                                                                                                                                                                                               | جوجل مكافحة الجاذبية                                                                                                                                                    | معرفات المشروع/الجلسة المخصصة، إعادة المحاولة بعد التحليل               |
+| `منفذ الكودكس`                                                                                                                                                                                                      | OpenAI Codex                                                                                                                                                            | يحقن تعليمات النظام، ويفرض جهدًا منطقيًا                                |
+| `منفذ مفصل`                                                                                                                                                                                                         | بيئة تطوير متكاملة للمؤشر                                                                                                                                               | البروتوكول ConnectRPC، ترجمة Protobuf، طلب التوقيع عبر الفصول الاختباري |
+| `GithubExecutor`                                                                                                                                                                                                    | جيثب مساعد الطيار                                                                                                                                                       | تحديث الرمز المميز لـ Copilot، ورؤوس محاكاة VSCode                      |
+| `KiroExecutor`                                                                                                                                                                                                      | AWS CodeWhisperer/كيرو                                                                                                                                                  | يتغير الثنائي لـ AWS EventStream → تحويل SSE                            |
+| `الجوزاءCLIEExecutor`                                                                                                                                                                                               | الجوزاء CLI                                                                                                                                                             | دورة تحديث رمز OAuth المميز لـ Google                                   |
+
+| يستخدم جميع الموفرين الآخرين (بما في ذلك العقد المتوافق المخصص) "DefaultExecutor".## مصفوفة توافق الموفرين | مقدم             | التنسيق                                | مصادقة          | تيار مستمر | غير دفق | تحديث الرمز المميز      | برمجة تطبيقات الاستخدام |
+| ---------------------------------------------------------------------------------------------------------- | ---------------- | -------------------------------------- | --------------- | ---------- | ------- | ----------------------- | ----------------------- |
+| كلود                                                                                                       | كلود             | واجهة برمجة التطبيقات الرئيسية / OAuth | ✅              | ✅         | ✅      | ⚠️ المشرف فقط           |
+| الجوزاء                                                                                                    | الجوزاء          | واجهة برمجة التطبيقات الرئيسية / OAuth | ✅              | ✅         | ✅      | ⚠️ وحدة التحكم السحابية |
+| الجوزاء CLI                                                                                                | الجوزاء-cli      | أووث                                   | ✅              | ✅         | ✅      | ⚠️ وحدة التحكم السحابية |
+| مكافحة الجاذبية                                                                                            | ضد الجاذبية      | أووث                                   | ✅              | ✅         | ✅      | ✅ الحصة الكاملة API    |
+| أوبن آي                                                                                                    | أوبيناي          | مفتاح واجهة برمجة التطبيقات            | ✅              | ✅         | ❌      | ❌                      |
+| الدستور الغذائي                                                                                            | openai-responses | أووث                                   | ✅ مجبور        | ❌         | ✅      | ✅الحدود المعدلة        |
+| جيثب مساعد الطيار                                                                                          | أوبيناي          | OAuth + رمز مساعد الطيار               | ✅              | ✅         | ✅      | ✅ لقطات الحصص          |
+|                                                                                                            | مؤثر             | مؤثر الاستطلاع المفضل                  | ✅              | ✅         | ❌      | ❌                      |
+| كيرو                                                                                                       | كيرو             | AWS SSO OIDC                           | ✅(ايفنت ستريم) | ❌         | ✅      | ✅ حدود الاستخدام       |
+| كوين                                                                                                       | أوبيناي          | أووث                                   | ✅              | ✅         | ✅      | ⚠️ طلب حسب الطلب        |
+| قدير                                                                                                       | أوبيناي          | OAuth (أساسي)                          | ✅              | ✅         | ✅      | ⚠️ طلب حسب الطلب        |
+| اوبن راوتر                                                                                                 | أوبيناي          | مفتاح واجهة برمجة التطبيقات            | ✅              | ✅         | ❌      | ❌                      |
+| جي إل إم/كيمي/ميني ماكس                                                                                    | كلود             | مفتاح واجهة برمجة التطبيقات            | ✅              | ✅         | ❌      | ❌                      |
+| ديب سيك                                                                                                    | أوبيناي          | مفتاح واجهة برمجة التطبيقات            | ✅              | ✅         | ❌      | ❌                      |
+| جروك                                                                                                       | أوبيناي          | مفتاح واجهة برمجة التطبيقات            | ✅              | ✅         | ❌      | ❌                      |
+| xAI (جروك)                                                                                                 | أوبيناي          | مفتاح واجهة برمجة التطبيقات            | ✅              | ✅         | ❌      | ❌                      |
+| ميسترال                                                                                                    | أوبيناي          | مفتاح واجهة برمجة التطبيقات            | ✅              | ✅         | ❌      | ❌                      |
+| الحيرة                                                                                                     | أوبيناي          | مفتاح واجهة برمجة التطبيقات            | ✅              | ✅         | ❌      | ❌                      |
+| منظمة العفو الدولية                                                                                        | أوبيناي          | مفتاح واجهة برمجة التطبيقات            | ✅              | ✅         | ❌      | ❌                      |
+| منظمة العفو الدولية للعبة                                                                                  | أوبيناي          | مفتاح واجهة برمجة التطبيقات            | ✅              | ✅         | ❌      | ❌                      |
+| الشيخ                                                                                                      | أوبيناي          | مفتاح واجهة برمجة التطبيقات            | ✅              | ✅         | ❌      | ❌                      |
+| كوهير                                                                                                      | أوبيناي          | مفتاح واجهة برمجة التطبيقات            | ✅              | ✅         | ❌      | ❌                      |
+| نفيديا نيم                                                                                                 | أوبيناي          | مفتاح واجهة برمجة التطبيقات            | ✅              | ✅         | ❌      | ❌                      | ## تنسيق تغطية الترجمة  |
+
+تتضمن التنسيقات المصدر المكتشفة ما يلي:
+
+- `أوبيني`
+- `الردود المفتوحة`
+- "كلود".
+- "الجوزاء".
+
+تتضمن الواردات التفصيلية ما يلي:
+
+- دردشة/ردود OpenAI
+- كلود
+  -الجوزاء/الجوزاء-CLI/الظرف للجاذبية
+- كيرو
+- مرض
+
+استخدم الترجمات**OpenAI كتنسيق مركزي**— جرب جميع التحويلات عبر OpenAI كتنسيق وسيط:`
+تنسيق المصدر → OpenAI (المحور) → التنسيق المستهدف`
+
+يتم تحديد الترجمات ديناميكيًا استنادًا إلى شكل حمولة المصدر والتنسيق المستهدف للموفر.
+
+طبقات معالجة إضافية في مسار الترجمة:
+
+-**تطهير الاستجابة**— يزيل الحقول غير القياسية من استجابات تنسيق OpenAI (سواء المتدفقة أو غير المتدفقة) لضمان الامتثال الصارم لـ SDK -**تطبيع الدور**— تحويل `المطور` ← `النظام` للأهداف غير التابعة لـ OpenAI؛ يدمج "النظام" → "المستخدم" للنماذج التي ترفض دور النظام (GLM، ERNIE) -**استخراج علامة التفكير**— يوزع كتل `<think>...</think>` من المحتوى إلى حقل `reasoning_content` -**الإخراج المنظم**— يحول OpenAI `response_format.json_schema` إلى `responseMimeType` + `responseSchema` الخاص بـ Gemini## Supported API Endpoints
+
+| نقطة النهاية                                       | تنسيق              | معالج                                                                     |
+| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------------- | ----------------- |
+| `POST /v1/chat/completions`                        | دردشة OpenAI       | `src/sse/handlers/chat.ts`                                                |
+| `POST /v1/messages`                                | رسائل كلود         | نفس المعالج (تم اكتشافه تلقائيًا)                                         |
+| `POST /v1/responses`                               | ردود OpenAI        | `open-sse/handlers/responsesHandler.ts`                                   |
+| `POST /v1/embeddings`                              | تضمينات OpenAI     | `open-sse/handlers/embeddings.ts`                                         |
+| `الحصول على /v1/embeddings`                        | قائمة النماذج      | طريق API                                                                  |
+| `POST /v1/images/أجيال`                            | صور OpenAI         | `open-sse/handlers/imageGeneration.ts`                                    |
+| `الحصول على /v1/images/أجيال`                      | قائمة النماذج      | طريق API                                                                  |
+| `POST /v1/providers/{provider}/chat/completions`   | دردشة OpenAI       | مخصص لكل مزود مع التحقق من صحة النموذج                                    |
+| `POST /v1/providers/{provider}/embeddings`         | تضمينات OpenAI     | مخصص لكل مزود مع التحقق من صحة النموذج                                    |
+| `POST /v1/providers/{provider}/images/generations` | صور OpenAI         | مخصص لكل مزود مع التحقق من صحة النموذج                                    |
+| `POST /v1/messages/count_tokens`                   | عدد كلود توكن      | طريق API                                                                  |
+| `الحصول على /v1/models`                            | قائمة نماذج OpenAI | مسار واجهة برمجة التطبيقات (الدردشة + التضمين + الصورة + النماذج المخصصة) |
+| `الحصول على /api/models/catalog`                   | كتالوج             | جميع النماذج مجمعة حسب الموفر + النوع                                     |
+| `POST /v1beta/models/*:streamGenerateContent`      | مولود برج الجوزاء  | طريق API                                                                  |
+| `الحصول على/PUT/DELETE /api/settings/proxy`        | تكوين الوكيل       | تكوين وكيل الشبكة                                                         |
+| `POST /api/settings/proxy/test`                    | اتصال الوكيل       | نقطة نهاية اختبار صحة الوكيل/الاتصال                                      |
+| `الحصول على/النشر/الحذف /api/provider-models`      | نماذج المزود       | البيانات الوصفية لنموذج الموفر تدعم النماذج المتاحة المخصصة والمدارة      | ## Bypass Handler |
+
+يعترض معالج التجاوز (`open-sse/utils/bypassHandler.ts`) طلبات "رمية سريعة" معروفة من Claude CLI - أصوات التمهيد، واستخراج العناوين، وعدد الرموز المميزة - ويعيد**استجابة زائفة**دون استهلاك الرموز المميزة للموفر الرئيسي. يتم تشغيل هذا فقط عندما يحتوي "User-Agent" على "clude-cli".## Request Logger Pipeline
+
+يوفر مسجل الطلب (`open-sse/utils/requestLogger.ts`) مسارًا لتسجيل تصحيح الأخطاء مكون من 7 مراحل، معطل افتراضيًا، وممكن عبر `ENABLE_REQUEST_LOGS=true`:```
+1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json
+→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt
+
+```
+
+تتم كتابة الملفات إلى `<repo>/logs/<session>/` لكل جلسة طلب.## أوضاع الفشل والمرونة## 1) Account/Provider Availability
+
+- عبارة عن حساب الموفر عند أخطاء/معدل/مصادقة
+- إرجاع الحساب قبل فشل الطلب
+- نموذج التحرير والسرد الاحتياطي عند استنفاد مسار النموذج/المزود الحالي## 2) Token Expiry
+
+- ملفات التقدم والتحديث مع إعادة محاولة توفير خدمة موثوقة للتحديث
+- 401/403 إعادة المحاولة بعد محاولة التحديث في المسار الأساسي## 3) Stream Safety
+
+- وحدة تحكم قطع الاتصال بالتيار المستمر
+- دفق الترجمة تدفق مع نهاية الدفق و `[تم]`
+- ترخيص للاستخدام عندما تكون البيانات الوصفية للاستخدام الموفر المفقود## 4) تدهور المزامنة السحابية
+
+- أخطاء الأخطاء ولكن استمر تشغيلها محليًا
+- يحتوي على المجدول على منطقه قادر على إعادة المحاولة، ولكن التنفيذ الدوري يستدعي حاليا متزامنة التفعيل بشكل افتراضي## 5) Data Integrity
+
+- عمليات ترحيل مخطط SQLite وفواتير الترقية التلقائية عند بدء التشغيل
+- JSON القديم → مسار التوافق ترحيل SQLite## إمكانية المراقبة والإشارات التشغيلية
+
+مصادر معرفة وقت التشغيل:
+
+- أرشيف وحدة التحكم من `src/sse/utils/logger.ts`
+- مجاميع الاستخدام لكل طلب في SQLite (`usage_history`، `call_logs`، `proxy_logs`)
+- التقاط التفاصيل الصافية الصافية على أربع مراحل في SQLite (`request_detail_logs`) عندما تكون `settings.detailed_logs_enabled=true`
+- سجل حالة الطلب النصي في "log.txt" (اختياري/متوافق)
+- سجلات الطلب/الترجمة المتخصصة الاختيارية ضمن `السجلات/` عندما يكون `ENABLE_REQUEST_LOGS=true`
+- نقاط نهاية استخدام معلومات اللوحة (`/api/usage/*`) لاستهلاك واجهة المستخدم
+
+يقوم بالتقاط تكتيكات متعددة بتخزين ما يصل إلى أربع مراحل من نشاطات JSON لكل ما يستقبل بصرية:
+
+- الطلب الوارد من العميل
+- تم إرسال الطلب المترجم إلى المنبع
+- إعادة بناء الرابط الموفر JSON؛ يتم ضغط الاستجابات المتدفقة إلى الملخص النهائي بالإضافة إلى بيانات تعريف الدفق
+-الرد النهائي الذي تم إرجاعه بواسطة OmniRoute؛ يتم تخزين الاستجابات المتدفقة في نفس النموذج الملخص المكون## الحدود الحساسة للأمان
+
+- يعمل سر JWT (`JWT_SECRET`) على تأمين المصادقة/التوقيع على ملف تعريف الارتباط لجلسة لوحة المعلومات
+- يجب الالتزام بالبراءة الأولية لكلمة المرور (`INITIAL_PASSWORD`) ووافق على الاعتراف بها لأول مرة
+- يعمل سر HMAC لمفتاح API (`API_KEY_SECRET`) على تنسيق تنسيق مفتاح API المحلي الذي تم التعاقد معه
+- تظلل أسرار الموفر (مفاتيح/رموز برمجة التطبيقات) موجودة في قاعدة البيانات الأصلية وحماتها على مستوى نظام الملفات
+- تعتمد نقاط نهاية الهجمات السحابية على مصادقة مفتاح API + دلالات معرف الجهاز## مصفوفة البيئة ووقت التشغيل
+
+تحريرات البيئة المستخدمة بشكل نشط بواسطة تعليمات الحظر:- التطبيق/المصادقة: `JWT_SECRET`، `INITIAL_PASSWORD`
+- التخزين: `DATA_DIR`
+- العقدة المتوافقة: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
+- تجاوز قاعدة الاختيار الاختيارية (Linux/macOS عند إلغاء تعيين `DATA_DIR`): `XDG_CONFIG_HOME`
+- التجزئة الأمنية: `API_KEY_SECRET`، `MACHINE_ID_SALT`
+- التسجيل: `ENABLE_REQUEST_LOGS`
+- عناوين URL للاستقبال/السحابة: `NEXT_PUBLIC_BASE_URL`، `NEXT_PUBLIC_CLOUD_URL`
+- الوكيل الشامل: `HTTP_PROXY`، `HTTPS_PROXY`، `ALL_PROXY`، `NO_PROXY` ومتغيرات الصغيرة الصغيرة
+- علامات ميزات SOCKS5: `ENABLE_SOCKS5_PROXY`، `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
+- مساعدو النظام الأساسي/وقت التشغيل (وليس تفعيل الخاص بالتطبيق): `APPDATA`، `NODE_ENV`، `PORT`، `HOSTNAME`## الملاحظات المعمارية المعروفة
+
+1. تشارك `usageDb` و`localDb` في نفس الدليل الأساسي (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> ``~/.omniroute`) مع ترحيل الملفات القديمة.
+2. يفوض `/api/v1/route.ts` إلى نفس منشئ الكتالوج الموحد الذي يستخدمه `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) العلم الانحراف الدلالي.
+3. يقوم بطلب تسجيل بكتابة الرؤوس/النص الكامل عند جاكسونه؛ التعامل مع سجل الدليل على أنه حساسية.
+4. يعتمد حماية السحابة على `NEXT_PUBLIC_BASE_URL` صحيح وإمكانية الوصول إلى نقطة نهاية السحابة.
+5. تم نشر الدليل `open-sse/` باسم `@omniroute/open-sse`**حزمة مساحة العمل npm**. يقوم بكود المصدر باستيراده عبر `@omniroute/open-sse/...` (تم حله بواسطة Next.js `transpilePackages`). لا تسلك الطرق المستمرة في هذا المستند استخدم اسم الدليل `open-sse/` للاتساق.
+6. نستخدم الكائنات الموجودة في لوحة المعلومات**Recharts**(المستندة إلى SVG) لتصورات التحليلات التفاعلية التي يمكن الوصول إليها (المخططات الشريطية للاستخدام للنموذج، والجرافيك المستخدمة للمخرجين مع النجاح).
+7.استخدام السيولة E2E**Playwright**(`tests/e2e/`)، ويمكنها عبر `npm run test:e2e`. المستخدمة في الوحدة**Node.js test runner**(`tests/unit/`)، ويمكن تشغيلها عبر `npm run test:unit`. كود المصدر ضمن `src/` هو**TypeScript**(`.ts`/`.tsx`)؛ تختلف مساحة العمل `open-sse/` JavaScript (`.js`).
+8. تم ضبط صفحة الإعدادات في 5 علامات: الأمان، التوجيه (6 إستراتيجيات عالمية: التعبئة العامة، جولة روبن، p2c، تنظيم غير محدد لاستخدامًا، تحسين التكلفة)، اشتراك (حدود الرسوم المتحركة للتحرير، قطع الدقة، إبداع)، الذكاء الاصطناعي (ميزانية التفكير، متشوق للنظام، ذاكرة التخزين المؤقت السريع)، المتقدمة (الوكيل).## قائمة التحقق من التشغيل
+
+- البناء من المصدر: ``npm run build``
+- إنشاء صورة Docker: `docker build -t omniroute .`
+- بدء الخدمة والتحقق:
+- `الحصول على /api/settings`
+- `الحصول على /api/v1/models`
+- يجب أن يكون عنوان URL الأساسي لهدف واجهة سطر اللاسلكي هو `http://<host>:20128/v1` عندما يكون `PORT=20128`
+```

docs/i18n/ar/docs/AUTO-COMBO.md

@@ -0,0 +1,55 @@
+# OmniRoute Auto-Combo Engine (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/AUTO-COMBO.md) · 🇪🇸 [es](../../es/docs/AUTO-COMBO.md) · 🇫🇷 [fr](../../fr/docs/AUTO-COMBO.md) · 🇩🇪 [de](../../de/docs/AUTO-COMBO.md) · 🇮🇹 [it](../../it/docs/AUTO-COMBO.md) · 🇷🇺 [ru](../../ru/docs/AUTO-COMBO.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) · 🇯🇵 [ja](../../ja/docs/AUTO-COMBO.md) · 🇰🇷 [ko](../../ko/docs/AUTO-COMBO.md) · 🇸🇦 [ar](../../ar/docs/AUTO-COMBO.md) · 🇮🇳 [hi](../../hi/docs/AUTO-COMBO.md) · 🇮🇳 [in](../../in/docs/AUTO-COMBO.md) · 🇹🇭 [th](../../th/docs/AUTO-COMBO.md) · 🇻🇳 [vi](../../vi/docs/AUTO-COMBO.md) · 🇮🇩 [id](../../id/docs/AUTO-COMBO.md) · 🇲🇾 [ms](../../ms/docs/AUTO-COMBO.md) · 🇳🇱 [nl](../../nl/docs/AUTO-COMBO.md) · 🇵🇱 [pl](../../pl/docs/AUTO-COMBO.md) · 🇸🇪 [sv](../../sv/docs/AUTO-COMBO.md) · 🇳🇴 [no](../../no/docs/AUTO-COMBO.md) · 🇩🇰 [da](../../da/docs/AUTO-COMBO.md) · 🇫🇮 [fi](../../fi/docs/AUTO-COMBO.md) · 🇵🇹 [pt](../../pt/docs/AUTO-COMBO.md) · 🇷🇴 [ro](../../ro/docs/AUTO-COMBO.md) · 🇭🇺 [hu](../../hu/docs/AUTO-COMBO.md) · 🇧🇬 [bg](../../bg/docs/AUTO-COMBO.md) · 🇸🇰 [sk](../../sk/docs/AUTO-COMBO.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) · 🇮🇱 [he](../../he/docs/AUTO-COMBO.md) · 🇵🇭 [phi](../../phi/docs/AUTO-COMBO.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) · 🇨🇿 [cs](../../cs/docs/AUTO-COMBO.md) · 🇹🇷 [tr](../../tr/docs/AUTO-COMBO.md)
+
+---
+
+> نماذج النماذج الذاتية الإدارة مع تسجيل التعديلات التكيفية## How It Works
+
+يقوم محرك التحرير والسرد التلقائي باختيار أفضل/نموذج ديناميكي لكل طلب باستخدام**وظيفة تسجيل مكونة من 6 اختيارات**:
+
+| عامل            | الوزن | الوصف                                  |
+| :-------------- | :---- | :------------------------------------- | ------------- |
+| الحصة           | 0.20  | القدرة المتبقية [0..1]                 |
+| الصحة           | 0.25  | الفاصل: مغلق=1.0، نصف=0.5، مفتوح=0.0   |
+| تكلفة الاستثمار | 0.20  | التكلفة العكسية (أرخص = الدرجة الأعلى) |
+| الكمون          | 0.15  | الكمون العكسي p95 (أسرع = الأعلى)      |
+| تاسكفيت         | 0.10  | نموذج × درجة اللياقة البدنية لنوع مهم  |
+|                 | 0.10  | متباينة في الوصول إلى زمن/الأخطاء      | ## Mode Packs |
+
+| حزمة                     | التركيز    | الوزن الرئيسي       |
+| :----------------------- | :--------- | :------------------ | ---------------- |
+| 🚀**الشحن السريع**       | السرعة     | الكمون: 0.35        |
+| 💰**توفير التكلفة**      | اقتصاد     | تكلفة التكلفة: 0.40 |
+| 🎯**الجودة الجديدة**     | أفضل نموذج | المهمة فيت: 0.40    |
+| 📡**غير متصل بالإنترنت** | التوفر     | الحصة: 0.40         | ## الشفاء الذاتي |
+
+-**الاستبعاد المؤقت**: النتيجة < 0.2 ← تم الاستبعاد لمدة 5 صباحا ( التراجع المتقدم، الأقصى 30 دقيقة) -**التوعية بقاطع الدورة**: مفتوح → مدمر التدمير؛ HALF_OPEN → طلبات التحقيق -**وضع الحادث**: >50% متوقع → ثم الاستكشاف المتوقع -**استرداد فترة التهدئة**: بعد الاختفاء، يكون الطلب الأول من "تحقيق" مع مهلة الأقل## Bandit Exploration
+
+يتم توجيه 5% من الطلبات (القابلة للتكوين) إلى موفر خدمات غير آمنة للاستكشاف. معطل في الحادث.## API```bash
+
+# Create auto-combo
+
+curl -X POST http://localhost:20128/api/combos/auto \
+ -H "Content-Type: application/json" \
+ -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}'
+
+# List auto-combos
+
+curl http://localhost:20128/api/combos/auto
+
+```
+
+## Task Fitness
+
+تم تسجيل أكثر من 30 نموذجًا عبر 6 أنواع من المهام (`الترميز`، و`المراجعة`، و`التخطيط`، و`التحليل`، و`تصحيح سبب`، و`التوثيق`). محترف أحرف البدل (على سبيل المثال، `*-coder` → درجة ترميز عالية).## Files
+
+| ملف | الحصاد |
+| :------------------------------------------- | :------------------------------------ |
+| `open-sse/services/autoCombo/scoring.ts` | وظيفة الهديف وتطبيع التكيف |
+| `open-sse/services/autoCombo/taskFitness.ts` | نموذج × مهمة بحث اللياقة البدنية |
+| `open-sse/services/autoCombo/engine.ts` | الاختيار المنطقي، قطاع الطرق، ميزانية الإنفاق |
+| `open-sse/services/autoCombo/selfHealing.ts` | الابعاد، التفاصيل، حالة الحادث |
+| `open-sse/services/autoCombo/modePacks.ts` | 4 ملفات تعريف للوزن |
+| `src/app/api/combos/auto/route.ts` | ريست API |
+```

docs/i18n/ar/docs/CLI-TOOLS.md

@@ -0,0 +1,289 @@
+# CLI Tools Setup Guide — OmniRoute (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/CLI-TOOLS.md) · 🇪🇸 [es](../../es/docs/CLI-TOOLS.md) · 🇫🇷 [fr](../../fr/docs/CLI-TOOLS.md) · 🇩🇪 [de](../../de/docs/CLI-TOOLS.md) · 🇮🇹 [it](../../it/docs/CLI-TOOLS.md) · 🇷🇺 [ru](../../ru/docs/CLI-TOOLS.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) · 🇯🇵 [ja](../../ja/docs/CLI-TOOLS.md) · 🇰🇷 [ko](../../ko/docs/CLI-TOOLS.md) · 🇸🇦 [ar](../../ar/docs/CLI-TOOLS.md) · 🇮🇳 [hi](../../hi/docs/CLI-TOOLS.md) · 🇮🇳 [in](../../in/docs/CLI-TOOLS.md) · 🇹🇭 [th](../../th/docs/CLI-TOOLS.md) · 🇻🇳 [vi](../../vi/docs/CLI-TOOLS.md) · 🇮🇩 [id](../../id/docs/CLI-TOOLS.md) · 🇲🇾 [ms](../../ms/docs/CLI-TOOLS.md) · 🇳🇱 [nl](../../nl/docs/CLI-TOOLS.md) · 🇵🇱 [pl](../../pl/docs/CLI-TOOLS.md) · 🇸🇪 [sv](../../sv/docs/CLI-TOOLS.md) · 🇳🇴 [no](../../no/docs/CLI-TOOLS.md) · 🇩🇰 [da](../../da/docs/CLI-TOOLS.md) · 🇫🇮 [fi](../../fi/docs/CLI-TOOLS.md) · 🇵🇹 [pt](../../pt/docs/CLI-TOOLS.md) · 🇷🇴 [ro](../../ro/docs/CLI-TOOLS.md) · 🇭🇺 [hu](../../hu/docs/CLI-TOOLS.md) · 🇧🇬 [bg](../../bg/docs/CLI-TOOLS.md) · 🇸🇰 [sk](../../sk/docs/CLI-TOOLS.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) · 🇮🇱 [he](../../he/docs/CLI-TOOLS.md) · 🇵🇭 [phi](../../phi/docs/CLI-TOOLS.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) · 🇨🇿 [cs](../../cs/docs/CLI-TOOLS.md) · 🇹🇷 [tr](../../tr/docs/CLI-TOOLS.md)
+
+---
+
+يشرح هذا الدليل كيفية تثبيت وتكوين جميع أدوات CLI البسيطة للذكاء الاصطناعي والمدعم
+استخدام**OmniRoute**ك واجهة خلفية موحدة، مما يتيح لك إدارة المفاتيح التركية،
+تتبع التكلفة، وتبديل الارتباطات، والتسجيل عبر كل أداة.---## How It Works
+
+```
+Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot
+           │
+           ▼  (all point to OmniRoute)
+    http://YOUR_SERVER:20128/v1
+           │
+           ▼  (OmniRoute routes to the right provider)
+    Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...
+```
+
+**الفوائد:**
+
+- مفتاح API واحد لإبتكار جميع الأدوات
+- تتبع التكلفة عبر جميع CLIs في لوحة المعلومات
+- النموذج النموذجي دون إعادة كل أداة
+- يعمل محليا وعلى الموقع البعيد (VPS)---## Supported Tools (Dashboard Source of Truth)
+
+يتم إنشاء بطاقة معلومات اللوحة في `/dashboard/cli-tools` من `src/shared/constants/cliTools.ts`.
+القائمة الحالية (v3.0.0-rc.16):
+
+| أداة                  | معرف             | الأمر         | وضع الإعداد | طريقة التثبيت      |
+| --------------------- | ---------------- | ------------- | ----------- | ------------------ | ----------------------------------------- |
+| **كود كلود**          | "كلود"           | "كلود"        | ببيئة       | نم                 |
+| **مخطوطة OpenAI**     | `المخطوطة`       | `المخطوطة`    | مخصص        | نم                 |
+| **مصنع الروبوت**      | "الروبوت"        | "الروبوت"     | مخصص        | المجمعة/CLI        |
+| **أوبنكلاو**          | `مخلب مفتوح`     | `مخلب مفتوح`  | مخصص        | المجمعة/CLI        |
+| **المؤشر**            | `المؤشر`         | التطبيق       | دليل        | تطبيق سطح المكتب   |
+| **كلاين**             | `كلاين`          | `كلاين`       | مخصص        | نم                 |
+| **كيلو كود**          | `كيلو`           | `الكيلو كود`  | مخصص        | نم                 |
+| **تابع**              | `متابعة`         | امتداد        | دليل        | كود مقابل          |
+| **مضادة الجاذبية**    | `مضادة الجاذبية` |               | ميتوم       | أومنيروتي          |
+| **جيثب مساعد الطيار** | `مساعد الطيار`   | امتداد        | مخصص        | كود مقابل          |
+| **الكود مفتوح**       | `الرمز مفتوح`    | `الرمز مفتوح` | دليل        | نم                 |
+| **كيرو آي**           | `كيرو`           | التطبيق/كلي   | ميتوم       | سطح المكتب/سطر مود | ### مزامنة بصمة CLI (الوكلاء + الإعدادات) |
+
+استخدم `/dashboard/agents` و`Settings > CLI Fingerprint` src/shared/constants/cliCompatProviders.ts.
+يؤدي ذلك إلى تفاصيل البطاقات الموفر المعتمدة ببطاقات CLI والمعارف القديمة.
+
+| معرف واجهة سطر مود                                                                                    | معرف بصمة الإصبع |
+| ----------------------------------------------------------------------------------------------------- | ---------------- |
+| `كيلو`                                                                                                | `الكيلو كود`     |
+| `مساعد الطيار`                                                                                        | `جيثب`           |
+| `كلود` / `كوديكس` / `مضاد الجاذبية` / `كيرو` / `المؤشر` / `كلاين` / `opencode` / `droid` / `openclaw` | نفس المعرف       |
+
+لا تزال المعرفات القديمة مقبولة للتوافق: `مساعد الطيار`، `كيمي كودينج`، `كوين`.---## Step 1 — Get an OmniRoute API Key
+
+1. تسجيل الدخول إلى لوحة التحكم OmniRoute →**API Manager**(`/dashboard/api-manager`)
+2. انقر**إنشاء مفتاح واجهة برمجة التطبيقات**
+3. أعطته اسمًا (على سبيل المثال، "أدوات cli") وتحديد جميع الأذونات
+4. انسخ المفتاح — ستحتاج إليه لكل واجهة سطر الأوامر (CLI) أدناه
+
+> يبدو مفتاحك كما يلي: `sk-xxxxxxxxxxxxxxxxxx-xxxxxxxxx`---## Step 2 — Install CLI Tools
+
+تتطلب جميع المستندات المستندة إلى npm Node.js 18+:```bash
+
+# كلود كود (أنثروبي)
+
+تثبيت npm -g @anthropic-ai/claude-code
+
+# مخطوطة OpenAI
+
+تثبيت npm -g @openai/codex
+
+# الكود المفتوح
+
+تثبيت npm -g opencode-ai
+
+# كلاين
+
+تثبيت npm -g cline
+
+# كيلو كود
+
+تثبيت npm -g كيلوكود
+
+# Kiro CLI (أمازون - يتطلب تجعيد + فك الضغط)
+
+apt-get install -y unzip # على Debian/Ubuntu
+حليقة -fsSL https://cli.kiro.dev/install | باش
+تصدير PATH = "$HOME/.local/bin:$PATH" # إضافة إلى ~/.bashrc```
+
+**يؤكد:**```bash
+claude --version # 2.x.x
+codex --version # 0.x.x
+opencode --version # x.x.x
+cline --version # 2.x.x
+kilocode --version # x.x.x (or: kilo --version)
+kiro-cli --version # 1.x.x
+
+````
+
+---
+
+## Step 3 — Set Global Environment Variables
+
+إضافة إلى `~/.bashrc` (أو `~/.zshrc`)، ثم قم ويسمح `المصدر ~/.bashrc`:```bash
+# نقطة النهاية العالمية OmniRoute
+تصدير OPENAI_BASE_URL = "http://localhost:20128/v1"
+تصدير OPENAI_API_KEY = "sk-your-omniroute-key"
+تصدير ANTHROPIC_BASE_URL = "http://localhost:20128/v1"
+تصدير ANTHROPIC_API_KEY = "sk-your-omniroute-key"
+تصدير GEMINI_BASE_URL = "http://localhost:20128/v1"
+تصدير GEMINI_API_KEY = "sk-your-omniroute-key"```
+
+> بالنسبة إلى**الخادم البعيد**، استبدل `localhost:20128` بعنوان IP للخادم أو المجال،
+> على سبيل المثال `http://192.168.0.15:20128`.---
+
+## Step 4 — Configure Each Tool
+
+### Claude Code
+
+```bash
+# عبر سطر الأوامر:
+مجموعة تكوين كلود - عنوان URL لواجهة برمجة التطبيقات العالمية http://localhost:20128/v1
+
+# أو قم بإنشاء ~/.claude/settings.json:
+mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF
+{
+  "apiBaseUrl": "http://localhost:20128/v1",
+  "apiKey": "مفتاح sk-your-omniroute-"
+}
+EOF```
+
+**اختبار:**`كلود "قل مرحبا"`---
+
+### OpenAI Codex
+
+```bash
+mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF
+نموذج: السيارات
+apiKey: sk-your-omniroute-key
+رابط واجهة برمجة التطبيقات: http://localhost:20128/v1
+EOF```
+
+**اختبار:**`مخطوطة "ما هو 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-omniroute"
+EOF```
+
+**اختبار:**`الرمز المفتوح`---
+
+### Cline (CLI or VS Code)
+
+**وضع سطر الأوامر:**```bash
+mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF
+{
+  "apiProvider": "openai",
+  "openAiBaseUrl": "http://localhost:20128/v1",
+  "openAiApiKey": "sk-your-omniroute-key"
+}
+EOF
+````
+
+**وضع رمز VS:**
+إعدادات امتداد Cline ← موفر واجهة برمجة التطبيقات: `متوافق مع OpenAI` ← عنوان URL الأساسي: `http://localhost:20128/v1`
+
+استخدام لوحة معلومات OmniRoute →**أدوات CLI → Cline → تطبيق المتاح**.---### KiloCode (CLI or VS Code)
+
+**وضع سطر مود:**`bash
+كيلو كود --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key`
+
+**إعدادات رمز VS:**```json
+{
+"kilo-code.openAiBaseUrl": "http://localhost:20128/v1",
+"kilo-code.apiKey": "sk-your-omniroute-key"
+}
+
+````
+
+استخدام لوحة معلومات OmniRoute →**CLI → KiloCode → تطبيق تفعيل**.---### Continue (VS Code Extension)
+
+تحرير `~/.continue/config.yaml`:```yaml
+النماذج:
+  - الاسم: OmniRoute
+    المزود: openai
+    نموذج: السيارات
+    واجهة برمجة التطبيقات: http://localhost:20128/v1
+    apiKey: sk-your-omniroute-key
+    الافتراضي: صحيح```
+
+أعد تشغيل VS Code بعد التحرير.---
+
+### Kiro CLI (Amazon)
+
+```bash
+# قم بتسجيل الدخول إلى حساب AWS/Kiro الخاص بك:
+كيرو كلي تسجيل الدخول
+
+# تستخدم واجهة سطر الأوامر (CLI) مصادقة خاصة بها — ليست هناك حاجة إلى OmniRoute كواجهة خلفية لـ Kiro CLI نفسها.
+# استخدم kiro-cli بجانب OmniRoute لأدوات أخرى.
+حالة كيرو كلي```
+
+---
+
+### Cursor (Desktop App)
+
+>**ملاحظة:**يقوم المؤشر بتوجيه الطلبات عبر السحابة الخاصة به. لتكامل OmniRoute،
+> قم بتمكين**Cloud Endpoint**في إعدادات OmniRoute واستخدم عنوان URL للنطاق العام الخاص بك.
+
+عبر واجهة المستخدم الرسومية:**الإعدادات → النماذج → مفتاح OpenAI API**
+
+- عنوان URL الأساسي: `https://your-domain.com/v1`
+- مفتاح API: مفتاح OmniRoute الخاص بك---
+
+## Dashboard Auto-Configuration
+
+تقوم لوحة معلومات OmniRoute بأتمتة التكوين لمعظم الأدوات:
+
+1. انتقل إلى `http://localhost:20128/dashboard/cli-tools`
+2. قم بتوسيع أي بطاقة أداة
+3. حدد مفتاح API الخاص بك من القائمة المنسدلة
+4. انقر فوق**تطبيق التكوين**(إذا تم اكتشاف الأداة على أنها مثبتة)
+5. أو انسخ مقتطف التكوين الذي تم إنشاؤه يدويًا---
+
+## Built-in Agents: Droid & OpenClaw
+
+**Droid**و**OpenClaw**هما وكيلان للذكاء الاصطناعي مدمجان مباشرة في OmniRoute — لا حاجة للتثبيت.
+يتم تشغيلها كمسارات داخلية وتستخدم توجيه نموذج OmniRoute تلقائيًا.
+
+- الوصول: `http://localhost:20128/dashboard/agents`
+- التكوين: نفس المجموعات ومقدمي الخدمات مثل جميع الأدوات الأخرى
+- لا يلزم تثبيت مفتاح API أو CLI---
+
+## Available API Endpoints
+
+| نقطة النهاية | الوصف | استخدم لـ |
+| -------------------------- | ----------------------------- | --------------------------- |
+| `/v1/chat/completions` | الدردشة القياسية (جميع مقدمي الخدمة) | جميع الأدوات الحديثة |
+| `/v1/الردود` | واجهة برمجة تطبيقات الردود (تنسيق OpenAI) | الدستور الغذائي، سير العمل الوكيل |
+| `/v1/الإكمال` | إكمال النص القديم | الأدوات القديمة التي تستخدم `المطالبة:` |
+| `/v1/embeddings` | تضمينات النص | راج، بحث |
+| `/v1/images/أجيال` | توليد الصور | DALL-E، الجريان، وما إلى ذلك |
+| `/v1/audio/speech` | تحويل النص إلى كلام | أحد عشر مختبرًا، OpenAI TTS |
+| `/v1/audio/transcriptions` | تحويل الكلام إلى نص | ديبجرام، الجمعية AI |---
+
+## استكشاف الأخطاء
+
+| خطأ | السبب | إصلاح |
+| ------------------------- | ----------------------- | ------------------------------------------ |
+| `تم رفض الاتصال` | OmniRoute لا يعمل | `pm2 ابدأ في كل الاتجاهات` |
+| `401 غير مصرح به' | مفتاح API خاطئ | قم بتسجيل الدخول `/dashboard/api-manager` |
+| `لم يتم تكوين التحرير والسرد` | لا يوجد مجموعة توجيه نشطة | تم الإعداد في `/dashboard/combos` |
+| `نموذج غير صالح` | الموديل غير موجود في الكتالوج | استخدم "تلقائي" أو حدد "/dashboard/providers" |
+| يظهر سطر الأوامر "غير مثبت" | ثنائي ليس في PATH | حدد `أي <command>` |
+| `كيرو كلي: غير موجود` | ليس في المسار | `تصدير المسار = "$HOME/.local/bin:$PATH"` |---
+
+## Quick Setup Script (One Command)
+
+```bash
+# تثبيت جميع واجهات سطر الأوامر (CLI) وتكوين OmniRoute (استبدلها بمفتاحك وعنوان URL الخاص بالخادم)
+OMNIROUTE_URL="http://localhost:20128/v1"
+OMNIROUTE_KEY="sk-your-omniroute-key"
+
+تثبيت npm -g @anthropic-ai/clude-code @openai/codex opencode-ai cline Kilocode
+
+# كيرو كلي
+apt-get install -y unzip 2>/dev/null; حليقة -fsSL https://cli.kiro.dev/install | باش
+
+# كتابة التكوينات
+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"
+القط >> ~/.bashrc << EOF
+تصدير OPENAI_BASE_URL="$OMNIROUTE_URL"
+تصدير OPENAI_API_KEY = "$OMNIROUTE_KEY"
+تصدير ANTHROPIC_BASE_URL="$OMNIROUTE_URL"
+تصدير ANTHROPIC_API_KEY = "$OMNIROUTE_KEY"
+EOF
+
+المصدر ~/.bashrc
+صدى " ✅ تم تثبيت جميع واجهات سطر الأوامر (CLI) وتكوينها لـ OmniRoute"```
+````

docs/i18n/ar/docs/CODEBASE_DOCUMENTATION.md

@@ -0,0 +1,527 @@
+# omniroute — Codebase Documentation (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../../es/docs/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../../de/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../../it/docs/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [hi](../../hi/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [in](../../in/docs/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../../th/docs/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../../id/docs/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../../no/docs/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../../da/docs/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../../he/docs/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) · 🇨🇿 [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) · 🇹🇷 [tr](../../tr/docs/CODEBASE_DOCUMENTATION.md)
+
+---
+
+> دليل شامل ومناسب للمبتدئين إلى مدير المدير AI**omniroute**متعدد الموفرين.---## 1. What Is omniroute?
+
+omniroute هو**جهاز وكيل التوجيه**يقع بين عملاء الذكاء الاصطناعي (Claude CLI، وCodex، وCursor IDE، وما إلى ذلك) وموفري الذكاء الاصطناعي (Anthropic، وGoogle، وOpenAI، وAWS، وGitHub، وما إلى ذلك). يحل مشكلة واحدة كبيرة:
+
+> **يتحدث عملاء الذكاء الاصطناعي المختلفون "لغات" مختلفة (تنسيقات واجهة برمجة التطبيقات)، ويتوقع مقدمو خدمات الذكاء الاصطناعي المختلفون "لغات مختلفة" أيضاً.**يترجم المسار الشامل بما فيه الكفاية.
+
+فكر في الأمر التالي مترجم عالمي في الأمم المتحدة - يمكن لأي مندوبات أي لغة، والمترجم هل يمكن أن يترجمها لأي مندوب آخر.---## 2. Architecture Overview
+
+```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
+```
+
+### Core Principle: Hub-and-Spoke Translation
+
+تمر جميع ترجمةات عبر**تنسيق OpenAI كمركز**:`
+تنسيق العميل → [OpenAI Hub] → تنسيق الموفر (طلب)
+تنسيق الموفر → [OpenAI Hub] → تنسيق العميل (الاستجابة)`
+
+هذا يعني أنك تحتاج فقط إلى مترجمين**N**(واحد لكل تنسيق) بدلاً من**N²**(كل زوج).---
+
+## 3. Project Structure
+
+````
+الطريق الشامل/
+├── open-sse/ ← مكتبة الوكيل الأساسية (محمول، لا إطاري)
+│ ├── Index.js ← نقطة الدخول الرئيسية، تصدر كل شيء
+│ ├── التكوين/ ← التكوين والثوابت
+│ ├── المنفذون/ ← تنفيذ الطلب الخاص بالمزود
+│ ├── معالجات/ ← طلب تنسيق التعامل
+│ ├── الخدمات/ ← منطق الأعمال (المصادقة، النماذج، الاحتياطي، الاستخدام)
+│ ├── مترجم/ ← تنسيق محرك الترجمة
+│ │ ├── طلب/ ← طلب مترجمين (8 ملفات)
+│ │ ├── استجابة/ ← مترجمو الاستجابة (7 ملفات)
+│ │ └── مساعدون/ ← أدوات الترجمة المشتركة (6 ملفات)
+│ └── المرافق/ ← وظائف المرافق
+├── src/ ← طبقة التطبيق (وقت تشغيل Express/Worker)
+│ ├── التطبيق/ ← واجهة مستخدم الويب، مسارات واجهة برمجة التطبيقات، البرامج الوسيطة
+│ ├── lib/ ← قاعدة البيانات والمصادقة وكود المكتبة المشتركة
+│ ├── mitm/ ← أدوات الوكيل الوسيطة
+│ ├── النماذج/ ← نماذج قواعد البيانات
+│ ├── مشترك/ ← أدوات مساعدة مشتركة (مغلفات حول open-sse)
+│ ├── sse/ ← معالجات نقطة النهاية SSE
+│ └── المتجر/ ← إدارة الدولة
+├── البيانات/ ← بيانات وقت التشغيل (بيانات الاعتماد والسجلات)
+│ └── Provider-credentials.json (تجاوز بيانات الاعتماد الخارجية، gitignored)
+└── اختبار/ ← اختبار المرافق```
+
+---
+
+## 4. Module-by-Module Breakdown
+
+### 4.1 Config (`open-sse/config/`)
+
+**المصدر الوحيد للحقيقة**لجميع إعدادات الموفر.
+
+| ملف | الغرض |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `الثوابت.ts` | كائن `PROVIDERS` يحتوي على عناوين URL الأساسية وبيانات اعتماد OAuth (الافتراضية) والرؤوس ومطالبات النظام الافتراضية لكل موفر. يحدد أيضًا `HTTP_STATUS` و`ERROR_TYPES` و`COOLDOWN_MS` و`BACKOFF_CONFIG` و`SKIP_PATTERNS`. |
+| "credentialLoader.ts" | يقوم بتحميل بيانات الاعتماد الخارجية من "data/provider-credentials.json" ويدمجها في الإعدادات الافتراضية المضمنة في "PROVIDERS". يحافظ على الأسرار خارج نطاق التحكم بالمصدر مع الحفاظ على التوافق مع الإصدارات السابقة.               |
+| `providerModels.ts` | سجل النموذج المركزي: الأسماء المستعارة لموفر الخرائط → معرفات النموذج. وظائف مثل `getModels()` و`getProviderByAlias()`.                                                                                                          |
+| `codexInstructions.ts` | تعليمات النظام التي تم إدخالها في طلبات الدستور الغذائي (قيود التحرير، قواعد الاختبار، سياسات الموافقة).                                                                                                                 |
+| `defaultThinkingSignature.ts` | توقيعات "التفكير" الافتراضية لنماذج كلود وجيميني.                                                                                                                                                               |
+| `olmaModels.ts` | تعريف المخطط لنماذج أولاما المحلية (الاسم، الحجم، العائلة، التكميم).                                                                                                                                             |#### Credential Loading Flow
+
+```mermaid
+مخطط انسيابي TD
+    A["يبدأ التطبيق"] --> B["constants.ts يحدد مقدمي الخدمة\nبإعدادات افتراضية مضمنة"]
+    B --> C{"data/provider-credentials.json\nexists؟"}
+    ج -->|نعم| D["credentialLoader يقرأ JSON"]
+    ج -->|لا| E["استخدام الإعدادات الافتراضية المشفرة"]
+    D --> F{"لكل موفر في JSON"}
+    F --> G{"الموفر موجود\nفي الموفرين؟"}
+    ز -->|لا| H["تحذير السجل، تخطي"]
+    ز -->|نعم| أنا{"القيمة هي كائن؟"}
+    أنا -->|لا| J["تحذير السجل، تخطي"]
+    أنا -->|نعم| K["دمج معرف العميل، ClientSecret،\ntokenUrl، authUrl، RefreshUrl"]
+    ك --> ف
+    ح --> ف
+    ي --> ف
+    F -->|تم| L["الموفرون جاهزون\nببيانات اعتماد مدمجة"]
+    ه --> ل```
+
+---
+
+### 4.2 Executors (`open-sse/executors/`)
+
+يقوم المنفذون بتغليف**المنطق الخاص بالمزود**باستخدام**نمط الإستراتيجية**. يتجاوز كل منفذ الأساليب الأساسية حسب الحاجة.```mermaid
+classDiagram
+    class BaseExecutor {
+        +buildUrl(model, stream, options)
+        +buildHeaders(credentials, stream, body)
+        +transformRequest(body, model, stream, credentials)
+        +execute(url, options)
+        +shouldRetry(status, error)
+        +refreshCredentials(credentials, log)
+    }
+
+    class DefaultExecutor {
+        +refreshCredentials()
+    }
+
+    class AntigravityExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +shouldRetry()
+        +refreshCredentials()
+    }
+
+    class CursorExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseResponse()
+        +generateChecksum()
+    }
+
+    class KiroExecutor {
+        +buildUrl()
+        +buildHeaders()
+        +transformRequest()
+        +parseEventStream()
+        +refreshCredentials()
+    }
+
+    BaseExecutor <|-- DefaultExecutor
+    BaseExecutor <|-- AntigravityExecutor
+    BaseExecutor <|-- CursorExecutor
+    BaseExecutor <|-- KiroExecutor
+    BaseExecutor <|-- CodexExecutor
+    BaseExecutor <|-- GeminiCLIExecutor
+    BaseExecutor <|-- GithubExecutor
+````
+
+| المنفذ               | مقدم                                                | التخصص الرئيسي                                                                                                                    |
+| -------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `base.ts`            | —                                                   | قاعدة الملخصات: إنشاء عنوان URL، والرؤوس، ومنطقة إعادة المحاولة، وتحديث بيانات الاعتماد                                           |
+| `default.ts`         | كلود، جيميني، أوبن آي آي، جي إل إم، كيمي، ميني ماكس | تحديث رمز OAuth العام للموفرين الكلاسيكيين                                                                                        |
+| `مكافحة الجاذبية.ts` | جوجل كلود كود                                       | إنشاء معرف المشروع/الجلسة، وإرجاع عناوين URL الإعلامية، بعد محاولة تحديد موقع رسائل الخطأ ("إعادة بعد 2 ساعة و7 دقائق و23 ثانية") |
+| `cursor.ts`          | منطقة تطوير متعددة للمؤشر                           | **الأكثر مخاطرًا**: مصادقة التسجيل الاختباري SHA-256، وترميز طلب Protobuf، وEventStream ثنائي → تحليل اتصال SSE                   |
+| `codex.ts`           | OpenAI Codex                                        | حجم تعليمات النظام، وإدارة مستويات التفكير، تجديد المعلمات غير المدعومة                                                           |
+| `الجوزاء-cli.ts`     | جوجل الجوزاء CLI                                    | إنشاء عنوان URL مخصص (`streamGenerateContent`)، وتحديث رمز OAuth المميز لـ Google                                                 |
+| `جيثب.ts`            | جيثب مساعد الطيار                                   | نظام رمزي ثنائي (GitHub OAuth + Copilot token)، محاكاة رأس VSCode                                                                 |
+| `kiro.ts`            | AWS CodeWhisperer                                   | التحليل الثنائي لـ AWS EventStream، وإطارات أحداث AMZN، والتقدير المميز                                                           |
+| `index.ts`           | —                                                   | المصنع: اسم موفر ← فئة المنفذ، مع خيار بديل افتراضي                                                                               | ---### 4.3 Handlers (`open-sse/handlers/`) |
+
+**طبقة تأتي**— تترتب على الترجمة والتنفيذ والتدفق ويسبب سبب.
+
+| ملف                   | الحصاد                                                                                                                                                            |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `chatCore.ts`         | **المنسق المركزي**(~ 600 سطر). لاحظ مع دورة حياة الطلب الكامل: اكتشاف ← الترجمة ← رحلة مميزة ← عزيزي القارئ/غير المتدفق ← تحديث ← أسباب ← تسجيل الاستخدام.        |
+| `responsesHandler.ts` | محول برمجة تطبيقات الخاصة بـ OpenAI: تحويل تنسيق الردود ← إرسال ملفات الدردشة ← إرسال إلى `chatCore` ← تحويل SSE مرة أخرى إلى تنسيق الردود.                       |
+| `embeddings.ts`       | محرك إنشاء التضمين: يحل نموذج التضمين → الموفر، ويرسل إلى واجهة برمجة تطبيقات الموفر، ويعيد الاتصال بالتضمين المتوافق مع OpenAI. يدعم 6+ مقدمي الخدمات.           |
+| `imageGeneration.ts`  | معالج إنشاء الصور: يحل نموذج الصورة → الموفر، ويدعم الأوضاع المتوافقة مع OpenAI، وGemini-image (Antigravity)، والوضع الاحتياطي (Nebius). إرجاع صور base64 أو URL. | #### دورة حياة الطلب (chatCore.ts)```mermaid |
+
+sequenceDiagram
+participant Client
+participant chatCore
+participant Translator
+participant Executor
+participant Provider
+
+    Client->>chatCore: Request (any format)
+    chatCore->>chatCore: Detect source format
+    chatCore->>chatCore: Check bypass patterns
+    chatCore->>chatCore: Resolve model & provider
+    chatCore->>Translator: Translate request (source → OpenAI → target)
+    chatCore->>Executor: Get executor for provider
+    Executor->>Executor: Build URL, headers, transform request
+    Executor->>Executor: Refresh credentials if needed
+    Executor->>Provider: HTTP fetch (streaming or non-streaming)
+
+    alt Streaming
+        Provider-->>chatCore: SSE stream
+        chatCore->>chatCore: Pipe through SSE transform stream
+        Note over chatCore: Transform stream translates<br/>each chunk: target → OpenAI → source
+        chatCore-->>Client: Translated SSE stream
+    else Non-streaming
+        Provider-->>chatCore: JSON response
+        chatCore->>Translator: Translate response
+        chatCore-->>Client: Translated JSON
+    end
+
+    alt Error (401, 429, 500...)
+        chatCore->>Executor: Retry with credential refresh
+        chatCore->>chatCore: Account fallback logic
+    end
+
+````
+
+---
+
+### 4.4 Services (`open-sse/services/`)
+
+منطق الأعمال الذي يدعم المعالجات والمنفذين.| File                 | Purpose                                                                                                                                                                                                                                                                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider.ts`        | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. |
+| `model.ts`           | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support.                                                                             |
+| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not).                                                                                                                                                                         |
+| `tokenRefresh.ts`    | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, Qoder, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff.                                                                       |
+| `combo.ts`           | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes.                                                                                                                                                                          |
+| `usage.ts`           | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings).                                                                                                                                                                              |
+| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request.                                                                                                                                                              |
+| `contextManager.ts`  | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging.                                                                                                                                                                  |
+| `ipFilter.ts`        | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests.                                                                                                                                                                                          |
+| `sessionManager.ts`  | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics.                                                                                                                                                                            |
+| `signatureCache.ts`  | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window.                                                                                                                                              |
+| `systemPrompt.ts`    | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling.                                                                                                                                                                                            |
+| `thinkingBudget.ts`  | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens.                                                                                                                                        |
+| `wildcardRouter.ts`  | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority.                                                                                                                                                                                   |
+
+#### Token Refresh Deduplication
+
+```mermaid
+sequenceDiagram
+    participant R1 as Request 1
+    participant R2 as Request 2
+    participant Cache as refreshPromiseCache
+    participant OAuth as OAuth Provider
+
+    R1->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: No in-flight promise
+    Cache->>OAuth: Start refresh
+    R2->>Cache: getAccessToken("gemini", token)
+    Cache->>Cache: Found in-flight promise
+    Cache-->>R2: Return existing promise
+    OAuth-->>Cache: New access token
+    Cache-->>R1: New access token
+    Cache-->>R2: Same access token (shared)
+    Cache->>Cache: Delete cache entry
+````
+
+#### Account Fallback State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active
+    Active --> Error: Request fails (401/429/500)
+    Error --> Cooldown: Apply backoff
+    Cooldown --> Active: Cooldown expires
+    Active --> Active: Request succeeds (reset backoff)
+
+    state Error {
+        [*] --> ClassifyError
+        ClassifyError --> ShouldFallback: Rate limit / Auth / Transient
+        ClassifyError --> NoFallback: 400 Bad Request
+    }
+
+    state Cooldown {
+        [*] --> ExponentialBackoff
+        ExponentialBackoff: Level 0 = 1s
+        ExponentialBackoff: Level 1 = 2s
+        ExponentialBackoff: Level 2 = 4s
+        ExponentialBackoff: Max = 2min
+    }
+```
+
+#### Combo Model Chain
+
+```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 Translator (`open-sse/translator/`)
+
+**محرك استعداد**باستخدام نظام التوقيع الذاتي.#### الكائنات```mermaid
+graph TD
+subgraph "Request Translation"
+A["Claude → OpenAI"]
+B["Gemini → OpenAI"]
+C["Antigravity → OpenAI"]
+D["OpenAI Responses → OpenAI"]
+E["OpenAI → Claude"]
+F["OpenAI → Gemini"]
+G["OpenAI → Kiro"]
+H["OpenAI → Cursor"]
+end
+
+    subgraph "Response Translation"
+        I["Claude → OpenAI"]
+        J["Gemini → OpenAI"]
+        K["Kiro → OpenAI"]
+        L["Cursor → OpenAI"]
+        M["OpenAI → Claude"]
+        N["OpenAI → Antigravity"]
+        O["OpenAI → Responses"]
+    end
+
+````
+
+| الدليل | ملفات | الوصف |
+| ------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `طلب/` | 8 مترجمين | تحويل أجسام بين الصيغ. يتم تسجيل كل ملف ذاتيًا عبر "التسجيل (من، إلى، fn)" عند الاستيراد.                                                                                                                                                         |
+| `الاستجابة/` | 7 مترجمين | تحويل قطع المضخّم بين الصيغة. للتعرف على أنواع أحداث SSE وكتل التفكير وأدوات الأدوات.                                                                                                                                                         |
+| `المساعدين/` | 6 مساعدين | الأداة المساعدة المشتركة: `cludeHelper` (استخراج النظام، البحث المطلوب البحث)، `geminiHelper` (تخطيط الأجزاء/المحتويات)، `openaiHelper` (خيار مناسب)، `toolCallHelper` (إنشاء المعرف، البحث المطلوب المطلوبة)، `maxTokensHelper`، `responsesApiHelper`. |
+| `index.ts` | — | ترجمة المحرك: `translateRequest()`، `translateResponse()`، إدارة الحالة، التسجيل.                                                                                                                                                                     |
+| `formats.ts` | — | ثوابت عادة: `OPENAI`، `CLAUDE`، `GEMINI`، `ANTIGRAVITY`، `KIRO`، `CURSOR`، `OPENAI_RESPONSES`.                                                                                                                                                             |#### التصميم الرئيسي: المكونات الإضافية ذاتية التسجيل```javascript
+// Each translator file calls register() on import:
+import { register } from "../index.js";
+register("claude", "openai", translateClaudeToOpenAI);
+
+// The index.js imports all translator files, triggering registration:
+import "./request/claude-to-openai.js"; // ← self-registers
+````
+
+---
+
+### 4.6 Utils (`open-sse/utils/`)
+
+| ملف                | الحصاد                                                                                                                                                                                                                                                             |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- |
+| "خطأ.ts"           | إنشاء كلمات للأخطاء (تنسيق متوافق مع OpenAI)، وسبب المشكلة، واستخراجها، وحاول إعادة محاولة Antigravity من رسائل الخطأ، وأخطاء SSE.                                                                                                                                 |
+| "stream.ts"        | **SSE Transform Stream**— خط أنابيب البث الأساسي. وضعان: "الترجمة" (ترجمة كاملة) و"العبور" (التطبيع + الطلب المستخدم). وأخذ بعين الاعتبار التخزين المؤقت للقطعة وتقدير استخدامها وتتبع طول الفيديو. تجنب مثيلات وحدة التشفير/وحدة فك التشفير لكل حالة DC المشتركة. |
+| `streamHelpers.ts` | SSE ذات المستوى المنخفض: `parseSSELine` (متسامح مع المسافات البيضاء)، `hasValuableContent` ( تصفية أدوات الفارغة لـ OpenAI/Claude/Gemini)، `fixInvalidId`، `formatSSE` (تسلسل SSE مدرك للتنسيق مع `perf_metrics`).                                                 |
+| `usageTracking.ts` | استخدام النسخة المميزة من أي تنسيق (Claude/OpenAI/Gemini/Responses)، والاستعانة بـ DNS لكل رمز مميز للأداة/الرسالة، والمخزن المؤقت (هامش أمان 2000 رمز مميز)، وتصفية الخاصيات بالتنسيق، وتسجيل وحدة التحكم مع ANSI.                                                |
+| `requestLogger.ts` | تسجيل الطلب إلى الملف (قم بالاشتراك عبر `ENABLE_REQUEST_LOGS=true`). ينشئ مجلدات الجلسة بملفات مرقمة: `1_req_client.json` → `7_res_client.txt`. كل عمليات الإدخال/الإخراج غير متزامنة (أطلق النار وانسى). داخل المسام.                                             |
+| `bypassHandler.ts` | ويمثل خيارًا محددًا لـ Claude CLI (عنوان الإنتاج، والحماية، والعد) ويعيد ميزة دون الاتصال بأي مكان. يدعم كل من الدف وغير الدف. لذلك عمدا على نطاق كلود CLI.                                                                                                        |
+| `networkProxy.ts`  | يحل عنوان URL للوكلاء لموفر معين مع الأسبقية: تفعيل الخاص بالموفر → تفعيل العام → متغيرات البيئة (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). يدعم استثناءات `NO_PROXY`. اختيارية ذاكرة تخزين مؤقتة لمدة 30 ثانية.                                                    | #### خط أنابيب تدفق SSE```mermaid |
+
+flowchart TD
+A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"]
+B --> C["Buffer lines\n(split on newline)"]
+C --> D["parseSSELine()\n(trim whitespace, parse JSON)"]
+D --> E{"Mode?"}
+E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"]
+E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"]
+F --> H["hasValuableContent()\nfilter empty chunks"]
+G --> H
+H -->|"Has content"| I["extractUsage()\ntrack token counts"]
+H -->|"Empty"| J["Skip chunk"]
+I --> K["formatSSE()\nserialize + clean perf_metrics"]
+K --> L["TextEncoder\n(per-stream instance)"]
+L --> M["Enqueue to\nclient stream"]
+
+    style A fill:#f9f,stroke:#333
+    style M fill:#9f9,stroke:#333
+
+```
+
+#### Request Logger Session Structure
+
+```
+
+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 Application Layer (`src/`)
+
+| الدليل | الحصاد |
+| ------------- | ---------------------------------------------------------------------- |
+| `src/app/` | واجهة مستخدم الويب، مسارات واجهة برمجة التطبيقات (API)، البرامج الأساسية السريعة، معالجات رد اتصال OAuth |
+| `src/lib/` | إلى قاعدة الوصول إلى البيانات (`localDb.ts`، `usageDb.ts`)، المصادقة، البرمجة |
+| `src/mitm/` | أداة مساعدة للوسيط لاعتراض حركة المرور |
+| `src/models/` | تعريفات قواعد البيانات |
+| `src/shared/` | أغلفة حول وظائف open-sse (المزود، الدفق، الخطأ، إلخ) |
+| `src/sse/` | معالجات نقطة نهاية SSE التي تتوفر في مكتبة open-sse بمسارات Express |
+| `src/store/` | إدارة التطبيق |#### مسارات API البارزة
+
+| الطريق | طرق | الحصاد |
+| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
+| `/api/provider-models` | الحصول على/نشر/حذف | CRUD للنماذج المتخصصة لكل |
+| `/api/models/catalog` | احصل على | مجمع كتالوج لجميع الارتباطات (الدردشة، التضمين، الصورة، تخصيص) مجمعة حسب الموفر |
+| `/api/settings/proxy` | الحصول على/وضع/حذف | الجاهزة التفصيلي (`العالمي/الموفرون/المجموعات/المفاتيح`) |
+| `/api/settings/proxy/test` | مشاركة | التحقق من صحة الاتصال الوكيل وإرجاع IP/زمن الوصول العام |
+| `/v1/providers/[provider]/chat/completions` | مشاركة | عمليات البحث عن الاختيار المناسب لكل شخص مع التحقق من صحة النموذج |
+| `/v1/providers/[provider]/embeddings` | مشاركة | عمليات تضمين التخصص حسب الاختيار مع نموذج التحقق من الصحة |
+| `/v1/providers/[provider]/images/ Generations` | مشاركة | إنشاء صور مخصصة لكل وثيقة معتمدة من نموذج صحة |
+| `/api/settings/ip-filter` | الحصول على/وضع | قائمة IP الخاصة بها/إدارة القائمة المحظورة |
+| `/api/settings/thinking-budget` | الحصول على/وضع | المحددة المحددة الرمز (العبور/التلقائي/المخصص/التكيفي) |
+| `/api/settings/system-prompt` | الحصول على/وضع | القطع المؤقتة لأدوات البناء العالمية |
+| `/api/sessions` | احصل على | تحديد العضوية ومعاييرها |
+| `/api/rate-limits` | احصل على | الحالة لا يمكن تعديلها لكل حساب |---## 5. Key Design Patterns
+
+### 5.1 Hub-and-Spoke Translation
+
+تتم ترجمة جميع الاحتمالات من خلال**تنسيق OpenAI كمحور**. لا تتطلب إضافة موفر جديد سوى كتابة**زوج واحد**من المترجمين (من/ إلى OpenAI)، وليس عدد N من المترجمين.### 5.2 Executor Strategy Pattern
+
+كل ما لديها فئة تنفيذية مخصصة ترث من "BaseExecutor". تم تصنيع المصنع الموجود في "executors/index.ts" وبالتالي أصبح المصنع جاهزًا في وقت التشغيل.### 5.3 نظام البرنامج الإضافي للتسجيل الذاتي
+
+وحدات المترجمة نفسها عند الاستيراد عبر ``تسجيل ()'. إن إضافة مترجم جديد يعني مجرد إنشاء ملف واستيراده.### 5.4 Account Fallback with Exponential Backoff
+
+عندما يقوم بتقديم خدمة بإرجاع 429/401/500، يمكن أن يتكامل مع الحساب التالي، مع تطبيق أحدث الحداثات الأسية (1ث → 2ث → 4ث → 2 دقيقة الضرر التام).### 5.5 Combo Model Chains
+
+يقوم "التحرير والسرد" بتجميع سلاسل "المزود/النموذج" حاسوبياً. في حالة الفشل الأول، يتم الرجوع إلى المنتج الأصلي.### 5.6 الترجمة المتدفقة ذات الحالة
+
+الحفاظ على ترجمة الأجزاء ذات الحالة عبر SSE (تتبع كتلة التفكير، وتراكم الاتصال بالجهة، وفهرسة كتلة المحتوى) عبر تقنية `initState()`.### 5.7 المخزن المؤقت لسلامة الاستخدام
+
+تم إضافة مخزن مؤقت مكون من 2000 رمز مميز إلى الحد الأقصى من الاستخدام لمساعدة العملاء على الوصول إلى حدود النافذة بسبب الحمل الزائد من مطالبات النظام وترجمة السائقين.---## 6. Supported Formats
+
+| التنسيق | | المعرف |
+| ----------------------- | --------------- | ------------------ |
+| استكمالات الدردشة OpenAI | المصدر + الهدف | `أوبيني` |
+| برمجة تطبيقات استجابات OpenAI | المصدر + الهدف | `الردود المفتوحة` |
+| أنثروب كلود | المصدر + الهدف | "كلود" |
+| جوجل الجوزاء | المصدر + الهدف | `الجوزاء` |
+| جوجل الجوزاء CLI | الهدف فقط | `الجوزاء-كلي` |
+| مكافحة الجاذبية | المصدر + الهدف | `مضادة الجاذبية` |
+| أوس كيرو | الهدف فقط | `كيرو` |
+| |مؤثر الهدف فقط | `المؤشر` |---## 7. Supported Providers
+
+| مقدم | طريقة المصادقة | المنفذ | المذكرة الرئيسية |
+| ------------------------ | ---------------------- | ----------- | --------------------------------------------- |
+| أنثروب كلود | واجهة برمجة التطبيقات الرئيسية أو OAuth | افتراضي | يستخدم رأس `x-api-key` |
+| جوجل الجوزاء | واجهة برمجة التطبيقات الرئيسية أو OAuth | افتراضي | يستخدم رأس `x-goog-api-key` |
+| جوجل الجوزاء CLI | أووث | الجوزاء كلي | يستخدم نقطة نهاية "streamGenerateContent" |
+| مكافحة الجاذبية | أووث | مكافحة الجاذبية | شراء عناوين URL الخاصة بها، إعادة محاولة البحث عن المواقع |
+| أوبن آي | واجهة برمجة التطبيقات الرئيسية | افتراضي | مصادقة الحامل |
+| الدستور الغذائي | أووث | الدستور الغذائي | يدخل تعليمات النظام ويدير التفكير |
+| جيثب مساعد الطيار | OAuth + رمز مساعد الطيار | جيثب | رمز مزدوج، محاكاة رأس VSCode |
+| كيرو (AWS) | AWS SSO OIDC أو اجتماعي | كيرو | تحليل دفق الأحداث الثنائية |
+| بيئة تطوير متكاملة للمؤشر | تصويت الاختياري | |مؤثر ترميز Protobuf، الجلسات الاختباري SHA-256 |
+| كوين | أووث | افتراضي | المصادقة القياسية |
+| قدير | OAuth (أساسي + حامل) | افتراضي | رأس المصادقة |
+| اوبن راوتر | واجهة برمجة التطبيقات الرئيسية | افتراضي | مصادقة الحامل |
+| جي إل إم، كيمي، ميني ماكس | واجهة برمجة التطبيقات الرئيسية | افتراضي | متوافق مع كلود، استخدم `x-api-key` |
+| `متوافق مع openai-*` | واجهة برمجة التطبيقات الرئيسية | افتراضي | برمجة: أي نقطة نهاية متوافقة مع OpenAI |
+| `متوافق مع البشر-*` | واجهة برمجة التطبيقات الرئيسية | افتراضي | برمجة: أي نقطة نهاية متوافقة مع كلود |---## 8. Data Flow Summary
+
+### Streaming Request
+
+```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()"]
+````
+
+### Non-Streaming Request
+
+```mermaid
+flowchart LR
+    A["Client"] --> B["detectFormat()"]
+    B --> C["translateRequest()\nsource → OpenAI → target"]
+    C --> D["Executor.execute()"]
+    D --> E["translateResponse()\ntarget → OpenAI → source"]
+    E --> F["Return JSON\nresponse"]
+```
+
+### Bypass Flow (Claude CLI)
+
+```mermaid
+flowchart LR
+    A["Claude CLI request"] --> B{"Match bypass\npattern?"}
+    B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"]
+    B -->|"No match"| D["Normal flow"]
+    C --> E["Translate to\nsource format"]
+    E --> F["Return without\ncalling provider"]
+```

docs/i18n/ar/docs/COVERAGE_PLAN.md

@@ -0,0 +1,137 @@
+# Test Coverage Plan (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/COVERAGE_PLAN.md) · 🇪🇸 [es](../../es/docs/COVERAGE_PLAN.md) · 🇫🇷 [fr](../../fr/docs/COVERAGE_PLAN.md) · 🇩🇪 [de](../../de/docs/COVERAGE_PLAN.md) · 🇮🇹 [it](../../it/docs/COVERAGE_PLAN.md) · 🇷🇺 [ru](../../ru/docs/COVERAGE_PLAN.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) · 🇯🇵 [ja](../../ja/docs/COVERAGE_PLAN.md) · 🇰🇷 [ko](../../ko/docs/COVERAGE_PLAN.md) · 🇸🇦 [ar](../../ar/docs/COVERAGE_PLAN.md) · 🇮🇳 [hi](../../hi/docs/COVERAGE_PLAN.md) · 🇮🇳 [in](../../in/docs/COVERAGE_PLAN.md) · 🇹🇭 [th](../../th/docs/COVERAGE_PLAN.md) · 🇻🇳 [vi](../../vi/docs/COVERAGE_PLAN.md) · 🇮🇩 [id](../../id/docs/COVERAGE_PLAN.md) · 🇲🇾 [ms](../../ms/docs/COVERAGE_PLAN.md) · 🇳🇱 [nl](../../nl/docs/COVERAGE_PLAN.md) · 🇵🇱 [pl](../../pl/docs/COVERAGE_PLAN.md) · 🇸🇪 [sv](../../sv/docs/COVERAGE_PLAN.md) · 🇳🇴 [no](../../no/docs/COVERAGE_PLAN.md) · 🇩🇰 [da](../../da/docs/COVERAGE_PLAN.md) · 🇫🇮 [fi](../../fi/docs/COVERAGE_PLAN.md) · 🇵🇹 [pt](../../pt/docs/COVERAGE_PLAN.md) · 🇷🇴 [ro](../../ro/docs/COVERAGE_PLAN.md) · 🇭🇺 [hu](../../hu/docs/COVERAGE_PLAN.md) · 🇧🇬 [bg](../../bg/docs/COVERAGE_PLAN.md) · 🇸🇰 [sk](../../sk/docs/COVERAGE_PLAN.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) · 🇮🇱 [he](../../he/docs/COVERAGE_PLAN.md) · 🇵🇭 [phi](../../phi/docs/COVERAGE_PLAN.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) · 🇨🇿 [cs](../../cs/docs/COVERAGE_PLAN.md) · 🇹🇷 [tr](../../tr/docs/COVERAGE_PLAN.md)
+
+---
+
+آخر تحديث: 2026-03-28##
+
+هناك تفاصيل تفصيلية متعددة حول كيفية حساب التقرير. للتخطيط، واحد منهم فقط مفيد.
+
+| متري         | النطاق                                 | بقدر / سطور |    فرع | الوظائف | تعليقات                                         |
+| ------------ | -------------------------------------- | ----------: | -----: | ------: | ----------------------------------------------- |
+| تراث         | اختبار تشغيل npm القديم: غلاف          |      79.42% | 75.15% |  67.94% | مضخم: يحصي اختبارات الاختبار ويستبعد `open-sse` |
+| التشخيص      | المصدر فقط، التمييز و السبب `open-sse` |      68.16% | 63.55% |  64.06% | مفيد فقط لعزل `src/**`                          |
+| خط الأساس له | المصدر فقط، لغرض القسم `open-sse`      |      56.95% | 66.05% |  57.80% | هذا هو خط الأساس لتحسين المشروع                 |
+
+خط الأساس به هو الرقم المطلوب وتحسينه.## Rules
+
+- تستهدف تحديد الملفات المصدر، وليس على "الاختبارات/\*\*".
+- `open-sse/**` هو جزء من المنتج ويجب أن يختفي في نطاقه.
+- يجب ألا تحدد الكود الجديد من المناطق التي تم لمسها.
+- تفضيل الاختبار ونتائج الجهة على تفاصيل التنفيذ.
+- تفضيلات متطلبات بيانات SQLite المطر والتركيبات الصغيرة على الارتباطات المتخصصة لـ src/lib/db/\*\*`.## مجموعة الأوامر الحالية
+
+- `اختبار تشغيل npm: التغطية`
+  - بوابة المصدر الرئيسي لمجموعة اختبار الوحدة
+  - إنشاء ملخص النص، وhtml، وملخص json، ولكوف
+- `تغطية تشغيل npm: تقرير`
+  - تقرير مفصل لملف الآخر من العملية الأخيرة
+- `اختبار تشغيل npm:التغطية:تراث`
+  - لتحدث التاريخية فقط## المعالم
+
+| المرحلة         |         الهدف | التركيز                                           |
+| --------------- | ------------: | ------------------------------------------------- |
+| المرحلة 1       | 60% لذلك/سطور | مكاسب سريعة وتغطية شاملة لمختلف الفئات            |
+| المرحلة الثانية | 65% لذلك/سطور | أسس قاعدة البيانات والطريق                        |
+| المرحلة 3       | 70% لذلك/سطور | التحقق من صحة الموفر وتحليلات الاستخدام           |
+| الخطوة الرابعة  | 75% لذلك/سطور | مترجمون ومساعدون `open-sse'                       |
+| المرحلة الخامسة | 80% لذلك/سطور | رامات وروعة الزجاجة `open-sse`                    |
+| المرحلة السادسة | 85% لذلك/سطور | الحالات القصوى، الديون الدينية، وأجنحة الانحدار   |
+| المرحلة السابعة | 90% لذلك/سطور | الاجتياح النهائي، الإغلاق الشامل، السقاطة الساكنة |
+
+يجب أن ترتكز الجذور والوظائف مع كل مرحلة، ولكن الهدف الأساسي الثابت هو البيانات/السطور.## النقاط الساخنة ذات الأولوية
+
+توفر هذه الملفات أو المناطق أفضل عائد للمراحل التالية:1. "فتح sse/معالجات".
+
+- `chatCore.ts` بنسبة 7.57%
+- الدليل الشامل بنسبة 29.07% 2.`open-sse/translator/request`
+- الرد المرسل إليه 36.39%
+- لا يزال العديد من المترجمين على مقربة من تغطية ما يكفي من رقم واحد
+
+3. "open-sse/translator/response".
+   - الرد المرسل إليه 8.07%
+4. "open-sse/المنفذين".
+   - البريد المرسل إليه 36.62% 5.`src/lib/db`
+   - `models.ts` بنسبة 20.66%
+   - "المفاتيح الجديدة" بنسبة 34.46%
+   - `modelComboMappings.ts` بنسبة 36.25%
+   - `settings.ts` عند 46.40%
+   - `webhooks.ts' بنسبة 33.33%
+6.`src/lib/usage`
+   - `usageHistory.ts` بنسبة 21.12%
+   - `usageStats.ts` بنسبة 9.56%
+   - `costCalculator.ts` بنسبة 30.00% 7.`src/lib/providers`
+   - `validation.ts` بنسبة 41.16%
+5. ملفات المساعدة وواجهة برمجة التطبيقات (API) ذات القدرة الضعيفة على فقدان القليل
+   - `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`## قائمة التحقق من التنفيذ### Phase 1: 56.95% -> 60%
+
+- [x] مقياس التغطية بحيث يعكس اللون الأفضل من ملفات الاختبار
+- [x] تستخدم بنص التغطية القديم للمقارنة
+- [x] قام بعدم وجود خط الأساس ونقاط الاتصال في الريبو
+- [ ] إضافة السيولة المركزية للمرافق المتعددة:
+  - `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`
+- [ ] إضافة السيولة لـ:
+  - `src/app/api/settings/require-login/route.ts`
+  - `src/app/api/providers/[id]/models/route.ts`### المرحلة الثانية: 60% -> 65%
+
+- [ ] إضافة السيولة المدعومة بقاعدة البيانات لـ:
+  - `src/lib/db/modelComboMappings.ts`
+  - `src/lib/db/settings.ts`
+  - `src/lib/db/registeredKeys.ts`
+- [ ] اشتباكات الفرع في:
+  - `src/lib/providers/validation.ts`
+  - `src/app/api/v1/embeddings/route.ts`
+  - `src/app/api/v1/moderations/route.ts`### المرحلة الثالثة: 65% -> 70%
+
+- [ ] إضافة السيولة تحليلات الاستخدام لـ:
+  - `src/lib/usage/usageHistory.ts`
+  - `src/lib/usage/usageStats.ts`
+  - `src/lib/usage/costCalculator.ts`
+- [ ] التغطية المكثفة للمحتوى الإبداعي متنوع ### المرحلة 4: 70% -> 75%
+
+- [ ] تغطية مساعدي المترجم ومسارات الترجمة المركزية:
+  - `open-sse/translator/index.ts`
+  - `open-sse/translator/helpers/*`
+  - `open-sse/translator/request/*`
+  - `open-sse/translator/response/*`### المرحلة الخامسة: 75% -> 80%
+
+- [ ] إضافة السيولة على مستوى رام لـ:
+  - `open-sse/handlers/chatCore.ts`
+  - `open-sse/handlers/responsesHandler.js`
+  - `open-sse/handlers/imageGeneration.js`
+  - `open-sse/handlers/embeddings.js`
+- [ ] إضافة المنفذ الفرعي للمصادقة الخاصة بالموفر، لتقديم المحاولة، وتجاوزات نقطة النهاية### المرحلة 6: 80% -> 85%
+
+- [ ] دمج المزيد من مجموعات الأحداث المتقدمة في مسار التغطية الرئيسية
+- [ ] الزيادة الوظيفية للوحدات قاعدة البيانات ذات التغطية الضعيفة للمنشئ/المساعد
+- [ ] إغلاق فجوات الفروع في "settings.ts"، و"registeredKeys.ts"، و"validation.ts"، ومساعدي المترجم### المرحلة السابعة: 85% -> 90%
+
+- [ ] بعض القضايا ذات الميزانية المحدودة المتبقية على أدوات الحظر
+- [ ] إضافة نسبة الانحدار لكل خطأ إنتاجي تم اكتشافه وإصلاحه أثناء الدفع إلى 90%
+- [ ] رفع بوابة التغطية في CI فقط بعد أن يكون الخط المحلي الأساسي قائمًا لتشغيلتين متتاليتين على الأقل## Ratchet Policy
+
+قم بالتأكيد بعتبات تشغيل npm: التغطية فقط بعد التجاوز الفعلي فعليًا، المرحلة الرئيسية التالية في مخزن الراحة.
+
+سلسلة السقاطة لسبب:
+
+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
+
+الترتيب هو "أسطر البيانات / الفروع / الوظائف".## الثغرة المعروفة
+
+يقيس أمر التغطية الحالية لمجموعة العقد الرئيسية بمشاركة المصدر الذي يتم الوصول إليه منه، بما في ذلك `open-sse`. لم أدمج بعد تغطية Vitest في التقرير الموحد الواحد. وقد تم إنجاز هذا لاحقًا، ولكن لا تزيد سرعة زيادة الذاكرة بنسبة 60% -> 80%.

docs/i18n/ar/docs/FEATURES.md

@@ -0,0 +1,73 @@
+# 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) · 🇮🇳 [hi](../../hi/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) · 🇨🇿 [cs](../../cs/docs/FEATURES.md) · 🇹🇷 [tr](../../tr/docs/FEATURES.md)
+
+---
+
+دليل مرئي لكل قسم من معلومات لوحة OmniRoute.---## 🔌 Providers
+
+إدارة اتصالات الذكاء الصناعي: موفري OAuth (Claude Code وCodex وGemini CLI) وموفري مفاتيح API (Groq وDeepSeek وOpenRouter) ومقدمي خدمات العيد (Qoder وQwen وKiro). لحسابات كيرو على تتبع الاعتماد الائتماني - الأرصدة النهائية لإجمالي استطلاعات الرأي المتخصصة في لوحة التحكم → استخدام.![Providers Dashboard](screenshots/01-providers.png)---
+
+## 🎨 Combos
+
+أنشئ مجموعات التوجيه باستخدام 6 إستراتيجيات: نأمل، والمتزايدة، والدورية، والعشوائية، وأقل استخدامًا، والمُحسّن من حيث التكلفة. وخاصة مجموعة نماذج متعددة مع اختلافات سريعة وفحوصات للجاهزية.![Combos Dashboard](screenshots/02-combos.png)---
+
+## 📊 Analytics
+
+تحليلات استخدام شاملة مع الرمز المميز، وتقديرات التكلفة، وخرائط، ومخططات التوزيع الأسبوعية، والتفاصيل لكل محمية.![Analytics Dashboard](screenshots/03-analytics.png)---
+
+## 🏥 System Health
+
+التسجيل في الوقت الفعلي: وقت العمل، والذاكرة، والإصدار، والنسب لزمن الوصول (p50/p95/p99)، وإحصائيات ذاكرة التخزين المؤقتة، وحالات منع دائرة الموفر.![Health Dashboard](screenshots/04-health.png)---
+
+## 🔧 Translator Playground
+
+أدوات لتصحيح أخطاء ترجمات برمجة التطبيقات:**ساحة اللعب**(محول أربعة نجاح)،**اختبار الدردشة**(الطلب المباشر)،**منصة الاختبار**(اختبارات الدفعة)، و**المراقب المباشر**(بث الوقت في العمل).![Translator Playground](screenshots/05-translator.png)---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+اختبر أي نموذج مباشرة من لوحة القيادة. حدد الموفر والطراز والنقطة النهائية، وكتب المطالبات باستخدام محرر موناكو، وقم بتفعيل الاستثناءات في المنتج الفعلي، وإلغاء منتصف الدفق، والمعايرة التقليدية مرة.---## 🎨 Themes _(v2.0.5+)_
+
+ألوان قابلة للتخصيص لمعلومات لوحة المفاتيح بأكملها. اختر من بين 7 ألوان محددة ليمين (مرجاني، أزرق، أخضر، بنفسجي، لون أحمر، سماوي) أو قم باختيار سمة مخصصة عن طريق اختيار أي سداسي عشري. يدعم وضع الضوء والظلام النظام.---## ⚙️ Settings
+
+لوحة الإعدادات شاملة مع علامات التبويب:
+
+-**عام**— تخزين النظام، وإدارة النسخ الاحتياطي (قاعدة بيانات التصدير/الاستيراد) -**المظهر**— محدد السماعة (داكن/فاتح/نظام)، الإعدادات المسبقة لموضوع الألوان والألوان المخصصة، ورؤية السجل الصحي، وعناصر التحكم في رؤية عنصر الشريط الجانبي -**الأمان**— حماية نقطة نهاية واجهة برمجة التطبيقات، وحظر الموفر المخصص، وتصفية IP، ومعلومات الاتصال -**التوجيه**— الأسماء المستعارة للنماذج، و الابتكارات الخلفية -**المرونة**— ونتيجة لذلك الحد الأقصى للمعدل، وضبط القيود، والتعطيل التلقائي للحسابات المحظورة، وانتهاء صلاحية الموفر -**متقدم**— تجاوز، ومسار تدقيق فقط، وتطبيق التدمير الاحتياطي![Settings Dashboard](screenshots/06-settings.png)---
+
+## 🔧 CLI Tools
+
+ختمة واحدة لأدوات تميز الذكاء الصناعي: Claude Code، وCodex CLI، وGemini CLI، وOpenClaw، وKilo Code، وAntigravity، وCline، وContinue، وCursor، وFactory Droid. تم تفعيل/إعادة ضبط تلقائي، فقط تعريف الاتصال، والنتائج المباشرة.![CLI Tools Dashboard](screenshots/07-cli-tools.png)---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+لوحة معلومات للتحكم في وكلاء CLI. تم عرض شبكة مكونة من 14 وكيلًا مدمجًا (Codex وClaude وGoose وGemini CLI وOpenClaw وAider وOpenCode وCline وQwen Code وForgeCode وAmazon Q وOpen Interpreter وCursor CLI وWarp) مع:
+
+-**حالة التثبيت**— تم التثبيت/لم يتم العثور عليه باستخدام اكتشاف الإصدار -**توصيات المذكورة**— stdio، HTTP، وما إلى ذلك. -**الوكلاء يستهدفون**— هل هناك أي أداة لواجهة سطر الوكيل (CLI) عبر النموذج (الاسم، ثنائي، أمر الإصدار، وسيط النشر) -**مطابقة بصمة CLI**— التبديل لكل المرشحين لمطابقة توقيعات طلب CLI الأصلية، مما سيقدر من المبدع بالفعل مع ضمان عنوان IP الوكيل---## 🖼️ Media _(v2.0.3+)_
+
+موجود في الصور ومقاطع الفيديو والموسيقى من لوحة التحكم. يدعم OpenAI وxAI وTogether وHyperbolic وSD WebUI وComfyUI وAnimateDiff وStable Audio Open وMusicGen.---## 📝 Request Logs
+
+تسجيل طلبات الإنتاج في الواقع باستخدام التصفية حسب الموفر والطراز والحساب ومفتاح واجهة برمجة التطبيقات. معلمات القيمة الناتجة عن التعويض الطبيعي ووقت التعويض وتفاصيل التعويض.![Usage Logs](screenshots/08-usage.png)---
+
+## 🌐 API Endpoint
+
+نقطة نهاية واجهة برمجة التطبيقات الموحدة الخاصة بك مع تفاصيل التفاصيل: عمليات التسجيل، وواجهة برمجة تطبيقات الاستجابات، والتضمينات، وأي الصور، إلى الإعداد، والنسخة الصوتية، تحويل النص إلى كلام، والإشراف، ومفاتيح واجهة برمجة التطبيقات المفقودة. تكامل Cloudflare Quick Tunnel للتواصل مع وكيل السحابي للوصول إليه بعد.![Endpoint Dashboard](screenshots/09-endpoint.png)---
+
+## 🔑 API Key Management
+
+إنشاء مفاتيح API ونطاقها لربط وإلها. يمكن أن يكون هناك كل المفاتيح الرئيسية على/موفري خدمات محددة لهم حق الوصول الكامل أو أذونات القراءة فقط. إدارة المفاتيح المرئية مع تكرار الاستخدام.---## 📋 Audit Log
+
+متابعة الإجراءات الإدارية بالتصفية حسب نوع الإجراء والممثل والهدف وعنوان IP والطابع الزمني. سجل الأحداث الأمنية الكاملة.---## 🖥️ Desktop Application
+
+تطبيق Native Electron لسطح المكتب لأنظمة التشغيل Windows وmacOS وLinux. قم بالموافقة على OmniRoute كتطبيق مستقل مع نظام متكامل للنظام والدعم دون الاتصال والتحديث التلقائي والتثبيت بنقرة واحدة.
+
+الميزات الرئيسية:
+
+- استقصاء جاهزية الضيوف (لا توجد شاشة عند التشغيل البارد)
+- نظام إدارة المنافذ
+- اتخاذ القرار بشأن المحتوى
+- مثال واحد
+- التحديث التلقائي عند إعادة التشغيل
+- واجهة المستخدم مشروطة بالكامل (إشارات المرور لنظام التشغيل MacOS، وشريط العنوان الإلكتروني لنظام التشغيل Windows/Linux)
+- بناء الإلكترون المقوى - يتم إبتكار "وحدات_العقدة" وتشهد بالرمز في المقترحات ورفضها قبل قبولها، مما يمنع الاعتماد في وقت التشغيل على البناء (الإصدار 2.5.5+)
+
+📖 راجع [`electron/README.md`](../electron/README.md) للحصول على التوثيق الكامل.

docs/i18n/ar/docs/FLY_IO_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,356 @@
+# OmniRoute Fly.io 部署指南 (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../../es/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../../de/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../../it/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [in](../../in/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../../th/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../../id/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../../no/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../../da/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../../he/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/FLY_IO_DEPLOYMENT_GUIDE.md)
+
+---
+
+تم إنشاء OmniRoute في Fly.io من خلال الرابط التالي:
+
+- تم تطويره بواسطة Fly.io
+- 后续代码更新后继续发布
+- 新项目参考同样流程部署
+
+من المحتمل أن هذا هو السبب في أن كل ما عليك فعله هو ` Omniroute`.---## 1. 部署目标
+
+- الاسم: Fly.io
+- 部署方式: تم إنشاء `flyctl` 直接接发布
+- قم بتنزيل الرابط: قم بتنزيل الملف `Dockerfile` و`fly.toml`.
+- الاسم الأصلي: Fly Volume موجود في `/data`
+- الرابط:`https://omniroute.fly.dev/`---## 2. 当前项目关键配置
+
+قم بزيارة الرابط التالي `fly.toml` من خلال الرابط التالي:```toml
+التطبيق = "الطريق الشامل"
+Primary_region = 'الخطيئة'
+
+[[يتصاعد]]
+المصدر = "البيانات"
+الوجهة = '/ البيانات'
+
+[العمليات]
+التطبيق = 'عقدة تشغيل Standalone.mjs'
+
+[http_service]
+منفذ داخلي = 20128
+
+[بيئة]
+TZ = "آسيا/شنغهاي"
+المضيف = "0.0.0.0"
+اسم المضيف = "0.0.0.0"
+ربط = "0.0.0.0"```
+
+الاسم:
+
+- `app = 'omniroute'' تطبيق Fly 应用
+- `الوجهة = '/ البيانات''
+- قم بإلغاء تحديد `DATA_DIR=/data`، وقم بإلغاء تحديد موقع الويب الخاص بك---
+
+## 3. 必备工具
+
+### 3.1 安装 Fly CLI
+
+ويندوز بوويرشيل:```powershell
+pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"
+
+````
+
+يمكن أن يكون هذا هو الحال بالنسبة لـ "flyctl" أو "PATH" أو "PATH".### 3.2 登录 Fly 账号```powershell
+flyctl auth login
+````
+
+### 3.3 检查登录状态
+
+```powershell
+flyctl auth whoami
+flyctl version
+```
+
+---
+
+## 4. 首次部署当前项目
+
+### 4.1 获取代码并进入目录
+
+```powershell
+git clone https://github.com/xiaoge1688/OmniRoute.git
+cd OmniRoute
+```
+
+### 4.2 确认应用名
+
+قم بزيارة `fly.toml`، باستخدام الرابط التالي:`toml
+التطبيق = "الطريق الشامل"`
+
+يجب أن تكون قادرًا على التعامل مع هذه المشكلة على النحو التالي:```toml
+app = 'omniroute-yourname'
+
+````
+
+الاسم:
+
+- قم بالنقر على زر "fly.toml" من خلال "التطبيق" الموجود على الرابط
+- 以前如果用过别的名字، 例如 `الطريق`، 不要 و``الطريق الشامل` 混淆### 4.3 创建应用
+
+اسم المنتج:```powershell
+تقوم تطبيقات flyctl بإنشاء طريق شامل```
+
+من المؤكد أن هذا يعني أن "الطريق الشامل" هو الطريق الصحيح.### 4.4 首次部署
+
+```powershell
+نشر flyctl```
+
+---
+
+## 5. 必配参数
+
+تم إطلاق لعبة Fly.io على جهاز الكمبيوتر الخاص بك.### 5.1 已验证使用的参数
+
+أفضل الطرق للوصول إلى الطريق الشامل هي:
+
+- `API_KEY_SECRET`
+- `DATA_DIR`
+- `JWT_SECRET`
+- `MACHINE_ID_SALT`
+- `NEXT_PUBLIC_BASE_URL`
+- `STORAGE_ENCRYPTION_KEY`### 5.2 关于 `INITIAL_PASSWORD`
+
+اختر كلمة مرور `INITIAL_PASSWORD`، وقم بإلغاء تحديدها.
+
+العنوان:
+
+- 启动日志会提示默认密码是 `CHANGEME'
+- ماكينات غسيل الملابس
+
+يجب أن تكون قادرًا على التعامل مع هذه المشكلة:
+
+- `INITIAL_PASSWORD`---
+
+## 6. 推荐参数说明
+
+### 6.1 Secrets 中设置
+
+أسرار الطيران:
+
+| 变量名 | 是否推荐 | 说明 |
+| ------------------------ | -------- | ------------------------------ |
+| `API_KEY_SECRET` | 必需 | مفتاح API 生成与校验使用 |
+| `JWT_SECRET` | 必需 | 登录态和 JWT 签名使用 |
+| `STORAGE_ENCRYPTION_KEY` | 强烈推荐 | 加密存储敏感连接信息 |
+| `MACHINE_ID_SALT` | جديد | 生成稳定机器标识 |
+| `INITIAL_PASSWORD` | 可选 | ماكينات غسيل الملابس في الصين |
+| OAuth/API 私密凭证 | الصفحة الرئيسية | 各类外部平台鉴权配置 |### 6.2 当前项目推荐值
+
+| 变量名 | جديد |
+| ---------------------- | --------------------------- |
+| `DATA_DIR` | `/ البيانات` |
+| `NEXT_PUBLIC_BASE_URL` | `https://omniroute.fly.dev` |
+
+الاسم:
+
+- `DATA_DIR=/data` 非常关键،تحديد حجم الطيران
+- `NEXT_PUBLIC_BASE_URL' عنوان البريد الإلكتروني الخاص بنا---
+
+## 7. 一键设置参数
+
+تم إنشاء هذا الرابط من قبل شركة Fly Secrets.
+
+الاسم:
+
+- اختر "INITIAL_PASSWORD".
+- 适用于当前项目 "شامل"```powershell
+$apiKeySecret = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
+$jwtSecret = [Convert]::ToHexString((1..64 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
+$machineIdSalt = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
+$storageKey = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
+
+flyctl secrets set `
+  API_KEY_SECRET=$apiKeySecret `
+  JWT_SECRET=$jwtSecret `
+  MACHINE_ID_SALT=$machineIdSalt `
+  STORAGE_ENCRYPTION_KEY=$storageKey `
+  DATA_DIR=/data `
+  NEXT_PUBLIC_BASE_URL=https://omniroute.fly.dev `
+  -a omniroute
+````
+
+ما هي أفضل الطرق التي يجب اتباعها:`powershell
+مجموعة أسرار flyctl INITIAL_PASSWORD=你的强密码 - طريق شامل`
+
+---
+
+## 8. 查看当前参数
+
+````powershell
+قائمة أسرار flyctl - طريق شامل```
+
+如果控制台 ``الأسرار`` 页面没有显示你期待的变量،先检查:
+
+- omniroute omniroute
+- `fly.toml' 的 `app` 是否和控制台应用一致---
+
+## 9. 后续更新发布
+
+أفضل ما في الأمر:```powershell
+git pull
+flyctl deploy
+````
+
+أفضل ما في الأمر:`powershell
+تعيين أسرار flyctl KEY=value -a omniroute`
+
+يطير هنا.### 9.1 跟踪原仓库更新并保留 fork 的 `fly.toml`
+
+شوكة 如果当前仓库是، 并且你要同步上游 `https://github.com/diegosouzapw/OmniRoute` 的更新، 推荐按下面流程执行.
+
+العنوان:```powershell
+git remote -v
+
+````
+
+اسم المنتج:
+
+- "الأصل" 指向你自己的
+- `المنبع` 指向原仓库
+
+المنبع ``المنبع``:```powershell
+git عن بعد إضافة المنبع https://github.com/diegosouzapw/OmniRoute.git```
+
+أفضل ما في الأمر:```powershell
+git fetch upstream --tags
+````
+
+أفضل ما في الأمر:`powershell
+وصف git --tags --دائما
+عرض git --no-patch --oneline v3.4.7`
+
+如果你想合并上游最新 `main`، 并强制保留 fork 当前的 `fly.toml`، 可按下面流程执行:```powershell
+git merge upstream/main
+git checkout HEAD~1 -- fly.toml
+git add -- fly.toml
+git commit -m "chore(deploy): keep fork fly.toml"
+git push origin main
+
+````
+
+الاسم:
+
+- ``دمج بوابة المنبع/الرئيسية''
+- `git checkout HEAD~1 -- fly.toml` 用于恢复合并前你 fork 自己的 `fly.toml`
+- 如果上游没有改 `fly.toml`، 这一步不会带来额外差异
+- اضغط على `fly.toml`، واستخدام حماية Fly لملفات تعريف الارتباط، والملفات، وشوكة شوكة.
+
+تم إنشاء الإصدار 3.4.7 من الإصدار 3.4.7، وقد تم تصميمه بواسطة ``المنبع/الرئيسي``:```powershell
+git merge-base --is-ancestor v3.4.7 upstream/main```
+
+يتم تحديد المنبع/الرئيسي بواسطة المنبع/الرئيسي.### 9.2 同步上游后的标准发布顺序
+
+أفضل ما في الأمر هو الحصول على أفضل الأسعار:
+
+1. جلب git المنبع --tags
+2. "دمج بوابة المنبع/الرئيسية".
+3. شوكة شوكة "fly.toml".
+4. `جيت دفع الأصل الرئيسي`
+5. "نشر flyctl".
+6. ``حالة flyctl - طريق شامل``
+7. ``flyctl logs --no-tail -a omniroute`
+
+تم تحديث الإصدار `v3.4.7` من الإصدار الجديد.---
+
+## 10. 发布后检查
+
+### 10.1 查看应用状态
+
+```powershell
+حالة flyctl - طريق شامل```
+
+### 10.2 查看启动日志
+
+```powershell
+سجلات flyctl - بدون ذيل - طريق شامل```
+
+### 10.3 检查网站可访问
+
+```powershell
+حاول {
+  (استدعاء WebRequest -Uri "https://omniroute.fly.dev" -MaximumRedirection 5 -UseBasicParsing).رمز الحالة
+} أمسك {
+  إذا ($_.Exception.Response) {
+    $_.Exception.Response.StatusCode.value__
+  } آخر {
+    رمي
+  }
+}```
+
+`200` 说明站点已正常响应.---
+
+## 11. 成功标志
+
+أفضل ما في الأمر:```text
+[bootstrap] Secrets persisted to: /data/server.env
+[DB] SQLite database ready: /data/storage.sqlite
+````
+
+هذا هو الحل:
+
+- `/data/server.env`
+- `/data/storage.sqlite` تم تخزين البيانات فيه
+
+تم إلغاء الطلب `/app/data/...`، ``DATA_DIR` إلغاء الطلب، 需要立即修正.---## 12. 常见问题
+
+### 12.1 `Secrets` 页面是空的
+
+اسم المنتج:
+
+- 你还没执行 "مجموعة أسرار flyctl".
+- تم إلغاء التثبيت، `الطريق`، `الطريق الشامل`### 12.2 `flyctlploy` `لم يتم العثور على التطبيق`
+
+اسم المنتج:`powershell
+تقوم تطبيقات flyctl بإنشاء طريق شامل`
+
+### 12.3 `fly.toml` 解析失败
+
+اسم المنتج:
+
+- 注释里是否有乱码字符
+- TOML 引号和缩进是否正确### 12.4 数据没有持久化
+
+检查以下两点:
+
+- `fly.toml` `الوجهة = '/ البيانات''
+- `DATA_DIR` 是否设置为 `/data`### 12.5 不设置 `INITIAL_PASSWORD` 是否能跑
+
+هذا هو السبب في أن هذا هو السبب وراء `CHANGEME`.---
+
+## 13. 新项目复用建议
+
+لا داعي للقلق بشأن هذه المشكلة:
+
+1. قم بتنزيل "fly.toml" على "التطبيق"
+2. قم بزيارة `NEXT_PUBLIC_BASE_URL`
+3. اختر "DATA_DIR=/data".
+4. قم بالضغط على `API_KEY_SECRET`、`JWT_SECRET`、`MACHINE_ID_SALT`、`STORAGE_ENCRYPTION_KEY`
+5. قم بإنشاء بيانات جديدة `/data`
+
+لا داعي للقلق بشأن هذا الأمر.---
+
+## 14. 当前项目的最小发布清单
+
+أفضل ما في الأمر هو الحصول على أفضل النتائج:```powershell
+flyctl auth whoami
+flyctl status -a omniroute
+flyctl secrets list -a omniroute
+flyctl deploy
+flyctl logs --no-tail -a omniroute
+
+````
+
+أفضل ما في الأمر:```powershell
+نشر flyctl```
+
+أفضل ما في الأمر:
+
+1. "تسجيل الدخول بمصادقة flyctl".
+2. `تطبيقات flyctl تنشئ طريقًا شاملاً`
+3. ``مجموعة أسرار flyctl ... -طريق شامل``
+4. "نشر flyctl".
+5. `سجلات flyctl --no-tail -a omniroute`
+````

docs/i18n/ar/docs/I18N.md

@@ -0,0 +1,361 @@
+# i18n — Internationalization Guide (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/I18N.md) · 🇪🇸 [es](../../es/docs/I18N.md) · 🇫🇷 [fr](../../fr/docs/I18N.md) · 🇩🇪 [de](../../de/docs/I18N.md) · 🇮🇹 [it](../../it/docs/I18N.md) · 🇷🇺 [ru](../../ru/docs/I18N.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/I18N.md) · 🇯🇵 [ja](../../ja/docs/I18N.md) · 🇰🇷 [ko](../../ko/docs/I18N.md) · 🇸🇦 [ar](../../ar/docs/I18N.md) · 🇮🇳 [hi](../../hi/docs/I18N.md) · 🇮🇳 [in](../../in/docs/I18N.md) · 🇹🇭 [th](../../th/docs/I18N.md) · 🇻🇳 [vi](../../vi/docs/I18N.md) · 🇮🇩 [id](../../id/docs/I18N.md) · 🇲🇾 [ms](../../ms/docs/I18N.md) · 🇳🇱 [nl](../../nl/docs/I18N.md) · 🇵🇱 [pl](../../pl/docs/I18N.md) · 🇸🇪 [sv](../../sv/docs/I18N.md) · 🇳🇴 [no](../../no/docs/I18N.md) · 🇩🇰 [da](../../da/docs/I18N.md) · 🇫🇮 [fi](../../fi/docs/I18N.md) · 🇵🇹 [pt](../../pt/docs/I18N.md) · 🇷🇴 [ro](../../ro/docs/I18N.md) · 🇭🇺 [hu](../../hu/docs/I18N.md) · 🇧🇬 [bg](../../bg/docs/I18N.md) · 🇸🇰 [sk](../../sk/docs/I18N.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/I18N.md) · 🇮🇱 [he](../../he/docs/I18N.md) · 🇵🇭 [phi](../../phi/docs/I18N.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/I18N.md) · 🇨🇿 [cs](../../cs/docs/I18N.md) · 🇹🇷 [tr](../../tr/docs/I18N.md)
+
+---
+
+يدعم OmniRoute**30 لغة**مع ترجمة كاملة لواجهة مستخدم لوحة المعلومات، والوثائق المترجمة، ودعم RTL للغة العربية والعبرية.## مرجع سريع
+
+| مهمة                                 | الأمر                                                                                   |
+| ------------------------------------ | --------------------------------------------------------------------------------------- | ---------------------------- |
+| توليد الترجمات                       | `نصوص المؤتمرة/i18n/generate-multilang.mjs messages`                                    |
+| ترجمة المستندات (ماجستير في القانون) | `python3 scripts/i18n_autotranslate.py --api-url <url> --api-key <key> --model <model>` |
+| التحقق من صحة اللغة                  | `python3 scripts/validate_translation.py fast -l cs`                                    |
+| تحقق من المفاتيح التعليمات           | `python3 scripts/check_translations.py`                                                 |
+| إنشاء تقرير ضمان الجودة              | `العقدة النصية/i18n/generate-qa-checklist.mjs`                                          |
+| ضمان الجودة المرئية (كاتب مسرحي)     | `العقدة النصية/i18n/run-visual-qa.mjs`                                                  | ##الهندسة### Source of Truth |
+
+-**سلاسل واجهة المستخدم**: `src/i18n/messages/en.json` (المصدر باللغة الإنجليزية، ~2800 مفتاح) -**ملفات اللغة**: `src/i18n/messages/{locale}.json` (30 ترجمة) -**Framework**: `next-intl` مع الاعتماد التلقائي المستندة إلى ملفات تعريف الارتباط -**التكوين**: `src/i18n/config.ts` — يحدد جميع اللغات الثلاثين وأسماء اللغات والأعلام### Runtime Flow
+
+1. يقوم المستخدم باختيار اللغة → مجموعة ملفات تعريف الارتباط `NEXT_LOCALE`
+2. `src/i18n/request.ts` يحل اللغة: ملف تعريف الارتباط → رأس `قبول اللغة` → محايد `ar`
+3. يقوم باستيراد الرسائل الالكترونية/{locale}.json
+   4.استخدام المكونات `useTranslations("namespace")` و`t("key")`### اللغات المدعومة
+
+| الكود                | اللغة                 | من الإنجليزية إلى فارس | كود ترجمة جوجل    |
+| -------------------- | --------------------- | ---------------------- | ----------------- | -------------------------------------------- |
+| `ع`                  | العربية               | نعم                    | `ع`               |
+| `بج`                 | البلغارية             | لا                     | `بج`              |
+| `CS`                 | تشيستينا              | لا                     | `CS`              |
+| `دا`                 | دانسك                 | لا                     | `دا`              |
+| `دي`                 | الألمانية             | لا                     | `دي`              |
+| `es`                 | الاسبانية             | لا                     | `es`              |
+| `في`                 | سومي                  | لا                     | `في`              |
+| `الاب`               | الفرنسية              | لا                     | `الاب`            |
+| `هو`                 | عبرية                 | نعم                    | `iw`              |
+| `مرحبا`              | الهندية               | لا                     | `مرحبا`           |
+| `هو`                 | المجرية               | لا                     | `هو`              |
+| "معرف"               | البهاسا الإندونيسية   | لا                     | "معرف"            |
+| "إنه"                | إيطالينو              | لا                     | "إنه"             |
+| `جا`                 | 日本語                | لا                     | `جا`              |
+| `كو`                 | 한국어                | لا                     | `كو`              |
+| `مس`                 | البهاسا ملايو         | لا                     | `مس`              |
+| `نل`                 | هولندا                | لا                     | `نل`              |
+| `لا`                 | نورسك                 | لا                     | `لا`              |
+| `فاي`                | فلبينية               | لا                     | `ل`               |
+| `ر`                  | بولسكي                | لا                     | `ر`               |
+| `نقطة`               | البرتغالية (البرتغال) | لا                     | `نقطة`            |
+| `pt-BR`              | إسبانيا (البرازيل)    | لا                     | `نقطة`            |
+| `رو`                 | رومانا                | لا                     | `رو`              |
+| `رو`                 | Русский               | لا                     | `رو`              |
+| `سك`                 | سلوفينيا              | لا                     | `سك`              |
+| `sv`                 | سفينسكا               | لا                     | `sv`              |
+| `ال`                 | ไทย                   | لا                     | `ال`              |
+| `تر`                 | تركي                  | لا                     | `تر`              |
+| `المملكة المتحدة-UA` | أوكرانيا              | لا                     | `المملكة المتحدة` |
+| `السادس`             | تينغ فيت              | لا                     | `السادس`          |
+| `zh-CN`              | 中文 (简体)           | لا                     | `zh-CN`           | ## إضافة لغة جديدة### 1. Register the Locale |
+
+تحرير `src/i18n/config.ts`:`ts
+// أضف إلى مجموعة LOCALES
+"س س"،
+// أضف إلى مصفوفة اللغات
+{ الكود: "xx"، التصنيف: "XX"، الاسم: "اسم اللغة"، العلم: "🏳️" },`
+
+### 2. Add to Generator
+
+تحرير "scripts/i18n/generate-multilang.mjs" - إضافة إدخال إلى "LOCALE_SPECS":```js
+{
+code: "xx",
+googleTl: "xx",
+label: "XX",
+flag: "🏳️",
+languageName: "Language Name",
+readmeName: "Language Name",
+docsName: "Language Name",
+},
+
+````
+
+### 3. Generate Initial Translation
+
+```bash
+node scripts/i18n/generate-multilang.mjs messages
+````
+
+يؤدي هذا إلى إنشاء src/i18n/messages/xx.json مترجمًا آليًا من `en.json` عبر الترجمة خدمة من Google.### 4. مراجعة الترجمات التلقائية وإصلاحها
+
+الترجمات التلقائية هي نقطة البداية. التعديل اليدوي لـ:
+
+- الدقة الفنية
+- المصطلحات الصحيحة للسياق
+- التعامل مع العناصر النائبة (`{count}`، `{value}`، وما إلى ذلك)### 5. التحقق من صحة```bash
+  python3 scripts/validate_translation.py quick -l xx
+  python3 scripts/validate_translation.py diff common -l xx
+
+````
+
+### 6. Generate Translated Documentation
+
+```bash
+node scripts/i18n/generate-multilang.mjs docs
+````
+
+## Auto-Translation Pipeline
+
+### generate-multilang.mjs (Google Translate)
+
+**محرك الترجمة التلقائي الأساسي**— يستخدم برمجة برمجة تطبيقات لترجمة Google إنشاء ترجمات لسلاسل واجهة المستخدم والملفات البرمجة والوثائق.`bash
+البرامج النصية للعقدة/i18n/generate-multilang.mjs [الرسائل|الملف التمهيدي|المستندات|الكل]`
+
+| الوضع            | ماذا يفعل                                                                 |
+| ---------------- | ------------------------------------------------------------------------- |
+| `الرسائل`        | يترجم المفاتيح المفقودة في `src/i18n/messages/{locale}.json` من `en.json` |
+| "الملف التمهيدي" | يترجم `README.md` إلى كافة اللغات كـ `README.{code}.md` في جذر المشروع    |
+| `المستندات`      | يترجم `DOC_SOURCE_FILES` إلى `docs/i18n/{locale}/{docName}`               |
+| `الكل`           | يعمل على جميع الأوضاع الثلاثة                                             |
+
+**الميزات:**
+
+-**حماية النص**: كتل التعليمات البرمجية للأقنعة (```)، والتعليمات البرمجية المضمنة (`` `)، وروابط/صور تخفيض السعر (`[نص](url)`)، وعلامات HTML، والجداول، والعناصر النائبة لـ ICU (`{count}`، `{value}`، `{total}`، وما إلى ذلك) قبل الترجمة، ثم استعادتها -**التجميع المقسم**: ربط سلاسل متعددة باستخدام محددات `__OMNIROUTE_I18N_SEPARATOR__` لتقليل استدعاءات واجهة برمجة التطبيقات (بحد أقصى 1800 حرف لكل طلب) -**ذاكرة التخزين المؤقت في الذاكرة**: تتجنب استدعاءات واجهة برمجة التطبيقات المتكررة للسلاسل المتكررة خلال الجلسة -**منطق إعادة المحاولة**: التراجع الأسي (حتى 5 محاولات مع 300 مللي ثانية × تأخير المحاولة) للأخطاء 429/5xx -**المهلة**: 20 ثانية لكل طلب -**تخطي الملف الموجود**: إذا كان الملف الهدف موجودًا بالفعل، فلن تتم الكتابة فوقه
+
+**سلوكيات مهمة:**
+
+- `docs/i18n/README.md` يتم**إعادة إنشائه**كل مرة — وهو عبارة عن فهرس يتم إنشاؤه تلقائيًا لجميع المستندات
+- يتم إنشاء ملفات `README.{code}.md` الجذر فقط في حالة عدم وجودها (يتخطى اللغات المحلية في `EXISTING_README_CODES`)
+- يتم إدراج/تحديث أشرطة اللغة (`🌐**اللغات:**...`) تلقائيًا في جميع المستندات المترجمة### i18n_autotranslate.py (LLM-based)
+
+**مترجم ثانوي**— يستخدم أي LLM API متوافق مع OpenAI (بما في ذلك OmniRoute نفسه) لترجمة ملفات تخفيض السعر الموجودة `docs/i18n/`. الأفضل لتلميع المستندات أو إعادة ترجمتها بجودة أفضل من ترجمة Google.```bash
+python3 scripts/i18n_autotranslate.py \
+ --api-url http://localhost:20128/v1 \
+ --api-key sk-your-key \
+ --model gpt-4o
+
+````
+
+**الميزات:**
+
+- يقوم بمسح الملفات المشهورة بسعر رخيص `docs/i18n/` بحثًا عن الفقرات الإنجليزية
+- تخطي كتل التعليمات البرمجية والبرمجيات والمحتوى المترجم بالفعل
+- يرسلون الفقرات إلى LLM مع نظام الترجمة الفوري
+- يدعم جميع اللغات الثلاثين## Validation & QA### validate_translation.py
+
+**أداة التحقق من صحة الترجمة**— مقارنة أي لغة JSON مع `en.json` وإبلاغ المشكلات.```bash
+# فحص سريع (التهم فقط)
+python3 scripts/validate_translation.py fast -l cs
+# الإخراج:
+#مفقود: 0
+# غير مترجم: 0
+# تم التجاهل (UNTRANSLATABLE_KEYS): 236
+
+# الفرق التفصيلي حسب الفئة
+python3 scripts/validate_translation.py diff common -l cs
+python3 scripts/validate_translation.py إعدادات الفرق -l cs
+
+# تصدير إلى CSV
+python3 scripts/validate_translation.py csv -l cs > report.csv
+
+# تصدير إلى تخفيض السعر
+python3 scripts/validate_translation.py md -l cs > report.md
+
+# التقرير الكامل (الافتراضي)
+python3 scripts/validate_translation.py -l cs```
+
+**يكتشف:**
+
+-**المفاتيح المفقودة**— المفاتيح الموجودة في `en.json` ولكن ليست في الملف المحلي
+-**مفاتيح إضافية**— مفاتيح في ملف الإعدادات المحلية ولكن ليس في `en.json`
+-**المفاتيح غير المترجمة**— المفاتيح التي تساوي فيها قيمة اللغة المصدر باللغة الإنجليزية (باستثناء القائمة المسموح بها)
+-**عدم تطابق العناصر النائبة**— العناصر النائبة لـ ICU غير متطابقة بين المصدر والترجمة
+
+**رموز الخروج:**
+| الكود | معنى |
+|------|---------|
+| 0 | موافق |
+| 1 | خطأ عام |
+| 2 | سلاسل مفقودة (خطأ فادح) |
+| 3 | تحذير غير مترجم (ناعم) |
+
+**البيئة:**قم بتعيين `TRANSLATION_LANG=cs` أو استخدم علامة `-l cs`.### check_translations.py
+
+**مدقق المفاتيح Code-to-JSON**— يفحص `src/**/*.tsx` و`src/**/*.ts` لاستدعاءات `useTranslations()` ويتحقق من وجود جميع المفاتيح المشار إليها في `en.json`.```bash
+# Basic check
+python3 scripts/check_translations.py
+
+# Verbose output
+python3 scripts/check_translations.py --verbose
+
+# Auto-fix (adds missing keys to en.json)
+python3 scripts/check_translations.py --fix
+````
+
+### generate-qa-checklist.mjs
+
+**تحليل ثابت وجودة**— يقوم بفحص الملفات صفحة Next.js بحثًا عن مقاييس ألمانية i18n منشئ ويتقرير Markdown.`bash
+العقدة النصية/i18n/generate-qa-checklist.mjs`
+
+**الفحوصات:**
+
+- استخدام فئة العرض الثابت (خطر التجاوز)
+- فئات الاتجاه لليسار/اليمين (خطر RTL)
+- الأنماط المعرضة للتقطيع
+- التكافؤ المحلي (مفاتيح مفقودة/إضافية مقابل `en.json`)
+- أشرطة تحديد اللغة README في اللغات المحلية ذات الأولوية (`es`، `fr`، `de`، `ja`، `ar`)
+
+**الإخراج:**`docs/reports/i18n-qa-checklist-{date}.md`### run-visual-qa.mjs
+
+**Visual QA عبر Playwright**— يلتقط لقطات شاشة لجميع مسارات لوحة المعلومات في مناطق ومنافذ عرض متعددة، ثم يقوم بتقييم صحة الصفحة.```bash
+
+# Default: es, fr, de, ja, ar on localhost:20128
+
+node scripts/i18n/run-visual-qa.mjs
+
+# Custom base URL and locales
+
+QA_BASE_URL=http://staging.example.com QA_LOCALES=de,fr node scripts/i18n/run-visual-qa.mjs
+
+# Custom routes
+
+QA_ROUTES=/dashboard/settings,/dashboard/providers node scripts/i18n/run-visual-qa.mjs
+
+````
+
+**اكتشف:**
+
+- تجاوز النص
+- قطع العناصر
+- عدم تطابق تخطيط RTL
+
+**الإخراج:**`docs/reports/i18n-visual-qa-{date}.md` + تقرير JSON## إدارة المفاتيح غير القابلة للترجمة### untranslatable-keys.json
+
+**الملف:**`scripts/i18n/untranslatable-keys.json`
+
+"""""""""""للمفاتيح التي يجب أن تستعين بها للمصدر باللغة الإنجليزية. انتبه بواسطة `validate_translation.py` للإشعارات المسببة لأسباب "غير الترجمة".```json
+{
+  "description": "المفاتيح التي يجب أن تظل غير مترجمة..."،
+  "مفاتيح": [
+    "النموذج المشترك"،
+    "common.oauth"،
+    "health.cpu"،
+    ...
+  ]
+}```
+
+**ما ينتمي هنا:**
+
+- أسماء العلامات التجارية/المنتجات: `landing.brandName`، `common.social-github`
+- المصطلحات/المختصرات الفنية: `health.cpu`، `mcpDashboard.pid`، `settings.ai`
+- سلاسل ICU/تنسيق: `apiManager.modelsCount`، `health.millithansShort`
+- قيم العنصر النائب: `providers.openaiBaseUrlPlaceholder`، `cliTools.baseUrlPlaceholder`
+- أسماء البروتوكولات: `common.http`، `common.oauth`، `providers.oauth2Label`
+- أقسام التنقل: `sidebar.primarySection`، `sidebar.cliSection`
+
+**لإضافة مفتاح:**قم بتحرير مصفوفة `المفاتيح` في `scripts/i18n/untranslatable-keys.json` وأعد تشغيل التحقق من الصحة.## CI Integration
+
+### GitHub Actions (`.github/workflows/ci.yml`)
+
+يتحقق خط أنابيب CI من صحة جميع اللغات في كل دفعة وPR:
+
+1.**`i18n-matrix` job**— يكتشف بشكل ديناميكي جميع الملفات المحلية (باستثناء `en.json`)
+2.**`i18n` job**— يتم تشغيل `validate_translation.py Quick -l '<lang>'` لكل لغة بالتوازي
+3.**`ci-summary` job**— تجميع النتائج في ملخص لوحة المعلومات```yaml
+# i18n-matrix: discovers languages
+LANGS=$(ls src/i18n/messages/*.json | xargs -n1 basename | sed 's/.json$//' | grep -v '^en$')
+
+# i18n: validates each language
+python3 scripts/validate_translation.py quick -l '${{ matrix.lang }}'
+````
+
+**إخراج لوحة التحكم:**```
+
+## 🌍 الترجمات
+
+| متري              | القيمة |
+| ----------------- | ------ |
+| تم فحص اللغات     | 30     |
+| المجموع غير مترجم | 0      |
+
+✅جميع الترجمات كاملة```
+
+## File Structure
+
+````
+سرك/i18n/
+├── config.ts # تعريفات الإعدادات المحلية (30 لغة، تكوين RTL)
+├── request.ts # دقة لغة وقت التشغيل
+└── الرسائل/
+    ├── ar.json # مصدر الحقيقة (~2800 مفتاح)
+    ├── cs.json # الترجمة التشيكية
+    ├── de.json # ترجمة ألمانية
+    └── ... إجمالي # 30 ملفًا محليًا
+
+البرامج النصية/
+├──i18n/
+│ ├── generator-multilang.mjs # محرك الترجمة التلقائية (ترجمة جوجل، 888 سطرًا)
+│ ├── create-qa-checklist.mjs # التحليل الثابت ضمان الجودة
+│ ├── run-visual-qa.mjs # Playwright visual QA
+│ └── untranslatable-keys.json # القائمة المسموح بها للتحقق (236 مفتاحًا)
+├── validate_translation.py # مدقق الترجمة
+├── check_translations.py # مدقق مفتاح Code-to-JSON
+└── i18n_autotranslate.py # مترجم مستندات مستند إلى LLM
+
+.جيثب/سير العمل/
+└── التحقق من صحة ci.yml # i18n في مصفوفة CI
+
+المستندات/
+├── I18N.md # هذا الملف — وثائق سلسلة أدوات i18n
+├──i18n/
+│ ├── README.md # فهرس اللغة الذي تم إنشاؤه تلقائيًا
+│ ├── cs/ # مستندات تشيكية
+│ │ └── المستندات /
+│ │ ├── I18N.md # الترجمة التشيكية لهذا الملف
+│ │ └── ...
+│ ├── de/ # المستندات الألمانية
+│ └── ... # 30 دليل محلي
+└── التقارير/
+    ├── i18n-qa-checklist-*.md # تقارير التحليل الثابت
+    └── i18n-visual-qa-*.md # تقارير ضمان الجودة المرئية```
+
+## Best Practices
+
+### When Editing Translations
+
+1.**قم دائمًا بتحرير `en.json` أولاً**— فهو مصدر الحقيقة
+2.**قم بتشغيل رسائل generator-multilang.mjs**لنشر مفاتيح جديدة لجميع اللغات
+3.**مراجعة الترجمات التلقائية**— ترجمة Google هي نقطة البداية، وليست نهائية
+4.**التحقق قبل الالتزام**— `python3 scripts/validate_translation.py Quick -l <lang>`
+5.**قم بتحديث `untranslatable-keys.json`**إذا كان ينبغي أن يظل المفتاح باللغة الإنجليزية### Placeholder Safety
+
+- يجب الحفاظ على العناصر النائبة لـ ICU (`{count}`، `{value}`، `{total}`، `{secions}`) تمامًا
+- يجب أن تحافظ صيغ الجمع (`{count, plural, one {# model} الأخرى {#models}}`) على البنية
+- يكتشف المدقق عدم تطابق العناصر النائبة تلقائيًا### Adding New Translation Keys in Code
+
+```tsx
+// استخدم مفاتيح مساحة الاسم
+const t = useTranslations("الإعدادات");
+t("إعدادات ذاكرة التخزين المؤقت"); // يتم تعيينه إلى settings.cacheSettings في JSON
+
+// قم بتشغيل check_translations.py للتحقق من وجود المفاتيح
+python3 scripts/check_translations.py --verbose```
+
+### RTL Considerations
+
+- العربية (`ar`) والعبرية (`he`) هي لغات RTL
+- تجنب استخدام لغة CSS ذات الترميز الثابت `left`/`right` - استخدم الخصائص المنطقية `start`/`end`
+- تكتشف Visual QA عدم تطابق تخطيط RTL عبر "run-visual-qa.mjs".## Known Issues & History
+
+### `in.json` → `hi.json` Fix
+
+استخدم المولد في الأصل `الكود: "in"` (كود ترجمة Google المهجور) للغة الهندية بدلاً من ISO 639-1 الصحيح `hi`. أدى هذا إلى إنشاء نسخة معزولة `in.json` من `hi.json`. تم الإصلاح عن طريق تغيير `code: "in"` إلى `code: "hi"` في `generate-multilang.mjs` وإزالة الملف المعزول.### `docs/i18n/README.md` Is Auto-Generated
+
+تمت إعادة إنشاء الملف "docs/i18n/README.md" بالكامل بواسطة "generate-multilang.mjs docs". سيتم فقدان أي تعديلات يدوية. استخدم `docs/I18N.md` (هذا الملف) للوثائق المكتوبة بخط اليد والتي يجب أن تستمر.### External Untranslatable Keys List
+
+تم نقل القائمة المسموح بها `untranslatable-keys.json` من مجموعة Python المضمنة في `validate_translation.py` إلى ملف JSON خارجي لتسهيل الصيانة. يقوم المدقق بتحميله في وقت التشغيل.### `generate-multilang.mjs` Hindi Code Fix
+
+استخدم المولد في الأصل `الكود: "in"` (كود ترجمة Google المهجور) للغة الهندية بدلاً من ISO 639-1 الصحيح `hi`. تم تقديم هذا في الالتزام الأولي `952b0b22c` بواسطة diegosouzapw. تم الإصلاح عن طريق تغيير `code: "in"` إلى `code: "hi"` في مصفوفة `LOCALE_SPECS` وإزالة الملف اليتيم `in.json`.### `validate_translation.py` Ignored Count Output
+
+يعرض الفحص "السريع" الآن عدد المفاتيح التي تم تجاهلها من "untranslatable-keys.json":```
+Missing: 0
+Untranslated: 0
+Ignored (UNTRANSLATABLE_KEYS): 236
+````

docs/i18n/ar/docs/MCP-SERVER.md

@@ -0,0 +1,72 @@
+# OmniRoute MCP Server Documentation (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/MCP-SERVER.md) · 🇪🇸 [es](../../es/docs/MCP-SERVER.md) · 🇫🇷 [fr](../../fr/docs/MCP-SERVER.md) · 🇩🇪 [de](../../de/docs/MCP-SERVER.md) · 🇮🇹 [it](../../it/docs/MCP-SERVER.md) · 🇷🇺 [ru](../../ru/docs/MCP-SERVER.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/MCP-SERVER.md) · 🇯🇵 [ja](../../ja/docs/MCP-SERVER.md) · 🇰🇷 [ko](../../ko/docs/MCP-SERVER.md) · 🇸🇦 [ar](../../ar/docs/MCP-SERVER.md) · 🇮🇳 [hi](../../hi/docs/MCP-SERVER.md) · 🇮🇳 [in](../../in/docs/MCP-SERVER.md) · 🇹🇭 [th](../../th/docs/MCP-SERVER.md) · 🇻🇳 [vi](../../vi/docs/MCP-SERVER.md) · 🇮🇩 [id](../../id/docs/MCP-SERVER.md) · 🇲🇾 [ms](../../ms/docs/MCP-SERVER.md) · 🇳🇱 [nl](../../nl/docs/MCP-SERVER.md) · 🇵🇱 [pl](../../pl/docs/MCP-SERVER.md) · 🇸🇪 [sv](../../sv/docs/MCP-SERVER.md) · 🇳🇴 [no](../../no/docs/MCP-SERVER.md) · 🇩🇰 [da](../../da/docs/MCP-SERVER.md) · 🇫🇮 [fi](../../fi/docs/MCP-SERVER.md) · 🇵🇹 [pt](../../pt/docs/MCP-SERVER.md) · 🇷🇴 [ro](../../ro/docs/MCP-SERVER.md) · 🇭🇺 [hu](../../hu/docs/MCP-SERVER.md) · 🇧🇬 [bg](../../bg/docs/MCP-SERVER.md) · 🇸🇰 [sk](../../sk/docs/MCP-SERVER.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/MCP-SERVER.md) · 🇮🇱 [he](../../he/docs/MCP-SERVER.md) · 🇵🇭 [phi](../../phi/docs/MCP-SERVER.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/MCP-SERVER.md) · 🇨🇿 [cs](../../cs/docs/MCP-SERVER.md) · 🇹🇷 [tr](../../tr/docs/MCP-SERVER.md)
+
+---
+
+> المدرسة التمهيدية النموذجية المزود بـ 16 أداة ذكية## تثبيت
+
+OmniRoute MCP المدمج. ابدأ بـ:`bash
+الطريق الشامل --mcp`
+
+أو عبر النقل المفتوح:```bash
+
+# HTTP streamable transport (port 20130)
+
+omniroute --dev # MCP auto-starts on /mcp endpoint
+
+```
+
+## IDE Configuration
+
+مراجعة تكوينات IDE](integrations/ide-configs.md) التوجه إلى إعداد Antigravity وCursor وCopilot وClaude Desktop.---## Essential Tools (8)
+
+| أداة | الوصف |
+| :------------------------------ | :--------------------------------------- |
+| `omniroute_get_health` | صحة البوابة، قواطع الضوء، الجهوزية |
+| `omniroute_list_combos` | جميع المجموعات التي تم اختيارها مع الارتباطات |
+| `omniroute_get_combo_metrics` | مقاييس محددة |
+| `omniroute_switch_combo` | تعديل التحرير والسرد فقط حسب المعرف/الاسم |
+| `omniroute_check_quota` | حالة الحصة لكل ما يتعلق أو الكل |
+| `omniroute_route_request` | استكمال الدردشة من خلال OmniRoute |
+| `تقرير رحلة_الطريق الشامل` | تحليلات التكلفة لوقت طويل |
+| `omniroute_list_models_catalog` | كتالوج نموذجي كامل مع رموزيات |## أدوات متقدمة (8)
+
+| أداة | الوصف |
+| :--------------------------------- | :---------------------------------------------------------- |
+| `omniroute_simulate_route` | المحاكاة الجافة باستخدام الشجرة التقليدية |
+| `omniroute_set_budget_guard` | ضبط إجراءات مع التخفيض/الحظر/التنبيه |
+| `omniroute_set_resilience_profile` | التقدم نحو التقدم/المتوازن/العدواني |
+| `omniroute_test_combo` | تم اختباره بشكل مباشر لجميع الاتجاهات في مجموعة من خلال طلب حقيقي للمنبع |
+| `omniroute_get_provider_metrics` | معايير محددة لمزود واحد |
+| `omniroute_best_combo_for_task` | وصفة بملاءة المهام مع البدائل |
+| `omniroute_explain_route` | شرح الوضع السابق |
+| `omniroute_get_session_snapshot` | ملحوظة: التكاليف والرموز والأخطاء |## Authentication
+
+تم مصادقة أدوات MCP عبر نطاقات المفاتيح API. متطلبات كل أدوات النطاقات المحددة:
+
+| النطاق | أدوات |
+| :------------- | :----------------------------------------------- |
+| `اقرأ:الصحة` | get_health، get_provider_metrics |
+| `اقرأ: المجموعات` | list_combos، get_combo_metrics |
+| `اكتب: المجموعات` | Switch_combo |
+| `اقرأ: الحصة` | check_quota |
+| `اكتب: الطريق` | طلب_الطريق، محاكاة_الطريق، اختبار_كومبو |
+| `قراءة:استخدام` | إقرار التكلفة، الحصول على لقطة_الجلسة، شرح_الطريق |
+| `الكتابة: إستبدل` | set_budget_guard، set_resilience_profile |
+| `اقرأ:النماذج` | list_models_catalog، best_combo_for_task |## تسجيل التدقيق
+
+يتم تسجيل كل الاتصال للأداة في `mcp_tool_audit` باستخدام:
+
+- اسم الأداة، والوسائط، والنتيجة
+- المدة (مللي ثانية)، النجاح/الفشل
+- تجزئة مفتاح API، الأثر العمري## Files
+
+| ملف | الحصاد |
+| :------------------------------------------- | :------------------------------------------ |
+| `open-sse/mcp-server/server.ts` | إنشاء خادم MCP + تسجيل 16 أداة |
+| `open-sse/mcp-server/transport.ts` | نقل Stdio + HTTP |
+| `open-sse/mcp-server/auth.ts` | مفتاح API + التحقق من صحة النطاق |
+| `open-sse/mcp-server/audit.ts` | تسجيل تدقيق الاتصال بالأداة |
+| `open-sse/mcp-server/tools/advancedTools.ts` | 8 معالجات وأدوات متقدمة |
+```

docs/i18n/ar/docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,26 @@
+# Release Checklist (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/RELEASE_CHECKLIST.md) · 🇪🇸 [es](../../es/docs/RELEASE_CHECKLIST.md) · 🇫🇷 [fr](../../fr/docs/RELEASE_CHECKLIST.md) · 🇩🇪 [de](../../de/docs/RELEASE_CHECKLIST.md) · 🇮🇹 [it](../../it/docs/RELEASE_CHECKLIST.md) · 🇷🇺 [ru](../../ru/docs/RELEASE_CHECKLIST.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) · 🇯🇵 [ja](../../ja/docs/RELEASE_CHECKLIST.md) · 🇰🇷 [ko](../../ko/docs/RELEASE_CHECKLIST.md) · 🇸🇦 [ar](../../ar/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [hi](../../hi/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [in](../../in/docs/RELEASE_CHECKLIST.md) · 🇹🇭 [th](../../th/docs/RELEASE_CHECKLIST.md) · 🇻🇳 [vi](../../vi/docs/RELEASE_CHECKLIST.md) · 🇮🇩 [id](../../id/docs/RELEASE_CHECKLIST.md) · 🇲🇾 [ms](../../ms/docs/RELEASE_CHECKLIST.md) · 🇳🇱 [nl](../../nl/docs/RELEASE_CHECKLIST.md) · 🇵🇱 [pl](../../pl/docs/RELEASE_CHECKLIST.md) · 🇸🇪 [sv](../../sv/docs/RELEASE_CHECKLIST.md) · 🇳🇴 [no](../../no/docs/RELEASE_CHECKLIST.md) · 🇩🇰 [da](../../da/docs/RELEASE_CHECKLIST.md) · 🇫🇮 [fi](../../fi/docs/RELEASE_CHECKLIST.md) · 🇵🇹 [pt](../../pt/docs/RELEASE_CHECKLIST.md) · 🇷🇴 [ro](../../ro/docs/RELEASE_CHECKLIST.md) · 🇭🇺 [hu](../../hu/docs/RELEASE_CHECKLIST.md) · 🇧🇬 [bg](../../bg/docs/RELEASE_CHECKLIST.md) · 🇸🇰 [sk](../../sk/docs/RELEASE_CHECKLIST.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) · 🇮🇱 [he](../../he/docs/RELEASE_CHECKLIST.md) · 🇵🇭 [phi](../../phi/docs/RELEASE_CHECKLIST.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) · 🇨🇿 [cs](../../cs/docs/RELEASE_CHECKLIST.md) · 🇹🇷 [tr](../../tr/docs/RELEASE_CHECKLIST.md)
+
+---
+
+استخدم قائمة التحقق هذه قبل وضع علامة على إصدار OmniRoute الجديد أو نشره.## الإصدار وسجل التغيير
+
+1. قم بتثبيت الإصدار `package.json` (`x.y.z`) في فرع الإصدار.
+2. انقل نسخة التعليقات من `## [Unreleased]` في `CHANGELOG.md` إلى قسم المؤرخ:
+   - `## [x.y.z] — YYYY-MM-DD`
+3. يستخدم بـ `## [Unreleased]` كقسم جديد للعمل القادم القادم.
+4. تأكد من أن أحدث قسم في `CHANGELOG.md` يساوي الإصدار `package.json`.## API Docs
+
+5. قم بزيارة "docs/openapi.yaml":
+   - يجب أن يكون `info.version` مساويًا لإصدار `package.json`.
+6. التحقق من صحة الأمثلة على نقاط نهائية في حالة عدة عقود API.## Runtime Docs
+
+7. قم بمراجعة docs/ARCHITECTURE.md للتخزين/وقت التشغيل.
+8. راجع `docs/TROUBLESHOOTING.md` بحثًا عن env var والانجراف التشغيلي.
+9. قم بزيارة الموقع بشكل غير المترجم إذا تغيرت مصدر العشب ملحوظة.## الفحص الآلي
+
+يُسمح له بالسيطرة المحلية قبل فتح العلاقات العامة:`bash
+التحقق من تشغيل npm:docs-sync`
+
+يقوم CI أيضًا بتشغيل هذا الفحص في `.github/workflows/ci.yml` (مهمة الوبر).

docs/i18n/ar/docs/TROUBLESHOOTING.md

@@ -0,0 +1,175 @@
+# Troubleshooting (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/TROUBLESHOOTING.md) · 🇪🇸 [es](../../es/docs/TROUBLESHOOTING.md) · 🇫🇷 [fr](../../fr/docs/TROUBLESHOOTING.md) · 🇩🇪 [de](../../de/docs/TROUBLESHOOTING.md) · 🇮🇹 [it](../../it/docs/TROUBLESHOOTING.md) · 🇷🇺 [ru](../../ru/docs/TROUBLESHOOTING.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) · 🇯🇵 [ja](../../ja/docs/TROUBLESHOOTING.md) · 🇰🇷 [ko](../../ko/docs/TROUBLESHOOTING.md) · 🇸🇦 [ar](../../ar/docs/TROUBLESHOOTING.md) · 🇮🇳 [hi](../../hi/docs/TROUBLESHOOTING.md) · 🇮🇳 [in](../../in/docs/TROUBLESHOOTING.md) · 🇹🇭 [th](../../th/docs/TROUBLESHOOTING.md) · 🇻🇳 [vi](../../vi/docs/TROUBLESHOOTING.md) · 🇮🇩 [id](../../id/docs/TROUBLESHOOTING.md) · 🇲🇾 [ms](../../ms/docs/TROUBLESHOOTING.md) · 🇳🇱 [nl](../../nl/docs/TROUBLESHOOTING.md) · 🇵🇱 [pl](../../pl/docs/TROUBLESHOOTING.md) · 🇸🇪 [sv](../../sv/docs/TROUBLESHOOTING.md) · 🇳🇴 [no](../../no/docs/TROUBLESHOOTING.md) · 🇩🇰 [da](../../da/docs/TROUBLESHOOTING.md) · 🇫🇮 [fi](../../fi/docs/TROUBLESHOOTING.md) · 🇵🇹 [pt](../../pt/docs/TROUBLESHOOTING.md) · 🇷🇴 [ro](../../ro/docs/TROUBLESHOOTING.md) · 🇭🇺 [hu](../../hu/docs/TROUBLESHOOTING.md) · 🇧🇬 [bg](../../bg/docs/TROUBLESHOOTING.md) · 🇸🇰 [sk](../../sk/docs/TROUBLESHOOTING.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) · 🇮🇱 [he](../../he/docs/TROUBLESHOOTING.md) · 🇵🇭 [phi](../../phi/docs/TROUBLESHOOTING.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) · 🇨🇿 [cs](../../cs/docs/TROUBLESHOOTING.md) · 🇹🇷 [tr](../../tr/docs/TROUBLESHOOTING.md)
+
+---
+
+المشاكل والحلول الشائعة لـ OmniRoute.---## Quick Fixes
+
+| مشكلة                                 | الحل                                                                  |
+| ------------------------------------- | --------------------------------------------------------------------- | --------------------- |
+| تسجيل الدخول الأول لا يعمل            | قم بزيارة `INITIAL_PASSWORD` في `.env` (بدون ترميز افتراضي)           |
+| بدأت لوحة المعلومات على المنفذ الخاطئ | قم بزيارة `PORT=20128` و`NEXT_PUBLIC_BASE_URL=http://localhost:20128` |
+| لا توجد سجلات للطلب ضمن `السجلات/`    | اضبط `ENABLE_REQUEST_LOGS=true`                                       |
+| EACCES: تم رفض الإذن                  | اضبط `DATA_DIR=/path/to/writable/dir` لتجاوز `~/.omniroute`           |
+| استراتيجية لا تنقذ                    | التحديث إلى الإصدار 1.4.11+ (إصلاح مخطط Zod لاستمرارية الإعدادات)     | ---## Provider Issues |
+
+### "Language model did not provide messages"
+
+**السبب:**استنفدت حصة الموفر.
+
+**الإصلاح:**
+
+1. تحقق من تعقب الحصص في لوحة القيادة
+2. استخدم المجموعة من المستويات التجريبية
+3. قم بالبديل إلى اللغة اللاتينية الأرخص/المجانية### تحديد المعدل
+
+**السبب:**استنفدت حصة الاشتراك.
+
+**الإصلاح:**
+
+- إضافة بيع: `cc/clude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- استخدم GLM/MiniMax كنسخة بيعية بسعر رخيص### OAuth Token منتهي الصلاحية
+
+يقوم OmniRoute بكتابة الشعارات المميزة. إذا كانت هناك مشاكل:
+
+1. لوحة المعلومات → الموفر → إعادة الاتصال
+2. قم بإلغاء الحذف وإضافة اتصال الموفر---## Cloud Issues
+
+### Cloud Sync Errors
+
+1. تحقق من نقاط `BASE_URL` لمثيلك قيد التشغيل (على سبيل المثال، `http://localhost:20128`)
+2. تحقق من نقاط `CLOUD_URL` إلى نقطة نهاية السحابة الخاصة بك (على سبيل المثال، `https://omniroute.dev`)
+3. حافظ على قيم `NEXT_PUBLIC_*` مع قيم من جانب العمال### Cloud `stream=false` Returns 500
+
+**العلامة:**`الرمز المميز 'd'...' غير متوقع في نقطة نهاية السحابة للمكالمات غير المتدفقة.
+
+**السبب:**يقوم المنبع بإرجاع حمولة SSE أثناء العميل JSON.
+
+**الحل البديل:**استخدم `stream=true` للمكالمات السحابية المباشرة. قم بتضمين SSE المحلي → JSON الاحتياطي.### السحابة تقول أنها متصلة ولكن "مفتاح API غير صالح"
+
+1. أنشئ مفتاحًا جديدًا من لوحة التحكم المحلية (`/api/keys`)
+2. قم بتشغيل البروتوكولات السحابية: قم بتمكين السحابة → النوبات الآن
+3. لا يزال بإمكانها المفاتيح القديمة/غير المتزامنة إرجاع "401" على السحابة---## Docker Issues
+
+### CLI Tool Shows Not Installed
+
+1. تحقق من استهلاك وقت التشغيل: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. بالنسبة لوضع الهاتف المحمول: استخدم الصورة الهدف `runner-cli` (CLIs المجمعة)
+3. بالنسبة لصلاحية التثبيت المحلية: قم بـ `CLI_EXTRA_PATHS` وتثبيت دليل المضيفة للقراءة فقط
+4. إذا كان "تم التثبيت = صحيح" و"قابل للتشغيل = خطأ": تم العثور على الملف الثنائي ولكن فشل التحقق من الصحة### Quick Runtime Validation```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}'
+
+````
+
+---
+
+## Cost Issues
+
+### High Costs
+
+1. التحقق من إحصائيات استخدام لوحة المعلومات →
+2. قم باستبدال النموذج الأساسي بـ GLM/MiniMax
+3. استخدم طلب التقديم (Gemini CLI، Qoder) للمهام غير المرغوب فيه
+4. قم بإنشاء اقتصاديات التكلفة لكل مفتاح برمجة التطبيقات: لوحة المعلومات ← مفاتيح برمجة التطبيقات ← الميزانية---## Debugging
+
+### Enable Request Logs
+
+قم بزيارة `ENABLE_REQUEST_LOGS=true` في ملف `.env` الخاص بك. تسجيل سجلات ضمن دليل "السجلات/".### التحقق من صحة المزود```bash
+# Health dashboard
+http://localhost:20128/dashboard/health
+
+# API health check
+curl http://localhost:20128/api/monitoring/health
+````
+
+### Runtime Storage
+
+- الحالة الرئيسية: `${DATA_DIR}/storage.sqlite` (الموفرون، المجموعات، الأسماء المستعارة، المفاتيح، الإعدادات)
+  -استخدام: جداول SQLite في `storage.sqlite` (`usage_history`، `call_logs`، `proxy_logs`) + اختياري `${DATA_DIR}/log.txt` و`${DATA_DIR}/call_logs/`
+- أرشيف الطلب: `<repo>/logs/...` (عندما يكون `ENABLE_REQUEST_LOGS=true`)---## Circuit Breaker Issues
+
+### Provider stuck in OPEN state
+
+عندما يكون حظر دائرة الموفر مفتوحًا، يتم حظره حتى نهاية فترة التهدئة.
+
+**الإصلاح:**
+
+1. انتقل إلى**لوحة التحكم ← الإعدادات ← طيران**
+2. التحقق من بطاقة القاطع الكهربائي الخاصة بالمزود المتأثر
+3. انقر فوق**إعادة تعيين الكل**لمسح جميع القواطع، أو انتظر حتى انتهاء فترة التهدئة
+4. التحقق من أن الموفر فعلياً قبل العودة### مقدم الخدمة يستمر في قطع قاطع الدائرة الكهربائية
+
+إذا وصلت الخدمة بشكل عام في الحالة المفتوحة:
+
+1. تحقق من**لوحة التحكم ← الصحة ← صحة مقدم الخدمة**نمط المعرفة تبني
+2. انتقل إلى**الإعدادات → اختلاف → ملفات تعريف الموفر**وكم حتى حد ما
+3. تحقق مما إذا كان الموفر قد قام بتغيير حدود واجهة برمجة التطبيقات (API) أو طلب إعادة المصادقة
+4. قم بمراجعة القياس عن بعد لزمن التعرض - قد يتسبب في حدوث التأثيرات الناتجة في سبب واحد بسبب انتهاء المهلة---## Audio Transcription Issues
+
+### "Unsupported model" error
+
+- تأكد من أنك تستخدم القواعد الصحيحة: `deepgram/nova-3` أو `assemblyai/best`
+- تحقق من أن الموفر متصل في**لوحة التحكم ← الموفرون**### يعود النسخ فارغًا أو فاشلًا
+
+- التحقق من تنسيقات الصوت المدعومة: `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`
+- التحقق من أن حجم الملف يقع ضمن حدود الموفر (عادةً أقل من 25 ميجابايت)
+- التحقق من صلاحية مفتاح API الخاص بالموفر في البطاقة المزودة---## Translator Debugging
+
+استخدم**لوحة المعلومات → المترجم**لتصحيح المناسب لرغبتك:
+
+| الوضع              | متى تستخدم                                                                     |
+| ------------------ | ------------------------------------------------------------------------------ | -------------------------- |
+| **ساحة اللعب**     | قارن ملفات الإدخال/الإخراج جنباً إلى جنب — لا لصق طلباً فاشلاً لترى كيف ترجمته |
+| **اختبار الدردشة** | أرسل الرسائل مباشرة وافحص فاعلية الطلب/الاستجابة الكاملة بما في ذلك الرؤوس     |
+| **الاختبار**       | قم بإنهاء الفقرات المجمعة عبر مجموعات محددة على الترجمات المعطلة               |
+| **مراقبة حية**     | شاهد تدفق الطلبات في التنسيق المطلوب على الترجمة المتقطعة                      | ### مشكلات التنسيق الشائعة |
+
+-**لا تضع علامات التفكير**— تحقق مما إذا كان الموفر المستهدف مقبولاً يمكن توقعه -**استدعاءات مساعدة**— قد توفر بعض الترجمات بشكل فعال لحذف الأشخاص غير المساعدين؛ تحقق في وضع الملعب -**مطالبة النظام مفقودة**— نظام Claude وGemini مع المطالبات المختلفة؛ التحقق من إخراج الترجمة -**ترجع سلسلة SDK أولية أخرى من**- تم إصلاح ذلك في الإصدار 1.1.0: تقوم أداة التأثير الفوري الآن وأنواعها غير الممتازة (`x_groq`، و`usage_breakdown`، وما إلى ذلك) التي فشلت في التحقق من صحة OpenAI SDK Pydantic -**GLM/ERNIE يرفض دور `النظام`**- تم إصلاحه في الإصدار 1.1.0: يقوم بـ«تطبيع الدور التنفيذي برسائل مدمجة في النظام في رسائل المستخدم للنماذج غير المتوافقة» -**لم يتم التعرف على دور "المطور"**- تم إصلاحه في الإصدار 1.1.0: تم تحويله تلقائياً إلى "نظام" لتقديم الخدمات غير التابعة لـ OpenAI -**`json_schema` لا يعمل مع Gemini**— تم إصلاحه في الإصدار 1.1.0: تم الآن تحويل `response_format` إلى `responseMimeType` + `responseSchema` الخاص بـ Gemini---## Resilience Settings
+
+### Auto rate-limit not triggering
+
+- يُطبق حتى يتم التعديل تلقائيًا فقط على لوحة مفاتيح برمجة التطبيقات (وليس OAuth/الاشتراك)
+- تحقق من أن**الإعدادات → ← ملفات تعريف الموفر**تم وأيضا تعديلها بشكل تلقائي
+- تحقق مما إذا كان الموفر يعرض رموز الحالة "429" أو الذاكرة "إعادة المحاولة بعد".### ضبط التراجع الأسي
+
+تدعم ملفات تعريف الموفر هذه الإعدادات:
+
+-**التأخير الأساسي**— وقت الانتظار الأول بعد الأول (الافتراضي: 1 ثانية) -**الحد الأقصى للتأخير**— الحد الأقصى لوقت الانتظار (الافتراضي: 30 ثانية) -**المضاعف**— كمية الزيادة الشاملة لكل فشل متتالي (الافتراضي: 2x)### قطيع مضاد الرعد
+
+عندما تصل العديد من الطلبات المتزامنة إلى وفرة السعر، يستخدم تقنية OmniRoute تقنية Mutex + تحديد موعد مباشر لتنزيل الطلبات مباشرة من أجل توقف الحالات المتتالية. وهذا تلقائي لموفري مفاتيح API.---## Optional RAG / LLM failure taxonomy (16 problems)
+
+يقوم بعض مستخدمي OmniRoute بالتحرك أمام RAG أو مكدسات الوكيل. في هذه الإعدادات، من الشائع رؤية نمط غريب: يبدو OmniRoute سليمًا (مقدمو خدمة في وضع جيد، وإصدار الأحكام الشخصية على ما بعد، ولا توجد تنبيهات بخلاف حدود القضاء) ولكن الإجابة لا تزال لا تزال صحيحة.
+
+ومن ثم، يأتي هذا الذي يأتي من خط الأنابيب النهائي RAG، وليس من نفسه.
+
+إذا كنت تريد مفردات الحصول على وصف لتلك الإخفاقات، فيمكنك استخدام WFGY IssueMap، وهو مصدر ترخيص MIT الخارجي يحدد ستة عشرة نمطًاًا لفشل RAG / LLM. على مستوى عال يغطي:
+
+- الانجراف استرجاع وحدود السياقة المكسورة
+- الفهارس الفارغة أو القديمة ومخازن المتجهات
+- التضمين مقابل عدم التطابق الدلالي
+- رخص السياقة ورافعة السياقة
+- مجموعة واسعة من الإجابات الاستخدام في التجارة الحرة
+- خلل في النص بين النص والوكيل
+- ذاكرة متعددة للعامل والمؤثرات
+- مشاكل النشر والتمهيد
+
+فكرة بسيطة:
+
+1. عندما تقوم بالتحقق من خلل في حسابك، قم بالقاطع:
+   - مهمة المستخدم وطلبه
+   - مجموعة الطريق أو المورد في OmniRoute
+   - أي مؤتمر RAG في المراحل النهائية (المستندات المستردة، وأدوات الأدوات، وما إلى ذلك)
+2. قم بتخطيط الحادث لواحد أو من أرقام WFGY IssueMap (`رقم 1`...`رقم 16`).
+3. قم بتخزين الرقم في لوحة المعلومات الخاصة بك، أو دليل التشغيل، أو أداة التعقب بجوار سجلات OmniRoute.
+4. استخدم صفحة WFGY لتقرر ما إذا كنت تريد تغيير مكدس RAG أو المسترد أو استراتيجية التوجيه.
+
+النص الكامل والوصفات الملموسة موجودة هنا (ترخيص معهد ماساتشوستس فارس، النص فقط):
+
+[الملف التمهيدي لخريطة مشاكل WFGY](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
+
+ستتجاهل هذا القسم إذا لم تسمح لـ RAG أو خطوط الأنابيب الخارجية خلف OmniRoute.---## Still Stuck?
+
+-**مشكلات GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -**الهندسة الداخلية**: راجع [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) للحصول على التفاصيل -**مرجع واجهة برمجة التطبيقات**: راجع [`docs/API_REFERENCE.md`](API_REFERENCE.md) -**لوحة معلومات الصحة**: التحقق من**معلومات اللوحة ← صحة**معرفة النظام في الوقت الفعلي -**المترجم**: استخدم**لوحة المعلومات ← المترجم**ل التصحيح المناسب لك

docs/i18n/ar/docs/USER_GUIDE.md

@@ -0,0 +1,824 @@
+# User Guide (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/USER_GUIDE.md) · 🇪🇸 [es](../../es/docs/USER_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/USER_GUIDE.md) · 🇩🇪 [de](../../de/docs/USER_GUIDE.md) · 🇮🇹 [it](../../it/docs/USER_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/USER_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/USER_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/USER_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/USER_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/USER_GUIDE.md) · 🇮🇳 [in](../../in/docs/USER_GUIDE.md) · 🇹🇭 [th](../../th/docs/USER_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/USER_GUIDE.md) · 🇮🇩 [id](../../id/docs/USER_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/USER_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/USER_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/USER_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/USER_GUIDE.md) · 🇳🇴 [no](../../no/docs/USER_GUIDE.md) · 🇩🇰 [da](../../da/docs/USER_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/USER_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/USER_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/USER_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/USER_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/USER_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/USER_GUIDE.md) · 🇮🇱 [he](../../he/docs/USER_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/USER_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/USER_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/USER_GUIDE.md)
+
+---
+
+الدليل الكامل لتكوين مقدمي الخدمات، وتشمل المجموعات، ودمج أدوات CLI، ونشر OmniRoute.---## Table of Contents
+
+- [نظرة سريعة على التسعير](#- التسعير في لمحة سريعة)
+- [حالات الاستخدام](#-حالات الاستخدام)
+- [إعداد الموفر](#-إعداد الموفر)
+- [تكامل CLI](#-cli-integration)
+- [النشر](#-النشر)
+- [النماذج التجريبية](#-النماذج التجريبية)
+- [الميزات المتقدمة](#-الميزات المتقدمة)---## 💰 Pricing at a Glance
+
+| ايرلندية                           | مقدم                         | التكلفة                | إعادة ضبط الحصص         | الكل لـ                               |
+| ---------------------------------- | ---------------------------- | ---------------------- | ----------------------- | ------------------------------------- |
+| **💳الإشتراك**                     | كلود كود (برو)               | 20 شهريًا              | 5 ساعات + أسبوعي        | ❤ت بالفعل                             |
+|                                    | الدستور الغذائي (زائد / برو) | 20-200 دولار شهريًا    | 5 ساعات + أسبوعي        | مستخدم OpenAI                         |
+|                                    | الجوزاء CLI                  | **مجاني**              | 180 ألف/شهر + 1 ألف/يوم | الجميع!                               |
+|                                    | جيثب مساعد الطيار            | 10-19 شهريًا           | شهري                    | مستخدمين جيثب                         |
+| **🔑 مفتاح واجهة برمجة التطبيقات** | ديب سيك                      | الدفع لكل استخدام      | لا شيء                  | الاستدلال الرخيص                      |
+|                                    | جروك                         | الدفع لكل استخدام      | لا شيء                  | الاستدلال فائق السرعة                 |
+|                                    | xAI (جروك)                   | الدفع لكل استخدام      | لا شيء                  | جروك 4 منطق                           |
+|                                    | ميسترال                      | الدفع لكل استخدام      | لا شيء                  | التطورات التي يكملها الاتحاد الأوروبي |
+|                                    | الحيرة                       | الدفع لكل استخدام      | لا شيء                  | البحث المعزز                          |
+|                                    | منظمة العفو الدولية          | الدفع لكل استخدام      | لا شيء                  | نماذج مفتوحة المصدر                   |
+|                                    | منظمة العفو الدولية للعبة    | الدفع لكل استخدام      | لا شيء                  | صور سريعة موتورز                      |
+|                                    | الشيخ                        | الدفع لكل استخدام      | لا شيء                  | السرعة على نطاق الراقة                |
+|                                    | كوهير                        | الدفع لكل استخدام      | لا شيء                  | الأمر R+ RAG                          |
+|                                    | نفيديا نيم                   | الدفع لكل استخدام      | لا شيء                  | الأشياء                               |
+| **💰 رخيص**                        | جي إل إم-4.7                 | 0.6 دولار/1 مليون      | يوميا 10 صباحا          | نسخة للميزانية                        |
+|                                    | ميني ماكس M2.1               | 0.2 دولار/1 مليون      | التداول لمدة 5 ساعات    | الخيار الأرخص                         |
+|                                    | كيمي ك2                      | 9 دولارات شهريًا مسطحة | 10 مليون رمز/شهر        | حساب التكلفة                          |
+| **🆓مجانًا**                       | قدير                         | $0                     | غير محدود               | 8 نماذج مجانية                        |
+|                                    | كوين                         | $0                     | غير محدود               | 3 نماذج مجانية                        |
+|                                    | كيرو                         | $0                     | غير محدود               | كلود مجاني                            |
+
+**💡 نصيحه العامه:**ابدأ مع Gemini CLI (180 ألف دولار شهريًا) + مجموعة Qoder (مجانية غير محدودة) = تكلفة 0 دولار!---## 🎯 Use Cases
+
+### Case 1: "I have Claude Pro subscription"
+
+**المشكلة:**تنتهي صلاحية الحصة غير المستخدمة، وتحد من المعدل أثناء عملية الترميز```
+التحرير والسرد: "تعظيم كلود"
+
+1. cc/clude-opus-4-6 (استخدم الاشتراك بالكامل)
+2. glm/glm-4.7 (نسخة احتياطية رخيصة عند انتهاء الحصة)
+3. if/kimi-k2-thinking (الاحتياطي المجاني في حالات الطوارئ)
+
+التكلفة الشهرية: 20 دولارًا (اشتراك) + ~ 5 دولارات (احتياطي) = إجمالي 25 دولارًا
+مقابل 20 دولارًا + حدود الوصول = الإحباط```
+
+### Case 2: "I want zero cost"
+
+**المشكلة:**لا أستطيع تحمل تكلفة الاشتراكات، وتحتاج إلى ترميز يعتمد على الذكاء الاصطناعي```
+Combo: "free-forever"
+
+1. gc/gemini-3-flash (180K free/month)
+2. if/kimi-k2-thinking (unlimited free)
+3. qw/qwen3-coder-plus (unlimited free)
+
+Monthly cost: $0
+Quality: Production-ready models
+
+````
+
+### Case 3: "I need 24/7 coding, no interruptions"
+
+**المشكلة:**المواعيد النهائية، اضطرت إلى التوقف عن العمل```
+التحرير والسرد: "دائما على"
+  1.cc/كلود-opus-4-6 (أفضل جودة)
+  2.cx/gpt-5.2-codex (الاشتراك الثاني)
+  3. glm/glm-4.7 (رخيص، يُعاد ضبطه يوميًا)
+  4. minimax/MiniMax-M2.1 (الأرخص، إعادة ضبط لمدة 5 ساعات)
+  5. if/kimi-k2-thinking (مجاني غير محدود)
+
+النتيجة: 5 طبقات احتياطية = صفر توقف
+التكلفة الشهرية: 20-200 دولار (اشتراكات) + 10-20 دولار (احتياطي)```
+
+### Case 4: "I want FREE AI in OpenClaw"
+
+**المشكلة:**تحتاج إلى مساعد الذكاء الاصطناعي في تطبيقات المراسلة، مجانًا تمامًا```
+Combo: "openclaw-free"
+  1. if/glm-4.7                (unlimited free)
+  2. if/minimax-m2.1           (unlimited free)
+  3. if/kimi-k2-thinking       (unlimited free)
+
+Monthly cost: $0
+Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+````
+
+---
+
+## 📖 Provider Setup
+
+### 🔐 Subscription Providers
+
+#### Claude Code (Pro/Max)
+
+```bash
+Dashboard → Providers → Connect Claude Code
+→ OAuth login → Auto token refresh
+→ 5-hour + weekly quota tracking
+
+Models:
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**نصيحة الرأس:**استخدم Opus للمهام المعقدة، وSonnet للسرعة. OmniRoute يتتبع الحصة لكل نموذج!#### OpenAI Codex (Plus/Pro)```bash
+Dashboard → Providers → Connect Codex
+→ OAuth login (port 1455)
+→ 5-hour + weekly reset
+
+Models:
+cx/gpt-5.2-codex
+cx/gpt-5.1-codex-max
+
+````
+
+#### Gemini CLI (FREE 180K/month!)
+
+```bash
+Dashboard → Providers → Connect Gemini CLI
+→ Google OAuth
+→ 180K completions/month + 1K/day
+
+Models:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+````
+
+**أفضل قيمة:**طبقة مجانية كبيرة! استخدم هذا من قبل حتى لا يتطلب الأمر.#### GitHub 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.1-pro-preview
+
+````
+
+### 💰 Cheap Providers
+
+#### GLM-4.7 (Daily reset, $0.6/1M)
+
+1. قم بالتسجيل: [Zhipu AI](https://open.bigmodel.cn/)
+2. احصل على مفتاح API من خطة الترميز
+3. لوحة المعلومات → إضافة واجهة برمجة التطبيقات الرئيسية: الموفر: `glm`، واجهة برمجة التطبيقات الرئيسية: `your-key`
+
+**الاستخدام:**`glm/glm-4.7` —**نصيحة الرئيسة:**توفر خطة للأهداف 3× لتغطية 1/7! إعادة ضبط الساعة اليومية 10:00 صباحًا.#### MiniMax M2.1 (5hset, $0.20/1M)
+
+1. قم بالتسجيل: [MiniMax](https://www.minimax.io/)
+2. الحصول على مفتاح API → لوحة المعلومات → إضافة مفتاح API
+
+**الاستخدام:**`minimax/MiniMax-M2.1` —**نصيحة الرأس:**الخيار الأرخص للسياق الطويل (مليون رمز)!#### Kimi K2 ($9/شهر ثابت)
+
+1. اشتراك: [Moonshot AI](https://platform.moonshot.ai/)
+2. الحصول على مفتاح API → لوحة المعلومات → إضافة مفتاح API
+
+**الاستخدام:**`kimi/kimi-latest` —**نصيحة شاملة:**سعر ثابت دفاع 9 دولارات شهريًا مقابل 10 ملايين رمز مميز = 0.90 دولار أمريكي/التكلفة يريد لمليون واحد!### 🆓 مقدمو الخدمات مجانًا#### Qoder (8 FREE models)
+
+```bash
+Dashboard → Connect Qoder → OAuth login → Unlimited usage
+
+Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1
+````
+
+#### Qwen (3 FREE models)
+
+```bash
+Dashboard → Connect Qwen → Device code auth → Unlimited usage
+
+Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
+```
+
+#### Kiro (Claude FREE)
+
+```bash
+Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
+
+Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
+```
+
+---
+
+## 🎨 Combos
+
+### Example 1: Maximize Subscription → Cheap Backup
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-6 (Subscription primary)
+  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
+  3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
+
+Use in CLI: premium-coding
+```
+
+### Example 2: Free-Only (Zero Cost)
+
+```
+Name: free-combo
+Models:
+  1. gc/gemini-3-flash-preview (180K free/month)
+  2. if/kimi-k2-thinking (unlimited)
+  3. qw/qwen3-coder-plus (unlimited)
+
+Cost: $0 forever!
+```
+
+---
+
+## 🔧 CLI Integration
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from omniroute dashboard]
+  Model: cc/claude-opus-4-6
+```
+
+### Claude Code
+
+تحرير `~/.claude/config.json`:`json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "مفتاح واجهة برمجة التطبيقات الخاص بك"
+}`
+
+### Codex CLI
+
+````bash
+تصدير OPENAI_BASE_URL = "http://localhost:20128"
+تصدير OPENAI_API_KEY = "مفتاح واجهة برمجة التطبيقات الخاص بك"
+المخطوطة "المطالبة الخاصة بك"```
+
+### OpenClaw
+
+تحرير `~/.openclaw/openclaw.json`:```json
+{
+  "agents": {
+    "defaults": {
+      "model": { "primary": "omniroute/if/glm-4.7" }
+    }
+  },
+  "models": {
+    "providers": {
+      "omniroute": {
+        "baseUrl": "http://localhost:20128/v1",
+        "apiKey": "your-omniroute-api-key",
+        "api": "openai-completions",
+        "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+      }
+    }
+  }
+}
+````
+
+**أو استخدام معلومات اللوحة:**أدوات CLI → OpenClaw → تفعيل التشغيل### Cline / متابعة / RooCode```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-6
+
+````
+
+---
+
+## النشر
+
+### Global npm install (Recommended)
+
+```bash
+npm install -g omniroute
+
+# Create config directory
+mkdir -p ~/.omniroute
+
+# Create .env file (see .env.example)
+cp .env.example ~/.omniroute/.env
+
+# Start server
+omniroute
+# Or with custom port:
+omniroute --port 3000
+````
+
+يقوم سطر التعديل بتحميل `.env` من `~/.omniroute/.env` أو `./.env`.### VPS Deployment```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
+
+````
+
+### PM2 Deployment (Low Memory)
+
+بالنسبة لمكان فقدان الوصول العشوائي المحدودة، استخدم خيار الذاكرة:``bash
+# بحد 512 ميجابايت (افتراضي)
+PM2 ابدأ npm - اسم المسار الشامل - ابدأ
+
+# أو مع حد الذاكرة المخصصة
+OMNIROUTE_MEMORY_MB=512 مساءً2 ابدأ npm --اسم المسار الشامل -- ابدأ
+
+# أو باستخدام النظام البيئي.config.js
+PM2 ابدأ تشغيل النظام البيئي.config.js```
+
+قم بإنشاء "ecosystem.config.js":```javascript
+module.exports = {
+  apps: [
+    {
+      name: "omniroute",
+      script: "npm",
+      args: "start",
+      env: {
+        NODE_ENV: "production",
+        OMNIROUTE_MEMORY_MB: "512",
+        JWT_SECRET: "your-secret",
+        INITIAL_PASSWORD: "your-password",
+      },
+      node_args: "--max-old-space-size=512",
+      max_memory_restart: "300M",
+    },
+  ],
+};
+````
+
+### Docker
+
+```bash
+# Build image (default = runner-cli with codex/claude/droid preinstalled)
+docker build -t omniroute:cli .
+
+# Portable mode (recommended)
+docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
+```
+
+بالنسبة للوضع المدمج مع واجهة CLI، راجع قسم Docker في المستند الرئيسي.### Void Linux (xbps-src)
+
+يمكن لمستخدمي Void Linux حزم OmniRoute وتثبيته محليًا باستخدام إطار عمل مشترك متقاطع `xbps-src`. يؤدي هذا إلى رسم إنشاء Node.js المستقل جنبًا إلى جنب مع الارتباطات الأصلية المطلوبة `better-sqlite3`.
+
+<التفاصيل>
+
+<summary><b>عرض قالب xbps-src</b></summary>```bash
+# ملف القالب لـ "omniroute"
+pkgname=omniroute
+الإصدار=3.2.4
+المراجعة=1
+hostmakedepends = "nodejs python3 make"
+يعتمد = "openssl"
+short_desc="بوابة الذكاء الاصطناعي العالمية مع التوجيه الذكي لموفري LLM المتعددين"
+المشرف = "zenobit <zenobit@disroot.org>"
+ترخيص = "معهد ماساتشوستس للتكنولوجيا"
+الصفحة الرئيسية = "https://github.com/diegosouzapw/OmniRoute"
+distfiles = "https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
+المجموع الاختباري=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
+حسابات النظام = "_omniroute"
+omniroute_homedir = "/var/lib/omniroute"
+تصدير NODE_ENV = الإنتاج
+تصدير npm_config_engine_strict=false
+تصدير npm_config_loglevel=خطأ
+تصدير npm_config_fund=false
+تصدير npm_config_audit=false
+
+دو_بناء () { # تحديد قوس وحدة المعالجة المركزية المستهدف لـ Node-gyp
+\_gyp_arch المحلي
+الحالة "$XBPS_TARGET_MACHINE" في
+aarch64*) \_gyp_arch=arm64 ;;
+Armv7*|armv6*) \_gyp_arch=arm ;;
+i686*) \_gyp_arch=ia32 ;;
+\*) \_gyp_arch=x64 ;;
+إسحاق
+
+    # 1) قم بتثبيت كافة الطلبات – تخطي البرامج النصية
+    NODE_ENV=تطوير npm ci --ignore-scripts
+
+    # 2) أنشئ حزمة Next.js المستقلة
+    بناء تشغيل npm
+
+    # 3) انسخ الأصول الثابتة إلى قائمة بذاتها
+    cp -r .next/static .next/standalone/.next/static
+    [ -d عام ] && cp -r public .next/standalone/public || صحيح
+
+    # 4) تجميع الربط الأصلي لـ sqlite3 بشكل أفضل
+    local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+    (cdNode_modules/better-sqlite3 && العقدة "$_node_gyp" إعادة البناء --arch="$_gyp_arch")
+
+    # 5) ضع الرابط المترجم في الحزمة المستقلة
+    local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+    مكدير -p "$_bs3_release"
+    cpNode_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+
+    # 6) إزالة الحزم الحادة الخاصة بالقوس
+    rm -rf .next/standalone/node_modules/@img
+
+    # 7) انسخ عمليات حذف وقت التشغيل pino التي تم حذفها بواسطة التحليل الثابت لـ Next.js:
+    لـ _mod في تحذير عملية pino-abstract-transport Split2؛ افعل
+    	cp -r "node_modules/$_mod" .next/standalone/node_modules/
+    تم
+
+}
+
+دو_شيك () {
+اختبار تشغيل npm: الوحدة
+}
+
+دو_تثبيت () {
+vmkdir usr/lib/omniroute/.next
+vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+
+    # منع إزالة توجيهات تطبيق Next.js الفارغة عن طريق ربط ما بعد التثبيت
+    ل _د في \
+    	.next/standalone/.next/server/app/dashboard \
+    	.next/standalone/.next/server/app/dashboard/settings \
+    	.next/standalone/.next/server/app/dashboard/providers؛ افعل
+    	المس "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+    تمقطة > "${WRKDIR}/omniroute" <<'EOF'
+
+#!/بن/ش
+تصدير بورت = "$ {ميناء: -20128}"
+تصدير DATA_DIR = "${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
+تصدير LOG_TO_FILE = "${LOG_TO_FILE:-false}"
+مكدير -p "${DATA_DIR}"
+عقدة exec /usr/lib/omniroute/.next/standalone/server.js "$@"
+EOF
+فبن "${WRKDIR}/omniroute"
+}
+
+بوست_تثبيت () {
+ترخيص vlicense
+}```
+
+</details>
+
+### Environment Variables
+
+| متغير                                   | الافتراضي                                            | الوصف                                                                                                                         |
+| --------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `JWT_SECRET`                            | `الطريق الشامل الافتراضي السري تغيير لي`             | سر توقيع JWT (**تغيير في الإنتاج**)                                                                                           |
+| `INITIAL_PASSWORD`                      | `123456`                                             | كلمة المرور الأولى لتسجيل الدخول                                                                                              |
+| `DATA_DIR`                              | `~/.omniroute`                                       | دليل البيانات (ديسيبل، الاستخدام، السجلات)                                                                                    |
+| "ميناء"                                 | الإطار الافتراضي                                     | منفذ الخدمة ('20128` في الأمثلة)                                                                                              |
+| "اسم المضيف"                            | الإطار الافتراضي                                     | ربط المضيف (إعدادات Docker الافتراضية هي `0.0.0.0`)                                                                           |
+| `NODE_ENV`                              | وقت التشغيل الافتراضي                                | اضبط "الإنتاج" للنشر                                                                                                          |
+| `BASE_URL`                              | `http://localhost:20128`                             | عنوان URL الأساسي الداخلي من جانب الخادم                                                                                      |
+| `CLOUD_URL`                             | `https://omniroute.dev`                              | عنوان URL الأساسي لنقطة نهاية المزامنة السحابية                                                                               |
+| `API_KEY_SECRET`                        | `نقطة النهاية-الوكيل-واجهة برمجة التطبيقات-مفتاح-سر` | سر HMAC لمفاتيح API التي تم إنشاؤها                                                                                           |
+| `REQUIRE_API_KEY`                       | `كاذبة`                                              | فرض مفتاح Bearer API على `/v1/*`                                                                                              |
+| `ALLOW_API_KEY_REVEAL`                  | `كاذبة`                                              | السماح لـ Api Manager بنسخ مفاتيح API الكاملة عند الطلب                                                                       |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70`                                                 | إيقاع التحديث من جانب الخادم لبيانات حدود الموفر المخزنة مؤقتًا؛ لا تزال أزرار تحديث واجهة المستخدم تؤدي إلى المزامنة اليدوية |
+| `DISABLE_SQLITE_AUTO_BACKUP`            | `كاذبة`                                              | تعطيل لقطات SQLite التلقائية قبل الكتابة/الاستيراد/الاستعادة؛ النسخ الاحتياطية اليدوية لا تزال تعمل                           |
+| `ENABLE_REQUEST_LOGS`                   | `كاذبة`                                              | تمكين سجلات الطلب/الاستجابة                                                                                                   |
+| `AUTH_COOKIE_SECURE`                    | `كاذبة`                                              | فرض ملف تعريف ارتباط المصادقة "الآمن" (خلف الوكيل العكسي HTTPS)                                                               |
+| `CLOUDFLARED_BIN`                       | غير محدد                                             | استخدم ملفًا ثنائيًا موجودًا `cloudflared` بدلاً من التنزيل المُدار                                                           |
+| `CLOUDFLARED_PROTOCOL`                  | `http2`                                              | النقل للأنفاق السريعة المُدارة (`http2` أو `quic` أو `auto`)                                                                  |
+| `OMNIROUTE_MEMORY_MB`                   | `512`                                                | الحد الأقصى لكومة Node.js بالميجابايت                                                                                         |
+| `PROMPT_CACHE_MAX_SIZE`                 | `50`                                                 | الحد الأقصى لإدخالات ذاكرة التخزين المؤقت السريعة                                                                             |
+| `SEMANTIC_CACHE_MAX_SIZE`               | `100`                                                | الحد الأقصى لإدخالات ذاكرة التخزين المؤقت الدلالية                                                                            | للحصول على مرجع متغير البيئة الكامل، راجع [README](../README.md).--- |
+
+## 📊 Available Models
+
+<التفاصيل>
+
+<summary><b>عرض جميع النماذج المتاحة</b></summary>
+
+**كود كلود (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`، `cc/claude-sonnet-4-5-20250929`، `cc/claude-haiku-4-5-20251001`
+
+**المخطوطة (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`، `cx/gpt-5.1-codex-max`
+
+**Gemini CLI (`gc/`)**— مجانًا: `gc/gemini-3-flash-preview`، `gc/gemini-2.5-pro`
+
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`، `gh/claude-4.5-sonnet`
+
+**GLM (`glm/`)**— 0.6 دولار/1 مليون: `glm/glm-4.7`
+
+**MiniMax (`minimax/`)**— 0.2 دولار/1 مليون: `minimax/MiniMax-M2.1`
+
+**Qoder (`if/`)**- مجانًا: `if/kimi-k2-thinking`، `if/qwen3-coder-plus`، `if/deepseek-r1`
+
+**Qwen (`qw/`)**— مجانًا: `qw/qwen3-coder-plus`، `qw/qwen3-coder-flash`
+
+**كيرو (`kr/`)**— مجانًا: `kr/clude-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`
+
+**ميسترال (`ميسترال/`)**: `ميسترال/ميسترال-كبير-2501`، `ميسترال/كودسترال-2501`
+
+**الحيرة (`pplx/`)**: `pplx/sonar-pro`، `pplx/sonar`
+
+**معًا AI (`معًا/`)**: `معًا/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+
+**المخ (`المخ/`)**: `المخ/اللاما-3.3-70ب`
+
+**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
+
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`</details>
+
+---
+
+## 🧩 Advanced Features
+
+### Custom Models
+
+أضف أي معرف نموذج إلى أي مزود دون انتظار تحديث التطبيق:```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"
+
+````
+
+أو استخدام معلومات اللوحة:**المزودون → [الموفر] → الارتباطات الارتباطية**.
+
+التعليقات:
+
+- تم إدارة موفري خدمات OpenRouter وOpenAI/Anthropic المتوافقين من**نماذج النماذج**فقط. يمكنك الإضافة اليدوية والاستيراد والنوبات بشكل تلقائي لجميع العناصر الموجودة في نفس قائمة الارتباطات المتاحة، لذلك لا يوجد قسم منفصل للنماذج المخصصة لهؤلاء الموفرين.
+- قسم**النماذج المتخصصة**مخصص للموزعين الذين لا يقومون بإدارة المنتجات المقدمة منهم، استيراد النتائج المتاحة للمصممين.### مسارات موفر مخصصة
+
+توجيه الطلبات مباشرة إلى موفر محدد مع التحقق من صحة النموذج:```bash
+نشر http://localhost:20128/v1/providers/openai/chat/completions
+مشاركة http://localhost:20128/v1/providers/openai/embeddings
+نشر http://localhost:20128/v1/providers/fireworks/images/generations```
+
+تتم إضافة بادئة الموفر تلقائيًا في حالة فقدانها. تُرجع النماذج غير المتطابقة "400".### Network Proxy Configuration
+
+```bash
+# تعيين الوكيل العالمي
+حليقة -X ضع http://localhost:20128/api/settings/proxy \
+  -d '{"global": {"type": "http"، "host": "proxy.example.com"، "port": "8080"}}'
+
+# وكيل لكل مزود
+حليقة -X ضع http://localhost:20128/api/settings/proxy \
+  -d '{"providers": {"openai": {"type": "socks5"، "host": "proxy.example.com"، "port": "1080"}}}'
+
+# اختبار الوكيل
+حليقة -X POST http://localhost:20128/api/settings/proxy/test \
+  -d '{"proxy":{"type": "socks5"، "host": "proxy.example.com"، "port": "1080"}}'```
+
+**الأسبقية:**خاص بالمفتاح ← خاص بالسرد والسرد ← خاص بالموفر ← عالمي ← البيئة.### Model Catalog API
+
+```bash
+حليقة http://localhost:20128/api/models/catalog```
+
+إرجاع النماذج المجمعة حسب الموفر مع الأنواع (`الدردشة`، و`التضمين`، و`الصورة`).### Cloud Sync
+
+- موفري المزامنة والمجموعات والإعدادات عبر الأجهزة
+- مزامنة خلفية تلقائية مع انتهاء المهلة + فشل سريع
+- تفضيل `BASE_URL`/`CLOUD_URL` من جانب الخادم في الإنتاج### Cloudflare Quick Tunnel
+
+- متوفر في**Dashboard → Endpoints**لـ Docker وعمليات النشر الأخرى المستضافة ذاتيًا
+- إنشاء عنوان URL مؤقت `https://*.trycloudflare.com` يقوم بإعادة التوجيه إلى نقطة النهاية الحالية المتوافقة مع OpenAI `/v1`
+- قم أولاً بتمكين عمليات التثبيت `cloudflared` فقط عند الحاجة؛ يتم إعادة التشغيل لاحقًا لإعادة استخدام نفس الملف الثنائي المُدار
+- لا تتم استعادة الأنفاق السريعة تلقائيًا بعد إعادة تشغيل OmniRoute أو الحاوية؛ أعد تمكينها من لوحة التحكم عند الحاجة
+- عناوين URL للأنفاق سريعة الزوال وتتغير في كل مرة تقوم فيها بإيقاف/بدء تشغيل النفق
+- الأنفاق السريعة المدارة هي النقل الافتراضي عبر HTTP/2 لتجنب تحذيرات المخزن المؤقت QUIC UDP المزعجة في الحاويات المقيدة
+- قم بتعيين `CLOUDFLARED_PROTOCOL=quic` أو `auto` إذا كنت تريد تجاوز اختيار النقل المُدار
+- قم بتعيين `CLOUDFLARED_BIN` إذا كنت تفضل استخدام الملف الثنائي `cloudflared` المثبت مسبقًا بدلاً من التنزيل المُدار### LLM Gateway Intelligence (Phase 9)
+
+-**ذاكرة التخزين المؤقت الدلالية**— ذاكرة تخزين مؤقت تلقائية غير متدفقة، درجة الحرارة = 0 استجابات (تجاوز باستخدام `X-OmniRoute-No-Cache: true`)
+-**Request Idempotency**— إلغاء تكرار الطلبات خلال 5 ثوانٍ عبر رأس `Idempotency-Key` أو رأس `X-Request-Id`
+-**تتبع التقدم**— الاشتراك في أحداث SSE `الحدث: التقدم` عبر رأس `X-OmniRoute-Progress: true`---
+
+### Translator Playground
+
+الوصول عبر**لوحة المعلومات → المترجم**. تصحيح الأخطاء وتصور كيفية قيام OmniRoute بترجمة طلبات واجهة برمجة التطبيقات (API) بين مقدمي الخدمة.
+
+| الوضع | الغرض |
+| ---------------- | -------------------------------------------------------------------------------------- |
+|**ساحة اللعب**| حدد تنسيقات المصدر/الهدف، والصق طلبًا، وشاهد المخرجات المترجمة على الفور |
+|**اختبار الدردشة**| أرسل رسائل الدردشة المباشرة من خلال الوكيل وافحص دورة الطلب/الاستجابة الكاملة |
+|**مقعد الاختبار**| قم بإجراء اختبارات مجمعة عبر مجموعات تنسيقات متعددة للتحقق من صحة الترجمة |
+|**مراقبة حية**| شاهد الترجمات في الوقت الفعلي أثناء تدفق الطلبات عبر الوكيل |
+
+**حالات الاستخدام:**
+
+- تصحيح سبب فشل مجموعة محددة من العميل/الموفر
+- التحقق من ترجمة علامات التفكير واستدعاءات الأدوات ومطالبات النظام بشكل صحيح
+- مقارنة اختلافات التنسيق بين تنسيقات OpenAI وClaude وGemini وResponsions API---
+
+### Routing Strategies
+
+قم بالتكوين عبر**لوحة المعلومات → الإعدادات → التوجيه**.
+
+| استراتيجية | الوصف |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+|**املأ أولا**| يستخدم الحسابات بترتيب الأولوية — يعالج الحساب الأساسي جميع الطلبات حتى تصبح غير متاحة |
+|**راوند روبن**| للتنقل عبر جميع الحسابات بحد ثابت قابل للتكوين (الافتراضي: 3 مكالمات لكل حساب) |
+|**P2C (قوة الاختيارين)**| يختار حسابين عشوائيين ويوجهك إلى الحساب الأكثر صحة - الأرصدة محملة بالوعي الصحي |
+|**عشوائي**| تحديد حساب عشوائيًا لكل طلب باستخدام خلط Fisher-Yates |
+|**الأقل استخدامًا**| توجيهات إلى الحساب ذو الطابع الزمني الأقدم `lastUsedAt`، مع توزيع حركة المرور بالتساوي |
+|**التكلفة الأمثل**| التوجيهات إلى الحساب ذي أقل قيمة أولوية، مع تحسين موفري الخدمة الأقل تكلفة |#### External Sticky Session Header
+
+بالنسبة لتقارب الجلسة الخارجية (على سبيل المثال، وكلاء Claude Code/Codex خلف الوكلاء العكسيين)، أرسل:```http
+X-Session-Id: your-session-key
+````
+
+يقبل OmniRoute أيضًا `x_session_id` ويعيد مفتاح الكلام الفعال في `X-OmniRoute-Session-Id`.
+
+إذا كنت تستخدم Nginx وترسل ترويسات على شكل شرطة سفلية، المجاورة بتمكين:`nginx
+underscores_in_headers على؛`
+
+#### Wildcard Model Aliases
+
+قم بإنشاء أنماط أحرف البدل لإعادة تعيين أسماء النماذج:```
+Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+
+````
+
+تدعم أحرف البدل `*` (أي حرف) و`?` (حرف واحد).#### السلاسل الاحتياطية
+
+تحديد الخطوط التقليدية العالمية التي تنطبق على جميع الطلبات:```
+السلسلة: الإنتاج الاحتياطي
+  1. سم مكعب/كلود-أوبوس-4-6
+  2.gh/gpt-5.1-codex
+  3.glm/glm-4.7```
+
+---
+
+### Resilience & Circuit Breakers
+
+قم بالتكوين عبر**لوحة المعلومات → الإعدادات → المرونة**.
+
+تطبق OmniRoute المرونة على مستوى المزود من خلال أربعة مكونات:
+
+1.**ملفات تعريف الموفر**— التكوين لكل موفر لـ:
+   - عتبة الفشل (كم عدد حالات الفشل قبل الفتح)
+   - مدة التهدئة
+   - حساسية الكشف عن حد المعدل
+   - معلمات التراجع الأسي
+
+2.**حدود المعدل القابلة للتحرير**— الإعدادات الافتراضية على مستوى النظام قابلة للتكوين في لوحة المعلومات:
+   -**الطلبات في الدقيقة (RPM)**— الحد الأقصى للطلبات في الدقيقة لكل حساب
+   -**الحد الأدنى للوقت بين الطلبات**— الحد الأدنى للفجوة بالمللي ثانية بين الطلبات
+   -**الحد الأقصى للطلبات المتزامنة**— الحد الأقصى للطلبات المتزامنة لكل حساب
+   - انقر**تحرير**للتعديل، ثم**حفظ**أو**إلغاء**. تستمر القيم عبر واجهة برمجة تطبيقات المرونة.
+
+3.**قاطع الدائرة**— يتتبع حالات الفشل لكل مزود ويفتح الدائرة تلقائيًا عند الوصول إلى الحد الأدنى:
+   -**مغلق**(صحي) — تتدفق الطلبات بشكل طبيعي
+   -**مفتوح**— تم حظر الموفر مؤقتًا بعد الفشل المتكرر
+   -**HALF_OPEN**— اختبار ما إذا كان الموفر قد استعاد عافيته
+
+4.**السياسات والمعرفات المقفلة**— تعرض حالة قاطع الدائرة والمعرفات المقفلة مع إمكانية إلغاء القفل بالقوة.
+
+5.**الاكتشاف التلقائي لحدود المعدل**— يراقب الرؤوس `429` و`إعادة المحاولة بعد` لتجنب الوصول إلى حدود معدل الموفر بشكل استباقي.
+
+**نصيحة احترافية:**استخدم زر**إعادة تعيين الكل**لمسح جميع قواطع الدائرة وفترات التهدئة عندما يتعافى المزود من انقطاع الخدمة.---
+
+### Database Export / Import
+
+إدارة النسخ الاحتياطية لقاعدة البيانات في**لوحة المعلومات → الإعدادات → النظام والتخزين**.
+
+| العمل | الوصف |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+|**تصدير قاعدة البيانات**| يقوم بتنزيل قاعدة بيانات SQLite الحالية كملف `.sqlite` |
+|**تصدير الكل (.tar.gz)**| تنزيل أرشيف نسخ احتياطي كامل بما في ذلك: قاعدة البيانات، والإعدادات، والمجموعات، واتصالات الموفر (بدون بيانات اعتماد)، وبيانات تعريف مفتاح API |
+|**استيراد قاعدة البيانات**| قم بتحميل ملف `.sqlite` ليحل محل قاعدة البيانات الحالية. يتم إنشاء نسخة احتياطية للاستيراد المسبق تلقائيًا ما لم `DISABLE_SQLITE_AUTO_BACKUP=true` |```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"
+````
+
+**التحقق من صحة الاستيراد:**التحقق من صحة الملف المستورد للتأكد من سلامته (التحقق من صحة الملف المستورد)، والجداول الأساسية (`provider_connections`، و`provider_nodes`، و`combos`، و`api_keys`)، غير (بحد أقصى 100 ميجابايت).
+
+**حالات الاستخدام:**
+
+- رحيل OmniRoute بين الأجهزة
+- إنشاء نسخة احتياطية خارجية للتعافي من الكوارث
+- مشاركة تلكات بين أعضاء الفريق (تصدير الكل → مشاركة الأرشيف)---### Settings Dashboard
+
+يتم تنظيم إعدادات الصفحات في 6 علامات مخصصة للتخصيص:
+
+| علامة التبويب        | محتويات                                                                                                                    |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| **عام**              | النظام، تحتاج إلى تخزين الأدوات، وعناصر التحكم في الميزات، وإمكانية رؤية الشريط الجانبي لكل العناصر                        |
+| **الأمن**            | إعدادات تسجيل الدخول/كلمة المرور، تسجيل الدخول إلى IP، ومصادقة واجهة برمجة التطبيقات لـ `/models`، وحظر الموفر             |
+| **التوجيه**          | استراتيجية التوجيه العالمية (6 خيارات)، والأسماء المستعارة لنماذج أحرف البدل، والطرق الاحتياطية، وافتراضيات التحرير والسرد |
+| **المرونة**          | ملفات تعريف الموفر، وحدود التصاميم الجميلة للتحرير، وحالة حدود، والسياسات والمعرفات المحجوبة                               |
+| **الذكاء الاصطناعي** | الاختيار الاختيار، والحقن القصير الشامل، وذاكرة الإحصائيات للتخزين السريع                                                  |
+| **متقدم**            | المهمة الرسمية العالمية (HTTP/SOCKS5)                                                                                      | ---### Costs & Budget Management |
+
+عبر**لوحة التحكم ← الأسعار**.
+
+| علامة التبويب | الحصاد                                                                                               |
+| ------------- | ---------------------------------------------------------------------------------------------------- | ------- |
+| **الميزانية** | قم بتغطية النطاق الأقصى لكل مفتاح API باستخدام القياسات اليومية/الأسبوعية/الشهرية وتتبع الوقت الفعلي |
+| **التسعير**   | نموذج عرض وتحرير التسجيلات الرقمية - التكلفة لكل ألف رمز التسجيل/الإخراج لكل تلفزيون                 | ```bash |
+
+# API: تحديد الميزانية
+
+حليقة -X POST http://localhost:20128/api/usage/budget \
+ -H "نوع المحتوى: application/json" \
+ -d '{"keyId": "key-123"، "الحد": 50.00، "الفترة": "شهريًا"}'
+
+# API: احصل على حالة الميزانية الحالية
+
+حليقة http://localhost:20128/api/usage/budget```
+
+**تتبع التكلفة:**يقوم كل طلب بتسجيل استخدام الرمز المميز وحساب التكلفة باستخدام جدول التسعير. عرض التفاصيل في**لوحة المعلومات → الاستخدام**حسب الموفر والطراز ومفتاح واجهة برمجة التطبيقات.---
+
+### Audio Transcription
+
+يدعم OmniRoute النسخ الصوتي عبر نقطة النهاية المتوافقة مع OpenAI:```bash
+POST /v1/audio/transcriptions
+Authorization: Bearer your-api-key
+Content-Type: multipart/form-data
+
+# Example with curl
+
+curl -X POST http://localhost:20128/v1/audio/transcriptions \
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+
+````
+
+الموفرون متاحون:**Deepgram**(`deepgram/`)،**AssemblyAI**(`assemblyai/`).
+
+تنسيقات الصوت المدعومة: `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`.---### Combo Balancing Strategies
+
+قم بتكوين مجموعة متنوعة في**لوحة المعلومات → المجموعات → إنشاء/تحرير → اختيار**.
+
+| استراتيجية | الوصف |
+| ------------------ | ------------------------------------------------------------------------ |
+|**جولة روبن**| التفاعل عبر الاتجاهات بالتتابع |
+|**الأولوية**| يحاول دائمًا النموذج الأول؛ لا يعود إلا على الخطأ |
+|**عشوائي**| اختيار نموذجًا من المجموعة لكل طلب |
+|**المولد**| تعتمد المسارات بشكل يتناسب مع الوزن المخصص لكل نموذج |
+|**الأقل استخدامًا**| توجيهات إلى النموذج الذي يحتوي على أقل عدد من الطلبات الأخيرة (يستخدم مقاييس التحرير والسرد) |
+|**التكلفة المقررة**| الطريق إلى خيارات الخيارات (يستخدم جدول التسعير) |
+
+يمكن ضبط إعدادات التحرير والسرد العام في**لوحة المعلومات → الإعدادات → التوجيه → إعدادات التحرير والسرد الافتراضي**.---### Health Dashboard
+
+عبر**لوحة التحكم → الصحة**. نظرة عامة على صحة النظام في الوقت الحقيقي مع 6 بطاقات:
+
+| بطاقة | ما يظهر |
+| --------------------- | ----------------------------------------------------------- |
+|**حالة النظام**| وقت التشغيل، الإصدار، استخدام الذاكرة، دليل البيانات |
+|**صحة المزود**| حالة فاصل كهربائي لكل الدائرة (مغلق/مفتوح/نصف مفتوح) |
+|**حدود التعديل**| لتهدئة بعض التغيير لأي حساب مع الوقت المؤقت |
+|**عمليات التأمين العضوي**| تم حظر مقدمي الخدمة مؤقتًا بواسطة شركة التأمين للتأمين |
+|**ذاكرة تخزين مؤقت للتوقيع**| إحصائيات إلغاء البيانات المكررة (المفاتيح العضوية، معدل الدخول) |
+|**قياس زمن الوصول**| p50/p95/p99 تجميع زمن الوصول لكل حدود |
+
+**نصيحة شاملة:**يتم تحديث صفحة الصحة الطازجة كل 10. استخدم بطاقة القاطع للخدمة المقدمة الذين يستفيدون.---## 🖥️ Desktop Application (Electron)
+
+يسمى OmniRoute كتطبيق سطح المكتب الأصلي لأنظمة التشغيل Windows وmacOS وLinux.### تثبيت```bash
+# From the electron directory:
+cd electron
+npm install
+
+# Development mode (connect to running Next.js dev server):
+npm run dev
+
+# Production mode (uses standalone build):
+npm start
+````
+
+### Building Installers
+
+```bash
+cd electron
+npm run build          # Current platform
+npm run build:win      # Windows (.exe NSIS)
+npm run build:mac      # macOS (.dmg universal)
+npm run build:linux    # Linux (.AppImage)
+```
+
+المنتج → ``الإلكترون/توزيع الإلكترون/`### الميزات الرئيسية
+
+| غرض                      | الوصف                                                    |
+| ------------------------ | -------------------------------------------------------- | ------------------ |
+| **جاهزة للخدم**          | وكيلات قبل بدء التشغيل (لا توجد شاشة كافية)              |
+| **علبة النظام**          | تصغير إلى المرحاض، تغيير الشراب، والخروج من قائمة الدرج  |
+| **إدارة المشاريع**       | تغيير مدير الخادم من الدرج (خادم إعادة التشغيل التلقائي) |
+| **سياسة امان المحتوى**   | ليس CSP عبر الحروف اللامكانية                            |
+| **مثيل واحد**            | يمكن تشغيل تطبيق واحد فقط في الاستخدام                   |
+| **وضع غير متصل بالشبكة** | خادم Next.js المجمع يعمل بدون إنترنت                     | ### متغيرات البيئة |
+
+| فنية                  | افتراضي | الوصف                                         |
+| --------------------- | ------- | --------------------------------------------- |
+| `OMNIROUTE_PORT`      | `20128` | منفذ الخادم                                   |
+| `OMNIROUTE_MEMORY_MB` | `512`   | الحد الأقصى لكومة Node.js (64–16384 ميجابايت) |
+
+📖 التوثيق الكامل: [`electron/README.md`](../electron/README.md)

docs/i18n/ar/docs/VM_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,365 @@
+# OmniRoute — Deployment Guide on VM with Cloudflare (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/VM_DEPLOYMENT_GUIDE.md)
+
+---
+
+الدليل الكامل لـ OmniRoute وتكوينه على VM (VPS) مع المجال المُدار عبر Cloudflare.---## Prerequisites
+
+| حرق                        | الحد                             | موصى به                          |
+| -------------------------- | -------------------------------- | -------------------------------- |
+| **وحدة المعالجة المركزية** | 1 وحدة المعالجة المركزية الرقمية | 2 وحدة المعالجة المركزية الرقمية |
+| **ذاكرة الوصول العشوائي**  | 1 جيجا                           | 2 جيجا                           |
+| **القرص**                  | 10 جيجا اس اس دي                 | 25 جيجا اس دي                    |
+| **نظام التشغيل**           | أوبونتو 22.04 LTS                | أوبونتو 24.04 LTS                |
+| **المجال**                 | مسجل في Cloudflare               | —                                |
+| **عامل ميناء**             | محرك دوكر 24+                    | عامل ميناء 27+                   |
+
+**المزودون الذين تم اختبارهم**: Akamai (Linode)، DigitalOcean، Vultr، Hetzner، AWS Lightsail.---## 1. Configure the VM
+
+### 1.1 Create the instance
+
+على موفر VPS المفضل لديك:
+
+- اختر Ubuntu 24.04 LTS
+  -تحديد الحد الأدنى للخطة (1 vCPU / 1 جيجابايت من ذاكرة الوصول العشوائي)
+- قم بتواجد كلمة مرور جذر قوية أو قم بتكوين مفتاح SSH
+- ملحوظة**عنوان IP العام**(على سبيل المثال، `203.0.113.10`)### 1.2 الاتصال عبر SSH```bash
+  ssh root@203.0.113.10
+
+````
+
+### 1.3 Update the system
+
+```bash
+apt update && apt upgrade -y
+````
+
+### 1.4 Install Docker
+
+```bash
+# Install dependencies
+apt install -y ca-certificates curl gnupg
+
+# 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
+apt update
+apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
+```
+
+### 1.5 Install nginx
+
+```bash
+apt install -y nginx
+```
+
+### 1.6 Configure Firewall (UFW)
+
+```bash
+ufw default deny incoming
+ufw default allow outgoing
+ufw allow 22/tcp    # SSH
+ufw allow 80/tcp    # HTTP (redirect)
+ufw allow 443/tcp   # HTTPS
+ufw enable
+```
+
+> **نصيحة**: للحصول على الحد الأقصى من الأمان، يجب بتقييد المنفذين 80 و443 بناوين Cloudflare IP فقط. راجع قسم [الأمان المتقدم](#الأمن المتقدم).---## 2. Install OmniRoute
+
+### 2.1 Create configuration directory
+
+```bash
+mkdir -p /opt/omniroute
+```
+
+### 2.2 Create environment variables file
+
+```bash
+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=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
+
+# === Domain (change to your domain) ===
+BASE_URL=https://llms.seudominio.com
+NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
+
+# === Cloud Sync (optional) ===
+# CLOUD_URL=https://cloud.omniroute.online
+# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online
+EOF
+```
+
+> ⚠️**هام**: أنشئ مفاتيح سرية فريدة! استخدم "openssl rand -hex 32" لكل مفتاح.### 2.3 ابدأ الحاوية```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 Verify that it is running
+
+```bash
+docker ps | grep omniroute
+docker logs omniroute --tail 20
+````
+
+يجب أن يتم تعرض: "قاعدة بيانات SQLite [DB] جاهزة" و"الاشتراك في منفذ 20128".---## 3. Configure nginx (Reverse Proxy)
+
+### 3.1 Generate SSL certificate (Cloudflare Origin)
+
+في لوحة معلومات Cloudflare:
+
+1. انتقل إلى**SSL/TLS → الخادم الأصلي**
+   2.نقر**إنشاء شهادة**
+2. استخدم الإعدادات الافتراضية (15 عامًا، \*.yourdomain.com)
+   4.انسخ**شهادة المنشأ**و**المفتاح الخاص**```bash
+   mkdir -p /etc/nginx/ssl
+
+# لصق الشهادة
+
+نانو /etc/nginx/ssl/origin.crt
+
+# الصق المفتاح الخاص
+
+نانو /etc/nginx/ssl/origin.key
+
+chmod 600 /etc/nginx/ssl/origin.key```
+
+### 3.2 Nginx Configuration
+
+````bash
+cat > /etc/nginx/sites-available/omniroute << 'NGINX'
+# الخادم الافتراضي - يمنع الوصول المباشر عبر IP
+الخادم {
+    الاستماع 80 default_server؛
+    الاستماع [::]:80 default_server؛
+    الاستماع 443 SSL default_server؛
+    استمع [::]:443 ssl default_server؛
+    ssl_certificate /etc/nginx/ssl/origin.crt;
+    ssl_certificate_key /etc/nginx/ssl/origin.key;
+    اسم الخادم _;
+    العودة 444؛
+}
+
+# OmniRoute - HTTPS
+الخادم {
+    الاستماع 443 SSL؛
+    استمع [::]:443 ssl;
+    اسم الخادم llms.yourdomain.com;  # التغيير إلى المجال الخاص بك
+
+    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؛
+
+    الموقع / {
+        proxy_pass http://127.0.0.1:20128;
+        proxy_set_header المضيف $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 $;
+
+        # دعم ويبسوكيت
+        proxy_http_version 1.1;
+        ترقية proxy_set_header $http_upgrade;
+        اتصال proxy_set_header "ترقية"؛
+
+        # SSE (الأحداث المرسلة من الخادم) - تدفق استجابات الذكاء الاصطناعي
+        proxy_buffering معطل؛
+        proxy_cache معطل؛
+        proxy_read_timeout 600s؛
+        proxy_send_timeout 600s;
+    }
+}
+
+# HTTP → إعادة توجيه HTTPS
+الخادم {
+    استمع 80؛
+    استمع [::]:80;
+    اسم الخادم llms.yourdomain.com;
+    إرجاع 301 https://$server_name$request_uri;
+}
+نجينكس```
+
+حافظ على توافق مهلات دفق الوكيل العكسي مع vars env لمهلة OmniRoute. إذا رفعت
+`FETCH_TIMEOUT_MS` / `STREAM_IDLE_TIMEOUT_MS`، ارفع `proxy_read_timeout` / `proxy_send_timeout`
+فوق نفس العتبة.### 3.3 Enable and Test
+
+```bash
+# إزالة التكوين الافتراضي
+rm -f /etc/nginx/sites-enabled/default
+
+# تمكين OmniRoute
+ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute
+
+# اختبار وإعادة تحميل
+nginx -t && systemctl إعادة تحميل nginx```
+
+---
+
+## 4. Configure Cloudflare DNS
+
+### 4.1 Add DNS record
+
+في لوحة معلومات Cloudflare → DNS:
+
+| اكتب | الاسم | المحتوى | الوكيل |
+| ---- | ------ | ---------------------- | ---------- |
+| أ | ``للم`` | `203.0.113.10` (VM IP) | ✅ توكيل |### 4.2 Configure SSL
+
+ضمن**SSL/TLS → نظرة عامة**:
+
+- الوضع:**كامل (صارم)**
+
+ضمن**SSL/TLS → شهادات الحافة**:
+
+- استخدم HTTPS دائمًا: ✅ قيد التشغيل
+- الحد الأدنى لإصدار TLS: TLS 1.2
+- إعادة كتابة HTTPS تلقائيًا: ✅ تشغيل### 4.3 Testing
+
+```bash
+حليقة -sI https://llms.seudominio.com/health
+# يجب أن يُرجع HTTP/2 200```
+
+---
+
+## 5. Operations and Maintenance
+
+### Upgrade to a new version
+
+```bash
+عامل ميناء سحب diegosouzapw/omniroute:latest
+عامل ميناء توقف omniroute && docker rm omniroute
+تشغيل عامل الإرساء -d --اسم المسار الشامل --إعادة التشغيل ما لم يتم إيقافه \
+  --env-ملف /opt/omniroute/.env \
+  -ص20128:20128\
+  -v بيانات المسار الشامل:/app/data \
+  diegosouzapw/omniroute:latest```
+
+### View logs
+
+```bash
+سجلات عامل الإرساء -f omniroute # البث في الوقت الفعلي
+سجلات عامل الإرساء في كل الاتجاهات --tail 50 # آخر 50 سطرًا```
+
+### Manual database backup
+
+```bash
+# انسخ البيانات من المجلد إلى المضيف
+docker cp omniroute:/app/data ./backup-$(date +%F)
+
+# أو ضغط الحجم بأكمله
+تشغيل عامل الميناء --rm -v omniroute-data:/data -v $(pwd):/backup \
+  جبال الألب القطران czf /backup/omniroute-data-$(date +%F).tar.gz /data```
+
+### Restore from backup
+
+```bash
+توقف عامل الإرساء في كل اتجاه
+تشغيل عامل الميناء --rm -v omniroute-data:/data -v $(pwd):/backup \
+  جبال الألب sh -c “rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /”
+عامل الإرساء يبدأ في كل اتجاه```
+
+---
+
+## 6. Advanced Security
+
+### Restrict nginx to Cloudflare IPs
+
+```bash
+cat > /etc/nginx/cloudflare-ips.conf << 'CF'
+# نطاقات Cloudflare IPv4 - يتم تحديثها بشكل دوري
+# 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;
+قوات التحالف```
+
+أضف ما يلي إلى `nginx.conf` داخل الكتلة `http {}`:```nginx
+include /etc/nginx/cloudflare-ips.conf;
+````
+
+### Install fail2ban
+
+```bash
+apt install -y fail2ban
+systemctl enable fail2ban
+systemctl start fail2ban
+
+# Check status
+fail2ban-client status sshd
+```
+
+### Block direct access to the Docker port
+
+```bash
+# 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
+
+# Persist the rules
+apt install -y iptables-persistent
+netfilter-persistent save
+```
+
+---
+
+## 7. Deploy to Cloudflare Workers (Optional)
+
+للوصول بعد عبر Cloudflare Workers (دون الكشف عن الجهاز الافتراضي مباشرة):```bash
+
+# في المستودع المحلي
+
+cd omnirouteCloud
+تثبيت npm
+تسجيل دخول رانجلر npx
+نشر رانجلر npx```
+
+راجع الوثائق الكاملة على [omnirouteCloud/README.md](../omnirouteCloud/README.md).---
+
+## Port Summary
+
+| ميناء | الخدمة        | الوصول                        |
+| ----- | ------------- | ----------------------------- |
+| 22    | سش            | عام (مع Fail2ban)             |
+| 80    | إنجينكس HTTP  | إعادة التوجيه → HTTPS         |
+| 443   | إنجينكس HTTPS | عبر وكيل Cloudflare           |
+| 20128 | أومنيروتي     | المضيف المحلي فقط (عبر nginx) |

docs/i18n/ar/src/lib/a2a/README.md

@@ -0,0 +1,703 @@
+# OmniRoute A2A Server (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../../../src/lib/a2a/README.md) · 🇪🇸 [es](../../../../es/src/lib/a2a/README.md) · 🇫🇷 [fr](../../../../fr/src/lib/a2a/README.md) · 🇩🇪 [de](../../../../de/src/lib/a2a/README.md) · 🇮🇹 [it](../../../../it/src/lib/a2a/README.md) · 🇷🇺 [ru](../../../../ru/src/lib/a2a/README.md) · 🇨🇳 [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) · 🇯🇵 [ja](../../../../ja/src/lib/a2a/README.md) · 🇰🇷 [ko](../../../../ko/src/lib/a2a/README.md) · 🇸🇦 [ar](../../../../ar/src/lib/a2a/README.md) · 🇮🇳 [hi](../../../../hi/src/lib/a2a/README.md) · 🇮🇳 [in](../../../../in/src/lib/a2a/README.md) · 🇹🇭 [th](../../../../th/src/lib/a2a/README.md) · 🇻🇳 [vi](../../../../vi/src/lib/a2a/README.md) · 🇮🇩 [id](../../../../id/src/lib/a2a/README.md) · 🇲🇾 [ms](../../../../ms/src/lib/a2a/README.md) · 🇳🇱 [nl](../../../../nl/src/lib/a2a/README.md) · 🇵🇱 [pl](../../../../pl/src/lib/a2a/README.md) · 🇸🇪 [sv](../../../../sv/src/lib/a2a/README.md) · 🇳🇴 [no](../../../../no/src/lib/a2a/README.md) · 🇩🇰 [da](../../../../da/src/lib/a2a/README.md) · 🇫🇮 [fi](../../../../fi/src/lib/a2a/README.md) · 🇵🇹 [pt](../../../../pt/src/lib/a2a/README.md) · 🇷🇴 [ro](../../../../ro/src/lib/a2a/README.md) · 🇭🇺 [hu](../../../../hu/src/lib/a2a/README.md) · 🇧🇬 [bg](../../../../bg/src/lib/a2a/README.md) · 🇸🇰 [sk](../../../../sk/src/lib/a2a/README.md) · 🇺🇦 [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) · 🇮🇱 [he](../../../../he/src/lib/a2a/README.md) · 🇵🇭 [phi](../../../../phi/src/lib/a2a/README.md) · 🇧🇷 [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) · 🇨🇿 [cs](../../../../cs/src/lib/a2a/README.md) · 🇹🇷 [tr](../../../../tr/src/lib/a2a/README.md)
+
+---
+
+> **Agent-to-Agent Protocol v0.3**— يتزايد أي وكيل AI من استخدام OmniRoute كوكيل توجيه ذكي عبر JSON-RPC 2.0.
+
+يعرض مضيف A2A OmniRoute**وكيلًا من الدرجة الأولى**يمكن لوكلاء الاكتشافات الأخرى وطلب الاتصال به باستخدام [بروتوكول A2A](https://google.github.io/A2A/).---## الهندسة
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                    Orchestrator Agent                             │
+│        (LangChain, CrewAI, AutoGen, Custom Agent)                │
+└──────────────────────┬───────────────────────────────────────────┘
+                       │  1. GET /.well-known/agent.json  (discover)
+                       │  2. POST /a2a  (JSON-RPC 2.0)
+                       ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                     OmniRoute A2A Server                         │
+│  ┌────────────────┐  ┌────────────────┐  ┌───────────────────┐  │
+│  │  Task Manager  │  │  Skill Engine  │  │  SSE Streaming    │  │
+│  │  (lifecycle)   │──│  (registry)    │──│  (real-time)      │  │
+│  └────────────────┘  └────────┬───────┘  └───────────────────┘  │
+│                               │                                  │
+│  Skills:                      │                                  │
+│    ├─ smart-routing ──────────┤  ┌────────────────────────────┐  │
+│    └─ quota-management ───────┘  │  Routing Decision Logger   │  │
+│                                  └────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────┘
+                       │
+                       ▼  OmniRoute Gateway (internal)
+              /v1/chat/completions, /api/combos, /api/usage/quota
+```
+
+---
+
+## بداية سريعة
+
+### Agent Discovery
+
+يعرض كل وكيل متوافق مع A2A**بطاقة الوكيل**على `/.well-known/agent.json`:`bash
+حليقة http://localhost:20128/.well-known/agent.json`
+
+**إجابة:**```json
+{
+"name": "OmniRoute",
+"description": "Intelligent AI gateway with auto-routing across 50+ providers",
+"url": "http://localhost:20128/a2a",
+"version": "1.8.1",
+"capabilities": {
+"streaming": true,
+"pushNotifications": false
+},
+"skills": [
+{
+"id": "smart-routing",
+"name": "Smart Routing",
+"description": "Routes prompts through OmniRoute intelligent pipeline",
+"tags": ["routing", "llm", "multi-provider", "cost-optimization"],
+"examples": [
+"Write a hello world in Python",
+"Explain quantum computing using the cheapest provider"
+]
+},
+{
+"id": "quota-management",
+"name": "Quota Management",
+"description": "Natural-language queries about provider quotas",
+"tags": ["quota", "analytics", "cost"],
+"examples": [
+"Which provider has the most quota remaining?",
+"Suggest a free combo for coding"
+]
+}
+],
+"authentication": {
+"schemes": ["bearer"],
+"apiKeyHeader": "Authorization"
+}
+}
+
+````
+
+---
+
+## JSON-RPC 2.0 Methods
+
+### `message/send` — Synchronous Execution
+
+أرسل رسالة إلى إحدى المهارات واحصل على الرد الكامل.```bash
+حليقة -X POST http://localhost:20128/a2a \
+  -H "نوع المحتوى: application/json" \
+  -H "التفويض: حامل YOUR_KEY" \
+  -د '{
+    "jsonrpc": "2.0",
+    "المعرف": "1"،
+    "الطريقة": "رسالة/إرسال"،
+    "المعلمات": {
+      "المهارة": "التوجيه الذكي"،
+      "messages": [{"role": "user", "content": "اكتب عالم بايثون المرحب"}],
+      "بيانات التعريف": {"model": "auto"، "combo": "الترميز السريع"}
+    }
+  }'```
+
+**إجابة:**```json
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "result": {
+    "task": { "id": "a1b2c3d4-...", "state": "completed" },
+    "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }],
+    "metadata": {
+      "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)",
+      "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" },
+      "resilience_trace": [
+        { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." }
+      ],
+      "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" }
+    }
+  }
+}
+````
+
+### `message/stream` — SSE Streaming
+
+نفس `الرسالة/الإرسال` ولكنها تُرجع الأحداث المرسلة من العميل للبث في الوقت الحقيقي.`bash
+حليقة -N -X POST http://localhost:20128/a2a \
+  -H "نوع المحتوى: application/json" \
+  -H "التفويض: حامل YOUR_KEY" \
+  -د '{
+    "jsonrpc": "2.0",
+    "المعرف": "1"،
+    "الطريقة": "رسالة/دفق"،
+    "المعلمات": {
+      "المهارة": "التوجيه الذكي"،
+      "messages": [{"role": "user", "content": "شرح الحوسبة الكمومية"}]
+    }
+  }'`
+
+**أحداث SSE:**```
+data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}}
+
+: heartbeat 2026-03-04T21:00:00Z
+
+data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}}
+
+````
+
+### `tasks/get` — Query Task Status
+
+```bash
+curl -X POST http://localhost:20128/a2a \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_KEY" \
+  -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}'
+````
+
+### `tasks/cancel` — Cancel a Running Task
+
+```bash
+curl -X POST http://localhost:20128/a2a \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_KEY" \
+  -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}'
+```
+
+---
+
+## Skills Reference
+
+### `smart-routing`
+
+تطالب المسارات عبر خط الأنابيب OmniRoute الذكي مع إمكانية المراقبة الكاملة.
+
+**المعلمات (في `البيانات الوصفية`):**
+
+| المعلمة          | اكتب      | افتراضي            | الوصف                                                                         |
+| ---------------- | --------- | ------------------ | ----------------------------------------------------------------------------- |
+| `نموذج`          | "السلسلة" | `"تلقائي"`         | النموذج المستهدف (على سبيل المثال، `clude-sonnet-4`، `gpt-4o`، `auto`)        |
+| `التحرير والسرد` | "السلسلة" | التحرير والسرد لكم | التحرير والسرد للتوجيه من خلال                                                |
+| `الميزانية`      | `الرقم`   | لا شيء             | الحد الأقصى للتكلفة بالدولار الأمريكي هذا الطلب                               |
+| `دور`            | "السلسلة" | لا شيء             | تلميح مهم: `التميز`، `المراجعة`، `التخطيط`، `التحليل`، `تصحيح سبب`، `التوثيق` |
+
+**المرتجعات:**
+
+|                                | الوصف                                                                    |
+| ------------------------------ | ------------------------------------------------------------------------ | ----------------- |
+| `المصنوعات[].content`          | نصرد LLM                                                                 |
+| `metadata.routing_explanation` | شرح مفهوم لقرار التوجيه                                                  |
+| `metadata.cost_envelope`       | التكلفة المقدرة مقابل تكلفة التكلفة للعملة                               |
+| `metadata.resilience_trace`    | مصفوفة من الأحداث (تم تحديدها بشكل أساسي، والمطلوبة بديلاً، وما إلى ذلك) |
+| `metadata.policy_verdict`      | ما إذا كان ائداً لها لسبب                                                | ### `إدارة الحصص` |
+
+يجيب على استفسارات اللغة الطبيعية حول حصص الموفرين.
+
+**أنواع اتفق (المنتهية من محتوى الرسالة):**
+
+| نمط                                               | نوع المصدر                                |
+| ------------------------------------------------- | ----------------------------------------- | -------------------- |
+| يحتوي على `"التصنيف"`، `"الأكثر حصة"`، `"الأفضل"` | تم ترتيب مقدمي الخدمة حسب الحصص النهائية  |
+| يحتوي على `"مجاني"`، `"اقتراح"`                   | يسرد المهرجانات أو المهرجانات المجانية    |
+| افتراضي                                           | ملخص كامل للحصص مع تحذيرات للحصص المنخفضة | ---## Task Lifecycle |
+
+```
+submitted ──→ working ──→ completed
+                       ──→ failed
+              ──────────→ cancelled
+```
+
+| الدولة   | الوصف                                                        |
+| -------- | ------------------------------------------------------------ |
+| `مُقدم`  | تم إنشاء المهمة، في قائمة الانتظار للتنفيذ                   |
+| `العمل`  | معالج المهارة ينفذ                                           |
+| `مكتملة` | البدء في التنفيذ، القطع الأثرية الصعبة                       |
+| `فشل`    | فشل التنفيذ أو النهاية إلى النهاية (TTL: 5 بالضغط الافتراضي) |
+| `ملغاة`  | تم الإلغاء من قبل العميل عبر `المهام/الإلغاء`                |
+
+- حالات الوحدة الطرفية: `مكتملة`، `فشل`، `ملغى` (لم تحدث عمليات انتقال أخرى)
+- يتم وضع العلامة التجارية الجديدة على انتهاء الصلاحية في "المقدمة" أو "الجاري" على أنها "فاشلة".
+- يتم جمع المهام المهمة بعد 2 × TTL---## Client Examples
+
+### Python — Orchestrator Agent
+
+```python
+"""
+A2A Client — Python example.
+Discovers OmniRoute agent, sends a task, and processes the result.
+"""
+import requests
+import json
+
+BASE_URL = "http://localhost:20128"
+API_KEY = "your-api-key"
+HEADERS = {
+    "Content-Type": "application/json",
+    "Authorization": f"Bearer {API_KEY}",
+}
+
+# 1. Discover agent capabilities
+agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json()
+print(f"Agent: {agent_card['name']} v{agent_card['version']}")
+print(f"Skills: {[s['id'] for s in agent_card['skills']]}")
+
+# 2. Send a smart-routing task
+response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={
+    "jsonrpc": "2.0",
+    "id": "task-1",
+    "method": "message/send",
+    "params": {
+        "skill": "smart-routing",
+        "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}],
+        "metadata": {
+            "model": "auto",
+            "combo": "fast-coding",
+            "budget": 0.10,
+        }
+    }
+})
+result = response.json()["result"]
+print(f"\n📝 Response: {result['artifacts'][0]['content'][:200]}...")
+print(f"🔀 Routing: {result['metadata']['routing_explanation']}")
+print(f"💰 Cost: ${result['metadata']['cost_envelope']['actual']}")
+print(f"🛡️ Policy: {result['metadata']['policy_verdict']['reason']}")
+
+# 3. Query quota status
+quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={
+    "jsonrpc": "2.0",
+    "id": "task-2",
+    "method": "message/send",
+    "params": {
+        "skill": "quota-management",
+        "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}],
+    }
+})
+quota_result = quota_resp.json()["result"]
+print(f"\n📊 Quota: {quota_result['artifacts'][0]['content']}")
+```
+
+### TypeScript — Multi-Agent Orchestrator
+
+```typescript
+/**
+ * A2A Client — TypeScript example.
+ * Shows agent discovery, task delegation, and streaming.
+ */
+
+const BASE_URL = "http://localhost:20128";
+const API_KEY = "your-api-key";
+
+interface JsonRpcResponse<T = any> {
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: T;
+  error?: { code: number; message: string };
+}
+
+async function a2aCall<T>(method: string, params: Record<string, any>): Promise<T> {
+  const resp = await fetch(`${BASE_URL}/a2a`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${API_KEY}`,
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: `${method}-${Date.now()}`,
+      method,
+      params,
+    }),
+  });
+  const json: JsonRpcResponse<T> = await resp.json();
+  if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`);
+  return json.result!;
+}
+
+// ── Agent Discovery ──
+const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json());
+console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`);
+
+// ── Smart Routing: Send a coding task ──
+const routingResult = await a2aCall("message/send", {
+  skill: "smart-routing",
+  messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }],
+  metadata: { model: "claude-sonnet-4", role: "coding" },
+});
+console.log("Response:", routingResult.artifacts[0].content);
+console.log("Provider:", routingResult.metadata.routing_explanation);
+
+// ── Quota Management: Find free alternatives ──
+const quotaResult = await a2aCall("message/send", {
+  skill: "quota-management",
+  messages: [{ role: "user", content: "Suggest free combos for documentation" }],
+});
+console.log("Free combos:", quotaResult.artifacts[0].content);
+
+// ── Streaming: Real-time response ──
+const streamResp = await fetch(`${BASE_URL}/a2a`, {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${API_KEY}`,
+  },
+  body: JSON.stringify({
+    jsonrpc: "2.0",
+    id: "stream-1",
+    method: "message/stream",
+    params: {
+      skill: "smart-routing",
+      messages: [{ role: "user", content: "Explain microservices architecture" }],
+    },
+  }),
+});
+
+const reader = streamResp.body!.getReader();
+const decoder = new TextDecoder();
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  const chunk = decoder.decode(value);
+  for (const line of chunk.split("\n")) {
+    if (line.startsWith("data: ")) {
+      const event = JSON.parse(line.slice(6));
+      if (event.params.chunk) {
+        process.stdout.write(event.params.chunk.content);
+      }
+      if (event.params.task.state === "completed") {
+        console.log("\n✅ Stream completed");
+      }
+    }
+  }
+}
+```
+
+### Python — LangChain A2A Integration
+
+```python
+"""
+LangChain integration — Use OmniRoute A2A as a custom LLM.
+"""
+from langchain.llms.base import BaseLLM
+from langchain.schema import LLMResult, Generation
+import requests
+from typing import List, Optional
+
+class OmniRouteA2A(BaseLLM):
+    base_url: str = "http://localhost:20128"
+    api_key: str = ""
+    model: str = "auto"
+    combo: Optional[str] = None
+
+    @property
+    def _llm_type(self) -> str:
+        return "omniroute-a2a"
+
+    def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str:
+        response = requests.post(
+            f"{self.base_url}/a2a",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.api_key}",
+            },
+            json={
+                "jsonrpc": "2.0",
+                "id": "langchain-1",
+                "method": "message/send",
+                "params": {
+                    "skill": "smart-routing",
+                    "messages": [{"role": "user", "content": prompt}],
+                    "metadata": {
+                        "model": self.model,
+                        **({"combo": self.combo} if self.combo else {}),
+                    },
+                },
+            },
+        )
+        result = response.json()["result"]
+        return result["artifacts"][0]["content"]
+
+    def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult:
+        return LLMResult(
+            generations=[[Generation(text=self._call(p, stop))] for p in prompts]
+        )
+
+# Usage
+llm = OmniRouteA2A(
+    base_url="http://localhost:20128",
+    api_key="your-key",
+    model="auto",
+    combo="fast-coding",
+)
+result = llm("Write a Python function to merge two sorted lists")
+print(result)
+```
+
+### Go — A2A Client
+
+```go
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+)
+
+const baseURL = "http://localhost:20128"
+const apiKey = "your-api-key"
+
+type JsonRpcRequest struct {
+	Jsonrpc string      `json:"jsonrpc"`
+	ID      string      `json:"id"`
+	Method  string      `json:"method"`
+	Params  interface{} `json:"params"`
+}
+
+type JsonRpcResponse struct {
+	Jsonrpc string      `json:"jsonrpc"`
+	ID      string      `json:"id"`
+	Result  interface{} `json:"result"`
+	Error   *struct {
+		Code    int    `json:"code"`
+		Message string `json:"message"`
+	} `json:"error"`
+}
+
+func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) {
+	body, _ := json.Marshal(JsonRpcRequest{
+		Jsonrpc: "2.0",
+		ID:      "go-1",
+		Method:  method,
+		Params:  params,
+	})
+
+	req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+apiKey)
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	data, _ := io.ReadAll(resp.Body)
+
+	var result JsonRpcResponse
+	json.Unmarshal(data, &result)
+	return &result, nil
+}
+
+func main() {
+	// Discover agent
+	resp, _ := http.Get(baseURL + "/.well-known/agent.json")
+	defer resp.Body.Close()
+	body, _ := io.ReadAll(resp.Body)
+	fmt.Println("Agent Card:", string(body))
+
+	// Send smart-routing task
+	result, _ := a2aCall("message/send", map[string]interface{}{
+		"skill":    "smart-routing",
+		"messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}},
+		"metadata": map[string]interface{}{"model": "auto"},
+	})
+	out, _ := json.MarshalIndent(result.Result, "", "  ")
+	fmt.Println("Result:", string(out))
+}
+```
+
+---
+
+## Use Cases
+
+### 🤖 Use Case 1: Multi-Agent Coding Pipeline
+
+يقوم وكيل منسق بتفويض إنشاء تعليمات الحظر إلى OmniRoute، ثم يقوم بتمرير الترخيص لوكيل التعديل.```python
+تعريف coding_pipeline (المهمة: str): # الخطوة 1: قم بإنشاء الكود عبر OmniRoute A2A
+code_result = a2a_send("التوجيه الذكي"، [
+{"role": "user"، "content": f"اكتب كود جودة الإنتاج: {task}"}
+]، البيانات الوصفية={"model": "auto"، "role": "coding"})
+كود = code_result["artifacts"][0]["content"]
+
+    # الخطوة الثانية: قم بمراجعة الكود عبر OmniRoute A2A (نموذج مختلف)
+    review_result = a2a_send("التوجيه الذكي"، [
+        {"role": "user"، "content": f"راجع هذا الرمز بحثًا عن الأخطاء والتحسينات:\n\n{code}"}
+    ]، البيانات الوصفية={"model": "auto"، "role": "review"})
+    المراجعة = review_result["artifacts"][0]["content"]
+
+    # الخطوة 3: التحقق من التكاليف
+    print(f"تكلفة الكود: ${code_result['metadata']['cost_envelope']['actual']}")
+    print(f"تكلفة المراجعة: ${review_result['metadata']['cost_envelope']['actual']}")
+
+    إرجاع {"كود": كود، "مراجعة": مراجعة}```
+
+### 💡 Use Case 2: Quota-Aware Agent Swarm
+
+يقوم العديد من الوكلاء بمشاركة الحصص من خلال OmniRoute، وذلك باستخدام مهارة الحصص للتنسيق.```python
+async def quota_aware_agent(agent_name: str, task: str): # Check quota before starting
+quota = a2a_send("quota-management", [
+{"role": "user", "content": "Which provider has the most quota remaining?"}
+])
+print(f"[{agent_name}] {quota['artifacts'][0]['content']}")
+
+    # Send request with budget constraint
+    result = a2a_send("smart-routing", [
+        {"role": "user", "content": task}
+    ], metadata={"budget": 0.05})
+
+    policy = result["metadata"]["policy_verdict"]
+    if not policy["allowed"]:
+        print(f"[{agent_name}] ⚠️ Budget exceeded: {policy['reason']}")
+        # Fall back to free combo
+        quota = a2a_send("quota-management", [
+            {"role": "user", "content": "Suggest free combos"}
+        ])
+        print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}")
+
+    return result
+
+````
+
+### 📊 Use Case 3: Real-Time Streaming Dashboard
+
+يقوم بالمراقبة ببث الاستجابات ويعرض التقدم في الوقت الفعلي.```typescript
+وظيفة غير متزامنة StreamDashboard(prompt: string) {
+  استجابة ثابتة = انتظار الجلب(`${BASE_URL}/a2a`, {
+    الطريقة: "POST"،
+    الرؤوس: { "نوع المحتوى": "application/json"، التفويض: `Bearer ${API_KEY}` }،
+    الجسم: JSON.stringify({
+      جسونربك: "2.0"،
+      المعرف: "داش-1"،
+      الطريقة: "رسالة/دفق"،
+      المعلمات: { المهارة: "التوجيه الذكي"، الرسائل: [{ الدور: "المستخدم"، المحتوى: موجه }] }،
+    }),
+  });
+
+  دع مجموع القطع = 0؛
+  قارئ ثابت = استجابة. الجسم!.getReader();
+  const decoder = new TextDecoder();
+
+  بينما (صحيح) {
+    const { تم، القيمة } = انتظار Reader.read();
+    إذا (تم) كسر؛
+
+    for (سطر ثابت من decoder.decode(value).split("\n")) {
+      إذا (line.startsWith("البيانات:")) {
+        حدث const = JSON.parse(line.slice(6));
+        حالة ثابتة = Event.params.task.state;
+
+        إذا (الحالة === "العمل" && events.params.chunk) {
+          TotalChunks++;
+          عملية.stdout.write(
+            `\r[قطعة ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...`
+          );
+        }
+        إذا (الحالة === "مكتملة") {
+          const meta = events.params.metadata;
+          console.log(
+            `\n ✅ تم | التكلفة: $${meta?.cost_envelope?.actual || 0} | الطريق: ${meta?.routing_explanation || "غير متوفر"}`
+          );
+        }
+        إذا (الحالة === "فشل") {
+          console.error(`\n❌ Failed: ${event.params.metadata?.error}`);
+        }
+      }
+    }
+  }
+}```
+
+### 🔁 Use Case 4: Task Polling Pattern
+
+بالنسبة للمهام طويلة الأمد، قم باستقصاء حالة المهمة بدلاً من الانتظار بشكل متزامن.```python
+import time
+
+def poll_task(task_id: str, timeout: int = 60):
+    """Poll task status until completion or timeout."""
+    start = time.time()
+    while time.time() - start < timeout:
+        result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={
+            "jsonrpc": "2.0",
+            "id": "poll-1",
+            "method": "tasks/get",
+            "params": {"taskId": task_id},
+        }).json()
+
+        task = result["result"]["task"]
+        state = task["state"]
+        print(f"  Task {task_id[:8]}... state={state}")
+
+        if state in ("completed", "failed", "cancelled"):
+            return task
+        time.sleep(2)
+
+    # Timeout — cancel the task
+    requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={
+        "jsonrpc": "2.0",
+        "id": "cancel-1",
+        "method": "tasks/cancel",
+        "params": {"taskId": task_id},
+    })
+    raise TimeoutError(f"Task {task_id} timed out after {timeout}s")
+````
+
+---
+
+## Error Codes
+
+| الكود  | ثابت                       | معنى                              |
+| ------ | -------------------------- | --------------------------------- | -------------------- |
+| -32700 | —                          | خطأ في التحليل (JSON غير صالح)    |
+| -32600 | `طلب_غير صالح`             | طلب JSON-RPC غير صالح أو          | غير مصرح به          |
+| -32601 | `METHOD_NOT_FOUND`         | طريقة أو مهارة غير معروفة         |
+| -32602 | `INVALID_PARAMS`           | معلمات مفقودة أو غير صالحة        |
+| -32603 | `خطأ_داخلي`                | فشل في تنفيذ المهارة              |
+| -32001 | `مهمة_لم يتم العثور عليها` | لم يتم العثور على المفتاح الرئيسي |
+| -32002 | `المهمة_الجاهزة_مكتملة`    | لا يمكن تعديل مهمة مكتملة         |
+| -32003 | "غير مصرح به"              | API الرئيسية غير صالحة أو مفقودة  |
+| -32004 | `الميزانية_تجاوزت`         | التجاوز المدى المكمل              |
+| -32005 | `PROVIDER_UNAVAILABLE`     | لا يوجد مقدمي خيارات الأسهم       | ---## Authentication |
+
+تتطلب جميع الطلبات `/a2a` رمزًا مميزًا لحاملها عبر الرأس `الإعلان`:`
+التفويض: الحامل YOUR_OMNIROUTE_API_KEY`
+
+إذا لم يتم تكوين أي مفتاح API على الخادم (`OMNIROUTE_API_KEY` فارغ)، فسيتم تجاوز المصادقة.---
+
+## File Structure
+
+````
+سرك/ليب/a2a/
+├── TaskManager.ts # دورة حياة المهمة (إنشاء/تحديث/إلغاء/قائمة)، TTL، تنظيف
+├── TaskExecution.ts # منفذ المهام العامة مع إدارة الحالة
+├── Stream.ts # تنسيق دفق SSE، ونبضات القلب، وأحداث القطعة/الإكمال
+├── routingLogger.ts # مسجل قرار التوجيه (الإحصائيات والتاريخ والاحتفاظ)
+└── المهارات/
+    ├── SmartRouting.ts # مهارة التوجيه الذكي (الطرق عبر /v1/chat/completions)
+    └── quotaManagement.ts # مهارة إدارة الحصص (استعلامات الحصص باللغة الطبيعية)
+
+سرك/التطبيق/a2a/
+└── Route.ts # معالج مسار واجهة برمجة التطبيقات Next.js (إرسال JSON-RPC 2.0)
+
+مفتوح-SSE/MCP-خادم/
+└── schemas/a2a.ts # مخططات Zod (AgentCard، Task، JSON-RPC، أحداث SSE)```
+
+---
+
+## Comparison: MCP vs A2A
+
+| ميزة | خادم MCP | خادم A2A |
+| ----------------- | ---------------------------- | ------------------------------------------------- |
+|**البروتوكول**| بروتوكول السياق النموذجي | بروتوكول وكيل إلى وكيل v0.3 |
+|**النقل**| ستديو / HTTP | HTTP (JSON-RPC 2.0) |
+|**الاكتشاف**| قائمة الأدوات عبر MCP | `/.well-known/agent.json` |
+|**التفاصيل**| 16 أداة فردية | 2 مهارات عالية المستوى |
+|**الأفضل لـ**| وكلاء IDE (المؤشر، كود VS) | أنظمة متعددة الوكلاء (LangChain، CrewAI) |
+|**البث**| غير مدعوم | SSE عبر "الرسالة/الدفق" |
+|**تتبع المهام**| لا | دورة حياة كاملة (مقدمة → مكتملة) |
+|**الملاحظة**| سجل التدقيق لكل استدعاء أداة | مظروف التكلفة + تتبع المرونة + حكم السياسة |---
+
+## الرخصة
+
+جزء من [OmniRoute](https://github.com/diegosouzapw/OmniRoute) - ترخيص معهد ماساتشوستس للتكنولوجيا.
+````

docs/i18n/bg/ARCHITECTURE.md

@@ -1,787 +0,0 @@
-🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/ARCHITECTURE.md) · 🇪🇸 [es](../es/ARCHITECTURE.md) · 🇫🇷 [fr](../fr/ARCHITECTURE.md) · 🇩🇪 [de](../de/ARCHITECTURE.md) · 🇮🇹 [it](../it/ARCHITECTURE.md) · 🇷🇺 [ru](../ru/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../zh-CN/ARCHITECTURE.md) · 🇯🇵 [ja](../ja/ARCHITECTURE.md) · 🇰🇷 [ko](../ko/ARCHITECTURE.md) · 🇸🇦 [ar](../ar/ARCHITECTURE.md) · 🇮🇳 [in](../in/ARCHITECTURE.md) · 🇹🇭 [th](../th/ARCHITECTURE.md) · 🇻🇳 [vi](../vi/ARCHITECTURE.md) · 🇮🇩 [id](../id/ARCHITECTURE.md) · 🇲🇾 [ms](../ms/ARCHITECTURE.md) · 🇳🇱 [nl](../nl/ARCHITECTURE.md) · 🇵🇱 [pl](../pl/ARCHITECTURE.md) · 🇸🇪 [sv](../sv/ARCHITECTURE.md) · 🇳🇴 [no](../no/ARCHITECTURE.md) · 🇩🇰 [da](../da/ARCHITECTURE.md) · 🇫🇮 [fi](../fi/ARCHITECTURE.md) · 🇵🇹 [pt](../pt/ARCHITECTURE.md) · 🇷🇴 [ro](../ro/ARCHITECTURE.md) · 🇭🇺 [hu](../hu/ARCHITECTURE.md) · 🇧🇬 [bg](../bg/ARCHITECTURE.md) · 🇸🇰 [sk](../sk/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../uk-UA/ARCHITECTURE.md) · 🇮🇱 [he](../he/ARCHITECTURE.md) · 🇵🇭 [phi](../phi/ARCHITECTURE.md)
-
----
-
-# OmniRoute Architecture
-
-🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md)
-
-_Last updated: 2026-03-04_
-
-## Executive Summary
-
-OmniRoute is a local AI routing gateway and dashboard built on Next.js.
-It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
-
-Core capabilities:
-
-- OpenAI-compatible API surface for CLI/tools (28 providers)
-- Request/response translation across provider formats
-- Model combo fallback (multi-model sequence)
-- Account-level fallback (multi-account per provider)
-- OAuth + API-key provider connection management
-- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
-- Image generation via `/v1/images/generations` (4 providers, 9 models)
-- Think tag parsing (`<think>...</think>`) for reasoning models
-- Response sanitization for strict OpenAI SDK compatibility
-- Role normalization (developer→system, system→user) for cross-provider compatibility
-- Structured output conversion (json_schema → Gemini responseSchema)
-- Local persistence for providers, keys, aliases, combos, settings, pricing
-- Usage/cost tracking and request logging
-- Optional cloud sync for multi-device/state sync
-- IP allowlist/blocklist for API access control
-- Thinking budget management (passthrough/auto/custom/adaptive)
-- Global system prompt injection
-- Session tracking and fingerprinting
-- Per-account enhanced rate limiting with provider-specific profiles
-- Circuit breaker pattern for provider resilience
-- Anti-thundering herd protection with mutex locking
-- Signature-based request deduplication cache
-- Domain layer: model availability, cost rules, fallback policy, lockout policy
-- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers)
-- Policy engine for centralized request evaluation (lockout → budget → fallback)
-- Request telemetry with p50/p95/p99 latency aggregation
-- Correlation ID (X-Request-Id) for end-to-end tracing
-- Compliance audit logging with opt-out per API key
-- Eval framework for LLM quality assurance
-- Resilience UI dashboard with real-time circuit breaker status
-- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`)
-
-Primary runtime model:
-
-- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
-- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
-
-## Scope and Boundaries
-
-### In Scope
-
-- Local gateway runtime
-- Dashboard management APIs
-- Provider authentication and token refresh
-- Request translation and SSE streaming
-- Local state + usage persistence
-- Optional cloud sync orchestration
-
-### Out of Scope
-
-- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
-- Provider SLA/control plane outside local process
-- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
-
-## High-Level System Context
-
-```mermaid
-flowchart LR
-    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
-```
-
-## Core Runtime Components
-
-## 1) API and Routing Layer (Next.js App Routes)
-
-Main directories:
-
-- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
-- `src/app/api/*` for management/configuration APIs
-- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
-
-Important compatibility routes:
-
-- `src/app/api/v1/chat/completions/route.ts`
-- `src/app/api/v1/messages/route.ts`
-- `src/app/api/v1/responses/route.ts`
-- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`
-- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)
-- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)
-- `src/app/api/v1/messages/count_tokens/route.ts`
-- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat
-- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings
-- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images
-- `src/app/api/v1beta/models/route.ts`
-- `src/app/api/v1beta/models/[...path]/route.ts`
-
-Management domains:
-
-- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
-- Providers/connections: `src/app/api/providers*`
-- Provider nodes: `src/app/api/provider-nodes*`
-- Custom models: `src/app/api/provider-models` (GET/POST/DELETE)
-- Model catalog: `src/app/api/models/route.ts` (GET)
-- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
-- OAuth: `src/app/api/oauth/*`
-- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
-- Usage: `src/app/api/usage/*`
-- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
-- CLI tooling helpers: `src/app/api/cli-tools/*`
-- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)
-- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)
-- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)
-- Sessions: `src/app/api/sessions` (GET)
-- Rate limits: `src/app/api/rate-limits` (GET)
-- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state
-- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns
-- Cache stats: `src/app/api/cache/stats` (GET/DELETE)
-- Model availability: `src/app/api/models/availability` (GET/POST)
-- Telemetry: `src/app/api/telemetry/summary` (GET)
-- Budget: `src/app/api/usage/budget` (GET/POST)
-- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)
-- Compliance audit: `src/app/api/compliance/audit-log` (GET)
-- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
-- Policies: `src/app/api/policies` (GET/POST)
-
-## 2) SSE + Translation Core
-
-Main flow modules:
-
-- Entry: `src/sse/handlers/chat.ts`
-- Core orchestration: `open-sse/handlers/chatCore.ts`
-- Provider execution adapters: `open-sse/executors/*`
-- Format detection/provider config: `open-sse/services/provider.ts`
-- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
-- Account fallback logic: `open-sse/services/accountFallback.ts`
-- Translation registry: `open-sse/translator/index.ts`
-- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
-- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
-- Think tag parser: `open-sse/utils/thinkTagParser.ts`
-- Embedding handler: `open-sse/handlers/embeddings.ts`
-- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
-- Image generation handler: `open-sse/handlers/imageGeneration.ts`
-- Image provider registry: `open-sse/config/imageRegistry.ts`
-- Response sanitization: `open-sse/handlers/responseSanitizer.ts`
-- Role normalization: `open-sse/services/roleNormalizer.ts`
-
-Services (business logic):
-
-- Account selection/scoring: `open-sse/services/accountSelector.ts`
-- Context lifecycle management: `open-sse/services/contextManager.ts`
-- IP filter enforcement: `open-sse/services/ipFilter.ts`
-- Session tracking: `open-sse/services/sessionManager.ts`
-- Request deduplication: `open-sse/services/signatureCache.ts`
-- System prompt injection: `open-sse/services/systemPrompt.ts`
-- Thinking budget management: `open-sse/services/thinkingBudget.ts`
-- Wildcard model routing: `open-sse/services/wildcardRouter.ts`
-- Rate limit management: `open-sse/services/rateLimitManager.ts`
-- Circuit breaker: `open-sse/services/circuitBreaker.ts`
-
-Domain layer modules:
-
-- Model availability: `src/lib/domain/modelAvailability.ts`
-- Cost rules/budgets: `src/lib/domain/costRules.ts`
-- Fallback policy: `src/lib/domain/fallbackPolicy.ts`
-- Combo resolver: `src/lib/domain/comboResolver.ts`
-- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
-- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
-- Error codes catalog: `src/lib/domain/errorCodes.ts`
-- Request ID: `src/lib/domain/requestId.ts`
-- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
-- Request telemetry: `src/lib/domain/requestTelemetry.ts`
-- Compliance/audit: `src/lib/domain/compliance/index.ts`
-- Eval runner: `src/lib/domain/evalRunner.ts`
-- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
-
-OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
-
-- Registry index: `src/lib/oauth/providers/index.ts`
-- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
-- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
-
-## 3) Persistence Layer
-
-Primary state DB (SQLite):
-
-- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL)
-- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers)
-- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`)
-- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
-
-Usage persistence:
-
-- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`)
-- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
-- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
-- legacy JSON files are migrated to SQLite by startup migrations when present
-
-Domain State DB (SQLite):
-
-- `src/lib/db/domainState.ts` — CRUD operations for domain state
-- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
-- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
-
-## 4) Auth + Security Surfaces
-
-- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
-- API key generation/verification: `src/shared/utils/apiKey.ts`
-- Provider secrets persisted in `providerConnections` entries
-- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
-
-## 5) Cloud Sync
-
-- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
-- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
-- Control route: `src/app/api/sync/cloud/route.ts`
-
-## Request Lifecycle (`/v1/chat/completions`)
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant Client as CLI/SDK Client
-    participant Route as /api/v1/chat/completions
-    participant Chat as src/sse/handlers/chat
-    participant Core as open-sse/handlers/chatCore
-    participant Model as Model Resolver
-    participant Auth as Credential Selector
-    participant Exec as Provider Executor
-    participant Prov as Upstream Provider
-    participant Stream as Stream Translator
-    participant Usage as usageDb
-
-    Client->>Route: POST /v1/chat/completions
-    Route->>Chat: handleChat(request)
-    Chat->>Model: parse/resolve model or combo
-
-    alt Combo model
-        Chat->>Chat: iterate combo models (handleComboChat)
-    end
-
-    Chat->>Auth: getProviderCredentials(provider)
-    Auth-->>Chat: active account + tokens/api key
-
-    Chat->>Core: handleChatCore(body, modelInfo, credentials)
-    Core->>Core: detect source format
-    Core->>Core: translate request to target format
-    Core->>Exec: execute(provider, transformedBody)
-    Exec->>Prov: upstream API call
-    Prov-->>Exec: SSE/JSON response
-    Exec-->>Core: response + metadata
-
-    alt 401/403
-        Core->>Exec: refreshCredentials()
-        Exec-->>Core: updated tokens
-        Core->>Exec: retry request
-    end
-
-    Core->>Stream: translate/normalize stream to client format
-    Stream-->>Client: SSE chunks / JSON response
-
-    Stream->>Usage: extract usage + persist history/log
-```
-
-## Combo + Account Fallback Flow
-
-```mermaid
-flowchart TD
-    A[Incoming model string] --> B{Is combo name?}
-    B -- Yes --> C[Load combo models sequence]
-    B -- No --> D[Single model path]
-
-    C --> E[Try model N]
-    E --> F[Resolve provider/model]
-    D --> F
-
-    F --> G[Select account credentials]
-    G --> H{Credentials available?}
-    H -- No --> I[Return provider unavailable]
-    H -- Yes --> J[Execute request]
-
-    J --> K{Success?}
-    K -- Yes --> L[Return response]
-    K -- No --> M{Fallback-eligible error?}
-
-    M -- No --> N[Return error]
-    M -- Yes --> O[Mark account unavailable cooldown]
-    O --> P{Another account for provider?}
-    P -- Yes --> G
-    P -- No --> Q{In combo with next model?}
-    Q -- Yes --> E
-    Q -- No --> R[Return all unavailable]
-```
-
-Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics.
-
-## OAuth Onboarding and Token Refresh Lifecycle
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant UI as Dashboard UI
-    participant OAuth as /api/oauth/[provider]/[action]
-    participant ProvAuth as Provider Auth Server
-    participant DB as localDb
-    participant Test as /api/providers/[id]/test
-    participant Exec as Provider Executor
-
-    UI->>OAuth: GET authorize or device-code
-    OAuth->>ProvAuth: create auth/device flow
-    ProvAuth-->>OAuth: auth URL or device code payload
-    OAuth-->>UI: flow data
-
-    UI->>OAuth: POST exchange or poll
-    OAuth->>ProvAuth: token exchange/poll
-    ProvAuth-->>OAuth: access/refresh tokens
-    OAuth->>DB: createProviderConnection(oauth data)
-    OAuth-->>UI: success + connection id
-
-    UI->>Test: POST /api/providers/[id]/test
-    Test->>Exec: validate credentials / optional refresh
-    Exec-->>Test: valid or refreshed token info
-    Test->>DB: update status/tokens/errors
-    Test-->>UI: validation result
-```
-
-Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
-
-## Cloud Sync Lifecycle (Enable / Sync / Disable)
-
-```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
-```
-
-Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
-
-## Data Model and Storage Map
-
-```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
-    }
-```
-
-Physical storage files:
-
-- primary runtime DB: `${DATA_DIR}/storage.sqlite`
-- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact)
-- structured call payload archives: `${DATA_DIR}/call_logs/`
-- optional translator/request debug sessions: `<repo>/logs/...`
-
-## Deployment Topology
-
-```mermaid
-flowchart LR
-    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
-```
-
-## Module Mapping (Decision-Critical)
-
-### Route and API Modules
-
-- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
-- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
-- `src/app/api/providers*`: provider CRUD, validation, testing
-- `src/app/api/provider-nodes*`: custom compatible node management
-- `src/app/api/provider-models`: custom model management (CRUD)
-- `src/app/api/models/route.ts`: model catalog API (aliases + custom models)
-- `src/app/api/oauth/*`: OAuth/device-code flows
-- `src/app/api/keys*`: local API key lifecycle
-- `src/app/api/models/alias`: alias management
-- `src/app/api/combos*`: fallback combo management
-- `src/app/api/pricing`: pricing overrides for cost calculation
-- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
-- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
-- `src/app/api/usage/*`: usage and logs APIs
-- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
-- `src/app/api/cli-tools/*`: local CLI config writers/checkers
-- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
-- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
-- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
-- `src/app/api/sessions`: active session listing (GET)
-- `src/app/api/rate-limits`: per-account rate limit status (GET)
-
-### Routing and Execution Core
-
-- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
-- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
-- `open-sse/executors/*`: provider-specific network and format behavior
-
-### Translation Registry and Format Converters
-
-- `open-sse/translator/index.ts`: translator registry and orchestration
-- Request translators: `open-sse/translator/request/*`
-- Response translators: `open-sse/translator/response/*`
-- Format constants: `open-sse/translator/formats.ts`
-
-### Persistence
-
-- `src/lib/db/*`: persistent config/state and domain persistence on SQLite
-- `src/lib/localDb.ts`: compatibility re-export for DB modules
-- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables
-
-## Provider Executor Coverage (Strategy Pattern)
-
-Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method.
-
-| Executor              | Provider(s)                                                                                                                                                  | Special Handling                                                     |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
-| `DefaultExecutor`     | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider                               |
-| `AntigravityExecutor` | Google Antigravity                                                                                                                                           | Custom project/session IDs, Retry-After parsing                      |
-| `CodexExecutor`       | OpenAI Codex                                                                                                                                                 | Injects system instructions, forces reasoning effort                 |
-| `CursorExecutor`      | Cursor IDE                                                                                                                                                   | ConnectRPC protocol, Protobuf encoding, request signing via checksum |
-| `GithubExecutor`      | GitHub Copilot                                                                                                                                               | Copilot token refresh, VSCode-mimicking headers                      |
-| `KiroExecutor`        | AWS CodeWhisperer/Kiro                                                                                                                                       | AWS EventStream binary format → SSE conversion                       |
-| `GeminiCLIExecutor`   | Gemini CLI                                                                                                                                                   | Google OAuth token refresh cycle                                     |
-
-All other providers (including custom compatible nodes) use the `DefaultExecutor`.
-
-## Provider Compatibility Matrix
-
-| Provider         | Format           | Auth                  | Stream           | Non-Stream | Token Refresh | Usage API          |
-| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
-| Claude           | claude           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Admin only      |
-| Gemini           | gemini           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
-| Gemini CLI       | gemini-cli       | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
-| Antigravity      | antigravity      | OAuth                 | ✅               | ✅         | ✅            | ✅ Full quota API  |
-| OpenAI           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
-| Codex            | openai-responses | OAuth                 | ✅ forced        | ❌         | ✅            | ✅ Rate limits     |
-| GitHub Copilot   | openai           | OAuth + Copilot Token | ✅               | ✅         | ✅            | ✅ Quota snapshots |
-| Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
-| Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
-| Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
-| iFlow            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
-| OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
-| GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
-| DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
-| Groq             | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
-| xAI (Grok)       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
-| Mistral          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
-| Perplexity       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
-| Together AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
-| Fireworks AI     | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
-| Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
-| Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
-| NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
-
-## Format Translation Coverage
-
-Detected source formats include:
-
-- `openai`
-- `openai-responses`
-- `claude`
-- `gemini`
-
-Target formats include:
-
-- OpenAI chat/Responses
-- Claude
-- Gemini/Gemini-CLI/Antigravity envelope
-- Kiro
-- Cursor
-
-Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
-
-```
-Source Format → OpenAI (hub) → Target Format
-```
-
-Translations are selected dynamically based on source payload shape and provider target format.
-
-Additional processing layers in the translation pipeline:
-
-- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance
-- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)
-- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field
-- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`
-
-## Supported API Endpoints
-
-| Endpoint                                           | Format             | Handler                                              |
-| -------------------------------------------------- | ------------------ | ---------------------------------------------------- |
-| `POST /v1/chat/completions`                        | OpenAI Chat        | `src/sse/handlers/chat.ts`                           |
-| `POST /v1/messages`                                | Claude Messages    | Same handler (auto-detected)                         |
-| `POST /v1/responses`                               | OpenAI Responses   | `open-sse/handlers/responsesHandler.ts`              |
-| `POST /v1/embeddings`                              | OpenAI Embeddings  | `open-sse/handlers/embeddings.ts`                    |
-| `GET /v1/embeddings`                               | Model listing      | API route                                            |
-| `POST /v1/images/generations`                      | OpenAI Images      | `open-sse/handlers/imageGeneration.ts`               |
-| `GET /v1/images/generations`                       | Model listing      | API route                                            |
-| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat        | Dedicated per-provider with model validation         |
-| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings  | Dedicated per-provider with model validation         |
-| `POST /v1/providers/{provider}/images/generations` | OpenAI Images      | Dedicated per-provider with model validation         |
-| `POST /v1/messages/count_tokens`                   | Claude Token Count | API route                                            |
-| `GET /v1/models`                                   | OpenAI Models list | API route (chat + embedding + image + custom models) |
-| `GET /api/models/catalog`                          | Catalog            | All models grouped by provider + type                |
-| `POST /v1beta/models/*:streamGenerateContent`      | Gemini native      | API route                                            |
-| `GET/PUT/DELETE /api/settings/proxy`               | Proxy Config       | Network proxy configuration                          |
-| `POST /api/settings/proxy/test`                    | Proxy Connectivity | Proxy health/connectivity test endpoint              |
-| `GET/POST/DELETE /api/provider-models`             | Custom Models      | Custom model management per provider                 |
-
-## Bypass Handler
-
-The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`.
-
-## Request Logger Pipeline
-
-The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`:
-
-```
-1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json
-→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt
-```
-
-Files are written to `<repo>/logs/<session>/` for each request session.
-
-## Failure Modes and Resilience
-
-## 1) Account/Provider Availability
-
-- provider account cooldown on transient/rate/auth errors
-- account fallback before failing request
-- combo model fallback when current model/provider path is exhausted
-
-## 2) Token Expiry
-
-- pre-check and refresh with retry for refreshable providers
-- 401/403 retry after refresh attempt in core path
-
-## 3) Stream Safety
-
-- disconnect-aware stream controller
-- translation stream with end-of-stream flush and `[DONE]` handling
-- usage estimation fallback when provider usage metadata is missing
-
-## 4) Cloud Sync Degradation
-
-- sync errors are surfaced but local runtime continues
-- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
-
-## 5) Data Integrity
-
-- SQLite schema migrations and auto-upgrade hooks at startup
-- legacy JSON → SQLite migration compatibility path
-
-## Observability and Operational Signals
-
-Runtime visibility sources:
-
-- console logs from `src/sse/utils/logger.ts`
-- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
-- textual request status log in `log.txt` (optional/compat)
-- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true`
-- dashboard usage endpoints (`/api/usage/*`) for UI consumption
-
-## Security-Sensitive Boundaries
-
-- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
-- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning
-- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format
-- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level
-- Cloud sync endpoints rely on API key auth + machine id semantics
-
-## Environment and Runtime Matrix
-
-Environment variables actively used by code:
-
-- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
-- Storage: `DATA_DIR`
-- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
-- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME`
-- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
-- Logging: `ENABLE_REQUEST_LOGS`
-- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
-- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants
-- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
-- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
-
-## Known Architectural Notes
-
-1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.
-2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift.
-3. Request logger writes full headers/body when enabled; treat log directory as sensitive.
-4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability.
-5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency.
-6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates).
-7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`).
-8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
-
-## Operational Verification Checklist
-
-- Build from source: `npm run build`
-- Build Docker image: `docker build -t omniroute .`
-- Start service and verify:
-- `GET /api/settings`
-- `GET /api/v1/models`
-- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`

docs/i18n/bg/CODEBASE_DOCUMENTATION.md

@@ -1,593 +0,0 @@
-🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../es/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../fr/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../de/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../it/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../ru/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../ja/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../ko/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../ar/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [in](../in/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../th/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../vi/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../id/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../ms/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../nl/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../pl/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../sv/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../no/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../da/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../fi/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../pt/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../ro/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../hu/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../bg/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../sk/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../he/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../phi/CODEBASE_DOCUMENTATION.md)
-
----
-
-# omniroute — Codebase Documentation
-
-🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md)
-
-> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router.
-
----
-
-## 1. What Is omniroute?
-
-omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem:
-
-> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically.
-
-Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate.
-
----
-
-## 2. Architecture Overview
-
-```mermaid
-graph LR
-    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
-```
-
-### Core Principle: Hub-and-Spoke Translation
-
-All format translation passes through **OpenAI format as the hub**:
-
-```
-Client Format → [OpenAI Hub] → Provider Format    (request)
-Provider Format → [OpenAI Hub] → Client Format    (response)
-```
-
-This means you only need **N translators** (one per format) instead of **N²** (every pair).
-
----
-
-## 3. Project Structure
-
-```
-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. Module-by-Module Breakdown
-
-### 4.1 Config (`open-sse/config/`)
-
-The **single source of truth** for all provider configuration.
-
-| File                          | Purpose                                                                                                                                                                                                                   |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `constants.ts`                | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. |
-| `credentialLoader.ts`         | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility.               |
-| `providerModels.ts`           | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`.                                                                                                          |
-| `codexInstructions.ts`        | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies).                                                                                                                 |
-| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models.                                                                                                                                                               |
-| `ollamaModels.ts`             | Schema definition for local Ollama models (name, size, family, quantization).                                                                                                                                             |
-
-#### Credential Loading Flow
-
-```mermaid
-flowchart TD
-    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 Executors (`open-sse/executors/`)
-
-Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed.
-
-```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
-```
-
-| Executor         | Provider                                   | Key Specializations                                                                                                 |
-| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
-| `base.ts`        | —                                          | Abstract base: URL building, headers, retry logic, credential refresh                                               |
-| `default.ts`     | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers                                                                  |
-| `antigravity.ts` | Google Cloud Code                          | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") |
-| `cursor.ts`      | Cursor IDE                                 | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing       |
-| `codex.ts`       | OpenAI Codex                               | Injects system instructions, manages thinking levels, removes unsupported parameters                                |
-| `gemini-cli.ts`  | Google Gemini CLI                          | Custom URL building (`streamGenerateContent`), Google OAuth token refresh                                           |
-| `github.ts`      | GitHub Copilot                             | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking                                           |
-| `kiro.ts`        | AWS CodeWhisperer                          | AWS EventStream binary parsing, AMZN event frames, token estimation                                                 |
-| `index.ts`       | —                                          | Factory: maps provider name → executor class, with default fallback                                                 |
-
----
-
-### 4.3 Handlers (`open-sse/handlers/`)
-
-The **orchestration layer** — coordinates translation, execution, streaming, and error handling.
-
-| File                  | Purpose                                                                                                                                                                                                                |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `chatCore.ts`         | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. |
-| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format.                                                                        |
-| `embeddings.ts`       | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers.                                                    |
-| `imageGeneration.ts`  | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images.                                          |
-
-#### Request Lifecycle (chatCore.ts)
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant chatCore
-    participant Translator
-    participant Executor
-    participant Provider
-
-    Client->>chatCore: Request (any format)
-    chatCore->>chatCore: Detect source format
-    chatCore->>chatCore: Check bypass patterns
-    chatCore->>chatCore: Resolve model & provider
-    chatCore->>Translator: Translate request (source → OpenAI → target)
-    chatCore->>Executor: Get executor for provider
-    Executor->>Executor: Build URL, headers, transform request
-    Executor->>Executor: Refresh credentials if needed
-    Executor->>Provider: HTTP fetch (streaming or non-streaming)
-
-    alt Streaming
-        Provider-->>chatCore: SSE stream
-        chatCore->>chatCore: Pipe through SSE transform stream
-        Note over chatCore: Transform stream translates<br/>each chunk: target → OpenAI → source
-        chatCore-->>Client: Translated SSE stream
-    else Non-streaming
-        Provider-->>chatCore: JSON response
-        chatCore->>Translator: Translate response
-        chatCore-->>Client: Translated JSON
-    end
-
-    alt Error (401, 429, 500...)
-        chatCore->>Executor: Retry with credential refresh
-        chatCore->>chatCore: Account fallback logic
-    end
-```
-
----
-
-### 4.4 Services (`open-sse/services/`)
-
-Business logic that supports the handlers and executors.
-
-| File                 | Purpose                                                                                                                                                                                                                                                                                                                                |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `provider.ts`        | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. |
-| `model.ts`           | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support.                                                                             |
-| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not).                                                                                                                                                                         |
-| `tokenRefresh.ts`    | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff.                                                                       |
-| `combo.ts`           | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes.                                                                                                                                                                          |
-| `usage.ts`           | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings).                                                                                                                                                                              |
-| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request.                                                                                                                                                              |
-| `contextManager.ts`  | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging.                                                                                                                                                                  |
-| `ipFilter.ts`        | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests.                                                                                                                                                                                          |
-| `sessionManager.ts`  | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics.                                                                                                                                                                            |
-| `signatureCache.ts`  | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window.                                                                                                                                              |
-| `systemPrompt.ts`    | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling.                                                                                                                                                                                            |
-| `thinkingBudget.ts`  | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens.                                                                                                                                        |
-| `wildcardRouter.ts`  | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority.                                                                                                                                                                                   |
-
-#### Token Refresh Deduplication
-
-```mermaid
-sequenceDiagram
-    participant R1 as Request 1
-    participant R2 as Request 2
-    participant Cache as refreshPromiseCache
-    participant OAuth as OAuth Provider
-
-    R1->>Cache: getAccessToken("gemini", token)
-    Cache->>Cache: No in-flight promise
-    Cache->>OAuth: Start refresh
-    R2->>Cache: getAccessToken("gemini", token)
-    Cache->>Cache: Found in-flight promise
-    Cache-->>R2: Return existing promise
-    OAuth-->>Cache: New access token
-    Cache-->>R1: New access token
-    Cache-->>R2: Same access token (shared)
-    Cache->>Cache: Delete cache entry
-```
-
-#### Account Fallback State Machine
-
-```mermaid
-stateDiagram-v2
-    [*] --> Active
-    Active --> Error: Request fails (401/429/500)
-    Error --> Cooldown: Apply backoff
-    Cooldown --> Active: Cooldown expires
-    Active --> Active: Request succeeds (reset backoff)
-
-    state Error {
-        [*] --> ClassifyError
-        ClassifyError --> ShouldFallback: Rate limit / Auth / Transient
-        ClassifyError --> NoFallback: 400 Bad Request
-    }
-
-    state Cooldown {
-        [*] --> ExponentialBackoff
-        ExponentialBackoff: Level 0 = 1s
-        ExponentialBackoff: Level 1 = 2s
-        ExponentialBackoff: Level 2 = 4s
-        ExponentialBackoff: Max = 2min
-    }
-```
-
-#### Combo Model Chain
-
-```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 Translator (`open-sse/translator/`)
-
-The **format translation engine** using a self-registering plugin system.
-
-#### Architecture
-
-```mermaid
-graph TD
-    subgraph "Request Translation"
-        A["Claude → OpenAI"]
-        B["Gemini → OpenAI"]
-        C["Antigravity → OpenAI"]
-        D["OpenAI Responses → OpenAI"]
-        E["OpenAI → Claude"]
-        F["OpenAI → Gemini"]
-        G["OpenAI → Kiro"]
-        H["OpenAI → Cursor"]
-    end
-
-    subgraph "Response Translation"
-        I["Claude → OpenAI"]
-        J["Gemini → OpenAI"]
-        K["Kiro → OpenAI"]
-        L["Cursor → OpenAI"]
-        M["OpenAI → Claude"]
-        N["OpenAI → Antigravity"]
-        O["OpenAI → Responses"]
-    end
-```
-
-| Directory    | Files         | Description                                                                                                                                                                                                                                                      |
-| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request/`   | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import.                                                                                                                                                         |
-| `response/`  | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls.                                                                                                                                                         |
-| `helpers/`   | 6 helpers     | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. |
-| `index.ts`   | —             | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry.                                                                                                                                                                     |
-| `formats.ts` | —             | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`.                                                                                                                                                             |
-
-#### Key Design: Self-Registering Plugins
-
-```javascript
-// Each translator file calls register() on import:
-import { register } from "../index.js";
-register("claude", "openai", translateClaudeToOpenAI);
-
-// The index.js imports all translator files, triggering registration:
-import "./request/claude-to-openai.js"; // ← self-registers
-```
-
----
-
-### 4.6 Utils (`open-sse/utils/`)
-
-| File               | Purpose                                                                                                                                                                                                                                                                              |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `error.ts`         | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming.                                                                                                                              |
-| `stream.ts`        | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. |
-| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup).                                                       |
-| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors.                                |
-| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers.                                                              |
-| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope.                                                        |
-| `networkProxy.ts`  | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s.                                                  |
-
-#### SSE Streaming Pipeline
-
-```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
-```
-
-#### Request Logger Session Structure
-
-```
-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 Application Layer (`src/`)
-
-| Directory     | Purpose                                                                |
-| ------------- | ---------------------------------------------------------------------- |
-| `src/app/`    | Web UI, API routes, Express middleware, OAuth callback handlers        |
-| `src/lib/`    | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared   |
-| `src/mitm/`   | Man-in-the-middle proxy utilities for intercepting provider traffic    |
-| `src/models/` | Database model definitions                                             |
-| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.)     |
-| `src/sse/`    | SSE endpoint handlers that wire the open-sse library to Express routes |
-| `src/store/`  | Application state management                                           |
-
-#### Notable API Routes
-
-| Route                                         | Methods         | Purpose                                                                               |
-| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
-| `/api/provider-models`                        | GET/POST/DELETE | CRUD for custom models per provider                                                   |
-| `/api/models/catalog`                         | GET             | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider |
-| `/api/settings/proxy`                         | GET/PUT/DELETE  | Hierarchical outbound proxy configuration (`global/providers/combos/keys`)            |
-| `/api/settings/proxy/test`                    | POST            | Validates proxy connectivity and returns public IP/latency                            |
-| `/v1/providers/[provider]/chat/completions`   | POST            | Dedicated per-provider chat completions with model validation                         |
-| `/v1/providers/[provider]/embeddings`         | POST            | Dedicated per-provider embeddings with model validation                               |
-| `/v1/providers/[provider]/images/generations` | POST            | Dedicated per-provider image generation with model validation                         |
-| `/api/settings/ip-filter`                     | GET/PUT         | IP allowlist/blocklist management                                                     |
-| `/api/settings/thinking-budget`               | GET/PUT         | Reasoning token budget configuration (passthrough/auto/custom/adaptive)               |
-| `/api/settings/system-prompt`                 | GET/PUT         | Global system prompt injection for all requests                                       |
-| `/api/sessions`                               | GET             | Active session tracking and metrics                                                   |
-| `/api/rate-limits`                            | GET             | Per-account rate limit status                                                         |
-
----
-
-## 5. Key Design Patterns
-
-### 5.1 Hub-and-Spoke Translation
-
-All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs.
-
-### 5.2 Executor Strategy Pattern
-
-Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime.
-
-### 5.3 Self-Registering Plugin System
-
-Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it.
-
-### 5.4 Account Fallback with Exponential Backoff
-
-When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min).
-
-### 5.5 Combo Model Chains
-
-A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically.
-
-### 5.6 Stateful Streaming Translation
-
-Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism.
-
-### 5.7 Usage Safety Buffer
-
-A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation.
-
----
-
-## 6. Supported Formats
-
-| Format                  | Direction       | Identifier         |
-| ----------------------- | --------------- | ------------------ |
-| OpenAI Chat Completions | source + target | `openai`           |
-| OpenAI Responses API    | source + target | `openai-responses` |
-| Anthropic Claude        | source + target | `claude`           |
-| Google Gemini           | source + target | `gemini`           |
-| Google Gemini CLI       | target only     | `gemini-cli`       |
-| Antigravity             | source + target | `antigravity`      |
-| AWS Kiro                | target only     | `kiro`             |
-| Cursor                  | target only     | `cursor`           |
-
----
-
-## 7. Supported Providers
-
-| Provider                 | Auth Method            | Executor    | Key Notes                                     |
-| ------------------------ | ---------------------- | ----------- | --------------------------------------------- |
-| Anthropic Claude         | API key or OAuth       | Default     | Uses `x-api-key` header                       |
-| Google Gemini            | API key or OAuth       | Default     | Uses `x-goog-api-key` header                  |
-| Google Gemini CLI        | OAuth                  | GeminiCLI   | Uses `streamGenerateContent` endpoint         |
-| Antigravity              | OAuth                  | Antigravity | Multi-URL fallback, custom retry parsing      |
-| OpenAI                   | API key                | Default     | Standard Bearer auth                          |
-| Codex                    | OAuth                  | Codex       | Injects system instructions, manages thinking |
-| GitHub Copilot           | OAuth + Copilot token  | Github      | Dual token, VSCode header mimicking           |
-| Kiro (AWS)               | AWS SSO OIDC or Social | Kiro        | Binary EventStream parsing                    |
-| Cursor IDE               | Checksum auth          | Cursor      | Protobuf encoding, SHA-256 checksums          |
-| Qwen                     | OAuth                  | Default     | Standard auth                                 |
-| iFlow                    | OAuth (Basic + Bearer) | Default     | Dual auth header                              |
-| OpenRouter               | API key                | Default     | Standard Bearer auth                          |
-| GLM, Kimi, MiniMax       | API key                | Default     | Claude-compatible, use `x-api-key`            |
-| `openai-compatible-*`    | API key                | Default     | Dynamic: any OpenAI-compatible endpoint       |
-| `anthropic-compatible-*` | API key                | Default     | Dynamic: any Claude-compatible endpoint       |
-
----
-
-## 8. Data Flow Summary
-
-### Streaming Request
-
-```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()"]
-```
-
-### Non-Streaming Request
-
-```mermaid
-flowchart LR
-    A["Client"] --> B["detectFormat()"]
-    B --> C["translateRequest()\nsource → OpenAI → target"]
-    C --> D["Executor.execute()"]
-    D --> E["translateResponse()\ntarget → OpenAI → source"]
-    E --> F["Return JSON\nresponse"]
-```
-
-### Bypass Flow (Claude CLI)
-
-```mermaid
-flowchart LR
-    A["Claude CLI request"] --> B{"Match bypass\npattern?"}
-    B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"]
-    B -->|"No match"| D["Normal flow"]
-    C --> E["Translate to\nsource format"]
-    E --> F["Return without\ncalling provider"]
-```

docs/i18n/bg/CONTRIBUTING.md

@@ -0,0 +1,246 @@
+# Contributing to OmniRoute (Български)
+
+🌐 **Languages:** 🇺🇸 [English](../../../CONTRIBUTING.md) · 🇪🇸 [es](../es/CONTRIBUTING.md) · 🇫🇷 [fr](../fr/CONTRIBUTING.md) · 🇩🇪 [de](../de/CONTRIBUTING.md) · 🇮🇹 [it](../it/CONTRIBUTING.md) · 🇷🇺 [ru](../ru/CONTRIBUTING.md) · 🇨🇳 [zh-CN](../zh-CN/CONTRIBUTING.md) · 🇯🇵 [ja](../ja/CONTRIBUTING.md) · 🇰🇷 [ko](../ko/CONTRIBUTING.md) · 🇸🇦 [ar](../ar/CONTRIBUTING.md) · 🇮🇳 [hi](../hi/CONTRIBUTING.md) · 🇮🇳 [in](../in/CONTRIBUTING.md) · 🇹🇭 [th](../th/CONTRIBUTING.md) · 🇻🇳 [vi](../vi/CONTRIBUTING.md) · 🇮🇩 [id](../id/CONTRIBUTING.md) · 🇲🇾 [ms](../ms/CONTRIBUTING.md) · 🇳🇱 [nl](../nl/CONTRIBUTING.md) · 🇵🇱 [pl](../pl/CONTRIBUTING.md) · 🇸🇪 [sv](../sv/CONTRIBUTING.md) · 🇳🇴 [no](../no/CONTRIBUTING.md) · 🇩🇰 [da](../da/CONTRIBUTING.md) · 🇫🇮 [fi](../fi/CONTRIBUTING.md) · 🇵🇹 [pt](../pt/CONTRIBUTING.md) · 🇷🇴 [ro](../ro/CONTRIBUTING.md) · 🇭🇺 [hu](../hu/CONTRIBUTING.md) · 🇧🇬 [bg](../bg/CONTRIBUTING.md) · 🇸🇰 [sk](../sk/CONTRIBUTING.md) · 🇺🇦 [uk-UA](../uk-UA/CONTRIBUTING.md) · 🇮🇱 [he](../he/CONTRIBUTING.md) · 🇵🇭 [phi](../phi/CONTRIBUTING.md) · 🇧🇷 [pt-BR](../pt-BR/CONTRIBUTING.md) · 🇨🇿 [cs](../cs/CONTRIBUTING.md) · 🇹🇷 [tr](../tr/CONTRIBUTING.md)
+
+---
+
+Благодарим ви за интереса да допринесете! Това ръководство обхваща всичко необходимо, за да работи.---## Development Setup
+
+### Prerequisites
+
+-**Node.js**>= 18 < 24 (препоръчително: 22 LTS) -**npm**10+ -**Git**### Клониране и инсталиране```bash
+git clone https://github.com/diegosouzapw/OmniRoute.git
+cd OmniRoute
+npm install
+
+````
+
+### Environment Variables
+
+```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
+````
+
+Ключови променливи за развитие:
+
+| Променлива             | Разработка по подразбиране | Описание                                   |
+| ---------------------- | -------------------------- | ------------------------------------------ | ---------------------- |
+| `ПОРТ`                 | „20128“                    | Порт на сървъра                            |
+| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128`   | Основен URL адрес за интерфейс             |
+| `JWT_SECRET`           | (генериране по-горе)       | Тайна за подписване на JWT                 |
+| `ПЪРВОНАЧАЛНА_ПАРОЛА`  | `CHANGEME`                 | Първа парола за влизане                    |
+| `APP_LOG_LEVEL`        | `информация`               | Ниво на подробност на регистрационния файл | ### Dashboard Settings |
+
+Таблото за управление предоставя UI превключватели за функции, които също могат да бъдат конфигурирани чрез променливи на средата:
+
+| Задаване на местоположение | Превключване                    | Описание                                                                          |
+| -------------------------- | ------------------------------- | --------------------------------------------------------------------------------- |
+| Настройки → Разширени      | Режим на отстраняване на грешки | Активиране на регистрационните файлове на заявките за отстраняване на грешки (UI) |
+| Настройки → Общи           | Видимост на страничната лента   | Показване/скриване на секциите на страничната лента                               |
+
+Тези настройки се запазват в базата данни и се запазват при рестартиране, като заменят настройките по подразбиране env var, когато са претърпени.### Running Locally```bash
+
+# Development mode (hot reload)
+
+npm run dev
+
+# Production build
+
+npm run build
+npm run start
+
+# Common port configuration
+
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+
+````
+
+URL адреси по подразбиране:
+
+-**Табло за управление**: `http://localhost:20128/табло за управление`
+-**API**: `http://localhost:20128/v1`---## Git Workflow
+
+> ⚠️**НИКОГА не се включва директно с `main`.**Винаги използват разклонения на функции.```bash
+git checkout -b feat/your-feature-name
+# ... направи промени ...
+git commit -m "feat: опишете вашата промяна"
+git push -u origin feat/your-feature-name
+# Отворете заявка за изтегляне в GitHub```
+
+### Branch Naming
+
+| Префикс | Цел |
+| ----------- | ------------------------ |
+| `подвиг/` | Нови функции |
+| `поправи/` | Поправки на грешки |
+| `рефактор/` | Преструктуриране на код |
+| `документи/` | Промени в документацията |
+| `тест/` | Тестови допълнения/поправки |
+| `скучна работа/` | Инструментална екипировка, CI, зависимости |### Commit Messages
+
+Следвайте [Конвенционални ангажименти](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
+````
+
+Обхвати: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`.---## Running Tests
+
+```bash
+# All tests (unit + vitest + ecosystem + e2e)
+npm run test:all
+
+# Single test file (Node.js native test runner — most tests use this)
+node --import tsx/esm --test tests/unit/your-file.test.mjs
+
+# Vitest (MCP server, autoCombo, cache)
+npm run test:vitest
+
+# E2E tests (requires Playwright)
+npm run test:e2e
+
+# Protocol clients E2E (MCP transports, A2A)
+npm run test:protocols:e2e
+
+# Ecosystem compatibility tests
+npm run test:ecosystem
+
+# Coverage (60% min statements/lines/functions/branches)
+npm run test:coverage
+npm run coverage:report
+
+# Lint + format check
+npm run lint
+npm run check
+```
+
+Бележки за покритието:
+
+- `npm run test:coverage` измерва покритието на източника за тестови пакети на основната единица, изключвайки `tests/**` и включва `open-sse/**`
+- Заявките за изтегляне трябва да поддържат общата врата за покритие на**60% или по-висока**за отчети, линии, функции и клонове
+- Ако PR промени производствения код в `src/`, `open-sse/`, `electron/` или `bin/`, той трябва да добави или актуализира автоматизирани тестове в същия PR
+- `npm run coverage:report` отпечатва подробния отчетен файл по файл от последното изпълнение на покритието
+- `npm run test:coverage:legacy` запазва по-старата метрика за историческо сравнение
+- Вижте `docs/COVERAGE_PLAN.md` за поетапна пътна карта за подобряване на покритието### Pull Request Requirements
+
+Преди да отворите или обедините PR:
+
+- Стартирайте `npm run test:unit`
+- Стартирайте `npm run test:coverage`
+- Уверете се, че вратата за покритие остава на**60%+**за всички показатели
+- Включете променените или добавени тестови файлове в PR описанието при промяна на производствения код
+- Проверете резултатите от SonarQube на PR, когато тайните на проекта са конфигурирани в CI
+
+Текущо състояние на теста:**122 файла за единичен тест**, обхващащи:
+
+- Преводачи на доставчици и конвертиране на формати
+- Ограничаване на скоростта, прекъсвач и устойчивост
+- Семантичен кеш, идемпотентност, проследяване на напредъка
+- Операции с база данни и схема (21 DB модула)
+- OAuth потоци и удостоверяване
+- API валиден за крайни точки (Zod v4)
+- MCP сървърни инструменти и прилагане на обхват
+- Системи за памет и умения---## Code Style
+
+-**ESLint**— Стартирайте `npm run lint` преди извършване -**Prettier**— Автоматично форматирано чрез `lint-staged` при ангажиране (2 интервала, точка и запетая, двойни кавички, ширина 100 знака, es5 запетая в края) -**TypeScript**— Всички `src/` кодове се използват `.ts`/`.tsx`; `open-sse/` използва `.ts`/`.js`; документ с TSDoc (`@param`, `@returns`, `@throws`) -**Без `eval()`**— ESLint налага `no-eval`, `no-implied-eval`, `no-new-func` -**Zod валидиране**— Използвайте Zod v4 схеми за всички входни валидации на API -**Именуване**: Файлове = camelCase/kebab-case, компоненти = PascalCase, константи = UPPER_SNAKE---## Project Structure
+
+```
+src/                        # TypeScript (.ts / .tsx)
+├── app/                    # Next.js 16 App Router
+│   ├── (dashboard)/        # Dashboard pages (23 sections)
+│   ├── api/                # API routes (51 directories)
+│   └── login/              # Auth pages (.tsx)
+├── domain/                 # Policy engine (policyEngine, comboResolver, costRules, etc.)
+├── lib/                    # Core business logic (.ts)
+│   ├── a2a/                # Agent-to-Agent v0.3 protocol server
+│   ├── acp/                # Agent Communication Protocol registry
+│   ├── compliance/         # Compliance policy engine
+│   ├── db/                 # SQLite database layer (21 modules + 16 migrations)
+│   ├── memory/             # Persistent conversational memory
+│   ├── oauth/              # OAuth providers, services, and utilities
+│   ├── skills/             # Extensible skill framework
+│   ├── usage/              # Usage tracking and cost calculation
+│   └── localDb.ts          # Re-export layer only — never add logic here
+├── middleware/              # Request middleware (promptInjectionGuard)
+├── mitm/                   # MITM proxy (cert, DNS, target routing)
+├── shared/
+│   ├── components/         # React components (.tsx)
+│   ├── constants/          # Provider definitions (60+), MCP scopes, routing strategies
+│   ├── utils/              # Circuit breaker, sanitizer, auth helpers
+│   └── validation/         # Zod v4 schemas
+└── sse/                    # SSE proxy pipeline
+
+open-sse/                   # @omniroute/open-sse workspace
+├── executors/              # 14 provider-specific request executors
+├── handlers/               # 11 request handlers (chat, responses, embeddings, images, etc.)
+├── mcp-server/             # MCP server (25 tools, 3 transports, 10 scopes)
+├── services/               # 36+ services (combo, autoCombo, rateLimitManager, etc.)
+├── translator/             # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama)
+├── transformer/            # Responses API transformer
+└── utils/                  # 22 utility modules (stream, TLS, proxy, logging)
+
+electron/                   # Electron desktop app (cross-platform)
+
+tests/
+├── unit/                   # Node.js test runner (122 test files)
+├── integration/            # Integration tests
+├── e2e/                    # Playwright tests
+├── security/               # Security tests
+├── translator/             # Translator-specific tests
+└── load/                   # Load tests
+
+docs/                       # Documentation
+├── ARCHITECTURE.md         # System architecture
+├── API_REFERENCE.md        # All endpoints
+├── USER_GUIDE.md           # Provider setup, CLI integration
+├── TROUBLESHOOTING.md      # Common issues
+├── MCP-SERVER.md           # MCP server (25 tools)
+├── A2A-SERVER.md           # A2A agent protocol
+├── AUTO-COMBO.md           # Auto-combo engine
+├── CLI-TOOLS.md            # CLI tools integration
+├── COVERAGE_PLAN.md        # Test coverage improvement plan
+├── openapi.yaml            # OpenAPI specification
+└── adr/                    # Architecture Decision Records
+```
+
+---
+
+## Adding a New Provider
+
+### Step 1: Register Provider Constants
+
+Добавете към `src/shared/constants/providers.ts` — Zod-валидирано при зареждане на модула.### Стъпка 2: Добавяне на изпълнител (ако е необходима персонализирана логика)
+
+Създайте изпълнител в `open-sse/executors/your-provider.ts`, като разширите базовия изпълнител.### Стъпка 3: Добавете преводач (ако форматът не е OpenAI)
+
+Създайте преводачи на заявка/отговор в `open-sse/translator/`.### Стъпка 4: Добавете OAuth Config (ако е базиран на OAuth)
+
+Добавете идентификационни данни за OAuth в `src/lib/oauth/constants/oauth.ts` и услуга в `src/lib/oauth/services/`.### Стъпка 5: Регистрирайте модели
+
+Добавете дефиниции на модели в `open-sse/config/providerRegistry.ts`.### Стъпка 6: Добавете тестове
+
+Напишете модулни тестове в `tests/unit/`, покривайки минимум:
+
+- Регистрация при доставчик
+- Превод на заявка/отговор
+- Обработка на грешки---## Pull Request Checklist
+
+- [ ] Тестовете преминават („npm тест“)
+- [ ] Linting преминава (`npm run lint`)
+- [ ] Компилацията е успешна (`npm run build`)
+- [] TypeScript типове, добавени за нови публични функции и интерфейси
+- [ ] Няма твърдо кодирани тайни или резервни стойности
+- [ ] Всички входове, валидирани със схеми на Zod
+- [ ] CHANGELOG актуализиран (ако промяната е пред потребителя)
+- [ ] Актуализирана документация (ако е приложимо)---## Releasing
+
+Изданията се управляват чрез работен процес `/generate-release`. Когато се създаде ново издание на GitHub, пакетът се**автоматично публикува в npm**чрез GitHub Actions.---## Getting Help
+
+-**Архитектура**: Вижте [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) -**API справка**: Вижте [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) -**Проблеми**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -**ADRs**: Вижте `docs/adr/` за записи на архитектурни решения

docs/i18n/bg/MCP-SERVER.md

@@ -1,87 +0,0 @@
-🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/MCP-SERVER.md) · 🇪🇸 [es](../es/MCP-SERVER.md) · 🇫🇷 [fr](../fr/MCP-SERVER.md) · 🇩🇪 [de](../de/MCP-SERVER.md) · 🇮🇹 [it](../it/MCP-SERVER.md) · 🇷🇺 [ru](../ru/MCP-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/MCP-SERVER.md) · 🇯🇵 [ja](../ja/MCP-SERVER.md) · 🇰🇷 [ko](../ko/MCP-SERVER.md) · 🇸🇦 [ar](../ar/MCP-SERVER.md) · 🇮🇳 [in](../in/MCP-SERVER.md) · 🇹🇭 [th](../th/MCP-SERVER.md) · 🇻🇳 [vi](../vi/MCP-SERVER.md) · 🇮🇩 [id](../id/MCP-SERVER.md) · 🇲🇾 [ms](../ms/MCP-SERVER.md) · 🇳🇱 [nl](../nl/MCP-SERVER.md) · 🇵🇱 [pl](../pl/MCP-SERVER.md) · 🇸🇪 [sv](../sv/MCP-SERVER.md) · 🇳🇴 [no](../no/MCP-SERVER.md) · 🇩🇰 [da](../da/MCP-SERVER.md) · 🇫🇮 [fi](../fi/MCP-SERVER.md) · 🇵🇹 [pt](../pt/MCP-SERVER.md) · 🇷🇴 [ro](../ro/MCP-SERVER.md) · 🇭🇺 [hu](../hu/MCP-SERVER.md) · 🇧🇬 [bg](../bg/MCP-SERVER.md) · 🇸🇰 [sk](../sk/MCP-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/MCP-SERVER.md) · 🇮🇱 [he](../he/MCP-SERVER.md) · 🇵🇭 [phi](../phi/MCP-SERVER.md)
-
----
-
-# OmniRoute MCP Server Documentation
-
-> Model Context Protocol server with 16 intelligent tools
-
-## Installation
-
-OmniRoute MCP is built-in. Start it with:
-
-```bash
-omniroute --mcp
-```
-
-Or via the open-sse transport:
-
-```bash
-# HTTP streamable transport (port 20130)
-omniroute --dev  # MCP auto-starts on /mcp endpoint
-```
-
-## IDE Configuration
-
-See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup.
-
----
-
-## Essential Tools (8)
-
-| Tool                            | Description                              |
-| :------------------------------ | :--------------------------------------- |
-| `omniroute_get_health`          | Gateway health, circuit breakers, uptime |
-| `omniroute_list_combos`         | All configured combos with models        |
-| `omniroute_get_combo_metrics`   | Performance metrics for a specific combo |
-| `omniroute_switch_combo`        | Switch active combo by ID/name           |
-| `omniroute_check_quota`         | Quota status per provider or all         |
-| `omniroute_route_request`       | Send a chat completion through OmniRoute |
-| `omniroute_cost_report`         | Cost analytics for a time period         |
-| `omniroute_list_models_catalog` | Full model catalog with capabilities     |
-
-## Advanced Tools (8)
-
-| Tool                               | Description                                     |
-| :--------------------------------- | :---------------------------------------------- |
-| `omniroute_simulate_route`         | Dry-run routing simulation with fallback tree   |
-| `omniroute_set_budget_guard`       | Session budget with degrade/block/alert actions |
-| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset   |
-| `omniroute_test_combo`             | Live-test all models in a combo                 |
-| `omniroute_get_provider_metrics`   | Detailed metrics for one provider               |
-| `omniroute_best_combo_for_task`    | Task-fitness recommendation with alternatives   |
-| `omniroute_explain_route`          | Explain a past routing decision                 |
-| `omniroute_get_session_snapshot`   | Full session state: costs, tokens, errors       |
-
-## Authentication
-
-MCP tools are authenticated via API key scopes. Each tool requires specific scopes:
-
-| Scope          | Tools                                            |
-| :------------- | :----------------------------------------------- |
-| `read:health`  | get_health, get_provider_metrics                 |
-| `read:combos`  | list_combos, get_combo_metrics                   |
-| `write:combos` | switch_combo                                     |
-| `read:quota`   | check_quota                                      |
-| `write:route`  | route_request, simulate_route, test_combo        |
-| `read:usage`   | cost_report, get_session_snapshot, explain_route |
-| `write:config` | set_budget_guard, set_resilience_profile         |
-| `read:models`  | list_models_catalog, best_combo_for_task         |
-
-## Audit Logging
-
-Every tool call is logged to `mcp_tool_audit` with:
-
-- Tool name, arguments, result
-- Duration (ms), success/failure
-- API key hash, timestamp
-
-## Files
-
-| File                                         | Purpose                                     |
-| :------------------------------------------- | :------------------------------------------ |
-| `open-sse/mcp-server/server.ts`              | MCP server creation + 16 tool registrations |
-| `open-sse/mcp-server/transport.ts`           | Stdio + HTTP transport                      |
-| `open-sse/mcp-server/auth.ts`                | API key + scope validation                  |
-| `open-sse/mcp-server/audit.ts`               | Tool call audit logging                     |
-| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers                    |