fix: remove duplicate LOAD_CODE_ASSIST exports from merge artifact

Release v3.7.2

.agents/workflows/generate-release.md

@@ -52,19 +52,19 @@ Before creating the release, you must ensure the codebase and supply chain are s
 git checkout -b release/v2.x.y
 ```
 
-### 2. Determine new version
+### 2. Determine and sync version
 
-Check current version in `package.json` and increment the **patch** number only:
+Check current version in `package.json`:
 
 ```bash
 grep '"version"' package.json
 ```
 
-Version format: `2.x.y` — examples:
-
-- `2.1.2` → `2.1.3` (patch)
-- `2.1.9` → `2.1.10` (patch)
-- `2.1.10` → `2.2.0` (minor threshold — do manually with `sed`)
+> **🔴 BRANCH-VERSION PARITY RULE**: The logical version in `package.json` MUST exactly match the release branch name. For example, if you are on `release/v3.7.0`, the version in `package.json` MUST be `3.7.0`.
+>
+> - If this is the FIRST time generating a release for a new minor/major branch (e.g., bumping from 3.6.9 to 3.7.0), you MUST ensure the version is bumped to match the new branch logic.
+> - If you are just bumping a patch on the current branch (e.g., 3.6.9 to 3.6.10), use:
+>   `npm version patch --no-git-tag-version`
 
 > **⚠️ ATOMIC COMMIT RULE — Version bump MUST happen before committing feature files.**
 >
@@ -97,15 +97,29 @@ npm install
 
 ### 4. Finalize CHANGELOG.md
 
-Replace `[Unreleased]` header with the new version and date.
-Keep an empty `## [Unreleased]` section above it.
+> **🔴 NO MIXUPS RULE**: Ensure you do NOT mix the backlog of the previous version with the new one. The new version section must ONLY contain the features and fixes for the current release.
+
+Replace the `[Unreleased]` header with the new version and date.
+Keep an empty `## [Unreleased]` section above it, separated by a horizontal rule (`---`).
 
 ```markdown
 ## [Unreleased]
 
 ---
 
-## [2.x.y] — YYYY-MM-DD
+## [3.7.0] — 2026-04-19
+
+### ✨ New Features
+
+- ...
+
+### 🐛 Bug Fixes
+
+- ...
+
+---
+
+## [3.6.9] — 2026-04-19
 ```
 
 ### 5. Update openapi.yaml version ⚠️ MANDATORY
@@ -159,21 +173,29 @@ git push origin release/v2.x.y
 
 ### 9. Open PR to main
 
+### 9. Open PR to main
+
+// turbo
+
 ```bash
+VERSION=$(node -p "require('./package.json').version")
+
+# Extract the exact changelog entry for this version from the root CHANGELOG.md
+awk "/^## \\[$VERSION\\]/{flag=1; print; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md > /tmp/changelog_body.txt
+
+# Append test status and next steps
+echo "" >> /tmp/changelog_body.txt
+echo "### Tests" >> /tmp/changelog_body.txt
+echo "- All tests pass" >> /tmp/changelog_body.txt
+echo "" >> /tmp/changelog_body.txt
+echo "### ⚠️ After merging: run Phase 2 steps to tag, publish, and deploy." >> /tmp/changelog_body.txt
+
 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."
+  --head release/v$VERSION \
+  --title "Release v$VERSION" \
+  --body-file /tmp/changelog_body.txt
 ```
 
 ### 10. 🛑 STOP — Notify User & Await PR Confirmation
@@ -203,9 +225,14 @@ Inform the user:
 git checkout main
 git pull origin main
 VERSION=$(node -p "require('./package.json').version")
+
+# Extracts the changelog section for this version
+NOTES=$(awk '/^## \['"$VERSION"'\]/{flag=1; next} /^## \[[0-9]+/{if(flag) exit} flag' CHANGELOG.md | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+if [ -z "$NOTES" ]; then NOTES="OmniRoute v$VERSION Release"; fi
+
 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
+gh release create "v$VERSION" --title "v$VERSION" --notes "$NOTES" --target main
 ```
 
 ### 14. 🐳 Trigger Docker Hub build (MANDATORY — keep npm and Docker in sync)
@@ -253,10 +280,10 @@ 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
+### 16. Preserve release branch
 
 ```bash
-git branch -d release/v2.x.y
+# Branch is kept for historical purposes. Do not delete.
 ```
 
 ---

.agents/workflows/implement-features.md

@@ -2,23 +2,45 @@
 description: Analyze open feature request issues, implement viable ones on dedicated branches, and respond to authors
 ---
 
-# /implement-features — Feature Request Implementation Workflow
+# /implement-features — Feature Request Harvest, Research & Implementation Workflow
 
 ## Overview
 
-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.
+A **5-phase** workflow that systematically harvests feature requests from GitHub issues, creates structured idea files, researches solutions across the internet and Git repositories, presents a consolidated report for user approval, then generates detailed implementation plans and executes them.
 
-> **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.
+**Output directory structure:**
 
-## Steps
+```
+_ideia/
+├── viable/                  # Features approved for implementation
+│   ├── need_details/        # ❓ Good idea but waiting for author clarification (issues stay OPEN)
+│   │   └── 1015-warp-terminal-mitm.md
+│   ├── 1046-native-playground.md           # ✅ Ready — researched and planned
+│   └── 1046-native-playground.requirements.md
+├── defer/                   # ⏭️ Good ideas deferred for future cycles (issues CLOSED)
+│   └── 1041-smart-auto-combos.md
+└── notfit/                  # ❌ Out of scope / already exists (issues CLOSED)
+    └── 945-telegram-integration.md
 
-### 1. Identify the Repository
+_tasks/features-vX.Y.Z/   # Implementation plans (per-release)
+└── 1046-native-playground.plan.md
+```
+
+> **LIFECYCLE RULE:** `viable/` files are **DELETED** once the feature is implemented — they are not moved. Only unimplemented features live in `viable/` (or `viable/need_details/`). Files in `defer/` and `notfit/` remain as permanent reference.
+
+> **BRANCH RULE**: All implementation 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.
+
+---
+
+## Phase 1 — Harvest: Collect & Catalog Feature Ideas
+
+### 1.1 Identify the Repository
 
 // turbo
 
-- Run: `git -C <project_root> remote get-url origin` to extract owner/repo
+- Run: `git -C <project_root> remote get-url origin` to extract owner/repo.
 
-### 2. Ensure Release Branch Exists
+### 1.2 Ensure Release Branch Exists
 
 // turbo
 
@@ -38,127 +60,647 @@ npm install
 
 If already on a `release/vX.Y.Z` branch, continue working there.
 
-### 3. Fetch Open Feature Request Issues
+### 1.3 Fetch ALL Open Feature Requests
 
 // 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.
+**⚠️ 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.
 
-**Step 3a — Get Issue numbers only** (small output, never truncated):
+**Step 1 — 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.
+```bash
+# Fetch issues with feature/enhancement labels
+gh issue list --repo <owner>/<repo> --state open -l "enhancement" --limit 500 --json number --jq '.[].number'
 
-**Step 3b — Fetch full metadata & conversations for each Issue** (one call per issue):
+# Also check for [Feature] in title (common pattern when no labels are set)
+gh issue list --repo <owner>/<repo> --state open --limit 500 --json number,title --jq '.[] | select(.title | test("\\[Feature\\]|\\[feature\\]|feature request"; "i")) | .number'
+```
 
-- 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.
+- Merge both lists, deduplicate. Count and confirm the total.
+
+**Step 2 — Fetch full metadata for each Issue** (one call per issue):
+
+```bash
+gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author,assignees
+```
+
+- Read the **entire body** — including description, use cases, screenshots, mockups, and any embedded images.
+- Read **ALL comments** — community discussion, agreements, restrictions, owner responses, and linked PRs.
+- **Images**: If the body or comments contain image URLs (`![...](...)` or `https://...png/jpg/gif`), note them — they may contain UI mockups, wireframes, or architecture diagrams that are essential to understanding the request.
 - 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.
+- Sort by oldest first (FIFO).
 
-### 4. Analyze Each Feature Request
+### 1.4 Create Idea Files (initially in `_ideia/` root)
 
-For each feature request issue, perform a **two-level analysis**:
+For each feature request, create a structured idea file in `<project_root>/_ideia/`:
 
-#### Level 1 — Viability Assessment
+**Filename convention**: `<NUMBER>-<kebab-case-short-title>.md`
+Example: `1046-native-playground.md`, `1041-smart-auto-combos.md`
 
-Ask yourself:
+#### 1.4a — If the idea file does NOT exist yet, create it:
 
-- Does this feature align with the project's goals and architecture?
-- Is the request technically feasible with the current codebase?
-- Does it duplicate existing functionality?
-- Would it introduce breaking changes or security risks?
-- Is there enough detail to implement it?
+```markdown
+# Feature: <Title from Issue>
+
+> GitHub Issue: #<NUMBER> — opened by @<author> on <date>
+> Status: 📋 Cataloged | Priority: TBD
+
+## 📝 Original Request
+
+<Paste the FULL issue body here, preserving all formatting, images, and code blocks>
+
+## 💬 Community Discussion
+
+<Summarize ALL comments chronologically, noting who said what and any decisions or objections raised>
+
+### Participants
+
+- @<author> — Original requester
+- @<commenter1> — <brief role/opinion>
+- ...
+
+### Key Points
+
+- <bullet list of the most important discussion points>
+- <agreements reached>
+- <objections raised>
+
+## 🎯 Refined Feature Description
+
+<YOUR interpretation and enrichment of the feature request. Expand on what was asked, fill in logical gaps, provide concrete examples of how it would work. This section should be MORE detailed and clearer than the original request.>
+
+### What it solves
+
+- <problem 1>
+- <problem 2>
+
+### How it should work (high level)
+
+1. <step 1>
+2. <step 2>
+3. ...
+
+### Affected areas
+
+- <list of codebase areas, modules, files likely affected>
+
+## 📎 Attachments & References
+
+- <any image URLs, mockup links, or external references from the issue>
+
+## 🔗 Related Ideas
+
+- <links to related \_ideia/ files if any overlap found>
+```
+
+#### 1.4b — If the idea file ALREADY exists, update it:
+
+- Append new comments from the issue to the **Community Discussion** section.
+- Update the **Refined Feature Description** if new information changes the understanding.
+- Add any new **Related Ideas** cross-references found.
+- **Do NOT overwrite** existing content — append and enrich it.
+
+### 1.5 Cross-Reference & Deduplication
+
+After processing all issues:
+
+- Scan all `_ideia/*.md` files for overlapping features.
+- If two features are substantially the same, add `🔗 Related Ideas` cross-references to both.
+- If one is a strict subset of another, note it in the smaller file: `> ℹ️ This feature is a subset of #<OTHER_NUMBER>. Consider implementing together.`
+
+---
+
+## Phase 2 — Research: Find Solutions & Build Requirements
+
+For each cataloged idea that is **viable** (aligns with the project's goals):
+
+### 2.1 Viability Pre-Check
+
+Before investing in research, quickly assess:
+
+- [ ] Does this feature align with the project's goals and architecture?
+- [ ] Is it technically feasible with the current codebase?
+- [ ] Does it duplicate existing functionality?
+- [ ] Would it introduce breaking changes or security risks?
+- [ ] Is there enough detail to understand what's needed?
 
 **Verdict options:**
 
-1. ✅ **VIABLE** — Makes sense, enough detail to implement → Go to Level 2
-2. ❓ **NEEDS MORE INFO** — Good idea but insufficient detail → Post comment asking for specifics
-3. ❌ **NOT VIABLE** — Doesn't fit the project or is fundamentally flawed → Post comment explaining why, close issue
+| Verdict               | When                                  | Action                      |
+| --------------------- | ------------------------------------- | --------------------------- |
+| ✅ **VIABLE**         | Good idea, enough context             | Proceed to Research         |
+| ❓ **NEEDS DETAIL**   | Good idea, insufficient spec          | Skip research, ask author   |
+| ⏭️ **DEFER**          | Good idea, too complex for this cycle | Catalog only, skip research |
+| ❌ **NOT FIT**        | Doesn't fit the project               | Explain why                 |
+| 🔁 **ALREADY EXISTS** | Feature already implemented           | Point to existing feature   |
 
-#### Level 2 — Implementation (only for VIABLE features)
+### 2.2 Internet Research (for VIABLE features)
 
-> **⚠️ ALL implementation happens on the release branch.**
+For each viable feature, perform systematic research:
 
-1. **Research** — Read all related source files to understand the current architecture
-2. **Design** — Plan the implementation, filling gaps in the original request
-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)
+**Step 1 — Web search for similar implementations:**
 
-### 5. Respond to Authors
-
-#### For VIABLE (implemented) features:
-
-// turbo
-Post a comment on the issue:
-
-````markdown
-## ✅ Feature Implemented!
-
-Hi @<author>! We've analyzed your request and implemented it.
-
-**Branch:** `release/vX.Y.Z` (upcoming release)
-
-### What was implemented:
-
-- <bullet list of what was done>
-
-### How to try it:
-
-```bash
-git fetch origin
-git checkout release/vX.Y.Z
-npm install && npm run dev
+```
+search_web("how to implement <feature description> in <tech stack>")
+search_web("<feature keyword> implementation nextjs typescript 2025 2026")
+search_web("<feature keyword> open source library npm")
 ```
 
-### Next steps:
+**Step 2 — Find reference Git repositories:**
 
-1. **Test it** — Please verify it works as you expected
-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
+```
+search_web("site:github.com <feature keyword> <tech stack> stars:>100")
+search_web("github <feature keyword> implementation recently updated 2026")
+```
 
-This will be included in the next release. Looking forward to your feedback! 🚀
+- Find **up to 10 relevant repositories**, sorted by most recently updated.
+- For each repository:
+  - Note the repo URL, star count, last commit date
+  - Read its README and relevant source files via `read_url_content`
+  - Extract the architectural approach, patterns used, and key code snippets
+
+**Step 3 — Read API docs and standards:**
+
+If the feature involves an external API, protocol, or standard:
+
+- Find and read the official documentation
+- Note version requirements, authentication patterns, rate limits
+
+### 2.3 Create Requirements File
+
+For each researched feature, create a requirements file alongside its idea file:
+
+**Filename**: `<NUMBER>-<kebab-case-short-title>.requirements.md`
+
+```markdown
+# Requirements: <Feature Title>
+
+> Feature Idea: [#<NUMBER>](./<NUMBER>-<kebab-case-short-title>.md)
+> Research Date: <YYYY-MM-DD>
+> Verdict: ✅ VIABLE
+
+## 🔍 Research Summary
+
+<Brief summary of what was found during research>
+
+## 📚 Reference Implementations
+
+| #   | Repository       | Stars | Last Updated | Approach | Relevance    |
+| --- | ---------------- | ----- | ------------ | -------- | ------------ |
+| 1   | [repo/name](url) | ⭐ N  | YYYY-MM-DD   | <brief>  | High/Med/Low |
+| 2   | ...              |       |              |          |              |
+
+### Key Patterns Found
+
+- <pattern 1 with code snippet or link>
+- <pattern 2>
+
+## 📐 Proposed Solution Architecture
+
+### Approach
+
+<Describe the chosen approach based on research findings>
+
+### New Files
+
+| File                  | Purpose       |
+| --------------------- | ------------- |
+| `path/to/new/file.ts` | <description> |
+
+### Modified Files
+
+| File                       | Changes        |
+| -------------------------- | -------------- |
+| `path/to/existing/file.ts` | <what changes> |
+
+### Database Changes
+
+- <migrations needed, if any>
+
+### API Changes
+
+- <new/modified endpoints, if any>
+
+### UI Changes
+
+- <new/modified pages/components, if any>
+
+## ⚙️ Implementation Effort
+
+- **Estimated complexity**: Low / Medium / High / Very High
+- **Estimated files changed**: ~N
+- **Dependencies needed**: <new npm packages, if any>
+- **Breaking changes**: Yes/No — <details>
+- **i18n impact**: <number of new translation keys>
+- **Test coverage needed**: <brief description>
+
+## ⚠️ Open Questions
+
+- <question 1>
+- <question 2>
+
+## 🔗 External References
+
+- <documentation URLs>
+- <API references>
+```
+
+---
+
+## Phase 2.5 — Organize & Respond: Sort Files and Post GitHub Comments
+
+### 2.5.1 Create Directory Structure
+
+// turbo
+
+```bash
+mkdir -p <project_root>/_ideia/viable
+mkdir -p <project_root>/_ideia/viable/need_details
+mkdir -p <project_root>/_ideia/defer
+mkdir -p <project_root>/_ideia/notfit
+```
+
+### 2.5.2 Move Idea Files to Category Subdirectories
+
+After classification, move EVERY idea file to its correct subdirectory:
+
+```bash
+# ✅ VIABLE — move idea + requirements files
+mv _ideia/<NUMBER>-*.md _ideia/viable/
+mv _ideia/<NUMBER>-*.requirements.md _ideia/viable/
+
+# ❓ NEEDS DETAIL — viable but waiting for author response
+mv _ideia/<NUMBER>-*.md _ideia/viable/need_details/
+
+# ⏭️ DEFER — move idea files only
+mv _ideia/<NUMBER>-*.md _ideia/defer/
+
+# ❌ NOT FIT & 🔁 ALREADY EXISTS — move idea files only
+mv _ideia/<NUMBER>-*.md _ideia/notfit/
+```
+
+No files should remain in `_ideia/` root after this step (except subdirectories).
+
+### 2.5.3 Post GitHub Comments by Category
+
+**Each category has a specific comment template and action:**
+
+---
+
+#### For 🔁 ALREADY EXISTS — Comment + CLOSE issue
+
+// turbo
+
+The feature already exists in the system. Explain WHERE it is and HOW to use it.
+
+```markdown
+Hi @<author>! Thanks for the suggestion! 🙏
+
+Great news — this functionality **already exists** in OmniRoute:
+
+**📍 Where to find it:** <exact dashboard path or settings location>
+
+**🔧 How to use it:**
+
+1. <step 1>
+2. <step 2>
+3. <step 3>
+
+If you have any trouble finding or using it, feel free to ask in a Discussion. We're always happy to help!
+
+Closing this as the feature is already available. 🎉
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ⏭️ DEFER — Comment + CLOSE issue
+
+// turbo
+
+Thank the user, explain the idea was cataloged, and that we'll study it before implementing.
+
+```markdown
+Hi @<author>! Thanks for this thoughtful feature request! 🙏
+
+We really appreciate the detailed proposal. We've **cataloged your idea** and it's now part of our improvement backlog.
+
+Due to the **significant architectural impact** of this feature, we'll need to conduct thorough use-case studies and architectural analysis before we start development. This ensures we build it right and don't introduce regressions.
+
+**What happens next:**
+
+- Your idea is saved in our internal feature backlog
+- We'll conduct architecture studies when this area is prioritized
+- We'll notify you here when development begins
+
+Thank you for contributing to OmniRoute's roadmap! Your input helps shape the product. 🚀
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ❌ NOT FIT — Comment + CLOSE issue
+
+// turbo
+
+Politely explain why the feature doesn't fit the project scope.
+
+```markdown
+Hi @<author>! Thanks for the suggestion! 🙏
+
+After careful analysis, we've determined that this feature **falls outside OmniRoute's core scope** as a proxy/router.
+
+**Reason:** <explain why — e.g., "Telegram integration belongs in the application/orchestrator layer that consumes OmniRoute's API, not inside the router itself.">
+
+**Alternative:** <suggest an alternative approach if possible>
+
+We appreciate you thinking of ways to improve OmniRoute! If you'd like to discuss this further, feel free to open a Discussion. 🙏
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ❓ NEEDS DETAIL — Comment (keep OPEN)
+
+// turbo
+
+Ask for the specific missing details needed.
+
+```markdown
+Hi @<author>! Thanks for the feature request — it's an interesting idea and we'd love to explore it further. 🙏
+
+To move forward, we need a few more details:
+
+1. <specific question 1>
+2. <specific question 2>
+3. <specific question 3>
+
+If you know of any **open-source projects or repositories** that implement something similar, please share links — it would help us design the best solution.
+
+Looking forward to your response! 🚀
+```
+
+---
+
+#### For ✅ VIABLE — Comment (keep OPEN)
+
+// turbo
+
+Thank the user, confirm we've cataloged their idea, and explain it may be implemented in future versions.
+
+```markdown
+Hi @<author>! Thanks for the great feature suggestion! 🙏
+
+We've analyzed your request and it aligns well with OmniRoute's roadmap. We've **cataloged this feature** and it's in our implementation backlog.
+
+**Status:** 📋 Cataloged for future implementation
+
+This feature may be included in upcoming releases. We'll **respond to this issue and tag you** as soon as implementation begins so you can test it.
+
+Thank you for helping improve OmniRoute! 🚀
+```
+
+**⚠️ Do NOT close viable issues — they remain OPEN for tracking.**
+
+---
+
+## Phase 3 — Report: Present Findings to User
+
+### 3.1 🛑 MANDATORY STOP — Present Consolidated Report
+
+After completing Phase 1, Phase 2, and Phase 2.5, **STOP and present the following report** in the chat. Do NOT proceed to implementation.
+
+Present a structured report containing:
+
+#### 3.1a — Feature Summary Table
+
+| #   | Issue | Title | Verdict         | Location                      | Action                        |
+| --- | ----- | ----- | --------------- | ----------------------------- | ----------------------------- |
+| 1   | #N    | Title | ✅ VIABLE       | `_ideia/viable/`              | Issue OPEN, comment posted    |
+| 2   | #N    | Title | ⏭️ DEFER        | `_ideia/defer/`               | Issue CLOSED with explanation |
+| 3   | #N    | Title | ❌ NOT FIT      | `_ideia/notfit/`              | Issue CLOSED with explanation |
+| 4   | #N    | Title | 🔁 EXISTS       | `_ideia/notfit/`              | Issue CLOSED with guidance    |
+| 5   | #N    | Title | ❓ NEEDS DETAIL | `_ideia/viable/need_details/` | Issue OPEN, questions posted  |
+
+#### 3.1b — Viable Features Detail
+
+For each VIABLE feature, provide a brief paragraph:
+
+- What was found during research
+- The proposed approach
+- Key risks or unknowns
+- Which reference repositories were most useful
+
+#### 3.1c — Issues Requiring Author Feedback
+
+For features marked ❓ NEEDS DETAIL, list:
+
+- What specific information is missing
+- What examples or repository references would help
+
+#### 3.1d — Ask for User Confirmation
+
+End the report with:
+
+> **Ready to proceed with implementation?**
+>
+> - Reply **"sim"** or **"yes"** to generate full implementation plans for all VIABLE features.
+> - Reply with specific issue numbers to select only certain features.
+> - Reply **"não"** or **"no"** to stop here.
+
+---
+
+## Phase 4 — Plan: Generate Implementation Plans (after user says "yes")
+
+> **⚠️ Do NOT enter this phase without explicit user approval from Phase 3.**
+
+### 4.1 Create Task Directory
+
+```bash
+mkdir -p <project_root>/_tasks/features-vX.Y.Z/
+```
+
+### 4.2 Generate One Implementation Plan Per Feature
+
+For each VIABLE feature approved by the user, create:
+
+**Filename**: `_tasks/features-vX.Y.Z/<NUMBER>-<kebab-case-title>.plan.md`
+
+```markdown
+# Implementation Plan: <Feature Title>
+
+> Issue: #<NUMBER>
+> Idea: [\_ideia/viable/<NUMBER>-title.md](../../_ideia/viable/<NUMBER>-title.md)
+> Requirements: [\_ideia/viable/<NUMBER>-title.requirements.md](../../_ideia/viable/<NUMBER>-title.requirements.md)
+> Branch: `release/vX.Y.Z`
+
+## Overview
+
+<Brief description of what will be built>
+
+## Pre-Implementation Checklist
+
+- [ ] Read all related source files listed below
+- [ ] Confirm no conflicts with in-flight PRs
+- [ ] Verify database migration numbering
+
+## Implementation Steps
+
+### Step 1: <Title>
+
+**Files:**
+
+- `path/to/file.ts` — <what to change>
+
+**Details:**
+<Detailed description of the change, including code patterns to follow, function signatures, etc.>
+
+### Step 2: <Title>
+
+...
+
+### Step N: Tests
+
+**New test files:**
+
+- `tests/unit/<test-file>.test.mjs` — <what to test>
+
+**Test cases:**
+
+- [ ] <test case 1>
+- [ ] <test case 2>
+
+### Step N+1: i18n
+
+**Translation keys to add:**
+
+- `<namespace>.<key>` — "<English value>"
+
+### Step N+2: Documentation
+
+- [ ] Update CHANGELOG.md
+- [ ] Update relevant docs/ files
+
+## Verification Plan
+
+1. Run `npm run build` — must pass
+2. Run `npm test` — all tests must pass
+3. Run `npm run lint` — no new errors
+4. <Manual verification steps>
+
+## Commit Plan
+```
+
+feat: <description> (#<NUMBER>)
+
+```
+
+```
+
+### 4.3 Present Plans for Final Approval
+
+Present a summary of all generated plans:
+
+> **Implementation plans generated:**
+>
+> | #   | Feature | Plan File                                | Steps   | Effort |
+> | --- | ------- | ---------------------------------------- | ------- | ------ |
+> | 1   | <title> | `_tasks/features-vX.Y.Z/N-title.plan.md` | N steps | Medium |
+>
+> Reply **"sim"** or **"yes"** to begin implementation of all features.
+> Reply with specific issue numbers to implement only certain ones.
+
+---
+
+## Phase 5 — Execute: Implement the Plans (after user says "yes")
+
+> **⚠️ Do NOT enter this phase without explicit user approval from Phase 4.**
+
+### 5.1 Implement Each Feature
+
+For each approved plan, execute it step by step:
+
+1. **Follow the plan** — implement exactly as specified in the `.plan.md` file
+2. **Build** — Run `npm run build` after each feature to verify compilation
+3. **Test** — Run `npm test` to ensure no regressions
+4. **Commit** — Commit with: `feat: <description> (#<NUMBER>)`
+5. **Update the plan** — Mark completed steps with `[x]` in the plan file
+6. **Continue** — Move to the next feature (do NOT switch branches)
+
+### 5.2 Respond to Authors (Update Viable Issues)
+
+For each implemented feature, **close the issue with a final comment**:
+
+````markdown
+✅ **Implemented in `release/vX.Y.Z`!**
+
+Hi @<author>! Great news — your feature request has been implemented! 🎉
+
+**What was done:**
+
+- <bullet list of what was built>
+
+**How to try it:**
+
+```bash
+git fetch origin && git checkout release/vX.Y.Z
+npm install && npm run dev
+```
 ````
 
-#### For NEEDS MORE INFO:
+This will be included in the upcoming **vX.Y.Z** release. Feel free to reopen if you spot any issues! 🚀
 
-// 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?"
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+````
 
-Add the context of WHY you need each piece of information.
+Then **DELETE the idea file** — it has served its purpose:
 
-#### For NOT VIABLE:
+```bash
+# ✅ Implemented files are DELETED (not moved)
+rm _ideia/viable/<NUMBER>-<title>.md
+rm _ideia/viable/<NUMBER>-<title>.requirements.md  # if exists
+```
 
-// turbo
-Post a polite comment explaining why the feature doesn't fit at this time:
+> **Why delete?** `viable/` only holds features that still NEED to be done. Once implemented, the commit history and CHANGELOG are the source of truth. Keeping the file would be confusing.
 
-- 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.3 Finalize & Push
 
-### 6. Finalize & Push
-
-After implementing all viable features:
+After implementing all approved 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
+### 5.4 Final Summary Report
 
-Present a summary report to the user via `notify_user`:
+Present a final summary report to the user:
 
-| Issue | Title | Verdict        | Action                  |
-| ----- | ----- | -------------- | ----------------------- |
-| #N    | Title | ✅ Implemented | Committed on release/vX |
-| #N    | Title | ❓ Needs Info  | Comment posted          |
-| #N    | Title | ❌ Not Viable  | Closed with explanation |
+| Issue | Title | Verdict         | Action                                             | Commit    |
+| ----- | ----- | --------------- | -------------------------------------------------- | --------- |
+| #N    | Title | ✅ Implemented  | Issue closed, idea file deleted                    | `abc1234` |
+| #N    | Title | ⏭️ Deferred     | Issue closed + saved in `_ideia/defer/`            | —         |
+| #N    | Title | ❌ Not Fit      | Issue closed + saved in `_ideia/notfit/`           | —         |
+| #N    | Title | 🔁 Exists       | Issue closed + saved in `_ideia/notfit/`           | —         |
+| #N    | Title | ❓ Needs Detail | Issue OPEN, moved to `_ideia/viable/need_details/` | —         |
+
+Include:
+
+- Total features harvested
+- Total ideas cataloged (`viable/need_details/` + `defer/` + `notfit/`)
+- Total features implemented (idea files deleted, issues closed)
+- Total features deferred
+- Total issues closed
+- Total issues left open (needs detail only — viable are closed after implementation)
+- Test results (pass/fail count)

.agents/workflows/resolve-issues.md

@@ -6,7 +6,7 @@ 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. **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.
+This workflow fetches all open issues from the project's GitHub repository, classifies them, analyzes bugs, proposes a resolution plan, waits for user validation, and ONLY THEN implements the fixes, commits, and closes the issues 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.
 
@@ -96,25 +96,25 @@ Verify the issue contains enough to act on:
 
 For each bug, classify into one of 5 actions:
 
-| 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 |
+| 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                    |
+| **✅ CLOSE — Stale**         | We requested logs/info > 7 days ago with no reply                                           | Close thanking the user, invite to reopen if needed     |
+| **📝 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, propose solution in report, wait for approval |
 
 #### 5d. For "FIX — Code Change" Issues
 
-Before coding, perform deep source analysis:
+Before coding, perform deep source analysis to formulate a plan:
 
 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. **Formulate a proposed solution** — detail the exact files and lines you will change and how you will solve it.
+6. **DO NOT modify the codebase yet** — wait for user approval on your report first.
 
 #### 5e. For "RESPOND" Issues
 
@@ -129,50 +129,35 @@ Post a substantive comment that:
 
 ### 6. Generate Report & Wait for Validation
 
-Present a summary report to the user via `notify_user` with `BlockedOnUser: true`:
+Present a summary report to the user detailing your proposed actions. For any bugs that need fixing, explicitly explain your proposed solution (files to change and logic) and point out that it will be implemented on the release branch (`release/vX.Y.Z`) after approval.
 
-| 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 |
+| Issue | Title | Status        | Proposed Action / Version                 |
+| ----- | ----- | ------------- | ----------------------------------------- |
+| #N    | Title | ✅ Close      | Already fixed / duplicate (explain why)   |
+| #N    | Title | 🔧 Propose    | Explanation of the code fix to be applied |
+| #N    | Title | 📝 Respond    | Guidance comment to be posted             |
+| #N    | Title | ❓ Needs Info | Triage comment to be posted               |
+| #N    | Title | ⏭️ Skip       | Feature request / not a bug               |
 
-> **⚠️ IMPORTANT**: Do NOT merge or generate releases at this step.
-> Wait for the user to review the changes and respond with **OK** before proceeding.
+> **⚠️ IMPORTANT**: Do NOT implement code changes, commit, push, or close issues at this step.
+> Wait for the user to review the proposed fixes and respond with **OK** before proceeding.
 
 - 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
+- If the user requests changes → Adjust the proposed solution and present the report again
+- If the user rejects → Revert any accidental changes and stop
 
-### 7. Commit & Push (only after user approval)
+### 7. Implement Fixes, Run Tests & Commit (only after user approval)
 
-After the user validates:
+After the user validates and gives the OK:
 
-- 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
+1. **Implement the fixes** — modify the codebase according to the approved plan.
+2. **Run tests** — `npm run test:all` (or the specific test file) to ensure 100% pass.
+3. **Update CHANGELOG.md** with all new bug fix entries.
+4. **Commit** each fix individually on the release branch with message format: `fix: <description> (#<issue_number>)`.
+5. **Push** the release branch: `git push origin release/vX.Y.Z`.
+6. **Close resolved issues immediately**. For each issue that was marked as Fixed, run:
+   `gh issue close <NUMBER> --repo <owner>/<repo> --comment "Thank you for reporting! This issue has been fixed and will be included in the next release (vX.Y.Z)."`
+7. Likewise, close `Duplicate` issues referencing the original, close `Needs Info` if stale, and post the required comments.
+8. If the project runs automatic releases or needs a PR, proceed to run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user).
 
-### 8. 🛑 WAIT — Notify User & Await Verification
-
-**This is a mandatory stop point.** Use `notify_user` with `BlockedOnUser: true`:
-
-- 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 9
-- **User requests changes** → Apply changes, push to the same branch, notify again
-- **User rejects** → Revert and stop
-
-### 9. Close Issues & Finalize (only after user confirms)
-
-After the user confirms:
-
-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.
+If NO fixes were committed, skip closing and source control steps and just conclude the workflow.

.agents/workflows/review-prs.md

@@ -8,7 +8,7 @@ description: Analyze open Pull Requests from the project's GitHub repository, ge
 
 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.
+> **BRANCH RULE**: PRs are ALWAYS merged into the current `release/vX.Y.Z` branch, NEVER directly into `main`. The release branch acts as a staging area — only after all PRs are integrated and tests pass does the release branch get merged into `main` via the `/generate-release` workflow.
 
 ## Steps
 
@@ -53,7 +53,7 @@ If already on a `release/vX.Y.Z` branch, continue working there.
 **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`
+  `gh pr view <NUMBER> --repo <owner>/<repo> --json number,title,author,headRefName,baseRefName,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):
@@ -70,6 +70,30 @@ If already on a `release/vX.Y.Z` branch, continue working there.
 
 **Verification**: Confirm the count of PRs analyzed matches the count from step 3a before proceeding.
 
+### 3.5 Redirect PR Base Branches to Release Branch
+
+// turbo-all
+
+**⚠️ CRITICAL**: Contributors typically open PRs targeting `main`. Before analyzing or merging, redirect ALL open PRs to target the current release branch instead.
+
+```bash
+# Get the current release branch name
+RELEASE_BRANCH=$(git branch --show-current)  # e.g. release/v3.5.4
+
+# For each open PR that targets main, change its base to the release branch
+for PR_NUM in $(gh pr list --repo <owner>/<repo> --state open --json number,baseRefName --jq '.[] | select(.baseRefName == "main") | .number'); do
+  echo "Redirecting PR #$PR_NUM → $RELEASE_BRANCH"
+  gh pr edit "$PR_NUM" --repo <owner>/<repo> --base "$RELEASE_BRANCH"
+done
+```
+
+This ensures:
+
+1. PRs merge into the release branch, not directly into `main`
+2. Merge conflict detection is accurate against the release branch
+3. The release branch accumulates all changes before the final merge to `main`
+4. If the release branch doesn't exist on remote yet, push it first: `git push origin $RELEASE_BRANCH`
+
 ### 4. Analyze Each PR — For each open PR, perform the following analysis:
 
 #### 4a. Feature Assessment
@@ -139,9 +163,9 @@ Perform a **global impact assessment** to verify whether the PR changes are comp
 
 ### 7. Pre-Merge Fixes & CI Green-Lighting (if approved)
 
-> **⚠️ 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.
+> **⚠️ Fixes and Conflict Resolutions MUST 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).
+- **Sync latest fixes & Resolve Conflicts:** Merge the current `release` branch into the PR branch. If there are merge conflicts, you MUST resolve them inside the author's PR branch. NEVER resolve conflicts by closing their PR and doing the work in a separate branch, as this steals credit from the original author.
 - **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:**
 
@@ -167,28 +191,41 @@ Perform a **global impact assessment** to verify whether the PR changes are comp
   // turbo
 - Run: `npm test` or equivalent test command
 
-### 8. Merge & Integrate
+### 8. Merge into Release Branch
 
-- 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`).
+### 8. Merge into Release Branch (NEVER CLOSE!)
 
-  ```bash
-  gh pr merge <NUMBER> --repo <owner>/<repo>
-  ```
+> **⚠️ CRITICAL**: NEVER use `gh pr close` for a PR whose idea or code was accepted. Closing a PR in a contributor's face after taking their idea—or closing it just because it had conflicts—is unacceptable.
+> You MUST ALWAYS resolve conflicts and apply fixes on the author's PR branch, and then merge the PR using GitHub so the contributor gets the official "Merged" badge and proper credit on their profile.
 
-- Post a **thank-you comment** on the PR via the GitHub API
+Even if the PR had severe conflicts or required significant architectural adjustments, you MUST:
+
+1. Resolve any conflicts and apply the fixes directly to their PR branch (as detailed in step 7).
+2. Once the PR branch is green, conflict-free, and correct, merge it into the release branch using the GitHub CLI.
+
+```bash
+# Merge the PR (base is already set to release/vX.Y.Z from step 3.5)
+gh pr merge <NUMBER> --repo <owner>/<repo> --squash --body "Integrated into release/vX.Y.Z"
+```
+
+In ALL cases:
+
+- Post a **thank-you comment** on the PR via the GitHub API before or immediately after merging.
 - 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] has been integrated into the release/vX.Y.Z branch and will be part of the next release. We appreciate your effort!"_
+  - Thank the author by name/username for their contribution.
+  - Explain what was adjusted or improved (if we pushed fixes to their branch).
+  - Note it will be included in the upcoming release.
+  - Be friendly, professional, and encouraging.
+- Example: _"Thanks @author for this great contribution! 🎉 We've added a few small adjustments to your branch to align with our latest architecture, and it's now officially merged into the release/vX.Y.Z branch. It will be part of the next release. We appreciate your effort!"_
 
-### 9. Close the Original PR
+### 9. Sync Local Release Branch
 
-- 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!"
-  ```
+After merging PRs, sync the local release branch to include the new changes:
+
+```bash
+git fetch origin
+git pull origin release/vX.Y.Z
+```
 
 ### 10. Continue or Finalize
 
@@ -196,4 +233,10 @@ 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 **test coverage** to verify all metrics stay above 85%:
+  ```bash
+  npm run test:coverage
+  ```
+- Fix any test regressions introduced by merged PRs
 - Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)
+- The `/generate-release` workflow handles the final merge from `release/vX.Y.Z` → `main`

.dockerignore

@@ -67,3 +67,42 @@ images
 clipr
 omnirouteCloud
 omnirouteSite
+
+# Temporary/Scratch Folders
+_*
+
+# CI/CD and Version Control (that are not actual code)
+.github
+.husky
+.omc
+
+# Test Configs and Reports
+playwright.config.ts
+vitest*.ts
+audit-report.json
+sonar-project.properties
+
+# Deployment Configs
+docker-compose*.yml
+fly.toml
+
+# Consistent with .gitignore
+.DS_Store
+.idea/
+.config/
+.data/
+.omnivscodeagent/
+*.sqlite-*
+*.tsbuildinfo
+next-env.d.ts
+security-analysis/
+.analysis/
+antigravity-manager-analysis/
+.sisyphus/
+.plans/
+app.__qa_backup/
+.app-build-backup-*/
+.gitnexus
+.worktrees
+.next-playwright/
+cloud/

.env.example

@@ -1,161 +1,463 @@
-# OmniRoute environment contract
-# This file reflects actual runtime usage in the current codebase.
+# ┌─────────────────────────────────────────────────────────────────────────────┐
+# │                          OmniRoute — .env Contract                        │
+# │  This file documents EVERY environment variable read by the runtime.      │
+# │  Copy to .env and adjust values. Lines starting with # are commented out  │
+# │  (optional / off-by-default). Uncomment only what you need.               │
+# │  Reference: docs/ENVIRONMENT.md for full details and usage scenarios.     │
+# └─────────────────────────────────────────────────────────────────────────────┘
 
-# ═══════════════════════════════════════════════════
-#   REQUIRED SECRETS — Generate strong values!
-# ═══════════════════════════════════════════════════
-# Generate with: openssl rand -base64 48
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 1. REQUIRED SECRETS — Must be set before first run!
+# ═══════════════════════════════════════════════════════════════════════════════
+# These secrets are critical for security. Generate strong, unique values.
+
+# JWT signing key for dashboard session tokens.
+# Used by: src/lib/auth — signs/verifies all authenticated session cookies.
+# Generate: openssl rand -base64 48
 JWT_SECRET=
-# Generate with: openssl rand -hex 32
+
+# Encryption key for API keys stored in the database.
+# Used by: src/lib/db/apiKeys.ts — encrypts API key values at rest in SQLite.
+# Generate: openssl rand -hex 32
 API_KEY_SECRET=
 
-# Initial admin password — CHANGE THIS before first use!
+# Initial admin login password — CHANGE THIS before first use!
+# Used by: bootstrap only — sets the initial dashboard password on first boot.
+# After first login you can change it from Dashboard → Settings → Security.
+# Default: CHANGEME (insecure, for local dev only)
 INITIAL_PASSWORD=CHANGEME
-DATA_DIR=/var/lib/omniroute
 
-# Storage (SQLite)
-STORAGE_DRIVER=sqlite
-# Generate with: openssl rand -hex 32
+# ═══════════════════════════════════════════════════════════════════════════════
+# 2. STORAGE & DATABASE
+# ═══════════════════════════════════════════════════════════════════════════════
+# OmniRoute uses SQLite for all persistence. These variables control where
+# data lives, encryption, and cleanup policies.
+
+# Base directory for all persistent data (SQLite DB, logs, backups).
+# Used by: src/lib/db/core.ts — resolves the SQLite database file path.
+# Default: ~/.omniroute/  |  Override for Docker or custom installations.
+# DATA_DIR=/var/lib/omniroute
+
+# Encryption key for SQLite database encryption at rest.
+# Used by: src/lib/db/encryption.ts — encrypts the entire SQLite database.
+# Generate: openssl rand -hex 32  |  Leave empty to disable DB encryption.
 STORAGE_ENCRYPTION_KEY=
+
+# Version tag for the encryption key — allows future key rotation.
+# Used by: scripts/bootstrap-env.mjs, electron/main.js — persists key version.
+# Default: v1  |  Increment when rotating STORAGE_ENCRYPTION_KEY.
 STORAGE_ENCRYPTION_KEY_VERSION=v1
-APP_LOG_RETENTION_DAYS=90
-CALL_LOG_RETENTION_DAYS=90
-SQLITE_MAX_SIZE_MB=2048
-SQLITE_CLEAN_LEGACY_FILES=true
+
+# Automatic SQLite backup on startup.
+# Used by: src/lib/db/backup.ts — creates a timestamped backup before migrations.
+# Default: false (backups enabled)  |  Set true to skip backup on every restart.
 DISABLE_SQLITE_AUTO_BACKUP=false
 
-# Recommended runtime variables
-# Canonical/base port (keeps backward compatibility)
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 3. NETWORK & PORTS
+# ═══════════════════════════════════════════════════════════════════════════════
+# OmniRoute can run on a single port (default) or split Dashboard/API ports.
+
+# Canonical port for both Dashboard UI and API (single-port mode).
+# Used by: src/lib/runtime/ports.ts — base port for the Next.js server.
+# Default: 20128
 PORT=20128
-# Optional split ports:
+
+# Split-port mode: serve Dashboard and API on separate ports for network isolation.
+# Used by: src/lib/runtime/ports.ts — overrides PORT for each service.
 # API_PORT=20129
 # API_HOST=0.0.0.0
 # DASHBOARD_PORT=20128
-# Optional Docker production host publish ports:
+
+# Use Turbopack in local dev. Next 16.2.4 can fail to compile next/font/google
+# through the custom dev runner without this on Windows.
+OMNIROUTE_USE_TURBOPACK=1
+
+# Docker production port mappings (docker-compose.prod.yml only).
+# These set the HOST-side published ports. Container ports use PORT/API_PORT.
 # PROD_DASHBOARD_PORT=20130
 # PROD_API_PORT=20131
+
+# Runtime override used by Electron and wrapped environments.
+# OMNIROUTE_PORT takes precedence over PORT when running inside wrappers.
+# Used by: src/lib/runtime/ports.ts — preserves canonical port in Electron.
+# OMNIROUTE_PORT=20128
+
+# Environment mode — affects Next.js behavior, logging verbosity, and caching.
+# Values: production | development  |  Default: production
 NODE_ENV=production
-INSTANCE_NAME=omniroute
 
-# Recommended security and ops variables
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 4. SECURITY & AUTHENTICATION
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Salt for generating unique machine IDs (fingerprint diversification).
+# Used by: src/lib/auth — combined with hardware identifiers for machine-id hash.
+# Default: endpoint-proxy-salt  |  Change per-deployment for isolation.
 MACHINE_ID_SALT=endpoint-proxy-salt
-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)
+# Set true when running behind HTTPS (reverse proxy with TLS termination).
+# Used by: src/lib/auth — sets the Secure flag on session cookies.
+# Default: false  |  MUST be true in any non-localhost deployment.
+AUTH_COOKIE_SECURE=false
+
+# Require an API key for all /v1/* proxy endpoints.
+# Used by: API middleware — rejects unauthenticated requests to the proxy API.
+# Default: false  |  Set true for multi-user/public deployments.
+REQUIRE_API_KEY=false
+
+# Allow revealing full API key values in the Dashboard UI.
+# Used by: Dashboard providers page — controls show/hide of key values.
+# Default: false  |  Security risk if enabled on shared instances.
+ALLOW_API_KEY_REVEAL=false
+
+# Shared secret for the internal Codex Responses WebSocket bridge.
+# Used by: src/app/api/internal/codex-responses-ws/route.ts — authenticates
+#          bridge requests between the Electron/browser WS relay and OmniRoute.
+# ⚠️  REQUIRED for production — if unset, all WS bridge requests are rejected.
+# Generate: openssl rand -base64 32
+# OMNIROUTE_WS_BRIDGE_SECRET=
+
+# Comma-separated API key IDs that skip request logging (GDPR/compliance).
+# Used by: src/lib/compliance/index.ts — suppresses logs for specific keys.
+# NO_LOG_API_KEY_IDS=key_abc123,key_def456
+
+# Maximum request body size in bytes (rejects larger payloads).
+# Used by: src/shared/middleware/bodySizeGuard.ts — prevents oversized uploads.
+# Default: 10485760 (10 MB)
+# MAX_BODY_SIZE_BYTES=10485760
+
+# CORS configuration — controls which origins can call the API.
+# Used by: Next.js middleware — sets Access-Control-Allow-Origin header.
+# Default: * (all origins)  |  Restrict for production security.
+# CORS_ORIGIN=https://your-domain.com
+
+# Allow provider URLs pointing to private/local networks (localhost, 192.168.x.x, etc.).
+# REQUIRED for self-hosted providers: LM Studio, Ollama, vLLM, Llamafile, Triton, etc.
+# Used by: src/shared/network/outboundUrlGuard.ts — disables SSRF guard for provider calls.
+# Default: false (blocked)  |  Set true to enable local providers.
+# OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 5. INPUT SANITIZATION & PII PROTECTION (FASE-01)
+# ═══════════════════════════════════════════════════════════════════════════════
+# Multi-layer defense: request-side injection guard + response-side PII sanitizer.
+
+# ── Request-Side: Prompt Injection Guard ──
+# Scans incoming messages for prompt injection patterns before routing.
+# Used by: src/middleware/promptInjectionGuard.ts
 # INPUT_SANITIZER_ENABLED=true
-# INPUT_SANITIZER_MODE=warn    # warn | block | redact
+# INPUT_SANITIZER_MODE=warn    # warn = log only | block = reject request | redact = strip patterns
+
+# Legacy alias for INPUT_SANITIZER_MODE (same effect).
+# INJECTION_GUARD_MODE=warn
+
+# PII detection in incoming requests (emails, phone numbers, SSNs, etc.).
+# Used by: src/middleware/promptInjectionGuard.ts — extends injection guard.
 # PII_REDACTION_ENABLED=false
 
-# Cloud sync variables
-# Must point to this running instance so internal sync jobs can call /api/sync/cloud.
-# Server-side preferred variables:
+# ── Response-Side: PII Sanitizer ──
+# Scans LLM responses for leaked PII before returning to the client.
+# Used by: src/lib/piiSanitizer.ts
+# PII_RESPONSE_SANITIZATION=false
+# PII_RESPONSE_SANITIZATION_MODE=redact  # redact = mask PII | warn = log only | block = drop response
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 6. TOOL & ROUTING POLICIES
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Tool policy mode — controls which tools LLMs can invoke via function calling.
+# Used by: src/lib/toolPolicy.ts — enforces allowlist/denylist on tool_choice.
+# Values: allowlist | denylist | disabled  |  Default: disabled
+# TOOL_POLICY_MODE=disabled
+
+# Payload manipulation rules JSON file.
+# Used by: open-sse/services/payloadRules.ts — injects/removes upstream payload fields per model/protocol.
+# Default: ./config/payloadRules.json
+# OMNIROUTE_PAYLOAD_RULES_PATH=./config/payloadRules.json
+
+# Reload interval for payloadRules.json mtime checks in milliseconds.
+# Used by: open-sse/services/payloadRules.ts — keeps file-based rules hot-reloadable without restart.
+# Default: 5000  |  Minimum: 1000
+# OMNIROUTE_PAYLOAD_RULES_RELOAD_MS=5000
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 7. URLS & CLOUD SYNC
+# ═══════════════════════════════════════════════════════════════════════════════
+# URLs used for internal sync jobs, OAuth callbacks, and cloud relay.
+
+# Internal base URL — used by server-side sync jobs to call /api/sync/cloud.
+# Used by: src/lib/cloudSync.ts, src/lib/initCloudSync.ts
+# Default: http://localhost:20128
 BASE_URL=http://localhost:20128
+
+# Cloud relay URL — premium feature for remote config sync.
+# Used by: src/lib/cloudSync.ts — pushes/pulls settings from OmniRoute Cloud.
 CLOUD_URL=
-# Backward-compatible/public variables:
-# NEXT_PUBLIC_BASE_URL is also used as the OAuth redirect_uri origin when running behind a
-# reverse proxy (e.g., nginx). Set this to your public-facing URL so OAuth callbacks work.
-# Example: NEXT_PUBLIC_BASE_URL=https://omniroute.example.com
+
+# Timeout for cloud sync HTTP requests in milliseconds.
+# Used by: src/lib/cloudSync.ts — fetchWithTimeout wrapper.
+# Default: 12000 (12 seconds)
+# CLOUD_SYNC_TIMEOUT_MS=12000
+
+# Public-facing base URL — CRITICAL for reverse proxy / OAuth callback setups.
+# Used by: OAuth redirect_uri computation, Dashboard UI links, cloud/model sync.
+# Set to your public URL when behind nginx/Caddy (e.g., https://omniroute.example.com).
+# Default: http://localhost:20128
 NEXT_PUBLIC_BASE_URL=http://localhost:20128
+
+# Browser-facing OmniRoute origin for generated assets in API responses.
+# Used by: chatgpt-web image generation cache URLs (/v1/chatgpt-web/image/<id>).
+# Set this when OpenWebUI or another relay reaches OmniRoute by an internal URL
+# but the user's browser must fetch images from a LAN, tunnel, or public origin.
+# Do not include /v1; if included accidentally it will be normalized away.
+# OMNIROUTE_PUBLIC_BASE_URL=http://192.168.0.15:20128
+
+# Max wait time for an async chatgpt-web image to land via the celsius
+# WebSocket, in milliseconds. Default 180000 (3 minutes). Increase during
+# upstream queue-deep windows ("Lots of people are creating images right now").
+# OMNIROUTE_CGPT_WEB_IMAGE_TIMEOUT_MS=180000
+
+# Total in-memory byte budget for the chatgpt-web image cache (used to serve
+# /v1/chatgpt-web/image/<id>), in megabytes. Default 256. Lower this if you
+# run OmniRoute on a memory-constrained host; raise it if image generation
+# is heavy and clients are racing the 30-minute TTL.
+# OMNIROUTE_CGPT_WEB_IMAGE_CACHE_MAX_MB=256
+
+# Public cloud URL — client-side mirror of CLOUD_URL.
 NEXT_PUBLIC_CLOUD_URL=
 
-# Optional outbound proxy variables for upstream provider calls
-# Lowercase variants are also supported: http_proxy, https_proxy, all_proxy, no_proxy
-# SOCKS5 proxy support
+# Legacy alias — fallback for NEXT_PUBLIC_BASE_URL in sync schedulers.
+# NEXT_PUBLIC_APP_URL=http://localhost:20128
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 8. OUTBOUND PROXY (Upstream Provider Calls)
+# ═══════════════════════════════════════════════════════════════════════════════
+# Route upstream LLM API calls through an HTTP/SOCKS5 proxy.
+# Useful for corporate egress, geo-routing, or IP masking.
+
+# Enable SOCKS5 proxy support in both server and client components.
+# Used by: open-sse/executors — wraps fetch() calls through the proxy agent.
 ENABLE_SOCKS5_PROXY=true
 NEXT_PUBLIC_ENABLE_SOCKS5_PROXY=true
+
+# Standard proxy variables (lowercase variants also supported).
 # HTTP_PROXY=http://127.0.0.1:7890
 # HTTPS_PROXY=http://127.0.0.1:7890
 # ALL_PROXY=socks5://127.0.0.1:7890
 # NO_PROXY=localhost,127.0.0.1
 
-# TLS fingerprint spoofing (opt-in) — mimics Chrome 124 TLS handshake via wreq-js
-# Reduces risk of JA3/JA4 fingerprint-based blocking by providers (e.g., Google)
-# Requires wreq-js to be installed (included in dependencies)
+# TLS fingerprint spoofing (opt-in) — mimics Chrome 124 TLS handshake via wreq-js.
+# Reduces risk of JA3/JA4 fingerprint-based blocking by providers (e.g., Google).
+# Used by: open-sse/executors — replaces Node.js default TLS fingerprint.
 # ENABLE_TLS_FINGERPRINT=true
 
-# Optional CLI runtime overrides (Docker/host integration)
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 9. CLI TOOL INTEGRATION
+# ═══════════════════════════════════════════════════════════════════════════════
+# Control how OmniRoute discovers and launches CLI sidecars (Claude, Codex, etc.).
+# Used by: src/shared/services/cliRuntime.ts
+
+# CLI discovery mode: auto = search PATH | manual = use explicit paths below.
 # CLI_MODE=auto
-# CLI_EXTRA_PATHS=/host-cli/bin
+
+# Additional PATH entries for finding CLI binaries (colon-separated).
+# CLI_EXTRA_PATHS=/host-cli/bin:/usr/local/bin
+
+# Home directory override for reading CLI config files (~/.claude, etc.).
 # CLI_CONFIG_HOME=/root
+
+# Allow OmniRoute to write CLI config files (token refresh, etc.).
 # CLI_ALLOW_CONFIG_WRITES=true
+
+# Override binary paths for individual CLI tools.
 # CLI_CLAUDE_BIN=claude
 # CLI_CODEX_BIN=codex
 # CLI_DROID_BIN=droid
 # CLI_OPENCLAW_BIN=openclaw
 # CLI_CURSOR_BIN=agent
 # CLI_CLINE_BIN=cline
-# CLI_ROO_BIN=roo
 # CLI_CONTINUE_BIN=cn
+# CLI_QODER_BIN=qoder
+# CLI_QWEN_BIN=qwen
 
-# Provider OAuth Credentials (optional — override hardcoded defaults)
-# These can also be set via data/provider-credentials.json
-# CLAUDE_OAUTH_CLIENT_ID=
 
-# ─────────────────────────────────────────────────────────────────────────────
-# ⚠️  GOOGLE OAUTH (Antigravity, Gemini CLI) — IMPORTANT FOR REMOTE SERVERS
-# ─────────────────────────────────────────────────────────────────────────────
-# The built-in Google OAuth credentials ONLY work when OmniRoute runs on
-# localhost (127.0.0.1 / local network). They are registered with
-# redirect_uri = http://localhost:PORT/callback and Google will reject any
-# other redirect URI with: redirect_uri_mismatch.
-#
-# If you are hosting OmniRoute on a remote server (VPS, Docker, cloud), you
-# MUST register your own Google Cloud OAuth 2.0 credentials:
-#
-#   1. Go to https://console.cloud.google.com/apis/credentials
-#   2. Create an OAuth 2.0 Client ID (type: "Web application")
-#   3. Add your server URL as Authorized redirect URI:
-#        https://your-server.com/callback
-#   4. Copy the Client ID and Client Secret below.
-#
-# See the full tutorial in README.md → "OAuth em Servidor Remoto" section.
-#
-# Antigravity (Google Gemini Code Assist):
-# ANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
-# ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret
+# ═══════════════════════════════════════════════════════════════════════════════
+# 10. INTERNAL AGENT & MCP INTEGRATIONS
+# ═══════════════════════════════════════════════════════════════════════════════
+# Used by MCP server, A2A skills, and CLI sidecars to call the running instance.
+
+# Explicit base URL for MCP/A2A tools to reach OmniRoute (overrides localhost auto-detect).
+# For browser-visible generated image URLs, prefer OMNIROUTE_PUBLIC_BASE_URL above.
+# Used by: open-sse/mcp-server/server.ts, src/lib/a2a/
+# OMNIROUTE_BASE_URL=http://localhost:20128
+
+# API key for internal tool calls (MCP tools, A2A skills).
+# OMNIROUTE_API_KEY=
+
+# API key ID for MCP audit logging.
+# Used by: open-sse/mcp-server/audit.ts — tags audit events with a key identity.
+# OMNIROUTE_API_KEY_ID=
+
+# Legacy alias for OMNIROUTE_API_KEY.
+# ROUTER_API_KEY=
+
+# Enforce scope-based access control on MCP tool calls.
+# Used by: open-sse/mcp-server/server.ts — rejects calls outside allowed scopes.
+# OMNIROUTE_MCP_ENFORCE_SCOPES=false
+
+# Comma-separated scopes granted to this MCP connection.
+# Full list: admin, combos, health, models, routing, budget, metrics, pricing, memory, skills
+# OMNIROUTE_MCP_SCOPES=admin,combos,health
+
+# Model catalog sync interval in hours.
+# Used by: src/shared/services/modelSyncScheduler.ts — periodic model refresh.
+# Default: 24
+# MODEL_SYNC_INTERVAL_HOURS=24
+
+# Provider limits sync interval in minutes (rate limit windows, quotas).
+# Used by: src/server-init.ts — polls provider health endpoints.
+# Default: 70
+PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70
+
+# Disable all background services (sync, pricing, model refresh).
+# Used by: src/instrumentation-node.ts, src/lib/initCloudSync.ts
+# Useful for: CI builds, test environments, or resource-constrained containers.
+# OMNIROUTE_DISABLE_BACKGROUND_SERVICES=false
+
+# Flag set by bootstrap script after initial setup is complete.
+# Used by: src/app/(dashboard)/dashboard/page.tsx — shows setup wizard vs. dashboard.
+# OMNIROUTE_BOOTSTRAPPED=false
+
+# Allow request body to override the Antigravity project field.
+# Used by: open-sse/executors/antigravity.ts — escape hatch for multi-project setups.
+# OMNIROUTE_ALLOW_BODY_PROJECT_OVERRIDE=0
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 11. OAUTH PROVIDER CREDENTIALS
+# ═══════════════════════════════════════════════════════════════════════════════
+# Built-in default credentials for localhost development.
+# For remote/VPS deployments, register your own at each provider's developer console.
+# The bootstrap-env script auto-populates these in .env if missing.
+# Can also be overridden via data/provider-credentials.json where supported.
+
+# ── Claude Code (Anthropic) ──
+CLAUDE_OAUTH_CLIENT_ID=9d1c250a-e61b-44d9-88ed-5944d1962f5e
+# Custom redirect URI override for Claude OAuth callback.
+# CLAUDE_CODE_REDIRECT_URI=https://platform.claude.com/oauth/code/callback
+
+# ── Codex / OpenAI ──
+CODEX_OAUTH_CLIENT_ID=app_EMoamEEZ73f0CkXaXp7hrann
+
+# ── Gemini (Google) ──
+GEMINI_OAUTH_CLIENT_ID=681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com
+GEMINI_OAUTH_CLIENT_SECRET=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
+
+# ── Gemini CLI (Google) ──
+GEMINI_CLI_OAUTH_CLIENT_ID=681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com
+GEMINI_CLI_OAUTH_CLIENT_SECRET=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
+
+# ── Qwen (Alibaba) ──
+QWEN_OAUTH_CLIENT_ID=f0304373b74a44d2b584a3fb70ca9e56
+
+# ── Kimi Coding (Moonshot) ──
+KIMI_CODING_OAUTH_CLIENT_ID=17e5f671-d194-4dfb-9706-5516cb48c098
+
+# ── Antigravity (Google Cloud Code) ──
+ANTIGRAVITY_OAUTH_CLIENT_ID=1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com
 ANTIGRAVITY_OAUTH_CLIENT_SECRET=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
 
-# Gemini CLI (Google AI):
-# GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
-# GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret
-# GEMINI_CLI_OAUTH_CLIENT_ID=
-GEMINI_OAUTH_CLIENT_SECRET=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
-GEMINI_CLI_OAUTH_CLIENT_SECRET=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
-# ─────────────────────────────────────────────────────────────────────────────
+# ── GitHub Copilot ──
+GITHUB_OAUTH_CLIENT_ID=Iv1.b507a08c87ecfe98
 
-# CLAUDE_OAUTH_CLIENT_ID=
-# CODEX_OAUTH_CLIENT_ID=
-# CODEX_OAUTH_CLIENT_SECRET=
-# QWEN_OAUTH_CLIENT_ID=
-# QODER_OAUTH_CLIENT_ID=
+# ── Qoder ──
 QODER_OAUTH_CLIENT_SECRET=4Z3YjXycVsQvyGF1etiNlIBB4RsqSDtW
 
-# ─────────────────────────────────────────────────────────────────────────────
-# Provider User-Agent Overrides (optional — customize per-provider UA headers)
-# ─────────────────────────────────────────────────────────────────────────────
-# Format: {PROVIDER_ID}_USER_AGENT=custom-value
-# When set, overrides the default User-Agent header sent to that provider.
-# Useful when providers update versions or block old user-agents.
-CLAUDE_USER_AGENT=claude-cli/1.0.83 (external, cli)
-CODEX_USER_AGENT=codex-cli/0.92.0 (Windows 10.0.26100; x64)
-GITHUB_USER_AGENT=GitHubCopilotChat/0.26.7
-ANTIGRAVITY_USER_AGENT=antigravity/1.104.0 darwin/arm64
-KIRO_USER_AGENT=AWS-SDK-JS/3.0.0 kiro-ide/1.0.0
-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
+# ── Qoder Browser OAuth (experimental) ──
+# OmniRoute only enables the browser OAuth flow when ALL 5 variables below are set:
+#   - QODER_OAUTH_AUTHORIZE_URL
+#   - QODER_OAUTH_TOKEN_URL
+#   - QODER_OAUTH_USERINFO_URL
+#   - QODER_OAUTH_CLIENT_ID
+#   - QODER_OAUTH_CLIENT_SECRET
+#
+# Redirect URI to register in the Qoder OAuth app:
+#   - Localhost dev with PORT=20128: http://localhost:20128/callback
+#   - LAN access (example):        http://192.168.0.15:20128/callback
+#   - Public domain (recommended): https://omniroute.example.com/callback
+#
+# Behind reverse proxy / public domain, also set NEXT_PUBLIC_BASE_URL to the same public origin.
+# If these values are not available, prefer QODER_PERSONAL_ACCESS_TOKEN below.
+# QODER_OAUTH_AUTHORIZE_URL=
+# QODER_OAUTH_TOKEN_URL=
+# QODER_OAUTH_USERINFO_URL=
+# QODER_OAUTH_CLIENT_ID=
+# QODER_OAUTH_CLIENT_SECRET=
+
+# ── Qoder Personal Access Token (direct API key fallback) ──
+# Used by: open-sse/executors/qoder.ts — bypasses OAuth when set.
+# QODER_PERSONAL_ACCESS_TOKEN=
+# QODER_CLI_WORKSPACE=
+# OMNIROUTE_QODER_WORKSPACE=
 
 # ─────────────────────────────────────────────────────────────────────────────
-# CLI Fingerprint Compatibility (optional — match native CLI binary signatures)
+# ⚠️  GOOGLE OAUTH (Antigravity, Gemini CLI) & OTHER PROVIDERS — REMOTE SERVERS
 # ─────────────────────────────────────────────────────────────────────────────
+# The default Client IDs above ONLY work when OmniRoute runs on localhost.
+# For remote/VPS hosting (including Docker containers on remote servers):
+#   1. By default, the browser will attempt OAuth redirects back to localhost, which will fail.
+#   2. Set NEXT_PUBLIC_BASE_URL=https://your-domain.com to fix the redirect URI.
+#   3. You MUST create your own OAuth App in each provider's developer console (Google Cloud, etc.)
+#      and set the Authorized redirect URI to your domain (e.g., https://your-domain.com/callback).
+#   4. Replace the _OAUTH_CLIENT_ID and _SECRET values above with your own credentials.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── OAuth sidecar/CLI bridge (internal) ──
+# Used by: src/lib/oauth/config/index.ts — internal CLI↔OmniRoute auth bridge.
+# OMNIROUTE_SERVER=http://localhost:20128
+# OMNIROUTE_TOKEN=
+# OMNIROUTE_USER_ID=cli
+# CLI_TOKEN=        # legacy alias for OMNIROUTE_TOKEN
+# CLI_USER_ID=      # legacy alias for OMNIROUTE_USER_ID
+# SERVER_URL=       # legacy alias for OMNIROUTE_SERVER
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 12. PROVIDER USER-AGENT OVERRIDES
+# ═══════════════════════════════════════════════════════════════════════════════
+# Customize the User-Agent header sent to each upstream provider.
+# Format: {PROVIDER_ID}_USER_AGENT=custom-value
+# Used by: open-sse/executors/base.ts — buildHeaders() dynamic lookup.
+# Update these when providers release new CLI versions to avoid blocks.
+
+CLAUDE_USER_AGENT=claude-cli/2.1.121 (external, cli)
+CODEX_USER_AGENT=codex-cli/0.125.0 (Windows 10.0.26100; x64)
+GITHUB_USER_AGENT=GitHubCopilotChat/0.45.1
+ANTIGRAVITY_USER_AGENT=antigravity/1.107.0 darwin/arm64
+KIRO_USER_AGENT=AWS-SDK-JS/3.0.0 kiro-ide/1.0.0
+QODER_USER_AGENT=Qoder-Cli
+QWEN_USER_AGENT=QwenCode/0.15.3 (linux; x64)
+CURSOR_USER_AGENT=connect-es/1.6.1
+GEMINI_CLI_USER_AGENT=google-api-nodejs-client/10.3.0
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 13. CLI FINGERPRINT COMPATIBILITY (Anti-Detection)
+# ═══════════════════════════════════════════════════════════════════════════════
 # 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.
-#
+# Used by: open-sse/config/cliFingerprints.ts, open-sse/executors/base.ts
+
 # Enable per-provider:
 # CLI_COMPAT_CODEX=1
 # CLI_COMPAT_CLAUDE=1
@@ -167,12 +469,18 @@ GEMINI_CLI_USER_AGENT=google-api-nodejs-client/9.15.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
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 14. API KEY PROVIDERS
+# ═══════════════════════════════════════════════════════════════════════════════
+# API keys for direct-authentication providers.
+# Preferred setup: Dashboard → Providers → Add API Key.
+# Setting here is an alternative for Docker/headless deployments.
+
 # DEEPSEEK_API_KEY=
 # GROQ_API_KEY=
 # XAI_API_KEY=
@@ -186,54 +494,276 @@ GEMINI_CLI_USER_AGENT=google-api-nodejs-client/9.15.1
 
 # Embedding Providers (optional — used by /v1/embeddings)
 # NEBIUS_API_KEY=
-# Provider keys above (openai, mistral, together, fireworks, nvidia) also work for embeddings
+# Provider keys above (OpenAI, Mistral, Together, Fireworks, NVIDIA) also work for embeddings.
 
-# Timeout settings
-# 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=*
+# ═══════════════════════════════════════════════════════════════════════════════
+# 15. TIMEOUT SETTINGS
+# ═══════════════════════════════════════════════════════════════════════════════
+# All timeout values are in milliseconds.
+# Used by: src/shared/utils/runtimeTimeouts.ts — centralized timeout resolution.
+#
+# Hierarchy: REQUEST_TIMEOUT_MS acts as a global override.
+# If set, it becomes the default for FETCH_TIMEOUT_MS and STREAM_IDLE_TIMEOUT_MS.
+# The fine-grained variables below override their respective defaults only when set.
 
-# Logging
+# ── Global shortcut ──
+# REQUEST_TIMEOUT_MS=600000          # Overrides both fetch and stream idle defaults
+
+# ── Upstream fetch (provider calls) ──
+# FETCH_TIMEOUT_MS=600000            # Total request timeout (default: 600000 = 10 min)
+#                                     # Also drives anthropic-compatible-cc-* X-Stainless-Timeout.
+# FETCH_HEADERS_TIMEOUT_MS=600000    # Time to receive response headers
+# FETCH_BODY_TIMEOUT_MS=600000       # Time to receive full response body
+# FETCH_CONNECT_TIMEOUT_MS=30000     # TCP connection establishment (default: 30s)
+# FETCH_KEEPALIVE_TIMEOUT_MS=4000    # Keep-alive socket idle timeout (default: 4s)
+
+# ── Stream idle detection ──
+# STREAM_IDLE_TIMEOUT_MS=600000      # Max silence between SSE chunks (default: 600000)
+#                                     # Extended-thinking models rarely pause >90s.
+
+# ── TLS client (wreq-js fingerprint proxy) ──
+# TLS_CLIENT_TIMEOUT_MS=600000       # Inherits from FETCH_TIMEOUT_MS by default
+
+# ── API Bridge (/v1 proxy server) ──
+# API_BRIDGE_PROXY_TIMEOUT_MS=30000              # Proxy hop timeout (default: 30s)
+# API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS=300000     # Overall server request timeout
+# API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS=60000      # Time to send response headers
+# API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS=5000     # Keep-alive idle timeout
+# API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS=0           # Raw socket timeout (0 = disabled)
+
+# ── Graceful shutdown ──
+# Time to wait for in-flight requests before force-exiting on SIGTERM/SIGINT.
+# Used by: src/lib/gracefulShutdown.ts
+# Default: 30000 (30 seconds)
+# SHUTDOWN_TIMEOUT_MS=30000
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 16. LOGGING
+# ═══════════════════════════════════════════════════════════════════════════════
+# Used by: src/lib/logEnv.ts, src/lib/logRotation.ts, src/shared/utils/logger.ts
+
+# Application log level — controls console and file log verbosity.
+# Values: debug | info | warn | error  |  Default: info
 # APP_LOG_LEVEL=info
+
+# Log output format.
+# Values: text | json  |  Default: text
 # APP_LOG_FORMAT=text
+
+# Write logs to file in addition to stdout.
+# Default: true  |  Set false to disable file logging.
 APP_LOG_TO_FILE=true
+
+# Path to the application log file.
+# Default: logs/application/app.log (relative to project root / DATA_DIR)
 # APP_LOG_FILE_PATH=logs/application/app.log
+
+# Maximum single log file size before rotation.
+# Accepts: plain bytes or suffixed (50M, 1G, 512K). Default: 50M
 # APP_LOG_MAX_FILE_SIZE=50M
+
+# Days to keep rotated application log files before auto-deletion.
+# Default: 7
 # APP_LOG_RETENTION_DAYS=7
+
+# Maximum number of rotated log file backups to keep.
+# Default: 20
 # APP_LOG_MAX_FILES=20
+
+# How often OmniRoute checks whether the active log file has exceeded
+# APP_LOG_MAX_FILE_SIZE and triggers a rotation. Set lower for very verbose
+# services to prevent log files from growing large between checks.
+# Accepts milliseconds. Default: 60000 (1 minute)
+# APP_LOG_ROTATION_CHECK_INTERVAL_MS=60000
+
+# Days to keep request/call log entries in the database before auto-cleanup.
+# Default: 7
 # CALL_LOG_RETENTION_DAYS=7
+
+# Maximum call log entries stored in-memory buffer.
+# Default: 10000
 # CALL_LOG_MAX_ENTRIES=10000
 
-# ─────────────────────────────────────────────────────────────────────────────
-# Memory Optimization (Low-RAM configurations)
-# ─────────────────────────────────────────────────────────────────────────────
-# Node.js heap limit in MB (default: 256 for Docker, system default for npm)
+# Maximum rows in the call_logs SQLite table before oldest entries are pruned.
+# Default: 100000
+# CALL_LOGS_TABLE_MAX_ROWS=100000
+
+# Whether call log pipeline capture stores stream chunks when enabled in settings.
+# Only applies when call_log_pipeline_enabled=true.
+# Default: true
+# CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=true
+
+# Maximum call log artifact size for pipeline captures, in KB.
+# Only applies when call_log_pipeline_enabled=true.
+# Default: 512
+# CALL_LOG_PIPELINE_MAX_SIZE_KB=512
+
+# Maximum rows in the proxy_logs SQLite table.
+# Default: 100000
+# PROXY_LOGS_TABLE_MAX_ROWS=100000
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 17. MEMORY OPTIMIZATION (Low-RAM / Docker)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Node.js V8 heap limit in MB.
+# Used by: Docker entrypoint — sets --max-old-space-size.
+# Default: 256 (Docker) | system default (npm)
 # OMNIROUTE_MEMORY_MB=256
 
-# Prompt cache settings
-# PROMPT_CACHE_MAX_SIZE=50
-# PROMPT_CACHE_MAX_BYTES=2097152
-# PROMPT_CACHE_TTL_MS=300000
+# ── Prompt cache (system prompt deduplication) ──
+# Used by: open-sse/services — caches identical system prompts across requests.
+# PROMPT_CACHE_MAX_SIZE=50              # Max cached entries (default: 50)
+# PROMPT_CACHE_MAX_BYTES=2097152        # Max total cache size in bytes (default: 2 MB)
+# PROMPT_CACHE_TTL_MS=300000            # Cache entry TTL (default: 5 minutes)
 
-# Semantic cache settings (temperature=0 responses)
-# SEMANTIC_CACHE_MAX_SIZE=100
-# SEMANTIC_CACHE_MAX_BYTES=4194304
-# SEMANTIC_CACHE_TTL_MS=1800000
+# ── Semantic cache (deterministic response dedup, temperature=0) ──
+# Used by: open-sse/services — caches identical temperature=0 responses.
+# SEMANTIC_CACHE_MAX_SIZE=100            # Max cached entries (default: 100)
+# SEMANTIC_CACHE_MAX_BYTES=4194304       # Max total cache size in bytes (default: 4 MB)
+# SEMANTIC_CACHE_TTL_MS=1800000          # Cache entry TTL (default: 30 minutes)
 
-# In-memory log buffers
+# ── In-memory log buffers ──
+# Maximum recent stream events kept in memory for the Dashboard live view.
 # STREAM_HISTORY_MAX=50
+
+# ── Context length default ──
+# Global fallback max context length for models without explicit config.
+# Used by: open-sse/services/contextManager.ts
+# CONTEXT_LENGTH_DEFAULT=128000
+
+# ── Usage token buffer ──
+# Extra token headroom reserved when tracking usage quotas (prevents over-limit).
+# Used by: open-sse/utils/usageTracking.ts
+# USAGE_TOKEN_BUFFER=100
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 18. PRICING SYNC
+# ═══════════════════════════════════════════════════════════════════════════════
+# Automatic model pricing synchronization from external sources.
+# Used by: src/lib/pricingSync.ts
+
+# Enable periodic pricing data sync.  Default: false (opt-in only).
+# PRICING_SYNC_ENABLED=false
+
+# Sync interval in seconds.  Default: 86400 (24 hours).
+# PRICING_SYNC_INTERVAL=86400
+
+# Comma-separated data sources.  Default: litellm
+# PRICING_SYNC_SOURCES=litellm
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 19. MODEL SYNC (Dev)
+# ═══════════════════════════════════════════════════════════════════════════════
+# Development-time model catalog sync interval in seconds.
+# Used by: src/lib/modelsDevSync.ts
+# Default: 86400 (24 hours)
+# MODELS_DEV_SYNC_INTERVAL=86400
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 20. PROVIDER-SPECIFIC SETTINGS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# ── OpenRouter ──
+# OpenRouter model catalog cache TTL in ms.
+# Used by: src/lib/catalog/openrouterCatalog.ts
+# Default: 86400000 (24 hours)
+# OPENROUTER_CATALOG_TTL_MS=86400000
+
+# ── NanoBanana (Image Generation) ──
+# Polling config for async image generation jobs.
+# Used by: open-sse/handlers/imageGeneration.ts
+# NANOBANANA_POLL_TIMEOUT_MS=120000    # Max wait for job completion (default: 120s)
+# NANOBANANA_POLL_INTERVAL_MS=2500     # Poll frequency (default: 2.5s)
+
+# ── Cloudflare Workers AI ──
+# Account ID override for Cloudflare Workers AI executor.
+# Used by: open-sse/executors/cloudflare-ai.ts
+# CLOUDFLARE_ACCOUNT_ID=
+
+# ── Cloudflare Tunnel (cloudflared) ──
+# Custom path to cloudflared binary for tunnel management.
+# Used by: src/lib/cloudflaredTunnel.ts
+# CLOUDFLARED_BIN=/usr/local/bin/cloudflared
+
+# ── Search cache ──
+# TTL for search API response caching (Perplexity, Brave, etc.).
+# Used by: open-sse/services/searchCache.ts
+# Default: 300000 (5 minutes)
+# SEARCH_CACHE_TTL_MS=300000
+
+# ── OpenAI-compatible multi-connection ──
+# Allow multiple simultaneous connections per OpenAI-compatible provider node.
+# Used by: src/app/api/providers/route.ts
+# ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE=false
+
+# ── CC-compatible provider (experimental) ──
+# Enable the Claude Code compatible provider endpoint.
+# Used by: src/shared/utils/featureFlags.ts
+# ENABLE_CC_COMPATIBLE_PROVIDER=false
+
+# ── CLIProxyAPI bridge (legacy) ──
+# Connection settings for external CLIProxyAPI instances.
+# Used by: open-sse/executors/cliproxyapi.ts
+# CLIPROXYAPI_HOST=127.0.0.1
+# CLIPROXYAPI_PORT=5544
+# CLIPROXYAPI_CONFIG_DIR=~/.cli-proxy-api
+
+# ── Local hostnames (Docker networking) ──
+# Comma-separated additional hostnames treated as "local" for provider routing.
+# Used by: open-sse/config/providerRegistry.ts — allows Docker service names.
+# LOCAL_HOSTNAMES=omlx,mlx-audio
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 21. PROXY HEALTH
+# ═══════════════════════════════════════════════════════════════════════════════
+# Fine-tune proxy health checking behavior.
+# Used by: src/lib/proxyHealth.ts
+
+# Timeout for fast-fail health checks (ms).  Default: 2000
+# PROXY_FAST_FAIL_TIMEOUT_MS=2000
+
+# Health check result cache TTL (ms).  Default: 30000 (30s)
+# PROXY_HEALTH_CACHE_TTL_MS=30000
+
+# Rate limit maximum wait time before failing a request (ms).  Default: 120000 (2 min)
+# Used by: open-sse/services/rateLimitManager.ts
+# RATE_LIMIT_MAX_WAIT_MS=120000
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 22. DEBUGGING
+# ═══════════════════════════════════════════════════════════════════════════════
+# These variables enable verbose debugging output. NEVER enable in production.
+
+# Dump Cursor protobuf decode/encode details to console.
+# CURSOR_PROTOBUF_DEBUG=1
+
+# Dump raw Cursor SSE stream data to console.
+# CURSOR_STREAM_DEBUG=1
+
+# Log Responses API SSE-to-JSON translation details.
+# DEBUG_RESPONSES_SSE_TO_JSON=true
+
+# Enable E2E test mode — relaxes auth and enables test harness hooks.
+# NEXT_PUBLIC_OMNIROUTE_E2E_MODE=true
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 23. GITHUB INTEGRATION (Issue Reporting)
+# ═══════════════════════════════════════════════════════════════════════════════
+# Allow users to report issues directly from the Dashboard to GitHub.
+# Used by: src/app/api/v1/issues/report/route.ts
+
+# GitHub repository in owner/repo format.
+# GITHUB_ISSUES_REPO=owner/repo
+
+# GitHub Personal Access Token with issues:write scope.
+# GITHUB_ISSUES_TOKEN=ghp_xxxx

.github/CODEOWNERS

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

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -119,6 +119,20 @@ body:
     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:
@@ -143,3 +157,15 @@ body:
       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.ts
+        - npm run test:coverage
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -1,4 +1,4 @@
-blank_issues_enabled: true
+blank_issues_enabled: false
 contact_links:
   - name: Question / Help
     url: https://github.com/diegosouzapw/OmniRoute/discussions

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -33,6 +33,19 @@ body:
     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:
@@ -68,3 +81,16 @@ body:
       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.ts
+    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.ts
+        - 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/dependabot.yml

@@ -29,3 +29,19 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+
+  - package-ecosystem: "npm"
+    directory: "/electron"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "deps"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "deps"

.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/build-fork.yml

@@ -0,0 +1,41 @@
+name: Build Fork Image (ghcr.io)
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build:
+    name: Build and Push to ghcr.io
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: fix/claude-thinking-mapping
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          target: runner-base
+          platforms: linux/amd64
+          push: true
+          tags: |
+            ghcr.io/inkorcloud/omniroute:fix-claude-thinking-mapping
+            ghcr.io/inkorcloud/omniroute:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/ci.yml

@@ -5,6 +5,8 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+    types: [opened, synchronize, reopened, ready_for_review]
+  workflow_dispatch:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -13,6 +15,10 @@ concurrency:
 permissions:
   contents: read
 
+env:
+  CI_NODE_VERSION: "24"
+  CI_NODE_24_VERSION: "24"
+
 jobs:
   lint:
     name: Lint
@@ -21,9 +27,10 @@ jobs:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
       - run: npm ci
+      - run: npm run check:node-runtime
       - run: npm run lint
       - run: npm run check:cycles
       - run: npm run check:route-validation:t06
@@ -43,7 +50,7 @@ jobs:
         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
+          echo "langs=${LANGS}" >> "$GITHUB_OUTPUT"
 
   i18n:
     name: i18n Validation
@@ -56,7 +63,7 @@ jobs:
     needs: i18n-matrix
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6.2.0
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -66,111 +73,340 @@ jobs:
 
       - name: Upload result
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: i18n-${{ matrix.lang }}
           path: result.txt
 
-  security:
-    name: Security Audit
+  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
-          cache: npm
-      - run: npm ci
-      - name: Dependency audit
-        run: npm audit --audit-level=high --omit=dev || true
-      - name: Check for known vulnerabilities
-        run: npx is-my-node-vulnerable || true
+          node-version: ${{ env.CI_NODE_VERSION }}
+      - 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
 
   build:
     name: Build
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [20, 22]
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
       - run: npm ci
+      - run: npm run check:node-runtime
       - run: npm run build
 
-  test-unit:
-    name: Unit Tests
+  package-artifact:
+    name: Package Artifact
     runs-on: ubuntu-latest
     needs: build
+    env:
+      JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      - run: npm run check:node-runtime
+      - run: npm run build:cli
+      - run: npm run check:pack-artifact
+
+  electron-package-smoke:
+    name: Electron Package Smoke
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    needs: build
+    env:
+      JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
+      CSC_IDENTITY_AUTO_DISCOVERY: "false"
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      - run: npm run check:node-runtime
+      - run: npm run build
+      - name: Install Electron dependencies
+        working-directory: electron
+        run: npm install --no-audit --no-fund
+      - name: Pack Electron app
+        working-directory: electron
+        run: npm run pack
+      - name: Smoke packaged Electron app
+        env:
+          ELECTRON_SMOKE_TIMEOUT_MS: 60000
+        run: xvfb-run -a npm run electron:smoke:packaged
+
+  test-unit:
+    name: Unit Tests (${{ matrix.shard }}/2)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: build
     strategy:
+      fail-fast: false
       matrix:
-        node-version: [20, 22]
+        shard: [1, 2]
     env:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
       - run: npm ci
-      - run: npm run test:unit
+      - run: npm run check:node-runtime
+      - run: node --import tsx/esm --test --test-concurrency=1 --test-shard=${{ matrix.shard }}/2 tests/unit/*.test.ts
+
+  node-24-compat:
+    name: Node 24 Compatibility (${{ matrix.shard }}/2)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2]
+    env:
+      JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-test-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_24_VERSION }}
+          cache: npm
+      - run: npm ci
+      - run: npm run check:node-runtime
+      - run: npm run build
+      - run: node --import tsx/esm --test --test-concurrency=1 --test-shard=${{ matrix.shard }}/2 tests/unit/*.test.ts
 
   test-coverage:
     name: Coverage
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     needs: build
     env:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
       - run: npm ci
-      - run: npm run test:coverage
+      - run: npm run check:node-runtime
+      - name: Run coverage gate
+        run: npm run test:coverage
+      - name: Build coverage summary
+        if: always()
+        run: |
+          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@v7
+        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@v8
+        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@v8
+        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@v9
+        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 }}/6)
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4, 5, 6]
     env:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+      OMNIROUTE_PLAYWRIGHT_SKIP_BUILD: "1"
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
       - run: npm ci
+      - run: npm run check:node-runtime
       - 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 }}/6
 
   test-integration:
-    name: Integration Tests
+    name: Integration Tests (${{ matrix.shard }}/2)
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2]
     env:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
       INITIAL_PASSWORD: ci-test-password-for-integration
-      DATA_DIR: /tmp/omniroute-ci
+      DATA_DIR: /tmp/omniroute-ci-${{ matrix.shard }}
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
       - run: npm ci
-      - run: npm run test:integration
+      - run: npm run check:node-runtime
+      - run: node --import tsx/esm --test --test-shard=${{ matrix.shard }}/2 tests/integration/*.test.ts
 
   test-security:
     name: Security Tests
@@ -179,101 +415,116 @@ jobs:
     env:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
       - run: npm ci
+      - run: npm run check:node-runtime
       - run: npm run test:security
 
-  # 🔥 DASHBOARD
   ci-summary:
     name: CI Dashboard
     runs-on: ubuntu-latest
     if: always()
     needs:
       - lint
-      - security
+      - i18n
+      - pr-test-policy
+
       - build
+      - package-artifact
+      - electron-package-smoke
       - test-unit
+      - node-24-compat
       - test-coverage
+      - sonarqube
+      - coverage-pr-comment
       - test-e2e
       - test-integration
       - test-security
-      - i18n
-
     steps:
       - name: Download i18n results
+        continue-on-error: true
         uses: actions/download-artifact@v8
         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 "# 🚀 CI Dashboard" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
 
-          # 🔹 CORE
-          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 "| Security Audit | $(status '${{ needs.security.result }}') |" >> $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"
 
-          # 🔹 BUILD
-          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 "| SonarQube | $(status '${{ needs.sonarqube.result }}') |" >> "$GITHUB_STEP_SUMMARY"
 
-          # 🔹 TESTS
-          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 "| 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 "## 🏗️ 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 "| Package Artifact | $(status '${{ needs.package-artifact.result }}') |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Electron Package Smoke | $(status '${{ needs.electron-package-smoke.result }}') |" >> "$GITHUB_STEP_SUMMARY"
 
-          # 🔹 I18N
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "## 🌍 Translations" >> $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
 
-          for dir in results/*; do
-            file="$dir/result.txt"
-            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
+          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
+          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
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo "⚠️ **Translations need attention**" >> "$GITHUB_STEP_SUMMARY"
           else
-            echo "" >> $GITHUB_STEP_SUMMARY
-            echo "✅ **All translations complete**" >> $GITHUB_STEP_SUMMARY
+            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

@@ -36,13 +36,13 @@ jobs:
         uses: docker/setup-buildx-action@v4
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -61,7 +61,7 @@ jobs:
           echo "Publishing Docker image: $IMAGE_NAME:$VERSION"
 
       - name: Build and push multi-arch image
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
         with:
           context: .
           target: runner-base
@@ -83,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@v4
+        uses: peter-evans/dockerhub-description@v5
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}

.github/workflows/electron-release.yml

@@ -71,17 +71,15 @@ jobs:
             deb_ext: .deb
 
     steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-
-      - name: Setup Node.js
+      - uses: actions/checkout@v6
+      - name: Setup Node
         uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
 
       - name: Cache node_modules
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: node_modules
           key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
@@ -90,6 +88,18 @@ jobs:
 
       - name: Install dependencies
         run: npm ci
+        env:
+          NPM_CONFIG_LEGACY_PEER_DEPS: true
+
+      - name: Sanitize Windows home directory
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          # The default USERPROFILE contains junction points (Application Data)
+          # that cause EPERM errors during Next.js standalone build glob scans.
+          # Create a clean temp profile directory to avoid this.
+          mkdir -p "$RUNNER_TEMP/home"
+          echo "USERPROFILE=$RUNNER_TEMP/home" >> $GITHUB_ENV
 
       - name: Build Next.js standalone
         env:
@@ -123,6 +133,23 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: npm run build:${{ matrix.target }}
 
+      - name: Smoke packaged Electron app
+        if: matrix.platform != 'linux'
+        # Windows CI: requestSingleInstanceLock() fails due to USERPROFILE
+        # sanitization needed for the build step. Smoke is best-effort there.
+        continue-on-error: ${{ matrix.platform == 'windows' }}
+        env:
+          ELECTRON_SMOKE_TIMEOUT_MS: 60000
+          ELECTRON_SMOKE_STREAM_LOGS: "1"
+        run: npm run electron:smoke:packaged
+
+      - name: Smoke packaged Electron app (Linux)
+        if: matrix.platform == 'linux'
+        env:
+          ELECTRON_SMOKE_TIMEOUT_MS: 60000
+          ELECTRON_SMOKE_STREAM_LOGS: "1"
+        run: xvfb-run -a npm run electron:smoke:packaged
+
       - name: Collect installers
         shell: bash
         run: |
@@ -148,7 +175,7 @@ jobs:
           fi
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: electron-${{ matrix.platform }}
           path: release-assets/
@@ -186,7 +213,7 @@ jobs:
         run: ls -la release-assets/
 
       - name: Create Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ needs.validate.outputs.version }}
           draft: false

.github/workflows/npm-publish.yml

@@ -37,6 +37,9 @@ permissions:
   id-token: write
   packages: write
 
+env:
+  NPM_PUBLISH_NODE_VERSION: "24"
+
 jobs:
   publish:
     runs-on: ubuntu-latest
@@ -48,7 +51,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: ${{ env.NPM_PUBLISH_NODE_VERSION }}
           registry-url: https://registry.npmjs.org
 
       - name: Install dependencies (skip scripts to avoid heavy build)
@@ -88,7 +91,10 @@ jobs:
       - name: Build CLI bundle (standalone app)
         env:
           JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
-        run: node scripts/prepublish.mjs
+        run: npm run build:cli
+
+      - name: Validate npm package artifact
+        run: npm run check:pack-artifact
 
       - name: Publish to npm
         run: |

.gitignore

@@ -21,9 +21,11 @@ node_modules/
 !.yarn/releases
 !.yarn/versions
 .data/
+.next-playwright/
 
 # testing
 coverage/
+coverage**
 
 # next.js
 .next/
@@ -92,11 +94,17 @@ docs/*
 !docs/screenshots/
 !docs/i18n/
 !docs/i18n/**
+!docs/features/
+!docs/features/**
 !docs/A2A-SERVER.md
 !docs/AUTO-COMBO.md
 !docs/MCP-SERVER.md
 !docs/CLI-TOOLS.md
 !docs/COVERAGE_PLAN.md
+!docs/ENVIRONMENT.md
+!docs/UNINSTALL.md
+!docs/I18N.md
+!docs/FLY_IO_DEPLOYMENT_GUIDE.md
 
 
 # open-sse tests
@@ -110,6 +118,7 @@ test-results/
 playwright-report/
 blob-report/
 cloud/
+.tmp/
 
 # Security Analysis (standalone project with own git)
 security-analysis/
@@ -118,6 +127,7 @@ security-analysis/
 clipr/
 app.log
 *.tgz
+.gh-discussions.json
 
 # Backup directories
 app.__qa_backup/
@@ -158,4 +168,17 @@ typescript
 .gemini/
 
 # Superpowers plans/specs (internal tooling, not project code)
-docs/superpowers/
+docs/superpowers/
+
+# GitNexus local index
+.gitnexus
+.worktrees
+bin/omniroute.mjs
+
+# Consistent with .dockerignore / .npmignore
+.omc/
+audit-report.json
+bun.lock
+
+# Private environment variables for .http-client
+http-client.private.env.json

.husky/pre-commit

@@ -1,4 +1,10 @@
+#!/usr/bin/env sh
+if ! command -v npx >/dev/null 2>&1; then
+  echo "⚠️  npx not found in PATH — skipping pre-commit hooks"
+  echo "   Run 'npm run lint && npm run check:any-budget:t11' manually before pushing."
+  exit 0
+fi
+
 npx lint-staged
 node scripts/check-docs-sync.mjs
 npm run check:any-budget:t11
-npm run test:unit

.husky/pre-push

@@ -0,0 +1,8 @@
+#!/usr/bin/env sh
+if ! command -v npm >/dev/null 2>&1; then
+  echo "⚠️  npm not found in PATH — skipping pre-push hooks"
+  echo "   Run 'npm test' manually before pushing."
+  exit 0
+fi
+
+npm run test:unit

.node-version

@@ -0,0 +1 @@
+24

.npmignore

@@ -28,6 +28,8 @@ scripts/
 .vscode/
 .agents/
 .env*
+app/.env
+app/.env*
 eslint.config.mjs
 prettier.config.mjs
 postcss.config.mjs
@@ -67,3 +69,34 @@ clipr/
 omnirouteCloud/
 omnirouteSite/
 vscode-extension/
+
+# Root-level underscore-prefixed directories (private/draft — never publish)
+/_*/
+app/_*/
+app/coverage/
+app/logs/
+app/tests/
+
+# Consistent with .gitignore and .dockerignore
+.DS_Store
+.idea/
+.config/
+.data/
+.omnivscodeagent/
+.omc/
+*.sqlite-*
+*.tsbuildinfo
+security-analysis/
+.analysis/
+antigravity-manager-analysis/
+.sisyphus/
+.plans/
+app.__qa_backup/
+.app-build-backup-*/
+.gitnexus
+.worktrees
+.next-playwright/
+test-results/
+playwright-report/
+blob-report/
+coverage/

.npmrc

@@ -0,0 +1,4 @@
+# @lobehub/icons declares UI peers that are not needed by our deep icon imports.
+# Keeping peer auto-install disabled prevents npm from pulling @lobehub/ui/mermaid
+# back into the tree and reopening npm audit findings for unused packages.
+legacy-peer-deps=true

.nvmrc

@@ -0,0 +1 @@
+24

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

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

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

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

.vscode/settings.json

@@ -16,5 +16,6 @@
     "javascript:S3776": {
       "level": "off"
     }
-  }
+  },
+  "git.ignoreLimitWarning": true
 }

AGENTS.md

@@ -3,9 +3,10 @@
 ## Project
 
 Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support
-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**.
+with **160+ providers** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks,
+Cohere, NVIDIA, Cerebras, Pollinations, Puter, Cloudflare AI, HuggingFace, DeepInfra,
+SambaNova, Meta Llama API, Moonshot AI, AI21 Labs, Databricks, Snowflake, and many more)
+with **MCP Server** (29 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.
 
 ## Stack
 
@@ -14,7 +15,7 @@ with **MCP Server** (25 tools), **A2A v0.3 Protocol**, and **Electron desktop ap
 - **Database**: better-sqlite3 (SQLite) — `DATA_DIR` configurable, default `~/.omniroute/`
 - **Streaming**: SSE via `open-sse` internal workspace package
 - **Styling**: Tailwind CSS v4
-- **i18n**: next-intl with 30 languages
+- **i18n**: next-intl with 40+ languages
 - **Desktop**: Electron (cross-platform: Windows, macOS, Linux)
 - **Schemas**: Zod v4 for all API / MCP input validation
 
@@ -43,13 +44,13 @@ with **MCP Server** (25 tools), **A2A v0.3 Protocol**, and **Electron desktop ap
 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
+node --import tsx/esm --test tests/unit/your-file.test.ts
+node --import tsx/esm --test tests/unit/plan3-p0.test.ts
+node --import tsx/esm --test tests/unit/fixes-p1.test.ts
+node --import tsx/esm --test tests/unit/security-fase01.test.ts
 
 # Integration tests
-node --import tsx/esm --test tests/integration/*.test.mjs
+node --import tsx/esm --test tests/integration/*.test.ts
 
 # Vitest (MCP server, autoCombo)
 npm run test:vitest
@@ -63,10 +64,12 @@ npm run test:protocols:e2e
 # Ecosystem compatibility tests
 npm run test:ecosystem
 
-# Coverage (55% min thresholds — statements, lines, functions; 60% branches)
+# Coverage (see CONTRIBUTING.md)
 npm run test:coverage
 ```
 
+**For authoritative coverage requirements, test execution, and PR gates, see [`CONTRIBUTING.md`](CONTRIBUTING.md#running-tests).**
+
 ---
 
 ## Code Style Guidelines
@@ -128,13 +131,74 @@ All persistence uses SQLite through domain-specific modules:
 `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`.
+`cliToolState.ts`, `encryption.ts`, `readCache.ts`, `secrets.ts`, `stateReset.ts`,
+`contextHandoffs.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.
 
+#### DB Internals
+
+- **`core.ts`**: `getDbInstance()` returns a singleton `better-sqlite3` instance with WAL
+  journaling. `SCHEMA_SQL` defines 15 base tables. Helpers: `rowToCamel`, `encryptConnectionFields`.
+- **`migrationRunner.ts`**: Applies versioned SQL files from `db/migrations/` inside transactions.
+  Tracks applied migrations in `_omniroute_migrations` table.
+- **Migrations**: 21 files (`001_initial_schema.sql` → `021_combo_call_log_targets.sql`).
+  Each migration is idempotent and runs in a transaction.
+- **Domain modules** import `getDbInstance()` from `core.ts` for all CRUD operations.
+  Each module owns a specific table/set of tables (e.g., `providers.ts` → `provider_connections`,
+  `combos.ts` → `combos`). Encryption helpers protect sensitive fields at rest.
+- **`localDb.ts`** re-exports all domain modules — consumers import from here for convenience.
+
+### API Route Layer (`src/app/api/v1/`)
+
+Next.js App Router routes — each follows a consistent pattern:
+
+```
+Route → CORS preflight → Body validation (Zod) → Optional auth (extractApiKey/isValidApiKey)
+  → API key policy enforcement (enforceApiKeyPolicy) → Handler delegation (open-sse)
+```
+
+| Route                           | Handler                   | Notes                                     |
+| ------------------------------- | ------------------------- | ----------------------------------------- |
+| `chat/completions/route.ts`     | `handleChat()`            | + prompt injection guard (clones request) |
+| `responses/route.ts`            | `handleChat()` (unified)  | Responses API format                      |
+| `embeddings/route.ts`           | `handleEmbedding()`       | Model listing + creation                  |
+| `images/generations/route.ts`   | `handleImageGeneration()` | Model listing + creation                  |
+| `audio/transcriptions/route.ts` | audio handler             | Multipart form data                       |
+| `audio/speech/route.ts`         | TTS handler               | Binary audio response                     |
+| `videos/generations/route.ts`   | video handler             | ComfyUI/SD WebUI                          |
+| `music/generations/route.ts`    | music handler             | ComfyUI workflows                         |
+| `moderations/route.ts`          | moderation handler        | Content safety                            |
+| `rerank/route.ts`               | rerank handler            | Document relevance                        |
+| `search/route.ts`               | search handler            | Web search (5 providers)                  |
+
+**No global Next.js middleware file** — interception is route-specific. Auth is optional
+(controlled by `REQUIRE_API_KEY` env). Prompt injection guard is unique to chat completions.
+
 ### Request Pipeline (`open-sse/`)
 
-`chatCore.ts` → executor → upstream provider. Translations in `open-sse/translator/`.
+The `open-sse/` workspace is the core streaming engine. Full request flow:
+
+```
+Client Request
+  → src/app/api/v1/.../route.ts (Next.js route)
+    → open-sse/handlers/chatCore.ts::handleChatCore()
+      → Semantic/signature cache check
+      → Rate limit check (rateLimitManager)
+      → Combo routing? → open-sse/services/combo.ts::handleComboChat()
+        → resolveComboTargets() → ordered ResolvedComboTarget[]
+        → For each target: handleSingleModel() (wraps chatCore)
+      → translateRequest() (open-sse/translator/)
+        → Convert source format (e.g., OpenAI) → target format (e.g., Claude)
+      → getExecutor() → provider-specific executor instance
+        → executor.execute() (BaseExecutor → DefaultExecutor or provider-specific)
+          → buildUrl() + buildHeaders() + transformRequest()
+          → fetch() to upstream provider
+          → Retry logic with exponential backoff
+      → Response translation back to client format
+      → If Responses API: responsesTransformer.ts TransformStream
+  → SSE stream or JSON response to client
+```
 
 **Handlers** (`open-sse/handlers/`): `chatCore.ts`, `responsesHandler.ts`, `embeddings.ts`,
 `imageGeneration.ts`, `videoGeneration.ts`, `musicGeneration.ts`, `audioSpeech.ts`,
@@ -149,13 +213,21 @@ Zod schemas, and unit tests aligned when editing.
 
 - **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,
+- **API Key** (120+): 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.
+  Tavily, OpenCode Zen/Go, Bailian Coding Plan, DeepInfra, Vercel AI Gateway,
+  Lambda AI, SambaNova, nScale, OVHcloud AI, Baseten, PublicAI, Moonshot AI,
+  Meta Llama API, v0 (Vercel), Morph, Featherless AI, FriendliAI, LlamaGate,
+  Galadriel, Weights & Biases Inference, Volcengine, AI21 Labs, Venice.ai,
+  Codestral, Upstage, Maritalk, Xiaomi MiMo, Inference.net, NanoGPT, Predibase,
+  Bytez, Heroku AI, Databricks, Snowflake Cortex, GigaChat (Sber), CrofAI,
+  AgentRouter, ChatGPT Web, Baidu Qianfan, AWS Polly, RunwayML, GitLab Duo,
+  Amazon Q, Empower, Poe, and many more.
+- **Self-Hosted** (8+): LM Studio, vLLM, Lemonade, Llamafile, Triton, Docker Model Runner, Xinference, Oobabooga
 - **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.
@@ -166,15 +238,46 @@ Provider-specific request executors: `base.ts`, `default.ts`, `cursor.ts`, `code
 `antigravity.ts`, `github.ts`, `gemini-cli.ts`, `kiro.ts`, `qoder.ts`, `vertex.ts`,
 `cloudflare-ai.ts`, `opencode.ts`, `pollinations.ts`, `puter.ts`.
 
+#### Executor Internals
+
+- **`base.ts`** (`BaseExecutor`): Abstract base with `buildUrl()`, `buildHeaders()`,
+  `transformRequest()`, retry logic (exponential backoff), and `execute()`. Subclasses
+  override URL/header/transform methods for provider-specific behavior.
+- **`default.ts`** (`DefaultExecutor extends BaseExecutor`): Handles most OpenAI-compatible
+  providers. Reads provider config from `providerRegistry.ts` to resolve base URL, auth
+  header format, and request transformations.
+- **`getExecutor()`** (`executors/index.ts`): Factory that returns the correct executor
+  instance based on provider ID. Provider-specific executors (Cursor, Codex, Vertex, etc.)
+  override only what differs from the default.
+
 ### Translator (`open-sse/translator/`)
 
 Translates between API formats (OpenAI-format ↔ Anthropic, Gemini, etc.).
 Includes request/response translators with helpers for image handling.
 
+#### Translator Internals
+
+- **`translator/index.ts`**: Exports `translateRequest()` and format constants. Called by
+  `chatCore.ts` before executor dispatch.
+- **Flow**: `translateRequest(body, sourceFormat, targetFormat)` → detects source format
+  (OpenAI, Anthropic, Gemini) → applies the matching translator module → returns
+  transformed body ready for the target provider.
+- **Response translation** runs in reverse after upstream response, converting back to
+  the client's expected format.
+
 ### Transformer (`open-sse/transformer/`)
 
 `responsesTransformer.ts` — transforms Responses API format to/from Chat Completions format.
 
+#### Transformer Internals
+
+- **`createResponsesApiTransformStream()`**: Returns a `TransformStream` that converts
+  Chat Completions SSE chunks (`data: {"choices":[...]}`) into Responses API SSE events
+  (`response.output_item.added`, `response.output_text.delta`, etc.).
+- Used when the client sends a Responses API request: the request is internally converted
+  to Chat Completions format, dispatched normally, and the response is piped through this
+  transform stream before reaching the client.
+
 ### Services (`open-sse/services/`)
 
 36+ service modules including: `combo.ts` (routing engine), `usage.ts`, `tokenRefresh.ts`,
@@ -182,7 +285,18 @@ Includes request/response translators with helpers for image handling.
 `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.
+`signatureCache.ts`, `volumeDetector.ts`, `contextHandoff.ts`, and more.
+
+#### Combo Routing Engine (`combo.ts`)
+
+- **`handleComboChat()`**: Entry point for combo-routed requests. Receives the combo config
+  and iterates through targets in order until one succeeds or all fail.
+- **`resolveComboTargets()`**: Expands a combo configuration into an ordered array of
+  `ResolvedComboTarget[]`, each specifying provider + model + account + credentials.
+- **Strategies** (13): priority, weighted, fill-first, round-robin, P2C, random, least-used,
+  cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay.
+- Each target calls **`handleSingleModel()`** which wraps `handleChatCore()` with
+  per-target error handling and circuit breaker checks.
 
 ### Domain Layer (`src/domain/`)
 
@@ -192,23 +306,50 @@ Policy engine modules: `policyEngine.ts`, `comboResolver.ts`, `costRules.ts`,
 
 ### MCP Server (`open-sse/mcp-server/`)
 
-25 tools, 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (10 scopes), Zod schemas.
+29 tools, 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (10 scopes), Zod schemas.
 
-**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,
+**Core tools** (20): get_health, list_combos, get_combo_metrics, switch_combo, check_quota,
+route_request, cost_report, list_models_catalog, web_search, 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.
+best_combo_for_task, explain_route, get_session_snapshot, db_health_check, sync_pricing.
+
+**Cache tools** (2): cache_stats, cache_flush.
 
 **Memory tools** (3): memory_search, memory_add, memory_clear.
 
 **Skill tools** (4): skills_list, skills_enable, skills_execute, skills_executions.
 
+#### MCP Internals
+
+- **Tool registration**: Each tool is an object with `{ name, description, inputSchema: ZodSchema,
+handler: async (args) => {...} }`. Zod validates inputs before the handler fires.
+- **`createMcpServer()`** and **`startMcpStdio()`** exported from `mcp-server/index.ts`.
+  `createMcpServer()` wires all tool sets; `startMcpStdio()` launches the stdio transport.
+- **Transports**: stdio (CLI `omniroute --mcp`), SSE (`/api/mcp/sse`), Streamable HTTP
+  (`/api/mcp/stream`). All share the same tool/scope engine.
+- **Scopes** (10): Control which tool categories an API key can access. Enforcement happens
+  before handler dispatch.
+- **Audit**: Every tool invocation is logged to SQLite (`mcp_audit` table) with tool name,
+  args, success/failure, API key attribution, and timestamp.
+
 ### A2A Server (`src/lib/a2a/`)
 
-JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup(
+JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup.
 Agent Card at `/.well-known/agent.json`.
 Skills: `quotaManagement.ts`, `smartRouting.ts`.
 
+#### A2A Internals
+
+- **`taskManager.ts`**: State machine lifecycle for tasks: `submitted → working →
+completed | failed | canceled`. Tasks have TTL and are cleaned up automatically.
+- **JSON-RPC methods**: `message/send` (sync), `message/stream` (SSE), `tasks/get`,
+  `tasks/cancel`. Dispatched via `POST /a2a`.
+- **Skills**: Registered in a DB-backed registry. Each skill receives task context
+  (messages, metadata) and returns structured results. `quotaManagement.ts` summarizes
+  quota; `smartRouting.ts` recommends routing decisions.
+- **Agent Card**: `/.well-known/agent.json` exposes capabilities, skills, and metadata
+  for client auto-discovery.
+
 ### ACP Module (`src/lib/acp/`)
 
 Agent Communication Protocol registry and manager.
@@ -223,6 +364,19 @@ conversational memory across sessions.
 Extensible skill framework: registry, executor, sandbox, built-in skills,
 custom skill support, interception, and injection.
 
+#### Skills Internals
+
+- **`registry.ts`**: DB-backed skill registration and discovery. Skills have metadata
+  (name, description, version, enabled status) stored in SQLite.
+- **`executor.ts`**: Execution engine with configurable timeout and retry logic.
+  Receives skill name + input, looks up the skill, runs it in the sandbox.
+- **`sandbox.ts`**: Isolation layer for custom (user-provided) skills. Limits resource
+  access and execution time.
+- **Built-in skills**: Ship with OmniRoute (e.g., quota management, routing). Located
+  alongside the registry.
+- **Interception/Injection**: Skills can intercept requests in the pipeline (pre/post
+  processing) or inject context into prompts.
+
 ### Compliance (`src/lib/compliance/`)
 
 Policy index for compliance enforcement.
@@ -245,6 +399,14 @@ Request middleware including `promptInjectionGuard.ts`.
 
 ---
 
+## Subdirectory AGENTS.md Files
+
+- **[`open-sse/AGENTS.md`](open-sse/AGENTS.md)** — Streaming engine, request pipeline, handlers, and executors
+- **[`src/lib/db/AGENTS.md`](src/lib/db/AGENTS.md)** — SQLite persistence, domain modules, migrations
+- **[`open-sse/services/AGENTS.md`](open-sse/services/AGENTS.md)** — Routing engine, combo resolution, strategy selection
+
+---
+
 ## Review Focus
 
 - **DB ops** go through `src/lib/db/` modules, never raw SQL in routes

CLAUDE.md

@@ -0,0 +1,229 @@
+# CLAUDE.md — AI Agent Session Bootstrap
+
+> Quick-start context for AI coding agents. For deep architecture details, see `AGENTS.md`.
+> For contribution workflow, see `CONTRIBUTING.md`.
+
+## Quick Start
+
+```bash
+npm install                    # Install deps (auto-generates .env from .env.example)
+npm run dev                    # Dev server at http://localhost:20128
+npm run build                  # Production build (Next.js 16 standalone)
+npm run lint                   # ESLint (0 errors expected; warnings are pre-existing)
+npm run typecheck:core         # TypeScript check (should be clean)
+npm run typecheck:noimplicit:core  # Strict check (no implicit any)
+npm run test:coverage          # Unit tests + coverage gate (60% min)
+npm run check                  # lint + test combined
+npm run check:cycles           # Detect circular dependencies
+```
+
+### Running a Single Test
+
+```bash
+# Node.js native test runner (most tests)
+node --import tsx/esm --test tests/unit/your-file.test.mjs
+
+# Vitest (MCP server, autoCombo, cache)
+npm run test:vitest
+```
+
+---
+
+## Project at a Glance
+
+**OmniRoute** — unified AI proxy/router. One endpoint, 100+ LLM providers, auto-fallback.
+
+| Layer           | Location                 | Purpose                                    |
+| --------------- | ------------------------ | ------------------------------------------ |
+| API Routes      | `src/app/api/v1/`        | Next.js App Router — entry points          |
+| Handlers        | `open-sse/handlers/`     | Request processing (chat, embeddings, etc) |
+| Executors       | `open-sse/executors/`    | Provider-specific HTTP dispatch            |
+| Translators     | `open-sse/translator/`   | Format conversion (OpenAI↔Claude↔Gemini)   |
+| Services        | `open-sse/services/`     | Combo routing, rate limits, caching, etc   |
+| Database        | `src/lib/db/`            | SQLite domain modules (22 files)           |
+| Domain/Policy   | `src/domain/`            | Policy engine, cost rules, fallback logic  |
+| MCP Server      | `open-sse/mcp-server/`   | 25 tools, 3 transports, 10 scopes          |
+| A2A Server      | `src/lib/a2a/`           | JSON-RPC 2.0 agent protocol                |
+| Skills          | `src/lib/skills/`        | Extensible skill framework                 |
+| Memory          | `src/lib/memory/`        | Persistent conversational memory           |
+| UI Components   | `src/shared/components/` | React components (Tailwind CSS v4)         |
+| Provider Consts | `src/shared/constants/`  | Provider registry (Zod-validated)          |
+| Validation      | `src/shared/validation/` | Zod v4 schemas                             |
+| Tests           | `tests/`                 | Unit, integration, e2e, security, load     |
+
+### Monorepo Layout
+
+```
+OmniRoute/              # Root package
+├── src/                # Next.js 16 app (TypeScript)
+├── open-sse/           # @omniroute/open-sse workspace (streaming engine)
+├── electron/           # Desktop app (Electron)
+├── tests/              # All test suites
+├── docs/               # Documentation
+└── bin/                # CLI entry point
+```
+
+---
+
+## Request Pipeline (Abbreviated)
+
+```
+Client → /v1/chat/completions (Next.js route)
+  → CORS → Zod validation → auth? → policy check → prompt injection guard
+  → handleChatCore() [open-sse/handlers/chatCore.ts]
+    → cache check → rate limit → combo routing?
+      → resolveComboTargets() → handleSingleModel() per target
+    → translateRequest() → getExecutor() → executor.execute()
+      → fetch() upstream → retry w/ backoff
+    → response translation → SSE stream or JSON
+```
+
+---
+
+## Key Conventions
+
+### Code Style
+
+- **2 spaces**, semicolons, double quotes, 100 char width, es5 trailing commas
+- **Imports**: external → internal (`@/`, `@omniroute/open-sse`) → relative
+- **Naming**: files=camelCase/kebab, components=PascalCase, constants=UPPER_SNAKE
+
+### Database Access
+
+- **Always** go through `src/lib/db/` domain modules
+- **Never** write raw SQL in routes or handlers
+- **Never** add logic to `src/lib/localDb.ts` (re-export layer only)
+- **Never** barrel-import from `localDb.ts` — import specific `db/` modules
+- DB singleton: `getDbInstance()` from `src/lib/db/core.ts` (WAL journaling)
+- Migrations: `src/lib/db/migrations/` — 21 versioned SQL files
+
+### Error Handling
+
+- try/catch with specific error types, log with pino context
+- Never swallow errors in SSE streams — use abort signals
+- Return proper HTTP status codes (4xx/5xx)
+
+### Security
+
+- **Never** commit secrets/credentials
+- **Never** use `eval()`, `new Function()`, or implied eval
+- Validate all inputs with Zod schemas
+- Encrypt credentials at rest (AES-256-GCM)
+
+---
+
+## Common Modification Scenarios
+
+### Adding a New Provider
+
+1. Register in `src/shared/constants/providers.ts` (Zod-validated at load)
+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. Register models in `open-sse/config/providerRegistry.ts`
+6. Write tests in `tests/unit/` (registration, translation, error handling)
+
+### Adding a New API Route
+
+1. Create directory under `src/app/api/v1/your-route/`
+2. Create `route.ts` with `GET`/`POST` handlers
+3. Follow pattern: CORS → Zod body validation → optional auth → handler delegation
+4. Handler goes in `open-sse/handlers/` (import from there, not inline)
+5. Add tests
+
+### Adding a New DB Module
+
+1. Create `src/lib/db/yourModule.ts`
+2. Import `getDbInstance` from `./core.ts`
+3. Export CRUD functions for your domain table(s)
+4. Add migration in `src/lib/db/migrations/` if new tables needed
+5. Re-export from `src/lib/localDb.ts` (add to the re-export list only)
+6. Write tests
+
+### Adding a New MCP Tool
+
+1. Add tool definition in `open-sse/mcp-server/tools/`
+2. Define Zod input schema + async handler
+3. Register in tool set (wired by `createMcpServer()`)
+4. Assign to appropriate scope(s)
+5. Write tests (tool invocation logged to `mcp_audit` table)
+
+### Adding a New A2A Skill
+
+1. Create skill in `src/lib/a2a/skills/`
+2. Skill receives task context (messages, metadata) → returns structured result
+3. Register in the DB-backed skill registry
+4. Write tests
+
+---
+
+## Testing Cheat Sheet
+
+| What                    | Command                                                 |
+| ----------------------- | ------------------------------------------------------- |
+| All tests               | `npm run test:all`                                      |
+| Unit tests              | `npm run test:unit`                                     |
+| Single file             | `node --import tsx/esm --test tests/unit/file.test.mjs` |
+| Vitest (MCP, autoCombo) | `npm run test:vitest`                                   |
+| E2E (Playwright)        | `npm run test:e2e`                                      |
+| Protocol E2E (MCP+A2A)  | `npm run test:protocols:e2e`                            |
+| Ecosystem               | `npm run test:ecosystem`                                |
+| Coverage gate           | `npm run test:coverage` (60% min all metrics)           |
+| Coverage report         | `npm run coverage:report`                               |
+
+**PR rule**: If you change production code in `src/`, `open-sse/`, `electron/`, or `bin/`,
+you must include or update tests in the same PR.
+
+**Test layer preference**: unit first → integration (multi-module or DB state) → e2e (UI/workflow only). Encode bug reproductions as automated tests before or alongside the fix.
+
+---
+
+## Git Workflow
+
+```bash
+# Never commit directly to main
+git checkout -b feat/your-feature
+# ... make changes ...
+git commit -m "feat: describe your change"
+git push -u origin feat/your-feature
+```
+
+**Branch prefixes**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`
+
+**Commit format** ([Conventional Commits](https://www.conventionalcommits.org/)):
+
+```
+feat: add circuit breaker for provider calls
+fix: resolve JWT secret validation edge case
+docs: update AGENTS.md with pipeline internals
+test: add MCP tool unit tests
+refactor(db): consolidate rate limit tables
+```
+
+**Scopes**: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`,
+`memory`, `skills`.
+
+---
+
+## Environment
+
+- **Runtime**: Node.js ≥18 <24, ES Modules
+- **TypeScript**: 5.9, target ES2022, module esnext, resolution bundler
+- **Path aliases**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`
+- **Default port**: 20128 (API + dashboard on same port)
+- **Data directory**: `DATA_DIR` env var, defaults to `~/.omniroute/`
+- **Key env vars**: `PORT`, `JWT_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`
+
+---
+
+## Hard Rules (Never Violate)
+
+1. Never commit secrets or credentials
+2. Never add logic to `localDb.ts`
+3. Never use `eval()` / `new Function()` / implied eval
+4. Never commit directly to `main`
+5. Never write raw SQL in routes — use `src/lib/db/` modules
+6. Never silently swallow errors in SSE streams
+7. Always validate inputs with Zod schemas
+8. Always include tests when changing production code
+9. Coverage must stay ≥60% (statements, lines, functions, branches)

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -119,7 +119,7 @@ Scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`,
 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/your-file.test.ts
 
 # Vitest (MCP server, autoCombo, cache)
 npm run test:vitest
@@ -133,7 +133,7 @@ npm run test:protocols:e2e
 # Ecosystem compatibility tests
 npm run test:ecosystem
 
-# Coverage (55% min statements/lines/functions; 60% branches)
+# Coverage (60% min statements/lines/functions/branches)
 npm run test:coverage
 npm run coverage:report
 
@@ -145,10 +145,22 @@ npm run check
 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

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:22-bookworm-slim AS builder
+FROM node:24.15.0-trixie-slim AS builder
 WORKDIR /app
 
 RUN apt-get update \
@@ -7,13 +7,15 @@ RUN apt-get update \
 
 COPY package*.json ./
 COPY scripts/postinstall.mjs ./scripts/postinstall.mjs
+COPY scripts/postinstallSupport.mjs ./scripts/postinstallSupport.mjs
 COPY scripts/native-binary-compat.mjs ./scripts/native-binary-compat.mjs
+ENV NPM_CONFIG_LEGACY_PEER_DEPS=true
 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 -- --webpack
 
-FROM node:22-bookworm-slim AS runner-base
+FROM node:24.15.0-trixie-slim AS runner-base
 WORKDIR /app
 
 LABEL org.opencontainers.image.title="omniroute" \
@@ -44,6 +46,11 @@ COPY --from=builder /app/node_modules/@swc/helpers ./node_modules/@swc/helpers
 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
+# Migration SQL files are read via fs.readFileSync at runtime and are NOT
+# traced by Next.js standalone output — copy them explicitly.
+COPY --from=builder /app/src/lib/db/migrations ./migrations
+ENV OMNIROUTE_MIGRATIONS_DIR=/app/migrations
+
 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

GEMINI.md

@@ -0,0 +1,21 @@
+# Security and Cleanliness Rules for AI Assistants
+
+## 1. File Placement & Organization
+
+- **Test Files**: ALL unit tests, integration tests, ecosystem tests, or Vitest files MUST strictly be placed within the `tests/` directory (e.g., `tests/unit/`, `tests/integration/`). NEVER create test files in the project root (`/`).
+- **Scripts and Utilities**: ALL maintenance, debugging, generation, or experimental scripts (`.cjs`, `.mjs`, `.js`, `.ts`) MUST be placed strictly inside the `scripts/` directory or `scripts/scratch/` for temporary one-offs. NEVER dump loose scripts in the project root (`/`).
+
+**The Project Root MUST ONLY CONTAIN:**
+
+- Configuration files (`vitest.config.ts`, `next.config.mjs`, `eslint.config.mjs`, etc.)
+- Dependency files (`package.json`, `package-lock.json`)
+- Documentation files (`README.md`, `CHANGELOG.md`, `AGENTS.md`)
+- CI/CD files and ignore definitions (`.gitignore`, `.dockerignore`)
+
+When creating _any_ validation tests or one-off logic scripts, default to using `scripts/scratch/` or the `tests/unit/` directories according to your goals. Do not pollute the `/` root context.
+
+## 2. VPS Dashboard Credentials
+
+| Environment | URL                       | Password |
+| ----------- | ------------------------- | -------- |
+| Local VPS   | http://192.168.0.15:20128 | 123456   |

README.md

@@ -2,7 +2,7 @@
 
 ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
 
-_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
+_Your universal API proxy — one endpoint, 160+ providers, zero downtime. Now with **MCP Server (29 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
 
 **Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
 
@@ -243,7 +243,9 @@ Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve
 - **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention
 - **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI
 - **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next
-- **Custom Combos** — Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random)
+- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)
+- **Structured Combo Builder** — Build combos with guided steps or expert single-page editing, including explicit provider + model + account selection, repeated providers, fixed-account targets, and direct model entry
+- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use
 - **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
 
 </details>
@@ -255,7 +257,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If
 
 **How OmniRoute solves it:**
 
-- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 60+ providers
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 160+ providers
 - **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
 - **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+
 - **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE
@@ -322,12 +324,13 @@ AI providers can become unstable, return 5xx errors, or hit temporary rate limit
 
 **How OmniRoute solves it:**
 
-- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks
-- **Exponential Backoff** — Progressive retry delays
+- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps
+- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff
+- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown
+- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically
 - **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms
 - **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention
-- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain
-- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
+- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency
 
 </details>
 
@@ -341,7 +344,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code..
 - **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
 - **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection
 - **Onboarding Wizard** — Guided 4-step setup for first-time users
-- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 60+ providers
+- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 160+ providers
 
 </details>
 
@@ -385,10 +388,10 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w
 
 - **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console
 - **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter
-- **SQLite Proxy Logs** — Persistent logs that survive server restarts
+- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite
 - **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)
 - **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing
-- **File-Based Logging with Rotation** — App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count
+- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries
 - **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.
 
 </details>
@@ -417,9 +420,9 @@ Teams in non-English-speaking countries, especially in Latin America, Asia, and
 
 **How OmniRoute solves it:**
 
-- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English
-- **RTL Support** — Right-to-left support for Arabic and Hebrew
-- **Multi-Language READMEs** — 30 complete documentation translations
+- **Dashboard i18n — 40+ Languages** — All 500+ keys translated including Arabic, Bengali, Bulgarian, Czech, Danish, German, Spanish, Persian, Finnish, French, Gujarati, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Marathi, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Swahili, Tamil, Telugu, Thai, Turkish, Ukrainian, Urdu, Vietnamese, Chinese, Filipino, English
+- **RTL Support** — Right-to-left support for Arabic, Persian, Hebrew, and Urdu
+- **Multi-Language READMEs** — 40+ complete documentation translations
 - **Language Selector** — Globe icon in header for real-time switching
 
 </details>
@@ -468,7 +471,7 @@ As request volume grows, without caching the same questions generate duplicate c
 - **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency
 - **Request Idempotency** — 5s deduplication window for identical requests
 - **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking
-- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence
+- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience
 - **API Key Validation Cache** — 3-tier cache for production performance
 - **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
 
@@ -486,6 +489,7 @@ Developers who want all responses in a specific language, with a specific tone,
 - **9 Routing Strategies** — Global strategies that determine how requests are distributed
 - **Wildcard Router** — `provider/*` patterns route dynamically to any provider
 - **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
 - **Provider Toggle** — Enable/disable all connections for a provider with one click
 - **Blocked Providers** — Exclude specific providers from `/v1/models` listing
 
@@ -564,8 +568,8 @@ Teams need quick runtime changes during incidents or cost events.
 **How OmniRoute solves it:**
 
 - Switch combo activation directly from MCP dashboard
-- Apply resilience profiles from pre-defined policy packs
-- Reset circuit breaker state from the same operations panel
+- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page
+- Review live provider breaker state from the Health dashboard
 
 </details>
 
@@ -673,13 +677,26 @@ Teams lose velocity when stitching multiple ad-hoc services and scripts.
 
 </details>
 
+<details>
+<summary><b>📚 31. "My long sessions crash with 'context_length_exceeded' limits"</b></summary>
+
+During deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.
+
+**How OmniRoute solves it:**
+
+- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.
+- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.
+- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.
+
+</details>
+
 ### Example Playbooks (Integrated Use Cases)
 
 **Playbook A: Maximize paid subscription + cheap backup**
 
 ```txt
 Combo: "maximize-claude"
-  1. cc/claude-opus-4-6
+  1. cc/claude-opus-4-7
   2. glm/glm-4.7
   3. if/kimi-k2-thinking
 
@@ -703,7 +720,7 @@ Outcome: stable free coding workflow
 
 ```txt
 Combo: "always-on"
-  1. cc/claude-opus-4-6
+  1. cc/claude-opus-4-7
   2. cx/gpt-5.2-codex
   3. glm/glm-4.7
   4. minimax/MiniMax-M2.1
@@ -758,6 +775,15 @@ omniroute
 
 Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
 
+#### Arch Linux (AUR)
+
+Arch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:
+
+```bash
+yay -S omniroute-bin
+systemctl --user enable --now omniroute.service
+```
+
 | Command                 | Description                                                 |
 | ----------------------- | ----------------------------------------------------------- |
 | `omniroute`             | Start server (`PORT=20128`, API and dashboard on same port) |
@@ -774,22 +800,40 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
 # Dashboard: http://localhost:20129
 ```
 
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command                  | Action                                                                              |
+| ------------------------ | ----------------------------------------------------------------------------------- |
+| `npm run uninstall`      | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`.  |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
 ### Long-Running Streaming Timeouts
 
 For most deployments, you only need:
 
-| Variable                 | Default                       | Purpose                                                                                                                     |
-| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `REQUEST_TIMEOUT_MS`     | `600000`                      | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |
-| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream                                                 |
+| Variable                 | Default                       | Purpose                                                                                                                                      |
+| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `REQUEST_TIMEOUT_MS`     | `600000`                      | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |
+| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream                                                                  |
 
 Backward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.
 
+For Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.
+
+For third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default
+`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,
+only forwards client-provided `cache_control` markers. If the request does not include
+`cache_control`, OmniRoute does not inject bridge-owned markers.
+
 Advanced overrides are available if you need finer control:
 
 | Variable                                 | Default                                    | Purpose                                                              |
 | ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |
-| `FETCH_TIMEOUT_MS`                       | inherits `REQUEST_TIMEOUT_MS`              | Total upstream request timeout used by the main fetch abort signal   |
+| `FETCH_TIMEOUT_MS`                       | inherits `REQUEST_TIMEOUT_MS`              | Upstream response-start timeout used until response headers arrive   |
 | `FETCH_HEADERS_TIMEOUT_MS`               | inherits `FETCH_TIMEOUT_MS`                | Undici time limit for receiving upstream response headers            |
 | `FETCH_BODY_TIMEOUT_MS`                  | inherits `FETCH_TIMEOUT_MS`                | Undici time limit between upstream body chunks (`0` disables it)     |
 | `FETCH_CONNECT_TIMEOUT_MS`               | `30000`                                    | Undici TCP connect timeout                                           |
@@ -801,6 +845,8 @@ Advanced overrides are available if you need finer control:
 | `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000`                                     | Keep-alive timeout on the API bridge server                          |
 | `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS`    | `0`                                        | Socket inactivity timeout on the API bridge server (`0` disables it) |
 
+For streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).
+
 If you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy
 timeouts are also higher than your OmniRoute stream/fetch timeouts.
 
@@ -954,7 +1000,7 @@ do_install() {
 #!/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}"
+export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
 mkdir -p "${DATA_DIR}"
 exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
 EOF
@@ -1057,7 +1103,7 @@ volumes:
 | Image                    | Tag      | Size   | Description           |
 | ------------------------ | -------- | ------ | --------------------- |
 | `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |
-| `diegosouzapw/omniroute` | `1.0.3`  | ~250MB | Current version       |
+| `diegosouzapw/omniroute` | `3.6.2`  | ~250MB | Current version       |
 
 ---
 
@@ -1114,6 +1160,7 @@ When minimized, OmniRoute lives in your system tray with quick actions:
 |                     | xAI Grok-4 (standard)       | $0.20/$1.50 per 1M 🆕     | None             | Reasoning flagship from xAI       |
 |                     | Mistral                     | Free trial + paid         | Rate limited     | European AI                       |
 |                     | OpenRouter                  | Pay-per-use               | None             | 100+ models aggr.                 |
+|                     | AgentRouter 🆕              | Pay-per-use               | None             | $200 free credits at signup       |
 | **💰 CHEAP**        | GLM-5 (via Z.AI) 🆕         | $0.5/1M                   | Daily 10AM       | 128K output, newest flagship      |
 |                     | GLM-4.7                     | $0.6/1M                   | Daily 10AM       | Budget backup                     |
 |                     | MiniMax M2.5 🆕             | $0.3/1M input             | 5-hour rolling   | Reasoning + agentic tasks         |
@@ -1304,7 +1351,32 @@ Then in `/dashboard/media` → **Transcription** tab: upload any audio or video
 
 ## 💡 Key Features
 
-OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
+OmniRoute v3.6 is built as an operational platform, not just a relay proxy.
+
+### 🆕 New — v3.6.x Highlights (Apr 2026)
+
+| Feature                            | What It Does                                                                                                                                      |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🌐 **V1 WebSocket Bridge**         | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie)      |
+| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling                            |
+| 🧠 **GLM Thinking (glmt) Preset**  | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API        |
+| 🔢 **Hybrid Token Counting**       | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing                   |
+| 🌱 **Model Alias Auto-Seed**       | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches                                                                |
+| 🛡️ **Safe Outbound Fetch**         | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |
+| ⏳ **Wait For Cooldown**           | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec`             |
+| 🔍 **Runtime Env Validation**      | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types                                  |
+| 📋 **Compliance Audit Expansion**  | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging                    |
+| 🔐 **TPS Log Metric**              | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request                                                 |
+| 🗑️ **Uninstall / Full Uninstall**  | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods                               |
+| 🔧 **OAuth Env Repair**            | One-click "Repair env" action for OAuth providers restores missing env vars and fixes broken auth state                                           |
+| 🔒 **Graceful Electron Shutdown**  | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close                                       |
+| 👁️ **Model Visibility Toggle**     | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages                                  |
+| 📧 **Email Privacy Masking**       | OAuth account emails masked (`di*****@g****.com`), full address visible on hover                                                                  |
+| 🔗 **Context Relay Strategy**      | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation                               |
+| 🛡️ **Proxy Hardening**             | Token health check, API key validation, and undici dispatcher all honor proxy config                                                              |
+| ⚠️ **Node.js 24 Login Warning**    | Login page proactively detects incompatible Node.js versions and shows a clear warning banner                                                     |
+| 📎 **Gemini PDF Attachments**      | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection                                                         |
+| 🔒 **CodeQL Security Hardening**   | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts                                                      |
 
 ### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)
 
@@ -1333,19 +1405,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 
 ### 🤖 Agent & Protocol Operations (v2.0)
 
-| Feature                               | What It Does                                                                                                                           |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| 🔧 **MCP Server (25 tools)**          | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |
-| 🤝 **A2A Server (JSON-RPC + SSE)**    | Agent-to-agent task execution with sync and streaming flows                                                                            |
-| 🧭 **Consolidated Endpoints Page**    | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs                                                           |
-| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF)                                                               |
-| 🛰️ **MCP Runtime Heartbeat**          | Real process status (pid, uptime, heartbeat age, transport, scope mode)                                                                |
-| 📋 **MCP Audit Trail**                | Filterable audit logs with success/failure and key attribution                                                                         |
-| 🔐 **MCP Scope Enforcement**          | 10 granular scope permissions for controlled tool access                                                                               |
-| 📡 **A2A Task Lifecycle Management**  | List/filter tasks, inspect events/artifacts, cancel running tasks                                                                      |
-| 📋 **Agent Card Discovery**           | `/.well-known/agent.json` for client auto-discovery                                                                                    |
-| 🧪 **Protocol E2E Test Harness**      | Real MCP SDK + A2A client flows in `test:protocols:e2e`                                                                                |
-| ⚙️ **Operational Controls**           | Switch combo, apply resilience profiles, reset breakers from one control surface                                                       |
+| Feature                               | What It Does                                                                                                                                     |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 🔧 **MCP Server (29 tools)**          | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 20 core + 2 cache + 3 memory + 4 skill tools |
+| 🤝 **A2A Server (JSON-RPC + SSE)**    | Agent-to-agent task execution with sync and streaming flows                                                                                      |
+| 🧭 **Consolidated Endpoints Page**    | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs                                                                     |
+| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF)                                                                         |
+| 🛰️ **MCP Runtime Heartbeat**          | Real process status (pid, uptime, heartbeat age, transport, scope mode)                                                                          |
+| 📋 **MCP Audit Trail**                | Filterable audit logs with success/failure and key attribution                                                                                   |
+| 🔐 **MCP Scope Enforcement**          | 10 granular scope permissions for controlled tool access                                                                                         |
+| 📡 **A2A Task Lifecycle Management**  | List/filter tasks, inspect events/artifacts, cancel running tasks                                                                                |
+| 📋 **Agent Card Discovery**           | `/.well-known/agent.json` for client auto-discovery                                                                                              |
+| 🧪 **Protocol E2E Test Harness**      | Real MCP SDK + A2A client flows in `test:protocols:e2e`                                                                                          |
+| ⚙️ **Operational Controls**           | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces                                    |
 
 ### 🧠 Routing & Intelligence
 
@@ -1356,7 +1428,8 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 | 🔄 **Format Translation**          | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions        |
 | 👥 **Multi-Account Support**       | Multiple accounts per provider with intelligent selection                |
 | 🔄 **Auto Token Refresh**          | OAuth tokens refresh automatically with retry                            |
-| 🎨 **Custom Combos**               | 9 balancing strategies + fallback chain control                          |
+| 🎨 **Custom Combos**               | 13 balancing strategies + fallback chain control                         |
+| 🔗 **Context Relay**               | Session continuity handoffs when account rotation happens mid-session    |
 | 🌐 **Wildcard Router**             | `provider/*` dynamic routing                                             |
 | 🧠 **Thinking Budget Controls**    | Passthrough, auto, custom, and adaptive reasoning limits                 |
 | 🔀 **Model Aliases**               | Built-in + custom model aliasing and migration safety                    |
@@ -1384,31 +1457,38 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 
 ### 🛡️ Resilience, Security & Governance
 
-| Feature                             | What It Does                                                                           |
-| ----------------------------------- | -------------------------------------------------------------------------------------- |
-| 🔌 **Circuit Breakers**             | Per-model trip/recover with threshold controls                                         |
-| 🎯 **Endpoint-Aware Models**        | Custom models declare supported endpoints + API format                                 |
-| 🛡️ **Anti-Thundering Herd**         | Mutex + semaphore protections on retry/rate events                                     |
-| 🧠 **Semantic + Signature Cache**   | Cost/latency reduction with two cache layers                                           |
-| ⚡ **Request Idempotency**          | Duplicate protection window                                                            |
-| 🔒 **TLS Fingerprint Spoofing**     | Browser-like TLS fingerprint — **reduces bot detection and account flagging**          |
-| 🔏 **CLI Fingerprint Matching**     | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
-| 🌐 **IP Filtering**                 | Allowlist/blocklist control for exposed deployments                                    |
-| 📊 **Editable Rate Limits**         | Configurable global/provider-level limits with persistence                             |
-| 📉 **Graceful Degradation**         | Multi-layer capability fallbacks protecting core gateway operations                    |
-| 📜 **Config Audit Trail**           | Diff-based change tracking preventing operational drift with simple rollbacks          |
-| ⏳ **Provider Health Sync**         | Proactive token expiration monitoring triggering alerts before authorization failures  |
-| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically   |
-| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls                               |
-| 👁️ **Scoped API Key Reveal** 🆕     | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL`                                 |
-| 🛡️ **Protected `/models`**          | Optional auth gating and provider hiding for model catalog                             |
+| Feature                             | What It Does                                                                                            |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 🔌 **Provider Circuit Breakers**    | Provider-wide trip/recover after fallback exhaustion with configurable thresholds                       |
+| 🔒 **Daily Quota Lock** 🆕          | Detects exhaustion signals and locks routing for the specific model until midnight                      |
+| 🎯 **Endpoint-Aware Models**        | Custom models declare supported endpoints + API format                                                  |
+| 🛡️ **Anti-Thundering Herd**         | Mutex + semaphore protections on retry/rate events                                                      |
+| 🧠 **Semantic + Signature Cache**   | Cost/latency reduction with two cache layers                                                            |
+| ⚡ **Request Idempotency**          | Duplicate protection window                                                                             |
+| 🔒 **TLS Fingerprint Spoofing**     | Browser-like TLS fingerprint — **reduces bot detection and account flagging**                           |
+| 🔏 **CLI Fingerprint Matching**     | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP**                  |
+| 🌐 **IP Filtering**                 | Allowlist/blocklist control for exposed deployments                                                     |
+| 🚦 **Request Queue & Pacing**       | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait                 |
+| 📉 **Graceful Degradation**         | Multi-layer capability fallbacks protecting core gateway operations                                     |
+| 📜 **Config Audit Trail**           | Diff-based change tracking preventing operational drift with simple rollbacks                           |
+| ⏳ **Provider Health Sync**         | Proactive token expiration monitoring triggering alerts before authorization failures                   |
+| ❄️ **Connection Cooldown**          | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints               |
+| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically                                        |
+| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls                                                |
+| 👁️ **Scoped API Key Reveal** 🆕     | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL`                                                  |
+| 🛡️ **Protected `/models`**          | Optional auth gating and provider hiding for model catalog                                              |
+| 🛡️ **Safe Outbound Fetch** 🆕       | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection                  |
+| ⏳ **Wait For Cooldown** 🆕         | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |
+| 🔍 **Runtime Env Validation** 🆕    | Zod-based env schema validation at startup with actionable error messages                               |
+| 📋 **Compliance Audit v2** 🆕       | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging                       |
 
 ### 📊 Observability & Analytics
 
 | Feature                          | What It Does                                          |
 | -------------------------------- | ----------------------------------------------------- |
 | 📝 **Request + Proxy Logging**   | Full request/response and proxy logging               |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI  |
+| 📉 **Streamed Detailed Logs**    | Reconstructs SSE payload streams cleanly into the UI  |
+| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers    |
 | 📋 **Unified Logs Dashboard**    | Request, proxy, audit, and console views in one page  |
 | 🔍 **Request Telemetry**         | p50/p95/p99 latency and request tracing               |
 | 🏥 **Health Dashboard**          | Uptime, breaker states, lockouts, cache stats         |
@@ -1416,6 +1496,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 | 📈 **Analytics Visualizations**  | Model/provider usage insights and trend views         |
 | 🧪 **Evaluation Framework**      | Golden set testing with configurable match strategies |
 | 📡 **Live Diagnostics** 🆕       | Semantic cache bypass for accurate combo live testing |
+| 🔐 **TPS Log Metric** 🆕         | Tokens Per Second badge in log details modal          |
 
 ### ☁️ Deployment & Platform
 
@@ -1430,11 +1511,13 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 | 🔧 **CLI Tools Dashboard**     | One-click setup for popular coding tools                              |
 | 🎮 **Model Playground**        | Test any provider/model/endpoint from the dashboard                   |
 | 🔏 **CLI Fingerprint Toggle**  | Per-provider fingerprint matching in Settings > Security              |
-| 🌐 **i18n (30 languages)**     | Full dashboard + docs language support with RTL coverage              |
+| 🌐 **i18n (40+ languages)**    | Full dashboard + docs language support with RTL coverage              |
 | 🧹 **Clear All Models**        | One-click model list clearing in provider details                     |
 | 👁️ **Sidebar Controls** 🆕     | Hide components and integrations from Appearance Settings             |
 | 📋 **Issue Templates**         | Standardized GitHub templates for bugs and features                   |
 | 📂 **Custom Data Directory**   | `DATA_DIR` override for storage location                              |
+| 🌐 **V1 WebSocket Bridge** 🆕  | OpenAI-compatible WebSocket traffic proxied via `/v1/ws`              |
+| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support      |
 
 ### Feature Deep Dive
 
@@ -1442,7 +1525,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 
 ```txt
 Combo: "my-coding-stack"
-  1. cc/claude-opus-4-6
+  1. cc/claude-opus-4-7
   2. nvidia/llama-3.3-70b
   3. glm/glm-4.7
   4. if/kimi-k2-thinking
@@ -1581,7 +1664,7 @@ Dashboard → Providers → Connect Claude Code
 → 5-hour + weekly quota tracking
 
 Models:
-  cc/claude-opus-4-6
+  cc/claude-opus-4-7
   cc/claude-sonnet-4-5-20250929
   cc/claude-haiku-4-5-20251001
 ```
@@ -1688,6 +1771,16 @@ Models:
 
 **Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.
 
+### Baidu Qianfan / ERNIE
+
+1. Sign up: [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop)
+2. Create a Qianfan API key
+3. Dashboard → Add Provider → Baidu Qianfan
+
+**Use:** `qianfan/ernie-4.5-turbo-128k`, `qianfan/ernie-x1-turbo-32k`, or any Qianfan OpenAI-compatible model ID.
+
+**Dashboard behavior:** Qianfan is registered as an OpenAI-compatible API key provider. Built-in ERNIE models are available immediately, and passthrough model IDs are accepted for newer Qianfan deployments.
+
 </details>
 
 <details>
@@ -1781,7 +1874,7 @@ Dashboard → Combos → Create New
 
 Name: premium-coding
 Models:
-  1. cc/claude-opus-4-6 (Subscription primary)
+  1. cc/claude-opus-4-7 (Subscription primary)
   2. glm/glm-4.7 (Cheap backup, $0.6/1M)
   3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
 
@@ -1811,7 +1904,7 @@ Cost: $0 forever!
 Settings → Models → Advanced:
   OpenAI API Base URL: http://localhost:20128/v1
   OpenAI API Key: [from OmniRoute dashboard]
-  Model: cc/claude-opus-4-6
+  Model: cc/claude-opus-4-7
 ```
 
 ### Claude Code
@@ -1921,7 +2014,7 @@ opencode
 **Rate limiting**
 
 - Subscription quota out → Fallback to GLM/MiniMax
-- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`
 
 **OAuth token expired**
 
@@ -1954,8 +2047,11 @@ opencode
 
 **No request logs**
 
-- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request
+- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views
+- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request
 - Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads
+- When pipeline capture is enabled, `CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=false` skips stream chunks and `CALL_LOG_PIPELINE_MAX_SIZE_KB` controls the artifact cap in KB
+- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`
 - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`
 - Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed
 
@@ -2161,7 +2257,7 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
 - **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)
 - **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)
 - **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)
+- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills
 - **Schemas**: Zod (MCP tool I/O validation, API contracts)
 - **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)
 - **Streaming**: Server-Sent Events (SSE)
@@ -2179,36 +2275,40 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
 
 ## 📖 Documentation
 
-| Document                                       | Description                                         |
-| ---------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md)               | Providers, combos, CLI integration, deployment      |
-| [API Reference](docs/API_REFERENCE.md)         | All endpoints with examples                         |
-| [MCP Server](open-sse/mcp-server/README.md)    | 16 MCP tools, IDE configs, Python/TS/Go clients     |
-| [A2A Server](src/lib/a2a/README.md)            | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/auto-combo.md)        | 6-factor scoring, mode packs, self-healing          |
-| [Troubleshooting](docs/TROUBLESHOOTING.md)     | Common problems and solutions                       |
-| [Architecture](docs/ARCHITECTURE.md)           | System architecture and internals                   |
-| [Contributing](CONTRIBUTING.md)                | Development setup and guidelines                    |
-| [OpenAPI Spec](docs/openapi.yaml)              | OpenAPI 3.0 specification                           |
-| [Security Policy](SECURITY.md)                 | Vulnerability reporting and security practices      |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md)   | Complete guide: VM + nginx + Cloudflare setup       |
-| [Features Gallery](docs/FEATURES.md)           | Visual dashboard tour with screenshots              |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps                        |
+| Document                                                 | Description                                         |
+| -------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md)                         | Providers, combos, CLI integration, deployment      |
+| [API Reference](docs/API_REFERENCE.md)                   | All endpoints with examples                         |
+| [MCP Server](open-sse/mcp-server/README.md)              | 29 MCP tools, IDE configs, Python/TS/Go clients     |
+| [A2A Server](src/lib/a2a/README.md)                      | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/AUTO-COMBO.md)                  | 6-factor scoring, mode packs, self-healing          |
+| [Context Relay](docs/features/context-relay.md)          | Session handoff strategy for account rotation       |
+| [Troubleshooting](docs/TROUBLESHOOTING.md)               | Common problems and solutions                       |
+| [Architecture](docs/ARCHITECTURE.md)                     | System architecture and internals                   |
+| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough              |
+| [Uninstall Guide](docs/UNINSTALL.md)                     | Clean removal for all install methods               |
+| [Environment Config](docs/ENVIRONMENT.md)                | Complete `.env` variables and references            |
+| [Contributing](CONTRIBUTING.md)                          | Development setup and guidelines                    |
+| [OpenAPI Spec](docs/openapi.yaml)                        | OpenAPI 3.0 specification                           |
+| [Security Policy](SECURITY.md)                           | Vulnerability reporting and security practices      |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md)             | Complete guide: VM + nginx + Cloudflare setup       |
+| [Features Gallery](docs/FEATURES.md)                     | Visual dashboard tour with screenshots              |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md)           | Pre-release validation steps                        |
 
 ---
 
 ## 🗺️ Roadmap
 
-OmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:
+OmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:
 
-| Category                      | Planned Features | Highlights                                                                             |
-| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |
-| 🧠 **Routing & Intelligence** | 25+              | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection      |
-| 🔒 **Security & Compliance**  | 20+              | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping   |
-| 📊 **Observability**          | 15+              | OpenTelemetry integration, real-time quota monitoring, cost tracking per model         |
-| 🔄 **Provider Integrations**  | 20+              | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |
-| ⚡ **Performance**            | 15+              | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API         |
-| 🌐 **Ecosystem**              | 10+              | WebSocket API, config hot-reload, distributed config store, commercial mode            |
+| Category                      | Planned Features | Highlights                                                                                            |
+| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
+| 🧠 **Routing & Intelligence** | 25+              | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |
+| 🔒 **Security & Compliance**  | 20+              | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping                  |
+| 📊 **Observability**          | 15+              | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model   |
+| 🔄 **Provider Integrations**  | 20+              | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing              |
+| ⚡ **Performance**            | 15+              | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API                        |
+| 🌐 **Ecosystem**              | 10+              | WebSocket API, config hot-reload, distributed config store, commercial mode                           |
 
 ### 🔜 Coming Soon
 
@@ -2247,9 +2347,23 @@ gh release create v2.0.0 --title "v2.0.0" --generate-notes
 
 ## 📊 Star History
 
-## Stargazers over time
+<a href="https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left" />
+ </picture>
+</a>
 
-## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)
+## 🌍 StarMapper
+
+<a href="https://starmapper.bruniaux.com/diegosouzapw/omniroute">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light" />
+    <img alt="StarMapper" src="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute" />
+  </picture>
+</a>
 
 ## 🙏 Acknowledgments
 

SECURITY.md

@@ -20,9 +20,9 @@ If you discover a security vulnerability in OmniRoute, please report it responsi
 
 | Version | Support Status |
 | ------- | -------------- |
-| 3.4.x   | ✅ Active      |
-| 3.0.x   | ✅ Security    |
-| < 3.0.0 | ❌ Unsupported |
+| 3.6.x   | ✅ Active      |
+| 3.5.x   | ✅ Security    |
+| < 3.5.0 | ❌ Unsupported |
 
 ---
 

audit-report.json

@@ -0,0 +1,48 @@
+{
+  "auditReportVersion": 2,
+  "vulnerabilities": {
+    "follow-redirects": {
+      "name": "follow-redirects",
+      "severity": "moderate",
+      "isDirect": false,
+      "via": [
+        {
+          "source": 1116560,
+          "name": "follow-redirects",
+          "dependency": "follow-redirects",
+          "title": "follow-redirects leaks Custom Authentication Headers to Cross-Domain Redirect Targets",
+          "url": "https://github.com/advisories/GHSA-r4q5-vmmm-2653",
+          "severity": "moderate",
+          "cwe": ["CWE-200"],
+          "cvss": {
+            "score": 0,
+            "vectorString": null
+          },
+          "range": "<=1.15.11"
+        }
+      ],
+      "effects": [],
+      "range": "<=1.15.11",
+      "nodes": ["node_modules/follow-redirects"],
+      "fixAvailable": true
+    }
+  },
+  "metadata": {
+    "vulnerabilities": {
+      "info": 0,
+      "low": 0,
+      "moderate": 1,
+      "high": 0,
+      "critical": 0,
+      "total": 1
+    },
+    "dependencies": {
+      "prod": 421,
+      "dev": 480,
+      "optional": 158,
+      "peer": 480,
+      "peerOptional": 0,
+      "total": 1462
+    }
+  }
+}

bin/nodeRuntimeSupport.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+export const SECURE_NODE_LINES = Object.freeze([
+  Object.freeze({ major: 20, minor: 20, patch: 2 }),
+  Object.freeze({ major: 22, minor: 22, patch: 2 }),
+  Object.freeze({ major: 24, minor: 0, patch: 0 }),
+]);
+
+export const RECOMMENDED_NODE_VERSION = "24.14.1";
+export const SUPPORTED_NODE_RANGE = ">=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <25";
+export const SUPPORTED_NODE_DISPLAY =
+  "Node.js 20.20.2+ (20.x LTS), 22.22.2+ (22.x LTS), or 24.0.0+ (24.x LTS)";
+
+function formatVersion(version) {
+  return `${version.major}.${version.minor}.${version.patch}`;
+}
+
+export function parseNodeVersion(version = process.versions.node) {
+  const rawInput = String(version || process.versions.node || "0.0.0").trim();
+  const normalized = rawInput.replace(/^v/i, "");
+  const parts = normalized.split(".");
+  const major = Number.parseInt(parts[0] || "0", 10);
+  const minor = Number.parseInt(parts[1] || "0", 10);
+  const patch = Number.parseInt(parts[2] || "0", 10);
+
+  return {
+    raw: normalized ? `v${normalized}` : "v0.0.0",
+    normalized: normalized || "0.0.0",
+    major: Number.isFinite(major) ? major : 0,
+    minor: Number.isFinite(minor) ? minor : 0,
+    patch: Number.isFinite(patch) ? patch : 0,
+  };
+}
+
+export function compareNodeVersions(a, b) {
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  return a.patch - b.patch;
+}
+
+export function getSecureFloorForMajor(major) {
+  return SECURE_NODE_LINES.find((line) => line.major === major) || null;
+}
+
+export function getNodeRuntimeSupport(version = process.versions.node) {
+  const parsed = parseNodeVersion(version);
+  const secureFloor = getSecureFloorForMajor(parsed.major);
+  const nodeCompatible = secureFloor ? compareNodeVersions(parsed, secureFloor) >= 0 : false;
+
+  let reason = "unsupported-major";
+  if (nodeCompatible) {
+    reason = "supported";
+  } else if (secureFloor) {
+    reason = "below-security-floor";
+  } else if (parsed.major >= 25) {
+    reason = "unreleased-major";
+  }
+
+  return {
+    nodeVersion: parsed.raw,
+    nodeCompatible,
+    reason,
+    supportedRange: SUPPORTED_NODE_RANGE,
+    supportedDisplay: SUPPORTED_NODE_DISPLAY,
+    recommendedVersion: `v${RECOMMENDED_NODE_VERSION}`,
+    minimumSecureVersion: secureFloor ? `v${formatVersion(secureFloor)}` : null,
+  };
+}
+
+export function getNodeRuntimeWarning(version = process.versions.node) {
+  const support = getNodeRuntimeSupport(version);
+  if (support.nodeCompatible) return null;
+
+  if (support.reason === "below-security-floor" && support.minimumSecureVersion) {
+    return `Node.js ${support.nodeVersion} is below the patched minimum ${support.minimumSecureVersion} for this LTS line.`;
+  }
+
+  if (support.reason === "unreleased-major") {
+    return `Node.js ${support.nodeVersion} is outside the supported LTS lines. OmniRoute currently supports Node.js 20.x, 22.x, and 24.x.`;
+  }
+
+  return `Node.js ${support.nodeVersion} is outside OmniRoute's approved secure runtime policy.`;
+}

bin/omniroute.mjs

@@ -4,36 +4,35 @@
  * OmniRoute CLI — Smart AI Router with Auto Fallback
  *
  * Usage:
- *   omniroute              Start the server (default port 20128)
- *   omniroute --port 3000  Start on custom port
- *   omniroute --no-open    Start without opening browser
- *   omniroute --mcp        Start MCP server (stdio transport for IDEs)
- *   omniroute --help       Show help
- *   omniroute --version    Show version
+ *   omniroute                          Start the server (default port 20128)
+ *   omniroute --port 3000              Start on custom port
+ *   omniroute --no-open                Start without opening browser
+ *   omniroute --mcp                    Start MCP server (stdio transport for IDEs)
+ *   omniroute reset-encrypted-columns  Reset broken encrypted credentials
+ *   omniroute --help                   Show help
+ *   omniroute --version                Show version
  */
 
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { homedir, platform } from "node:os";
 import { isNativeBinaryCompatible } from "../scripts/native-binary-compat.mjs";
+import { getNodeRuntimeSupport, getNodeRuntimeWarning } from "./nodeRuntimeSupport.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const ROOT = join(__dirname, "..");
 const APP_DIR = join(ROOT, "app");
 
-// ── Load .env file (for global npm install) ─────────────────
 function loadEnvFile() {
   const envPaths = [];
 
-  // 1. DATA_DIR/.env if set
   if (process.env.DATA_DIR) {
     envPaths.push(join(process.env.DATA_DIR, ".env"));
   }
 
-  // 2. ~/.omniroute/.env (default data dir)
   const home = homedir();
   if (home) {
     if (platform() === "win32") {
@@ -44,7 +43,6 @@ function loadEnvFile() {
     }
   }
 
-  // 3. ./.env (current working directory)
   envPaths.push(join(process.cwd(), ".env"));
 
   for (const envPath of envPaths) {
@@ -53,15 +51,12 @@ function loadEnvFile() {
         const content = readFileSync(envPath, "utf-8");
         for (const line of content.split("\n")) {
           const trimmed = line.trim();
-          // Skip empty lines and comments
           if (!trimmed || trimmed.startsWith("#")) continue;
           const eqIdx = trimmed.indexOf("=");
           if (eqIdx > 0) {
             const key = trimmed.slice(0, eqIdx).trim();
             const value = trimmed.slice(eqIdx + 1).trim();
-            // Don't override existing env vars
             if (process.env[key] === undefined) {
-              // Remove surrounding quotes
               process.env[key] = value.replace(/^["']|["']$/g, "");
             }
           }
@@ -70,14 +65,13 @@ function loadEnvFile() {
         return;
       }
     } catch {
-      // Ignore errors reading env files
+      // Ignore errors reading env files.
     }
   }
 }
 
 loadEnvFile();
 
-// ── Parse args ─────────────────────────────────────────────
 const args = process.argv.slice(2);
 
 if (args.includes("--help") || args.includes("-h")) {
@@ -89,6 +83,7 @@ if (args.includes("--help") || args.includes("-h")) {
     omniroute --port <port>   Use custom API port (default: 20128)
     omniroute --no-open       Don't open browser automatically
     omniroute --mcp           Start MCP server (stdio transport for IDEs)
+    omniroute reset-encrypted-columns  Reset encrypted credentials (recovery)
     omniroute --help          Show this help
     omniroute --version       Show version
 
@@ -124,10 +119,106 @@ if (args.includes("--version") || args.includes("-v")) {
   process.exit(0);
 }
 
-// ── MCP Server Mode ───────────────────────────────────────
+// ── reset-encrypted-columns subcommand ──────────────────────────────────────
+// Recovery tool for users who lost STORAGE_ENCRYPTION_KEY after upgrade (#1622)
+if (args.includes("reset-encrypted-columns")) {
+  const dataDir = (() => {
+    const configured = process.env.DATA_DIR?.trim();
+    if (configured) return configured;
+    if (platform() === "win32") {
+      const appData = process.env.APPDATA || join(homedir(), "AppData", "Roaming");
+      return join(appData, "omniroute");
+    }
+    const xdg = process.env.XDG_CONFIG_HOME?.trim();
+    if (xdg) return join(xdg, "omniroute");
+    return join(homedir(), ".omniroute");
+  })();
+
+  const dbPath = join(dataDir, "storage.sqlite");
+
+  if (!existsSync(dbPath)) {
+    console.log(`\x1b[33m⚠ No database found at ${dbPath}\x1b[0m`);
+    process.exit(0);
+  }
+
+  const force = args.includes("--force");
+  if (!force) {
+    console.log(`
+  \x1b[1m\x1b[33m⚠ WARNING: This will erase all encrypted credentials\x1b[0m
+
+  This command will NULL out the following columns in provider_connections:
+    • api_key
+    • access_token
+    • refresh_token
+    • id_token
+
+  Provider metadata (name, provider_id, settings) will be preserved.
+  You will need to re-authenticate all providers after this operation.
+
+  Database: ${dbPath}
+
+  \x1b[1mTo confirm, run:\x1b[0m
+    omniroute reset-encrypted-columns --force
+    `);
+    process.exit(0);
+  }
+
+  try {
+    const { createRequire } = await import("node:module");
+    const require = createRequire(import.meta.url);
+    const Database = require("better-sqlite3");
+    const db = new Database(dbPath);
+
+    const countResult = db
+      .prepare(
+        `SELECT COUNT(*) as cnt FROM provider_connections
+         WHERE api_key LIKE 'enc:v1:%'
+            OR access_token LIKE 'enc:v1:%'
+            OR refresh_token LIKE 'enc:v1:%'
+            OR id_token LIKE 'enc:v1:%'`
+      )
+      .get();
+
+    const affected = countResult?.cnt ?? 0;
+
+    if (affected === 0) {
+      console.log("\x1b[32m✔ No encrypted credentials found — nothing to reset.\x1b[0m");
+      db.close();
+      process.exit(0);
+    }
+
+    const result = db
+      .prepare(
+        `UPDATE provider_connections
+            SET api_key = NULL,
+                access_token = NULL,
+                refresh_token = NULL,
+                id_token = NULL
+          WHERE api_key LIKE 'enc:v1:%'
+             OR access_token LIKE 'enc:v1:%'
+             OR refresh_token LIKE 'enc:v1:%'
+             OR id_token LIKE 'enc:v1:%'`
+      )
+      .run();
+
+    db.close();
+
+    console.log(
+      `\x1b[32m✔ Reset ${result.changes} provider connection(s).\x1b[0m\n` +
+        `  Re-authenticate your providers in the dashboard or re-add API keys.\n`
+    );
+  } catch (err) {
+    console.error(
+      `\x1b[31m✖ Failed to reset encrypted columns:\x1b[0m ${err.message || err}`
+    );
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
 if (args.includes("--mcp")) {
   try {
-    const { startMcpCli } = await import(join(ROOT, "bin", "mcp-server.mjs"));
+    const { startMcpCli } = await import(pathToFileURL(join(ROOT, "bin", "mcp-server.mjs")).href);
     await startMcpCli(ROOT);
   } catch (err) {
     console.error("\x1b[31m✖ Failed to start MCP server:\x1b[0m", err.message || err);
@@ -141,7 +232,6 @@ function parsePort(value, fallback) {
   return Number.isFinite(parsed) && parsed > 0 && parsed <= 65535 ? parsed : fallback;
 }
 
-// Parse --port (canonical/base port)
 let port = parsePort(process.env.PORT || "20128", 20128);
 const portIdx = args.indexOf("--port");
 if (portIdx !== -1 && args[portIdx + 1]) {
@@ -155,41 +245,36 @@ if (portIdx !== -1 && args[portIdx + 1]) {
 
 const apiPort = parsePort(process.env.API_PORT || String(port), port);
 const dashboardPort = parsePort(process.env.DASHBOARD_PORT || String(port), port);
-
 const noOpen = args.includes("--no-open");
 
-// ── Banner ─────────────────────────────────────────────────
 console.log(`
 \x1b[36m   ____                  _ ____              _
-   / __ \\                (_) __ \\            | |
+   / __ \\\\                (_) __ \\\\            | |
   | |  | |_ __ ___  _ __ _| |__) |___  _   _| |_ ___
-  | |  | | '_ \` _ \\| '_ \\ |  _  // _ \\| | | | __/ _ \\
-  | |__| | | | | | | | | | | | \\ \\ (_) | |_| | ||  __/
-   \\____/|_| |_| |_|_| |_|_|_|  \\_\\___/ \\__,_|\\__\\___|
+  | |  | | '_ \` _ \\\\| '_ \\\\ |  _  // _ \\\\| | | | __/ _ \\\\
+  | |__| | | | | | | | | | | | \\\\ \\\\ (_) | |_| | ||  __/
+   \\\\____/|_| |_| |_|_| |_|_|_|  \\\\_\\\\___/ \\\\__,_|\\\\__\\\\___|
 \x1b[0m`);
 
-// ── Node.js version check ──────────────────────────────────
-const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
-if (nodeMajor >= 24) {
+const nodeSupport = getNodeRuntimeSupport();
+if (!nodeSupport.nodeCompatible) {
+  const runtimeWarning = getNodeRuntimeWarning() || "Unsupported Node.js runtime detected.";
   console.warn(`\x1b[33m  ⚠  Warning: You are running Node.js ${process.versions.node}.
-     OmniRoute uses better-sqlite3, a native addon that does not yet
-     have compatible prebuilt binaries for Node.js 24+.
-     You may experience errors like "is not a valid Win32 application"
-     or "NODE_MODULE_VERSION mismatch".
+     ${runtimeWarning}
 
-     Recommended: use Node.js 22 LTS (or 20 LTS).
+     Supported secure runtimes: ${nodeSupport.supportedDisplay}
+     Recommended: use Node.js ${nodeSupport.recommendedVersion} or newer on the 22.x LTS line.
      Workaround:  npm rebuild better-sqlite3\x1b[0m
 `);
 }
 
-// ── Resolve server entry ───────────────────────────────────
-const serverJs = join(APP_DIR, "server.js");
+const serverWsJs = join(APP_DIR, "server-ws.mjs");
+const serverJs = existsSync(serverWsJs) ? serverWsJs : join(APP_DIR, "server.js");
 
 if (!existsSync(serverJs)) {
   console.error("\x1b[31m✖ Server not found at:\x1b[0m", serverJs);
   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");
@@ -211,10 +296,6 @@ if (!existsSync(serverJs)) {
   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",
@@ -234,10 +315,8 @@ if (existsSync(sqliteBinary) && !isNativeBinaryCompatible(sqliteBinary)) {
   process.exit(1);
 }
 
-// ── Start server ───────────────────────────────────────────
 console.log(`  \x1b[2m⏳ Starting server...\x1b[0m\n`);
 
-// Sanitize memory limit — parseInt to prevent command injection (#150)
 const rawMemory = parseInt(process.env.OMNIROUTE_MEMORY_MB || "512", 10);
 const memoryLimit =
   Number.isFinite(rawMemory) && rawMemory >= 64 && rawMemory <= 16384 ? rawMemory : 512;
@@ -265,7 +344,6 @@ server.stdout.on("data", (data) => {
   const text = data.toString();
   process.stdout.write(text);
 
-  // Detect server ready
   if (
     !started &&
     (text.includes("Ready") || text.includes("started") || text.includes("listening"))
@@ -291,7 +369,6 @@ server.on("exit", (code) => {
   process.exit(code ?? 0);
 });
 
-// ── Graceful shutdown ──────────────────────────────────────
 function shutdown() {
   console.log("\n\x1b[33m⏹ Shutting down OmniRoute...\x1b[0m");
   server.kill("SIGTERM");
@@ -304,7 +381,6 @@ function shutdown() {
 process.on("SIGINT", shutdown);
 process.on("SIGTERM", shutdown);
 
-// ── On ready ───────────────────────────────────────────────
 async function onReady() {
   const dashboardUrl = `http://localhost:${dashboardPort}`;
   const apiUrl = `http://localhost:${apiPort}`;
@@ -326,12 +402,11 @@ async function onReady() {
       const open = await import("open");
       await open.default(dashboardUrl);
     } catch {
-      // open is optional — if not available, just skip
+      // open is optional — if not available, just skip.
     }
   }
 }
 
-// Fallback: if no "Ready" message detected in 15s, assume server is up
 setTimeout(() => {
   if (!started) {
     started = true;

bin/reset-password.mjs

@@ -70,10 +70,10 @@ async function main() {
     console.log("ℹ️  No password is currently set.");
   }
 
-  const password = await ask("Enter new password (min 4 chars): ");
+  const password = await ask("Enter new password (min 8 chars): ");
 
-  if (!password || password.length < 4) {
-    console.error("\n❌ Password must be at least 4 characters.\n");
+  if (!password || password.length < 8) {
+    console.error("\n❌ Password must be at least 8 characters.\n");
     db.close();
     rl.close();
     process.exit(1);

config/payloadRules.json

@@ -0,0 +1,6 @@
+{
+  "default": [],
+  "default-raw": [],
+  "override": [],
+  "filter": []
+}

dbsetup.js

@@ -1,23 +0,0 @@
-#!/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}`))
-      }
-    })
-  })
-}

docker-compose.yml

@@ -20,6 +20,7 @@
 
 x-common: &common
   restart: unless-stopped
+  stop_grace_period: 40s
   env_file: .env
   environment:
     - DATA_DIR=/app/data # Must match the volume mount below
@@ -28,7 +29,7 @@ x-common: &common
     - API_PORT=${API_PORT:-20129}
     - API_HOST=${API_HOST:-0.0.0.0}
   volumes:
-    - omniroute-data:/app/data
+    - ./data:/app/data
   healthcheck:
     test: ["CMD", "node", "healthcheck.mjs"]
     interval: 30s
@@ -63,7 +64,7 @@ services:
       - "${DASHBOARD_PORT:-${PORT:-20128}}:${DASHBOARD_PORT:-${PORT:-20128}}"
       - "${API_PORT:-20129}:${API_PORT:-20129}"
     volumes:
-      - omniroute-data:/app/data
+      - ./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
@@ -96,12 +97,12 @@ services:
       # - CLI_CLINE_BIN=cline
       # - CLI_CONTINUE_BIN=cn
     volumes:
-      - omniroute-data:/app/data
+      - ./data:/app/data
       # ── Host binary mounts (read-only) ──
       # Adjust paths below to match YOUR host system.
       - ~/.local/bin:/host-local/bin:ro
       # Node global binaries (adjust node version path)
-      # - ~/.nvm/versions/node/v22.16.0/bin:/host-node/bin:ro
+      # - ~/.nvm/versions/node/v24.14.1/bin:/host-node/bin:ro
       # ── Host config mounts (read-write) ──
       - ~/.codex:/host-home/.codex:rw
       - ~/.claude:/host-home/.claude:rw
@@ -135,7 +136,5 @@ services:
       - cliproxyapi
 
 volumes:
-  omniroute-data:
-    name: omniroute-data
   cliproxyapi-data:
     name: cliproxyapi-data

docs/API_REFERENCE.md

@@ -68,7 +68,7 @@ Content-Type: application/json
 }
 ```
 
-Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, **GitHub Models**.
 
 ```bash
 # List all embedding models
@@ -91,7 +91,7 @@ Content-Type: application/json
 }
 ```
 
-Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+Available providers: OpenAI (DALL-E, GPT Image 1), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (local), ComfyUI (local).
 
 ```bash
 # List all image models
@@ -179,15 +179,15 @@ Response example:
 
 ### 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            |
+| 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/PATCH/DELETE | Custom models (add, update, hide/show, delete) |
 
 ### OAuth Flows
 
@@ -284,12 +284,12 @@ GET response includes `agents[]` (id, name, binary, version, installed, protocol
 
 ### Resilience & Rate Limits
 
-| 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 |
+| Endpoint                | Method    | Description                                                                        |
+| ----------------------- | --------- | ---------------------------------------------------------------------------------- |
+| `/api/resilience`       | GET/PATCH | Get/update request queue, connection cooldown, provider breaker, and wait settings |
+| `/api/resilience/reset` | POST      | Reset provider circuit breakers                                                    |
+| `/api/rate-limits`      | GET       | Per-account rate limit status                                                      |
+| `/api/rate-limit`       | GET       | Global rate limit configuration                                                    |
 
 ### Evals
 
@@ -320,15 +320,38 @@ These endpoints mirror Gemini's API format for clients that expect native Gemini
 
 ### 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                     |
+| 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                     |
+| `/api/system/env/repair` | POST   | Repair OAuth provider environment variables          |
+| `/api/system-info`       | GET    | Generate system diagnostics report                   |
 
 > **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users.
 
+### OAuth Environment Repair _(v3.6.1+)_
+
+```bash
+POST /api/system/env/repair
+Content-Type: application/json
+
+{
+  "provider": "claude-code"
+}
+```
+
+Repairs missing or corrupted OAuth environment variables for a specific provider. Returns:
+
+```json
+{
+  "success": true,
+  "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
+  "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
+}
+```
+
 ---
 
 ## Audio Transcription
@@ -420,25 +443,6 @@ Content-Type: application/json
 }
 ```
 
----
-
-## 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/*`

docs/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 🌐 **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-28_
+_Last updated: 2026-04-15_
 
 ## Executive Summary
 
@@ -11,18 +11,27 @@ It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic acr
 
 Core capabilities:
 
-- OpenAI-compatible API surface for CLI/tools (28 providers)
+- OpenAI-compatible API surface for CLI/tools (160+ providers, 16 executors)
 - Request/response translation across provider formats
 - Model combo fallback (multi-model sequence)
+- Structured combo steps (`provider + model + connection`) with runtime ordering by `compositeTiers`
 - Account-level fallback (multi-account per provider)
-- OAuth + API-key provider connection management
+- Quota preflight and quota-aware P2C account selection in the main chat path
+- OAuth + API-key provider connection management (13 OAuth modules)
 - Embedding generation via `/v1/embeddings` (6 providers, 9 models)
-- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Image generation via `/v1/images/generations` (10+ providers, 20+ models)
+- Audio transcription via `/v1/audio/transcriptions` (7 providers)
+- Text-to-speech via `/v1/audio/speech` (10 providers)
+- Video generation via `/v1/videos/generations` (ComfyUI + SD WebUI)
+- Music generation via `/v1/music/generations` (ComfyUI)
+- Web search via `/v1/search` (5 providers)
+- Moderations via `/v1/moderations`
+- Reranking via `/v1/rerank`
 - 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
+- Local persistence for providers, keys, aliases, combos, settings, pricing (26 DB modules)
 - Usage/cost tracking and request logging
 - Optional cloud sync for multi-device/state sync
 - IP allowlist/blocklist for API access control
@@ -33,15 +42,35 @@ Core capabilities:
 - 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 layer: cost rules, fallback policy, lockout policy
+- Context Relay: session handoff summaries for account rotation continuity
 - 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
+- Combo target telemetry and historical combo target health via `combo_execution_key` / `combo_step_id`
 - 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/`)
+- Health dashboard with real-time provider circuit breaker status
+- MCP Server (29 tools) with 3 transports (stdio/SSE/Streamable HTTP)
+- A2A Server (JSON-RPC 2.0 + SSE) with skills and task lifecycle
+- Memory system (extraction, injection, retrieval, summarization)
+- Skills system (registry, executor, sandbox, built-in skills)
+- MITM proxy with certificate management and DNS handling
+- Prompt injection guard middleware
+- ACP (Agent Communication Protocol) registry
+- Modular OAuth providers (13 individual modules under `src/lib/oauth/providers/`)
+- Uninstall/full-uninstall scripts
+- OAuth environment repair action
+- WebSocket bridge for OpenAI-compatible WS clients (`/v1/ws`)
+- Sync token management (issue/revoke, ETag-versioned config bundle download)
+- GLM Thinking (`glmt`) first-class provider preset
+- Hybrid token counting (provider-side `/messages/count_tokens` with estimation fallback)
+- Model alias auto-seeding (30+ cross-proxy dialect normalizations at startup)
+- Safe outbound fetch with SSRF guard, private URL blocking, and configurable retry
+- Cooldown-aware chat retries with configurable `requestRetry` and `maxRetryIntervalSec`
+- Runtime environment validation with Zod at startup
+- Compliance audit v2 with pagination, provider CRUD events, and SSRF-blocked validation logging
 
 Primary runtime model:
 
@@ -72,15 +101,15 @@ 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/combos` — combo strategies, templates, step-based builder, model routing rules, manual persisted ordering
 - `/dashboard/costs` — cost aggregation and pricing visibility
-- `/dashboard/analytics` — usage analytics and evaluations
+- `/dashboard/analytics` — usage analytics, evaluations, combo target health
 - `/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/health` — uptime, circuit breakers, rate limits, quota-monitored sessions
 - `/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
@@ -176,16 +205,18 @@ Management domains:
 - 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
+- Resilience: `src/app/api/resilience` (GET/PATCH) — request queue, connection cooldown, provider breaker, wait-for-cooldown config
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset provider breakers
 - 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)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET, with pagination + structured metadata)
 - Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
 - Policies: `src/app/api/policies` (GET/POST)
+- Sync tokens: `src/app/api/sync/tokens` (GET/POST), `src/app/api/sync/tokens/[id]` (GET/DELETE)
+- Config bundle: `src/app/api/sync/bundle` (GET, ETag-versioned snapshot of settings/providers/combos/keys)
+- WebSocket: `src/app/api/v1/ws/route.ts` — Upgrade handler for OpenAI-compatible WS clients
 
 ## 2) SSE + Translation Core
 
@@ -220,10 +251,19 @@ Services (business logic):
 - Wildcard model routing: `open-sse/services/wildcardRouter.ts`
 - Rate limit management: `open-sse/services/rateLimitManager.ts`
 - Circuit breaker: `open-sse/services/circuitBreaker.ts`
+- Context handoff: `open-sse/services/contextHandoff.ts` — handoff summary generation and injection for context-relay strategy
+- Codex quota fetcher: `open-sse/services/codexQuotaFetcher.ts` — fetches Codex quota for context-relay handoff decisions
+- Cooldown-aware retry: `src/sse/services/cooldownAwareRetry.ts` — per-model cooldown retries with configurable `requestRetry` / `maxRetryIntervalSec`
+- Safe outbound fetch: `src/shared/network/safeOutboundFetch.ts` — guarded provider/model fetch with SSRF guard, private-URL blocking, retry, and timeout
+- Outbound URL guard: `src/shared/network/outboundUrlGuard.ts` — validates provider URLs against private/localhost CIDR ranges
+- Provider request defaults: `open-sse/services/providerRequestDefaults.ts` — provider-level `maxTokens`, `temperature`, `thinkingBudgetTokens` defaults
+- GLM provider constants: `open-sse/config/glmProvider.ts` — shared GLM models, quota URLs, GLMT timeout/defaults
+- Antigravity upstream: `open-sse/config/antigravityUpstream.ts` — base URL and discovery path constants
+- Codex client constants: `open-sse/config/codexClient.ts` — versioned user-agent and client-version values
+- Model alias seed: `src/lib/modelAliasSeed.ts` — seeds 30+ cross-proxy dialect aliases at startup
 
 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`
@@ -237,7 +277,7 @@ Domain layer modules:
 - 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/`):
+OAuth provider modules (13 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`, `qoder.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
@@ -271,6 +311,10 @@ Domain State DB (SQLite):
 - 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)
+- SSRF / outbound URL guard: `src/shared/network/outboundUrlGuard.ts` — blocks private/loopback/link-local ranges for all provider calls
+- Runtime env validation: `src/lib/env/runtimeEnv.ts` — Zod schema for all environment variables, surfaced as startup errors/warnings
+- Sync tokens: `src/lib/db/syncTokens.ts` — scoped tokens for config bundle download endpoints; backed by `sync_tokens` SQLite table (migration `024_create_sync_tokens.sql`)
+- WebSocket handshake auth: `src/lib/ws/handshake.ts` — validates WS upgrade requests via API key or session cookie
 
 ## 5) Cloud Sync
 
@@ -588,6 +632,10 @@ flowchart LR
 - `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)
+- `src/app/api/sync/tokens`: sync token CRUD (GET/POST)
+- `src/app/api/sync/tokens/[id]`: sync token get/delete (GET/DELETE)
+- `src/app/api/sync/bundle`: config bundle download (GET, ETag versioning)
+- `src/app/api/v1/ws`: WebSocket upgrade handler for OpenAI-compatible WS clients
 
 ### Routing and Execution Core
 
@@ -612,15 +660,22 @@ flowchart LR
 
 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, 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 |
-| `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                                     |
+| Executor               | Provider(s)                                                                                                                                                 | Special Handling                                                     |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `DefaultExecutor`      | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA, etc. | Dynamic URL/header config per provider                               |
+| `AntigravityExecutor`  | Google Antigravity                                                                                                                                          | Custom project/session IDs, Retry-After parsing                      |
+| `CliProxyApiExecutor`  | CLIProxyAPI-compatible providers                                                                                                                            | Custom auth and protocol handling                                    |
+| `CloudflareAiExecutor` | Cloudflare Workers AI                                                                                                                                       | Account ID injection, Neurons-based usage tracking                   |
+| `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                      |
+| `GeminiCLIExecutor`    | Gemini CLI                                                                                                                                                  | Google OAuth token refresh cycle                                     |
+| `KiroExecutor`         | AWS CodeWhisperer/Kiro                                                                                                                                      | AWS EventStream binary format → SSE conversion                       |
+| `OpenCodeExecutor`     | OpenCode                                                                                                                                                    | AI SDK compatible provider setup                                     |
+| `PollinationsExecutor` | Pollinations AI                                                                                                                                             | No API key required, rate-limited requests                           |
+| `PuterExecutor`        | Puter                                                                                                                                                       | Browser-based provider integration                                   |
+| `QoderExecutor`        | Qoder AI                                                                                                                                                    | PAT and OAuth support, multi-model free tier                         |
+| `VertexExecutor`       | Google Vertex AI                                                                                                                                            | Service account auth, region-based endpoints                         |
 
 All other providers (including custom compatible nodes) use the `DefaultExecutor`.
 
@@ -638,7 +693,10 @@ 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     |
-| Qoder            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Qoder            | openai           | OAuth / PAT           | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Kilo Code        | openai           | OAuth                 | ✅               | ✅         | ✅            | ❌                 |
+| Cline            | openai           | OAuth                 | ✅               | ✅         | ✅            | ❌                 |
+| Kimi Coding      | openai           | OAuth                 | ✅               | ✅         | ✅            | ❌                 |
 | OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
@@ -651,6 +709,17 @@ All other providers (including custom compatible nodes) use the `DefaultExecutor
 | Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cloudflare AI    | openai           | API Token + Acct ID   | ✅               | ✅         | ❌            | ❌                 |
+| Pollinations     | openai           | None (no key)         | ✅               | ✅         | ❌            | ❌                 |
+| Scaleway AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| LongCat          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Ollama Cloud     | openai           | API Key (optional)    | ✅               | ✅         | ❌            | ❌                 |
+| HuggingFace      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Nebius           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| SiliconFlow      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Hyperbolic       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Vertex AI        | gemini           | Service Account       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Puter            | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 
 ## Format Translation Coverage
 
@@ -710,22 +779,20 @@ Additional processing layers in the translation pipeline:
 
 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
+## Request Logging and Artifacts
 
-The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`:
+The older file-based request logger (`open-sse/utils/requestLogger.ts`) is retained only for
+legacy compatibility. The current runtime contract uses:
 
-```
-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.
+- `APP_LOG_TO_FILE=true` for application and audit logs written under `<repo>/logs/`
+- SQLite-backed call log records in `call_logs`
+- `${DATA_DIR}/call_logs/YYYY-MM-DD/...` artifacts when the call log pipeline is enabled
 
 ## Failure Modes and Resilience
 
 ## 1) Account/Provider Availability
 
-- provider account cooldown on transient/rate/auth errors
+- connection cooldown on retryable upstream failures
 - account fallback before failing request
 - combo model fallback when current model/provider path is exhausted
 
@@ -750,6 +817,12 @@ Files are written to `<repo>/logs/<session>/` for each request session.
 - SQLite schema migrations and auto-upgrade hooks at startup
 - legacy JSON → SQLite migration compatibility path
 
+## 6) SSRF / Outbound URL Guard
+
+- `src/shared/network/outboundUrlGuard.ts` blocks all private/loopback/link-local target URLs before they reach provider executors
+- Provider model discovery and validation routes use `src/shared/network/safeOutboundFetch.ts` which applies the guard before every outbound request
+- Guard errors surface as `URL_GUARD_BLOCKED` with HTTP 422 and are logged to the compliance audit trail via `providerAudit.ts`
+
 ## Observability and Operational Signals
 
 Runtime visibility sources:
@@ -758,7 +831,8 @@ Runtime visibility sources:
 - 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`
+- optional application log files under `logs/` when `APP_LOG_TO_FILE=true`
+- optional request artifacts under `${DATA_DIR}/call_logs/` when the call log pipeline is enabled
 - dashboard usage endpoints (`/api/usage/*`) for UI consumption
 
 Detailed request payload capture stores up to four JSON payload stages per routed call:
@@ -785,7 +859,7 @@ Environment variables actively used by code:
 - 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`
+- Logging: `APP_LOG_TO_FILE`, `APP_LOG_RETENTION_DAYS`, `CALL_LOG_RETENTION_DAYS`
 - 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`
@@ -800,7 +874,10 @@ Environment variables actively used by code:
 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).
+8. Settings page is organized into 7 tabs: General, Appearance, AI, Security, Routing, Resilience, Advanced. The Resilience page only configures request queue, connection cooldown, provider breaker, and wait-for-cooldown behavior; live breaker runtime state is shown on the Health page.
+9. **Context Relay** strategy (`context-relay`) is split across two layers: `combo.ts` decides if a handoff should be generated, `chat.ts` injects the handoff after account resolution. Handoff data lives in `context_handoffs` SQLite table. This split is intentional because only `chat.ts` knows whether the actual account changed.
+10. **Proxy enforcement** is now comprehensive: `tokenHealthCheck.ts` resolves proxy per connection, `/api/providers/validate` uses `runWithProxyContext`, and `proxyFetch.ts` uses `undici.fetch()` to maintain dispatcher compatibility on Node 22.
+11. **Node.js runtime policy detection**: `/api/settings/require-login` returns `nodeVersion` and `nodeCompatible` fields. The login page renders a warning banner when the runtime falls outside the supported secure Node.js lines.
 
 ## Operational Verification Checklist
 

docs/CLI-TOOLS.md

@@ -32,31 +32,32 @@ Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilo
 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    |
+| 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    |
+| **Qwen Code**      | `qwen`        | `qwen`     | custom     | npm            |
 
 ### 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 |
+| 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`.
 
@@ -253,6 +254,55 @@ kiro-cli status
 
 ---
 
+### Qwen Code (Alibaba)
+
+Qwen Code supports OpenAI-compatible API endpoints via environment variables or `settings.json`.
+
+**Option 1: Environment variables (`~/.qwen/.env`)**
+
+```bash
+mkdir -p ~/.qwen && cat > ~/.qwen/.env << EOF
+OPENAI_API_KEY="sk-your-omniroute-key"
+OPENAI_BASE_URL="http://localhost:20128/v1"
+OPENAI_MODEL="auto"
+EOF
+```
+
+**Option 2: `settings.json` with model providers**
+
+```json
+// ~/.qwen/settings.json
+{
+  "env": {
+    "OPENAI_API_KEY": "sk-your-omniroute-key",
+    "OPENAI_BASE_URL": "http://localhost:20128/v1"
+  },
+  "modelProviders": {
+    "openai": [
+      {
+        "id": "omniroute-default",
+        "name": "OmniRoute (Auto)",
+        "envKey": "OPENAI_API_KEY",
+        "baseUrl": "http://localhost:20128/v1"
+      }
+    ]
+  }
+}
+```
+
+**Option 3: Inline CLI flags**
+
+```bash
+OPENAI_BASE_URL="http://localhost:20128/v1" \
+OPENAI_API_KEY="sk-your-omniroute-key" \
+OPENAI_MODEL="auto" \
+qwen
+```
+
+> For a **remote server** replace `localhost:20128` with the server IP or domain.
+
+**Test:** `qwen "say hello"`
+
 ### Cursor (Desktop App)
 
 > **Note:** Cursor routes requests through its cloud. For OmniRoute integration,
@@ -322,7 +372,7 @@ They run as internal routes and use OmniRoute's model routing automatically.
 OMNIROUTE_URL="http://localhost:20128/v1"
 OMNIROUTE_KEY="sk-your-omniroute-key"
 
-npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode
+npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode @qwen-code/qwen-code
 
 # Kiro CLI
 apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash

docs/CODEBASE_DOCUMENTATION.md

@@ -403,7 +403,7 @@ import "./request/claude-to-openai.js"; // ← self-registers
 | `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.                                                              |
+| `requestLogger.ts` | Legacy file-based request logging helper kept for compatibility. Current deployments should prefer `APP_LOG_TO_FILE` for application logs and the call log pipeline for persisted request artifacts.                                                                                 |
 | `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.                                                  |
 

docs/ENVIRONMENT.md

@@ -0,0 +1,668 @@
+# Environment Variables Reference
+
+> Complete reference for every environment variable recognized by OmniRoute.
+> For a quick-start template, see [`.env.example`](../.env.example).
+
+---
+
+## Table of Contents
+
+- [1. Required Secrets](#1-required-secrets)
+- [2. Storage & Database](#2-storage--database)
+- [3. Network & Ports](#3-network--ports)
+- [4. Security & Authentication](#4-security--authentication)
+- [5. Input Sanitization & PII Protection](#5-input-sanitization--pii-protection)
+- [6. Tool & Routing Policies](#6-tool--routing-policies)
+- [7. URLs & Cloud Sync](#7-urls--cloud-sync)
+- [8. Outbound Proxy](#8-outbound-proxy)
+- [9. CLI Tool Integration](#9-cli-tool-integration)
+- [10. Internal Agent & MCP Integrations](#10-internal-agent--mcp-integrations)
+- [11. OAuth Provider Credentials](#11-oauth-provider-credentials)
+- [12. Provider User-Agent Overrides](#12-provider-user-agent-overrides)
+- [13. CLI Fingerprint Compatibility](#13-cli-fingerprint-compatibility)
+- [14. API Key Providers](#14-api-key-providers)
+- [15. Timeout Settings](#15-timeout-settings)
+- [16. Logging](#16-logging)
+- [17. Memory Optimization](#17-memory-optimization)
+- [18. Pricing Sync](#18-pricing-sync)
+- [19. Model Sync (Dev)](#19-model-sync-dev)
+- [20. Provider-Specific Settings](#20-provider-specific-settings)
+- [21. Proxy Health](#21-proxy-health)
+- [22. Debugging](#22-debugging)
+- [23. GitHub Integration](#23-github-integration)
+- [Deployment Scenarios](#deployment-scenarios)
+- [Audit: Removed / Dead Variables](#audit-removed--dead-variables)
+
+---
+
+## 1. Required Secrets
+
+These **must** be set before the first run. Without them, the application will either refuse to start or operate with insecure defaults.
+
+| Variable           | Required | Default  | Source File             | Description                                                                                                                      |
+| ------------------ | -------- | -------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET`       | **Yes**  | _(none)_ | `src/lib/auth`          | Signs/verifies all dashboard session cookies (JWT). Generate with `openssl rand -base64 48`.                                     |
+| `API_KEY_SECRET`   | **Yes**  | _(none)_ | `src/lib/db/apiKeys.ts` | AES encryption key for API key values at rest in SQLite. Generate with `openssl rand -hex 32`.                                   |
+| `INITIAL_PASSWORD` | **Yes**  | `123456` | Bootstrap script        | Sets the initial admin dashboard password. **Change before first use.** After login, change via Dashboard → Settings → Security. |
+
+### Generation Commands
+
+```bash
+# Generate all three secrets at once:
+echo "JWT_SECRET=$(openssl rand -base64 48)"
+echo "API_KEY_SECRET=$(openssl rand -hex 32)"
+echo "INITIAL_PASSWORD=$(openssl rand -base64 16)"
+```
+
+> [!CAUTION]
+> Never commit `.env` files with real secrets to version control. The `.gitignore` already excludes `.env`, but verify before pushing.
+
+---
+
+## 2. Storage & Database
+
+OmniRoute uses **SQLite** (via `better-sqlite3`) for all persistence. These variables control data location, encryption, and lifecycle.
+
+| Variable                         | Default              | Source File                                     | Description                                                                                                        |
+| -------------------------------- | -------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `DATA_DIR`                       | `~/.omniroute/`      | `src/lib/db/core.ts`                            | Root directory for SQLite DB, backups, and data files. Override for Docker volumes or custom paths.                |
+| `STORAGE_ENCRYPTION_KEY`         | _(empty = disabled)_ | `src/lib/db/encryption.ts`                      | AES key for full SQLite database encryption at rest. Generate with `openssl rand -hex 32`.                         |
+| `STORAGE_ENCRYPTION_KEY_VERSION` | `v1`                 | `scripts/bootstrap-env.mjs`, `electron/main.js` | Version label for the encryption key. Increment when performing key rotation to support decryption of old backups. |
+| `DISABLE_SQLITE_AUTO_BACKUP`     | `false`              | `src/lib/db/backup.ts`                          | When `true`, skips the automatic database backup that runs before migrations on every startup.                     |
+| `OMNIROUTE_CRYPT_KEY`            | _(unset)_            | `src/lib/db/encryption.ts`                      | **Legacy alias** for `STORAGE_ENCRYPTION_KEY`. Accepted as a fallback when the primary variable is absent.         |
+| `OMNIROUTE_API_KEY_BASE64`       | _(unset)_            | `src/lib/db/encryption.ts`                      | **Legacy alias** (Base64-encoded form) accepted as a fallback. Decoded automatically before use.                   |
+
+### Scenarios
+
+| Scenario              | Configuration                                                                    |
+| --------------------- | -------------------------------------------------------------------------------- |
+| **Local development** | Leave all defaults. DB lives at `~/.omniroute/omniroute.db`.                     |
+| **Docker**            | `DATA_DIR=/data` + mount a volume at `/data`.                                    |
+| **Encrypted at rest** | Set `STORAGE_ENCRYPTION_KEY` + keep backups of the key! Losing it = losing data. |
+| **CI/Testing**        | `DATA_DIR=/tmp/omniroute-test` — ephemeral, no encryption needed.                |
+
+---
+
+## 3. Network & Ports
+
+| Variable              | Default      | Source File                | Description                                                                            |
+| --------------------- | ------------ | -------------------------- | -------------------------------------------------------------------------------------- |
+| `PORT`                | `20128`      | `src/lib/runtime/ports.ts` | Primary port for both Dashboard UI and API endpoints (single-port mode).               |
+| `API_PORT`            | _(unset)_    | `src/lib/runtime/ports.ts` | When set, serves the `/v1/*` proxy API on this separate port.                          |
+| `API_HOST`            | `0.0.0.0`    | `src/lib/runtime/ports.ts` | Bind address for the API port.                                                         |
+| `DASHBOARD_PORT`      | _(unset)_    | `src/lib/runtime/ports.ts` | When set, serves the Dashboard UI on this separate port.                               |
+| `PROD_DASHBOARD_PORT` | `20130`      | `docker-compose.prod.yml`  | Host-side published port for the Dashboard in Docker production mode.                  |
+| `PROD_API_PORT`       | `20131`      | `docker-compose.prod.yml`  | Host-side published port for the API in Docker production mode.                        |
+| `OMNIROUTE_PORT`      | _(unset)_    | `src/lib/runtime/ports.ts` | Takes precedence over `PORT` when running inside Electron or other wrappers.           |
+| `NODE_ENV`            | `production` | Next.js core               | Controls logging verbosity, caching, error detail exposure, and Next.js optimizations. |
+
+### Port Modes
+
+```
+┌─────────────────────────── Single Port (default) ──────────────────────────┐
+│  PORT=20128                                                                 │
+│  → Dashboard: http://localhost:20128                                        │
+│  → API:       http://localhost:20128/v1/chat/completions                    │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────── Split Ports ─────────────────────────────────────┐
+│  DASHBOARD_PORT=20128                                                       │
+│  API_PORT=20129                                                             │
+│  API_HOST=0.0.0.0                                                           │
+│  → Dashboard: http://localhost:20128                                        │
+│  → API:       http://0.0.0.0:20129/v1/chat/completions                     │
+│  Use case: Expose API to LAN while restricting Dashboard to localhost.      │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────── Docker Production ──────────────────────────────┐
+│  PROD_DASHBOARD_PORT=443   PROD_API_PORT=8443                              │
+│  → Maps container ports to host ports in docker-compose.prod.yml.          │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 4. Security & Authentication
+
+| Variable                      | Default               | Source File                              | Description                                                                                               |
+| ----------------------------- | --------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `MACHINE_ID_SALT`             | `endpoint-proxy-salt` | `src/lib/auth`                           | Salt combined with hardware identifiers for machine fingerprinting. Change per-deployment for isolation.  |
+| `AUTH_COOKIE_SECURE`          | `false`               | `src/lib/auth`                           | Sets the `Secure` flag on session cookies. **Must be `true`** when running behind HTTPS.                  |
+| `REQUIRE_API_KEY`             | `false`               | API middleware                           | When `true`, all `/v1/*` proxy requests must include a valid API key.                                     |
+| `ALLOW_API_KEY_REVEAL`        | `false`               | Dashboard providers page                 | Allows revealing full API key values in the Dashboard UI. Security risk on shared instances.              |
+| `NO_LOG_API_KEY_IDS`          | _(empty)_             | `src/lib/compliance/index.ts`            | Comma-separated API key IDs that bypass request logging (GDPR compliance).                                |
+| `MAX_BODY_SIZE_BYTES`         | `10485760` (10 MB)    | `src/shared/middleware/bodySizeGuard.ts` | Maximum allowed request body size. Rejects payloads exceeding this limit.                                 |
+| `CORS_ORIGIN`                 | `*`                   | Next.js middleware                       | CORS `Access-Control-Allow-Origin` value. Restrict for production.                                        |
+| `OUTBOUND_SSRF_GUARD_ENABLED` | `true`                | `src/shared/network/outboundUrlGuard.ts` | Block provider calls targeting private/loopback/link-local IP ranges. Disable only in isolated test envs. |
+
+### Hardening Checklist
+
+```bash
+# Production security minimum:
+AUTH_COOKIE_SECURE=true        # Requires HTTPS
+REQUIRE_API_KEY=true           # Authenticate all proxy calls
+ALLOW_API_KEY_REVEAL=false     # Never expose keys in UI
+CORS_ORIGIN=https://your.domain.com
+MAX_BODY_SIZE_BYTES=5242880    # 5 MB limit
+```
+
+---
+
+## 5. Input Sanitization & PII Protection
+
+OmniRoute provides a two-layer defense: request-side injection scanning and response-side PII stripping.
+
+### Request-Side: Prompt Injection Guard
+
+| Variable                  | Default   | Source File                              | Description                                                                                 |
+| ------------------------- | --------- | ---------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `INPUT_SANITIZER_ENABLED` | `false`   | `src/middleware/promptInjectionGuard.ts` | Enable scanning of incoming messages for prompt injection patterns.                         |
+| `INPUT_SANITIZER_MODE`    | `warn`    | `src/middleware/promptInjectionGuard.ts` | `warn` = log only, `block` = reject request with 400, `redact` = strip suspicious patterns. |
+| `INJECTION_GUARD_MODE`    | _(unset)_ | `src/middleware/promptInjectionGuard.ts` | Legacy alias for `INPUT_SANITIZER_MODE` — same behavior.                                    |
+| `PII_REDACTION_ENABLED`   | `false`   | `src/middleware/promptInjectionGuard.ts` | Detect PII (emails, phones, SSNs) in incoming requests.                                     |
+
+### Response-Side: PII Sanitizer
+
+| Variable                         | Default  | Source File               | Description                                                             |
+| -------------------------------- | -------- | ------------------------- | ----------------------------------------------------------------------- |
+| `PII_RESPONSE_SANITIZATION`      | `false`  | `src/lib/piiSanitizer.ts` | Scan LLM responses for leaked PII before returning to client.           |
+| `PII_RESPONSE_SANITIZATION_MODE` | `redact` | `src/lib/piiSanitizer.ts` | `redact` = mask PII, `warn` = log only, `block` = drop entire response. |
+
+### Scenarios
+
+| Scenario                  | Configuration                                                                                                                |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| **Enterprise compliance** | `INPUT_SANITIZER_ENABLED=true`, `INPUT_SANITIZER_MODE=block`, `PII_REDACTION_ENABLED=true`, `PII_RESPONSE_SANITIZATION=true` |
+| **Monitoring only**       | `INPUT_SANITIZER_ENABLED=true`, `INPUT_SANITIZER_MODE=warn` — logs but never blocks                                          |
+| **Personal use**          | Leave all disabled — zero overhead                                                                                           |
+
+---
+
+## 6. Tool & Routing Policies
+
+| Variable           | Default    | Source File             | Description                                                                                                                               |
+| ------------------ | ---------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `TOOL_POLICY_MODE` | `disabled` | `src/lib/toolPolicy.ts` | Controls LLM tool/function-calling access. `allowlist` = only listed tools, `denylist` = all except listed, `disabled` = no restrictions. |
+
+---
+
+## 7. URLs & Cloud Sync
+
+| Variable                | Default                  | Source File                                 | Description                                                                                                     |
+| ----------------------- | ------------------------ | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `BASE_URL`              | `http://localhost:20128` | `src/lib/cloudSync.ts`                      | Server-side URL for internal sync jobs to call `/api/sync/cloud`.                                               |
+| `CLOUD_URL`             | _(empty)_                | `src/lib/cloudSync.ts`                      | Cloud relay endpoint URL (premium feature).                                                                     |
+| `CLOUD_SYNC_TIMEOUT_MS` | `12000`                  | `src/lib/cloudSync.ts`                      | HTTP timeout for cloud sync requests.                                                                           |
+| `NEXT_PUBLIC_BASE_URL`  | `http://localhost:20128` | OAuth, Dashboard, sync                      | Public-facing URL for OAuth redirect_uri, Dashboard links. **Must match your public URL behind reverse proxy.** |
+| `NEXT_PUBLIC_CLOUD_URL` | _(empty)_                | Client-side                                 | Client-side mirror of `CLOUD_URL`.                                                                              |
+| `NEXT_PUBLIC_APP_URL`   | _(unset)_                | `src/shared/services/cloudSyncScheduler.ts` | Legacy fallback for `NEXT_PUBLIC_BASE_URL`.                                                                     |
+
+> [!IMPORTANT]
+> When deploying behind a reverse proxy (nginx, Caddy), `NEXT_PUBLIC_BASE_URL` **must** be set to your public URL (e.g., `https://omniroute.example.com`). Without this, OAuth callbacks will fail because the redirect_uri won't match.
+
+---
+
+## 8. Outbound Proxy
+
+Route upstream LLM provider calls through an HTTP or SOCKS5 proxy for egress control, geo-routing, or IP masking.
+
+| Variable                          | Default   | Source File          | Description                                                                         |
+| --------------------------------- | --------- | -------------------- | ----------------------------------------------------------------------------------- |
+| `ENABLE_SOCKS5_PROXY`             | `true`    | `open-sse/executors` | Enable SOCKS5 proxy agent for upstream calls.                                       |
+| `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` | `true`    | Client-side          | Client-side awareness of SOCKS5 availability.                                       |
+| `HTTP_PROXY`                      | _(unset)_ | Node.js standard     | HTTP proxy for upstream calls.                                                      |
+| `HTTPS_PROXY`                     | _(unset)_ | Node.js standard     | HTTPS proxy for upstream calls.                                                     |
+| `ALL_PROXY`                       | _(unset)_ | Node.js standard     | Universal proxy (supports `socks5://`).                                             |
+| `NO_PROXY`                        | _(unset)_ | Node.js standard     | Comma-separated hostnames/IPs to bypass the proxy.                                  |
+| `ENABLE_TLS_FINGERPRINT`          | `false`   | `open-sse/executors` | Spoof TLS fingerprint using wreq-js (mimics Chrome 124). Counters JA3/JA4 blocking. |
+
+### Scenarios
+
+| Scenario                      | Configuration                                                                                                             |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| **SOCKS5 through SSH tunnel** | `ALL_PROXY=socks5://127.0.0.1:7890`, `ENABLE_SOCKS5_PROXY=true`                                                           |
+| **Corporate HTTP proxy**      | `HTTP_PROXY=http://proxy.corp.com:3128`, `HTTPS_PROXY=http://proxy.corp.com:3128`, `NO_PROXY=localhost,internal.corp.com` |
+| **Anti-fingerprint**          | `ENABLE_TLS_FINGERPRINT=true` — requires `wreq-js` (included)                                                             |
+
+---
+
+## 9. CLI Tool Integration
+
+Controls how OmniRoute discovers and launches CLI sidecars (Claude Code, Codex, etc.).
+
+| Variable                  | Default    | Source File                         | Description                                                                |
+| ------------------------- | ---------- | ----------------------------------- | -------------------------------------------------------------------------- |
+| `CLI_MODE`                | `auto`     | `src/shared/services/cliRuntime.ts` | `auto` = search system PATH; `manual` = use explicit paths only.           |
+| `CLI_EXTRA_PATHS`         | _(unset)_  | `src/shared/services/cliRuntime.ts` | Additional PATH entries for CLI binary discovery (colon-separated).        |
+| `CLI_CONFIG_HOME`         | _(unset)_  | `src/shared/services/cliRuntime.ts` | Override home directory for reading CLI configs (`~/.claude`, `~/.codex`). |
+| `CLI_ALLOW_CONFIG_WRITES` | `false`    | `src/shared/services/cliRuntime.ts` | Allow OmniRoute to write CLI config files (token refresh, session data).   |
+| `CLI_CLAUDE_BIN`          | `claude`   | `src/shared/services/cliRuntime.ts` | Custom path to Claude CLI binary.                                          |
+| `CLI_CODEX_BIN`           | `codex`    | `src/shared/services/cliRuntime.ts` | Custom path to Codex CLI binary.                                           |
+| `CLI_DROID_BIN`           | `droid`    | `src/shared/services/cliRuntime.ts` | Custom path to Droid CLI binary.                                           |
+| `CLI_OPENCLAW_BIN`        | `openclaw` | `src/shared/services/cliRuntime.ts` | Custom path to OpenClaw CLI binary.                                        |
+| `CLI_CURSOR_BIN`          | `agent`    | `src/shared/services/cliRuntime.ts` | Custom path to Cursor agent binary.                                        |
+| `CLI_CLINE_BIN`           | `cline`    | `src/shared/services/cliRuntime.ts` | Custom path to Cline CLI binary.                                           |
+| `CLI_CONTINUE_BIN`        | `cn`       | `src/shared/services/cliRuntime.ts` | Custom path to Continue CLI binary.                                        |
+| `CLI_QODER_BIN`           | `qoder`    | `src/shared/services/cliRuntime.ts` | Custom path to Qoder CLI binary.                                           |
+
+### Docker Example
+
+```bash
+# Mount host binaries into the container and tell OmniRoute where they are:
+CLI_EXTRA_PATHS=/host-cli/bin
+CLI_CONFIG_HOME=/root
+CLI_ALLOW_CONFIG_WRITES=true
+CLI_CLAUDE_BIN=/host-cli/bin/claude
+```
+
+---
+
+## 10. Internal Agent & MCP Integrations
+
+| Variable                                | Default     | Source File                                 | Description                                                                                                                   |
+| --------------------------------------- | ----------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `OMNIROUTE_BASE_URL`                    | auto-detect | `open-sse/mcp-server/server.ts`             | Explicit URL for MCP/A2A tools to reach OmniRoute. Overrides localhost auto-detection.                                        |
+| `OMNIROUTE_API_KEY`                     | _(unset)_   | MCP/A2A modules                             | API key for internal MCP tool and A2A skill calls.                                                                            |
+| `OMNIROUTE_API_KEY_ID`                  | _(unset)_   | `open-sse/mcp-server/audit.ts`              | Key ID for MCP audit log attribution.                                                                                         |
+| `ROUTER_API_KEY`                        | _(unset)_   | Legacy                                      | Legacy alias for `OMNIROUTE_API_KEY`.                                                                                         |
+| `OMNIROUTE_MCP_ENFORCE_SCOPES`          | `false`     | `open-sse/mcp-server/server.ts`             | Enforce scope-based access control on MCP tool calls.                                                                         |
+| `OMNIROUTE_MCP_SCOPES`                  | _(all)_     | `open-sse/mcp-server/server.ts`             | Comma-separated scopes: `admin`, `combos`, `health`, `models`, `routing`, `budget`, `metrics`, `pricing`, `memory`, `skills`. |
+| `MODEL_SYNC_INTERVAL_HOURS`             | `24`        | `src/shared/services/modelSyncScheduler.ts` | Model catalog sync interval in hours.                                                                                         |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70`        | `src/server-init.ts`                        | Provider rate-limit and quota polling interval.                                                                               |
+| `OMNIROUTE_DISABLE_BACKGROUND_SERVICES` | `false`     | `src/instrumentation-node.ts`               | Disable all background services (sync, pricing, model refresh). Useful for CI/test.                                           |
+| `OMNIROUTE_BOOTSTRAPPED`                | `false`     | `src/app/(dashboard)/dashboard/page.tsx`    | Set `true` by bootstrap script after initial setup. Controls setup wizard visibility.                                         |
+| `OMNIROUTE_ALLOW_BODY_PROJECT_OVERRIDE` | `0`         | `open-sse/executors/antigravity.ts`         | Escape hatch: allow request body to override the Antigravity project field.                                                   |
+
+### OAuth CLI Bridge (Internal)
+
+| Variable            | Default     | Source File                     | Description                               |
+| ------------------- | ----------- | ------------------------------- | ----------------------------------------- |
+| `OMNIROUTE_SERVER`  | auto-detect | `src/lib/oauth/config/index.ts` | Server URL for CLI↔OmniRoute auth bridge. |
+| `OMNIROUTE_TOKEN`   | _(unset)_   | `src/lib/oauth/config/index.ts` | Auth token for CLI bridge.                |
+| `OMNIROUTE_USER_ID` | `cli`       | `src/lib/oauth/config/index.ts` | User ID for CLI bridge sessions.          |
+| `SERVER_URL`        | _(unset)_   | `src/lib/oauth/config/index.ts` | Legacy alias for `OMNIROUTE_SERVER`.      |
+| `CLI_TOKEN`         | _(unset)_   | `src/lib/oauth/config/index.ts` | Legacy alias for `OMNIROUTE_TOKEN`.       |
+| `CLI_USER_ID`       | _(unset)_   | `src/lib/oauth/config/index.ts` | Legacy alias for `OMNIROUTE_USER_ID`.     |
+
+---
+
+## 11. OAuth Provider Credentials
+
+Built-in credentials for **localhost development**. For remote deployments, register your own at each provider's developer console.
+
+| Variable                          | Provider                | Notes                                                                             |
+| --------------------------------- | ----------------------- | --------------------------------------------------------------------------------- |
+| `CLAUDE_OAUTH_CLIENT_ID`          | Claude Code (Anthropic) | Public client — no secret needed.                                                 |
+| `CLAUDE_CODE_REDIRECT_URI`        | Claude Code             | Override redirect URI. Default: `https://platform.claude.com/oauth/code/callback` |
+| `CODEX_OAUTH_CLIENT_ID`           | Codex / OpenAI          | Public client.                                                                    |
+| `GEMINI_OAUTH_CLIENT_ID`          | Gemini (Google)         | Requires matching `_SECRET`.                                                      |
+| `GEMINI_OAUTH_CLIENT_SECRET`      | Gemini (Google)         | —                                                                                 |
+| `GEMINI_CLI_OAUTH_CLIENT_ID`      | Gemini CLI              | Usually same as Gemini.                                                           |
+| `GEMINI_CLI_OAUTH_CLIENT_SECRET`  | Gemini CLI              | —                                                                                 |
+| `QWEN_OAUTH_CLIENT_ID`            | Qwen (Alibaba)          | Public client.                                                                    |
+| `KIMI_CODING_OAUTH_CLIENT_ID`     | Kimi Coding (Moonshot)  | Public client.                                                                    |
+| `ANTIGRAVITY_OAUTH_CLIENT_ID`     | Antigravity (Google)    | Requires matching `_SECRET`.                                                      |
+| `ANTIGRAVITY_OAUTH_CLIENT_SECRET` | Antigravity (Google)    | —                                                                                 |
+| `GITHUB_OAUTH_CLIENT_ID`          | GitHub Copilot          | Public client.                                                                    |
+| `QODER_OAUTH_CLIENT_SECRET`       | Qoder                   | —                                                                                 |
+| `QODER_OAUTH_AUTHORIZE_URL`       | Qoder                   | Set to enable Qoder OAuth.                                                        |
+| `QODER_OAUTH_TOKEN_URL`           | Qoder                   | —                                                                                 |
+| `QODER_OAUTH_USERINFO_URL`        | Qoder                   | —                                                                                 |
+| `QODER_OAUTH_CLIENT_ID`           | Qoder                   | —                                                                                 |
+| `QODER_PERSONAL_ACCESS_TOKEN`     | Qoder                   | Direct API key fallback (bypasses OAuth).                                         |
+| `QODER_CLI_WORKSPACE`             | Qoder                   | Workspace ID for Qoder CLI.                                                       |
+| `OMNIROUTE_QODER_WORKSPACE`       | Qoder                   | Alias for `QODER_CLI_WORKSPACE`.                                                  |
+
+> [!WARNING]
+> **Google OAuth** (Antigravity, Gemini CLI) credentials **only work on localhost**. For remote servers:
+>
+> 1. Go to [Google Cloud Console → Credentials](https://console.cloud.google.com/apis/credentials)
+> 2. Create an OAuth 2.0 Client ID (type: "Web application")
+> 3. Add your server URL as Authorized redirect URI
+> 4. Replace the credential values in `.env`.
+
+---
+
+## 12. Provider User-Agent Overrides
+
+Override the `User-Agent` header sent to each upstream provider. This is dynamically resolved at runtime by the executor base class:
+
+```
+process.env[`${PROVIDER_ID}_USER_AGENT`]
+```
+
+> **Source:** `open-sse/executors/base.ts` → `buildHeaders()`
+
+| Variable                 | Default Value                                 | When to Update                                                |
+| ------------------------ | --------------------------------------------- | ------------------------------------------------------------- |
+| `CLAUDE_USER_AGENT`      | `claude-cli/2.1.121 (external, cli)`          | When Anthropic releases a new CLI version                     |
+| `CODEX_USER_AGENT`       | `codex-cli/0.125.0 (Windows 10.0.26100; x64)` | When OpenAI updates the Codex CLI                             |
+| `CODEX_CLIENT_VERSION`   | `0.125.0`                                     | Override Codex client version independently of full UA string |
+| `GITHUB_USER_AGENT`      | `GitHubCopilotChat/0.45.1`                    | When GitHub Copilot Chat updates                              |
+| `ANTIGRAVITY_USER_AGENT` | `antigravity/1.107.0 darwin/arm64`            | When Antigravity IDE updates                                  |
+| `KIRO_USER_AGENT`        | `AWS-SDK-JS/3.0.0 kiro-ide/1.0.0`             | When Kiro IDE updates                                         |
+| `QODER_USER_AGENT`       | `Qoder-Cli`                                   | When Qoder CLI updates                                        |
+| `QWEN_USER_AGENT`        | `QwenCode/0.15.3 (linux; x64)`                | When Qwen Code updates                                        |
+| `CURSOR_USER_AGENT`      | `connect-es/1.6.1`                            | When Cursor updates                                           |
+| `GEMINI_CLI_USER_AGENT`  | `google-api-nodejs-client/10.3.0`             | When Google API client updates                                |
+
+> [!TIP]
+> You can add User-Agent overrides for **any** provider using the pattern `{PROVIDER_ID}_USER_AGENT`. The executor dynamically constructs the env var name.
+
+---
+
+## 13. CLI Fingerprint Compatibility
+
+When enabled, OmniRoute reorders HTTP headers and JSON body fields to match the exact signature of official CLI tools. This reduces the risk of account flagging while preserving your proxy IP.
+
+**Source:** `open-sse/config/cliFingerprints.ts`, `open-sse/executors/base.ts`
+
+### Per-Provider
+
+| Variable                   | Effect                                  |
+| -------------------------- | --------------------------------------- |
+| `CLI_COMPAT_CODEX=1`       | Mimics Codex CLI request signature      |
+| `CLI_COMPAT_CLAUDE=1`      | Mimics Claude Code request signature    |
+| `CLI_COMPAT_GITHUB=1`      | Mimics GitHub Copilot request signature |
+| `CLI_COMPAT_ANTIGRAVITY=1` | Mimics Antigravity request signature    |
+| `CLI_COMPAT_KIRO=1`        | Mimics Kiro IDE request signature       |
+| `CLI_COMPAT_CURSOR=1`      | Mimics Cursor request signature         |
+| `CLI_COMPAT_KIMI_CODING=1` | Mimics Kimi Coding request signature    |
+| `CLI_COMPAT_KILOCODE=1`    | Mimics Kilo Code request signature      |
+| `CLI_COMPAT_CLINE=1`       | Mimics Cline request signature          |
+| `CLI_COMPAT_QWEN=1`        | Mimics Qwen Code request signature      |
+
+### Global
+
+| Variable           | Effect                                                          |
+| ------------------ | --------------------------------------------------------------- |
+| `CLI_COMPAT_ALL=1` | Enable fingerprint compatibility for **all** providers at once. |
+
+> [!NOTE]
+> This feature works alongside the User-Agent overrides (§12). The fingerprint system handles header ordering and body field ordering, while User-Agent overrides handle the specific UA string. Both can be enabled independently.
+
+---
+
+## 14. API Key Providers
+
+API keys for providers that use direct authentication. **Preferred setup:** Dashboard → Providers → Add API Key.
+
+Setting via environment variables is an alternative for Docker or headless deployments.
+
+Recognized pattern: `{PROVIDER_ID}_API_KEY`
+
+| Variable             | Provider            |
+| -------------------- | ------------------- |
+| `DEEPSEEK_API_KEY`   | DeepSeek            |
+| `GROQ_API_KEY`       | Groq                |
+| `XAI_API_KEY`        | xAI (Grok)          |
+| `MISTRAL_API_KEY`    | Mistral AI          |
+| `PERPLEXITY_API_KEY` | Perplexity          |
+| `TOGETHER_API_KEY`   | Together AI         |
+| `FIREWORKS_API_KEY`  | Fireworks AI        |
+| `CEREBRAS_API_KEY`   | Cerebras            |
+| `COHERE_API_KEY`     | Cohere              |
+| `NVIDIA_API_KEY`     | NVIDIA NIM          |
+| `NEBIUS_API_KEY`     | Nebius (embeddings) |
+| `QIANFAN_API_KEY`    | Baidu Qianfan       |
+
+> [!TIP]
+> Keys set via the Dashboard are stored encrypted in SQLite and take precedence over environment variables.
+
+---
+
+## 15. Timeout Settings
+
+All values are in **milliseconds**. Centralized resolution in `src/shared/utils/runtimeTimeouts.ts`.
+
+### Timeout Hierarchy
+
+```
+REQUEST_TIMEOUT_MS (global override)
+├─→ FETCH_TIMEOUT_MS (upstream provider calls, default: 600000)
+│   ├─→ FETCH_HEADERS_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS)
+│   ├─→ FETCH_BODY_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS)
+│   ├─→ TLS_CLIENT_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS)
+│   ├── FETCH_CONNECT_TIMEOUT_MS (independent, default: 30000)
+│   └── FETCH_KEEPALIVE_TIMEOUT_MS (independent, default: 4000)
+├─→ STREAM_IDLE_TIMEOUT_MS (inherits from REQUEST_TIMEOUT_MS, default: 600000)
+└─→ API_BRIDGE_PROXY_TIMEOUT_MS (inherits from REQUEST_TIMEOUT_MS, default: 30000)
+    ├─→ API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS (derived, default: 300000)
+    ├── API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS (default: 60000)
+    ├── API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS (default: 5000)
+    └── API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS (default: 0 = disabled)
+```
+
+| Variable                                 | Default              | Description                                                                                 |
+| ---------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------- |
+| `REQUEST_TIMEOUT_MS`                     | _(unset)_            | Global shortcut — overrides both `FETCH_TIMEOUT_MS` and `STREAM_IDLE_TIMEOUT_MS` defaults.  |
+| `FETCH_TIMEOUT_MS`                       | `600000`             | Total HTTP request timeout for upstream provider calls.                                     |
+| `STREAM_IDLE_TIMEOUT_MS`                 | `600000`             | Max silence between SSE chunks before aborting. Extended-thinking models rarely pause >90s. |
+| `FETCH_HEADERS_TIMEOUT_MS`               | = `FETCH_TIMEOUT_MS` | Time to receive response headers.                                                           |
+| `FETCH_BODY_TIMEOUT_MS`                  | = `FETCH_TIMEOUT_MS` | Time to receive the full response body.                                                     |
+| `FETCH_CONNECT_TIMEOUT_MS`               | `30000`              | TCP connection establishment timeout.                                                       |
+| `FETCH_KEEPALIVE_TIMEOUT_MS`             | `4000`               | Keep-alive socket idle timeout.                                                             |
+| `TLS_CLIENT_TIMEOUT_MS`                  | = `FETCH_TIMEOUT_MS` | TLS fingerprint proxy (wreq-js) timeout.                                                    |
+| `API_BRIDGE_PROXY_TIMEOUT_MS`            | `30000`              | Proxy hop timeout for `/v1` bridge requests.                                                |
+| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS`   | `300000`             | Overall server request timeout for the bridge.                                              |
+| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS`   | `60000`              | Time to send response headers via the bridge.                                               |
+| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000`               | Bridge keep-alive idle timeout.                                                             |
+| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS`    | `0`                  | Raw socket timeout (0 = disabled).                                                          |
+| `SHUTDOWN_TIMEOUT_MS`                    | `30000`              | Grace period on SIGTERM/SIGINT before force-exit.                                           |
+
+### Scenarios
+
+| Scenario                         | Configuration                                          |
+| -------------------------------- | ------------------------------------------------------ |
+| **Long-running code generation** | `REQUEST_TIMEOUT_MS=900000` (15 min)                   |
+| **Fast-fail for production API** | `API_BRIDGE_PROXY_TIMEOUT_MS=10000`                    |
+| **Extended thinking models**     | `STREAM_IDLE_TIMEOUT_MS=300000` (5 min between chunks) |
+
+---
+
+## 16. Logging
+
+The logging system writes to both stdout and rotated log files. All configuration is read by `src/lib/logEnv.ts`.
+
+| Variable                                  | Default                    | Description                                                                      |
+| ----------------------------------------- | -------------------------- | -------------------------------------------------------------------------------- |
+| `APP_LOG_LEVEL`                           | `info`                     | Minimum log level: `debug`, `info`, `warn`, `error`.                             |
+| `APP_LOG_FORMAT`                          | `text`                     | Output format: `text` (human-readable) or `json` (structured).                   |
+| `APP_LOG_TO_FILE`                         | `true`                     | Write logs to file alongside stdout.                                             |
+| `APP_LOG_FILE_PATH`                       | `logs/application/app.log` | Log file path (relative to project root or `DATA_DIR`).                          |
+| `APP_LOG_MAX_FILE_SIZE`                   | `50M`                      | Max file size before rotation. Accepts: `50M`, `1G`, `512K`, or plain bytes.     |
+| `APP_LOG_RETENTION_DAYS`                  | `7`                        | Days to keep rotated application log files.                                      |
+| `APP_LOG_MAX_FILES`                       | `20`                       | Maximum rotated log file backups.                                                |
+| `CALL_LOG_RETENTION_DAYS`                 | `7`                        | Days to keep request/call log entries in the database.                           |
+| `CALL_LOG_MAX_ENTRIES`                    | `10000`                    | Max call log entries in the in-memory buffer.                                    |
+| `CALL_LOGS_TABLE_MAX_ROWS`                | `100000`                   | Max rows in the `call_logs` SQLite table before pruning.                         |
+| `CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS` | `true`                     | Store stream chunks in pipeline artifacts when `call_log_pipeline_enabled=true`. |
+| `CALL_LOG_PIPELINE_MAX_SIZE_KB`           | `512`                      | Max pipeline call log artifact size in KB when `call_log_pipeline_enabled=true`. |
+| `PROXY_LOGS_TABLE_MAX_ROWS`               | `100000`                   | Max rows in the `proxy_logs` SQLite table before pruning.                        |
+
+---
+
+## 17. Memory Optimization
+
+| Variable                   | Default                         | Description                                                            |
+| -------------------------- | ------------------------------- | ---------------------------------------------------------------------- |
+| `OMNIROUTE_MEMORY_MB`      | `256` (Docker) / system default | V8 heap limit. Sets `--max-old-space-size`.                            |
+| `PROMPT_CACHE_MAX_SIZE`    | `50`                            | Max cached system prompt entries.                                      |
+| `PROMPT_CACHE_MAX_BYTES`   | `2097152` (2 MB)                | Max total prompt cache size.                                           |
+| `PROMPT_CACHE_TTL_MS`      | `300000` (5 min)                | Prompt cache entry TTL.                                                |
+| `SEMANTIC_CACHE_MAX_SIZE`  | `100`                           | Max cached temperature=0 responses.                                    |
+| `SEMANTIC_CACHE_MAX_BYTES` | `4194304` (4 MB)                | Max total semantic cache size.                                         |
+| `SEMANTIC_CACHE_TTL_MS`    | `1800000` (30 min)              | Semantic cache entry TTL.                                              |
+| `STREAM_HISTORY_MAX`       | `50`                            | Max recent stream events in the Dashboard live view buffer.            |
+| `CONTEXT_LENGTH_DEFAULT`   | `128000`                        | Global fallback max context length for models without explicit config. |
+| `USAGE_TOKEN_BUFFER`       | `100`                           | Extra token headroom reserved when tracking usage quotas.              |
+
+### Low-RAM Docker Example
+
+```bash
+OMNIROUTE_MEMORY_MB=128
+PROMPT_CACHE_MAX_SIZE=20
+PROMPT_CACHE_MAX_BYTES=524288        # 512 KB
+SEMANTIC_CACHE_MAX_SIZE=25
+SEMANTIC_CACHE_MAX_BYTES=1048576     # 1 MB
+STREAM_HISTORY_MAX=10
+```
+
+---
+
+## 18. Pricing Sync
+
+Automatic model pricing data synchronization from external sources.
+
+| Variable                | Default       | Source File              | Description                   |
+| ----------------------- | ------------- | ------------------------ | ----------------------------- |
+| `PRICING_SYNC_ENABLED`  | `false`       | `src/lib/pricingSync.ts` | Opt-in periodic pricing sync. |
+| `PRICING_SYNC_INTERVAL` | `86400` (24h) | `src/lib/pricingSync.ts` | Sync interval in seconds.     |
+| `PRICING_SYNC_SOURCES`  | `litellm`     | `src/lib/pricingSync.ts` | Comma-separated data sources. |
+
+---
+
+## 19. Model Sync (Dev)
+
+| Variable                   | Default       | Source File                | Description                                              |
+| -------------------------- | ------------- | -------------------------- | -------------------------------------------------------- |
+| `MODELS_DEV_SYNC_INTERVAL` | `86400` (24h) | `src/lib/modelsDevSync.ts` | Development-time model catalog sync interval in seconds. |
+
+---
+
+## 20. Provider-Specific Settings
+
+| Variable                                  | Default            | Source File                                | Description                                                                           |
+| ----------------------------------------- | ------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------- |
+| `OPENROUTER_CATALOG_TTL_MS`               | `86400000` (24h)   | `src/lib/catalog/openrouterCatalog.ts`     | OpenRouter model catalog cache TTL.                                                   |
+| `NANOBANANA_POLL_TIMEOUT_MS`              | `120000`           | `open-sse/handlers/imageGeneration.ts`     | Max wait for NanoBanana image generation jobs.                                        |
+| `NANOBANANA_POLL_INTERVAL_MS`             | `2500`             | `open-sse/handlers/imageGeneration.ts`     | NanoBanana job polling frequency.                                                     |
+| `CLOUDFLARE_ACCOUNT_ID`                   | _(unset)_          | `open-sse/executors/cloudflare-ai.ts`      | Account ID for Cloudflare Workers AI.                                                 |
+| `CLOUDFLARED_BIN`                         | auto-detect        | `src/lib/cloudflaredTunnel.ts`             | Custom path to `cloudflared` binary.                                                  |
+| `SEARCH_CACHE_TTL_MS`                     | `300000` (5 min)   | `open-sse/services/searchCache.ts`         | TTL for search API (Perplexity, Brave, etc.) response caching.                        |
+| `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` | `false`            | `src/app/api/providers/route.ts`           | Allow multiple simultaneous connections per OpenAI-compatible provider.               |
+| `ENABLE_CC_COMPATIBLE_PROVIDER`           | `false`            | `src/shared/utils/featureFlags.ts`         | Enable experimental Claude Code compatible provider endpoint.                         |
+| `CLIPROXYAPI_HOST`                        | `127.0.0.1`        | `open-sse/executors/cliproxyapi.ts`        | CLIProxyAPI bridge host (legacy integration).                                         |
+| `CLIPROXYAPI_PORT`                        | `5544`             | `open-sse/executors/cliproxyapi.ts`        | CLIProxyAPI bridge port.                                                              |
+| `CLIPROXYAPI_CONFIG_DIR`                  | `~/.cli-proxy-api` | `src/lib/versionManager/processManager.ts` | CLIProxyAPI config directory.                                                         |
+| `LOCAL_HOSTNAMES`                         | _(empty)_          | `open-sse/config/providerRegistry.ts`      | Comma-separated additional hostnames treated as "local" (Docker service names, etc.). |
+
+---
+
+## 21. Proxy Health
+
+| Variable                     | Default          | Source File                              | Description                                                                                                         |
+| ---------------------------- | ---------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `PROXY_FAST_FAIL_TIMEOUT_MS` | `2000`           | `src/lib/proxyHealth.ts`                 | Fast-fail health check timeout.                                                                                     |
+| `PROXY_HEALTH_CACHE_TTL_MS`  | `30000`          | `src/lib/proxyHealth.ts`                 | Health check result cache TTL.                                                                                      |
+| `RATE_LIMIT_MAX_WAIT_MS`     | `120000` (2 min) | `open-sse/services/rateLimitManager.ts`  | Max time to wait on a 429 before failing the request.                                                               |
+| `REQUEST_RETRY`              | `2`              | `src/sse/services/cooldownAwareRetry.ts` | Number of automatic retries on model-scoped cooldown responses before returning error to client.                    |
+| `MAX_RETRY_INTERVAL_SEC`     | `30`             | `src/sse/services/cooldownAwareRetry.ts` | Max backoff interval (seconds) between cooldown retries. Capped by this value regardless of upstream `Retry-After`. |
+
+---
+
+## 22. Debugging
+
+> [!CAUTION]
+> These variables produce **verbose output** and may leak sensitive data. **Never enable in production.**
+
+| Variable                         | Default   | Source File                               | Description                                                    |
+| -------------------------------- | --------- | ----------------------------------------- | -------------------------------------------------------------- |
+| `CURSOR_PROTOBUF_DEBUG`          | _(unset)_ | `open-sse/utils/cursorProtobuf.ts`        | Set `1` to dump Cursor protobuf decode/encode details.         |
+| `CURSOR_STREAM_DEBUG`            | _(unset)_ | `open-sse/executors/cursor.ts`            | Set `1` to dump raw Cursor SSE stream data.                    |
+| `DEBUG_RESPONSES_SSE_TO_JSON`    | _(unset)_ | `open-sse/handlers/responseTranslator.ts` | Set `true` to log Responses API SSE→JSON translation details.  |
+| `NEXT_PUBLIC_OMNIROUTE_E2E_MODE` | _(unset)_ | E2E test harness                          | Set `true` to enable E2E test mode (relaxed auth, test hooks). |
+
+---
+
+## 23. GitHub Integration
+
+Allow users to report issues directly from the Dashboard.
+
+| Variable              | Default   | Source File                             | Description                                             |
+| --------------------- | --------- | --------------------------------------- | ------------------------------------------------------- |
+| `GITHUB_ISSUES_REPO`  | _(unset)_ | `src/app/api/v1/issues/report/route.ts` | Repository in `owner/repo` format.                      |
+| `GITHUB_ISSUES_TOKEN` | _(unset)_ | `src/app/api/v1/issues/report/route.ts` | GitHub Personal Access Token with `issues:write` scope. |
+
+---
+
+## Deployment Scenarios
+
+### Minimal Local Development
+
+```bash
+JWT_SECRET=$(openssl rand -base64 48)
+API_KEY_SECRET=$(openssl rand -hex 32)
+INITIAL_PASSWORD=dev123
+PORT=20128
+NODE_ENV=development
+```
+
+### Docker Production
+
+```bash
+JWT_SECRET=<generated>
+API_KEY_SECRET=<generated>
+INITIAL_PASSWORD=<generated>
+STORAGE_ENCRYPTION_KEY=<generated>
+DATA_DIR=/data
+PORT=20128
+API_PORT=20129
+NODE_ENV=production
+AUTH_COOKIE_SECURE=true
+REQUIRE_API_KEY=true
+NEXT_PUBLIC_BASE_URL=https://omniroute.example.com
+BASE_URL=http://localhost:20128
+OMNIROUTE_MEMORY_MB=512
+CORS_ORIGIN=https://your-frontend.example.com
+```
+
+### Air-Gapped / CI
+
+```bash
+JWT_SECRET=test-jwt-secret-for-ci
+API_KEY_SECRET=test-api-key-secret-for-ci
+INITIAL_PASSWORD=testpass
+NODE_ENV=production
+OMNIROUTE_DISABLE_BACKGROUND_SERVICES=true
+APP_LOG_TO_FILE=false
+```
+
+### VPS with Reverse Proxy (nginx + Cloudflare)
+
+```bash
+JWT_SECRET=<generated>
+API_KEY_SECRET=<generated>
+STORAGE_ENCRYPTION_KEY=<generated>
+PORT=20128
+AUTH_COOKIE_SECURE=true
+REQUIRE_API_KEY=true
+NEXT_PUBLIC_BASE_URL=https://omniroute.example.com
+BASE_URL=http://127.0.0.1:20128
+CORS_ORIGIN=https://omniroute.example.com
+ENABLE_TLS_FINGERPRINT=true
+CLI_COMPAT_ALL=1
+```
+
+---
+
+## Audit: Removed / Dead Variables
+
+The following variables appeared in previous versions of `.env.example` but have **no runtime references** in the current codebase. They have been removed:
+
+| Variable                                              | Reason                                                                                                  |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `STORAGE_DRIVER=sqlite`                               | Never read by any source file. SQLite is the only supported driver — no selection needed.               |
+| `INSTANCE_NAME=omniroute`                             | Present in old docs/env templates but unused at runtime. May return in a future multi-instance feature. |
+| `SQLITE_MAX_SIZE_MB=2048`                             | Not referenced in source code. Database size is not artificially limited.                               |
+| `SQLITE_CLEAN_LEGACY_FILES=true`                      | Not referenced in source code. Legacy cleanup was likely removed.                                       |
+| `CLI_ROO_BIN`                                         | Not registered in `src/shared/services/cliRuntime.ts`.                                                  |
+| `CLI_KIMI_CODING_BIN`                                 | Not registered in `src/shared/services/cliRuntime.ts` (Kimi Coding uses OAuth, not a CLI binary).       |
+| `IFLOW_OAUTH_CLIENT_ID` / `IFLOW_OAUTH_CLIENT_SECRET` | Not referenced anywhere in source code.                                                                 |
+
+### Default Value Corrections
+
+| Variable                  | Old `.env.example` Value | Actual Code Default | Fixed                                                  |
+| ------------------------- | ------------------------ | ------------------- | ------------------------------------------------------ |
+| `APP_LOG_RETENTION_DAYS`  | `90`                     | `7`                 | ✅ Removed misleading value; documented `7` as default |
+| `CALL_LOG_RETENTION_DAYS` | `90`                     | `7`                 | ✅ Removed misleading value; documented `7` as default |

docs/FEATURES.md

@@ -16,7 +16,14 @@ Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI)
 
 ## 🎨 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.
+Create model routing combos with 13 strategies: priority, weighted, round-robin, random, least-used, cost-optimized, strict-random, auto, fill-first, p2c, lkgp, context-optimized, and **context-relay**. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+Recent combo improvements:
+
+- **Structured combo builder** — create each step by selecting provider, model, and exact account/connection
+- **Repeated provider support** — reuse the same provider many times in one combo as long as the `(provider, model, connection)` tuple is unique
+- **Combo target health** — analytics and health surfaces now distinguish individual combo targets/steps instead of collapsing everything into model strings
+- **Composite tier ordering** — `defaultTier -> fallbackTier` now influences runtime execution/fallback order for top-level combo steps
 
 ![Combos Dashboard](screenshots/02-combos.png)
 
@@ -32,7 +39,7 @@ Comprehensive usage analytics with token consumption, cost estimates, activity h
 
 ## 🏥 System Health
 
-Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, provider circuit breaker states, active quota-monitored sessions, and combo target health.
 
 ![Health Dashboard](screenshots/04-health.png)
 
@@ -66,7 +73,7 @@ Comprehensive settings panel with tabs:
 - **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
 - **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
 - **Routing** — Model aliases, background task degradation
-- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring
+- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring, **Context Relay** handoff threshold and summary model configuration
 - **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
 
 ![Settings Dashboard](screenshots/06-settings.png)
@@ -92,6 +99,68 @@ Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in a
 
 ---
 
+## 🔗 Context Relay _(v3.5.5+)_
+
+A combo strategy that preserves session continuity when account rotation happens mid-conversation. Before the active account is exhausted, OmniRoute generates a structured handoff summary in the background. After the next request resolves to a different account, the summary is injected as a system message so the new account continues with full context.
+
+Configurable via combo-level or global settings:
+
+- **Handoff Threshold** — Quota usage percentage that triggers summary generation (default 85%)
+- **Max Messages For Summary** — How much recent history to condense
+- **Summary Model** — Optional override model for generating the handoff summary
+
+Currently supports Codex account rotation. See [Context Relay documentation](features/context-relay.md).
+
+---
+
+## 🛡️ Proxy Hardening _(v3.5.5+)_
+
+Comprehensive proxy configuration enforcement across the entire request pipeline:
+
+- **Token Health Check** — Background OAuth refresh now resolves proxy config per connection, preventing failures in proxy-required environments
+- **API Key Validation** — Provider key validation (`POST /api/providers/validate`) routes through `runWithProxyContext`, honoring provider-level and global proxy settings
+- **undici Dispatcher Fix** — Proxy dispatchers use undici's own fetch implementation instead of Node's built-in fetch, resolving `invalid onRequestStart method` errors on Node.js 22
+- **Node.js Version Detection** — Login page proactively detects incompatible Node.js versions (24+) and displays a warning banner with instructions to use Node 22 LTS
+
+---
+
+## 📧 Email Privacy Masking _(v3.5.6+)_
+
+OAuth account emails are now masked in the provider dashboard (e.g. `di*****@g****.com`) to prevent accidental exposure when sharing screenshots or recording demos. The full email address remains accessible via hover tooltip (`title` attribute).
+
+---
+
+## 👁️ Model Visibility Toggle _(v3.5.6+)_
+
+The provider page model list now includes:
+
+- **Real-time search/filter bar** — Quickly find specific models
+- **Per-model visibility toggle** (👁 icon) — Hidden models are grayed out and excluded from the `/v1/models` catalog
+- **Active-count badge** (`N/M active`) — Shows at a glance how many models are enabled vs total
+
+---
+
+## 🔧 OAuth Env Repair _(v3.6.1+)_
+
+One-click "Repair env" action for OAuth providers that restores missing environment variables and fixes broken auth state. Accessible from `Dashboard → Providers → [OAuth Provider] → Repair env`. Automatically detects and repairs:
+
+- Missing OAuth client credentials
+- Corrupted env file entries
+- Backup path sanitization
+
+---
+
+## 🗑️ Uninstall / Full Uninstall _(v3.6.2+)_
+
+Clean removal scripts for all installation methods:
+
+| Command                  | Action                                                                              |
+| ------------------------ | ----------------------------------------------------------------------------------- |
+| `npm run uninstall`      | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`.  |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+---
+
 ## 🖼️ 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.
@@ -139,5 +208,61 @@ Key features:
 - 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+)
+- **Graceful shutdown** — Electron `before-quit` shuts down Next.js cleanly, preventing SQLite WAL database locks (v3.6.2+)
 
 📖 See [`electron/README.md`](../electron/README.md) for full documentation.
+
+---
+
+## 🌐 V1 WebSocket Bridge _(v3.6.6+)_
+
+OmniRoute now supports **OpenAI-compatible WebSocket clients** via the `/v1/ws` upgrade endpoint. The custom `scripts/v1-ws-bridge.mjs` server wraps Next.js and upgrades WS connections to full bidirectional streaming sessions. Authentication uses the same API key or session cookie as HTTP requests.
+
+Key behaviours:
+
+- WS upgrade validated by `src/lib/ws/handshake.ts` before the connection is established
+- Streams terminated cleanly on session close or upstream error
+- Works alongside the existing HTTP+SSE streaming path simultaneously
+
+---
+
+## 🔑 Sync Tokens & Config Bundle _(v3.6.6+)_
+
+Multi-device and external operator access is now possible via **scoped sync tokens**:
+
+- **`POST /api/sync/tokens`** — Issue a new sync token (scoped, with optional expiry)
+- **`DELETE /api/sync/tokens/:id`** — Revoke a token
+- **`GET /api/sync/bundle`** — Download a versioned, ETag-keyed JSON snapshot of all non-sensitive settings (passwords redacted)
+
+The config bundle is built by `src/lib/sync/bundle.ts`. Consumers compare the `ETag` response header to detect changes without re-downloading the full payload.
+
+---
+
+## 🧠 GLM Thinking Preset _(v3.6.6+)_
+
+**GLM Thinking (`glmt`)** is now a registered first-class provider: 65 536 max output tokens, 24 576 thinking budget, 900 s default timeout, Claude-compatible API format, and shared usage sync with the GLM family.
+
+**Hybrid token counting** also lands in v3.6.6: when a Claude-compatible provider exposes `/messages/count_tokens`, OmniRoute calls it before large requests with graceful estimation fallback.
+
+---
+
+## 🛡️ Safe Outbound Fetch & SSRF Guard _(v3.6.6+)_
+
+All provider validation and model discovery calls now go through a two-layer outbound guard:
+
+1. **URL guard** (`src/shared/network/outboundUrlGuard.ts`) — Blocks private/loopback/link-local IP ranges before the socket is opened.
+2. **Safe fetch wrapper** (`src/shared/network/safeOutboundFetch.ts`) — Applies the URL guard, normalises timeouts, and retries transient errors with exponential backoff.
+
+Guard violations surface as HTTP 422 (`URL_GUARD_BLOCKED`) and are written to the compliance audit log via `providerAudit.ts`.
+
+---
+
+## 🔄 Cooldown-Aware Retries _(v3.6.6+)_
+
+Chat requests now **automatically retry** when an upstream provider returns a model-scoped cooldown. Configurable via `REQUEST_RETRY` (default: 2) and `MAX_RETRY_INTERVAL_SEC` (default: 30 s). Rate-limit header learning improved across `x-ratelimit-reset-requests`, `x-ratelimit-reset-tokens`, and `Retry-After` — per-model cooldown state is visible in the Resilience dashboard.
+
+---
+
+## 📋 Compliance Audit v2 _(v3.6.6+)_
+
+The audit log has been expanded with cursor-based pagination, request context enrichment (request ID, user agent, IP), structured auth events, provider CRUD events with diff context, and SSRF-blocked validation logging. New events emitted by `src/lib/compliance/providerAudit.ts`.

docs/RELEASE_CHECKLIST.md

@@ -20,7 +20,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
 
 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.
+3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
+   - `>=20.20.2 <21` or `>=22.22.2 <23`
+   - `npm run check:node-runtime`
+4. Validate the npm publish artifact after building the standalone package:
+   - `npm run build:cli`
+   - `npm run check:pack-artifact`
+   - confirm no `app.__qa_backup`, `scripts/scratch`, `package-lock.json`, or other local residue
+5. Update localized docs if source docs changed significantly.
 
 ## Automated Check
 

docs/TROUBLESHOOTING.md

@@ -8,13 +8,95 @@ Common problems and solutions for OmniRoute.
 
 ## Quick Fixes
 
-| Problem                       | Solution                                                           |
-| ----------------------------- | ------------------------------------------------------------------ |
-| First login not working       | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default)            |
-| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` |
-| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true`                                     |
-| EACCES: permission denied     | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute`    |
-| Routing strategy not saving   | Update to v1.4.11+ (Zod schema fix for settings persistence)       |
+| Problem                                             | Solution                                                                                                                                                 |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| First login not working                             | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default)                                                                                                  |
+| Dashboard opens on wrong port                       | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128`                                                                                       |
+| No logs written to disk                             | Set `APP_LOG_TO_FILE=true` and verify call log capture is enabled                                                                                        |
+| EACCES: permission denied                           | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute`                                                                                          |
+| Routing strategy not saving                         | Update to v1.4.11+ (Zod schema fix for settings persistence)                                                                                             |
+| Login crash / blank page                            | Check Node.js version — see [Node.js Compatibility](#nodejs-compatibility) below                                                                         |
+| `dlopen` / `slice is not valid mach-o file` (macOS) | Run `cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute` — see [macOS native module rebuild](#macos-native-module-rebuild) below |
+| Proxy "fetch failed"                                | Ensure proxy config is set at the correct level — see [Proxy Issues](#proxy-issues) below                                                                |
+
+---
+
+## Node.js Compatibility
+
+<a name="nodejs-compatibility"></a>
+
+### Login page crashes or shows "Module self-registration" error
+
+**Cause:** You are running a Node.js version outside OmniRoute's approved secure runtime floor. The most common case is running an older Node 20, 22, or 24 patch level that falls below the patched security floor OmniRoute requires.
+
+**Symptoms:**
+
+- Login page shows a blank screen or a server error
+- Console shows `Error: Module did not self-register` or similar native binding errors
+- The login page shows an **orange warning banner** with your Node version if the runtime is outside the supported secure policy
+
+**Fix:**
+
+1. Install a supported Node.js LTS release (recommended: Node.js 24.x):
+   ```bash
+   nvm install 24
+   nvm use 24
+   ```
+2. Verify your version: `node --version` should show `v24.0.0` or newer on the 24.x LTS line
+3. Reinstall OmniRoute: `npm install -g omniroute`
+4. Restart: `omniroute`
+
+> **Supported secure versions:** `>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25`. Node.js 24.x LTS (Krypton) is fully supported.
+
+### macOS: `dlopen` / "slice is not valid mach-o file"
+
+<a name="macos-native-module-rebuild"></a>
+
+**Cause:** After a global `npm install -g omniroute`, the `better-sqlite3` native binary inside the package may have been compiled for a different architecture or Node.js ABI than what is running locally. This is common on macOS (both Apple Silicon and Intel) when the pre-built binary does not match your environment.
+
+**Symptoms:**
+
+- Server fails immediately on startup with a `dlopen` error
+- Error contains `slice is not valid mach-o file`
+- Full example:
+
+```
+dlopen(/Users/<user>/.nvm/versions/node/v24.14.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file)
+```
+
+**Fix — rebuild for your local environment (no Node.js downgrade required):**
+
+```bash
+cd $(npm root -g)/omniroute/app
+npm rebuild better-sqlite3
+omniroute
+```
+
+> **Note:** This recompiles the native binding against your local Node.js version and CPU architecture, resolving the binary mismatch. The officially supported range is **`>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25`** (`engines` field in `package.json`). Node.js 24.x LTS (Krypton) is fully supported with `better-sqlite3` v12.x.
+
+---
+
+## Proxy Issues
+
+<a name="proxy-issues"></a>
+
+### Provider validation shows "fetch failed"
+
+**Cause:** The API key validation endpoint (`POST /api/providers/validate`) was previously bypassing proxy configuration, causing failures in environments that require proxy routing.
+
+**Fix (v3.5.5+):** This is now fixed. Provider validation routes through `runWithProxyContext`, honoring provider-level and global proxy settings automatically.
+
+### Token health check fails with "fetch failed"
+
+**Cause:** Background OAuth token refresh was not resolving proxy configuration per connection.
+
+**Fix (v3.5.5+):** The token health check scheduler now resolves proxy config per connection before attempting refresh. Update to v3.5.5+.
+
+### SOCKS5 proxy returns "invalid onRequestStart method"
+
+**Cause:** On Node.js 22, the undici@8 dispatcher is incompatible with Node's built-in `fetch()` implementation.
+
+**Fix (v3.5.5+):** OmniRoute now uses undici's own `fetch()` function when a proxy dispatcher is active, ensuring consistent behavior. Update to v3.5.5+.
 
 ---
 
@@ -104,9 +186,13 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
 
 ## Debugging
 
-### Enable Request Logs
+### Enable Log Files
 
-Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory.
+Set `APP_LOG_TO_FILE=true` in your `.env` file. Application logs are written under `logs/`.
+Request artifacts are stored under `${DATA_DIR}/call_logs/` when the call log pipeline is
+enabled in settings.
+When pipeline capture is enabled, set `CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=false` to omit
+stream chunk payloads, or tune `CALL_LOG_PIPELINE_MAX_SIZE_KB` to change the artifact cap in KB.
 
 ### Check Provider Health
 
@@ -121,8 +207,9 @@ curl http://localhost:20128/api/monitoring/health
 ### Runtime Storage
 
 - Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings)
-- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/`
-- Request logs: `<repo>/logs/...` (when `ENABLE_REQUEST_LOGS=true`)
+- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/call_logs/`
+- Application logs: `<repo>/logs/...` (when `APP_LOG_TO_FILE=true`)
+- Call log artifacts: `${DATA_DIR}/call_logs/YYYY-MM-DD/...` when the call log pipeline is enabled
 
 ---
 

docs/UNINSTALL.md

@@ -0,0 +1,155 @@
+# OmniRoute — Uninstall Guide
+
+🌐 **Languages:** 🇺🇸 [English](UNINSTALL.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/UNINSTALL.md) | 🇪🇸 [Español](i18n/es/UNINSTALL.md) | 🇫🇷 [Français](i18n/fr/UNINSTALL.md) | 🇮🇹 [Italiano](i18n/it/UNINSTALL.md) | 🇷🇺 [Русский](i18n/ru/UNINSTALL.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/UNINSTALL.md) | 🇩🇪 [Deutsch](i18n/de/UNINSTALL.md) | 🇮🇳 [हिन्दी](i18n/in/UNINSTALL.md) | 🇹🇭 [ไทย](i18n/th/UNINSTALL.md) | 🇺🇦 [Українська](i18n/uk-UA/UNINSTALL.md) | 🇸🇦 [العربية](i18n/ar/UNINSTALL.md) | 🇯🇵 [日本語](i18n/ja/UNINSTALL.md) | 🇻🇳 [Tiếng Việt](i18n/vi/UNINSTALL.md) | 🇧🇬 [Български](i18n/bg/UNINSTALL.md) | 🇩🇰 [Dansk](i18n/da/UNINSTALL.md) | 🇫🇮 [Suomi](i18n/fi/UNINSTALL.md) | 🇮🇱 [עברית](i18n/he/UNINSTALL.md) | 🇭🇺 [Magyar](i18n/hu/UNINSTALL.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/UNINSTALL.md) | 🇰🇷 [한국어](i18n/ko/UNINSTALL.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/UNINSTALL.md) | 🇳🇱 [Nederlands](i18n/nl/UNINSTALL.md) | 🇳🇴 [Norsk](i18n/no/UNINSTALL.md) | 🇵🇹 [Português (Portugal)](i18n/pt/UNINSTALL.md) | 🇷🇴 [Română](i18n/ro/UNINSTALL.md) | 🇵🇱 [Polski](i18n/pl/UNINSTALL.md) | 🇸🇰 [Slovenčina](i18n/sk/UNINSTALL.md) | 🇸🇪 [Svenska](i18n/sv/UNINSTALL.md) | 🇵🇭 [Filipino](i18n/phi/UNINSTALL.md) | 🇨🇿 [Čeština](i18n/cs/UNINSTALL.md)
+
+This guide covers how to cleanly remove OmniRoute from your system.
+
+---
+
+## Quick Uninstall (v3.6.2+)
+
+OmniRoute provides two built-in scripts for clean removal:
+
+### Keep Your Data
+
+```bash
+npm run uninstall
+```
+
+This removes the OmniRoute application but **preserves** your database, configurations, API keys, and provider settings in `~/.omniroute/`. Use this if you plan to reinstall later and want to keep your setup.
+
+### Full Removal
+
+```bash
+npm run uninstall:full
+```
+
+This removes the application **and permanently erases** all data:
+
+- Database (`storage.sqlite`)
+- Provider configurations and API keys
+- Backup files
+- Log files
+- All files in the `~/.omniroute/` directory
+
+> ⚠️ **Warning:** `npm run uninstall:full` is irreversible. All your provider connections, combos, API keys, and usage history will be permanently deleted.
+
+---
+
+## Manual Uninstall
+
+### NPM Global Install
+
+```bash
+# Remove the global package
+npm uninstall -g omniroute
+
+# (Optional) Remove data directory
+rm -rf ~/.omniroute
+```
+
+### pnpm Global Install
+
+```bash
+pnpm uninstall -g omniroute
+rm -rf ~/.omniroute
+```
+
+### Docker
+
+```bash
+# Stop and remove the container
+docker stop omniroute
+docker rm omniroute
+
+# Remove the volume (deletes all data)
+docker volume rm omniroute-data
+
+# (Optional) Remove the image
+docker rmi diegosouzapw/omniroute:latest
+```
+
+### Docker Compose
+
+```bash
+# Stop and remove containers
+docker compose down
+
+# Also remove volumes (deletes all data)
+docker compose down -v
+```
+
+### Electron Desktop App
+
+**Windows:**
+
+- Open `Settings → Apps → OmniRoute → Uninstall`
+- Or run the NSIS uninstaller from the install directory
+
+**macOS:**
+
+- Drag `OmniRoute.app` from `/Applications` to Trash
+- Remove data: `rm -rf ~/Library/Application Support/omniroute`
+
+**Linux:**
+
+- Remove the AppImage file
+- Remove data: `rm -rf ~/.omniroute`
+
+### Source Install (git clone)
+
+```bash
+# Remove the cloned directory
+rm -rf /path/to/omniroute
+
+# (Optional) Remove data directory
+rm -rf ~/.omniroute
+```
+
+---
+
+## Data Directories
+
+OmniRoute stores data in the following locations by default:
+
+| Platform      | Default Path                  | Override                  |
+| ------------- | ----------------------------- | ------------------------- |
+| Linux         | `~/.omniroute/`               | `DATA_DIR` env var        |
+| macOS         | `~/.omniroute/`               | `DATA_DIR` env var        |
+| Windows       | `%APPDATA%/omniroute/`        | `DATA_DIR` env var        |
+| Docker        | `/app/data/` (mounted volume) | `DATA_DIR` env var        |
+| XDG-compliant | `$XDG_CONFIG_HOME/omniroute/` | `XDG_CONFIG_HOME` env var |
+
+### Files in the data directory
+
+| File/Directory       | Description                                       |
+| -------------------- | ------------------------------------------------- |
+| `storage.sqlite`     | Main database (providers, combos, settings, keys) |
+| `storage.sqlite-wal` | SQLite write-ahead log (temporary)                |
+| `storage.sqlite-shm` | SQLite shared memory (temporary)                  |
+| `call_logs/`         | Request payload archives                          |
+| `backups/`           | Automatic database backups                        |
+| `log.txt`            | Legacy request log (optional)                     |
+
+---
+
+## Verify Complete Removal
+
+After uninstalling, verify there are no remaining files:
+
+```bash
+# Check for global npm package
+npm list -g omniroute 2>/dev/null
+
+# Check for data directory
+ls -la ~/.omniroute/ 2>/dev/null
+
+# Check for running processes
+pgrep -f omniroute
+```
+
+If any process is still running, stop it:
+
+```bash
+pkill -f omniroute
+```

docs/USER_GUIDE.md

@@ -36,6 +36,7 @@ Complete guide for configuring providers, creating combos, integrating CLI tools
 |                     | Cerebras          | Pay per use | None             | Wafer-scale speed    |
 |                     | Cohere            | Pay per use | None             | Command R+ RAG       |
 |                     | NVIDIA NIM        | Pay per use | None             | Enterprise models    |
+|                     | Baidu Qianfan     | Pay per use | None             | ERNIE 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     |
@@ -55,7 +56,7 @@ Complete guide for configuring providers, creating combos, integrating CLI tools
 
 ```
 Combo: "maximize-claude"
-  1. cc/claude-opus-4-6        (use subscription fully)
+  1. cc/claude-opus-4-7        (use subscription fully)
   2. glm/glm-4.7               (cheap backup when quota out)
   3. if/kimi-k2-thinking       (free emergency fallback)
 
@@ -83,7 +84,7 @@ Quality: Production-ready models
 
 ```
 Combo: "always-on"
-  1. cc/claude-opus-4-6        (best quality)
+  1. cc/claude-opus-4-7        (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)
@@ -121,7 +122,7 @@ Dashboard → Providers → Connect Claude Code
 → 5-hour + weekly quota tracking
 
 Models:
-  cc/claude-opus-4-6
+  cc/claude-opus-4-7
   cc/claude-sonnet-4-5-20250929
   cc/claude-haiku-4-5-20251001
 ```
@@ -191,6 +192,13 @@ Models:
 
 **Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
 
+#### Baidu Qianfan / ERNIE
+
+1. Sign up: [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop)
+2. Create a Qianfan API key → Dashboard → Add API Key: Provider: `qianfan`
+
+**Use:** `qianfan/ernie-4.5-turbo-128k`, `qianfan/ernie-x1-turbo-32k`, or another Qianfan OpenAI-compatible model ID.
+
 ### 🆓 FREE Providers
 
 #### Qoder (8 FREE models)
@@ -221,6 +229,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
 
 ## 🎨 Combos
 
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
 ### Example 1: Maximize Subscription → Cheap Backup
 
 ```
@@ -228,7 +238,7 @@ Dashboard → Combos → Create New
 
 Name: premium-coding
 Models:
-  1. cc/claude-opus-4-6 (Subscription primary)
+  1. cc/claude-opus-4-7 (Subscription primary)
   2. glm/glm-4.7 (Cheap backup, $0.6/1M)
   3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
 
@@ -257,7 +267,7 @@ Cost: $0 forever!
 Settings → Models → Advanced:
   OpenAI API Base URL: http://localhost:20128/v1
   OpenAI API Key: [from omniroute dashboard]
-  Model: cc/claude-opus-4-6
+  Model: cc/claude-opus-4-7
 ```
 
 ### Claude Code
@@ -311,7 +321,7 @@ Edit `~/.openclaw/openclaw.json`:
 Provider: OpenAI Compatible
 Base URL: http://localhost:20128/v1
 API Key: [from dashboard]
-Model: cc/claude-opus-4-6
+Model: cc/claude-opus-4-7
 ```
 
 ---
@@ -337,6 +347,17 @@ omniroute --port 3000
 
 The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
 
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command                  | Action                                                                              |
+| ------------------------ | ----------------------------------------------------------------------------------- |
+| `npm run uninstall`      | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`.  |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
 ### VPS Deployment
 
 ```bash
@@ -491,7 +512,7 @@ do_install() {
 #!/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}"
+export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
 mkdir -p "${DATA_DIR}"
 exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
 EOF
@@ -522,7 +543,7 @@ post_install() {
 | `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                                                                             |
+| `APP_LOG_TO_FILE`                       | `true`                               | Enables application and audit log output to disk                                                          |
 | `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`)                                          |
@@ -539,7 +560,7 @@ For the full environment variable reference, see the [README](../README.md).
 <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`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-7`, `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`
 
@@ -577,6 +598,8 @@ For the full environment variable reference, see the [README](../README.md).
 
 **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
 
+**Baidu Qianfan (`qianfan/`)**: `qianfan/ernie-4.5-turbo-128k`, `qianfan/ernie-x1-turbo-32k`
+
 </details>
 
 ---
@@ -732,7 +755,7 @@ Define global fallback chains that apply across all requests:
 
 ```
 Chain: production-fallback
-  1. cc/claude-opus-4-6
+  1. cc/claude-opus-4-7
   2. gh/gpt-5.1-codex
   3. glm/glm-4.7
 ```
@@ -743,30 +766,34 @@ Chain: production-fallback
 
 Configure via **Dashboard → Settings → Resilience**.
 
-OmniRoute implements provider-level resilience with four components:
+OmniRoute implements provider-level resilience with five 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:
+1. **Request Queue & Pacing** — System-level request shaping:
    - **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:
+2. **Connection Cooldown** — Per-auth-type configuration for a single connection after retryable failures:
+   - **Base Cooldown** — Default cooldown window for retryable upstream failures
+   - **Use Upstream Retry Hints** — Honors authoritative `Retry-After` or reset hints when provided
+   - **Max Backoff Steps** — Maximum exponential backoff level for repeated failures
+
+3. **Provider Circuit Breaker** — Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:
+   - **Failure Threshold** — Consecutive provider failures before opening the breaker
+   - **Reset Timeout** — Time window before the provider is tested again
    - **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.
+   Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.
 
-5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
+   The provider breaker runtime state is shown on **Dashboard → Health** only.
 
-**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
+4. **Wait For Cooldown** — If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.
+
+5. **Rate Limit Auto-Detection** — When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.
+
+**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.
 
 ---
 
@@ -806,14 +833,14 @@ curl -X POST http://localhost:20128/api/db-backups/import \
 
 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 |
-| **AI**         | Thinking budget configuration, global system prompt injection, prompt cache stats              |
-| **Advanced**   | Global proxy configuration (HTTP/SOCKS5)                                                       |
+| 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** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior  |
+| **AI**         | Thinking budget configuration, global system prompt injection, prompt cache stats            |
+| **Advanced**   | Global proxy configuration (HTTP/SOCKS5)                                                     |
 
 ---
 
@@ -886,9 +913,9 @@ Access via **Dashboard → Health**. Real-time system health overview with 6 car
 | 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         |
+| **Provider Health**   | Global provider circuit breaker runtime state               |
+| **Rate Limits**       | Active connection cooldowns per account with remaining time |
+| **Active Lockouts**   | Active model-scoped lockouts and temporary exclusions       |
 | **Signature Cache**   | Deduplication cache stats (active keys, hit rate)           |
 | **Latency Telemetry** | p50/p95/p99 latency aggregation per provider                |
 

docs/VM_DEPLOYMENT_GUIDE.md

@@ -106,7 +106,7 @@ NODE_ENV=production
 HOSTNAME=0.0.0.0
 DATA_DIR=/app/data
 STORAGE_DRIVER=sqlite
-ENABLE_REQUEST_LOGS=true
+APP_LOG_TO_FILE=true
 AUTH_COOKIE_SECURE=false
 REQUIRE_API_KEY=false
 

docs/features/context-relay.md

@@ -0,0 +1,130 @@
+# Context Relay
+
+🌐 **Languages:** 🇺🇸 [English](context-relay.md) · 🇪🇸 [es](../i18n/es/docs/features/context-relay.md) · 🇫🇷 [fr](../i18n/fr/docs/features/context-relay.md) · 🇩🇪 [de](../i18n/de/docs/features/context-relay.md) · 🇮🇹 [it](../i18n/it/docs/features/context-relay.md) · 🇷🇺 [ru](../i18n/ru/docs/features/context-relay.md) · 🇨🇳 [zh-CN](../i18n/zh-CN/docs/features/context-relay.md) · 🇯🇵 [ja](../i18n/ja/docs/features/context-relay.md) · 🇰🇷 [ko](../i18n/ko/docs/features/context-relay.md) · 🇸🇦 [ar](../i18n/ar/docs/features/context-relay.md) · 🇮🇳 [hi](../i18n/hi/docs/features/context-relay.md) · 🇮🇳 [in](../i18n/in/docs/features/context-relay.md) · 🇹🇭 [th](../i18n/th/docs/features/context-relay.md) · 🇻🇳 [vi](../i18n/vi/docs/features/context-relay.md) · 🇮🇩 [id](../i18n/id/docs/features/context-relay.md) · 🇲🇾 [ms](../i18n/ms/docs/features/context-relay.md) · 🇳🇱 [nl](../i18n/nl/docs/features/context-relay.md) · 🇵🇱 [pl](../i18n/pl/docs/features/context-relay.md) · 🇸🇪 [sv](../i18n/sv/docs/features/context-relay.md) · 🇳🇴 [no](../i18n/no/docs/features/context-relay.md) · 🇩🇰 [da](../i18n/da/docs/features/context-relay.md) · 🇫🇮 [fi](../i18n/fi/docs/features/context-relay.md) · 🇵🇹 [pt](../i18n/pt/docs/features/context-relay.md) · 🇷🇴 [ro](../i18n/ro/docs/features/context-relay.md) · 🇭🇺 [hu](../i18n/hu/docs/features/context-relay.md) · 🇧🇬 [bg](../i18n/bg/docs/features/context-relay.md) · 🇸🇰 [sk](../i18n/sk/docs/features/context-relay.md) · 🇺🇦 [uk-UA](../i18n/uk-UA/docs/features/context-relay.md) · 🇮🇱 [he](../i18n/he/docs/features/context-relay.md) · 🇵🇭 [phi](../i18n/phi/docs/features/context-relay.md) · 🇧🇷 [pt-BR](../i18n/pt-BR/docs/features/context-relay.md) · 🇨🇿 [cs](../i18n/cs/docs/features/context-relay.md) · 🇹🇷 [tr](../i18n/tr/docs/features/context-relay.md)
+
+---
+
+`context-relay` is a combo strategy that keeps session continuity when the active account
+rotates before the conversation is finished.
+
+The current runtime behaves like priority routing for model selection, then adds a
+handoff layer on top:
+
+- before the active account is exhausted, OmniRoute generates a compact structured summary
+- after authentication selects a different account for the same session, OmniRoute injects
+  that summary as a system message into the next request
+- once the handoff is consumed successfully, it is removed from storage
+
+## When To Use It
+
+Use `context-relay` when all of the following are true:
+
+- the combo is expected to rotate between multiple accounts of the same provider
+- losing short-term conversational continuity would hurt task quality
+- the provider exposes enough quota information to predict an approaching account limit
+
+This is most useful for long-running coding or research sessions that may outlive a single
+account window.
+
+## Runtime Flow
+
+The current behavior is intentionally split across two runtime layers.
+
+### 0% to 84% quota used
+
+No handoff is generated. Requests behave like normal priority routing.
+
+### 85% to 94% quota used
+
+If the active provider is enabled in `handoffProviders`, OmniRoute generates a structured
+handoff summary in the background before the account is fully exhausted.
+
+Important details:
+
+- the default warning threshold is `0.85`
+- the hard stop for generation is `0.95`
+- only one in-flight handoff generation is allowed per `sessionId + comboName`
+- if an active handoff already exists for that session/combo, no duplicate summary is generated
+
+### 95% or more quota used
+
+No new handoff is generated. At this point the system is already in or near exhaustion and
+the runtime avoids scheduling another summary request.
+
+### After account rotation
+
+When the next request for the same session resolves to a different authenticated account,
+OmniRoute prepends the stored handoff as a system message. Injection happens only after the
+real account switch is known.
+
+## Handoff Payload
+
+The persisted handoff payload is stored in `context_handoffs` and includes:
+
+- `sessionId`
+- `comboName`
+- `fromAccount`
+- `summary`
+- `keyDecisions`
+- `taskProgress`
+- `activeEntities`
+- `messageCount`
+- `model`
+- `warningThresholdPct`
+- `generatedAt`
+- `expiresAt`
+
+The summary model is instructed to return a JSON object with this structure:
+
+```json
+{
+  "summary": "Dense summary of what matters for continuity",
+  "keyDecisions": ["Decision 1", "Decision 2"],
+  "taskProgress": "What is done, what is pending, and the next step",
+  "activeEntities": ["fileA.ts", "feature X", "provider Y"]
+}
+```
+
+At injection time, OmniRoute converts that payload into a `<context_handoff>` system
+message so the next account can continue with the correct local context.
+
+## Configuration
+
+`context-relay` supports these config fields:
+
+- `handoffThreshold`: warning threshold for summary generation, default `0.85`
+- `handoffModel`: optional model override used only for summary generation
+- `handoffProviders`: allowlist of providers allowed to trigger handoff generation
+
+Global defaults can be configured in Settings, and combo-specific values can override them
+in the Combos page.
+
+## Architectural Note
+
+The current implementation does not use a standalone `handleContextRelayCombo` handler.
+
+Instead:
+
+- `open-sse/services/combo.ts` decides whether a successful turn should generate a handoff
+- `src/sse/handlers/chat.ts` injects the handoff only after authentication resolves the
+  actual account used for the request
+
+This split is intentional in the current codebase because the combo loop alone does not know
+whether the request stayed on the same account or actually switched accounts.
+
+## Limitations
+
+- Effective runtime support is currently centered on `codex` quota rotation.
+- `handoffProviders` is already modeled as a config surface, but real handoff generation
+  still depends on provider-specific quota plumbing.
+- The summary is intentionally compact and recent-history based; it is not a full transcript
+  replay mechanism.
+- Handoffs are scoped by `sessionId + comboName` and expire automatically.
+- If the session does not switch accounts, the stored handoff is not injected.
+
+## Recommended Usage Pattern
+
+- use multiple accounts from the same provider
+- keep stable `sessionId` values across the session
+- set `handoffThreshold` early enough to leave room for the background summary request
+- treat the feature as continuity assistance, not as a replacement for persistent memory

docs/i18n/README.md

@@ -1,38 +1,45 @@
 # 🌐 Multilingual Documentation — 9router
 
-Translations of documentation into 32 languages. Code blocks remain in English.
+Translations of documentation into 39 languages. Code blocks remain in English.
 
 ---
 
-- 🇪🇸 **Español** (`es`): [Docs Root](./es/README.md)
-- 🇫🇷 **Français** (`fr`): [Docs Root](./fr/README.md)
+- 🇸🇦 **العربية** (`ar`): [Docs Root](./ar/README.md)
+- 🇧🇬 **Български** (`bg`): [Docs Root](./bg/README.md)
+- 🇧🇩 **বাংলা** (`bn`): [Docs Root](./bn/README.md)
+- 🇨🇿 **Čeština** (`cs`): [Docs Root](./cs/README.md)
+- 🇩🇰 **Dansk** (`da`): [Docs Root](./da/README.md)
 - 🇩🇪 **Deutsch** (`de`): [Docs Root](./de/README.md)
+- 🇪🇸 **Español** (`es`): [Docs Root](./es/README.md)
+- 🇮🇷 **فارسی** (`fa`): [Docs Root](./fa/README.md)
+- 🇫🇮 **Suomi** (`fi`): [Docs Root](./fi/README.md)
+- 🇫🇷 **Français** (`fr`): [Docs Root](./fr/README.md)
+- 🇮🇳 **ગુજરાતી** (`gu`): [Docs Root](./gu/README.md)
+- 🇮🇱 **עברית** (`he`): [Docs Root](./he/README.md)
+- 🇮🇳 **हिन्दी** (`hi`): [Docs Root](./hi/README.md)
+- 🇭🇺 **Magyar** (`hu`): [Docs Root](./hu/README.md)
+- 🇮🇩 **Bahasa Indonesia** (`id`): [Docs Root](./id/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)
+- 🇮🇳 **मराठी** (`mr`): [Docs Root](./mr/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)
+- 🇵🇱 **Polski** (`pl`): [Docs Root](./pl/README.md)
+- 🇵🇹 **Português (Portugal)** (`pt`): [Docs Root](./pt/README.md)
 - 🇧🇷 **Português (Brasil)** (`pt-BR`): [Docs Root](./pt-BR/README.md)
-- 🇨🇿 **Čeština** (`cs`): [Docs Root](./cs/README.md)
+- 🇷🇴 **Română** (`ro`): [Docs Root](./ro/README.md)
+- 🇷🇺 **Русский** (`ru`): [Docs Root](./ru/README.md)
+- 🇸🇰 **Slovenčina** (`sk`): [Docs Root](./sk/README.md)
+- 🇸🇪 **Svenska** (`sv`): [Docs Root](./sv/README.md)
+- 🇰🇪 **Kiswahili** (`sw`): [Docs Root](./sw/README.md)
+- 🇮🇳 **தமிழ்** (`ta`): [Docs Root](./ta/README.md)
+- 🇮🇳 **తెలుగు** (`te`): [Docs Root](./te/README.md)
+- 🇹🇭 **ไทย** (`th`): [Docs Root](./th/README.md)
 - 🇹🇷 **Türkçe** (`tr`): [Docs Root](./tr/README.md)
+- 🇺🇦 **Українська** (`uk-UA`): [Docs Root](./uk-UA/README.md)
+- 🇵🇰 **اردو** (`ur`): [Docs Root](./ur/README.md)
+- 🇻🇳 **Tiếng Việt** (`vi`): [Docs Root](./vi/README.md)
+- 🇨🇳 **中文 (简体)** (`zh-CN`): [Docs Root](./zh-CN/README.md)

docs/i18n/ar/CLAUDE.md

@@ -0,0 +1,233 @@
+# CLAUDE.md — AI Agent Session Bootstrap (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../CLAUDE.md) · 🇸🇦 [ar](../ar/CLAUDE.md) · 🇧🇬 [bg](../bg/CLAUDE.md) · 🇧🇩 [bn](../bn/CLAUDE.md) · 🇨🇿 [cs](../cs/CLAUDE.md) · 🇩🇰 [da](../da/CLAUDE.md) · 🇩🇪 [de](../de/CLAUDE.md) · 🇪🇸 [es](../es/CLAUDE.md) · 🇮🇷 [fa](../fa/CLAUDE.md) · 🇫🇮 [fi](../fi/CLAUDE.md) · 🇫🇷 [fr](../fr/CLAUDE.md) · 🇮🇳 [gu](../gu/CLAUDE.md) · 🇮🇱 [he](../he/CLAUDE.md) · 🇮🇳 [hi](../hi/CLAUDE.md) · 🇭🇺 [hu](../hu/CLAUDE.md) · 🇮🇩 [id](../id/CLAUDE.md) · 🇮🇹 [it](../it/CLAUDE.md) · 🇯🇵 [ja](../ja/CLAUDE.md) · 🇰🇷 [ko](../ko/CLAUDE.md) · 🇮🇳 [mr](../mr/CLAUDE.md) · 🇲🇾 [ms](../ms/CLAUDE.md) · 🇳🇱 [nl](../nl/CLAUDE.md) · 🇳🇴 [no](../no/CLAUDE.md) · 🇵🇭 [phi](../phi/CLAUDE.md) · 🇵🇱 [pl](../pl/CLAUDE.md) · 🇵🇹 [pt](../pt/CLAUDE.md) · 🇧🇷 [pt-BR](../pt-BR/CLAUDE.md) · 🇷🇴 [ro](../ro/CLAUDE.md) · 🇷🇺 [ru](../ru/CLAUDE.md) · 🇸🇰 [sk](../sk/CLAUDE.md) · 🇸🇪 [sv](../sv/CLAUDE.md) · 🇰🇪 [sw](../sw/CLAUDE.md) · 🇮🇳 [ta](../ta/CLAUDE.md) · 🇮🇳 [te](../te/CLAUDE.md) · 🇹🇭 [th](../th/CLAUDE.md) · 🇹🇷 [tr](../tr/CLAUDE.md) · 🇺🇦 [uk-UA](../uk-UA/CLAUDE.md) · 🇵🇰 [ur](../ur/CLAUDE.md) · 🇻🇳 [vi](../vi/CLAUDE.md) · 🇨🇳 [zh-CN](../zh-CN/CLAUDE.md)
+
+---
+
+> Quick-start context for AI coding agents. For deep architecture details, see `AGENTS.md`.
+> For contribution workflow, see `CONTRIBUTING.md`.
+
+## بداية سريعة
+
+```bash
+npm install                    # Install deps (auto-generates .env from .env.example)
+npm run dev                    # Dev server at http://localhost:20128
+npm run build                  # Production build (Next.js 16 standalone)
+npm run lint                   # ESLint (0 errors expected; warnings are pre-existing)
+npm run typecheck:core         # TypeScript check (should be clean)
+npm run typecheck:noimplicit:core  # Strict check (no implicit any)
+npm run test:coverage          # Unit tests + coverage gate (60% min)
+npm run check                  # lint + test combined
+npm run check:cycles           # Detect circular dependencies
+```
+
+### Running a Single Test
+
+```bash
+# Node.js native test runner (most tests)
+node --import tsx/esm --test tests/unit/your-file.test.mjs
+
+# Vitest (MCP server, autoCombo, cache)
+npm run test:vitest
+```
+
+---
+
+## نظرة عامة
+
+**OmniRoute** — unified AI proxy/router. One endpoint, 100+ LLM providers, auto-fallback.
+
+| Layer           | Location                 | Purpose                                    |
+| --------------- | ------------------------ | ------------------------------------------ |
+| API Routes      | `src/app/api/v1/`        | Next.js App Router — entry points          |
+| Handlers        | `open-sse/handlers/`     | Request processing (chat, embeddings, etc) |
+| Executors       | `open-sse/executors/`    | Provider-specific HTTP dispatch            |
+| Translators     | `open-sse/translator/`   | Format conversion (OpenAI↔Claude↔Gemini)   |
+| Services        | `open-sse/services/`     | Combo routing, rate limits, caching, etc   |
+| Database        | `src/lib/db/`            | SQLite domain modules (22 files)           |
+| Domain/Policy   | `src/domain/`            | Policy engine, cost rules, fallback logic  |
+| MCP Server      | `open-sse/mcp-server/`   | 25 tools, 3 transports, 10 scopes          |
+| A2A Server      | `src/lib/a2a/`           | JSON-RPC 2.0 agent protocol                |
+| Skills          | `src/lib/skills/`        | Extensible skill framework                 |
+| Memory          | `src/lib/memory/`        | Persistent conversational memory           |
+| UI Components   | `src/shared/components/` | React components (Tailwind CSS v4)         |
+| Provider Consts | `src/shared/constants/`  | Provider registry (Zod-validated)          |
+| Validation      | `src/shared/validation/` | Zod v4 schemas                             |
+| Tests           | `tests/`                 | Unit, integration, e2e, security, load     |
+
+### Monorepo Layout
+
+```
+OmniRoute/              # Root package
+├── src/                # Next.js 16 app (TypeScript)
+├── open-sse/           # @omniroute/open-sse workspace (streaming engine)
+├── electron/           # Desktop app (Electron)
+├── tests/              # All test suites
+├── docs/               # Documentation
+└── bin/                # CLI entry point
+```
+
+---
+
+## Request Pipeline (Abbreviated)
+
+```
+Client → /v1/chat/completions (Next.js route)
+  → CORS → Zod validation → auth? → policy check → prompt injection guard
+  → handleChatCore() [open-sse/handlers/chatCore.ts]
+    → cache check → rate limit → combo routing?
+      → resolveComboTargets() → handleSingleModel() per target
+    → translateRequest() → getExecutor() → executor.execute()
+      → fetch() upstream → retry w/ backoff
+    → response translation → SSE stream or JSON
+```
+
+---
+
+## Key Conventions
+
+### Code Style
+
+- **2 spaces**, semicolons, double quotes, 100 char width, es5 trailing commas
+- **Imports**: external → internal (`@/`, `@omniroute/open-sse`) → relative
+- **Naming**: files=camelCase/kebab, components=PascalCase, constants=UPPER_SNAKE
+
+### Database Access
+
+- **Always** go through `src/lib/db/` domain modules
+- **Never** write raw SQL in routes or handlers
+- **Never** add logic to `src/lib/localDb.ts` (re-export layer only)
+- **Never** barrel-import from `localDb.ts` — import specific `db/` modules
+- DB singleton: `getDbInstance()` from `src/lib/db/core.ts` (WAL journaling)
+- Migrations: `src/lib/db/migrations/` — 21 versioned SQL files
+
+### Error Handling
+
+- try/catch with specific error types, log with pino context
+- Never swallow errors in SSE streams — use abort signals
+- Return proper HTTP status codes (4xx/5xx)
+
+### الأمان
+
+- **Never** commit secrets/credentials
+- **Never** use `eval()`, `new Function()`, or implied eval
+- Validate all inputs with Zod schemas
+- Encrypt credentials at rest (AES-256-GCM)
+
+---
+
+## Common Modification Scenarios
+
+### Adding a New Provider
+
+1. Register in `src/shared/constants/providers.ts` (Zod-validated at load)
+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. Register models in `open-sse/config/providerRegistry.ts`
+6. Write tests in `tests/unit/` (registration, translation, error handling)
+
+### Adding a New API Route
+
+1. Create directory under `src/app/api/v1/your-route/`
+2. Create `route.ts` with `GET`/`POST` handlers
+3. Follow pattern: CORS → Zod body validation → optional auth → handler delegation
+4. Handler goes in `open-sse/handlers/` (import from there, not inline)
+5. Add tests
+
+### Adding a New DB Module
+
+1. Create `src/lib/db/yourModule.ts`
+2. Import `getDbInstance` from `./core.ts`
+3. Export CRUD functions for your domain table(s)
+4. Add migration in `src/lib/db/migrations/` if new tables needed
+5. Re-export from `src/lib/localDb.ts` (add to the re-export list only)
+6. Write tests
+
+### Adding a New MCP Tool
+
+1. Add tool definition in `open-sse/mcp-server/tools/`
+2. Define Zod input schema + async handler
+3. Register in tool set (wired by `createMcpServer()`)
+4. Assign to appropriate scope(s)
+5. Write tests (tool invocation logged to `mcp_audit` table)
+
+### Adding a New A2A Skill
+
+1. Create skill in `src/lib/a2a/skills/`
+2. Skill receives task context (messages, metadata) → returns structured result
+3. Register in the DB-backed skill registry
+4. Write tests
+
+---
+
+## Testing Cheat Sheet
+
+| What                    | Command                                                 |
+| ----------------------- | ------------------------------------------------------- |
+| All tests               | `npm run test:all`                                      |
+| Unit tests              | `npm run test:unit`                                     |
+| Single file             | `node --import tsx/esm --test tests/unit/file.test.mjs` |
+| Vitest (MCP, autoCombo) | `npm run test:vitest`                                   |
+| E2E (Playwright)        | `npm run test:e2e`                                      |
+| Protocol E2E (MCP+A2A)  | `npm run test:protocols:e2e`                            |
+| Ecosystem               | `npm run test:ecosystem`                                |
+| Coverage gate           | `npm run test:coverage` (60% min all metrics)           |
+| Coverage report         | `npm run coverage:report`                               |
+
+**PR rule**: If you change production code in `src/`, `open-sse/`, `electron/`, or `bin/`,
+you must include or update tests in the same PR.
+
+**Test layer preference**: unit first → integration (multi-module or DB state) → e2e (UI/workflow only). Encode bug reproductions as automated tests before or alongside the fix.
+
+---
+
+## Git Workflow
+
+```bash
+# Never commit directly to main
+git checkout -b feat/your-feature
+# ... make changes ...
+git commit -m "feat: describe your change"
+git push -u origin feat/your-feature
+```
+
+**Branch prefixes**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`
+
+**Commit format** ([Conventional Commits](https://www.conventionalcommits.org/)):
+
+```
+feat: add circuit breaker for provider calls
+fix: resolve JWT secret validation edge case
+docs: update AGENTS.md with pipeline internals
+test: add MCP tool unit tests
+refactor(db): consolidate rate limit tables
+```
+
+**Scopes**: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`,
+`memory`, `skills`.
+
+---
+
+## Environment
+
+- **Runtime**: Node.js ≥18 <24, ES Modules
+- **TypeScript**: 5.9, target ES2022, module esnext, resolution bundler
+- **Path aliases**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`
+- **Default port**: 20128 (API + dashboard on same port)
+- **Data directory**: `DATA_DIR` env var, defaults to `~/.omniroute/`
+- **Key env vars**: `PORT`, `JWT_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`
+
+---
+
+## Hard Rules (Never Violate)
+
+1. Never commit secrets or credentials
+2. Never add logic to `localDb.ts`
+3. Never use `eval()` / `new Function()` / implied eval
+4. Never commit directly to `main`
+5. Never write raw SQL in routes — use `src/lib/db/` modules
+6. Never silently swallow errors in SSE streams
+7. Always validate inputs with Zod schemas
+8. Always include tests when changing production code
+9. Coverage must stay ≥60% (statements, lines, functions, branches)

docs/i18n/ar/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../CODE_OF_CONDUCT.md) · 🇸🇦 [ar](../ar/CODE_OF_CONDUCT.md) · 🇧🇬 [bg](../bg/CODE_OF_CONDUCT.md) · 🇧🇩 [bn](../bn/CODE_OF_CONDUCT.md) · 🇨🇿 [cs](../cs/CODE_OF_CONDUCT.md) · 🇩🇰 [da](../da/CODE_OF_CONDUCT.md) · 🇩🇪 [de](../de/CODE_OF_CONDUCT.md) · 🇪🇸 [es](../es/CODE_OF_CONDUCT.md) · 🇮🇷 [fa](../fa/CODE_OF_CONDUCT.md) · 🇫🇮 [fi](../fi/CODE_OF_CONDUCT.md) · 🇫🇷 [fr](../fr/CODE_OF_CONDUCT.md) · 🇮🇳 [gu](../gu/CODE_OF_CONDUCT.md) · 🇮🇱 [he](../he/CODE_OF_CONDUCT.md) · 🇮🇳 [hi](../hi/CODE_OF_CONDUCT.md) · 🇭🇺 [hu](../hu/CODE_OF_CONDUCT.md) · 🇮🇩 [id](../id/CODE_OF_CONDUCT.md) · 🇮🇹 [it](../it/CODE_OF_CONDUCT.md) · 🇯🇵 [ja](../ja/CODE_OF_CONDUCT.md) · 🇰🇷 [ko](../ko/CODE_OF_CONDUCT.md) · 🇮🇳 [mr](../mr/CODE_OF_CONDUCT.md) · 🇲🇾 [ms](../ms/CODE_OF_CONDUCT.md) · 🇳🇱 [nl](../nl/CODE_OF_CONDUCT.md) · 🇳🇴 [no](../no/CODE_OF_CONDUCT.md) · 🇵🇭 [phi](../phi/CODE_OF_CONDUCT.md) · 🇵🇱 [pl](../pl/CODE_OF_CONDUCT.md) · 🇵🇹 [pt](../pt/CODE_OF_CONDUCT.md) · 🇧🇷 [pt-BR](../pt-BR/CODE_OF_CONDUCT.md) · 🇷🇴 [ro](../ro/CODE_OF_CONDUCT.md) · 🇷🇺 [ru](../ru/CODE_OF_CONDUCT.md) · 🇸🇰 [sk](../sk/CODE_OF_CONDUCT.md) · 🇸🇪 [sv](../sv/CODE_OF_CONDUCT.md) · 🇰🇪 [sw](../sw/CODE_OF_CONDUCT.md) · 🇮🇳 [ta](../ta/CODE_OF_CONDUCT.md) · 🇮🇳 [te](../te/CODE_OF_CONDUCT.md) · 🇹🇭 [th](../th/CODE_OF_CONDUCT.md) · 🇹🇷 [tr](../tr/CODE_OF_CONDUCT.md) · 🇺🇦 [uk-UA](../uk-UA/CODE_OF_CONDUCT.md) · 🇵🇰 [ur](../ur/CODE_OF_CONDUCT.md) · 🇻🇳 [vi](../vi/CODE_OF_CONDUCT.md) · 🇨🇳 [zh-CN](../zh-CN/CODE_OF_CONDUCT.md)
+
+---
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

docs/i18n/ar/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../CONTRIBUTING.md) · 🇸🇦 [ar](../ar/CONTRIBUTING.md) · 🇧🇬 [bg](../bg/CONTRIBUTING.md) · 🇧🇩 [bn](../bn/CONTRIBUTING.md) · 🇨🇿 [cs](../cs/CONTRIBUTING.md) · 🇩🇰 [da](../da/CONTRIBUTING.md) · 🇩🇪 [de](../de/CONTRIBUTING.md) · 🇪🇸 [es](../es/CONTRIBUTING.md) · 🇮🇷 [fa](../fa/CONTRIBUTING.md) · 🇫🇮 [fi](../fi/CONTRIBUTING.md) · 🇫🇷 [fr](../fr/CONTRIBUTING.md) · 🇮🇳 [gu](../gu/CONTRIBUTING.md) · 🇮🇱 [he](../he/CONTRIBUTING.md) · 🇮🇳 [hi](../hi/CONTRIBUTING.md) · 🇭🇺 [hu](../hu/CONTRIBUTING.md) · 🇮🇩 [id](../id/CONTRIBUTING.md) · 🇮🇹 [it](../it/CONTRIBUTING.md) · 🇯🇵 [ja](../ja/CONTRIBUTING.md) · 🇰🇷 [ko](../ko/CONTRIBUTING.md) · 🇮🇳 [mr](../mr/CONTRIBUTING.md) · 🇲🇾 [ms](../ms/CONTRIBUTING.md) · 🇳🇱 [nl](../nl/CONTRIBUTING.md) · 🇳🇴 [no](../no/CONTRIBUTING.md) · 🇵🇭 [phi](../phi/CONTRIBUTING.md) · 🇵🇱 [pl](../pl/CONTRIBUTING.md) · 🇵🇹 [pt](../pt/CONTRIBUTING.md) · 🇧🇷 [pt-BR](../pt-BR/CONTRIBUTING.md) · 🇷🇴 [ro](../ro/CONTRIBUTING.md) · 🇷🇺 [ru](../ru/CONTRIBUTING.md) · 🇸🇰 [sk](../sk/CONTRIBUTING.md) · 🇸🇪 [sv](../sv/CONTRIBUTING.md) · 🇰🇪 [sw](../sw/CONTRIBUTING.md) · 🇮🇳 [ta](../ta/CONTRIBUTING.md) · 🇮🇳 [te](../te/CONTRIBUTING.md) · 🇹🇭 [th](../th/CONTRIBUTING.md) · 🇹🇷 [tr](../tr/CONTRIBUTING.md) · 🇺🇦 [uk-UA](../uk-UA/CONTRIBUTING.md) · 🇵🇰 [ur](../ur/CONTRIBUTING.md) · 🇻🇳 [vi](../vi/CONTRIBUTING.md) · 🇨🇳 [zh-CN](../zh-CN/CONTRIBUTING.md)
 
 ---
 
@@ -123,7 +123,7 @@ Scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`,
 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/your-file.test.ts
 
 # Vitest (MCP server, autoCombo, cache)
 npm run test:vitest
@@ -137,7 +137,7 @@ npm run test:protocols:e2e
 # Ecosystem compatibility tests
 npm run test:ecosystem
 
-# Coverage (55% min statements/lines/functions; 60% branches)
+# Coverage (60% min statements/lines/functions/branches)
 npm run test:coverage
 npm run coverage:report
 
@@ -149,10 +149,22 @@ npm run check
 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

docs/i18n/ar/GEMINI.md

@@ -0,0 +1,25 @@
+# Security and Cleanliness Rules for AI Assistants (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../GEMINI.md) · 🇸🇦 [ar](../ar/GEMINI.md) · 🇧🇬 [bg](../bg/GEMINI.md) · 🇧🇩 [bn](../bn/GEMINI.md) · 🇨🇿 [cs](../cs/GEMINI.md) · 🇩🇰 [da](../da/GEMINI.md) · 🇩🇪 [de](../de/GEMINI.md) · 🇪🇸 [es](../es/GEMINI.md) · 🇮🇷 [fa](../fa/GEMINI.md) · 🇫🇮 [fi](../fi/GEMINI.md) · 🇫🇷 [fr](../fr/GEMINI.md) · 🇮🇳 [gu](../gu/GEMINI.md) · 🇮🇱 [he](../he/GEMINI.md) · 🇮🇳 [hi](../hi/GEMINI.md) · 🇭🇺 [hu](../hu/GEMINI.md) · 🇮🇩 [id](../id/GEMINI.md) · 🇮🇹 [it](../it/GEMINI.md) · 🇯🇵 [ja](../ja/GEMINI.md) · 🇰🇷 [ko](../ko/GEMINI.md) · 🇮🇳 [mr](../mr/GEMINI.md) · 🇲🇾 [ms](../ms/GEMINI.md) · 🇳🇱 [nl](../nl/GEMINI.md) · 🇳🇴 [no](../no/GEMINI.md) · 🇵🇭 [phi](../phi/GEMINI.md) · 🇵🇱 [pl](../pl/GEMINI.md) · 🇵🇹 [pt](../pt/GEMINI.md) · 🇧🇷 [pt-BR](../pt-BR/GEMINI.md) · 🇷🇴 [ro](../ro/GEMINI.md) · 🇷🇺 [ru](../ru/GEMINI.md) · 🇸🇰 [sk](../sk/GEMINI.md) · 🇸🇪 [sv](../sv/GEMINI.md) · 🇰🇪 [sw](../sw/GEMINI.md) · 🇮🇳 [ta](../ta/GEMINI.md) · 🇮🇳 [te](../te/GEMINI.md) · 🇹🇭 [th](../th/GEMINI.md) · 🇹🇷 [tr](../tr/GEMINI.md) · 🇺🇦 [uk-UA](../uk-UA/GEMINI.md) · 🇵🇰 [ur](../ur/GEMINI.md) · 🇻🇳 [vi](../vi/GEMINI.md) · 🇨🇳 [zh-CN](../zh-CN/GEMINI.md)
+
+---
+
+## 1. File Placement & Organization
+
+- **Test Files**: ALL unit tests, integration tests, ecosystem tests, or Vitest files MUST strictly be placed within the `tests/` directory (e.g., `tests/unit/`, `tests/integration/`). NEVER create test files in the project root (`/`).
+- **Scripts and Utilities**: ALL maintenance, debugging, generation, or experimental scripts (`.cjs`, `.mjs`, `.js`, `.ts`) MUST be placed strictly inside the `scripts/` directory or `scripts/scratch/` for temporary one-offs. NEVER dump loose scripts in the project root (`/`).
+
+**The Project Root MUST ONLY CONTAIN:**
+
+- Configuration files (`vitest.config.ts`, `next.config.mjs`, `eslint.config.mjs`, etc.)
+- Dependency files (`package.json`, `package-lock.json`)
+- Documentation files (`README.md`, `CHANGELOG.md`, `AGENTS.md`)
+- CI/CD files and ignore definitions (`.gitignore`, `.dockerignore`)
+
+When creating _any_ validation tests or one-off logic scripts, default to using `scripts/scratch/` or the `tests/unit/` directories according to your goals. Do not pollute the `/` root context.
+
+## 2. VPS Dashboard Credentials
+
+| Environment | URL                       | Password |
+| ----------- | ------------------------- | -------- |
+| Local VPS   | http://192.168.0.15:20128 | 123456   |

docs/i18n/ar/README.md

@@ -1,12 +1,12 @@
 # 🚀 OmniRoute — The Free AI Gateway (العربية)
 
-🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇹🇷 [tr](../tr/README.md)
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md)
 
 ---
 
 ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
 
-_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
+_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
 
 **Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
 
@@ -247,7 +247,9 @@ Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve
 - **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention
 - **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI
 - **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next
-- **Custom Combos** — Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random)
+- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)
+- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets
+- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use
 - **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
 
 </details>
@@ -259,7 +261,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If
 
 **How OmniRoute solves it:**
 
-- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 60+ providers
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers
 - **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
 - **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+
 - **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE
@@ -326,12 +328,13 @@ AI providers can become unstable, return 5xx errors, or hit temporary rate limit
 
 **How OmniRoute solves it:**
 
-- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks
-- **Exponential Backoff** — Progressive retry delays
+- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps
+- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff
+- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown
+- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically
 - **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms
 - **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention
-- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain
-- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
+- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency
 
 </details>
 
@@ -345,7 +348,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code..
 - **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
 - **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection
 - **Onboarding Wizard** — Guided 4-step setup for first-time users
-- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 60+ providers
+- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers
 
 </details>
 
@@ -389,10 +392,10 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w
 
 - **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console
 - **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter
-- **SQLite Proxy Logs** — Persistent logs that survive server restarts
+- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite
 - **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)
 - **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing
-- **File-Based Logging with Rotation** — App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count
+- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries
 - **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.
 
 </details>
@@ -472,7 +475,7 @@ As request volume grows, without caching the same questions generate duplicate c
 - **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency
 - **Request Idempotency** — 5s deduplication window for identical requests
 - **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking
-- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence
+- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience
 - **API Key Validation Cache** — 3-tier cache for production performance
 - **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
 
@@ -490,6 +493,7 @@ Developers who want all responses in a specific language, with a specific tone,
 - **9 Routing Strategies** — Global strategies that determine how requests are distributed
 - **Wildcard Router** — `provider/*` patterns route dynamically to any provider
 - **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
 - **Provider Toggle** — Enable/disable all connections for a provider with one click
 - **Blocked Providers** — Exclude specific providers from `/v1/models` listing
 
@@ -568,8 +572,8 @@ Teams need quick runtime changes during incidents or cost events.
 **How OmniRoute solves it:**
 
 - Switch combo activation directly from MCP dashboard
-- Apply resilience profiles from pre-defined policy packs
-- Reset circuit breaker state from the same operations panel
+- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page
+- Review live provider breaker state from the Health dashboard
 
 </details>
 
@@ -677,13 +681,26 @@ Teams lose velocity when stitching multiple ad-hoc services and scripts.
 
 </details>
 
+<details>
+<summary><b>📚 31. "My long sessions crash with 'context_length_exceeded' limits"</b></summary>
+
+During deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.
+
+**How OmniRoute solves it:**
+
+- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.
+- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.
+- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.
+
+</details>
+
 ### Example Playbooks (Integrated Use Cases)
 
 **Playbook A: Maximize paid subscription + cheap backup**
 
 ```txt
 Combo: "maximize-claude"
-  1. cc/claude-opus-4-6
+  1. cc/claude-opus-4-7
   2. glm/glm-4.7
   3. if/kimi-k2-thinking
 
@@ -707,7 +724,7 @@ Outcome: stable free coding workflow
 
 ```txt
 Combo: "always-on"
-  1. cc/claude-opus-4-6
+  1. cc/claude-opus-4-7
   2. cx/gpt-5.2-codex
   3. glm/glm-4.7
   4. minimax/MiniMax-M2.1
@@ -762,6 +779,15 @@ omniroute
 
 Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
 
+#### Arch Linux (AUR)
+
+Arch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:
+
+```bash
+yay -S omniroute-bin
+systemctl --user enable --now omniroute.service
+```
+
 | Command                 | Description                                                 |
 | ----------------------- | ----------------------------------------------------------- |
 | `omniroute`             | Start server (`PORT=20128`, API and dashboard on same port) |
@@ -778,22 +804,40 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
 # Dashboard: http://localhost:20129
 ```
 
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command                  | Action                                                                              |
+| ------------------------ | ----------------------------------------------------------------------------------- |
+| `npm run uninstall`      | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`.  |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
 ### Long-Running Streaming Timeouts
 
 For most deployments, you only need:
 
-| Variable                 | Default                       | Purpose                                                                                                                     |
-| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `REQUEST_TIMEOUT_MS`     | `600000`                      | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |
-| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream                                                 |
+| Variable                 | Default                       | Purpose                                                                                                                                      |
+| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `REQUEST_TIMEOUT_MS`     | `600000`                      | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |
+| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream                                                                  |
 
 Backward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.
 
+For Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.
+
+For third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default
+`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,
+only forwards client-provided `cache_control` markers. If the request does not include
+`cache_control`, OmniRoute does not inject bridge-owned markers.
+
 Advanced overrides are available if you need finer control:
 
 | Variable                                 | Default                                    | Purpose                                                              |
 | ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |
-| `FETCH_TIMEOUT_MS`                       | inherits `REQUEST_TIMEOUT_MS`              | Total upstream request timeout used by the main fetch abort signal   |
+| `FETCH_TIMEOUT_MS`                       | inherits `REQUEST_TIMEOUT_MS`              | Upstream response-start timeout used until response headers arrive   |
 | `FETCH_HEADERS_TIMEOUT_MS`               | inherits `FETCH_TIMEOUT_MS`                | Undici time limit for receiving upstream response headers            |
 | `FETCH_BODY_TIMEOUT_MS`                  | inherits `FETCH_TIMEOUT_MS`                | Undici time limit between upstream body chunks (`0` disables it)     |
 | `FETCH_CONNECT_TIMEOUT_MS`               | `30000`                                    | Undici TCP connect timeout                                           |
@@ -805,6 +849,8 @@ Advanced overrides are available if you need finer control:
 | `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000`                                     | Keep-alive timeout on the API bridge server                          |
 | `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS`    | `0`                                        | Socket inactivity timeout on the API bridge server (`0` disables it) |
 
+For streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).
+
 If you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy
 timeouts are also higher than your OmniRoute stream/fetch timeouts.
 
@@ -958,7 +1004,7 @@ do_install() {
 #!/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}"
+export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
 mkdir -p "${DATA_DIR}"
 exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
 EOF
@@ -1061,7 +1107,7 @@ volumes:
 | Image                    | Tag      | Size   | Description           |
 | ------------------------ | -------- | ------ | --------------------- |
 | `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |
-| `diegosouzapw/omniroute` | `1.0.3`  | ~250MB | Current version       |
+| `diegosouzapw/omniroute` | `3.6.2`  | ~250MB | Current version       |
 
 ---
 
@@ -1308,7 +1354,32 @@ Then in `/dashboard/media` → **Transcription** tab: upload any audio or video
 
 ## 💡 Key Features
 
-OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
+OmniRoute v3.6 is built as an operational platform, not just a relay proxy.
+
+### 🆕 New — v3.6.x Highlights (Apr 2026)
+
+| Feature                            | What It Does                                                                                                                                      |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🌐 **V1 WebSocket Bridge**         | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie)      |
+| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling                            |
+| 🧠 **GLM Thinking (glmt) Preset**  | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API        |
+| 🔢 **Hybrid Token Counting**       | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing                   |
+| 🌱 **Model Alias Auto-Seed**       | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches                                                                |
+| 🛡️ **Safe Outbound Fetch**         | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |
+| ⏳ **Wait For Cooldown**           | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec`             |
+| 🔍 **Runtime Env Validation**      | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types                                  |
+| 📋 **Compliance Audit Expansion**  | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging                    |
+| 🔐 **TPS Log Metric**              | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request                                                 |
+| 🗑️ **Uninstall / Full Uninstall**  | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods                               |
+| 🔧 **OAuth Env Repair**            | One-click "Repair env" action for OAuth providers restores missing env vars and fixes broken auth state                                           |
+| 🔒 **Graceful Electron Shutdown**  | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close                                       |
+| 👁️ **Model Visibility Toggle**     | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages                                  |
+| 📧 **Email Privacy Masking**       | OAuth account emails masked (`di*****@g****.com`), full address visible on hover                                                                  |
+| 🔗 **Context Relay Strategy**      | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation                               |
+| 🛡️ **Proxy Hardening**             | Token health check, API key validation, and undici dispatcher all honor proxy config                                                              |
+| ⚠️ **Node.js 24 Login Warning**    | Login page proactively detects incompatible Node.js versions and shows a clear warning banner                                                     |
+| 📎 **Gemini PDF Attachments**      | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection                                                         |
+| 🔒 **CodeQL Security Hardening**   | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts                                                      |
 
 ### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)
 
@@ -1349,7 +1420,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 | 📡 **A2A Task Lifecycle Management**  | List/filter tasks, inspect events/artifacts, cancel running tasks                                                                      |
 | 📋 **Agent Card Discovery**           | `/.well-known/agent.json` for client auto-discovery                                                                                    |
 | 🧪 **Protocol E2E Test Harness**      | Real MCP SDK + A2A client flows in `test:protocols:e2e`                                                                                |
-| ⚙️ **Operational Controls**           | Switch combo, apply resilience profiles, reset breakers from one control surface                                                       |
+| ⚙️ **Operational Controls**           | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces                          |
 
 ### 🧠 Routing & Intelligence
 
@@ -1360,7 +1431,8 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 | 🔄 **Format Translation**          | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions        |
 | 👥 **Multi-Account Support**       | Multiple accounts per provider with intelligent selection                |
 | 🔄 **Auto Token Refresh**          | OAuth tokens refresh automatically with retry                            |
-| 🎨 **Custom Combos**               | 9 balancing strategies + fallback chain control                          |
+| 🎨 **Custom Combos**               | 13 balancing strategies + fallback chain control                         |
+| 🔗 **Context Relay**               | Session continuity handoffs when account rotation happens mid-session    |
 | 🌐 **Wildcard Router**             | `provider/*` dynamic routing                                             |
 | 🧠 **Thinking Budget Controls**    | Passthrough, auto, custom, and adaptive reasoning limits                 |
 | 🔀 **Model Aliases**               | Built-in + custom model aliasing and migration safety                    |
@@ -1388,31 +1460,38 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 
 ### 🛡️ Resilience, Security & Governance
 
-| Feature                             | What It Does                                                                           |
-| ----------------------------------- | -------------------------------------------------------------------------------------- |
-| 🔌 **Circuit Breakers**             | Per-model trip/recover with threshold controls                                         |
-| 🎯 **Endpoint-Aware Models**        | Custom models declare supported endpoints + API format                                 |
-| 🛡️ **Anti-Thundering Herd**         | Mutex + semaphore protections on retry/rate events                                     |
-| 🧠 **Semantic + Signature Cache**   | Cost/latency reduction with two cache layers                                           |
-| ⚡ **Request Idempotency**          | Duplicate protection window                                                            |
-| 🔒 **TLS Fingerprint Spoofing**     | Browser-like TLS fingerprint — **reduces bot detection and account flagging**          |
-| 🔏 **CLI Fingerprint Matching**     | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
-| 🌐 **IP Filtering**                 | Allowlist/blocklist control for exposed deployments                                    |
-| 📊 **Editable Rate Limits**         | Configurable global/provider-level limits with persistence                             |
-| 📉 **Graceful Degradation**         | Multi-layer capability fallbacks protecting core gateway operations                    |
-| 📜 **Config Audit Trail**           | Diff-based change tracking preventing operational drift with simple rollbacks          |
-| ⏳ **Provider Health Sync**         | Proactive token expiration monitoring triggering alerts before authorization failures  |
-| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically   |
-| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls                               |
-| 👁️ **Scoped API Key Reveal** 🆕     | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL`                                 |
-| 🛡️ **Protected `/models`**          | Optional auth gating and provider hiding for model catalog                             |
+| Feature                             | What It Does                                                                                            |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 🔌 **Provider Circuit Breakers**    | Provider-wide trip/recover after fallback exhaustion with configurable thresholds                       |
+| 🔒 **Daily Quota Lock** 🆕          | Detects exhaustion signals and locks routing for the specific model until midnight                      |
+| 🎯 **Endpoint-Aware Models**        | Custom models declare supported endpoints + API format                                                  |
+| 🛡️ **Anti-Thundering Herd**         | Mutex + semaphore protections on retry/rate events                                                      |
+| 🧠 **Semantic + Signature Cache**   | Cost/latency reduction with two cache layers                                                            |
+| ⚡ **Request Idempotency**          | Duplicate protection window                                                                             |
+| 🔒 **TLS Fingerprint Spoofing**     | Browser-like TLS fingerprint — **reduces bot detection and account flagging**                           |
+| 🔏 **CLI Fingerprint Matching**     | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP**                  |
+| 🌐 **IP Filtering**                 | Allowlist/blocklist control for exposed deployments                                                     |
+| 🚦 **Request Queue & Pacing**       | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait                 |
+| 📉 **Graceful Degradation**         | Multi-layer capability fallbacks protecting core gateway operations                                     |
+| 📜 **Config Audit Trail**           | Diff-based change tracking preventing operational drift with simple rollbacks                           |
+| ⏳ **Provider Health Sync**         | Proactive token expiration monitoring triggering alerts before authorization failures                   |
+| ❄️ **Connection Cooldown**          | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints               |
+| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically                                        |
+| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls                                                |
+| 👁️ **Scoped API Key Reveal** 🆕     | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL`                                                  |
+| 🛡️ **Protected `/models`**          | Optional auth gating and provider hiding for model catalog                                              |
+| 🛡️ **Safe Outbound Fetch** 🆕       | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection                  |
+| ⏳ **Wait For Cooldown** 🆕         | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |
+| 🔍 **Runtime Env Validation** 🆕    | Zod-based env schema validation at startup with actionable error messages                               |
+| 📋 **Compliance Audit v2** 🆕       | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging                       |
 
 ### 📊 Observability & Analytics
 
 | Feature                          | What It Does                                          |
 | -------------------------------- | ----------------------------------------------------- |
 | 📝 **Request + Proxy Logging**   | Full request/response and proxy logging               |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI  |
+| 📉 **Streamed Detailed Logs**    | Reconstructs SSE payload streams cleanly into the UI  |
+| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers    |
 | 📋 **Unified Logs Dashboard**    | Request, proxy, audit, and console views in one page  |
 | 🔍 **Request Telemetry**         | p50/p95/p99 latency and request tracing               |
 | 🏥 **Health Dashboard**          | Uptime, breaker states, lockouts, cache stats         |
@@ -1420,6 +1499,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 | 📈 **Analytics Visualizations**  | Model/provider usage insights and trend views         |
 | 🧪 **Evaluation Framework**      | Golden set testing with configurable match strategies |
 | 📡 **Live Diagnostics** 🆕       | Semantic cache bypass for accurate combo live testing |
+| 🔐 **TPS Log Metric** 🆕         | Tokens Per Second badge in log details modal          |
 
 ### ☁️ Deployment & Platform
 
@@ -1439,6 +1519,8 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 | 👁️ **Sidebar Controls** 🆕     | Hide components and integrations from Appearance Settings             |
 | 📋 **Issue Templates**         | Standardized GitHub templates for bugs and features                   |
 | 📂 **Custom Data Directory**   | `DATA_DIR` override for storage location                              |
+| 🌐 **V1 WebSocket Bridge** 🆕  | OpenAI-compatible WebSocket traffic proxied via `/v1/ws`              |
+| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support      |
 
 ### Feature Deep Dive
 
@@ -1446,7 +1528,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 
 ```txt
 Combo: "my-coding-stack"
-  1. cc/claude-opus-4-6
+  1. cc/claude-opus-4-7
   2. nvidia/llama-3.3-70b
   3. glm/glm-4.7
   4. if/kimi-k2-thinking
@@ -1585,7 +1667,7 @@ Dashboard → Providers → Connect Claude Code
 → 5-hour + weekly quota tracking
 
 Models:
-  cc/claude-opus-4-6
+  cc/claude-opus-4-7
   cc/claude-sonnet-4-5-20250929
   cc/claude-haiku-4-5-20251001
 ```
@@ -1785,7 +1867,7 @@ Dashboard → Combos → Create New
 
 Name: premium-coding
 Models:
-  1. cc/claude-opus-4-6 (Subscription primary)
+  1. cc/claude-opus-4-7 (Subscription primary)
   2. glm/glm-4.7 (Cheap backup, $0.6/1M)
   3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
 
@@ -1815,7 +1897,7 @@ Cost: $0 forever!
 Settings → Models → Advanced:
   OpenAI API Base URL: http://localhost:20128/v1
   OpenAI API Key: [from OmniRoute dashboard]
-  Model: cc/claude-opus-4-6
+  Model: cc/claude-opus-4-7
 ```
 
 ### Claude Code
@@ -1925,7 +2007,7 @@ opencode
 **Rate limiting**
 
 - Subscription quota out → Fallback to GLM/MiniMax
-- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`
 
 **OAuth token expired**
 
@@ -1958,8 +2040,10 @@ opencode
 
 **No request logs**
 
-- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request
+- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views
+- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request
 - Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads
+- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`
 - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`
 - Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed
 
@@ -2165,7 +2249,7 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
 - **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)
 - **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)
 - **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)
+- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills
 - **Schemas**: Zod (MCP tool I/O validation, API contracts)
 - **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)
 - **Streaming**: Server-Sent Events (SSE)
@@ -2183,36 +2267,40 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
 
 ## التوثيق
 
-| Document                                       | Description                                         |
-| ---------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md)               | Providers, combos, CLI integration, deployment      |
-| [API Reference](docs/API_REFERENCE.md)         | All endpoints with examples                         |
-| [MCP Server](open-sse/mcp-server/README.md)    | 16 MCP tools, IDE configs, Python/TS/Go clients     |
-| [A2A Server](src/lib/a2a/README.md)            | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/auto-combo.md)        | 6-factor scoring, mode packs, self-healing          |
-| [Troubleshooting](docs/TROUBLESHOOTING.md)     | Common problems and solutions                       |
-| [Architecture](docs/ARCHITECTURE.md)           | System architecture and internals                   |
-| [Contributing](CONTRIBUTING.md)                | Development setup and guidelines                    |
-| [OpenAPI Spec](docs/openapi.yaml)              | OpenAPI 3.0 specification                           |
-| [Security Policy](SECURITY.md)                 | Vulnerability reporting and security practices      |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md)   | Complete guide: VM + nginx + Cloudflare setup       |
-| [Features Gallery](docs/FEATURES.md)           | Visual dashboard tour with screenshots              |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps                        |
+| Document                                                 | Description                                         |
+| -------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md)                         | Providers, combos, CLI integration, deployment      |
+| [API Reference](docs/API_REFERENCE.md)                   | All endpoints with examples                         |
+| [MCP Server](open-sse/mcp-server/README.md)              | 25 MCP tools, IDE configs, Python/TS/Go clients     |
+| [A2A Server](src/lib/a2a/README.md)                      | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/AUTO-COMBO.md)                  | 6-factor scoring, mode packs, self-healing          |
+| [Context Relay](docs/features/context-relay.md)          | Session handoff strategy for account rotation       |
+| [Troubleshooting](docs/TROUBLESHOOTING.md)               | Common problems and solutions                       |
+| [Architecture](docs/ARCHITECTURE.md)                     | System architecture and internals                   |
+| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough              |
+| [Uninstall Guide](docs/UNINSTALL.md)                     | Clean removal for all install methods               |
+| [Environment Config](docs/ENVIRONMENT.md)                | Complete `.env` variables and references            |
+| [Contributing](CONTRIBUTING.md)                          | Development setup and guidelines                    |
+| [OpenAPI Spec](docs/openapi.yaml)                        | OpenAPI 3.0 specification                           |
+| [Security Policy](SECURITY.md)                           | Vulnerability reporting and security practices      |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md)             | Complete guide: VM + nginx + Cloudflare setup       |
+| [Features Gallery](docs/FEATURES.md)                     | Visual dashboard tour with screenshots              |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md)           | Pre-release validation steps                        |
 
 ---
 
 ## 🗺️ Roadmap
 
-OmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:
+OmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:
 
-| Category                      | Planned Features | Highlights                                                                             |
-| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |
-| 🧠 **Routing & Intelligence** | 25+              | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection      |
-| 🔒 **Security & Compliance**  | 20+              | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping   |
-| 📊 **Observability**          | 15+              | OpenTelemetry integration, real-time quota monitoring, cost tracking per model         |
-| 🔄 **Provider Integrations**  | 20+              | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |
-| ⚡ **Performance**            | 15+              | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API         |
-| 🌐 **Ecosystem**              | 10+              | WebSocket API, config hot-reload, distributed config store, commercial mode            |
+| Category                      | Planned Features | Highlights                                                                                            |
+| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
+| 🧠 **Routing & Intelligence** | 25+              | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |
+| 🔒 **Security & Compliance**  | 20+              | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping                  |
+| 📊 **Observability**          | 15+              | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model   |
+| 🔄 **Provider Integrations**  | 20+              | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing              |
+| ⚡ **Performance**            | 15+              | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API                        |
+| 🌐 **Ecosystem**              | 10+              | WebSocket API, config hot-reload, distributed config store, commercial mode                           |
 
 ### 🔜 Coming Soon
 
@@ -2251,9 +2339,23 @@ gh release create v2.0.0 --title "v2.0.0" --generate-notes
 
 ## 📊 Star History
 
-## Stargazers over time
+<a href="https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left" />
+ </picture>
+</a>
 
-## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)
+## 🌍 StarMapper
+
+<a href="https://starmapper.bruniaux.com/diegosouzapw/omniroute">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light" />
+    <img alt="StarMapper" src="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute" />
+  </picture>
+</a>
 
 ## 🙏 Acknowledgments
 

docs/i18n/ar/SECURITY.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../SECURITY.md) · 🇸🇦 [ar](../ar/SECURITY.md) · 🇧🇬 [bg](../bg/SECURITY.md) · 🇧🇩 [bn](../bn/SECURITY.md) · 🇨🇿 [cs](../cs/SECURITY.md) · 🇩🇰 [da](../da/SECURITY.md) · 🇩🇪 [de](../de/SECURITY.md) · 🇪🇸 [es](../es/SECURITY.md) · 🇮🇷 [fa](../fa/SECURITY.md) · 🇫🇮 [fi](../fi/SECURITY.md) · 🇫🇷 [fr](../fr/SECURITY.md) · 🇮🇳 [gu](../gu/SECURITY.md) · 🇮🇱 [he](../he/SECURITY.md) · 🇮🇳 [hi](../hi/SECURITY.md) · 🇭🇺 [hu](../hu/SECURITY.md) · 🇮🇩 [id](../id/SECURITY.md) · 🇮🇹 [it](../it/SECURITY.md) · 🇯🇵 [ja](../ja/SECURITY.md) · 🇰🇷 [ko](../ko/SECURITY.md) · 🇮🇳 [mr](../mr/SECURITY.md) · 🇲🇾 [ms](../ms/SECURITY.md) · 🇳🇱 [nl](../nl/SECURITY.md) · 🇳🇴 [no](../no/SECURITY.md) · 🇵🇭 [phi](../phi/SECURITY.md) · 🇵🇱 [pl](../pl/SECURITY.md) · 🇵🇹 [pt](../pt/SECURITY.md) · 🇧🇷 [pt-BR](../pt-BR/SECURITY.md) · 🇷🇴 [ro](../ro/SECURITY.md) · 🇷🇺 [ru](../ru/SECURITY.md) · 🇸🇰 [sk](../sk/SECURITY.md) · 🇸🇪 [sv](../sv/SECURITY.md) · 🇰🇪 [sw](../sw/SECURITY.md) · 🇮🇳 [ta](../ta/SECURITY.md) · 🇮🇳 [te](../te/SECURITY.md) · 🇹🇭 [th](../th/SECURITY.md) · 🇹🇷 [tr](../tr/SECURITY.md) · 🇺🇦 [uk-UA](../uk-UA/SECURITY.md) · 🇵🇰 [ur](../ur/SECURITY.md) · 🇻🇳 [vi](../vi/SECURITY.md) · 🇨🇳 [zh-CN](../zh-CN/SECURITY.md)
 
 ---
 
@@ -24,9 +24,9 @@ If you discover a security vulnerability in OmniRoute, please report it responsi
 
 | Version | Support Status |
 | ------- | -------------- |
-| 3.4.x   | ✅ Active      |
-| 3.0.x   | ✅ Security    |
-| < 3.0.0 | ❌ Unsupported |
+| 3.6.x   | ✅ Active      |
+| 3.5.x   | ✅ Security    |
+| < 3.5.0 | ❌ Unsupported |
 
 ---
 

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

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

docs/i18n/ar/docs/API_REFERENCE.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/API_REFERENCE.md) · 🇸🇦 [ar](../../ar/docs/API_REFERENCE.md) · 🇧🇬 [bg](../../bg/docs/API_REFERENCE.md) · 🇧🇩 [bn](../../bn/docs/API_REFERENCE.md) · 🇨🇿 [cs](../../cs/docs/API_REFERENCE.md) · 🇩🇰 [da](../../da/docs/API_REFERENCE.md) · 🇩🇪 [de](../../de/docs/API_REFERENCE.md) · 🇪🇸 [es](../../es/docs/API_REFERENCE.md) · 🇮🇷 [fa](../../fa/docs/API_REFERENCE.md) · 🇫🇮 [fi](../../fi/docs/API_REFERENCE.md) · 🇫🇷 [fr](../../fr/docs/API_REFERENCE.md) · 🇮🇳 [gu](../../gu/docs/API_REFERENCE.md) · 🇮🇱 [he](../../he/docs/API_REFERENCE.md) · 🇮🇳 [hi](../../hi/docs/API_REFERENCE.md) · 🇭🇺 [hu](../../hu/docs/API_REFERENCE.md) · 🇮🇩 [id](../../id/docs/API_REFERENCE.md) · 🇮🇹 [it](../../it/docs/API_REFERENCE.md) · 🇯🇵 [ja](../../ja/docs/API_REFERENCE.md) · 🇰🇷 [ko](../../ko/docs/API_REFERENCE.md) · 🇮🇳 [mr](../../mr/docs/API_REFERENCE.md) · 🇲🇾 [ms](../../ms/docs/API_REFERENCE.md) · 🇳🇱 [nl](../../nl/docs/API_REFERENCE.md) · 🇳🇴 [no](../../no/docs/API_REFERENCE.md) · 🇵🇭 [phi](../../phi/docs/API_REFERENCE.md) · 🇵🇱 [pl](../../pl/docs/API_REFERENCE.md) · 🇵🇹 [pt](../../pt/docs/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/API_REFERENCE.md) · 🇷🇴 [ro](../../ro/docs/API_REFERENCE.md) · 🇷🇺 [ru](../../ru/docs/API_REFERENCE.md) · 🇸🇰 [sk](../../sk/docs/API_REFERENCE.md) · 🇸🇪 [sv](../../sv/docs/API_REFERENCE.md) · 🇰🇪 [sw](../../sw/docs/API_REFERENCE.md) · 🇮🇳 [ta](../../ta/docs/API_REFERENCE.md) · 🇮🇳 [te](../../te/docs/API_REFERENCE.md) · 🇹🇭 [th](../../th/docs/API_REFERENCE.md) · 🇹🇷 [tr](../../tr/docs/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/API_REFERENCE.md) · 🇵🇰 [ur](../../ur/docs/API_REFERENCE.md) · 🇻🇳 [vi](../../vi/docs/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/API_REFERENCE.md)
 
 ---
 
@@ -70,7 +70,7 @@ Content-Type: application/json
 }
 ```
 
-Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, **GitHub Models**.
 
 ```bash
 # List all embedding models
@@ -93,7 +93,7 @@ Content-Type: application/json
 }
 ```
 
-Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+Available providers: OpenAI (DALL-E, GPT Image 1), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (local), ComfyUI (local).
 
 ```bash
 # List all image models
@@ -181,15 +181,15 @@ Response example:
 
 ### 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            |
+| 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/PATCH/DELETE | Custom models (add, update, hide/show, delete) |
 
 ### OAuth Flows
 
@@ -286,12 +286,12 @@ GET response includes `agents[]` (id, name, binary, version, installed, protocol
 
 ### Resilience & Rate Limits
 
-| 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 |
+| Endpoint                | Method    | Description                                                                        |
+| ----------------------- | --------- | ---------------------------------------------------------------------------------- |
+| `/api/resilience`       | GET/PATCH | Get/update request queue, connection cooldown, provider breaker, and wait settings |
+| `/api/resilience/reset` | POST      | Reset provider circuit breakers                                                    |
+| `/api/rate-limits`      | GET       | Per-account rate limit status                                                      |
+| `/api/rate-limit`       | GET       | Global rate limit configuration                                                    |
 
 ### Evals
 
@@ -322,15 +322,38 @@ These endpoints mirror Gemini's API format for clients that expect native Gemini
 
 ### 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                     |
+| 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                     |
+| `/api/system/env/repair` | POST   | Repair OAuth provider environment variables          |
+| `/api/system-info`       | GET    | Generate system diagnostics report                   |
 
 > **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users.
 
+### OAuth Environment Repair _(v3.6.1+)_
+
+```bash
+POST /api/system/env/repair
+Content-Type: application/json
+
+{
+  "provider": "claude-code"
+}
+```
+
+Repairs missing or corrupted OAuth environment variables for a specific provider. Returns:
+
+```json
+{
+  "success": true,
+  "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
+  "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
+}
+```
+
 ---
 
 ## Audio Transcription
@@ -422,25 +445,6 @@ Content-Type: application/json
 }
 ```
 
----
-
-## 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/*`

docs/i18n/ar/docs/ARCHITECTURE.md

@@ -1,10 +1,10 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/ARCHITECTURE.md) · 🇸🇦 [ar](../../ar/docs/ARCHITECTURE.md) · 🇧🇬 [bg](../../bg/docs/ARCHITECTURE.md) · 🇧🇩 [bn](../../bn/docs/ARCHITECTURE.md) · 🇨🇿 [cs](../../cs/docs/ARCHITECTURE.md) · 🇩🇰 [da](../../da/docs/ARCHITECTURE.md) · 🇩🇪 [de](../../de/docs/ARCHITECTURE.md) · 🇪🇸 [es](../../es/docs/ARCHITECTURE.md) · 🇮🇷 [fa](../../fa/docs/ARCHITECTURE.md) · 🇫🇮 [fi](../../fi/docs/ARCHITECTURE.md) · 🇫🇷 [fr](../../fr/docs/ARCHITECTURE.md) · 🇮🇳 [gu](../../gu/docs/ARCHITECTURE.md) · 🇮🇱 [he](../../he/docs/ARCHITECTURE.md) · 🇮🇳 [hi](../../hi/docs/ARCHITECTURE.md) · 🇭🇺 [hu](../../hu/docs/ARCHITECTURE.md) · 🇮🇩 [id](../../id/docs/ARCHITECTURE.md) · 🇮🇹 [it](../../it/docs/ARCHITECTURE.md) · 🇯🇵 [ja](../../ja/docs/ARCHITECTURE.md) · 🇰🇷 [ko](../../ko/docs/ARCHITECTURE.md) · 🇮🇳 [mr](../../mr/docs/ARCHITECTURE.md) · 🇲🇾 [ms](../../ms/docs/ARCHITECTURE.md) · 🇳🇱 [nl](../../nl/docs/ARCHITECTURE.md) · 🇳🇴 [no](../../no/docs/ARCHITECTURE.md) · 🇵🇭 [phi](../../phi/docs/ARCHITECTURE.md) · 🇵🇱 [pl](../../pl/docs/ARCHITECTURE.md) · 🇵🇹 [pt](../../pt/docs/ARCHITECTURE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) · 🇷🇴 [ro](../../ro/docs/ARCHITECTURE.md) · 🇷🇺 [ru](../../ru/docs/ARCHITECTURE.md) · 🇸🇰 [sk](../../sk/docs/ARCHITECTURE.md) · 🇸🇪 [sv](../../sv/docs/ARCHITECTURE.md) · 🇰🇪 [sw](../../sw/docs/ARCHITECTURE.md) · 🇮🇳 [ta](../../ta/docs/ARCHITECTURE.md) · 🇮🇳 [te](../../te/docs/ARCHITECTURE.md) · 🇹🇭 [th](../../th/docs/ARCHITECTURE.md) · 🇹🇷 [tr](../../tr/docs/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) · 🇵🇰 [ur](../../ur/docs/ARCHITECTURE.md) · 🇻🇳 [vi](../../vi/docs/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/ARCHITECTURE.md)
 
 ---
 
-_Last updated: 2026-03-28_
+_Last updated: 2026-04-15_
 
 ## Executive Summary
 
@@ -13,18 +13,27 @@ It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic acr
 
 Core capabilities:
 
-- OpenAI-compatible API surface for CLI/tools (28 providers)
+- OpenAI-compatible API surface for CLI/tools (100+ providers, 16 executors)
 - Request/response translation across provider formats
 - Model combo fallback (multi-model sequence)
+- Structured combo steps (`provider + model + connection`) with runtime ordering by `compositeTiers`
 - Account-level fallback (multi-account per provider)
-- OAuth + API-key provider connection management
+- Quota preflight and quota-aware P2C account selection in the main chat path
+- OAuth + API-key provider connection management (13 OAuth modules)
 - Embedding generation via `/v1/embeddings` (6 providers, 9 models)
-- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Image generation via `/v1/images/generations` (10+ providers, 20+ models)
+- Audio transcription via `/v1/audio/transcriptions` (7 providers)
+- Text-to-speech via `/v1/audio/speech` (10 providers)
+- Video generation via `/v1/videos/generations` (ComfyUI + SD WebUI)
+- Music generation via `/v1/music/generations` (ComfyUI)
+- Web search via `/v1/search` (5 providers)
+- Moderations via `/v1/moderations`
+- Reranking via `/v1/rerank`
 - 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
+- Local persistence for providers, keys, aliases, combos, settings, pricing (26 DB modules)
 - Usage/cost tracking and request logging
 - Optional cloud sync for multi-device/state sync
 - IP allowlist/blocklist for API access control
@@ -35,15 +44,35 @@ Core capabilities:
 - 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 layer: cost rules, fallback policy, lockout policy
+- Context Relay: session handoff summaries for account rotation continuity
 - 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
+- Combo target telemetry and historical combo target health via `combo_execution_key` / `combo_step_id`
 - 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/`)
+- Health dashboard with real-time provider circuit breaker status
+- MCP Server (25 tools) with 3 transports (stdio/SSE/Streamable HTTP)
+- A2A Server (JSON-RPC 2.0 + SSE) with skills and task lifecycle
+- Memory system (extraction, injection, retrieval, summarization)
+- Skills system (registry, executor, sandbox, built-in skills)
+- MITM proxy with certificate management and DNS handling
+- Prompt injection guard middleware
+- ACP (Agent Communication Protocol) registry
+- Modular OAuth providers (13 individual modules under `src/lib/oauth/providers/`)
+- Uninstall/full-uninstall scripts
+- OAuth environment repair action
+- WebSocket bridge for OpenAI-compatible WS clients (`/v1/ws`)
+- Sync token management (issue/revoke, ETag-versioned config bundle download)
+- GLM Thinking (`glmt`) first-class provider preset
+- Hybrid token counting (provider-side `/messages/count_tokens` with estimation fallback)
+- Model alias auto-seeding (30+ cross-proxy dialect normalizations at startup)
+- Safe outbound fetch with SSRF guard, private URL blocking, and configurable retry
+- Cooldown-aware chat retries with configurable `requestRetry` and `maxRetryIntervalSec`
+- Runtime environment validation with Zod at startup
+- Compliance audit v2 with pagination, provider CRUD events, and SSRF-blocked validation logging
 
 Primary runtime model:
 
@@ -74,15 +103,15 @@ 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/combos` — combo strategies, templates, step-based builder, model routing rules, manual persisted ordering
 - `/dashboard/costs` — cost aggregation and pricing visibility
-- `/dashboard/analytics` — usage analytics and evaluations
+- `/dashboard/analytics` — usage analytics, evaluations, combo target health
 - `/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/health` — uptime, circuit breakers, rate limits, quota-monitored sessions
 - `/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
@@ -178,16 +207,18 @@ Management domains:
 - 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
+- Resilience: `src/app/api/resilience` (GET/PATCH) — request queue, connection cooldown, provider breaker, wait-for-cooldown config
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset provider breakers
 - 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)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET, with pagination + structured metadata)
 - Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
 - Policies: `src/app/api/policies` (GET/POST)
+- Sync tokens: `src/app/api/sync/tokens` (GET/POST), `src/app/api/sync/tokens/[id]` (GET/DELETE)
+- Config bundle: `src/app/api/sync/bundle` (GET, ETag-versioned snapshot of settings/providers/combos/keys)
+- WebSocket: `src/app/api/v1/ws/route.ts` — Upgrade handler for OpenAI-compatible WS clients
 
 ## 2) SSE + Translation Core
 
@@ -222,10 +253,19 @@ Services (business logic):
 - Wildcard model routing: `open-sse/services/wildcardRouter.ts`
 - Rate limit management: `open-sse/services/rateLimitManager.ts`
 - Circuit breaker: `open-sse/services/circuitBreaker.ts`
+- Context handoff: `open-sse/services/contextHandoff.ts` — handoff summary generation and injection for context-relay strategy
+- Codex quota fetcher: `open-sse/services/codexQuotaFetcher.ts` — fetches Codex quota for context-relay handoff decisions
+- Cooldown-aware retry: `src/sse/services/cooldownAwareRetry.ts` — per-model cooldown retries with configurable `requestRetry` / `maxRetryIntervalSec`
+- Safe outbound fetch: `src/shared/network/safeOutboundFetch.ts` — guarded provider/model fetch with SSRF guard, private-URL blocking, retry, and timeout
+- Outbound URL guard: `src/shared/network/outboundUrlGuard.ts` — validates provider URLs against private/localhost CIDR ranges
+- Provider request defaults: `open-sse/services/providerRequestDefaults.ts` — provider-level `maxTokens`, `temperature`, `thinkingBudgetTokens` defaults
+- GLM provider constants: `open-sse/config/glmProvider.ts` — shared GLM models, quota URLs, GLMT timeout/defaults
+- Antigravity upstream: `open-sse/config/antigravityUpstream.ts` — base URL and discovery path constants
+- Codex client constants: `open-sse/config/codexClient.ts` — versioned user-agent and client-version values
+- Model alias seed: `src/lib/modelAliasSeed.ts` — seeds 30+ cross-proxy dialect aliases at startup
 
 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`
@@ -239,7 +279,7 @@ Domain layer modules:
 - 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/`):
+OAuth provider modules (13 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`, `qoder.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
@@ -273,6 +313,10 @@ Domain State DB (SQLite):
 - 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)
+- SSRF / outbound URL guard: `src/shared/network/outboundUrlGuard.ts` — blocks private/loopback/link-local ranges for all provider calls
+- Runtime env validation: `src/lib/env/runtimeEnv.ts` — Zod schema for all environment variables, surfaced as startup errors/warnings
+- Sync tokens: `src/lib/db/syncTokens.ts` — scoped tokens for config bundle download endpoints; backed by `sync_tokens` SQLite table (migration `024_create_sync_tokens.sql`)
+- WebSocket handshake auth: `src/lib/ws/handshake.ts` — validates WS upgrade requests via API key or session cookie
 
 ## 5) Cloud Sync
 
@@ -590,6 +634,10 @@ flowchart LR
 - `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)
+- `src/app/api/sync/tokens`: sync token CRUD (GET/POST)
+- `src/app/api/sync/tokens/[id]`: sync token get/delete (GET/DELETE)
+- `src/app/api/sync/bundle`: config bundle download (GET, ETag versioning)
+- `src/app/api/v1/ws`: WebSocket upgrade handler for OpenAI-compatible WS clients
 
 ### Routing and Execution Core
 
@@ -614,15 +662,22 @@ flowchart LR
 
 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, 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 |
-| `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                                     |
+| Executor               | Provider(s)                                                                                                                                                 | Special Handling                                                     |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `DefaultExecutor`      | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA, etc. | Dynamic URL/header config per provider                               |
+| `AntigravityExecutor`  | Google Antigravity                                                                                                                                          | Custom project/session IDs, Retry-After parsing                      |
+| `CliProxyApiExecutor`  | CLIProxyAPI-compatible providers                                                                                                                            | Custom auth and protocol handling                                    |
+| `CloudflareAiExecutor` | Cloudflare Workers AI                                                                                                                                       | Account ID injection, Neurons-based usage tracking                   |
+| `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                      |
+| `GeminiCLIExecutor`    | Gemini CLI                                                                                                                                                  | Google OAuth token refresh cycle                                     |
+| `KiroExecutor`         | AWS CodeWhisperer/Kiro                                                                                                                                      | AWS EventStream binary format → SSE conversion                       |
+| `OpenCodeExecutor`     | OpenCode                                                                                                                                                    | AI SDK compatible provider setup                                     |
+| `PollinationsExecutor` | Pollinations AI                                                                                                                                             | No API key required, rate-limited requests                           |
+| `PuterExecutor`        | Puter                                                                                                                                                       | Browser-based provider integration                                   |
+| `QoderExecutor`        | Qoder AI                                                                                                                                                    | PAT and OAuth support, multi-model free tier                         |
+| `VertexExecutor`       | Google Vertex AI                                                                                                                                            | Service account auth, region-based endpoints                         |
 
 All other providers (including custom compatible nodes) use the `DefaultExecutor`.
 
@@ -640,7 +695,10 @@ 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     |
-| Qoder            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Qoder            | openai           | OAuth / PAT           | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Kilo Code        | openai           | OAuth                 | ✅               | ✅         | ✅            | ❌                 |
+| Cline            | openai           | OAuth                 | ✅               | ✅         | ✅            | ❌                 |
+| Kimi Coding      | openai           | OAuth                 | ✅               | ✅         | ✅            | ❌                 |
 | OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
@@ -653,6 +711,17 @@ All other providers (including custom compatible nodes) use the `DefaultExecutor
 | Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cloudflare AI    | openai           | API Token + Acct ID   | ✅               | ✅         | ❌            | ❌                 |
+| Pollinations     | openai           | None (no key)         | ✅               | ✅         | ❌            | ❌                 |
+| Scaleway AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| LongCat          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Ollama Cloud     | openai           | API Key (optional)    | ✅               | ✅         | ❌            | ❌                 |
+| HuggingFace      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Nebius           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| SiliconFlow      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Hyperbolic       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Vertex AI        | gemini           | Service Account       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Puter            | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 
 ## Format Translation Coverage
 
@@ -712,22 +781,20 @@ Additional processing layers in the translation pipeline:
 
 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
+## Request Logging and Artifacts
 
-The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`:
+The older file-based request logger (`open-sse/utils/requestLogger.ts`) is retained only for
+legacy compatibility. The current runtime contract uses:
 
-```
-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.
+- `APP_LOG_TO_FILE=true` for application and audit logs written under `<repo>/logs/`
+- SQLite-backed call log records in `call_logs`
+- `${DATA_DIR}/call_logs/YYYY-MM-DD/...` artifacts when the call log pipeline is enabled
 
 ## Failure Modes and Resilience
 
 ## 1) Account/Provider Availability
 
-- provider account cooldown on transient/rate/auth errors
+- connection cooldown on retryable upstream failures
 - account fallback before failing request
 - combo model fallback when current model/provider path is exhausted
 
@@ -752,6 +819,12 @@ Files are written to `<repo>/logs/<session>/` for each request session.
 - SQLite schema migrations and auto-upgrade hooks at startup
 - legacy JSON → SQLite migration compatibility path
 
+## 6) SSRF / Outbound URL Guard
+
+- `src/shared/network/outboundUrlGuard.ts` blocks all private/loopback/link-local target URLs before they reach provider executors
+- Provider model discovery and validation routes use `src/shared/network/safeOutboundFetch.ts` which applies the guard before every outbound request
+- Guard errors surface as `URL_GUARD_BLOCKED` with HTTP 422 and are logged to the compliance audit trail via `providerAudit.ts`
+
 ## Observability and Operational Signals
 
 Runtime visibility sources:
@@ -760,7 +833,8 @@ Runtime visibility sources:
 - 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`
+- optional application log files under `logs/` when `APP_LOG_TO_FILE=true`
+- optional request artifacts under `${DATA_DIR}/call_logs/` when the call log pipeline is enabled
 - dashboard usage endpoints (`/api/usage/*`) for UI consumption
 
 Detailed request payload capture stores up to four JSON payload stages per routed call:
@@ -787,7 +861,7 @@ Environment variables actively used by code:
 - 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`
+- Logging: `APP_LOG_TO_FILE`, `APP_LOG_RETENTION_DAYS`, `CALL_LOG_RETENTION_DAYS`
 - 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`
@@ -802,7 +876,10 @@ Environment variables actively used by code:
 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).
+8. Settings page is organized into 7 tabs: General, Appearance, AI, Security, Routing, Resilience, Advanced. The Resilience page only configures request queue, connection cooldown, provider breaker, and wait-for-cooldown behavior; live breaker runtime state is shown on the Health page.
+9. **Context Relay** strategy (`context-relay`) is split across two layers: `combo.ts` decides if a handoff should be generated, `chat.ts` injects the handoff after account resolution. Handoff data lives in `context_handoffs` SQLite table. This split is intentional because only `chat.ts` knows whether the actual account changed.
+10. **Proxy enforcement** is now comprehensive: `tokenHealthCheck.ts` resolves proxy per connection, `/api/providers/validate` uses `runWithProxyContext`, and `proxyFetch.ts` uses `undici.fetch()` to maintain dispatcher compatibility on Node 22.
+11. **Node.js runtime policy detection**: `/api/settings/require-login` returns `nodeVersion` and `nodeCompatible` fields. The login page renders a warning banner when the runtime falls outside the supported secure Node.js lines.
 
 ## Operational Verification Checklist
 

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

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

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

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/CLI-TOOLS.md) · 🇸🇦 [ar](../../ar/docs/CLI-TOOLS.md) · 🇧🇬 [bg](../../bg/docs/CLI-TOOLS.md) · 🇧🇩 [bn](../../bn/docs/CLI-TOOLS.md) · 🇨🇿 [cs](../../cs/docs/CLI-TOOLS.md) · 🇩🇰 [da](../../da/docs/CLI-TOOLS.md) · 🇩🇪 [de](../../de/docs/CLI-TOOLS.md) · 🇪🇸 [es](../../es/docs/CLI-TOOLS.md) · 🇮🇷 [fa](../../fa/docs/CLI-TOOLS.md) · 🇫🇮 [fi](../../fi/docs/CLI-TOOLS.md) · 🇫🇷 [fr](../../fr/docs/CLI-TOOLS.md) · 🇮🇳 [gu](../../gu/docs/CLI-TOOLS.md) · 🇮🇱 [he](../../he/docs/CLI-TOOLS.md) · 🇮🇳 [hi](../../hi/docs/CLI-TOOLS.md) · 🇭🇺 [hu](../../hu/docs/CLI-TOOLS.md) · 🇮🇩 [id](../../id/docs/CLI-TOOLS.md) · 🇮🇹 [it](../../it/docs/CLI-TOOLS.md) · 🇯🇵 [ja](../../ja/docs/CLI-TOOLS.md) · 🇰🇷 [ko](../../ko/docs/CLI-TOOLS.md) · 🇮🇳 [mr](../../mr/docs/CLI-TOOLS.md) · 🇲🇾 [ms](../../ms/docs/CLI-TOOLS.md) · 🇳🇱 [nl](../../nl/docs/CLI-TOOLS.md) · 🇳🇴 [no](../../no/docs/CLI-TOOLS.md) · 🇵🇭 [phi](../../phi/docs/CLI-TOOLS.md) · 🇵🇱 [pl](../../pl/docs/CLI-TOOLS.md) · 🇵🇹 [pt](../../pt/docs/CLI-TOOLS.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) · 🇷🇴 [ro](../../ro/docs/CLI-TOOLS.md) · 🇷🇺 [ru](../../ru/docs/CLI-TOOLS.md) · 🇸🇰 [sk](../../sk/docs/CLI-TOOLS.md) · 🇸🇪 [sv](../../sv/docs/CLI-TOOLS.md) · 🇰🇪 [sw](../../sw/docs/CLI-TOOLS.md) · 🇮🇳 [ta](../../ta/docs/CLI-TOOLS.md) · 🇮🇳 [te](../../te/docs/CLI-TOOLS.md) · 🇹🇭 [th](../../th/docs/CLI-TOOLS.md) · 🇹🇷 [tr](../../tr/docs/CLI-TOOLS.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) · 🇵🇰 [ur](../../ur/docs/CLI-TOOLS.md) · 🇻🇳 [vi](../../vi/docs/CLI-TOOLS.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/CLI-TOOLS.md)
 
 ---
 
@@ -50,6 +50,7 @@ Current list (v3.0.0-rc.16):
 | **GitHub Copilot** | `copilot`     | extension  | custom     | VS Code        |
 | **OpenCode**       | `opencode`    | `opencode` | guide      | npm            |
 | **Kiro AI**        | `kiro`        | app/cli    | mitm       | desktop/CLI    |
+| **Qwen Code**      | `qwen`        | `qwen`     | custom     | npm            |
 
 ### CLI fingerprint sync (Agents + Settings)
 
@@ -257,6 +258,55 @@ kiro-cli status
 
 ---
 
+### Qwen Code (Alibaba)
+
+Qwen Code supports OpenAI-compatible API endpoints via environment variables or `settings.json`.
+
+**Option 1: Environment variables (`~/.qwen/.env`)**
+
+```bash
+mkdir -p ~/.qwen && cat > ~/.qwen/.env << EOF
+OPENAI_API_KEY="sk-your-omniroute-key"
+OPENAI_BASE_URL="http://localhost:20128/v1"
+OPENAI_MODEL="auto"
+EOF
+```
+
+**Option 2: `settings.json` with model providers**
+
+```json
+// ~/.qwen/settings.json
+{
+  "env": {
+    "OPENAI_API_KEY": "sk-your-omniroute-key",
+    "OPENAI_BASE_URL": "http://localhost:20128/v1"
+  },
+  "modelProviders": {
+    "openai": [
+      {
+        "id": "omniroute-default",
+        "name": "OmniRoute (Auto)",
+        "envKey": "OPENAI_API_KEY",
+        "baseUrl": "http://localhost:20128/v1"
+      }
+    ]
+  }
+}
+```
+
+**Option 3: Inline CLI flags**
+
+```bash
+OPENAI_BASE_URL="http://localhost:20128/v1" \
+OPENAI_API_KEY="sk-your-omniroute-key" \
+OPENAI_MODEL="auto" \
+qwen
+```
+
+> For a **remote server** replace `localhost:20128` with the server IP or domain.
+
+**Test:** `qwen "say hello"`
+
 ### Cursor (Desktop App)
 
 > **Note:** Cursor routes requests through its cloud. For OmniRoute integration,
@@ -326,7 +376,7 @@ They run as internal routes and use OmniRoute's model routing automatically.
 OMNIROUTE_URL="http://localhost:20128/v1"
 OMNIROUTE_KEY="sk-your-omniroute-key"
 
-npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode
+npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode @qwen-code/qwen-code
 
 # Kiro CLI
 apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash

docs/i18n/ar/docs/CODEBASE_DOCUMENTATION.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) · 🇧🇩 [bn](../../bn/docs/CODEBASE_DOCUMENTATION.md) · 🇨🇿 [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../../da/docs/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../../de/docs/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../../es/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇷 [fa](../../fa/docs/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [gu](../../gu/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../../he/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [hi](../../hi/docs/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../../id/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../../it/docs/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [mr](../../mr/docs/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../../no/docs/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) · 🇰🇪 [sw](../../sw/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ta](../../ta/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [te](../../te/docs/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../../th/docs/CODEBASE_DOCUMENTATION.md) · 🇹🇷 [tr](../../tr/docs/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) · 🇵🇰 [ur](../../ur/docs/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md)
 
 ---
 
@@ -405,7 +405,7 @@ import "./request/claude-to-openai.js"; // ← self-registers
 | `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.                                                              |
+| `requestLogger.ts` | Legacy file-based request logging helper kept for compatibility. Current deployments should prefer `APP_LOG_TO_FILE` for application logs and the call log pipeline for persisted request artifacts.                                                                                 |
 | `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.                                                  |
 

docs/i18n/ar/docs/COVERAGE_PLAN.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/COVERAGE_PLAN.md) · 🇸🇦 [ar](../../ar/docs/COVERAGE_PLAN.md) · 🇧🇬 [bg](../../bg/docs/COVERAGE_PLAN.md) · 🇧🇩 [bn](../../bn/docs/COVERAGE_PLAN.md) · 🇨🇿 [cs](../../cs/docs/COVERAGE_PLAN.md) · 🇩🇰 [da](../../da/docs/COVERAGE_PLAN.md) · 🇩🇪 [de](../../de/docs/COVERAGE_PLAN.md) · 🇪🇸 [es](../../es/docs/COVERAGE_PLAN.md) · 🇮🇷 [fa](../../fa/docs/COVERAGE_PLAN.md) · 🇫🇮 [fi](../../fi/docs/COVERAGE_PLAN.md) · 🇫🇷 [fr](../../fr/docs/COVERAGE_PLAN.md) · 🇮🇳 [gu](../../gu/docs/COVERAGE_PLAN.md) · 🇮🇱 [he](../../he/docs/COVERAGE_PLAN.md) · 🇮🇳 [hi](../../hi/docs/COVERAGE_PLAN.md) · 🇭🇺 [hu](../../hu/docs/COVERAGE_PLAN.md) · 🇮🇩 [id](../../id/docs/COVERAGE_PLAN.md) · 🇮🇹 [it](../../it/docs/COVERAGE_PLAN.md) · 🇯🇵 [ja](../../ja/docs/COVERAGE_PLAN.md) · 🇰🇷 [ko](../../ko/docs/COVERAGE_PLAN.md) · 🇮🇳 [mr](../../mr/docs/COVERAGE_PLAN.md) · 🇲🇾 [ms](../../ms/docs/COVERAGE_PLAN.md) · 🇳🇱 [nl](../../nl/docs/COVERAGE_PLAN.md) · 🇳🇴 [no](../../no/docs/COVERAGE_PLAN.md) · 🇵🇭 [phi](../../phi/docs/COVERAGE_PLAN.md) · 🇵🇱 [pl](../../pl/docs/COVERAGE_PLAN.md) · 🇵🇹 [pt](../../pt/docs/COVERAGE_PLAN.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) · 🇷🇴 [ro](../../ro/docs/COVERAGE_PLAN.md) · 🇷🇺 [ru](../../ru/docs/COVERAGE_PLAN.md) · 🇸🇰 [sk](../../sk/docs/COVERAGE_PLAN.md) · 🇸🇪 [sv](../../sv/docs/COVERAGE_PLAN.md) · 🇰🇪 [sw](../../sw/docs/COVERAGE_PLAN.md) · 🇮🇳 [ta](../../ta/docs/COVERAGE_PLAN.md) · 🇮🇳 [te](../../te/docs/COVERAGE_PLAN.md) · 🇹🇭 [th](../../th/docs/COVERAGE_PLAN.md) · 🇹🇷 [tr](../../tr/docs/COVERAGE_PLAN.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) · 🇵🇰 [ur](../../ur/docs/COVERAGE_PLAN.md) · 🇻🇳 [vi](../../vi/docs/COVERAGE_PLAN.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md)
 
 ---
 

docs/i18n/ar/docs/ENVIRONMENT.md

@@ -0,0 +1,669 @@
+# Environment Variables Reference (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/ENVIRONMENT.md) · 🇸🇦 [ar](../../ar/docs/ENVIRONMENT.md) · 🇧🇬 [bg](../../bg/docs/ENVIRONMENT.md) · 🇧🇩 [bn](../../bn/docs/ENVIRONMENT.md) · 🇨🇿 [cs](../../cs/docs/ENVIRONMENT.md) · 🇩🇰 [da](../../da/docs/ENVIRONMENT.md) · 🇩🇪 [de](../../de/docs/ENVIRONMENT.md) · 🇪🇸 [es](../../es/docs/ENVIRONMENT.md) · 🇮🇷 [fa](../../fa/docs/ENVIRONMENT.md) · 🇫🇮 [fi](../../fi/docs/ENVIRONMENT.md) · 🇫🇷 [fr](../../fr/docs/ENVIRONMENT.md) · 🇮🇳 [gu](../../gu/docs/ENVIRONMENT.md) · 🇮🇱 [he](../../he/docs/ENVIRONMENT.md) · 🇮🇳 [hi](../../hi/docs/ENVIRONMENT.md) · 🇭🇺 [hu](../../hu/docs/ENVIRONMENT.md) · 🇮🇩 [id](../../id/docs/ENVIRONMENT.md) · 🇮🇹 [it](../../it/docs/ENVIRONMENT.md) · 🇯🇵 [ja](../../ja/docs/ENVIRONMENT.md) · 🇰🇷 [ko](../../ko/docs/ENVIRONMENT.md) · 🇮🇳 [mr](../../mr/docs/ENVIRONMENT.md) · 🇲🇾 [ms](../../ms/docs/ENVIRONMENT.md) · 🇳🇱 [nl](../../nl/docs/ENVIRONMENT.md) · 🇳🇴 [no](../../no/docs/ENVIRONMENT.md) · 🇵🇭 [phi](../../phi/docs/ENVIRONMENT.md) · 🇵🇱 [pl](../../pl/docs/ENVIRONMENT.md) · 🇵🇹 [pt](../../pt/docs/ENVIRONMENT.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/ENVIRONMENT.md) · 🇷🇴 [ro](../../ro/docs/ENVIRONMENT.md) · 🇷🇺 [ru](../../ru/docs/ENVIRONMENT.md) · 🇸🇰 [sk](../../sk/docs/ENVIRONMENT.md) · 🇸🇪 [sv](../../sv/docs/ENVIRONMENT.md) · 🇰🇪 [sw](../../sw/docs/ENVIRONMENT.md) · 🇮🇳 [ta](../../ta/docs/ENVIRONMENT.md) · 🇮🇳 [te](../../te/docs/ENVIRONMENT.md) · 🇹🇭 [th](../../th/docs/ENVIRONMENT.md) · 🇹🇷 [tr](../../tr/docs/ENVIRONMENT.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/ENVIRONMENT.md) · 🇵🇰 [ur](../../ur/docs/ENVIRONMENT.md) · 🇻🇳 [vi](../../vi/docs/ENVIRONMENT.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/ENVIRONMENT.md)
+
+---
+
+> Complete reference for every environment variable recognized by OmniRoute.
+> For a quick-start template, see [`.env.example`](../.env.example).
+
+---
+
+## Table of Contents
+
+- [1. Required Secrets](#1-required-secrets)
+- [2. Storage & Database](#2-storage--database)
+- [3. Network & Ports](#3-network--ports)
+- [4. Security & Authentication](#4-security--authentication)
+- [5. Input Sanitization & PII Protection](#5-input-sanitization--pii-protection)
+- [6. Tool & Routing Policies](#6-tool--routing-policies)
+- [7. URLs & Cloud Sync](#7-urls--cloud-sync)
+- [8. Outbound Proxy](#8-outbound-proxy)
+- [9. CLI Tool Integration](#9-cli-tool-integration)
+- [10. Internal Agent & MCP Integrations](#10-internal-agent--mcp-integrations)
+- [11. OAuth Provider Credentials](#11-oauth-provider-credentials)
+- [12. Provider User-Agent Overrides](#12-provider-user-agent-overrides)
+- [13. CLI Fingerprint Compatibility](#13-cli-fingerprint-compatibility)
+- [14. API Key Providers](#14-api-key-providers)
+- [15. Timeout Settings](#15-timeout-settings)
+- [16. Logging](#16-logging)
+- [17. Memory Optimization](#17-memory-optimization)
+- [18. Pricing Sync](#18-pricing-sync)
+- [19. Model Sync (Dev)](#19-model-sync-dev)
+- [20. Provider-Specific Settings](#20-provider-specific-settings)
+- [21. Proxy Health](#21-proxy-health)
+- [22. Debugging](#22-debugging)
+- [23. GitHub Integration](#23-github-integration)
+- [Deployment Scenarios](#deployment-scenarios)
+- [Audit: Removed / Dead Variables](#audit-removed--dead-variables)
+
+---
+
+## 1. Required Secrets
+
+These **must** be set before the first run. Without them, the application will either refuse to start or operate with insecure defaults.
+
+| Variable           | Required | Default  | Source File             | Description                                                                                                                      |
+| ------------------ | -------- | -------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET`       | **Yes**  | _(none)_ | `src/lib/auth`          | Signs/verifies all dashboard session cookies (JWT). Generate with `openssl rand -base64 48`.                                     |
+| `API_KEY_SECRET`   | **Yes**  | _(none)_ | `src/lib/db/apiKeys.ts` | AES encryption key for API key values at rest in SQLite. Generate with `openssl rand -hex 32`.                                   |
+| `INITIAL_PASSWORD` | **Yes**  | `123456` | Bootstrap script        | Sets the initial admin dashboard password. **Change before first use.** After login, change via Dashboard → Settings → Security. |
+
+### Generation Commands
+
+```bash
+# Generate all three secrets at once:
+echo "JWT_SECRET=$(openssl rand -base64 48)"
+echo "API_KEY_SECRET=$(openssl rand -hex 32)"
+echo "INITIAL_PASSWORD=$(openssl rand -base64 16)"
+```
+
+> [!CAUTION]
+> Never commit `.env` files with real secrets to version control. The `.gitignore` already excludes `.env`, but verify before pushing.
+
+---
+
+## 2. Storage & Database
+
+OmniRoute uses **SQLite** (via `better-sqlite3`) for all persistence. These variables control data location, encryption, and lifecycle.
+
+| Variable                         | Default              | Source File                                     | Description                                                                                                        |
+| -------------------------------- | -------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `DATA_DIR`                       | `~/.omniroute/`      | `src/lib/db/core.ts`                            | Root directory for SQLite DB, backups, and data files. Override for Docker volumes or custom paths.                |
+| `STORAGE_ENCRYPTION_KEY`         | _(empty = disabled)_ | `src/lib/db/encryption.ts`                      | AES key for full SQLite database encryption at rest. Generate with `openssl rand -hex 32`.                         |
+| `STORAGE_ENCRYPTION_KEY_VERSION` | `v1`                 | `scripts/bootstrap-env.mjs`, `electron/main.js` | Version label for the encryption key. Increment when performing key rotation to support decryption of old backups. |
+| `DISABLE_SQLITE_AUTO_BACKUP`     | `false`              | `src/lib/db/backup.ts`                          | When `true`, skips the automatic database backup that runs before migrations on every startup.                     |
+| `OMNIROUTE_CRYPT_KEY`            | _(unset)_            | `src/lib/db/encryption.ts`                      | **Legacy alias** for `STORAGE_ENCRYPTION_KEY`. Accepted as a fallback when the primary variable is absent.         |
+| `OMNIROUTE_API_KEY_BASE64`       | _(unset)_            | `src/lib/db/encryption.ts`                      | **Legacy alias** (Base64-encoded form) accepted as a fallback. Decoded automatically before use.                   |
+
+### Scenarios
+
+| Scenario              | Configuration                                                                    |
+| --------------------- | -------------------------------------------------------------------------------- |
+| **Local development** | Leave all defaults. DB lives at `~/.omniroute/omniroute.db`.                     |
+| **Docker**            | `DATA_DIR=/data` + mount a volume at `/data`.                                    |
+| **Encrypted at rest** | Set `STORAGE_ENCRYPTION_KEY` + keep backups of the key! Losing it = losing data. |
+| **CI/Testing**        | `DATA_DIR=/tmp/omniroute-test` — ephemeral, no encryption needed.                |
+
+---
+
+## 3. Network & Ports
+
+| Variable              | Default      | Source File                | Description                                                                            |
+| --------------------- | ------------ | -------------------------- | -------------------------------------------------------------------------------------- |
+| `PORT`                | `20128`      | `src/lib/runtime/ports.ts` | Primary port for both Dashboard UI and API endpoints (single-port mode).               |
+| `API_PORT`            | _(unset)_    | `src/lib/runtime/ports.ts` | When set, serves the `/v1/*` proxy API on this separate port.                          |
+| `API_HOST`            | `0.0.0.0`    | `src/lib/runtime/ports.ts` | Bind address for the API port.                                                         |
+| `DASHBOARD_PORT`      | _(unset)_    | `src/lib/runtime/ports.ts` | When set, serves the Dashboard UI on this separate port.                               |
+| `PROD_DASHBOARD_PORT` | `20130`      | `docker-compose.prod.yml`  | Host-side published port for the Dashboard in Docker production mode.                  |
+| `PROD_API_PORT`       | `20131`      | `docker-compose.prod.yml`  | Host-side published port for the API in Docker production mode.                        |
+| `OMNIROUTE_PORT`      | _(unset)_    | `src/lib/runtime/ports.ts` | Takes precedence over `PORT` when running inside Electron or other wrappers.           |
+| `NODE_ENV`            | `production` | Next.js core               | Controls logging verbosity, caching, error detail exposure, and Next.js optimizations. |
+
+### Port Modes
+
+```
+┌─────────────────────────── Single Port (default) ──────────────────────────┐
+│  PORT=20128                                                                 │
+│  → Dashboard: http://localhost:20128                                        │
+│  → API:       http://localhost:20128/v1/chat/completions                    │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────── Split Ports ─────────────────────────────────────┐
+│  DASHBOARD_PORT=20128                                                       │
+│  API_PORT=20129                                                             │
+│  API_HOST=0.0.0.0                                                           │
+│  → Dashboard: http://localhost:20128                                        │
+│  → API:       http://0.0.0.0:20129/v1/chat/completions                     │
+│  Use case: Expose API to LAN while restricting Dashboard to localhost.      │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────── Docker Production ──────────────────────────────┐
+│  PROD_DASHBOARD_PORT=443   PROD_API_PORT=8443                              │
+│  → Maps container ports to host ports in docker-compose.prod.yml.          │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 4. Security & Authentication
+
+| Variable                      | Default               | Source File                              | Description                                                                                               |
+| ----------------------------- | --------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `MACHINE_ID_SALT`             | `endpoint-proxy-salt` | `src/lib/auth`                           | Salt combined with hardware identifiers for machine fingerprinting. Change per-deployment for isolation.  |
+| `AUTH_COOKIE_SECURE`          | `false`               | `src/lib/auth`                           | Sets the `Secure` flag on session cookies. **Must be `true`** when running behind HTTPS.                  |
+| `REQUIRE_API_KEY`             | `false`               | API middleware                           | When `true`, all `/v1/*` proxy requests must include a valid API key.                                     |
+| `ALLOW_API_KEY_REVEAL`        | `false`               | Dashboard providers page                 | Allows revealing full API key values in the Dashboard UI. Security risk on shared instances.              |
+| `NO_LOG_API_KEY_IDS`          | _(empty)_             | `src/lib/compliance/index.ts`            | Comma-separated API key IDs that bypass request logging (GDPR compliance).                                |
+| `MAX_BODY_SIZE_BYTES`         | `10485760` (10 MB)    | `src/shared/middleware/bodySizeGuard.ts` | Maximum allowed request body size. Rejects payloads exceeding this limit.                                 |
+| `CORS_ORIGIN`                 | `*`                   | Next.js middleware                       | CORS `Access-Control-Allow-Origin` value. Restrict for production.                                        |
+| `OUTBOUND_SSRF_GUARD_ENABLED` | `true`                | `src/shared/network/outboundUrlGuard.ts` | Block provider calls targeting private/loopback/link-local IP ranges. Disable only in isolated test envs. |
+
+### Hardening Checklist
+
+```bash
+# Production security minimum:
+AUTH_COOKIE_SECURE=true        # Requires HTTPS
+REQUIRE_API_KEY=true           # Authenticate all proxy calls
+ALLOW_API_KEY_REVEAL=false     # Never expose keys in UI
+CORS_ORIGIN=https://your.domain.com
+MAX_BODY_SIZE_BYTES=5242880    # 5 MB limit
+```
+
+---
+
+## 5. Input Sanitization & PII Protection
+
+OmniRoute provides a two-layer defense: request-side injection scanning and response-side PII stripping.
+
+### Request-Side: Prompt Injection Guard
+
+| Variable                  | Default   | Source File                              | Description                                                                                 |
+| ------------------------- | --------- | ---------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `INPUT_SANITIZER_ENABLED` | `false`   | `src/middleware/promptInjectionGuard.ts` | Enable scanning of incoming messages for prompt injection patterns.                         |
+| `INPUT_SANITIZER_MODE`    | `warn`    | `src/middleware/promptInjectionGuard.ts` | `warn` = log only, `block` = reject request with 400, `redact` = strip suspicious patterns. |
+| `INJECTION_GUARD_MODE`    | _(unset)_ | `src/middleware/promptInjectionGuard.ts` | Legacy alias for `INPUT_SANITIZER_MODE` — same behavior.                                    |
+| `PII_REDACTION_ENABLED`   | `false`   | `src/middleware/promptInjectionGuard.ts` | Detect PII (emails, phones, SSNs) in incoming requests.                                     |
+
+### Response-Side: PII Sanitizer
+
+| Variable                         | Default  | Source File               | Description                                                             |
+| -------------------------------- | -------- | ------------------------- | ----------------------------------------------------------------------- |
+| `PII_RESPONSE_SANITIZATION`      | `false`  | `src/lib/piiSanitizer.ts` | Scan LLM responses for leaked PII before returning to client.           |
+| `PII_RESPONSE_SANITIZATION_MODE` | `redact` | `src/lib/piiSanitizer.ts` | `redact` = mask PII, `warn` = log only, `block` = drop entire response. |
+
+### Scenarios
+
+| Scenario                  | Configuration                                                                                                                |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| **Enterprise compliance** | `INPUT_SANITIZER_ENABLED=true`, `INPUT_SANITIZER_MODE=block`, `PII_REDACTION_ENABLED=true`, `PII_RESPONSE_SANITIZATION=true` |
+| **Monitoring only**       | `INPUT_SANITIZER_ENABLED=true`, `INPUT_SANITIZER_MODE=warn` — logs but never blocks                                          |
+| **Personal use**          | Leave all disabled — zero overhead                                                                                           |
+
+---
+
+## 6. Tool & Routing Policies
+
+| Variable           | Default    | Source File             | Description                                                                                                                               |
+| ------------------ | ---------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `TOOL_POLICY_MODE` | `disabled` | `src/lib/toolPolicy.ts` | Controls LLM tool/function-calling access. `allowlist` = only listed tools, `denylist` = all except listed, `disabled` = no restrictions. |
+
+---
+
+## 7. URLs & Cloud Sync
+
+| Variable                | Default                  | Source File                                 | Description                                                                                                     |
+| ----------------------- | ------------------------ | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `BASE_URL`              | `http://localhost:20128` | `src/lib/cloudSync.ts`                      | Server-side URL for internal sync jobs to call `/api/sync/cloud`.                                               |
+| `CLOUD_URL`             | _(empty)_                | `src/lib/cloudSync.ts`                      | Cloud relay endpoint URL (premium feature).                                                                     |
+| `CLOUD_SYNC_TIMEOUT_MS` | `12000`                  | `src/lib/cloudSync.ts`                      | HTTP timeout for cloud sync requests.                                                                           |
+| `NEXT_PUBLIC_BASE_URL`  | `http://localhost:20128` | OAuth, Dashboard, sync                      | Public-facing URL for OAuth redirect_uri, Dashboard links. **Must match your public URL behind reverse proxy.** |
+| `NEXT_PUBLIC_CLOUD_URL` | _(empty)_                | Client-side                                 | Client-side mirror of `CLOUD_URL`.                                                                              |
+| `NEXT_PUBLIC_APP_URL`   | _(unset)_                | `src/shared/services/cloudSyncScheduler.ts` | Legacy fallback for `NEXT_PUBLIC_BASE_URL`.                                                                     |
+
+> [!IMPORTANT]
+> When deploying behind a reverse proxy (nginx, Caddy), `NEXT_PUBLIC_BASE_URL` **must** be set to your public URL (e.g., `https://omniroute.example.com`). Without this, OAuth callbacks will fail because the redirect_uri won't match.
+
+---
+
+## 8. Outbound Proxy
+
+Route upstream LLM provider calls through an HTTP or SOCKS5 proxy for egress control, geo-routing, or IP masking.
+
+| Variable                          | Default   | Source File          | Description                                                                         |
+| --------------------------------- | --------- | -------------------- | ----------------------------------------------------------------------------------- |
+| `ENABLE_SOCKS5_PROXY`             | `true`    | `open-sse/executors` | Enable SOCKS5 proxy agent for upstream calls.                                       |
+| `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` | `true`    | Client-side          | Client-side awareness of SOCKS5 availability.                                       |
+| `HTTP_PROXY`                      | _(unset)_ | Node.js standard     | HTTP proxy for upstream calls.                                                      |
+| `HTTPS_PROXY`                     | _(unset)_ | Node.js standard     | HTTPS proxy for upstream calls.                                                     |
+| `ALL_PROXY`                       | _(unset)_ | Node.js standard     | Universal proxy (supports `socks5://`).                                             |
+| `NO_PROXY`                        | _(unset)_ | Node.js standard     | Comma-separated hostnames/IPs to bypass the proxy.                                  |
+| `ENABLE_TLS_FINGERPRINT`          | `false`   | `open-sse/executors` | Spoof TLS fingerprint using wreq-js (mimics Chrome 124). Counters JA3/JA4 blocking. |
+
+### Scenarios
+
+| Scenario                      | Configuration                                                                                                             |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| **SOCKS5 through SSH tunnel** | `ALL_PROXY=socks5://127.0.0.1:7890`, `ENABLE_SOCKS5_PROXY=true`                                                           |
+| **Corporate HTTP proxy**      | `HTTP_PROXY=http://proxy.corp.com:3128`, `HTTPS_PROXY=http://proxy.corp.com:3128`, `NO_PROXY=localhost,internal.corp.com` |
+| **Anti-fingerprint**          | `ENABLE_TLS_FINGERPRINT=true` — requires `wreq-js` (included)                                                             |
+
+---
+
+## 9. CLI Tool Integration
+
+Controls how OmniRoute discovers and launches CLI sidecars (Claude Code, Codex, etc.).
+
+| Variable                  | Default    | Source File                         | Description                                                                |
+| ------------------------- | ---------- | ----------------------------------- | -------------------------------------------------------------------------- |
+| `CLI_MODE`                | `auto`     | `src/shared/services/cliRuntime.ts` | `auto` = search system PATH; `manual` = use explicit paths only.           |
+| `CLI_EXTRA_PATHS`         | _(unset)_  | `src/shared/services/cliRuntime.ts` | Additional PATH entries for CLI binary discovery (colon-separated).        |
+| `CLI_CONFIG_HOME`         | _(unset)_  | `src/shared/services/cliRuntime.ts` | Override home directory for reading CLI configs (`~/.claude`, `~/.codex`). |
+| `CLI_ALLOW_CONFIG_WRITES` | `false`    | `src/shared/services/cliRuntime.ts` | Allow OmniRoute to write CLI config files (token refresh, session data).   |
+| `CLI_CLAUDE_BIN`          | `claude`   | `src/shared/services/cliRuntime.ts` | Custom path to Claude CLI binary.                                          |
+| `CLI_CODEX_BIN`           | `codex`    | `src/shared/services/cliRuntime.ts` | Custom path to Codex CLI binary.                                           |
+| `CLI_DROID_BIN`           | `droid`    | `src/shared/services/cliRuntime.ts` | Custom path to Droid CLI binary.                                           |
+| `CLI_OPENCLAW_BIN`        | `openclaw` | `src/shared/services/cliRuntime.ts` | Custom path to OpenClaw CLI binary.                                        |
+| `CLI_CURSOR_BIN`          | `agent`    | `src/shared/services/cliRuntime.ts` | Custom path to Cursor agent binary.                                        |
+| `CLI_CLINE_BIN`           | `cline`    | `src/shared/services/cliRuntime.ts` | Custom path to Cline CLI binary.                                           |
+| `CLI_CONTINUE_BIN`        | `cn`       | `src/shared/services/cliRuntime.ts` | Custom path to Continue CLI binary.                                        |
+| `CLI_QODER_BIN`           | `qoder`    | `src/shared/services/cliRuntime.ts` | Custom path to Qoder CLI binary.                                           |
+
+### Docker Example
+
+```bash
+# Mount host binaries into the container and tell OmniRoute where they are:
+CLI_EXTRA_PATHS=/host-cli/bin
+CLI_CONFIG_HOME=/root
+CLI_ALLOW_CONFIG_WRITES=true
+CLI_CLAUDE_BIN=/host-cli/bin/claude
+```
+
+---
+
+## 10. Internal Agent & MCP Integrations
+
+| Variable                                | Default     | Source File                                 | Description                                                                                                                   |
+| --------------------------------------- | ----------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `OMNIROUTE_BASE_URL`                    | auto-detect | `open-sse/mcp-server/server.ts`             | Explicit URL for MCP/A2A tools to reach OmniRoute. Overrides localhost auto-detection.                                        |
+| `OMNIROUTE_API_KEY`                     | _(unset)_   | MCP/A2A modules                             | API key for internal MCP tool and A2A skill calls.                                                                            |
+| `OMNIROUTE_API_KEY_ID`                  | _(unset)_   | `open-sse/mcp-server/audit.ts`              | Key ID for MCP audit log attribution.                                                                                         |
+| `ROUTER_API_KEY`                        | _(unset)_   | Legacy                                      | Legacy alias for `OMNIROUTE_API_KEY`.                                                                                         |
+| `OMNIROUTE_MCP_ENFORCE_SCOPES`          | `false`     | `open-sse/mcp-server/server.ts`             | Enforce scope-based access control on MCP tool calls.                                                                         |
+| `OMNIROUTE_MCP_SCOPES`                  | _(all)_     | `open-sse/mcp-server/server.ts`             | Comma-separated scopes: `admin`, `combos`, `health`, `models`, `routing`, `budget`, `metrics`, `pricing`, `memory`, `skills`. |
+| `MODEL_SYNC_INTERVAL_HOURS`             | `24`        | `src/shared/services/modelSyncScheduler.ts` | Model catalog sync interval in hours.                                                                                         |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70`        | `src/server-init.ts`                        | Provider rate-limit and quota polling interval.                                                                               |
+| `OMNIROUTE_DISABLE_BACKGROUND_SERVICES` | `false`     | `src/instrumentation-node.ts`               | Disable all background services (sync, pricing, model refresh). Useful for CI/test.                                           |
+| `OMNIROUTE_BOOTSTRAPPED`                | `false`     | `src/app/(dashboard)/dashboard/page.tsx`    | Set `true` by bootstrap script after initial setup. Controls setup wizard visibility.                                         |
+| `OMNIROUTE_ALLOW_BODY_PROJECT_OVERRIDE` | `0`         | `open-sse/executors/antigravity.ts`         | Escape hatch: allow request body to override the Antigravity project field.                                                   |
+
+### OAuth CLI Bridge (Internal)
+
+| Variable            | Default     | Source File                     | Description                               |
+| ------------------- | ----------- | ------------------------------- | ----------------------------------------- |
+| `OMNIROUTE_SERVER`  | auto-detect | `src/lib/oauth/config/index.ts` | Server URL for CLI↔OmniRoute auth bridge. |
+| `OMNIROUTE_TOKEN`   | _(unset)_   | `src/lib/oauth/config/index.ts` | Auth token for CLI bridge.                |
+| `OMNIROUTE_USER_ID` | `cli`       | `src/lib/oauth/config/index.ts` | User ID for CLI bridge sessions.          |
+| `SERVER_URL`        | _(unset)_   | `src/lib/oauth/config/index.ts` | Legacy alias for `OMNIROUTE_SERVER`.      |
+| `CLI_TOKEN`         | _(unset)_   | `src/lib/oauth/config/index.ts` | Legacy alias for `OMNIROUTE_TOKEN`.       |
+| `CLI_USER_ID`       | _(unset)_   | `src/lib/oauth/config/index.ts` | Legacy alias for `OMNIROUTE_USER_ID`.     |
+
+---
+
+## 11. OAuth Provider Credentials
+
+Built-in credentials for **localhost development**. For remote deployments, register your own at each provider's developer console.
+
+| Variable                          | Provider                | Notes                                                                             |
+| --------------------------------- | ----------------------- | --------------------------------------------------------------------------------- |
+| `CLAUDE_OAUTH_CLIENT_ID`          | Claude Code (Anthropic) | Public client — no secret needed.                                                 |
+| `CLAUDE_CODE_REDIRECT_URI`        | Claude Code             | Override redirect URI. Default: `https://platform.claude.com/oauth/code/callback` |
+| `CODEX_OAUTH_CLIENT_ID`           | Codex / OpenAI          | Public client.                                                                    |
+| `GEMINI_OAUTH_CLIENT_ID`          | Gemini (Google)         | Requires matching `_SECRET`.                                                      |
+| `GEMINI_OAUTH_CLIENT_SECRET`      | Gemini (Google)         | —                                                                                 |
+| `GEMINI_CLI_OAUTH_CLIENT_ID`      | Gemini CLI              | Usually same as Gemini.                                                           |
+| `GEMINI_CLI_OAUTH_CLIENT_SECRET`  | Gemini CLI              | —                                                                                 |
+| `QWEN_OAUTH_CLIENT_ID`            | Qwen (Alibaba)          | Public client.                                                                    |
+| `KIMI_CODING_OAUTH_CLIENT_ID`     | Kimi Coding (Moonshot)  | Public client.                                                                    |
+| `ANTIGRAVITY_OAUTH_CLIENT_ID`     | Antigravity (Google)    | Requires matching `_SECRET`.                                                      |
+| `ANTIGRAVITY_OAUTH_CLIENT_SECRET` | Antigravity (Google)    | —                                                                                 |
+| `GITHUB_OAUTH_CLIENT_ID`          | GitHub Copilot          | Public client.                                                                    |
+| `QODER_OAUTH_CLIENT_SECRET`       | Qoder                   | —                                                                                 |
+| `QODER_OAUTH_AUTHORIZE_URL`       | Qoder                   | Set to enable Qoder OAuth.                                                        |
+| `QODER_OAUTH_TOKEN_URL`           | Qoder                   | —                                                                                 |
+| `QODER_OAUTH_USERINFO_URL`        | Qoder                   | —                                                                                 |
+| `QODER_OAUTH_CLIENT_ID`           | Qoder                   | —                                                                                 |
+| `QODER_PERSONAL_ACCESS_TOKEN`     | Qoder                   | Direct API key fallback (bypasses OAuth).                                         |
+| `QODER_CLI_WORKSPACE`             | Qoder                   | Workspace ID for Qoder CLI.                                                       |
+| `OMNIROUTE_QODER_WORKSPACE`       | Qoder                   | Alias for `QODER_CLI_WORKSPACE`.                                                  |
+
+> [!WARNING]
+> **Google OAuth** (Antigravity, Gemini CLI) credentials **only work on localhost**. For remote servers:
+>
+> 1. Go to [Google Cloud Console → Credentials](https://console.cloud.google.com/apis/credentials)
+> 2. Create an OAuth 2.0 Client ID (type: "Web application")
+> 3. Add your server URL as Authorized redirect URI
+> 4. Replace the credential values in `.env`.
+
+---
+
+## 12. Provider User-Agent Overrides
+
+Override the `User-Agent` header sent to each upstream provider. This is dynamically resolved at runtime by the executor base class:
+
+```
+process.env[`${PROVIDER_ID}_USER_AGENT`]
+```
+
+> **Source:** `open-sse/executors/base.ts` → `buildHeaders()`
+
+| Variable                 | Default Value                                 | When to Update                                                |
+| ------------------------ | --------------------------------------------- | ------------------------------------------------------------- |
+| `CLAUDE_USER_AGENT`      | `claude-cli/2.1.121 (external, cli)`          | When Anthropic releases a new CLI version                     |
+| `CODEX_USER_AGENT`       | `codex-cli/0.125.0 (Windows 10.0.26100; x64)` | When OpenAI updates the Codex CLI                             |
+| `CODEX_CLIENT_VERSION`   | `0.125.0`                                     | Override Codex client version independently of full UA string |
+| `GITHUB_USER_AGENT`      | `GitHubCopilotChat/0.45.1`                    | When GitHub Copilot Chat updates                              |
+| `ANTIGRAVITY_USER_AGENT` | `antigravity/1.107.0 darwin/arm64`            | When Antigravity IDE updates                                  |
+| `KIRO_USER_AGENT`        | `AWS-SDK-JS/3.0.0 kiro-ide/1.0.0`             | When Kiro IDE updates                                         |
+| `QODER_USER_AGENT`       | `Qoder-Cli`                                   | When Qoder CLI updates                                        |
+| `QWEN_USER_AGENT`        | `QwenCode/0.15.3 (linux; x64)`                | When Qwen Code updates                                        |
+| `CURSOR_USER_AGENT`      | `connect-es/1.6.1`                            | When Cursor updates                                           |
+| `GEMINI_CLI_USER_AGENT`  | `google-api-nodejs-client/10.3.0`             | When Google API client updates                                |
+
+> [!TIP]
+> You can add User-Agent overrides for **any** provider using the pattern `{PROVIDER_ID}_USER_AGENT`. The executor dynamically constructs the env var name.
+
+---
+
+## 13. CLI Fingerprint Compatibility
+
+When enabled, OmniRoute reorders HTTP headers and JSON body fields to match the exact signature of official CLI tools. This reduces the risk of account flagging while preserving your proxy IP.
+
+**Source:** `open-sse/config/cliFingerprints.ts`, `open-sse/executors/base.ts`
+
+### Per-Provider
+
+| Variable                   | Effect                                  |
+| -------------------------- | --------------------------------------- |
+| `CLI_COMPAT_CODEX=1`       | Mimics Codex CLI request signature      |
+| `CLI_COMPAT_CLAUDE=1`      | Mimics Claude Code request signature    |
+| `CLI_COMPAT_GITHUB=1`      | Mimics GitHub Copilot request signature |
+| `CLI_COMPAT_ANTIGRAVITY=1` | Mimics Antigravity request signature    |
+| `CLI_COMPAT_KIRO=1`        | Mimics Kiro IDE request signature       |
+| `CLI_COMPAT_CURSOR=1`      | Mimics Cursor request signature         |
+| `CLI_COMPAT_KIMI_CODING=1` | Mimics Kimi Coding request signature    |
+| `CLI_COMPAT_KILOCODE=1`    | Mimics Kilo Code request signature      |
+| `CLI_COMPAT_CLINE=1`       | Mimics Cline request signature          |
+| `CLI_COMPAT_QWEN=1`        | Mimics Qwen Code request signature      |
+
+### Global
+
+| Variable           | Effect                                                          |
+| ------------------ | --------------------------------------------------------------- |
+| `CLI_COMPAT_ALL=1` | Enable fingerprint compatibility for **all** providers at once. |
+
+> [!NOTE]
+> This feature works alongside the User-Agent overrides (§12). The fingerprint system handles header ordering and body field ordering, while User-Agent overrides handle the specific UA string. Both can be enabled independently.
+
+---
+
+## 14. API Key Providers
+
+API keys for providers that use direct authentication. **Preferred setup:** Dashboard → Providers → Add API Key.
+
+Setting via environment variables is an alternative for Docker or headless deployments.
+
+Recognized pattern: `{PROVIDER_ID}_API_KEY`
+
+| Variable             | Provider            |
+| -------------------- | ------------------- |
+| `DEEPSEEK_API_KEY`   | DeepSeek            |
+| `GROQ_API_KEY`       | Groq                |
+| `XAI_API_KEY`        | xAI (Grok)          |
+| `MISTRAL_API_KEY`    | Mistral AI          |
+| `PERPLEXITY_API_KEY` | Perplexity          |
+| `TOGETHER_API_KEY`   | Together AI         |
+| `FIREWORKS_API_KEY`  | Fireworks AI        |
+| `CEREBRAS_API_KEY`   | Cerebras            |
+| `COHERE_API_KEY`     | Cohere              |
+| `NVIDIA_API_KEY`     | NVIDIA NIM          |
+| `NEBIUS_API_KEY`     | Nebius (embeddings) |
+
+> [!TIP]
+> Keys set via the Dashboard are stored encrypted in SQLite and take precedence over environment variables.
+
+---
+
+## 15. Timeout Settings
+
+All values are in **milliseconds**. Centralized resolution in `src/shared/utils/runtimeTimeouts.ts`.
+
+### Timeout Hierarchy
+
+```
+REQUEST_TIMEOUT_MS (global override)
+├─→ FETCH_TIMEOUT_MS (upstream provider calls, default: 600000)
+│   ├─→ FETCH_HEADERS_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS)
+│   ├─→ FETCH_BODY_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS)
+│   ├─→ TLS_CLIENT_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS)
+│   ├── FETCH_CONNECT_TIMEOUT_MS (independent, default: 30000)
+│   └── FETCH_KEEPALIVE_TIMEOUT_MS (independent, default: 4000)
+├─→ STREAM_IDLE_TIMEOUT_MS (inherits from REQUEST_TIMEOUT_MS, default: 600000)
+└─→ API_BRIDGE_PROXY_TIMEOUT_MS (inherits from REQUEST_TIMEOUT_MS, default: 30000)
+    ├─→ API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS (derived, default: 300000)
+    ├── API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS (default: 60000)
+    ├── API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS (default: 5000)
+    └── API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS (default: 0 = disabled)
+```
+
+| Variable                                 | Default              | Description                                                                                 |
+| ---------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------- |
+| `REQUEST_TIMEOUT_MS`                     | _(unset)_            | Global shortcut — overrides both `FETCH_TIMEOUT_MS` and `STREAM_IDLE_TIMEOUT_MS` defaults.  |
+| `FETCH_TIMEOUT_MS`                       | `600000`             | Total HTTP request timeout for upstream provider calls.                                     |
+| `STREAM_IDLE_TIMEOUT_MS`                 | `600000`             | Max silence between SSE chunks before aborting. Extended-thinking models rarely pause >90s. |
+| `FETCH_HEADERS_TIMEOUT_MS`               | = `FETCH_TIMEOUT_MS` | Time to receive response headers.                                                           |
+| `FETCH_BODY_TIMEOUT_MS`                  | = `FETCH_TIMEOUT_MS` | Time to receive the full response body.                                                     |
+| `FETCH_CONNECT_TIMEOUT_MS`               | `30000`              | TCP connection establishment timeout.                                                       |
+| `FETCH_KEEPALIVE_TIMEOUT_MS`             | `4000`               | Keep-alive socket idle timeout.                                                             |
+| `TLS_CLIENT_TIMEOUT_MS`                  | = `FETCH_TIMEOUT_MS` | TLS fingerprint proxy (wreq-js) timeout.                                                    |
+| `API_BRIDGE_PROXY_TIMEOUT_MS`            | `30000`              | Proxy hop timeout for `/v1` bridge requests.                                                |
+| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS`   | `300000`             | Overall server request timeout for the bridge.                                              |
+| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS`   | `60000`              | Time to send response headers via the bridge.                                               |
+| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000`               | Bridge keep-alive idle timeout.                                                             |
+| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS`    | `0`                  | Raw socket timeout (0 = disabled).                                                          |
+| `SHUTDOWN_TIMEOUT_MS`                    | `30000`              | Grace period on SIGTERM/SIGINT before force-exit.                                           |
+
+### Scenarios
+
+| Scenario                         | Configuration                                          |
+| -------------------------------- | ------------------------------------------------------ |
+| **Long-running code generation** | `REQUEST_TIMEOUT_MS=900000` (15 min)                   |
+| **Fast-fail for production API** | `API_BRIDGE_PROXY_TIMEOUT_MS=10000`                    |
+| **Extended thinking models**     | `STREAM_IDLE_TIMEOUT_MS=300000` (5 min between chunks) |
+
+---
+
+## 16. Logging
+
+The logging system writes to both stdout and rotated log files. All configuration is read by `src/lib/logEnv.ts`.
+
+| Variable                    | Default                    | Description                                                                  |
+| --------------------------- | -------------------------- | ---------------------------------------------------------------------------- |
+| `APP_LOG_LEVEL`             | `info`                     | Minimum log level: `debug`, `info`, `warn`, `error`.                         |
+| `APP_LOG_FORMAT`            | `text`                     | Output format: `text` (human-readable) or `json` (structured).               |
+| `APP_LOG_TO_FILE`           | `true`                     | Write logs to file alongside stdout.                                         |
+| `APP_LOG_FILE_PATH`         | `logs/application/app.log` | Log file path (relative to project root or `DATA_DIR`).                      |
+| `APP_LOG_MAX_FILE_SIZE`     | `50M`                      | Max file size before rotation. Accepts: `50M`, `1G`, `512K`, or plain bytes. |
+| `APP_LOG_RETENTION_DAYS`    | `7`                        | Days to keep rotated application log files.                                  |
+| `APP_LOG_MAX_FILES`         | `20`                       | Maximum rotated log file backups.                                            |
+| `CALL_LOG_RETENTION_DAYS`   | `7`                        | Days to keep request/call log entries in the database.                       |
+| `CALL_LOG_MAX_ENTRIES`      | `10000`                    | Max call log entries in the in-memory buffer.                                |
+| `CALL_LOGS_TABLE_MAX_ROWS`  | `100000`                   | Max rows in the `call_logs` SQLite table before pruning.                     |
+| `PROXY_LOGS_TABLE_MAX_ROWS` | `100000`                   | Max rows in the `proxy_logs` SQLite table before pruning.                    |
+
+---
+
+## 17. Memory Optimization
+
+| Variable                   | Default                         | Description                                                            |
+| -------------------------- | ------------------------------- | ---------------------------------------------------------------------- |
+| `OMNIROUTE_MEMORY_MB`      | `256` (Docker) / system default | V8 heap limit. Sets `--max-old-space-size`.                            |
+| `PROMPT_CACHE_MAX_SIZE`    | `50`                            | Max cached system prompt entries.                                      |
+| `PROMPT_CACHE_MAX_BYTES`   | `2097152` (2 MB)                | Max total prompt cache size.                                           |
+| `PROMPT_CACHE_TTL_MS`      | `300000` (5 min)                | Prompt cache entry TTL.                                                |
+| `SEMANTIC_CACHE_MAX_SIZE`  | `100`                           | Max cached temperature=0 responses.                                    |
+| `SEMANTIC_CACHE_MAX_BYTES` | `4194304` (4 MB)                | Max total semantic cache size.                                         |
+| `SEMANTIC_CACHE_TTL_MS`    | `1800000` (30 min)              | Semantic cache entry TTL.                                              |
+| `STREAM_HISTORY_MAX`       | `50`                            | Max recent stream events in the Dashboard live view buffer.            |
+| `CONTEXT_LENGTH_DEFAULT`   | `128000`                        | Global fallback max context length for models without explicit config. |
+| `USAGE_TOKEN_BUFFER`       | `100`                           | Extra token headroom reserved when tracking usage quotas.              |
+
+### Low-RAM Docker Example
+
+```bash
+OMNIROUTE_MEMORY_MB=128
+PROMPT_CACHE_MAX_SIZE=20
+PROMPT_CACHE_MAX_BYTES=524288        # 512 KB
+SEMANTIC_CACHE_MAX_SIZE=25
+SEMANTIC_CACHE_MAX_BYTES=1048576     # 1 MB
+STREAM_HISTORY_MAX=10
+```
+
+---
+
+## 18. Pricing Sync
+
+Automatic model pricing data synchronization from external sources.
+
+| Variable                | Default       | Source File              | Description                   |
+| ----------------------- | ------------- | ------------------------ | ----------------------------- |
+| `PRICING_SYNC_ENABLED`  | `false`       | `src/lib/pricingSync.ts` | Opt-in periodic pricing sync. |
+| `PRICING_SYNC_INTERVAL` | `86400` (24h) | `src/lib/pricingSync.ts` | Sync interval in seconds.     |
+| `PRICING_SYNC_SOURCES`  | `litellm`     | `src/lib/pricingSync.ts` | Comma-separated data sources. |
+
+---
+
+## 19. Model Sync (Dev)
+
+| Variable                   | Default       | Source File                | Description                                              |
+| -------------------------- | ------------- | -------------------------- | -------------------------------------------------------- |
+| `MODELS_DEV_SYNC_INTERVAL` | `86400` (24h) | `src/lib/modelsDevSync.ts` | Development-time model catalog sync interval in seconds. |
+
+---
+
+## 20. Provider-Specific Settings
+
+| Variable                                  | Default            | Source File                                | Description                                                                           |
+| ----------------------------------------- | ------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------- |
+| `OPENROUTER_CATALOG_TTL_MS`               | `86400000` (24h)   | `src/lib/catalog/openrouterCatalog.ts`     | OpenRouter model catalog cache TTL.                                                   |
+| `NANOBANANA_POLL_TIMEOUT_MS`              | `120000`           | `open-sse/handlers/imageGeneration.ts`     | Max wait for NanoBanana image generation jobs.                                        |
+| `NANOBANANA_POLL_INTERVAL_MS`             | `2500`             | `open-sse/handlers/imageGeneration.ts`     | NanoBanana job polling frequency.                                                     |
+| `CLOUDFLARE_ACCOUNT_ID`                   | _(unset)_          | `open-sse/executors/cloudflare-ai.ts`      | Account ID for Cloudflare Workers AI.                                                 |
+| `CLOUDFLARED_BIN`                         | auto-detect        | `src/lib/cloudflaredTunnel.ts`             | Custom path to `cloudflared` binary.                                                  |
+| `SEARCH_CACHE_TTL_MS`                     | `300000` (5 min)   | `open-sse/services/searchCache.ts`         | TTL for search API (Perplexity, Brave, etc.) response caching.                        |
+| `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` | `false`            | `src/app/api/providers/route.ts`           | Allow multiple simultaneous connections per OpenAI-compatible provider.               |
+| `ENABLE_CC_COMPATIBLE_PROVIDER`           | `false`            | `src/shared/utils/featureFlags.ts`         | Enable experimental Claude Code compatible provider endpoint.                         |
+| `CLIPROXYAPI_HOST`                        | `127.0.0.1`        | `open-sse/executors/cliproxyapi.ts`        | CLIProxyAPI bridge host (legacy integration).                                         |
+| `CLIPROXYAPI_PORT`                        | `5544`             | `open-sse/executors/cliproxyapi.ts`        | CLIProxyAPI bridge port.                                                              |
+| `CLIPROXYAPI_CONFIG_DIR`                  | `~/.cli-proxy-api` | `src/lib/versionManager/processManager.ts` | CLIProxyAPI config directory.                                                         |
+| `LOCAL_HOSTNAMES`                         | _(empty)_          | `open-sse/config/providerRegistry.ts`      | Comma-separated additional hostnames treated as "local" (Docker service names, etc.). |
+
+---
+
+## 21. Proxy Health
+
+| Variable                     | Default          | Source File                              | Description                                                                                                         |
+| ---------------------------- | ---------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `PROXY_FAST_FAIL_TIMEOUT_MS` | `2000`           | `src/lib/proxyHealth.ts`                 | Fast-fail health check timeout.                                                                                     |
+| `PROXY_HEALTH_CACHE_TTL_MS`  | `30000`          | `src/lib/proxyHealth.ts`                 | Health check result cache TTL.                                                                                      |
+| `RATE_LIMIT_MAX_WAIT_MS`     | `120000` (2 min) | `open-sse/services/rateLimitManager.ts`  | Max time to wait on a 429 before failing the request.                                                               |
+| `REQUEST_RETRY`              | `2`              | `src/sse/services/cooldownAwareRetry.ts` | Number of automatic retries on model-scoped cooldown responses before returning error to client.                    |
+| `MAX_RETRY_INTERVAL_SEC`     | `30`             | `src/sse/services/cooldownAwareRetry.ts` | Max backoff interval (seconds) between cooldown retries. Capped by this value regardless of upstream `Retry-After`. |
+
+---
+
+## 22. Debugging
+
+> [!CAUTION]
+> These variables produce **verbose output** and may leak sensitive data. **Never enable in production.**
+
+| Variable                         | Default   | Source File                               | Description                                                    |
+| -------------------------------- | --------- | ----------------------------------------- | -------------------------------------------------------------- |
+| `CURSOR_PROTOBUF_DEBUG`          | _(unset)_ | `open-sse/utils/cursorProtobuf.ts`        | Set `1` to dump Cursor protobuf decode/encode details.         |
+| `CURSOR_STREAM_DEBUG`            | _(unset)_ | `open-sse/executors/cursor.ts`            | Set `1` to dump raw Cursor SSE stream data.                    |
+| `DEBUG_RESPONSES_SSE_TO_JSON`    | _(unset)_ | `open-sse/handlers/responseTranslator.ts` | Set `true` to log Responses API SSE→JSON translation details.  |
+| `NEXT_PUBLIC_OMNIROUTE_E2E_MODE` | _(unset)_ | E2E test harness                          | Set `true` to enable E2E test mode (relaxed auth, test hooks). |
+
+---
+
+## 23. GitHub Integration
+
+Allow users to report issues directly from the Dashboard.
+
+| Variable              | Default   | Source File                             | Description                                             |
+| --------------------- | --------- | --------------------------------------- | ------------------------------------------------------- |
+| `GITHUB_ISSUES_REPO`  | _(unset)_ | `src/app/api/v1/issues/report/route.ts` | Repository in `owner/repo` format.                      |
+| `GITHUB_ISSUES_TOKEN` | _(unset)_ | `src/app/api/v1/issues/report/route.ts` | GitHub Personal Access Token with `issues:write` scope. |
+
+---
+
+## Deployment Scenarios
+
+### Minimal Local Development
+
+```bash
+JWT_SECRET=$(openssl rand -base64 48)
+API_KEY_SECRET=$(openssl rand -hex 32)
+INITIAL_PASSWORD=dev123
+PORT=20128
+NODE_ENV=development
+```
+
+### Docker Production
+
+```bash
+JWT_SECRET=<generated>
+API_KEY_SECRET=<generated>
+INITIAL_PASSWORD=<generated>
+STORAGE_ENCRYPTION_KEY=<generated>
+DATA_DIR=/data
+PORT=20128
+API_PORT=20129
+NODE_ENV=production
+AUTH_COOKIE_SECURE=true
+REQUIRE_API_KEY=true
+NEXT_PUBLIC_BASE_URL=https://omniroute.example.com
+BASE_URL=http://localhost:20128
+OMNIROUTE_MEMORY_MB=512
+CORS_ORIGIN=https://your-frontend.example.com
+```
+
+### Air-Gapped / CI
+
+```bash
+JWT_SECRET=test-jwt-secret-for-ci
+API_KEY_SECRET=test-api-key-secret-for-ci
+INITIAL_PASSWORD=testpass
+NODE_ENV=production
+OMNIROUTE_DISABLE_BACKGROUND_SERVICES=true
+APP_LOG_TO_FILE=false
+```
+
+### VPS with Reverse Proxy (nginx + Cloudflare)
+
+```bash
+JWT_SECRET=<generated>
+API_KEY_SECRET=<generated>
+STORAGE_ENCRYPTION_KEY=<generated>
+PORT=20128
+AUTH_COOKIE_SECURE=true
+REQUIRE_API_KEY=true
+NEXT_PUBLIC_BASE_URL=https://omniroute.example.com
+BASE_URL=http://127.0.0.1:20128
+CORS_ORIGIN=https://omniroute.example.com
+ENABLE_TLS_FINGERPRINT=true
+CLI_COMPAT_ALL=1
+```
+
+---
+
+## Audit: Removed / Dead Variables
+
+The following variables appeared in previous versions of `.env.example` but have **no runtime references** in the current codebase. They have been removed:
+
+| Variable                                              | Reason                                                                                                  |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `STORAGE_DRIVER=sqlite`                               | Never read by any source file. SQLite is the only supported driver — no selection needed.               |
+| `INSTANCE_NAME=omniroute`                             | Present in old docs/env templates but unused at runtime. May return in a future multi-instance feature. |
+| `SQLITE_MAX_SIZE_MB=2048`                             | Not referenced in source code. Database size is not artificially limited.                               |
+| `SQLITE_CLEAN_LEGACY_FILES=true`                      | Not referenced in source code. Legacy cleanup was likely removed.                                       |
+| `CLI_ROO_BIN`                                         | Not registered in `src/shared/services/cliRuntime.ts`.                                                  |
+| `CLI_KIMI_CODING_BIN`                                 | Not registered in `src/shared/services/cliRuntime.ts` (Kimi Coding uses OAuth, not a CLI binary).       |
+| `IFLOW_OAUTH_CLIENT_ID` / `IFLOW_OAUTH_CLIENT_SECRET` | Not referenced anywhere in source code.                                                                 |
+
+### Default Value Corrections
+
+| Variable                  | Old `.env.example` Value | Actual Code Default | Fixed                                                  |
+| ------------------------- | ------------------------ | ------------------- | ------------------------------------------------------ |
+| `APP_LOG_RETENTION_DAYS`  | `90`                     | `7`                 | ✅ Removed misleading value; documented `7` as default |
+| `CALL_LOG_RETENTION_DAYS` | `90`                     | `7`                 | ✅ Removed misleading value; documented `7` as default |

docs/i18n/ar/docs/FEATURES.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇧🇩 [bn](../../bn/docs/FEATURES.md) · 🇨🇿 [cs](../../cs/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇮🇷 [fa](../../fa/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇮🇳 [gu](../../gu/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇮🇳 [hi](../../hi/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇮🇳 [mr](../../mr/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇰🇪 [sw](../../sw/docs/FEATURES.md) · 🇮🇳 [ta](../../ta/docs/FEATURES.md) · 🇮🇳 [te](../../te/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇹🇷 [tr](../../tr/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇵🇰 [ur](../../ur/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md)
 
 ---
 
@@ -18,7 +18,14 @@ Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI)
 
 ## 🎨 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.
+Create model routing combos with 13 strategies: priority, weighted, round-robin, random, least-used, cost-optimized, strict-random, auto, fill-first, p2c, lkgp, context-optimized, and **context-relay**. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+Recent combo improvements:
+
+- **Structured combo builder** — create each step by selecting provider, model, and exact account/connection
+- **Repeated provider support** — reuse the same provider many times in one combo as long as the `(provider, model, connection)` tuple is unique
+- **Combo target health** — analytics and health surfaces now distinguish individual combo targets/steps instead of collapsing everything into model strings
+- **Composite tier ordering** — `defaultTier -> fallbackTier` now influences runtime execution/fallback order for top-level combo steps
 
 ![Combos Dashboard](screenshots/02-combos.png)
 
@@ -34,7 +41,7 @@ Comprehensive usage analytics with token consumption, cost estimates, activity h
 
 ## 🏥 System Health
 
-Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, provider circuit breaker states, active quota-monitored sessions, and combo target health.
 
 ![Health Dashboard](screenshots/04-health.png)
 
@@ -68,7 +75,7 @@ Comprehensive settings panel with tabs:
 - **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
 - **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
 - **Routing** — Model aliases, background task degradation
-- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring
+- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring, **Context Relay** handoff threshold and summary model configuration
 - **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
 
 ![Settings Dashboard](screenshots/06-settings.png)
@@ -94,6 +101,68 @@ Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in a
 
 ---
 
+## 🔗 Context Relay _(v3.5.5+)_
+
+A combo strategy that preserves session continuity when account rotation happens mid-conversation. Before the active account is exhausted, OmniRoute generates a structured handoff summary in the background. After the next request resolves to a different account, the summary is injected as a system message so the new account continues with full context.
+
+Configurable via combo-level or global settings:
+
+- **Handoff Threshold** — Quota usage percentage that triggers summary generation (default 85%)
+- **Max Messages For Summary** — How much recent history to condense
+- **Summary Model** — Optional override model for generating the handoff summary
+
+Currently supports Codex account rotation. See [Context Relay documentation](features/context-relay.md).
+
+---
+
+## 🛡️ Proxy Hardening _(v3.5.5+)_
+
+Comprehensive proxy configuration enforcement across the entire request pipeline:
+
+- **Token Health Check** — Background OAuth refresh now resolves proxy config per connection, preventing failures in proxy-required environments
+- **API Key Validation** — Provider key validation (`POST /api/providers/validate`) routes through `runWithProxyContext`, honoring provider-level and global proxy settings
+- **undici Dispatcher Fix** — Proxy dispatchers use undici's own fetch implementation instead of Node's built-in fetch, resolving `invalid onRequestStart method` errors on Node.js 22
+- **Node.js Version Detection** — Login page proactively detects incompatible Node.js versions (24+) and displays a warning banner with instructions to use Node 22 LTS
+
+---
+
+## 📧 Email Privacy Masking _(v3.5.6+)_
+
+OAuth account emails are now masked in the provider dashboard (e.g. `di*****@g****.com`) to prevent accidental exposure when sharing screenshots or recording demos. The full email address remains accessible via hover tooltip (`title` attribute).
+
+---
+
+## 👁️ Model Visibility Toggle _(v3.5.6+)_
+
+The provider page model list now includes:
+
+- **Real-time search/filter bar** — Quickly find specific models
+- **Per-model visibility toggle** (👁 icon) — Hidden models are grayed out and excluded from the `/v1/models` catalog
+- **Active-count badge** (`N/M active`) — Shows at a glance how many models are enabled vs total
+
+---
+
+## 🔧 OAuth Env Repair _(v3.6.1+)_
+
+One-click "Repair env" action for OAuth providers that restores missing environment variables and fixes broken auth state. Accessible from `Dashboard → Providers → [OAuth Provider] → Repair env`. Automatically detects and repairs:
+
+- Missing OAuth client credentials
+- Corrupted env file entries
+- Backup path sanitization
+
+---
+
+## 🗑️ Uninstall / Full Uninstall _(v3.6.2+)_
+
+Clean removal scripts for all installation methods:
+
+| Command                  | Action                                                                              |
+| ------------------------ | ----------------------------------------------------------------------------------- |
+| `npm run uninstall`      | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`.  |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+---
+
 ## 🖼️ 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.
@@ -141,5 +210,61 @@ Key features:
 - 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+)
+- **Graceful shutdown** — Electron `before-quit` shuts down Next.js cleanly, preventing SQLite WAL database locks (v3.6.2+)
 
 📖 See [`electron/README.md`](../electron/README.md) for full documentation.
+
+---
+
+## 🌐 V1 WebSocket Bridge _(v3.6.6+)_
+
+OmniRoute now supports **OpenAI-compatible WebSocket clients** via the `/v1/ws` upgrade endpoint. The custom `scripts/v1-ws-bridge.mjs` server wraps Next.js and upgrades WS connections to full bidirectional streaming sessions. Authentication uses the same API key or session cookie as HTTP requests.
+
+Key behaviours:
+
+- WS upgrade validated by `src/lib/ws/handshake.ts` before the connection is established
+- Streams terminated cleanly on session close or upstream error
+- Works alongside the existing HTTP+SSE streaming path simultaneously
+
+---
+
+## 🔑 Sync Tokens & Config Bundle _(v3.6.6+)_
+
+Multi-device and external operator access is now possible via **scoped sync tokens**:
+
+- **`POST /api/sync/tokens`** — Issue a new sync token (scoped, with optional expiry)
+- **`DELETE /api/sync/tokens/:id`** — Revoke a token
+- **`GET /api/sync/bundle`** — Download a versioned, ETag-keyed JSON snapshot of all non-sensitive settings (passwords redacted)
+
+The config bundle is built by `src/lib/sync/bundle.ts`. Consumers compare the `ETag` response header to detect changes without re-downloading the full payload.
+
+---
+
+## 🧠 GLM Thinking Preset _(v3.6.6+)_
+
+**GLM Thinking (`glmt`)** is now a registered first-class provider: 65 536 max output tokens, 24 576 thinking budget, 900 s default timeout, Claude-compatible API format, and shared usage sync with the GLM family.
+
+**Hybrid token counting** also lands in v3.6.6: when a Claude-compatible provider exposes `/messages/count_tokens`, OmniRoute calls it before large requests with graceful estimation fallback.
+
+---
+
+## 🛡️ Safe Outbound Fetch & SSRF Guard _(v3.6.6+)_
+
+All provider validation and model discovery calls now go through a two-layer outbound guard:
+
+1. **URL guard** (`src/shared/network/outboundUrlGuard.ts`) — Blocks private/loopback/link-local IP ranges before the socket is opened.
+2. **Safe fetch wrapper** (`src/shared/network/safeOutboundFetch.ts`) — Applies the URL guard, normalises timeouts, and retries transient errors with exponential backoff.
+
+Guard violations surface as HTTP 422 (`URL_GUARD_BLOCKED`) and are written to the compliance audit log via `providerAudit.ts`.
+
+---
+
+## 🔄 Cooldown-Aware Retries _(v3.6.6+)_
+
+Chat requests now **automatically retry** when an upstream provider returns a model-scoped cooldown. Configurable via `REQUEST_RETRY` (default: 2) and `MAX_RETRY_INTERVAL_SEC` (default: 30 s). Rate-limit header learning improved across `x-ratelimit-reset-requests`, `x-ratelimit-reset-tokens`, and `Retry-After` — per-model cooldown state is visible in the Resilience dashboard.
+
+---
+
+## 📋 Compliance Audit v2 _(v3.6.6+)_
+
+The audit log has been expanded with cursor-based pagination, request context enrichment (request ID, user agent, IP), structured auth events, provider CRUD events with diff context, and SSRF-blocked validation logging. New events emitted by `src/lib/compliance/providerAudit.ts`.

docs/i18n/ar/docs/FLY_IO_DEPLOYMENT_GUIDE.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../../da/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../../de/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../../es/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../../he/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../../id/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../../it/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../../no/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [te](../../te/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../../th/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FLY_IO_DEPLOYMENT_GUIDE.md)
 
 ---
 

docs/i18n/ar/docs/I18N.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/I18N.md) · 🇸🇦 [ar](../../ar/docs/I18N.md) · 🇧🇬 [bg](../../bg/docs/I18N.md) · 🇧🇩 [bn](../../bn/docs/I18N.md) · 🇨🇿 [cs](../../cs/docs/I18N.md) · 🇩🇰 [da](../../da/docs/I18N.md) · 🇩🇪 [de](../../de/docs/I18N.md) · 🇪🇸 [es](../../es/docs/I18N.md) · 🇮🇷 [fa](../../fa/docs/I18N.md) · 🇫🇮 [fi](../../fi/docs/I18N.md) · 🇫🇷 [fr](../../fr/docs/I18N.md) · 🇮🇳 [gu](../../gu/docs/I18N.md) · 🇮🇱 [he](../../he/docs/I18N.md) · 🇮🇳 [hi](../../hi/docs/I18N.md) · 🇭🇺 [hu](../../hu/docs/I18N.md) · 🇮🇩 [id](../../id/docs/I18N.md) · 🇮🇹 [it](../../it/docs/I18N.md) · 🇯🇵 [ja](../../ja/docs/I18N.md) · 🇰🇷 [ko](../../ko/docs/I18N.md) · 🇮🇳 [mr](../../mr/docs/I18N.md) · 🇲🇾 [ms](../../ms/docs/I18N.md) · 🇳🇱 [nl](../../nl/docs/I18N.md) · 🇳🇴 [no](../../no/docs/I18N.md) · 🇵🇭 [phi](../../phi/docs/I18N.md) · 🇵🇱 [pl](../../pl/docs/I18N.md) · 🇵🇹 [pt](../../pt/docs/I18N.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/I18N.md) · 🇷🇴 [ro](../../ro/docs/I18N.md) · 🇷🇺 [ru](../../ru/docs/I18N.md) · 🇸🇰 [sk](../../sk/docs/I18N.md) · 🇸🇪 [sv](../../sv/docs/I18N.md) · 🇰🇪 [sw](../../sw/docs/I18N.md) · 🇮🇳 [ta](../../ta/docs/I18N.md) · 🇮🇳 [te](../../te/docs/I18N.md) · 🇹🇭 [th](../../th/docs/I18N.md) · 🇹🇷 [tr](../../tr/docs/I18N.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/I18N.md) · 🇵🇰 [ur](../../ur/docs/I18N.md) · 🇻🇳 [vi](../../vi/docs/I18N.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/I18N.md)
 
 ---
 

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

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

docs/i18n/ar/docs/RELEASE_CHECKLIST.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/RELEASE_CHECKLIST.md) · 🇸🇦 [ar](../../ar/docs/RELEASE_CHECKLIST.md) · 🇧🇬 [bg](../../bg/docs/RELEASE_CHECKLIST.md) · 🇧🇩 [bn](../../bn/docs/RELEASE_CHECKLIST.md) · 🇨🇿 [cs](../../cs/docs/RELEASE_CHECKLIST.md) · 🇩🇰 [da](../../da/docs/RELEASE_CHECKLIST.md) · 🇩🇪 [de](../../de/docs/RELEASE_CHECKLIST.md) · 🇪🇸 [es](../../es/docs/RELEASE_CHECKLIST.md) · 🇮🇷 [fa](../../fa/docs/RELEASE_CHECKLIST.md) · 🇫🇮 [fi](../../fi/docs/RELEASE_CHECKLIST.md) · 🇫🇷 [fr](../../fr/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [gu](../../gu/docs/RELEASE_CHECKLIST.md) · 🇮🇱 [he](../../he/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [hi](../../hi/docs/RELEASE_CHECKLIST.md) · 🇭🇺 [hu](../../hu/docs/RELEASE_CHECKLIST.md) · 🇮🇩 [id](../../id/docs/RELEASE_CHECKLIST.md) · 🇮🇹 [it](../../it/docs/RELEASE_CHECKLIST.md) · 🇯🇵 [ja](../../ja/docs/RELEASE_CHECKLIST.md) · 🇰🇷 [ko](../../ko/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [mr](../../mr/docs/RELEASE_CHECKLIST.md) · 🇲🇾 [ms](../../ms/docs/RELEASE_CHECKLIST.md) · 🇳🇱 [nl](../../nl/docs/RELEASE_CHECKLIST.md) · 🇳🇴 [no](../../no/docs/RELEASE_CHECKLIST.md) · 🇵🇭 [phi](../../phi/docs/RELEASE_CHECKLIST.md) · 🇵🇱 [pl](../../pl/docs/RELEASE_CHECKLIST.md) · 🇵🇹 [pt](../../pt/docs/RELEASE_CHECKLIST.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) · 🇷🇴 [ro](../../ro/docs/RELEASE_CHECKLIST.md) · 🇷🇺 [ru](../../ru/docs/RELEASE_CHECKLIST.md) · 🇸🇰 [sk](../../sk/docs/RELEASE_CHECKLIST.md) · 🇸🇪 [sv](../../sv/docs/RELEASE_CHECKLIST.md) · 🇰🇪 [sw](../../sw/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [ta](../../ta/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [te](../../te/docs/RELEASE_CHECKLIST.md) · 🇹🇭 [th](../../th/docs/RELEASE_CHECKLIST.md) · 🇹🇷 [tr](../../tr/docs/RELEASE_CHECKLIST.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) · 🇵🇰 [ur](../../ur/docs/RELEASE_CHECKLIST.md) · 🇻🇳 [vi](../../vi/docs/RELEASE_CHECKLIST.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md)
 
 ---
 
@@ -24,7 +24,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
 
 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.
+3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
+   - `>=20.20.2 <21` or `>=22.22.2 <23`
+   - `npm run check:node-runtime`
+4. Validate the npm publish artifact after building the standalone package:
+   - `npm run build:cli`
+   - `npm run check:pack-artifact`
+   - confirm no `app.__qa_backup`, `scripts/scratch`, `package-lock.json`, or other local residue
+5. Update localized docs if source docs changed significantly.
 
 ## Automated Check
 

docs/i18n/ar/docs/TROUBLESHOOTING.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/TROUBLESHOOTING.md) · 🇸🇦 [ar](../../ar/docs/TROUBLESHOOTING.md) · 🇧🇬 [bg](../../bg/docs/TROUBLESHOOTING.md) · 🇧🇩 [bn](../../bn/docs/TROUBLESHOOTING.md) · 🇨🇿 [cs](../../cs/docs/TROUBLESHOOTING.md) · 🇩🇰 [da](../../da/docs/TROUBLESHOOTING.md) · 🇩🇪 [de](../../de/docs/TROUBLESHOOTING.md) · 🇪🇸 [es](../../es/docs/TROUBLESHOOTING.md) · 🇮🇷 [fa](../../fa/docs/TROUBLESHOOTING.md) · 🇫🇮 [fi](../../fi/docs/TROUBLESHOOTING.md) · 🇫🇷 [fr](../../fr/docs/TROUBLESHOOTING.md) · 🇮🇳 [gu](../../gu/docs/TROUBLESHOOTING.md) · 🇮🇱 [he](../../he/docs/TROUBLESHOOTING.md) · 🇮🇳 [hi](../../hi/docs/TROUBLESHOOTING.md) · 🇭🇺 [hu](../../hu/docs/TROUBLESHOOTING.md) · 🇮🇩 [id](../../id/docs/TROUBLESHOOTING.md) · 🇮🇹 [it](../../it/docs/TROUBLESHOOTING.md) · 🇯🇵 [ja](../../ja/docs/TROUBLESHOOTING.md) · 🇰🇷 [ko](../../ko/docs/TROUBLESHOOTING.md) · 🇮🇳 [mr](../../mr/docs/TROUBLESHOOTING.md) · 🇲🇾 [ms](../../ms/docs/TROUBLESHOOTING.md) · 🇳🇱 [nl](../../nl/docs/TROUBLESHOOTING.md) · 🇳🇴 [no](../../no/docs/TROUBLESHOOTING.md) · 🇵🇭 [phi](../../phi/docs/TROUBLESHOOTING.md) · 🇵🇱 [pl](../../pl/docs/TROUBLESHOOTING.md) · 🇵🇹 [pt](../../pt/docs/TROUBLESHOOTING.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) · 🇷🇴 [ro](../../ro/docs/TROUBLESHOOTING.md) · 🇷🇺 [ru](../../ru/docs/TROUBLESHOOTING.md) · 🇸🇰 [sk](../../sk/docs/TROUBLESHOOTING.md) · 🇸🇪 [sv](../../sv/docs/TROUBLESHOOTING.md) · 🇰🇪 [sw](../../sw/docs/TROUBLESHOOTING.md) · 🇮🇳 [ta](../../ta/docs/TROUBLESHOOTING.md) · 🇮🇳 [te](../../te/docs/TROUBLESHOOTING.md) · 🇹🇭 [th](../../th/docs/TROUBLESHOOTING.md) · 🇹🇷 [tr](../../tr/docs/TROUBLESHOOTING.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) · 🇵🇰 [ur](../../ur/docs/TROUBLESHOOTING.md) · 🇻🇳 [vi](../../vi/docs/TROUBLESHOOTING.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md)
 
 ---
 
@@ -10,13 +10,95 @@ Common problems and solutions for OmniRoute.
 
 ## Quick Fixes
 
-| Problem                       | Solution                                                           |
-| ----------------------------- | ------------------------------------------------------------------ |
-| First login not working       | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default)            |
-| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` |
-| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true`                                     |
-| EACCES: permission denied     | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute`    |
-| Routing strategy not saving   | Update to v1.4.11+ (Zod schema fix for settings persistence)       |
+| Problem                                             | Solution                                                                                                                                                 |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| First login not working                             | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default)                                                                                                  |
+| Dashboard opens on wrong port                       | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128`                                                                                       |
+| No logs written to disk                             | Set `APP_LOG_TO_FILE=true` and verify call log capture is enabled                                                                                        |
+| EACCES: permission denied                           | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute`                                                                                          |
+| Routing strategy not saving                         | Update to v1.4.11+ (Zod schema fix for settings persistence)                                                                                             |
+| Login crash / blank page                            | Check Node.js version — see [Node.js Compatibility](#nodejs-compatibility) below                                                                         |
+| `dlopen` / `slice is not valid mach-o file` (macOS) | Run `cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute` — see [macOS native module rebuild](#macos-native-module-rebuild) below |
+| Proxy "fetch failed"                                | Ensure proxy config is set at the correct level — see [Proxy Issues](#proxy-issues) below                                                                |
+
+---
+
+## Node.js Compatibility
+
+<a name="nodejs-compatibility"></a>
+
+### Login page crashes or shows "Module self-registration" error
+
+**Cause:** You are running a Node.js version outside OmniRoute's approved secure runtime floor. The most common case is running an older Node 20, 22, or 24 patch level that falls below the patched security floor OmniRoute requires.
+
+**Symptoms:**
+
+- Login page shows a blank screen or a server error
+- Console shows `Error: Module did not self-register` or similar native binding errors
+- The login page shows an **orange warning banner** with your Node version if the runtime is outside the supported secure policy
+
+**Fix:**
+
+1. Install a supported Node.js LTS release (recommended: Node.js 24.x):
+   ```bash
+   nvm install 24
+   nvm use 24
+   ```
+2. Verify your version: `node --version` should show `v24.0.0` or newer on the 24.x LTS line
+3. Reinstall OmniRoute: `npm install -g omniroute`
+4. Restart: `omniroute`
+
+> **Supported secure versions:** `>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25`. Node.js 24.x LTS (Krypton) is fully supported.
+
+### macOS: `dlopen` / "slice is not valid mach-o file"
+
+<a name="macos-native-module-rebuild"></a>
+
+**Cause:** After a global `npm install -g omniroute`, the `better-sqlite3` native binary inside the package may have been compiled for a different architecture or Node.js ABI than what is running locally. This is common on macOS (both Apple Silicon and Intel) when the pre-built binary does not match your environment.
+
+**Symptoms:**
+
+- Server fails immediately on startup with a `dlopen` error
+- Error contains `slice is not valid mach-o file`
+- Full example:
+
+```
+dlopen(/Users/<user>/.nvm/versions/node/v24.14.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file)
+```
+
+**Fix — rebuild for your local environment (no Node.js downgrade required):**
+
+```bash
+cd $(npm root -g)/omniroute/app
+npm rebuild better-sqlite3
+omniroute
+```
+
+> **Note:** This recompiles the native binding against your local Node.js version and CPU architecture, resolving the binary mismatch. The officially supported range is **`>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25`** (`engines` field in `package.json`). Node.js 24.x LTS (Krypton) is fully supported with `better-sqlite3` v12.x.
+
+---
+
+## Proxy Issues
+
+<a name="proxy-issues"></a>
+
+### Provider validation shows "fetch failed"
+
+**Cause:** The API key validation endpoint (`POST /api/providers/validate`) was previously bypassing proxy configuration, causing failures in environments that require proxy routing.
+
+**Fix (v3.5.5+):** This is now fixed. Provider validation routes through `runWithProxyContext`, honoring provider-level and global proxy settings automatically.
+
+### Token health check fails with "fetch failed"
+
+**Cause:** Background OAuth token refresh was not resolving proxy configuration per connection.
+
+**Fix (v3.5.5+):** The token health check scheduler now resolves proxy config per connection before attempting refresh. Update to v3.5.5+.
+
+### SOCKS5 proxy returns "invalid onRequestStart method"
+
+**Cause:** On Node.js 22, the undici@8 dispatcher is incompatible with Node's built-in `fetch()` implementation.
+
+**Fix (v3.5.5+):** OmniRoute now uses undici's own `fetch()` function when a proxy dispatcher is active, ensuring consistent behavior. Update to v3.5.5+.
 
 ---
 
@@ -106,9 +188,11 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
 
 ## Debugging
 
-### Enable Request Logs
+### Enable Log Files
 
-Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory.
+Set `APP_LOG_TO_FILE=true` in your `.env` file. Application logs are written under `logs/`.
+Request artifacts are stored under `${DATA_DIR}/call_logs/` when the call log pipeline is
+enabled in settings.
 
 ### Check Provider Health
 
@@ -123,8 +207,9 @@ curl http://localhost:20128/api/monitoring/health
 ### Runtime Storage
 
 - Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings)
-- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/`
-- Request logs: `<repo>/logs/...` (when `ENABLE_REQUEST_LOGS=true`)
+- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/call_logs/`
+- Application logs: `<repo>/logs/...` (when `APP_LOG_TO_FILE=true`)
+- Call log artifacts: `${DATA_DIR}/call_logs/YYYY-MM-DD/...` when the call log pipeline is enabled
 
 ---
 

docs/i18n/ar/docs/UNINSTALL.md

@@ -0,0 +1,157 @@
+# OmniRoute — Uninstall Guide (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/UNINSTALL.md) · 🇸🇦 [ar](../../ar/docs/UNINSTALL.md) · 🇧🇬 [bg](../../bg/docs/UNINSTALL.md) · 🇧🇩 [bn](../../bn/docs/UNINSTALL.md) · 🇨🇿 [cs](../../cs/docs/UNINSTALL.md) · 🇩🇰 [da](../../da/docs/UNINSTALL.md) · 🇩🇪 [de](../../de/docs/UNINSTALL.md) · 🇪🇸 [es](../../es/docs/UNINSTALL.md) · 🇮🇷 [fa](../../fa/docs/UNINSTALL.md) · 🇫🇮 [fi](../../fi/docs/UNINSTALL.md) · 🇫🇷 [fr](../../fr/docs/UNINSTALL.md) · 🇮🇳 [gu](../../gu/docs/UNINSTALL.md) · 🇮🇱 [he](../../he/docs/UNINSTALL.md) · 🇮🇳 [hi](../../hi/docs/UNINSTALL.md) · 🇭🇺 [hu](../../hu/docs/UNINSTALL.md) · 🇮🇩 [id](../../id/docs/UNINSTALL.md) · 🇮🇹 [it](../../it/docs/UNINSTALL.md) · 🇯🇵 [ja](../../ja/docs/UNINSTALL.md) · 🇰🇷 [ko](../../ko/docs/UNINSTALL.md) · 🇮🇳 [mr](../../mr/docs/UNINSTALL.md) · 🇲🇾 [ms](../../ms/docs/UNINSTALL.md) · 🇳🇱 [nl](../../nl/docs/UNINSTALL.md) · 🇳🇴 [no](../../no/docs/UNINSTALL.md) · 🇵🇭 [phi](../../phi/docs/UNINSTALL.md) · 🇵🇱 [pl](../../pl/docs/UNINSTALL.md) · 🇵🇹 [pt](../../pt/docs/UNINSTALL.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/UNINSTALL.md) · 🇷🇴 [ro](../../ro/docs/UNINSTALL.md) · 🇷🇺 [ru](../../ru/docs/UNINSTALL.md) · 🇸🇰 [sk](../../sk/docs/UNINSTALL.md) · 🇸🇪 [sv](../../sv/docs/UNINSTALL.md) · 🇰🇪 [sw](../../sw/docs/UNINSTALL.md) · 🇮🇳 [ta](../../ta/docs/UNINSTALL.md) · 🇮🇳 [te](../../te/docs/UNINSTALL.md) · 🇹🇭 [th](../../th/docs/UNINSTALL.md) · 🇹🇷 [tr](../../tr/docs/UNINSTALL.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/UNINSTALL.md) · 🇵🇰 [ur](../../ur/docs/UNINSTALL.md) · 🇻🇳 [vi](../../vi/docs/UNINSTALL.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/UNINSTALL.md)
+
+---
+
+This guide covers how to cleanly remove OmniRoute from your system.
+
+---
+
+## Quick Uninstall (v3.6.2+)
+
+OmniRoute provides two built-in scripts for clean removal:
+
+### Keep Your Data
+
+```bash
+npm run uninstall
+```
+
+This removes the OmniRoute application but **preserves** your database, configurations, API keys, and provider settings in `~/.omniroute/`. Use this if you plan to reinstall later and want to keep your setup.
+
+### Full Removal
+
+```bash
+npm run uninstall:full
+```
+
+This removes the application **and permanently erases** all data:
+
+- Database (`storage.sqlite`)
+- Provider configurations and API keys
+- Backup files
+- Log files
+- All files in the `~/.omniroute/` directory
+
+> ⚠️ **Warning:** `npm run uninstall:full` is irreversible. All your provider connections, combos, API keys, and usage history will be permanently deleted.
+
+---
+
+## Manual Uninstall
+
+### NPM Global Install
+
+```bash
+# Remove the global package
+npm uninstall -g omniroute
+
+# (Optional) Remove data directory
+rm -rf ~/.omniroute
+```
+
+### pnpm Global Install
+
+```bash
+pnpm uninstall -g omniroute
+rm -rf ~/.omniroute
+```
+
+### Docker
+
+```bash
+# Stop and remove the container
+docker stop omniroute
+docker rm omniroute
+
+# Remove the volume (deletes all data)
+docker volume rm omniroute-data
+
+# (Optional) Remove the image
+docker rmi diegosouzapw/omniroute:latest
+```
+
+### Docker Compose
+
+```bash
+# Stop and remove containers
+docker compose down
+
+# Also remove volumes (deletes all data)
+docker compose down -v
+```
+
+### Electron Desktop App
+
+**Windows:**
+
+- Open `Settings → Apps → OmniRoute → Uninstall`
+- Or run the NSIS uninstaller from the install directory
+
+**macOS:**
+
+- Drag `OmniRoute.app` from `/Applications` to Trash
+- Remove data: `rm -rf ~/Library/Application Support/omniroute`
+
+**Linux:**
+
+- Remove the AppImage file
+- Remove data: `rm -rf ~/.omniroute`
+
+### Source Install (git clone)
+
+```bash
+# Remove the cloned directory
+rm -rf /path/to/omniroute
+
+# (Optional) Remove data directory
+rm -rf ~/.omniroute
+```
+
+---
+
+## Data Directories
+
+OmniRoute stores data in the following locations by default:
+
+| Platform      | Default Path                  | Override                  |
+| ------------- | ----------------------------- | ------------------------- |
+| Linux         | `~/.omniroute/`               | `DATA_DIR` env var        |
+| macOS         | `~/.omniroute/`               | `DATA_DIR` env var        |
+| Windows       | `%APPDATA%/omniroute/`        | `DATA_DIR` env var        |
+| Docker        | `/app/data/` (mounted volume) | `DATA_DIR` env var        |
+| XDG-compliant | `$XDG_CONFIG_HOME/omniroute/` | `XDG_CONFIG_HOME` env var |
+
+### Files in the data directory
+
+| File/Directory       | Description                                       |
+| -------------------- | ------------------------------------------------- |
+| `storage.sqlite`     | Main database (providers, combos, settings, keys) |
+| `storage.sqlite-wal` | SQLite write-ahead log (temporary)                |
+| `storage.sqlite-shm` | SQLite shared memory (temporary)                  |
+| `call_logs/`         | Request payload archives                          |
+| `backups/`           | Automatic database backups                        |
+| `log.txt`            | Legacy request log (optional)                     |
+
+---
+
+## Verify Complete Removal
+
+After uninstalling, verify there are no remaining files:
+
+```bash
+# Check for global npm package
+npm list -g omniroute 2>/dev/null
+
+# Check for data directory
+ls -la ~/.omniroute/ 2>/dev/null
+
+# Check for running processes
+pgrep -f omniroute
+```
+
+If any process is still running, stop it:
+
+```bash
+pkill -f omniroute
+```

docs/i18n/ar/docs/USER_GUIDE.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/USER_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/USER_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/USER_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/USER_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/USER_GUIDE.md) · 🇩🇰 [da](../../da/docs/USER_GUIDE.md) · 🇩🇪 [de](../../de/docs/USER_GUIDE.md) · 🇪🇸 [es](../../es/docs/USER_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/USER_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/USER_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/USER_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/USER_GUIDE.md) · 🇮🇱 [he](../../he/docs/USER_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/USER_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/USER_GUIDE.md) · 🇮🇩 [id](../../id/docs/USER_GUIDE.md) · 🇮🇹 [it](../../it/docs/USER_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/USER_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/USER_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/USER_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/USER_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/USER_GUIDE.md) · 🇳🇴 [no](../../no/docs/USER_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/USER_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/USER_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/USER_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/USER_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/USER_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/USER_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/USER_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/USER_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/USER_GUIDE.md) · 🇮🇳 [te](../../te/docs/USER_GUIDE.md) · 🇹🇭 [th](../../th/docs/USER_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/USER_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/USER_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/USER_GUIDE.md)
 
 ---
 
@@ -57,7 +57,7 @@ Complete guide for configuring providers, creating combos, integrating CLI tools
 
 ```
 Combo: "maximize-claude"
-  1. cc/claude-opus-4-6        (use subscription fully)
+  1. cc/claude-opus-4-7        (use subscription fully)
   2. glm/glm-4.7               (cheap backup when quota out)
   3. if/kimi-k2-thinking       (free emergency fallback)
 
@@ -85,7 +85,7 @@ Quality: Production-ready models
 
 ```
 Combo: "always-on"
-  1. cc/claude-opus-4-6        (best quality)
+  1. cc/claude-opus-4-7        (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)
@@ -123,7 +123,7 @@ Dashboard → Providers → Connect Claude Code
 → 5-hour + weekly quota tracking
 
 Models:
-  cc/claude-opus-4-6
+  cc/claude-opus-4-7
   cc/claude-sonnet-4-5-20250929
   cc/claude-haiku-4-5-20251001
 ```
@@ -223,6 +223,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
 
 ## 🎨 Combos
 
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
 ### Example 1: Maximize Subscription → Cheap Backup
 
 ```
@@ -230,7 +232,7 @@ Dashboard → Combos → Create New
 
 Name: premium-coding
 Models:
-  1. cc/claude-opus-4-6 (Subscription primary)
+  1. cc/claude-opus-4-7 (Subscription primary)
   2. glm/glm-4.7 (Cheap backup, $0.6/1M)
   3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
 
@@ -259,7 +261,7 @@ Cost: $0 forever!
 Settings → Models → Advanced:
   OpenAI API Base URL: http://localhost:20128/v1
   OpenAI API Key: [from omniroute dashboard]
-  Model: cc/claude-opus-4-6
+  Model: cc/claude-opus-4-7
 ```
 
 ### Claude Code
@@ -313,7 +315,7 @@ Edit `~/.openclaw/openclaw.json`:
 Provider: OpenAI Compatible
 Base URL: http://localhost:20128/v1
 API Key: [from dashboard]
-Model: cc/claude-opus-4-6
+Model: cc/claude-opus-4-7
 ```
 
 ---
@@ -339,6 +341,17 @@ omniroute --port 3000
 
 The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
 
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command                  | Action                                                                              |
+| ------------------------ | ----------------------------------------------------------------------------------- |
+| `npm run uninstall`      | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`.  |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
 ### VPS Deployment
 
 ```bash
@@ -493,7 +506,7 @@ do_install() {
 #!/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}"
+export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
 mkdir -p "${DATA_DIR}"
 exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
 EOF
@@ -524,7 +537,7 @@ post_install() {
 | `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                                                                             |
+| `APP_LOG_TO_FILE`                       | `true`                               | Enables application and audit log output to disk                                                          |
 | `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`)                                          |
@@ -541,7 +554,7 @@ For the full environment variable reference, see the [README](../README.md).
 <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`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-7`, `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`
 
@@ -734,7 +747,7 @@ Define global fallback chains that apply across all requests:
 
 ```
 Chain: production-fallback
-  1. cc/claude-opus-4-6
+  1. cc/claude-opus-4-7
   2. gh/gpt-5.1-codex
   3. glm/glm-4.7
 ```
@@ -745,30 +758,34 @@ Chain: production-fallback
 
 Configure via **Dashboard → Settings → Resilience**.
 
-OmniRoute implements provider-level resilience with four components:
+OmniRoute implements provider-level resilience with five 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:
+1. **Request Queue & Pacing** — System-level request shaping:
    - **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:
+2. **Connection Cooldown** — Per-auth-type configuration for a single connection after retryable failures:
+   - **Base Cooldown** — Default cooldown window for retryable upstream failures
+   - **Use Upstream Retry Hints** — Honors authoritative `Retry-After` or reset hints when provided
+   - **Max Backoff Steps** — Maximum exponential backoff level for repeated failures
+
+3. **Provider Circuit Breaker** — Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:
+   - **Failure Threshold** — Consecutive provider failures before opening the breaker
+   - **Reset Timeout** — Time window before the provider is tested again
    - **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.
+   Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.
 
-5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
+   The provider breaker runtime state is shown on **Dashboard → Health** only.
 
-**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
+4. **Wait For Cooldown** — If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.
+
+5. **Rate Limit Auto-Detection** — When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.
+
+**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.
 
 ---
 
@@ -808,14 +825,14 @@ curl -X POST http://localhost:20128/api/db-backups/import \
 
 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 |
-| **AI**         | Thinking budget configuration, global system prompt injection, prompt cache stats              |
-| **Advanced**   | Global proxy configuration (HTTP/SOCKS5)                                                       |
+| 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** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior  |
+| **AI**         | Thinking budget configuration, global system prompt injection, prompt cache stats            |
+| **Advanced**   | Global proxy configuration (HTTP/SOCKS5)                                                     |
 
 ---
 
@@ -888,9 +905,9 @@ Access via **Dashboard → Health**. Real-time system health overview with 6 car
 | 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         |
+| **Provider Health**   | Global provider circuit breaker runtime state               |
+| **Rate Limits**       | Active connection cooldowns per account with remaining time |
+| **Active Lockouts**   | Active model-scoped lockouts and temporary exclusions       |
 | **Signature Cache**   | Deduplication cache stats (active keys, hit rate)           |
 | **Latency Telemetry** | p50/p95/p99 latency aggregation per provider                |
 

docs/i18n/ar/docs/VM_DEPLOYMENT_GUIDE.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/VM_DEPLOYMENT_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/VM_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/VM_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [te](../../te/docs/VM_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/VM_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/VM_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md)
 
 ---
 
@@ -108,7 +108,7 @@ NODE_ENV=production
 HOSTNAME=0.0.0.0
 DATA_DIR=/app/data
 STORAGE_DRIVER=sqlite
-ENABLE_REQUEST_LOGS=true
+APP_LOG_TO_FILE=true
 AUTH_COOKIE_SECURE=false
 REQUIRE_API_KEY=false
 

docs/i18n/ar/docs/cloudflare-zero-trust-guide.md

@@ -0,0 +1,106 @@
+# Guia Completo: Cloudflare Tunnel & Zero Trust (Split-Port) (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/cloudflare-zero-trust-guide.md) · 🇪🇸 [es](../../es/docs/cloudflare-zero-trust-guide.md) · 🇫🇷 [fr](../../fr/docs/cloudflare-zero-trust-guide.md) · 🇩🇪 [de](../../de/docs/cloudflare-zero-trust-guide.md) · 🇮🇹 [it](../../it/docs/cloudflare-zero-trust-guide.md) · 🇷🇺 [ru](../../ru/docs/cloudflare-zero-trust-guide.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/cloudflare-zero-trust-guide.md) · 🇯🇵 [ja](../../ja/docs/cloudflare-zero-trust-guide.md) · 🇰🇷 [ko](../../ko/docs/cloudflare-zero-trust-guide.md) · 🇸🇦 [ar](../../ar/docs/cloudflare-zero-trust-guide.md) · 🇮🇳 [hi](../../hi/docs/cloudflare-zero-trust-guide.md) · 🇮🇳 [in](../../in/docs/cloudflare-zero-trust-guide.md) · 🇹🇭 [th](../../th/docs/cloudflare-zero-trust-guide.md) · 🇻🇳 [vi](../../vi/docs/cloudflare-zero-trust-guide.md) · 🇮🇩 [id](../../id/docs/cloudflare-zero-trust-guide.md) · 🇲🇾 [ms](../../ms/docs/cloudflare-zero-trust-guide.md) · 🇳🇱 [nl](../../nl/docs/cloudflare-zero-trust-guide.md) · 🇵🇱 [pl](../../pl/docs/cloudflare-zero-trust-guide.md) · 🇸🇪 [sv](../../sv/docs/cloudflare-zero-trust-guide.md) · 🇳🇴 [no](../../no/docs/cloudflare-zero-trust-guide.md) · 🇩🇰 [da](../../da/docs/cloudflare-zero-trust-guide.md) · 🇫🇮 [fi](../../fi/docs/cloudflare-zero-trust-guide.md) · 🇵🇹 [pt](../../pt/docs/cloudflare-zero-trust-guide.md) · 🇷🇴 [ro](../../ro/docs/cloudflare-zero-trust-guide.md) · 🇭🇺 [hu](../../hu/docs/cloudflare-zero-trust-guide.md) · 🇧🇬 [bg](../../bg/docs/cloudflare-zero-trust-guide.md) · 🇸🇰 [sk](../../sk/docs/cloudflare-zero-trust-guide.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/cloudflare-zero-trust-guide.md) · 🇮🇱 [he](../../he/docs/cloudflare-zero-trust-guide.md) · 🇵🇭 [phi](../../phi/docs/cloudflare-zero-trust-guide.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/cloudflare-zero-trust-guide.md) · 🇨🇿 [cs](../../cs/docs/cloudflare-zero-trust-guide.md) · 🇹🇷 [tr](../../tr/docs/cloudflare-zero-trust-guide.md)
+
+---
+
+Este guia documenta o padrão ouro de infraestrutura de rede para proteger o **OmniRoute** e expor sua aplicação de forma segura para a internet, **sem abrir nenhuma porta (Zero Inbound)**.
+
+## O que foi feito na sua VM?
+
+Nós ativamos o OmniRoute em modo **Split-Port** através do PM2:
+
+- **Porta \`20128\`:** Roda **apenas a API** `/v1`.
+- **Porta \`20129\`:** Roda **apenas o Dashboard** Administrativo visual.
+
+Além disso, o serviço interno exige \`REQUIRE_API_KEY=true\`, o que significa que nenhum agente pode consumir os endpoints da API sem enviar um "Bearer Token" legítimo gerado na aba API Keys do Painel.
+
+Isso nos permite criar duas regras completamente independentes na rede. É aqui que entra o **Cloudflare Tunnel (cloudflared)**.
+
+---
+
+## 1. Como Criar o Túnel na Cloudflare
+
+O utilitário \`cloudflared\` já está instalado na sua máquina. Siga os passos na nuvem:
+
+1. Acesse seu painel **Cloudflare Zero Trust** (One.dash.cloudflare.com).
+2. No menu à esquerda, vá em **Networks > Tunnels**.
+3. Clique em **Add a Tunnel**, escolha **Cloudflared** e dê o nome \`OmniRoute-VM\`.
+4. Ele vai gerar um comando na tela chamado "Install and run a connector". **Você só precisa copiar o Token (a string longa após `--token`)**.
+5. Logue via SSH na sua máquina virtual (ou Terminal do Proxmox) e execute:
+   \`\`\`bash
+   # Inicia e amarra o túnel permanentemente à sua conta
+   cloudflared service install SEU_TOKEN_GIGANTE_AQUI
+   \`\`\`
+
+---
+
+## 2. Configurando o Roteamento (Public Hostnames)
+
+Ainda na tela do Tunnel recém-criado, vá para a aba **Public Hostnames** e adicione as **duas** rotas, aproveitando a separação que fizemos:
+
+### Rota 1: API Segura (Limitada)
+
+- **Subdomain:** \`api\`
+- **Domain:** \`seuglobal.com.br\` (escolha seu domínio real)
+- **Service Type:** \`HTTP\`
+- **URL:** \`127.0.0.1:20128\` _(Porta interna da API)_
+
+### Rota 2: Painel Zero Trust (Fechado)
+
+- **Subdomain:** \`omniroute\` ou \`painel\`
+- **Domain:** \`seuglobal.com.br\`
+- **Service Type:** \`HTTP\`
+- **URL:** \`127.0.0.1:20129\` _(Porta interna do App/Visual)_
+
+Neste momento, a conectividade "Física" está resolvida. Agora vamos blindar de verdade.
+
+---
+
+## 3. Blindando o Painel com Zero Trust (Access)
+
+Nenhuma senha local protege melhor o seu painel do que remover totalmente o acesso a ele da internet aberta.
+
+1. No painel Zero Trust, vá em **Access > Applications > Add an application**.
+2. Selecione **Self-hosted**.
+3. Em **Application name**, coloque \`Painel OmniRoute\`.
+4. Em **Application domain**, coloque \`omniroute.seuglobal.com.br\` (O mesmo que você fez na "Rota 2").
+5. Clique em **Next**.
+6. Em **Rule action**, escolha \`Allow\`. Em nome da Rule coloque \`Admin Apenas\`.
+7. Em **Include**, no seletor de "Selector" escolha \`Emails\` e digite o seu email, por exemplo \`admin@spgeo.com.br\`.
+8. Salve (`Add application`).
+
+> **O que isso fez:** Se você tentar abrir \`omniroute.seuglobal.com.br\`, não cai mais na sua aplicação OmniRoute! Cai numa tela elegante da Cloudflare pedindo para digitar seu email. Somente se você (ou o email que você botou) for digitado lá, ele recebe no Outlook/Gmail um código de 6 dígitos temporário que libera o túnel até a porta \`20129\`.
+
+---
+
+## 4. Limitando e Protegendo a API com Rate Limit (WAF)
+
+O Dashboard do Zero Trust não se aplica à rota da API (\`api.seuglobal.com.br\`), porque é um acesso programático via ferramentas automatizadas (agentes) sem navegador. Para ele, usaremos o Firewall principal (WAF) da Cloudflare.
+
+1. Acesse o **Painel Normal** da Cloudflare (dash.cloudflare.com) e entre no seu Domínio.
+2. No menu esquerdo, vá em **Security > WAF > Rate limiting rules**.
+3. Clique em **Create rule**.
+4. **Name:** \`Anti-Abuso OmniRoute API\`
+5. **If incoming requests match...**
+   - Escolha em Field: \`Hostname\`
+   - Operator: \`equals\`
+   - Value: \`api.seuglobal.com.br\`
+6. Em **With the same characteristics:** Mantenha \`IP\`.
+7. Nos limites (Limit):
+   - **When requests exceed:** \`50\`
+   - **Period:** \`1 minute\`
+8. No final, em **Action**: \`Block\` (Bloquear) e decida se o bloqueio dura por 1 minuto ou 1 hora.
+9. **Deploy**.
+
+> **O que isso fez:** Ninguém pode mandar mais de 50 requisições num período de 60 segundos na sua URL de API. Como você roda vários agentes e os consumos por trás já batem rate limit e já rastreiam tokens, isso é apenas uma medida na Borda da Internet (Edge Layer) que protege sua Instância On-Premises de cair por estresse térmico antes mesmo do tráfego descer pelo túnel.
+
+---
+
+## Finalização
+
+1. A sua VM **não possui nenhuma porta exposta** em `/etc/ufw`.
+2. O OmniRoute só conversa HTTPS saindo (\`cloudflared\`) e não recebendo TCP direto do mundo.
+3. Seus requets pro OpenAI são ofuscados porque configuramos eles globalmente pra passar em um Proxy SOCKS5 (A nuvem não liga pro SOCKS5 porque ela vem Inbound).
+4. Seu painel web tem 2-Factor com Email.
+5. Sua API está ratelimitada na borda pela Cloudflare e só trafega Bearer Tokens.

docs/i18n/ar/docs/features/context-relay.md

@@ -0,0 +1,130 @@
+# Context Relay (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../../docs/features/context-relay.md) · 🇪🇸 [es](../../../es/docs/features/context-relay.md) · 🇫🇷 [fr](../../../fr/docs/features/context-relay.md) · 🇩🇪 [de](../../../de/docs/features/context-relay.md) · 🇮🇹 [it](../../../it/docs/features/context-relay.md) · 🇷🇺 [ru](../../../ru/docs/features/context-relay.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/features/context-relay.md) · 🇯🇵 [ja](../../../ja/docs/features/context-relay.md) · 🇰🇷 [ko](../../../ko/docs/features/context-relay.md) · 🇸🇦 [ar](../../../ar/docs/features/context-relay.md) · 🇮🇳 [hi](../../../hi/docs/features/context-relay.md) · 🇮🇳 [in](../../../in/docs/features/context-relay.md) · 🇹🇭 [th](../../../th/docs/features/context-relay.md) · 🇻🇳 [vi](../../../vi/docs/features/context-relay.md) · 🇮🇩 [id](../../../id/docs/features/context-relay.md) · 🇲🇾 [ms](../../../ms/docs/features/context-relay.md) · 🇳🇱 [nl](../../../nl/docs/features/context-relay.md) · 🇵🇱 [pl](../../../pl/docs/features/context-relay.md) · 🇸🇪 [sv](../../../sv/docs/features/context-relay.md) · 🇳🇴 [no](../../../no/docs/features/context-relay.md) · 🇩🇰 [da](../../../da/docs/features/context-relay.md) · 🇫🇮 [fi](../../../fi/docs/features/context-relay.md) · 🇵🇹 [pt](../../../pt/docs/features/context-relay.md) · 🇷🇴 [ro](../../../ro/docs/features/context-relay.md) · 🇭🇺 [hu](../../../hu/docs/features/context-relay.md) · 🇧🇬 [bg](../../../bg/docs/features/context-relay.md) · 🇸🇰 [sk](../../../sk/docs/features/context-relay.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/features/context-relay.md) · 🇮🇱 [he](../../../he/docs/features/context-relay.md) · 🇵🇭 [phi](../../../phi/docs/features/context-relay.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/features/context-relay.md) · 🇨🇿 [cs](../../../cs/docs/features/context-relay.md) · 🇹🇷 [tr](../../../tr/docs/features/context-relay.md)
+
+---
+
+`context-relay` is a combo strategy that keeps session continuity when the active account
+rotates before the conversation is finished.
+
+The current runtime behaves like priority routing for model selection, then adds a
+handoff layer on top:
+
+- before the active account is exhausted, OmniRoute generates a compact structured summary
+- after authentication selects a different account for the same session, OmniRoute injects
+  that summary as a system message into the next request
+- once the handoff is consumed successfully, it is removed from storage
+
+## When To Use It
+
+Use `context-relay` when all of the following are true:
+
+- the combo is expected to rotate between multiple accounts of the same provider
+- losing short-term conversational continuity would hurt task quality
+- the provider exposes enough quota information to predict an approaching account limit
+
+This is most useful for long-running coding or research sessions that may outlive a single
+account window.
+
+## Runtime Flow
+
+The current behavior is intentionally split across two runtime layers.
+
+### 0% to 84% quota used
+
+No handoff is generated. Requests behave like normal priority routing.
+
+### 85% to 94% quota used
+
+If the active provider is enabled in `handoffProviders`, OmniRoute generates a structured
+handoff summary in the background before the account is fully exhausted.
+
+Important details:
+
+- the default warning threshold is `0.85`
+- the hard stop for generation is `0.95`
+- only one in-flight handoff generation is allowed per `sessionId + comboName`
+- if an active handoff already exists for that session/combo, no duplicate summary is generated
+
+### 95% or more quota used
+
+No new handoff is generated. At this point the system is already in or near exhaustion and
+the runtime avoids scheduling another summary request.
+
+### After account rotation
+
+When the next request for the same session resolves to a different authenticated account,
+OmniRoute prepends the stored handoff as a system message. Injection happens only after the
+real account switch is known.
+
+## Handoff Payload
+
+The persisted handoff payload is stored in `context_handoffs` and includes:
+
+- `sessionId`
+- `comboName`
+- `fromAccount`
+- `summary`
+- `keyDecisions`
+- `taskProgress`
+- `activeEntities`
+- `messageCount`
+- `model`
+- `warningThresholdPct`
+- `generatedAt`
+- `expiresAt`
+
+The summary model is instructed to return a JSON object with this structure:
+
+```json
+{
+  "summary": "Dense summary of what matters for continuity",
+  "keyDecisions": ["Decision 1", "Decision 2"],
+  "taskProgress": "What is done, what is pending, and the next step",
+  "activeEntities": ["fileA.ts", "feature X", "provider Y"]
+}
+```
+
+At injection time, OmniRoute converts that payload into a `<context_handoff>` system
+message so the next account can continue with the correct local context.
+
+## الإعداد
+
+`context-relay` supports these config fields:
+
+- `handoffThreshold`: warning threshold for summary generation, default `0.85`
+- `handoffModel`: optional model override used only for summary generation
+- `handoffProviders`: allowlist of providers allowed to trigger handoff generation
+
+Global defaults can be configured in Settings, and combo-specific values can override them
+in the Combos page.
+
+## Architectural Note
+
+The current implementation does not use a standalone `handleContextRelayCombo` handler.
+
+Instead:
+
+- `open-sse/services/combo.ts` decides whether a successful turn should generate a handoff
+- `src/sse/handlers/chat.ts` injects the handoff only after authentication resolves the
+  actual account used for the request
+
+This split is intentional in the current codebase because the combo loop alone does not know
+whether the request stayed on the same account or actually switched accounts.
+
+## Limitations
+
+- Effective runtime support is currently centered on `codex` quota rotation.
+- `handoffProviders` is already modeled as a config surface, but real handoff generation
+  still depends on provider-specific quota plumbing.
+- The summary is intentionally compact and recent-history based; it is not a full transcript
+  replay mechanism.
+- Handoffs are scoped by `sessionId + comboName` and expire automatically.
+- If the session does not switch accounts, the stored handoff is not injected.
+
+## Recommended Usage Pattern
+
+- use multiple accounts from the same provider
+- keep stable `sessionId` values across the session
+- set `handoffThreshold` early enough to leave room for the background summary request
+- treat the feature as continuity assistance, not as a replacement for persistent memory

docs/i18n/ar/llm.txt

@@ -0,0 +1,476 @@
+# OmniRoute (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../llm.txt) · 🇪🇸 [es](../es/llm.txt) · 🇫🇷 [fr](../fr/llm.txt) · 🇩🇪 [de](../de/llm.txt) · 🇮🇹 [it](../it/llm.txt) · 🇷🇺 [ru](../ru/llm.txt) · 🇨🇳 [zh-CN](../zh-CN/llm.txt) · 🇯🇵 [ja](../ja/llm.txt) · 🇰🇷 [ko](../ko/llm.txt) · 🇸🇦 [ar](../ar/llm.txt) · 🇮🇳 [hi](../hi/llm.txt) · 🇮🇳 [in](../in/llm.txt) · 🇹🇭 [th](../th/llm.txt) · 🇻🇳 [vi](../vi/llm.txt) · 🇮🇩 [id](../id/llm.txt) · 🇲🇾 [ms](../ms/llm.txt) · 🇳🇱 [nl](../nl/llm.txt) · 🇵🇱 [pl](../pl/llm.txt) · 🇸🇪 [sv](../sv/llm.txt) · 🇳🇴 [no](../no/llm.txt) · 🇩🇰 [da](../da/llm.txt) · 🇫🇮 [fi](../fi/llm.txt) · 🇵🇹 [pt](../pt/llm.txt) · 🇷🇴 [ro](../ro/llm.txt) · 🇭🇺 [hu](../hu/llm.txt) · 🇧🇬 [bg](../bg/llm.txt) · 🇸🇰 [sk](../sk/llm.txt) · 🇺🇦 [uk-UA](../uk-UA/llm.txt) · 🇮🇱 [he](../he/llm.txt) · 🇵🇭 [phi](../phi/llm.txt) · 🇧🇷 [pt-BR](../pt-BR/llm.txt) · 🇨🇿 [cs](../cs/llm.txt) · 🇹🇷 [tr](../tr/llm.txt)
+
+---
+
+
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 60+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (25 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+
+## نظرة عامة
+
+OmniRoute solves the problem of managing multiple AI provider subscriptions, quotas, and rate limits. It sits between your AI-powered tools (IDE agents, CLI tools) and AI providers, routing requests intelligently through a 4-tier fallback system: Subscription → API Key → Cheap → Free.
+
+**Key value:** One endpoint (`http://localhost:20128/v1`), unlimited models, zero downtime, minimal cost.
+
+**Current version:** 3.5.5
+
+## Tech Stack
+
+- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **State management:** Zustand (client), SQLite (server persistence)
+- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
+- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
+- **Schemas:** Zod v4 for all API / MCP input validation
+- **Background jobs:** Custom token health check scheduler, 24h model auto-sync
+- **Streaming:** Server-Sent Events (SSE) for real-time proxy responses
+- **Proxy engine:** Custom pipeline with format translation, circuit breaker, rate limiting, auto-combo engine
+- **i18n:** next-intl with 30 languages
+- **Desktop:** Electron (cross-platform: Windows, macOS, Linux)
+- **Package:** Published on npm (`omniroute`) and Docker Hub (`diegosouzapw/omniroute`)
+
+## Project Structure
+
+```
+/
+├── src/                          # Main application source
+│   ├── app/                      # Next.js App Router pages and API routes
+│   │   ├── (dashboard)/          # Dashboard UI pages
+│   │   │   └── dashboard/
+│   │   │       ├── agents/       # ACP Agents dashboard (CLI agent detection + custom agents)
+│   │   │       ├── analytics/    # Usage analytics and charts
+│   │   │       ├── api-manager/  # API key management
+│   │   │       ├── audit/        # Audit logs
+│   │   │       ├── auto-combo/   # Auto-combo engine dashboard
+│   │   │       ├── cache/        # Cache dashboard (semantic cache stats)
+│   │   │       ├── cli-tools/    # CLI tool configuration (Claude Code, Codex, Gemini CLI, etc.)
+│   │   │       ├── combos/       # Model combo management (13 strategies + 4 templates)
+│   │   │       ├── costs/        # Cost tracking per provider/model
+│   │   │       ├── endpoint/     # Unified: Endpoint Proxy, MCP, A2A, API Endpoints tabs
+│   │   │       ├── health/       # System health (uptime, circuit breakers, latency)
+│   │   │       ├── limits/       # Rate limits dashboard
+│   │   │       ├── logs/         # Request, Proxy, Audit, Console logs (tabbed)
+│   │   │       ├── media/        # Image/video/music generation + transcription
+│   │   │       ├── memory/       # Memory system dashboard
+│   │   │       ├── onboarding/   # Onboarding wizard
+│   │   │       ├── playground/   # Model playground (Monaco editor, streaming)
+│   │   │       ├── providers/    # Provider management (OAuth + API key + free)
+│   │   │       ├── search-tools/ # Search tools configuration
+│   │   │       ├── settings/     # Settings tabs (General, Appearance, Security, Routing, Resilience, Advanced)
+│   │   │       ├── skills/       # Skills system dashboard
+│   │   │       ├── translator/   # Format translator + debug tools
+│   │   │       └── usage/        # Usage history
+│   │   ├── api/                  # REST API endpoints (51 route directories)
+│   │   │   ├── v1/               # OpenAI-compatible API (chat, completions, models, embeddings,
+│   │   │   │                     #   images, audio, videos, music, moderations, rerank, search,
+│   │   │   │                     #   responses, messages, registered-keys, quotas, accounts)
+│   │   │   ├── v1beta/           # Gemini-compatible API
+│   │   │   ├── a2a/              # A2A agent management API
+│   │   │   ├── acp/              # ACP agent management API
+│   │   │   ├── oauth/            # OAuth flows per provider
+│   │   │   ├── providers/        # Provider CRUD and batch testing
+│   │   │   ├── models/           # Dashboard model listing and aliases
+│   │   │   ├── combos/           # Combo CRUD (multi-model fallback chains)
+│   │   │   ├── memory/           # Memory system API
+│   │   │   ├── skills/           # Skills system API
+│   │   │   ├── evals/            # Eval runner API
+│   │   │   ├── mcp/              # MCP HTTP transport API
+│   │   │   ├── search/           # Search provider API
+│   │   │   ├── webhooks/         # Webhook management
+│   │   │   ├── tunnels/          # Cloudflare tunnel management
+│   │   │   └── ...               # Other endpoints (usage, logs, health, settings, pricing, etc.)
+│   │   ├── landing/              # Landing page
+│   │   ├── login/                # Login page
+│   │   ├── forgot-password/      # Password recovery
+│   │   ├── status/               # Status page
+│   │   └── docs/                 # In-app documentation
+│   ├── domain/                   # Domain types and policy engine
+│   │   ├── policyEngine.ts       # Central policy engine
+│   │   ├── comboResolver.ts      # Combo resolution logic
+│   │   ├── costRules.ts          # Cost calculation rules
+│   │   ├── degradation.ts        # Graceful degradation
+│   │   ├── fallbackPolicy.ts     # Fallback behavior
+│   │   ├── lockoutPolicy.ts      # Account lockout logic
+│   │   ├── modelAvailability.ts  # Model availability checks
+│   │   ├── providerExpiration.ts # Provider credential expiration
+│   │   ├── quotaCache.ts         # Quota caching layer
+│   │   ├── configAudit.ts        # Configuration auditing
+│   │   └── responses.ts          # Domain response types
+│   ├── i18n/                     # Internationalization
+│   │   └── messages/             # 30 language JSON files
+│   ├── lib/                      # Core libraries
+│   │   ├── a2a/                  # Agent-to-Agent v0.3 protocol server
+│   │   │   ├── skills/           # A2A skills (quotaManagement, smartRouting)
+│   │   │   ├── taskManager.ts    # Task lifecycle with TTL cleanup
+│   │   │   └── streaming.ts      # SSE streaming for A2A
+│   │   ├── acp/                  # Agent Communication Protocol registry and manager
+│   │   ├── compliance/           # Compliance policy engine
+│   │   ├── db/                   # SQLite database layer (21 modules + migrations)
+│   │   │   ├── core.ts           # Database initialization, connection, schema
+│   │   │   ├── providers.ts      # Provider connection CRUD
+│   │   │   ├── models.ts         # Model catalog management
+│   │   │   ├── combos.ts         # Combo configuration
+│   │   │   ├── apiKeys.ts        # API key management
+│   │   │   ├── settings.ts       # Settings persistence
+│   │   │   ├── backup.ts         # Database backup/restore
+│   │   │   ├── proxies.ts        # Proxy registry
+│   │   │   ├── prompts.ts        # Prompt templates
+│   │   │   ├── webhooks.ts       # Webhook subscriptions
+│   │   │   ├── detailedLogs.ts   # Detailed request logging
+│   │   │   ├── domainState.ts    # Domain state persistence
+│   │   │   ├── registeredKeys.ts # Registered API keys with quotas
+│   │   │   ├── quotaSnapshots.ts # Quota snapshot history
+│   │   │   ├── modelComboMappings.ts # Model-to-combo mappings
+│   │   │   ├── cliToolState.ts   # CLI tool state tracking
+│   │   │   ├── encryption.ts     # Data encryption
+│   │   │   ├── readCache.ts      # Read-through cache layer
+│   │   │   ├── secrets.ts        # Secrets management
+│   │   │   ├── stateReset.ts     # State reset utilities
+│   │   │   ├── migrationRunner.ts # Schema migration runner
+│   │   │   └── migrations/       # 16 SQL migration files
+│   │   ├── evals/                # Eval runner and scheduler
+│   │   ├── memory/               # Persistent conversational memory
+│   │   │   ├── extraction.ts     # Memory extraction from conversations
+│   │   │   ├── injection.ts      # Memory injection into context
+│   │   │   ├── retrieval.ts      # Memory retrieval/search
+│   │   │   ├── store.ts          # Memory persistence layer
+│   │   │   └── summarization.ts  # Memory summarization
+│   │   ├── oauth/                # OAuth providers, services, and utilities
+│   │   │   ├── constants/        # Default OAuth credentials (overridable via env)
+│   │   │   ├── providers/        # Provider-specific OAuth configs
+│   │   │   ├── services/         # Provider-specific token exchange logic
+│   │   │   └── utils/            # PKCE, callback server, token helpers
+│   │   ├── plugins/              # Plugin system
+│   │   ├── skills/               # Extensible skill framework
+│   │   │   ├── registry.ts       # Skill registration
+│   │   │   ├── executor.ts       # Skill execution engine
+│   │   │   ├── sandbox.ts        # Skill sandbox environment
+│   │   │   ├── builtin/          # Built-in skills
+│   │   │   ├── interception.ts   # Skill request interception
+│   │   │   └── injection.ts      # Skill context injection
+│   │   ├── usage/                # Usage tracking system
+│   │   │   ├── callLogs.ts       # Call log persistence
+│   │   │   ├── costCalculator.ts # Cost calculation engine
+│   │   │   └── usageHistory.ts   # Usage history queries
+│   │   ├── cloudSync.ts          # Cloud sync via Cloudflare Workers
+│   │   ├── cloudflaredTunnel.ts  # Cloudflare tunnel management
+│   │   ├── pricingSync.ts        # LiteLLM pricing data sync
+│   │   ├── semanticCache.ts      # Semantic caching layer
+│   │   ├── tokenHealthCheck.ts   # Background OAuth token refresh scheduler
+│   │   ├── webhookDispatcher.ts  # Webhook event dispatcher
+│   │   └── localDb.ts            # Unified re-export layer for all DB modules
+│   ├── middleware/               # Request middleware
+│   │   └── promptInjectionGuard.ts # Prompt injection detection
+│   ├── mitm/                     # MITM proxy capability
+│   │   ├── cert/                 # Certificate management
+│   │   ├── dns/                  # DNS handling
+│   │   ├── targets/              # Target routing
+│   │   └── manager.ts            # MITM proxy manager
+│   ├── shared/                   # Shared utilities, components, and constants
+│   │   ├── components/           # Reusable UI components (Card, Badge, Button, Modal, Sidebar, ProviderIcon, etc.)
+│   │   ├── constants/            # Provider definitions (60+), model lists, pricing, routing strategies, MCP scopes
+│   │   ├── contracts/            # Shared API contracts
+│   │   ├── hooks/                # React hooks
+│   │   ├── middleware/           # Shared middleware utilities
+│   │   ├── schemas/              # Shared Zod schemas
+│   │   ├── services/             # Shared services
+│   │   ├── types/                # Shared TypeScript types
+│   │   ├── validation/           # Zod schemas (settings, providers, routes)
+│   │   └── utils/                # Helpers (auth, CORS, error codes, machine ID)
+│   ├── sse/                      # SSE proxy pipeline
+│   │   ├── services/             # Auth resolution, format translation, response handling
+│   │   └── middleware/           # Rate limiting, circuit breaker, caching, idempotency
+│   ├── store/                    # Zustand client-side stores (theme, providers, etc.)
+│   └── types/                    # TypeScript type definitions
+├── open-sse/                     # Standalone SSE server (npm workspace)
+│   ├── config/                   # Model registries (providerRegistry, embedding, image, audio, video,
+│   │                             #   music, rerank, moderation, search, CLI fingerprints, Ollama models)
+│   ├── executors/                # Provider-specific request executors (14 executors)
+│   │   ├── base.ts               # Base executor with shared logic
+│   │   ├── default.ts            # Default OpenAI-compatible executor
+│   │   ├── cursor.ts             # Cursor IDE (protobuf + checksum)
+│   │   ├── codex.ts              # OpenAI Codex CLI
+│   │   ├── antigravity.ts        # Antigravity IDE
+│   │   ├── github.ts             # GitHub Copilot
+│   │   ├── gemini-cli.ts         # Gemini CLI
+│   │   ├── kiro.ts               # Kiro AI
+│   │   ├── qoder.ts              # Qoder AI
+│   │   ├── vertex.ts             # Vertex AI (Service Account JSON)
+│   │   ├── cloudflare-ai.ts      # Cloudflare Workers AI
+│   │   ├── opencode.ts           # OpenCode Zen/Go
+│   │   ├── pollinations.ts       # Pollinations AI
+│   │   └── puter.ts              # Puter AI
+│   ├── handlers/                 # Request handlers per API type (11 handlers)
+│   │   ├── chatCore.ts           # Main chat completions handler
+│   │   ├── responsesHandler.ts   # OpenAI Responses API handler
+│   │   ├── embeddings.ts         # Embedding generation
+│   │   ├── imageGeneration.ts    # Image generation (DALL-E, FLUX, SD, etc.)
+│   │   ├── videoGeneration.ts    # Video generation
+│   │   ├── musicGeneration.ts    # Music generation
+│   │   ├── audioSpeech.ts        # Text-to-speech
+│   │   ├── audioTranscription.ts # Speech-to-text (Whisper, Deepgram, AssemblyAI)
+│   │   ├── moderations.ts        # Content moderation
+│   │   ├── rerank.ts             # Reranking API
+│   │   └── search.ts             # Web search API
+│   ├── mcp-server/               # Built-in MCP server (25 tools, 3 transports: stdio/SSE/streamable-HTTP)
+│   │   ├── server.ts             # MCP server core (tool registration, scope enforcement)
+│   │   ├── tools/                # Tool implementations (advancedTools, memoryTools, skillTools)
+│   │   ├── schemas/              # Zod input schemas (tools, audit, a2a)
+│   │   ├── scopeEnforcement.ts   # Scope-based access control (10 scopes)
+│   │   ├── audit.ts              # Tool call audit logging
+│   │   ├── runtimeHeartbeat.ts   # MCP runtime heartbeat
+│   │   └── httpTransport.ts      # HTTP transport handler
+│   ├── services/                 # 36+ service modules
+│   │   ├── combo.ts              # Core routing engine
+│   │   ├── usage.ts              # Usage tracking
+│   │   ├── tokenRefresh.ts       # OAuth token refresh
+│   │   ├── rateLimitManager.ts   # Rate limit management
+│   │   ├── accountFallback.ts    # Multi-account fallback
+│   │   ├── sessionManager.ts     # Session management
+│   │   ├── wildcardRouter.ts     # Wildcard model routing
+│   │   ├── autoCombo/            # Auto-combo engine (6-factor scoring, bandit exploration)
+│   │   ├── intentClassifier.ts   # Request intent classification
+│   │   ├── taskAwareRouter.ts    # Task-aware routing
+│   │   ├── thinkingBudget.ts     # Thinking budget management
+│   │   ├── contextManager.ts     # Context window management
+│   │   ├── modelDeprecation.ts   # Model deprecation handling
+│   │   ├── modelFamilyFallback.ts # Intra-family model fallback
+│   │   ├── emergencyFallback.ts  # Emergency fallback
+│   │   ├── workflowFSM.ts        # Workflow state machine
+│   │   ├── backgroundTaskDetector.ts # Background task detection
+│   │   ├── ipFilter.ts           # IP-based access control
+│   │   ├── signatureCache.ts     # CLI signature caching
+│   │   ├── volumeDetector.ts     # Request volume detection
+│   │   ├── contextHandoff.ts    # Context relay handoff generation and injection
+│   │   ├── codexQuotaFetcher.ts # Codex quota fetching for context-relay
+│   │   └── ...                   # Additional services (14 more modules)
+│   ├── transformer/              # Responses API transformer
+│   │   └── responsesTransformer.ts
+│   ├── translator/               # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama ↔ DeepSeek)
+│   │   ├── request/              # Request translators per provider
+│   │   ├── response/             # Response translators per provider
+│   │   ├── helpers/              # Translation helpers
+│   │   └── image/                # Image format translation
+│   └── utils/                    # 22 utility modules (stream, TLS, proxy, logging, etc.)
+├── electron/                     # Electron desktop app (cross-platform)
+│   ├── main.js                   # Electron main process
+│   ├── preload.js                # Preload script (IPC bridge)
+│   └── assets/                   # App icons and assets
+├── tests/                        # Test suites
+│   ├── unit/                     # 122 unit test files
+│   ├── integration/              # Integration tests
+│   ├── e2e/                      # Playwright E2E tests
+│   ├── security/                 # Security tests
+│   ├── translator/               # Translator-specific tests
+│   └── load/                     # Load tests
+├── docs/                         # Documentation
+│   ├── i18n/                     # 30-language translated docs
+│   ├── ARCHITECTURE.md           # Full architecture documentation
+│   ├── API_REFERENCE.md          # API reference
+│   ├── USER_GUIDE.md             # User guide
+│   ├── CODEBASE_DOCUMENTATION.md # Codebase overview
+│   ├── CLI-TOOLS.md              # CLI tools integration guide
+│   ├── A2A-SERVER.md             # A2A agent protocol documentation
+│   ├── AUTO-COMBO.md             # Auto-combo engine (6-factor scoring)
+│   ├── MCP-SERVER.md             # MCP server (25 tools)
+│   ├── TROUBLESHOOTING.md        # Troubleshooting guide
+│   ├── VM_DEPLOYMENT_GUIDE.md    # VPS deployment guide
+│   ├── openapi.yaml              # OpenAPI specification
+│   └── screenshots/              # Dashboard screenshots
+├── bin/                          # CLI entry points (omniroute, reset-password)
+├── scripts/                      # Build and utility scripts
+└── .env.example                  # Environment variable template
+```
+
+## Key Features (v3.5.5)
+
+### Core Proxy
+- **60+ AI providers** with automatic format translation
+- **4 provider categories**: Free (4), OAuth (8), API Key (48+), Custom (OpenAI/Anthropic-compatible)
+- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **4-tier fallback**: Subscription → API Key → Cheap → Free
+- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
+- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Semantic caching** with cache hit/miss headers
+- **Idempotency** with configurable dedup window
+- **Circuit breaker** per provider with configurable thresholds
+- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
+- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
+- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
+- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
+- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
+- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **MITM Proxy**: Certificate management, DNS handling, and target routing
+- **Cloudflare Tunnels**: Managed tunnel creation for remote access
+- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+
+### الأمان
+- **CodeQL security**: Fixed 10+ CodeQL alerts (polynomial-redos, insecure-randomness, shell-injection, SSRF, incomplete URLs)
+- **Web Crypto session IDs**: `generateSessionId` uses `crypto.getRandomValues()` instead of `Math.random()`
+- **Route validation**: All API routes validated with Zod v4 schemas + `validateBody()`
+- **omniModel tag sanitization**: Internal `<omniModel>` tags never leak to clients in SSE streams
+- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint to reduce bot detection
+- **CLI Fingerprint Matching** — Per-provider request signature matching
+- **Prompt injection guard** — Request middleware detection
+- **Provider constants validated at module load** via Zod (`src/shared/validation/providerSchema.ts`)
+- **PII sanitizer** — Sensitive data scrubbing in logs
+
+### Dashboard Pages (23 sections)
+- **Providers** — OAuth, API key, and free provider management with ProviderIcon SVG icons
+- **Combos** — Multi-model combo builder with 4 templates (Free Stack, High Availability, Cost Saver, Balanced) + 13 strategies
+- **Auto-Combo** — Auto-combo engine dashboard with scoring metrics
+- **Analytics** — Token consumption, cost, heatmaps, distributions
+- **Health** — Uptime, memory, latency percentiles, circuit breakers
+- **Logs** — Request, Proxy, Audit, Console (tabbed)
+- **Audit** — Audit trail and compliance logging
+- **Costs** — Cost tracking per provider/model
+- **Limits** — Rate limit monitoring
+- **Cache** — Semantic cache statistics and management
+- **CLI Tools** — One-click configuration for 10+ AI CLI tools
+- **CLI Agents** — Grid of 14+ built-in agents with ProviderIcon and install detection + custom agent registration
+- **Playground** — Test any model with Monaco editor, streaming responses
+- **Media** — Image/video/music generation (DALL-E, FLUX, etc.) + audio transcription (up to 2GB files)
+- **Search Tools** — Search provider configuration and testing
+- **Memory** — Memory system management and visualization
+- **Skills** — Skills framework management and execution
+- **Translator** — Format debugging: playground, chat tester, test bench, live monitor
+- **Settings** — General, Appearance (7 color themes), Security (TLS/CLI fingerprint, IP filter), Routing, Resilience, Advanced
+- **Endpoint** — Unified: Endpoint Proxy, MCP Server, A2A Server, API Endpoints (tabbed)
+- **Onboarding** — Setup wizard for new users
+- **Usage** — Usage history and analytics
+- **API Manager** — API key management with scoped permissions
+
+### Protocol Support
+- **OpenAI-compatible** — `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/transcriptions`, `/v1/audio/speech`, `/v1/moderations`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`
+- **Anthropic** — `/v1/messages`, `/v1/messages/count_tokens`
+- **OpenAI Responses** — `/v1/responses`
+- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
+- **Ollama** — `/v1/api/chat`, `/api/tags`
+- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
+- **MCP** — 25-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **ACP** — Agent Communication Protocol registry and manager
+
+### MCP Server (25 Tools)
+| Category  | Tools |
+|-----------|-------|
+| Core (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` |
+| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
+| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
+
+**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+
+### Provider Categories
+
+**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+
+**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+
+**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
+
+**Custom Providers:** OpenAI-compatible (`openai-compatible-*`) and Anthropic-compatible (`anthropic-compatible-*`) with custom base URLs
+
+### Internationalization
+- 30 languages for UI (all dashboard pages)
+- 30 translated documentation sets in docs/i18n/
+- Language switcher in documentation
+
+## Key Architectural Decisions
+
+1. **OpenAI-compatible API surface:** All incoming requests follow the OpenAI API format. This makes OmniRoute a drop-in replacement for any tool that supports custom OpenAI endpoints.
+
+2. **Provider abstraction via format translators:** Each AI provider has a translator in `open-sse/translator/` that converts between OpenAI format and the provider's native format transparently.
+
+3. **Connection-based provider model:** Providers are stored as "connections" in SQLite. Each connection has an `id`, `provider`, `authType` (oauth/apikey/free), `isActive` flag, and credentials. Multiple connections per provider for multi-account rotation.
+
+4. **Combo system for fallback:** Users create "combos" — ordered lists of `provider/model` pairs. The proxy tries each in order until one succeeds. Supports 13 strategies including auto-combo with self-healing and context-relay for session continuity.
+
+5. **SSE proxy pipeline:** The proxy pipeline is middleware-based: request → auth resolution → rate limiting → circuit breaker → format translation → upstream call → response translation → SSE streaming back to client.
+
+6. **SQLite for persistence:** All state (providers, combos, logs, settings, API keys, memory, skills) stored in a single SQLite database via 21 domain-specific modules. All DB operations go through `src/lib/db/` modules, never raw SQL in routes.
+
+7. **OAuth with PKCE:** OAuth flows use PKCE for security. Token refresh handled by background job (`tokenHealthCheck.ts`).
+
+8. **ProviderIcon component:** Unified icon system using `@lobehub/icons` (130+ SVG) with PNG fallback and generic icon fallback chain. Used on providers, dashboard, and agents pages.
+
+9. **DB architecture:** `localDb.ts` is a re-export layer only — real logic lives in 21 `src/lib/db/` modules with 16 SQL migrations.
+
+10. **Upstream headers:** Custom headers merged in executors after default auth; same header name replaces executor value. Forbidden header names in `src/shared/constants/upstreamHeaders.ts`.
+
+11. **Memory/Skills cross-cutting systems:** Memory and Skills affect the MCP tools, request pipeline, and A2A skills. Memory provides persistent context across sessions; Skills provide extensible tool execution with sandbox isolation.
+
+12. **Domain policy engine:** `src/domain/` contains policy engine modules (policyEngine, comboResolver, costRules, degradation, fallbackPolicy, lockoutPolicy, modelAvailability, providerExpiration, quotaCache, configAudit) that govern routing decisions independently from the pipeline.
+
+13. **Provider constants validated at load:** All provider definitions validated via Zod schemas at module load time (`src/shared/validation/providerSchema.ts`). Invalid providers fail fast.
+
+## Main Flows
+
+### Proxy Request Flow
+1. Client sends OpenAI-format request to `/v1/chat/completions`
+2. API key validation
+3. Model resolution: direct model or combo lookup
+4. For combos: iterate through models with selected strategy
+5. Auth resolution: get credentials for the target provider
+6. Format translation: OpenAI → provider native format
+7. CLI fingerprint matching (if enabled for provider)
+8. Upstream request with circuit breaker and rate limiting
+9. Response translation: provider → OpenAI format
+10. omniModel tag sanitization (strip internal tags)
+11. SSE streaming back to client
+12. Memory extraction (if memory system enabled)
+13. Usage logging and cost calculation
+
+### OAuth Flow
+1. Dashboard initiates `/api/oauth/[provider]/authorize`
+2. User completes OAuth login in browser
+3. Callback hits `/api/oauth/[provider]/exchange`
+4. Tokens stored as a provider connection in SQLite
+5. Background job refreshes tokens before expiry
+
+## Important Notes for LLMs
+
+1. **Two model endpoints exist:** `/api/models` (dashboard, all models) and `/v1/models` (OpenAI-compatible, active only).
+
+2. **Provider IDs vs aliases:** Providers have both an ID (`claude`, `github`) and a short alias (`cc`, `gh`). Models are referenced as `alias/model-name` (e.g., `cc/claude-opus-4-6`).
+
+3. **The `open-sse/` directory is a separate npm workspace** with its own config, handlers, executors, translators, and services.
+
+4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
+
+5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+
+6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+
+7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
+
+8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
+
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+
+10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
+
+11. **Electron desktop app** in `electron/` with main.js and preload.js. Build with `npm run electron:build` (supports Windows, macOS, Linux).
+
+12. **Pricing data** syncs from LiteLLM via `src/lib/pricingSync.ts`. Use `sync_pricing` MCP tool or API endpoint.
+
+13. **Memory system** in `src/lib/memory/` provides extraction, injection, retrieval, summarization, and persistent store. Exposed via MCP memory tools and `/api/memory/ API.
+
+14. **Skills system** in `src/lib/skills/` provides registry, executor, sandbox isolation, built-in skills, custom skill support, request interception, and context injection. Exposed via MCP skill tools and `/api/skills/` API.
+
+15. **Zod v4** is used for all validation. Import from `zod` package. Provider schemas validated at module load time.
+
+16. **Context Relay** strategy (`context-relay`) is split across two layers: `combo.ts` decides if a handoff should be generated after a successful turn; `chat.ts` injects the handoff only after account resolution. Handoff data lives in `context_handoffs` SQLite table. Config: `handoffThreshold`, `handoffModel`, `handoffProviders`.
+
+17. **Proxy enforcement** is now comprehensive: token health checks resolve proxy per connection, provider validation wraps in `runWithProxyContext`, and proxy dispatchers use `undici.fetch()` instead of the Node built-in `fetch()` to avoid dispatcher incompatibilities on Node 22.
+
+18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+
+## Links
+
+- Repository: https://github.com/diegosouzapw/OmniRoute
+- Website: https://omniroute.online
+- npm: https://www.npmjs.com/package/omniroute
+- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
+- Documentation: See `/docs/` directory

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

@@ -1,752 +0,0 @@
-# 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** — Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0.
-
-The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](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
-
-Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`:
-
-```bash
-curl http://localhost:20128/.well-known/agent.json
-```
-
-**Response:**
-
-```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
-
-Send a message to a skill and receive 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 Python hello world"}],
-      "metadata": {"model": "auto", "combo": "fast-coding"}
-    }
-  }'
-```
-
-**Response:**
-
-```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
-
-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":"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`
-
-Routes prompts through OmniRoute's intelligent pipeline with full observability.
-
-**Parameters (in `metadata`):**
-
-| Parameter | Type     | Default      | Description                                                                              |
-| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- |
-| `model`   | `string` | `"auto"`     | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`)                                 |
-| `combo`   | `string` | active combo | Specific combo to route through                                                          |
-| `budget`  | `number` | none         | Maximum cost in USD for this request                                                     |
-| `role`    | `string` | none         | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` |
-
-**Returns:**
-
-| Field                          | Description                                               |
-| ------------------------------ | --------------------------------------------------------- |
-| `artifacts[].content`          | The LLM response text                                     |
-| `metadata.routing_explanation` | Human-readable explanation of routing decision            |
-| `metadata.cost_envelope`       | Estimated vs actual cost with currency                    |
-| `metadata.resilience_trace`    | Array of events (primary_selected, fallback_needed, etc.) |
-| `metadata.policy_verdict`      | Whether the request was allowed and why                   |
-
-### `quota-management`
-
-Answers natural-language queries about provider quotas.
-
-**Query types (inferred from message content):**
-
-| Query Pattern                                  | Response Type                                            |
-| ---------------------------------------------- | -------------------------------------------------------- |
-| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota                      |
-| Contains `"free"`, `"suggest"`                 | Lists free combos or suggests free-tier providers        |
-| Default                                        | Full quota summary with warnings for low-quota providers |
-
----
-
-## Task Lifecycle
-
-```
-submitted ──→ working ──→ completed
-                       ──→ failed
-              ──────────→ cancelled
-```
-
-| State       | Description                                           |
-| ----------- | ----------------------------------------------------- |
-| `submitted` | Task created, queued for execution                    |
-| `working`   | Skill handler is executing                            |
-| `completed` | Execution succeeded, artifacts available              |
-| `failed`    | Execution failed or task expired (TTL: 5 min default) |
-| `cancelled` | Cancelled by client via `tasks/cancel`                |
-
-- Terminal states: `completed`, `failed`, `cancelled` (no further transitions)
-- Expired tasks in `submitted` or `working` are auto-marked as `failed`
-- Tasks are garbage-collected after 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
-
-An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent.
-
-```python
-def coding_pipeline(task: str):
-    # Step 1: Generate code via OmniRoute A2A
-    code_result = a2a_send("smart-routing", [
-        {"role": "user", "content": f"Write production-quality code: {task}"}
-    ], metadata={"model": "auto", "role": "coding"})
-    code = code_result["artifacts"][0]["content"]
-
-    # Step 2: Review the code via OmniRoute A2A (different model)
-    review_result = a2a_send("smart-routing", [
-        {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"}
-    ], metadata={"model": "auto", "role": "review"})
-    review = review_result["artifacts"][0]["content"]
-
-    # Step 3: Check costs
-    print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}")
-    print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}")
-
-    return {"code": code, "review": review}
-```
-
-### 💡 Use Case 2: Quota-Aware Agent Swarm
-
-Multiple agents share quota through OmniRoute, using the quota skill to coordinate.
-
-```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
-
-A monitoring agent streams responses and displays progress in real-time.
-
-```typescript
-async function streamingDashboard(prompt: string) {
-  const response = await fetch(`${BASE_URL}/a2a`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` },
-    body: JSON.stringify({
-      jsonrpc: "2.0",
-      id: "dash-1",
-      method: "message/stream",
-      params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] },
-    }),
-  });
-
-  let totalChunks = 0;
-  const reader = response.body!.getReader();
-  const decoder = new TextDecoder();
-
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-
-    for (const line of decoder.decode(value).split("\n")) {
-      if (line.startsWith("data: ")) {
-        const event = JSON.parse(line.slice(6));
-        const state = event.params.task.state;
-
-        if (state === "working" && event.params.chunk) {
-          totalChunks++;
-          process.stdout.write(
-            `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...`
-          );
-        }
-        if (state === "completed") {
-          const meta = event.params.metadata;
-          console.log(
-            `\n✅ Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}`
-          );
-        }
-        if (state === "failed") {
-          console.error(`\n❌ Failed: ${event.params.metadata?.error}`);
-        }
-      }
-    }
-  }
-}
-```
-
-### 🔁 Use Case 4: Task Polling Pattern
-
-For long-running tasks, poll the task status instead of waiting synchronously.
-
-```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
-
-| Code   | Constant                 | Meaning                                  |
-| ------ | ------------------------ | ---------------------------------------- |
-| -32700 | —                        | Parse error (invalid JSON)               |
-| -32600 | `INVALID_REQUEST`        | Invalid JSON-RPC request or unauthorized |
-| -32601 | `METHOD_NOT_FOUND`       | Unknown method or skill                  |
-| -32602 | `INVALID_PARAMS`         | Missing or invalid parameters            |
-| -32603 | `INTERNAL_ERROR`         | Skill execution failed                   |
-| -32001 | `TASK_NOT_FOUND`         | Task ID not found                        |
-| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task           |
-| -32003 | `UNAUTHORIZED`           | Invalid or missing API key               |
-| -32004 | `BUDGET_EXCEEDED`        | Request exceeds configured budget        |
-| -32005 | `PROVIDER_UNAVAILABLE`   | No available providers                   |
-
----
-
-## Authentication
-
-All `/a2a` requests require a Bearer token via the `Authorization` header:
-
-```
-Authorization: Bearer YOUR_OMNIROUTE_API_KEY
-```
-
-If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed.
-
----
-
-## File Structure
-
-```
-src/lib/a2a/
-├── taskManager.ts         # Task lifecycle (create/update/cancel/list), TTL, cleanup
-├── taskExecution.ts       # Generic task executor with state management
-├── streaming.ts           # SSE stream formatting, heartbeat, chunk/completion events
-├── routingLogger.ts       # Routing decision logger (stats, history, retention)
-└── skills/
-    ├── smartRouting.ts    # Smart routing skill (routes via /v1/chat/completions)
-    └── quotaManagement.ts # Quota management skill (natural-language quota queries)
-
-src/app/a2a/
-└── route.ts               # Next.js API route handler (JSON-RPC 2.0 dispatch)
-
-open-sse/mcp-server/
-└── schemas/a2a.ts         # Zod schemas (AgentCard, Task, JSON-RPC, SSE events)
-```
-
----
-
-## Comparison: MCP vs A2A
-
-| Feature           | MCP Server                   | A2A Server                                        |
-| ----------------- | ---------------------------- | ------------------------------------------------- |
-| **Protocol**      | Model Context Protocol       | Agent-to-Agent Protocol v0.3                      |
-| **Transport**     | stdio / HTTP                 | HTTP (JSON-RPC 2.0)                               |
-| **Discovery**     | Tool listing via MCP         | `/.well-known/agent.json`                         |
-| **Granularity**   | 16 individual tools          | 2 high-level skills                               |
-| **Best for**      | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI)           |
-| **Streaming**     | Not supported                | SSE via `message/stream`                          |
-| **Task tracking** | No                           | Full lifecycle (submitted → completed)            |
-| **Observability** | Audit log per tool call      | Cost envelope + resilience trace + policy verdict |
-
----
-
-## الرخصة
-
-Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) — MIT License.

docs/i18n/bg/CLAUDE.md

@@ -0,0 +1,233 @@
+# CLAUDE.md — AI Agent Session Bootstrap (Български)
+
+🌐 **Languages:** 🇺🇸 [English](../../../CLAUDE.md) · 🇸🇦 [ar](../ar/CLAUDE.md) · 🇧🇬 [bg](../bg/CLAUDE.md) · 🇧🇩 [bn](../bn/CLAUDE.md) · 🇨🇿 [cs](../cs/CLAUDE.md) · 🇩🇰 [da](../da/CLAUDE.md) · 🇩🇪 [de](../de/CLAUDE.md) · 🇪🇸 [es](../es/CLAUDE.md) · 🇮🇷 [fa](../fa/CLAUDE.md) · 🇫🇮 [fi](../fi/CLAUDE.md) · 🇫🇷 [fr](../fr/CLAUDE.md) · 🇮🇳 [gu](../gu/CLAUDE.md) · 🇮🇱 [he](../he/CLAUDE.md) · 🇮🇳 [hi](../hi/CLAUDE.md) · 🇭🇺 [hu](../hu/CLAUDE.md) · 🇮🇩 [id](../id/CLAUDE.md) · 🇮🇹 [it](../it/CLAUDE.md) · 🇯🇵 [ja](../ja/CLAUDE.md) · 🇰🇷 [ko](../ko/CLAUDE.md) · 🇮🇳 [mr](../mr/CLAUDE.md) · 🇲🇾 [ms](../ms/CLAUDE.md) · 🇳🇱 [nl](../nl/CLAUDE.md) · 🇳🇴 [no](../no/CLAUDE.md) · 🇵🇭 [phi](../phi/CLAUDE.md) · 🇵🇱 [pl](../pl/CLAUDE.md) · 🇵🇹 [pt](../pt/CLAUDE.md) · 🇧🇷 [pt-BR](../pt-BR/CLAUDE.md) · 🇷🇴 [ro](../ro/CLAUDE.md) · 🇷🇺 [ru](../ru/CLAUDE.md) · 🇸🇰 [sk](../sk/CLAUDE.md) · 🇸🇪 [sv](../sv/CLAUDE.md) · 🇰🇪 [sw](../sw/CLAUDE.md) · 🇮🇳 [ta](../ta/CLAUDE.md) · 🇮🇳 [te](../te/CLAUDE.md) · 🇹🇭 [th](../th/CLAUDE.md) · 🇹🇷 [tr](../tr/CLAUDE.md) · 🇺🇦 [uk-UA](../uk-UA/CLAUDE.md) · 🇵🇰 [ur](../ur/CLAUDE.md) · 🇻🇳 [vi](../vi/CLAUDE.md) · 🇨🇳 [zh-CN](../zh-CN/CLAUDE.md)
+
+---
+
+> Quick-start context for AI coding agents. For deep architecture details, see `AGENTS.md`.
+> For contribution workflow, see `CONTRIBUTING.md`.
+
+## Бърз старт
+
+```bash
+npm install                    # Install deps (auto-generates .env from .env.example)
+npm run dev                    # Dev server at http://localhost:20128
+npm run build                  # Production build (Next.js 16 standalone)
+npm run lint                   # ESLint (0 errors expected; warnings are pre-existing)
+npm run typecheck:core         # TypeScript check (should be clean)
+npm run typecheck:noimplicit:core  # Strict check (no implicit any)
+npm run test:coverage          # Unit tests + coverage gate (60% min)
+npm run check                  # lint + test combined
+npm run check:cycles           # Detect circular dependencies
+```
+
+### Running a Single Test
+
+```bash
+# Node.js native test runner (most tests)
+node --import tsx/esm --test tests/unit/your-file.test.mjs
+
+# Vitest (MCP server, autoCombo, cache)
+npm run test:vitest
+```
+
+---
+
+## Преглед
+
+**OmniRoute** — unified AI proxy/router. One endpoint, 100+ LLM providers, auto-fallback.
+
+| Layer           | Location                 | Purpose                                    |
+| --------------- | ------------------------ | ------------------------------------------ |
+| API Routes      | `src/app/api/v1/`        | Next.js App Router — entry points          |
+| Handlers        | `open-sse/handlers/`     | Request processing (chat, embeddings, etc) |
+| Executors       | `open-sse/executors/`    | Provider-specific HTTP dispatch            |
+| Translators     | `open-sse/translator/`   | Format conversion (OpenAI↔Claude↔Gemini)   |
+| Services        | `open-sse/services/`     | Combo routing, rate limits, caching, etc   |
+| Database        | `src/lib/db/`            | SQLite domain modules (22 files)           |
+| Domain/Policy   | `src/domain/`            | Policy engine, cost rules, fallback logic  |
+| MCP Server      | `open-sse/mcp-server/`   | 25 tools, 3 transports, 10 scopes          |
+| A2A Server      | `src/lib/a2a/`           | JSON-RPC 2.0 agent protocol                |
+| Skills          | `src/lib/skills/`        | Extensible skill framework                 |
+| Memory          | `src/lib/memory/`        | Persistent conversational memory           |
+| UI Components   | `src/shared/components/` | React components (Tailwind CSS v4)         |
+| Provider Consts | `src/shared/constants/`  | Provider registry (Zod-validated)          |
+| Validation      | `src/shared/validation/` | Zod v4 schemas                             |
+| Tests           | `tests/`                 | Unit, integration, e2e, security, load     |
+
+### Monorepo Layout
+
+```
+OmniRoute/              # Root package
+├── src/                # Next.js 16 app (TypeScript)
+├── open-sse/           # @omniroute/open-sse workspace (streaming engine)
+├── electron/           # Desktop app (Electron)
+├── tests/              # All test suites
+├── docs/               # Documentation
+└── bin/                # CLI entry point
+```
+
+---
+
+## Request Pipeline (Abbreviated)
+
+```
+Client → /v1/chat/completions (Next.js route)
+  → CORS → Zod validation → auth? → policy check → prompt injection guard
+  → handleChatCore() [open-sse/handlers/chatCore.ts]
+    → cache check → rate limit → combo routing?
+      → resolveComboTargets() → handleSingleModel() per target
+    → translateRequest() → getExecutor() → executor.execute()
+      → fetch() upstream → retry w/ backoff
+    → response translation → SSE stream or JSON
+```
+
+---
+
+## Key Conventions
+
+### Code Style
+
+- **2 spaces**, semicolons, double quotes, 100 char width, es5 trailing commas
+- **Imports**: external → internal (`@/`, `@omniroute/open-sse`) → relative
+- **Naming**: files=camelCase/kebab, components=PascalCase, constants=UPPER_SNAKE
+
+### Database Access
+
+- **Always** go through `src/lib/db/` domain modules
+- **Never** write raw SQL in routes or handlers
+- **Never** add logic to `src/lib/localDb.ts` (re-export layer only)
+- **Never** barrel-import from `localDb.ts` — import specific `db/` modules
+- DB singleton: `getDbInstance()` from `src/lib/db/core.ts` (WAL journaling)
+- Migrations: `src/lib/db/migrations/` — 21 versioned SQL files
+
+### Error Handling
+
+- try/catch with specific error types, log with pino context
+- Never swallow errors in SSE streams — use abort signals
+- Return proper HTTP status codes (4xx/5xx)
+
+### Сигурност
+
+- **Never** commit secrets/credentials
+- **Never** use `eval()`, `new Function()`, or implied eval
+- Validate all inputs with Zod schemas
+- Encrypt credentials at rest (AES-256-GCM)
+
+---
+
+## Common Modification Scenarios
+
+### Adding a New Provider
+
+1. Register in `src/shared/constants/providers.ts` (Zod-validated at load)
+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. Register models in `open-sse/config/providerRegistry.ts`
+6. Write tests in `tests/unit/` (registration, translation, error handling)
+
+### Adding a New API Route
+
+1. Create directory under `src/app/api/v1/your-route/`
+2. Create `route.ts` with `GET`/`POST` handlers
+3. Follow pattern: CORS → Zod body validation → optional auth → handler delegation
+4. Handler goes in `open-sse/handlers/` (import from there, not inline)
+5. Add tests
+
+### Adding a New DB Module
+
+1. Create `src/lib/db/yourModule.ts`
+2. Import `getDbInstance` from `./core.ts`
+3. Export CRUD functions for your domain table(s)
+4. Add migration in `src/lib/db/migrations/` if new tables needed
+5. Re-export from `src/lib/localDb.ts` (add to the re-export list only)
+6. Write tests
+
+### Adding a New MCP Tool
+
+1. Add tool definition in `open-sse/mcp-server/tools/`
+2. Define Zod input schema + async handler
+3. Register in tool set (wired by `createMcpServer()`)
+4. Assign to appropriate scope(s)
+5. Write tests (tool invocation logged to `mcp_audit` table)
+
+### Adding a New A2A Skill
+
+1. Create skill in `src/lib/a2a/skills/`
+2. Skill receives task context (messages, metadata) → returns structured result
+3. Register in the DB-backed skill registry
+4. Write tests
+
+---
+
+## Testing Cheat Sheet
+
+| What                    | Command                                                 |
+| ----------------------- | ------------------------------------------------------- |
+| All tests               | `npm run test:all`                                      |
+| Unit tests              | `npm run test:unit`                                     |
+| Single file             | `node --import tsx/esm --test tests/unit/file.test.mjs` |
+| Vitest (MCP, autoCombo) | `npm run test:vitest`                                   |
+| E2E (Playwright)        | `npm run test:e2e`                                      |
+| Protocol E2E (MCP+A2A)  | `npm run test:protocols:e2e`                            |
+| Ecosystem               | `npm run test:ecosystem`                                |
+| Coverage gate           | `npm run test:coverage` (60% min all metrics)           |
+| Coverage report         | `npm run coverage:report`                               |
+
+**PR rule**: If you change production code in `src/`, `open-sse/`, `electron/`, or `bin/`,
+you must include or update tests in the same PR.
+
+**Test layer preference**: unit first → integration (multi-module or DB state) → e2e (UI/workflow only). Encode bug reproductions as automated tests before or alongside the fix.
+
+---
+
+## Git Workflow
+
+```bash
+# Never commit directly to main
+git checkout -b feat/your-feature
+# ... make changes ...
+git commit -m "feat: describe your change"
+git push -u origin feat/your-feature
+```
+
+**Branch prefixes**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`
+
+**Commit format** ([Conventional Commits](https://www.conventionalcommits.org/)):
+
+```
+feat: add circuit breaker for provider calls
+fix: resolve JWT secret validation edge case
+docs: update AGENTS.md with pipeline internals
+test: add MCP tool unit tests
+refactor(db): consolidate rate limit tables
+```
+
+**Scopes**: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`,
+`memory`, `skills`.
+
+---
+
+## Environment
+
+- **Runtime**: Node.js ≥18 <24, ES Modules
+- **TypeScript**: 5.9, target ES2022, module esnext, resolution bundler
+- **Path aliases**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`
+- **Default port**: 20128 (API + dashboard on same port)
+- **Data directory**: `DATA_DIR` env var, defaults to `~/.omniroute/`
+- **Key env vars**: `PORT`, `JWT_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`
+
+---
+
+## Hard Rules (Never Violate)
+
+1. Never commit secrets or credentials
+2. Never add logic to `localDb.ts`
+3. Never use `eval()` / `new Function()` / implied eval
+4. Never commit directly to `main`
+5. Never write raw SQL in routes — use `src/lib/db/` modules
+6. Never silently swallow errors in SSE streams
+7. Always validate inputs with Zod schemas
+8. Always include tests when changing production code
+9. Coverage must stay ≥60% (statements, lines, functions, branches)

docs/i18n/bg/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct (Български)
+
+🌐 **Languages:** 🇺🇸 [English](../../../CODE_OF_CONDUCT.md) · 🇸🇦 [ar](../ar/CODE_OF_CONDUCT.md) · 🇧🇬 [bg](../bg/CODE_OF_CONDUCT.md) · 🇧🇩 [bn](../bn/CODE_OF_CONDUCT.md) · 🇨🇿 [cs](../cs/CODE_OF_CONDUCT.md) · 🇩🇰 [da](../da/CODE_OF_CONDUCT.md) · 🇩🇪 [de](../de/CODE_OF_CONDUCT.md) · 🇪🇸 [es](../es/CODE_OF_CONDUCT.md) · 🇮🇷 [fa](../fa/CODE_OF_CONDUCT.md) · 🇫🇮 [fi](../fi/CODE_OF_CONDUCT.md) · 🇫🇷 [fr](../fr/CODE_OF_CONDUCT.md) · 🇮🇳 [gu](../gu/CODE_OF_CONDUCT.md) · 🇮🇱 [he](../he/CODE_OF_CONDUCT.md) · 🇮🇳 [hi](../hi/CODE_OF_CONDUCT.md) · 🇭🇺 [hu](../hu/CODE_OF_CONDUCT.md) · 🇮🇩 [id](../id/CODE_OF_CONDUCT.md) · 🇮🇹 [it](../it/CODE_OF_CONDUCT.md) · 🇯🇵 [ja](../ja/CODE_OF_CONDUCT.md) · 🇰🇷 [ko](../ko/CODE_OF_CONDUCT.md) · 🇮🇳 [mr](../mr/CODE_OF_CONDUCT.md) · 🇲🇾 [ms](../ms/CODE_OF_CONDUCT.md) · 🇳🇱 [nl](../nl/CODE_OF_CONDUCT.md) · 🇳🇴 [no](../no/CODE_OF_CONDUCT.md) · 🇵🇭 [phi](../phi/CODE_OF_CONDUCT.md) · 🇵🇱 [pl](../pl/CODE_OF_CONDUCT.md) · 🇵🇹 [pt](../pt/CODE_OF_CONDUCT.md) · 🇧🇷 [pt-BR](../pt-BR/CODE_OF_CONDUCT.md) · 🇷🇴 [ro](../ro/CODE_OF_CONDUCT.md) · 🇷🇺 [ru](../ru/CODE_OF_CONDUCT.md) · 🇸🇰 [sk](../sk/CODE_OF_CONDUCT.md) · 🇸🇪 [sv](../sv/CODE_OF_CONDUCT.md) · 🇰🇪 [sw](../sw/CODE_OF_CONDUCT.md) · 🇮🇳 [ta](../ta/CODE_OF_CONDUCT.md) · 🇮🇳 [te](../te/CODE_OF_CONDUCT.md) · 🇹🇭 [th](../th/CODE_OF_CONDUCT.md) · 🇹🇷 [tr](../tr/CODE_OF_CONDUCT.md) · 🇺🇦 [uk-UA](../uk-UA/CODE_OF_CONDUCT.md) · 🇵🇰 [ur](../ur/CODE_OF_CONDUCT.md) · 🇻🇳 [vi](../vi/CODE_OF_CONDUCT.md) · 🇨🇳 [zh-CN](../zh-CN/CODE_OF_CONDUCT.md)
+
+---
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

docs/i18n/bg/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../CONTRIBUTING.md) · 🇸🇦 [ar](../ar/CONTRIBUTING.md) · 🇧🇬 [bg](../bg/CONTRIBUTING.md) · 🇧🇩 [bn](../bn/CONTRIBUTING.md) · 🇨🇿 [cs](../cs/CONTRIBUTING.md) · 🇩🇰 [da](../da/CONTRIBUTING.md) · 🇩🇪 [de](../de/CONTRIBUTING.md) · 🇪🇸 [es](../es/CONTRIBUTING.md) · 🇮🇷 [fa](../fa/CONTRIBUTING.md) · 🇫🇮 [fi](../fi/CONTRIBUTING.md) · 🇫🇷 [fr](../fr/CONTRIBUTING.md) · 🇮🇳 [gu](../gu/CONTRIBUTING.md) · 🇮🇱 [he](../he/CONTRIBUTING.md) · 🇮🇳 [hi](../hi/CONTRIBUTING.md) · 🇭🇺 [hu](../hu/CONTRIBUTING.md) · 🇮🇩 [id](../id/CONTRIBUTING.md) · 🇮🇹 [it](../it/CONTRIBUTING.md) · 🇯🇵 [ja](../ja/CONTRIBUTING.md) · 🇰🇷 [ko](../ko/CONTRIBUTING.md) · 🇮🇳 [mr](../mr/CONTRIBUTING.md) · 🇲🇾 [ms](../ms/CONTRIBUTING.md) · 🇳🇱 [nl](../nl/CONTRIBUTING.md) · 🇳🇴 [no](../no/CONTRIBUTING.md) · 🇵🇭 [phi](../phi/CONTRIBUTING.md) · 🇵🇱 [pl](../pl/CONTRIBUTING.md) · 🇵🇹 [pt](../pt/CONTRIBUTING.md) · 🇧🇷 [pt-BR](../pt-BR/CONTRIBUTING.md) · 🇷🇴 [ro](../ro/CONTRIBUTING.md) · 🇷🇺 [ru](../ru/CONTRIBUTING.md) · 🇸🇰 [sk](../sk/CONTRIBUTING.md) · 🇸🇪 [sv](../sv/CONTRIBUTING.md) · 🇰🇪 [sw](../sw/CONTRIBUTING.md) · 🇮🇳 [ta](../ta/CONTRIBUTING.md) · 🇮🇳 [te](../te/CONTRIBUTING.md) · 🇹🇭 [th](../th/CONTRIBUTING.md) · 🇹🇷 [tr](../tr/CONTRIBUTING.md) · 🇺🇦 [uk-UA](../uk-UA/CONTRIBUTING.md) · 🇵🇰 [ur](../ur/CONTRIBUTING.md) · 🇻🇳 [vi](../vi/CONTRIBUTING.md) · 🇨🇳 [zh-CN](../zh-CN/CONTRIBUTING.md)
 
 ---
 
@@ -123,7 +123,7 @@ Scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`,
 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/your-file.test.ts
 
 # Vitest (MCP server, autoCombo, cache)
 npm run test:vitest
@@ -137,7 +137,7 @@ npm run test:protocols:e2e
 # Ecosystem compatibility tests
 npm run test:ecosystem
 
-# Coverage (55% min statements/lines/functions; 60% branches)
+# Coverage (60% min statements/lines/functions/branches)
 npm run test:coverage
 npm run coverage:report
 
@@ -149,10 +149,22 @@ npm run check
 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

docs/i18n/bg/GEMINI.md

@@ -0,0 +1,25 @@
+# Security and Cleanliness Rules for AI Assistants (Български)
+
+🌐 **Languages:** 🇺🇸 [English](../../../GEMINI.md) · 🇸🇦 [ar](../ar/GEMINI.md) · 🇧🇬 [bg](../bg/GEMINI.md) · 🇧🇩 [bn](../bn/GEMINI.md) · 🇨🇿 [cs](../cs/GEMINI.md) · 🇩🇰 [da](../da/GEMINI.md) · 🇩🇪 [de](../de/GEMINI.md) · 🇪🇸 [es](../es/GEMINI.md) · 🇮🇷 [fa](../fa/GEMINI.md) · 🇫🇮 [fi](../fi/GEMINI.md) · 🇫🇷 [fr](../fr/GEMINI.md) · 🇮🇳 [gu](../gu/GEMINI.md) · 🇮🇱 [he](../he/GEMINI.md) · 🇮🇳 [hi](../hi/GEMINI.md) · 🇭🇺 [hu](../hu/GEMINI.md) · 🇮🇩 [id](../id/GEMINI.md) · 🇮🇹 [it](../it/GEMINI.md) · 🇯🇵 [ja](../ja/GEMINI.md) · 🇰🇷 [ko](../ko/GEMINI.md) · 🇮🇳 [mr](../mr/GEMINI.md) · 🇲🇾 [ms](../ms/GEMINI.md) · 🇳🇱 [nl](../nl/GEMINI.md) · 🇳🇴 [no](../no/GEMINI.md) · 🇵🇭 [phi](../phi/GEMINI.md) · 🇵🇱 [pl](../pl/GEMINI.md) · 🇵🇹 [pt](../pt/GEMINI.md) · 🇧🇷 [pt-BR](../pt-BR/GEMINI.md) · 🇷🇴 [ro](../ro/GEMINI.md) · 🇷🇺 [ru](../ru/GEMINI.md) · 🇸🇰 [sk](../sk/GEMINI.md) · 🇸🇪 [sv](../sv/GEMINI.md) · 🇰🇪 [sw](../sw/GEMINI.md) · 🇮🇳 [ta](../ta/GEMINI.md) · 🇮🇳 [te](../te/GEMINI.md) · 🇹🇭 [th](../th/GEMINI.md) · 🇹🇷 [tr](../tr/GEMINI.md) · 🇺🇦 [uk-UA](../uk-UA/GEMINI.md) · 🇵🇰 [ur](../ur/GEMINI.md) · 🇻🇳 [vi](../vi/GEMINI.md) · 🇨🇳 [zh-CN](../zh-CN/GEMINI.md)
+
+---
+
+## 1. File Placement & Organization
+
+- **Test Files**: ALL unit tests, integration tests, ecosystem tests, or Vitest files MUST strictly be placed within the `tests/` directory (e.g., `tests/unit/`, `tests/integration/`). NEVER create test files in the project root (`/`).
+- **Scripts and Utilities**: ALL maintenance, debugging, generation, or experimental scripts (`.cjs`, `.mjs`, `.js`, `.ts`) MUST be placed strictly inside the `scripts/` directory or `scripts/scratch/` for temporary one-offs. NEVER dump loose scripts in the project root (`/`).
+
+**The Project Root MUST ONLY CONTAIN:**
+
+- Configuration files (`vitest.config.ts`, `next.config.mjs`, `eslint.config.mjs`, etc.)
+- Dependency files (`package.json`, `package-lock.json`)
+- Documentation files (`README.md`, `CHANGELOG.md`, `AGENTS.md`)
+- CI/CD files and ignore definitions (`.gitignore`, `.dockerignore`)
+
+When creating _any_ validation tests or one-off logic scripts, default to using `scripts/scratch/` or the `tests/unit/` directories according to your goals. Do not pollute the `/` root context.
+
+## 2. VPS Dashboard Credentials
+
+| Environment | URL                       | Password |
+| ----------- | ------------------------- | -------- |
+| Local VPS   | http://192.168.0.15:20128 | 123456   |

docs/i18n/bg/README.md

@@ -1,12 +1,12 @@
 # 🚀 OmniRoute — The Free AI Gateway (Български)
 
-🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇹🇷 [tr](../tr/README.md)
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md)
 
 ---
 
 ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
 
-_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
+_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
 
 **Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
 
@@ -247,7 +247,9 @@ Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve
 - **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention
 - **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI
 - **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next
-- **Custom Combos** — Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random)
+- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)
+- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets
+- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use
 - **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
 
 </details>
@@ -259,7 +261,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If
 
 **How OmniRoute solves it:**
 
-- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 60+ providers
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers
 - **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
 - **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+
 - **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE
@@ -326,12 +328,13 @@ AI providers can become unstable, return 5xx errors, or hit temporary rate limit
 
 **How OmniRoute solves it:**
 
-- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks
-- **Exponential Backoff** — Progressive retry delays
+- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps
+- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff
+- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown
+- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically
 - **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms
 - **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention
-- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain
-- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
+- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency
 
 </details>
 
@@ -345,7 +348,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code..
 - **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
 - **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection
 - **Onboarding Wizard** — Guided 4-step setup for first-time users
-- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 60+ providers
+- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers
 
 </details>
 
@@ -389,10 +392,10 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w
 
 - **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console
 - **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter
-- **SQLite Proxy Logs** — Persistent logs that survive server restarts
+- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite
 - **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)
 - **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing
-- **File-Based Logging with Rotation** — App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count
+- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries
 - **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.
 
 </details>
@@ -472,7 +475,7 @@ As request volume grows, without caching the same questions generate duplicate c
 - **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency
 - **Request Idempotency** — 5s deduplication window for identical requests
 - **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking
-- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence
+- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience
 - **API Key Validation Cache** — 3-tier cache for production performance
 - **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
 
@@ -490,6 +493,7 @@ Developers who want all responses in a specific language, with a specific tone,
 - **9 Routing Strategies** — Global strategies that determine how requests are distributed
 - **Wildcard Router** — `provider/*` patterns route dynamically to any provider
 - **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
 - **Provider Toggle** — Enable/disable all connections for a provider with one click
 - **Blocked Providers** — Exclude specific providers from `/v1/models` listing
 
@@ -568,8 +572,8 @@ Teams need quick runtime changes during incidents or cost events.
 **How OmniRoute solves it:**
 
 - Switch combo activation directly from MCP dashboard
-- Apply resilience profiles from pre-defined policy packs
-- Reset circuit breaker state from the same operations panel
+- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page
+- Review live provider breaker state from the Health dashboard
 
 </details>
 
@@ -677,13 +681,26 @@ Teams lose velocity when stitching multiple ad-hoc services and scripts.
 
 </details>
 
+<details>
+<summary><b>📚 31. "My long sessions crash with 'context_length_exceeded' limits"</b></summary>
+
+During deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.
+
+**How OmniRoute solves it:**
+
+- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.
+- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.
+- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.
+
+</details>
+
 ### Example Playbooks (Integrated Use Cases)
 
 **Playbook A: Maximize paid subscription + cheap backup**
 
 ```txt
 Combo: "maximize-claude"
-  1. cc/claude-opus-4-6
+  1. cc/claude-opus-4-7
   2. glm/glm-4.7
   3. if/kimi-k2-thinking
 
@@ -707,7 +724,7 @@ Outcome: stable free coding workflow
 
 ```txt
 Combo: "always-on"
-  1. cc/claude-opus-4-6
+  1. cc/claude-opus-4-7
   2. cx/gpt-5.2-codex
   3. glm/glm-4.7
   4. minimax/MiniMax-M2.1
@@ -762,6 +779,15 @@ omniroute
 
 Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
 
+#### Arch Linux (AUR)
+
+Arch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:
+
+```bash
+yay -S omniroute-bin
+systemctl --user enable --now omniroute.service
+```
+
 | Command                 | Description                                                 |
 | ----------------------- | ----------------------------------------------------------- |
 | `omniroute`             | Start server (`PORT=20128`, API and dashboard on same port) |
@@ -778,22 +804,40 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
 # Dashboard: http://localhost:20129
 ```
 
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command                  | Action                                                                              |
+| ------------------------ | ----------------------------------------------------------------------------------- |
+| `npm run uninstall`      | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`.  |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
 ### Long-Running Streaming Timeouts
 
 For most deployments, you only need:
 
-| Variable                 | Default                       | Purpose                                                                                                                     |
-| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `REQUEST_TIMEOUT_MS`     | `600000`                      | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |
-| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream                                                 |
+| Variable                 | Default                       | Purpose                                                                                                                                      |
+| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `REQUEST_TIMEOUT_MS`     | `600000`                      | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |
+| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream                                                                  |
 
 Backward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.
 
+For Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.
+
+For third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default
+`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,
+only forwards client-provided `cache_control` markers. If the request does not include
+`cache_control`, OmniRoute does not inject bridge-owned markers.
+
 Advanced overrides are available if you need finer control:
 
 | Variable                                 | Default                                    | Purpose                                                              |
 | ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |
-| `FETCH_TIMEOUT_MS`                       | inherits `REQUEST_TIMEOUT_MS`              | Total upstream request timeout used by the main fetch abort signal   |
+| `FETCH_TIMEOUT_MS`                       | inherits `REQUEST_TIMEOUT_MS`              | Upstream response-start timeout used until response headers arrive   |
 | `FETCH_HEADERS_TIMEOUT_MS`               | inherits `FETCH_TIMEOUT_MS`                | Undici time limit for receiving upstream response headers            |
 | `FETCH_BODY_TIMEOUT_MS`                  | inherits `FETCH_TIMEOUT_MS`                | Undici time limit between upstream body chunks (`0` disables it)     |
 | `FETCH_CONNECT_TIMEOUT_MS`               | `30000`                                    | Undici TCP connect timeout                                           |
@@ -805,6 +849,8 @@ Advanced overrides are available if you need finer control:
 | `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000`                                     | Keep-alive timeout on the API bridge server                          |
 | `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS`    | `0`                                        | Socket inactivity timeout on the API bridge server (`0` disables it) |
 
+For streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).
+
 If you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy
 timeouts are also higher than your OmniRoute stream/fetch timeouts.
 
@@ -958,7 +1004,7 @@ do_install() {
 #!/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}"
+export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
 mkdir -p "${DATA_DIR}"
 exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
 EOF
@@ -1061,7 +1107,7 @@ volumes:
 | Image                    | Tag      | Size   | Description           |
 | ------------------------ | -------- | ------ | --------------------- |
 | `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |
-| `diegosouzapw/omniroute` | `1.0.3`  | ~250MB | Current version       |
+| `diegosouzapw/omniroute` | `3.6.2`  | ~250MB | Current version       |
 
 ---
 
@@ -1308,7 +1354,32 @@ Then in `/dashboard/media` → **Transcription** tab: upload any audio or video
 
 ## 💡 Key Features
 
-OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
+OmniRoute v3.6 is built as an operational platform, not just a relay proxy.
+
+### 🆕 New — v3.6.x Highlights (Apr 2026)
+
+| Feature                            | What It Does                                                                                                                                      |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🌐 **V1 WebSocket Bridge**         | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie)      |
+| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling                            |
+| 🧠 **GLM Thinking (glmt) Preset**  | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API        |
+| 🔢 **Hybrid Token Counting**       | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing                   |
+| 🌱 **Model Alias Auto-Seed**       | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches                                                                |
+| 🛡️ **Safe Outbound Fetch**         | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |
+| ⏳ **Wait For Cooldown**           | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec`             |
+| 🔍 **Runtime Env Validation**      | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types                                  |
+| 📋 **Compliance Audit Expansion**  | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging                    |
+| 🔐 **TPS Log Metric**              | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request                                                 |
+| 🗑️ **Uninstall / Full Uninstall**  | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods                               |
+| 🔧 **OAuth Env Repair**            | One-click "Repair env" action for OAuth providers restores missing env vars and fixes broken auth state                                           |
+| 🔒 **Graceful Electron Shutdown**  | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close                                       |
+| 👁️ **Model Visibility Toggle**     | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages                                  |
+| 📧 **Email Privacy Masking**       | OAuth account emails masked (`di*****@g****.com`), full address visible on hover                                                                  |
+| 🔗 **Context Relay Strategy**      | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation                               |
+| 🛡️ **Proxy Hardening**             | Token health check, API key validation, and undici dispatcher all honor proxy config                                                              |
+| ⚠️ **Node.js 24 Login Warning**    | Login page proactively detects incompatible Node.js versions and shows a clear warning banner                                                     |
+| 📎 **Gemini PDF Attachments**      | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection                                                         |
+| 🔒 **CodeQL Security Hardening**   | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts                                                      |
 
 ### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)
 
@@ -1349,7 +1420,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 | 📡 **A2A Task Lifecycle Management**  | List/filter tasks, inspect events/artifacts, cancel running tasks                                                                      |
 | 📋 **Agent Card Discovery**           | `/.well-known/agent.json` for client auto-discovery                                                                                    |
 | 🧪 **Protocol E2E Test Harness**      | Real MCP SDK + A2A client flows in `test:protocols:e2e`                                                                                |
-| ⚙️ **Operational Controls**           | Switch combo, apply resilience profiles, reset breakers from one control surface                                                       |
+| ⚙️ **Operational Controls**           | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces                          |
 
 ### 🧠 Routing & Intelligence
 
@@ -1360,7 +1431,8 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 | 🔄 **Format Translation**          | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions        |
 | 👥 **Multi-Account Support**       | Multiple accounts per provider with intelligent selection                |
 | 🔄 **Auto Token Refresh**          | OAuth tokens refresh automatically with retry                            |
-| 🎨 **Custom Combos**               | 9 balancing strategies + fallback chain control                          |
+| 🎨 **Custom Combos**               | 13 balancing strategies + fallback chain control                         |
+| 🔗 **Context Relay**               | Session continuity handoffs when account rotation happens mid-session    |
 | 🌐 **Wildcard Router**             | `provider/*` dynamic routing                                             |
 | 🧠 **Thinking Budget Controls**    | Passthrough, auto, custom, and adaptive reasoning limits                 |
 | 🔀 **Model Aliases**               | Built-in + custom model aliasing and migration safety                    |
@@ -1388,31 +1460,38 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 
 ### 🛡️ Resilience, Security & Governance
 
-| Feature                             | What It Does                                                                           |
-| ----------------------------------- | -------------------------------------------------------------------------------------- |
-| 🔌 **Circuit Breakers**             | Per-model trip/recover with threshold controls                                         |
-| 🎯 **Endpoint-Aware Models**        | Custom models declare supported endpoints + API format                                 |
-| 🛡️ **Anti-Thundering Herd**         | Mutex + semaphore protections on retry/rate events                                     |
-| 🧠 **Semantic + Signature Cache**   | Cost/latency reduction with two cache layers                                           |
-| ⚡ **Request Idempotency**          | Duplicate protection window                                                            |
-| 🔒 **TLS Fingerprint Spoofing**     | Browser-like TLS fingerprint — **reduces bot detection and account flagging**          |
-| 🔏 **CLI Fingerprint Matching**     | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
-| 🌐 **IP Filtering**                 | Allowlist/blocklist control for exposed deployments                                    |
-| 📊 **Editable Rate Limits**         | Configurable global/provider-level limits with persistence                             |
-| 📉 **Graceful Degradation**         | Multi-layer capability fallbacks protecting core gateway operations                    |
-| 📜 **Config Audit Trail**           | Diff-based change tracking preventing operational drift with simple rollbacks          |
-| ⏳ **Provider Health Sync**         | Proactive token expiration monitoring triggering alerts before authorization failures  |
-| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically   |
-| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls                               |
-| 👁️ **Scoped API Key Reveal** 🆕     | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL`                                 |
-| 🛡️ **Protected `/models`**          | Optional auth gating and provider hiding for model catalog                             |
+| Feature                             | What It Does                                                                                            |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 🔌 **Provider Circuit Breakers**    | Provider-wide trip/recover after fallback exhaustion with configurable thresholds                       |
+| 🔒 **Daily Quota Lock** 🆕          | Detects exhaustion signals and locks routing for the specific model until midnight                      |
+| 🎯 **Endpoint-Aware Models**        | Custom models declare supported endpoints + API format                                                  |
+| 🛡️ **Anti-Thundering Herd**         | Mutex + semaphore protections on retry/rate events                                                      |
+| 🧠 **Semantic + Signature Cache**   | Cost/latency reduction with two cache layers                                                            |
+| ⚡ **Request Idempotency**          | Duplicate protection window                                                                             |
+| 🔒 **TLS Fingerprint Spoofing**     | Browser-like TLS fingerprint — **reduces bot detection and account flagging**                           |
+| 🔏 **CLI Fingerprint Matching**     | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP**                  |
+| 🌐 **IP Filtering**                 | Allowlist/blocklist control for exposed deployments                                                     |
+| 🚦 **Request Queue & Pacing**       | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait                 |
+| 📉 **Graceful Degradation**         | Multi-layer capability fallbacks protecting core gateway operations                                     |
+| 📜 **Config Audit Trail**           | Diff-based change tracking preventing operational drift with simple rollbacks                           |
+| ⏳ **Provider Health Sync**         | Proactive token expiration monitoring triggering alerts before authorization failures                   |
+| ❄️ **Connection Cooldown**          | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints               |
+| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically                                        |
+| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls                                                |
+| 👁️ **Scoped API Key Reveal** 🆕     | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL`                                                  |
+| 🛡️ **Protected `/models`**          | Optional auth gating and provider hiding for model catalog                                              |
+| 🛡️ **Safe Outbound Fetch** 🆕       | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection                  |
+| ⏳ **Wait For Cooldown** 🆕         | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |
+| 🔍 **Runtime Env Validation** 🆕    | Zod-based env schema validation at startup with actionable error messages                               |
+| 📋 **Compliance Audit v2** 🆕       | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging                       |
 
 ### 📊 Observability & Analytics
 
 | Feature                          | What It Does                                          |
 | -------------------------------- | ----------------------------------------------------- |
 | 📝 **Request + Proxy Logging**   | Full request/response and proxy logging               |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI  |
+| 📉 **Streamed Detailed Logs**    | Reconstructs SSE payload streams cleanly into the UI  |
+| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers    |
 | 📋 **Unified Logs Dashboard**    | Request, proxy, audit, and console views in one page  |
 | 🔍 **Request Telemetry**         | p50/p95/p99 latency and request tracing               |
 | 🏥 **Health Dashboard**          | Uptime, breaker states, lockouts, cache stats         |
@@ -1420,6 +1499,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 | 📈 **Analytics Visualizations**  | Model/provider usage insights and trend views         |
 | 🧪 **Evaluation Framework**      | Golden set testing with configurable match strategies |
 | 📡 **Live Diagnostics** 🆕       | Semantic cache bypass for accurate combo live testing |
+| 🔐 **TPS Log Metric** 🆕         | Tokens Per Second badge in log details modal          |
 
 ### ☁️ Deployment & Platform
 
@@ -1439,6 +1519,8 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 | 👁️ **Sidebar Controls** 🆕     | Hide components and integrations from Appearance Settings             |
 | 📋 **Issue Templates**         | Standardized GitHub templates for bugs and features                   |
 | 📂 **Custom Data Directory**   | `DATA_DIR` override for storage location                              |
+| 🌐 **V1 WebSocket Bridge** 🆕  | OpenAI-compatible WebSocket traffic proxied via `/v1/ws`              |
+| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support      |
 
 ### Feature Deep Dive
 
@@ -1446,7 +1528,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
 
 ```txt
 Combo: "my-coding-stack"
-  1. cc/claude-opus-4-6
+  1. cc/claude-opus-4-7
   2. nvidia/llama-3.3-70b
   3. glm/glm-4.7
   4. if/kimi-k2-thinking
@@ -1585,7 +1667,7 @@ Dashboard → Providers → Connect Claude Code
 → 5-hour + weekly quota tracking
 
 Models:
-  cc/claude-opus-4-6
+  cc/claude-opus-4-7
   cc/claude-sonnet-4-5-20250929
   cc/claude-haiku-4-5-20251001
 ```
@@ -1785,7 +1867,7 @@ Dashboard → Combos → Create New
 
 Name: premium-coding
 Models:
-  1. cc/claude-opus-4-6 (Subscription primary)
+  1. cc/claude-opus-4-7 (Subscription primary)
   2. glm/glm-4.7 (Cheap backup, $0.6/1M)
   3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
 
@@ -1815,7 +1897,7 @@ Cost: $0 forever!
 Settings → Models → Advanced:
   OpenAI API Base URL: http://localhost:20128/v1
   OpenAI API Key: [from OmniRoute dashboard]
-  Model: cc/claude-opus-4-6
+  Model: cc/claude-opus-4-7
 ```
 
 ### Claude Code
@@ -1925,7 +2007,7 @@ opencode
 **Rate limiting**
 
 - Subscription quota out → Fallback to GLM/MiniMax
-- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`
 
 **OAuth token expired**
 
@@ -1958,8 +2040,10 @@ opencode
 
 **No request logs**
 
-- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request
+- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views
+- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request
 - Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads
+- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`
 - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`
 - Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed
 
@@ -2165,7 +2249,7 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
 - **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)
 - **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)
 - **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)
+- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills
 - **Schemas**: Zod (MCP tool I/O validation, API contracts)
 - **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)
 - **Streaming**: Server-Sent Events (SSE)
@@ -2183,36 +2267,40 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
 
 ## Документация
 
-| Document                                       | Description                                         |
-| ---------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md)               | Providers, combos, CLI integration, deployment      |
-| [API Reference](docs/API_REFERENCE.md)         | All endpoints with examples                         |
-| [MCP Server](open-sse/mcp-server/README.md)    | 16 MCP tools, IDE configs, Python/TS/Go clients     |
-| [A2A Server](src/lib/a2a/README.md)            | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/auto-combo.md)        | 6-factor scoring, mode packs, self-healing          |
-| [Troubleshooting](docs/TROUBLESHOOTING.md)     | Common problems and solutions                       |
-| [Architecture](docs/ARCHITECTURE.md)           | System architecture and internals                   |
-| [Contributing](CONTRIBUTING.md)                | Development setup and guidelines                    |
-| [OpenAPI Spec](docs/openapi.yaml)              | OpenAPI 3.0 specification                           |
-| [Security Policy](SECURITY.md)                 | Vulnerability reporting and security practices      |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md)   | Complete guide: VM + nginx + Cloudflare setup       |
-| [Features Gallery](docs/FEATURES.md)           | Visual dashboard tour with screenshots              |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps                        |
+| Document                                                 | Description                                         |
+| -------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md)                         | Providers, combos, CLI integration, deployment      |
+| [API Reference](docs/API_REFERENCE.md)                   | All endpoints with examples                         |
+| [MCP Server](open-sse/mcp-server/README.md)              | 25 MCP tools, IDE configs, Python/TS/Go clients     |
+| [A2A Server](src/lib/a2a/README.md)                      | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/AUTO-COMBO.md)                  | 6-factor scoring, mode packs, self-healing          |
+| [Context Relay](docs/features/context-relay.md)          | Session handoff strategy for account rotation       |
+| [Troubleshooting](docs/TROUBLESHOOTING.md)               | Common problems and solutions                       |
+| [Architecture](docs/ARCHITECTURE.md)                     | System architecture and internals                   |
+| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough              |
+| [Uninstall Guide](docs/UNINSTALL.md)                     | Clean removal for all install methods               |
+| [Environment Config](docs/ENVIRONMENT.md)                | Complete `.env` variables and references            |
+| [Contributing](CONTRIBUTING.md)                          | Development setup and guidelines                    |
+| [OpenAPI Spec](docs/openapi.yaml)                        | OpenAPI 3.0 specification                           |
+| [Security Policy](SECURITY.md)                           | Vulnerability reporting and security practices      |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md)             | Complete guide: VM + nginx + Cloudflare setup       |
+| [Features Gallery](docs/FEATURES.md)                     | Visual dashboard tour with screenshots              |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md)           | Pre-release validation steps                        |
 
 ---
 
 ## 🗺️ Roadmap
 
-OmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:
+OmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:
 
-| Category                      | Planned Features | Highlights                                                                             |
-| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |
-| 🧠 **Routing & Intelligence** | 25+              | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection      |
-| 🔒 **Security & Compliance**  | 20+              | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping   |
-| 📊 **Observability**          | 15+              | OpenTelemetry integration, real-time quota monitoring, cost tracking per model         |
-| 🔄 **Provider Integrations**  | 20+              | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |
-| ⚡ **Performance**            | 15+              | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API         |
-| 🌐 **Ecosystem**              | 10+              | WebSocket API, config hot-reload, distributed config store, commercial mode            |
+| Category                      | Planned Features | Highlights                                                                                            |
+| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
+| 🧠 **Routing & Intelligence** | 25+              | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |
+| 🔒 **Security & Compliance**  | 20+              | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping                  |
+| 📊 **Observability**          | 15+              | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model   |
+| 🔄 **Provider Integrations**  | 20+              | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing              |
+| ⚡ **Performance**            | 15+              | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API                        |
+| 🌐 **Ecosystem**              | 10+              | WebSocket API, config hot-reload, distributed config store, commercial mode                           |
 
 ### 🔜 Coming Soon
 
@@ -2251,9 +2339,23 @@ gh release create v2.0.0 --title "v2.0.0" --generate-notes
 
 ## 📊 Star History
 
-## Stargazers over time
+<a href="https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left" />
+ </picture>
+</a>
 
-## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)
+## 🌍 StarMapper
+
+<a href="https://starmapper.bruniaux.com/diegosouzapw/omniroute">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light" />
+    <img alt="StarMapper" src="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute" />
+  </picture>
+</a>
 
 ## 🙏 Acknowledgments
 

docs/i18n/bg/SECURITY.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../SECURITY.md) · 🇸🇦 [ar](../ar/SECURITY.md) · 🇧🇬 [bg](../bg/SECURITY.md) · 🇧🇩 [bn](../bn/SECURITY.md) · 🇨🇿 [cs](../cs/SECURITY.md) · 🇩🇰 [da](../da/SECURITY.md) · 🇩🇪 [de](../de/SECURITY.md) · 🇪🇸 [es](../es/SECURITY.md) · 🇮🇷 [fa](../fa/SECURITY.md) · 🇫🇮 [fi](../fi/SECURITY.md) · 🇫🇷 [fr](../fr/SECURITY.md) · 🇮🇳 [gu](../gu/SECURITY.md) · 🇮🇱 [he](../he/SECURITY.md) · 🇮🇳 [hi](../hi/SECURITY.md) · 🇭🇺 [hu](../hu/SECURITY.md) · 🇮🇩 [id](../id/SECURITY.md) · 🇮🇹 [it](../it/SECURITY.md) · 🇯🇵 [ja](../ja/SECURITY.md) · 🇰🇷 [ko](../ko/SECURITY.md) · 🇮🇳 [mr](../mr/SECURITY.md) · 🇲🇾 [ms](../ms/SECURITY.md) · 🇳🇱 [nl](../nl/SECURITY.md) · 🇳🇴 [no](../no/SECURITY.md) · 🇵🇭 [phi](../phi/SECURITY.md) · 🇵🇱 [pl](../pl/SECURITY.md) · 🇵🇹 [pt](../pt/SECURITY.md) · 🇧🇷 [pt-BR](../pt-BR/SECURITY.md) · 🇷🇴 [ro](../ro/SECURITY.md) · 🇷🇺 [ru](../ru/SECURITY.md) · 🇸🇰 [sk](../sk/SECURITY.md) · 🇸🇪 [sv](../sv/SECURITY.md) · 🇰🇪 [sw](../sw/SECURITY.md) · 🇮🇳 [ta](../ta/SECURITY.md) · 🇮🇳 [te](../te/SECURITY.md) · 🇹🇭 [th](../th/SECURITY.md) · 🇹🇷 [tr](../tr/SECURITY.md) · 🇺🇦 [uk-UA](../uk-UA/SECURITY.md) · 🇵🇰 [ur](../ur/SECURITY.md) · 🇻🇳 [vi](../vi/SECURITY.md) · 🇨🇳 [zh-CN](../zh-CN/SECURITY.md)
 
 ---
 
@@ -24,9 +24,9 @@ If you discover a security vulnerability in OmniRoute, please report it responsi
 
 | Version | Support Status |
 | ------- | -------------- |
-| 3.4.x   | ✅ Active      |
-| 3.0.x   | ✅ Security    |
-| < 3.0.0 | ❌ Unsupported |
+| 3.6.x   | ✅ Active      |
+| 3.5.x   | ✅ Security    |
+| < 3.5.0 | ❌ Unsupported |
 
 ---
 

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

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

docs/i18n/bg/docs/API_REFERENCE.md

@@ -1,6 +1,6 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/API_REFERENCE.md) · 🇸🇦 [ar](../../ar/docs/API_REFERENCE.md) · 🇧🇬 [bg](../../bg/docs/API_REFERENCE.md) · 🇧🇩 [bn](../../bn/docs/API_REFERENCE.md) · 🇨🇿 [cs](../../cs/docs/API_REFERENCE.md) · 🇩🇰 [da](../../da/docs/API_REFERENCE.md) · 🇩🇪 [de](../../de/docs/API_REFERENCE.md) · 🇪🇸 [es](../../es/docs/API_REFERENCE.md) · 🇮🇷 [fa](../../fa/docs/API_REFERENCE.md) · 🇫🇮 [fi](../../fi/docs/API_REFERENCE.md) · 🇫🇷 [fr](../../fr/docs/API_REFERENCE.md) · 🇮🇳 [gu](../../gu/docs/API_REFERENCE.md) · 🇮🇱 [he](../../he/docs/API_REFERENCE.md) · 🇮🇳 [hi](../../hi/docs/API_REFERENCE.md) · 🇭🇺 [hu](../../hu/docs/API_REFERENCE.md) · 🇮🇩 [id](../../id/docs/API_REFERENCE.md) · 🇮🇹 [it](../../it/docs/API_REFERENCE.md) · 🇯🇵 [ja](../../ja/docs/API_REFERENCE.md) · 🇰🇷 [ko](../../ko/docs/API_REFERENCE.md) · 🇮🇳 [mr](../../mr/docs/API_REFERENCE.md) · 🇲🇾 [ms](../../ms/docs/API_REFERENCE.md) · 🇳🇱 [nl](../../nl/docs/API_REFERENCE.md) · 🇳🇴 [no](../../no/docs/API_REFERENCE.md) · 🇵🇭 [phi](../../phi/docs/API_REFERENCE.md) · 🇵🇱 [pl](../../pl/docs/API_REFERENCE.md) · 🇵🇹 [pt](../../pt/docs/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/API_REFERENCE.md) · 🇷🇴 [ro](../../ro/docs/API_REFERENCE.md) · 🇷🇺 [ru](../../ru/docs/API_REFERENCE.md) · 🇸🇰 [sk](../../sk/docs/API_REFERENCE.md) · 🇸🇪 [sv](../../sv/docs/API_REFERENCE.md) · 🇰🇪 [sw](../../sw/docs/API_REFERENCE.md) · 🇮🇳 [ta](../../ta/docs/API_REFERENCE.md) · 🇮🇳 [te](../../te/docs/API_REFERENCE.md) · 🇹🇭 [th](../../th/docs/API_REFERENCE.md) · 🇹🇷 [tr](../../tr/docs/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/API_REFERENCE.md) · 🇵🇰 [ur](../../ur/docs/API_REFERENCE.md) · 🇻🇳 [vi](../../vi/docs/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/API_REFERENCE.md)
 
 ---
 
@@ -70,7 +70,7 @@ Content-Type: application/json
 }
 ```
 
-Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
+Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, **GitHub Models**.
 
 ```bash
 # List all embedding models
@@ -93,7 +93,7 @@ Content-Type: application/json
 }
 ```
 
-Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
+Available providers: OpenAI (DALL-E, GPT Image 1), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (local), ComfyUI (local).
 
 ```bash
 # List all image models
@@ -181,15 +181,15 @@ Response example:
 
 ### 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            |
+| 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/PATCH/DELETE | Custom models (add, update, hide/show, delete) |
 
 ### OAuth Flows
 
@@ -286,12 +286,12 @@ GET response includes `agents[]` (id, name, binary, version, installed, protocol
 
 ### Resilience & Rate Limits
 
-| 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 |
+| Endpoint                | Method    | Description                                                                        |
+| ----------------------- | --------- | ---------------------------------------------------------------------------------- |
+| `/api/resilience`       | GET/PATCH | Get/update request queue, connection cooldown, provider breaker, and wait settings |
+| `/api/resilience/reset` | POST      | Reset provider circuit breakers                                                    |
+| `/api/rate-limits`      | GET       | Per-account rate limit status                                                      |
+| `/api/rate-limit`       | GET       | Global rate limit configuration                                                    |
 
 ### Evals
 
@@ -322,15 +322,38 @@ These endpoints mirror Gemini's API format for clients that expect native Gemini
 
 ### 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                     |
+| 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                     |
+| `/api/system/env/repair` | POST   | Repair OAuth provider environment variables          |
+| `/api/system-info`       | GET    | Generate system diagnostics report                   |
 
 > **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users.
 
+### OAuth Environment Repair _(v3.6.1+)_
+
+```bash
+POST /api/system/env/repair
+Content-Type: application/json
+
+{
+  "provider": "claude-code"
+}
+```
+
+Repairs missing or corrupted OAuth environment variables for a specific provider. Returns:
+
+```json
+{
+  "success": true,
+  "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
+  "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
+}
+```
+
 ---
 
 ## Audio Transcription
@@ -422,25 +445,6 @@ Content-Type: application/json
 }
 ```
 
----
-
-## 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/*`

docs/i18n/bg/docs/ARCHITECTURE.md

@@ -1,10 +1,10 @@
 # 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)
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/ARCHITECTURE.md) · 🇸🇦 [ar](../../ar/docs/ARCHITECTURE.md) · 🇧🇬 [bg](../../bg/docs/ARCHITECTURE.md) · 🇧🇩 [bn](../../bn/docs/ARCHITECTURE.md) · 🇨🇿 [cs](../../cs/docs/ARCHITECTURE.md) · 🇩🇰 [da](../../da/docs/ARCHITECTURE.md) · 🇩🇪 [de](../../de/docs/ARCHITECTURE.md) · 🇪🇸 [es](../../es/docs/ARCHITECTURE.md) · 🇮🇷 [fa](../../fa/docs/ARCHITECTURE.md) · 🇫🇮 [fi](../../fi/docs/ARCHITECTURE.md) · 🇫🇷 [fr](../../fr/docs/ARCHITECTURE.md) · 🇮🇳 [gu](../../gu/docs/ARCHITECTURE.md) · 🇮🇱 [he](../../he/docs/ARCHITECTURE.md) · 🇮🇳 [hi](../../hi/docs/ARCHITECTURE.md) · 🇭🇺 [hu](../../hu/docs/ARCHITECTURE.md) · 🇮🇩 [id](../../id/docs/ARCHITECTURE.md) · 🇮🇹 [it](../../it/docs/ARCHITECTURE.md) · 🇯🇵 [ja](../../ja/docs/ARCHITECTURE.md) · 🇰🇷 [ko](../../ko/docs/ARCHITECTURE.md) · 🇮🇳 [mr](../../mr/docs/ARCHITECTURE.md) · 🇲🇾 [ms](../../ms/docs/ARCHITECTURE.md) · 🇳🇱 [nl](../../nl/docs/ARCHITECTURE.md) · 🇳🇴 [no](../../no/docs/ARCHITECTURE.md) · 🇵🇭 [phi](../../phi/docs/ARCHITECTURE.md) · 🇵🇱 [pl](../../pl/docs/ARCHITECTURE.md) · 🇵🇹 [pt](../../pt/docs/ARCHITECTURE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) · 🇷🇴 [ro](../../ro/docs/ARCHITECTURE.md) · 🇷🇺 [ru](../../ru/docs/ARCHITECTURE.md) · 🇸🇰 [sk](../../sk/docs/ARCHITECTURE.md) · 🇸🇪 [sv](../../sv/docs/ARCHITECTURE.md) · 🇰🇪 [sw](../../sw/docs/ARCHITECTURE.md) · 🇮🇳 [ta](../../ta/docs/ARCHITECTURE.md) · 🇮🇳 [te](../../te/docs/ARCHITECTURE.md) · 🇹🇭 [th](../../th/docs/ARCHITECTURE.md) · 🇹🇷 [tr](../../tr/docs/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) · 🇵🇰 [ur](../../ur/docs/ARCHITECTURE.md) · 🇻🇳 [vi](../../vi/docs/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/ARCHITECTURE.md)
 
 ---
 
-_Last updated: 2026-03-28_
+_Last updated: 2026-04-15_
 
 ## Executive Summary
 
@@ -13,18 +13,27 @@ It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic acr
 
 Core capabilities:
 
-- OpenAI-compatible API surface for CLI/tools (28 providers)
+- OpenAI-compatible API surface for CLI/tools (100+ providers, 16 executors)
 - Request/response translation across provider formats
 - Model combo fallback (multi-model sequence)
+- Structured combo steps (`provider + model + connection`) with runtime ordering by `compositeTiers`
 - Account-level fallback (multi-account per provider)
-- OAuth + API-key provider connection management
+- Quota preflight and quota-aware P2C account selection in the main chat path
+- OAuth + API-key provider connection management (13 OAuth modules)
 - Embedding generation via `/v1/embeddings` (6 providers, 9 models)
-- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Image generation via `/v1/images/generations` (10+ providers, 20+ models)
+- Audio transcription via `/v1/audio/transcriptions` (7 providers)
+- Text-to-speech via `/v1/audio/speech` (10 providers)
+- Video generation via `/v1/videos/generations` (ComfyUI + SD WebUI)
+- Music generation via `/v1/music/generations` (ComfyUI)
+- Web search via `/v1/search` (5 providers)
+- Moderations via `/v1/moderations`
+- Reranking via `/v1/rerank`
 - 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
+- Local persistence for providers, keys, aliases, combos, settings, pricing (26 DB modules)
 - Usage/cost tracking and request logging
 - Optional cloud sync for multi-device/state sync
 - IP allowlist/blocklist for API access control
@@ -35,15 +44,35 @@ Core capabilities:
 - 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 layer: cost rules, fallback policy, lockout policy
+- Context Relay: session handoff summaries for account rotation continuity
 - 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
+- Combo target telemetry and historical combo target health via `combo_execution_key` / `combo_step_id`
 - 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/`)
+- Health dashboard with real-time provider circuit breaker status
+- MCP Server (25 tools) with 3 transports (stdio/SSE/Streamable HTTP)
+- A2A Server (JSON-RPC 2.0 + SSE) with skills and task lifecycle
+- Memory system (extraction, injection, retrieval, summarization)
+- Skills system (registry, executor, sandbox, built-in skills)
+- MITM proxy with certificate management and DNS handling
+- Prompt injection guard middleware
+- ACP (Agent Communication Protocol) registry
+- Modular OAuth providers (13 individual modules under `src/lib/oauth/providers/`)
+- Uninstall/full-uninstall scripts
+- OAuth environment repair action
+- WebSocket bridge for OpenAI-compatible WS clients (`/v1/ws`)
+- Sync token management (issue/revoke, ETag-versioned config bundle download)
+- GLM Thinking (`glmt`) first-class provider preset
+- Hybrid token counting (provider-side `/messages/count_tokens` with estimation fallback)
+- Model alias auto-seeding (30+ cross-proxy dialect normalizations at startup)
+- Safe outbound fetch with SSRF guard, private URL blocking, and configurable retry
+- Cooldown-aware chat retries with configurable `requestRetry` and `maxRetryIntervalSec`
+- Runtime environment validation with Zod at startup
+- Compliance audit v2 with pagination, provider CRUD events, and SSRF-blocked validation logging
 
 Primary runtime model:
 
@@ -74,15 +103,15 @@ 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/combos` — combo strategies, templates, step-based builder, model routing rules, manual persisted ordering
 - `/dashboard/costs` — cost aggregation and pricing visibility
-- `/dashboard/analytics` — usage analytics and evaluations
+- `/dashboard/analytics` — usage analytics, evaluations, combo target health
 - `/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/health` — uptime, circuit breakers, rate limits, quota-monitored sessions
 - `/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
@@ -178,16 +207,18 @@ Management domains:
 - 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
+- Resilience: `src/app/api/resilience` (GET/PATCH) — request queue, connection cooldown, provider breaker, wait-for-cooldown config
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset provider breakers
 - 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)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET, with pagination + structured metadata)
 - Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
 - Policies: `src/app/api/policies` (GET/POST)
+- Sync tokens: `src/app/api/sync/tokens` (GET/POST), `src/app/api/sync/tokens/[id]` (GET/DELETE)
+- Config bundle: `src/app/api/sync/bundle` (GET, ETag-versioned snapshot of settings/providers/combos/keys)
+- WebSocket: `src/app/api/v1/ws/route.ts` — Upgrade handler for OpenAI-compatible WS clients
 
 ## 2) SSE + Translation Core
 
@@ -222,10 +253,19 @@ Services (business logic):
 - Wildcard model routing: `open-sse/services/wildcardRouter.ts`
 - Rate limit management: `open-sse/services/rateLimitManager.ts`
 - Circuit breaker: `open-sse/services/circuitBreaker.ts`
+- Context handoff: `open-sse/services/contextHandoff.ts` — handoff summary generation and injection for context-relay strategy
+- Codex quota fetcher: `open-sse/services/codexQuotaFetcher.ts` — fetches Codex quota for context-relay handoff decisions
+- Cooldown-aware retry: `src/sse/services/cooldownAwareRetry.ts` — per-model cooldown retries with configurable `requestRetry` / `maxRetryIntervalSec`
+- Safe outbound fetch: `src/shared/network/safeOutboundFetch.ts` — guarded provider/model fetch with SSRF guard, private-URL blocking, retry, and timeout
+- Outbound URL guard: `src/shared/network/outboundUrlGuard.ts` — validates provider URLs against private/localhost CIDR ranges
+- Provider request defaults: `open-sse/services/providerRequestDefaults.ts` — provider-level `maxTokens`, `temperature`, `thinkingBudgetTokens` defaults
+- GLM provider constants: `open-sse/config/glmProvider.ts` — shared GLM models, quota URLs, GLMT timeout/defaults
+- Antigravity upstream: `open-sse/config/antigravityUpstream.ts` — base URL and discovery path constants
+- Codex client constants: `open-sse/config/codexClient.ts` — versioned user-agent and client-version values
+- Model alias seed: `src/lib/modelAliasSeed.ts` — seeds 30+ cross-proxy dialect aliases at startup
 
 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`
@@ -239,7 +279,7 @@ Domain layer modules:
 - 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/`):
+OAuth provider modules (13 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`, `qoder.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
@@ -273,6 +313,10 @@ Domain State DB (SQLite):
 - 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)
+- SSRF / outbound URL guard: `src/shared/network/outboundUrlGuard.ts` — blocks private/loopback/link-local ranges for all provider calls
+- Runtime env validation: `src/lib/env/runtimeEnv.ts` — Zod schema for all environment variables, surfaced as startup errors/warnings
+- Sync tokens: `src/lib/db/syncTokens.ts` — scoped tokens for config bundle download endpoints; backed by `sync_tokens` SQLite table (migration `024_create_sync_tokens.sql`)
+- WebSocket handshake auth: `src/lib/ws/handshake.ts` — validates WS upgrade requests via API key or session cookie
 
 ## 5) Cloud Sync
 
@@ -590,6 +634,10 @@ flowchart LR
 - `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)
+- `src/app/api/sync/tokens`: sync token CRUD (GET/POST)
+- `src/app/api/sync/tokens/[id]`: sync token get/delete (GET/DELETE)
+- `src/app/api/sync/bundle`: config bundle download (GET, ETag versioning)
+- `src/app/api/v1/ws`: WebSocket upgrade handler for OpenAI-compatible WS clients
 
 ### Routing and Execution Core
 
@@ -614,15 +662,22 @@ flowchart LR
 
 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, 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 |
-| `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                                     |
+| Executor               | Provider(s)                                                                                                                                                 | Special Handling                                                     |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `DefaultExecutor`      | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA, etc. | Dynamic URL/header config per provider                               |
+| `AntigravityExecutor`  | Google Antigravity                                                                                                                                          | Custom project/session IDs, Retry-After parsing                      |
+| `CliProxyApiExecutor`  | CLIProxyAPI-compatible providers                                                                                                                            | Custom auth and protocol handling                                    |
+| `CloudflareAiExecutor` | Cloudflare Workers AI                                                                                                                                       | Account ID injection, Neurons-based usage tracking                   |
+| `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                      |
+| `GeminiCLIExecutor`    | Gemini CLI                                                                                                                                                  | Google OAuth token refresh cycle                                     |
+| `KiroExecutor`         | AWS CodeWhisperer/Kiro                                                                                                                                      | AWS EventStream binary format → SSE conversion                       |
+| `OpenCodeExecutor`     | OpenCode                                                                                                                                                    | AI SDK compatible provider setup                                     |
+| `PollinationsExecutor` | Pollinations AI                                                                                                                                             | No API key required, rate-limited requests                           |
+| `PuterExecutor`        | Puter                                                                                                                                                       | Browser-based provider integration                                   |
+| `QoderExecutor`        | Qoder AI                                                                                                                                                    | PAT and OAuth support, multi-model free tier                         |
+| `VertexExecutor`       | Google Vertex AI                                                                                                                                            | Service account auth, region-based endpoints                         |
 
 All other providers (including custom compatible nodes) use the `DefaultExecutor`.
 
@@ -640,7 +695,10 @@ 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     |
-| Qoder            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Qoder            | openai           | OAuth / PAT           | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Kilo Code        | openai           | OAuth                 | ✅               | ✅         | ✅            | ❌                 |
+| Cline            | openai           | OAuth                 | ✅               | ✅         | ✅            | ❌                 |
+| Kimi Coding      | openai           | OAuth                 | ✅               | ✅         | ✅            | ❌                 |
 | OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
@@ -653,6 +711,17 @@ All other providers (including custom compatible nodes) use the `DefaultExecutor
 | Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 | NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cloudflare AI    | openai           | API Token + Acct ID   | ✅               | ✅         | ❌            | ❌                 |
+| Pollinations     | openai           | None (no key)         | ✅               | ✅         | ❌            | ❌                 |
+| Scaleway AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| LongCat          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Ollama Cloud     | openai           | API Key (optional)    | ✅               | ✅         | ❌            | ❌                 |
+| HuggingFace      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Nebius           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| SiliconFlow      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Hyperbolic       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Vertex AI        | gemini           | Service Account       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Puter            | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
 
 ## Format Translation Coverage
 
@@ -712,22 +781,20 @@ Additional processing layers in the translation pipeline:
 
 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
+## Request Logging and Artifacts
 
-The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`:
+The older file-based request logger (`open-sse/utils/requestLogger.ts`) is retained only for
+legacy compatibility. The current runtime contract uses:
 
-```
-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.
+- `APP_LOG_TO_FILE=true` for application and audit logs written under `<repo>/logs/`
+- SQLite-backed call log records in `call_logs`
+- `${DATA_DIR}/call_logs/YYYY-MM-DD/...` artifacts when the call log pipeline is enabled
 
 ## Failure Modes and Resilience
 
 ## 1) Account/Provider Availability
 
-- provider account cooldown on transient/rate/auth errors
+- connection cooldown on retryable upstream failures
 - account fallback before failing request
 - combo model fallback when current model/provider path is exhausted
 
@@ -752,6 +819,12 @@ Files are written to `<repo>/logs/<session>/` for each request session.
 - SQLite schema migrations and auto-upgrade hooks at startup
 - legacy JSON → SQLite migration compatibility path
 
+## 6) SSRF / Outbound URL Guard
+
+- `src/shared/network/outboundUrlGuard.ts` blocks all private/loopback/link-local target URLs before they reach provider executors
+- Provider model discovery and validation routes use `src/shared/network/safeOutboundFetch.ts` which applies the guard before every outbound request
+- Guard errors surface as `URL_GUARD_BLOCKED` with HTTP 422 and are logged to the compliance audit trail via `providerAudit.ts`
+
 ## Observability and Operational Signals
 
 Runtime visibility sources:
@@ -760,7 +833,8 @@ Runtime visibility sources:
 - 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`
+- optional application log files under `logs/` when `APP_LOG_TO_FILE=true`
+- optional request artifacts under `${DATA_DIR}/call_logs/` when the call log pipeline is enabled
 - dashboard usage endpoints (`/api/usage/*`) for UI consumption
 
 Detailed request payload capture stores up to four JSON payload stages per routed call:
@@ -787,7 +861,7 @@ Environment variables actively used by code:
 - 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`
+- Logging: `APP_LOG_TO_FILE`, `APP_LOG_RETENTION_DAYS`, `CALL_LOG_RETENTION_DAYS`
 - 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`
@@ -802,7 +876,10 @@ Environment variables actively used by code:
 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).
+8. Settings page is organized into 7 tabs: General, Appearance, AI, Security, Routing, Resilience, Advanced. The Resilience page only configures request queue, connection cooldown, provider breaker, and wait-for-cooldown behavior; live breaker runtime state is shown on the Health page.
+9. **Context Relay** strategy (`context-relay`) is split across two layers: `combo.ts` decides if a handoff should be generated, `chat.ts` injects the handoff after account resolution. Handoff data lives in `context_handoffs` SQLite table. This split is intentional because only `chat.ts` knows whether the actual account changed.
+10. **Proxy enforcement** is now comprehensive: `tokenHealthCheck.ts` resolves proxy per connection, `/api/providers/validate` uses `runWithProxyContext`, and `proxyFetch.ts` uses `undici.fetch()` to maintain dispatcher compatibility on Node 22.
+11. **Node.js runtime policy detection**: `/api/settings/require-login` returns `nodeVersion` and `nodeCompatible` fields. The login page renders a warning banner when the runtime falls outside the supported secure Node.js lines.
 
 ## Operational Verification Checklist
 

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

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