Merge pull request #1144 from diegosouzapw/release/v3.6.2

chore(release): v3.6.2 — Provider Expansion and Stabilization

.agents/workflows/fix-ci.md

@@ -0,0 +1,182 @@
+# Fix CI Workflow
+
+Look up the latest GitHub Actions CI run for the current release branch, diagnose all failures, fix them locally, push, and wait for the new CI run to go green before notifying the user.
+
+---
+
+## Phase 1: Identify the Failing CI Run
+
+### 1. Determine the current release version and branch
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+VERSION=$(node -p "require('./package.json').version")
+BRANCH=$(git branch --show-current)
+echo "Version: $VERSION"
+echo "Branch: $BRANCH"
+```
+
+### 2. Find the latest CI run for the release PR
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+# Find the PR number for the release branch
+PR_NUMBER=$(gh pr list --repo diegosouzapw/OmniRoute --head "$BRANCH" --json number --jq '.[0].number')
+echo "PR: #$PR_NUMBER"
+
+# Get the latest CI run
+RUN_ID=$(gh run list --repo diegosouzapw/OmniRoute --branch "$BRANCH" --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId')
+echo "Latest CI Run: $RUN_ID"
+echo "URL: https://github.com/diegosouzapw/OmniRoute/actions/runs/$RUN_ID"
+```
+
+---
+
+## Phase 2: Diagnose Failures
+
+### 3. List all failing jobs
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+RUN_ID=$(gh run list --repo diegosouzapw/OmniRoute --branch "$(git branch --show-current)" --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId')
+gh run view "$RUN_ID" --repo diegosouzapw/OmniRoute --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {name: .name, conclusion: .conclusion, steps: [.steps[] | select(.conclusion == "failure") | .name]}'
+```
+
+### 4. Download and analyze failure logs
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+RUN_ID=$(gh run list --repo diegosouzapw/OmniRoute --branch "$(git branch --show-current)" --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId')
+gh run view "$RUN_ID" --repo diegosouzapw/OmniRoute --log-failed 2>&1 | grep -aE "not ok|FAIL|Error:|error:|AssertionError|expected|actual" | grep -v "node_modules\|runner\|git version" | head -50
+```
+
+### 5. Classify each failure
+
+For each failing job, determine the root cause category:
+
+| Category           | Pattern                            | Fix Strategy                               |
+| ------------------ | ---------------------------------- | ------------------------------------------ |
+| **docs-sync**      | OpenAPI/CHANGELOG version mismatch | Run `/version-bump` step 7-8               |
+| **Test assertion** | `not ok` + `AssertionError`        | Update test expectations to match new code |
+| **E2E flaky**      | Auth-related 401/403/307           | Make tests tolerate auth states            |
+| **Coverage gate**  | `below threshold`                  | Add more tests or adjust threshold         |
+| **Lint**           | ESLint errors                      | Fix code or update rules                   |
+| **Build**          | Compilation errors                 | Fix TypeScript issues                      |
+
+---
+
+## Phase 3: Apply Fixes
+
+### 6. Fix each failure
+
+For each classified failure:
+
+1. **Read the failing test file** to understand the assertion
+2. **Read the production source** to understand the new behavior
+3. **Update the test** to match the current behavior
+4. **Run the test locally** to verify the fix
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+# Run the specific failing test file(s) to confirm fixes
+# Example: node --import tsx/esm --test tests/unit/FAILING_FILE.test.mjs
+```
+
+### 7. Run the full local test suite
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+npm test
+```
+
+### 8. Run docs-sync check
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+npm run check:docs-sync
+```
+
+---
+
+## Phase 4: Push and Monitor
+
+### 9. Commit and push fixes
+
+// turbo-all
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+git add -A
+git commit -m "fix(tests): align CI tests with release changes"
+git push origin "$(git branch --show-current)"
+```
+
+### 10. Wait for CI to trigger and find the new run
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+sleep 15
+BRANCH=$(git branch --show-current)
+NEW_RUN_ID=$(gh run list --repo diegosouzapw/OmniRoute --branch "$BRANCH" --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId')
+echo "New CI Run: $NEW_RUN_ID"
+echo "URL: https://github.com/diegosouzapw/OmniRoute/actions/runs/$NEW_RUN_ID"
+```
+
+### 11. Monitor the CI run
+
+// turbo
+
+```bash
+cd /home/diegosouzapw/dev/proxys/9router
+BRANCH=$(git branch --show-current)
+NEW_RUN_ID=$(gh run list --repo diegosouzapw/OmniRoute --branch "$BRANCH" --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId')
+gh run watch "$NEW_RUN_ID" --repo diegosouzapw/OmniRoute --exit-status
+```
+
+If `gh run watch` exits with 0, the CI is green. If it exits with non-zero, go back to Phase 2 and repeat.
+
+### 12. 🛑 STOP — Notify User
+
+Present a summary to the user:
+
+- **Previous CI run**: URL, list of failures
+- **Root causes**: What broke and why
+- **Fixes applied**: What tests were changed
+- **New CI run**: URL, all-green status
+- **PR status**: Ready for review/merge
+
+---
+
+## Common CI Failure Patterns
+
+| Failure                                    | Root Cause                             | Fix                           |
+| ------------------------------------------ | -------------------------------------- | ----------------------------- |
+| `docs-sync FAIL - OpenAPI version differs` | Version not synced after bump          | `sed -i` openapi.yaml         |
+| `docs-sync FAIL - CHANGELOG first section` | Missing `## [Unreleased]` header       | Add unreleased section        |
+| `not ok - cleanupExpiredLogs`              | Return shape changed (new fields)      | Update `assert.deepEqual`     |
+| `not ok - email masking`                   | Email now masked in call logs          | Assert masked pattern instead |
+| `E2E /api/providers` returns non-200       | Auth enabled in CI, endpoint protected | Accept 401/403 as valid       |
+| `coverage below 60%`                       | New untested code                      | Add unit tests                |
+
+## Notes
+
+- This workflow is **iterative**: if the first fix attempt doesn't clear all failures, repeat Phases 2-4.
+- Always run tests **locally** before pushing to avoid wasting CI minutes.
+- The CI is triggered automatically on push to branches with open PRs to `main`.
+- Use `gh run watch` to monitor in real-time instead of polling.

.agents/workflows/generate-release.md

@@ -203,9 +203,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)

.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

@@ -100,6 +100,7 @@ For each bug, classify into one of 5 actions:
 | ---------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------- |
 | **✅ 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, implement, test, commit on release branch |

.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,29 @@ 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
@@ -141,7 +164,7 @@ Perform a **global impact assessment** to verify whether the PR changes are comp
 
 > **⚠️ Fixes should be pushed back to the PR branch before merging.** We want the PR itself to be green and fully valid before it integrates.
 
-- **Sync latest fixes:** Merge `main` or the current `release` branch into the PR branch so the PR inherits any latest CI or integration test fixes (preventing false-positive failures).
+- **Sync latest fixes:** Merge the current `release` branch into the PR branch so the PR inherits any latest CI or integration test fixes (preventing false-positive failures).
 - **Implement improvements:** Apply the required fixes identified in the analysis directly on the PR branch (e.g., adding missing API routes, fixing SSRF, applying comments from other agents).
 - **Pushing changes to PR branches:**
 
@@ -167,12 +190,19 @@ 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`).
+> **⚠️ IMPORTANT**: PRs are merged into the **release branch** (`release/vX.Y.Z`), NOT into `main`.
+
+- Once the PR is green (you can check with `gh pr status`), merge the PR into the release branch.
+- The PR's base was already changed to the release branch in step 3.5, so the default merge target is correct.
 
   ```bash
-  gh pr merge <NUMBER> --repo <owner>/<repo>
+  # 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"
+
+  # If the PR is a draft, mark it as ready first
+  gh pr ready <NUMBER> --repo <owner>/<repo>
   ```
 
 - Post a **thank-you comment** on the PR via the GitHub API
@@ -183,12 +213,14 @@ Perform a **global impact assessment** to verify whether the PR changes are comp
   - 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!"_
 
-### 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 +228,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`

.env.example

@@ -10,8 +10,8 @@ JWT_SECRET=
 API_KEY_SECRET=
 
 # Initial admin password — CHANGE THIS before first use!
-INITIAL_PASSWORD=CHANGEME
-DATA_DIR=/var/lib/omniroute
+INITIAL_PASSWORD=123456
+# DATA_DIR=/var/lib/omniroute
 
 # Storage (SQLite)
 STORAGE_DRIVER=sqlite
@@ -90,49 +90,70 @@ NEXT_PUBLIC_ENABLE_SOCKS5_PROXY=true
 # CLI_ROO_BIN=roo
 # CLI_CONTINUE_BIN=cn
 
-# Provider OAuth Credentials (optional — override hardcoded defaults)
-# These can also be set via data/provider-credentials.json
-# CLAUDE_OAUTH_CLIENT_ID=
+# Internal agent / tool integrations (optional)
+# Used by the MCP server, A2A skills, and CLI sidecars when they need to call
+# the running OmniRoute instance explicitly instead of relying on localhost.
+# OMNIROUTE_BASE_URL=http://localhost:20128
+# OMNIROUTE_API_KEY=
+# ROUTER_API_KEY=
+# MODEL_SYNC_INTERVAL_HOURS=24
+
+# ═══════════════════════════════════════════════════
+#   OAUTH PROVIDER CREDENTIALS
+# ═══════════════════════════════════════════════════
+# These are the built-in default credentials that work for localhost setups.
+# For remote/VPS deployments, register your own credentials at each provider.
+# The sync-env script will auto-populate these in your .env if missing.
+#
+# These can also be overridden via data/provider-credentials.json where supported.
+
+# ── Claude Code (Anthropic) ──
+CLAUDE_OAUTH_CLIENT_ID=9d1c250a-e61b-44d9-88ed-5944d1962f5e
+
+# ── 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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
+
+# ── GitHub Copilot ──
+GITHUB_OAUTH_CLIENT_ID=Iv1.b507a08c87ecfe98
+
+# ── Qoder ──
+QODER_OAUTH_CLIENT_SECRET=4Z3YjXycVsQvyGF1etiNlIBB4RsqSDtW
+
+# ── Qoder (URLs — set these to enable Qoder OAuth login) ──
+# QODER_OAUTH_AUTHORIZE_URL=
+# QODER_OAUTH_TOKEN_URL=
+# QODER_OAUTH_USERINFO_URL=
+# QODER_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:
-#
+# The credentials above ONLY work when OmniRoute runs on localhost.
+# If you are hosting OmniRoute on a remote server, register your own:
 #   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
-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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
+#   3. Add your server URL as Authorized redirect URI
+#   4. Replace the values above with your credentials.
 # ─────────────────────────────────────────────────────────────────────────────
 
-# CLAUDE_OAUTH_CLIENT_ID=
-# CODEX_OAUTH_CLIENT_ID=
-# CODEX_OAUTH_CLIENT_SECRET=
-# QWEN_OAUTH_CLIENT_ID=
-# QODER_OAUTH_CLIENT_ID=
-QODER_OAUTH_CLIENT_SECRET=4Z3YjXycVsQvyGF1etiNlIBB4RsqSDtW
-
 # ─────────────────────────────────────────────────────────────────────────────
 # Provider User-Agent Overrides (optional — customize per-provider UA headers)
 # ─────────────────────────────────────────────────────────────────────────────
@@ -206,7 +227,7 @@ GEMINI_CLI_USER_AGENT=google-api-nodejs-client/9.15.1
 # API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS=0
 
 # CORS configuration (default: * allows all origins)
-# CORS_ORIGINS=*
+# CORS_ORIGIN=*
 
 # Logging
 # APP_LOG_LEVEL=info

.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/workflows/ci.yml

@@ -67,7 +67,7 @@ jobs:
 
       - name: Upload result
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: i18n-${{ matrix.lang }}
           path: result.txt
@@ -201,7 +201,7 @@ jobs:
           cat coverage/coverage-report.md >> "$GITHUB_STEP_SUMMARY"
       - name: Upload coverage artifacts
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: coverage-report
           path: |
@@ -281,7 +281,7 @@ jobs:
               echo "This PR changes production code in \`src/\`, \`open-sse/\`, \`electron/\`, or \`bin/\` without accompanying automated tests."
             fi
           } > .artifacts/pr-coverage-comment.md
-      - uses: actions/github-script@v8
+      - uses: actions/github-script@v9
         with:
           script: |
             const fs = require("fs");

.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 }}
@@ -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

@@ -81,7 +81,7 @@ jobs:
           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') }}
@@ -148,7 +148,7 @@ jobs:
           fi
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: electron-${{ matrix.platform }}
           path: release-assets/

.gitignore

@@ -120,6 +120,7 @@ security-analysis/
 clipr/
 app.log
 *.tgz
+.gh-discussions.json
 
 # Backup directories
 app.__qa_backup/
@@ -160,4 +161,7 @@ typescript
 .gemini/
 
 # Superpowers plans/specs (internal tooling, not project code)
-docs/superpowers/
+docs/superpowers/
+
+# GitNexus local index
+.gitnexus

.husky/pre-commit

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

.husky/pre-push

@@ -1 +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 @@
+22

.nvmrc

@@ -0,0 +1 @@
+22

.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]

AGENTS.md

@@ -3,8 +3,9 @@
 ## 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 **100+ 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** (25 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.
 
 ## Stack
@@ -135,7 +136,8 @@ 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.
 
@@ -156,13 +158,18 @@ 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** (91): 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), and more.
 - **Custom**: OpenAI-compatible (`openai-compatible-*`) and Anthropic-compatible (`anthropic-compatible-*`) prefixes
 
 Providers are registered in `src/shared/constants/providers.ts` with Zod validation at module load.
@@ -189,7 +196,7 @@ 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.
 
 ### Domain Layer (`src/domain/`)
 

CHANGELOG.md

@@ -4,6 +4,197 @@
 
 ---
 
+## [3.6.2] — 2026-04-11
+
+### ✨ New Features
+
+- **33 New API Key Providers:** Massive provider expansion adding 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, and GigaChat (Sber). OmniRoute now supports **100+ providers** (4 Free + 8 OAuth + 91 API Key + Custom compatible)
+- **Global Email Privacy Toggle:** Added a persistent eye-icon toggle button across all dashboard pages (Providers, Usage Limits, Playground) that reveals or hides masked email addresses. Toggle state is stored in localStorage and synced globally via Zustand store
+- **Documentation Refresh:** Updated README, ARCHITECTURE, FEATURES, AGENTS.md, and API_REFERENCE for v3.6.2 with accurate provider counts (100+), new executor list, and system API documentation
+- **Uninstall Guide:** Created comprehensive `docs/UNINSTALL.md` covering clean uninstallation for all deployment methods (npm, Docker, Electron, source)
+
+### 🐛 Bug Fixes
+
+- **PDF Attachments:** Unlocked deep string object parsing (`geminiHelper`) ensuring Gemini translation successfully passes complex PDF payloads from OpenAI-compatible streams without dropping them silently (#993)
+- **SkillsMP Engine:** Corrected object extraction path mappings inside the API router to fix UI marketplace rendering under Docker/Standalone Node isolated deployments (#988)
+
+---
+
+## [3.6.1] — 2026-04-10
+
+### ✨ New Features
+
+- **OAuth Env Repair Action:** Added a "Repair env" button to the OAuth Providers dashboard that detects and restores missing OAuth client IDs from `.env.example` — with timestamped backup and append-only safety. Includes full 33-language i18n support and sanitized API responses (#1116, by @yart)
+
+### 🐛 Bug Fixes
+
+- **i18n: Missing Provider Keys:** Added missing `filterModels`, `modelsActive`, `showModel`, `hideModel` keys across all 32 locale files, fixing runtime `MISSING_MESSAGE` errors in the providers UI. Also cleaned up duplicate keys in `en.json` (#1111, by @rilham97)
+- **GPT-5.4 Routing:** Added missing `targetFormat: "openai-responses"` to `gpt-5.4` and `gpt-5.4-mini` models in both the Codex and GitHub Copilot providers, fixing `[400]: model not accessible via /chat/completions` errors (#1114, by @ask33r)
+
+---
+
+## [3.6.0] — 2026-04-10
+
+### ✨ New Features & Analytics
+
+- **Combo Smoke Test:** Raised the default token budget to 2048 to prevent truncation of thinking models during preflight checks, and fully randomized the arithmetic probe prompt to bypass deterministic caching from upstream relays (#1105)
+
+### 🐛 Bug Fixes & Compliance
+
+- **DB Bloat / Row Limits:** Added `CALL_LOGS_TABLE_MAX_ROWS` and `PROXY_LOGS_TABLE_MAX_ROWS` (default: 100,000) to the backend DB compliance cleaner to prevent runaway SQLite growth. Limits are enforced automatically on the TTL cycle (#1104, fixes #1101)
+- **HTML Error Handling:** The router now correctly identifies unexpected HTML responses (e.g. `<!DOCTYPE html>`) sent by upstream providers (like Azure/Copilot) instead of throwing obscure `Unexpected token '<'` JSON parse errors, bubbling up a clean 502 Bad Gateway (#1104, fixes #1066)
+- **Android/Termux SQLite Native Support:** `better-sqlite3` is now correctly built from source with cross-compilation flags in ARM64 local Termux deployments without failing on missing prebuilt binaries (#1107)
+
+---
+
+## [3.5.9] — 2026-04-09
+
+### ✨ New Features
+
+- **Persistent Combo Ordering:** Drag combo cards by handle to reorder them in the dashboard; order is persisted to SQLite via a new `sort_order` column and `POST /api/combos/reorder` endpoint. Includes DB migration `020_combo_sort_order.sql` and JSON import preservation (#1095)
+- **Sidebar Group Reorder:** Moved "Logs" before "Health" in the System section and "Limits & Quotas" after "Cache" in the Primary section for a more logical navigation flow (#1095)
+
+### 🐛 Bug Fixes
+
+- **Stream Failure Surfacing:** Upstream `response.failed` events (e.g. Codex rate-limit errors) are now properly surfaced as non-200 errors instead of being silently swallowed as empty 200 OK streams. Rate-limit failures return HTTP 429 (#1098, closes #1093)
+- **Upstream Model Preservation:** The Responses-to-OpenAI stream translator now preserves the actual upstream model (e.g. `gpt-5.4`) instead of hardcoding a `gpt-4` fallback (#1098, closes #1094)
+- **Docker EXDEV Fix:** `build-next-isolated.mjs` now falls back from `fs.rename()` to `cp/rm` when Docker buildx raises `EXDEV` (cross-device link), unblocking the Docker image publish workflow (#1097)
+- **macOS CLI Path Resolution:** `cliRuntime.ts` resolves symlink parents with `fs.realpath()` to handle macOS `/var` → `/private/var` chains, preventing false `symlink_escape` rejections (#1097)
+- **Request Log Token Layout:** Split token badges into separate Input (Total In, Cache Read, Cache Write) and Output (Total Out, Reasoning) groups for clearer readability; renamed "Time" label to "Completed Time" (#1096)
+
+---
+
+## [3.5.8] — 2026-04-09
+
+### ✨ New Features & Analytics
+
+- **Analytics Layout Redesign:** Replaced flat metrics with a responsive `CompactStatGrid`, grouping data visually across sections (#1089)
+
+### 🐛 Bug Fixes
+
+- **Build Core:** Force Turbopack cleanup via Prepbulish script to prevent Next.js 16 app/ routing conflicts on runtime.
+- **Provider Quarantine:** Introduces model/provider circuit-breakers with adaptive TTL exponential backoff for recurring upstream errors (#1090)
+- **Oauth Keep-Alive:** Safely protects authenticated active accounts against spontaneous dropping from router due to transient token refresh failures (#1085)
+
+### 🔒 Security & Maintenance
+
+- **Dependabot:** bumped axios from 1.14.0 to 1.15.0 addressing SSRF flags (#1088)
+
+---
+
+## [3.5.7] — 2026-04-09
+
+### 🐛 Bug Fixes & Security
+
+- **Turbopack Standalone Chunks:** Fixed a critical bug in `scripts/prepublish.mjs` where Turbopack chunks missing from the `.next/standalone` trace resulted in a `500 ChunkLoadError` (e.g., `_not-found` page crash) during production deployments via NPM or Docker. Standalone chunks are now explicitly copied and correctly stripped of Turbopack hashes.
+
+---
+
+## [3.5.6] — 2026-04-09
+
+### ✨ New Features
+
+- **Email Privacy Masking:** OAuth account emails are now masked in the provider dashboard (e.g. `di*****@g****.com`) to prevent accidental exposure when sharing screenshots. Full address visible on hover via `title` attribute (#1025).
+- **OpenRouter & GitHub in Embedding/Image Registries:** OpenRouter (3 embedding models, 4 image models) and GitHub Models (2 embedding models via Azure inference) are now first-class entries in the provider registries, enabling their use for `/v1/embeddings` and `/v1/images/generations` (#960).
+- **Model Visibility Toggle & Search Filter:** The provider page model list now includes a real-time search/filter bar and a per-model visibility toggle (👁 icon). Hidden models are grayed out and excluded from the `/v1/models` catalog. An active-count badge (`N/M active`) shows at a glance how many models are enabled (#750).
+- **Chinese Localization (zh-CN):** Added missing translations for Context Relay, Memory, LKGP, and Models.dev sync features, while standardizing terminology across the application (#1079).
+- **Environment Auto-Sync:** Added `sync-env.mjs` to auto-generate and append `.env` from `.env.example` during installation, automatically generating cryptographic secrets on first run.
+- **Source Mode Dashboard Update:** Fixed real-time Source (git-checkout) updating in the dashboard, enabling secure, real-time update pipelines for non-NPM installations.
+
+### 🐛 Bug Fixes & Security
+
+- **Hardcoded Secret Cleanup:** Removed 12 hardcoded OAuth credential fallbacks from the source code, forcing secure reliance on environment variables and resolving static analysis security alerts.
+- **Next.js Security Patch:** Bumped `next` from 16.2.2 to 16.2.3 to resolve critical RSC deserialization RCE vulnerability (SNYK-JS-NEXT-15954202).
+- **Memory/Cache UI Crash:** Added null-safety guards (`?? 0`) to `.toLocaleString()` calls in Memory and Cache dashboard pages, preventing `TypeError` crashes when database tables are empty or contain null numeric values (#1083).
+- **WebSearch tool_choice Translation:** Fixed OpenAI-to-Claude translator dropping `tool_choice` objects with `type: "function"` as-is, which Claude rejects. Now properly maps all OpenAI `tool_choice` variants (`function`, `required`, `none`) to Claude-compatible format (`tool`, `any`, `auto`), fixing "Did 0 searches" in Claude Code WebSearch (#1072).
+- **Provider Validation baseUrl Override:** Added `baseUrl` passthrough from frontend validation requests to the backend validation endpoint. Chinese-site users of Alibaba Coding Plan (bailian-coding-plan) can now validate API keys against their custom Base URL instead of always hitting the international endpoint (#1078).
+- **Minimax Auth Header:** Switched Minimax provider from `x-api-key` to `Authorization: Bearer` header format, matching the current API spec (#1076).
+- **Native Fetch Fallback:** Added graceful fallback to native `fetch` when the `undici` dispatcher fails, improving resilience in environments where undici is unavailable (#1054).
+- **EPIPE Flood Fix:** Added circuit-breaker logic to prevent EPIPE errors from creating a feedback loop that fills logs at GB/s (#1006).
+- **Qoder PAT Validation:** Improved Qoder Personal Access Token validation with actionable error messages that guide users to the correct token format (#966).
+- **CI/CD Pipeline:** Fixed `check:docs-sync` failure by syncing OpenAPI version to 3.5.6 and finalizing CHANGELOG release heading. Commented out `DATA_DIR` in `.env.example` to prevent E2E test failures in CI runners lacking root permissions.
+
+### 🌍 i18n
+
+- **Auto Language Generation (CI):** Added CI pipeline to auto-generate missing language files and strings via `feat(CI,i18n)` workflow, covering 30+ locales (#1071).
+
+---
+
+## [3.5.5] — 2026-04-08
+
+### ✨ New Features
+
+- **Node.js 24 Compatibility Warning:** Added a proactive version incompatibility warning on the login page to guide users to the stable Node.js 22 LTS, preventing native sqlite binding crashes.
+- **Context Relay Combo Strategy:** Added the new `context-relay` combo strategy with priority-style routing, structured handoff summary generation once quota usage reaches the warning threshold, and handoff injection after the next real account switch.
+- **Global Context Relay Defaults:** Added global Settings defaults plus combo-level configuration for `handoffThreshold`, `handoffModel`, and `handoffProviders`, so new or unconfigured combos can inherit the feature consistently.
+
+### 🐛 Bug Fixes
+
+- **Proxy Connection Healthchecks:** Applied proxy resolution per connection in the sweeping loop (`tokenHealthCheck.ts`) and global provider validation sweeps, resolving Node 22 bypass and improving proxy stability (#1051, #1056, #1061).
+- **Security Vulnerability Remediation:** Resolved multiple CodeQL scanning alerts including SSRF in model sync, insecure randomness in web crypto (`generateSessionId`), and incomplete URL sanitization.
+- **Context Relay Typing & Synchronization:** Reverted out-of-scope test breakages and resolved `handoffProvider` and response `input` extraction payload typing.
+- **Legacy OpenAI-Compatible Responses Routing:** Fixed legacy/imported OpenAI-compatible providers (for example `openai-compatible-sp-openai`) incorrectly routing Chat Completions traffic to `/chat/completions` when the real provider node was configured as `apiType: "responses"`. OmniRoute now treats `providerSpecificData.apiType` as authoritative across routing, executors, and translator tools, avoiding false empty-content failures during combo/provider smoke tests (#1069).
+- **Gemini PDF Attachment Integration:** Fixed payload generation and format for parsing `inline_data` and generic base64 sources for deep Gemini PDF routing (#993, #1021).
+- **Vercel AI SDK Fallbacks:** Mapped `max_output_tokens` to `max_tokens` for strict OpenAI-compatible providers, resolving errors from standard AI agents and frameworks (#994).
+- **External Auth & UI Reliability:** Handled null `state` failures in Cline OAuth exchange (#1016), added 3rd-party 400 error patterns to combo fallback (#1024), and resolved desktop sidebar layout and popover overflows (#1039, #1001).
+- **Context Relay In-Flight Deduplication:** Prevented duplicate handoff generation for the same session/combo while an earlier summary request is still in flight.
+- **Context Relay Provider Gating:** Aligned runtime behavior with configuration so explicit `handoffProviders` exclusions, including an empty array, now disable handoff generation as expected.
+
+### 🛠️ Maintenance & Dependabot
+
+- **Updated Sub-dependencies:** Bumped `hono` to `4.12.12` and `@hono/node-server` to `1.19.13` to patch critical security gaps (#1063, #1064, #1067, #1068).
+
+### 📚 Documentation
+
+- **Documentation Synchronization:** Updated system documentation (README, Architecture, Features, Tools, Troubleshooting) and synced `i18n` configurations to match the v3.5.5 context relay patterns and proxy troubleshooting steps.
+- **Context Relay Delivery Notes:** Documented the current architecture, runtime flow, and Codex-focused scope in the feature docs, changelog, and agent guidance.
+
+---
+
+## [3.5.4] — 2026-04-07
+
+### ✨ New Features
+
+- **Detailed Token Tracking:** Added granular token breakdown columns (cache read, cache write, reasoning) to call logs with proper null vs zero distinction. Includes DB migration 018 and 5-label UI display per provider capability (#1017 — thanks @rdself).
+- **Legacy JSON Config Import/Export:** Restored JSON-based settings export and import for migration from legacy 9router configurations. Security-hardened with Zero-Trust redaction of passwords and `requireLogin` fields, and automatic pre-import database backups (#1012 — thanks @luandiasrj).
+- **Non-Stream Aliases:** Added API support for explicit non-streaming aliases (`non_stream`, `disable_stream`, `disable_streaming`, `streaming=false`), normalized at the boundary before provider translation (#1036 — thanks @wlfonseca).
+- **Russian Dashboard Localization:** Comprehensive Russian translation for the dashboard UI, including fixes for 2 Ukrainian locale keys (#1003 — thanks @mercs2910).
+
+### 🐛 Bug Fixes
+
+- **Anthropic Streaming Input Undercount:** Fixed a critical bug where Anthropic streaming `prompt_tokens` only reported non-cached tokens (e.g., `in=3` when actual total was 113,616). Cache tokens are now summed into prompt_tokens during streaming (#1017).
+- **Built-in Responses API Tool Types:** Preserved built-in Responses API tools (`web_search`, `file_search`, `computer`, `code_interpreter`, `image_generation`) from being silently stripped by the empty-name tool filter — these tools carry no `.name` field (#1014 — thanks @rdself).
+- **Cursor/Codex Responses Compatibility:** Fixed empty output in Cursor when using Codex models by hoisting system input items to `instructions`, sanitizing invalid tool names, and detecting Responses-format payloads on chat/completions endpoint (#1002 — thanks @mercs2910).
+- **OAuth Token Expiry Display:** Fixed OAuth connections showing "expired" badge even with valid tokens by reading `tokenExpiresAt` (updated on refresh) instead of `expiresAt` (original grant timestamp) (#1032 — thanks @tombii).
+- **Codex Fast-Tier Copy:** Corrected dashboard settings copy from `service_tier=fast` to `service_tier=priority`, matching the actual Codex wire format (#1045 — thanks @kfiramar).
+- **macOS Desktop App Startup:** Stabilized packaged macOS app launch by excluding desktop artifacts from the standalone bundle and improving launch path detection (#1004 — thanks @mercs2910).
+- **macOS Sidebar Layout:** Fixed macOS traffic light overlap, sidebar spacing, and button overflow in the Electron desktop app (#1001 — thanks @mercs2910).
+
+### ⚡ Performance
+
+- **Analytics Page Load:** Dramatically reduced analytics page load times (30s→1-2s for 50K entries) via date-filtered DB queries, parallel `Promise.all()` cost calculations, and merged 6 COUNT queries into a single CASE WHEN aggregate (#1038 — thanks @oyi77).
+
+### 🔒 Security & Dependencies
+
+- **Node Base Image:** Upgraded Docker base from `22-bookworm-slim` to `22.22.2-trixie-slim` (#1011 — Snyk).
+- **Production Dependencies:** Bumped 5 production dependencies (#1044 — Dependabot).
+- **Vite:** Bumped from 8.0.3 to 8.0.5 (#1031 — Dependabot).
+- **Development Dependencies:** Bumped 4 development dependencies (#1030 — Dependabot).
+
+### 🧪 Tests
+
+- **Token Accounting Tests:** Added 18 new unit tests covering detailed token breakdown, null vs zero semantics, per-provider token extraction, and Anthropic streaming input fix (#1017).
+- **Built-in Tool Tests:** Added 3 new test cases for built-in Responses API tool type preservation (#1014).
+- **ChatCore Sanitization:** Updated sanitization tests to accommodate Responses format detection (PR #1002) and built-in tool preservation (PR #1014).
+
+### 🛠️ Maintenance
+
+- **PR Workflow:** Updated `/review-prs` workflow to merge PRs into the release branch (`release/vX.Y.Z`) instead of directly into `main`, ensuring proper pre-release staging.
+
+### Coverage
+
+- **2537 tests, 2532 passing** — Statement coverage: 91.95%, Branch coverage: 78.79%, Function coverage: 93.19%
+
 ## [3.5.3] - 2026-04-07
 
 ### Security

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:22-bookworm-slim AS builder
+FROM node:22.22.2-trixie-slim AS builder
 WORKDIR /app
 
 RUN apt-get update \
@@ -13,7 +13,7 @@ RUN if [ -f package-lock.json ]; then npm ci --no-audit --no-fund; else npm inst
 COPY . ./
 RUN mkdir -p /app/data && npm run build -- --webpack
 
-FROM node:22-bookworm-slim AS runner-base
+FROM node:22.22.2-trixie-slim AS runner-base
 WORKDIR /app
 
 LABEL org.opencontainers.image.title="omniroute" \

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, 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**
 
@@ -243,7 +243,7 @@ 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**)
 - **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
 
 </details>
@@ -255,7 +255,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
@@ -341,7 +341,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>
 
@@ -486,6 +486,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
 
@@ -774,6 +775,17 @@ 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:
@@ -954,7 +966,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 +1069,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       |
 
 ---
 
@@ -1304,7 +1316,22 @@ 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                                                                                                                |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal scripts for all install methods |
+| 🔧 **OAuth Env Repair**           | One-click "Repair env" action for OAuth providers restores missing environment variables and fixes broken auth state        |
+| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` now shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop app 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 in provider dashboard (`di*****@g****.com`), full address visible on hover                      |
+| 🔗 **Context Relay Strategy**     | Combo strategy that preserves 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 — no more bypass in restricted envs    |
+| ⚠️ **Node.js 24 Login Warning**   | Login page proactively detects incompatible Node.js versions and shows a clear warning banner with instructions             |
+| 📎 **Gemini PDF Attachments**     | PDF files attached in chat messages are now 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)
 
@@ -1356,7 +1383,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                    |
@@ -2161,7 +2189,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,21 +2207,24 @@ 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)              | 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               |
+| [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                        |
 
 ---
 

audit_results.json

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

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}`))
-      }
-    })
-  })
-}

debug2.log

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

docker-compose.yml

@@ -28,7 +28,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 +63,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,7 +96,7 @@ 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
@@ -135,7 +135,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
 
@@ -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

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-11_
 
 ## Executive Summary
 
@@ -11,18 +11,25 @@ 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)
 - Account-level fallback (multi-account per provider)
-- OAuth + API-key provider connection management
+- 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
@@ -34,6 +41,7 @@ Core capabilities:
 - Anti-thundering herd protection with mutex locking
 - Signature-based request deduplication cache
 - Domain layer: model availability, 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
@@ -41,7 +49,16 @@ Core capabilities:
 - 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/`)
+- 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
 
 Primary runtime model:
 
@@ -72,7 +89,7 @@ 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, model routing rules, manual persisted ordering
 - `/dashboard/costs` — cost aggregation and pricing visibility
 - `/dashboard/analytics` — usage analytics and evaluations
 - `/dashboard/limits` — quota/rate controls
@@ -220,6 +237,8 @@ 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
 
 Domain layer modules:
 
@@ -237,7 +256,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`
@@ -612,15 +631,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 +664,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 +680,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,16 +750,14 @@ 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
 
@@ -758,7 +796,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 +824,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 +839,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 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies, **Context Relay** handoff config), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
+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 24+ detection**: `/api/settings/require-login` returns `nodeVersion` and `nodeCompatible` fields. The login page renders a warning banner when the runtime is incompatible.
 
 ## Operational Verification Checklist
 

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/FEATURES.md

@@ -16,7 +16,7 @@ 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.
 
 ![Combos Dashboard](screenshots/02-combos.png)
 
@@ -66,7 +66,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 +92,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 +201,6 @@ 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.

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      | You may be on Node.js 24+ — 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 Node.js 24+. The `better-sqlite3` native binary is not compatible with Node.js 24, which causes a fatal crash when the server tries to initialize the database.
+
+**Symptoms:**
+
+- Login page shows a blank screen or a server error
+- Console shows `Error: Module did not self-register` or similar native binding errors
+- Starting with v3.5.5, the login page shows an **orange warning banner** with your Node version if incompatibility is detected
+
+**Fix:**
+
+1. Install Node.js 22 LTS (recommended):
+   ```bash
+   nvm install 22
+   nvm use 22
+   ```
+2. Verify your version: `node --version` should show `v22.x.x`
+3. Reinstall OmniRoute: `npm install -g omniroute`
+4. Restart: `omniroute`
+
+> **Supported versions:** Node.js 18, 20, or 22 LTS. Node.js 24+ is **not 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.13.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 remains **Node.js 18, 20, or 22 LTS** (`engines` field in `package.json`). If you are on Node.js 24, the rebuild may silence this specific startup error but other issues can still occur — downgrading to Node.js 22 LTS remains the recommended path.
+
+---
+
+## 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,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
 
@@ -121,8 +205,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/USER_GUIDE.md

@@ -221,6 +221,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
 
 ```
@@ -337,6 +339,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 +504,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 +535,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`)                                          |

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/i18n/ar/docs/CODEBASE_DOCUMENTATION.md

@@ -371,7 +371,7 @@ import "./request/claude-to-openai.js"; // ← self-registers
 | "stream.ts"        | **SSE Transform Stream**— خط أنابيب البث الأساسي. وضعان: "الترجمة" (ترجمة كاملة) و"العبور" (التطبيع + الطلب المستخدم). وأخذ بعين الاعتبار التخزين المؤقت للقطعة وتقدير استخدامها وتتبع طول الفيديو. تجنب مثيلات وحدة التشفير/وحدة فك التشفير لكل حالة DC المشتركة. |
 | `streamHelpers.ts` | SSE ذات المستوى المنخفض: `parseSSELine` (متسامح مع المسافات البيضاء)، `hasValuableContent` ( تصفية أدوات الفارغة لـ OpenAI/Claude/Gemini)، `fixInvalidId`، `formatSSE` (تسلسل SSE مدرك للتنسيق مع `perf_metrics`).                                                 |
 | `usageTracking.ts` | استخدام النسخة المميزة من أي تنسيق (Claude/OpenAI/Gemini/Responses)، والاستعانة بـ DNS لكل رمز مميز للأداة/الرسالة، والمخزن المؤقت (هامش أمان 2000 رمز مميز)، وتصفية الخاصيات بالتنسيق، وتسجيل وحدة التحكم مع ANSI.                                                |
-| `requestLogger.ts` | تسجيل الطلب إلى الملف (قم بالاشتراك عبر `ENABLE_REQUEST_LOGS=true`). ينشئ مجلدات الجلسة بملفات مرقمة: `1_req_client.json` → `7_res_client.txt`. كل عمليات الإدخال/الإخراج غير متزامنة (أطلق النار وانسى). داخل المسام.                                             |
+| `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` | ويمثل خيارًا محددًا لـ Claude CLI (عنوان الإنتاج، والحماية، والعد) ويعيد ميزة دون الاتصال بأي مكان. يدعم كل من الدف وغير الدف. لذلك عمدا على نطاق كلود CLI.                                                                                                        |
 | `networkProxy.ts`  | يحل عنوان URL للوكلاء لموفر معين مع الأسبقية: تفعيل الخاص بالموفر → تفعيل العام → متغيرات البيئة (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). يدعم استثناءات `NO_PROXY`. اختيارية ذاكرة تخزين مؤقتة لمدة 30 ثانية.                                                    | #### خط أنابيب تدفق SSE```mermaid |
 

docs/i18n/ar/docs/FEATURES.md

@@ -4,70 +4,168 @@
 
 ---
 
-دليل مرئي لكل قسم من معلومات لوحة OmniRoute.---## 🔌 Providers
 
-إدارة اتصالات الذكاء الصناعي: موفري OAuth (Claude Code وCodex وGemini CLI) وموفري مفاتيح API (Groq وDeepSeek وOpenRouter) ومقدمي خدمات العيد (Qoder وQwen وKiro). لحسابات كيرو على تتبع الاعتماد الائتماني - الأرصدة النهائية لإجمالي استطلاعات الرأي المتخصصة في لوحة التحكم → استخدام.![Providers Dashboard](screenshots/01-providers.png)---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+![Providers Dashboard](screenshots/01-providers.png)
+
+---
 
 ## 🎨 Combos
 
-أنشئ مجموعات التوجيه باستخدام 6 إستراتيجيات: نأمل، والمتزايدة، والدورية، والعشوائية، وأقل استخدامًا، والمُحسّن من حيث التكلفة. وخاصة مجموعة نماذج متعددة مع اختلافات سريعة وفحوصات للجاهزية.![Combos Dashboard](screenshots/02-combos.png)---
+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.
+
+![Combos Dashboard](screenshots/02-combos.png)
+
+---
 
 ## 📊 Analytics
 
-تحليلات استخدام شاملة مع الرمز المميز، وتقديرات التكلفة، وخرائط، ومخططات التوزيع الأسبوعية، والتفاصيل لكل محمية.![Analytics Dashboard](screenshots/03-analytics.png)---
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
+
+---
 
 ## 🏥 System Health
 
-التسجيل في الوقت الفعلي: وقت العمل، والذاكرة، والإصدار، والنسب لزمن الوصول (p50/p95/p99)، وإحصائيات ذاكرة التخزين المؤقتة، وحالات منع دائرة الموفر.![Health Dashboard](screenshots/04-health.png)---
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+![Health Dashboard](screenshots/04-health.png)
+
+---
 
 ## 🔧 Translator Playground
 
-أدوات لتصحيح أخطاء ترجمات برمجة التطبيقات:**ساحة اللعب**(محول أربعة نجاح)،**اختبار الدردشة**(الطلب المباشر)،**منصة الاختبار**(اختبارات الدفعة)، و**المراقب المباشر**(بث الوقت في العمل).![Translator Playground](screenshots/05-translator.png)---
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+![Translator Playground](screenshots/05-translator.png)
+
+---
 
 ## 🎮 Model Playground _(v2.0.9+)_
 
-اختبر أي نموذج مباشرة من لوحة القيادة. حدد الموفر والطراز والنقطة النهائية، وكتب المطالبات باستخدام محرر موناكو، وقم بتفعيل الاستثناءات في المنتج الفعلي، وإلغاء منتصف الدفق، والمعايرة التقليدية مرة.---## 🎨 Themes _(v2.0.5+)_
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
 
-ألوان قابلة للتخصيص لمعلومات لوحة المفاتيح بأكملها. اختر من بين 7 ألوان محددة ليمين (مرجاني، أزرق، أخضر، بنفسجي، لون أحمر، سماوي) أو قم باختيار سمة مخصصة عن طريق اختيار أي سداسي عشري. يدعم وضع الضوء والظلام النظام.---## ⚙️ Settings
+---
 
-لوحة الإعدادات شاملة مع علامات التبويب:
+## 🎨 Themes _(v2.0.5+)_
 
--**عام**— تخزين النظام، وإدارة النسخ الاحتياطي (قاعدة بيانات التصدير/الاستيراد) -**المظهر**— محدد السماعة (داكن/فاتح/نظام)، الإعدادات المسبقة لموضوع الألوان والألوان المخصصة، ورؤية السجل الصحي، وعناصر التحكم في رؤية عنصر الشريط الجانبي -**الأمان**— حماية نقطة نهاية واجهة برمجة التطبيقات، وحظر الموفر المخصص، وتصفية IP، ومعلومات الاتصال -**التوجيه**— الأسماء المستعارة للنماذج، و الابتكارات الخلفية -**المرونة**— ونتيجة لذلك الحد الأقصى للمعدل، وضبط القيود، والتعطيل التلقائي للحسابات المحظورة، وانتهاء صلاحية الموفر -**متقدم**— تجاوز، ومسار تدقيق فقط، وتطبيق التدمير الاحتياطي![Settings Dashboard](screenshots/06-settings.png)---
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring, **Context Relay** handoff threshold and summary model configuration
+- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
+
+![Settings Dashboard](screenshots/06-settings.png)
+
+---
 
 ## 🔧 CLI Tools
 
-ختمة واحدة لأدوات تميز الذكاء الصناعي: Claude Code، وCodex CLI، وGemini CLI، وOpenClaw، وKilo Code، وAntigravity، وCline، وContinue، وCursor، وFactory Droid. تم تفعيل/إعادة ضبط تلقائي، فقط تعريف الاتصال، والنتائج المباشرة.![CLI Tools Dashboard](screenshots/07-cli-tools.png)---
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+
+---
 
 ## 🤖 CLI Agents _(v2.0.11+)_
 
-لوحة معلومات للتحكم في وكلاء CLI. تم عرض شبكة مكونة من 14 وكيلًا مدمجًا (Codex وClaude وGoose وGemini CLI وOpenClaw وAider وOpenCode وCline وQwen Code وForgeCode وAmazon Q وOpen Interpreter وCursor CLI وWarp) مع:
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
 
--**حالة التثبيت**— تم التثبيت/لم يتم العثور عليه باستخدام اكتشاف الإصدار -**توصيات المذكورة**— stdio، HTTP، وما إلى ذلك. -**الوكلاء يستهدفون**— هل هناك أي أداة لواجهة سطر الوكيل (CLI) عبر النموذج (الاسم، ثنائي، أمر الإصدار، وسيط النشر) -**مطابقة بصمة CLI**— التبديل لكل المرشحين لمطابقة توقيعات طلب CLI الأصلية، مما سيقدر من المبدع بالفعل مع ضمان عنوان IP الوكيل---## 🖼️ Media _(v2.0.3+)_
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
 
-موجود في الصور ومقاطع الفيديو والموسيقى من لوحة التحكم. يدعم OpenAI وxAI وTogether وHyperbolic وSD WebUI وComfyUI وAnimateDiff وStable Audio Open وMusicGen.---## 📝 Request Logs
+---
 
-تسجيل طلبات الإنتاج في الواقع باستخدام التصفية حسب الموفر والطراز والحساب ومفتاح واجهة برمجة التطبيقات. معلمات القيمة الناتجة عن التعويض الطبيعي ووقت التعويض وتفاصيل التعويض.![Usage Logs](screenshots/08-usage.png)---
+## 🔗 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
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+![Usage Logs](screenshots/08-usage.png)
+
+---
 
 ## 🌐 API Endpoint
 
-نقطة نهاية واجهة برمجة التطبيقات الموحدة الخاصة بك مع تفاصيل التفاصيل: عمليات التسجيل، وواجهة برمجة تطبيقات الاستجابات، والتضمينات، وأي الصور، إلى الإعداد، والنسخة الصوتية، تحويل النص إلى كلام، والإشراف، ومفاتيح واجهة برمجة التطبيقات المفقودة. تكامل Cloudflare Quick Tunnel للتواصل مع وكيل السحابي للوصول إليه بعد.![Endpoint Dashboard](screenshots/09-endpoint.png)---
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)
+
+---
 
 ## 🔑 API Key Management
 
-إنشاء مفاتيح API ونطاقها لربط وإلها. يمكن أن يكون هناك كل المفاتيح الرئيسية على/موفري خدمات محددة لهم حق الوصول الكامل أو أذونات القراءة فقط. إدارة المفاتيح المرئية مع تكرار الاستخدام.---## 📋 Audit Log
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
 
-متابعة الإجراءات الإدارية بالتصفية حسب نوع الإجراء والممثل والهدف وعنوان IP والطابع الزمني. سجل الأحداث الأمنية الكاملة.---## 🖥️ Desktop Application
+---
 
-تطبيق Native Electron لسطح المكتب لأنظمة التشغيل Windows وmacOS وLinux. قم بالموافقة على OmniRoute كتطبيق مستقل مع نظام متكامل للنظام والدعم دون الاتصال والتحديث التلقائي والتثبيت بنقرة واحدة.
+## 📋 Audit Log
 
-الميزات الرئيسية:
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
 
-- استقصاء جاهزية الضيوف (لا توجد شاشة عند التشغيل البارد)
-- نظام إدارة المنافذ
-- اتخاذ القرار بشأن المحتوى
-- مثال واحد
-- التحديث التلقائي عند إعادة التشغيل
-- واجهة المستخدم مشروطة بالكامل (إشارات المرور لنظام التشغيل MacOS، وشريط العنوان الإلكتروني لنظام التشغيل Windows/Linux)
-- بناء الإلكترون المقوى - يتم إبتكار "وحدات_العقدة" وتشهد بالرمز في المقترحات ورفضها قبل قبولها، مما يمنع الاعتماد في وقت التشغيل على البناء (الإصدار 2.5.5+)
+---
 
-📖 راجع [`electron/README.md`](../electron/README.md) للحصول على التوثيق الكامل.
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/ar/docs/TROUBLESHOOTING.md

@@ -4,65 +4,147 @@
 
 ---
 
-المشاكل والحلول الشائعة لـ OmniRoute.---## Quick Fixes
+Common problems and solutions for OmniRoute.
 
-| مشكلة                                 | الحل                                                                  |
-| ------------------------------------- | --------------------------------------------------------------------- | --------------------- |
-| تسجيل الدخول الأول لا يعمل            | قم بزيارة `INITIAL_PASSWORD` في `.env` (بدون ترميز افتراضي)           |
-| بدأت لوحة المعلومات على المنفذ الخاطئ | قم بزيارة `PORT=20128` و`NEXT_PUBLIC_BASE_URL=http://localhost:20128` |
-| لا توجد سجلات للطلب ضمن `السجلات/`    | اضبط `ENABLE_REQUEST_LOGS=true`                                       |
-| EACCES: تم رفض الإذن                  | اضبط `DATA_DIR=/path/to/writable/dir` لتجاوز `~/.omniroute`           |
-| استراتيجية لا تنقذ                    | التحديث إلى الإصدار 1.4.11+ (إصلاح مخطط Zod لاستمرارية الإعدادات)     | ---## Provider Issues |
+---
+
+## 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 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      | You may be on Node.js 24+ — see [Node.js Compatibility](#nodejs-compatibility) 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 Node.js 24+. The `better-sqlite3` native binary is not compatible with Node.js 24, which causes a fatal crash when the server tries to initialize the database.
+
+**Symptoms:**
+
+- Login page shows a blank screen or a server error
+- Console shows `Error: Module did not self-register` or similar native binding errors
+- Starting with v3.5.5, the login page shows an **orange warning banner** with your Node version if incompatibility is detected
+
+**Fix:**
+
+1. Install Node.js 22 LTS (recommended):
+   ```bash
+   nvm install 22
+   nvm use 22
+   ```
+2. Verify your version: `node --version` should show `v22.x.x`
+3. Reinstall OmniRoute: `npm install -g omniroute`
+4. Restart: `omniroute`
+
+> **Supported versions:** Node.js 18, 20, or 22 LTS. Node.js 24+ is **not supported**.
+
+---
+
+## 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+.
+
+---
+
+## Provider Issues
 
 ### "Language model did not provide messages"
 
-**السبب:**استنفدت حصة الموفر.
+**Cause:** Provider quota exhausted.
 
-**الإصلاح:**
+**Fix:**
 
-1. تحقق من تعقب الحصص في لوحة القيادة
-2. استخدم المجموعة من المستويات التجريبية
-3. قم بالبديل إلى اللغة اللاتينية الأرخص/المجانية### تحديد المعدل
+1. Check dashboard quota tracker
+2. Use a combo with fallback tiers
+3. Switch to cheaper/free tier
 
-**السبب:**استنفدت حصة الاشتراك.
+### Rate Limiting
 
-**الإصلاح:**
+**Cause:** Subscription quota exhausted.
 
-- إضافة بيع: `cc/clude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-- استخدم GLM/MiniMax كنسخة بيعية بسعر رخيص### OAuth Token منتهي الصلاحية
+**Fix:**
 
-يقوم OmniRoute بكتابة الشعارات المميزة. إذا كانت هناك مشاكل:
+- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Use GLM/MiniMax as cheap backup
 
-1. لوحة المعلومات → الموفر → إعادة الاتصال
-2. قم بإلغاء الحذف وإضافة اتصال الموفر---## Cloud Issues
+### OAuth Token Expired
+
+OmniRoute auto-refreshes tokens. If issues persist:
+
+1. Dashboard → Provider → Reconnect
+2. Delete and re-add the provider connection
+
+---
+
+## Cloud Issues
 
 ### Cloud Sync Errors
 
-1. تحقق من نقاط `BASE_URL` لمثيلك قيد التشغيل (على سبيل المثال، `http://localhost:20128`)
-2. تحقق من نقاط `CLOUD_URL` إلى نقطة نهاية السحابة الخاصة بك (على سبيل المثال، `https://omniroute.dev`)
-3. حافظ على قيم `NEXT_PUBLIC_*` مع قيم من جانب العمال### Cloud `stream=false` Returns 500
+1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
+2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
+3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
 
-**العلامة:**`الرمز المميز 'd'...' غير متوقع في نقطة نهاية السحابة للمكالمات غير المتدفقة.
+### Cloud `stream=false` Returns 500
 
-**السبب:**يقوم المنبع بإرجاع حمولة SSE أثناء العميل JSON.
+**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
 
-**الحل البديل:**استخدم `stream=true` للمكالمات السحابية المباشرة. قم بتضمين SSE المحلي → JSON الاحتياطي.### السحابة تقول أنها متصلة ولكن "مفتاح API غير صالح"
+**Cause:** Upstream returns SSE payload while client expects JSON.
 
-1. أنشئ مفتاحًا جديدًا من لوحة التحكم المحلية (`/api/keys`)
-2. قم بتشغيل البروتوكولات السحابية: قم بتمكين السحابة → النوبات الآن
-3. لا يزال بإمكانها المفاتيح القديمة/غير المتزامنة إرجاع "401" على السحابة---## Docker Issues
+**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
+
+### Cloud Says Connected but "Invalid API key"
+
+1. Create a fresh key from local dashboard (`/api/keys`)
+2. Run cloud sync: Enable Cloud → Sync Now
+3. Old/non-synced keys can still return `401` on cloud
+
+---
+
+## Docker Issues
 
 ### CLI Tool Shows Not Installed
 
-1. تحقق من استهلاك وقت التشغيل: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
-2. بالنسبة لوضع الهاتف المحمول: استخدم الصورة الهدف `runner-cli` (CLIs المجمعة)
-3. بالنسبة لصلاحية التثبيت المحلية: قم بـ `CLI_EXTRA_PATHS` وتثبيت دليل المضيفة للقراءة فقط
-4. إذا كان "تم التثبيت = صحيح" و"قابل للتشغيل = خطأ": تم العثور على الملف الثنائي ولكن فشل التحقق من الصحة### Quick Runtime Validation```bash
-   curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
-   curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
-   curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. For portable mode: use image target `runner-cli` (bundled CLIs)
+3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
+4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
 
-````
+### Quick Runtime Validation
+
+```bash
+curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+```
 
 ---
 
@@ -70,106 +152,163 @@
 
 ### High Costs
 
-1. التحقق من إحصائيات استخدام لوحة المعلومات →
-2. قم باستبدال النموذج الأساسي بـ GLM/MiniMax
-3. استخدم طلب التقديم (Gemini CLI، Qoder) للمهام غير المرغوب فيه
-4. قم بإنشاء اقتصاديات التكلفة لكل مفتاح برمجة التطبيقات: لوحة المعلومات ← مفاتيح برمجة التطبيقات ← الميزانية---## Debugging
+1. Check usage stats in Dashboard → Usage
+2. Switch primary model to GLM/MiniMax
+3. Use free tier (Gemini CLI, Qoder) for non-critical tasks
+4. Set cost budgets per API key: Dashboard → API Keys → Budget
 
-### Enable Request Logs
+---
 
-قم بزيارة `ENABLE_REQUEST_LOGS=true` في ملف `.env` الخاص بك. تسجيل سجلات ضمن دليل "السجلات/".### التحقق من صحة المزود```bash
+## Debugging
+
+### Enable Log Files
+
+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
+
+```bash
 # Health dashboard
 http://localhost:20128/dashboard/health
 
 # API health check
 curl http://localhost:20128/api/monitoring/health
-````
+```
 
 ### Runtime Storage
 
-- الحالة الرئيسية: `${DATA_DIR}/storage.sqlite` (الموفرون، المجموعات، الأسماء المستعارة، المفاتيح، الإعدادات)
-  -استخدام: جداول SQLite في `storage.sqlite` (`usage_history`، `call_logs`، `proxy_logs`) + اختياري `${DATA_DIR}/log.txt` و`${DATA_DIR}/call_logs/`
-- أرشيف الطلب: `<repo>/logs/...` (عندما يكون `ENABLE_REQUEST_LOGS=true`)---## Circuit Breaker Issues
+- 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}/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
+
+---
+
+## Circuit Breaker Issues
 
 ### Provider stuck in OPEN state
 
-عندما يكون حظر دائرة الموفر مفتوحًا، يتم حظره حتى نهاية فترة التهدئة.
+When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
 
-**الإصلاح:**
+**Fix:**
 
-1. انتقل إلى**لوحة التحكم ← الإعدادات ← طيران**
-2. التحقق من بطاقة القاطع الكهربائي الخاصة بالمزود المتأثر
-3. انقر فوق**إعادة تعيين الكل**لمسح جميع القواطع، أو انتظر حتى انتهاء فترة التهدئة
-4. التحقق من أن الموفر فعلياً قبل العودة### مقدم الخدمة يستمر في قطع قاطع الدائرة الكهربائية
+1. Go to **Dashboard → Settings → Resilience**
+2. Check the circuit breaker card for the affected provider
+3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
+4. Verify the provider is actually available before resetting
 
-إذا وصلت الخدمة بشكل عام في الحالة المفتوحة:
+### Provider keeps tripping the circuit breaker
 
-1. تحقق من**لوحة التحكم ← الصحة ← صحة مقدم الخدمة**نمط المعرفة تبني
-2. انتقل إلى**الإعدادات → اختلاف → ملفات تعريف الموفر**وكم حتى حد ما
-3. تحقق مما إذا كان الموفر قد قام بتغيير حدود واجهة برمجة التطبيقات (API) أو طلب إعادة المصادقة
-4. قم بمراجعة القياس عن بعد لزمن التعرض - قد يتسبب في حدوث التأثيرات الناتجة في سبب واحد بسبب انتهاء المهلة---## Audio Transcription Issues
+If a provider repeatedly enters OPEN state:
+
+1. Check **Dashboard → Health → Provider Health** for the failure pattern
+2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
+3. Check if the provider has changed API limits or requires re-authentication
+4. Review latency telemetry — high latency may cause timeout-based failures
+
+---
+
+## Audio Transcription Issues
 
 ### "Unsupported model" error
 
-- تأكد من أنك تستخدم القواعد الصحيحة: `deepgram/nova-3` أو `assemblyai/best`
-- تحقق من أن الموفر متصل في**لوحة التحكم ← الموفرون**### يعود النسخ فارغًا أو فاشلًا
+- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
+- Verify the provider is connected in **Dashboard → Providers**
 
-- التحقق من تنسيقات الصوت المدعومة: `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`
-- التحقق من أن حجم الملف يقع ضمن حدود الموفر (عادةً أقل من 25 ميجابايت)
-- التحقق من صلاحية مفتاح API الخاص بالموفر في البطاقة المزودة---## Translator Debugging
+### Transcription returns empty or fails
 
-استخدم**لوحة المعلومات → المترجم**لتصحيح المناسب لرغبتك:
+- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Verify file size is within provider limits (typically < 25MB)
+- Check provider API key validity in the provider card
 
-| الوضع              | متى تستخدم                                                                     |
-| ------------------ | ------------------------------------------------------------------------------ | -------------------------- |
-| **ساحة اللعب**     | قارن ملفات الإدخال/الإخراج جنباً إلى جنب — لا لصق طلباً فاشلاً لترى كيف ترجمته |
-| **اختبار الدردشة** | أرسل الرسائل مباشرة وافحص فاعلية الطلب/الاستجابة الكاملة بما في ذلك الرؤوس     |
-| **الاختبار**       | قم بإنهاء الفقرات المجمعة عبر مجموعات محددة على الترجمات المعطلة               |
-| **مراقبة حية**     | شاهد تدفق الطلبات في التنسيق المطلوب على الترجمة المتقطعة                      | ### مشكلات التنسيق الشائعة |
+---
 
--**لا تضع علامات التفكير**— تحقق مما إذا كان الموفر المستهدف مقبولاً يمكن توقعه -**استدعاءات مساعدة**— قد توفر بعض الترجمات بشكل فعال لحذف الأشخاص غير المساعدين؛ تحقق في وضع الملعب -**مطالبة النظام مفقودة**— نظام Claude وGemini مع المطالبات المختلفة؛ التحقق من إخراج الترجمة -**ترجع سلسلة SDK أولية أخرى من**- تم إصلاح ذلك في الإصدار 1.1.0: تقوم أداة التأثير الفوري الآن وأنواعها غير الممتازة (`x_groq`، و`usage_breakdown`، وما إلى ذلك) التي فشلت في التحقق من صحة OpenAI SDK Pydantic -**GLM/ERNIE يرفض دور `النظام`**- تم إصلاحه في الإصدار 1.1.0: يقوم بـ«تطبيع الدور التنفيذي برسائل مدمجة في النظام في رسائل المستخدم للنماذج غير المتوافقة» -**لم يتم التعرف على دور "المطور"**- تم إصلاحه في الإصدار 1.1.0: تم تحويله تلقائياً إلى "نظام" لتقديم الخدمات غير التابعة لـ OpenAI -**`json_schema` لا يعمل مع Gemini**— تم إصلاحه في الإصدار 1.1.0: تم الآن تحويل `response_format` إلى `responseMimeType` + `responseSchema` الخاص بـ Gemini---## Resilience Settings
+## Translator Debugging
+
+Use **Dashboard → Translator** to debug format translation issues:
+
+| Mode             | When to Use                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| **Playground**   | Compare input/output formats side by side — paste a failing request to see how it translates |
+| **Chat Tester**  | Send live messages and inspect the full request/response payload including headers           |
+| **Test Bench**   | Run batch tests across format combinations to find which translations are broken             |
+| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues                        |
+
+### Common format issues
+
+- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
+- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
+- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
+- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures
+- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
+- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers
+- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema`
+
+---
+
+## Resilience Settings
 
 ### Auto rate-limit not triggering
 
-- يُطبق حتى يتم التعديل تلقائيًا فقط على لوحة مفاتيح برمجة التطبيقات (وليس OAuth/الاشتراك)
-- تحقق من أن**الإعدادات → ← ملفات تعريف الموفر**تم وأيضا تعديلها بشكل تلقائي
-- تحقق مما إذا كان الموفر يعرض رموز الحالة "429" أو الذاكرة "إعادة المحاولة بعد".### ضبط التراجع الأسي
+- Auto rate-limit only applies to API key providers (not OAuth/subscription)
+- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
+- Check if the provider returns `429` status codes or `Retry-After` headers
 
-تدعم ملفات تعريف الموفر هذه الإعدادات:
+### Tuning exponential backoff
 
--**التأخير الأساسي**— وقت الانتظار الأول بعد الأول (الافتراضي: 1 ثانية) -**الحد الأقصى للتأخير**— الحد الأقصى لوقت الانتظار (الافتراضي: 30 ثانية) -**المضاعف**— كمية الزيادة الشاملة لكل فشل متتالي (الافتراضي: 2x)### قطيع مضاد الرعد
+Provider profiles support these settings:
 
-عندما تصل العديد من الطلبات المتزامنة إلى وفرة السعر، يستخدم تقنية OmniRoute تقنية Mutex + تحديد موعد مباشر لتنزيل الطلبات مباشرة من أجل توقف الحالات المتتالية. وهذا تلقائي لموفري مفاتيح API.---## Optional RAG / LLM failure taxonomy (16 problems)
+- **Base delay** — Initial wait time after first failure (default: 1s)
+- **Max delay** — Maximum wait time cap (default: 30s)
+- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
 
-يقوم بعض مستخدمي OmniRoute بالتحرك أمام RAG أو مكدسات الوكيل. في هذه الإعدادات، من الشائع رؤية نمط غريب: يبدو OmniRoute سليمًا (مقدمو خدمة في وضع جيد، وإصدار الأحكام الشخصية على ما بعد، ولا توجد تنبيهات بخلاف حدود القضاء) ولكن الإجابة لا تزال لا تزال صحيحة.
+### Anti-thundering herd
 
-ومن ثم، يأتي هذا الذي يأتي من خط الأنابيب النهائي RAG، وليس من نفسه.
+When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
 
-إذا كنت تريد مفردات الحصول على وصف لتلك الإخفاقات، فيمكنك استخدام WFGY IssueMap، وهو مصدر ترخيص MIT الخارجي يحدد ستة عشرة نمطًاًا لفشل RAG / LLM. على مستوى عال يغطي:
+---
 
-- الانجراف استرجاع وحدود السياقة المكسورة
-- الفهارس الفارغة أو القديمة ومخازن المتجهات
-- التضمين مقابل عدم التطابق الدلالي
-- رخص السياقة ورافعة السياقة
-- مجموعة واسعة من الإجابات الاستخدام في التجارة الحرة
-- خلل في النص بين النص والوكيل
-- ذاكرة متعددة للعامل والمؤثرات
-- مشاكل النشر والتمهيد
+## Optional RAG / LLM failure taxonomy (16 problems)
 
-فكرة بسيطة:
+Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong.
 
-1. عندما تقوم بالتحقق من خلل في حسابك، قم بالقاطع:
-   - مهمة المستخدم وطلبه
-   - مجموعة الطريق أو المورد في OmniRoute
-   - أي مؤتمر RAG في المراحل النهائية (المستندات المستردة، وأدوات الأدوات، وما إلى ذلك)
-2. قم بتخطيط الحادث لواحد أو من أرقام WFGY IssueMap (`رقم 1`...`رقم 16`).
-3. قم بتخزين الرقم في لوحة المعلومات الخاصة بك، أو دليل التشغيل، أو أداة التعقب بجوار سجلات OmniRoute.
-4. استخدم صفحة WFGY لتقرر ما إذا كنت تريد تغيير مكدس RAG أو المسترد أو استراتيجية التوجيه.
+In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself.
 
-النص الكامل والوصفات الملموسة موجودة هنا (ترخيص معهد ماساتشوستس فارس، النص فقط):
+If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers:
 
-[الملف التمهيدي لخريطة مشاكل WFGY](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
+- retrieval drift and broken context boundaries
+- empty or stale indexes and vector stores
+- embedding versus semantic mismatch
+- prompt assembly and context window issues
+- logic collapse and overconfident answers
+- long chain and agent coordination failures
+- multi agent memory and role drift
+- deployment and bootstrap ordering problems
 
-ستتجاهل هذا القسم إذا لم تسمح لـ RAG أو خطوط الأنابيب الخارجية خلف OmniRoute.---## Still Stuck?
+The idea is simple:
 
--**مشكلات GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -**الهندسة الداخلية**: راجع [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) للحصول على التفاصيل -**مرجع واجهة برمجة التطبيقات**: راجع [`docs/API_REFERENCE.md`](API_REFERENCE.md) -**لوحة معلومات الصحة**: التحقق من**معلومات اللوحة ← صحة**معرفة النظام في الوقت الفعلي -**المترجم**: استخدم**لوحة المعلومات ← المترجم**ل التصحيح المناسب لك
+1. When you investigate a bad response, capture:
+   - user task and request
+   - route or provider combo in OmniRoute
+   - any RAG context used downstream (retrieved documents, tool calls, etc)
+2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`).
+3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs.
+4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy.
+
+Full text and concrete recipes live here (MIT license, text only):
+
+[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
+
+You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute.
+
+---
+
+## Still Stuck?
+
+- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
+- **Translator**: Use **Dashboard → Translator** to debug format issues

docs/i18n/ar/docs/VM_DEPLOYMENT_GUIDE.md

@@ -93,7 +93,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/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/bg/docs/ARCHITECTURE.md

@@ -4,80 +4,91 @@
 
 ---
 
-_Последна актуализация: 2026-03-28_## Executive Summary
+_Last updated: 2026-03-28_
 
-OmniRoute е локален AI маршрутизиращ шлюз и табло за управление, изградено на Next.js.
-Той осигурява единична OpenAI-съвместима крайна точка (`/v1/*`) и маршрутизира трафик през множество доставчици нагоре по веригата с превод, резервен вариант, опресняване на токени и проследяване на използването.
+## Executive Summary
 
-Основни възможности:
+OmniRoute is a local AI routing gateway and dashboard built on Next.js.
+It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
 
-- OpenAI-съвместима API повърхност за CLI/инструменти (28 доставчици)
-- Превод на заявка/отговор във форматите на доставчика
-- Резервна комбинация от модели (последователност от няколко модела)
-- Резервен вариант на ниво акаунт (мулти акаунт на доставчик)
-- OAuth + API-ключ управление на връзката на доставчика
-- Генериране на вграждане чрез `/v1/embeddings` (6 доставчика, 9 модела)
-- Генериране на изображения чрез `/v1/images/generations` (4 доставчика, 9 модела)
-- Синтактичен анализ на таг за мислене (`<think>...</think>`) за разсъждаващи модели
-- Дезинфекция на отговора за стриктна съвместимост с OpenAI SDK
-- Нормализиране на ролята (разработчик→система, система→потребител) за съвместимост между доставчици
-- Структурирано преобразуване на изход (json_schema → Gemini responseSchema)
-- Локална устойчивост за доставчици, ключове, псевдоними, комбинации, настройки, ценообразуване
-- Проследяване на използване/разходи и регистриране на заявки
-- Допълнителна облачна синхронизация за синхронизиране на множество устройства/състояние
-- Списък с разрешени/блокирани IP адреси за контрол на достъпа до API
-- Мислещо управление на бюджета (преминаване/автоматично/персонализирано/адаптивно)
-- Бързо инжектиране на глобалната система
-- Проследяване на сесии и пръстови отпечатъци
-- Подобрено ограничаване на скоростта за всеки акаунт със специфични за доставчика профили
-- Модел на прекъсвача за устойчивост на доставчика
-- Анти-гръмотевична стадна защита с mutex заключване
-- Кеш за дедупликация на заявки, базиран на подпис
-- Слой на домейна: наличност на модела, правила за разходите, резервна политика, политика за блокиране
-- Устойчивост на състоянието на домейна (кеш за запис на SQLite за резервни варианти, бюджети, блокировки, прекъсвачи на верига)
-- Механизъм за правила за централизирана оценка на заявката (заключване → бюджет → резервен)
-- Заявка за телеметрия с p50/p95/p99 агрегиране на латентност
-- ID на корелация (X-Request-Id) за проследяване от край до край
-- Регистриране на одит за съответствие с отказ за всеки API ключ
-- Eval framework за осигуряване на качеството на LLM
-- Resilience UI табло със статус на прекъсвача в реално време
-- Модулни OAuth доставчици (12 отделни модула под `src/lib/oauth/providers/`)
+Core capabilities:
 
-Основен модел на изпълнение:
+- OpenAI-compatible API surface for CLI/tools (28 providers)
+- Request/response translation across provider formats
+- Model combo fallback (multi-model sequence)
+- Account-level fallback (multi-account per provider)
+- OAuth + API-key provider connection management
+- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
+- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Think tag parsing (`<think>...</think>`) for reasoning models
+- Response sanitization for strict OpenAI SDK compatibility
+- Role normalization (developer→system, system→user) for cross-provider compatibility
+- Structured output conversion (json_schema → Gemini responseSchema)
+- Local persistence for providers, keys, aliases, combos, settings, pricing
+- Usage/cost tracking and request logging
+- Optional cloud sync for multi-device/state sync
+- IP allowlist/blocklist for API access control
+- Thinking budget management (passthrough/auto/custom/adaptive)
+- Global system prompt injection
+- Session tracking and fingerprinting
+- Per-account enhanced rate limiting with provider-specific profiles
+- Circuit breaker pattern for provider resilience
+- Anti-thundering herd protection with mutex locking
+- Signature-based request deduplication cache
+- Domain layer: model availability, cost rules, fallback policy, lockout policy
+- 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
+- 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/`)
 
-- Маршрутите на приложението Next.js под `src/app/api/*` внедряват както API на таблото, така и API за съвместимост
-- Споделено SSE/маршрутизиращо ядро в `src/sse/*` + `open-sse/*` обработва изпълнението на доставчика, превода, стрийминг, резервен вариант и използване## Scope and Boundaries
+Primary runtime model:
+
+- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
+- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
+
+## Scope and Boundaries
 
 ### In Scope
 
-- Време за изпълнение на локален шлюз
-- API за управление на таблото
-- Удостоверяване на доставчика и опресняване на токена
-- Заявка за превод и SSE стрийминг
-- Локално състояние + постоянство на използване
-- Допълнителна синхронизация в облака### Out of Scope
+- Local gateway runtime
+- Dashboard management APIs
+- Provider authentication and token refresh
+- Request translation and SSE streaming
+- Local state + usage persistence
+- Optional cloud sync orchestration
 
-- Внедряване на облачна услуга зад `NEXT_PUBLIC_CLOUD_URL`
-- SLA/контролна равнина на доставчика извън локалния процес
-- Самите външни CLI двоични файлове (Claude CLI, Codex CLI и т.н.)## Dashboard Surface (Current)
+### Out of Scope
 
-Главни страници под `src/app/(dashboard)/dashboard/`:
+- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
+- Provider SLA/control plane outside local process
+- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
 
-- `/dashboard` — бърз старт + преглед на доставчика
-- `/dashboard/endpoint` — крайна точка прокси + MCP + A2A + раздели за крайна точка на API
-- `/dashboard/providers` — връзки и идентификационни данни на доставчика
-- `/dashboard/combos` — комбинирани стратегии, шаблони, правила за маршрутизиране на модели
-- `/dashboard/costs` — агрегиране на разходите и видимост на цените
-- `/dashboard/analytics` — анализи и оценки на използването
-- `/dashboard/limits` — контроли на квоти/ставки
-- `/dashboard/cli-tools` — CLI включване, откриване по време на изпълнение, генериране на конфигурация
-- `/dashboard/agents` — открити ACP агенти + потребителска регистрация на агент
-- `/dashboard/media` — игрище за изображения/видео/музика
-- `/dashboard/search-tools` — тестване и история на доставчика на търсене
-- `/dashboard/health` — време на работа, прекъсвачи, ограничения на скоростта
-- `/dashboard/logs` — регистрационни файлове на заявка/прокси/одит/конзола
-- `/dashboard/settings` — раздели за системни настройки (общи, маршрутизиране, комбинирани настройки по подразбиране и т.н.)
-- `/dashboard/api-manager` — жизнен цикъл на API ключ и разрешения за модел## High-Level System Context
+## Dashboard Surface (Current)
+
+Main pages under `src/app/(dashboard)/dashboard/`:
+
+- `/dashboard` — quick start + provider overview
+- `/dashboard/endpoint` — endpoint proxy + MCP + A2A + API endpoint tabs
+- `/dashboard/providers` — provider connections and credentials
+- `/dashboard/combos` — combo strategies, templates, model routing rules
+- `/dashboard/costs` — cost aggregation and pricing visibility
+- `/dashboard/analytics` — usage analytics and evaluations
+- `/dashboard/limits` — quota/rate controls
+- `/dashboard/cli-tools` — CLI onboarding, runtime detection, config generation
+- `/dashboard/agents` — detected ACP agents + custom agent registration
+- `/dashboard/media` — image/video/music playground
+- `/dashboard/search-tools` — search provider testing and history
+- `/dashboard/health` — uptime, circuit breakers, rate limits
+- `/dashboard/logs` — request/proxy/audit/console logs
+- `/dashboard/settings` — system settings tabs (general, routing, combo defaults, etc.)
+- `/dashboard/api-manager` — API key lifecycle and model permissions
+
+## High-Level System Context
 
 ```mermaid
 flowchart LR
@@ -129,139 +140,151 @@ flowchart LR
 
 ## 1) API and Routing Layer (Next.js App Routes)
 
-Основни директории:
+Main directories:
 
-- `src/app/api/v1/*` и `src/app/api/v1beta/*` за API за съвместимост
-- `src/app/api/*` за API за управление/конфигуриране
-- Следващото пренаписване в `next.config.mjs` преобразува `/v1/*` в `/api/v1/*`
+- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
+- `src/app/api/*` for management/configuration APIs
+- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
 
-Важни пътища за съвместимост:
+Important compatibility routes:
 
 - `src/app/api/v1/chat/completions/route.ts`
 - `src/app/api/v1/messages/route.ts`
 - `src/app/api/v1/responses/route.ts`
-- `src/app/api/v1/models/route.ts` — включва потребителски модели с `custom: true`
-- `src/app/api/v1/embeddings/route.ts` — генериране на вграждане (6 доставчика)
-- `src/app/api/v1/images/generations/route.ts` — генериране на изображения (4+ доставчици, включително Antigravity/Nebius)
+- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`
+- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)
+- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)
 - `src/app/api/v1/messages/count_tokens/route.ts`
-- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — специален чат за всеки доставчик
-- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — специални вграждания за всеки доставчик
-- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — специални изображения за всеки доставчик
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images
 - `src/app/api/v1beta/models/route.ts`
 - `src/app/api/v1beta/models/[...path]/route.ts`
 
-Домейни за управление:
+Management domains:
 
-- Удостоверяване/настройки: `src/app/api/auth/*`, `src/app/api/settings/*`
-- Доставчици/връзки: `src/app/api/providers*`
-- Възли на доставчик: `src/app/api/provider-nodes*`
-- Персонализирани модели: `src/app/api/provider-models` (GET/POST/DELETE)
-- Каталог с модели: `src/app/api/models/route.ts` (GET)
-- Прокси конфигурация: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
+- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
+- Providers/connections: `src/app/api/providers*`
+- Provider nodes: `src/app/api/provider-nodes*`
+- Custom models: `src/app/api/provider-models` (GET/POST/DELETE)
+- Model catalog: `src/app/api/models/route.ts` (GET)
+- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
 - OAuth: `src/app/api/oauth/*`
-- Ключове/псевдоними/комбота/цени: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
-- Използване: `src/app/api/usage/*`
-- Синхронизиране/облак: `src/app/api/sync/*`, `src/app/api/cloud/*`
-- Помощни инструменти за CLI: `src/app/api/cli-tools/*`
-- IP филтър: `src/app/api/settings/ip-filter` (GET/PUT)
-- Мислен бюджет: `src/app/api/settings/thinking-budget` (GET/PUT)
-- Системна подкана: `src/app/api/settings/system-prompt` (GET/PUT)
-- Сесии: `src/app/api/sessions` (GET)
-- Ограничения на скоростта: `src/app/api/rate-limits` (GET)
-- Устойчивост: `src/app/api/resilience` (GET/PATCH) — профили на доставчика, прекъсвач, състояние на ограничение на скоростта
-- Нулиране на устойчивостта: `src/app/api/resilience/reset` (POST) — прекъсвачи за нулиране + охлаждане
-- Кеш статистики: `src/app/api/cache/stats` (GET/DELETE)
-- Наличност на модела: `src/app/api/models/availability` (GET/POST)
-- Телеметрия: `src/app/api/telemetry/summary` (GET)
-- Бюджет: `src/app/api/usage/budget` (GET/POST)
-- Резервни вериги: `src/app/api/fallback/chains` (GET/POST/DELETE)
-- Одит на съответствието: `src/app/api/compliance/audit-log` (GET)
+- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
+- Usage: `src/app/api/usage/*`
+- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
+- CLI tooling helpers: `src/app/api/cli-tools/*`
+- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)
+- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)
+- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)
+- Sessions: `src/app/api/sessions` (GET)
+- Rate limits: `src/app/api/rate-limits` (GET)
+- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns
+- Cache stats: `src/app/api/cache/stats` (GET/DELETE)
+- Model availability: `src/app/api/models/availability` (GET/POST)
+- Telemetry: `src/app/api/telemetry/summary` (GET)
+- Budget: `src/app/api/usage/budget` (GET/POST)
+- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET)
 - Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
-- Правила: `src/app/api/policies` (GET/POST)## 2) SSE + Translation Core
+- Policies: `src/app/api/policies` (GET/POST)
 
-Основни модули на потока:
+## 2) SSE + Translation Core
 
-- Запис: `src/sse/handlers/chat.ts`
-- Оркестрация на ядрото: `open-sse/handlers/chatCore.ts`
-- Адаптери за изпълнение на доставчик: `open-sse/executors/*`
-- Откриване на формат/конфигурация на доставчик: `open-sse/services/provider.ts`
-- Разбор/разрешаване на модела: `src/sse/services/model.ts`, `open-sse/services/model.ts`
-- Логика за резервен акаунт: `open-sse/services/accountFallback.ts`
-- Регистър на преводите: `open-sse/translator/index.ts`
-- Трансформации на потока: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
-- Извличане/нормализиране на използването: `open-sse/utils/usageTracking.ts`
-- Анализатор на мислен етикет: `open-sse/utils/thinkTagParser.ts`
-- Манипулатор за вграждане: `open-sse/handlers/embeddings.ts`
-- Регистър на доставчика на вграждане: `open-sse/config/embeddingRegistry.ts`
-- Манипулатор за генериране на изображения: `open-sse/handlers/imageGeneration.ts`
-- Регистър на доставчика на изображения: `open-sse/config/imageRegistry.ts`
-- Дезинфекция на отговора: `open-sse/handlers/responseSanitizer.ts`
-- Нормализация на ролята: `open-sse/services/roleNormalizer.ts`
+Main flow modules:
 
-Услуги (бизнес логика):
+- Entry: `src/sse/handlers/chat.ts`
+- Core orchestration: `open-sse/handlers/chatCore.ts`
+- Provider execution adapters: `open-sse/executors/*`
+- Format detection/provider config: `open-sse/services/provider.ts`
+- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
+- Account fallback logic: `open-sse/services/accountFallback.ts`
+- Translation registry: `open-sse/translator/index.ts`
+- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
+- Think tag parser: `open-sse/utils/thinkTagParser.ts`
+- Embedding handler: `open-sse/handlers/embeddings.ts`
+- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
+- Image generation handler: `open-sse/handlers/imageGeneration.ts`
+- Image provider registry: `open-sse/config/imageRegistry.ts`
+- Response sanitization: `open-sse/handlers/responseSanitizer.ts`
+- Role normalization: `open-sse/services/roleNormalizer.ts`
 
-- Избор/точкуване на акаунт: `open-sse/services/accountSelector.ts`
-- Управление на жизнения цикъл на контекста: `open-sse/services/contextManager.ts`
-- Налагане на IP филтър: `open-sse/services/ipFilter.ts`
-- Проследяване на сесии: `open-sse/services/sessionManager.ts`
-- Дедупликация на заявка: `open-sse/services/signatureCache.ts`
-- Инжектиране на системна подкана: `open-sse/services/systemPrompt.ts`
-- Мислещо управление на бюджета: `open-sse/services/thinkingBudget.ts`
-- Маршрутизиране на модел с заместващи символи: `open-sse/services/wildcardRouter.ts`
-- Управление на лимита на скоростта: `open-sse/services/rateLimitManager.ts`
-- Прекъсвач: `open-sse/services/circuitBreaker.ts`
+Services (business logic):
 
-Модули на ниво домейн:
+- Account selection/scoring: `open-sse/services/accountSelector.ts`
+- Context lifecycle management: `open-sse/services/contextManager.ts`
+- IP filter enforcement: `open-sse/services/ipFilter.ts`
+- Session tracking: `open-sse/services/sessionManager.ts`
+- Request deduplication: `open-sse/services/signatureCache.ts`
+- System prompt injection: `open-sse/services/systemPrompt.ts`
+- Thinking budget management: `open-sse/services/thinkingBudget.ts`
+- Wildcard model routing: `open-sse/services/wildcardRouter.ts`
+- Rate limit management: `open-sse/services/rateLimitManager.ts`
+- Circuit breaker: `open-sse/services/circuitBreaker.ts`
+- 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
 
-- Наличност на модела: `src/lib/domain/modelAvailability.ts`
-- Правила/бюджети за разходи: `src/lib/domain/costRules.ts`
-- Резервна политика: `src/lib/domain/fallbackPolicy.ts`
-- Комбо резолвер: `src/lib/domain/comboResolver.ts`
-- Политика за блокиране: `src/lib/domain/lockoutPolicy.ts`
-- Механизъм за правила: `src/domain/policyEngine.ts` — централизирано блокиране → бюджет → резервна оценка
-- Каталог с кодове за грешки: `src/lib/domain/errorCodes.ts`
-- ID на заявката: `src/lib/domain/requestId.ts`
-- Време за изчакване на извличане: `src/lib/domain/fetchTimeout.ts`
-- Заявка за телеметрия: `src/lib/domain/requestTelemetry.ts`
-- Съответствие/одит: `src/lib/domain/compliance/index.ts`
-- Изпълнител на оценка: `src/lib/domain/evalRunner.ts`
-- Устойчивост на състоянието на домейна: `src/lib/db/domainState.ts` — SQLite CRUD за резервни вериги, бюджети, история на разходите, състояние на блокиране, прекъсвачи
+Domain layer modules:
 
-Модули за доставчик на OAuth (12 отделни файла под `src/lib/oauth/providers/`):
+- Model availability: `src/lib/domain/modelAvailability.ts`
+- Cost rules/budgets: `src/lib/domain/costRules.ts`
+- Fallback policy: `src/lib/domain/fallbackPolicy.ts`
+- Combo resolver: `src/lib/domain/comboResolver.ts`
+- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
+- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
+- Error codes catalog: `src/lib/domain/errorCodes.ts`
+- Request ID: `src/lib/domain/requestId.ts`
+- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
+- Request telemetry: `src/lib/domain/requestTelemetry.ts`
+- Compliance/audit: `src/lib/domain/compliance/index.ts`
+- Eval runner: `src/lib/domain/evalRunner.ts`
+- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
 
-- Индекс на регистъра: `src/lib/oauth/providers/index.ts`
-- Индивидуални доставчици: `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`
-- Тънка обвивка: `src/lib/oauth/providers.ts` — повторно експортиране от отделни модули## 3) Persistence Layer
+OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
-Основно състояние DB (SQLite):
+- 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`
+- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
-- Основна информация: `src/lib/db/core.ts` (better-sqlite3, миграции, WAL)
-- Повторно експортиране на фасада: `src/lib/localDb.ts` (тънък слой за съвместимост за повикващите)
-- файл: `${DATA_DIR}/storage.sqlite` (или `$XDG_CONFIG_HOME/omniroute/storage.sqlite`, когато е зададено, иначе `~/.omniroute/storage.sqlite`)
-- обекти (таблици + KV пространства от имена): providerConnections, providerNodes, modelAliases, комбинации, apiKeys, настройки, ценообразуване,**customModels**,**proxyConfig**,**ipFilter**,**thinkingBudget**,**systemPrompt**
+## 3) Persistence Layer
 
-Устойчивост на употреба:
+Primary state DB (SQLite):
 
-- фасада: `src/lib/usageDb.ts` (декомпозирани модули в `src/lib/usage/*`)
-- SQLite таблици в `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
-- незадължителните файлови артефакти остават за съвместимост/отстраняване на грешки (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
-- наследените JSON файлове се мигрират към SQLite чрез миграции при стартиране, когато има такива
+- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL)
+- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers)
+- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`)
+- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
 
-DB на състоянието на домейна (SQLite):
+Usage persistence:
 
-- `src/lib/db/domainState.ts` — CRUD операции за състояние на домейн
-- Таблици (създадени в `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
-- Модел на кеша за запис: Картите в паметта са авторитетни по време на изпълнение; мутациите се записват синхронно в SQLite; състоянието се възстановява от DB при студен старт## 4) Auth + Security Surfaces
+- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`)
+- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
+- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
+- legacy JSON files are migrated to SQLite by startup migrations when present
 
-- Удостоверяване на бисквитките на таблото за управление: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
-- Генериране/проверка на API ключ: `src/shared/utils/apiKey.ts`
-- Тайните на доставчика се запазват в записите `providerConnections`
-- Поддръжка на изходящ прокси чрез `open-sse/utils/proxyFetch.ts` (env vars) и `open-sse/utils/networkProxy.ts` (конфигурируем за всеки доставчик или глобален)## 5) Cloud Sync
+Domain State DB (SQLite):
 
-- Инициализация на Scheduler: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
-- Периодична задача: `src/shared/services/cloudSyncScheduler.ts`
-- Периодична задача: `src/shared/services/modelSyncScheduler.ts`
-- Контролен маршрут: `src/app/api/sync/cloud/route.ts`## Request Lifecycle (`/v1/chat/completions`)
+- `src/lib/db/domainState.ts` — CRUD operations for domain state
+- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
+- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
+
+## 4) Auth + Security Surfaces
+
+- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
+- API key generation/verification: `src/shared/utils/apiKey.ts`
+- Provider secrets persisted in `providerConnections` entries
+- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
+
+## 5) Cloud Sync
+
+- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
+- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Periodic task: `src/shared/services/modelSyncScheduler.ts`
+- Control route: `src/app/api/sync/cloud/route.ts`
+
+## Request Lifecycle (`/v1/chat/completions`)
 
 ```mermaid
 sequenceDiagram
@@ -338,7 +361,9 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-Резервните решения се управляват от `open-sse/services/accountFallback.ts`, като се използват кодове за състояние и евристика за съобщения за грешка. Комбинираното маршрутизиране добавя един допълнителен предпазител: 400-те с обхват на доставчика, като неизправности при блокиране на съдържание нагоре и проверка на роли, се третират като неизправности в локален модел, така че по-късните комбинирани цели все още могат да се изпълняват.## OAuth Onboarding and Token Refresh Lifecycle
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run.
+
+## OAuth Onboarding and Token Refresh Lifecycle
 
 ```mermaid
 sequenceDiagram
@@ -368,7 +393,9 @@ sequenceDiagram
     Test-->>UI: validation result
 ```
 
-Опресняването по време на трафик на живо се изпълнява вътре в `open-sse/handlers/chatCore.ts` чрез изпълнител `refreshCredentials()`.## Cloud Sync Lifecycle (Enable / Sync / Disable)
+Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
+
+## Cloud Sync Lifecycle (Enable / Sync / Disable)
 
 ```mermaid
 sequenceDiagram
@@ -400,7 +427,9 @@ sequenceDiagram
     Sync-->>UI: disabled
 ```
 
-Периодичното синхронизиране се задейства от „CloudSyncScheduler“, когато облакът е активиран.## Data Model and Storage Map
+Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
+
+## Data Model and Storage Map
 
 ```mermaid
 erDiagram
@@ -501,12 +530,14 @@ erDiagram
     }
 ```
 
-Файлове за физическо съхранение:
+Physical storage files:
 
-- основна база данни за изпълнение: `${DATA_DIR}/storage.sqlite`
-- Редове за заявка: `${DATA_DIR}/log.txt` (компат/дебъг артефакт)
-- структурирани архиви на полезния товар на повикванията: `${DATA_DIR}/call_logs/`
-- незадължителни сесии за преводач/заявка за отстраняване на грешки: `<repo>/logs/...`## Deployment Topology
+- primary runtime DB: `${DATA_DIR}/storage.sqlite`
+- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact)
+- structured call payload archives: `${DATA_DIR}/call_logs/`
+- optional translator/request debug sessions: `<repo>/logs/...`
+
+## Deployment Topology
 
 ```mermaid
 flowchart LR
@@ -541,205 +572,248 @@ flowchart LR
 
 ### Route and API Modules
 
-- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API за съвместимост
-- `src/app/api/v1/providers/[provider]/*`: специални маршрути за всеки доставчик (чат, вграждания, изображения)
-- `src/app/api/providers*`: доставчик CRUD, валидиране, тестване
-- `src/app/api/provider-nodes*`: персонализирано съвместимо управление на възли
-- `src/app/api/provider-models`: персонализирано управление на модела (CRUD)
-- `src/app/api/models/route.ts`: API за каталог на модели (псевдоними + потребителски модели)
-- `src/app/api/oauth/*`: потоци OAuth/код на устройство
-- `src/app/api/keys*`: жизнен цикъл на местен API ключ
-- `src/app/api/models/alias`: управление на псевдоними
-- `src/app/api/combos*`: резервно управление на комбо
-- `src/app/api/pricing`: отменя ценообразуването за изчисляване на разходите
-- `src/app/api/settings/proxy`: конфигурация на прокси (GET/PUT/DELETE)
-- `src/app/api/settings/proxy/test`: тест за свързване на изходящ прокси (POST)
-- `src/app/api/usage/*`: API за използване и регистрационни файлове
-- `src/app/api/sync/*` + `src/app/api/cloud/*`: облачно синхронизиране и помощници в облака
-- `src/app/api/cli-tools/*`: локални CLI конфигурационни писатели/проверки
-- `src/app/api/settings/ip-filter`: списък с разрешени/блокирани IP адреси (GET/PUT)
-- `src/app/api/settings/thinking-budget`: конфигурация на бюджета на мислещия токен (GET/PUT)
-- `src/app/api/settings/system-prompt`: глобална системна подкана (GET/PUT)
-- `src/app/api/sessions`: списък на активни сесии (GET)
-- `src/app/api/rate-limits`: състояние на ограничение на скоростта за всеки акаунт (GET)### Routing and Execution Core
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
+- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
+- `src/app/api/providers*`: provider CRUD, validation, testing
+- `src/app/api/provider-nodes*`: custom compatible node management
+- `src/app/api/provider-models`: custom model management (CRUD)
+- `src/app/api/models/route.ts`: model catalog API (aliases + custom models)
+- `src/app/api/oauth/*`: OAuth/device-code flows
+- `src/app/api/keys*`: local API key lifecycle
+- `src/app/api/models/alias`: alias management
+- `src/app/api/combos*`: fallback combo management
+- `src/app/api/pricing`: pricing overrides for cost calculation
+- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
+- `src/app/api/usage/*`: usage and logs APIs
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
+- `src/app/api/cli-tools/*`: local CLI config writers/checkers
+- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
+- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
+- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
+- `src/app/api/sessions`: active session listing (GET)
+- `src/app/api/rate-limits`: per-account rate limit status (GET)
 
-- `src/sse/handlers/chat.ts`: анализ на заявка, комбо обработка, цикъл за избор на акаунт
-- `open-sse/handlers/chatCore.ts`: превод, изпращане на изпълнителя, повторен опит/опресняване, настройка на потока
-- `open-sse/executors/*`: специфично за доставчика поведение на мрежа и формат### Translation Registry and Format Converters
+### Routing and Execution Core
 
-- `open-sse/translator/index.ts`: регистър на преводачите и оркестрация
-- Заявка за преводачи: `open-sse/translator/request/*`
-- Преводачи на отговор: `open-sse/translator/response/*`
-- Форматни константи: `open-sse/translator/formats.ts`### Persistence
+- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
+- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
+- `open-sse/executors/*`: provider-specific network and format behavior
 
-- `src/lib/db/*`: постоянна конфигурация/състояние и устойчивост на домейн на SQLite
-- `src/lib/localDb.ts`: повторно експортиране на съвместимост за DB модули
-- `src/lib/usageDb.ts`: хронология на използването/фасада на регистрационните файлове на повикванията върху SQLite таблици## Provider Executor Coverage (Strategy Pattern)
+### Translation Registry and Format Converters
 
-Всеки доставчик има специализиран изпълнител, разширяващ `BaseExecutor` (в `open-sse/executors/base.ts`), който осигурява изграждане на URL адрес, изграждане на заглавка, повторен опит с експоненциално забавяне, кукички за опресняване на идентификационни данни и метода за оркестрация `execute()`.
+- `open-sse/translator/index.ts`: translator registry and orchestration
+- Request translators: `open-sse/translator/request/*`
+- Response translators: `open-sse/translator/response/*`
+- Format constants: `open-sse/translator/formats.ts`
 
-| Изпълнител                   | Доставчик(и)                                                                                                                                                 | Специална обработка                                                                 |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
-| `Изпълнител по подразбиране` | OpenAI, Claude, Gemini, Qwen, Qoder, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Конфигурация на динамичен URL/заглавие за доставчик                                 |
-| `AntigravityExecutor`        | Google Антигравитация                                                                                                                                        | Идентификационни номера на персонализирани проекти/сесии, повторен опит след анализ |
-| `CodexExecutor`              | OpenAI Codex                                                                                                                                                 | Вкарва системни инструкции, принуждава усилие за разсъждение                        |
-| `CursorExecutor`             | Курсор IDE                                                                                                                                                   | ConnectRPC протокол, Protobuf кодиране, подписване на заявка чрез контролна сума    |
-| `GithubExecutor`             | Копилот на GitHub                                                                                                                                            | Опресняване на Copilot token, заглавки, имитиращи VSCode                            |
-| `KiroExecutor`               | AWS CodeWhisperer/Киро                                                                                                                                       | AWS EventStream двоичен формат → SSE конвертиране                                   |
-| `GeminiCLIExecutor`          | Gemini CLI                                                                                                                                                   | Цикъл на опресняване на Google OAuth токен                                          |
+### Persistence
 
-Всички други доставчици (включително персонализирани съвместими възли) използват `DefaultExecutor`.## Provider Compatibility Matrix
+- `src/lib/db/*`: persistent config/state and domain persistence on SQLite
+- `src/lib/localDb.ts`: compatibility re-export for DB modules
+- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables
 
-| Доставчик         | Формат          | Удостоверяване                 | Поток            | Непоточно | Опресняване на токена | API за използване            |
-| ----------------- | --------------- | ------------------------------ | ---------------- | --------- | --------------------- | ---------------------------- | ------------------------------ |
-| Клод              | Клод            | API ключ / OAuth               | ✅               | ✅        | ✅                    | ⚠️ Само администратор        |
-| Близнаци          | близнаци        | API ключ / OAuth               | ✅               | ✅        | ✅                    | ⚠️ Облачна конзола           |
-| Gemini CLI        | gemini-cli      | OAuth                          | ✅               | ✅        | ✅                    | ⚠️ Облачна конзола           |
-| Антигравитация    | антигравитация  | OAuth                          | ✅               | ✅        | ✅                    | ✅ API с пълна квота         |
-| OpenAI            | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Кодекс            | openai-отговори | OAuth                          | ✅ принуден      | ❌        | ✅                    | ✅ Ограничения на скоростта  |
-| Копилот на GitHub | openai          | OAuth + Copilot Token          | ✅               | ✅        | ✅                    | ✅ Моментни снимки на квоти  |
-| Курсор            | курсор          | Персонализирана контролна сума | ✅               | ✅        | ❌                    | ❌                           |
-| Киро              | киро            | AWS SSO OIDC                   | ✅ (EventStream) | ❌        | ✅                    | ✅ Ограничения за използване |
-| Куен              | openai          | OAuth                          | ✅               | ✅        | ✅                    | ⚠️ По заявка                 |
-| Qoder             | openai          | OAuth (основен)                | ✅               | ✅        | ✅                    | ⚠️ По заявка                 |
-| OpenRouter        | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| GLM/Кими/МиниМакс | Клод            | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| DeepSeek          | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Groq              | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| xAI (Grok)        | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Мистрал           | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Недоумение        | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Заедно AI         | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Фойерверки AI     | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Мозъци            | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| Cohere            | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           |
-| NVIDIA NIM        | openai          | API ключ                       | ✅               | ✅        | ❌                    | ❌                           | ## Format Translation Coverage |
+## Provider Executor Coverage (Strategy Pattern)
 
-Откритите изходни формати включват:
+Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method.
 
-- `опенай`
-- `openaj-отговори`
-- „Клод“.
-- "близнаци".
+| 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                                     |
 
-Целевите формати включват:
+All other providers (including custom compatible nodes) use the `DefaultExecutor`.
 
-- OpenAI чат/Отговори
-- Клод
-- Gemini/Gemini-CLI/Антигравитационен плик
-- Киро
-- Курсор
+## Provider Compatibility Matrix
 
-Преводите използват**OpenAI като хъб формат**— всички реализации преминават през OpenAI като междинен:```
+| Provider         | Format           | Auth                  | Stream           | Non-Stream | Token Refresh | Usage API          |
+| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
+| Claude           | claude           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Admin only      |
+| Gemini           | gemini           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Gemini CLI       | gemini-cli       | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Antigravity      | antigravity      | OAuth                 | ✅               | ✅         | ✅            | ✅ Full quota API  |
+| OpenAI           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Codex            | openai-responses | OAuth                 | ✅ forced        | ❌         | ✅            | ✅ Rate limits     |
+| GitHub Copilot   | openai           | OAuth + Copilot Token | ✅               | ✅         | ✅            | ✅ Quota snapshots |
+| Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
+| Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
+| Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Qoder            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Groq             | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| xAI (Grok)       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Mistral          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Perplexity       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Together AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Fireworks AI     | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+
+## Format Translation Coverage
+
+Detected source formats include:
+
+- `openai`
+- `openai-responses`
+- `claude`
+- `gemini`
+
+Target formats include:
+
+- OpenAI chat/Responses
+- Claude
+- Gemini/Gemini-CLI/Antigravity envelope
+- Kiro
+- Cursor
+
+Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
+
+```
 Source Format → OpenAI (hub) → Target Format
+```
 
-````
+Translations are selected dynamically based on source payload shape and provider target format.
 
-Преводите се избират динамично въз основа на формата на изходния полезен товар и целевия формат на доставчика.
+Additional processing layers in the translation pipeline:
 
-Допълнителни слоеве за обработка в тръбопровода за превод:
+- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance
+- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)
+- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field
+- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`
 
--**Дефектиране на отговора**— Премахва нестандартните полета от отговорите във формат OpenAI (както стрийминг, така и без стрийминг), за да се гарантира стриктно съответствие с SDK
--**Нормализиране на ролята**— Преобразува `developer` → `system` за цели, които не са OpenAI; обединява `system` → `user` за модели, които отхвърлят системната роля (GLM, ERNIE)
--**Извличане на мислен етикет**— Анализира `<think>...</think>` блокове от съдържание в полето `reasoning_content`
--**Структуриран изход**— Преобразува OpenAI `response_format.json_schema` в `responseMimeType` + `responseSchema` на Gemini## Supported API Endpoints
+## Supported API Endpoints
 
-| Крайна точка | Формат | Манипулатор |
-| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------ |
-| `POST /v1/chat/completions` | OpenAI чат | `src/sse/handlers/chat.ts` |
-| `POST /v1/messages` | Съобщения на Клод | Същият манипулатор (автоматично разпознат) |
-| `POST /v1/responses` | OpenAI отговори | `open-sse/handlers/responsesHandler.ts` |
-| `POST /v1/вграждания` | OpenAI вграждания | `open-sse/handlers/embeddings.ts` |
-| `GET /v1/вграждания` | Списък на модели | API маршрут |
-| `POST /v1/images/generations` | OpenAI изображения | `open-sse/handlers/imageGeneration.ts` |
-| `GET /v1/images/generations` | Списък на модели | API маршрут |
-| `POST /v1/providers/{provider}/chat/completions` | OpenAI чат | Специализиран за всеки доставчик с валидиране на модел |
-| `POST /v1/providers/{provider}/embeddings` | OpenAI вграждания | Специализиран за всеки доставчик с валидиране на модел |
-| `POST /v1/providers/{provider}/images/generations` | OpenAI изображения | Специализиран за всеки доставчик с валидиране на модел |
-| `POST /v1/messages/count_tokens` | Клод Токен Брой | API маршрут |
-| `GET /v1/models` | Списък с модели на OpenAI | API маршрут (чат + вграждане + изображение + потребителски модели) |
-| `GET /api/models/catalog` | Каталог | Всички модели, групирани по доставчик + тип |
-| `POST /v1beta/models/*:streamGenerateContent` | Роден Близнаци | API маршрут |
-| `GET/PUT/DELETE /api/settings/proxy` | Прокси конфигурация | Конфигурация на мрежов прокси |
-| `POST /api/settings/proxy/test` | Прокси свързаност | Крайна точка на теста за изправност/свързване на прокси |
-| `GET/POST/DELETE /api/provider-models` | Модели на доставчици | Метаданни за модела на доставчика, поддържащи персонализирани и управлявани налични модели |## Bypass Handler
+| Endpoint                                           | Format             | Handler                                                             |
+| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------- |
+| `POST /v1/chat/completions`                        | OpenAI Chat        | `src/sse/handlers/chat.ts`                                          |
+| `POST /v1/messages`                                | Claude Messages    | Same handler (auto-detected)                                        |
+| `POST /v1/responses`                               | OpenAI Responses   | `open-sse/handlers/responsesHandler.ts`                             |
+| `POST /v1/embeddings`                              | OpenAI Embeddings  | `open-sse/handlers/embeddings.ts`                                   |
+| `GET /v1/embeddings`                               | Model listing      | API route                                                           |
+| `POST /v1/images/generations`                      | OpenAI Images      | `open-sse/handlers/imageGeneration.ts`                              |
+| `GET /v1/images/generations`                       | Model listing      | API route                                                           |
+| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat        | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings  | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/images/generations` | OpenAI Images      | Dedicated per-provider with model validation                        |
+| `POST /v1/messages/count_tokens`                   | Claude Token Count | API route                                                           |
+| `GET /v1/models`                                   | OpenAI Models list | API route (chat + embedding + image + custom models)                |
+| `GET /api/models/catalog`                          | Catalog            | All models grouped by provider + type                               |
+| `POST /v1beta/models/*:streamGenerateContent`      | Gemini native      | API route                                                           |
+| `GET/PUT/DELETE /api/settings/proxy`               | Proxy Config       | Network proxy configuration                                         |
+| `POST /api/settings/proxy/test`                    | Proxy Connectivity | Proxy health/connectivity test endpoint                             |
+| `GET/POST/DELETE /api/provider-models`             | Provider Models    | Provider model metadata backing custom and managed available models |
 
-Обходният манипулатор (`open-sse/utils/bypassHandler.ts`) прихваща известни заявки за "изхвърляне" от Claude CLI - пингове за загряване, извличане на заглавия и броене на токени - и връща**фалшив отговор**, без да консумира токени на доставчика нагоре по веригата. Това се задейства само когато `User-Agent` съдържа `claude-cli`.## Request Logger Pipeline
+## Bypass Handler
 
-Регистраторът на заявки (`open-sse/utils/requestLogger.ts`) осигурява 7-етапен тръбопровод за регистриране на грешки, деактивиран по подразбиране, активиран чрез `ENABLE_REQUEST_LOGS=true`:```
-1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json
-→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt
-````
+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`.
 
-Файловете се записват в `<repo>/logs/<session>/` за всяка сесия на заявка.## Failure Modes and Resilience
+## Request Logging and Artifacts
+
+The older file-based request logger (`open-sse/utils/requestLogger.ts`) is retained only for
+legacy compatibility. The current runtime contract uses:
+
+- `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
 
-- изчакване на акаунта на доставчика при преходни/скоростни/удостоверителни грешки
-- резервен акаунт преди неуспешна заявка
-- резервен комбиниран модел, когато пътят на текущия модел/доставчик е изчерпан## 2) Token Expiry
+- provider account cooldown on transient/rate/auth errors
+- account fallback before failing request
+- combo model fallback when current model/provider path is exhausted
 
-- предварителна проверка и опресняване с повторен опит за опресняващи доставчици
-- 401/403 повторен опит след опит за опресняване в основния път## 3) Stream Safety
+## 2) Token Expiry
 
-- контролер на потоци с прекъсване на връзката
-- поток за превод с промиване в края на потока и обработка на `[DONE]`
-- резервна оценка на използването, когато липсват метаданни за използване на доставчика## 4) Cloud Sync Degradation
+- pre-check and refresh with retry for refreshable providers
+- 401/403 retry after refresh attempt in core path
 
-- появяват се грешки при синхронизиране, но локалното изпълнение продължава
-- планировчикът има логика с възможност за повторен опит, но периодичното изпълнение в момента извиква синхронизиране с един опит по подразбиране## 5) Data Integrity
+## 3) Stream Safety
 
-- Миграции на SQLite схема и кукички за автоматично надграждане при стартиране
-- наследен JSON → път за съвместимост на миграцията на SQLite## Observability and Operational Signals
+- disconnect-aware stream controller
+- translation stream with end-of-stream flush and `[DONE]` handling
+- usage estimation fallback when provider usage metadata is missing
 
-Източници на видимост по време на изпълнение:
+## 4) Cloud Sync Degradation
 
-- регистрационни файлове на конзолата от `src/sse/utils/logger.ts`
-- агрегати за използване на заявка в SQLite (`usage_history`, `call_logs`, `proxy_logs`)
-- четиристепенно улавяне на подробен полезен товар в SQLite (`request_detail_logs`), когато `settings.detailed_logs_enabled=true`
-- текстов регистър на състоянието на заявката в `log.txt` (по избор/compat)
-- незадължителни дълбоки регистрационни файлове за заявка/превод под `logs/`, когато `ENABLE_REQUEST_LOGS=true`
-- крайни точки за използване на таблото за управление (`/api/usage/*`) за използване на UI
+- sync errors are surfaced but local runtime continues
+- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
 
-Подробно улавяне на полезен товар на заявка съхранява до четири етапа на полезен товар в JSON на маршрутизирано повикване:
+## 5) Data Integrity
 
-- необработена заявка, получена от клиента
-- преведена заявка, действително изпратена нагоре
-- отговор на доставчика, реконструиран като JSON; поточно предаваните отговори се уплътняват до крайното резюме плюс метаданни на потока
-- окончателен клиентски отговор, върнат от OmniRoute; поточно предаваните отговори се съхраняват в същата компактна обобщена форма## Security-Sensitive Boundaries
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
-- JWT тайна (`JWT_SECRET`) защитава проверката/подписването на бисквитките на сесията на таблото за управление
-- Първоначалната парола за зареждане (`INITIAL_PASSWORD`) трябва да бъде изрично конфигурирана за осигуряване при първо стартиране
-- API ключ HMAC тайна (`API_KEY_SECRET`) защитава генерирания локален формат на API ключ
-- Тайните на доставчика (API ключове/токени) се съхраняват в локалната база данни и трябва да бъдат защитени на ниво файлова система
-- Крайните точки за синхронизиране в облак разчитат на удостоверяване на API ключ + семантика на идентификатор на машина## Environment and Runtime Matrix
+## Observability and Operational Signals
 
-Променливите на средата, използвани активно от кода:
+Runtime visibility sources:
 
-- Приложение/удостоверяване: `JWT_SECRET`, `INITIAL_PASSWORD`
-- Съхранение: `DATA_DIR`
-- Съвместимо поведение на възел: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
-- Допълнителна отмяна на базата за съхранение (Linux/macOS, когато `DATA_DIR` не е зададено): `XDG_CONFIG_HOME`
-- Хеширане на сигурността: `API_KEY_SECRET`, `MACHINE_ID_SALT`
-- Регистриране: `ENABLE_REQUEST_LOGS`
-- Синхронизиране/облачно URL адресиране: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
-- Изходящ прокси: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` и варианти с малки букви
-- Флагове на функцията SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
-- Помощници за платформа/време на изпълнение (не специфична за приложението конфигурация): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`## Known Architectural Notes
+- console logs from `src/sse/utils/logger.ts`
+- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true`
+- textual request status log in `log.txt` (optional/compat)
+- optional 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
 
-1. `usageDb` и `localDb` споделят една и съща основна политика за директория (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) с мигриране на наследени файлове.
-2. `/api/v1/route.ts` делегира на същия унифициран конструктор на каталог, използван от `/api/v1/models` (`src/app/api/v1/models/catalog.ts`), за да се избегне семантично отклонение.
-3. Request logger записва пълни заглавки/тяло, когато е разрешено; третира регистрационната директория като чувствителна.
-4. Поведението в облака зависи от правилния `NEXT_PUBLIC_BASE_URL` и достъпността на крайната точка на облака.
-5. Директорията `open-sse/` се публикува като `@omniroute/open-sse`**npm workspace package**. Изходният код го импортира чрез `@omniroute/open-sse/...` (разрешено от Next.js `transpilePackages`). Пътищата на файловете в този документ все още използват името на директорията `open-sse/` за последователност.
-6. Диаграмите в таблото за управление използват**Recharts**(базирани на SVG) за достъпни, интерактивни аналитични визуализации (стълбовидни диаграми на използването на модела, таблици с разбивка на доставчиците с проценти на успех).
-7. E2E тестовете използват**Playwright**(`tests/e2e/`), изпълняват се чрез `npm run test:e2e`. Единичните тестове използват**Node.js test runner**(`tests/unit/`), изпълняват се чрез `npm run test:unit`. Изходният код под `src/` е**TypeScript**(`.ts`/`.tsx`); работното пространство `open-sse/` остава JavaScript (`.js`).
-8. Страницата с настройки е организирана в 5 раздела: Сигурност, Маршрутизация (6 глобални стратегии: първо запълване, кръгова система, p2c, произволна, най-малко използвана, оптимизирана по отношение на разходите), Устойчивост (ограничения на скоростта за редактиране, прекъсвач, политики), AI (мислещ бюджет, системна подкана, кеш за подкана), Разширени (прокси).## Operational Verification Checklist
+Detailed request payload capture stores up to four JSON payload stages per routed call:
 
-- Изграждане от източник: `npm run build`
-- Изграждане на Docker изображение: `docker build -t omniroute .`
-- Стартирайте услугата и проверете:
+- raw request received from the client
+- translated request actually sent upstream
+- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata
+- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form
+
+## Security-Sensitive Boundaries
+
+- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
+- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning
+- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format
+- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level
+- Cloud sync endpoints rely on API key auth + machine id semantics
+
+## Environment and Runtime Matrix
+
+Environment variables actively used by code:
+
+- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Storage: `DATA_DIR`
+- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
+- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME`
+- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
+- Logging: `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`
+- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+
+## Known Architectural Notes
+
+1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.
+2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift.
+3. Request logger writes full headers/body when enabled; treat log directory as sensitive.
+4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability.
+5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency.
+6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates).
+7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`).
+8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies, **Context Relay** handoff config), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
+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 24+ detection**: `/api/settings/require-login` returns `nodeVersion` and `nodeCompatible` fields. The login page renders a warning banner when the runtime is incompatible.
+
+## Operational Verification Checklist
+
+- Build from source: `npm run build`
+- Build Docker image: `docker build -t omniroute .`
+- Start service and verify:
 - `GET /api/settings`
 - `GET /api/v1/models`
-- CLI целевият базов URL трябва да бъде `http://<host>:20128/v1`, когато `PORT=20128`
+- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`

docs/i18n/bg/docs/CODEBASE_DOCUMENTATION.md

@@ -387,7 +387,7 @@ import "./request/claude-to-openai.js"; // ← self-registers
 | `stream.ts`        | **SSE Transform Stream**— основният тръбопровод за стрийминг. Два режима: `TRANSLATE` (превод в пълен формат) и `PASSTHROUGH` (нормализиране + извличане на използването). Управлява буфериране на парчета, оценка на използването, проследяване на дължината на съдържанието. Екземплярите на енкодер/декодер на поток избягват споделено състояние. |
 | `streamHelpers.ts` | Помощни програми за SSE на ниско ниво: `parseSSELine` (толерантно към бели интервали), `hasValuableContent` (филтрира празни парчета за OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (съобразено с формат SSE сериализиране с почистване на `perf_metrics`).                                                                                    |
 | `usageTracking.ts` | Извличане на използване на токени от всеки формат (Claude/OpenAI/Gemini/Responses), оценка с отделни съотношения на инструмент/съобщение char-per-token, добавяне на буфер (марж за безопасност от 2000 токена), филтриране на специфично за формат поле, конзолно регистриране с ANSI цветове.                                                       |
-| `requestLogger.ts` | Регистриране на заявки, базирани на файлове (включване чрез `ENABLE_REQUEST_LOGS=true`). Създава сесийни папки с номерирани файлове: `1_req_client.json` → `7_res_client.txt`. Всички I/O са асинхронни (задействай и забрави). Маскира чувствителните заглавки.                                                                                      |
+| `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` | Прихваща специфични модели от Claude CLI (извличане на заглавие, загряване, броене) и връща фалшиви отговори, без да се обажда на доставчик. Поддържа както стрийминг, така и не стрийминг. Умишлено ограничен до Claude CLI обхват.                                                                                                                  |
 | `networkProxy.ts`  | Разрешава изходящ URL адрес на прокси за даден доставчик с предимство: специфична за доставчика конфигурация → глобална конфигурация → променливи на средата (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Поддържа изключения `NO_PROXY`. Кешира конфигурацията за 30s.                                                                                  | #### SSE Streaming Pipeline |
 

docs/i18n/bg/docs/FEATURES.md

@@ -4,102 +4,168 @@
 
 ---
 
-Визуално ръководство за всеки раздел на таблото за управление OmniRoute.---
+
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
 
 ## 🔌 Providers
 
-Управлявайте връзките на доставчици на AI: OAuth доставчици (Claude Code, Codex, Gemini CLI), доставчици на API ключове (Groq, DeepSeek, OpenRouter) и безплатни доставчици (Qoder, Qwen, Kiro). Сметките в Kiro включват проследяване на кредитния баланс — оставащи кредити, обща надбавка и дата на подновяване, видими в Табло за управление → Използване.![Providers Dashboard](screenshots/01-providers.png)
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+![Providers Dashboard](screenshots/01-providers.png)
 
 ---
 
 ## 🎨 Combos
 
-Създавайте комбинации за маршрутизиране на модели с 6 стратегии: приоритетни, претеглени, кръгови, произволни, най-малко използвани и оптимизирани по отношение на разходите. Всяка комбинация свързва няколко модела с автоматичен резервен вариант и включва бързи шаблони и проверки за готовност.![Combos Dashboard](screenshots/02-combos.png)
+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.
+
+![Combos Dashboard](screenshots/02-combos.png)
 
 ---
 
 ## 📊 Analytics
 
-Изчерпателни анализи на използването с потребление на токени, оценки на разходите, топлинни карти на активността, седмични диаграми на разпределение и разбивки по доставчик.![Analytics Dashboard](screenshots/03-analytics.png)
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
 
 ---
 
 ## 🏥 System Health
 
-Мониторинг в реално време: време на работа, памет, версия, процентили на латентност (p50/p95/p99), статистика на кеша и състояния на прекъсвача на доставчика.![Health Dashboard](screenshots/04-health.png)
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+![Health Dashboard](screenshots/04-health.png)
 
 ---
 
 ## 🔧 Translator Playground
 
-Четири режима за отстраняване на грешки в API преводи:**Playground**(конвертор на формати),**Chat Tester**(заявки на живо),**Test Bench**(пакетни тестове) и**Live Monitor**(поток в реално време).![Translator Playground](screenshots/05-translator.png)
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+![Translator Playground](screenshots/05-translator.png)
 
 ---
 
 ## 🎮 Model Playground _(v2.0.9+)_
 
-Тествайте всеки модел директно от таблото. Изберете доставчик, модел и крайна точка, пишете подкани с Monaco Editor, предавайте отговори в реално време, прекъсвайте по средата на потока и преглеждайте показатели за времето.---
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
 
 ## 🎨 Themes _(v2.0.5+)_
 
-Цветови теми с възможност за персонализиране за цялото табло. Изберете от 7 предварително зададени цвята (корал, син, червен, зелен, виолетов, оранжев, циан) или създайте персонализирана тема, като изберете всеки шестнадесетичен цвят. Поддържа светъл, тъмен и системен режим.---
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
 
 ## ⚙️ Settings
 
-Изчерпателен панел с настройки с раздели:
+Comprehensive settings panel with tabs:
 
--**Общи**— Системно съхранение, управление на архивиране (база данни за експорт/импорт) -**Външен вид**— Селектор на тема (тъмно/светло/система), предварително зададени цветови теми и персонализирани цветове, видимост на журнала за здраве, контроли за видимост на елементи от страничната лента -**Сигурност**— API защита на крайната точка, персонализирано блокиране на доставчика, IP филтриране, информация за сесията -**Маршрутизиране**— Псевдоними на модела, влошаване на фоновата задача -**Устойчивост**— Устойчивост на лимита на скоростта, настройка на прекъсвача, автоматично деактивиране на забранени акаунти, наблюдение на изтичане на доставчика -**Разширени**— Замени на конфигурацията, одитна пътека на конфигурацията, резервен режим на влошаване![Settings Dashboard](screenshots/06-settings.png)
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring, **Context Relay** handoff threshold and summary model configuration
+- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
+
+![Settings Dashboard](screenshots/06-settings.png)
 
 ---
 
 ## 🔧 CLI Tools
 
-Конфигурация с едно кликване за инструменти за кодиране на AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor и Factory Droid. Включва автоматизирано прилагане/нулиране на конфигурация, профили на свързване и картографиране на модела.![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
 
 ---
 
 ## 🤖 CLI Agents _(v2.0.11+)_
 
-Табло за откриване и управление на CLI агенти. Показва мрежа от 14 вградени агента (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) с:
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
 
--**Състояние на инсталацията**— Инсталирано / Не е намерено с откриване на версия -**Протоколни значки**— stdio, HTTP и др. -**Персонализирани агенти**— Регистрирайте всеки CLI инструмент чрез формуляр (име, двоичен файл, команда за версия, аргументи за генериране) -**CLI съпоставяне на пръстови отпечатъци**— Превключване за всеки доставчик, за да съответства на собствените подписи на CLI заявка, намалявайки риска от забрана, като същевременно запазва прокси IP---
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🔗 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
+
+---
 
 ## 🖼️ Media _(v2.0.3+)_
 
-Генерирайте изображения, видеоклипове и музика от таблото за управление. Поддържа OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open и MusicGen.---
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
 
 ## 📝 Request Logs
 
-Регистриране на заявки в реално време с филтриране по доставчик, модел, акаунт и API ключ. Показва кодове за състояние, използване на токени, латентност и подробности за отговора.![Usage Logs](screenshots/08-usage.png)
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+![Usage Logs](screenshots/08-usage.png)
 
 ---
 
 ## 🌐 API Endpoint
 
-Вашата унифицирана крайна точка на API с разбивка на възможностите: завършвания на чатове, API за отговори, вграждания, генериране на изображения, прекласиране, аудио транскрипция, текст към говор, модериране и регистрирани ключове за API. Интегриране на Cloudflare Quick Tunnel и поддръжка на облачен прокси за отдалечен достъп.![Endpoint Dashboard](screenshots/09-endpoint.png)
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)
 
 ---
 
 ## 🔑 API Key Management
 
-Създаване, обхват и отмяна на API ключове. Всеки ключ може да бъде ограничен до конкретни модели/доставчици с пълен достъп или разрешения само за четене. Визуално управление на ключове с проследяване на използването.---
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
 
 ## 📋 Audit Log
 
-Проследяване на административни действия с филтриране по тип действие, актьор, цел, IP адрес и клеймо за време. Пълна история на събитията за сигурност.---
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
 
 ## 🖥️ Desktop Application
 
-Настолно приложение Native Electron за Windows, macOS и Linux. Стартирайте OmniRoute като самостоятелно приложение с интеграция в системната област, офлайн поддръжка, автоматично актуализиране и инсталиране с едно щракване.
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
 
-Ключови характеристики:
+Key features:
 
-- Проучване на готовността на сървъра (без празен екран при студен старт)
-- Системна област с управление на портове
-- Политика за сигурност на съдържанието
-- Еднократно заключване
-- Автоматична актуализация при рестартиране
-- Платформено условен потребителски интерфейс (светофари на MacOS, заглавна лента по подразбиране на Windows/Linux)
-- Hardened Electron build packaging — символично свързаните `node_modules` в самостоятелния пакет се откриват и отхвърлят преди опаковането, предотвратявайки зависимостта по време на изпълнение от машината за изграждане (v2.5.5+)
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
 
-📖 Вижте [`electron/README.md`](../electron/README.md) за пълна документация.
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/bg/docs/TROUBLESHOOTING.md

@@ -4,65 +4,147 @@
 
 ---
 
-Често срещани проблеми и решения за OmniRoute.---## Quick Fixes
+Common problems and solutions for OmniRoute.
 
-| Проблем                                         | Решение                                                                        |
-| ----------------------------------------------- | ------------------------------------------------------------------------------ | --------------------- |
-| Първото влизане не работи                       | Задайте `INITIAL_PASSWORD` в `.env` (без твърдо кодирано подразбиране)         |
-| Таблото се отваря на грешен порт                | Задайте `PORT=20128` и `NEXT_PUBLIC_BASE_URL=http://localhost:20128`           |
-| Няма регистрирани файлове за заявки под `logs/` | Задайте `ENABLE_REQUEST_LOGS=true`                                             |
-| EACCES: разрешението е показано                 | Задайте `DATA_DIR=/path/to/writable/dir` да замените `~/.omniroute`            |
-| Стратегията за маршрутизиране не се запазва     | Актуализация до v1.4.11+ (корекция на Zod схема за постоянство на настройките) | ---## Provider Issues |
+---
+
+## 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 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      | You may be on Node.js 24+ — see [Node.js Compatibility](#nodejs-compatibility) 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 Node.js 24+. The `better-sqlite3` native binary is not compatible with Node.js 24, which causes a fatal crash when the server tries to initialize the database.
+
+**Symptoms:**
+
+- Login page shows a blank screen or a server error
+- Console shows `Error: Module did not self-register` or similar native binding errors
+- Starting with v3.5.5, the login page shows an **orange warning banner** with your Node version if incompatibility is detected
+
+**Fix:**
+
+1. Install Node.js 22 LTS (recommended):
+   ```bash
+   nvm install 22
+   nvm use 22
+   ```
+2. Verify your version: `node --version` should show `v22.x.x`
+3. Reinstall OmniRoute: `npm install -g omniroute`
+4. Restart: `omniroute`
+
+> **Supported versions:** Node.js 18, 20, or 22 LTS. Node.js 24+ is **not supported**.
+
+---
+
+## 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+.
+
+---
+
+## Provider Issues
 
 ### "Language model did not provide messages"
 
-**Причина:**Квотата на доставчика е изчерпана.
+**Cause:** Provider quota exhausted.
 
-**Коригиране:**
+**Fix:**
 
-1. Проверете инструмента за проследяване на квотите на таблото за управление
-2. Използвайте комбо с резервни нива
-3. Преминете към по-евтино/безплатно ниво### Rate Limiting
+1. Check dashboard quota tracker
+2. Use a combo with fallback tiers
+3. Switch to cheaper/free tier
 
-**Причина:**Абонаментната квота е изчерпана.
+### Rate Limiting
 
-**Коригиране:**
+**Cause:** Subscription quota exhausted.
 
-- Добавете резервен вариант: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-- Използвайте GLM/MiniMax като евтино резервно копие### OAuth Token Expired
+**Fix:**
 
-OmniRoute автоматично опреснява токените. Ако проблемите продължават:
+- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Use GLM/MiniMax as cheap backup
 
-1. Табло → Доставчик → Свързване отново
-2. Изтрийте и добавете отново връзката с доставчика---## Cloud Issues
+### OAuth Token Expired
+
+OmniRoute auto-refreshes tokens. If issues persist:
+
+1. Dashboard → Provider → Reconnect
+2. Delete and re-add the provider connection
+
+---
+
+## Cloud Issues
 
 ### Cloud Sync Errors
 
-1. Проверете дали `BASE_URL` е към вашия работен екземпляр (напр. `http://localhost:20128`)
-2. Проверете дали `CLOUD_URL` е към вашата крайна точка в облака (напр. `https://omniroute.dev`)
-3. Поддържайте стойността `NEXT_PUBLIC_*` в съответствие със стойността от страната на сървъра### Cloud `stream=false` Връща 500
+1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
+2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
+3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
 
-**Симптом:**`Неочакван токен 'd'...` в крайната точка на облака за повикане без точно предаване.
+### Cloud `stream=false` Returns 500
 
-**Причина:**Upstream връща SSE полезен продукт, докато клиентът очаква JSON.
+**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
 
-**Заобиколно решение:**Използвайте `stream=true` за директни повикания в облака. Локалното време за изпълнение включва резервен SSE→JSON.### Cloud Says Connected but "Invalid API key"
+**Cause:** Upstream returns SSE payload while client expects JSON.
 
-1. Създайте нов ключ от локалното табло за управление (`/api/keys`)
-2. Стартирайте облачна синхронизация: Активирайте облака → Синхронизирай сега
-3. Старите/несинхронизираните ключове все още могат да връщат „401“ в облака---## Docker Issues
+**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
+
+### Cloud Says Connected but "Invalid API key"
+
+1. Create a fresh key from local dashboard (`/api/keys`)
+2. Run cloud sync: Enable Cloud → Sync Now
+3. Old/non-synced keys can still return `401` on cloud
+
+---
+
+## Docker Issues
 
 ### CLI Tool Shows Not Installed
 
-1. Проверете полетата за изпълнение: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
-2. За преносим режим: използвайте целево изображение `runner-cli` (пакетни CLI)
-3. За режим на монтиране на хост: задайте `CLI_EXTRA_PATHS` и монтирайте директорията bin на хоста като само за четене
-4. Ако `installed=true` и `runnable=false`: двоичният файл е намерен, но проверката на състоянието е неуспешна### Quick Runtime Validation```bash
-   curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
-   curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
-   curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. For portable mode: use image target `runner-cli` (bundled CLIs)
+3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
+4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
 
-````
+### Quick Runtime Validation
+
+```bash
+curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
+```
 
 ---
 
@@ -70,108 +152,163 @@ OmniRoute автоматично опреснява токените. Ако п
 
 ### High Costs
 
-1. Проверете статистическите данни за употреба в Табло → Използване
-2. Превключете основния модел на GLM/MiniMax
-3. Използвайте безплатно ниво (Gemini CLI, Qoder) за некритични задачи
-4. Задайте бюджети за разходи за API ключ: Табло за управление → API ключове → Бюджет---## Debugging
+1. Check usage stats in Dashboard → Usage
+2. Switch primary model to GLM/MiniMax
+3. Use free tier (Gemini CLI, Qoder) for non-critical tasks
+4. Set cost budgets per API key: Dashboard → API Keys → Budget
 
-### Enable Request Logs
+---
 
-Задайте `ENABLE_REQUEST_LOGS=true` във вашия `.env` файл. Дневниците се появяват в директорията `logs/`.### Проверете здравето на доставчика```bash
+## Debugging
+
+### Enable Log Files
+
+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
+
+```bash
 # Health dashboard
 http://localhost:20128/dashboard/health
 
 # API health check
 curl http://localhost:20128/api/monitoring/health
-````
+```
 
 ### Runtime Storage
 
-- Основно състояние: `${DATA_DIR}/storage.sqlite` (доставчици, комбинации, псевдоними, ключове, настройки)
-- Използване: SQLite таблици в `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + незадължително `${DATA_DIR}/log.txt` и `${DATA_DIR}/call_logs/`
-- Заявки за регистрационни файлове: `<repo>/logs/...` (като `ENABLE_REQUEST_LOGS=true`)---## Circuit Breaker Issues
+- 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}/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
+
+---
+
+## Circuit Breaker Issues
 
 ### Provider stuck in OPEN state
 
-При прекъсване на веригата на доставчика е ОТВОРЕЕН, заявките се блокират, докато изтече времето за охлаждане.
+When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
 
-**Коригиране:**
+**Fix:**
 
-1. Отидете на**Табло → Настройки → Устойчивост**
-2. Проверете картата на прекъсвача на сървъра на доставчика
-3. Щракнете върху**Нулиране на всички**, за да изчистите всички прекъсвачи, или изчакайте времето за охлаждане да изтече
-4. Уверете се, че доставчикът действително е наличен, преди да нулира### Доставчикът продължава да изключва прекъсвача
+1. Go to **Dashboard → Settings → Resilience**
+2. Check the circuit breaker card for the affected provider
+3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
+4. Verify the provider is actually available before resetting
 
-Ако доставчикът многократно влезе в ОТВОРЕНО състояние:
+### Provider keeps tripping the circuit breaker
 
-1. Проверете**Таблото → Здраве → Здраве на доставчика**за модел на повреда
-2. Отидете на**Настройки → Устойчивост → Профили на доставчици**и увеличите прага на отказ
-3. Проверете дали доставчикът е променил ограниченията на API или изисква повторно удостоверяване
-4. Прегледайте телеметрията за латентност — високата латентност може да причини грешки, базирани на изчакване---## Audio Transcription Issues
+If a provider repeatedly enters OPEN state:
+
+1. Check **Dashboard → Health → Provider Health** for the failure pattern
+2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
+3. Check if the provider has changed API limits or requires re-authentication
+4. Review latency telemetry — high latency may cause timeout-based failures
+
+---
+
+## Audio Transcription Issues
 
 ### "Unsupported model" error
 
-- Уверете се, че използвате правилния префикс: `deepgram/nova-3` или `assemblyai/best`
-- Проверете дали доставчикът е свързан в**Табло → Доставчици**### Транскрипцията се връща празна или е неуспешна
+- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
+- Verify the provider is connected in **Dashboard → Providers**
 
-- Проверете поддържаните аудио формати: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
-- Уверете се, че размерът на файла е в границите на доставчика (обикновено < 25MB)
-- Проверете валидността на API ключа на доставчика в картата на доставчика---## Translator Debugging
+### Transcription returns empty or fails
 
-Използвайте**Таблица за управление → Преводач**за отстраняване на грешки при проблеми с превод на формат:
+- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Verify file size is within provider limits (typically < 25MB)
+- Check provider API key validity in the provider card
 
-| Режим               | Кога да използвате                                                                                            |
-| ------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| **Детска площадка** | Сравнете входно/изходните формати един до друг — поставете неуспешна заявка, за да видите как се превежда     |
-| **Чат тестер**      | Изпращайте съобщения на живо и проверете допълнителен полезен продукт на заявка/отговор, включително заглавки |
-| **Тестова стенда**  | Изпълнете групови тестове в комбинации от формати, за да откриете кои преводи са нарушени                     |
-| **Монитор на живо** | Гледайте потока на заявките в реално време, за да уловите периодични проблеми с превод                        | ### Common format issues |
+---
 
--**Тагове за мислене не се появяват**— Проверете дали целевият доставчик поддържа мисленето и настройката на бюджета за мислене -**Отпадане на извикванията на инструментите**— Някои преводи на формати могат да премахнат неподдържаните полета; потвърдете в режим Playground -**Липсва системна подкана**— Клод и Джемини обработват системните подкани по различен начин; проверка на резултата за превод -**SDK връща необработен низ вместо валиден обект**— Коригирано във v1.1.0: дезинфектантът за отговор вече премахва нестандартните полета (`x_groq`, `usage_breakdown` и т.н.), които предизвикват неуспешно пускане на OpenAI SDK Pydantic -**GLM/ERNIE отхвърля `системна` роля**— Коригирано във v1.1.0: нормализаторът на ролите автоматично обединява системни съобщения в потребителски съобщения за несъвместими модели
+## Translator Debugging
 
-- Ролята на**`разработчик` не е разпозната**— Коригирано във v1.1.0: автоматично се преобразува в `системата` за доставчици, не е с OpenAI -**`json_schema` не работи с Gemini**— Коригирано във v1.1.0: `response_format` вече се преобразува в `responseMimeType` + `responseSchema` на Gemini---## Resilience Settings
+Use **Dashboard → Translator** to debug format translation issues:
+
+| Mode             | When to Use                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| **Playground**   | Compare input/output formats side by side — paste a failing request to see how it translates |
+| **Chat Tester**  | Send live messages and inspect the full request/response payload including headers           |
+| **Test Bench**   | Run batch tests across format combinations to find which translations are broken             |
+| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues                        |
+
+### Common format issues
+
+- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
+- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
+- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
+- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures
+- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
+- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers
+- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema`
+
+---
+
+## Resilience Settings
 
 ### Auto rate-limit not triggering
 
-- Автоматичното ограничение на скоростта се прилага само за доставчици на API ключове (без OAuth/абонамент)
-- Уверете се, че**Настройки → Устойчивост → Профили на доставчици**има активиран автоматичен лимит на скоростта
-- Проверете дали доставчикът връща кодове за състояние `429` или заглавки `Retry-After`### Tuning exponential backoff
+- Auto rate-limit only applies to API key providers (not OAuth/subscription)
+- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
+- Check if the provider returns `429` status codes or `Retry-After` headers
 
-Профилът на доставчика поддържа тези настройки:
+### Tuning exponential backoff
 
--**Базово плащане**— Първоначално време на изчакване след първото увреждане (по подразбиране: 1s) -**Максимално заплащане**— Максимално ограничение на времето за изчакване (по подразбиране: 30 секунди) -**Множител**— Колко да се увеличи закъснението за последователен отказ (по подразбиране: 2x)### Anti-thundering herd
+Provider profiles support these settings:
 
-Когато много едновременни заявки се появяват на доставчика с ограничена скорост, OmniRoute използва mutex + автоматично регулиране на скоростта, за да сериализира заявките и да предотврати каскадни грешки. Това е автоматично за доставчиците на API ключове.---## Optional RAG / LLM failure taxonomy (16 problems)
+- **Base delay** — Initial wait time after first failure (default: 1s)
+- **Max delay** — Maximum wait time cap (default: 30s)
+- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
 
-Някои потребители на OmniRoute поставят шлюза пред RAG или агент стекове. В тези настройки е обичайно да се вижда отстранен модел: OmniRoute изглежда здрав (доставчиците работят, профилите за маршрутизиране са добри, няма предупреждения за ограничение на скоростта), но крайният отговор е още по-грешен.
+### Anti-thundering herd
 
-На практика тези инциденти идват от тръбопровода RAG надолу по веригата, а не от вашия шлюз.
+When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
 
-Ако търсите отделен речник, който да напише тези повреди, можете да използвате WFGY ProblemMap, външен текстов ресурс за лиценз на MIT, който дефинира шестнадесет повтарящи се модели при отказ на RAG / LLM. На високо ниво: обхваща
+---
 
-- отклонение при извличане и нарушени контекстни граници
-- празни или остарели индекси и векторни хранилища
-- вграждане срещу семантично несъответствие
-- бързо сглобяване и проблеми с контекстния прозорец
-- логически колапс и изключително самоуверени отговори
-- дълга верига и неуспехи в координацията на агента
-- мултиагентна памет и дрейф на ролите
-- проблеми с внедряването и подреждането на избраното зареждане
+## Optional RAG / LLM failure taxonomy (16 problems)
 
-Идеята е проста:
+Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong.
 
-1. Когато проучвате лош отговор, заснемете:
-   - потребителска задача и заявка
-   - комбо маршрут или доставчик в OmniRoute
-   - всеки RAG контекст, използван надолу по веригата (извлечени документи, извиквания на инструменти и т.н.)
-2. Съставете инцидента с едно или две номера на картата на проблемите на WFGY („No.1“ … „No.16“).
-3. Съхранявайте номера във вашето собствено табло, runbook или инструмент за проследяване на инциденти до регистриране на файлове в OmniRoute.
-4. Съществувате WFGY страница, за да решите дали трябва да промените своя RAG стек, ретривър или стратегия за маршрутизиране.
+In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself.
 
-Пълният текст и конкретните рецепти се намират тук (лиценз на MIT, само текстът):
+If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers:
+
+- retrieval drift and broken context boundaries
+- empty or stale indexes and vector stores
+- embedding versus semantic mismatch
+- prompt assembly and context window issues
+- logic collapse and overconfident answers
+- long chain and agent coordination failures
+- multi agent memory and role drift
+- deployment and bootstrap ordering problems
+
+The idea is simple:
+
+1. When you investigate a bad response, capture:
+   - user task and request
+   - route or provider combo in OmniRoute
+   - any RAG context used downstream (retrieved documents, tool calls, etc)
+2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`).
+3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs.
+4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy.
+
+Full text and concrete recipes live here (MIT license, text only):
 
 [WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
 
-Можете да пренебрегнете този раздел, ако не изпълните RAG или конвейери на агенти зад OmniRoute.---## Still Stuck?
+You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute.
 
--**Проблеми с GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -**Архитектура**: Вижте [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) за вътрешни подробности -**API Reference**: Вижте [`docs/API_REFERENCE.md`](API_REFERENCE.md) за всички крайни точки -**Таблица за управление на здравето**: Проверете**Таблица за управление → Здраве**за състоянието на системата в реално време -**Преводач**: Използвайте**Табло за управление → Преводач**за отстраняване на грешки във форматирането
+---
+
+## Still Stuck?
+
+- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
+- **Translator**: Use **Dashboard → Translator** to debug format issues

docs/i18n/bg/docs/VM_DEPLOYMENT_GUIDE.md

@@ -93,7 +93,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/bg/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/cs/docs/ARCHITECTURE.md

@@ -4,80 +4,91 @@
 
 ---
 
-_Poslední aktualizace: 28.03.2026_## Executive Summary
+_Last updated: 2026-03-28_
 
-OmniRoute je místní AI směrovací brána a řídicí panel postavený na Next.js.
-Poskytuje jeden koncový bod kompatibilní s OpenAI (`/v1/*`) a směruje provoz přes několik upstreamových poskytovatelů s překladem, nouzovým obnovením, obnovením tokenu a sledováním využití.
+## Executive Summary
 
-Základní schopnosti:
+OmniRoute is a local AI routing gateway and dashboard built on Next.js.
+It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
 
-- OpenAI kompatibilní povrch API pro CLI/nástroje (28 poskytovatelů)
-- Překlad požadavku/odpovědi mezi formáty poskytovatelů
-- Záložní kombinace modelů (sekvence více modelů)
-  – Záloha na úrovni účtu (více účtů na poskytovatele)
-- Správa připojení poskytovatele OAuth + API klíče
-- Generování vkládání pomocí `/v1/embeddings` (6 poskytovatelů, 9 modelů)
-- Generování obrázků pomocí `/v1/images/generations` (4 poskytovatelé, 9 modelů)
-- Myslete na analýzu značek (`<think>...</think>`) pro modely uvažování
-- Dezinfekce odezvy pro přísnou kompatibilitu OpenAI SDK
-- Normalizace rolí (vývojář→systém, systém→uživatel) pro kompatibilitu mezi poskytovateli
-- Konverze strukturovaného výstupu (json_schema → Gemini responseSchema)
-- Místní perzistence pro poskytovatele, klíče, aliasy, komba, nastavení, ceny
-- Sledování využití/nákladů a protokolování požadavků
-- Volitelná cloudová synchronizace pro synchronizaci mezi více zařízeními/stavy
-- Seznam povolených/blokovaných IP pro řízení přístupu k API
-- Myslet na správu rozpočtu (průchozí/automatické/vlastní/adaptivní)
-- Okamžité vstřikování globálního systému
-- Sledování relací a snímání otisků prstů
-- Rozšířené omezení sazeb na účet pomocí profilů specifických pro poskytovatele
-- Vzor jističe pro odolnost poskytovatele
-- Ochrana stáda proti hromu s mutexovým zamykáním
-- Mezipaměť deduplikace požadavků na základě podpisu
-- Doménová vrstva: dostupnost modelu, nákladová pravidla, záložní politika, politika uzamčení
-- Perzistence stavu domény (mezipaměť pro zápis SQLite pro záložní, rozpočty, uzamčení, jističe)
-- Modul zásad pro centralizované vyhodnocování požadavků (uzamčení → rozpočet → záložní)
-- Vyžádejte si telemetrii s agregací latence p50/p95/p99
-- ID korelace (X-Request-Id) pro end-to-end trasování
-- Protokolování auditu shody s odhlášením podle klíče API
-- Eval rámec pro zajištění kvality LLM
-- Řídicí panel Resilience UI se stavem jističe v reálném čase
-- Modulární poskytovatelé OAuth (12 jednotlivých modulů pod `src/lib/oauth/providers/`)
+Core capabilities:
 
-Primární runtime model:
+- OpenAI-compatible API surface for CLI/tools (28 providers)
+- Request/response translation across provider formats
+- Model combo fallback (multi-model sequence)
+- Account-level fallback (multi-account per provider)
+- OAuth + API-key provider connection management
+- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
+- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Think tag parsing (`<think>...</think>`) for reasoning models
+- Response sanitization for strict OpenAI SDK compatibility
+- Role normalization (developer→system, system→user) for cross-provider compatibility
+- Structured output conversion (json_schema → Gemini responseSchema)
+- Local persistence for providers, keys, aliases, combos, settings, pricing
+- Usage/cost tracking and request logging
+- Optional cloud sync for multi-device/state sync
+- IP allowlist/blocklist for API access control
+- Thinking budget management (passthrough/auto/custom/adaptive)
+- Global system prompt injection
+- Session tracking and fingerprinting
+- Per-account enhanced rate limiting with provider-specific profiles
+- Circuit breaker pattern for provider resilience
+- Anti-thundering herd protection with mutex locking
+- Signature-based request deduplication cache
+- Domain layer: model availability, cost rules, fallback policy, lockout policy
+- 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
+- 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/`)
 
-- Trasy aplikací Next.js pod `src/app/api/*` implementují jak rozhraní API řídicího panelu, tak rozhraní API pro kompatibilitu
-- Sdílené jádro SSE/směrování v `src/sse/*` + `open-sse/*` se stará o provádění poskytovatele, překlad, streamování, zálohování a používání## Scope and Boundaries
+Primary runtime model:
+
+- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
+- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
+
+## Scope and Boundaries
 
 ### In Scope
 
-- Runtime místní brány
-- Rozhraní API pro správu řídicích panelů
-- Ověření poskytovatele a obnovení tokenu
-- Vyžádejte si překlad a streamování SSE
-- Místní stav + perzistence používání
-- Volitelná orchestrace synchronizace s cloudem### Out of Scope
+- Local gateway runtime
+- Dashboard management APIs
+- Provider authentication and token refresh
+- Request translation and SSE streaming
+- Local state + usage persistence
+- Optional cloud sync orchestration
 
-- Implementace cloudové služby za `NEXT_PUBLIC_CLOUD_URL`
-- Poskytovatel SLA/řídící rovina mimo místní proces
-- Samotné externí binární soubory CLI (Claude CLI, Codex CLI atd.)## Dashboard Surface (Current)
+### Out of Scope
 
-Hlavní stránky pod `src/app/(dashboard)/dashboard/`:
+- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
+- Provider SLA/control plane outside local process
+- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
 
-- `/dashboard` — rychlý start + přehled poskytovatele
-- `/dashboard/endpoint` — proxy koncového bodu + MCP + A2A + karty koncového bodu API
-- `/dashboard/providers` — připojení a přihlašovací údaje poskytovatele
-- `/dashboard/combos` — kombo strategie, šablony, pravidla směrování modelů
-- `/dashboard/costs` — agregace nákladů a viditelnost cen
-- `/dashboard/analytics` — analýzy a vyhodnocení využití
-- `/dashboard/limits` — kontroly kvót/sazeb
-- `/dashboard/cli-tools` — CLI onboarding, runtime detekce, generování konfigurace
-- `/dashboard/agents` — detekovaní agenti AKT + vlastní registrace agenta
-- `/dashboard/media` — hřiště pro obrázky/video/hudbu
-- `/dashboard/search-tools` — testování a historie poskytovatelů vyhledávání
-- `/dashboard/health` — doba provozuschopnosti, jističe, limity sazeb
-- `/dashboard/logs` — protokoly požadavku/proxy/audit/konzole
-- `/dashboard/settings` — karty nastavení systému (obecné, směrování, výchozí kombinace atd.)
-- `/dashboard/api-manager` — životní cyklus klíče API a oprávnění k modelu## High-Level System Context
+## Dashboard Surface (Current)
+
+Main pages under `src/app/(dashboard)/dashboard/`:
+
+- `/dashboard` — quick start + provider overview
+- `/dashboard/endpoint` — endpoint proxy + MCP + A2A + API endpoint tabs
+- `/dashboard/providers` — provider connections and credentials
+- `/dashboard/combos` — combo strategies, templates, model routing rules
+- `/dashboard/costs` — cost aggregation and pricing visibility
+- `/dashboard/analytics` — usage analytics and evaluations
+- `/dashboard/limits` — quota/rate controls
+- `/dashboard/cli-tools` — CLI onboarding, runtime detection, config generation
+- `/dashboard/agents` — detected ACP agents + custom agent registration
+- `/dashboard/media` — image/video/music playground
+- `/dashboard/search-tools` — search provider testing and history
+- `/dashboard/health` — uptime, circuit breakers, rate limits
+- `/dashboard/logs` — request/proxy/audit/console logs
+- `/dashboard/settings` — system settings tabs (general, routing, combo defaults, etc.)
+- `/dashboard/api-manager` — API key lifecycle and model permissions
+
+## High-Level System Context
 
 ```mermaid
 flowchart LR
@@ -129,139 +140,151 @@ flowchart LR
 
 ## 1) API and Routing Layer (Next.js App Routes)
 
-Hlavní adresáře:
+Main directories:
 
-- `src/app/api/v1/*` a `src/app/api/v1beta/*` pro rozhraní API pro kompatibilitu
-- `src/app/api/*` pro správu/konfiguraci API
-- Další přepíše mapu `next.config.mjs` `/v1/*` na `/api/v1/*`
+- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
+- `src/app/api/*` for management/configuration APIs
+- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
 
-Důležité cesty kompatibility:
+Important compatibility routes:
 
 - `src/app/api/v1/chat/completions/route.ts`
 - `src/app/api/v1/messages/route.ts`
 - `src/app/api/v1/responses/route.ts`
-- `src/app/api/v1/models/route.ts` — zahrnuje vlastní modely s `custom: true`
-- `src/app/api/v1/embeddings/route.ts` — generování vložení (6 poskytovatelů)
-- `src/app/api/v1/images/generations/route.ts` — generování obrázků (4+ poskytovatelé včetně Antigravity/Nebius)
+- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`
+- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)
+- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)
 - `src/app/api/v1/messages/count_tokens/route.ts`
-  – `src/app/api/v1/providers/[poskytovatel]/chat/completions/route.ts` – vyhrazený chat pro jednotlivé poskytovatele
-  – `src/app/api/v1/providers/[poskytovatel]/embeddings/route.ts` – vyhrazená vložení pro jednotlivé poskytovatele
-- `src/app/api/v1/providers/[poskytovatel]/images/generations/route.ts` – vyhrazené obrázky pro jednotlivé poskytovatele
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images
 - `src/app/api/v1beta/models/route.ts`
-- `src/app/api/v1beta/models/[...cesta]/route.ts`
+- `src/app/api/v1beta/models/[...path]/route.ts`
 
-Domény správy:
+Management domains:
 
 - Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
-- Poskytovatelé/připojení: `src/app/api/providers*`
-- Uzly poskytovatele: `src/app/api/provider-nodes*`
-- Vlastní modely: `src/app/api/provider-models` (GET/POST/DELETE)
-- Katalog modelů: `src/app/api/models/route.ts` (GET)
-- Konfigurace proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
+- Providers/connections: `src/app/api/providers*`
+- Provider nodes: `src/app/api/provider-nodes*`
+- Custom models: `src/app/api/provider-models` (GET/POST/DELETE)
+- Model catalog: `src/app/api/models/route.ts` (GET)
+- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
 - OAuth: `src/app/api/oauth/*`
-- Klíče/aliasy/komba/cena: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
-- Použití: `src/app/api/usage/*`
+- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
+- Usage: `src/app/api/usage/*`
 - Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
-- Pomocníci nástrojů CLI: `src/app/api/cli-tools/*`
-- IP filtr: `src/app/api/settings/ip-filter` (GET/PUT)
+- CLI tooling helpers: `src/app/api/cli-tools/*`
+- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)
 - Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)
-- Systémová výzva: `src/app/api/settings/system-prompt` (GET/PUT)
-- Relace: `src/app/api/sessions` (GET)
-- Sazbové limity: `src/app/api/rate-limits` (GET)
-- Odolnost: `src/app/api/resilience` (GET/PATCH) — profily poskytovatelů, jistič, stav omezení rychlosti
-- Resetování odolnosti: `src/app/api/resilience/reset` (POST) — resetujte jističe + cooldowny
-- Statistiky mezipaměti: `src/app/api/cache/stats` (GET/DELETE)
-- Dostupnost modelu: `src/app/api/models/availability` (GET/POST)
-- Telemetrie: `src/app/api/telemetry/summary` (GET)
-  – Rozpočet: `src/app/api/usage/budget` (GET/POST)
-- Záložní řetězce: `src/app/api/fallback/chains` (GET/POST/DELETE)
-- Audit souladu: `src/app/api/compliance/audit-log` (GET)
-- Hodnoty: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
-- Zásady: `src/app/api/policies` (GET/POST)## 2) SSE + Translation Core
+- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)
+- Sessions: `src/app/api/sessions` (GET)
+- Rate limits: `src/app/api/rate-limits` (GET)
+- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns
+- Cache stats: `src/app/api/cache/stats` (GET/DELETE)
+- Model availability: `src/app/api/models/availability` (GET/POST)
+- Telemetry: `src/app/api/telemetry/summary` (GET)
+- Budget: `src/app/api/usage/budget` (GET/POST)
+- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET)
+- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
+- Policies: `src/app/api/policies` (GET/POST)
 
-Hlavní průtokové moduly:
+## 2) SSE + Translation Core
 
-- Záznam: `src/sse/handlers/chat.ts`
-- Základní orchestrace: `open-sse/handlers/chatCore.ts`
-- Spouštěcí adaptéry poskytovatele: `open-sse/executors/*`
-- Detekce formátu/konfigurace poskytovatele: `open-sse/services/provider.ts`
-- Parse/resolve modelu: `src/sse/services/model.ts`, `open-sse/services/model.ts`
-- Logika záložního účtu: `open-sse/services/accountFallback.ts`
-- Registr překladů: `open-sse/translator/index.ts`
-- Transformace streamu: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
-- Extrakce/normalizace použití: `open-sse/utils/usageTracking.ts`
-- Analyzátor značek Think: `open-sse/utils/thinkTagParser.ts`
-- Obsluha vkládání: `open-sse/handlers/embeddings.ts`
-- Registr poskytovatele vkládání: `open-sse/config/embeddingRegistry.ts`
-- Ovladač generování obrázků: `open-sse/handlers/imageGeneration.ts`
-- Registr poskytovatele obrázků: `open-sse/config/imageRegistry.ts`
-- Dezinfekce odezvy: `open-sse/handlers/responseSanitizer.ts`
-- Normalizace rolí: `open-sse/services/roleNormalizer.ts`
+Main flow modules:
 
-Služby (obchodní logika):
+- Entry: `src/sse/handlers/chat.ts`
+- Core orchestration: `open-sse/handlers/chatCore.ts`
+- Provider execution adapters: `open-sse/executors/*`
+- Format detection/provider config: `open-sse/services/provider.ts`
+- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
+- Account fallback logic: `open-sse/services/accountFallback.ts`
+- Translation registry: `open-sse/translator/index.ts`
+- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
+- Think tag parser: `open-sse/utils/thinkTagParser.ts`
+- Embedding handler: `open-sse/handlers/embeddings.ts`
+- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
+- Image generation handler: `open-sse/handlers/imageGeneration.ts`
+- Image provider registry: `open-sse/config/imageRegistry.ts`
+- Response sanitization: `open-sse/handlers/responseSanitizer.ts`
+- Role normalization: `open-sse/services/roleNormalizer.ts`
 
-- Výběr účtu/bodování: `open-sse/services/accountSelector.ts`
-- Kontextová správa životního cyklu: `open-sse/services/contextManager.ts`
-- Vynucení filtru IP: `open-sse/services/ipFilter.ts`
-- Sledování relací: `open-sse/services/sessionManager.ts`
-- Žádost o deduplikaci: `open-sse/services/signatureCache.ts`
-- Vložení příkazu systému: `open-sse/services/systemPrompt.ts`
+Services (business logic):
+
+- Account selection/scoring: `open-sse/services/accountSelector.ts`
+- Context lifecycle management: `open-sse/services/contextManager.ts`
+- IP filter enforcement: `open-sse/services/ipFilter.ts`
+- Session tracking: `open-sse/services/sessionManager.ts`
+- Request deduplication: `open-sse/services/signatureCache.ts`
+- System prompt injection: `open-sse/services/systemPrompt.ts`
 - Thinking budget management: `open-sse/services/thinkingBudget.ts`
-- Směrování modelu se zástupnými znaky: `open-sse/services/wildcardRouter.ts`
-- Správa limitu sazby: `open-sse/services/rateLimitManager.ts`
-- Jistič: `open-sse/services/circuitBreaker.ts`
+- 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
 
-Moduly vrstvy domény:
+Domain layer modules:
 
-- Dostupnost modelu: `src/lib/domain/modelAvailability.ts`
-- Pravidla/rozpočty nákladů: `src/lib/domain/costRules.ts`
-- Záložní zásady: `src/lib/domain/fallbackPolicy.ts`
+- 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`
-- Zásady uzamčení: `src/lib/domain/lockoutPolicy.ts`
-- Modul zásad: `src/domain/policyEngine.ts` — centralizované uzamčení → rozpočet → záložní vyhodnocení
-- Katalog chybových kódů: `src/lib/domain/errorCodes.ts`
-- ID požadavku: `src/lib/domain/requestId.ts`
-- Časový limit načtení: `src/lib/domain/fetchTimeout.ts`
-- Žádost o telemetrii: `src/lib/domain/requestTelemetry.ts`
-- Soulad/audit: `src/lib/domain/compliance/index.ts`
+- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
+- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
+- Error codes catalog: `src/lib/domain/errorCodes.ts`
+- Request ID: `src/lib/domain/requestId.ts`
+- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
+- Request telemetry: `src/lib/domain/requestTelemetry.ts`
+- Compliance/audit: `src/lib/domain/compliance/index.ts`
 - Eval runner: `src/lib/domain/evalRunner.ts`
-- Trvalost stavu domény: `src/lib/db/domainState.ts` — SQLite CRUD pro záložní řetězce, rozpočty, historii nákladů, stav uzamčení, jističe
+- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
 
-Moduly poskytovatele OAuth (12 samostatných souborů pod `src/lib/oauth/providers/`):
+OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
-- Index registru: `src/lib/oauth/providers/index.ts`
-  – Jednotliví poskytovatelé: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `qoder.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilo`codes`, `kilo`code
-- Tenký obal: `src/lib/oauth/providers.ts` — reexporty z jednotlivých modulů## 3) Persistence Layer
+- 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`
+- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
-Primární stav DB (SQLite):
+## 3) Persistence Layer
 
-- Základní jádro: `src/lib/db/core.ts` (better-sqlite3, migrace, WAL)
-- Fasáda pro reexport: `src/lib/localDb.ts` (tenká vrstva kompatibility pro volající)
-- soubor: `${DATA_DIR}/storage.sqlite` (nebo `$XDG_CONFIG_HOME/omniroute/storage.sqlite`, pokud je nastaven, jinak `~/.omniroute/storage.sqlite`)
-- entity (tabulky + jmenné prostory KV): providerConnections, providerNodes, modelAliases, komba, apiKeys, nastavení, ceny,**customModels**,**proxyConfig**,**ipFilter**,**thinkingBudget**,**systemPrompt**
+Primary state DB (SQLite):
 
-Perzistence při používání:
+- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL)
+- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers)
+- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`)
+- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
 
-- fasáda: `src/lib/usageDb.ts` (rozložené moduly v `src/lib/usage/*`)
-- SQLite tabulky v `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
-- volitelné artefakty souborů zůstávají kvůli kompatibilitě/ladění (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
-- starší soubory JSON jsou migrovány do SQLite migrací při spuštění, pokud jsou k dispozici
+Usage persistence:
 
-Stavová databáze domény (SQLite):
+- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`)
+- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
+- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
+- legacy JSON files are migrated to SQLite by startup migrations when present
 
-- `src/lib/db/domainState.ts` — operace CRUD pro stav domény
-  – Tabulky (vytvořené v `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
-- Vzor mezipaměti pro zápis: mapy v paměti jsou autoritativní za běhu; mutace se zapisují synchronně do SQLite; stav je obnoven z DB při studeném startu## 4) Auth + Security Surfaces
+Domain State DB (SQLite):
 
-- Ověření souboru cookie řídicího panelu: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
-- Generování/ověření klíče API: `src/shared/utils/apiKey.ts`
-- Tajné informace poskytovatele zůstaly v položkách `providerConnections`
-- Podpora odchozích proxy přes `open-sse/utils/proxyFetch.ts` (env vars) a `open-sse/utils/networkProxy.ts` (konfigurovatelné pro jednotlivé poskytovatele nebo globální)## 5) Cloud Sync
+- `src/lib/db/domainState.ts` — CRUD operations for domain state
+- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
+- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
 
-- Init plánovače: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
-- Pravidelný úkol: `src/shared/services/cloudSyncScheduler.ts`
-- Pravidelný úkol: `src/shared/services/modelSyncScheduler.ts`
-- Řídící cesta: `src/app/api/sync/cloud/route.ts`## Request Lifecycle (`/v1/chat/completions`)
+## 4) Auth + Security Surfaces
+
+- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
+- API key generation/verification: `src/shared/utils/apiKey.ts`
+- Provider secrets persisted in `providerConnections` entries
+- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
+
+## 5) Cloud Sync
+
+- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
+- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Periodic task: `src/shared/services/modelSyncScheduler.ts`
+- Control route: `src/app/api/sync/cloud/route.ts`
+
+## Request Lifecycle (`/v1/chat/completions`)
 
 ```mermaid
 sequenceDiagram
@@ -338,7 +361,9 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-Záložní rozhodnutí jsou řízena `open-sse/services/accountFallback.ts` pomocí stavových kódů a heuristiky chybových zpráv. Kombinované směrování přidává ještě jednu ochranu: 400s v rozsahu poskytovatele, jako jsou selhání blokování obsahu a ověřování rolí, jsou považovány za lokální selhání modelu, takže pozdější kombinované cíle mohou stále běžet.## OAuth Onboarding and Token Refresh Lifecycle
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run.
+
+## OAuth Onboarding and Token Refresh Lifecycle
 
 ```mermaid
 sequenceDiagram
@@ -368,7 +393,9 @@ sequenceDiagram
     Test-->>UI: validation result
 ```
 
-Obnovení během živého provozu se provádí uvnitř `open-sse/handlers/chatCore.ts` prostřednictvím spouštěče `refreshCredentials()`.## Cloud Sync Lifecycle (Enable / Sync / Disable)
+Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
+
+## Cloud Sync Lifecycle (Enable / Sync / Disable)
 
 ```mermaid
 sequenceDiagram
@@ -400,7 +427,9 @@ sequenceDiagram
     Sync-->>UI: disabled
 ```
 
-Pravidelnou synchronizaci spouští „CloudSyncScheduler“, když je povolen cloud.## Data Model and Storage Map
+Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
+
+## Data Model and Storage Map
 
 ```mermaid
 erDiagram
@@ -501,12 +530,14 @@ erDiagram
     }
 ```
 
-Soubory fyzického úložiště:
+Physical storage files:
 
-- primární runtime DB: `${DATA_DIR}/storage.sqlite`
-- řádky protokolu požadavku: `${DATA_DIR}/log.txt` (artefakt compat/debug)
-- archivy strukturovaného obsahu volání: `${DATA_DIR}/call_logs/`
-- volitelné relace ladění překladatele/požadavku: `<repo>/logs/...`## Deployment Topology
+- primary runtime DB: `${DATA_DIR}/storage.sqlite`
+- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact)
+- structured call payload archives: `${DATA_DIR}/call_logs/`
+- optional translator/request debug sessions: `<repo>/logs/...`
+
+## Deployment Topology
 
 ```mermaid
 flowchart LR
@@ -541,205 +572,248 @@ flowchart LR
 
 ### Route and API Modules
 
-- `src/app/api/v1/*`, `src/app/api/v1beta/*`: rozhraní API pro kompatibilitu
-- `src/app/api/v1/providers/[poskytovatel]/*`: vyhrazené trasy pro jednotlivé poskytovatele (chat, vkládání, obrázky)
-- `src/app/api/providers*`: poskytovatel CRUD, ověření, testování
-- `src/app/api/provider-nodes*`: vlastní kompatibilní správa uzlů
-- `src/app/api/provider-models`: správa vlastních modelů (CRUD)
-- `src/app/api/models/route.ts`: API katalogu modelů (aliasy + vlastní modely)
-- `src/app/api/oauth/*`: toky OAuth/kódu zařízení
-- `src/app/api/keys*`: životní cyklus místního klíče API
-- `src/app/api/models/alias`: správa aliasů
-- `src/app/api/combos*`: správa záložních kombinací
-- `src/app/api/pricing`: přepisy cen pro výpočet nákladů
-- `src/app/api/settings/proxy`: konfigurace proxy (GET/PUT/DELETE)
-- `src/app/api/settings/proxy/test`: test odchozího proxy připojení (POST)
-- `src/app/api/usage/*`: využití a protokoly API
-- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloudová synchronizace a pomocníci pro cloud
-- `src/app/api/cli-tools/*`: místní zapisovače/kontroly konfigurace CLI
-- `src/app/api/settings/ip-filter`: seznam povolených/blokovaných IP adres (GET/PUT)
-- `src/app/api/settings/thinking-budget`: konfigurace rozpočtu tokenu myšlení (GET/PUT)
-- `src/app/api/settings/system-prompt`: globální systémová výzva (GET/PUT)
-- `src/app/api/sessions`: seznam aktivních relací (GET)
-- `src/app/api/rate-limits`: stav limitu sazby na účet (GET)### Routing and Execution Core
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
+- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
+- `src/app/api/providers*`: provider CRUD, validation, testing
+- `src/app/api/provider-nodes*`: custom compatible node management
+- `src/app/api/provider-models`: custom model management (CRUD)
+- `src/app/api/models/route.ts`: model catalog API (aliases + custom models)
+- `src/app/api/oauth/*`: OAuth/device-code flows
+- `src/app/api/keys*`: local API key lifecycle
+- `src/app/api/models/alias`: alias management
+- `src/app/api/combos*`: fallback combo management
+- `src/app/api/pricing`: pricing overrides for cost calculation
+- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
+- `src/app/api/usage/*`: usage and logs APIs
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
+- `src/app/api/cli-tools/*`: local CLI config writers/checkers
+- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
+- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
+- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
+- `src/app/api/sessions`: active session listing (GET)
+- `src/app/api/rate-limits`: per-account rate limit status (GET)
 
-- `src/sse/handlers/chat.ts`: analýza požadavků, zpracování kombinací, smyčka výběru účtu
-- `open-sse/handlers/chatCore.ts`: překlad, odeslání exekutora, zpracování opakování/obnovení, nastavení streamu
-- `open-sse/executors/*`: chování sítě a formátu specifické pro poskytovatele### Translation Registry and Format Converters
+### Routing and Execution Core
 
-- `open-sse/translator/index.ts`: registr a orchestrace překladatelů
-- Požadavek na překladatele: `open-sse/translator/request/*`
-- Překladače odpovědí: `open-sse/translator/response/*`
-- Formátové konstanty: `open-sse/translator/formats.ts`### Persistence
+- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
+- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
+- `open-sse/executors/*`: provider-specific network and format behavior
 
-- `src/lib/db/*`: trvalá trvalá konfigurace/stav a doména na SQLite
-- `src/lib/localDb.ts`: reexport kompatibility pro moduly DB
-- `src/lib/usageDb.ts`: fasáda historie použití/protokolů volání nad tabulkami SQLite## Provider Executor Coverage (Strategy Pattern)
+### Translation Registry and Format Converters
 
-Každý poskytovatel má specializovaný spouštěč rozšiřující `BaseExecutor` (v `open-sse/executors/base.ts`), který poskytuje vytváření URL, konstrukci záhlaví, opakování s exponenciálním stažením, háky pro obnovení pověření a metodu orchestrace `execute()`.
+- `open-sse/translator/index.ts`: translator registry and orchestration
+- Request translators: `open-sse/translator/request/*`
+- Response translators: `open-sse/translator/response/*`
+- Format constants: `open-sse/translator/formats.ts`
 
-| Exekutor              | Poskytovatel(é)                                                                                                                                              | Speciální manipulace                                                                     |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
-| `DefaultExecutor`     | OpenAI, Claude, Gemini, Qwen, Qoder, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamická konfigurace URL/záhlaví na poskytovatele                                       |
-| "AntigravityExecutor" | Google Antigravity                                                                                                                                           | Vlastní ID projektů/relací, Opakovat po analýze                                          |
-| "CodexExecutor"       | Kodex OpenAI                                                                                                                                                 | Vkládá systémové instrukce, nutí k logickému úsilí                                       |
-| `CursorExecutor`      | Kurzor IDE                                                                                                                                                   | Protokol ConnectRPC, kódování Protobuf, podepisování požadavků pomocí kontrolního součtu |
-| "GithubExecutor"      | GitHub Copilot                                                                                                                                               | Obnovení tokenu druhého pilota, hlavičky napodobující VSCode                             |
-| "KiroExecutor"        | AWS CodeWhisperer/Kiro                                                                                                                                       | Binární formát AWS EventStream → konverze SSE                                            |
-| "GeminiCLIExecutor"   | Gemini CLI                                                                                                                                                   | Cyklus obnovení tokenu Google OAuth                                                      |
+### Persistence
 
-Všichni ostatní poskytovatelé (včetně vlastních kompatibilních uzlů) používají `DefaultExecutor`.## Provider Compatibility Matrix
+- `src/lib/db/*`: persistent config/state and domain persistence on SQLite
+- `src/lib/localDb.ts`: compatibility re-export for DB modules
+- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables
 
-| Poskytovatel     | Formát           | Auth                     | Stream               | Nestreamovat | Obnovení tokenu | Použití API         |
-| ---------------- | ---------------- | ------------------------ | -------------------- | ------------ | --------------- | ------------------- | ------------------------------ |
-| Claude           | claude           | Klíč API / OAuth         | ✅                   | ✅           | ✅              | ⚠️ Pouze správce    |
-| Blíženci         | Blíženci         | Klíč API / OAuth         | ✅                   | ✅           | ✅              | ⚠️ Cloudová konzole |
-| Gemini CLI       | gemini-cli       | OAuth                    | ✅                   | ✅           | ✅              | ⚠️ Cloudová konzole |
-| Antigravitace    | antigravitace    | OAuth                    | ✅                   | ✅           | ✅              | ✅ Plná kvóta API   |
-| OpenAI           | openai           | API klíč                 | ✅                   | ✅           | ❌              | ❌                  |
-| Codex            | openai-responses | OAuth                    | ✅ nuceně            | ❌           | ✅              | ✅ Sazbové limity   |
-| GitHub Copilot   | openai           | OAuth + Copilot Token    | ✅                   | ✅           | ✅              | ✅ Snímky kvót      |
-| Kurzor           | kurzor           | Vlastní kontrolní součet | ✅                   | ✅           | ❌              | ❌                  |
-| Kiro             | kiro             | AWS SSO OIDC             | ✅ (Stream událostí) | ❌           | ✅              | ✅ Limity použití   |
-| Qwen             | openai           | OAuth                    | ✅                   | ✅           | ✅              | ⚠️ Na vyžádání      |
-| Qoder            | openai           | OAuth (základní)         | ✅                   | ✅           | ✅              | ⚠️ Na vyžádání      |
-| OpenRouter       | openai           | API klíč                 | ✅                   | ✅           | ❌              | ❌                  |
-| GLM/Kimi/MiniMax | claude           | API klíč                 | ✅                   | ✅           | ❌              | ❌                  |
-| DeepSeek         | openai           | API klíč                 | ✅                   | ✅           | ❌              | ❌                  |
-| Groq             | openai           | API klíč                 | ✅                   | ✅           | ❌              | ❌                  |
-| xAI (Grok)       | openai           | API klíč                 | ✅                   | ✅           | ❌              | ❌                  |
-| Mistral          | openai           | API klíč                 | ✅                   | ✅           | ❌              | ❌                  |
-| Zmatenost        | openai           | API klíč                 | ✅                   | ✅           | ❌              | ❌                  |
-| Společně AI      | openai           | Klíč API                 | ✅                   | ✅           | ❌              | ❌                  |
-| Ohňostroje AI    | openai           | API klíč                 | ✅                   | ✅           | ❌              | ❌                  |
-| Cerebras         | openai           | API klíč                 | ✅                   | ✅           | ❌              | ❌                  |
-| Cohere           | openai           | API klíč                 | ✅                   | ✅           | ❌              | ❌                  |
-| NVIDIA NIM       | openai           | API klíč                 | ✅                   | ✅           | ❌              | ❌                  | ## Format Translation Coverage |
+## Provider Executor Coverage (Strategy Pattern)
 
-Mezi zjištěné zdrojové formáty patří:
+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.
 
-- "openai".
-- "openai-odpovědi".
-- "claude".
-- "blíženci".
+| 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                                     |
 
-Mezi cílové formáty patří:
+All other providers (including custom compatible nodes) use the `DefaultExecutor`.
 
-- OpenAI chat/odpovědi
+## Provider Compatibility Matrix
+
+| Provider         | Format           | Auth                  | Stream           | Non-Stream | Token Refresh | Usage API          |
+| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
+| Claude           | claude           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Admin only      |
+| Gemini           | gemini           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Gemini CLI       | gemini-cli       | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Antigravity      | antigravity      | OAuth                 | ✅               | ✅         | ✅            | ✅ Full quota API  |
+| OpenAI           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Codex            | openai-responses | OAuth                 | ✅ forced        | ❌         | ✅            | ✅ Rate limits     |
+| GitHub Copilot   | openai           | OAuth + Copilot Token | ✅               | ✅         | ✅            | ✅ Quota snapshots |
+| Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
+| Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
+| Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Qoder            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Groq             | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| xAI (Grok)       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Mistral          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Perplexity       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Together AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Fireworks AI     | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+
+## Format Translation Coverage
+
+Detected source formats include:
+
+- `openai`
+- `openai-responses`
+- `claude`
+- `gemini`
+
+Target formats include:
+
+- OpenAI chat/Responses
 - Claude
-- Gemini/Gemini-CLI/Antigravitační obálka
+- Gemini/Gemini-CLI/Antigravity envelope
 - Kiro
-- Kurzor
+- Cursor
 
-Překlady používají**OpenAI jako formát centra**— všechny konverze procházejí přes OpenAI jako prostředník:```
+Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
+
+```
 Source Format → OpenAI (hub) → Target Format
+```
 
-````
+Translations are selected dynamically based on source payload shape and provider target format.
 
-Překlady jsou vybírány dynamicky na základě tvaru zdrojové užitečné zátěže a cílového formátu poskytovatele.
+Additional processing layers in the translation pipeline:
 
-Další vrstvy zpracování v překladovém potrubí:
+- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance
+- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)
+- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field
+- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`
 
--**Dezinfekce odezvy**– Odstraňuje nestandardní pole z odpovědí ve formátu OpenAI (streamovaných i nestreamovaných), aby byla zajištěna přísná shoda se sadou SDK
--**Normalizace rolí**— Převádí `vývojář` → `systém` pro jiné cíle než OpenAI; sloučí `systém` → `uživatel` pro modely, které odmítají systémovou roli (GLM, ERNIE)
-–**Extrakce značek Think**– analyzuje bloky „<think>...</think>“ z obsahu do pole „reasoning_content“
-–**Strukturovaný výstup**– Převádí OpenAI `response_format.json_schema` na Gemini `responseMimeType` + `responseSchema`## Supported API Endpoints
+## Supported API Endpoints
 
-| Koncový bod | Formát | Psovod |
-| --------------------------------------------------- | ------------------- | -------------------------------------------------------------------- |
-| `POST /v1/chat/completions` | Chat OpenAI | `src/sse/handlers/chat.ts` |
-| `POST /v1/messages` | Claude Messages | Stejná obsluha (automaticky zjištěna) |
-| `POST /v1/responses` | Odezvy OpenAI | `open-sse/handlers/responsesHandler.ts` |
-| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` |
-| `ZÍSKAT /v1/embeddings` | Seznam modelů | Cesta API |
-| `POST /v1/images/generations` | Obrázky OpenAI | `open-sse/handlers/imageGeneration.ts` |
-| `ZÍSKAT /v1/images/generations` | Seznam modelů | Cesta API |
-| `POST /v1/providers/{provider}/chat/completions` | Chat OpenAI | Vyhrazené na poskytovatele s ověřením modelu |
-| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Vyhrazené na poskytovatele s ověřením modelu |
-| `POST /v1/providers/{poskytovatel}/images/generations` | Obrázky OpenAI | Vyhrazené na poskytovatele s ověřením modelu |
-| `POST /v1/messages/count_tokens` | Počet tokenů Claude | Cesta API |
-| `GET /v1/models` | Seznam modelů OpenAI | Cesta API (chat + vkládání + obrázek + vlastní modely) |
-| `GET /api/models/catalog` | Katalog | Všechny modely seskupené podle poskytovatele + typ |
-| `POST /v1beta/models/*:streamGenerateContent` | Blíženec domorodec | Cesta API |
-| `GET/PUT/DELETE /api/settings/proxy` | Konfigurace proxy | Konfigurace síťového proxy |
-| `POST /api/settings/proxy/test` | Připojení proxy | Koncový bod testu stavu proxy/konektivity |
-| `GET/POST/DELETE /api/provider-models` | Modely poskytovatelů | Vlastní a spravované dostupné modely podporují metadata modelu poskytovatele |## Bypass Handler
+| Endpoint                                           | Format             | Handler                                                             |
+| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------- |
+| `POST /v1/chat/completions`                        | OpenAI Chat        | `src/sse/handlers/chat.ts`                                          |
+| `POST /v1/messages`                                | Claude Messages    | Same handler (auto-detected)                                        |
+| `POST /v1/responses`                               | OpenAI Responses   | `open-sse/handlers/responsesHandler.ts`                             |
+| `POST /v1/embeddings`                              | OpenAI Embeddings  | `open-sse/handlers/embeddings.ts`                                   |
+| `GET /v1/embeddings`                               | Model listing      | API route                                                           |
+| `POST /v1/images/generations`                      | OpenAI Images      | `open-sse/handlers/imageGeneration.ts`                              |
+| `GET /v1/images/generations`                       | Model listing      | API route                                                           |
+| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat        | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings  | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/images/generations` | OpenAI Images      | Dedicated per-provider with model validation                        |
+| `POST /v1/messages/count_tokens`                   | Claude Token Count | API route                                                           |
+| `GET /v1/models`                                   | OpenAI Models list | API route (chat + embedding + image + custom models)                |
+| `GET /api/models/catalog`                          | Catalog            | All models grouped by provider + type                               |
+| `POST /v1beta/models/*:streamGenerateContent`      | Gemini native      | API route                                                           |
+| `GET/PUT/DELETE /api/settings/proxy`               | Proxy Config       | Network proxy configuration                                         |
+| `POST /api/settings/proxy/test`                    | Proxy Connectivity | Proxy health/connectivity test endpoint                             |
+| `GET/POST/DELETE /api/provider-models`             | Provider Models    | Provider model metadata backing custom and managed available models |
 
-Obslužná rutina bypassu (`open-sse/utils/bypassHandler.ts`) zachycuje známé požadavky na „zahození“ od Claude CLI – zahřívací pingy, extrakce titulů a počty tokenů – a vrací**falešnou odpověď**, aniž by spotřebovával tokeny poskytovatele upstream. To se spustí pouze v případě, že `User-Agent` obsahuje `claude-cli`.## Request Logger Pipeline
+## Bypass Handler
 
-Záznamník požadavků (`open-sse/utils/requestLogger.ts`) poskytuje 7fázový kanál protokolování ladění, který je ve výchozím nastavení vypnutý, povolený pomocí `ENABLE_REQUEST_LOGS=true`:```
-1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json
-→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt
-````
+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`.
 
-Soubory se zapisují do `<repo>/logs/<session>/` pro každou relaci požadavku.## Failure Modes and Resilience
+## Request Logging and Artifacts
+
+The older file-based request logger (`open-sse/utils/requestLogger.ts`) is retained only for
+legacy compatibility. The current runtime contract uses:
+
+- `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
 
-- Cooldown účtu poskytovatele při přechodných chybách/chybách rychlosti/autorizace
-- záložní účet před neúspěšným žádostí
-- Záloha kombinovaného modelu, když je vyčerpána aktuální cesta modelu/poskytovatele## 2) Token Expiry
+- provider account cooldown on transient/rate/auth errors
+- account fallback before failing request
+- combo model fallback when current model/provider path is exhausted
 
-- Předběžná kontrola a obnovení s opakovaným pokusem pro poskytovatele obnovitelných zdrojů
-- 401/403 opakování po pokusu o obnovení v cestě jádra## 3) Stream Safety
+## 2) Token Expiry
 
-- řadič toku s vědomím odpojení
-- překladový proud s vyprázdněním konce proudu a zpracováním `[DONE]`
-- záložní odhad využití, když chybí metadata využití poskytovatele## 4) Cloud Sync Degradation
+- pre-check and refresh with retry for refreshable providers
+- 401/403 retry after refresh attempt in core path
 
-- Objeví se chyby synchronizace, ale místní běh pokračuje
-- plánovač má logiku umožňující opakování, ale periodické spouštění aktuálně standardně volá synchronizaci na jeden pokus## 5) Data Integrity
+## 3) Stream Safety
 
-- Migrace schémat SQLite a automatické upgrady při spuštění
-- starší cesta ke kompatibilitě migrace JSON → SQLite## Observability and Operational Signals
+- disconnect-aware stream controller
+- translation stream with end-of-stream flush and `[DONE]` handling
+- usage estimation fallback when provider usage metadata is missing
 
-Zdroje viditelnosti za běhu:
+## 4) Cloud Sync Degradation
 
-- protokoly konzoly z `src/sse/utils/logger.ts`
-- agregáty využití na žádost v SQLite (`usage_history`, `call_logs`, `proxy_logs`)
-- čtyřfázové podrobné zachycení užitečného zatížení v SQLite (`request_detail_logs`), když `settings.detailed_logs_enabled=true`
-- textový protokol o stavu požadavku v `log.txt` (nepovinné/kompatibilní)
-- volitelné protokoly hlubokých požadavků/překladů pod `logs/`, když `ENABLE_REQUEST_LOGS=true`
-- koncové body využití řídicího panelu (`/api/usage/*`) pro spotřebu uživatelského rozhraní
+- sync errors are surfaced but local runtime continues
+- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
 
-Podrobné zachycení datové části požadavku ukládá až čtyři fáze datové zátěže JSON na směrované volání:
+## 5) Data Integrity
 
-- nezpracovaný požadavek přijatý od klienta
-- přeložená žádost skutečně odeslaná proti proudu
-- odpověď poskytovatele rekonstruovaná jako JSON; streamované odpovědi jsou komprimovány do konečného shrnutí plus metadata streamu
-- konečná odpověď klienta vrácená OmniRoute; streamované odpovědi jsou uloženy ve stejném kompaktním souhrnném formuláři## Security-Sensitive Boundaries
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
-- Tajný klíč JWT (`JWT_SECRET`) zajišťuje ověřování/podepisování souborů cookie relace řídicího panelu
-- Počáteční zaváděcí heslo (`INITIAL_PASSWORD`) by mělo být explicitně nakonfigurováno pro zřizování při prvním spuštění
-- Tajný klíč API HMAC (`API_KEY_SECRET`) zabezpečuje vygenerovaný formát lokálního klíče API
-- Tajné informace poskytovatele (klíče/tokeny API) jsou uloženy v místní databázi a měly by být chráněny na úrovni souborového systému
-- Koncové body synchronizace cloudu se spoléhají na sémantiku klíče API + ID počítače## Environment and Runtime Matrix
+## Observability and Operational Signals
 
-Proměnné prostředí aktivně používané kódem:
+Runtime visibility sources:
 
-- Aplikace/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
-- Úložiště: `DATA_DIR`
-- Kompatibilní chování uzlu: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
-- Volitelné přepsání základny úložiště (Linux/macOS, když není `DATA_DIR` nastaveno): `XDG_CONFIG_HOME`
-  – Bezpečnostní hash: `API_KEY_SECRET`, `MACHINE_ID_SALT`
-- Protokolování: `ENABLE_REQUEST_LOGS`
-  – Synchronizace/cloudové URL: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
-  – Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` a varianty s malými písmeny
-- Příznaky funkce SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
-- Pomocníci platformy/běhu (nikoli konfigurace specifická pro aplikaci): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`## Known Architectural Notes
+- console logs from `src/sse/utils/logger.ts`
+- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true`
+- textual request status log in `log.txt` (optional/compat)
+- optional 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
 
-1. `usageDb` a `localDb` sdílejí stejnou zásadu základního adresáře (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) se starší migrací souborů.
-2. `/api/v1/route.ts` deleguje stejný tvůrce jednotného katalogu, který používá `/api/v1/models` (`src/app/api/v1/models/catalog.ts`), aby se zabránilo sémantickému posunu.
-3. Pokud je povoleno, zapisovač požadavku zapisuje celé záhlaví/tělo; považovat adresář log za citlivý.
-4. Chování cloudu závisí na správné dosažitelnosti koncového bodu cloudu „NEXT_PUBLIC_BASE_URL“.
-5. Adresář `open-sse/` je publikován jako balíček `@omniroute/open-sse`**npm workspace**. Zdrojový kód jej importuje přes `@omniroute/open-sse/...` (vyřešeno Next.js `transpilePackages`). Cesty k souborům v tomto dokumentu stále používají název adresáře `open-sse/` kvůli konzistenci.
-6. Grafy v řídicím panelu používají**Recharts**(založené na SVG) pro přístupné, interaktivní analytické vizualizace (sloupcové grafy využití modelu, tabulky rozdělení poskytovatelů s mírou úspěšnosti).
-7. E2E testy používají**Playwright**(`tests/e2e/`), spouštěné přes `npm run test:e2e`. Unit testy používají**Node.js test runner**(`tests/unit/`), spouštějí se přes `npm run test:unit`. Zdrojový kód pod `src/` je**TypeScript**(`.ts`/`.tsx`); pracovní prostor `open-sse/` zůstává JavaScriptem (`.js`).
-8. Stránka Nastavení je uspořádána do 5 záložek: Zabezpečení, Směrování (6 globálních strategií: fill-first, round-robin, p2c, náhodné, nejméně používané, nákladově optimalizované), Odolnost (upravitelné rychlostní limity, jistič, zásady), AI (rozpočet myšlení, systémová výzva, mezipaměť výzvy), Pokročilé (proxy).## Operational Verification Checklist
+Detailed request payload capture stores up to four JSON payload stages per routed call:
 
-- Sestavení ze zdroje: `npm run build`
-- Sestavení obrazu Dockeru: `docker build -t omniroute .`
-- Spusťte službu a ověřte:
+- raw request received from the client
+- translated request actually sent upstream
+- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata
+- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form
+
+## Security-Sensitive Boundaries
+
+- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
+- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning
+- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format
+- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level
+- Cloud sync endpoints rely on API key auth + machine id semantics
+
+## Environment and Runtime Matrix
+
+Environment variables actively used by code:
+
+- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Storage: `DATA_DIR`
+- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
+- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME`
+- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
+- Logging: `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`
+- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+
+## Known Architectural Notes
+
+1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.
+2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift.
+3. Request logger writes full headers/body when enabled; treat log directory as sensitive.
+4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability.
+5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency.
+6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates).
+7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`).
+8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies, **Context Relay** handoff config), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
+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 24+ detection**: `/api/settings/require-login` returns `nodeVersion` and `nodeCompatible` fields. The login page renders a warning banner when the runtime is incompatible.
+
+## Operational Verification Checklist
+
+- Build from source: `npm run build`
+- Build Docker image: `docker build -t omniroute .`
+- Start service and verify:
 - `GET /api/settings`
 - `GET /api/v1/models`
-- Základní adresa URL cíle CLI by měla být `http://<hostitel>:20128/v1`, když `PORT=20128`
+- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`

docs/i18n/cs/docs/CODEBASE_DOCUMENTATION.md

@@ -387,7 +387,7 @@ import "./request/claude-to-openai.js"; // ← self-registers
 | `stream.ts`        | **SSE Transform Stream**– hlavní streamovací kanál. Dva režimy: `TRANSLATE` (překlad plného formátu) a `PASSTHROUGH` (normalizovat + extrahovat použití). Zvládá ukládání do vyrovnávací paměti, odhad využití, sledování délky obsahu. Instance kodéru/dekodéru pro jednotlivé proudy se vyhýbají sdílenému stavu. |
 | `streamHelpers.ts` | Nízkoúrovňové nástroje SSE: `parseSSELine` (tolerující mezery), `hasValuableContent` (filtruje prázdné bloky pro OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (serializace SSE s ohledem na formát s vyčištěním `perf_metrics`).                                                                              |
 | `usageTracking.ts` | Extrakce využití tokenů z libovolného formátu (Claude/OpenAI/Gemini/Responses), odhad pomocí samostatných poměrů znaků na token nástroje/zprávy, přidání do vyrovnávací paměti (bezpečnostní rezerva 2000 tokenů), filtrování polí podle formátu, protokolování konzoly pomocí barev ANSI.                          |
-| `requestLogger.ts` | Protokolování požadavků na základě souborů (přihlášení přes `ENABLE_REQUEST_LOGS=true`). Vytváří složky relací s číslovanými soubory: `1_req_client.json` → `7_res_client.txt`. Všechny I/O jsou asynchronní (fire-and-forget). Maskuje citlivé hlavičky.                                                           |
+| `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` | Zachycuje specifické vzory z Claude CLI (extrakce titulů, zahřívání, počet) a vrací falešné odpovědi bez volání jakéhokoli poskytovatele. Podporuje streamování i nestreamování. Záměrně omezeno na rozsah Claude CLI.                                                                                              |
 | `networkProxy.ts`  | Vyřeší odchozí adresu URL proxy pro daného poskytovatele s prioritou: konfigurace specifická pro poskytovatele → globální konfigurace → proměnné prostředí (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Podporuje výjimky `NO_PROXY`. Konfiguraci mezipaměti po dobu 30 s.                                             | #### SSE Streaming Pipeline |
 

docs/i18n/cs/docs/FEATURES.md

@@ -4,102 +4,168 @@
 
 ---
 
-Vizuální průvodce každou částí řídicího panelu OmniRoute.---
+
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
 
 ## 🔌 Providers
 
-Správa připojení poskytovatelů AI: poskytovatelé OAuth (Claude Code, Codex, Gemini CLI), poskytovatelé klíčů API (Groq, DeepSeek, OpenRouter) a bezplatní poskytovatelé (Qoder, Qwen, Kiro). Účty Kiro zahrnují sledování zůstatku kreditu – zbývající kredity, celkový příspěvek a datum obnovení jsou viditelné v Dashboard → Použití.![Providers Dashboard](screenshots/01-providers.png)
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+![Providers Dashboard](screenshots/01-providers.png)
 
 ---
 
 ## 🎨 Combos
 
-Vytvářejte komba směrování modelů se 6 strategiemi: prioritní, vážená, cyklická, náhodná, nejméně používaná a nákladově optimalizovaná. Každé kombo řetězí více modelů s automatickým nouzovým návratem a zahrnuje rychlé šablony a kontroly připravenosti.![Combos Dashboard](screenshots/02-combos.png)
+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.
+
+![Combos Dashboard](screenshots/02-combos.png)
 
 ---
 
 ## 📊 Analytics
 
-Komplexní analýzy využití se spotřebou tokenů, odhady nákladů, teplotní mapy aktivit, týdenní distribuční grafy a rozpisy podle poskytovatelů.![Analytics Dashboard](screenshots/03-analytics.png)
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
 
 ---
 
 ## 🏥 System Health
 
-Monitorování v reálném čase: doba provozuschopnosti, paměť, verze, percentily latence (p50/p95/p99), statistika mezipaměti a stavy jističe poskytovatele.![Health Dashboard](screenshots/04-health.png)
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+![Health Dashboard](screenshots/04-health.png)
 
 ---
 
 ## 🔧 Translator Playground
 
-Čtyři režimy pro ladění překladů API:**Playground**(konvertor formátů),**Chat Tester**(živé požadavky),**Test Bench**(dávkové testy) a**Live Monitor**(stream v reálném čase).![Translator Playground](screenshots/05-translator.png)
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+![Translator Playground](screenshots/05-translator.png)
 
 ---
 
 ## 🎮 Model Playground _(v2.0.9+)_
 
-Otestujte jakýkoli model přímo z palubní desky. Vyberte poskytovatele, model a koncový bod, pište výzvy pomocí editoru Monaco, streamujte odpovědi v reálném čase, rušte uprostřed streamu a zobrazujte metriky časování.---
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
 
 ## 🎨 Themes _(v2.0.5+)_
 
-Přizpůsobitelné barevné motivy pro celý přístrojový panel. Vyberte si ze 7 přednastavených barev (korálová, modrá, červená, zelená, fialová, oranžová, azurová) nebo si vytvořte vlastní motiv výběrem libovolné šestihranné barvy. Podporuje světlý, tmavý a systémový režim.---
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
 
 ## ⚙️ Settings
 
-Komplexní panel nastavení s kartami:
+Comprehensive settings panel with tabs:
 
--**Obecné**— Systémové úložiště, správa zálohování (export/import databáze) -**Vzhled**— Volič motivu (tmavý/světlý/systém), přednastavení barevných motivů a vlastní barvy, viditelnost zdravotního deníku, ovládací prvky viditelnosti položek na postranním panelu -**Zabezpečení**— Ochrana koncových bodů API, blokování vlastního poskytovatele, filtrování IP, informace o relaci -**Směrování**— Modelové aliasy, degradace úloh na pozadí -**Odolnost**- Perzistence rychlostního limitu, ladění jističe, automatické deaktivace zakázaných účtů, sledování expirace poskytovatele -**Advanced**– Přepisy konfigurace, auditní záznam konfigurace, režim degradace záložního řešení![Settings Dashboard](screenshots/06-settings.png)
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring, **Context Relay** handoff threshold and summary model configuration
+- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
+
+![Settings Dashboard](screenshots/06-settings.png)
 
 ---
 
 ## 🔧 CLI Tools
 
-Konfigurace jedním kliknutím pro nástroje pro kódování AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor a Factory Droid. Obsahuje automatické nastavení konfigurace/resetování, profily připojení a mapování modelu.![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
 
 ---
 
 ## 🤖 CLI Agents _(v2.0.11+)_
 
-Dashboard pro zjišťování a správu agentů CLI. Zobrazuje mřížku 14 vestavěných agentů (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) s:
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
 
--**Stav instalace**— Instalováno / Nenalezeno s detekcí verze -**Odznaky protokolu**— stdio, HTTP atd. -**Vlastní agenti**— Zaregistrujte jakýkoli nástroj CLI prostřednictvím formuláře (název, binární soubor, příkaz verze, spawn args) -**CLI Fingerprint Matching**– Přepínání na jednotlivé poskytovatele, aby odpovídalo nativním podpisům požadavků CLI, čímž se snižuje riziko zákazu při zachování IP adresy proxy---
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🔗 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
+
+---
 
 ## 🖼️ Media _(v2.0.3+)_
 
-Generujte obrázky, videa a hudbu z řídicího panelu. Podporuje OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open a MusicGen.---
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
 
 ## 📝 Request Logs
 
-Protokolování požadavků v reálném čase s filtrováním podle poskytovatele, modelu, účtu a klíče API. Zobrazuje stavové kódy, využití tokenu, latenci a podrobnosti o odpovědi.![Usage Logs](screenshots/08-usage.png)
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+![Usage Logs](screenshots/08-usage.png)
 
 ---
 
 ## 🌐 API Endpoint
 
-Váš sjednocený koncový bod API s rozdělením schopností: Dokončení chatu, API odpovědí, vkládání, generování obrázků, změna pořadí, přepis zvuku, převod textu na řeč, moderování a registrované klíče rozhraní API. Integrace Cloudflare Quick Tunnel a podpora cloudového proxy pro vzdálený přístup.![Endpoint Dashboard](screenshots/09-endpoint.png)
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)
 
 ---
 
 ## 🔑 API Key Management
 
-Vytvářejte, upravujte a rušte klíče API. Každý klíč může být omezen na konkrétní modely/poskytovatele s plným přístupem nebo oprávněním pouze pro čtení. Vizuální správa klíčů se sledováním využití.---
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
 
 ## 📋 Audit Log
 
-Sledování administrativních akcí s filtrováním podle typu akce, aktéra, cíle, IP adresy a časového razítka. Úplná historie událostí zabezpečení.---
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
 
 ## 🖥️ Desktop Application
 
-Nativní desktopová aplikace Electron pro Windows, macOS a Linux. Spusťte OmniRoute jako samostatnou aplikaci s integrací na systémové liště, offline podporou, automatickou aktualizací a instalací jedním kliknutím.
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
 
-Klíčové vlastnosti:
+Key features:
 
-- Dotazování připravenosti serveru (žádná prázdná obrazovka při studeném startu)
-- Systémová lišta se správou portů
-- Zásady zabezpečení obsahu
-- Jednoinstanční zámek
-- Automatická aktualizace při restartu
-- Platformově podmíněné uživatelské rozhraní (semafory macOS, výchozí titulek Windows/Linux)
-- Balení sestavení Hardened Electron – symbolicky propojené `node_modules` v samostatném balíčku jsou detekovány a odmítnuty před zabalením, čímž se zabrání závislosti běhu na sestavení (v2.5.5+)
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
 
-📖 Úplnou dokumentaci naleznete v [`electron/README.md`](../electron/README.md).
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/cs/docs/TROUBLESHOOTING.md

@@ -4,69 +4,141 @@
 
 ---
 
-Běžné problémy a řešení pro OmniRoute.---
+Common problems and solutions for OmniRoute.
+
+---
 
 ## Quick Fixes
 
-| Problém                                  | Řešení                                                                                |
-| ---------------------------------------- | ------------------------------------------------------------------------------------- | --- |
-| První přihlášení nefunguje               | Nastavit `INITIAL_PASSWORD` v `.env` (žádné napevno zakódované výchozí nastavení)     |
-| Dashboard se otevírá na nesprávném portu | Nastavit `PORT=20128` a `NEXT_PUBLIC_BASE_URL=http://localhost:20128`                 |
-| Žádné záznamy požadavků pod `logs/`      | Nastavte `ENABLE_REQUEST_LOGS=true`                                                   |
-| EACCES: povolení odepřeno                | Nastavte `DATA_DIR=/cesta/k/zapisovatelnému/adresáři` tak, aby přepsal `~/.omniroute` |
-| Strategie směrování se neukládá          | Aktualizace na v1.4.11+ (oprava schématu Zod pro trvalost nastavení)                  | --- |
+| 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      | You may be on Node.js 24+ — see [Node.js Compatibility](#nodejs-compatibility) 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 Node.js 24+. The `better-sqlite3` native binary is not compatible with Node.js 24, which causes a fatal crash when the server tries to initialize the database.
+
+**Symptoms:**
+
+- Login page shows a blank screen or a server error
+- Console shows `Error: Module did not self-register` or similar native binding errors
+- Starting with v3.5.5, the login page shows an **orange warning banner** with your Node version if incompatibility is detected
+
+**Fix:**
+
+1. Install Node.js 22 LTS (recommended):
+   ```bash
+   nvm install 22
+   nvm use 22
+   ```
+2. Verify your version: `node --version` should show `v22.x.x`
+3. Reinstall OmniRoute: `npm install -g omniroute`
+4. Restart: `omniroute`
+
+> **Supported versions:** Node.js 18, 20, or 22 LTS. Node.js 24+ is **not supported**.
+
+---
+
+## 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+.
+
+---
 
 ## Provider Issues
 
 ### "Language model did not provide messages"
 
-**Příčina:**Kvóta poskytovatele je vyčerpána.
+**Cause:** Provider quota exhausted.
 
-**Oprava:**
+**Fix:**
 
-1. Zkontrolujte sledování kvót na řídicím panelu
-2. Použijte kombinaci se záložními úrovněmi
-3. Přejděte na levnější/bezplatnou úroveň### Rate Limiting
+1. Check dashboard quota tracker
+2. Use a combo with fallback tiers
+3. Switch to cheaper/free tier
 
-**Příčina:**Vyčerpaná kvóta předplatného.
+### Rate Limiting
 
-**Oprava:**
+**Cause:** Subscription quota exhausted.
 
-– Přidejte záložní: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+**Fix:**
 
-- Použijte GLM/MiniMax jako levnou zálohu### OAuth Token Expired
+- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Use GLM/MiniMax as cheap backup
 
-OmniRoute automaticky obnovuje tokeny. Pokud problémy přetrvávají:
+### OAuth Token Expired
 
-1. Ovládací panel → Poskytovatel → Znovu připojit
-2. Odstraňte a znovu přidejte připojení poskytovatele---
+OmniRoute auto-refreshes tokens. If issues persist:
+
+1. Dashboard → Provider → Reconnect
+2. Delete and re-add the provider connection
+
+---
 
 ## Cloud Issues
 
 ### Cloud Sync Errors
 
-1. Ověřte, že `BASE_URL` odkazuje na vaši spuštěnou instanci (např. `http://localhost:20128`)
-2. Ověřte, že `CLOUD_URL` odkazuje na váš koncový bod cloudu (např. `https://omniroute.dev`)
-3. Udržujte hodnoty `NEXT_PUBLIC_*` zarovnané s hodnotami na straně serveru### Cloud `stream=false` Returns 500
+1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
+2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
+3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
 
-**Příznak:**`Neočekávaný token 'd'...` na koncovém bodu cloudu pro nestreamovaná volání.
+### Cloud `stream=false` Returns 500
 
-**Příčina:**Upstream vrací užitečné zatížení SSE, zatímco klient očekává JSON.
+**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
 
-**Řešení:**Pro přímá cloudová volání použijte `stream=true`. Místní běhové prostředí zahrnuje záložní SSE→JSON.### Cloud Says Connected but "Invalid API key"
+**Cause:** Upstream returns SSE payload while client expects JSON.
 
-1. Vytvořte nový klíč z místního řídicího panelu (`/api/keys`)
-2. Spusťte synchronizaci s cloudem: Povolte cloud → Synchronizovat nyní
-3. Staré/nesynchronizované klíče mohou v cloudu stále vracet „401“.---
+**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
+
+### Cloud Says Connected but "Invalid API key"
+
+1. Create a fresh key from local dashboard (`/api/keys`)
+2. Run cloud sync: Enable Cloud → Sync Now
+3. Old/non-synced keys can still return `401` on cloud
+
+---
 
 ## Docker Issues
 
 ### CLI Tool Shows Not Installed
 
-1. Zkontrolujte pole runtime: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
-2. Pro přenosný režim: použijte cíl obrazu `runner-cli` (přibalená rozhraní CLI)
-3. Pro režim připojení hostitele: nastavte `CLI_EXTRA_PATHS` a připojte adresář hostitele bin jako pouze pro čtení
-4. Pokud `installed=true` a `runnable=false`: binární soubor byl nalezen, ale neprošel zdravotní kontrolou### Quick Runtime Validation
+1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. For portable mode: use image target `runner-cli` (bundled CLIs)
+3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
+4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
+
+### Quick Runtime Validation
 
 ```bash
 curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
@@ -80,16 +152,22 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
 
 ### High Costs
 
-1. Zkontrolujte statistiky využití v Dashboard → Usage
-2. Přepněte primární model na GLM/MiniMax
-3. Pro nekritické úkoly používejte bezplatnou vrstvu (Gemini CLI, Qoder).
-4. Nastavte rozpočty nákladů na klíč API: Dashboard → API Keys → Budget---
+1. Check usage stats in Dashboard → Usage
+2. Switch primary model to GLM/MiniMax
+3. Use free tier (Gemini CLI, Qoder) for non-critical tasks
+4. Set cost budgets per API key: Dashboard → API Keys → Budget
+
+---
 
 ## Debugging
 
-### Enable Request Logs
+### Enable Log Files
 
-V souboru `.env` nastavte `ENABLE_REQUEST_LOGS=true`. Protokoly se zobrazují v adresáři `logs/`.### Check Provider Health
+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
 
 ```bash
 # Health dashboard
@@ -101,106 +179,136 @@ curl http://localhost:20128/api/monitoring/health
 
 ### Runtime Storage
 
-- Hlavní stav: `${DATA_DIR}/storage.sqlite` (poskytovatelé, komba, aliasy, klíče, nastavení)
-- Použití: SQLite tabulky v `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + volitelné `${DATA_DIR}/log.txt` a `${DATA_DIR}/call_logs/`
-- Protokoly požadavků: `<repo>/logs/...` (když `ENABLE_REQUEST_LOGS=true`)---
+- 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}/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
+
+---
 
 ## Circuit Breaker Issues
 
 ### Provider stuck in OPEN state
 
-Když je jistič poskytovatele OTEVŘENÝ, požadavky jsou blokovány, dokud nevyprší cooldown.
+When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
 
-**Oprava:**
+**Fix:**
 
-1. Přejděte na**Hlavní panel → Nastavení → Odolnost**
-2. Zkontrolujte kartu jističe pro dotčeného poskytovatele
-3. Kliknutím na**Resetovat vše**vymažete všechny jističe nebo počkejte, až vyprší cooldown
-4. Před resetováním ověřte, zda je poskytovatel skutečně dostupný### Provider keeps tripping the circuit breaker
+1. Go to **Dashboard → Settings → Resilience**
+2. Check the circuit breaker card for the affected provider
+3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
+4. Verify the provider is actually available before resetting
 
-Pokud poskytovatel opakovaně přejde do stavu OTEVŘENO:
+### Provider keeps tripping the circuit breaker
 
-1. Zkontrolujte**Dashboard → Health → Provider Health**pro vzor selhání
-2. Přejděte na**Nastavení → Odolnost → Profily poskytovatelů**a zvyšte práh selhání
-3. Zkontrolujte, zda poskytovatel nezměnil limity API nebo vyžaduje opětovné ověření
-4. Zkontrolujte telemetrii latence – vysoká latence může způsobit selhání na základě časového limitu---
+If a provider repeatedly enters OPEN state:
+
+1. Check **Dashboard → Health → Provider Health** for the failure pattern
+2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
+3. Check if the provider has changed API limits or requires re-authentication
+4. Review latency telemetry — high latency may cause timeout-based failures
+
+---
 
 ## Audio Transcription Issues
 
 ### "Unsupported model" error
 
-- Ujistěte se, že používáte správnou předponu: `deepgram/nova-3` nebo `assemblyai/best`
-  – Ověřte, že je poskytovatel připojen v**Dashboard → Providers**### Transcription returns empty or fails
+- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
+- Verify the provider is connected in **Dashboard → Providers**
 
-- Zkontrolujte podporované zvukové formáty: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
-- Ověřte, zda je velikost souboru v rámci limitů poskytovatele (obvykle < 25 MB)
-- Zkontrolujte platnost klíče API poskytovatele na kartě poskytovatele---
+### Transcription returns empty or fails
+
+- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Verify file size is within provider limits (typically < 25MB)
+- Check provider API key validity in the provider card
+
+---
 
 ## Translator Debugging
 
-K ladění problémů s překladem formátu použijte**Dashboard → Translator**:
+Use **Dashboard → Translator** to debug format translation issues:
 
-| Režim                | Kdy použít                                                                                                  |
-| -------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------ |
-| **Hřiště**           | Porovnejte vstupní/výstupní formáty vedle sebe — vložte neúspěšný požadavek, abyste viděli, jak se překládá |
-| **Chat Tester**      | Odesílejte živé zprávy a kontrolujte celý obsah požadavku/odpovědi včetně záhlaví                           |
-| **Zkušební stolice** | Spusťte dávkové testy napříč kombinacemi formátů, abyste zjistili, které překlady jsou poškozené            |
-| **Živý monitor**     | Sledujte tok požadavků v reálném čase, abyste zachytili občasné problémy s překladem                        | ### Common format issues |
+| Mode             | When to Use                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| **Playground**   | Compare input/output formats side by side — paste a failing request to see how it translates |
+| **Chat Tester**  | Send live messages and inspect the full request/response payload including headers           |
+| **Test Bench**   | Run batch tests across format combinations to find which translations are broken             |
+| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues                        |
 
--**Značky myšlení se nezobrazují**— Zkontrolujte, zda cílový poskytovatel podporuje myšlení a nastavení rozpočtu na myšlení -**Přerušení volání nástroje**— Některé překlady formátů mohou odstranit nepodporovaná pole; ověřit v režimu Playground -**Chybí systémová výzva**– Claude a Gemini zacházejí s výzvami systému odlišně; zkontrolovat překladový výstup
-–**SDK vrací surový řetězec místo objektu**– Opraveno ve verzi 1.1.0: sanitizér odpovědi nyní odstraňuje nestandardní pole (`x_groq`, `usage_breakdown` atd.), která způsobují selhání ověření OpenAI SDK Pydantic -**GLM/ERNIE odmítá `systémovou` roli**— Opraveno ve verzi 1.1.0: normalizátor rolí automaticky spojuje systémové zprávy do uživatelských zpráv pro nekompatibilní modely
+### Common format issues
 
-- Role**`vývojáře` nebyla rozpoznána**— Opraveno ve verzi 1.1.0: automaticky převedeno na `systém` pro poskytovatele mimo OpenAI -**`json_schema` nefunguje s Gemini**– Opraveno ve verzi 1.1.0: `response_format` je nyní převeden na Gemini `responseMimeType` + `responseSchema`---
+- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
+- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
+- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
+- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures
+- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
+- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers
+- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema`
+
+---
 
 ## Resilience Settings
 
 ### Auto rate-limit not triggering
 
-– Automatický limit sazby se vztahuje pouze na poskytovatele klíčů API (nikoli OAuth/předplatné)
+- Auto rate-limit only applies to API key providers (not OAuth/subscription)
+- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
+- Check if the provider returns `429` status codes or `Retry-After` headers
 
-- Ověřte, zda je v**Nastavení → Odolnost → Profily poskytovatelů**povolen automatický limit rychlosti
-- Zkontrolujte, zda poskytovatel vrací stavové kódy `429` nebo záhlaví `Retry-After`### Tuning exponential backoff
+### Tuning exponential backoff
 
-Profily poskytovatelů podporují tato nastavení:
+Provider profiles support these settings:
 
--**Základní zpoždění**— Počáteční doba čekání po prvním selhání (výchozí: 1s)
-–**Max. zpoždění**– Maximální doba čekání (výchozí: 30 s) -**Multiplikátor**– o kolik se má prodloužit zpoždění při po sobě jdoucím selhání (výchozí: 2x)### Anti-thundering herd
+- **Base delay** — Initial wait time after first failure (default: 1s)
+- **Max delay** — Maximum wait time cap (default: 30s)
+- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
 
-Když mnoho souběžných požadavků zasáhne poskytovatele s omezenou rychlostí, OmniRoute použije mutex + automatické omezování rychlosti k serializaci požadavků a prevenci kaskádových selhání. To je automatické pro poskytovatele klíčů API.---
+### Anti-thundering herd
+
+When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
+
+---
 
 ## Optional RAG / LLM failure taxonomy (16 problems)
 
-Někteří uživatelé OmniRoute umístí bránu před RAG nebo zásobníky agentů. V těchto nastaveních je běžné vidět podivný vzorec: OmniRoute vypadá zdravě (poskytovatelé jsou v pořádku, směrovací profily jsou v pořádku, žádná upozornění na omezení rychlosti), ale konečná odpověď je stále špatná.
+Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong.
 
-V praxi tyto incidenty obvykle pocházejí z navazujícího potrubí RAG, nikoli ze samotné brány.
+In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself.
 
-Pokud chcete sdílený slovník pro popis těchto selhání, můžete použít WFGY ProblemMap, externí textový zdroj licence MIT, který definuje šestnáct opakujících se vzorců selhání RAG / LLM. Na vysoké úrovni pokrývá:
+If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers:
 
-- posun vyhledávání a porušené hranice kontextu
-- prázdné nebo zastaralé indexy a vektorová úložiště
-- vkládání versus sémantický nesoulad
-- rychlé sestavení a problémy s kontextovým oknem
-- logický kolaps a příliš sebevědomé odpovědi
-- selhání koordinace dlouhých řetězců a agentů
-- multiagentní paměť a posun rolí
-- problémy s nasazením a objednáním bootstrapu
+- retrieval drift and broken context boundaries
+- empty or stale indexes and vector stores
+- embedding versus semantic mismatch
+- prompt assembly and context window issues
+- logic collapse and overconfident answers
+- long chain and agent coordination failures
+- multi agent memory and role drift
+- deployment and bootstrap ordering problems
 
-Myšlenka je jednoduchá:
+The idea is simple:
 
-1. Když prozkoumáte špatnou odpověď, zachyťte:
-   - uživatelský úkol a požadavek
-   - kombinace trasy nebo poskytovatele v OmniRoute
-   - jakýkoli kontext RAG použitý po proudu (načtené dokumenty, volání nástrojů atd.)
-2. Namapujte incident na jedno nebo dvě čísla WFGY ProblemMap (`č.1` … `č.16`).
-3. Uložte číslo na svůj vlastní řídicí panel, runbook nebo sledovač incidentů vedle protokolů OmniRoute.
-4. Použijte příslušnou stránku WFGY k rozhodnutí, zda potřebujete změnit strategii zásobníku RAG, retrieveru nebo směrování.
+1. When you investigate a bad response, capture:
+   - user task and request
+   - route or provider combo in OmniRoute
+   - any RAG context used downstream (retrieved documents, tool calls, etc)
+2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`).
+3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs.
+4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy.
 
-Celý text a konkrétní recepty jsou k dispozici zde (licence MIT, pouze text):
+Full text and concrete recipes live here (MIT license, text only):
 
-[SOUBOR WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
+[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
 
-Tuto sekci můžete ignorovat, pokud za OmniRoute nespouštíte RAG nebo agenty.---
+You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute.
+
+---
 
 ## Still Stuck?
 
-–**Problémy s GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -**Architecture**: Interní podrobnosti viz [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) -**Reference API**: Všechny koncové body viz [`docs/API_REFERENCE.md`](API_REFERENCE.md) -**Health Dashboard**: Zkontrolujte**Dashboard → Health**pro stav systému v reálném čase -**Translator**: K ladění problémů s formátem použijte**Dashboard → Translator**
+- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
+- **Translator**: Use **Dashboard → Translator** to debug format issues

docs/i18n/cs/docs/VM_DEPLOYMENT_GUIDE.md

@@ -100,7 +100,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/cs/llm.txt

@@ -0,0 +1,476 @@
+# OmniRoute (Čeština)
+
+🌐 **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.
+
+## Přehled
+
+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)
+
+### Bezpečnost
+- **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/da/docs/ARCHITECTURE.md

@@ -4,80 +4,91 @@
 
 ---
 
-_Sidst opdateret: 2026-03-28_## Executive Summary
+_Last updated: 2026-03-28_
 
-OmniRoute er en lokal AI-routinggateway og dashboard bygget på Next.js.
-Det giver et enkelt OpenAI-kompatibelt slutpunkt (`/v1/*`) og dirigerer trafik på tværs af flere upstream-udbydere med oversættelse, fallback, token-opdatering og brugssporing.
+## Executive Summary
 
-Kerneegenskaber:
+OmniRoute is a local AI routing gateway and dashboard built on Next.js.
+It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
 
-- OpenAI-kompatibel API-overflade til CLI/værktøjer (28 udbydere)
-- Anmodning/svar oversættelse på tværs af udbyderformater
-- Model combo fallback (multi-model sekvens)
-- Fallback på kontoniveau (multi-konto pr. udbyder)
-- Administration af forbindelse til OAuth + API-nøgleudbyder
-- Indlejringsgenerering via `/v1/embeddings` (6 udbydere, 9 modeller)
-- Billedgenerering via `/v1/images/generations` (4 udbydere, 9 modeller)
-- Tænk tag-parsing (`<think>...</think>`) for ræsonneringsmodeller
-- Response sanitization for streng OpenAI SDK-kompatibilitet
-- Rollenormalisering (udvikler→system, system→bruger) for kompatibilitet på tværs af udbydere
-- Struktureret outputkonvertering (json_schema → Gemini responseSchema)
-- Lokal persistens for udbydere, nøgler, aliaser, kombinationer, indstillinger, priser
-- Brug/omkostningssporing og anmodningslogning
-- Valgfri skysynkronisering til synkronisering af flere enheder/tilstande
-- IP-tilladelsesliste/blokeringsliste til API-adgangskontrol
-- Tænkende budgetstyring (passthrough/auto/custom/adaptive)
-- Global system prompt injektion
-- Sessionssporing og fingeraftryk
-- Forbedret prisbegrænsning pr. konto med udbyderspecifikke profiler
-- Circuit breaker mønster for udbyderens modstandsdygtighed
-- Anti-tordenbeskyttelse med mutex-låsning
-- Signaturbaseret anmodnings deduplikeringscache
-- Domænelag: modeltilgængelighed, omkostningsregler, fallback-politik, lockout-politik
-- Vedvarende domænetilstand (SQLite-gennemskrivningscache til fallbacks, budgetter, lockouts, strømafbrydere)
-- Politikmotor til centraliseret anmodningsevaluering (lockout → budget → fallback)
-- Anmod om telemetri med p50/p95/p99 latency aggregering
-- Korrelations-ID (X-Request-Id) til ende-til-ende-sporing
-- Overholdelsesrevisionslogning med opt-out pr. API-nøgle
-- Evalueringsramme for LLM kvalitetssikring
-- Resilience UI-dashboard med strømafbryderstatus i realtid
-- Modulære OAuth-udbydere (12 individuelle moduler under `src/lib/oauth/providers/`)
+Core capabilities:
 
-Primær runtime model:
+- OpenAI-compatible API surface for CLI/tools (28 providers)
+- Request/response translation across provider formats
+- Model combo fallback (multi-model sequence)
+- Account-level fallback (multi-account per provider)
+- OAuth + API-key provider connection management
+- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
+- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Think tag parsing (`<think>...</think>`) for reasoning models
+- Response sanitization for strict OpenAI SDK compatibility
+- Role normalization (developer→system, system→user) for cross-provider compatibility
+- Structured output conversion (json_schema → Gemini responseSchema)
+- Local persistence for providers, keys, aliases, combos, settings, pricing
+- Usage/cost tracking and request logging
+- Optional cloud sync for multi-device/state sync
+- IP allowlist/blocklist for API access control
+- Thinking budget management (passthrough/auto/custom/adaptive)
+- Global system prompt injection
+- Session tracking and fingerprinting
+- Per-account enhanced rate limiting with provider-specific profiles
+- Circuit breaker pattern for provider resilience
+- Anti-thundering herd protection with mutex locking
+- Signature-based request deduplication cache
+- Domain layer: model availability, cost rules, fallback policy, lockout policy
+- 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
+- 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/`)
 
-- Next.js app-ruter under `src/app/api/*` implementerer både dashboard-API'er og kompatibilitets-API'er
-- En delt SSE/routingkerne i `src/sse/*` + `open-sse/*` håndterer udbyderens udførelse, oversættelse, streaming, fallback og brug## Scope and Boundaries
+Primary runtime model:
+
+- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
+- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
+
+## Scope and Boundaries
 
 ### In Scope
 
-- Lokal gateway køretid
-- Dashboard management API'er
-- Udbydergodkendelse og tokenopdatering
-- Anmod om oversættelse og SSE-streaming
-- Lokal stat + vedvarende brug
-- Valgfri skysynkroniseringsorkestrering### Out of Scope
+- Local gateway runtime
+- Dashboard management APIs
+- Provider authentication and token refresh
+- Request translation and SSE streaming
+- Local state + usage persistence
+- Optional cloud sync orchestration
 
-- Implementering af skytjenester bag `NEXT_PUBLIC_CLOUD_URL`
-- Udbyder SLA/kontrolplan uden for lokal proces
-- Eksterne CLI-binære filer selv (Claude CLI, Codex CLI osv.)## Dashboard Surface (Current)
+### Out of Scope
 
-Hovedsider under `src/app/(dashboard)/dashboard/`:
+- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
+- Provider SLA/control plane outside local process
+- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
 
-- `/dashboard` — hurtig start + udbyderoversigt
-- `/dashboard/endpoint` — endpoint proxy + MCP + A2A + API endpoint faner
-- `/dashboard/providers` — udbyderforbindelser og legitimationsoplysninger
-- `/dashboard/combos` — kombinationsstrategier, skabeloner, modelrutingsregler
-- `/dashboard/costs` — prissammenlægning og prissynlighed
-- `/dashboard/analytics` — brugsanalyse og -evalueringer
-- `/dashboard/limits` — kvote-/satskontrol
+## Dashboard Surface (Current)
+
+Main pages under `src/app/(dashboard)/dashboard/`:
+
+- `/dashboard` — quick start + provider overview
+- `/dashboard/endpoint` — endpoint proxy + MCP + A2A + API endpoint tabs
+- `/dashboard/providers` — provider connections and credentials
+- `/dashboard/combos` — combo strategies, templates, model routing rules
+- `/dashboard/costs` — cost aggregation and pricing visibility
+- `/dashboard/analytics` — usage analytics and evaluations
+- `/dashboard/limits` — quota/rate controls
 - `/dashboard/cli-tools` — CLI onboarding, runtime detection, config generation
-- `/dashboard/agents` — opdagede ACP-agenter + tilpasset agentregistrering
-- `/dashboard/media` — billed-/video-/musiklegeplads
-- `/dashboard/search-tools` — test af søgeudbydere og historik
-- `/dashboard/health` — oppetid, strømafbrydere, hastighedsgrænser
+- `/dashboard/agents` — detected ACP agents + custom agent registration
+- `/dashboard/media` — image/video/music playground
+- `/dashboard/search-tools` — search provider testing and history
+- `/dashboard/health` — uptime, circuit breakers, rate limits
 - `/dashboard/logs` — request/proxy/audit/console logs
-- `/dashboard/indstillinger` — systemindstillinger faner (generelt, routing, kombinationsstandarder osv.)
-- `/dashboard/api-manager` — API-nøglelivscyklus og modeltilladelser## High-Level System Context
+- `/dashboard/settings` — system settings tabs (general, routing, combo defaults, etc.)
+- `/dashboard/api-manager` — API key lifecycle and model permissions
+
+## High-Level System Context
 
 ```mermaid
 flowchart LR
@@ -129,139 +140,151 @@ flowchart LR
 
 ## 1) API and Routing Layer (Next.js App Routes)
 
-Hovedmapper:
+Main directories:
 
-- `src/app/api/v1/*` og `src/app/api/v1beta/*` til kompatibilitets-API'er
-- `src/app/api/*` til administrations-/konfigurations-API'er
-- Næste omskrivninger i `next.config.mjs` map `/v1/*` til `/api/v1/*`
+- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
+- `src/app/api/*` for management/configuration APIs
+- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
 
-Vigtige kompatibilitetsruter:
+Important compatibility routes:
 
 - `src/app/api/v1/chat/completions/route.ts`
 - `src/app/api/v1/messages/route.ts`
 - `src/app/api/v1/responses/route.ts`
-- `src/app/api/v1/models/route.ts` – inkluderer brugerdefinerede modeller med `custom: true`
-- `src/app/api/v1/embeddings/route.ts` — indlejringsgenerering (6 udbydere)
-- `src/app/api/v1/images/generations/route.ts` — billedgenerering (4+ udbydere inkl. Antigravity/Nebius)
+- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`
+- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)
+- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)
 - `src/app/api/v1/messages/count_tokens/route.ts`
-- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedikeret chat pr. udbyder
-- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedikerede indlejringer pr. udbyder
-- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedikerede billeder pr. udbyder
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images
 - `src/app/api/v1beta/models/route.ts`
 - `src/app/api/v1beta/models/[...path]/route.ts`
 
-Ledelsesdomæner:
+Management domains:
 
-- Godkendelse/indstillinger: `src/app/api/auth/*`, `src/app/api/settings/*`
-- Udbydere/forbindelser: `src/app/api/providers*`
-- Provider noder: `src/app/api/provider-nodes*`
-- Brugerdefinerede modeller: `src/app/api/provider-models` (GET/POST/DELETE)
-- Modelkatalog: `src/app/api/models/route.ts` (GET)
+- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
+- Providers/connections: `src/app/api/providers*`
+- Provider nodes: `src/app/api/provider-nodes*`
+- Custom models: `src/app/api/provider-models` (GET/POST/DELETE)
+- Model catalog: `src/app/api/models/route.ts` (GET)
 - Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
 - OAuth: `src/app/api/oauth/*`
 - Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
-- Brug: `src/app/api/usage/*`
+- Usage: `src/app/api/usage/*`
 - Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
-- CLI-værktøjshjælpere: `src/app/api/cli-tools/*`
-- IP-filter: `src/app/api/settings/ip-filter` (GET/PUT)
-- Tænkebudget: `src/app/api/settings/thinking-budget` (GET/PUT)
-- Systemprompt: `src/app/api/settings/system-prompt` (GET/PUT)
-- Sessioner: `src/app/api/sessions` (GET)
-- Satsgrænser: `src/app/api/rate-limits` (GET)
-- Resiliens: `src/app/api/resilience` (GET/PATCH) — udbyderprofiler, afbryder, hastighedsgrænsetilstand
-- Resilience reset: `src/app/api/resilience/reset` (POST) — nulstil breakers + cooldowns
-- Cachestatistik: `src/app/api/cache/stats` (GET/DELETE)
-- Modeltilgængelighed: `src/app/api/models/availability` (GET/POST)
-- Telemetri: `src/app/api/telemetry/summary` (GET)
+- CLI tooling helpers: `src/app/api/cli-tools/*`
+- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)
+- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)
+- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)
+- Sessions: `src/app/api/sessions` (GET)
+- Rate limits: `src/app/api/rate-limits` (GET)
+- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns
+- Cache stats: `src/app/api/cache/stats` (GET/DELETE)
+- Model availability: `src/app/api/models/availability` (GET/POST)
+- Telemetry: `src/app/api/telemetry/summary` (GET)
 - Budget: `src/app/api/usage/budget` (GET/POST)
-- Fallback-kæder: `src/app/api/fallback/chains` (GET/POST/DELETE)
-- Overholdelsesrevision: `src/app/api/compliance/audit-log` (GET)
+- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET)
 - Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
-- Politikker: `src/app/api/policies` (GET/POST)## 2) SSE + Translation Core
+- Policies: `src/app/api/policies` (GET/POST)
 
-Hovedflowmoduler:
+## 2) SSE + Translation Core
 
-- Indtastning: `src/sse/handlers/chat.ts`
-- Kerneorkestrering: `open-sse/handlers/chatCore.ts`
-- Udbyder eksekveringsadaptere: `open-sse/executors/*`
-- Formatdetektion/udbyderkonfiguration: `open-sse/services/provider.ts`
+Main flow modules:
+
+- Entry: `src/sse/handlers/chat.ts`
+- Core orchestration: `open-sse/handlers/chatCore.ts`
+- Provider execution adapters: `open-sse/executors/*`
+- Format detection/provider config: `open-sse/services/provider.ts`
 - Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
-- Konto fallback logik: `open-sse/services/accountFallback.ts`
-- Oversættelsesregister: `open-sse/translator/index.ts`
-- Stream transformationer: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
-- Brugsudtrækning/normalisering: `open-sse/utils/usageTracking.ts`
-- Tænk tag-parser: `open-sse/utils/thinkTagParser.ts`
-- Indlejringshåndtering: `open-sse/handlers/embeddings.ts`
-- Indlejringsudbyderregistrering: `open-sse/config/embeddingRegistry.ts`
-- Billedgenereringshåndtering: `open-sse/handlers/imageGeneration.ts`
-- Billedudbyderregistrering: `open-sse/config/imageRegistry.ts`
-- Reaktionssanering: `open-sse/handlers/responseSanitizer.ts`
-- Rollenormalisering: `open-sse/services/roleNormalizer.ts`
+- Account fallback logic: `open-sse/services/accountFallback.ts`
+- Translation registry: `open-sse/translator/index.ts`
+- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
+- Think tag parser: `open-sse/utils/thinkTagParser.ts`
+- Embedding handler: `open-sse/handlers/embeddings.ts`
+- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
+- Image generation handler: `open-sse/handlers/imageGeneration.ts`
+- Image provider registry: `open-sse/config/imageRegistry.ts`
+- Response sanitization: `open-sse/handlers/responseSanitizer.ts`
+- Role normalization: `open-sse/services/roleNormalizer.ts`
 
-Tjenester (forretningslogik):
+Services (business logic):
 
-- Kontovalg/scoring: `open-sse/services/accountSelector.ts`
+- Account selection/scoring: `open-sse/services/accountSelector.ts`
 - Context lifecycle management: `open-sse/services/contextManager.ts`
-- Håndhævelse af IP-filter: `open-sse/services/ipFilter.ts`
-- Sessionssporing: `open-sse/services/sessionManager.ts`
-- Anmod om deduplikering: `open-sse/services/signatureCache.ts`
-- Injektion af systemprompt: `open-sse/services/systemPrompt.ts`
-- Tænkende budgetstyring: `open-sse/services/thinkingBudget.ts`
+- IP filter enforcement: `open-sse/services/ipFilter.ts`
+- Session tracking: `open-sse/services/sessionManager.ts`
+- Request deduplication: `open-sse/services/signatureCache.ts`
+- System prompt injection: `open-sse/services/systemPrompt.ts`
+- Thinking budget management: `open-sse/services/thinkingBudget.ts`
 - Wildcard model routing: `open-sse/services/wildcardRouter.ts`
-- Satsgrænsestyring: `open-sse/services/rateLimitManager.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
 
-Domænelagsmoduler:
+Domain layer modules:
 
-- Modeltilgængelighed: `src/lib/domain/modelAvailability.ts`
-- Omkostningsregler/budgetter: `src/lib/domain/costRules.ts`
-- Fallback-politik: `src/lib/domain/fallbackPolicy.ts`
+- Model availability: `src/lib/domain/modelAvailability.ts`
+- Cost rules/budgets: `src/lib/domain/costRules.ts`
+- Fallback policy: `src/lib/domain/fallbackPolicy.ts`
 - Combo resolver: `src/lib/domain/comboResolver.ts`
-- Lockout-politik: `src/lib/domain/lockoutPolicy.ts`
-- Politikmotor: `src/domain/policyEngine.ts` — centraliseret lockout → budget → fallback-evaluering
-- Fejlkodekatalog: `src/lib/domain/errorCodes.ts`
-- Anmodnings-id: `src/lib/domain/requestId.ts`
-- Hente timeout: `src/lib/domain/fetchTimeout.ts`
-- Anmod om telemetri: `src/lib/domain/requestTelemetry.ts`
-- Overholdelse/revision: `src/lib/domain/compliance/index.ts`
+- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
+- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
+- Error codes catalog: `src/lib/domain/errorCodes.ts`
+- Request ID: `src/lib/domain/requestId.ts`
+- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
+- Request telemetry: `src/lib/domain/requestTelemetry.ts`
+- Compliance/audit: `src/lib/domain/compliance/index.ts`
 - Eval runner: `src/lib/domain/evalRunner.ts`
-- Vedvarende domænetilstand: `src/lib/db/domainState.ts` — SQLite CRUD til reservekæder, budgetter, omkostningshistorik, lockouttilstand, strømafbrydere
+- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
 
-OAuth-udbydermoduler (12 individuelle filer under `src/lib/oauth/providers/`):
+OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
-- Registerindeks: `src/lib/oauth/providers/index.ts`
-- Individuelle udbydere: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `qoder.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts.line`, `t.`s.`s.`s.`
-- Tyndt omslag: `src/lib/oauth/providers.ts` — reeksporterer fra individuelle moduler## 3) Persistence Layer
+- 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`
+- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
-Primær tilstand DB (SQLite):
+## 3) Persistence Layer
 
-- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrationer, WAL)
-- Re-eksport facade: `src/lib/localDb.ts` (tyndt kompatibilitetslag for opkaldere)
-- fil: `${DATA_DIR}/storage.sqlite` (eller `$XDG_CONFIG_HOME/omniroute/storage.sqlite` når indstillet, ellers `~/.omniroute/storage.sqlite`)
-- enheder (tabeller + KV-navnerum): providerConnections, providerNodes, modelAliaser, combos, apiKeys, indstillinger, prissætning,**customModels**,**proxyConfig**,**ipFilter**,**thinkingBudget**,**systemPrompt**
+Primary state DB (SQLite):
 
-Brugsvedholdenhed:
+- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL)
+- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers)
+- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`)
+- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
 
-- facade: `src/lib/usageDb.ts` (dekomponerede moduler i `src/lib/usage/*`)
-- SQLite-tabeller i `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
-- valgfrie filartefakter forbliver for kompatibilitet/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
-- Ældre JSON-filer migreres til SQLite ved opstartsmigreringer, når de er til stede
+Usage persistence:
+
+- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`)
+- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
+- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
+- legacy JSON files are migrated to SQLite by startup migrations when present
 
 Domain State DB (SQLite):
 
-- `src/lib/db/domainState.ts` — CRUD-operationer for domænetilstand
-- Tabeller (oprettet i `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
-- Gennemskrivningscachemønster: Kort i hukommelsen er autoritative under kørsel; mutationer skrives synkront til SQLite; tilstand gendannes fra DB ved koldstart## 4) Auth + Security Surfaces
+- `src/lib/db/domainState.ts` — CRUD operations for domain state
+- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
+- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
+
+## 4) Auth + Security Surfaces
 
 - Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
-- Generering/bekræftelse af API-nøgler: `src/shared/utils/apiKey.ts`
-- Udbyderhemmeligheder vedblev i 'providerConnections'-poster
-- Udgående proxy-understøttelse via `open-sse/utils/proxyFetch.ts` (env vars) og `open-sse/utils/networkProxy.ts` (konfigurerbar pr. udbyder eller global)## 5) Cloud Sync
+- API key generation/verification: `src/shared/utils/apiKey.ts`
+- Provider secrets persisted in `providerConnections` entries
+- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
+
+## 5) Cloud Sync
 
 - Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
-- Periodisk opgave: `src/shared/services/cloudSyncScheduler.ts`
-- Periodisk opgave: `src/shared/services/modelSyncScheduler.ts`
-- Styr rute: `src/app/api/sync/cloud/route.ts`## Request Lifecycle (`/v1/chat/completions`)
+- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Periodic task: `src/shared/services/modelSyncScheduler.ts`
+- Control route: `src/app/api/sync/cloud/route.ts`
+
+## Request Lifecycle (`/v1/chat/completions`)
 
 ```mermaid
 sequenceDiagram
@@ -338,7 +361,9 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-Fallback-beslutninger er drevet af `open-sse/services/accountFallback.ts` ved hjælp af statuskoder og fejlmeddelelsesheuristik. Combo-routing tilføjer en ekstra beskyttelse: udbyder-omfattede 400'er, såsom upstream-indholdsblokering og rollevalideringsfejl, behandles som model-lokale fejl, så senere combo-mål kan stadig køre.## OAuth Onboarding and Token Refresh Lifecycle
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run.
+
+## OAuth Onboarding and Token Refresh Lifecycle
 
 ```mermaid
 sequenceDiagram
@@ -368,7 +393,9 @@ sequenceDiagram
     Test-->>UI: validation result
 ```
 
-Opdatering under live trafik udføres inde i `open-sse/handlers/chatCore.ts` via eksekveren `refreshCredentials()`.## Cloud Sync Lifecycle (Enable / Sync / Disable)
+Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
+
+## Cloud Sync Lifecycle (Enable / Sync / Disable)
 
 ```mermaid
 sequenceDiagram
@@ -400,7 +427,9 @@ sequenceDiagram
     Sync-->>UI: disabled
 ```
 
-Periodisk synkronisering udløses af "CloudSyncScheduler", når skyen er aktiveret.## Data Model and Storage Map
+Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
+
+## Data Model and Storage Map
 
 ```mermaid
 erDiagram
@@ -501,12 +530,14 @@ erDiagram
     }
 ```
 
-Fysiske lagerfiler:
+Physical storage files:
 
-- primær runtime DB: `${DATA_DIR}/storage.sqlite`
-- anmode om log linjer: `${DATA_DIR}/log.txt` (compat/debug artefakt)
-- strukturerede opkaldsdataarkiver: `${DATA_DIR}/call_logs/`
-- valgfri oversætter/anmodningsfejlfindingssessioner: `<repo>/logs/...`## Deployment Topology
+- primary runtime DB: `${DATA_DIR}/storage.sqlite`
+- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact)
+- structured call payload archives: `${DATA_DIR}/call_logs/`
+- optional translator/request debug sessions: `<repo>/logs/...`
+
+## Deployment Topology
 
 ```mermaid
 flowchart LR
@@ -541,205 +572,248 @@ flowchart LR
 
 ### Route and API Modules
 
-- `src/app/api/v1/*`, `src/app/api/v1beta/*`: kompatibilitets-API'er
-- `src/app/api/v1/providers/[provider]/*`: dedikerede ruter pr. udbyder (chat, indlejringer, billeder)
-- `src/app/api/providers*`: udbyder CRUD, validering, test
-- `src/app/api/provider-nodes*`: tilpasset kompatibel nodestyring
-- `src/app/api/provider-models`: Custom model management (CRUD)
-- `src/app/api/models/route.ts`: modelkatalog API (aliaser + tilpassede modeller)
-- `src/app/api/oauth/*`: OAuth/enhedskode-flow
-- `src/app/api/keys*`: lokal API-nøglelivscyklus
-- `src/app/api/models/alias`: aliashåndtering
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
+- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
+- `src/app/api/providers*`: provider CRUD, validation, testing
+- `src/app/api/provider-nodes*`: custom compatible node management
+- `src/app/api/provider-models`: custom model management (CRUD)
+- `src/app/api/models/route.ts`: model catalog API (aliases + custom models)
+- `src/app/api/oauth/*`: OAuth/device-code flows
+- `src/app/api/keys*`: local API key lifecycle
+- `src/app/api/models/alias`: alias management
 - `src/app/api/combos*`: fallback combo management
-- `src/app/api/pricing`: pristilsidesættelser til omkostningsberegning
-- `src/app/api/settings/proxy`: proxy-konfiguration (GET/PUT/DELETE)
-- `src/app/api/settings/proxy/test`: test af udgående proxyforbindelse (POST)
-- `src/app/api/usage/*`: brugs- og log-API'er
-- `src/app/api/sync/*` + `src/app/api/cloud/*`: skysynkronisering og skyvendte hjælpere
-- `src/app/api/cli-tools/*`: lokale CLI-konfigurationsskrivere/checkers
-- `src/app/api/settings/ip-filter`: IP-tilladelsesliste/blokeringsliste (GET/PUT)
-- `src/app/api/settings/thinking-budget`: Tænketoken-budgetkonfiguration (GET/PUT)
-- `src/app/api/settings/system-prompt`: global systemprompt (GET/PUT)
-- `src/app/api/sessions`: aktiv sessionsfortegnelse (GET)
-- `src/app/api/rate-limits`: rategrænsestatus pr. konto (GET)### Routing and Execution Core
+- `src/app/api/pricing`: pricing overrides for cost calculation
+- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
+- `src/app/api/usage/*`: usage and logs APIs
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
+- `src/app/api/cli-tools/*`: local CLI config writers/checkers
+- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
+- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
+- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
+- `src/app/api/sessions`: active session listing (GET)
+- `src/app/api/rate-limits`: per-account rate limit status (GET)
 
-- `src/sse/handlers/chat.ts`: anmodning om parse, kombinationshåndtering, kontovalgsløkke
-- `open-sse/handlers/chatCore.ts`: oversættelse, eksekutorafsendelse, genforsøg/opdateringshåndtering, stream-opsætning
-- `open-sse/executors/*`: udbyderspecifik netværks- og formatadfærd### Translation Registry and Format Converters
+### Routing and Execution Core
 
-- `open-sse/translator/index.ts`: oversætterregister og orkestrering
-- Anmod om oversættere: `open-sse/translator/request/*`
-- Svaroversættere: `open-sse/translator/response/*`
-- Formatkonstanter: `open-sse/translator/formats.ts`### Persistence
+- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
+- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
+- `open-sse/executors/*`: provider-specific network and format behavior
 
-- `src/lib/db/*`: persistent config/state og domæne persistens på SQLite
-- `src/lib/localDb.ts`: re-eksport af kompatibilitet til DB-moduler
-- `src/lib/usageDb.ts`: brugshistorik/opkaldslogs facade oven på SQLite-tabeller## Provider Executor Coverage (Strategy Pattern)
+### Translation Registry and Format Converters
 
-Hver udbyder har en specialiseret executor, der udvider `BaseExecutor` (i `open-sse/executors/base.ts`), som giver URL-opbygning, header-konstruktion, genforsøg med eksponentiel backoff, credential refresh hooks og `execute()`-orkestreringsmetoden.
+- `open-sse/translator/index.ts`: translator registry and orchestration
+- Request translators: `open-sse/translator/request/*`
+- Response translators: `open-sse/translator/response/*`
+- Format constants: `open-sse/translator/formats.ts`
 
-| Eksekutør             | Udbyder(e)                                                                                                                                                    | Særlig håndtering                                                       |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| `DefaultExecutor`     | OpenAI, Claude, Gemini, Qwen, Qoder, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fyrværkeri, Cerebras, Cohere, NVIDIA | Dynamisk URL/header-konfiguration pr. udbyder                           |
-| `AntigravityExecutor` | Google Antigravity                                                                                                                                            | Brugerdefinerede projekt-/sessions-id'er, forsøg igen - efter parsing   |
-| `CodexExecutor`       | OpenAI Codex                                                                                                                                                  | Injicerer systeminstruktioner, fremtvinger ræsonnement indsats          |
-| `CursorExecutor`      | Markør IDE                                                                                                                                                    | ConnectRPC-protokol, Protobuf-kodning, anmodningssignering via checksum |
-| `GithubExecutor`      | GitHub Copilot                                                                                                                                                | Copilot token opdatering, VSCode-mimicing headers                       |
-| `KiroExecutor`        | AWS CodeWhisperer/Kiro                                                                                                                                        | AWS EventStream binært format → SSE-konvertering                        |
-| `GeminiCLIEexecutor`  | Gemini CLI                                                                                                                                                    | Opdateringscyklus for Google OAuth-token                                |
+### Persistence
 
-Alle andre udbydere (inklusive brugerdefinerede kompatible noder) bruger `DefaultExecutor`.## Provider Compatibility Matrix
+- `src/lib/db/*`: persistent config/state and domain persistence on SQLite
+- `src/lib/localDb.ts`: compatibility re-export for DB modules
+- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables
 
-| Udbyder          | Format          | Auth                  | Stream           | Ikke-stream | Token Opdater | Brug API             |
-| ---------------- | --------------- | --------------------- | ---------------- | ----------- | ------------- | -------------------- | ------------------------------ |
-| Claude           | claude          | API-nøgle / OAuth     | ✅               | ✅          | ✅            | ⚠️ Kun administrator |
-| Tvillingerne     | gemini          | API-nøgle / OAuth     | ✅               | ✅          | ✅            | ⚠️ Cloud Console     |
-| Gemini CLI       | gemini-cli      | OAuth                 | ✅               | ✅          | ✅            | ⚠️ Cloud Console     |
-| Antigravitation  | antityngdekraft | OAuth                 | ✅               | ✅          | ✅            | ✅ Fuld kvote API    |
-| OpenAI           | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Codex            | openai-svar     | OAuth                 | ✅ tvunget       | ❌          | ✅            | ✅ Satsgrænser       |
-| GitHub Copilot   | åbne            | OAuth + Copilot Token | ✅               | ✅          | ✅            | ✅ Kvote snapshots   |
-| Markør           | markør          | Tilpasset kontrolsum  | ✅               | ✅          | ❌            | ❌                   |
-| Kiro             | kiro            | AWS SSO OIDC          | ✅ (EventStream) | ❌          | ✅            | ✅ Brugsgrænser      |
-| Qwen             | åbne            | OAuth                 | ✅               | ✅          | ✅            | ⚠️ Efter anmodning   |
-| Qoder            | åbne            | OAuth (Grundlæggende) | ✅               | ✅          | ✅            | ⚠️ Efter anmodning   |
-| OpenRouter       | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| GLM/Kimi/MiniMax | claude          | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| DeepSeek         | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Groq             | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| xAI (Grok)       | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Mistral          | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Forvirring       | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Sammen AI        | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Fyrværkeri AI    | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Cerebras         | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| Sammenhæng       | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   |
-| NVIDIA NIM       | åbne            | API-nøgle             | ✅               | ✅          | ❌            | ❌                   | ## Format Translation Coverage |
+## Provider Executor Coverage (Strategy Pattern)
 
-Detekterede kildeformater omfatter:
+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.
 
-- 'openai'
-- `openai-svar`
-- `Claude`
-- 'tvilling'
+| 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                                     |
 
-Målformater omfatter:
+All other providers (including custom compatible nodes) use the `DefaultExecutor`.
 
-- OpenAI chat/svar
+## Provider Compatibility Matrix
+
+| Provider         | Format           | Auth                  | Stream           | Non-Stream | Token Refresh | Usage API          |
+| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
+| Claude           | claude           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Admin only      |
+| Gemini           | gemini           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Gemini CLI       | gemini-cli       | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Antigravity      | antigravity      | OAuth                 | ✅               | ✅         | ✅            | ✅ Full quota API  |
+| OpenAI           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Codex            | openai-responses | OAuth                 | ✅ forced        | ❌         | ✅            | ✅ Rate limits     |
+| GitHub Copilot   | openai           | OAuth + Copilot Token | ✅               | ✅         | ✅            | ✅ Quota snapshots |
+| Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
+| Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
+| Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Qoder            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Groq             | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| xAI (Grok)       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Mistral          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Perplexity       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Together AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Fireworks AI     | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+
+## Format Translation Coverage
+
+Detected source formats include:
+
+- `openai`
+- `openai-responses`
+- `claude`
+- `gemini`
+
+Target formats include:
+
+- OpenAI chat/Responses
 - Claude
-- Gemini/Gemini-CLI/Antigravity kuvert
+- Gemini/Gemini-CLI/Antigravity envelope
 - Kiro
-- Markør
+- Cursor
 
-Oversættelser bruger**OpenAI som hub-format**- alle konverteringer går gennem OpenAI som mellemliggende:```
+Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
+
+```
 Source Format → OpenAI (hub) → Target Format
+```
 
-````
+Translations are selected dynamically based on source payload shape and provider target format.
 
-Oversættelser vælges dynamisk baseret på kildens nyttelastform og udbyderens målformat.
+Additional processing layers in the translation pipeline:
 
-Yderligere behandlingslag i oversættelsespipelinen:
+- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance
+- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)
+- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field
+- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`
 
--**Responssanering**— Fjerner ikke-standardfelter fra OpenAI-formatsvar (både streaming og ikke-streaming) for at sikre streng SDK-overholdelse
--**Rollenormalisering**— Konverterer `udvikler` → `system` til ikke-OpenAI-mål; fletter `system` → `bruger` for modeller, der afviser systemrollen (GLM, ERNIE)
--**Tænk tag-udtrækning**— Parser "<think>...</think>"-blokke fra indhold til feltet "reasoning_content"
--**Structured output**— Konverterer OpenAI `response_format.json_schema` til Geminis `responseMimeType` + `responseSchema`## Supported API Endpoints
+## Supported API Endpoints
 
-| Slutpunkt | Format | Behandler |
-| -------------------------------------------------- | ------------------ | -------------------------------------------------------------------------- |
-| `POST /v1/chat/afslutninger` | OpenAI Chat | `src/sse/handlers/chat.ts` |
-| `POST /v1/meddelelser` | Claude Beskeder | Samme handler (auto-detekteret) |
-| `POST /v1/svar` | OpenAI-svar | `open-sse/handlers/responsesHandler.ts` |
-| `POST /v1/indlejringer` | OpenAI-indlejringer | `open-sse/handlers/embeddings.ts` |
-| `GET /v1/indlejringer` | Modelliste | API-rute |
-| `POST /v1/billeder/generationer` | OpenAI Billeder | `open-sse/handlers/imageGeneration.ts` |
-| `GET /v1/billeder/generationer` | Modelliste | API-rute |
-| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedikeret per udbyder med modelvalidering |
-| `POST /v1/providers/{provider}/embeddings` | OpenAI-indlejringer | Dedikeret per udbyder med modelvalidering |
-| `POST /v1/providers/{provider}/images/generations` | OpenAI Billeder | Dedikeret per udbyder med modelvalidering |
-| `POST /v1/messages/count_tokens` | Claude Token Count | API-rute |
-| `GET /v1/modeller` | OpenAI Models liste | API-rute (chat + indlejring + billede + brugerdefinerede modeller) |
-| `GET /api/models/catalog` | Katalog | Alle modeller grupperet efter udbyder + type |
-| `POST /v1beta/models/*:streamGenerateContent` | Tvilling hjemmehørende | API-rute |
-| `GET/PUT/DELETE /api/indstillinger/proxy` | Proxy-konfiguration | Netværk proxy-konfiguration |
-| `POST /api/settings/proxy/test` | Proxy-forbindelse | Proxy-sundheds-/forbindelsestestslutpunkt |
-| `GET/POST/DELETE /api/provider-models` | Udbyder modeller | Udbydermodelmetadata understøtter tilpassede og administrerede tilgængelige modeller |## Bypass Handler
+| Endpoint                                           | Format             | Handler                                                             |
+| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------- |
+| `POST /v1/chat/completions`                        | OpenAI Chat        | `src/sse/handlers/chat.ts`                                          |
+| `POST /v1/messages`                                | Claude Messages    | Same handler (auto-detected)                                        |
+| `POST /v1/responses`                               | OpenAI Responses   | `open-sse/handlers/responsesHandler.ts`                             |
+| `POST /v1/embeddings`                              | OpenAI Embeddings  | `open-sse/handlers/embeddings.ts`                                   |
+| `GET /v1/embeddings`                               | Model listing      | API route                                                           |
+| `POST /v1/images/generations`                      | OpenAI Images      | `open-sse/handlers/imageGeneration.ts`                              |
+| `GET /v1/images/generations`                       | Model listing      | API route                                                           |
+| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat        | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings  | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/images/generations` | OpenAI Images      | Dedicated per-provider with model validation                        |
+| `POST /v1/messages/count_tokens`                   | Claude Token Count | API route                                                           |
+| `GET /v1/models`                                   | OpenAI Models list | API route (chat + embedding + image + custom models)                |
+| `GET /api/models/catalog`                          | Catalog            | All models grouped by provider + type                               |
+| `POST /v1beta/models/*:streamGenerateContent`      | Gemini native      | API route                                                           |
+| `GET/PUT/DELETE /api/settings/proxy`               | Proxy Config       | Network proxy configuration                                         |
+| `POST /api/settings/proxy/test`                    | Proxy Connectivity | Proxy health/connectivity test endpoint                             |
+| `GET/POST/DELETE /api/provider-models`             | Provider Models    | Provider model metadata backing custom and managed available models |
 
-Bypass-handleren (`open-sse/utils/bypassHandler.ts`) opsnapper kendte "throwaway"-anmodninger fra Claude CLI - opvarmningsping, titeludtræk og tokentællinger - og returnerer et**falsk svar**uden at forbruge upstream-udbydertokens. Dette udløses kun, når `User-Agent` indeholder `claude-cli`.## Request Logger Pipeline
+## Bypass Handler
 
-Anmodningsloggeren (`open-sse/utils/requestLogger.ts`) giver en 7-trins debug-logningspipeline, deaktiveret som standard, aktiveret via `ENABLE_REQUEST_LOGS=true`:```
-1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json
-→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt
-````
+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`.
 
-Filer skrives til `<repo>/logs/<session>/` for hver anmodningssession.## Failure Modes and Resilience
+## Request Logging and Artifacts
+
+The older file-based request logger (`open-sse/utils/requestLogger.ts`) is retained only for
+legacy compatibility. The current runtime contract uses:
+
+- `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
 
-- Nedkøling af udbyderkonto på forbigående/rate/godkendelsesfejl
-- konto fallback før mislykket anmodning
-- combo model fallback, når den nuværende model/udbydersti er udtømt## 2) Token Expiry
+- provider account cooldown on transient/rate/auth errors
+- account fallback before failing request
+- combo model fallback when current model/provider path is exhausted
 
-- Forhåndstjek og opdater med genforsøg for udbydere, der kan opdateres
-- 401/403 forsøg igen efter opdateringsforsøg i kernestien## 3) Stream Safety
+## 2) Token Expiry
 
-- afbrydelsesbevidst streamcontroller
-- oversættelsesstrøm med slut-af-stream-skyl og `[DONE]`-håndtering
-- forbrugsestimeret fallback, når udbyderens brugsmetadata mangler## 4) Cloud Sync Degradation
+- pre-check and refresh with retry for refreshable providers
+- 401/403 retry after refresh attempt in core path
 
-- Synkroniseringsfejl dukker op, men lokal kørsel fortsætter
-- Scheduler har logik, der kan genforsøge, men periodisk udførelse kalder i øjeblikket enkelt-forsøgssynkronisering som standard## 5) Data Integrity
+## 3) Stream Safety
 
-- SQLite-skemamigreringer og auto-opgraderingshooks ved opstart
-- ældre JSON → SQLite-migreringskompatibilitetssti## Observability and Operational Signals
+- disconnect-aware stream controller
+- translation stream with end-of-stream flush and `[DONE]` handling
+- usage estimation fallback when provider usage metadata is missing
 
-Kilder til synlighed ved kørsel:
+## 4) Cloud Sync Degradation
 
-- konsollogfiler fra `src/sse/utils/logger.ts`
-- brugsaggregater pr. anmodning i SQLite (`usage_history`, `call_logs`, `proxy_logs`)
-- fire-trins detaljeret nyttelastfangst i SQLite (`request_detail_logs`), når `settings.detailed_logs_enabled=true`
-- statuslog for tekstanmodning i `log.txt` (valgfrit/kompatibelt)
-- valgfri dybe anmodnings-/oversættelseslogfiler under `logs/` når `ENABLE_REQUEST_LOGS=true`
-- dashboardbrugsslutpunkter (`/api/usage/*`) for brugergrænsefladeforbrug
+- sync errors are surfaced but local runtime continues
+- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
 
-Detaljeret anmodning om nyttelastfangst gemmer op til fire JSON-nyttelasttrin pr. dirigeret opkald:
+## 5) Data Integrity
 
-- rå anmodning modtaget fra klienten
-- oversat anmodning faktisk sendt opstrøms
-- Providersvar rekonstrueret som JSON; streamede svar komprimeres til den endelige oversigt plus stream metadata
-- endelig kundesvar returneret af OmniRoute; streamede svar gemmes i den samme kompakte oversigtsform## Security-Sensitive Boundaries
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
-- JWT-hemmelighed (`JWT_SECRET`) sikrer bekræftelse/signering af dashboard-sessionscookie
-- Oprindelig adgangskode-bootstrap ('INITIAL_PASSWORD') skal eksplicit konfigureres til førstegangs-klargøring
-- API-nøgle HMAC-hemmelighed (`API_KEY_SECRET`) sikrer genereret lokalt API-nøgleformat
-- Udbyderhemmeligheder (API-nøgler/tokens) bevares i lokal DB og bør beskyttes på filsystemniveau
-- Slutpunkter for skysynkronisering er afhængige af API-nøglegodkendelse + maskin-id-semantik## Environment and Runtime Matrix
+## Observability and Operational Signals
 
-Miljøvariabler aktivt brugt af kode:
+Runtime visibility sources:
 
-- App/godkendelse: `JWT_SECRET`, `INITIAL_PASSWORD`
-- Lager: `DATA_DIR`
-- Kompatibel nodeadfærd: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
-- Valgfri lagerbasetilsidesættelse (Linux/macOS, når `DATA_DIR` er deaktiveret): `XDG_CONFIG_HOME`
-- Sikkerhedshashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
-- Logning: `ENABLE_REQUEST_LOGS`
-- Synkronisering/sky-URL: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
-- Udgående proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` og varianter med små bogstaver
-- SOCKS5-funktionsflag: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
-- Platform/runtime-hjælpere (ikke app-specifik konfiguration): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`## Known Architectural Notes
+- console logs from `src/sse/utils/logger.ts`
+- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true`
+- textual request status log in `log.txt` (optional/compat)
+- optional 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
 
-1. `usageDb` og `localDb` deler den samme basismappepolitik (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) med ældre filmigrering.
-2. `/api/v1/route.ts` uddelegerer til den samme forenede katalogbygger, der bruges af `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) for at undgå semantisk drift.
-3. Anmodningslogger skriver hele headers/body, når den er aktiveret; behandle logbiblioteket som følsomt.
-4. Cloudadfærd afhænger af korrekt `NEXT_PUBLIC_BASE_URL` og cloud-endepunkts tilgængelighed.
-5. `open-sse/` biblioteket udgives som `@omniroute/open-sse`**npm workspace-pakken**. Kildekoden importerer den via `@omniroute/open-sse/...` (løst af Next.js `transpilePackages`). Filstier i dette dokument bruger stadig mappenavnet `open-sse/` for at opnå konsistens.
-6. Diagrammer i dashboardet bruger**Recharts**(SVG-baseret) til tilgængelige, interaktive analysevisualiseringer (søjlediagrammer for modelbrug, udbyderopdelingstabeller med succesrater).
-7. E2E-tests bruger**Playwright**(`tests/e2e/`), køres via `npm run test:e2e`. Enhedstests bruger**Node.js test runner**(`tests/unit/`), køres via `npm run test:unit`. Kildekoden under `src/` er**TypeScript**(`.ts`/`.tsx`); `open-sse/`-arbejdsområdet forbliver JavaScript (`.js`).
-8. Siden Indstillinger er organiseret i 5 faner: Sikkerhed, Routing (6 globale strategier: fill-first, round-robin, p2c, random, mindst brugt, omkostningsoptimeret), Resiliens (redigerbare hastighedsgrænser, strømafbryder, politikker), AI (tænkebudget, systemprompt, promptcache), Avanceret (proxy).## Operational Verification Checklist
+Detailed request payload capture stores up to four JSON payload stages per routed call:
 
-- Byg fra kilde: `npm run build`
-- Byg Docker-billede: `docker build -t omniroute .`
-- Start service og bekræft:
-- `GET /api/indstillinger`
-- `GET /api/v1/modeller`
-- CLI-målbasis-URL skal være "http://<host>:20128/v1", når "PORT=20128"
+- raw request received from the client
+- translated request actually sent upstream
+- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata
+- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form
+
+## Security-Sensitive Boundaries
+
+- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
+- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning
+- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format
+- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level
+- Cloud sync endpoints rely on API key auth + machine id semantics
+
+## Environment and Runtime Matrix
+
+Environment variables actively used by code:
+
+- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Storage: `DATA_DIR`
+- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
+- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME`
+- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
+- Logging: `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`
+- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+
+## Known Architectural Notes
+
+1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.
+2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift.
+3. Request logger writes full headers/body when enabled; treat log directory as sensitive.
+4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability.
+5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency.
+6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates).
+7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`).
+8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies, **Context Relay** handoff config), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
+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 24+ detection**: `/api/settings/require-login` returns `nodeVersion` and `nodeCompatible` fields. The login page renders a warning banner when the runtime is incompatible.
+
+## Operational Verification Checklist
+
+- Build from source: `npm run build`
+- Build Docker image: `docker build -t omniroute .`
+- Start service and verify:
+- `GET /api/settings`
+- `GET /api/v1/models`
+- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`

docs/i18n/da/docs/CODEBASE_DOCUMENTATION.md

@@ -387,7 +387,7 @@ import "./request/claude-to-openai.js"; // ← self-registers
 | `stream.ts`        | **SSE Transform Stream**— den centrale streamingpipeline. To tilstande: 'OVERSÆTT' (oversættelse i fuld format) og 'PASSTHROUGH' (normalisere + udtræk brug). Håndterer chunk-buffring, brugsestimering, indholdslængdesporing. Per-stream encoder/decoder-instanser undgår delt tilstand. |
 | `streamHelpers.ts` | SSE-værktøjer på lavt niveau: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filtrerer tomme bidder til OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-bevidst SSE-serialisering med `perf_metrics`-oprydning).                                                   |
 | `usageTracking.ts` | Udtræk af tokenbrug fra ethvert format (Claude/OpenAI/Gemini/Responses), estimering med separate værktøj/meddelelse-char-per-token-forhold, buffertilsætning (2000 tokens sikkerhedsmargen), formatspecifik feltfiltrering, konsollogning med ANSI-farver.                                 |
-| `requestLogger.ts` | Filbaseret anmodningslogning (tilmelding via `ENABLE_REQUEST_LOGS=true`). Opretter sessionsmapper med nummererede filer: `1_req_client.json` → `7_res_client.txt`. Alle I/O er asynkrone (fire-and-forget). Masker følsomme overskrifter.                                                  |
+| `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` | Opsnapper specifikke mønstre fra Claude CLI (titeludtræk, opvarmning, optælling) og returnerer falske svar uden at ringe til nogen udbyder. Understøtter både streaming og ikke-streaming. Med vilje begrænset til Claude CLI-omfang.                                                      |
 | `netværkProxy.ts`  | Løser udgående proxy-URL for en given udbyder med forrang: udbyderspecifik konfiguration → global konfiguration → miljøvariabler (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Understøtter "NO_PROXY"-ekskluderinger. Caches konfiguration for 30'erne.                                       | #### SSE Streaming Pipeline |
 

docs/i18n/da/docs/FEATURES.md

@@ -4,102 +4,168 @@
 
 ---
 
-Visuel guide til hver sektion af OmniRoute-dashboardet.---
+
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
 
 ## 🔌 Providers
 
-Administrer AI-udbyderforbindelser: OAuth-udbydere (Claude Code, Codex, Gemini CLI), API-nøgleudbydere (Groq, DeepSeek, OpenRouter) og gratis udbydere (Qoder, Qwen, Kiro). Kiro-konti inkluderer sporing af kreditsaldo - resterende kreditter, samlet godtgørelse og fornyelsesdato synlig i Dashboard → Brug.![Providers Dashboard](screenshots/01-providers.png)
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+![Providers Dashboard](screenshots/01-providers.png)
 
 ---
 
 ## 🎨 Combos
 
-Opret modelrouting-kombinationer med 6 strategier: prioritet, vægtet, round-robin, tilfældig, mindst brugt og omkostningsoptimeret. Hver combo kæder flere modeller med automatisk fallback og inkluderer hurtige skabeloner og klarhedstjek.![Combos Dashboard](screenshots/02-combos.png)
+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.
+
+![Combos Dashboard](screenshots/02-combos.png)
 
 ---
 
 ## 📊 Analytics
 
-Omfattende brugsanalyse med token-forbrug, omkostningsestimater, aktivitetsvarmekort, ugentlige distributionsdiagrammer og opdelinger pr. udbyder.![Analytics Dashboard](screenshots/03-analytics.png)
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
 
 ---
 
 ## 🏥 System Health
 
-Overvågning i realtid: oppetid, hukommelse, version, latency percentiler (p50/p95/p99), cache-statistik og udbyderens afbrydertilstande.![Health Dashboard](screenshots/04-health.png)
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+![Health Dashboard](screenshots/04-health.png)
 
 ---
 
 ## 🔧 Translator Playground
 
-Fire tilstande til fejlfinding af API-oversættelser:**Playground**(formatkonverter),**Chat Tester**(live-anmodninger),**Test Bench**(batchtest) og**Live Monitor**(streaming i realtid).![Translator Playground](screenshots/05-translator.png)
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+![Translator Playground](screenshots/05-translator.png)
 
 ---
 
 ## 🎮 Model Playground _(v2.0.9+)_
 
-Test enhver model direkte fra instrumentbrættet. Vælg udbyder, model og slutpunkt, skriv prompts med Monaco Editor, stream svar i realtid, afbryd midt-stream, og se timing-metrics.---
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
 
 ## 🎨 Themes _(v2.0.5+)_
 
-Brugerdefinerbare farvetemaer til hele dashboardet. Vælg mellem 7 forudindstillede farver (koral, blå, rød, grøn, violet, orange, cyan) eller opret et brugerdefineret tema ved at vælge en hex-farve. Understøtter lys, mørk og systemtilstand.---
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
 
 ## ⚙️ Settings
 
-Omfattende indstillingspanel med faner:
+Comprehensive settings panel with tabs:
 
--**Generelt**— Systemlagring, backupstyring (eksport/importdatabase) -**Udseende**— Temavælger (mørke/lys/system), forudindstillinger af farvetema og brugerdefinerede farver, synlighed i sundhedslog, synlighedskontrol for sidebjælkeelementer -**Sikkerhed**— API-endepunktsbeskyttelse, tilpasset udbyderblokering, IP-filtrering, sessionsoplysninger -**Routing**— Modelaliaser, forringelse af baggrundsopgaver -**Resiliens**— Frekvensgrænsevedholdenhed, tuning af strømafbryder, automatisk deaktivering af forbudte konti, overvågning af udbyderens udløb -**Avanceret**— Konfigurationstilsidesættelser, konfigurationsrevisionsspor, fallback-forringelsestilstand![Settings Dashboard](screenshots/06-settings.png)
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring, **Context Relay** handoff threshold and summary model configuration
+- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
+
+![Settings Dashboard](screenshots/06-settings.png)
 
 ---
 
 ## 🔧 CLI Tools
 
-Et-klik-konfiguration til AI-kodningsværktøjer: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor og Factory Droid. Indeholder automatiseret konfigurationsanvendelse/nulstilling, forbindelsesprofiler og modelkortlægning.![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
 
 ---
 
 ## 🤖 CLI Agents _(v2.0.11+)_
 
-Dashboard til at opdage og administrere CLI-agenter. Viser et gitter med 14 indbyggede agenter (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) med:
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
 
--**Installationsstatus**— Installeret / Ikke fundet med versionsregistrering -**Protokolmærker**— stdio, HTTP osv. -**Tilpassede agenter**- Registrer ethvert CLI-værktøj via formular (navn, binær, versionskommando, spawn args) -**CLI Fingerprint Matching**— Skift pr. udbyder for at matche native CLI-anmodningssignaturer, hvilket reducerer risikoen for forbud, mens proxy-IP bevares---
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🔗 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
+
+---
 
 ## 🖼️ Media _(v2.0.3+)_
 
-Generer billeder, videoer og musik fra dashboardet. Understøtter OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open og MusicGen.---
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
 
 ## 📝 Request Logs
 
-Anmodningslogning i realtid med filtrering efter udbyder, model, konto og API-nøgle. Viser statuskoder, tokenbrug, latenstid og svardetaljer.![Usage Logs](screenshots/08-usage.png)
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+![Usage Logs](screenshots/08-usage.png)
 
 ---
 
 ## 🌐 API Endpoint
 
-Dit forenede API-slutpunkt med kapacitetsopdeling: Chatfuldførelser, Responses API, indlejringer, billedgenerering, omrangering, lydtransskription, tekst-til-tale, modereringer og registrerede API-nøgler. Cloudflare Quick Tunnel integration og cloud proxy support til fjernadgang.![Endpoint Dashboard](screenshots/09-endpoint.png)
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)
 
 ---
 
 ## 🔑 API Key Management
 
-Opret, omfang og tilbagekald API-nøgler. Hver nøgle kan begrænses til specifikke modeller/udbydere med fuld adgang eller skrivebeskyttet tilladelse. Visuel nøglestyring med brugssporing.---
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
 
 ## 📋 Audit Log
 
-Administrativ handlingssporing med filtrering efter handlingstype, aktør, mål, IP-adresse og tidsstempel. Fuld historik for sikkerhedshændelser.---
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
 
 ## 🖥️ Desktop Application
 
-Native Electron desktop-app til Windows, macOS og Linux. Kør OmniRoute som et selvstændigt program med systembakkeintegration, offline support, automatisk opdatering og installation med ét klik.
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
 
-Nøglefunktioner:
+Key features:
 
-- Afstemning af serverberedskab (ingen tom skærm ved koldstart)
-- Systembakke med portstyring
-- Indholdssikkerhedspolitik
-- Engangslås
-- Automatisk opdatering ved genstart
-- Platform-betinget UI (macOS trafiklys, Windows/Linux standard titellinje)
-- Hærdet Electron build-emballage — symlinkede 'node_modules' i den selvstændige bundt detekteres og afvises før pakning, hvilket forhindrer runtime-afhængighed af build-maskinen (v2.5.5+)
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
 
-📖 Se [`electron/README.md`](../electron/README.md) for fuld dokumentation.
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/da/docs/TROUBLESHOOTING.md

@@ -4,68 +4,141 @@
 
 ---
 
-Almindelige problemer og løsninger til OmniRoute.---
+Common problems and solutions for OmniRoute.
+
+---
 
 ## Quick Fixes
 
-| Problem                                | Løsning                                                                     |
-| -------------------------------------- | --------------------------------------------------------------------------- | --- |
-| Første login virker ikke               | Indstil `INITIAL_PASSWORD` i `.env` (ingen hardcoded standard)              |
-| Dashboard åbner ved forkert port       | Indstil `PORT=20128` og `NEXT_PUBLIC_BASE_URL=http://localhost:20128`       |
-| Ingen anmodningslogfiler under `logs/` | Indstil `ENABLE_REQUEST_LOGS=true`                                          |
-| EACCES: tilladelse nægtet              | Indstil `DATA_DIR=/path/to/writable/dir` for at tilsidesætte `~/.omniroute` |
-| Routingstrategi gemmer ikke            | Opdatering til v1.4.11+ (Zod-skemafix for indstillinger persistens)         | --- |
+| 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      | You may be on Node.js 24+ — see [Node.js Compatibility](#nodejs-compatibility) 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 Node.js 24+. The `better-sqlite3` native binary is not compatible with Node.js 24, which causes a fatal crash when the server tries to initialize the database.
+
+**Symptoms:**
+
+- Login page shows a blank screen or a server error
+- Console shows `Error: Module did not self-register` or similar native binding errors
+- Starting with v3.5.5, the login page shows an **orange warning banner** with your Node version if incompatibility is detected
+
+**Fix:**
+
+1. Install Node.js 22 LTS (recommended):
+   ```bash
+   nvm install 22
+   nvm use 22
+   ```
+2. Verify your version: `node --version` should show `v22.x.x`
+3. Reinstall OmniRoute: `npm install -g omniroute`
+4. Restart: `omniroute`
+
+> **Supported versions:** Node.js 18, 20, or 22 LTS. Node.js 24+ is **not supported**.
+
+---
+
+## 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+.
+
+---
 
 ## Provider Issues
 
 ### "Language model did not provide messages"
 
-**Årsag:**Udbyderkvoten er opbrugt.
+**Cause:** Provider quota exhausted.
 
-**Ret:**
+**Fix:**
 
-1. Tjek dashboard-kvotesporing
-2. Brug en kombination med reserveniveauer
-3. Skift til billigere/gratis niveau### Rate Limiting
+1. Check dashboard quota tracker
+2. Use a combo with fallback tiers
+3. Switch to cheaper/free tier
 
-**Årsag:**Abonnementskvoten er opbrugt.
+### Rate Limiting
 
-**Ret:**
+**Cause:** Subscription quota exhausted.
 
-- Tilføj reserve: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-- Brug GLM/MiniMax som billig backup### OAuth Token Expired
+**Fix:**
 
-OmniRoute opdaterer automatisk tokens. Hvis problemerne fortsætter:
+- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Use GLM/MiniMax as cheap backup
 
-1. Dashboard → Udbyder → Genopret forbindelse
-2. Slet og tilføj udbyderforbindelsen igen---
+### OAuth Token Expired
+
+OmniRoute auto-refreshes tokens. If issues persist:
+
+1. Dashboard → Provider → Reconnect
+2. Delete and re-add the provider connection
+
+---
 
 ## Cloud Issues
 
 ### Cloud Sync Errors
 
-1. Bekræft, at `BASE_URL` peger på din kørende forekomst (f.eks. `http://localhost:20128`)
-2. Bekræft "CLOUD_URL" peger på dit cloud-slutpunkt (f.eks. "https://omniroute.dev")
-3. Hold `NEXT_PUBLIC_*`-værdier på linje med værdier på serversiden### Cloud `stream=false` Returns 500
+1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
+2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
+3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
 
-**Symptom:**`Uventet token 'd'...` på cloud-slutpunktet for ikke-streaming-opkald.
+### Cloud `stream=false` Returns 500
 
-**Årsag:**Upstream returnerer SSE-nyttelast, mens klienten forventer JSON.
+**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
 
-**Løsning:**Brug 'stream=true' til direkte skyopkald. Lokal kørselstid inkluderer SSE→JSON fallback.### Cloud Says Connected but "Invalid API key"
+**Cause:** Upstream returns SSE payload while client expects JSON.
 
-1. Opret en ny nøgle fra det lokale dashboard (`/api/keys`)
-2. Kør skysynkronisering: Aktiver sky → Synkroniser nu
-3. Gamle/ikke-synkroniserede nøgler kan stadig returnere '401' på skyen---
+**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
+
+### Cloud Says Connected but "Invalid API key"
+
+1. Create a fresh key from local dashboard (`/api/keys`)
+2. Run cloud sync: Enable Cloud → Sync Now
+3. Old/non-synced keys can still return `401` on cloud
+
+---
 
 ## Docker Issues
 
 ### CLI Tool Shows Not Installed
 
-1. Tjek runtime-felter: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
-2. For bærbar tilstand: brug billedmål "runner-cli" (bundtet CLI'er)
-3. For værtsmonteringstilstand: indstil `CLI_EXTRA_PATHS` og monter host bin-mappe som skrivebeskyttet
-4. Hvis `installed=true` og `runnable=false`: binær blev fundet, men sundhedstjekket mislykkedes### Quick Runtime Validation
+1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. For portable mode: use image target `runner-cli` (bundled CLIs)
+3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
+4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
+
+### Quick Runtime Validation
 
 ```bash
 curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
@@ -79,16 +152,22 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
 
 ### High Costs
 
-1. Tjek brugsstatistik i Dashboard → Brug
-2. Skift primær model til GLM/MiniMax
-3. Brug gratis niveau (Gemini CLI, Qoder) til ikke-kritiske opgaver
-4. Indstil omkostningsbudgetter pr. API-nøgle: Dashboard → API-nøgler → Budget---
+1. Check usage stats in Dashboard → Usage
+2. Switch primary model to GLM/MiniMax
+3. Use free tier (Gemini CLI, Qoder) for non-critical tasks
+4. Set cost budgets per API key: Dashboard → API Keys → Budget
+
+---
 
 ## Debugging
 
-### Enable Request Logs
+### Enable Log Files
 
-Indstil `ENABLE_REQUEST_LOGS=true` i din `.env`-fil. Logs vises under mappen `logs/`.### Check Provider Health
+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
 
 ```bash
 # Health dashboard
@@ -100,101 +179,136 @@ curl http://localhost:20128/api/monitoring/health
 
 ### Runtime Storage
 
-- Hovedtilstand: `${DATA_DIR}/storage.sqlite` (udbydere, kombinationer, aliaser, nøgler, indstillinger)
-- Anvendelse: SQLite-tabeller i `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + valgfri `${DATA_DIR}/log.txt` og `${DATA_DIR}/call_logs/`
-- Anmodningslogfiler: `<repo>/logs/...` (når `ENABLE_REQUEST_LOGS=true`)---
+- 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}/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
+
+---
 
 ## Circuit Breaker Issues
 
 ### Provider stuck in OPEN state
 
-Når en udbyders afbryder er ÅBEN, blokeres anmodninger, indtil nedkølingen udløber.
+When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
 
-**Ret:**
+**Fix:**
 
-1. Gå til**Dashboard → Indstillinger → Resiliens**
-2. Tjek afbryderkortet for den berørte udbyder
-3. Klik på**Nulstil alle**for at rydde alle afbrydere, eller vent på, at nedkølingen udløber
-4. Bekræft, at udbyderen faktisk er tilgængelig, før du nulstiller### Provider keeps tripping the circuit breaker
+1. Go to **Dashboard → Settings → Resilience**
+2. Check the circuit breaker card for the affected provider
+3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
+4. Verify the provider is actually available before resetting
 
-Hvis en udbyder gentagne gange går i ÅBEN tilstand:
+### Provider keeps tripping the circuit breaker
 
-1. Tjek**Dashboard → Health → Provider Health**for fejlmønsteret
-2. Gå til**Indstillinger → Resiliens → Udbyderprofiler**og øg fejltærsklen
-3. Tjek, om udbyderen har ændret API-grænser eller kræver gengodkendelse
-4. Gennemgå latency-telemetri — høj latenstid kan forårsage timeout-baserede fejl---
+If a provider repeatedly enters OPEN state:
+
+1. Check **Dashboard → Health → Provider Health** for the failure pattern
+2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
+3. Check if the provider has changed API limits or requires re-authentication
+4. Review latency telemetry — high latency may cause timeout-based failures
+
+---
 
 ## Audio Transcription Issues
 
 ### "Unsupported model" error
 
-- Sørg for, at du bruger det korrekte præfiks: `deepgram/nova-3` eller `assemblyai/best`
-- Bekræft, at udbyderen er tilsluttet i**Dashboard → Udbydere**### Transcription returns empty or fails
+- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
+- Verify the provider is connected in **Dashboard → Providers**
 
-- Tjek understøttede lydformater: "mp3", "wav", "m4a", "flac", "ogg", "webm"
-- Bekræft filstørrelsen er inden for udbyderens grænser (typisk < 25 MB)
-- Tjek gyldigheden af udbyderens API-nøgle på udbyderkortet---
+### Transcription returns empty or fails
+
+- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Verify file size is within provider limits (typically < 25MB)
+- Check provider API key validity in the provider card
+
+---
 
 ## Translator Debugging
 
-Brug**Dashboard → Oversætter**til at fejlfinde problemer med formatoversættelse:
+Use **Dashboard → Translator** to debug format translation issues:
 
-| Tilstand         | Hvornår skal man bruge                                                                                          |
-| ---------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| **Legeplads**    | Sammenlign input/output-formater side om side — indsæt en mislykket anmodning for at se, hvordan den oversættes |
-| **Chattester**   | Send livebeskeder og inspicer den fulde anmodnings-/svarnyttelast inklusive overskrifter                        |
-| **Testbænk**     | Kør batchtest på tværs af formatkombinationer for at finde ud af, hvilke oversættelser der er brudte            |
-| **Live Monitor** | Se anmodningsflow i realtid for at fange periodiske oversættelsesproblemer                                      | ### Common format issues |
+| Mode             | When to Use                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| **Playground**   | Compare input/output formats side by side — paste a failing request to see how it translates |
+| **Chat Tester**  | Send live messages and inspect the full request/response payload including headers           |
+| **Test Bench**   | Run batch tests across format combinations to find which translations are broken             |
+| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues                        |
 
--**Tænke-tags vises ikke**— Tjek, om måludbyderen understøtter tænkning og indstilling af tænkebudget -**Værktøjsopkald falder**— Nogle formatoversættelser kan fjerne ikke-understøttede felter; verificere i Playground-tilstand -**Systemprompt mangler**— Claude og Gemini håndterer systemprompts forskelligt; kontrollere oversættelsesoutput -**SDK returnerer rå streng i stedet for objekt**— Rettet i v1.1.0: svar sanitizer fjerner nu ikke-standard felter (`x_groq`, `usage_breakdown` osv.), der forårsager OpenAI SDK Pydantic valideringsfejl -**GLM/ERNIE afviser 'system'-rolle**— Rettet i v1.1.0: Rollenormalisering flettes automatisk systemmeddelelser ind i brugermeddelelser for inkompatible modeller -**"udvikler"-rolle ikke genkendt**- Rettet i v1.1.0: automatisk konverteret til "system" for ikke-OpenAI-udbydere -**`json_schema` virker ikke med Gemini**- Rettet i v1.1.0: `response_format` er nu konverteret til Gemini's `responseMimeType` + `responseSchema`---
+### Common format issues
+
+- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
+- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
+- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
+- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures
+- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
+- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers
+- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema`
+
+---
 
 ## Resilience Settings
 
 ### Auto rate-limit not triggering
 
-- Automatisk hastighedsgrænse gælder kun for API-nøgleudbydere (ikke OAuth/abonnement)
-- Bekræft, at**Indstillinger → Modstandsdygtighed → Udbyderprofiler**har aktiveret automatisk satsgrænse
-- Tjek, om udbyderen returnerer '429'-statuskoder eller 'Retry-After'-overskrifter### Tuning exponential backoff
+- Auto rate-limit only applies to API key providers (not OAuth/subscription)
+- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
+- Check if the provider returns `429` status codes or `Retry-After` headers
 
-Udbyderprofiler understøtter disse indstillinger:
+### Tuning exponential backoff
 
--**Base delay**— Indledende ventetid efter første fejl (standard: 1s) -**Maksimal forsinkelse**— Maksimal ventetid (standard: 30s) -**Multiplikator**— Hvor meget skal forsinkelsen øges pr. på hinanden følgende fejl (standard: 2x)### Anti-thundering herd
+Provider profiles support these settings:
 
-Når mange samtidige anmodninger rammer en hastighedsbegrænset udbyder, bruger OmniRoute mutex + automatisk hastighedsbegrænsning til at serialisere anmodninger og forhindre kaskadefejl. Dette er automatisk for API-nøgleudbydere.---
+- **Base delay** — Initial wait time after first failure (default: 1s)
+- **Max delay** — Maximum wait time cap (default: 30s)
+- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
+
+### Anti-thundering herd
+
+When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
+
+---
 
 ## Optional RAG / LLM failure taxonomy (16 problems)
 
-Nogle OmniRoute-brugere placerer gatewayen foran RAG- eller agentstakke. I disse opsætninger er det almindeligt at se et mærkeligt mønster: OmniRoute ser sund ud (udbydere op, routing profiler ok, ingen hastighedsgrænse advarsler), men det endelige svar er stadig forkert.
+Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong.
 
-I praksis kommer disse hændelser normalt fra RAG-rørledningen nedstrøms, ikke fra selve gatewayen.
+In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself.
 
-Hvis du ønsker et fælles ordforråd til at beskrive disse fejl, kan du bruge WFGY ProblemMap, en ekstern MIT-licenstekstressource, der definerer seksten tilbagevendende RAG/LLM-fejlmønstre. På et højt niveau dækker det over:
+If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers:
 
-- genfindingsdrift og brudte kontekstgrænser
-- tomme eller uaktuelle indekser og vektorlagre
-- indlejring versus semantisk mismatch
-- problemer med hurtig montering og kontekstvindue
-- logisk sammenbrud og oversikre svar
-- lang kæde og agentkoordinationsfejl
-- multiagent hukommelse og rolledrift
-- problemer med implementering og bootstrap-bestilling
+- retrieval drift and broken context boundaries
+- empty or stale indexes and vector stores
+- embedding versus semantic mismatch
+- prompt assembly and context window issues
+- logic collapse and overconfident answers
+- long chain and agent coordination failures
+- multi agent memory and role drift
+- deployment and bootstrap ordering problems
 
-Ideen er enkel:
+The idea is simple:
 
-1. Når du undersøger et dårligt svar, skal du fange:
-   - brugeropgave og anmodning
-   - rute eller udbyderkombination i OmniRoute
-   - enhver RAG-kontekst, der bruges downstream (hentede dokumenter, værktøjsopkald osv.)
-2. Kortlæg hændelsen til et eller to WFGY ProblemMap-numre (`No.1` … `No.16`).
-3. Gem nummeret i dit eget dashboard, runbook eller hændelsessporing ved siden af ​​OmniRoute-logfilerne.
-4. Brug den tilsvarende WFGY-side til at beslutte, om du skal ændre din RAG-stack, retriever eller routingstrategi.
+1. When you investigate a bad response, capture:
+   - user task and request
+   - route or provider combo in OmniRoute
+   - any RAG context used downstream (retrieved documents, tool calls, etc)
+2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`).
+3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs.
+4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy.
 
-Fuld tekst og konkrete opskrifter live her (MIT-licens, kun tekst):
+Full text and concrete recipes live here (MIT license, text only):
 
 [WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
 
-Du kan ignorere dette afsnit, hvis du ikke kører RAG eller agentpipelines bag OmniRoute.---
+You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute.
+
+---
 
 ## Still Stuck?
 
--**GitHub-problemer**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -**Architecture**: Se [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for interne detaljer -**API-reference**: Se [`docs/API_REFERENCE.md`](API_REFERENCE.md) for alle endepunkter -**Health Dashboard**: Tjek**Dashboard → Health**for systemstatus i realtid -**Oversætter**: Brug**Dashboard → Oversætter**til at fejlsøge formatproblemer
+- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
+- **Translator**: Use **Dashboard → Translator** to debug format issues

docs/i18n/da/docs/VM_DEPLOYMENT_GUIDE.md

@@ -100,7 +100,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/da/llm.txt

@@ -0,0 +1,476 @@
+# OmniRoute (Dansk)
+
+🌐 **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.
+
+## Overblik
+
+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)
+
+### Sikkerhed
+- **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/de/docs/ARCHITECTURE.md

@@ -4,80 +4,91 @@
 
 ---
 
-_Letzte Aktualisierung: 28.03.2026_## Executive Summary
+_Last updated: 2026-03-28_
 
-OmniRoute ist ein lokales KI-Routing-Gateway und Dashboard, das auf Next.js basiert.
-Es bietet einen einzigen OpenAI-kompatiblen Endpunkt („/v1/\*“) und leitet den Datenverkehr über mehrere Upstream-Anbieter mit Übersetzung, Fallback, Token-Aktualisierung und Nutzungsverfolgung weiter.
+## Executive Summary
 
-Kernkompetenzen:
+OmniRoute is a local AI routing gateway and dashboard built on Next.js.
+It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
 
-- OpenAI-kompatible API-Oberfläche für CLI/Tools (28 Anbieter)
-- Anforderungs-/Antwortübersetzung über Anbieterformate hinweg
-- Modell-Combo-Fallback (Multi-Modell-Sequenz)
-- Fallback auf Kontoebene (mehrere Konten pro Anbieter)
-- OAuth + API-Schlüssel-Provider-Verbindungsverwaltung
-- Einbettungsgenerierung über „/v1/embeddings“ (6 Anbieter, 9 Modelle)
-- Bildgenerierung über „/v1/images/generations“ (4 Anbieter, 9 Modelle)
-- Think-Tag-Parsing (`<think>...</think>`) für Argumentationsmodelle
-- Antwortbereinigung für strikte OpenAI SDK-Kompatibilität
-- Rollennormalisierung (Entwickler→System, System→Benutzer) für anbieterübergreifende Kompatibilität
-- Strukturierte Ausgabekonvertierung (json_schema → Gemini ResponseSchema)
-- Lokale Persistenz für Anbieter, Schlüssel, Aliase, Kombinationen, Einstellungen, Preise
-- Nutzungs-/Kostenverfolgung und Anforderungsprotokollierung
-- Optionale Cloud-Synchronisierung für die Synchronisierung mehrerer Geräte/Status
-- IP-Zulassungs-/Blockierungsliste für die API-Zugriffskontrolle
-- Denken Sie an die Budgetverwaltung (Passthrough/Auto/Benutzerdefiniert/Adaptiv)
-- Sofortige Injektion des globalen Systems
-- Sitzungsverfolgung und Fingerabdruck
-- Erweiterte Ratenbegrenzung pro Konto mit anbieterspezifischen Profilen
-- Leistungsschaltermuster für die Ausfallsicherheit des Anbieters
-- Donnernder Herdenschutz mit Mutex-Sperre
-  – Signaturbasierter Anforderungsdeduplizierungs-Cache
-- Domänenschicht: Modellverfügbarkeit, Kostenregeln, Fallback-Richtlinie, Sperrrichtlinie
-- Persistenz des Domänenstatus (SQLite-Durchschreibcache für Fallbacks, Budgets, Sperrungen, Leistungsschalter)
-- Richtlinien-Engine für zentralisierte Anfrageauswertung (Sperrung → Budget → Fallback)
-- Fordern Sie Telemetrie mit p50/p95/p99-Latenzaggregation an
-- Korrelations-ID (X-Request-Id) für eine durchgängige Nachverfolgung
-- Compliance-Audit-Protokollierung mit Opt-out pro API-Schlüssel
-- Evaluierungsrahmen für die LLM-Qualitätssicherung
-- Resilience-UI-Dashboard mit Echtzeit-Leistungsschalterstatus
-- Modulare OAuth-Anbieter (12 einzelne Module unter „src/lib/oauth/providers/“)
+Core capabilities:
 
-Primäres Laufzeitmodell:
+- OpenAI-compatible API surface for CLI/tools (28 providers)
+- Request/response translation across provider formats
+- Model combo fallback (multi-model sequence)
+- Account-level fallback (multi-account per provider)
+- OAuth + API-key provider connection management
+- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
+- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Think tag parsing (`<think>...</think>`) for reasoning models
+- Response sanitization for strict OpenAI SDK compatibility
+- Role normalization (developer→system, system→user) for cross-provider compatibility
+- Structured output conversion (json_schema → Gemini responseSchema)
+- Local persistence for providers, keys, aliases, combos, settings, pricing
+- Usage/cost tracking and request logging
+- Optional cloud sync for multi-device/state sync
+- IP allowlist/blocklist for API access control
+- Thinking budget management (passthrough/auto/custom/adaptive)
+- Global system prompt injection
+- Session tracking and fingerprinting
+- Per-account enhanced rate limiting with provider-specific profiles
+- Circuit breaker pattern for provider resilience
+- Anti-thundering herd protection with mutex locking
+- Signature-based request deduplication cache
+- Domain layer: model availability, cost rules, fallback policy, lockout policy
+- 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
+- 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/`)
 
-– Next.js-App-Routen unter „src/app/api/_“ implementieren sowohl Dashboard-APIs als auch Kompatibilitäts-APIs
-– Ein gemeinsam genutzter SSE/Routing-Kern in „src/sse/_“ + „open-sse/\*“ kümmert sich um die Ausführung, Übersetzung, Streaming, Fallback und Nutzung des Anbieters## Scope and Boundaries
+Primary runtime model:
+
+- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
+- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
+
+## Scope and Boundaries
 
 ### In Scope
 
-- Lokale Gateway-Laufzeit
-- Dashboard-Verwaltungs-APIs
-- Anbieterauthentifizierung und Token-Aktualisierung
-- Fordern Sie Übersetzung und SSE-Streaming an
-- Lokaler Status + Nutzungspersistenz
-- Optionale Orchestrierung der Cloud-Synchronisierung### Out of Scope
+- Local gateway runtime
+- Dashboard management APIs
+- Provider authentication and token refresh
+- Request translation and SSE streaming
+- Local state + usage persistence
+- Optional cloud sync orchestration
 
-- Cloud-Service-Implementierung hinter „NEXT_PUBLIC_CLOUD_URL“.
-- Anbieter-SLA/Kontrollebene außerhalb des lokalen Prozesses
-- Externe CLI-Binärdateien selbst (Claude CLI, Codex CLI usw.)## Dashboard Surface (Current)
+### Out of Scope
 
-Hauptseiten unter „src/app/(dashboard)/dashboard/“:
+- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
+- Provider SLA/control plane outside local process
+- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
 
-- „/dashboard“ – Schnellstart + Anbieterübersicht
-- „/dashboard/endpoint“ – Endpunkt-Proxy + MCP + A2A + API-Endpunkt-Registerkarten
-- „/dashboard/providers“ – Anbieterverbindungen und Anmeldeinformationen
-- „/dashboard/combos“ – Kombinationsstrategien, Vorlagen, Modell-Routing-Regeln
-- „/dashboard/costs“ – Kostenaggregation und Preistransparenz
-- „/dashboard/analytics“ – Nutzungsanalysen und Auswertungen
-- „/dashboard/limits“ – Kontingent-/Ratenkontrolle
-- „/dashboard/cli-tools“ – CLI-Onboarding, Laufzeiterkennung, Konfigurationsgenerierung
-- „/dashboard/agents“ – erkannte ACP-Agenten + benutzerdefinierte Agentenregistrierung
-- „/dashboard/media“ – Bild-/Video-/Musikspielplatz
-- „/dashboard/search-tools“ – Tests und Verlauf des Suchanbieters
-- „/dashboard/health“ – Betriebszeit, Leistungsschalter, Ratenbegrenzungen
-- „/dashboard/logs“ – Anforderungs-/Proxy-/Audit-/Konsolenprotokolle
-- „/dashboard/settings“ – Registerkarten für Systemeinstellungen (Allgemein, Routing, Combo-Standardeinstellungen usw.)
-- „/dashboard/api-manager“ – API-Schlüssellebenszyklus und Modellberechtigungen## High-Level System Context
+## Dashboard Surface (Current)
+
+Main pages under `src/app/(dashboard)/dashboard/`:
+
+- `/dashboard` — quick start + provider overview
+- `/dashboard/endpoint` — endpoint proxy + MCP + A2A + API endpoint tabs
+- `/dashboard/providers` — provider connections and credentials
+- `/dashboard/combos` — combo strategies, templates, model routing rules
+- `/dashboard/costs` — cost aggregation and pricing visibility
+- `/dashboard/analytics` — usage analytics and evaluations
+- `/dashboard/limits` — quota/rate controls
+- `/dashboard/cli-tools` — CLI onboarding, runtime detection, config generation
+- `/dashboard/agents` — detected ACP agents + custom agent registration
+- `/dashboard/media` — image/video/music playground
+- `/dashboard/search-tools` — search provider testing and history
+- `/dashboard/health` — uptime, circuit breakers, rate limits
+- `/dashboard/logs` — request/proxy/audit/console logs
+- `/dashboard/settings` — system settings tabs (general, routing, combo defaults, etc.)
+- `/dashboard/api-manager` — API key lifecycle and model permissions
+
+## High-Level System Context
 
 ```mermaid
 flowchart LR
@@ -129,140 +140,151 @@ flowchart LR
 
 ## 1) API and Routing Layer (Next.js App Routes)
 
-Hauptverzeichnisse:
+Main directories:
 
-- „src/app/api/v1/_“ und „src/app/api/v1beta/_“ für Kompatibilitäts-APIs
-- „src/app/api/\*“ für Verwaltungs-/Konfigurations-APIs
-- Next schreibt in „next.config.mjs“ die Zuordnung von „/v1/_“ zu „/api/v1/_“ um
+- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
+- `src/app/api/*` for management/configuration APIs
+- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
 
-Wichtige Kompatibilitätsrouten:
+Important compatibility routes:
 
 - `src/app/api/v1/chat/completions/route.ts`
 - `src/app/api/v1/messages/route.ts`
 - `src/app/api/v1/responses/route.ts`
-- „src/app/api/v1/models/route.ts“ – enthält benutzerdefinierte Modelle mit „custom: true“.
-- „src/app/api/v1/embeddings/route.ts“ – Einbettungsgenerierung (6 Anbieter)
-- `src/app/api/v1/images/generations/route.ts` — Bildgenerierung (4+ Anbieter inkl. Antigravity/Nebius)
+- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`
+- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)
+- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)
 - `src/app/api/v1/messages/count_tokens/route.ts`
-- „src/app/api/v1/providers/[provider]/chat/completions/route.ts“ – dedizierter Chat pro Anbieter
-- „src/app/api/v1/providers/[provider]/embeddings/route.ts“ – dedizierte Einbettungen pro Anbieter
-- „src/app/api/v1/providers/[provider]/images/generations/route.ts“ – dedizierte Bilder pro Anbieter
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images
 - `src/app/api/v1beta/models/route.ts`
-- `src/app/api/v1beta/models/[...pfad]/route.ts`
+- `src/app/api/v1beta/models/[...path]/route.ts`
 
-Verwaltungsdomänen:
+Management domains:
 
-- Authentifizierung/Einstellungen: `src/app/api/auth/*`, `src/app/api/settings/*`
-- Anbieter/Verbindungen: `src/app/api/providers*`
-- Anbieterknoten: `src/app/api/provider-nodes*`
-- Benutzerdefinierte Modelle: `src/app/api/provider-models` (GET/POST/DELETE)
-- Modellkatalog: `src/app/api/models/route.ts` (GET)
-- Proxy-Konfiguration: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
+- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
+- Providers/connections: `src/app/api/providers*`
+- Provider nodes: `src/app/api/provider-nodes*`
+- Custom models: `src/app/api/provider-models` (GET/POST/DELETE)
+- Model catalog: `src/app/api/models/route.ts` (GET)
+- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
 - OAuth: `src/app/api/oauth/*`
-- Schlüssel/Aliase/Combos/Preise: „src/app/api/keys*“, „src/app/api/models/alias“, „src/app/api/combos*“, „src/app/api/pricing“.
-- Verwendung: `src/app/api/usage/*`
-- Synchronisierung/Cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
-- CLI-Tool-Helfer: `src/app/api/cli-tools/*`
-- IP-Filter: `src/app/api/settings/ip-filter` (GET/PUT)
-- Thinking-Budget: `src/app/api/settings/thinking-budget` (GET/PUT)
-- Systemeingabeaufforderung: `src/app/api/settings/system-prompt` (GET/PUT)
-- Sitzungen: `src/app/api/sessions` (GET)
-- Ratenlimits: `src/app/api/rate-limits` (GET)
-  – Resilienz: „src/app/api/resilience“ (GET/PATCH) – Anbieterprofile, Leistungsschalter, Ratengrenzstatus
-- Resilience-Reset: `src/app/api/resilience/reset` (POST) – Breaker + Abklingzeiten zurücksetzen
-- Cache-Statistiken: `src/app/api/cache/stats` (GET/DELETE)
-- Modellverfügbarkeit: `src/app/api/models/availability` (GET/POST)
-- Telemetrie: `src/app/api/telemetry/summary` (GET)
+- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
+- Usage: `src/app/api/usage/*`
+- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
+- CLI tooling helpers: `src/app/api/cli-tools/*`
+- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)
+- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)
+- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)
+- Sessions: `src/app/api/sessions` (GET)
+- Rate limits: `src/app/api/rate-limits` (GET)
+- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns
+- Cache stats: `src/app/api/cache/stats` (GET/DELETE)
+- Model availability: `src/app/api/models/availability` (GET/POST)
+- Telemetry: `src/app/api/telemetry/summary` (GET)
 - Budget: `src/app/api/usage/budget` (GET/POST)
-- Fallback-Ketten: `src/app/api/fallback/chains` (GET/POST/DELETE)
-- Compliance-Audit: `src/app/api/compliance/audit-log` (GET)
-- Auswertungen: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
-- Richtlinien: `src/app/api/policies` (GET/POST)## 2) SSE + Translation Core
+- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET)
+- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
+- Policies: `src/app/api/policies` (GET/POST)
 
-Hauptflussmodule:
+## 2) SSE + Translation Core
 
-- Eintrag: `src/sse/handlers/chat.ts`
-- Kernorchestrierung: „open-sse/handlers/chatCore.ts“.
-- Anbieterausführungsadapter: „open-sse/executors/\*“.
-- Formaterkennung/Anbieterkonfiguration: „open-sse/services/provider.ts“.
-- Modellanalyse/-auflösung: `src/sse/services/model.ts`, `open-sse/services/model.ts`
-- Konto-Fallback-Logik: „open-sse/services/accountFallback.ts“.
-- Übersetzungsregister: „open-sse/translator/index.ts“.
-- Stream-Transformationen: „open-sse/utils/stream.ts“, „open-sse/utils/streamHandler.ts“.
-- Nutzungsextraktion/-normalisierung: `open-sse/utils/usageTracking.ts`
-- Think-Tag-Parser: „open-sse/utils/thinkTagParser.ts“.
-- Einbettungshandler: `open-sse/handlers/embeddings.ts`
-- Einbettungsanbieter-Registrierung: „open-sse/config/embeddingRegistry.ts“.
-- Handler für die Bildgenerierung: „open-sse/handlers/imageGeneration.ts“.
-- Registrierung des Bildanbieters: „open-sse/config/imageRegistry.ts“.
-- Antwortbereinigung: `open-sse/handlers/responseSanitizer.ts`
-- Rollennormalisierung: `open-sse/services/roleNormalizer.ts`
+Main flow modules:
 
-Dienste (Geschäftslogik):
+- Entry: `src/sse/handlers/chat.ts`
+- Core orchestration: `open-sse/handlers/chatCore.ts`
+- Provider execution adapters: `open-sse/executors/*`
+- Format detection/provider config: `open-sse/services/provider.ts`
+- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
+- Account fallback logic: `open-sse/services/accountFallback.ts`
+- Translation registry: `open-sse/translator/index.ts`
+- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
+- Think tag parser: `open-sse/utils/thinkTagParser.ts`
+- Embedding handler: `open-sse/handlers/embeddings.ts`
+- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
+- Image generation handler: `open-sse/handlers/imageGeneration.ts`
+- Image provider registry: `open-sse/config/imageRegistry.ts`
+- Response sanitization: `open-sse/handlers/responseSanitizer.ts`
+- Role normalization: `open-sse/services/roleNormalizer.ts`
 
-- Kontoauswahl/-bewertung: `open-sse/services/accountSelector.ts`
-- Kontextlebenszyklusverwaltung: „open-sse/services/contextManager.ts“.
-- Durchsetzung des IP-Filters: „open-sse/services/ipFilter.ts“.
-- Sitzungsverfolgung: `open-sse/services/sessionManager.ts`
-- Deduplizierung anfordern: „open-sse/services/signatureCache.ts“.
-- System-Prompt-Injection: „open-sse/services/systemPrompt.ts“.
-- Thinking Budget Management: „open-sse/services/thinkingBudget.ts“.
-- Wildcard-Modell-Routing: „open-sse/services/wildcardRouter.ts“.
-- Ratenlimitverwaltung: `open-sse/services/rateLimitManager.ts`
-- Leistungsschalter: `open-sse/services/CircuitBreaker.ts`
+Services (business logic):
 
-Module der Domänenschicht:
+- Account selection/scoring: `open-sse/services/accountSelector.ts`
+- Context lifecycle management: `open-sse/services/contextManager.ts`
+- IP filter enforcement: `open-sse/services/ipFilter.ts`
+- Session tracking: `open-sse/services/sessionManager.ts`
+- Request deduplication: `open-sse/services/signatureCache.ts`
+- System prompt injection: `open-sse/services/systemPrompt.ts`
+- Thinking budget management: `open-sse/services/thinkingBudget.ts`
+- Wildcard model routing: `open-sse/services/wildcardRouter.ts`
+- Rate limit management: `open-sse/services/rateLimitManager.ts`
+- Circuit breaker: `open-sse/services/circuitBreaker.ts`
+- 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
 
-- Modellverfügbarkeit: `src/lib/domain/modelAvailability.ts`
-- Kostenregeln/Budgets: `src/lib/domain/costRules.ts`
-- Fallback-Richtlinie: `src/lib/domain/fallbackPolicy.ts`
-- Combo-Resolver: `src/lib/domain/comboResolver.ts`
-- Sperrrichtlinie: `src/lib/domain/lockoutPolicy.ts`
-  – Richtlinien-Engine: „src/domain/policyEngine.ts“ – zentralisierte Sperrung → Budget → Fallback-Auswertung
-- Fehlercodekatalog: `src/lib/domain/errorCodes.ts`
-- Anforderungs-ID: `src/lib/domain/requestId.ts`
-- Abrufzeitüberschreitung: `src/lib/domain/fetchTimeout.ts`
-- Telemetrie anfordern: `src/lib/domain/requestTelemetry.ts`
-- Compliance/Audit: `src/lib/domain/compliance/index.ts`
-- Eval-Runner: `src/lib/domain/evalRunner.ts`
-  – Domänenstatus-Persistenz: „src/lib/db/domainState.ts“ – SQLite CRUD für Fallback-Ketten, Budgets, Kostenverlauf, Sperrstatus, Leistungsschalter
+Domain layer modules:
 
-OAuth-Provider-Module (12 einzelne Dateien unter „src/lib/oauth/providers/“):
+- Model availability: `src/lib/domain/modelAvailability.ts`
+- Cost rules/budgets: `src/lib/domain/costRules.ts`
+- Fallback policy: `src/lib/domain/fallbackPolicy.ts`
+- Combo resolver: `src/lib/domain/comboResolver.ts`
+- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
+- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
+- Error codes catalog: `src/lib/domain/errorCodes.ts`
+- Request ID: `src/lib/domain/requestId.ts`
+- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
+- Request telemetry: `src/lib/domain/requestTelemetry.ts`
+- Compliance/audit: `src/lib/domain/compliance/index.ts`
+- Eval runner: `src/lib/domain/evalRunner.ts`
+- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
 
-- Registrierungsindex: `src/lib/oauth/providers/index.ts`
-- Einzelne Anbieter: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `qoder.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
-  – Thin Wrapper: „src/lib/oauth/providers.ts“ – erneuter Export aus einzelnen Modulen## 3) Persistence Layer
+OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
-Primärstatus-DB (SQLite):
+- 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`
+- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
-- Kerninfra: `src/lib/db/core.ts` (better-sqlite3, Migrationen, WAL)
-- Fassade erneut exportieren: `src/lib/localDb.ts` (dünne Kompatibilitätsschicht für Aufrufer)
-- Datei: „${DATA_DIR}/storage.sqlite“ (oder „$XDG_CONFIG_HOME/omniroute/storage.sqlite“, wenn festgelegt, sonst „~/.omniroute/storage.sqlite“)
-- Entitäten (Tabellen + KV-Namespaces): ProviderConnections, ProviderNodes, ModelAliases, Combos, APIKeys, Einstellungen, Preise,**customModels**,**proxyConfig**,**ipFilter**,**thinkingBudget**,**systemPrompt**
+## 3) Persistence Layer
 
-Nutzungsdauer:
+Primary state DB (SQLite):
 
-- Fassade: `src/lib/usageDb.ts` (zerlegte Module in `src/lib/usage/*`)
-- SQLite-Tabellen in „storage.sqlite“: „usage_history“, „call_logs“, „proxy_logs“.
-- Optionale Dateiartefakte bleiben aus Kompatibilitäts-/Debuggründen erhalten (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
-  – Ältere JSON-Dateien werden durch Startmigrationen nach SQLite migriert, sofern vorhanden
+- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL)
+- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers)
+- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`)
+- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
+
+Usage persistence:
+
+- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`)
+- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
+- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
+- legacy JSON files are migrated to SQLite by startup migrations when present
 
 Domain State DB (SQLite):
 
-– „src/lib/db/domainState.ts“ – CRUD-Operationen für den Domänenstatus
+- `src/lib/db/domainState.ts` — CRUD operations for domain state
+- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
+- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
 
-- Tabellen (erstellt in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_Circuit_breakers`
-- Write-Through-Cache-Muster: In-Memory-Maps sind zur Laufzeit maßgeblich; Mutationen werden synchron zu SQLite geschrieben; Der Status wird beim Kaltstart aus der DB wiederhergestellt## 4) Auth + Security Surfaces
+## 4) Auth + Security Surfaces
 
-- Dashboard-Cookie-Authentifizierung: „src/proxy.ts“, „src/app/api/auth/login/route.ts“.
-- API-Schlüsselgenerierung/-überprüfung: `src/shared/utils/apiKey.ts`
-  – Provider-Geheimnisse blieben in „providerConnections“-Einträgen bestehen
-- Unterstützung für ausgehende Proxys über „open-sse/utils/proxyFetch.ts“ (env vars) und „open-sse/utils/networkProxy.ts“ (pro Anbieter oder global konfigurierbar)## 5) Cloud Sync
+- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
+- API key generation/verification: `src/shared/utils/apiKey.ts`
+- Provider secrets persisted in `providerConnections` entries
+- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
 
-- Scheduler-Init: „src/lib/initCloudSync.ts“, „src/shared/services/initializeCloudSync.ts“, „src/shared/services/modelSyncScheduler.ts“.
-- Periodische Aufgabe: `src/shared/services/cloudSyncScheduler.ts`
-- Periodische Aufgabe: `src/shared/services/modelSyncScheduler.ts`
-- Kontrollroute: `src/app/api/sync/cloud/route.ts`## Request Lifecycle (`/v1/chat/completions`)
+## 5) Cloud Sync
+
+- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
+- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Periodic task: `src/shared/services/modelSyncScheduler.ts`
+- Control route: `src/app/api/sync/cloud/route.ts`
+
+## Request Lifecycle (`/v1/chat/completions`)
 
 ```mermaid
 sequenceDiagram
@@ -339,7 +361,9 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-Fallback-Entscheidungen werden von „open-sse/services/accountFallback.ts“ unter Verwendung von Statuscodes und Fehlermeldungsheuristiken gesteuert. Combo-Routing fügt einen zusätzlichen Schutz hinzu: 400-Fehler im Anbieterbereich wie Upstream-Inhaltsblockierungs- und Rollenvalidierungsfehler werden als modelllokale Fehler behandelt, sodass spätere Combo-Ziele weiterhin ausgeführt werden können.## OAuth Onboarding and Token Refresh Lifecycle
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run.
+
+## OAuth Onboarding and Token Refresh Lifecycle
 
 ```mermaid
 sequenceDiagram
@@ -369,7 +393,9 @@ sequenceDiagram
     Test-->>UI: validation result
 ```
 
-Die Aktualisierung während des Live-Verkehrs wird in „open-sse/handlers/chatCore.ts“ über den Executor „refreshCredentials()“ ausgeführt.## Cloud Sync Lifecycle (Enable / Sync / Disable)
+Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
+
+## Cloud Sync Lifecycle (Enable / Sync / Disable)
 
 ```mermaid
 sequenceDiagram
@@ -401,7 +427,9 @@ sequenceDiagram
     Sync-->>UI: disabled
 ```
 
-Die regelmäßige Synchronisierung wird durch „CloudSyncScheduler“ ausgelöst, wenn die Cloud aktiviert ist.## Data Model and Storage Map
+Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
+
+## Data Model and Storage Map
 
 ```mermaid
 erDiagram
@@ -502,12 +530,14 @@ erDiagram
     }
 ```
 
-Physische Speicherdateien:
+Physical storage files:
 
-- Primäre Laufzeit-DB: „${DATA_DIR}/storage.sqlite“.
-- Protokollzeilen anfordern: „${DATA_DIR}/log.txt“ (Kompatibilitäts-/Debug-Artefakt)
-- Strukturierte Anrufnutzlastarchive: „${DATA_DIR}/call_logs/“.
-- optionale Übersetzer-/Request-Debug-Sitzungen: `<repo>/logs/...`## Deployment Topology
+- primary runtime DB: `${DATA_DIR}/storage.sqlite`
+- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact)
+- structured call payload archives: `${DATA_DIR}/call_logs/`
+- optional translator/request debug sessions: `<repo>/logs/...`
+
+## Deployment Topology
 
 ```mermaid
 flowchart LR
@@ -542,205 +572,248 @@ flowchart LR
 
 ### Route and API Modules
 
-- `src/app/api/v1/*`, `src/app/api/v1beta/*`: Kompatibilitäts-APIs
-- `src/app/api/v1/providers/[provider]/*`: dedizierte Routen pro Anbieter (Chat, Einbettungen, Bilder)
-- „src/app/api/providers\*“: Anbieter-CRUD, Validierung, Tests
-- „src/app/api/provider-nodes\*“: benutzerdefinierte kompatible Knotenverwaltung
-- „src/app/api/provider-models“: benutzerdefinierte Modellverwaltung (CRUD)
-- `src/app/api/models/route.ts`: Modellkatalog-API (Aliase + benutzerdefinierte Modelle)
-- `src/app/api/oauth/*`: OAuth/Gerätecodeflüsse
-- „src/app/api/keys\*“: Lebenszyklus des lokalen API-Schlüssels
-- `src/app/api/models/alias`: Alias-Verwaltung
-- `src/app/api/combos*`: Fallback-Combo-Verwaltung
-- „src/app/api/pricing“: Preisüberschreibungen für die Kostenberechnung
-- `src/app/api/settings/proxy`: Proxy-Konfiguration (GET/PUT/DELETE)
-- „src/app/api/settings/proxy/test“: Test der ausgehenden Proxy-Konnektivität (POST)
-- `src/app/api/usage/*`: Nutzungs- und Protokoll-APIs
-- `src/app/api/sync/*` + `src/app/api/cloud/*`: Cloud-Synchronisierung und Cloud-orientierte Helfer
-- `src/app/api/cli-tools/*`: lokale CLI-Konfigurationsschreiber/-prüfer
-- `src/app/api/settings/ip-filter`: IP-Zulassungsliste/Blockliste (GET/PUT)
-- `src/app/api/settings/thinking-budget`: Thinking-Token-Budgetkonfiguration (GET/PUT)
-- `src/app/api/settings/system-prompt`: globale Systemeingabeaufforderung (GET/PUT)
-- `src/app/api/sessions`: Auflistung der aktiven Sitzungen (GET)
-- `src/app/api/rate-limits`: Status des Ratenlimits pro Konto (GET)### Routing and Execution Core
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
+- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
+- `src/app/api/providers*`: provider CRUD, validation, testing
+- `src/app/api/provider-nodes*`: custom compatible node management
+- `src/app/api/provider-models`: custom model management (CRUD)
+- `src/app/api/models/route.ts`: model catalog API (aliases + custom models)
+- `src/app/api/oauth/*`: OAuth/device-code flows
+- `src/app/api/keys*`: local API key lifecycle
+- `src/app/api/models/alias`: alias management
+- `src/app/api/combos*`: fallback combo management
+- `src/app/api/pricing`: pricing overrides for cost calculation
+- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
+- `src/app/api/usage/*`: usage and logs APIs
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
+- `src/app/api/cli-tools/*`: local CLI config writers/checkers
+- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
+- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
+- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
+- `src/app/api/sessions`: active session listing (GET)
+- `src/app/api/rate-limits`: per-account rate limit status (GET)
 
-- „src/sse/handlers/chat.ts“: Anforderungsanalyse, Kombinationsverarbeitung, Kontoauswahlschleife
-- „open-sse/handlers/chatCore.ts“: Übersetzung, Executor-Dispatch, Wiederholungs-/Aktualisierungsbehandlung, Stream-Setup
-- „open-sse/executors/\*“: anbieterspezifisches Netzwerk- und Formatverhalten### Translation Registry and Format Converters
+### Routing and Execution Core
 
-- „open-sse/translator/index.ts“: Übersetzerregistrierung und Orchestrierung
-- Übersetzer anfordern: `open-sse/translator/request/*`
-- Antwortübersetzer: `open-sse/translator/response/*`
-- Formatkonstanten: „open-sse/translator/formats.ts“.### Persistence
+- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
+- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
+- `open-sse/executors/*`: provider-specific network and format behavior
 
-- `src/lib/db/*`: persistente Konfiguration/Status und Domänenpersistenz auf SQLite
-- `src/lib/localDb.ts`: Kompatibilitäts-Neuexport für DB-Module
-- „src/lib/usageDb.ts“: Fassade der Nutzungshistorie/Anrufprotokolle über SQLite-Tabellen## Provider Executor Coverage (Strategy Pattern)
+### Translation Registry and Format Converters
 
-Jeder Anbieter verfügt über einen speziellen Executor, der „BaseExecutor“ (in „open-sse/executors/base.ts“) erweitert und URL-Erstellung, Header-Konstruktion, Wiederholung mit exponentiellem Backoff, Hooks für die Aktualisierung von Anmeldeinformationen und die Orchestrierungsmethode „execute()“ bereitstellt.
+- `open-sse/translator/index.ts`: translator registry and orchestration
+- Request translators: `open-sse/translator/request/*`
+- Response translators: `open-sse/translator/response/*`
+- Format constants: `open-sse/translator/formats.ts`
 
-| Testamentsvollstrecker | Anbieter(n)                                                                                                                                                  | Besondere Handhabung                                                          |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
-| `DefaultExecutor`      | OpenAI, Claude, Gemini, Qwen, Qoder, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamische URL-/Header-Konfiguration pro Anbieter                             |
-| `AntigravityExecutor`  | Google Antigravitation                                                                                                                                       | Benutzerdefinierte Projekt-/Sitzungs-IDs, Wiederholen nach dem Parsen         |
-| `CodexExecutor`        | OpenAI-Codex                                                                                                                                                 | Fügt Systemanweisungen ein und erzwingt den Denkaufwand                       |
-| `CursorExecutor`       | Cursor-IDE                                                                                                                                                   | ConnectRPC-Protokoll, Protobuf-Kodierung, Anforderungssignatur über Prüfsumme |
-| `GithubExecutor`       | GitHub-Copilot                                                                                                                                               | Copilot-Token-Aktualisierung, VSCode-imitierende Header                       |
-| `KiroExecutor`         | AWS CodeWhisperer/Kiro                                                                                                                                       | AWS EventStream-Binärformat → SSE-Konvertierung                               |
-| `GeminiCLIExecutor`    | Gemini CLI                                                                                                                                                   | Aktualisierungszyklus des Google OAuth-Tokens                                 |
+### Persistence
 
-Alle anderen Anbieter (einschließlich benutzerdefinierter kompatibler Knoten) verwenden den „DefaultExecutor“.## Provider Compatibility Matrix
+- `src/lib/db/*`: persistent config/state and domain persistence on SQLite
+- `src/lib/localDb.ts`: compatibility re-export for DB modules
+- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables
 
-| Anbieter         | Formatieren      | Authentifizierung            | Stream           | Nicht-Stream | Token-Aktualisierung | Nutzungs-API                   |
-| ---------------- | ---------------- | ---------------------------- | ---------------- | ------------ | -------------------- | ------------------------------ | ------------------------------ |
-| Claude           | Claude           | API-Schlüssel / OAuth        | ✅               | ✅           | ✅                   | ⚠️ Nur Administrator           |
-| Zwillinge        | Zwillinge        | API-Schlüssel / OAuth        | ✅               | ✅           | ✅                   | ⚠️ Cloud-Konsole               |
-| Gemini CLI       | gemini-cli       | OAuth                        | ✅               | ✅           | ✅                   | ⚠️ Cloud-Konsole               |
-| Antigravitation  | Antigravitation  | OAuth                        | ✅               | ✅           | ✅                   | ✅ Vollständige Kontingent-API |
-| OpenAI           | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Kodex            | Openai-Antworten | OAuth                        | ✅ gezwungen     | ❌           | ✅                   | ✅ Tariflimits                 |
-| GitHub-Copilot   | openai           | OAuth + Copilot-Token        | ✅               | ✅           | ✅                   | ✅ Kontingent-Snapshots        |
-| Cursor           | Cursor           | Benutzerdefinierte Prüfsumme | ✅               | ✅           | ❌                   | ❌                             |
-| Kiro             | kiro             | AWS SSO OIDC                 | ✅ (EventStream) | ❌           | ✅                   | ✅ Nutzungsbeschränkungen      |
-| Qwen             | openai           | OAuth                        | ✅               | ✅           | ✅                   | ⚠️ Auf Anfrage                 |
-| Qoder            | openai           | OAuth (Basic)                | ✅               | ✅           | ✅                   | ⚠️ Auf Anfrage                 |
-| OpenRouter       | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| GLM/Kimi/MiniMax | Claude           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| DeepSeek         | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Groq             | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| xAI (Grok)       | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Mistral          | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Ratlosigkeit     | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Zusammen KI      | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Feuerwerk KI     | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Großhirn         | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| Kohärent         | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             |
-| NVIDIA NIM       | openai           | API-Schlüssel                | ✅               | ✅           | ❌                   | ❌                             | ## Format Translation Coverage |
+## Provider Executor Coverage (Strategy Pattern)
 
-Zu den erkannten Quellformaten gehören:
+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                                     |
+
+All other providers (including custom compatible nodes) use the `DefaultExecutor`.
+
+## Provider Compatibility Matrix
+
+| Provider         | Format           | Auth                  | Stream           | Non-Stream | Token Refresh | Usage API          |
+| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
+| Claude           | claude           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Admin only      |
+| Gemini           | gemini           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Gemini CLI       | gemini-cli       | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Antigravity      | antigravity      | OAuth                 | ✅               | ✅         | ✅            | ✅ Full quota API  |
+| OpenAI           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Codex            | openai-responses | OAuth                 | ✅ forced        | ❌         | ✅            | ✅ Rate limits     |
+| GitHub Copilot   | openai           | OAuth + Copilot Token | ✅               | ✅         | ✅            | ✅ Quota snapshots |
+| Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
+| Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
+| Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Qoder            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Groq             | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| xAI (Grok)       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Mistral          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Perplexity       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Together AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Fireworks AI     | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+
+## Format Translation Coverage
+
+Detected source formats include:
 
 - `openai`
-- „Openai-Antworten“.
-- `Claude`
-- „Zwillinge“.
+- `openai-responses`
+- `claude`
+- `gemini`
 
-Zu den Zielformaten gehören:
+Target formats include:
 
-- OpenAI-Chat/Antworten
+- OpenAI chat/Responses
 - Claude
-- Gemini/Gemini-CLI/Antigravity-Umschlag
+- Gemini/Gemini-CLI/Antigravity envelope
 - Kiro
 - Cursor
 
-Übersetzungen verwenden**OpenAI als Hub-Format**– alle Konvertierungen durchlaufen OpenAI als Zwischenformat:```
+Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
+
+```
 Source Format → OpenAI (hub) → Target Format
+```
 
-````
+Translations are selected dynamically based on source payload shape and provider target format.
 
-Übersetzungen werden dynamisch basierend auf der Form der Quellnutzlast und dem Zielformat des Anbieters ausgewählt.
+Additional processing layers in the translation pipeline:
 
-Zusätzliche Verarbeitungsebenen in der Übersetzungspipeline:
+- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance
+- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)
+- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field
+- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`
 
--**Antwortbereinigung**– Entfernt nicht standardmäßige Felder aus Antworten im OpenAI-Format (sowohl Streaming als auch Nicht-Streaming), um eine strikte SDK-Konformität sicherzustellen
--**Rollennormalisierung**– Konvertiert „Entwickler“ → „System“ für Nicht-OpenAI-Ziele; führt „System“ → „Benutzer“ für Modelle zusammen, die die Systemrolle ablehnen (GLM, ERNIE)
--**Think-Tag-Extraktion**– Analysiert „<think>...</think>“-Blöcke aus dem Inhalt in das Feld „reasoning_content“.
--**Strukturierte Ausgabe**– Konvertiert OpenAI „response_format.json_schema“ in „responseMimeType“ + „responseSchema“ von Gemini## Supported API Endpoints
+## Supported API Endpoints
 
-| Endpunkt | Formatieren | Handler |
-| ------------------------------------------------- | ------------------- | ------------------------------------------------------------------- |
-| `POST /v1/chat/completions` | OpenAI-Chat | `src/sse/handlers/chat.ts` |
-| `POST /v1/messages` | Claude-Nachrichten | Gleicher Handler (automatisch erkannt) |
-| `POST /v1/responses` | OpenAI-Antworten | `open-sse/handlers/responsesHandler.ts` |
-| `POST /v1/embeddings` | OpenAI-Einbettungen | `open-sse/handlers/embeddings.ts` |
-| `GET /v1/embeddings` | Modellliste | API-Route |
-| `POST /v1/images/generations` | OpenAI-Bilder | `open-sse/handlers/imageGeneration.ts` |
-| `GET /v1/images/generations` | Modellliste | API-Route |
-| `POST /v1/providers/{provider}/chat/completions` | OpenAI-Chat | Dedizierter pro Anbieter mit Modellvalidierung |
-| `POST /v1/providers/{provider}/embeddings` | OpenAI-Einbettungen | Dedizierter pro Anbieter mit Modellvalidierung |
-| `POST /v1/providers/{provider}/images/generations` | OpenAI-Bilder | Dedizierter pro Anbieter mit Modellvalidierung |
-| `POST /v1/messages/count_tokens` | Claude Token Count | API-Route |
-| `GET /v1/models` | Liste der OpenAI-Modelle | API-Route (Chat + Einbettung + Bild + benutzerdefinierte Modelle) |
-| `GET /api/models/catalog` | Katalog | Alle Modelle gruppiert nach Anbieter + Typ |
-| `POST /v1beta/models/*:streamGenerateContent` | Zwillinge heimisch | API-Route |
-| `GET/PUT/DELETE /api/settings/proxy` | Proxy-Konfiguration | Netzwerk-Proxy-Konfiguration |
-| `POST /api/settings/proxy/test` | Proxy-Konnektivität | Proxy-Zustands-/Konnektivitätstest-Endpunkt |
-| `GET/POST/DELETE /api/provider-models` | Anbietermodelle | Metadaten des Anbietermodells, die benutzerdefinierte und verwaltete verfügbare Modelle unterstützen |## Bypass Handler
+| Endpoint                                           | Format             | Handler                                                             |
+| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------- |
+| `POST /v1/chat/completions`                        | OpenAI Chat        | `src/sse/handlers/chat.ts`                                          |
+| `POST /v1/messages`                                | Claude Messages    | Same handler (auto-detected)                                        |
+| `POST /v1/responses`                               | OpenAI Responses   | `open-sse/handlers/responsesHandler.ts`                             |
+| `POST /v1/embeddings`                              | OpenAI Embeddings  | `open-sse/handlers/embeddings.ts`                                   |
+| `GET /v1/embeddings`                               | Model listing      | API route                                                           |
+| `POST /v1/images/generations`                      | OpenAI Images      | `open-sse/handlers/imageGeneration.ts`                              |
+| `GET /v1/images/generations`                       | Model listing      | API route                                                           |
+| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat        | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings  | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/images/generations` | OpenAI Images      | Dedicated per-provider with model validation                        |
+| `POST /v1/messages/count_tokens`                   | Claude Token Count | API route                                                           |
+| `GET /v1/models`                                   | OpenAI Models list | API route (chat + embedding + image + custom models)                |
+| `GET /api/models/catalog`                          | Catalog            | All models grouped by provider + type                               |
+| `POST /v1beta/models/*:streamGenerateContent`      | Gemini native      | API route                                                           |
+| `GET/PUT/DELETE /api/settings/proxy`               | Proxy Config       | Network proxy configuration                                         |
+| `POST /api/settings/proxy/test`                    | Proxy Connectivity | Proxy health/connectivity test endpoint                             |
+| `GET/POST/DELETE /api/provider-models`             | Provider Models    | Provider model metadata backing custom and managed available models |
 
-Der Bypass-Handler („open-sse/utils/bypassHandler.ts“) fängt bekannte „Wegwerf“-Anfragen von Claude CLI ab – Warmup-Pings, Titelextraktionen und Token-Zählungen – und gibt eine**falsche Antwort**zurück, ohne Upstream-Anbieter-Tokens zu verbrauchen. Dies wird nur ausgelöst, wenn „User-Agent“ „claude-cli“ enthält.## Request Logger Pipeline
+## Bypass Handler
 
-Der Anforderungslogger („open-sse/utils/requestLogger.ts“) bietet eine 7-stufige Debug-Protokollierungspipeline, die standardmäßig deaktiviert und über „ENABLE_REQUEST_LOGS=true“ aktiviert ist:```
-1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json
-→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt
-````
+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`.
 
-Dateien werden für jede Anforderungssitzung in „<repo>/logs/<session>/“ geschrieben.## Failure Modes and Resilience
+## Request Logging and Artifacts
+
+The older file-based request logger (`open-sse/utils/requestLogger.ts`) is retained only for
+legacy compatibility. The current runtime contract uses:
+
+- `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
 
-- Abklingzeit des Anbieterkontos bei vorübergehenden/Raten-/Authentifizierungsfehlern
-- Konto-Fallback vor fehlgeschlagener Anfrage
-- Combo-Modell-Fallback, wenn der aktuelle Modell-/Anbieterpfad erschöpft ist## 2) Token Expiry
+- provider account cooldown on transient/rate/auth errors
+- account fallback before failing request
+- combo model fallback when current model/provider path is exhausted
 
-- Vorabprüfung und Aktualisierung mit erneutem Versuch für aktualisierbare Anbieter
-  – 401/403-Wiederholungsversuch nach Aktualisierungsversuch im Kernpfad## 3) Stream Safety
+## 2) Token Expiry
 
-- Trennungsfähiger Stream-Controller
-- Übersetzungsstream mit Stream-Ende-Flush und „[FERTIG]“-Behandlung
-- Fallback der Nutzungsschätzung, wenn Metadaten zur Anbieternutzung fehlen## 4) Cloud Sync Degradation
+- pre-check and refresh with retry for refreshable providers
+- 401/403 retry after refresh attempt in core path
 
-– Synchronisierungsfehler werden angezeigt, die lokale Laufzeit wird jedoch fortgesetzt
-– Der Scheduler verfügt über eine wiederholfähige Logik, aber die regelmäßige Ausführung ruft derzeit standardmäßig eine Einzelversuchssynchronisierung auf## 5) Data Integrity
+## 3) Stream Safety
 
-- SQLite-Schemamigrationen und automatische Upgrade-Hooks beim Start
-- Legacy-JSON → SQLite-Migrationskompatibilitätspfad## Observability and Operational Signals
+- disconnect-aware stream controller
+- translation stream with end-of-stream flush and `[DONE]` handling
+- usage estimation fallback when provider usage metadata is missing
 
-Quellen für die Laufzeitsichtbarkeit:
+## 4) Cloud Sync Degradation
 
-- Konsolenprotokolle von „src/sse/utils/logger.ts“.
-- Nutzungsaggregate pro Anfrage in SQLite („usage_history“, „call_logs“, „proxy_logs“)
-- Vierstufige detaillierte Nutzlasterfassungen in SQLite (`request_detail_logs`), wenn `settings.detailed_logs_enabled=true`
-- Statusprotokoll der Textanfrage in „log.txt“ (optional/kompatibel)
-- optionale tiefe Anforderungs-/Übersetzungsprotokolle unter „logs/“, wenn „ENABLE_REQUEST_LOGS=true“ ist
-- Dashboard-Nutzungsendpunkte (`/api/usage/*`) für die UI-Nutzung
+- sync errors are surfaced but local runtime continues
+- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
 
-Die detaillierte Anforderungsnutzlasterfassung speichert bis zu vier JSON-Nutzlaststufen pro weitergeleitetem Anruf:
+## 5) Data Integrity
 
-- Rohanfrage vom Client erhalten
-- Die übersetzte Anfrage wurde tatsächlich an den Upstream gesendet
-- Anbieterantwort als JSON rekonstruiert; Gestreamte Antworten werden zur endgültigen Zusammenfassung plus Stream-Metadaten komprimiert
-  – endgültige Client-Antwort, die von OmniRoute zurückgegeben wird; Gestreamte Antworten werden in derselben kompakten Zusammenfassungsform gespeichert## Security-Sensitive Boundaries
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
-- JWT-Geheimnis („JWT_SECRET“) sichert die Überprüfung/Signatur von Dashboard-Sitzungscookies
-  – Der anfängliche Passwort-Bootstrap („INITIAL_PASSWORD“) sollte explizit für die erstmalige Bereitstellung konfiguriert werden
-- Das HMAC-Geheimnis des API-Schlüssels („API_KEY_SECRET“) sichert das generierte lokale API-Schlüsselformat
-  – Anbietergeheimnisse (API-Schlüssel/Tokens) werden in der lokalen Datenbank gespeichert und sollten auf Dateisystemebene geschützt werden
-  – Cloud-Synchronisierungsendpunkte basieren auf der API-Schlüsselauthentifizierung und der Maschinen-ID-Semantik## Environment and Runtime Matrix
+## Observability and Operational Signals
 
-Vom Code aktiv verwendete Umgebungsvariablen:
+Runtime visibility sources:
 
-- App/Auth: „JWT_SECRET“, „INITIAL_PASSWORD“.
-- Speicher: `DATA_DIR`
-- Kompatibles Knotenverhalten: „ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE“.
-- Optionale Speicherbasisüberschreibung (Linux/macOS, wenn „DATA_DIR“ nicht festgelegt ist): „XDG_CONFIG_HOME“.
-- Sicherheits-Hashing: „API_KEY_SECRET“, „MACHINE_ID_SALT“.
-- Protokollierung: „ENABLE_REQUEST_LOGS“.
-- Synchronisierungs-/Cloud-URLing: „NEXT_PUBLIC_BASE_URL“, „NEXT_PUBLIC_CLOUD_URL“.
-- Ausgehender Proxy: „HTTP_PROXY“, „HTTPS_PROXY“, „ALL_PROXY“, „NO_PROXY“ und Varianten in Kleinbuchstaben
-- SOCKS5-Funktionsflags: „ENABLE_SOCKS5_PROXY“, „NEXT_PUBLIC_ENABLE_SOCKS5_PROXY“.
-- Plattform-/Laufzeit-Helfer (keine App-spezifische Konfiguration): „APPDATA“, „NODE_ENV“, „PORT“, „HOSTNAME“.## Known Architectural Notes
+- console logs from `src/sse/utils/logger.ts`
+- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true`
+- textual request status log in `log.txt` (optional/compat)
+- optional 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
 
-1. „usageDb“ und „localDb“ verwenden dieselbe Basisverzeichnisrichtlinie („DATA_DIR“ -> „XDG_CONFIG_HOME/omniroute“ -> „~/.omniroute“) bei der Migration älterer Dateien.
-2. „/api/v1/route.ts“ delegiert an denselben einheitlichen Katalog-Builder, der von „/api/v1/models“ verwendet wird (`src/app/api/v1/models/catalog.ts`), um semantische Abweichungen zu vermeiden.
-3. Der Anforderungslogger schreibt bei Aktivierung vollständige Header/Textkörper. Behandeln Sie das Protokollverzeichnis als vertraulich.
-4. Das Cloud-Verhalten hängt von der korrekten „NEXT_PUBLIC_BASE_URL“ und der Erreichbarkeit des Cloud-Endpunkts ab.
-5. Das Verzeichnis „open-sse/“ wird als „@omniroute/open-sse“**npm-Workspace-Paket**veröffentlicht. Der Quellcode importiert es über „@omniroute/open-sse/...“ (aufgelöst durch Next.js „transpilePackages“). Dateipfade in diesem Dokument verwenden aus Konsistenzgründen weiterhin den Verzeichnisnamen „open-sse/“.
-6. Diagramme im Dashboard verwenden**Recharts**(SVG-basiert) für zugängliche, interaktive Analysevisualisierungen (Modellnutzungs-Balkendiagramme, Anbieteraufschlüsselungstabellen mit Erfolgsquoten).
-7. E2E-Tests verwenden**Playwright**(`tests/e2e/`) und werden über `npm run test:e2e` ausgeführt. Unit-Tests verwenden**Node.js Test Runner**(`tests/unit/`) und werden über `npm run test:unit` ausgeführt. Der Quellcode unter „src/“ ist**TypeScript**(`.ts`/`.tsx`); Der `open-sse/`-Arbeitsbereich bleibt JavaScript (`.js`).
-8. Die Einstellungsseite ist in 5 Registerkarten unterteilt: Sicherheit, Routing (6 globale Strategien: Fill-First, Round-Robin, P2C, Random, Least-Used, Cost-Optimized), Resilience (bearbeitbare Ratenlimits, Leistungsschalter, Richtlinien), AI (Thinking Budget, System Prompt, Prompt Cache), Advanced (Proxy).## Operational Verification Checklist
+Detailed request payload capture stores up to four JSON payload stages per routed call:
 
-- Aus der Quelle erstellen: „npm run build“.
-- Docker-Image erstellen: `docker build -t omniroute .`
-- Starten Sie den Dienst und überprüfen Sie:
+- raw request received from the client
+- translated request actually sent upstream
+- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata
+- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form
+
+## Security-Sensitive Boundaries
+
+- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
+- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning
+- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format
+- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level
+- Cloud sync endpoints rely on API key auth + machine id semantics
+
+## Environment and Runtime Matrix
+
+Environment variables actively used by code:
+
+- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Storage: `DATA_DIR`
+- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
+- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME`
+- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
+- Logging: `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`
+- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+
+## Known Architectural Notes
+
+1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.
+2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift.
+3. Request logger writes full headers/body when enabled; treat log directory as sensitive.
+4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability.
+5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency.
+6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates).
+7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`).
+8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies, **Context Relay** handoff config), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
+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 24+ detection**: `/api/settings/require-login` returns `nodeVersion` and `nodeCompatible` fields. The login page renders a warning banner when the runtime is incompatible.
+
+## Operational Verification Checklist
+
+- Build from source: `npm run build`
+- Build Docker image: `docker build -t omniroute .`
+- Start service and verify:
 - `GET /api/settings`
 - `GET /api/v1/models`
-  – Die Basis-URL des CLI-Ziels sollte „http://<host>:20128/v1“ lauten, wenn „PORT=20128“.
+- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`

docs/i18n/de/docs/CODEBASE_DOCUMENTATION.md

@@ -387,7 +387,7 @@ import "./request/claude-to-openai.js"; // ← self-registers
 | `stream.ts`        | **SSE Transform Stream**– die zentrale Streaming-Pipeline. Zwei Modi: „TRANSLATE“ (Vollformatübersetzung) und „PASSTHROUGH“ (Nutzung normalisieren + extrahieren). Verarbeitet Chunk-Pufferung, Nutzungsschätzung und Inhaltslängenverfolgung. Pro-Stream-Encoder-/Decoder-Instanzen vermeiden den gemeinsamen Status. |
 | `streamHelpers.ts` | Low-Level-SSE-Dienstprogramme: „parseSSELine“ (leerraumtolerant), „hasValuableContent“ (filtert leere Blöcke für OpenAI/Claude/Gemini), „fixInvalidId“, „formatSSE“ (formatbewusste SSE-Serialisierung mit „perf_metrics“-Bereinigung).                                                                                |
 | `usageTracking.ts` | Extraktion der Token-Nutzung aus jedem Format (Claude/OpenAI/Gemini/Responses), Schätzung mit separaten Zeichen-pro-Token-Verhältnissen für Tools/Nachrichten, Pufferzugabe (2000 Token-Sicherheitsspielraum), formatspezifische Feldfilterung, Konsolenprotokollierung mit ANSI-Farben.                               |
-| `requestLogger.ts` | Dateibasierte Anforderungsprotokollierung (Opt-in über „ENABLE_REQUEST_LOGS=true“). Erstellt Sitzungsordner mit nummerierten Dateien: „1_req_client.json“ → „7_res_client.txt“. Alle E/A erfolgen asynchron (Fire-and-Forget). Maskiert sensible Header.                                                               |
+| `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` | Fängt bestimmte Muster von Claude CLI ab (Titelextraktion, Aufwärmen, Zählung) und gibt gefälschte Antworten zurück, ohne einen Anbieter anzurufen. Unterstützt sowohl Streaming als auch Nicht-Streaming. Absichtlich auf den Claude-CLI-Bereich beschränkt.                                                          |
 | `networkProxy.ts`  | Löst die ausgehende Proxy-URL für einen bestimmten Anbieter mit der Priorität auf: anbieterspezifische Konfiguration → globale Konfiguration → Umgebungsvariablen („HTTPS_PROXY“/„HTTP_PROXY“/„ALL_PROXY“). Unterstützt „NO_PROXY“-Ausschlüsse. Speichert die Konfiguration 30 Sekunden lang im Cache.                 | #### SSE Streaming Pipeline |
 

docs/i18n/de/docs/FEATURES.md

@@ -4,102 +4,168 @@
 
 ---
 
-Visuelle Anleitung zu jedem Abschnitt des OmniRoute-Dashboards.---
+
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
 
 ## 🔌 Providers
 
-Verwalten Sie KI-Anbieterverbindungen: OAuth-Anbieter (Claude Code, Codex, Gemini CLI), API-Schlüsselanbieter (Groq, DeepSeek, OpenRouter) und kostenlose Anbieter (Qoder, Qwen, Kiro). Bei Kiro-Konten ist die Nachverfolgung des Guthabens möglich – verbleibende Guthaben, Gesamtguthaben und Verlängerungsdatum sind im Dashboard → Nutzung sichtbar.![Providers Dashboard](screenshots/01-providers.png)
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+![Providers Dashboard](screenshots/01-providers.png)
 
 ---
 
 ## 🎨 Combos
 
-Erstellen Sie Modell-Routing-Kombinationen mit 6 Strategien: Priorität, gewichtet, Round-Robin, zufällig, am wenigsten verwendet und kostenoptimiert. Jede Kombination verkettet mehrere Modelle mit automatischem Fallback und umfasst schnelle Vorlagen und Bereitschaftsprüfungen.![Combos Dashboard](screenshots/02-combos.png)
+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.
+
+![Combos Dashboard](screenshots/02-combos.png)
 
 ---
 
 ## 📊 Analytics
 
-Umfassende Nutzungsanalysen mit Token-Verbrauch, Kostenschätzungen, Aktivitäts-Heatmaps, wöchentlichen Verteilungsdiagrammen und Aufschlüsselungen pro Anbieter.![Analytics Dashboard](screenshots/03-analytics.png)
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
 
 ---
 
 ## 🏥 System Health
 
-Echtzeitüberwachung: Betriebszeit, Speicher, Version, Latenzperzentile (p50/p95/p99), Cache-Statistiken und Leistungsschalterzustände des Anbieters.![Health Dashboard](screenshots/04-health.png)
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+![Health Dashboard](screenshots/04-health.png)
 
 ---
 
 ## 🔧 Translator Playground
 
-Vier Modi zum Debuggen von API-Übersetzungen:**Playground**(Formatkonverter),**Chat Tester**(Live-Anfragen),**Test Bench**(Batch-Tests) und**Live Monitor**(Echtzeit-Stream).![Translator Playground](screenshots/05-translator.png)
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+![Translator Playground](screenshots/05-translator.png)
 
 ---
 
 ## 🎮 Model Playground _(v2.0.9+)_
 
-Testen Sie jedes Modell direkt vom Dashboard aus. Wählen Sie Anbieter, Modell und Endpunkt aus, schreiben Sie Eingabeaufforderungen mit Monaco Editor, streamen Sie Antworten in Echtzeit, brechen Sie mitten im Stream ab und sehen Sie sich Timing-Metriken an.---
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
 
 ## 🎨 Themes _(v2.0.5+)_
 
-Anpassbare Farbthemen für das gesamte Dashboard. Wählen Sie aus 7 voreingestellten Farben (Koralle, Blau, Rot, Grün, Violett, Orange, Cyan) oder erstellen Sie ein individuelles Design, indem Sie eine beliebige Hex-Farbe auswählen. Unterstützt Hell-, Dunkel- und Systemmodus.---
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
 
 ## ⚙️ Settings
 
-Umfangreiches Einstellungsfeld mit Registerkarten:
+Comprehensive settings panel with tabs:
 
--**Allgemein**– Systemspeicher, Backup-Management (Datenbank exportieren/importieren) -**Erscheinungsbild**– Themenauswahl (Dunkel/Hell/System), Voreinstellungen für Farbthemen und benutzerdefinierte Farben, Sichtbarkeit des Gesundheitsprotokolls, Steuerelemente für die Sichtbarkeit von Elementen in der Seitenleiste -**Sicherheit**– API-Endpunktschutz, benutzerdefinierte Anbieterblockierung, IP-Filterung, Sitzungsinformationen -**Routing**– Modellaliase, Verschlechterung der Hintergrundaufgabe -**Resilienz**– Persistenz der Ratenbegrenzung, Leistungsschalter-Optimierung, automatische Deaktivierung gesperrter Konten, Überwachung des Anbieterablaufs -**Erweitert**– Konfigurationsüberschreibungen, Konfigurations-Audit-Trail, Fallback-Verschlechterungsmodus![Settings Dashboard](screenshots/06-settings.png)
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring, **Context Relay** handoff threshold and summary model configuration
+- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
+
+![Settings Dashboard](screenshots/06-settings.png)
 
 ---
 
 ## 🔧 CLI Tools
 
-Ein-Klick-Konfiguration für KI-Codierungstools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor und Factory Droid. Bietet automatisches Anwenden/Zurücksetzen der Konfiguration, Verbindungsprofile und Modellzuordnung.![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
 
 ---
 
 ## 🤖 CLI Agents _(v2.0.11+)_
 
-Dashboard zum Erkennen und Verwalten von CLI-Agenten. Zeigt ein Raster mit 14 integrierten Agenten (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) mit:
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
 
--**Installationsstatus**– Installiert/Nicht gefunden mit Versionserkennung -**Protokollabzeichen**– stdio, HTTP usw. -**Benutzerdefinierte Agents**– Registrieren Sie jedes CLI-Tool über ein Formular (Name, Binärdatei, Versionsbefehl, Spawn-Argumente). -**CLI-Fingerabdruck-Abgleich**– Umschalten pro Anbieter, um native CLI-Anfragesignaturen abzugleichen, wodurch das Verbotsrisiko verringert und gleichzeitig die Proxy-IP erhalten bleibt---
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🔗 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
+
+---
 
 ## 🖼️ Media _(v2.0.3+)_
 
-Generieren Sie Bilder, Videos und Musik über das Dashboard. Unterstützt OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open und MusicGen.---
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
 
 ## 📝 Request Logs
 
-Echtzeit-Anfrageprotokollierung mit Filterung nach Anbieter, Modell, Konto und API-Schlüssel. Zeigt Statuscodes, Token-Nutzung, Latenz und Antwortdetails an.![Usage Logs](screenshots/08-usage.png)
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+![Usage Logs](screenshots/08-usage.png)
 
 ---
 
 ## 🌐 API Endpoint
 
-Ihr einheitlicher API-Endpunkt mit Aufschlüsselung der Funktionen: Chat-Abschlüsse, Antwort-API, Einbettungen, Bildgenerierung, Neuranking, Audiotranskription, Text-to-Speech, Moderationen und registrierte API-Schlüssel. Cloudflare Quick Tunnel-Integration und Cloud-Proxy-Unterstützung für Fernzugriff.![Endpoint Dashboard](screenshots/09-endpoint.png)
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)
 
 ---
 
 ## 🔑 API Key Management
 
-API-Schlüssel erstellen, festlegen und widerrufen. Jeder Schlüssel kann auf bestimmte Modelle/Anbieter mit Vollzugriff oder Nur-Lese-Berechtigungen beschränkt werden. Visuelle Schlüsselverwaltung mit Nutzungsverfolgung.---
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
 
 ## 📋 Audit Log
 
-Verwaltungsaktionsverfolgung mit Filterung nach Aktionstyp, Akteur, Ziel, IP-Adresse und Zeitstempel. Vollständiger Sicherheitsereignisverlauf.---
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
 
 ## 🖥️ Desktop Application
 
-Native Electron-Desktop-App für Windows, macOS und Linux. Führen Sie OmniRoute als eigenständige Anwendung mit Taskleistenintegration, Offline-Unterstützung, automatischer Aktualisierung und Installation mit einem Klick aus.
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
 
-Hauptmerkmale:
+Key features:
 
-- Abfrage der Serverbereitschaft (kein leerer Bildschirm beim Kaltstart)
-- Taskleiste mit Portverwaltung
-- Inhaltssicherheitsrichtlinie
-- Einzelinstanzsperre
-- Automatische Aktualisierung beim Neustart
-- Plattformabhängige Benutzeroberfläche (Ampeln für macOS, Standardtitelleiste für Windows/Linux)
-- Hardened Electron Build-Paketierung – symbolisch verknüpfte „node_modules“ im Standalone-Bundle werden vor dem Paketieren erkannt und abgelehnt, wodurch eine Laufzeitabhängigkeit von der Build-Maschine verhindert wird (v2.5.5+)
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
 
-📖 Die vollständige Dokumentation finden Sie unter [`electron/README.md`](../electron/README.md).
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/de/docs/TROUBLESHOOTING.md

@@ -4,68 +4,141 @@
 
 ---
 
-Häufige Probleme und Lösungen für OmniRoute.---
+Common problems and solutions for OmniRoute.
+
+---
 
 ## Quick Fixes
 
-| Problem                                    | Lösung                                                                                |
-| ------------------------------------------ | ------------------------------------------------------------------------------------- | --- |
-| Erster Login funktioniert nicht            | Legen Sie „INITIAL_PASSWORD“ in „.env“ fest (keine fest codierte Standardeinstellung) |
-| Dashboard wird am falschen Port geöffnet   | Setzen Sie „PORT=20128“ und „NEXT_PUBLIC_BASE_URL=http://localhost:20128“             |
-| Keine Anforderungsprotokolle unter „logs/“ | Setzen Sie „ENABLE_REQUEST_LOGS=true“                                                 |
-| EACCES: Berechtigung verweigert            | Setzen Sie „DATA_DIR=/path/to/writable/dir“, um „~/.omniroute“ zu überschreiben       |
-| Routing-Strategie wird nicht gespeichert   | Update auf v1.4.11+ (Zod-Schema-Korrektur für Einstellungspersistenz)                 | --- |
+| 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      | You may be on Node.js 24+ — see [Node.js Compatibility](#nodejs-compatibility) 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 Node.js 24+. The `better-sqlite3` native binary is not compatible with Node.js 24, which causes a fatal crash when the server tries to initialize the database.
+
+**Symptoms:**
+
+- Login page shows a blank screen or a server error
+- Console shows `Error: Module did not self-register` or similar native binding errors
+- Starting with v3.5.5, the login page shows an **orange warning banner** with your Node version if incompatibility is detected
+
+**Fix:**
+
+1. Install Node.js 22 LTS (recommended):
+   ```bash
+   nvm install 22
+   nvm use 22
+   ```
+2. Verify your version: `node --version` should show `v22.x.x`
+3. Reinstall OmniRoute: `npm install -g omniroute`
+4. Restart: `omniroute`
+
+> **Supported versions:** Node.js 18, 20, or 22 LTS. Node.js 24+ is **not supported**.
+
+---
+
+## 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+.
+
+---
 
 ## Provider Issues
 
 ### "Language model did not provide messages"
 
-**Ursache:**Anbieterkontingent erschöpft.
+**Cause:** Provider quota exhausted.
 
 **Fix:**
 
-1. Überprüfen Sie den Quoten-Tracker im Dashboard
-2. Verwenden Sie eine Kombination mit Fallback-Stufen
-3. Wechseln Sie zum günstigeren/kostenlosen Tarif### Rate Limiting
+1. Check dashboard quota tracker
+2. Use a combo with fallback tiers
+3. Switch to cheaper/free tier
 
-**Ursache:**Das Abonnementkontingent ist erschöpft.
+### Rate Limiting
+
+**Cause:** Subscription quota exhausted.
 
 **Fix:**
 
-- Fallback hinzufügen: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-- Verwenden Sie GLM/MiniMax als günstiges Backup### OAuth Token Expired
+- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Use GLM/MiniMax as cheap backup
 
-OmniRoute aktualisiert Token automatisch. Wenn die Probleme weiterhin bestehen:
+### OAuth Token Expired
 
-1. Dashboard → Anbieter → Erneut verbinden
-2. Löschen Sie die Provider-Verbindung und fügen Sie sie erneut hinzu---
+OmniRoute auto-refreshes tokens. If issues persist:
+
+1. Dashboard → Provider → Reconnect
+2. Delete and re-add the provider connection
+
+---
 
 ## Cloud Issues
 
 ### Cloud Sync Errors
 
-1. Überprüfen Sie, ob „BASE_URL“ auf Ihre laufende Instanz verweist (z. B. „http://localhost:20128“).
-2. Überprüfen Sie, ob „CLOUD_URL“ auf Ihren Cloud-Endpunkt verweist (z. B. „https://omniroute.dev“).
-3. Halten Sie die Werte von „NEXT*PUBLIC*\*“ an den serverseitigen Werten ausgerichtet### Cloud `stream=false` Returns 500
+1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
+2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
+3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
 
-**Symptom:**„Unerwartetes Token „d“...“ auf dem Cloud-Endpunkt für Nicht-Streaming-Aufrufe.
+### Cloud `stream=false` Returns 500
 
-**Ursache:**Upstream gibt SSE-Nutzdaten zurück, während der Client JSON erwartet.
+**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
 
-**Problemumgehung:**Verwenden Sie „stream=true“ für Cloud-Direktaufrufe. Die lokale Laufzeit umfasst SSE→JSON-Fallback.### Cloud Says Connected but "Invalid API key"
+**Cause:** Upstream returns SSE payload while client expects JSON.
 
-1. Erstellen Sie einen neuen Schlüssel aus dem lokalen Dashboard („/api/keys“).
-2. Führen Sie die Cloud-Synchronisierung aus: Cloud aktivieren → Jetzt synchronisieren
-3. Alte/nicht synchronisierte Schlüssel können in der Cloud immer noch „401“ zurückgeben---
+**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
+
+### Cloud Says Connected but "Invalid API key"
+
+1. Create a fresh key from local dashboard (`/api/keys`)
+2. Run cloud sync: Enable Cloud → Sync Now
+3. Old/non-synced keys can still return `401` on cloud
+
+---
 
 ## Docker Issues
 
 ### CLI Tool Shows Not Installed
 
-1. Überprüfen Sie die Laufzeitfelder: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
-2. Für den tragbaren Modus: Verwenden Sie das Image-Ziel „runner-cli“ (gebündelte CLIs).
-3. Für den Host-Mount-Modus: Legen Sie „CLI_EXTRA_PATHS“ fest und mounten Sie das Host-Bin-Verzeichnis als schreibgeschützt
-4. Wenn „installed=true“ und „runnable=false“: Binärdatei wurde gefunden, aber die Integritätsprüfung ist fehlgeschlagen### Quick Runtime Validation
+1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. For portable mode: use image target `runner-cli` (bundled CLIs)
+3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
+4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
+
+### Quick Runtime Validation
 
 ```bash
 curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
@@ -79,16 +152,22 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
 
 ### High Costs
 
-1. Überprüfen Sie die Nutzungsstatistiken im Dashboard → Nutzung
-2. Primärmodell auf GLM/MiniMax umstellen
-3. Nutzen Sie den kostenlosen Tarif (Gemini CLI, Qoder) für unkritische Aufgaben
-4. Legen Sie Kostenbudgets pro API-Schlüssel fest: Dashboard → API-Schlüssel → Budget---
+1. Check usage stats in Dashboard → Usage
+2. Switch primary model to GLM/MiniMax
+3. Use free tier (Gemini CLI, Qoder) for non-critical tasks
+4. Set cost budgets per API key: Dashboard → API Keys → Budget
+
+---
 
 ## Debugging
 
-### Enable Request Logs
+### Enable Log Files
 
-Setzen Sie „ENABLE_REQUEST_LOGS=true“ in Ihrer „.env“-Datei. Protokolle werden im Verzeichnis „logs/“ angezeigt.### Check Provider Health
+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
 
 ```bash
 # Health dashboard
@@ -100,102 +179,136 @@ curl http://localhost:20128/api/monitoring/health
 
 ### Runtime Storage
 
-- Hauptstatus: „${DATA_DIR}/storage.sqlite“ (Anbieter, Kombinationen, Aliase, Schlüssel, Einstellungen)
-- Verwendung: SQLite-Tabellen in „storage.sqlite“ („usage_history“, „call_logs“, „proxy_logs“) + optional „${DATA_DIR}/log.txt“ und „${DATA_DIR}/call_logs/“.
-- Protokolle anfordern: `<repo>/logs/...` (wenn `ENABLE_REQUEST_LOGS=true`)---
+- 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}/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
+
+---
 
 ## Circuit Breaker Issues
 
 ### Provider stuck in OPEN state
 
-Wenn der Leistungsschalter eines Anbieters OFFEN ist, werden Anfragen blockiert, bis die Abklingzeit abgelaufen ist.
+When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
 
 **Fix:**
 
-1. Gehen Sie zu**Dashboard → Einstellungen → Resilienz**
-2. Überprüfen Sie die Leistungsschalterkarte des betroffenen Anbieters
-3. Klicken Sie auf**Alle zurücksetzen**, um alle Unterbrecher zu löschen, oder warten Sie, bis die Abklingzeit abgelaufen ist
-4. Stellen Sie vor dem Zurücksetzen sicher, dass der Anbieter tatsächlich verfügbar ist### Provider keeps tripping the circuit breaker
+1. Go to **Dashboard → Settings → Resilience**
+2. Check the circuit breaker card for the affected provider
+3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
+4. Verify the provider is actually available before resetting
 
-Wenn ein Anbieter wiederholt in den OPEN-Zustand wechselt:
+### Provider keeps tripping the circuit breaker
 
-1. Überprüfen Sie**Dashboard → Health → Provider Health**auf das Fehlermuster
-2. Gehen Sie zu**Einstellungen → Ausfallsicherheit → Anbieterprofile**und erhöhen Sie den Fehlerschwellenwert
-3. Überprüfen Sie, ob der Anbieter die API-Grenzwerte geändert hat oder eine erneute Authentifizierung erfordert
-4. Überprüfen Sie die Latenz-Telemetrie – hohe Latenz kann zu zeitüberschreitungsbedingten Fehlern führen---
+If a provider repeatedly enters OPEN state:
+
+1. Check **Dashboard → Health → Provider Health** for the failure pattern
+2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
+3. Check if the provider has changed API limits or requires re-authentication
+4. Review latency telemetry — high latency may cause timeout-based failures
+
+---
 
 ## Audio Transcription Issues
 
 ### "Unsupported model" error
 
-- Stellen Sie sicher, dass Sie das richtige Präfix verwenden: „deepgram/nova-3“ oder „assemblyai/best“.
-- Überprüfen Sie, ob der Anbieter unter**Dashboard → Anbieter**verbunden ist.### Transcription returns empty or fails
+- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
+- Verify the provider is connected in **Dashboard → Providers**
 
-- Überprüfen Sie die unterstützten Audioformate: „mp3“, „wav“, „m4a“, „flac“, „ogg“, „webm“.
-- Stellen Sie sicher, dass die Dateigröße innerhalb der Anbietergrenzen liegt (normalerweise < 25 MB).
-- Überprüfen Sie die Gültigkeit des API-Schlüssels des Anbieters auf der Anbieterkarte---
+### Transcription returns empty or fails
+
+- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Verify file size is within provider limits (typically < 25MB)
+- Check provider API key validity in the provider card
+
+---
 
 ## Translator Debugging
 
-Verwenden Sie**Dashboard → Übersetzer**, um Formatübersetzungsprobleme zu beheben:
+Use **Dashboard → Translator** to debug format translation issues:
 
-| Modus            | Wann zu verwenden                                                                                                                       |
-| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| **Spielplatz**   | Vergleichen Sie Eingabe-/Ausgabeformate nebeneinander – fügen Sie eine fehlgeschlagene Anfrage ein, um zu sehen, wie sie übersetzt wird |
-| **Chat-Tester**  | Senden Sie Live-Nachrichten und überprüfen Sie die vollständige Anfrage-/Antwort-Nutzlast einschließlich Header                         |
-| **Prüfstand**    | Führen Sie Stapeltests über Formatkombinationen hinweg durch, um herauszufinden, welche Übersetzungen fehlerhaft sind                   |
-| **Live-Monitor** | Beobachten Sie den Anfragefluss in Echtzeit, um zeitweise auftretende Übersetzungsprobleme zu erkennen                                  | ### Common format issues |
+| Mode             | When to Use                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| **Playground**   | Compare input/output formats side by side — paste a failing request to see how it translates |
+| **Chat Tester**  | Send live messages and inspect the full request/response payload including headers           |
+| **Test Bench**   | Run batch tests across format combinations to find which translations are broken             |
+| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues                        |
 
--**Thinking-Tags werden nicht angezeigt**– Überprüfen Sie, ob der Zielanbieter Thinking und die Einstellung des Thinking-Budgets unterstützt -**Tool-Aufrufe löschen**– Bei einigen Formatübersetzungen werden möglicherweise nicht unterstützte Felder entfernt. im Playground-Modus überprüfen -**Systemaufforderung fehlt**– Claude und Gemini gehen unterschiedlich mit Systemaufforderungen um; Überprüfen Sie die Übersetzungsausgabe -**SDK gibt Rohzeichenfolge statt Objekt zurück**– In Version 1.1.0 behoben: Antwortbereinigung entfernt jetzt nicht standardmäßige Felder (`x_groq`, `usage_breakdown` usw.), die zu OpenAI SDK Pydantic-Validierungsfehlern führen -**GLM/ERNIE lehnt „System“-Rolle ab**– In Version 1.1.0 behoben: Der Rollennormalisierer führt automatisch Systemmeldungen in Benutzermeldungen für inkompatible Modelle zusammen -**Rolle „Entwickler“ nicht erkannt**– In Version 1.1.0 behoben: Für Nicht-OpenAI-Anbieter automatisch in „System“ konvertiert -**`json_schema` funktioniert nicht mit Gemini**– In v1.1.0 behoben: `response_format` wird jetzt in Geminis `responseMimeType` + `responseSchema` konvertiert---
+### Common format issues
+
+- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
+- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
+- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
+- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures
+- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
+- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers
+- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema`
+
+---
 
 ## Resilience Settings
 
 ### Auto rate-limit not triggering
 
-– Die automatische Ratenbegrenzung gilt nur für API-Schlüsselanbieter (nicht OAuth/Abonnement).
+- Auto rate-limit only applies to API key providers (not OAuth/subscription)
+- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
+- Check if the provider returns `429` status codes or `Retry-After` headers
 
-- Überprüfen Sie, ob in**Einstellungen → Ausfallsicherheit → Anbieterprofile**die automatische Ratenbegrenzung aktiviert ist
-- Überprüfen Sie, ob der Anbieter „429“-Statuscodes oder „Retry-After“-Header zurückgibt### Tuning exponential backoff
+### Tuning exponential backoff
 
-Anbieterprofile unterstützen diese Einstellungen:
+Provider profiles support these settings:
 
--**Basisverzögerung**– Anfängliche Wartezeit nach dem ersten Fehler (Standard: 1 s) -**Max. Verzögerung**– Maximale Wartezeitobergrenze (Standard: 30 s) -**Multiplikator**– Wie viel Verzögerung pro aufeinanderfolgendem Fehler erhöht werden soll (Standard: 2x)### Anti-thundering herd
+- **Base delay** — Initial wait time after first failure (default: 1s)
+- **Max delay** — Maximum wait time cap (default: 30s)
+- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
 
-Wenn viele gleichzeitige Anfragen einen Anbieter mit begrenzter Rate treffen, verwendet OmniRoute Mutex + automatische Ratenbegrenzung, um Anfragen zu serialisieren und kaskadierende Fehler zu verhindern. Dies geschieht automatisch für API-Schlüsselanbieter.---
+### Anti-thundering herd
+
+When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
+
+---
 
 ## Optional RAG / LLM failure taxonomy (16 problems)
 
-Einige OmniRoute-Benutzer platzieren das Gateway vor RAG- oder Agent-Stacks. In diesen Setups ist es üblich, ein seltsames Muster zu erkennen: OmniRoute sieht fehlerfrei aus (Anbieter aktiv, Routing-Profile in Ordnung, keine Ratenbegrenzungswarnungen), aber die endgültige Antwort ist immer noch falsch.
+Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong.
 
-In der Praxis gehen diese Vorfälle meist von der nachgelagerten RAG-Pipeline aus, nicht vom Gateway selbst.
+In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself.
 
-Wenn Sie ein gemeinsames Vokabular zur Beschreibung dieser Fehler wünschen, können Sie die WFGY ProblemMap verwenden, eine externe MIT-Lizenztextressource, die sechzehn wiederkehrende RAG-/LLM-Fehlermuster definiert. Auf hohem Niveau umfasst es:
+If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers:
 
-- Abrufdrift und gebrochene Kontextgrenzen
-- leere oder veraltete Indizes und Vektorspeicher
-- Einbettung versus semantische Nichtübereinstimmung
-- Probleme mit der Eingabeaufforderung und dem Kontextfenster
-- Zusammenbruch der Logik und übertriebene Antworten
-- Fehler bei der Koordinierung langer Ketten und Agenten
-- Multiagentengedächtnis und Rollendrift
-- Probleme bei der Bereitstellung und Bootstrap-Reihenfolge
+- retrieval drift and broken context boundaries
+- empty or stale indexes and vector stores
+- embedding versus semantic mismatch
+- prompt assembly and context window issues
+- logic collapse and overconfident answers
+- long chain and agent coordination failures
+- multi agent memory and role drift
+- deployment and bootstrap ordering problems
 
-Die Idee ist einfach:
+The idea is simple:
 
-1. Wenn Sie eine schlechte Antwort untersuchen, erfassen Sie Folgendes:
-   - Benutzeraufgabe und -anfrage
-   - Routen- oder Anbieterkombination in OmniRoute
-   - jeglicher RAG-Kontext, der nachgelagert verwendet wird (abgerufene Dokumente, Tool-Aufrufe usw.)
-2. Ordnen Sie den Vorfall einer oder zwei WFGY ProblemMap-Nummern („Nr. 1“ … „Nr. 16“) zu.
-3. Speichern Sie die Nummer in Ihrem eigenen Dashboard, Runbook oder Incident-Tracker neben den OmniRoute-Protokollen.
-4. Verwenden Sie die entsprechende WFGY-Seite, um zu entscheiden, ob Sie Ihren RAG-Stack, Retriever oder Ihre Routing-Strategie ändern müssen.
+1. When you investigate a bad response, capture:
+   - user task and request
+   - route or provider combo in OmniRoute
+   - any RAG context used downstream (retrieved documents, tool calls, etc)
+2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`).
+3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs.
+4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy.
 
-Volltext und konkrete Rezepte gibt es hier (MIT-Lizenz, nur Text):
+Full text and concrete recipes live here (MIT license, text only):
 
 [WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
 
-Sie können diesen Abschnitt ignorieren, wenn Sie keine RAG- oder Agent-Pipelines hinter OmniRoute ausführen.---
+You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute.
+
+---
 
 ## Still Stuck?
 
--**GitHub-Probleme**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -**Architektur**: Interne Details finden Sie unter [`docs/ARCHITECTURE.md`](ARCHITECTURE.md). -**API-Referenz**: Siehe [`docs/API_REFERENCE.md`](API_REFERENCE.md) für alle Endpunkte -**Gesundheits-Dashboard**: Überprüfen Sie**Dashboard → Gesundheit**auf den Echtzeit-Systemstatus -**Übersetzer**: Verwenden Sie**Dashboard → Übersetzer**, um Formatprobleme zu beheben
+- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
+- **Translator**: Use **Dashboard → Translator** to debug format issues

docs/i18n/de/docs/VM_DEPLOYMENT_GUIDE.md

@@ -100,7 +100,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/de/llm.txt

@@ -0,0 +1,476 @@
+# OmniRoute (Deutsch)
+
+🌐 **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.
+
+## Übersicht
+
+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)
+
+### Sicherheit
+- **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/es/docs/ARCHITECTURE.md

@@ -4,80 +4,91 @@
 
 ---
 
-_Última actualización: 2026-03-28_## Executive Summary
+_Last updated: 2026-03-28_
 
-OmniRoute es un panel y una puerta de enlace de enrutamiento de IA local creado en Next.js.
-Proporciona un único punto final compatible con OpenAI (`/v1/*`) y enruta el tráfico a través de múltiples proveedores ascendentes con traducción, respaldo, actualización de tokens y seguimiento de uso.
+## Executive Summary
 
-Capacidades principales:
+OmniRoute is a local AI routing gateway and dashboard built on Next.js.
+It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
 
-- Superficie API compatible con OpenAI para CLI/herramientas (28 proveedores)
-- Traducción de solicitudes/respuestas entre formatos de proveedores.
-- Modelo combinado de respaldo (secuencia multimodelo)
-- Respaldo a nivel de cuenta (varias cuentas por proveedor)
-- Gestión de conexión de proveedor de claves OAuth + API
-- Generación de incrustaciones mediante `/v1/embeddings` (6 proveedores, 9 modelos)
-- Generación de imágenes a través de `/v1/images/generaciones` (4 proveedores, 9 modelos)
-- Piense en el análisis de etiquetas (`<think>...</think>`) para modelos de razonamiento
-- Saneamiento de respuesta para una estricta compatibilidad con OpenAI SDK
-- Normalización de roles (desarrollador → sistema, sistema → usuario) para compatibilidad entre proveedores
-- Conversión de salida estructurada (json_schema → Gemini ResponseSchema)
-- Persistencia local para proveedores, claves, alias, combos, configuraciones, precios.
-- Seguimiento de uso/costos y registro de solicitudes
-- Sincronización en la nube opcional para sincronización multidispositivo/estado
-- Lista de IP permitidas/lista de bloqueo para control de acceso a API
-- Pensando en la gestión del presupuesto (transferencia/automática/personalizada/adaptativa)
-- Inyección rápida del sistema global
-- Seguimiento de sesiones y toma de huellas digitales
-- Limitación de tarifas mejorada por cuenta con perfiles específicos del proveedor
-- Patrón de disyuntor para la resiliencia del proveedor
-- Protección de rebaño anti-truenos con bloqueo mutex
-- Caché de deduplicación de solicitudes basado en firmas
-- Capa de dominio: disponibilidad del modelo, reglas de costos, política de respaldo, política de bloqueo
-- Persistencia del estado del dominio (caché de escritura SQLite para respaldos, presupuestos, bloqueos, disyuntores)
-- Motor de políticas para la evaluación centralizada de solicitudes (bloqueo → presupuesto → respaldo)
-- Solicitar telemetría con agregación de latencia p50/p95/p99
-- ID de correlación (X-Request-Id) para seguimiento de un extremo a otro
-- Registro de auditoría de cumplimiento con opción de exclusión por clave API
-- Marco de evaluación para el aseguramiento de la calidad del LLM.
-- Panel de interfaz de usuario de resiliencia con estado del disyuntor en tiempo real
-- Proveedores modulares de OAuth (12 módulos individuales en `src/lib/oauth/providers/`)
+Core capabilities:
 
-Modelo de tiempo de ejecución principal:
+- OpenAI-compatible API surface for CLI/tools (28 providers)
+- Request/response translation across provider formats
+- Model combo fallback (multi-model sequence)
+- Account-level fallback (multi-account per provider)
+- OAuth + API-key provider connection management
+- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
+- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Think tag parsing (`<think>...</think>`) for reasoning models
+- Response sanitization for strict OpenAI SDK compatibility
+- Role normalization (developer→system, system→user) for cross-provider compatibility
+- Structured output conversion (json_schema → Gemini responseSchema)
+- Local persistence for providers, keys, aliases, combos, settings, pricing
+- Usage/cost tracking and request logging
+- Optional cloud sync for multi-device/state sync
+- IP allowlist/blocklist for API access control
+- Thinking budget management (passthrough/auto/custom/adaptive)
+- Global system prompt injection
+- Session tracking and fingerprinting
+- Per-account enhanced rate limiting with provider-specific profiles
+- Circuit breaker pattern for provider resilience
+- Anti-thundering herd protection with mutex locking
+- Signature-based request deduplication cache
+- Domain layer: model availability, cost rules, fallback policy, lockout policy
+- 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
+- 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/`)
 
-- Las rutas de la aplicación Next.js en `src/app/api/*` implementan tanto las API del panel como las API de compatibilidad.
-- Un núcleo de enrutamiento/SSE compartido en `src/sse/*` + `open-sse/*` maneja la ejecución, traducción, transmisión, respaldo y uso del proveedor.## Scope and Boundaries
+Primary runtime model:
+
+- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
+- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
+
+## Scope and Boundaries
 
 ### In Scope
 
-- Tiempo de ejecución de la puerta de enlace local
-- API de gestión de paneles
-- Autenticación de proveedor y actualización de token
-- Solicitar traducción y transmisión SSE
-- Estado local + persistencia de uso.
-- Orquestación de sincronización en la nube opcional### Out of Scope
+- Local gateway runtime
+- Dashboard management APIs
+- Provider authentication and token refresh
+- Request translation and SSE streaming
+- Local state + usage persistence
+- Optional cloud sync orchestration
 
-- Implementación del servicio en la nube detrás de `NEXT_PUBLIC_CLOUD_URL`
-- Proveedor SLA/plano de control fuera del proceso local
-- Los propios binarios CLI externos (Claude CLI, Codex CLI, etc.)## Dashboard Surface (Current)
+### Out of Scope
 
-Páginas principales en `src/app/(dashboard)/dashboard/`:
+- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
+- Provider SLA/control plane outside local process
+- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
 
-- `/dashboard` — inicio rápido + descripción general del proveedor
-- `/dashboard/endpoint` — proxy de punto final + MCP + A2A + pestañas de punto final API
-- `/dashboard/providers` — conexiones y credenciales de proveedores
-- `/dashboard/combos` — estrategias combinadas, plantillas, reglas de enrutamiento de modelos
-- `/dashboard/costs` — agregación de costos y visibilidad de precios
-- `/dashboard/analytics` — análisis y evaluaciones de uso
-- `/dashboard/limits` — controles de cuota/tasa
-- `/dashboard/cli-tools`: incorporación de CLI, detección de tiempo de ejecución, generación de configuración
-- `/dashboard/agents` — agentes ACP detectados + registro de agente personalizado
-- `/dashboard/media` — área de juegos de imágenes/videos/música
-- `/dashboard/search-tools` — historial y pruebas del proveedor de búsqueda
-- `/dashboard/health`: tiempo de actividad, disyuntores, límites de velocidad
-- `/dashboard/logs` — registros de solicitud/proxy/auditoría/consola
-- `/dashboard/settings`: pestañas de configuración del sistema (general, enrutamiento, valores predeterminados combinados, etc.)
-- `/dashboard/api-manager` — Ciclo de vida de la clave API y permisos del modelo## High-Level System Context
+## Dashboard Surface (Current)
+
+Main pages under `src/app/(dashboard)/dashboard/`:
+
+- `/dashboard` — quick start + provider overview
+- `/dashboard/endpoint` — endpoint proxy + MCP + A2A + API endpoint tabs
+- `/dashboard/providers` — provider connections and credentials
+- `/dashboard/combos` — combo strategies, templates, model routing rules
+- `/dashboard/costs` — cost aggregation and pricing visibility
+- `/dashboard/analytics` — usage analytics and evaluations
+- `/dashboard/limits` — quota/rate controls
+- `/dashboard/cli-tools` — CLI onboarding, runtime detection, config generation
+- `/dashboard/agents` — detected ACP agents + custom agent registration
+- `/dashboard/media` — image/video/music playground
+- `/dashboard/search-tools` — search provider testing and history
+- `/dashboard/health` — uptime, circuit breakers, rate limits
+- `/dashboard/logs` — request/proxy/audit/console logs
+- `/dashboard/settings` — system settings tabs (general, routing, combo defaults, etc.)
+- `/dashboard/api-manager` — API key lifecycle and model permissions
+
+## High-Level System Context
 
 ```mermaid
 flowchart LR
@@ -181,89 +192,99 @@ Management domains:
 
 ## 2) SSE + Translation Core
 
-Módulos de flujo principales:
+Main flow modules:
 
-- Entrada: `src/sse/handlers/chat.ts`
-- Orquestación central: `open-sse/handlers/chatCore.ts`
-- Adaptadores de ejecución del proveedor: `open-sse/executors/*`
-- Detección de formato/configuración del proveedor: `open-sse/services/provider.ts`
-- Análisis/resolución del modelo: `src/sse/services/model.ts`, `open-sse/services/model.ts`
-- Lógica alternativa de cuenta: `open-sse/services/accountFallback.ts`
-- Registro de traducción: `open-sse/translator/index.ts`
-- Transformaciones de flujo: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
-- Extracción/normalización de uso: `open-sse/utils/usageTracking.ts`
-- Analizador de etiquetas Think: `open-sse/utils/thinkTagParser.ts`
-- Controlador de incrustación: `open-sse/handlers/embeddings.ts`
-- Registro de proveedores de incrustación: `open-sse/config/embeddingRegistry.ts`
-- Manejador de generación de imágenes: `open-sse/handlers/imageGeneration.ts`
-- Registro del proveedor de imágenes: `open-sse/config/imageRegistry.ts`
-- Sanitización de respuestas: `open-sse/handlers/responseSanitizer.ts`
-- Normalización de roles: `open-sse/services/roleNormalizer.ts`
+- Entry: `src/sse/handlers/chat.ts`
+- Core orchestration: `open-sse/handlers/chatCore.ts`
+- Provider execution adapters: `open-sse/executors/*`
+- Format detection/provider config: `open-sse/services/provider.ts`
+- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
+- Account fallback logic: `open-sse/services/accountFallback.ts`
+- Translation registry: `open-sse/translator/index.ts`
+- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
+- Think tag parser: `open-sse/utils/thinkTagParser.ts`
+- Embedding handler: `open-sse/handlers/embeddings.ts`
+- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
+- Image generation handler: `open-sse/handlers/imageGeneration.ts`
+- Image provider registry: `open-sse/config/imageRegistry.ts`
+- Response sanitization: `open-sse/handlers/responseSanitizer.ts`
+- Role normalization: `open-sse/services/roleNormalizer.ts`
 
-Servicios (lógica de negocios):
+Services (business logic):
 
-- Selección/puntuación de cuenta: `open-sse/services/accountSelector.ts`
-- Gestión del ciclo de vida del contexto: `open-sse/services/contextManager.ts`
-- Aplicación del filtro IP: `open-sse/services/ipFilter.ts`
-- Seguimiento de sesión: `open-sse/services/sessionManager.ts`
-- Solicitar deduplicación: `open-sse/services/signatureCache.ts`
-- Inyección de aviso del sistema: `open-sse/services/systemPrompt.ts`
-- Pensando en la gestión del presupuesto: `open-sse/services/thinkingBudget.ts`
-- Enrutamiento del modelo comodín: `open-sse/services/wildcardRouter.ts`
-- Gestión de límites de tarifas: `open-sse/services/rateLimitManager.ts`
-- Disyuntor: `open-sse/services/circuitBreaker.ts`
+- Account selection/scoring: `open-sse/services/accountSelector.ts`
+- Context lifecycle management: `open-sse/services/contextManager.ts`
+- IP filter enforcement: `open-sse/services/ipFilter.ts`
+- Session tracking: `open-sse/services/sessionManager.ts`
+- Request deduplication: `open-sse/services/signatureCache.ts`
+- System prompt injection: `open-sse/services/systemPrompt.ts`
+- Thinking budget management: `open-sse/services/thinkingBudget.ts`
+- Wildcard model routing: `open-sse/services/wildcardRouter.ts`
+- Rate limit management: `open-sse/services/rateLimitManager.ts`
+- Circuit breaker: `open-sse/services/circuitBreaker.ts`
+- 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
 
-Módulos de capa de dominio:
+Domain layer modules:
 
-- Disponibilidad del modelo: `src/lib/domain/modelAvailability.ts`
-- Reglas de costos/presupuestos: `src/lib/domain/costRules.ts`
-- Política alternativa: `src/lib/domain/fallbackPolicy.ts`
-- Resolución combinada: `src/lib/domain/comboResolver.ts`
-- Política de bloqueo: `src/lib/domain/lockoutPolicy.ts`
-- Motor de políticas: `src/domain/policyEngine.ts` — bloqueo centralizado → presupuesto → evaluación alternativa
-- Catálogo de códigos de error: `src/lib/domain/errorCodes.ts`
-- ID de solicitud: `src/lib/domain/requestId.ts`
-- Recuperar tiempo de espera: `src/lib/domain/fetchTimeout.ts`
-- Solicitar telemetría: `src/lib/domain/requestTelemetry.ts`
-- Cumplimiento/auditoría: `src/lib/domain/compliance/index.ts`
-- Corredor de evaluación: `src/lib/domain/evalRunner.ts`
-- Persistencia del estado del dominio: `src/lib/db/domainState.ts` — SQLite CRUD para cadenas de respaldo, presupuestos, historial de costos, estado de bloqueo, disyuntores
+- Model availability: `src/lib/domain/modelAvailability.ts`
+- Cost rules/budgets: `src/lib/domain/costRules.ts`
+- Fallback policy: `src/lib/domain/fallbackPolicy.ts`
+- Combo resolver: `src/lib/domain/comboResolver.ts`
+- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
+- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
+- Error codes catalog: `src/lib/domain/errorCodes.ts`
+- Request ID: `src/lib/domain/requestId.ts`
+- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
+- Request telemetry: `src/lib/domain/requestTelemetry.ts`
+- Compliance/audit: `src/lib/domain/compliance/index.ts`
+- Eval runner: `src/lib/domain/evalRunner.ts`
+- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
 
-Módulos de proveedor de OAuth (12 archivos individuales en `src/lib/oauth/providers/`):
+OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
-- Índice de registro: `src/lib/oauth/providers/index.ts`
-- Proveedores individuales: `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`
-- Contenedor delgado: `src/lib/oauth/providers.ts` — reexportaciones desde módulos individuales## 3) Persistence Layer
+- 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`
+- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
-Base de datos de estado primario (SQLite):
+## 3) Persistence Layer
 
-- Infraestructura principal: `src/lib/db/core.ts` (better-sqlite3, migraciones, WAL)
-- Reexportación de fachada: `src/lib/localDb.ts` (capa delgada de compatibilidad para quienes llaman)
-- archivo: `${DATA_DIR}/storage.sqlite` (o `$XDG_CONFIG_HOME/omniroute/storage.sqlite` cuando está configurado, en caso contrario `~/.omniroute/storage.sqlite`)
-- entidades (tablas + espacios de nombres KV): conexiones de proveedor, nodos de proveedor, alias de modelo, combos, claves de API, configuración, precios,**modelos personalizados**,**proxyConfig**,**ipFilter**,**thinkingBudget**,**systemPrompt**
+Primary state DB (SQLite):
 
-Persistencia de uso:
+- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL)
+- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers)
+- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`)
+- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
 
-- fachada: `src/lib/usageDb.ts` (módulos descompuestos en `src/lib/usage/*`)
-- Tablas SQLite en `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
-- Los artefactos de archivos opcionales permanecen para compatibilidad/depuración (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
-- Los archivos JSON heredados se migran a SQLite mediante migraciones de inicio cuando están presentes
+Usage persistence:
 
-Base de datos de estado de dominio (SQLite):
+- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`)
+- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
+- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
+- legacy JSON files are migrated to SQLite by startup migrations when present
 
-- `src/lib/db/domainState.ts` — Operaciones CRUD para el estado del dominio
-- Tablas (creadas en `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
-- Patrón de caché de escritura simultánea: los mapas en memoria tienen autoridad en tiempo de ejecución; las mutaciones se escriben sincrónicamente en SQLite; El estado se restaura desde la base de datos en el arranque en frío.## 4) Auth + Security Surfaces
+Domain State DB (SQLite):
 
-- Autenticación de cookies del panel: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
-- Generación/verificación de clave API: `src/shared/utils/apiKey.ts`
-- Los secretos del proveedor persistieron en las entradas de `providerConnections`
-- Soporte de proxy saliente a través de `open-sse/utils/proxyFetch.ts` (env vars) y `open-sse/utils/networkProxy.ts` (configurable por proveedor o global)## 5) Cloud Sync
+- `src/lib/db/domainState.ts` — CRUD operations for domain state
+- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
+- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
 
-- Inicio del programador: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
-- Tarea periódica: `src/shared/services/cloudSyncScheduler.ts`
-- Tarea periódica: `src/shared/services/modelSyncScheduler.ts`
-- Ruta de control: `src/app/api/sync/cloud/route.ts`## Request Lifecycle (`/v1/chat/completions`)
+## 4) Auth + Security Surfaces
+
+- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
+- API key generation/verification: `src/shared/utils/apiKey.ts`
+- Provider secrets persisted in `providerConnections` entries
+- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
+
+## 5) Cloud Sync
+
+- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
+- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Periodic task: `src/shared/services/modelSyncScheduler.ts`
+- Control route: `src/app/api/sync/cloud/route.ts`
+
+## Request Lifecycle (`/v1/chat/completions`)
 
 ```mermaid
 sequenceDiagram
@@ -340,7 +361,9 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-Las decisiones de respaldo están impulsadas por `open-sse/services/accountFallback.ts` utilizando códigos de estado y heurísticas de mensajes de error. El enrutamiento combinado agrega una protección adicional: los 400 con alcance del proveedor, como los errores de validación de roles y bloques de contenido ascendentes, se tratan como errores del modelo local, por lo que los destinos combinados posteriores aún pueden ejecutarse.## OAuth Onboarding and Token Refresh Lifecycle
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run.
+
+## OAuth Onboarding and Token Refresh Lifecycle
 
 ```mermaid
 sequenceDiagram
@@ -370,7 +393,9 @@ sequenceDiagram
     Test-->>UI: validation result
 ```
 
-La actualización durante el tráfico en vivo se ejecuta dentro de `open-sse/handlers/chatCore.ts` a través del ejecutor `refreshCredentials()`.## Cloud Sync Lifecycle (Enable / Sync / Disable)
+Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
+
+## Cloud Sync Lifecycle (Enable / Sync / Disable)
 
 ```mermaid
 sequenceDiagram
@@ -402,7 +427,9 @@ sequenceDiagram
     Sync-->>UI: disabled
 ```
 
-La sincronización periódica la activa "CloudSyncScheduler" cuando la nube está habilitada.## Data Model and Storage Map
+Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
+
+## Data Model and Storage Map
 
 ```mermaid
 erDiagram
@@ -503,12 +530,14 @@ erDiagram
     }
 ```
 
-Archivos de almacenamiento físico:
+Physical storage files:
 
-- Base de datos de ejecución principal: `${DATA_DIR}/storage.sqlite`
-- solicitar líneas de registro: `${DATA_DIR}/log.txt` (artefacto de compatibilidad/depuración)
-- archivos de carga útil de llamadas estructuradas: `${DATA_DIR}/call_logs/`
-- traductor opcional/solicitar sesiones de depuración: `<repo>/logs/...`## Deployment Topology
+- primary runtime DB: `${DATA_DIR}/storage.sqlite`
+- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact)
+- structured call payload archives: `${DATA_DIR}/call_logs/`
+- optional translator/request debug sessions: `<repo>/logs/...`
+
+## Deployment Topology
 
 ```mermaid
 flowchart LR
@@ -543,205 +572,248 @@ flowchart LR
 
 ### Route and API Modules
 
-- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API de compatibilidad
-- `src/app/api/v1/providers/[provider]/*`: rutas dedicadas por proveedor (chat, incrustaciones, imágenes)
-- `src/app/api/providers*`: proveedor CRUD, validación, pruebas
-- `src/app/api/provider-nodes*`: gestión personalizada de nodos compatibles
-- `src/app/api/provider-models`: gestión de modelos personalizados (CRUD)
-- `src/app/api/models/route.ts`: API de catálogo de modelos (alias + modelos personalizados)
-- `src/app/api/oauth/*`: OAuth/flujos de código de dispositivo
-- `src/app/api/keys*`: ciclo de vida de la clave API local
-- `src/app/api/models/alias`: gestión de alias
-- `src/app/api/combos*`: gestión de combos alternativos
-- `src/app/api/pricing`: anulación de precios para el cálculo de costos
-- `src/app/api/settings/proxy`: configuración del proxy (GET/PUT/DELETE)
-- `src/app/api/settings/proxy/test`: prueba de conectividad de proxy saliente (POST)
-- `src/app/api/usage/*`: API de uso y registros
-- `src/app/api/sync/*` + `src/app/api/cloud/*`: sincronización en la nube y ayudantes orientados a la nube
-- `src/app/api/cli-tools/*`: escritores/comprobadores de configuración CLI local
-- `src/app/api/settings/ip-filter`: lista de IP permitidas/lista de bloqueo (GET/PUT)
-- `src/app/api/settings/thinking-budget`: configuración del presupuesto del token de pensamiento (GET/PUT)
-- `src/app/api/settings/system-prompt`: indicador global del sistema (GET/PUT)
-- `src/app/api/sessions`: listado de sesiones activas (GET)
-- `src/app/api/rate-limits`: estado del límite de tasa por cuenta (GET)### Routing and Execution Core
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
+- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
+- `src/app/api/providers*`: provider CRUD, validation, testing
+- `src/app/api/provider-nodes*`: custom compatible node management
+- `src/app/api/provider-models`: custom model management (CRUD)
+- `src/app/api/models/route.ts`: model catalog API (aliases + custom models)
+- `src/app/api/oauth/*`: OAuth/device-code flows
+- `src/app/api/keys*`: local API key lifecycle
+- `src/app/api/models/alias`: alias management
+- `src/app/api/combos*`: fallback combo management
+- `src/app/api/pricing`: pricing overrides for cost calculation
+- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
+- `src/app/api/usage/*`: usage and logs APIs
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
+- `src/app/api/cli-tools/*`: local CLI config writers/checkers
+- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
+- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
+- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
+- `src/app/api/sessions`: active session listing (GET)
+- `src/app/api/rate-limits`: per-account rate limit status (GET)
 
-- `src/sse/handlers/chat.ts`: análisis de solicitudes, manejo combinado, bucle de selección de cuentas
-- `open-sse/handlers/chatCore.ts`: traducción, envío del ejecutor, reintento/actualización, configuración de flujo
-- `open-sse/executors/*`: comportamiento de formato y red específico del proveedor### Translation Registry and Format Converters
+### Routing and Execution Core
 
-- `open-sse/translator/index.ts`: registro y orquestación de traductores
-- Solicitar traductores: `open-sse/translator/request/*`
-- Traductores de respuesta: `open-sse/translator/response/*`
-- Constantes de formato: `open-sse/translator/formats.ts`### Persistence
+- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
+- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
+- `open-sse/executors/*`: provider-specific network and format behavior
 
-- `src/lib/db/*`: configuración/estado persistente y persistencia de dominio en SQLite
-- `src/lib/localDb.ts`: reexportación de compatibilidad para módulos DB
-- `src/lib/usageDb.ts`: fachada de historial de uso/registros de llamadas encima de las tablas SQLite## Provider Executor Coverage (Strategy Pattern)
+### Translation Registry and Format Converters
 
-Cada proveedor tiene un ejecutor especializado que extiende `BaseExecutor` (en `open-sse/executors/base.ts`), que proporciona creación de URL, construcción de encabezados, reintentos con retroceso exponencial, enlaces de actualización de credenciales y el método de orquestación `execute()`.
+- `open-sse/translator/index.ts`: translator registry and orchestration
+- Request translators: `open-sse/translator/request/*`
+- Response translators: `open-sse/translator/response/*`
+- Format constants: `open-sse/translator/formats.ts`
 
-| Ejecutor                  | Proveedor(es)                                                                                                                                                | Manejo Especial                                                                               |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
-| `Ejecutor predeterminado` | OpenAI, Claude, Gemini, Qwen, Qoder, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Configuración dinámica de URL/encabezado por proveedor                                        |
-| `AntigravityExecutor`     | Antigravedad de Google                                                                                                                                       | ID personalizados de proyecto/sesión, reintento después del análisis                          |
-| `CodexExecutor`           | Códice OpenAI                                                                                                                                                | Inyecta instrucciones del sistema, fuerza el esfuerzo de razonamiento                         |
-| `CursorEjecutor`          | Cursor IDE                                                                                                                                                   | Protocolo ConnectRPC, codificación Protobuf, solicitud de firma mediante suma de comprobación |
-| `GithubExecutor`          | Copiloto de GitHub                                                                                                                                           | Actualización del token Copilot, encabezados que imitan VSCode                                |
-| `KiroExecutor`            | AWS CodeWhisperer/Kiro                                                                                                                                       | Formato binario de AWS EventStream → Conversión SSE                                           |
-| `GeminiCLIExecutor`       | Géminis CLI                                                                                                                                                  | Ciclo de actualización del token OAuth de Google                                              |
+### Persistence
 
-Todos los demás proveedores (incluidos los nodos compatibles personalizados) utilizan `DefaultExecutor`.## Provider Compatibility Matrix
+- `src/lib/db/*`: persistent config/state and domain persistence on SQLite
+- `src/lib/localDb.ts`: compatibility re-export for DB modules
+- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables
 
-| Proveedor              | Formato           | Autenticación                      | Corriente                   | Sin transmisión | Actualización de token | API de uso                |
-| ---------------------- | ----------------- | ---------------------------------- | --------------------------- | --------------- | ---------------------- | ------------------------- | ------------------------------ |
-| Claudio                | claudio           | Clave API/OAuth                    | ✅                          | ✅              | ✅                     | ⚠️ Solo administrador     |
-| Géminis                | géminis           | Clave API/OAuth                    | ✅                          | ✅              | ✅                     | ⚠️ Consola en la nube     |
-| Géminis CLI            | gemini-cli        | OAuth                              | ✅                          | ✅              | ✅                     | ⚠️ Consola en la nube     |
-| Antigravedad           | antigravedad      | OAuth                              | ✅                          | ✅              | ✅                     | ✅ API de cuota completa  |
-| Abierta AI             | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Códice                 | respuestas-openai | OAuth                              | ✅ forzado                  | ❌              | ✅                     | ✅ Límites de tarifas     |
-| Copiloto de GitHub     | abierto           | OAuth + Token de copiloto          | ✅                          | ✅              | ✅                     | ✅ Instantáneas de cuotas |
-| Cursores               | cursor            | Suma de comprobación personalizada | ✅                          | ✅              | ❌                     | ❌                        |
-| kiro                   | kiro              | AWS SSO OIDC                       | ✅ (Transmisión de eventos) | ❌              | ✅                     | ✅ Límites de uso         |
-| Qwen                   | abierto           | OAuth                              | ✅                          | ✅              | ✅                     | ⚠️ Por solicitud          |
-| Qoder                  | abierto           | OAuth (básico)                     | ✅                          | ✅              | ✅                     | ⚠️ Por solicitud          |
-| Enrutador abierto      | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| GLM/Kimi/MiniMax       | claudio           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Búsqueda profunda      | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Groq                   | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| xAI (Grok)             | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Mistral                | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Perplejidad            | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Juntos IA              | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Fuegos artificiales AI | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Cerebras               | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| Coherir                | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        |
-| NIM de NVIDIA          | abierto           | Clave API                          | ✅                          | ✅              | ❌                     | ❌                        | ## Format Translation Coverage |
+## Provider Executor Coverage (Strategy Pattern)
 
-Los formatos de origen detectados incluyen:
+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                                     |
+
+All other providers (including custom compatible nodes) use the `DefaultExecutor`.
+
+## Provider Compatibility Matrix
+
+| Provider         | Format           | Auth                  | Stream           | Non-Stream | Token Refresh | Usage API          |
+| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
+| Claude           | claude           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Admin only      |
+| Gemini           | gemini           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Gemini CLI       | gemini-cli       | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Antigravity      | antigravity      | OAuth                 | ✅               | ✅         | ✅            | ✅ Full quota API  |
+| OpenAI           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Codex            | openai-responses | OAuth                 | ✅ forced        | ❌         | ✅            | ✅ Rate limits     |
+| GitHub Copilot   | openai           | OAuth + Copilot Token | ✅               | ✅         | ✅            | ✅ Quota snapshots |
+| Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
+| Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
+| Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Qoder            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Groq             | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| xAI (Grok)       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Mistral          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Perplexity       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Together AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Fireworks AI     | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+
+## Format Translation Coverage
+
+Detected source formats include:
 
 - `openai`
-- `respuestas openai`
-- `claudio`
-- `géminis`
+- `openai-responses`
+- `claude`
+- `gemini`
 
-Los formatos de destino incluyen:
+Target formats include:
 
-- Chat/Respuestas de OpenAI
-- Claudio
-- Géminis/Gemini-CLI/sobre antigravedad
-  -Kiro
-- Cursores
+- OpenAI chat/Responses
+- Claude
+- Gemini/Gemini-CLI/Antigravity envelope
+- Kiro
+- Cursor
 
-Las traducciones utilizan**OpenAI como formato central**; todas las conversiones pasan por OpenAI como formato intermedio:```
+Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
+
+```
 Source Format → OpenAI (hub) → Target Format
+```
 
-````
+Translations are selected dynamically based on source payload shape and provider target format.
 
-Las traducciones se seleccionan dinámicamente según la forma de la carga útil de origen y el formato de destino del proveedor.
+Additional processing layers in the translation pipeline:
 
-Capas de procesamiento adicionales en el proceso de traducción:
+- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance
+- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)
+- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field
+- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`
 
--**Desinfección de respuestas**: elimina los campos no estándar de las respuestas en formato OpenAI (tanto en streaming como sin streaming) para garantizar el estricto cumplimiento del SDK.
--**Normalización de roles**: convierte `desarrollador` → `sistema` para objetivos que no son OpenAI; fusiona `sistema` → `usuario` para modelos que rechazan el rol del sistema (GLM, ERNIE)
--**Extracción de etiquetas Think**: analiza los bloques `<think>...</think>` del contenido en el campo `reasoning_content`
--**Salida estructurada**: convierte OpenAI `response_format.json_schema` en `responseMimeType` + `responseSchema` de Gemini.## Supported API Endpoints
+## Supported API Endpoints
 
-| Punto final | Formato | Manejador |
+| Endpoint                                           | Format             | Handler                                                             |
 | -------------------------------------------------- | ------------------ | ------------------------------------------------------------------- |
-| `POST /v1/chat/compleciones` | Chat abierto de IA | `src/sse/handlers/chat.ts` |
-| `POST /v1/mensajes` | Mensajes de Claude | Mismo controlador (detectado automáticamente) |
-| `POST /v1/respuestas` | Respuestas de OpenAI | `open-sse/handlers/responsesHandler.ts` |
-| `POST /v1/incrustaciones` | Incrustaciones de OpenAI | `open-sse/handlers/embeddings.ts` |
-| `GET /v1/incrustaciones` | Listado de modelos | Ruta API |
-| `POST /v1/imagenes/generaciones` | Imágenes de OpenAI | `open-sse/handlers/imageGeneration.ts` |
-| `GET /v1/images/generaciones` | Listado de modelos | Ruta API |
-| `POST /v1/proveedores/{proveedor}/chat/completions` | Chat abierto de IA | Dedicado por proveedor con validación de modelo |
-| `POST /v1/proveedores/{proveedor}/incrustaciones` | Incrustaciones de OpenAI | Dedicado por proveedor con validación de modelo |
-| `POST /v1/proveedores/{proveedor}/images/generaciones` | Imágenes de OpenAI | Dedicado por proveedor con validación de modelo |
-| `POST /v1/mensajes/count_tokens` | Recuento de fichas de Claude | Ruta API |
-| `OBTENER /v1/modelos` | Lista de modelos OpenAI | Ruta API (chat + incrustación + imagen + modelos personalizados) |
-| `OBTENER /api/modelos/catalog` | Catálogo | Todos los modelos agrupados por proveedor + tipo |
-| `POST /v1beta/models/*:streamGenerateContent` | Nativo de Géminis | Ruta API |
-| `OBTENER/PONER/BORRAR /api/settings/proxy` | Configuración de proxy | Configuración del proxy de red |
-| `POST /api/configuración/proxy/prueba` | Conectividad de proxy | Punto final de prueba de conectividad/estado del proxy |
-| `GET/POST/DELETE /api/provider-models` | Modelos de proveedores | Metadatos del modelo de proveedor que respaldan los modelos disponibles personalizados y administrados |## Bypass Handler
+| `POST /v1/chat/completions`                        | OpenAI Chat        | `src/sse/handlers/chat.ts`                                          |
+| `POST /v1/messages`                                | Claude Messages    | Same handler (auto-detected)                                        |
+| `POST /v1/responses`                               | OpenAI Responses   | `open-sse/handlers/responsesHandler.ts`                             |
+| `POST /v1/embeddings`                              | OpenAI Embeddings  | `open-sse/handlers/embeddings.ts`                                   |
+| `GET /v1/embeddings`                               | Model listing      | API route                                                           |
+| `POST /v1/images/generations`                      | OpenAI Images      | `open-sse/handlers/imageGeneration.ts`                              |
+| `GET /v1/images/generations`                       | Model listing      | API route                                                           |
+| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat        | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings  | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/images/generations` | OpenAI Images      | Dedicated per-provider with model validation                        |
+| `POST /v1/messages/count_tokens`                   | Claude Token Count | API route                                                           |
+| `GET /v1/models`                                   | OpenAI Models list | API route (chat + embedding + image + custom models)                |
+| `GET /api/models/catalog`                          | Catalog            | All models grouped by provider + type                               |
+| `POST /v1beta/models/*:streamGenerateContent`      | Gemini native      | API route                                                           |
+| `GET/PUT/DELETE /api/settings/proxy`               | Proxy Config       | Network proxy configuration                                         |
+| `POST /api/settings/proxy/test`                    | Proxy Connectivity | Proxy health/connectivity test endpoint                             |
+| `GET/POST/DELETE /api/provider-models`             | Provider Models    | Provider model metadata backing custom and managed available models |
 
-El controlador de omisión (`open-sse/utils/bypassHandler.ts`) intercepta solicitudes "desechables" conocidas de Claude CLI (pings de preparación, extracciones de títulos y recuentos de tokens) y devuelve una**respuesta falsa**sin consumir tokens del proveedor ascendente. Esto se activa solo cuando "User-Agent" contiene "claude-cli".## Request Logger Pipeline
+## Bypass Handler
 
-El registrador de solicitudes (`open-sse/utils/requestLogger.ts`) proporciona un canal de registro de depuración de 7 etapas, deshabilitado de forma predeterminada, habilitado a través de `ENABLE_REQUEST_LOGS=true`:```
-1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json
-→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt
-````
+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`.
 
-Los archivos se escriben en `<repo>/logs/<session>/` para cada sesión de solicitud.## Failure Modes and Resilience
+## Request Logging and Artifacts
+
+The older file-based request logger (`open-sse/utils/requestLogger.ts`) is retained only for
+legacy compatibility. The current runtime contract uses:
+
+- `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
 
-- tiempo de reutilización de la cuenta del proveedor en errores transitorios/de tasa/autenticación
-- respaldo de la cuenta antes de fallar la solicitud
-- retroceso del modelo combinado cuando se agota la ruta del modelo/proveedor actual## 2) Token Expiry
+- provider account cooldown on transient/rate/auth errors
+- account fallback before failing request
+- combo model fallback when current model/provider path is exhausted
 
-- verificación previa y actualización con reintento para proveedores actualizables
-- Reintento 401/403 después de un intento de actualización en la ruta principal## 3) Stream Safety
+## 2) Token Expiry
 
-- controlador de flujo con reconocimiento de desconexión
-- flujo de traducción con descarga de final de flujo y manejo `[DONE]`
-- reserva de estimación de uso cuando faltan metadatos de uso del proveedor## 4) Cloud Sync Degradation
+- pre-check and refresh with retry for refreshable providers
+- 401/403 retry after refresh attempt in core path
 
-- Aparecen errores de sincronización pero el tiempo de ejecución local continúa
-- El programador tiene una lógica con capacidad de reintento, pero la ejecución periódica actualmente llama a la sincronización de un solo intento de forma predeterminada.## 5) Data Integrity
+## 3) Stream Safety
 
-- Migraciones de esquema SQLite y enlaces de actualización automática al inicio
-- JSON heredado → ruta de compatibilidad de migración SQLite## Observability and Operational Signals
+- disconnect-aware stream controller
+- translation stream with end-of-stream flush and `[DONE]` handling
+- usage estimation fallback when provider usage metadata is missing
 
-Fuentes de visibilidad en tiempo de ejecución:
+## 4) Cloud Sync Degradation
 
-- registros de consola desde `src/sse/utils/logger.ts`
-- agregados de uso por solicitud en SQLite (`usage_history`, `call_logs`, `proxy_logs`)
-- capturas de carga útil detalladas en cuatro etapas en SQLite (`request_detail_logs`) cuando `settings.detailed_logs_enabled=true`
-- registro de estado de solicitud textual en `log.txt` (opcional/compatible)
-- registros de traducción/solicitud profunda opcionales en `logs/` cuando `ENABLE_REQUEST_LOGS=true`
-- puntos finales de uso del panel (`/api/usage/*`) para el consumo de UI
+- sync errors are surfaced but local runtime continues
+- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
 
-La captura de carga útil de solicitud detallada almacena hasta cuatro etapas de carga útil JSON por llamada enrutada:
+## 5) Data Integrity
 
-- solicitud sin procesar recibida del cliente
-- solicitud traducida realmente enviada en sentido ascendente
-- respuesta del proveedor reconstruida como JSON; las respuestas transmitidas se compactan en el resumen final más los metadatos de la transmisión
-- respuesta final del cliente devuelta por OmniRoute; las respuestas transmitidas se almacenan en el mismo formulario de resumen compacto## Security-Sensitive Boundaries
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
-- JWT secret (`JWT_SECRET`) protege la verificación/firma de cookies de sesión del panel
-- El arranque de contraseña inicial (`INITIAL_PASSWORD`) debe configurarse explícitamente para el aprovisionamiento de primera ejecución.
-- La clave API HMAC secreta (`API_KEY_SECRET`) protege el formato de clave API local generado
-- Los secretos del proveedor (claves/tokens de API) se conservan en la base de datos local y deben protegerse a nivel del sistema de archivos.
-- Los puntos finales de sincronización en la nube se basan en la semántica de autenticación de clave API + ID de máquina## Environment and Runtime Matrix
+## Observability and Operational Signals
 
-Variables de entorno utilizadas activamente por el código:
+Runtime visibility sources:
 
-- Aplicación/autenticación: `JWT_SECRET`, `INITIAL_PASSWORD`
-- Almacenamiento: `DATA_DIR`
-- Comportamiento de nodo compatible: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
-- Anulación de la base de almacenamiento opcional (Linux/macOS cuando `DATA_DIR` no está configurado): `XDG_CONFIG_HOME`
-- Hashing de seguridad: `API_KEY_SECRET`, `MACHINE_ID_SALT`
-- Registro: `ENABLE_REQUEST_LOGS`
-- Sincronización/URL en la nube: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
-- Proxy saliente: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` y variantes en minúsculas
-- Marcas de características de SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
-- Ayudantes de plataforma/tiempo de ejecución (no configuración específica de la aplicación): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`## Known Architectural Notes
+- console logs from `src/sse/utils/logger.ts`
+- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true`
+- textual request status log in `log.txt` (optional/compat)
+- optional 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
 
-1. `usageDb` y `localDb` comparten la misma política de directorio base (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) con la migración de archivos heredados.
-2. `/api/v1/route.ts` delega al mismo generador de catálogo unificado utilizado por `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) para evitar la deriva semántica.
-3. El registrador de solicitudes escribe encabezados/cuerpo completo cuando está habilitado; trate el directorio de registro como confidencial.
-4. El comportamiento de la nube depende de la `NEXT_PUBLIC_BASE_URL` correcta y de la accesibilidad del punto final de la nube.
-5. El directorio `open-sse/` se publica como `@omniroute/open-sse`**paquete de espacio de trabajo npm**. El código fuente lo importa a través de `@omniroute/open-sse/...` (resuelto por Next.js `transpilePackages`). Las rutas de archivo en este documento todavía usan el nombre de directorio `open-sse/` para mantener la coherencia.
-6. Los gráficos en el panel utilizan**Recharts**(basados ​​en SVG) para visualizaciones analíticas interactivas y accesibles (gráficos de barras de uso de modelos, tablas de desglose de proveedores con tasas de éxito).
-7. Las pruebas E2E utilizan**Playwright**(`tests/e2e/`), se ejecutan mediante `npm run test:e2e`. Las pruebas unitarias utilizan**ejecutor de pruebas Node.js**(`tests/unit/`), se ejecutan a través de `npm run test:unit`. El código fuente bajo `src/` es**TypeScript**(`.ts`/`.tsx`); el espacio de trabajo `open-sse/` sigue siendo JavaScript (`.js`).
-8. La página de configuración está organizada en 5 pestañas: Seguridad, Enrutamiento (6 estrategias globales: completar primero, por turnos, p2c, aleatorio, menos utilizado, de costo optimizado), Resiliencia (límites de velocidad editables, disyuntor, políticas), IA (presupuesto pensado, aviso del sistema, caché de avisos), Avanzado (proxy).## Operational Verification Checklist
+Detailed request payload capture stores up to four JSON payload stages per routed call:
 
-- Compilación desde la fuente: `npm run build`
-- Crear imagen de Docker: `docker build -t omniroute.`
-- Iniciar el servicio y verificar:
-- `OBTENER /api/configuración`
-- `OBTENER /api/v1/modelos`
-- La URL base de destino de CLI debe ser `http://<host>:20128/v1` cuando `PORT=20128`
+- raw request received from the client
+- translated request actually sent upstream
+- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata
+- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form
+
+## Security-Sensitive Boundaries
+
+- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
+- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning
+- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format
+- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level
+- Cloud sync endpoints rely on API key auth + machine id semantics
+
+## Environment and Runtime Matrix
+
+Environment variables actively used by code:
+
+- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Storage: `DATA_DIR`
+- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
+- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME`
+- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
+- Logging: `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`
+- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+
+## Known Architectural Notes
+
+1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.
+2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift.
+3. Request logger writes full headers/body when enabled; treat log directory as sensitive.
+4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability.
+5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency.
+6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates).
+7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`).
+8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies, **Context Relay** handoff config), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
+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 24+ detection**: `/api/settings/require-login` returns `nodeVersion` and `nodeCompatible` fields. The login page renders a warning banner when the runtime is incompatible.
+
+## Operational Verification Checklist
+
+- Build from source: `npm run build`
+- Build Docker image: `docker build -t omniroute .`
+- Start service and verify:
+- `GET /api/settings`
+- `GET /api/v1/models`
+- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`

docs/i18n/es/docs/CODEBASE_DOCUMENTATION.md

@@ -387,7 +387,7 @@ import "./request/claude-to-openai.js"; // ← self-registers
 | `corriente.ts`     | **SSE Transform Stream**: el canal principal de transmisión. Dos modos: `TRANSLATE` (traducción de formato completo) y `PASSTHROUGH` (normalizar + extraer uso). Maneja el almacenamiento en búfer de fragmentos, la estimación de uso y el seguimiento de la longitud del contenido. Las instancias de codificador/decodificador por flujo evitan el estado compartido. |
 | `streamHelpers.ts` | Utilidades SSE de bajo nivel: `parseSSELine` (tolerante a espacios en blanco), `hasValuableContent` (filtra fragmentos vacíos para OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (serialización SSE con reconocimiento de formato con limpieza `perf_metrics`).                                                                                                     |
 | `usageTracking.ts` | Extracción de uso de tokens de cualquier formato (Claude/OpenAI/Gemini/Responses), estimación con proporciones separadas de caracteres por token de herramienta/mensaje, adición de búfer (margen de seguridad de 2000 tokens), filtrado de campos específicos del formato, registro de consola con colores ANSI.                                                        |
-| `requestLogger.ts` | Registro de solicitudes basado en archivos (optar mediante `ENABLE_REQUEST_LOGS=true`). Crea carpetas de sesión con archivos numerados: `1_req_client.json` → `7_res_client.txt`. Todas las E/S son asíncronas (disparar y olvidar). Enmascara encabezados sensibles.                                                                                                    |
+| `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` | Intercepta patrones específicos de Claude CLI (extracción de títulos, calentamiento, recuento) y devuelve respuestas falsas sin llamar a ningún proveedor. Admite tanto streaming como no streaming. Limitado intencionalmente al alcance de Claude CLI.                                                                                                                 |
 | `redProxy.ts`      | Resuelve la URL del proxy saliente para un proveedor determinado con prioridad: configuración específica del proveedor → configuración global → variables de entorno (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Admite exclusiones `NO_PROXY`. Configuración de cachés durante 30 segundos.                                                                               | #### SSE Streaming Pipeline |
 

docs/i18n/es/docs/FEATURES.md

@@ -4,102 +4,168 @@
 
 ---
 
-Guía visual de cada sección del panel de OmniRoute.---
+
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
 
 ## 🔌 Providers
 
-Administre las conexiones de proveedores de IA: proveedores de OAuth (Claude Code, Codex, Gemini CLI), proveedores de claves API (Groq, DeepSeek, OpenRouter) y proveedores gratuitos (Qoder, Qwen, Kiro). Las cuentas Kiro incluyen seguimiento del saldo de crédito: créditos restantes, asignación total y fecha de renovación visibles en Panel → Uso.![Providers Dashboard](screenshots/01-providers.png)
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+![Providers Dashboard](screenshots/01-providers.png)
 
 ---
 
 ## 🎨 Combos
 
-Cree combinaciones de enrutamiento de modelos con 6 estrategias: prioridad, ponderada, por turnos, aleatoria, menos utilizada y de costo optimizado. Cada combo encadena múltiples modelos con respaldo automático e incluye plantillas rápidas y comprobaciones de preparación.![Combos Dashboard](screenshots/02-combos.png)
+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.
+
+![Combos Dashboard](screenshots/02-combos.png)
 
 ---
 
 ## 📊 Analytics
 
-Análisis de uso integral con consumo de tokens, estimaciones de costos, mapas de actividad, gráficos de distribución semanal y desgloses por proveedor.![Analytics Dashboard](screenshots/03-analytics.png)
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
 
 ---
 
 ## 🏥 System Health
 
-Monitoreo en tiempo real: tiempo de actividad, memoria, versión, percentiles de latencia (p50/p95/p99), estadísticas de caché y estados de los disyuntores del proveedor.![Health Dashboard](screenshots/04-health.png)
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+![Health Dashboard](screenshots/04-health.png)
 
 ---
 
 ## 🔧 Translator Playground
 
-Cuatro modos para depurar traducciones de API:**Playground**(convertidor de formato),**Chat Tester**(solicitudes en vivo),**Test Bench**(pruebas por lotes) y**Live Monitor**(transmisión en tiempo real).![Translator Playground](screenshots/05-translator.png)
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+![Translator Playground](screenshots/05-translator.png)
 
 ---
 
 ## 🎮 Model Playground _(v2.0.9+)_
 
-Pruebe cualquier modelo directamente desde el tablero. Seleccione proveedor, modelo y punto final, escriba mensajes con Monaco Editor, transmita respuestas en tiempo real, cancele la transmisión a mitad de camino y vea métricas de tiempo.---
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
 
 ## 🎨 Themes _(v2.0.5+)_
 
-Temas de colores personalizables para todo el tablero. Elija entre 7 colores preestablecidos (coral, azul, rojo, verde, violeta, naranja, cian) o cree un tema personalizado eligiendo cualquier color hexadecimal. Admite modo claro, oscuro y de sistema.---
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
 
 ## ⚙️ Settings
 
-Panel de configuración completo con pestañas:
+Comprehensive settings panel with tabs:
 
--**General**— Almacenamiento del sistema, gestión de copias de seguridad (exportación/importación de base de datos) -**Apariencia**: selector de tema (oscuro/claro/sistema), ajustes preestablecidos de tema de color y colores personalizados, visibilidad del registro de estado, controles de visibilidad de elementos de la barra lateral -**Seguridad**: protección API de endpoints, bloqueo de proveedores personalizado, filtrado de IP, información de sesión -**Enrutamiento**: alias de modelo, degradación de tareas en segundo plano -**Resiliencia**: persistencia del límite de velocidad, ajuste de disyuntores, desactivación automática de cuentas prohibidas, monitoreo de vencimiento del proveedor -**Avanzado**: anulaciones de configuración, seguimiento de auditoría de configuración, modo de degradación alternativa![Settings Dashboard](screenshots/06-settings.png)
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring, **Context Relay** handoff threshold and summary model configuration
+- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
+
+![Settings Dashboard](screenshots/06-settings.png)
 
 ---
 
 ## 🔧 CLI Tools
 
-Configuración con un clic para herramientas de codificación de IA: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continuar, Cursor y Factory Droid. Incluye aplicación/restablecimiento de configuración automatizada, perfiles de conexión y mapeo de modelos.![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
 
 ---
 
 ## 🤖 CLI Agents _(v2.0.11+)_
 
-Panel para descubrir y administrar agentes CLI. Muestra una cuadrícula de 14 agentes integrados (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) con:
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
 
--**Estado de instalación**: Instalado/No encontrado con detección de versión -**Insignias de protocolo**: stdio, HTTP, etc. -**Agentes personalizados**: registre cualquier herramienta CLI a través del formulario (nombre, binario, comando de versión, argumentos de generación) -**CLI Fingerprint Matching**: alternancia por proveedor para hacer coincidir las firmas de solicitud CLI nativas, lo que reduce el riesgo de prohibición y preserva la IP del proxy.---
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🔗 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
+
+---
 
 ## 🖼️ Media _(v2.0.3+)_
 
-Genere imágenes, videos y música desde el tablero. Admite OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open y MusicGen.---
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
 
 ## 📝 Request Logs
 
-Registro de solicitudes en tiempo real con filtrado por proveedor, modelo, cuenta y clave API. Muestra códigos de estado, uso de token, latencia y detalles de respuesta.![Usage Logs](screenshots/08-usage.png)
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+![Usage Logs](screenshots/08-usage.png)
 
 ---
 
 ## 🌐 API Endpoint
 
-Su punto final API unificado con desglose de capacidades: finalización de chat, API de respuestas, incrustaciones, generación de imágenes, reclasificación, transcripción de audio, texto a voz, moderaciones y claves API registradas. Integración de Cloudflare Quick Tunnel y soporte de proxy en la nube para acceso remoto.![Endpoint Dashboard](screenshots/09-endpoint.png)
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)
 
 ---
 
 ## 🔑 API Key Management
 
-Cree, alcance y revoque claves API. Cada clave se puede restringir a modelos/proveedores específicos con acceso completo o permisos de solo lectura. Gestión visual de claves con seguimiento de uso.---
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
 
 ## 📋 Audit Log
 
-Seguimiento de acciones administrativas con filtrado por tipo de acción, actor, objetivo, dirección IP y marca de tiempo. Historial completo de eventos de seguridad.---
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
 
 ## 🖥️ Desktop Application
 
-Aplicación de escritorio Native Electron para Windows, macOS y Linux. Ejecute OmniRoute como una aplicación independiente con integración en la bandeja del sistema, soporte sin conexión, actualización automática e instalación con un solo clic.
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
 
-Características clave:
+Key features:
 
-- Sondeo de preparación del servidor (no hay pantalla en blanco durante el arranque en frío)
-- Bandeja del sistema con gestión de puertos.
-- Política de seguridad de contenidos
-- Cerradura de instancia única
-- Actualización automática al reiniciar
-- UI condicionada a la plataforma (semáforos de macOS, barra de título predeterminada de Windows/Linux)
-- Paquete de compilación de Electron reforzado: los `node_modules' vinculados simbólicamente en el paquete independiente se detectan y rechazan antes del empaquetado, lo que evita la dependencia del tiempo de ejecución en la máquina de compilación (v2.5.5+)
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
 
-📖 Consulte [`electron/README.md`](../electron/README.md) para obtener la documentación completa.
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/es/docs/TROUBLESHOOTING.md

@@ -4,68 +4,141 @@
 
 ---
 
-Problemas comunes y soluciones para OmniRoute.---
+Common problems and solutions for OmniRoute.
+
+---
 
 ## Quick Fixes
 
-| Problema                                   | Solución                                                                                       |
-| ------------------------------------------ | ---------------------------------------------------------------------------------------------- | --- |
-| El primer inicio de sesión no funciona     | Establezca `INITIAL_PASSWORD` en `.env` (sin valor predeterminado codificado)                  |
-| El panel se abre en el puerto incorrecto   | Establezca `PORT=20128` y `NEXT_PUBLIC_BASE_URL=http://localhost:20128`                        |
-| No hay registros de solicitudes en `logs/` | Establezca `ENABLE_REQUEST_LOGS = verdadero`                                                   |
-| EACCES: permiso denegado                   | Establezca `DATA_DIR=/path/to/writable/dir` para anular `~/.omniroute`                         |
-| La estrategia de enrutamiento no se guarda | Actualización a v1.4.11+ (corrección del esquema Zod para la persistencia de la configuración) | --- |
+| 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      | You may be on Node.js 24+ — see [Node.js Compatibility](#nodejs-compatibility) 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 Node.js 24+. The `better-sqlite3` native binary is not compatible with Node.js 24, which causes a fatal crash when the server tries to initialize the database.
+
+**Symptoms:**
+
+- Login page shows a blank screen or a server error
+- Console shows `Error: Module did not self-register` or similar native binding errors
+- Starting with v3.5.5, the login page shows an **orange warning banner** with your Node version if incompatibility is detected
+
+**Fix:**
+
+1. Install Node.js 22 LTS (recommended):
+   ```bash
+   nvm install 22
+   nvm use 22
+   ```
+2. Verify your version: `node --version` should show `v22.x.x`
+3. Reinstall OmniRoute: `npm install -g omniroute`
+4. Restart: `omniroute`
+
+> **Supported versions:** Node.js 18, 20, or 22 LTS. Node.js 24+ is **not supported**.
+
+---
+
+## 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+.
+
+---
 
 ## Provider Issues
 
 ### "Language model did not provide messages"
 
-**Causa:**Cuota de proveedor agotada.
+**Cause:** Provider quota exhausted.
 
-**Arreglo:**
+**Fix:**
 
-1. Verifique el rastreador de cuotas del panel
-2. Utilice un combo con niveles alternativos
-3. Cambiar al nivel más barato/gratuito### Rate Limiting
+1. Check dashboard quota tracker
+2. Use a combo with fallback tiers
+3. Switch to cheaper/free tier
 
-**Causa:**Cuota de suscripción agotada.
+### Rate Limiting
 
-**Arreglo:**
+**Cause:** Subscription quota exhausted.
 
-- Agregar respaldo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-- Utilice GLM/MiniMax como copia de seguridad económica### OAuth Token Expired
+**Fix:**
 
-OmniRoute actualiza automáticamente los tokens. Si los problemas persisten:
+- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Use GLM/MiniMax as cheap backup
 
-1. Panel de control → Proveedor → Reconectar
-2. Eliminar y volver a agregar la conexión del proveedor.---
+### OAuth Token Expired
+
+OmniRoute auto-refreshes tokens. If issues persist:
+
+1. Dashboard → Provider → Reconnect
+2. Delete and re-add the provider connection
+
+---
 
 ## Cloud Issues
 
 ### Cloud Sync Errors
 
-1. Verifique que `BASE_URL` apunte a su instancia en ejecución (por ejemplo, `http://localhost:20128`)
-2. Verifique que `CLOUD_URL` apunte a su punto final en la nube (por ejemplo, `https://omniroute.dev`).
-3. Mantenga los valores `NEXT_PUBLIC_*` alineados con los valores del lado del servidor### Cloud `stream=false` Returns 500
+1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
+2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
+3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
 
-**Síntoma:**`Token inesperado 'd'...` en el punto final de la nube para llamadas que no son de transmisión.
+### Cloud `stream=false` Returns 500
 
-**Causa:**Upstream devuelve la carga útil SSE mientras que el cliente espera JSON.
+**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
 
-**Solución alternativa:**Utilice `stream=true` para llamadas directas en la nube. El tiempo de ejecución local incluye el respaldo SSE → JSON.### Cloud Says Connected but "Invalid API key"
+**Cause:** Upstream returns SSE payload while client expects JSON.
 
-1. Cree una clave nueva desde el panel local (`/api/keys`)
-2. Ejecute la sincronización en la nube: Habilitar nube → Sincronizar ahora
-3. Las claves antiguas/no sincronizadas aún pueden devolver "401" en la nube---
+**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
+
+### Cloud Says Connected but "Invalid API key"
+
+1. Create a fresh key from local dashboard (`/api/keys`)
+2. Run cloud sync: Enable Cloud → Sync Now
+3. Old/non-synced keys can still return `401` on cloud
+
+---
 
 ## Docker Issues
 
 ### CLI Tool Shows Not Installed
 
-1. Verifique los campos de tiempo de ejecución: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
-2. Para el modo portátil: use el destino de imagen `runner-cli` (CLI incluidas)
-3. Para el modo de montaje del host: configure `CLI_EXTRA_PATHS` y monte el directorio bin del host como de solo lectura
-4. Si `installed=true` y `runnable=false`: se encontró el binario pero falló la verificación de estado### Quick Runtime Validation
+1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. For portable mode: use image target `runner-cli` (bundled CLIs)
+3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
+4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
+
+### Quick Runtime Validation
 
 ```bash
 curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
@@ -79,16 +152,22 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
 
 ### High Costs
 
-1. Verifique las estadísticas de uso en Panel → Uso
-2. Cambie el modelo principal a GLM/MiniMax
-3. Utilice el nivel gratuito (Gemini CLI, Qoder) para tareas no críticas
-4. Establezca presupuestos de costos por clave API: Panel → Claves API → Presupuesto---
+1. Check usage stats in Dashboard → Usage
+2. Switch primary model to GLM/MiniMax
+3. Use free tier (Gemini CLI, Qoder) for non-critical tasks
+4. Set cost budgets per API key: Dashboard → API Keys → Budget
+
+---
 
 ## Debugging
 
-### Enable Request Logs
+### Enable Log Files
 
-Establezca `ENABLE_REQUEST_LOGS=true` en su archivo `.env`. Los registros aparecen en el directorio `logs/`.### Check Provider Health
+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
 
 ```bash
 # Health dashboard
@@ -100,67 +179,96 @@ curl http://localhost:20128/api/monitoring/health
 
 ### Runtime Storage
 
-- Estado principal: `${DATA_DIR}/storage.sqlite` (proveedores, combos, alias, claves, configuraciones)
-- Uso: tablas SQLite en `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + opcional `${DATA_DIR}/log.txt` y `${DATA_DIR}/call_logs/`
-- Solicitar registros: `<repo>/logs/...` (cuando `ENABLE_REQUEST_LOGS=true`)---
+- 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}/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
+
+---
 
 ## Circuit Breaker Issues
 
 ### Provider stuck in OPEN state
 
-Cuando el disyuntor de un proveedor está ABIERTO, las solicitudes se bloquean hasta que expire el tiempo de reutilización.
+When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
 
-**Arreglo:**
+**Fix:**
 
-1. Vaya a**Panel → Configuración → Resiliencia**
-2. Verifique la tarjeta del disyuntor del proveedor afectado.
-3. Haga clic en**Restablecer todo**para borrar todos los interruptores o espere a que expire el tiempo de reutilización.
-4. Verifique que el proveedor esté realmente disponible antes de restablecer### Provider keeps tripping the circuit breaker
+1. Go to **Dashboard → Settings → Resilience**
+2. Check the circuit breaker card for the affected provider
+3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
+4. Verify the provider is actually available before resetting
 
-Si un proveedor ingresa repetidamente al estado ABIERTO:
+### Provider keeps tripping the circuit breaker
 
-1. Marque**Panel → Estado → Estado del proveedor**para ver el patrón de error.
-2. Vaya a**Configuración → Resiliencia → Perfiles de proveedores**y aumente el umbral de falla.
-3. Verifique si el proveedor ha cambiado los límites de API o requiere una nueva autenticación.
-4. Revise la telemetría de latencia: una latencia alta puede causar fallas basadas en el tiempo de espera---
+If a provider repeatedly enters OPEN state:
+
+1. Check **Dashboard → Health → Provider Health** for the failure pattern
+2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
+3. Check if the provider has changed API limits or requires re-authentication
+4. Review latency telemetry — high latency may cause timeout-based failures
+
+---
 
 ## Audio Transcription Issues
 
 ### "Unsupported model" error
 
-- Asegúrate de estar usando el prefijo correcto: `deepgram/nova-3` o `assemblyai/best`
-- Verifique que el proveedor esté conectado en**Panel → Proveedores**### Transcription returns empty or fails
+- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
+- Verify the provider is connected in **Dashboard → Providers**
 
-- Verifique los formatos de audio admitidos: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
-- Verifique que el tamaño del archivo esté dentro de los límites del proveedor (normalmente < 25 MB)
-- Verifique la validez de la clave API del proveedor en la tarjeta del proveedor---
+### Transcription returns empty or fails
+
+- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Verify file size is within provider limits (typically < 25MB)
+- Check provider API key validity in the provider card
+
+---
 
 ## Translator Debugging
 
-Utilice**Panel → Traductor**para depurar problemas de traducción de formato:
+Use **Dashboard → Translator** to debug format translation issues:
 
-| Modo                       | Cuándo utilizar                                                                                               |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| **Parque infantil**        | Compare formatos de entrada/salida uno al lado del otro: pegue una solicitud fallida para ver cómo se traduce |
-| **Probador de chat**       | Envíe mensajes en vivo e inspeccione la carga útil completa de solicitud/respuesta, incluidos los encabezados |
-| **Banco de pruebas**       | Ejecute pruebas por lotes en combinaciones de formatos para encontrar qué traducciones no funcionan           |
-| **Monitorización en vivo** | Observe el flujo de solicitudes en tiempo real para detectar problemas de traducción intermitentes            | ### Common format issues |
+| Mode             | When to Use                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| **Playground**   | Compare input/output formats side by side — paste a failing request to see how it translates |
+| **Chat Tester**  | Send live messages and inspect the full request/response payload including headers           |
+| **Test Bench**   | Run batch tests across format combinations to find which translations are broken             |
+| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues                        |
 
--**Las etiquetas de pensamiento no aparecen**: compruebe si el proveedor objetivo apoya el pensamiento y la configuración del presupuesto de pensamiento. -**Caídas de llamadas a herramientas**: algunas traducciones de formatos pueden eliminar campos no admitidos; verificar en modo Patio de Juegos -**Falta el mensaje del sistema**: Claude y Gemini manejan los mensajes del sistema de manera diferente; comprobar la salida de la traducción -**El SDK devuelve una cadena sin formato en lugar de un objeto**— Corregido en v1.1.0: el desinfectante de respuesta ahora elimina los campos no estándar (`x_groq`, `usage_breakdown`, etc.) que causan fallas de validación de Pydantic en el SDK de OpenAI -**GLM/ERNIE rechaza la función `sistema`**— Corregido en v1.1.0: el normalizador de funciones fusiona automáticamente mensajes del sistema con mensajes de usuario para modelos incompatibles -**Rol de "desarrollador" no reconocido**- Corregido en v1.1.0: convertido automáticamente a "sistema" para proveedores que no son OpenAI -**`json_schema` no funciona con Gemini**— Corregido en v1.1.0: `response_format` ahora se convierte a `responseMimeType` + `responseSchema` de Gemini---
+### Common format issues
+
+- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
+- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
+- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
+- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures
+- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
+- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers
+- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema`
+
+---
 
 ## Resilience Settings
 
 ### Auto rate-limit not triggering
 
-- El límite de velocidad automático solo se aplica a los proveedores de claves API (no a OAuth/suscripción)
-- Verifique que**Configuración → Resiliencia → Perfiles de proveedores**tenga habilitado el límite de tasa automática
-- Verifique si el proveedor devuelve códigos de estado `429` o encabezados `Reintentar después`### Tuning exponential backoff
+- Auto rate-limit only applies to API key providers (not OAuth/subscription)
+- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
+- Check if the provider returns `429` status codes or `Retry-After` headers
 
-Los perfiles de proveedor admiten estas configuraciones:
+### Tuning exponential backoff
 
--**Retraso base**: tiempo de espera inicial después del primer fallo (predeterminado: 1 s) -**Retraso máximo**: límite máximo de tiempo de espera (predeterminado: 30 segundos) -**Multiplicador**: cuánto aumentar el retraso por falla consecutiva (predeterminado: 2x)### Anti-thundering herd
+Provider profiles support these settings:
 
-Cuando muchas solicitudes simultáneas llegan a un proveedor de velocidad limitada, OmniRoute utiliza mutex + limitación de velocidad automática para serializar solicitudes y evitar fallas en cascada. Esto es automático para los proveedores de claves API.---
+- **Base delay** — Initial wait time after first failure (default: 1s)
+- **Max delay** — Maximum wait time cap (default: 30s)
+- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
+
+### Anti-thundering herd
+
+When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
+
+---
 
 ## Optional RAG / LLM failure taxonomy (16 problems)
 
@@ -199,4 +307,8 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
 
 ## Still Stuck?
 
--**Problemas de GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -**Arquitectura**: consulte [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) para obtener detalles internos -**Referencia de API**: consulte [`docs/API_REFERENCE.md`](API_REFERENCE.md) para todos los puntos finales -**Panel de estado**: marque**Panel → Salud**para ver el estado del sistema en tiempo real -**Traductor**: use**Panel → Traductor**para depurar problemas de formato
+- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
+- **Translator**: Use **Dashboard → Translator** to debug format issues

docs/i18n/es/docs/VM_DEPLOYMENT_GUIDE.md

@@ -100,7 +100,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/es/llm.txt

@@ -0,0 +1,476 @@
+# OmniRoute (Español)
+
+🌐 **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.
+
+## Resumen
+
+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)
+
+### Seguridad
+- **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/fi/docs/ARCHITECTURE.md

@@ -4,80 +4,91 @@
 
 ---
 
-_Viimeksi päivitetty: 2026-03-28_## Executive Summary
+_Last updated: 2026-03-28_
 
-OmniRoute on paikallinen AI-reititysyhdyskäytävä ja kojelauta, joka on rakennettu Next.js:lle.
-Se tarjoaa yhden OpenAI-yhteensopivan päätepisteen (`/v1/*`) ja reitittää liikenteen useiden alkupään palveluntarjoajien kesken kääntämisen, varaajan, tunnuksen päivityksen ja käytön seurannan avulla.
+## Executive Summary
 
-Ydinominaisuudet:
+OmniRoute is a local AI routing gateway and dashboard built on Next.js.
+It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
 
-- OpenAI-yhteensopiva API-pinta CLI:lle/työkaluille (28 toimittajaa)
-- Pyydä/vastaa käännös palveluntarjoajan eri formaattien välillä
-- Mallin yhdistelmävara (usean mallin sarja)
-- Tilitason varatoiminto (usea tili palveluntarjoajaa kohti)
-- OAuth + API-avain tarjoajan yhteyden hallinta
-- Upottamisen luominen /v1/embeddings-tiedoston kautta (6 palveluntarjoajaa, 9 mallia)
-- Kuvien luominen /v1/images/generations-tiedoston kautta (4 toimittajaa, 9 mallia)
-- Ajattele tagien jäsentämistä (`<think>...</think>`) päättelymalleille
-- Vastauksen desinfiointi tiukan OpenAI SDK -yhteensopivuuden takaamiseksi
-- Roolien normalisointi (kehittäjä→järjestelmä, järjestelmä→käyttäjä) palveluntarjoajien välistä yhteensopivuutta varten
-- Strukturoitu lähdön muunnos (json_schema → Gemini responseSchema)
-- Paikallinen pysyvyys tarjoajille, avaimille, aliaksille, yhdistelmille, asetuksille, hinnoittelulle
-- Käytön/kustannusten seuranta ja pyyntöjen kirjaaminen
-- Valinnainen pilvisynkronointi usean laitteen/tilan synkronointiin
-- IP-sallitut / estolistat API-käyttöoikeuksien hallinnassa
-- Ajatteleva budjetin hallinta (läpivienti/automaattinen/mukautettu/mukautuva)
-- Globaali järjestelmän nopea ruiskutus
-- Istunnon seuranta ja sormenjäljet
-- Tilikohtainen tehostettu hintarajoitus tarjoajakohtaisilla profiileilla
-- Katkaisijakuvio palveluntarjoajan joustavuuden parantamiseksi
-- Ukkosta estävä laumasuoja mutex-lukolla
-- Allekirjoituspohjainen pyyntöjen duplikoinnin välimuisti
-- Verkkotunnustaso: mallin saatavuus, hintasäännöt, varakäytäntö, lukituskäytäntö
-- Verkkotunnuksen tilan pysyvyys (SQLite-kirjoitusvälimuisti varauksille, budjeteille, lukituksille, katkaisimille)
-- Käytäntömoottori keskitettyä pyyntöjen arviointia varten (sulku → budjetti → vara)
-- Pyydä telemetriaa p50/p95/p99-latenssiaggregaatiolla
-- Korrelaatiotunnus (X-Request-Id) päästä päähän -jäljitykseen
-- Vaatimustenmukaisuuden tarkastuksen kirjaaminen ja opt-out API-avaimella
-- Eval-kehys LLM-laadunvarmistukseen
-- Joustavan käyttöliittymän kojelauta, jossa on reaaliaikainen katkaisijatila
-- Modulaariset OAuth-palveluntarjoajat (12 yksittäistä moduulia kohdassa "src/lib/oauth/providers/")
+Core capabilities:
 
-Ensisijainen suoritusaikamalli:
+- OpenAI-compatible API surface for CLI/tools (28 providers)
+- Request/response translation across provider formats
+- Model combo fallback (multi-model sequence)
+- Account-level fallback (multi-account per provider)
+- OAuth + API-key provider connection management
+- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
+- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Think tag parsing (`<think>...</think>`) for reasoning models
+- Response sanitization for strict OpenAI SDK compatibility
+- Role normalization (developer→system, system→user) for cross-provider compatibility
+- Structured output conversion (json_schema → Gemini responseSchema)
+- Local persistence for providers, keys, aliases, combos, settings, pricing
+- Usage/cost tracking and request logging
+- Optional cloud sync for multi-device/state sync
+- IP allowlist/blocklist for API access control
+- Thinking budget management (passthrough/auto/custom/adaptive)
+- Global system prompt injection
+- Session tracking and fingerprinting
+- Per-account enhanced rate limiting with provider-specific profiles
+- Circuit breaker pattern for provider resilience
+- Anti-thundering herd protection with mutex locking
+- Signature-based request deduplication cache
+- Domain layer: model availability, cost rules, fallback policy, lockout policy
+- 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
+- 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/`)
 
-- Next.js-sovellusreitit kohdassa `src/app/api/*` toteuttavat sekä hallintapaneelin sovellusliittymiä että yhteensopivuussovellusliittymiä
-- Jaettu SSE/reititysydin kohdassa `src/sse/*` + `open-sse/*` hoitaa palveluntarjoajan suorittamisen, käännöksen, suoratoiston, varatoiminnon ja käytön## Scope and Boundaries
+Primary runtime model:
+
+- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
+- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
+
+## Scope and Boundaries
 
 ### In Scope
 
-- Paikallisen yhdyskäytävän suoritusaika
-- Kojelaudan hallintasovellusliittymät
-- Palveluntarjoajan todennus ja tunnuksen päivitys
-- Pyydä käännöstä ja SSE-suoratoistoa
-- Paikallinen tila + käytön pysyvyys
-- Valinnainen pilvisynkronointiorkesteri### Out of Scope
+- Local gateway runtime
+- Dashboard management APIs
+- Provider authentication and token refresh
+- Request translation and SSE streaming
+- Local state + usage persistence
+- Optional cloud sync orchestration
 
-- Pilvipalvelun toteutus osoitteen "NEXT_PUBLIC_CLOUD_URL" takana
-- Palveluntarjoajan SLA/ohjaustaso paikallisen prosessin ulkopuolella
-- Itse ulkoiset CLI-binaarit (Claude CLI, Codex CLI jne.)## Dashboard Surface (Current)
+### Out of Scope
 
-Pääsivut kohdassa `src/app/(dashboard)/dashboard/`:
+- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
+- Provider SLA/control plane outside local process
+- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
 
-- `/dashboard` — pika-aloitus + palveluntarjoajan yleiskatsaus
-- "/dashboard/endpoint" - päätepisteen välityspalvelin + MCP + A2A + API-päätepisteen välilehdet
-- "/dashboard/providers" — palveluntarjoajan yhteydet ja tunnistetiedot
-- "/dashboard/combos" - yhdistelmästrategiat, mallit, mallin reitityssäännöt
-- "/dashboard/costs" — kustannusten yhteenlaskettu ja hinnoittelun näkyvyys
-- `/dashboard/analytics' — käyttöanalytiikka ja arvioinnit
-- "/dashboard/limits" - kiintiön/hinnan säätimet
-- "/dashboard/cli-tools" - CLI:n käyttöönotto, suorituksenaikainen tunnistus, asetusten luominen
-- "/dashboard/agents" — havaitut ACP-agentit + mukautetun agentin rekisteröinti
-- `/dashboard/media` — kuvan/videon/musiikin leikkipaikka
-- `/dashboard/search-tools' — hakupalveluntarjoajan testaus ja historia
-- `/dashboard/health' — käytettävyysaika, katkaisijat, nopeusrajoitukset
-- "/dashboard/logs" — pyyntö/välityspalvelin/tarkastus/konsolilokit
-- "/dashboard/settings" — järjestelmäasetusten välilehdet (yleiset, reititys, yhdistelmäoletusasetukset jne.)
-- `/dashboard/api-manager` — API-avaimen elinkaaren ja mallin käyttöoikeudet## High-Level System Context
+## Dashboard Surface (Current)
+
+Main pages under `src/app/(dashboard)/dashboard/`:
+
+- `/dashboard` — quick start + provider overview
+- `/dashboard/endpoint` — endpoint proxy + MCP + A2A + API endpoint tabs
+- `/dashboard/providers` — provider connections and credentials
+- `/dashboard/combos` — combo strategies, templates, model routing rules
+- `/dashboard/costs` — cost aggregation and pricing visibility
+- `/dashboard/analytics` — usage analytics and evaluations
+- `/dashboard/limits` — quota/rate controls
+- `/dashboard/cli-tools` — CLI onboarding, runtime detection, config generation
+- `/dashboard/agents` — detected ACP agents + custom agent registration
+- `/dashboard/media` — image/video/music playground
+- `/dashboard/search-tools` — search provider testing and history
+- `/dashboard/health` — uptime, circuit breakers, rate limits
+- `/dashboard/logs` — request/proxy/audit/console logs
+- `/dashboard/settings` — system settings tabs (general, routing, combo defaults, etc.)
+- `/dashboard/api-manager` — API key lifecycle and model permissions
+
+## High-Level System Context
 
 ```mermaid
 flowchart LR
@@ -129,139 +140,151 @@ flowchart LR
 
 ## 1) API and Routing Layer (Next.js App Routes)
 
-Päähakemistot:
+Main directories:
 
-- `src/app/api/v1/*` ja `src/app/api/v1beta/*` yhteensopiville sovellusliittymille
-- `src/app/api/*` hallinta-/määrityssovellusliittymille
-- Seuraavaksi kirjoitetaan uudelleen `next.config.mjs`-kartassa `/v1/*` muotoon `/api/v1/*`
+- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
+- `src/app/api/*` for management/configuration APIs
+- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
 
-Tärkeitä yhteensopivuusreittejä:
+Important compatibility routes:
 
-- `src/app/api/v1/chat/completions/route.ts'
-- "src/app/api/v1/messages/route.ts".
-- "src/app/api/v1/responses/route.ts".
-- "src/app/api/v1/models/route.ts" - sisältää mukautettuja malleja "custom: true"
-- "src/app/api/v1/embeddings/route.ts" - upotuksen sukupolvi (6 tarjoajaa)
-- "src/app/api/v1/images/generations/route.ts" - kuvien luominen (4+ tarjoajaa, mukaan lukien Antigravity/Nebius)
+- `src/app/api/v1/chat/completions/route.ts`
+- `src/app/api/v1/messages/route.ts`
+- `src/app/api/v1/responses/route.ts`
+- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`
+- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)
+- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)
 - `src/app/api/v1/messages/count_tokens/route.ts`
-- "src/app/api/v1/providers/[provider]/chat/completions/route.ts" - palveluntarjoajakohtainen keskustelu
-- `src/app/api/v1/providers/[provider]/embeddings/route.ts' – omat palveluntarjoajakohtaiset upotukset
-- "src/app/api/v1/providers/[provider]/images/generations/route.ts" - palveluntarjoajakohtaiset kuvat
-- "src/app/api/v1beta/models/route.ts".
-- `src/app/api/v1beta/models/[...polku]/route.ts`
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images
+- `src/app/api/v1beta/models/route.ts`
+- `src/app/api/v1beta/models/[...path]/route.ts`
 
-Hallintoverkkotunnukset:
+Management domains:
 
-- Todennus/asetukset: `src/app/api/auth/*`, `src/app/api/settings/*`
-- Palveluntarjoajat/yhteydet: `src/app/api/providers*`
-- Palveluntarjoajan solmut: `src/app/api/provider-nodes\*'
-- Mukautetut mallit: `src/app/api/provider-models' (GET/POST/DELETE)
-- Malliluettelo: `src/app/api/models/route.ts' (GET)
-- Välityspalvelimen konfiguraatio: "src/app/api/settings/proxy" (GET/PUT/DELETE) + "src/app/api/settings/proxy/test" (POST)
+- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
+- Providers/connections: `src/app/api/providers*`
+- Provider nodes: `src/app/api/provider-nodes*`
+- Custom models: `src/app/api/provider-models` (GET/POST/DELETE)
+- Model catalog: `src/app/api/models/route.ts` (GET)
+- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
 - OAuth: `src/app/api/oauth/*`
-- Keys/aliases/combos/pricing: "src/app/api/keys*", "src/app/api/models/alias", "src/app/api/combos*", "src/app/api/pricing"
-- Käyttö: `src/app/api/usage/*`
-- Synkronointi/pilvi: `src/app/api/sync/*`, `src/app/api/cloud/*`
-- CLI-työkalujen apuohjelmat: `src/app/api/cli-tools/*`
-- IP-suodatin: `src/app/api/settings/ip-filter' (GET/PUT)
-- Thinking-budjetti: `src/app/api/settings/thinking-budget' (GET/PUT)
-- Järjestelmäkehote: `src/app/api/settings/system-prompt' (GET/PUT)
-- Istunnot: `src/app/api/sessions' (GET)
-- Nopeusrajoitukset: `src/app/api/rate-limits' (GET)
-- Kestävyys: "src/app/api/resilience" (GET/PATCH) – palveluntarjoajan profiilit, katkaisija, nopeusrajoitustila
-- Kestävyyden nollaus: "src/app/api/resilience/reset" (POST) - nollaa katkaisijat + jäähdytys
-- Välimuistitilastot: `src/app/api/cache/stats' (GET/DELETE)
-- Mallin saatavuus: `src/app/api/models/availability' (GET/POST)
-- Telemetria: "src/app/api/telemetry/summary" (GET)
-- Budjetti: `src/app/api/usage/budget' (GET/POST)
-- Varaketjut: `src/app/api/fallback/chains' (GET/POST/DELETE)
-- Vaatimustenmukaisuuden tarkastus: `src/app/api/compliance/audit-log' (GET)
-- Evals: "src/app/api/evals" (GET/POST), "src/app/api/evals/[suiteId]" (GET)
-- Käytännöt: `src/app/api/policies' (GET/POST)## 2) SSE + Translation Core
+- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
+- Usage: `src/app/api/usage/*`
+- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
+- CLI tooling helpers: `src/app/api/cli-tools/*`
+- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)
+- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)
+- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)
+- Sessions: `src/app/api/sessions` (GET)
+- Rate limits: `src/app/api/rate-limits` (GET)
+- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns
+- Cache stats: `src/app/api/cache/stats` (GET/DELETE)
+- Model availability: `src/app/api/models/availability` (GET/POST)
+- Telemetry: `src/app/api/telemetry/summary` (GET)
+- Budget: `src/app/api/usage/budget` (GET/POST)
+- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET)
+- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
+- Policies: `src/app/api/policies` (GET/POST)
 
-Päävirtausmoduulit:
+## 2) SSE + Translation Core
 
-- Merkintä: "src/sse/handlers/chat.ts".
-- Ydinorkesteri: `open-sse/handlers/chatCore.ts`
-- Tarjoajan suoritussovittimet: `open-sse/executors/*`
-- Muototunnistuksen/palveluntarjoajan kokoonpano: `open-sse/services/provider.ts`
-- Mallin jäsennys/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
-- Tilin varalogiikka: "open-sse/services/accountFallback.ts".
-- Käännösrekisteri: "open-sse/translator/index.ts".
-- Stream-muunnokset: "open-sse/utils/stream.ts", "open-sse/utils/streamHandler.ts"
-- Käytön purkaminen/normalisointi: `open-sse/utils/usageTracking.ts`
-- Think tag -parser: `open-sse/utils/thinkTagParser.ts`
-- Upotuskäsittelijä: "open-sse/handlers/embeddings.ts".
-- Upotuspalveluntarjoajan rekisteri: `open-sse/config/embeddingRegistry.ts`
-- Kuvanluontikäsittelijä: "open-sse/handlers/imageGeneration.ts".
-- Kuvantarjoajan rekisteri: "open-sse/config/imageRegistry.ts".
-- Vastauksen desinfiointi: "open-sse/handlers/responseSanitizer.ts"
-- Roolin normalisointi: "open-sse/services/roleNormalizer.ts".
+Main flow modules:
 
-Palvelut (liiketoimintalogiikka):
+- Entry: `src/sse/handlers/chat.ts`
+- Core orchestration: `open-sse/handlers/chatCore.ts`
+- Provider execution adapters: `open-sse/executors/*`
+- Format detection/provider config: `open-sse/services/provider.ts`
+- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
+- Account fallback logic: `open-sse/services/accountFallback.ts`
+- Translation registry: `open-sse/translator/index.ts`
+- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
+- Think tag parser: `open-sse/utils/thinkTagParser.ts`
+- Embedding handler: `open-sse/handlers/embeddings.ts`
+- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
+- Image generation handler: `open-sse/handlers/imageGeneration.ts`
+- Image provider registry: `open-sse/config/imageRegistry.ts`
+- Response sanitization: `open-sse/handlers/responseSanitizer.ts`
+- Role normalization: `open-sse/services/roleNormalizer.ts`
 
-- Tilin valinta/pisteytys: `open-sse/services/accountSelector.ts`
-- Kontekstin elinkaarihallinta: `open-sse/services/contextManager.ts`
-- IP-suodattimen valvonta: "open-sse/services/ipFilter.ts".
-- Istunnon seuranta: `open-sse/services/sessionManager.ts`
-- Pyydä päällekkäisyyden poistoa: `open-sse/services/signatureCache.ts`
-- Järjestelmäkehotteen lisäys: "open-sse/services/systemPrompt.ts".
-- Ajatteleva budjetin hallinta: "open-sse/services/thinkingBudget.ts"
-- Jokerimerkkimallin reititys: `open-sse/services/wildcardRouter.ts`
-- Hintarajan hallinta: `open-sse/services/rateLimitManager.ts`
-- Katkaisija: "open-sse/services/circuitBreaker.ts"
+Services (business logic):
 
-Domain-kerroksen moduulit:
+- Account selection/scoring: `open-sse/services/accountSelector.ts`
+- Context lifecycle management: `open-sse/services/contextManager.ts`
+- IP filter enforcement: `open-sse/services/ipFilter.ts`
+- Session tracking: `open-sse/services/sessionManager.ts`
+- Request deduplication: `open-sse/services/signatureCache.ts`
+- System prompt injection: `open-sse/services/systemPrompt.ts`
+- Thinking budget management: `open-sse/services/thinkingBudget.ts`
+- Wildcard model routing: `open-sse/services/wildcardRouter.ts`
+- Rate limit management: `open-sse/services/rateLimitManager.ts`
+- Circuit breaker: `open-sse/services/circuitBreaker.ts`
+- 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
 
-- Mallin saatavuus: "src/lib/domain/modelAvailability.ts".
-- Kustannussäännöt/budjetit: `src/lib/domain/costRules.ts`
-- Varakäytäntö: "src/lib/domain/fallbackPolicy.ts".
-- Yhdistelmäratkaisu: `src/lib/domain/comboResolver.ts'
-- Lukituskäytäntö: "src/lib/domain/lockoutPolicy.ts".
-- Käytäntömoottori: "src/domain/policyEngine.ts" — keskitetty lukitus → budjetti → varaarviointi
-- Virhekoodiluettelo: "src/lib/domain/errorCodes.ts".
-- Pyyntötunnus: `src/lib/domain/requestId.ts'
-- Haun aikakatkaisu: "src/lib/domain/fetchTimeout.ts".
-- Pyydä telemetriaa: `src/lib/domain/requestTelemetry.ts`
-- Vaatimustenmukaisuus/tarkastus: `src/lib/domain/compliance/index.ts'
+Domain layer modules:
+
+- Model availability: `src/lib/domain/modelAvailability.ts`
+- Cost rules/budgets: `src/lib/domain/costRules.ts`
+- Fallback policy: `src/lib/domain/fallbackPolicy.ts`
+- Combo resolver: `src/lib/domain/comboResolver.ts`
+- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
+- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
+- Error codes catalog: `src/lib/domain/errorCodes.ts`
+- Request ID: `src/lib/domain/requestId.ts`
+- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
+- Request telemetry: `src/lib/domain/requestTelemetry.ts`
+- Compliance/audit: `src/lib/domain/compliance/index.ts`
 - Eval runner: `src/lib/domain/evalRunner.ts`
-- Verkkotunnuksen tilan pysyvyys: `src/lib/db/domainState.ts' — SQLite CRUD varaketjuille, budjeteille, kustannushistorialle, lukitustilalle, katkaisimille
+- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
 
-OAuth-palveluntarjoajan moduulit (12 yksittäistä tiedostoa kohdassa "src/lib/oauth/providers/"):
+OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
-- Rekisterihakemisto: "src/lib/oauth/providers/index.ts".
-- Yksittäiset palveluntarjoajat: "claude.ts", "codex.ts", "gemini.ts", "antigravity.ts", "qoder.ts", "qwen.ts", "kimi-coding.ts", "github.ts", "kiro.cursorts", `cline.ts`
-- Ohut kääre: "src/lib/oauth/providers.ts" - uudelleenvienti yksittäisistä moduuleista## 3) Persistence Layer
+- 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`
+- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
-Ensisijainen tila DB (SQLite):
+## 3) Persistence Layer
 
-- Ydininfrastruktuuri: "src/lib/db/core.ts" (better-sqlite3, migraatiot, WAL)
-- Vie julkisivu uudelleen: "src/lib/localDb.ts" (ohut yhteensopivuuskerros soittajille)
-- tiedosto: `${DATA_DIR}/storage.sqlite` (tai `$XDG_CONFIG_HOME/omniroute/storage.sqlite`, kun se on asetettu, muuten `~/.omniroute/storage.sqlite`)
-- entiteetit (taulukot + KV-nimitilat): providerConnections, providerNodes, mallialiakset, yhdistelmät, apiKeys, asetukset, hinnoittelu,**customModels**,**proxyConfig**,**ipFilter**,**thhinkingBudget**,**systemPrompt**
+Primary state DB (SQLite):
 
-Käytön pysyvyys:
+- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL)
+- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers)
+- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`)
+- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
 
-- julkisivu: "src/lib/usageDb.ts" (hajotetut moduulit tiedostossa "src/lib/usage/\*")
-- SQLite-taulukot tiedostossa "storage.sqlite": "usage_history", "call_logs", "proxy_logs"
-- valinnaiset tiedostoartefaktit jäävät yhteensopivuutta/virheenkorjausta varten (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
-- Vanhat JSON-tiedostot siirretään SQLiteen käynnistyssiirroilla, kun ne ovat olemassa
+Usage persistence:
+
+- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`)
+- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
+- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
+- legacy JSON files are migrated to SQLite by startup migrations when present
 
 Domain State DB (SQLite):
 
-- "src/lib/db/domainState.ts" - CRUD-toiminnot toimialueen tilalle
-- Taulukot (luodut tiedostossa "src/lib/db/core.ts"): "domain_fallback_chains", "domain_budgets", "domain_cost_history", "domain_lockout_state", "domain_circuit_breakers"
-- Kirjoitusvälimuistin malli: muistissa olevat kartat ovat arvovaltaisia ajon aikana; mutaatiot kirjoitetaan synkronisesti SQLiten kanssa; tila palautetaan DB:stä kylmäkäynnistyksen yhteydessä## 4) Auth + Security Surfaces
+- `src/lib/db/domainState.ts` — CRUD operations for domain state
+- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
+- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
 
-- Hallintapaneelin evästeiden todennus: "src/proxy.ts", "src/app/api/auth/login/route.ts"
-- API-avaimen luonti/vahvistus: `src/shared/utils/apiKey.ts`
-- Palveluntarjoajan salaisuudet säilyivät "providerConnections"-merkinnöissä
-- Lähtevän välityspalvelimen tuki "open-sse/utils/proxyFetch.ts" (env vars) ja "open-sse/utils/networkProxy.ts" kautta (määritettävä palveluntarjoajakohtaisesti tai globaali)## 5) Cloud Sync
+## 4) Auth + Security Surfaces
 
-- Aikataulun aloitus: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
-- Säännöllinen tehtävä: `src/shared/services/cloudSyncScheduler.ts`
-- Säännöllinen tehtävä: `src/shared/services/modelSyncScheduler.ts`
-- Hallitse reittiä: `src/app/api/sync/cloud/route.ts'## Request Lifecycle (`/v1/chat/completions`)
+- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
+- API key generation/verification: `src/shared/utils/apiKey.ts`
+- Provider secrets persisted in `providerConnections` entries
+- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
+
+## 5) Cloud Sync
+
+- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
+- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Periodic task: `src/shared/services/modelSyncScheduler.ts`
+- Control route: `src/app/api/sync/cloud/route.ts`
+
+## Request Lifecycle (`/v1/chat/completions`)
 
 ```mermaid
 sequenceDiagram
@@ -338,7 +361,9 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-Varapäätökset tehdään "open-sse/services/accountFallback.ts":n avulla tilakoodeja ja virheviestiheuristiikkaa käyttäen. Yhdistelmäreititys lisää yhden ylimääräisen suojan: palveluntarjoajan kattamat 400:t, kuten ylävirran sisällön lohko- ja roolivahvistuksen epäonnistumiset, käsitellään mallin paikallisina virheinä, jotta myöhempiä yhdistelmäkohteita voidaan edelleen suorittaa.## OAuth Onboarding and Token Refresh Lifecycle
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run.
+
+## OAuth Onboarding and Token Refresh Lifecycle
 
 ```mermaid
 sequenceDiagram
@@ -368,7 +393,9 @@ sequenceDiagram
     Test-->>UI: validation result
 ```
 
-Päivitys reaaliaikaisen liikenteen aikana suoritetaan "open-sse/handlers/chatCore.ts" -tiedostossa suorittimen "refreshCredentials()" kautta.## Cloud Sync Lifecycle (Enable / Sync / Disable)
+Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
+
+## Cloud Sync Lifecycle (Enable / Sync / Disable)
 
 ```mermaid
 sequenceDiagram
@@ -400,7 +427,9 @@ sequenceDiagram
     Sync-->>UI: disabled
 ```
 
-"CloudSyncScheduler" käynnistää säännöllisen synkronoinnin, kun pilvi on käytössä.## Data Model and Storage Map
+Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
+
+## Data Model and Storage Map
 
 ```mermaid
 erDiagram
@@ -501,12 +530,14 @@ erDiagram
     }
 ```
 
-Fyysiset tallennustiedostot:
+Physical storage files:
 
-- ensisijainen ajonaikainen tietokanta: `${DATA_DIR}/storage.sqlite`
-- pyyntölokin rivit: `${DATA_DIR}/log.txt` (compat/debug artefact)
-- jäsennellyt puhelun hyötykuorma-arkistot: `${DATA_DIR}/call_logs/`
-- valinnainen kääntäjä/pyydä virheenkorjausistuntoja: `<repo>/logs/...`## Deployment Topology
+- primary runtime DB: `${DATA_DIR}/storage.sqlite`
+- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact)
+- structured call payload archives: `${DATA_DIR}/call_logs/`
+- optional translator/request debug sessions: `<repo>/logs/...`
+
+## Deployment Topology
 
 ```mermaid
 flowchart LR
@@ -541,205 +572,248 @@ flowchart LR
 
 ### Route and API Modules
 
-- `src/app/api/v1/*`, `src/app/api/v1beta/*`: yhteensopivuussovellusliittymät
-- `src/app/api/v1/providers/[provider]/*`: omat palveluntarjoajakohtaiset reitit (chat, upotukset, kuvat)
-- `src/app/api/providers\*: palveluntarjoajan CRUD, validointi, testaus
-- `src/app/api/provider-nodes\*: mukautettu yhteensopiva solmuhallinta
-- "src/app/api/provider-models": mukautetun mallin hallinta (CRUD)
-- "src/app/api/models/route.ts": malliluettelon sovellusliittymä (aliakset + mukautetut mallit)
-- `src/app/api/oauth/*`: OAuth/laitekoodikulku
-- `src/app/api/keys\*: paikallisen API-avaimen elinkaari
-- "src/app/api/models/alias": aliaksen hallinta
-- `src/app/api/combos*`: varayhdistelmähallinta
-- "src/app/api/pricing": hinnoittelu ohittaa kustannuslaskennan
-- "src/app/api/settings/proxy": välityspalvelimen määritykset (GET/PUT/DELETE)
-- "src/app/api/settings/proxy/test": lähtevän välityspalvelimen yhteystesti (POST)
-- `src/app/api/usage/*`: käyttö- ja lokisovellusliittymät
-- `src/app/api/sync/*` + `src/app/api/cloud/*`: pilvisynkronointi ja pilveen suuntautuvat apuohjelmat
-- `src/app/api/cli-tools/*`: paikalliset CLI-asetusten kirjoittajat/tarkistajat
-- `src/app/api/settings/ip-filter': IP-sallittujen luettelo/estolista (GET/PUT)
-- `src/app/api/settings/thhinking-budget': ajattelutunnuksen budjetin konfiguraatio (GET/PUT)
-- "src/app/api/settings/system-prompt": yleinen järjestelmäkehote (GET/PUT)
-- `src/app/api/sessions': aktiivisten istuntojen luettelo (GET)
-- "src/app/api/rate-limits": tilikohtainen korkorajoitustila (GET)### Routing and Execution Core
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
+- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
+- `src/app/api/providers*`: provider CRUD, validation, testing
+- `src/app/api/provider-nodes*`: custom compatible node management
+- `src/app/api/provider-models`: custom model management (CRUD)
+- `src/app/api/models/route.ts`: model catalog API (aliases + custom models)
+- `src/app/api/oauth/*`: OAuth/device-code flows
+- `src/app/api/keys*`: local API key lifecycle
+- `src/app/api/models/alias`: alias management
+- `src/app/api/combos*`: fallback combo management
+- `src/app/api/pricing`: pricing overrides for cost calculation
+- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
+- `src/app/api/usage/*`: usage and logs APIs
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
+- `src/app/api/cli-tools/*`: local CLI config writers/checkers
+- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
+- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
+- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
+- `src/app/api/sessions`: active session listing (GET)
+- `src/app/api/rate-limits`: per-account rate limit status (GET)
 
-- `src/sse/handlers/chat.ts: pyynnön jäsennys, yhdistelmäkäsittely, tilin valintasilmukka
-- `open-sse/handlers/chatCore.ts`: käännös, suorittimen lähettäminen, uudelleenyritys/päivityskäsittely, streamin määritys
-- `open-sse/executors/*`: palveluntarjoajakohtainen verkko- ja muotokäyttäytyminen### Translation Registry and Format Converters
+### Routing and Execution Core
 
-- "open-sse/translator/index.ts": kääntäjien rekisteri ja orkestrointi
-- Pyydä kääntäjiä: `open-sse/translator/request/*`
-- Vastauskääntäjät: `open-sse/translator/response/*`
-- Muotovakiot: "open-sse/translator/formats.ts".### Persistence
+- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
+- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
+- `open-sse/executors/*`: provider-specific network and format behavior
 
-- `src/lib/db/*`: pysyvä konfiguraatio/tila ja verkkotunnuksen pysyvyys SQLitessa
-- `src/lib/localDb.ts`: DB-moduulien yhteensopivuuden uudelleenvienti
-- `src/lib/usageDb.ts`: käyttöhistorian/puhelulokien julkisivu SQLite-taulukoiden päällä## Provider Executor Coverage (Strategy Pattern)
+### Translation Registry and Format Converters
 
-Jokaisella palveluntarjoajalla on erikoistunut suorittaja, joka laajentaa "BaseExecutoria" (hakemistossa "open-sse/executors/base.ts"), joka tarjoaa URL-osoitteen rakentamisen, otsikon rakentamisen, uudelleenyrityksen eksponentiaalisella perääntymisellä, valtuustietojen päivityskoukut ja execute()-orkesterimenetelmän.
+- `open-sse/translator/index.ts`: translator registry and orchestration
+- Request translators: `open-sse/translator/request/*`
+- Response translators: `open-sse/translator/response/*`
+- Format constants: `open-sse/translator/formats.ts`
 
-| Toteuttaja            | Palveluntarjoaja(t)                                                                                                                                           | Erikoiskäsittely                                                                      |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| "DefaultExecutor"     | OpenAI, Claude, Gemini, Qwen, Qoder, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, ilotulitus, Cerebras, Cohere, NVIDIA | Dynaaminen URL-/otsikkomääritykset tarjoajakohtaisesti                                |
-| "AntigravityExecutor" | Google Antigravity                                                                                                                                            | Mukautetut projekti-/istuntotunnukset, Yritä uudelleen jäsentämisen jälkeen           |
-| "CodexExecutor"       | OpenAI Codex                                                                                                                                                  | Syöttää järjestelmäohjeita, pakottaa päättelyponnistuksen                             |
-| "CursorExecutor"      | Kohdistin IDE                                                                                                                                                 | ConnectRPC-protokolla, Protobuf-koodaus, pyynnön allekirjoitus tarkistussumman kautta |
-| "GithubExecutor"      | GitHub Copilot                                                                                                                                                | Copilot-tunnuksen päivitys, VSC-koodia jäljittelevät otsikot                          |
-| "KiroExecutor"        | AWS CodeWhisperer/Kiro                                                                                                                                        | AWS EventStream binaarimuoto → SSE-muunnos                                            |
-| "GeminiCLIExecutor"   | Gemini CLI                                                                                                                                                    | Google OAuth -tunnuksen päivitysjakso                                                 |
+### Persistence
 
-Kaikki muut palveluntarjoajat (mukaan lukien mukautetut yhteensopivat solmut) käyttävät DefaultExecutoria.## Provider Compatibility Matrix
+- `src/lib/db/*`: persistent config/state and domain persistence on SQLite
+- `src/lib/localDb.ts`: compatibility re-export for DB modules
+- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables
 
-| Palveluntarjoaja | Muoto             | Auth                      | Striimaa             | Ei-stream | Token Refresh | Käyttösovellusliittymä      |
-| ---------------- | ----------------- | ------------------------- | -------------------- | --------- | ------------- | --------------------------- | ------------------------------ |
-| Claude           | claude            | API-avain / OAuth         | ✅                   | ✅        | ✅            | ⚠️ Vain järjestelmänvalvoja |
-| Kaksoset         | kaksoset          | API-avain / OAuth         | ✅                   | ✅        | ✅            | ⚠️ Cloud Console            |
-| Gemini CLI       | gemini-cli        | OAuth                     | ✅                   | ✅        | ✅            | ⚠️ Cloud Console            |
-| Antigravitaatio  | antigravitaatio   | OAuth                     | ✅                   | ✅        | ✅            | ✅ Full quota API           |
-| OpenAI           | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
-| Codex            | openai-vastaukset | OAuth                     | ✅ pakotettu         | ❌        | ✅            | ✅ Hintarajat               |
-| GitHub Copilot   | openai            | OAuth + Copilot Token     | ✅                   | ✅        | ✅            | ✅ Kiintiön tilannekuvat    |
-| Kursori          | kohdistin         | Mukautettu tarkistussumma | ✅                   | ✅        | ❌            | ❌                          |
-| Kiro             | kiro              | AWS SSO OIDC              | ✅ (TapahtumaStream) | ❌        | ✅            | ✅ Käyttörajoitukset        |
-| Qwen             | openai            | OAuth                     | ✅                   | ✅        | ✅            | ⚠️ Pyynnöstä                |
-| Qoder            | openai            | OAuth (Perus)             | ✅                   | ✅        | ✅            | ⚠️ Pyynnöstä                |
-| OpenRouter       | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
-| GLM/Kimi/MiniMax | claude            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
-| DeepSeek         | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
-| Groq             | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
-| xAI (Grok)       | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
-| Mistral          | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
-| Hämmennys        | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
-| Yhdessä AI       | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
-| Ilotulitus AI    | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
-| Aivot            | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
-| Cohere           | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          |
-| NVIDIA NIM       | openai            | API-avain                 | ✅                   | ✅        | ❌            | ❌                          | ## Format Translation Coverage |
+## Provider Executor Coverage (Strategy Pattern)
 
-Havaittuja lähdemuotoja ovat:
+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.
 
-- "openai".
-- "openai-vastaukset".
-- "claude".
-- "kaksoset".
+| 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                                     |
 
-Kohdemuotoja ovat:
+All other providers (including custom compatible nodes) use the `DefaultExecutor`.
 
-- OpenAI chat / vastaukset
+## Provider Compatibility Matrix
+
+| Provider         | Format           | Auth                  | Stream           | Non-Stream | Token Refresh | Usage API          |
+| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
+| Claude           | claude           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Admin only      |
+| Gemini           | gemini           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Gemini CLI       | gemini-cli       | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Antigravity      | antigravity      | OAuth                 | ✅               | ✅         | ✅            | ✅ Full quota API  |
+| OpenAI           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Codex            | openai-responses | OAuth                 | ✅ forced        | ❌         | ✅            | ✅ Rate limits     |
+| GitHub Copilot   | openai           | OAuth + Copilot Token | ✅               | ✅         | ✅            | ✅ Quota snapshots |
+| Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
+| Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
+| Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Qoder            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Groq             | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| xAI (Grok)       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Mistral          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Perplexity       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Together AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Fireworks AI     | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+
+## Format Translation Coverage
+
+Detected source formats include:
+
+- `openai`
+- `openai-responses`
+- `claude`
+- `gemini`
+
+Target formats include:
+
+- OpenAI chat/Responses
 - Claude
-- Gemini/Gemini-CLI/Antigravity-kuori
+- Gemini/Gemini-CLI/Antigravity envelope
 - Kiro
-- Kursori
+- Cursor
 
-Käännöksissä käytetään keskitinmuotona**OpenAI-muotoa**— kaikki konversiot menevät OpenAI:n kautta välimuotona:```
+Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
+
+```
 Source Format → OpenAI (hub) → Target Format
+```
 
-````
+Translations are selected dynamically based on source payload shape and provider target format.
 
-Käännökset valitaan dynaamisesti lähteen hyötykuorman muodon ja toimittajan kohdemuodon perusteella.
+Additional processing layers in the translation pipeline:
 
-Muut käsittelytasot käännösputkessa:
+- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance
+- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)
+- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field
+- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`
 
--**Vastausten desinfiointi**– Poistaa standardista poikkeavat kentät OpenAI-muotoisista vastauksista (sekä suoratoistosta että ei-suoratoistosta) varmistaakseen tiukan SDK-yhteensopivuuden
--**Roolin normalisointi**— Muuntaa "kehittäjä" → "järjestelmä" muille kuin OpenAI-kohteille; yhdistää `system` → `user` malleille, jotka hylkäävät järjestelmäroolin (GLM, ERNIE)
--**Think-tunnisteen purkaminen**— Jäsentää "<think>...</think>" -lohkot sisällöstä "reasoning_content"-kenttään
--**Strukturoitu tulos**— Muuntaa OpenAI `response_format.json_schema` Geminin `responseMimeType` + `responseSchema`.## Supported API Endpoints
+## Supported API Endpoints
 
-| Päätepiste | Muoto | Käsittelijä |
-| --------------------------------------------------- | ------------------- | -------------------------------------------------------------------- |
-| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` |
-| `POST /v1/messages` | Claude Viestit | Sama käsittelijä (tunnistettu automaattisesti) |
-| `POST /v1/responses` | OpenAI-vastaukset | `open-sse/handlers/responsesHandler.ts` |
-| `POST /v1/embeddings` | OpenAI Embeddings | "open-sse/handlers/embeddings.ts" |
-| `HAE /v1/embeddings` | Malliluettelo | API reitti |
-| `POST /v1/images/generations` | OpenAI-kuvat | `open-sse/handlers/imageGeneration.ts` |
-| `GET /v1/images/generations` | Malliluettelo | API reitti |
-| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Palveluntarjoajakohtainen mallin validointi |
-| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Palveluntarjoajakohtainen mallin validointi |
-| `POST /v1/providers/{provider}/images/generations` | OpenAI-kuvat | Palveluntarjoajakohtainen mallin validointi |
-| `POST /v1/messages/count_tokens` | Claude Token Count | API reitti |
-| `HAE /v1/mallit` | OpenAI-mallien luettelo | API-reitti (chat + upotus + kuva + mukautetut mallit) |
-| "GET /api/models/catalog" | Luettelo | Kaikki mallit ryhmitelty tarjoajan + tyypin mukaan |
-| `POST /v1beta/models/*:streamGenerateContent` | Gemini syntyperäinen | API reitti |
-| `GET/PUT/DELETE /api/settings/proxy` | Välityspalvelimen kokoonpano | Verkon välityspalvelimen määritykset |
-| "POST /api/settings/proxy/test" | Välityspalvelinyhteydet | Välityspalvelimen kunto/yhteystestin päätepiste |
-| `GET/POST/DELETE /api/provider-models` | Palveluntarjoajan mallit | Palveluntarjoajan mallin metatietojen tausta mukautettuja ja hallittuja saatavilla olevia malleja |## Bypass Handler
+| Endpoint                                           | Format             | Handler                                                             |
+| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------- |
+| `POST /v1/chat/completions`                        | OpenAI Chat        | `src/sse/handlers/chat.ts`                                          |
+| `POST /v1/messages`                                | Claude Messages    | Same handler (auto-detected)                                        |
+| `POST /v1/responses`                               | OpenAI Responses   | `open-sse/handlers/responsesHandler.ts`                             |
+| `POST /v1/embeddings`                              | OpenAI Embeddings  | `open-sse/handlers/embeddings.ts`                                   |
+| `GET /v1/embeddings`                               | Model listing      | API route                                                           |
+| `POST /v1/images/generations`                      | OpenAI Images      | `open-sse/handlers/imageGeneration.ts`                              |
+| `GET /v1/images/generations`                       | Model listing      | API route                                                           |
+| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat        | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings  | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/images/generations` | OpenAI Images      | Dedicated per-provider with model validation                        |
+| `POST /v1/messages/count_tokens`                   | Claude Token Count | API route                                                           |
+| `GET /v1/models`                                   | OpenAI Models list | API route (chat + embedding + image + custom models)                |
+| `GET /api/models/catalog`                          | Catalog            | All models grouped by provider + type                               |
+| `POST /v1beta/models/*:streamGenerateContent`      | Gemini native      | API route                                                           |
+| `GET/PUT/DELETE /api/settings/proxy`               | Proxy Config       | Network proxy configuration                                         |
+| `POST /api/settings/proxy/test`                    | Proxy Connectivity | Proxy health/connectivity test endpoint                             |
+| `GET/POST/DELETE /api/provider-models`             | Provider Models    | Provider model metadata backing custom and managed available models |
 
-Ohituskäsittelijä (`open-sse/utils/bypassHandler.ts`) sieppaa Claude CLI:n tunnetut "heittopyynnöt" – lämmittelypingit, otsikon poiminnot ja tunnukset - ja palauttaa**väärennetyn vastauksen**kuluttamatta alkupään toimittajatunnuksia. Tämä käynnistyy vain, kun "User-Agent" sisältää "claude-cli".## Request Logger Pipeline
+## Bypass Handler
 
-Pyyntöloggeri (`open-sse/utils/requestLogger.ts`) tarjoaa 7-vaiheisen virheenkorjauslokiputken, joka on oletusarvoisesti pois käytöstä ja joka on käytössä kohdassa ENABLE_REQUEST_LOGS=true:```
-1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json
-→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt
-````
+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`.
 
-Tiedostot kirjoitetaan hakemistoon `<repo>/logs/<session>/` jokaista pyyntöistuntoa varten.## Failure Modes and Resilience
+## Request Logging and Artifacts
+
+The older file-based request logger (`open-sse/utils/requestLogger.ts`) is retained only for
+legacy compatibility. The current runtime contract uses:
+
+- `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
 
-- Palveluntarjoajan tilin jäähtyminen ohimenevien / nopeus / todennusvirheiden vuoksi
-- tilin varaosa ennen epäonnistunutta pyyntöä
-- Yhdistelmämallin palautus, kun nykyisen mallin/palveluntarjoajan polku on käytetty loppuun## 2) Token Expiry
+- provider account cooldown on transient/rate/auth errors
+- account fallback before failing request
+- combo model fallback when current model/provider path is exhausted
 
-- esitarkista ja päivitä yrittämällä uudelleen päivitettävien palveluntarjoajien kohdalla
-- 401/403 yritä uudelleen päivitysyrityksen jälkeen ydinpolulla## 3) Stream Safety
+## 2) Token Expiry
 
-- irrotettava stream-ohjain
-- käännösvirta streamin lopun huuhtelulla ja [VALMIS]-käsittelyllä
-- käyttöarvion varavaihtoehto, kun palveluntarjoajan käytön metatiedot puuttuvat## 4) Cloud Sync Degradation
+- pre-check and refresh with retry for refreshable providers
+- 401/403 retry after refresh attempt in core path
 
-- Synkronointivirheet tulevat esiin, mutta paikallinen suoritusaika jatkuu
-- ajastimessa on uudelleenyrityslogiikka, mutta säännöllinen suoritus tällä hetkellä kutsuu oletusarvoisesti yhden yrityksen synkronointia## 5) Data Integrity
+## 3) Stream Safety
 
-- SQLite-skeeman siirrot ja automaattisen päivityksen koukut käynnistyksen yhteydessä
-- vanha JSON → SQLite-siirtoyhteensopivuuspolku## Observability and Operational Signals
+- disconnect-aware stream controller
+- translation stream with end-of-stream flush and `[DONE]` handling
+- usage estimation fallback when provider usage metadata is missing
 
-Ajonaikaisen näkyvyyden lähteet:
+## 4) Cloud Sync Degradation
 
-- konsolin lokit osoitteesta "src/sse/utils/logger.ts".
-- SQLiten pyyntökohtaiset käyttöaggregaatit ("usage_history", "call_logs", "proxy_logs")
-- nelivaiheiset yksityiskohtaiset hyötykuorman kaappaukset SQLitessa (`request_detail_logs`), kun `settings.detailed_logs_enabled=true`
-- tekstimuotoisen pyynnön tilaloki tiedostossa "log.txt" (valinnainen/compat)
-- valinnaiset syvät pyyntö-/käännöslokit lokit/-kohdassa, kun ENABLE_REQUEST_LOGS=true
-- hallintapaneelin käyttöpäätepisteet (`/api/usage/*`) käyttöliittymän käyttöä varten
+- sync errors are surfaced but local runtime continues
+- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
 
-Yksityiskohtainen pyyntöhyötykuormakaappaus tallentaa jopa neljä JSON-hyötykuorman vaihetta reititettyä puhelua kohden:
+## 5) Data Integrity
 
-- Asiakkaalta saatu raakapyyntö
-- käännetty pyyntö todella lähetetty alkupäässä
-- palveluntarjoajan vastaus rekonstruoitu JSON-muodossa; suoratoistovastaukset tiivistetään lopulliseksi yhteenvedoksi ja virran metadataksi
-- OmniRouten palauttama lopullinen asiakkaan vastaus; suoratoistovastaukset tallennetaan samaan kompaktiin tiivistelmään## Security-Sensitive Boundaries
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
-- JWT-salaisuus (`JWT_SECRET`) suojaa hallintapaneelin istunnon evästeen vahvistuksen/allekirjoituksen
-- Alkuperäisen salasanan käynnistys (`INITIAL_PASSWORD`) on määritettävä eksplisiittisesti ensiajoa varten
-- API-avaimen HMAC-salaisuus (`API_KEY_SECRET`) suojaa luodun paikallisen API-avainmuodon
-- Tarjoajan salaisuudet (API-avaimet/tunnisteet) säilyvät paikallisessa tietokannassa, ja ne tulee suojata tiedostojärjestelmätasolla
-- Pilvisynkronoinnin päätepisteet perustuvat API-avaimen todennus + konetunnuksen semantiikkaan## Environment and Runtime Matrix
+## Observability and Operational Signals
 
-Koodin aktiivisesti käyttämät ympäristömuuttujat:
+Runtime visibility sources:
 
-- Sovellus/todennus: "JWT_SECRET", "INITIAL_PASSWORD"
-- Tallennustila: "DATA_DIR".
-- Yhteensopivan solmun toiminta: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
-- Valinnainen tallennuskannan ohitus (Linux/macOS, kun "DATA_DIR" ei ole asetettu): "XDG_CONFIG_HOME"
-- Suojaushajautus: `API_KEY_SECRET`, `MACHINE_ID_SALT`
-- Kirjaaminen: "ENABLE_REQUEST_LOGS".
-- Synkronointi/pilvi-URL-osoite: NEXT_PUBLIC_BASE_URL, NEXT_PUBLIC_CLOUD_URL
-- Lähtevä välityspalvelin: "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "NO_PROXY" ja pienet versiot
-- SOCKS5-ominaisuuden liput: "ENABLE_SOCKS5_PROXY", "NEXT_PUBLIC_ENABLE_SOCKS5_PROXY"
-- Alusta/ajonaikaiset apuohjelmat (ei sovelluskohtaiset asetukset): "APPDATA", "NODE_ENV", "PORTTI", "HOSTNAME"## Known Architectural Notes
+- console logs from `src/sse/utils/logger.ts`
+- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true`
+- textual request status log in `log.txt` (optional/compat)
+- optional 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
 
-1. `usageDb` ja `localDb` jakavat saman perushakemistokäytännön (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) vanhojen tiedostojen siirrolla.
-2. "/api/v1/route.ts" siirtää samaan yhdistetyn luettelon rakennustyökaluun, jota "/api/v1/models" ("src/app/api/v1/models/catalog.ts") käyttää semanttisen ajautumisen välttämiseksi.
-3. Pyyntöloggeri kirjoittaa täydet otsikot/runko, kun se on käytössä; käsittele lokihakemistoa arkaluontoisena.
-4. Pilven toiminta riippuu oikeasta NEXT_PUBLIC_BASE_URL-osoitteesta ja pilvipäätepisteen saavutettavuudesta.
-5. Hakemisto "open-sse/" julkaistaan ​​@omniroute/open-sse**npm-työtilapaketina**. Lähdekoodi tuo sen @omniroute/open-sse/...-tiedoston kautta (ratkaisi Next.js `transpilePackages`). Tämän asiakirjan tiedostopolut käyttävät edelleen hakemistonimeä `open-sse/` johdonmukaisuuden vuoksi.
-6. Hallintapaneelin kaaviot käyttävät**Uudelleenkaavioita**(SVG-pohjainen) helppokäyttöisten, interaktiivisten analytiikkavisualisoinnit (mallien käyttöpalkkikaaviot, toimittajien erittelytaulukot onnistumisprosentteineen) varten.
-7. E2E-testit käyttävät**Playwrightia**(`tests/e2e/`), suoritetaan komennolla "npm run test:e2e". Yksikkötesteissä käytetään**Node.js-testirunneria**(`tests/unit/`), suoritetaan komennolla "npm run test:unit". Lähdekoodi kohdassa `src/` on**TypeScript**(`.ts`/`.tsx`); `open-sse/`-työtila pysyy JavaScriptina (`.js`).
-8. Asetukset-sivu on järjestetty viiteen välilehteen: Suojaus, Reititys (6 globaalia strategiaa: täytä ensin, round-robin, p2c, satunnainen, vähiten käytetty, kustannusoptimoitu), Resilience (muokattavat nopeusrajoitukset, katkaisija, käytännöt), AI (ajattelubudjetti, järjestelmäkehote, kehote välimuisti), Advanced (välityspalvelin).## Operational Verification Checklist
+Detailed request payload capture stores up to four JSON payload stages per routed call:
 
-- Koonti lähteestä: `npm run build`
-- Build Docker -kuva: `docker build -t omniroute .`
-- Aloita huolto ja varmista:
-- "HAE /api/settings".
-- "GET /api/v1/models".
-- CLI-kohteen perus-URL-osoitteen tulee olla "http://<host>:20128/v1", kun PORT=20128
+- raw request received from the client
+- translated request actually sent upstream
+- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata
+- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form
+
+## Security-Sensitive Boundaries
+
+- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
+- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning
+- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format
+- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level
+- Cloud sync endpoints rely on API key auth + machine id semantics
+
+## Environment and Runtime Matrix
+
+Environment variables actively used by code:
+
+- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Storage: `DATA_DIR`
+- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
+- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME`
+- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
+- Logging: `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`
+- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+
+## Known Architectural Notes
+
+1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.
+2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift.
+3. Request logger writes full headers/body when enabled; treat log directory as sensitive.
+4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability.
+5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency.
+6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates).
+7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`).
+8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies, **Context Relay** handoff config), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
+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 24+ detection**: `/api/settings/require-login` returns `nodeVersion` and `nodeCompatible` fields. The login page renders a warning banner when the runtime is incompatible.
+
+## Operational Verification Checklist
+
+- Build from source: `npm run build`
+- Build Docker image: `docker build -t omniroute .`
+- Start service and verify:
+- `GET /api/settings`
+- `GET /api/v1/models`
+- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`

docs/i18n/fi/docs/CODEBASE_DOCUMENTATION.md

@@ -387,7 +387,7 @@ import "./request/claude-to-openai.js"; // ← self-registers
 | "stream.ts"        | **SSE Transform Stream**— suoratoiston ydinputki. Kaksi tilaa: `TRANSLATE` (täysmuotoinen käännös) ja `PASSTHROUGH` (normalisoi + poimi käyttö). Käsittelee osien puskuroinnin, käyttöarvioinnin ja sisällön pituuden seurannan. Virtakohtaiset enkooderi/dekooderiinstanssit välttävät jaetun tilan. |
 | `streamHelpers.ts` | Matalan tason SSE-apuohjelmat: "parseSSELine" (välilyöntejä sietävä), "hasValuableContent" (suodattaa tyhjät osat OpenAI:lle/Claudelle/Geminille), fixInvalidId, "formatSSE" (muototietoinen SSE-serialisointi ja "perf_metrics").                                                                    |
 | `usageTracking.ts` | Tokenin käytön poiminta mistä tahansa muodosta (Claude/OpenAI/Gemini/Responses), arvio erillisillä työkalu/viestin char-per-token-suhteilla, puskurin lisäys (2000 merkkiä turvamarginaali), muotokohtainen kenttäsuodatus, konsolin kirjaaminen ANSI-väreillä.                                       |
-| `requestLogger.ts` | Tiedostopohjainen pyyntöjen kirjaaminen (osallistu komennolla ENABLE_REQUEST_LOGS=true). Luo istuntokansioita numeroiduilla tiedostoilla: `1_req_client.json` → `7_res_client.txt`. Kaikki I/O on async (fire-and-forget). Peittää herkät otsikot.                                                    |
+| `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` | Kaappaa tiettyjä malleja Claude CLI:stä (otsikon poimiminen, lämmittely, laskenta) ja palauttaa vääriä vastauksia soittamatta palveluntarjoajille. Tukee sekä suoratoistoa että ei-suoratoistoa. Tarkoituksella rajoitettu Claude CLI:n soveltamisalaan.                                              |
 | `networkProxy.ts`  | Ratkaisee tietyn palveluntarjoajan lähtevän välityspalvelimen URL-osoitteen etusijalla: palveluntarjoajakohtainen määritys → yleinen määritys → ympäristömuuttujat (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Tukee NO_PROXY-poikkeuksia. Välimuistin konfiguraatio 30 sekuntia.                       | #### SSE Streaming Pipeline |
 

docs/i18n/fi/docs/FEATURES.md

@@ -4,102 +4,168 @@
 
 ---
 
-Visuaalinen opas OmniRoute-hallintapaneelin jokaiseen osioon.---
+
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
 
 ## 🔌 Providers
 
-Hallinnoi AI-palveluntarjoajan yhteyksiä: OAuth-palveluntarjoajat (Claude Code, Codex, Gemini CLI), API-avaintoimittajat (Groq, DeepSeek, OpenRouter) ja ilmaiset palveluntarjoajat (Qoder, Qwen, Kiro). Kiro-tilit sisältävät luottosaldon seurannan – jäljellä olevat saldot, kokonaisrahoitus ja uusimispäivä näkyvät kohdassa Dashboard → Käyttö.![Providers Dashboard](screenshots/01-providers.png)
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+![Providers Dashboard](screenshots/01-providers.png)
 
 ---
 
 ## 🎨 Combos
 
-Luo mallin reitityskomboja kuudella strategialla: prioriteetti, painotettu, kiertävä, satunnainen, vähiten käytetty ja kustannusoptimoitu. Jokainen yhdistelmä ketjuttaa useita malleja automaattisilla varauksilla ja sisältää nopeat mallit ja valmiustarkistukset.![Combos Dashboard](screenshots/02-combos.png)
+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.
+
+![Combos Dashboard](screenshots/02-combos.png)
 
 ---
 
 ## 📊 Analytics
 
-Kattava käyttöanalytiikka tunnuksen kulutuksella, kustannusarvioilla, aktiivisuuslämpökartoilla, viikoittaisilla jakelukaavioilla ja palveluntarjoajakohtaisilla erittelyillä.![Analytics Dashboard](screenshots/03-analytics.png)
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
 
 ---
 
 ## 🏥 System Health
 
-Reaaliaikainen seuranta: käyttöaika, muisti, versio, latenssiprosenttipisteet (p50/p95/p99), välimuistitilastot ja palveluntarjoajan katkaisijan tilat.![Health Dashboard](screenshots/04-health.png)
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+![Health Dashboard](screenshots/04-health.png)
 
 ---
 
 ## 🔧 Translator Playground
 
-Neljä tilaa API-käännösten virheenkorjaukseen:**Playground**(muodonmuunnin),**Chat Tester**(livepyynnöt),**Test Bench**(erätestit) ja**Live Monitor**(reaaliaikainen suoratoisto).![Translator Playground](screenshots/05-translator.png)
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+![Translator Playground](screenshots/05-translator.png)
 
 ---
 
 ## 🎮 Model Playground _(v2.0.9+)_
 
-Testaa mitä tahansa mallia suoraan kojelaudalta. Valitse palveluntarjoaja, malli ja päätepiste, kirjoita kehotteita Monaco Editorilla, suoratoista vastaukset reaaliajassa, keskeytä kesken stream ja tarkastele ajoitusmittauksia.---
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
 
 ## 🎨 Themes _(v2.0.5+)_
 
-Muokattavat väriteemat koko kojelautaan. Valitse 7 esiasetetusta väristä (koralli, sininen, punainen, vihreä, violetti, oranssi, syaani) tai luo mukautettu teema valitsemalla mikä tahansa kuusioväri. Tukee vaaleaa, tummaa ja järjestelmätilaa.---
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
 
 ## ⚙️ Settings
 
-Kattava asetuspaneeli välilehdillä:
+Comprehensive settings panel with tabs:
 
--**Yleistä**- Järjestelmän tallennus, varmuuskopioiden hallinta (vienti/tuonti tietokanta) -**Ulkoasu**- Teeman valitsin (tumma/vaalea/järjestelmä), väriteeman esiasetukset ja mukautetut värit, terveyslokin näkyvyys, sivupalkin kohteiden näkyvyyden säätimet -**Turvallisuus**— API-päätepisteiden suojaus, mukautetun palveluntarjoajan esto, IP-suodatus, istuntotiedot -**Reititys**— Mallin aliakset, taustatehtävän huononeminen -**Kestävyys**— Hintarajoituksen pysyvyys, katkaisijan viritys, estettyjen tilien automaattinen poistaminen käytöstä, palveluntarjoajan vanhenemisen valvonta -**Lisäasetukset**— Kokoonpanon ohitukset, määrityksen kirjausketju, varatilan heikkenemistila![Settings Dashboard](screenshots/06-settings.png)
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring, **Context Relay** handoff threshold and summary model configuration
+- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
+
+![Settings Dashboard](screenshots/06-settings.png)
 
 ---
 
 ## 🔧 CLI Tools
 
-Yhden napsautuksen konfigurointi AI-koodaustyökaluille: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor ja Factory Droid. Sisältää automaattisen konfiguroinnin käyttöönotto/nollaus, yhteysprofiilit ja mallikartoituksen.![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
 
 ---
 
 ## 🤖 CLI Agents _(v2.0.11+)_
 
-Kojelauta CLI-agenttien löytämiseen ja hallintaan. Näyttää 14 sisäänrakennetun agentin (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) ruudukon, jossa on:
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
 
--**Asennustila**— Asennettu / Ei löydy versiontunnistuksen kanssa -**Protokollamerkit**— stdio, HTTP jne. -**Muokatut agentit**— Rekisteröi mikä tahansa CLI-työkalu lomakkeella (nimi, binaari, versiokomento, spawn args) -**CLI-sormenjälkien vastaavuus**– Palveluntarjoajakohtainen kytkin vastaamaan alkuperäisten CLI-pyyntöjen allekirjoituksia, mikä vähentää eston riskiä ja säilyttää välityspalvelimen IP-osoitteen---
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🔗 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
+
+---
 
 ## 🖼️ Media _(v2.0.3+)_
 
-Luo kuvia, videoita ja musiikkia kojelaudalta. Tukee OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open ja MusicGen.---
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
 
 ## 📝 Request Logs
 
-Reaaliaikainen pyyntöjen kirjaaminen suodatuksella palveluntarjoajan, mallin, tilin ja API-avaimen mukaan. Näyttää tilakoodit, tunnuksen käytön, viiveen ja vastaustiedot.![Usage Logs](screenshots/08-usage.png)
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+![Usage Logs](screenshots/08-usage.png)
 
 ---
 
 ## 🌐 API Endpoint
 
-Yhdistetty API-päätepisteesi ominaisuuksien erittelyllä: Chat Completions, Responses API, upotukset, kuvan luominen, uudelleensijoitus, äänen transkriptio, tekstistä puheeksi, moderaatiot ja rekisteröidyt API-avaimet. Cloudflare Quick Tunnel -integraatio ja pilvivälityspalvelintuki etäkäyttöä varten.![Endpoint Dashboard](screenshots/09-endpoint.png)
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)
 
 ---
 
 ## 🔑 API Key Management
 
-Luo, laajenna ja peruuta API-avaimia. Jokainen avain voidaan rajoittaa tiettyihin malleihin/palveluntarjoajiin, joilla on täydet käyttöoikeudet tai vain lukuoikeudet. Visuaalinen avainten hallinta käytön seurannalla.---
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
 
 ## 📋 Audit Log
 
-Hallinnollinen toimintojen seuranta suodatuksella toimintotyypin, toimijan, kohteen, IP-osoitteen ja aikaleiman mukaan. Täydellinen tietoturvatapahtumahistoria.---
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
 
 ## 🖥️ Desktop Application
 
-Native Electron -työpöytäsovellus Windowsille, macOS:lle ja Linuxille. Suorita OmniRoute itsenäisenä sovelluksena, jossa on järjestelmälokeron integrointi, offline-tuki, automaattinen päivitys ja asennus yhdellä napsautuksella.
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
 
-Tärkeimmät ominaisuudet:
+Key features:
 
-- Palvelimen valmiuskysely (ei tyhjää näyttöä kylmäkäynnistyksen yhteydessä)
-- Järjestelmälokero portinhallinnan kanssa
-- Sisällön suojauskäytäntö
-- Yksiosainen lukko
-- Automaattinen päivitys uudelleenkäynnistyksen yhteydessä
-- Alustan ehdollinen käyttöliittymä (macOS-liikennevalot, Windowsin/Linuxin oletusotsikkopalkki)
-- Hardened Electron build -pakkaus – itsenäisen nipun symlinkoidut "solmumoduulit" tunnistetaan ja hylätään ennen pakkausta, mikä estää ajonaikaisen riippuvuuden rakennuskoneesta (v2.5.5+)
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
 
-📖 Katso täydelliset asiakirjat osoitteesta [`electron/README.md`](../electron/README.md).
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/fi/docs/TROUBLESHOOTING.md

@@ -4,68 +4,141 @@
 
 ---
 
-OmniRouten yleisiä ongelmia ja ratkaisuja.---
+Common problems and solutions for OmniRoute.
+
+---
 
 ## Quick Fixes
 
-| Ongelma                            | Ratkaisu                                                                        |
-| ---------------------------------- | ------------------------------------------------------------------------------- | --- |
-| Ensimmäinen kirjautuminen ei toimi | Aseta 'INITIAL_PASSWORD' .env:ssä (ei kovakoodattua oletusarvoa)                |
-| Kojelauta avautuu väärään porttiin | Aseta `PORT=20128` ja `NEXT_PUBLIC_BASE_URL=http://localhost:20128`             |
-| Ei pyyntölokeja kohdassa "lokit/"  | Aseta ENABLE_REQUEST_LOGS=true                                                  |
-| EACCES: lupa evätty                | Aseta "DATA_DIR=/polku/kirjoitettavaan/hakemistoon" ohittaaksesi "~/.omniroute" |
-| Reititysstrategia ei tallennu      | Päivitys versioon 1.4.11+ (Zod-skeeman korjaus asetusten pysyvyyttä varten)     | --- |
+| 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      | You may be on Node.js 24+ — see [Node.js Compatibility](#nodejs-compatibility) 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 Node.js 24+. The `better-sqlite3` native binary is not compatible with Node.js 24, which causes a fatal crash when the server tries to initialize the database.
+
+**Symptoms:**
+
+- Login page shows a blank screen or a server error
+- Console shows `Error: Module did not self-register` or similar native binding errors
+- Starting with v3.5.5, the login page shows an **orange warning banner** with your Node version if incompatibility is detected
+
+**Fix:**
+
+1. Install Node.js 22 LTS (recommended):
+   ```bash
+   nvm install 22
+   nvm use 22
+   ```
+2. Verify your version: `node --version` should show `v22.x.x`
+3. Reinstall OmniRoute: `npm install -g omniroute`
+4. Restart: `omniroute`
+
+> **Supported versions:** Node.js 18, 20, or 22 LTS. Node.js 24+ is **not supported**.
+
+---
+
+## 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+.
+
+---
 
 ## Provider Issues
 
 ### "Language model did not provide messages"
 
-**Syy:**Palveluntarjoajan kiintiö käytetty.
+**Cause:** Provider quota exhausted.
 
-**Korjaa:**
+**Fix:**
 
-1. Tarkista kojelaudan kiintiöiden seuranta
-2. Käytä yhdistelmää varatasoilla
-3. Vaihda halvempaan/ilmaiseen tasoon### Rate Limiting
+1. Check dashboard quota tracker
+2. Use a combo with fallback tiers
+3. Switch to cheaper/free tier
 
-**Syy:**Tilauskiintiö käytetty.
+### Rate Limiting
 
-**Korjaa:**
+**Cause:** Subscription quota exhausted.
 
-- Lisää vara: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-- Käytä GLM/MiniMaxia halvana varmuuskopiona### OAuth Token Expired
+**Fix:**
 
-OmniRoute päivittää tunnukset automaattisesti. Jos ongelmat jatkuvat:
+- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Use GLM/MiniMax as cheap backup
 
-1. Kojelauta → Palveluntarjoaja → Yhdistä uudelleen
-2. Poista ja lisää palveluntarjoajan yhteys uudelleen---
+### OAuth Token Expired
+
+OmniRoute auto-refreshes tokens. If issues persist:
+
+1. Dashboard → Provider → Reconnect
+2. Delete and re-add the provider connection
+
+---
 
 ## Cloud Issues
 
 ### Cloud Sync Errors
 
-1. Varmista, että BASE_URL osoittaa käynnissä olevaan esiintymääsi (esim. http://localhost:20128)
-2. Varmista, että CLOUD_URL-osoite osoittaa pilvipäätepisteeseesi (esim. https://omniroute.dev).
-3. Pidä NEXT*PUBLIC*\*-arvot kohdakkain palvelinpuolen arvojen kanssa### Cloud `stream=false` Returns 500
+1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
+2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
+3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
 
-**Oire:**"Odottamaton tunnus "d"..." pilvipäätepisteessä ei-suoratoistopuheluille.
+### Cloud `stream=false` Returns 500
 
-**Syy:**Upstream palauttaa SSE-hyötykuorman, kun asiakas odottaa JSONia.
+**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
 
-**Ratkaisu:**Käytä "stream=true" pilvisuorapuheluissa. Paikallinen suoritusaika sisältää SSE→JSON-varavaihtoehdon.### Cloud Says Connected but "Invalid API key"
+**Cause:** Upstream returns SSE payload while client expects JSON.
 
-1. Luo uusi avain paikallisesta hallintapaneelista (`/api/keys`)
-2. Suorita pilvisynkronointi: Ota pilvi käyttöön → Synkronoi nyt
-3. Vanhat/synkronoimattomat avaimet voivat edelleen palauttaa 401:n pilvessä---
+**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
+
+### Cloud Says Connected but "Invalid API key"
+
+1. Create a fresh key from local dashboard (`/api/keys`)
+2. Run cloud sync: Enable Cloud → Sync Now
+3. Old/non-synced keys can still return `401` on cloud
+
+---
 
 ## Docker Issues
 
 ### CLI Tool Shows Not Installed
 
-1. Tarkista ajonaikaiset kentät: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
-2. Kannettava tila: käytä kuvakohdetta "runner-cli" (niputetut CLI:t)
-3. Isäntäliitostila: aseta CLI_EXTRA_PATHS ja liitä isäntäalustahakemisto vain luku -muotoiseksi
-4. Jos "installed=true" ja "runnable=false": binaari löytyi, mutta kuntotarkastus epäonnistui### Quick Runtime Validation
+1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. For portable mode: use image target `runner-cli` (bundled CLIs)
+3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
+4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
+
+### Quick Runtime Validation
 
 ```bash
 curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
@@ -79,16 +152,22 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
 
 ### High Costs
 
-1. Tarkista käyttötilastot kohdassa Dashboard → Usage
-2. Vaihda ensisijaiseksi malliksi GLM/MiniMax
-3. Käytä ilmaista tasoa (Gemini CLI, Qoder) ei-kriittisiin tehtäviin
-4. Aseta kustannusbudjetit API-avainta kohti: Dashboard → API Keys → Budget---
+1. Check usage stats in Dashboard → Usage
+2. Switch primary model to GLM/MiniMax
+3. Use free tier (Gemini CLI, Qoder) for non-critical tasks
+4. Set cost budgets per API key: Dashboard → API Keys → Budget
+
+---
 
 ## Debugging
 
-### Enable Request Logs
+### Enable Log Files
 
-Aseta ENABLE_REQUEST_LOGS=true .env-tiedostoosi. Lokit näkyvät lokit/hakemistossa.### Check Provider Health
+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
 
 ```bash
 # Health dashboard
@@ -100,101 +179,136 @@ curl http://localhost:20128/api/monitoring/health
 
 ### Runtime Storage
 
-- Päätila: `${DATA_DIR}/storage.sqlite` (palveluntarjoajat, yhdistelmät, aliakset, avaimet, asetukset)
-- Käyttö: SQLite-taulukot tiedostossa "storage.sqlite" ("usage_history", "call_logs", "proxy_logs") + valinnainen "${DATA_DIR}/log.txt" ja "${DATA_DIR}/call_logs/"
-- Pyydä lokeja: `<repo>/logs/...` (kun `ENABLE_REQUEST_LOGS=true`)---
+- 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}/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
+
+---
 
 ## Circuit Breaker Issues
 
 ### Provider stuck in OPEN state
 
-Kun palveluntarjoajan katkaisija on AUKI, pyynnöt estetään, kunnes jäähdytys päättyy.
+When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
 
-**Korjaa:**
+**Fix:**
 
-1. Siirry kohtaan**Käyttöpaneeli → Asetukset → Resilience**
-2. Tarkista asianomaisen palveluntarjoajan katkaisijakortti
-3. Napsauta**Nollaa kaikki**tyhjentääksesi kaikki katkaisijat tai odota jäähdytysajan päättymistä
-4. Varmista, että palveluntarjoaja on todella saatavilla, ennen kuin nollaat### Provider keeps tripping the circuit breaker
+1. Go to **Dashboard → Settings → Resilience**
+2. Check the circuit breaker card for the affected provider
+3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
+4. Verify the provider is actually available before resetting
 
-Jos palveluntarjoaja siirtyy toistuvasti OPEN-tilaan:
+### Provider keeps tripping the circuit breaker
 
-1. Tarkista vikakuvio kohdasta**Dashboard → Health → Provider Health**
-2. Siirry kohtaan**Settings → Resilience → Provider Profiles**ja nosta vikakynnystä.
-3. Tarkista, onko palveluntarjoaja muuttanut API-rajoja tai vaatiiko todennuksen uudelleen
-4. Tarkista viiveen telemetria — korkea latenssi voi aiheuttaa aikakatkaisuun perustuvia virheitä---
+If a provider repeatedly enters OPEN state:
+
+1. Check **Dashboard → Health → Provider Health** for the failure pattern
+2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
+3. Check if the provider has changed API limits or requires re-authentication
+4. Review latency telemetry — high latency may cause timeout-based failures
+
+---
 
 ## Audio Transcription Issues
 
 ### "Unsupported model" error
 
-- Varmista, että käytät oikeaa etuliitettä: "deepgram/nova-3" tai "assemblyai/best"
-- Varmista, että palveluntarjoaja on yhdistetty kohdassa**Dashboard → Providers**### Transcription returns empty or fails
+- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
+- Verify the provider is connected in **Dashboard → Providers**
 
-- Tarkista tuetut äänimuodot: "mp3", "wav", "m4a", "flac", "ogg", "webm"
-- Varmista, että tiedostokoko on palveluntarjoajan rajoissa (yleensä < 25 Mt)
-- Tarkista palveluntarjoajan API-avaimen voimassaolo toimittajakortista---
+### Transcription returns empty or fails
+
+- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Verify file size is within provider limits (typically < 25MB)
+- Check provider API key validity in the provider card
+
+---
 
 ## Translator Debugging
 
-Käytä**Käyttöpaneeli → Kääntäjä**muotojen käännösongelmien korjaamiseen:
+Use **Dashboard → Translator** to debug format translation issues:
 
-| Tila                      | Milloin käyttää                                                                                         |
-| ------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------ |
-| **Leikkikenttä**          | Vertaa syöttö-/tulostusmuotoja vierekkäin – liitä epäonnistunut pyyntö nähdäksesi, miten se käännetään  |
-| **Pikaviestien testaaja** | Lähetä reaaliaikaisia ​​viestejä ja tarkasta koko pyynnön/vastauksen hyötykuorma, mukaan lukien otsikot |
-| **Testipenkki**           | Suorita erätestejä muotoyhdistelmille selvittääksesi, mitkä käännökset ovat rikki                       |
-| **Live Monitor**          | Tarkkaile reaaliaikaista pyyntövirtaa havaitaksesi ajoittaiset käännösongelmat                          | ### Common format issues |
+| Mode             | When to Use                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| **Playground**   | Compare input/output formats side by side — paste a failing request to see how it translates |
+| **Chat Tester**  | Send live messages and inspect the full request/response payload including headers           |
+| **Test Bench**   | Run batch tests across format combinations to find which translations are broken             |
+| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues                        |
 
--**Ajattelevat tunnisteet eivät näy**— Tarkista, tukeeko kohdetoimittaja ajattelua ja ajattelun budjettiasetusta -**Työkalukutsujen pudottaminen**— Jotkin muotokäännökset voivat poistaa ei-tuetut kentät. vahvista leikkikenttätilassa -**Järjestelmäkehote puuttuu**— Claude ja Gemini kahvajärjestelmä kehottaa eri tavalla; tarkista käännöstulos -**SDK palauttaa raakamerkkijonon objektin sijaan**— Korjattu versiossa 1.1.0: vastauspuhdistin poistaa nyt standardista poikkeavat kentät ("x_groq", "usage_breakdown" jne.), jotka aiheuttavat OpenAI SDK Pydantic -tarkistusvirheitä -**GLM/ERNIE hylkää "järjestelmän" roolin**- Korjattu versiossa 1.1.0: roolin normalisoija yhdistää automaattisesti järjestelmäviestit käyttäjäviesteiksi yhteensopimattomissa malleissa -**"kehittäjäroolia" ei tunnistettu**- Korjattu versiossa 1.1.0: muunnetaan automaattisesti "järjestelmäksi" muille kuin OpenAI-palveluntarjoajille -**`json_schema` ei toimi Geminin kanssa**— Korjattu versiossa 1.1.0: `response_format` muunnetaan nyt Geminin `responseMimeType` + `responseSchema` -muotoon.---
+### Common format issues
+
+- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
+- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
+- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
+- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures
+- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
+- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers
+- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema`
+
+---
 
 ## Resilience Settings
 
 ### Auto rate-limit not triggering
 
-- Automaattinen nopeusrajoitus koskee vain API-avainten toimittajia (ei OAuth-tilausta)
-- Varmista, että**Asetukset → Resilienssi → Palveluntarjoajan profiilit**on automaattinen rajoitus käytössä
-- Tarkista, palauttaako palveluntarjoaja "429"-tilakoodit tai "Retry-After"-otsikot### Tuning exponential backoff
+- Auto rate-limit only applies to API key providers (not OAuth/subscription)
+- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
+- Check if the provider returns `429` status codes or `Retry-After` headers
 
-Palveluntarjoajan profiilit tukevat näitä asetuksia:
+### Tuning exponential backoff
 
--**Perusviive**— Ensimmäinen odotusaika ensimmäisen epäonnistumisen jälkeen (oletus: 1 s) -**Maksimiviive**- Odotusajan enimmäisraja (oletus: 30 s) -**Kerroin**— Kuinka paljon viivettä lisätään peräkkäistä vikaa kohti (oletus: 2x)### Anti-thundering herd
+Provider profiles support these settings:
 
-Kun monet samanaikaiset pyynnöt osuvat nopeusrajoitettuun palveluntarjoajaan, OmniRoute käyttää mutex + automaattista nopeuden rajoitusta sarjoittamaan pyynnöt ja estämään peräkkäiset epäonnistumiset. Tämä on automaattinen API-avainten tarjoajille.---
+- **Base delay** — Initial wait time after first failure (default: 1s)
+- **Max delay** — Maximum wait time cap (default: 30s)
+- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
+
+### Anti-thundering herd
+
+When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
+
+---
 
 ## Optional RAG / LLM failure taxonomy (16 problems)
 
-Jotkut OmniRouten käyttäjät sijoittavat yhdyskäytävän RAG- tai agenttipinojen eteen. Näissä asetuksissa on tavallista nähdä outo kuvio: OmniRoute näyttää terveeltä (palveluntarjoajat valmiina, reititysprofiilit kunnossa, ei nopeusrajoitushälytyksiä), mutta lopullinen vastaus on silti väärä.
+Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong.
 
-Käytännössä nämä tapaukset tulevat yleensä loppupään RAG-putkistosta, eivät itse yhdyskäytävästä.
+In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself.
 
-Jos haluat jaetun sanaston kuvaamaan näitä vikoja, voit käyttää WFGY ProblemMapia, ulkoista MIT-lisenssitekstiresurssia, joka määrittelee kuusitoista toistuvaa RAG/LLM-vikamallia. Korkealla tasolla se kattaa:
+If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers:
 
-- haun ajautuminen ja rikotut kontekstin rajat
-- tyhjät tai vanhentuneet indeksit ja vektorivarastot
-- upottaminen vs. semanttinen yhteensopivuus
-- Nopeat kokoonpano- ja kontekstiikkuna-ongelmat
-- logiikka romahtaa ja liian itsevarmat vastaukset
-- pitkän ketjun ja agenttien koordinaatiohäiriöt
-- monen agentin muisti ja roolien siirtyminen
-- käyttöönotto- ja käynnistystilausongelmat
+- retrieval drift and broken context boundaries
+- empty or stale indexes and vector stores
+- embedding versus semantic mismatch
+- prompt assembly and context window issues
+- logic collapse and overconfident answers
+- long chain and agent coordination failures
+- multi agent memory and role drift
+- deployment and bootstrap ordering problems
 
-Idea on yksinkertainen:
+The idea is simple:
 
-1. Kun tutkit huonoa vastausta, tallenna:
-   - käyttäjän tehtävä ja pyyntö
-   - reitti- tai tarjoajayhdistelmä OmniRoutessa
-   - mikä tahansa loppupäässä käytetty RAG-konteksti (haettu asiakirjat, työkalukutsut jne.)
-2. Kartoita tapahtuma yhteen tai kahteen WFGY-ongelmakarttanumeroon (`No.1` … `No.16`).
-3. Tallenna numero omaan kojelautaan, runbookiin tai tapahtumaseurantaan OmniRoute-lokien viereen.
-4. Käytä vastaavaa WFGY-sivua päättääksesi, onko sinun muutettava RAG-pinoa, noutajaa tai reititysstrategiaa.
+1. When you investigate a bad response, capture:
+   - user task and request
+   - route or provider combo in OmniRoute
+   - any RAG context used downstream (retrieved documents, tool calls, etc)
+2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`).
+3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs.
+4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy.
 
-Koko teksti ja konkreettiset reseptit löytyvät täältä (MIT-lisenssi, vain teksti):
+Full text and concrete recipes live here (MIT license, text only):
 
 [WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
 
-Voit jättää tämän osion huomioimatta, jos et käytä RAG- tai agenttiputkia OmniRouten takana.---
+You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute.
+
+---
 
 ## Still Stuck?
 
--**GitHub-ongelmat**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -**Arkkitehtuuri**: Katso sisäiset tiedot osoitteesta [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) -**API-viite**: Katso [`docs/API_REFERENCE.md`](API_REFERENCE.md) kaikista päätepisteistä -**Health Dashboard**: Tarkista järjestelmän reaaliaikainen tila kohdasta**Dashboard → Health** -**Kääntäjä**: Käytä**Käyttöpaneeli → Kääntäjä**muotoongelmien korjaamiseen
+- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
+- **Translator**: Use **Dashboard → Translator** to debug format issues

docs/i18n/fi/docs/VM_DEPLOYMENT_GUIDE.md

@@ -100,7 +100,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/fi/llm.txt

@@ -0,0 +1,476 @@
+# OmniRoute (Suomi)
+
+🌐 **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.
+
+## Yleiskatsaus
+
+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)
+
+### Turvallisuus
+- **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/fr/docs/ARCHITECTURE.md

@@ -4,80 +4,91 @@
 
 ---
 
-_Dernière mise à jour : 2026-03-28_## Executive Summary
+_Last updated: 2026-03-28_
 
-OmniRoute est une passerelle de routage d'IA locale et un tableau de bord construit sur Next.js.
-Il fournit un seul point de terminaison compatible OpenAI (`/v1/*`) et achemine le trafic vers plusieurs fournisseurs en amont avec traduction, secours, actualisation des jetons et suivi de l'utilisation.
+## Executive Summary
 
-Capacités de base :
+OmniRoute is a local AI routing gateway and dashboard built on Next.js.
+It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
 
-- Surface API compatible OpenAI pour CLI/outils (28 fournisseurs)
-- Traduction des requêtes/réponses dans tous les formats de fournisseurs
-- Modèle de repli combo (séquence multi-modèles)
-- Repli au niveau du compte (multi-comptes par fournisseur)
-- Gestion des connexions du fournisseur de clé OAuth + API
-- Génération d'embarquement via `/v1/embeddings` (6 fournisseurs, 9 modèles)
-- Génération d'images via `/v1/images/generations` (4 fournisseurs, 9 modèles)
-- Pensez à l'analyse des balises (`<think>...</think>`) pour les modèles de raisonnement
-- Désinfection des réponses pour une compatibilité stricte avec le SDK OpenAI
-- Normalisation des rôles (développeur → système, système → utilisateur) pour une compatibilité entre fournisseurs
-- Conversion de sortie structurée (json_schema → Gemini ResponseSchema)
-- Persistance locale pour les fournisseurs, les clés, les alias, les combos, les paramètres, les prix
-- Suivi de l'utilisation/des coûts et journalisation des demandes
-- Synchronisation cloud en option pour la synchronisation multi-appareils/états
-- Liste d'autorisation/liste de blocage IP pour le contrôle d'accès aux API
-- Penser la gestion budgétaire (passthrough/auto/custom/adaptatif)
-  -Injection rapide du système global
-- Suivi de session et prise d'empreintes digitales
-- Limitation de débit améliorée par compte avec des profils spécifiques au fournisseur
-- Modèle de disjoncteur pour la résilience du fournisseur
-- Protection de troupeau anti-tonnerre avec verrouillage mutex
-- Cache de déduplication de requêtes basé sur les signatures
-- Couche domaine : disponibilité du modèle, règles de coûts, politique de repli, politique de verrouillage
-- Persistance de l'état du domaine (cache en écriture SQLite pour les solutions de repli, les budgets, les verrouillages, les disjoncteurs)
-- Moteur de politique pour l'évaluation centralisée des demandes (verrouillage → budget → repli)
-- Demande de télémétrie avec agrégation de latence p50/p95/p99
-- ID de corrélation (X-Request-Id) pour le traçage de bout en bout
-- Journalisation d'audit de conformité avec désinscription par clé API
-- Cadre d'évaluation pour l'assurance qualité LLM
-- Tableau de bord de l'interface utilisateur de résilience avec l'état du disjoncteur en temps réel
-- Fournisseurs OAuth modulaires (12 modules individuels sous `src/lib/oauth/providers/`)
+Core capabilities:
 
-Modèle d'exécution principal :
+- OpenAI-compatible API surface for CLI/tools (28 providers)
+- Request/response translation across provider formats
+- Model combo fallback (multi-model sequence)
+- Account-level fallback (multi-account per provider)
+- OAuth + API-key provider connection management
+- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
+- Image generation via `/v1/images/generations` (4 providers, 9 models)
+- Think tag parsing (`<think>...</think>`) for reasoning models
+- Response sanitization for strict OpenAI SDK compatibility
+- Role normalization (developer→system, system→user) for cross-provider compatibility
+- Structured output conversion (json_schema → Gemini responseSchema)
+- Local persistence for providers, keys, aliases, combos, settings, pricing
+- Usage/cost tracking and request logging
+- Optional cloud sync for multi-device/state sync
+- IP allowlist/blocklist for API access control
+- Thinking budget management (passthrough/auto/custom/adaptive)
+- Global system prompt injection
+- Session tracking and fingerprinting
+- Per-account enhanced rate limiting with provider-specific profiles
+- Circuit breaker pattern for provider resilience
+- Anti-thundering herd protection with mutex locking
+- Signature-based request deduplication cache
+- Domain layer: model availability, cost rules, fallback policy, lockout policy
+- 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
+- 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/`)
 
-- Les routes de l'application Next.js sous `src/app/api/*` implémentent à la fois les API de tableau de bord et les API de compatibilité
-- Un noyau SSE/routage partagé dans `src/sse/*` + `open-sse/*` gère l'exécution, la traduction, le streaming, le repli et l'utilisation du fournisseur## Scope and Boundaries
+Primary runtime model:
+
+- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
+- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
+
+## Scope and Boundaries
 
 ### In Scope
 
-- Runtime de la passerelle locale
-- API de gestion des tableaux de bord
-- Authentification du fournisseur et actualisation du jeton
-- Demander une traduction et un streaming SSE
-- État local + persistance d'utilisation
-- Orchestration de synchronisation cloud en option### Out of Scope
+- Local gateway runtime
+- Dashboard management APIs
+- Provider authentication and token refresh
+- Request translation and SSE streaming
+- Local state + usage persistence
+- Optional cloud sync orchestration
 
-- Implémentation du service Cloud derrière `NEXT_PUBLIC_CLOUD_URL`
-- SLA/plan de contrôle du fournisseur en dehors du processus local
-- Les binaires CLI externes eux-mêmes (Claude CLI, Codex CLI, etc.)## Dashboard Surface (Current)
+### Out of Scope
 
-Pages principales sous `src/app/(dashboard)/dashboard/` :
+- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
+- Provider SLA/control plane outside local process
+- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
 
-- `/dashboard` — démarrage rapide + aperçu du fournisseur
-- `/dashboard/endpoint` — proxy de point de terminaison + MCP + A2A + onglets de point de terminaison API
-- `/dashboard/providers` — connexions et informations d'identification du fournisseur
-- `/dashboard/combos` — stratégies de combo, modèles, règles de routage de modèles
-- `/dashboard/costs` — agrégation des coûts et visibilité sur les prix
-- `/dashboard/analytics` — analyses et évaluations d'utilisation
-- `/dashboard/limits` — contrôles de quotas/taux
-- `/dashboard/cli-tools` — Intégration CLI, détection d'exécution, génération de configuration
-- `/dashboard/agents` — agents ACP détectés + enregistrement d'agent personnalisé
-- `/dashboard/media` — terrain de jeu image/vidéo/musique
-- `/dashboard/search-tools` — tests et historique du moteur de recherche
-- `/dashboard/health` — temps de disponibilité, disjoncteurs, limites de débit
-- `/dashboard/logs` — journaux de requête/proxy/audit/console
-- `/dashboard/settings` — onglets des paramètres système (général, routage, valeurs par défaut des combos, etc.)
-- `/dashboard/api-manager` — Cycle de vie des clés API et autorisations du modèle## High-Level System Context
+## Dashboard Surface (Current)
+
+Main pages under `src/app/(dashboard)/dashboard/`:
+
+- `/dashboard` — quick start + provider overview
+- `/dashboard/endpoint` — endpoint proxy + MCP + A2A + API endpoint tabs
+- `/dashboard/providers` — provider connections and credentials
+- `/dashboard/combos` — combo strategies, templates, model routing rules
+- `/dashboard/costs` — cost aggregation and pricing visibility
+- `/dashboard/analytics` — usage analytics and evaluations
+- `/dashboard/limits` — quota/rate controls
+- `/dashboard/cli-tools` — CLI onboarding, runtime detection, config generation
+- `/dashboard/agents` — detected ACP agents + custom agent registration
+- `/dashboard/media` — image/video/music playground
+- `/dashboard/search-tools` — search provider testing and history
+- `/dashboard/health` — uptime, circuit breakers, rate limits
+- `/dashboard/logs` — request/proxy/audit/console logs
+- `/dashboard/settings` — system settings tabs (general, routing, combo defaults, etc.)
+- `/dashboard/api-manager` — API key lifecycle and model permissions
+
+## High-Level System Context
 
 ```mermaid
 flowchart LR
@@ -129,139 +140,151 @@ flowchart LR
 
 ## 1) API and Routing Layer (Next.js App Routes)
 
-Principaux répertoires :
+Main directories:
 
-- `src/app/api/v1/*` et `src/app/api/v1beta/*` pour les API de compatibilité
-- `src/app/api/*` pour les API de gestion/configuration
-- Les réécritures suivantes dans `next.config.mjs` mappent `/v1/*` en `/api/v1/*`
+- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
+- `src/app/api/*` for management/configuration APIs
+- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
 
-Itinéraires de compatibilité importants :
+Important compatibility routes:
 
 - `src/app/api/v1/chat/completions/route.ts`
 - `src/app/api/v1/messages/route.ts`
 - `src/app/api/v1/responses/route.ts`
-- `src/app/api/v1/models/route.ts` — inclut des modèles personnalisés avec `custom: true`
-- `src/app/api/v1/embeddings/route.ts` — génération d'intégration (6 fournisseurs)
-- `src/app/api/v1/images/generations/route.ts` — génération d'images (4+ fournisseurs dont Antigravity/Nebius)
+- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`
+- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)
+- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)
 - `src/app/api/v1/messages/count_tokens/route.ts`
-- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — chat dédié par fournisseur
-- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — intégrations dédiées par fournisseur
-- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — images dédiées par fournisseur
+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat
+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings
+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images
 - `src/app/api/v1beta/models/route.ts`
-- `src/app/api/v1beta/models/[...chemin]/route.ts`
+- `src/app/api/v1beta/models/[...path]/route.ts`
 
-Domaines de gestion :
+Management domains:
 
-- Authentification/paramètres : `src/app/api/auth/*`, `src/app/api/settings/*`
-- Fournisseurs/connexions : `src/app/api/providers*`
-- Nœuds fournisseurs : `src/app/api/provider-nodes*`
-- Modèles personnalisés : `src/app/api/provider-models` (GET/POST/DELETE)
-- Catalogue de modèles : `src/app/api/models/route.ts` (GET)
-- Configuration du proxy : `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
-  -OAuth : `src/app/api/oauth/*`
-- Clés/alias/combos/pricing : `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
-- Utilisation : `src/app/api/usage/*`
-- Synchronisation/cloud : `src/app/api/sync/*`, `src/app/api/cloud/*`
-- Aides aux outils CLI : `src/app/api/cli-tools/*`
-- Filtre IP : `src/app/api/settings/ip-filter` (GET/PUT)
-- Budget de réflexion : `src/app/api/settings/thinking-budget` (GET/PUT)
-- Invite système : `src/app/api/settings/system-prompt` (GET/PUT)
-- Sessions : `src/app/api/sessions` (GET)
-- Limites de débit : `src/app/api/rate-limits` (GET)
-- Résilience : `src/app/api/resilience` (GET/PATCH) — profils de fournisseur, disjoncteur, état limite de débit
-- Réinitialisation de la résilience : `src/app/api/resilience/reset` (POST) — réinitialisation des disjoncteurs + temps de recharge
-- Statistiques du cache : `src/app/api/cache/stats` (GET/DELETE)
-- Disponibilité du modèle : `src/app/api/models/availability` (GET/POST)
-- Télémétrie : `src/app/api/telemetry/summary` (GET)
-- Budget : `src/app/api/usage/budget` (GET/POST)
-- Chaînes de secours : `src/app/api/fallback/chains` (GET/POST/DELETE)
-- Audit de conformité : `src/app/api/compliance/audit-log` (GET)
-- Évaluations : `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
-- Politiques : `src/app/api/policies` (GET/POST)## 2) SSE + Translation Core
+- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
+- Providers/connections: `src/app/api/providers*`
+- Provider nodes: `src/app/api/provider-nodes*`
+- Custom models: `src/app/api/provider-models` (GET/POST/DELETE)
+- Model catalog: `src/app/api/models/route.ts` (GET)
+- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
+- OAuth: `src/app/api/oauth/*`
+- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
+- Usage: `src/app/api/usage/*`
+- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
+- CLI tooling helpers: `src/app/api/cli-tools/*`
+- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)
+- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)
+- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)
+- Sessions: `src/app/api/sessions` (GET)
+- Rate limits: `src/app/api/rate-limits` (GET)
+- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state
+- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns
+- Cache stats: `src/app/api/cache/stats` (GET/DELETE)
+- Model availability: `src/app/api/models/availability` (GET/POST)
+- Telemetry: `src/app/api/telemetry/summary` (GET)
+- Budget: `src/app/api/usage/budget` (GET/POST)
+- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)
+- Compliance audit: `src/app/api/compliance/audit-log` (GET)
+- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
+- Policies: `src/app/api/policies` (GET/POST)
 
-Principaux modules de flux :
+## 2) SSE + Translation Core
 
-- Entrée : `src/sse/handlers/chat.ts`
-- Orchestration de base : `open-sse/handlers/chatCore.ts`
-- Adaptateurs d'exécution du fournisseur : `open-sse/executors/*`
-- Détection de format/configuration du fournisseur : `open-sse/services/provider.ts`
-- Analyse/résolution du modèle : `src/sse/services/model.ts`, `open-sse/services/model.ts`
-- Logique de repli du compte : `open-sse/services/accountFallback.ts`
-- Registre de traduction : `open-sse/translator/index.ts`
-- Transformations de flux : `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
-- Extraction/normalisation d'utilisation : `open-sse/utils/usageTracking.ts`
-- Analyseur de balises Think : `open-sse/utils/thinkTagParser.ts`
-- Gestionnaire d'intégration : `open-sse/handlers/embeddings.ts`
-- Registre du fournisseur d'intégration : `open-sse/config/embeddingRegistry.ts`
-- Gestionnaire de génération d'images : `open-sse/handlers/imageGeneration.ts`
-- Registre du fournisseur d'images : `open-sse/config/imageRegistry.ts`
-- Désinfection des réponses : `open-sse/handlers/responseSanitizer.ts`
-- Normalisation des rôles : `open-sse/services/roleNormalizer.ts`
+Main flow modules:
 
-Services (logique métier) :
+- Entry: `src/sse/handlers/chat.ts`
+- Core orchestration: `open-sse/handlers/chatCore.ts`
+- Provider execution adapters: `open-sse/executors/*`
+- Format detection/provider config: `open-sse/services/provider.ts`
+- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
+- Account fallback logic: `open-sse/services/accountFallback.ts`
+- Translation registry: `open-sse/translator/index.ts`
+- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
+- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
+- Think tag parser: `open-sse/utils/thinkTagParser.ts`
+- Embedding handler: `open-sse/handlers/embeddings.ts`
+- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
+- Image generation handler: `open-sse/handlers/imageGeneration.ts`
+- Image provider registry: `open-sse/config/imageRegistry.ts`
+- Response sanitization: `open-sse/handlers/responseSanitizer.ts`
+- Role normalization: `open-sse/services/roleNormalizer.ts`
 
-- Sélection/scoration des comptes : `open-sse/services/accountSelector.ts`
-- Gestion du cycle de vie du contexte : `open-sse/services/contextManager.ts`
-- Application du filtre IP : `open-sse/services/ipFilter.ts`
-- Suivi de session : `open-sse/services/sessionManager.ts`
-- Demande de déduplication : `open-sse/services/signatureCache.ts`
-- Injection d'invite système : `open-sse/services/systemPrompt.ts`
-- Penser la gestion budgétaire : `open-sse/services/thinkingBudget.ts`
-- Routage du modèle générique : `open-sse/services/wildcardRouter.ts`
-- Gestion des limites de débit : `open-sse/services/rateLimitManager.ts`
-- Disjoncteur : `open-sse/services/circuitBreaker.ts`
+Services (business logic):
 
-Modules de couche de domaine :
+- Account selection/scoring: `open-sse/services/accountSelector.ts`
+- Context lifecycle management: `open-sse/services/contextManager.ts`
+- IP filter enforcement: `open-sse/services/ipFilter.ts`
+- Session tracking: `open-sse/services/sessionManager.ts`
+- Request deduplication: `open-sse/services/signatureCache.ts`
+- System prompt injection: `open-sse/services/systemPrompt.ts`
+- Thinking budget management: `open-sse/services/thinkingBudget.ts`
+- Wildcard model routing: `open-sse/services/wildcardRouter.ts`
+- Rate limit management: `open-sse/services/rateLimitManager.ts`
+- Circuit breaker: `open-sse/services/circuitBreaker.ts`
+- 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
 
-- Disponibilité du modèle : `src/lib/domain/modelAvailability.ts`
-- Règles de coûts/budgets : `src/lib/domain/costRules.ts`
-- Politique de repli : `src/lib/domain/fallbackPolicy.ts`
-- Résolveur combo : `src/lib/domain/comboResolver.ts`
-- Politique de verrouillage : `src/lib/domain/lockoutPolicy.ts`
-- Moteur de politique : `src/domain/policyEngine.ts` — verrouillage centralisé → budget → évaluation de secours
-- Catalogue de codes d'erreur : `src/lib/domain/errorCodes.ts`
-- ID de demande : `src/lib/domain/requestId.ts`
-- Délai d'expiration de la récupération : `src/lib/domain/fetchTimeout.ts`
-- Demande de télémétrie : `src/lib/domain/requestTelemetry.ts`
-- Conformité/audit : `src/lib/domain/compliance/index.ts`
-- Exécuteur d'évaluation : `src/lib/domain/evalRunner.ts`
-- Persistance de l'état du domaine : `src/lib/db/domainState.ts` — SQLite CRUD pour les chaînes de secours, les budgets, l'historique des coûts, l'état de verrouillage, les disjoncteurs
+Domain layer modules:
 
-Modules du fournisseur OAuth (12 fichiers individuels sous `src/lib/oauth/providers/`) :
+- Model availability: `src/lib/domain/modelAvailability.ts`
+- Cost rules/budgets: `src/lib/domain/costRules.ts`
+- Fallback policy: `src/lib/domain/fallbackPolicy.ts`
+- Combo resolver: `src/lib/domain/comboResolver.ts`
+- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
+- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
+- Error codes catalog: `src/lib/domain/errorCodes.ts`
+- Request ID: `src/lib/domain/requestId.ts`
+- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
+- Request telemetry: `src/lib/domain/requestTelemetry.ts`
+- Compliance/audit: `src/lib/domain/compliance/index.ts`
+- Eval runner: `src/lib/domain/evalRunner.ts`
+- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
 
-- Index du registre : `src/lib/oauth/providers/index.ts`
-- Fournisseurs individuels : `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `qoder.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
-- Thin wrapper : `src/lib/oauth/providers.ts` — réexportations à partir de modules individuels## 3) Persistence Layer
+OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
 
-Base de données d'état primaire (SQLite) :
+- 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`
+- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
 
-- Infrastructure de base : `src/lib/db/core.ts` (better-sqlite3, migrations, WAL)
-- Façade de réexportation : `src/lib/localDb.ts` (fine couche de compatibilité pour les appelants)
-- fichier : `${DATA_DIR}/storage.sqlite` (ou `$XDG_CONFIG_HOME/omniroute/storage.sqlite` lorsqu'il est défini, sinon `~/.omniroute/storage.sqlite`)
-- entités (tables + espaces de noms KV) : ProviderConnections, ProviderNodes, modelAliases, combos, apiKeys, settings, pricing,**customModels**,**proxyConfig**,**ipFilter**,**thinkingBudget**,**systemPrompt**
+## 3) Persistence Layer
 
-Persistance d'utilisation :
+Primary state DB (SQLite):
 
-- façade : `src/lib/usageDb.ts` (modules décomposés dans `src/lib/usage/*`)
-- Tables SQLite dans `storage.sqlite` : `usage_history`, `call_logs`, `proxy_logs`
-- des artefacts de fichiers facultatifs restent pour la compatibilité/débogage (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
-- Les anciens fichiers JSON sont migrés vers SQLite par les migrations de démarrage lorsqu'ils sont présents
+- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL)
+- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers)
+- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`)
+- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
 
-Base de données d'état du domaine (SQLite) :
+Usage persistence:
 
-- `src/lib/db/domainState.ts` — Opérations CRUD pour l'état du domaine
-- Tableaux (créés dans `src/lib/db/core.ts`) : `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
-- Modèle de cache en écriture : les cartes en mémoire font autorité au moment de l'exécution ; les mutations sont écrites de manière synchrone dans SQLite ; l'état est restauré à partir de la base de données lors d'un démarrage à froid## 4) Auth + Security Surfaces
+- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`)
+- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
+- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
+- legacy JSON files are migrated to SQLite by startup migrations when present
 
-- Authentification des cookies du tableau de bord : `src/proxy.ts`, `src/app/api/auth/login/route.ts`
-- Génération/vérification de clé API : `src/shared/utils/apiKey.ts`
-- Les secrets du fournisseur ont persisté dans les entrées `providerConnections`
-- Prise en charge du proxy sortant via `open-sse/utils/proxyFetch.ts` (vars env) et `open-sse/utils/networkProxy.ts` (configurable par fournisseur ou global)## 5) Cloud Sync
+Domain State DB (SQLite):
 
-- Initialisation du planificateur : `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
-- Tâche périodique : `src/shared/services/cloudSyncScheduler.ts`
-- Tâche périodique : `src/shared/services/modelSyncScheduler.ts`
-- Route de contrôle : `src/app/api/sync/cloud/route.ts`## Request Lifecycle (`/v1/chat/completions`)
+- `src/lib/db/domainState.ts` — CRUD operations for domain state
+- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
+- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
+
+## 4) Auth + Security Surfaces
+
+- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
+- API key generation/verification: `src/shared/utils/apiKey.ts`
+- Provider secrets persisted in `providerConnections` entries
+- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
+
+## 5) Cloud Sync
+
+- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
+- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
+- Periodic task: `src/shared/services/modelSyncScheduler.ts`
+- Control route: `src/app/api/sync/cloud/route.ts`
+
+## Request Lifecycle (`/v1/chat/completions`)
 
 ```mermaid
 sequenceDiagram
@@ -338,7 +361,9 @@ flowchart TD
     Q -- No --> R[Return all unavailable]
 ```
 
-Les décisions de secours sont pilotées par « open-sse/services/accountFallback.ts » à l'aide de codes d'état et d'heuristiques de messages d'erreur. Le routage combiné ajoute une protection supplémentaire : les 400 à l'échelle du fournisseur, tels que les échecs de bloc de contenu en amont et de validation de rôle, sont traités comme des échecs locaux du modèle afin que les cibles combinées ultérieures puissent toujours s'exécuter.## OAuth Onboarding and Token Refresh Lifecycle
+Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run.
+
+## OAuth Onboarding and Token Refresh Lifecycle
 
 ```mermaid
 sequenceDiagram
@@ -368,7 +393,9 @@ sequenceDiagram
     Test-->>UI: validation result
 ```
 
-L'actualisation pendant le trafic en direct est exécutée dans `open-sse/handlers/chatCore.ts` via l'exécuteur `refreshCredentials()`.## Cloud Sync Lifecycle (Enable / Sync / Disable)
+Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
+
+## Cloud Sync Lifecycle (Enable / Sync / Disable)
 
 ```mermaid
 sequenceDiagram
@@ -400,7 +427,9 @@ sequenceDiagram
     Sync-->>UI: disabled
 ```
 
-La synchronisation périodique est déclenchée par « CloudSyncScheduler » lorsque le cloud est activé.## Data Model and Storage Map
+Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
+
+## Data Model and Storage Map
 
 ```mermaid
 erDiagram
@@ -501,12 +530,14 @@ erDiagram
     }
 ```
 
-Fichiers de stockage physique :
+Physical storage files:
 
-- Base de données d'exécution principale : `${DATA_DIR}/storage.sqlite`
-- lignes de journal de requête : `${DATA_DIR}/log.txt` (artefact compat/debug)
-- archives de charge utile d'appel structurées : `${DATA_DIR}/call_logs/`
-- sessions facultatives de débogage de traduction/demande : `<repo>/logs/...`## Deployment Topology
+- primary runtime DB: `${DATA_DIR}/storage.sqlite`
+- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact)
+- structured call payload archives: `${DATA_DIR}/call_logs/`
+- optional translator/request debug sessions: `<repo>/logs/...`
+
+## Deployment Topology
 
 ```mermaid
 flowchart LR
@@ -541,205 +572,248 @@ flowchart LR
 
 ### Route and API Modules
 
-- `src/app/api/v1/*`, `src/app/api/v1beta/*` : API de compatibilité
-- `src/app/api/v1/providers/[provider]/*` : routes dédiées par fournisseur (chat, intégrations, images)
-- `src/app/api/providers*` : fournisseur CRUD, validation, tests
-- `src/app/api/provider-nodes*` : gestion des nœuds compatibles personnalisés
-- `src/app/api/provider-models` : gestion de modèles personnalisés (CRUD)
-- `src/app/api/models/route.ts` : API de catalogue de modèles (alias + modèles personnalisés)
-- `src/app/api/oauth/*` : flux OAuth/device-code
-- `src/app/api/keys*` : cycle de vie de la clé API locale
-- `src/app/api/models/alias` : gestion des alias
-- `src/app/api/combos*` : gestion des combos de repli
-- `src/app/api/pricing` : remplacements de prix pour le calcul des coûts
-- `src/app/api/settings/proxy` : configuration du proxy (GET/PUT/DELETE)
-- `src/app/api/settings/proxy/test` : test de connectivité proxy sortant (POST)
-- `src/app/api/usage/*` : API d'utilisation et de logs
-- `src/app/api/sync/*` + `src/app/api/cloud/*` : synchronisation cloud et assistants orientés cloud
-- `src/app/api/cli-tools/*` : rédacteurs/vérificateurs de configuration CLI locaux
-- `src/app/api/settings/ip-filter` : liste autorisée/liste de blocage IP (GET/PUT)
-- `src/app/api/settings/thinking-budget` : configuration du budget du jeton de réflexion (GET/PUT)
-- `src/app/api/settings/system-prompt` : invite système globale (GET/PUT)
-- `src/app/api/sessions` : liste des sessions actives (GET)
-- `src/app/api/rate-limits` : statut de limite de débit par compte (GET)### Routing and Execution Core
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
+- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
+- `src/app/api/providers*`: provider CRUD, validation, testing
+- `src/app/api/provider-nodes*`: custom compatible node management
+- `src/app/api/provider-models`: custom model management (CRUD)
+- `src/app/api/models/route.ts`: model catalog API (aliases + custom models)
+- `src/app/api/oauth/*`: OAuth/device-code flows
+- `src/app/api/keys*`: local API key lifecycle
+- `src/app/api/models/alias`: alias management
+- `src/app/api/combos*`: fallback combo management
+- `src/app/api/pricing`: pricing overrides for cost calculation
+- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
+- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
+- `src/app/api/usage/*`: usage and logs APIs
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
+- `src/app/api/cli-tools/*`: local CLI config writers/checkers
+- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
+- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
+- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
+- `src/app/api/sessions`: active session listing (GET)
+- `src/app/api/rate-limits`: per-account rate limit status (GET)
 
-- `src/sse/handlers/chat.ts` : analyse des requêtes, gestion des combos, boucle de sélection de compte
-- `open-sse/handlers/chatCore.ts` : traduction, envoi de l'exécuteur, gestion des nouvelles tentatives/actualisations, configuration du flux
-- `open-sse/executors/*` : comportement du réseau et du format spécifique au fournisseur### Translation Registry and Format Converters
+### Routing and Execution Core
 
-- `open-sse/translator/index.ts` : registre et orchestration du traducteur
-- Demander des traducteurs : `open-sse/translator/request/*`
-- Traducteurs de réponses : `open-sse/translator/response/*`
-- Constantes de format : `open-sse/translator/formats.ts`### Persistence
+- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
+- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
+- `open-sse/executors/*`: provider-specific network and format behavior
 
-- `src/lib/db/*` : configuration/état persistant et persistance du domaine sur SQLite
-- `src/lib/localDb.ts` : réexportation de compatibilité pour les modules DB
-- `src/lib/usageDb.ts` : façade historique d'utilisation/journaux d'appels au-dessus des tables SQLite## Provider Executor Coverage (Strategy Pattern)
+### Translation Registry and Format Converters
 
-Chaque fournisseur dispose d'un exécuteur spécialisé étendant `BaseExecutor` (dans `open-sse/executors/base.ts`), qui fournit la construction d'URL, la construction d'en-tête, les nouvelles tentatives avec intervalle exponentiel, les hooks d'actualisation des informations d'identification et la méthode d'orchestration `execute()`.
+- `open-sse/translator/index.ts`: translator registry and orchestration
+- Request translators: `open-sse/translator/request/*`
+- Response translators: `open-sse/translator/response/*`
+- Format constants: `open-sse/translator/formats.ts`
 
-| Exécuteur testamentaire | Fournisseur(s)                                                                                                                                               | Manutention spéciale                                                                |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
-| `Exécuteur par défaut`  | OpenAI, Claude, Gemini, Qwen, Qoder, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Configuration dynamique d'URL/d'en-tête par fournisseur                             |
-| `AntigravityExecutor`   | Google Antigravité                                                                                                                                           | ID de projet/session personnalisés, analyse réessayée après                         |
-| `CodexExecutor`         | Codex OpenAI                                                                                                                                                 | Injecte des instructions système, force un effort de raisonnement                   |
-| `CurseurExécuteur`      | Curseur IDE                                                                                                                                                  | Protocole ConnectRPC, encodage Protobuf, signature de demande via somme de contrôle |
-| `GithubExecutor`        | Copilote GitHub                                                                                                                                              | Actualisation du jeton Copilot, en-têtes imitant VSCode                             |
-| `KiroExécuteur`         | AWS CodeWhisperer/Kiro                                                                                                                                       | Format binaire AWS EventStream → conversion SSE                                     |
-| `GeminiCLIEExecutor`    | CLI Gémeaux                                                                                                                                                  | Cycle d'actualisation du jeton Google OAuth                                         |
+### Persistence
 
-Tous les autres fournisseurs (y compris les nœuds compatibles personnalisés) utilisent « DefaultExecutor ».## Provider Compatibility Matrix
+- `src/lib/db/*`: persistent config/state and domain persistence on SQLite
+- `src/lib/localDb.ts`: compatibility re-export for DB modules
+- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables
 
-| Fournisseur           | Formater          | Authentification                | Flux             | Hors flux | Actualisation des jetons | API d'utilisation            |
-| --------------------- | ----------------- | ------------------------------- | ---------------- | --------- | ------------------------ | ---------------------------- | ------------------------------ |
-| Claude                | Claude            | Clé API/OAuth                   | ✅               | ✅        | ✅                       | ⚠️ Administrateur uniquement |
-| Gémeaux               | Gémeaux           | Clé API/OAuth                   | ✅               | ✅        | ✅                       | ⚠️Console Cloud              |
-| CLI Gémeaux           | gemini-cli        | OAuth                           | ✅               | ✅        | ✅                       | ⚠️Console Cloud              |
-| Antigravité           | antigravity       | OAuth                           | ✅               | ✅        | ✅                       | ✅ API de quota complet      |
-| OpenAI                | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
-| Codex                 | réponses ouvertes | OAuth                           | ✅ forcé         | ❌        | ✅                       | ✅ Limites de taux           |
-| Copilote GitHub       | ouvert            | OAuth + Jeton Copilot           | ✅               | ✅        | ✅                       | ✅ Instantanés de quotas     |
-| Curseur               | curseur           | Somme de contrôle personnalisée | ✅               | ✅        | ❌                       | ❌                           |
-| Kiro                  | Kiro              | AWS SSO OIDC                    | ✅ (EventStream) | ❌        | ✅                       | ✅ Usage limits              |
-| Qwen                  | ouvert            | OAuth                           | ✅               | ✅        | ✅                       | ⚠️ Par demande               |
-| Qoder                 | ouvert            | OAuth (de base)                 | ✅               | ✅        | ✅                       | ⚠️ Par demande               |
-| OuvrirRouter          | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
-| GLM/Kimi/MiniMax      | Claude            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
-| Recherche profonde    | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
-| Groq                  | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
-| xAI (Grok)            | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
-| Mistral               | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
-| Perplexité            | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
-| Ensemble IA           | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
-| IA de feux d'artifice | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
-| Cérébraux             | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
-| Cohérer               | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           |
-| NIM NVIDIA            | ouvert            | Clé API                         | ✅               | ✅        | ❌                       | ❌                           | ## Format Translation Coverage |
+## Provider Executor Coverage (Strategy Pattern)
 
-Les formats sources détectés incluent :
+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.
 
-- `openaï`
+| 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                                     |
+
+All other providers (including custom compatible nodes) use the `DefaultExecutor`.
+
+## Provider Compatibility Matrix
+
+| Provider         | Format           | Auth                  | Stream           | Non-Stream | Token Refresh | Usage API          |
+| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
+| Claude           | claude           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Admin only      |
+| Gemini           | gemini           | API Key / OAuth       | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Gemini CLI       | gemini-cli       | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Cloud Console   |
+| Antigravity      | antigravity      | OAuth                 | ✅               | ✅         | ✅            | ✅ Full quota API  |
+| OpenAI           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Codex            | openai-responses | OAuth                 | ✅ forced        | ❌         | ✅            | ✅ Rate limits     |
+| GitHub Copilot   | openai           | OAuth + Copilot Token | ✅               | ✅         | ✅            | ✅ Quota snapshots |
+| Cursor           | cursor           | Custom checksum       | ✅               | ✅         | ❌            | ❌                 |
+| Kiro             | kiro             | AWS SSO OIDC          | ✅ (EventStream) | ❌         | ✅            | ✅ Usage limits    |
+| Qwen             | openai           | OAuth                 | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| Qoder            | openai           | OAuth (Basic)         | ✅               | ✅         | ✅            | ⚠️ Per request     |
+| OpenRouter       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| GLM/Kimi/MiniMax | claude           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| DeepSeek         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Groq             | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| xAI (Grok)       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Mistral          | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Perplexity       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Together AI      | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Fireworks AI     | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cerebras         | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| Cohere           | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+| NVIDIA NIM       | openai           | API Key               | ✅               | ✅         | ❌            | ❌                 |
+
+## Format Translation Coverage
+
+Detected source formats include:
+
+- `openai`
 - `openai-responses`
-- 'Claude'
-- `Gémeaux`
+- `claude`
+- `gemini`
 
-Les formats cibles incluent :
+Target formats include:
 
-- Discussion/Réponses OpenAI
-  -Claude
-- Enveloppe Gemini/Gemini-CLI/Antigravité
-  -Kiro
-- Curseur
+- OpenAI chat/Responses
+- Claude
+- Gemini/Gemini-CLI/Antigravity envelope
+- Kiro
+- Cursor
 
-Les traductions utilisent**OpenAI comme format hub**— toutes les conversions passent par OpenAI comme intermédiaire :```
+Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
+
+```
 Source Format → OpenAI (hub) → Target Format
+```
 
-````
+Translations are selected dynamically based on source payload shape and provider target format.
 
-Les traductions sont sélectionnées dynamiquement en fonction de la forme de la charge utile source et du format cible du fournisseur.
+Additional processing layers in the translation pipeline:
 
-Couches de traitement supplémentaires dans le pipeline de traduction :
+- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance
+- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)
+- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field
+- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`
 
--**Désinfection des réponses**— Supprime les champs non standard des réponses au format OpenAI (à la fois en streaming et hors streaming) pour garantir une stricte conformité au SDK.
--**Normalisation des rôles**— Convertit « développeur » → « système » pour les cibles non OpenAI ; fusionne `system` → `user` pour les modèles qui rejettent le rôle système (GLM, ERNIE)
--**Think tag extraction**— Analyse les blocs `<think>...</think>` du contenu dans le champ `reasoning_content`
--**Sortie structurée**— Convertit OpenAI `response_format.json_schema` en `responseMimeType` + `responseSchema` de Gemini## Supported API Endpoints
+## Supported API Endpoints
 
-| Point de terminaison | Formater | Gestionnaire |
+| Endpoint                                           | Format             | Handler                                                             |
 | -------------------------------------------------- | ------------------ | ------------------------------------------------------------------- |
-| `POST /v1/chat/complétions` | Chat OpenAI | `src/sse/handlers/chat.ts` |
-| `POST /v1/messages` | Messages de Claude | Même gestionnaire (détecté automatiquement) |
-| `POST /v1/réponses` | Réponses OpenAI | `open-sse/handlers/responsesHandler.ts` |
-| `POST /v1/embeddings` | Intégrations OpenAI | `open-sse/handlers/embeddings.ts` |
-| `GET /v1/embeddings` | Liste des modèles | Itinéraire API |
-| `POST /v1/images/générations` | Images OpenAI | `open-sse/handlers/imageGeneration.ts` |
-| `GET /v1/images/générations` | Liste des modèles | Itinéraire API |
-| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat        | Dédié par fournisseur avec validation du modèle |
-| `POST /v1/providers/{provider}/embeddings` | Intégrations OpenAI | Dédié par fournisseur avec validation du modèle |
-| `POST /v1/providers/{provider}/images/générations` | Images OpenAI | Dédié par fournisseur avec validation du modèle |
-| `POST /v1/messages/count_tokens` | Compte de jetons Claude | Itinéraire API |
-| `GET /v1/models` | Liste des modèles OpenAI | Route API (chat + intégration + image + modèles personnalisés) |
-| `GET /api/models/catalogue` | Catalogue | Tous les modèles regroupés par fournisseur + type |
-| `POST /v1beta/models/*:streamGenerateContent` | Natif des Gémeaux | Itinéraire API |
-| `GET/PUT/DELETE /api/settings/proxy` | Configuration du proxy | Configuration du proxy réseau |
-| `POST /api/settings/proxy/test` | Connectivité proxy | Point de terminaison du test d’intégrité/de connectivité du proxy |
-| `GET/POST/DELETE /api/provider-models` | Modèles de fournisseurs | Métadonnées du modèle de fournisseur soutenant les modèles disponibles personnalisés et gérés |## Bypass Handler
+| `POST /v1/chat/completions`                        | OpenAI Chat        | `src/sse/handlers/chat.ts`                                          |
+| `POST /v1/messages`                                | Claude Messages    | Same handler (auto-detected)                                        |
+| `POST /v1/responses`                               | OpenAI Responses   | `open-sse/handlers/responsesHandler.ts`                             |
+| `POST /v1/embeddings`                              | OpenAI Embeddings  | `open-sse/handlers/embeddings.ts`                                   |
+| `GET /v1/embeddings`                               | Model listing      | API route                                                           |
+| `POST /v1/images/generations`                      | OpenAI Images      | `open-sse/handlers/imageGeneration.ts`                              |
+| `GET /v1/images/generations`                       | Model listing      | API route                                                           |
+| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat        | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings  | Dedicated per-provider with model validation                        |
+| `POST /v1/providers/{provider}/images/generations` | OpenAI Images      | Dedicated per-provider with model validation                        |
+| `POST /v1/messages/count_tokens`                   | Claude Token Count | API route                                                           |
+| `GET /v1/models`                                   | OpenAI Models list | API route (chat + embedding + image + custom models)                |
+| `GET /api/models/catalog`                          | Catalog            | All models grouped by provider + type                               |
+| `POST /v1beta/models/*:streamGenerateContent`      | Gemini native      | API route                                                           |
+| `GET/PUT/DELETE /api/settings/proxy`               | Proxy Config       | Network proxy configuration                                         |
+| `POST /api/settings/proxy/test`                    | Proxy Connectivity | Proxy health/connectivity test endpoint                             |
+| `GET/POST/DELETE /api/provider-models`             | Provider Models    | Provider model metadata backing custom and managed available models |
 
-Le gestionnaire de contournement (`open-sse/utils/bypassHandler.ts`) intercepte les requêtes « jetables » connues de Claude CLI — pings d'échauffement, extractions de titres et nombre de jetons — et renvoie une**fausse réponse**sans consommer de jetons du fournisseur en amont. Ceci est déclenché uniquement lorsque `User-Agent` contient `claude-cli`.## Request Logger Pipeline
+## Bypass Handler
 
-L'enregistreur de requêtes (`open-sse/utils/requestLogger.ts`) fournit un pipeline de journalisation de débogage en 7 étapes, désactivé par défaut, activé via `ENABLE_REQUEST_LOGS=true` :```
-1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json
-→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt
-````
+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`.
 
-Les fichiers sont écrits dans `<repo>/logs/<session>/` pour chaque session de requête.## Failure Modes and Resilience
+## Request Logging and Artifacts
+
+The older file-based request logger (`open-sse/utils/requestLogger.ts`) is retained only for
+legacy compatibility. The current runtime contract uses:
+
+- `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
 
-- Temps de recharge du compte du fournisseur en cas d'erreurs transitoires/taux/auth.
-- repli du compte avant l'échec de la demande
-- repli du modèle combiné lorsque le chemin modèle/fournisseur actuel est épuisé## 2) Token Expiry
+- provider account cooldown on transient/rate/auth errors
+- account fallback before failing request
+- combo model fallback when current model/provider path is exhausted
 
-- pré-vérification et actualisation avec nouvelle tentative pour les fournisseurs actualisables
-- Nouvelle tentative 401/403 après tentative d'actualisation dans le chemin principal## 3) Stream Safety
+## 2) Token Expiry
 
-- contrôleur de flux prenant en charge la déconnexion
-- flux de traduction avec vidage de fin de flux et gestion `[DONE]`
-- repli de l'estimation de l'utilisation lorsque les métadonnées d'utilisation du fournisseur sont manquantes## 4) Cloud Sync Degradation
+- pre-check and refresh with retry for refreshable providers
+- 401/403 retry after refresh attempt in core path
 
-- des erreurs de synchronisation apparaissent mais l'exécution locale continue
-- le planificateur a une logique capable de réessayer, mais l'exécution périodique appelle actuellement une synchronisation à tentative unique par défaut## 5) Data Integrity
+## 3) Stream Safety
 
-- Migrations de schéma SQLite et hooks de mise à niveau automatique au démarrage
-- chemin de compatibilité de migration JSON → SQLite hérité## Observability and Operational Signals
+- disconnect-aware stream controller
+- translation stream with end-of-stream flush and `[DONE]` handling
+- usage estimation fallback when provider usage metadata is missing
 
-Sources de visibilité d'exécution :
+## 4) Cloud Sync Degradation
 
-- les journaux de la console de `src/sse/utils/logger.ts`
-- agrégats d'utilisation par requête dans SQLite (`usage_history`, `call_logs`, `proxy_logs`)
-- captures de charge utile détaillées en quatre étapes dans SQLite (`request_detail_logs`) lorsque `settings.detailed_logs_enabled=true`
-- journal textuel de l'état de la demande dans `log.txt` (facultatif/compat)
-- Journaux facultatifs de requêtes/traductions approfondies sous `logs/` lorsque `ENABLE_REQUEST_LOGS=true`
-- points de terminaison d'utilisation du tableau de bord (`/api/usage/*`) pour la consommation de l'interface utilisateur
+- sync errors are surfaced but local runtime continues
+- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
 
-La capture détaillée de la charge utile des requêtes stocke jusqu'à quatre étapes de charge utile JSON par appel routé :
+## 5) Data Integrity
 
-- demande brute reçue du client
-- requête traduite effectivement envoyée en amont
-- réponse du fournisseur reconstruite en JSON ; les réponses diffusées en continu sont compactées dans le résumé final ainsi que les métadonnées du flux
-- réponse finale du client renvoyée par OmniRoute ; les réponses diffusées en continu sont stockées dans le même formulaire récapitulatif compact## Security-Sensitive Boundaries
+- SQLite schema migrations and auto-upgrade hooks at startup
+- legacy JSON → SQLite migration compatibility path
 
-- Le secret JWT (`JWT_SECRET`) sécurise la vérification/signature des cookies de session du tableau de bord
-- L'amorçage du mot de passe initial (`INITIAL_PASSWORD`) doit être explicitement configuré pour le provisionnement de première exécution
-- Le secret de la clé API HMAC (`API_KEY_SECRET`) sécurise le format de clé API locale générée
-- Les secrets du fournisseur (clés/jetons API) sont conservés dans la base de données locale et doivent être protégés au niveau du système de fichiers
-- Les points de terminaison de synchronisation dans le cloud s'appuient sur l'authentification par clé API + la sémantique de l'identifiant de la machine## Environment and Runtime Matrix
+## Observability and Operational Signals
 
-Variables d'environnement activement utilisées par le code :
+Runtime visibility sources:
 
-- Application/authentification : `JWT_SECRET`, `INITIAL_PASSWORD`
-- Stockage : `DATA_DIR`
-- Comportement du nœud compatible : `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
-- Remplacement facultatif de la base de stockage (Linux/macOS lorsque `DATA_DIR` n'est pas défini) : `XDG_CONFIG_HOME`
-- Hachage de sécurité : `API_KEY_SECRET`, `MACHINE_ID_SALT`
-- Journalisation : `ENABLE_REQUEST_LOGS`
-- URL de synchronisation/cloud : `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
-- Proxy sortant : `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` et variantes minuscules
-- Indicateurs de fonctionnalités SOCKS5 : `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
-- Aides de plate-forme/d'exécution (pas de configuration spécifique à l'application) : `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`## Known Architectural Notes
+- console logs from `src/sse/utils/logger.ts`
+- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)
+- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true`
+- textual request status log in `log.txt` (optional/compat)
+- optional 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
 
-1. `usageDb` et `localDb` partagent la même politique de répertoire de base (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) avec la migration des fichiers hérités.
-2. `/api/v1/route.ts` délègue au même constructeur de catalogue unifié utilisé par `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) pour éviter la dérive sémantique.
-3. L'enregistreur de requêtes écrit les en-têtes/corps complets lorsqu'il est activé ; traiter le répertoire des journaux comme sensible.
-4. Le comportement du cloud dépend de l'exactitude de « NEXT_PUBLIC_BASE_URL » et de l'accessibilité du point de terminaison du cloud.
-5. Le répertoire `open-sse/` est publié sous le nom `@omniroute/open-sse`**npm workspace package**. Le code source l'importe via `@omniroute/open-sse/...` (résolu par Next.js `transpilePackages`). Les chemins de fichiers dans ce document utilisent toujours le nom de répertoire « open-sse/ » pour des raisons de cohérence.
-6. Les graphiques du tableau de bord utilisent**Recharts**(basé sur SVG) pour des visualisations analytiques accessibles et interactives (graphiques à barres d'utilisation du modèle, tableaux de répartition des fournisseurs avec taux de réussite).
-7. Les tests E2E utilisent**Playwright**(`tests/e2e/`), exécutés via `npm run test:e2e`. Les tests unitaires utilisent**l'exécuteur de test Node.js**(`tests/unit/`), exécutés via `npm run test:unit`. Le code source sous `src/` est**TypeScript**(`.ts`/`.tsx`) ; l'espace de travail `open-sse/` reste JavaScript (`.js`).
-8. La page Paramètres est organisée en 5 onglets : Sécurité, Routage (6 stratégies globales : remplissage en premier, round-robin, p2c, aléatoire, moins utilisé, coût optimisé), Résilience (limites de débit modifiables, disjoncteur, politiques), IA (budget de réflexion, invite système, cache d'invite), Avancé (proxy).## Operational Verification Checklist
+Detailed request payload capture stores up to four JSON payload stages per routed call:
 
-- Construire à partir des sources : `npm run build`
-- Construire l'image Docker : `docker build -t omniroute .`
-- Démarrez le service et vérifiez :
+- raw request received from the client
+- translated request actually sent upstream
+- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata
+- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form
+
+## Security-Sensitive Boundaries
+
+- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
+- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning
+- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format
+- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level
+- Cloud sync endpoints rely on API key auth + machine id semantics
+
+## Environment and Runtime Matrix
+
+Environment variables actively used by code:
+
+- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Storage: `DATA_DIR`
+- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
+- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME`
+- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
+- Logging: `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`
+- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+
+## Known Architectural Notes
+
+1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.
+2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift.
+3. Request logger writes full headers/body when enabled; treat log directory as sensitive.
+4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability.
+5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency.
+6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates).
+7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`).
+8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies, **Context Relay** handoff config), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
+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 24+ detection**: `/api/settings/require-login` returns `nodeVersion` and `nodeCompatible` fields. The login page renders a warning banner when the runtime is incompatible.
+
+## Operational Verification Checklist
+
+- Build from source: `npm run build`
+- Build Docker image: `docker build -t omniroute .`
+- Start service and verify:
 - `GET /api/settings`
 - `GET /api/v1/models`
-- L'URL de base cible CLI doit être `http://<host>:20128/v1` lorsque `PORT=20128`
+- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`

docs/i18n/fr/docs/CODEBASE_DOCUMENTATION.md

@@ -387,7 +387,7 @@ import "./request/claude-to-openai.js"; // ← self-registers
 | `stream.ts`        | **SSE Transform Stream** : le pipeline de streaming principal. Deux modes : `TRANSLATE` (traduction plein format) et `PASSTHROUGH` (normaliser + extraire l'utilisation). Gère la mise en mémoire tampon des blocs, l'estimation de l'utilisation et le suivi de la longueur du contenu. Les instances d'encodeur/décodeur par flux évitent l'état partagé. |
 | `streamHelpers.ts` | Utilitaires SSE de bas niveau : `parseSSELine` (tolérant les espaces), `hasValuableContent` (filtre les morceaux vides pour OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (sérialisation SSE sensible au format avec nettoyage `perf_metrics`).                                                                                                        |
 | `usageTracking.ts` | Extraction de l'utilisation des jetons à partir de n'importe quel format (Claude/OpenAI/Gemini/Responses), estimation avec des ratios outil/message séparés par jeton, ajout de tampon (marge de sécurité de 2000 jetons), filtrage de champs spécifiques au format, journalisation de la console avec couleurs ANSI.                                       |
-| `requestLogger.ts` | Journalisation des demandes basées sur des fichiers (opt-in via `ENABLE_REQUEST_LOGS=true`). Crée des dossiers de session avec des fichiers numérotés : `1_req_client.json` → `7_res_client.txt`. Toutes les E/S sont asynchrones (tirer et oublier). Masque les en-têtes sensibles.                                                                        |
+| `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` | Intercepte les modèles spécifiques de Claude CLI (extraction de titre, échauffement, décompte) et renvoie de fausses réponses sans appeler aucun fournisseur. Prend en charge le streaming et le non-streaming. Intentionnellement limité à la portée Claude CLI.                                                                                           |
 | `networkProxy.ts`  | Résout l'URL du proxy sortant pour un fournisseur donné avec la priorité : configuration spécifique au fournisseur → configuration globale → variables d'environnement (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Prend en charge les exclusions `NO_PROXY`. Met en cache la configuration pendant 30 s.                                                     | #### SSE Streaming Pipeline |
 

docs/i18n/fr/docs/FEATURES.md

@@ -4,102 +4,168 @@
 
 ---
 
-Guide visuel de chaque section du tableau de bord OmniRoute.---
+
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
 
 ## 🔌 Providers
 
-Gérez les connexions des fournisseurs d'IA : fournisseurs OAuth (Claude Code, Codex, Gemini CLI), fournisseurs de clés API (Groq, DeepSeek, OpenRouter) et fournisseurs gratuits (Qoder, Qwen, Kiro). Les comptes Kiro incluent le suivi du solde créditeur : crédits restants, allocation totale et date de renouvellement visibles dans Tableau de bord → Utilisation.![Providers Dashboard](screenshots/01-providers.png)
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+![Providers Dashboard](screenshots/01-providers.png)
 
 ---
 
 ## 🎨 Combos
 
-Créez des combinaisons de routage de modèles avec 6 stratégies : prioritaire, pondérée, à tour de rôle, aléatoire, la moins utilisée et optimisée en termes de coûts. Chaque combo enchaîne plusieurs modèles avec un repli automatique et comprend des modèles rapides et des contrôles de préparation.![Combos Dashboard](screenshots/02-combos.png)
+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.
+
+![Combos Dashboard](screenshots/02-combos.png)
 
 ---
 
 ## 📊 Analytics
 
-Analyses d'utilisation complètes avec consommation de jetons, estimations de coûts, cartes thermiques d'activité, graphiques de distribution hebdomadaire et répartitions par fournisseur.![Analytics Dashboard](screenshots/03-analytics.png)
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+![Analytics Dashboard](screenshots/03-analytics.png)
 
 ---
 
 ## 🏥 System Health
 
-Surveillance en temps réel : disponibilité, mémoire, version, centiles de latence (p50/p95/p99), statistiques du cache et états des disjoncteurs du fournisseur.![Health Dashboard](screenshots/04-health.png)
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+![Health Dashboard](screenshots/04-health.png)
 
 ---
 
 ## 🔧 Translator Playground
 
-Quatre modes de débogage des traductions d'API :**Playground**(convertisseur de format),**Chat Tester**(requêtes en direct),**Test Bench**(tests par lots) et**Live Monitor**(flux en temps réel).![Translator Playground](screenshots/05-translator.png)
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+![Translator Playground](screenshots/05-translator.png)
 
 ---
 
 ## 🎮 Model Playground _(v2.0.9+)_
 
-Testez n’importe quel modèle directement depuis le tableau de bord. Sélectionnez le fournisseur, le modèle et le point de terminaison, rédigez des invites avec Monaco Editor, diffusez les réponses en temps réel, abandonnez en cours de route et affichez les métriques de synchronisation.---
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
 
 ## 🎨 Themes _(v2.0.5+)_
 
-Thèmes de couleurs personnalisables pour l'ensemble du tableau de bord. Choisissez parmi 7 couleurs prédéfinies (corail, bleu, rouge, vert, violet, orange, cyan) ou créez un thème personnalisé en choisissant n'importe quelle couleur hexadécimale. Prend en charge les modes clair, sombre et système.---
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
 
 ## ⚙️ Settings
 
-Panneau de paramètres complet avec onglets :
+Comprehensive settings panel with tabs:
 
--**Général**— Stockage système, gestion des sauvegardes (base de données d'exportation/importation) -**Apparence**— Sélecteur de thème (sombre/clair/système), préréglages de thèmes de couleurs et couleurs personnalisées, visibilité du journal de santé, contrôles de visibilité des éléments de la barre latérale -**Sécurité**— Protection des points de terminaison de l'API, blocage des fournisseurs personnalisés, filtrage IP, informations de session -**Routage**— Alias de modèle, dégradation des tâches en arrière-plan -**Résilience**— Persistance des limites de débit, réglage du disjoncteur, désactivation automatique des comptes interdits, surveillance de l'expiration des fournisseurs -**Avancé**— Remplacements de configuration, piste d'audit de configuration, mode de dégradation de repli![Settings Dashboard](screenshots/06-settings.png)
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring, **Context Relay** handoff threshold and summary model configuration
+- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
+
+![Settings Dashboard](screenshots/06-settings.png)
 
 ---
 
 ## 🔧 CLI Tools
 
-Configuration en un clic pour les outils de codage d'IA : Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor et Factory Droid. Comprend l'application/la réinitialisation automatisée de la configuration, les profils de connexion et le mappage de modèle.![CLI Tools Dashboard](screenshots/07-cli-tools.png)
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+![CLI Tools Dashboard](screenshots/07-cli-tools.png)
 
 ---
 
 ## 🤖 CLI Agents _(v2.0.11+)_
 
-Tableau de bord pour découvrir et gérer les agents CLI. Affiche une grille de 14 agents intégrés (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) avec :
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
 
--**Statut de l'installation**— Installé/Introuvable avec détection de version -**Badges de protocole**— stdio, HTTP, etc. -**Agents personnalisés**— Enregistrez n'importe quel outil CLI via un formulaire (nom, binaire, commande de version, arguments de spawn) -**CLI Fingerprint Matching**— Bascule par fournisseur pour faire correspondre les signatures de requête CLI natives, réduisant ainsi le risque d'interdiction tout en préservant l'adresse IP du proxy.---
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🔗 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
+
+---
 
 ## 🖼️ Media _(v2.0.3+)_
 
-Générez des images, des vidéos et de la musique à partir du tableau de bord. Prend en charge OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open et MusicGen.---
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
 
 ## 📝 Request Logs
 
-Journalisation des demandes en temps réel avec filtrage par fournisseur, modèle, compte et clé API. Affiche les codes d'état, l'utilisation des jetons, la latence et les détails de la réponse.![Usage Logs](screenshots/08-usage.png)
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+![Usage Logs](screenshots/08-usage.png)
 
 ---
 
 ## 🌐 API Endpoint
 
-Votre point de terminaison d'API unifié avec répartition des capacités : achèvements de chat, API de réponses, intégrations, génération d'images, reclassement, transcription audio, synthèse vocale, modérations et clés API enregistrées. Intégration de Cloudflare Quick Tunnel et prise en charge du proxy cloud pour l'accès à distance.![Endpoint Dashboard](screenshots/09-endpoint.png)
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+![Endpoint Dashboard](screenshots/09-endpoint.png)
 
 ---
 
 ## 🔑 API Key Management
 
-Créez, définissez et révoquez des clés API. Chaque clé peut être limitée à des modèles/fournisseurs spécifiques avec un accès complet ou des autorisations en lecture seule. Gestion visuelle des clés avec suivi de l'utilisation.---
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
 
 ## 📋 Audit Log
 
-Suivi des actions administratives avec filtrage par type d'action, acteur, cible, adresse IP et horodatage. Historique complet des événements de sécurité.---
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
 
 ## 🖥️ Desktop Application
 
-Application de bureau Native Electron pour Windows, macOS et Linux. Exécutez OmniRoute en tant qu'application autonome avec intégration dans la barre d'état système, prise en charge hors ligne, mise à jour automatique et installation en un clic.
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
 
-Principales caractéristiques :
+Key features:
 
-- Sondage de préparation du serveur (pas d'écran vide au démarrage à froid)
-- Barre d'état système avec gestion des ports
-- Politique de sécurité du contenu
-- Verrouillage à instance unique
-- Mise à jour automatique au redémarrage
-- Interface utilisateur conditionnelle à la plate-forme (feux de signalisation macOS, barre de titre par défaut Windows/Linux)
-- Emballage de build Hardened Electron — les « node_modules » liés symboliquement dans le bundle autonome sont détectés et rejetés avant l'empaquetage, évitant ainsi la dépendance d'exécution sur la machine de build (v2.5.5+)
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
 
-📖 Voir [`electron/README.md`](../electron/README.md) pour une documentation complète.
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.

docs/i18n/fr/docs/TROUBLESHOOTING.md

@@ -4,68 +4,141 @@
 
 ---
 
-Problèmes courants et solutions pour OmniRoute.---
+Common problems and solutions for OmniRoute.
+
+---
 
 ## Quick Fixes
 
-| Problème                                       | Solutions                                                                              |
-| ---------------------------------------------- | -------------------------------------------------------------------------------------- | --- |
-| La première connexion ne fonctionne pas        | Définissez `INITIAL_PASSWORD` dans `.env` (pas de valeur par défaut codée en dur)      |
-| Le tableau de bord s'ouvre sur le mauvais port | Définissez `PORT=20128` et `NEXT_PUBLIC_BASE_URL=http://localhost:20128`               |
-| Aucun journal de requête sous `logs/`          | Définir `ENABLE_REQUEST_LOGS=true`                                                     |
-| EACCES : autorisation refusée                  | Définissez `DATA_DIR=/path/to/writable/dir` pour remplacer `~/.omniroute`              |
-| La stratégie de routage ne sauvegarde pas      | Mise à jour vers v1.4.11+ (correctif du schéma Zod pour la persistance des paramètres) | --- |
+| 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      | You may be on Node.js 24+ — see [Node.js Compatibility](#nodejs-compatibility) 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 Node.js 24+. The `better-sqlite3` native binary is not compatible with Node.js 24, which causes a fatal crash when the server tries to initialize the database.
+
+**Symptoms:**
+
+- Login page shows a blank screen or a server error
+- Console shows `Error: Module did not self-register` or similar native binding errors
+- Starting with v3.5.5, the login page shows an **orange warning banner** with your Node version if incompatibility is detected
+
+**Fix:**
+
+1. Install Node.js 22 LTS (recommended):
+   ```bash
+   nvm install 22
+   nvm use 22
+   ```
+2. Verify your version: `node --version` should show `v22.x.x`
+3. Reinstall OmniRoute: `npm install -g omniroute`
+4. Restart: `omniroute`
+
+> **Supported versions:** Node.js 18, 20, or 22 LTS. Node.js 24+ is **not supported**.
+
+---
+
+## 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+.
+
+---
 
 ## Provider Issues
 
 ### "Language model did not provide messages"
 
-**Cause :**Quota de fournisseur épuisé.
+**Cause:** Provider quota exhausted.
 
-**Correction :**
+**Fix:**
 
-1. Vérifiez le suivi des quotas du tableau de bord
-2. Utilisez un combo avec des niveaux de secours
-3. Passez au niveau moins cher/gratuit### Rate Limiting
+1. Check dashboard quota tracker
+2. Use a combo with fallback tiers
+3. Switch to cheaper/free tier
 
-**Cause :**Quota d'abonnement épuisé.
+### Rate Limiting
 
-**Correction :**
+**Cause:** Subscription quota exhausted.
 
-- Ajouter une solution de secours : `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
-- Utilisez GLM/MiniMax comme sauvegarde bon marché### OAuth Token Expired
+**Fix:**
 
-OmniRoute actualise automatiquement les jetons. Si les problèmes persistent :
+- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+- Use GLM/MiniMax as cheap backup
 
-1. Tableau de bord → Fournisseur → Reconnecter
-2. Supprimez et rajoutez la connexion du fournisseur---
+### OAuth Token Expired
+
+OmniRoute auto-refreshes tokens. If issues persist:
+
+1. Dashboard → Provider → Reconnect
+2. Delete and re-add the provider connection
+
+---
 
 ## Cloud Issues
 
 ### Cloud Sync Errors
 
-1. Vérifiez que `BASE_URL` pointe vers votre instance en cours d'exécution (par exemple, `http://localhost:20128`)
-2. Vérifiez que « CLOUD_URL » pointe vers votre point de terminaison cloud (par exemple, « https://omniroute.dev »)
-3. Gardez les valeurs `NEXT_PUBLIC_*` alignées avec les valeurs côté serveur### Cloud `stream=false` Returns 500
+1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
+2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
+3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
 
-**Symptôme :**`Jeton inattendu 'd'...` sur le point de terminaison cloud pour les appels sans streaming.
+### Cloud `stream=false` Returns 500
 
-**Cause :**Upstream renvoie la charge utile SSE alors que le client attend du JSON.
+**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
 
-**Solution de contournement :**Utilisez « stream=true » pour les appels directs vers le cloud. Le runtime local inclut le repli SSE → JSON.### Cloud Says Connected but "Invalid API key"
+**Cause:** Upstream returns SSE payload while client expects JSON.
 
-1. Créez une nouvelle clé à partir du tableau de bord local (`/api/keys`)
-2. Exécutez la synchronisation cloud : Activer le cloud → Synchroniser maintenant
-3. Les clés anciennes/non synchronisées peuvent toujours renvoyer « 401 » sur le cloud---
+**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
+
+### Cloud Says Connected but "Invalid API key"
+
+1. Create a fresh key from local dashboard (`/api/keys`)
+2. Run cloud sync: Enable Cloud → Sync Now
+3. Old/non-synced keys can still return `401` on cloud
+
+---
 
 ## Docker Issues
 
 ### CLI Tool Shows Not Installed
 
-1. Vérifiez les champs d'exécution : `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
-2. Pour le mode portable : utilisez la cible d'image `runner-cli` (CLI fournies)
-3. Pour le mode de montage de l'hôte : définissez `CLI_EXTRA_PATHS` et montez le répertoire bin de l'hôte en lecture seule
-4. Si `installed=true` et `runnable=false` : le binaire a été trouvé mais le contrôle de santé a échoué### Quick Runtime Validation
+1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
+2. For portable mode: use image target `runner-cli` (bundled CLIs)
+3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
+4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
+
+### Quick Runtime Validation
 
 ```bash
 curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
@@ -79,16 +152,22 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
 
 ### High Costs
 
-1. Vérifiez les statistiques d'utilisation dans le tableau de bord → Utilisation
-2. Basculez le modèle principal vers GLM/MiniMax
-3. Utilisez l'offre gratuite (Gemini CLI, Qoder) pour les tâches non critiques
-4. Définissez les budgets de coûts par clé API : Tableau de bord → Clés API → Budget---
+1. Check usage stats in Dashboard → Usage
+2. Switch primary model to GLM/MiniMax
+3. Use free tier (Gemini CLI, Qoder) for non-critical tasks
+4. Set cost budgets per API key: Dashboard → API Keys → Budget
+
+---
 
 ## Debugging
 
-### Enable Request Logs
+### Enable Log Files
 
-Définissez `ENABLE_REQUEST_LOGS=true` dans votre fichier `.env`. Les journaux apparaissent dans le répertoire `logs/`.### Check Provider Health
+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
 
 ```bash
 # Health dashboard
@@ -100,101 +179,136 @@ curl http://localhost:20128/api/monitoring/health
 
 ### Runtime Storage
 
-- État principal : `${DATA_DIR}/storage.sqlite` (fournisseurs, combos, alias, clés, paramètres)
-- Utilisation : tables SQLite dans `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + facultatif `${DATA_DIR}/log.txt` et `${DATA_DIR}/call_logs/`
-- Journaux de requête : `<repo>/logs/...` (quand `ENABLE_REQUEST_LOGS=true`)---
+- 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}/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
+
+---
 
 ## Circuit Breaker Issues
 
 ### Provider stuck in OPEN state
 
-Lorsque le disjoncteur d'un fournisseur est OUVERT, les demandes sont bloquées jusqu'à l'expiration du temps de recharge.
+When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
 
-**Correction :**
+**Fix:**
 
-1. Accédez à**Tableau de bord → Paramètres → Résilience**
-2. Vérifiez la carte de disjoncteur du fournisseur concerné
-3. Cliquez sur**Réinitialiser tout**pour effacer tous les disjoncteurs ou attendez l'expiration du temps de recharge.
-4. Vérifiez que le fournisseur est réellement disponible avant de réinitialiser### Provider keeps tripping the circuit breaker
+1. Go to **Dashboard → Settings → Resilience**
+2. Check the circuit breaker card for the affected provider
+3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
+4. Verify the provider is actually available before resetting
 
-Si un fournisseur entre à plusieurs reprises dans l’état OPEN :
+### Provider keeps tripping the circuit breaker
 
-1. Vérifiez**Tableau de bord → Santé → Santé du fournisseur**pour connaître le modèle d'échec.
-2. Accédez à**Paramètres → Résilience → Profils de fournisseur**et augmentez le seuil d'échec.
-3. Vérifiez si le fournisseur a modifié les limites de l'API ou nécessite une ré-authentification
-4. Examinez la télémétrie de latence : une latence élevée peut provoquer des échecs liés au délai d'attente.---
+If a provider repeatedly enters OPEN state:
+
+1. Check **Dashboard → Health → Provider Health** for the failure pattern
+2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
+3. Check if the provider has changed API limits or requires re-authentication
+4. Review latency telemetry — high latency may cause timeout-based failures
+
+---
 
 ## Audio Transcription Issues
 
 ### "Unsupported model" error
 
-- Assurez-vous d'utiliser le préfixe correct : `deepgram/nova-3` ou `assemblyai/best`
-- Vérifiez que le fournisseur est connecté dans**Tableau de bord → Fournisseurs**### Transcription returns empty or fails
+- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
+- Verify the provider is connected in **Dashboard → Providers**
 
-- Vérifiez les formats audio pris en charge : `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
-- Vérifiez que la taille du fichier est dans les limites du fournisseur (généralement < 25 Mo)
-- Vérifier la validité de la clé API du fournisseur dans la carte du fournisseur---
+### Transcription returns empty or fails
+
+- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
+- Verify file size is within provider limits (typically < 25MB)
+- Check provider API key validity in the provider card
+
+---
 
 ## Translator Debugging
 
-Utilisez**Tableau de bord → Traducteur**pour déboguer les problèmes de traduction de format :
+Use **Dashboard → Translator** to debug format translation issues:
 
-| Mode                   | Quand utiliser                                                                                                       |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| **Aire de jeux**       | Comparez les formats d'entrée/sortie côte à côte : collez une requête qui a échoué pour voir comment elle se traduit |
-| **Testeur de chat**    | Envoyez des messages en direct et inspectez la charge utile complète de la demande/réponse, y compris les en-têtes   |
-| **Banc d'essai**       | Exécutez des tests par lots sur les combinaisons de formats pour identifier les traductions défectueuses             |
-| **Moniteur en direct** | Observez le flux de requêtes en temps réel pour détecter les problèmes de traduction intermittents                   | ### Common format issues |
+| Mode             | When to Use                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| **Playground**   | Compare input/output formats side by side — paste a failing request to see how it translates |
+| **Chat Tester**  | Send live messages and inspect the full request/response payload including headers           |
+| **Test Bench**   | Run batch tests across format combinations to find which translations are broken             |
+| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues                        |
 
--**Les balises de réflexion n'apparaissent pas**— Vérifiez si le fournisseur cible prend en charge la réflexion et le paramètre de budget de réflexion -**Abandon des appels d'outils**— Certaines traductions de format peuvent supprimer des champs non pris en charge ; vérifier en mode Playground -**Invite système manquante**— Claude et Gemini gèrent les invites système différemment ; vérifier le résultat de la traduction -**Le SDK renvoie une chaîne brute au lieu d'un objet**— Corrigé dans la version 1.1.0 : le désinfectant de réponse supprime désormais les champs non standard (`x_groq`, `usage_breakdown`, etc.) qui provoquent des échecs de validation OpenAI SDK Pydantic -**GLM/ERNIE rejette le rôle `système`**— Corrigé dans la version 1.1.0 : le normalisateur de rôle fusionne automatiquement les messages système dans les messages utilisateur pour les modèles incompatibles -**Rôle de « développeur » non reconnu**— Corrigé dans la version 1.1.0 : automatiquement converti en « système » pour les fournisseurs non OpenAI -**`json_schema` ne fonctionne pas avec Gemini**— Corrigé dans la v1.1.0 : `response_format` est maintenant converti en `responseMimeType` + `responseSchema` de Gemini---
+### Common format issues
+
+- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
+- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
+- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
+- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures
+- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
+- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers
+- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema`
+
+---
 
 ## Resilience Settings
 
 ### Auto rate-limit not triggering
 
-- La limite de débit automatique s'applique uniquement aux fournisseurs de clés API (pas à OAuth/abonnement)
-- Vérifiez que**Paramètres → Résilience → Profils de fournisseur**a activé la limite de débit automatique.
-- Vérifiez si le fournisseur renvoie les codes d'état « 429 » ou les en-têtes « Retry-After »### Tuning exponential backoff
+- Auto rate-limit only applies to API key providers (not OAuth/subscription)
+- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
+- Check if the provider returns `429` status codes or `Retry-After` headers
 
-Les profils de fournisseur prennent en charge ces paramètres :
+### Tuning exponential backoff
 
--**Délai de base**— Temps d'attente initial après le premier échec (par défaut : 1 s) -**Délai maximum**— Limite maximale du temps d'attente (par défaut : 30 s) -**Multiplicateur**— De combien augmenter le délai par échec consécutif (par défaut : 2x)### Anti-thundering herd
+Provider profiles support these settings:
 
-Lorsque de nombreuses requêtes simultanées atteignent un fournisseur à débit limité, OmniRoute utilise mutex + limitation de débit automatique pour sérialiser les requêtes et éviter les échecs en cascade. Ceci est automatique pour les fournisseurs de clés API.---
+- **Base delay** — Initial wait time after first failure (default: 1s)
+- **Max delay** — Maximum wait time cap (default: 30s)
+- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
+
+### Anti-thundering herd
+
+When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
+
+---
 
 ## Optional RAG / LLM failure taxonomy (16 problems)
 
-Certains utilisateurs d'OmniRoute placent la passerelle devant les RAG ou les piles d'agents. Dans ces configurations, il est courant de voir un schéma étrange : OmniRoute semble sain (fournisseurs activés, profils de routage corrects, aucune alerte de limite de débit) mais la réponse finale est toujours fausse.
+Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong.
 
-En pratique, ces incidents proviennent généralement du pipeline RAG en aval, et non de la passerelle elle-même.
+In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself.
 
-Si vous souhaitez un vocabulaire partagé pour décrire ces échecs, vous pouvez utiliser le WFGY ProblemMap, une ressource textuelle externe sous licence MIT qui définit seize modèles d'échecs RAG/LLM récurrents. À un niveau élevé, il couvre :
+If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers:
 
-- dérive de récupération et limites de contexte brisées
-- index vides ou obsolètes et magasins de vecteurs
-- intégration versus inadéquation sémantique
-- problèmes d'assemblage rapide et de fenêtre contextuelle
-- effondrement de la logique et réponses trop confiantes
-- échecs de la longue chaîne et de la coordination des agents
-- mémoire multi-agents et dérive des rôles
-- problèmes de déploiement et d'ordre d'amorçage
+- retrieval drift and broken context boundaries
+- empty or stale indexes and vector stores
+- embedding versus semantic mismatch
+- prompt assembly and context window issues
+- logic collapse and overconfident answers
+- long chain and agent coordination failures
+- multi agent memory and role drift
+- deployment and bootstrap ordering problems
 
-L'idée est simple :
+The idea is simple:
 
-1. Lorsque vous enquêtez sur une mauvaise réponse, capturez :
-   - tâche et demande de l'utilisateur
-   - combo d'itinéraire ou de fournisseur dans OmniRoute
-   - tout contexte RAG utilisé en aval (documents récupérés, appels d'outils, etc.)
-2. Cartographiez l'incident avec un ou deux numéros WFGY ProblemMap (« No.1 » … « No.16 »).
-3. Stockez le numéro dans votre propre tableau de bord, runbook ou suivi des incidents à côté des journaux OmniRoute.
-4. Utilisez la page WFGY correspondante pour décider si vous devez modifier votre pile RAG, votre récupérateur ou votre stratégie de routage.
+1. When you investigate a bad response, capture:
+   - user task and request
+   - route or provider combo in OmniRoute
+   - any RAG context used downstream (retrieved documents, tool calls, etc)
+2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`).
+3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs.
+4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy.
 
-Texte intégral et recettes concrètes en direct ici (licence MIT, texte uniquement) :
+Full text and concrete recipes live here (MIT license, text only):
 
-[WFGY ProblemMap README](https://github.com/onestadao/WFGY/blob/main/ProblemMap/README.md)
+[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
 
-Vous pouvez ignorer cette section si vous n'exécutez pas de RAG ou de pipelines d'agent derrière OmniRoute.---
+You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute.
+
+---
 
 ## Still Stuck?
 
--**Problèmes GitHub** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -**Architecture** : Voir [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) pour les détails internes -**Référence API** : voir [`docs/API_REFERENCE.md`](API_REFERENCE.md) pour tous les points de terminaison -**Tableau de bord de santé** : consultez**Tableau de bord → Santé**pour connaître l'état du système en temps réel -**Traducteur** : utilisez**Tableau de bord → Traducteur**pour déboguer les problèmes de format
+- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
+- **Translator**: Use **Dashboard → Translator** to debug format issues

docs/i18n/fr/docs/VM_DEPLOYMENT_GUIDE.md

@@ -100,7 +100,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/fr/llm.txt

@@ -0,0 +1,476 @@
+# OmniRoute (Français)
+
+🌐 **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.
+
+## Aperçu
+
+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)
+
+### Sécurité
+- **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