Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
refactor: update root .md / .agents / .claude doc-path references
diegosouzapweb02fda32776
diff --git a/.agents/skills/generate-release/SKILL.md b/.agents/skills/generate-release/SKILL.mdindex 9dfb27ea87..6632c2a434 100644--- a/.agents/skills/generate-release/SKILL.md+++ b/.agents/skills/generate-release/SKILL.md@@ -130,13 +130,13 @@ Keep an empty `## [Unreleased]` section above it, separated by a horizontal rule### 5. Update openapi.yaml version ⚠️ MANDATORY-> **CI will fail** if `docs/openapi.yaml` version ≠ `package.json` version (`check:docs-sync` enforces this).+> **CI will fail** if `docs/reference/openapi.yaml` version ≠ `package.json` version (`check:docs-sync` enforces this).// turbo```bashVERSION=$(node -p "require('./package.json').version")-sed -i "s/ version: .*/ version: $VERSION/" docs/openapi.yaml+sed -i "s/ version: .*/ version: $VERSION/" docs/reference/openapi.yamlecho "✓ openapi.yaml → $VERSION"for dir in electron open-sse; do@@ -360,9 +360,9 @@ If a workflow fails:## Known CI Pitfalls-| CI failure | Cause | Fix |-| ------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- |-| `[docs-sync] FAIL - OpenAPI version differs from package.json` | Skipped step 5 — `docs/openapi.yaml` version not updated | Run step 5 (`sed -i ...`) and commit |-| `[docs-sync] FAIL - CHANGELOG.md first section must be "## [Unreleased]"` | `## [Unreleased]` missing or not at top of CHANGELOG | Add `## [Unreleased]\n\n---\n` before the first versioned `## [x.y.z]` |-| Electron Linux `.deb` build fails (`FpmTarget` error) | `fpm` Ruby gem not installed on `ubuntu-latest` runner | Already fixed in `electron-release.yml` (`gem install fpm` step) |-| Docker Hub `502 error writing layer blob` | Transient Docker Hub network error during ARM64 push | Re-run the Docker publish workflow; no code change needed |+| CI failure | Cause | Fix |+| ------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------- |+| `[docs-sync] FAIL - OpenAPI version differs from package.json` | Skipped step 5 — `docs/reference/openapi.yaml` version not updated | Run step 5 (`sed -i ...`) and commit |+| `[docs-sync] FAIL - CHANGELOG.md first section must be "## [Unreleased]"` | `## [Unreleased]` missing or not at top of CHANGELOG | Add `## [Unreleased]\n\n---\n` before the first versioned `## [x.y.z]` |+| Electron Linux `.deb` build fails (`FpmTarget` error) | `fpm` Ruby gem not installed on `ubuntu-latest` runner | Already fixed in `electron-release.yml` (`gem install fpm` step) |+| Docker Hub `502 error writing layer blob` | Transient Docker Hub network error during ARM64 push | Re-run the Docker publish workflow; no code change needed |diff --git a/.agents/skills/version-bump/SKILL.md b/.agents/skills/version-bump/SKILL.mdindex bc397ded33..3d3ddf9f4a 100644--- a/.agents/skills/version-bump/SKILL.md+++ b/.agents/skills/version-bump/SKILL.md@@ -142,9 +142,9 @@ The date must be today's date in `YYYY-MM-DD` format.cd /home/diegosouzapw/dev/proxys/OmniRouteVERSION=$(node -p "require('./package.json').version")-# Update docs/openapi.yaml version-sed -i "s/ version: .*/ version: $VERSION/" docs/openapi.yaml-echo "✓ docs/openapi.yaml → $VERSION"+# Update docs/reference/openapi.yaml version+sed -i "s/ version: .*/ version: $VERSION/" docs/reference/openapi.yaml+echo "✓ docs/reference/openapi.yaml → $VERSION"# Update workspace packages (open-sse, electron)for dir in electron open-sse; do@@ -214,36 +214,36 @@ For each file below, read the current content and determine if the CHANGELOG entFor each file in `docs/` (excluding `docs/i18n/`), review if CHANGELOG changes affect it:-| File | When to update |-| -------------------------------- | ------------------------------------------------------------------ |-| `docs/API_REFERENCE.md` | New API endpoints, changed request/response formats |-| `docs/ARCHITECTURE.md` | New modules, new services, changed data flow |-| `docs/CODEBASE_DOCUMENTATION.md` | New files, architectural changes, module reorganization |-| `docs/REPOSITORY_MAP.md` | New folders / files / one-line descriptions |-| `docs/CLI-TOOLS.md` | New CLI tool integrations, config format changes |-| `docs/USER_GUIDE.md` | UX changes, new dashboard pages, settings changes |-| `docs/PROVIDER_REFERENCE.md` | New providers (regenerate via `scripts/gen-provider-reference.ts`) |-| `docs/MCP-SERVER.md` | New MCP tools, changed tool signatures, scope changes |-| `docs/A2A-SERVER.md` | New A2A skills, protocol changes |-| `docs/AGENT_PROTOCOLS_GUIDE.md` | New external agent protocols supported |-| `docs/CLOUD_AGENT.md` | Cloud agent additions (codex-cloud, devin, jules) or API changes |-| `docs/AUTHZ_GUIDE.md` | New route classifications, policy changes |-| `docs/GUARDRAILS.md` | New guardrails registered, priority/order changes |-| `docs/COMPLIANCE.md` | Audit log / retention / no-log policy changes |-| `docs/SKILLS.md` | Skill framework / registry / built-in skill changes |-| `docs/MEMORY.md` | Memory pipeline / extraction / injection / Qdrant changes |-| `docs/EVALS.md` | Evaluation framework changes, new evaluators |-| `docs/WEBHOOKS.md` | New webhook events, payload schema changes |-| `docs/REASONING_REPLAY.md` | Reasoning capture/replay pipeline changes |-| `docs/AUTO-COMBO.md` | Routing changes, new strategies, scoring weight changes |-| `docs/RESILIENCE_GUIDE.md` | Circuit breaker / cooldown / lockout behavior changes |-| `docs/STEALTH_GUIDE.md` | TLS / CLI fingerprint changes |-| `docs/TUNNELS_GUIDE.md` | Cloudflare tunnel feature changes |-| `docs/ELECTRON_GUIDE.md` | Electron build / signing / packaging changes |-| `docs/TROUBLESHOOTING.md` | New known issues, resolved problems |-| `docs/RELEASE_CHECKLIST.md` | Process changes |-| `docs/COVERAGE_PLAN.md` | Coverage gate adjustments, target metrics |-| `docs/openapi.yaml` | Already updated in step 7 |+| File | When to update |+| --------------------------------------------- | ------------------------------------------------------------------ |+| `docs/reference/API_REFERENCE.md` | New API endpoints, changed request/response formats |+| `docs/architecture/ARCHITECTURE.md` | New modules, new services, changed data flow |+| `docs/architecture/CODEBASE_DOCUMENTATION.md` | New files, architectural changes, module reorganization |+| `docs/architecture/REPOSITORY_MAP.md` | New folders / files / one-line descriptions |+| `docs/reference/CLI-TOOLS.md` | New CLI tool integrations, config format changes |+| `docs/guides/USER_GUIDE.md` | UX changes, new dashboard pages, settings changes |+| `docs/reference/PROVIDER_REFERENCE.md` | New providers (regenerate via `scripts/gen-provider-reference.ts`) |+| `docs/frameworks/MCP-SERVER.md` | New MCP tools, changed tool signatures, scope changes |+| `docs/frameworks/A2A-SERVER.md` | New A2A skills, protocol changes |+| `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` | New external agent protocols supported |+| `docs/frameworks/CLOUD_AGENT.md` | Cloud agent additions (codex-cloud, devin, jules) or API changes |+| `docs/architecture/AUTHZ_GUIDE.md` | New route classifications, policy changes |+| `docs/security/GUARDRAILS.md` | New guardrails registered, priority/order changes |+| `docs/security/COMPLIANCE.md` | Audit log / retention / no-log policy changes |+| `docs/frameworks/SKILLS.md` | Skill framework / registry / built-in skill changes |+| `docs/frameworks/MEMORY.md` | Memory pipeline / extraction / injection / Qdrant changes |+| `docs/frameworks/EVALS.md` | Evaluation framework changes, new evaluators |+| `docs/frameworks/WEBHOOKS.md` | New webhook events, payload schema changes |+| `docs/routing/REASONING_REPLAY.md` | Reasoning capture/replay pipeline changes |+| `docs/routing/AUTO-COMBO.md` | Routing changes, new strategies, scoring weight changes |+| `docs/architecture/RESILIENCE_GUIDE.md` | Circuit breaker / cooldown / lockout behavior changes |+| `docs/security/STEALTH_GUIDE.md` | TLS / CLI fingerprint changes |+| `docs/ops/TUNNELS_GUIDE.md` | Cloudflare tunnel feature changes |+| `docs/guides/ELECTRON_GUIDE.md` | Electron build / signing / packaging changes |+| `docs/guides/TROUBLESHOOTING.md` | New known issues, resolved problems |+| `docs/ops/RELEASE_CHECKLIST.md` | Process changes |+| `docs/ops/COVERAGE_PLAN.md` | Coverage gate adjustments, target metrics |+| `docs/reference/openapi.yaml` | Already updated in step 7 |**Only update files where the CHANGELOG entries directly affect the documented content.** Do NOT update files just to bump a version number — only when the documented behavior, features, or architecture has actually changed.@@ -288,8 +288,8 @@ grep '"version"' open-sse/package.json | head -1echo "--- electron/package.json ---"[ -f electron/package.json ] && grep '"version"' electron/package.json | head -1-echo "--- docs/openapi.yaml ---"-grep " version:" docs/openapi.yaml | head -1+echo "--- docs/reference/openapi.yaml ---"+grep " version:" docs/reference/openapi.yaml | head -1echo "--- llm.txt ---"grep "Current version:" llm.txt@@ -337,11 +337,11 @@ git commit -m "chore(release): bump to v$VERSION — changelog, docs, version sy## Version Touchpoints Checklist-| File | Field/Pattern |-| ----------------------- | ----------------------------------------------------------- |-| `package.json` | `"version": "X.Y.Z"` |-| `open-sse/package.json` | `"version": "X.Y.Z"` |-| `electron/package.json` | `"version": "X.Y.Z"` |-| `docs/openapi.yaml` | `version: X.Y.Z` |-| `llm.txt` | `**Current version:** X.Y.Z` and `## Key Features (vX.Y.Z)` |-| `CHANGELOG.md` | `## [X.Y.Z] — YYYY-MM-DD` |+| File | Field/Pattern |+| ----------------------------- | ----------------------------------------------------------- |+| `package.json` | `"version": "X.Y.Z"` |+| `open-sse/package.json` | `"version": "X.Y.Z"` |+| `electron/package.json` | `"version": "X.Y.Z"` |+| `docs/reference/openapi.yaml` | `version: X.Y.Z` |+| `llm.txt` | `**Current version:** X.Y.Z` and `## Key Features (vX.Y.Z)` |+| `CHANGELOG.md` | `## [X.Y.Z] — YYYY-MM-DD` |diff --git a/.agents/workflows/generate-release-ag.md b/.agents/workflows/generate-release-ag.mdindex f92875a8f5..8919137688 100644--- a/.agents/workflows/generate-release-ag.md+++ b/.agents/workflows/generate-release-ag.md@@ -124,13 +124,13 @@ Keep an empty `## [Unreleased]` section above it, separated by a horizontal rule### 5. Update openapi.yaml version ⚠️ MANDATORY-> **CI will fail** if `docs/openapi.yaml` version ≠ `package.json` version (`check:docs-sync` enforces this).+> **CI will fail** if `docs/reference/openapi.yaml` version ≠ `package.json` version (`check:docs-sync` enforces this).// turbo```bashVERSION=$(node -p "require('./package.json').version")-sed -i "s/ version: .*/ version: $VERSION/" docs/openapi.yaml+sed -i "s/ version: .*/ version: $VERSION/" docs/reference/openapi.yamlecho "✓ openapi.yaml → $VERSION"for dir in electron open-sse; do@@ -354,9 +354,9 @@ If a workflow fails:## Known CI Pitfalls-| CI failure | Cause | Fix |-| ------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- |-| `[docs-sync] FAIL - OpenAPI version differs from package.json` | Skipped step 5 — `docs/openapi.yaml` version not updated | Run step 5 (`sed -i ...`) and commit |-| `[docs-sync] FAIL - CHANGELOG.md first section must be "## [Unreleased]"` | `## [Unreleased]` missing or not at top of CHANGELOG | Add `## [Unreleased]\n\n---\n` before the first versioned `## [x.y.z]` |-| Electron Linux `.deb` build fails (`FpmTarget` error) | `fpm` Ruby gem not installed on `ubuntu-latest` runner | Already fixed in `electron-release.yml` (`gem install fpm` step) |-| Docker Hub `502 error writing layer blob` | Transient Docker Hub network error during ARM64 push | Re-run the Docker publish workflow; no code change needed |+| CI failure | Cause | Fix |+| ------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------- |+| `[docs-sync] FAIL - OpenAPI version differs from package.json` | Skipped step 5 — `docs/reference/openapi.yaml` version not updated | Run step 5 (`sed -i ...`) and commit |+| `[docs-sync] FAIL - CHANGELOG.md first section must be "## [Unreleased]"` | `## [Unreleased]` missing or not at top of CHANGELOG | Add `## [Unreleased]\n\n---\n` before the first versioned `## [x.y.z]` |+| Electron Linux `.deb` build fails (`FpmTarget` error) | `fpm` Ruby gem not installed on `ubuntu-latest` runner | Already fixed in `electron-release.yml` (`gem install fpm` step) |+| Docker Hub `502 error writing layer blob` | Transient Docker Hub network error during ARM64 push | Re-run the Docker publish workflow; no code change needed |diff --git a/.agents/workflows/version-bump-ag.md b/.agents/workflows/version-bump-ag.mdindex dd11d7a98a..8c356e52b5 100644--- a/.agents/workflows/version-bump-ag.md+++ b/.agents/workflows/version-bump-ag.md@@ -136,9 +136,9 @@ The date must be today's date in `YYYY-MM-DD` format.cd /home/diegosouzapw/dev/proxys/OmniRouteVERSION=$(node -p "require('./package.json').version")-# Update docs/openapi.yaml version-sed -i "s/ version: .*/ version: $VERSION/" docs/openapi.yaml-echo "✓ docs/openapi.yaml → $VERSION"+# Update docs/reference/openapi.yaml version+sed -i "s/ version: .*/ version: $VERSION/" docs/reference/openapi.yaml+echo "✓ docs/reference/openapi.yaml → $VERSION"# Update workspace packages (open-sse, electron)for dir in electron open-sse; do@@ -208,36 +208,36 @@ For each file below, read the current content and determine if the CHANGELOG entFor each file in `docs/` (excluding `docs/i18n/`), review if CHANGELOG changes affect it:-| File | When to update |-| -------------------------------- | ------------------------------------------------------------------ |-| `docs/API_REFERENCE.md` | New API endpoints, changed request/response formats |-| `docs/ARCHITECTURE.md` | New modules, new services, changed data flow |-| `docs/CODEBASE_DOCUMENTATION.md` | New files, architectural changes, module reorganization |-| `docs/REPOSITORY_MAP.md` | New folders / files / one-line descriptions |-| `docs/CLI-TOOLS.md` | New CLI tool integrations, config format changes |-| `docs/USER_GUIDE.md` | UX changes, new dashboard pages, settings changes |-| `docs/PROVIDER_REFERENCE.md` | New providers (regenerate via `scripts/gen-provider-reference.ts`) |-| `docs/MCP-SERVER.md` | New MCP tools, changed tool signatures, scope changes |-| `docs/A2A-SERVER.md` | New A2A skills, protocol changes |-| `docs/AGENT_PROTOCOLS_GUIDE.md` | New external agent protocols supported |-| `docs/CLOUD_AGENT.md` | Cloud agent additions (codex-cloud, devin, jules) or API changes |-| `docs/AUTHZ_GUIDE.md` | New route classifications, policy changes |-| `docs/GUARDRAILS.md` | New guardrails registered, priority/order changes |-| `docs/COMPLIANCE.md` | Audit log / retention / no-log policy changes |-| `docs/SKILLS.md` | Skill framework / registry / built-in skill changes |-| `docs/MEMORY.md` | Memory pipeline / extraction / injection / Qdrant changes |-| `docs/EVALS.md` | Evaluation framework changes, new evaluators |-| `docs/WEBHOOKS.md` | New webhook events, payload schema changes |-| `docs/REASONING_REPLAY.md` | Reasoning capture/replay pipeline changes |-| `docs/AUTO-COMBO.md` | Routing changes, new strategies, scoring weight changes |-| `docs/RESILIENCE_GUIDE.md` | Circuit breaker / cooldown / lockout behavior changes |-| `docs/STEALTH_GUIDE.md` | TLS / CLI fingerprint changes |-| `docs/TUNNELS_GUIDE.md` | Cloudflare tunnel feature changes |-| `docs/ELECTRON_GUIDE.md` | Electron build / signing / packaging changes |-| `docs/TROUBLESHOOTING.md` | New known issues, resolved problems |-| `docs/RELEASE_CHECKLIST.md` | Process changes |-| `docs/COVERAGE_PLAN.md` | Coverage gate adjustments, target metrics |-| `docs/openapi.yaml` | Already updated in step 7 |+| File | When to update |+| --------------------------------------------- | ------------------------------------------------------------------ |+| `docs/reference/API_REFERENCE.md` | New API endpoints, changed request/response formats |+| `docs/architecture/ARCHITECTURE.md` | New modules, new services, changed data flow |+| `docs/architecture/CODEBASE_DOCUMENTATION.md` | New files, architectural changes, module reorganization |+| `docs/architecture/REPOSITORY_MAP.md` | New folders / files / one-line descriptions |+| `docs/reference/CLI-TOOLS.md` | New CLI tool integrations, config format changes |+| `docs/guides/USER_GUIDE.md` | UX changes, new dashboard pages, settings changes |+| `docs/reference/PROVIDER_REFERENCE.md` | New providers (regenerate via `scripts/gen-provider-reference.ts`) |+| `docs/frameworks/MCP-SERVER.md` | New MCP tools, changed tool signatures, scope changes |+| `docs/frameworks/A2A-SERVER.md` | New A2A skills, protocol changes |+| `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` | New external agent protocols supported |+| `docs/frameworks/CLOUD_AGENT.md` | Cloud agent additions (codex-cloud, devin, jules) or API changes |+| `docs/architecture/AUTHZ_GUIDE.md` | New route classifications, policy changes |+| `docs/security/GUARDRAILS.md` | New guardrails registered, priority/order changes |+| `docs/security/COMPLIANCE.md` | Audit log / retention / no-log policy changes |+| `docs/frameworks/SKILLS.md` | Skill framework / registry / built-in skill changes |+| `docs/frameworks/MEMORY.md` | Memory pipeline / extraction / injection / Qdrant changes |+| `docs/frameworks/EVALS.md` | Evaluation framework changes, new evaluators |+| `docs/frameworks/WEBHOOKS.md` | New webhook events, payload schema changes |+| `docs/routing/REASONING_REPLAY.md` | Reasoning capture/replay pipeline changes |+| `docs/routing/AUTO-COMBO.md` | Routing changes, new strategies, scoring weight changes |+| `docs/architecture/RESILIENCE_GUIDE.md` | Circuit breaker / cooldown / lockout behavior changes |+| `docs/security/STEALTH_GUIDE.md` | TLS / CLI fingerprint changes |+| `docs/ops/TUNNELS_GUIDE.md` | Cloudflare tunnel feature changes |+| `docs/guides/ELECTRON_GUIDE.md` | Electron build / signing / packaging changes |+| `docs/guides/TROUBLESHOOTING.md` | New known issues, resolved problems |+| `docs/ops/RELEASE_CHECKLIST.md` | Process changes |+| `docs/ops/COVERAGE_PLAN.md` | Coverage gate adjustments, target metrics |+| `docs/reference/openapi.yaml` | Already updated in step 7 |**Only update files where the CHANGELOG entries directly affect the documented content.** Do NOT update files just to bump a version number — only when the documented behavior, features, or architecture has actually changed.@@ -282,8 +282,8 @@ grep '"version"' open-sse/package.json | head -1echo "--- electron/package.json ---"[ -f electron/package.json ] && grep '"version"' electron/package.json | head -1-echo "--- docs/openapi.yaml ---"-grep " version:" docs/openapi.yaml | head -1+echo "--- docs/reference/openapi.yaml ---"+grep " version:" docs/reference/openapi.yaml | head -1echo "--- llm.txt ---"grep "Current version:" llm.txt@@ -331,11 +331,11 @@ git commit -m "chore(release): bump to v$VERSION — changelog, docs, version sy## Version Touchpoints Checklist-| File | Field/Pattern |-| ----------------------- | ----------------------------------------------------------- |-| `package.json` | `"version": "X.Y.Z"` |-| `open-sse/package.json` | `"version": "X.Y.Z"` |-| `electron/package.json` | `"version": "X.Y.Z"` |-| `docs/openapi.yaml` | `version: X.Y.Z` |-| `llm.txt` | `**Current version:** X.Y.Z` and `## Key Features (vX.Y.Z)` |-| `CHANGELOG.md` | `## [X.Y.Z] — YYYY-MM-DD` |+| File | Field/Pattern |+| ----------------------------- | ----------------------------------------------------------- |+| `package.json` | `"version": "X.Y.Z"` |+| `open-sse/package.json` | `"version": "X.Y.Z"` |+| `electron/package.json` | `"version": "X.Y.Z"` |+| `docs/reference/openapi.yaml` | `version: X.Y.Z` |+| `llm.txt` | `**Current version:** X.Y.Z` and `## Key Features (vX.Y.Z)` |+| `CHANGELOG.md` | `## [X.Y.Z] — YYYY-MM-DD` |diff --git a/.claude/commands/generate-release-cc.md b/.claude/commands/generate-release-cc.mdindex 5837f03a2f..7cb717c423 100644--- a/.claude/commands/generate-release-cc.md+++ b/.claude/commands/generate-release-cc.md@@ -124,13 +124,13 @@ Keep an empty `## [Unreleased]` section above it, separated by a horizontal rule### 5. Update openapi.yaml version ⚠️ MANDATORY-> **CI will fail** if `docs/openapi.yaml` version ≠ `package.json` version (`check:docs-sync` enforces this).+> **CI will fail** if `docs/reference/openapi.yaml` version ≠ `package.json` version (`check:docs-sync` enforces this).// turbo```bashVERSION=$(node -p "require('./package.json').version")-sed -i "s/ version: .*/ version: $VERSION/" docs/openapi.yaml+sed -i "s/ version: .*/ version: $VERSION/" docs/reference/openapi.yamlecho "✓ openapi.yaml → $VERSION"for dir in electron open-sse; do@@ -149,7 +149,7 @@ Manually perform these documentation updates (there is no `/update-docs` slash c- Update feature table rows and "What's new in vX.Y.Z" section in `README.md`- Sync feature changes to all 40 language `docs/i18n/*/README.md` files (use the same row edits across each translated README)-- Update the relevant `docs/<AREA>.md` if architecture or counts changed (e.g. `docs/MCP-SERVER.md` when MCP tools change)+- Update the relevant `docs/<AREA>.md` if architecture or counts changed (e.g. `docs/frameworks/MCP-SERVER.md` when MCP tools change)- Re-run `npm run check:docs-sync` and `npm run check:docs-all` to catch drift### 7. Run tests@@ -354,9 +354,9 @@ If a workflow fails:## Known CI Pitfalls-| CI failure | Cause | Fix |-| ------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- |-| `[docs-sync] FAIL - OpenAPI version differs from package.json` | Skipped step 5 — `docs/openapi.yaml` version not updated | Run step 5 (`sed -i ...`) and commit |-| `[docs-sync] FAIL - CHANGELOG.md first section must be "## [Unreleased]"` | `## [Unreleased]` missing or not at top of CHANGELOG | Add `## [Unreleased]\n\n---\n` before the first versioned `## [x.y.z]` |-| Electron Linux `.deb` build fails (`FpmTarget` error) | `fpm` Ruby gem not installed on `ubuntu-latest` runner | Already fixed in `electron-release.yml` (`gem install fpm` step) |-| Docker Hub `502 error writing layer blob` | Transient Docker Hub network error during ARM64 push | Re-run the Docker publish workflow; no code change needed |+| CI failure | Cause | Fix |+| ------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------- |+| `[docs-sync] FAIL - OpenAPI version differs from package.json` | Skipped step 5 — `docs/reference/openapi.yaml` version not updated | Run step 5 (`sed -i ...`) and commit |+| `[docs-sync] FAIL - CHANGELOG.md first section must be "## [Unreleased]"` | `## [Unreleased]` missing or not at top of CHANGELOG | Add `## [Unreleased]\n\n---\n` before the first versioned `## [x.y.z]` |+| Electron Linux `.deb` build fails (`FpmTarget` error) | `fpm` Ruby gem not installed on `ubuntu-latest` runner | Already fixed in `electron-release.yml` (`gem install fpm` step) |+| Docker Hub `502 error writing layer blob` | Transient Docker Hub network error during ARM64 push | Re-run the Docker publish workflow; no code change needed |diff --git a/.claude/commands/version-bump-cc.md b/.claude/commands/version-bump-cc.mdindex bef27c32c6..fbc63871ce 100644--- a/.claude/commands/version-bump-cc.md+++ b/.claude/commands/version-bump-cc.md@@ -136,9 +136,9 @@ The date must be today's date in `YYYY-MM-DD` format.cd /home/diegosouzapw/dev/proxys/OmniRouteVERSION=$(node -p "require('./package.json').version")-# Update docs/openapi.yaml version-sed -i "s/ version: .*/ version: $VERSION/" docs/openapi.yaml-echo "✓ docs/openapi.yaml → $VERSION"+# Update docs/reference/openapi.yaml version+sed -i "s/ version: .*/ version: $VERSION/" docs/reference/openapi.yaml+echo "✓ docs/reference/openapi.yaml → $VERSION"# Update workspace packages (open-sse, electron)for dir in electron open-sse; do@@ -208,36 +208,36 @@ For each file below, read the current content and determine if the CHANGELOG entFor each file in `docs/` (excluding `docs/i18n/`), review if CHANGELOG changes affect it:-| File | When to update |-| -------------------------------- | ------------------------------------------------------------------ |-| `docs/API_REFERENCE.md` | New API endpoints, changed request/response formats |-| `docs/ARCHITECTURE.md` | New modules, new services, changed data flow |-| `docs/CODEBASE_DOCUMENTATION.md` | New files, architectural changes, module reorganization |-| `docs/REPOSITORY_MAP.md` | New folders / files / one-line descriptions |-| `docs/CLI-TOOLS.md` | New CLI tool integrations, config format changes |-| `docs/USER_GUIDE.md` | UX changes, new dashboard pages, settings changes |-| `docs/PROVIDER_REFERENCE.md` | New providers (regenerate via `scripts/gen-provider-reference.ts`) |-| `docs/MCP-SERVER.md` | New MCP tools, changed tool signatures, scope changes |-| `docs/A2A-SERVER.md` | New A2A skills, protocol changes |-| `docs/AGENT_PROTOCOLS_GUIDE.md` | New external agent protocols supported |-| `docs/CLOUD_AGENT.md` | Cloud agent additions (codex-cloud, devin, jules) or API changes |-| `docs/AUTHZ_GUIDE.md` | New route classifications, policy changes |-| `docs/GUARDRAILS.md` | New guardrails registered, priority/order changes |-| `docs/COMPLIANCE.md` | Audit log / retention / no-log policy changes |-| `docs/SKILLS.md` | Skill framework / registry / built-in skill changes |-| `docs/MEMORY.md` | Memory pipeline / extraction / injection / Qdrant changes |-| `docs/EVALS.md` | Evaluation framework changes, new evaluators |-| `docs/WEBHOOKS.md` | New webhook events, payload schema changes |-| `docs/REASONING_REPLAY.md` | Reasoning capture/replay pipeline changes |-| `docs/AUTO-COMBO.md` | Routing changes, new strategies, scoring weight changes |-| `docs/RESILIENCE_GUIDE.md` | Circuit breaker / cooldown / lockout behavior changes |-| `docs/STEALTH_GUIDE.md` | TLS / CLI fingerprint changes |-| `docs/TUNNELS_GUIDE.md` | Cloudflare tunnel feature changes |-| `docs/ELECTRON_GUIDE.md` | Electron build / signing / packaging changes |-| `docs/TROUBLESHOOTING.md` | New known issues, resolved problems |-| `docs/RELEASE_CHECKLIST.md` | Process changes |-| `docs/COVERAGE_PLAN.md` | Coverage gate adjustments, target metrics |-| `docs/openapi.yaml` | Already updated in step 7 |+| File | When to update |+| --------------------------------------------- | ------------------------------------------------------------------ |+| `docs/reference/API_REFERENCE.md` | New API endpoints, changed request/response formats |+| `docs/architecture/ARCHITECTURE.md` | New modules, new services, changed data flow |+| `docs/architecture/CODEBASE_DOCUMENTATION.md` | New files, architectural changes, module reorganization |+| `docs/architecture/REPOSITORY_MAP.md` | New folders / files / one-line descriptions |+| `docs/reference/CLI-TOOLS.md` | New CLI tool integrations, config format changes |+| `docs/guides/USER_GUIDE.md` | UX changes, new dashboard pages, settings changes |+| `docs/reference/PROVIDER_REFERENCE.md` | New providers (regenerate via `scripts/gen-provider-reference.ts`) |+| `docs/frameworks/MCP-SERVER.md` | New MCP tools, changed tool signatures, scope changes |+| `docs/frameworks/A2A-SERVER.md` | New A2A skills, protocol changes |+| `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` | New external agent protocols supported |+| `docs/frameworks/CLOUD_AGENT.md` | Cloud agent additions (codex-cloud, devin, jules) or API changes |+| `docs/architecture/AUTHZ_GUIDE.md` | New route classifications, policy changes |+| `docs/security/GUARDRAILS.md` | New guardrails registered, priority/order changes |+| `docs/security/COMPLIANCE.md` | Audit log / retention / no-log policy changes |+| `docs/frameworks/SKILLS.md` | Skill framework / registry / built-in skill changes |+| `docs/frameworks/MEMORY.md` | Memory pipeline / extraction / injection / Qdrant changes |+| `docs/frameworks/EVALS.md` | Evaluation framework changes, new evaluators |+| `docs/frameworks/WEBHOOKS.md` | New webhook events, payload schema changes |+| `docs/routing/REASONING_REPLAY.md` | Reasoning capture/replay pipeline changes |+| `docs/routing/AUTO-COMBO.md` | Routing changes, new strategies, scoring weight changes |+| `docs/architecture/RESILIENCE_GUIDE.md` | Circuit breaker / cooldown / lockout behavior changes |+| `docs/security/STEALTH_GUIDE.md` | TLS / CLI fingerprint changes |+| `docs/ops/TUNNELS_GUIDE.md` | Cloudflare tunnel feature changes |+| `docs/guides/ELECTRON_GUIDE.md` | Electron build / signing / packaging changes |+| `docs/guides/TROUBLESHOOTING.md` | New known issues, resolved problems |+| `docs/ops/RELEASE_CHECKLIST.md` | Process changes |+| `docs/ops/COVERAGE_PLAN.md` | Coverage gate adjustments, target metrics |+| `docs/reference/openapi.yaml` | Already updated in step 7 |**Only update files where the CHANGELOG entries directly affect the documented content.** Do NOT update files just to bump a version number — only when the documented behavior, features, or architecture has actually changed.@@ -282,8 +282,8 @@ grep '"version"' open-sse/package.json | head -1echo "--- electron/package.json ---"[ -f electron/package.json ] && grep '"version"' electron/package.json | head -1-echo "--- docs/openapi.yaml ---"-grep " version:" docs/openapi.yaml | head -1+echo "--- docs/reference/openapi.yaml ---"+grep " version:" docs/reference/openapi.yaml | head -1echo "--- llm.txt ---"grep "Current version:" llm.txt@@ -331,11 +331,11 @@ git commit -m "chore(release): bump to v$VERSION — changelog, docs, version sy## Version Touchpoints Checklist-| File | Field/Pattern |-| ----------------------- | ----------------------------------------------------------- |-| `package.json` | `"version": "X.Y.Z"` |-| `open-sse/package.json` | `"version": "X.Y.Z"` |-| `electron/package.json` | `"version": "X.Y.Z"` |-| `docs/openapi.yaml` | `version: X.Y.Z` |-| `llm.txt` | `**Current version:** X.Y.Z` and `## Key Features (vX.Y.Z)` |-| `CHANGELOG.md` | `## [X.Y.Z] — YYYY-MM-DD` |+| File | Field/Pattern |+| ----------------------------- | ----------------------------------------------------------- |+| `package.json` | `"version": "X.Y.Z"` |+| `open-sse/package.json` | `"version": "X.Y.Z"` |+| `electron/package.json` | `"version": "X.Y.Z"` |+| `docs/reference/openapi.yaml` | `version: X.Y.Z` |+| `llm.txt` | `**Current version:** X.Y.Z` and `## Key Features (vX.Y.Z)` |+| `CHANGELOG.md` | `## [X.Y.Z] — YYYY-MM-DD` |diff --git a/AGENTS.md b/AGENTS.mdindex 5b429a8e1f..eb84cf6a1d 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -339,7 +339,7 @@ Policy engine modules: `policyEngine.ts`, `comboResolver.ts`, `costRules.ts`,### MCP Server (`open-sse/mcp-server/`)-37 tools (30 base + 3 memory + 4 skills), 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (~13 scopes), Zod schemas. See [`docs/MCP-SERVER.md`](docs/MCP-SERVER.md).+37 tools (30 base + 3 memory + 4 skills), 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (~13 scopes), Zod schemas. See [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md).**Core tools** (20): get_health, list_combos, get_combo_metrics, switch_combo, check_quota,route_request, cost_report, list_models_catalog, web_search, simulate_route, set_budget_guard,@@ -429,31 +429,31 @@ Request middleware including `promptInjectionGuard.ts`.### Guardrails (`src/lib/guardrails/`)-Hot-reloadable guardrails framework (3 built-in: pii-masker, prompt-injection, vision-bridge). Fail-open; per-request opt-out via header. See [`docs/GUARDRAILS.md`](docs/GUARDRAILS.md).+Hot-reloadable guardrails framework (3 built-in: pii-masker, prompt-injection, vision-bridge). Fail-open; per-request opt-out via header. See [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md).### Cloud Agents (`src/lib/cloudAgent/`)-`CloudAgentBase` abstract class + 3 agents (codex-cloud, devin, jules). Tasks persisted in `cloud_agent_tasks`; management auth required. See [`docs/CLOUD_AGENT.md`](docs/CLOUD_AGENT.md).+`CloudAgentBase` abstract class + 3 agents (codex-cloud, devin, jules). Tasks persisted in `cloud_agent_tasks`; management auth required. See [`docs/frameworks/CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md).### Evals (`src/lib/evals/`)-Generic eval framework: `evalRunner.ts`, `runtime.ts`. Targets: combo / model / suite-default. See [`docs/EVALS.md`](docs/EVALS.md).+Generic eval framework: `evalRunner.ts`, `runtime.ts`. Targets: combo / model / suite-default. See [`docs/frameworks/EVALS.md`](docs/frameworks/EVALS.md).### Webhooks (`src/lib/webhookDispatcher.ts`)-HMAC-signed delivery, exponential backoff, auto-disable after 10 failures. 7 event types. See [`docs/WEBHOOKS.md`](docs/WEBHOOKS.md).+HMAC-signed delivery, exponential backoff, auto-disable after 10 failures. 7 event types. See [`docs/frameworks/WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md).### Authorization Pipeline (`src/server/authz/`)-`classify → policies → enforce`. 3 route classes (PUBLIC / CLIENT_API / MANAGEMENT). See [`docs/AUTHZ_GUIDE.md`](docs/AUTHZ_GUIDE.md).+`classify → policies → enforce`. 3 route classes (PUBLIC / CLIENT_API / MANAGEMENT). See [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md).### Reasoning Replay (`src/lib/db/reasoningCache.ts` + `open-sse/services/reasoningCache.ts`)-Hybrid in-memory + SQLite cache for `reasoning_content`. Re-injects on multi-turn for strict providers (DeepSeek V4, Kimi K2, Qwen-Thinking, GLM, xiaomi-mimo). See [`docs/REASONING_REPLAY.md`](docs/REASONING_REPLAY.md).+Hybrid in-memory + SQLite cache for `reasoning_content`. Re-injects on multi-turn for strict providers (DeepSeek V4, Kimi K2, Qwen-Thinking, GLM, xiaomi-mimo). See [`docs/routing/REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md).### Tunnels (`src/lib/{cloudflaredTunnel,ngrokTunnel}.ts` + `src/app/api/tunnels/`)-Cloudflare Quick/Named, ngrok, Tailscale Funnel. See [`docs/TUNNELS_GUIDE.md`](docs/TUNNELS_GUIDE.md).+Cloudflare Quick/Named, ngrok, Tailscale Funnel. See [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md).### Adding a New Provider@@ -475,31 +475,31 @@ Cloudflare Quick/Named, ngrok, Tailscale Funnel. See [`docs/TUNNELS_GUIDE.md`](dFor any non-trivial change, read the matching deep-dive first:-| Area | Doc |-| ------------------------------------ | ------------------------------------------------------------------------------------------- |-| Repo navigation | [`docs/REPOSITORY_MAP.md`](docs/REPOSITORY_MAP.md) |-| Architecture | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) |-| Engineering reference | [`docs/CODEBASE_DOCUMENTATION.md`](docs/CODEBASE_DOCUMENTATION.md) |-| Auto-Combo (9-factor, 14 strategies) | [`docs/AUTO-COMBO.md`](docs/AUTO-COMBO.md) |-| Resilience (3 layers) | [`docs/RESILIENCE_GUIDE.md`](docs/RESILIENCE_GUIDE.md) |-| Skills | [`docs/SKILLS.md`](docs/SKILLS.md) |-| Memory | [`docs/MEMORY.md`](docs/MEMORY.md) |-| Cloud agents | [`docs/CLOUD_AGENT.md`](docs/CLOUD_AGENT.md) |-| Guardrails | [`docs/GUARDRAILS.md`](docs/GUARDRAILS.md) |-| Evals | [`docs/EVALS.md`](docs/EVALS.md) |-| Compliance | [`docs/COMPLIANCE.md`](docs/COMPLIANCE.md) |-| Webhooks | [`docs/WEBHOOKS.md`](docs/WEBHOOKS.md) |-| Authz | [`docs/AUTHZ_GUIDE.md`](docs/AUTHZ_GUIDE.md) |-| Stealth | [`docs/STEALTH_GUIDE.md`](docs/STEALTH_GUIDE.md) |-| Reasoning replay | [`docs/REASONING_REPLAY.md`](docs/REASONING_REPLAY.md) |-| Agent protocols (A2A / ACP / Cloud) | [`docs/AGENT_PROTOCOLS_GUIDE.md`](docs/AGENT_PROTOCOLS_GUIDE.md) |-| MCP server | [`docs/MCP-SERVER.md`](docs/MCP-SERVER.md) |-| A2A server | [`docs/A2A-SERVER.md`](docs/A2A-SERVER.md) |-| API reference | [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) + [`docs/openapi.yaml`](docs/openapi.yaml) |-| Provider catalog (auto-generated) | [`docs/PROVIDER_REFERENCE.md`](docs/PROVIDER_REFERENCE.md) |-| Tunnels | [`docs/TUNNELS_GUIDE.md`](docs/TUNNELS_GUIDE.md) |-| Electron desktop | [`docs/ELECTRON_GUIDE.md`](docs/ELECTRON_GUIDE.md) |-| Release flow | [`docs/RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md) |+| Area | Doc |+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |+| Repo navigation | [`docs/architecture/REPOSITORY_MAP.md`](docs/architecture/REPOSITORY_MAP.md) |+| Architecture | [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) |+| Engineering reference | [`docs/architecture/CODEBASE_DOCUMENTATION.md`](docs/architecture/CODEBASE_DOCUMENTATION.md) |+| Auto-Combo (9-factor, 14 strategies) | [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md) |+| Resilience (3 layers) | [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md) |+| Skills | [`docs/frameworks/SKILLS.md`](docs/frameworks/SKILLS.md) |+| Memory | [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md) |+| Cloud agents | [`docs/frameworks/CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md) |+| Guardrails | [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md) |+| Evals | [`docs/frameworks/EVALS.md`](docs/frameworks/EVALS.md) |+| Compliance | [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md) |+| Webhooks | [`docs/frameworks/WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md) |+| Authz | [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md) |+| Stealth | [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md) |+| Reasoning replay | [`docs/routing/REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md) |+| Agent protocols (A2A / ACP / Cloud) | [`docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) |+| MCP server | [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md) |+| A2A server | [`docs/frameworks/A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md) |+| API reference | [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md) + [`docs/reference/openapi.yaml`](docs/reference/openapi.yaml) |+| Provider catalog (auto-generated) | [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md) |+| Tunnels | [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md) |+| Electron desktop | [`docs/guides/ELECTRON_GUIDE.md`](docs/guides/ELECTRON_GUIDE.md) |+| Release flow | [`docs/ops/RELEASE_CHECKLIST.md`](docs/ops/RELEASE_CHECKLIST.md) |---diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6540496ffc..dacafafc3f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1374,7 +1374,7 @@ We identified that **155 community PRs** across the entire project history (from- **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)+- **Uninstall Guide:** Created comprehensive `docs/guides/UNINSTALL.md` covering clean uninstallation for all deployment methods (npm, Docker, Electron, source)### 🐛 Bug Fixesdiff --git a/CLAUDE.md b/CLAUDE.mdindex 3c96cb643f..7b8c337052 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -72,7 +72,7 @@ Client → /v1/chat/completions (Next.js route)API routes follow a consistent pattern: `Route → CORS preflight → Zod body validation → Optional auth (extractApiKey/isValidApiKey) → API key policy enforcement → Handler delegation (open-sse)`. No global Next.js middleware — interception is route-specific.-**Combo routing** (`open-sse/services/combo.ts`): 14 strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, reset-aware, strict-random, auto, lkgp, context-optimized, context-relay). Each target calls `handleSingleModel()` which wraps `handleChatCore()` with per-target error handling and circuit breaker checks. See `docs/AUTO-COMBO.md` for the 9-factor Auto-Combo scoring and `docs/RESILIENCE_GUIDE.md` for the 3 resilience layers.+**Combo routing** (`open-sse/services/combo.ts`): 14 strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, reset-aware, strict-random, auto, lkgp, context-optimized, context-relay). Each target calls `handleSingleModel()` which wraps `handleChatCore()` with per-target error handling and circuit breaker checks. See `docs/routing/AUTO-COMBO.md` for the 9-factor Auto-Combo scoring and `docs/architecture/RESILIENCE_GUIDE.md` for the 3 resilience layers.---@@ -285,7 +285,7 @@ connection continue serving other models.3. Register in `A2A_SKILL_HANDLERS` in `src/lib/a2a/taskExecution.ts`4. Expose in `src/app/.well-known/agent.json/route.ts` (Agent Card)5. Write tests in `tests/unit/`-6. Document in `docs/A2A-SERVER.md` skill table+6. Document in `docs/frameworks/A2A-SERVER.md` skill table### Adding a New Cloud Agent@@ -293,14 +293,14 @@ connection continue serving other models.2. Implement `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources`3. Register in `src/lib/cloudAgent/registry.ts`4. Add OAuth/credentials handling if needed (`src/lib/oauth/providers/`)-5. Tests + document in `docs/CLOUD_AGENT.md`+5. Tests + document in `docs/frameworks/CLOUD_AGENT.md`### Adding a New Guardrail / Eval / Skill / Webhook event-- Guardrail: `src/lib/guardrails/` → docs: `docs/GUARDRAILS.md`-- Eval suite: `src/lib/evals/` → docs: `docs/EVALS.md`-- Skill (sandbox): `src/lib/skills/` → docs: `docs/SKILLS.md`-- Webhook event: `src/lib/webhookDispatcher.ts` → docs: `docs/WEBHOOKS.md`+- Guardrail: `src/lib/guardrails/` → docs: `docs/security/GUARDRAILS.md`+- Eval suite: `src/lib/evals/` → docs: `docs/frameworks/EVALS.md`+- Skill (sandbox): `src/lib/skills/` → docs: `docs/frameworks/SKILLS.md`+- Webhook event: `src/lib/webhookDispatcher.ts` → docs: `docs/frameworks/WEBHOOKS.md`---@@ -308,29 +308,29 @@ connection continue serving other models.For any non-trivial change, read the matching deep-dive first:-| Area | Doc |-| -------------------------------------------- | --------------------------------------------- |-| Repo navigation | `docs/REPOSITORY_MAP.md` |-| Architecture | `docs/ARCHITECTURE.md` |-| Engineering reference | `docs/CODEBASE_DOCUMENTATION.md` |-| Auto-Combo (9-factor scoring, 14 strategies) | `docs/AUTO-COMBO.md` |-| Resilience (3 mechanisms) | `docs/RESILIENCE_GUIDE.md` |-| Reasoning replay | `docs/REASONING_REPLAY.md` |-| Skills framework | `docs/SKILLS.md` |-| Memory system (FTS5 + Qdrant) | `docs/MEMORY.md` |-| Cloud agents | `docs/CLOUD_AGENT.md` |-| Guardrails (PII / injection / vision) | `docs/GUARDRAILS.md` |-| Evals | `docs/EVALS.md` |-| Compliance / audit | `docs/COMPLIANCE.md` |-| Webhooks | `docs/WEBHOOKS.md` |-| Authorization pipeline | `docs/AUTHZ_GUIDE.md` |-| Stealth (TLS / fingerprint) | `docs/STEALTH_GUIDE.md` |-| Agent protocols (A2A / ACP / Cloud) | `docs/AGENT_PROTOCOLS_GUIDE.md` |-| MCP server | `docs/MCP-SERVER.md` |-| A2A server | `docs/A2A-SERVER.md` |-| API reference + OpenAPI | `docs/API_REFERENCE.md` + `docs/openapi.yaml` |-| Provider catalog (auto-generated) | `docs/PROVIDER_REFERENCE.md` |-| Release flow | `docs/RELEASE_CHECKLIST.md` |+| Area | Doc |+| -------------------------------------------- | ----------------------------------------------------------------- |+| Repo navigation | `docs/architecture/REPOSITORY_MAP.md` |+| Architecture | `docs/architecture/ARCHITECTURE.md` |+| Engineering reference | `docs/architecture/CODEBASE_DOCUMENTATION.md` |+| Auto-Combo (9-factor scoring, 14 strategies) | `docs/routing/AUTO-COMBO.md` |+| Resilience (3 mechanisms) | `docs/architecture/RESILIENCE_GUIDE.md` |+| Reasoning replay | `docs/routing/REASONING_REPLAY.md` |+| Skills framework | `docs/frameworks/SKILLS.md` |+| Memory system (FTS5 + Qdrant) | `docs/frameworks/MEMORY.md` |+| Cloud agents | `docs/frameworks/CLOUD_AGENT.md` |+| Guardrails (PII / injection / vision) | `docs/security/GUARDRAILS.md` |+| Evals | `docs/frameworks/EVALS.md` |+| Compliance / audit | `docs/security/COMPLIANCE.md` |+| Webhooks | `docs/frameworks/WEBHOOKS.md` |+| Authorization pipeline | `docs/architecture/AUTHZ_GUIDE.md` |+| Stealth (TLS / fingerprint) | `docs/security/STEALTH_GUIDE.md` |+| Agent protocols (A2A / ACP / Cloud) | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` |+| MCP server | `docs/frameworks/MCP-SERVER.md` |+| A2A server | `docs/frameworks/A2A-SERVER.md` |+| API reference + OpenAPI | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` |+| Provider catalog (auto-generated) | `docs/reference/PROVIDER_REFERENCE.md` |+| Release flow | `docs/ops/RELEASE_CHECKLIST.md` |---diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 1d40b49dc7..b81ddc496d 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -149,7 +149,7 @@ Coverage notes:- If a PR changes production code in `src/`, `open-sse/`, `electron/`, or `bin/`, it must add or update automated tests in the same PR- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run- `npm run test:coverage:legacy` preserves the older metric for historical comparison-- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap+- See `docs/ops/COVERAGE_PLAN.md` for the phased coverage improvement roadmap### Pull Request Requirements@@ -301,7 +301,7 @@ Releases are managed via the `/generate-release` workflow. When a new GitHub Rel## Getting Help-- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)-- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md)+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md)- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)- **ADRs**: See `docs/adr/` for architectural decision recordsdiff --git a/GEMINI.md b/GEMINI.mdindex c927102d37..895ee7bbd0 100644--- a/GEMINI.md+++ b/GEMINI.md@@ -31,14 +31,14 @@ When creating _any_ validation tests or one-off logic scripts, default to using## 3. Codebase navigation-| Task | Read this first |-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Understand the codebase | `docs/REPOSITORY_MAP.md` |-| Architecture overview | `docs/ARCHITECTURE.md` |-| Engineering reference | `docs/CODEBASE_DOCUMENTATION.md` |-| Add a feature | `CONTRIBUTING.md` + the matching `docs/<area>.md` |-| Per-area deep dives | `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/CLOUD_AGENT.md`, `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AUTHZ_GUIDE.md`, `docs/RESILIENCE_GUIDE.md`, `docs/AUTO-COMBO.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`, `docs/STEALTH_GUIDE.md`, `docs/TUNNELS_GUIDE.md`, `docs/ELECTRON_GUIDE.md`, `docs/PROVIDER_REFERENCE.md` |-| Release flow | `docs/RELEASE_CHECKLIST.md` |+| Task | Read this first |+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Understand the codebase | `docs/architecture/REPOSITORY_MAP.md` |+| Architecture overview | `docs/architecture/ARCHITECTURE.md` |+| Engineering reference | `docs/architecture/CODEBASE_DOCUMENTATION.md` |+| Add a feature | `CONTRIBUTING.md` + the matching `docs/<area>.md` |+| Per-area deep dives | `docs/frameworks/SKILLS.md`, `docs/frameworks/MEMORY.md`, `docs/frameworks/EVALS.md`, `docs/security/GUARDRAILS.md`, `docs/security/COMPLIANCE.md`, `docs/frameworks/CLOUD_AGENT.md`, `docs/frameworks/MCP-SERVER.md`, `docs/frameworks/A2A-SERVER.md`, `docs/architecture/AUTHZ_GUIDE.md`, `docs/architecture/RESILIENCE_GUIDE.md`, `docs/routing/AUTO-COMBO.md`, `docs/frameworks/WEBHOOKS.md`, `docs/routing/REASONING_REPLAY.md`, `docs/security/STEALTH_GUIDE.md`, `docs/ops/TUNNELS_GUIDE.md`, `docs/guides/ELECTRON_GUIDE.md`, `docs/reference/PROVIDER_REFERENCE.md` |+| Release flow | `docs/ops/RELEASE_CHECKLIST.md` |## 4. Local development accessdiff --git a/README.md b/README.mdindex 13853697cc..5ea1659691 100644--- a/README.md+++ b/README.md@@ -122,7 +122,7 @@ export OPENAI_BASE_URL=http://localhost:20128/v1export OPENAI_API_KEY=or_<your-omniroute-key>```-That's it. Cursor, Cline, Codex, Continue, Aider, and any SDK now work. → Detailed setup: [`docs/SETUP_GUIDE.md`](docs/SETUP_GUIDE.md)+That's it. Cursor, Cline, Codex, Continue, Aider, and any SDK now work. → Detailed setup: [`docs/guides/SETUP_GUIDE.md`](docs/guides/SETUP_GUIDE.md)---@@ -162,7 +162,7 @@ That's it. Cursor, Cline, Codex, Continue, Aider, and any SDK now work. → Deta| Self-hosted | ✅ MIT | Limited | ❌ (cloud) || Pricing | **$0 forever** | OSS / Cloud paid | 10% fee + API |-→ Detailed comparison: [`docs/FEATURES.md`](docs/FEATURES.md)+→ Detailed comparison: [`docs/guides/FEATURES.md`](docs/guides/FEATURES.md)---@@ -175,7 +175,7 @@ All work out-of-the-box once you point `OPENAI_BASE_URL` at OmniRoute:**Google family:** Gemini CLI · Antigravity · Jules**Others:** Windsurf · GitLab Duo · Devin CLI · Hermes · Amazon Q · Kiro · Qoder · Custom-→ Full setup: [`docs/CLI-TOOLS.md`](docs/CLI-TOOLS.md)+→ Full setup: [`docs/reference/CLI-TOOLS.md`](docs/reference/CLI-TOOLS.md)---@@ -196,7 +196,7 @@ All work out-of-the-box once you point `OPENAI_BASE_URL` at OmniRoute:⚠️ Qwen Code OAuth was **discontinued on 2026-04-15** (use API key with `alicode` provider instead).-→ Curated guide: [`docs/FREE_TIERS.md`](docs/FREE_TIERS.md) · Full catalog: [`docs/PROVIDER_REFERENCE.md`](docs/PROVIDER_REFERENCE.md) (auto-generated)+→ Curated guide: [`docs/reference/FREE_TIERS.md`](docs/reference/FREE_TIERS.md) · Full catalog: [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md) (auto-generated)### 🔐 OAuth providers (14)@@ -229,7 +229,7 @@ auto # → balanced default**How it picks:** 9-factor scoring (health · quota · cost · latency · taskFit · stability · tierPriority · tierAffinity · specificityMatch) over a virtual candidate pool built from all enabled providers.-→ Full guide: [`docs/AUTO-COMBO.md`](docs/AUTO-COMBO.md)+→ Full guide: [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md)---@@ -242,7 +242,7 @@ Two engines, stackable:**Modes:** `off` · `lite` · `standard` · `aggressive` · `ultra` · `rtk` · `stacked` (RTK→Caveman, max savings).-→ [`docs/COMPRESSION_GUIDE.md`](docs/COMPRESSION_GUIDE.md) · [`docs/RTK_COMPRESSION.md`](docs/RTK_COMPRESSION.md) · [`docs/COMPRESSION_LANGUAGE_PACKS.md`](docs/COMPRESSION_LANGUAGE_PACKS.md)+→ [`docs/compression/COMPRESSION_GUIDE.md`](docs/compression/COMPRESSION_GUIDE.md) · [`docs/compression/RTK_COMPRESSION.md`](docs/compression/RTK_COMPRESSION.md) · [`docs/compression/COMPRESSION_LANGUAGE_PACKS.md`](docs/compression/COMPRESSION_LANGUAGE_PACKS.md)---@@ -255,37 +255,37 @@ For users in **Russia, China, Iran, Cuba, Turkey** and other regions:- **Anti-detection** — TLS fingerprinting (JA3/JA4), CCH headshakes, header sanitization- **Public tunnels** — Cloudflare (Quick or Named), ngrok, Tailscale Funnel for OAuth callbacks-→ [`docs/PROXY_GUIDE.md`](docs/PROXY_GUIDE.md) · [`docs/TUNNELS_GUIDE.md`](docs/TUNNELS_GUIDE.md) · [`docs/STEALTH_GUIDE.md`](docs/STEALTH_GUIDE.md)+→ [`docs/ops/PROXY_GUIDE.md`](docs/ops/PROXY_GUIDE.md) · [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md) · [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md)---## 📱 Multi-Platform-| Platform | Install | Doc |-| --------------------------- | -------------------------------------------------------- | --------------------------------------------------------------- |-| **CLI / Server** | `npm install -g omniroute` | [`SETUP_GUIDE.md`](docs/SETUP_GUIDE.md) |-| **Desktop (Win/Mac/Linux)** | Electron installer from GitHub Releases | [`ELECTRON_GUIDE.md`](docs/ELECTRON_GUIDE.md) |-| **PWA** | Install from any modern browser | [`PWA_GUIDE.md`](docs/PWA_GUIDE.md) |-| **Android (Termux)** | `pkg install nodejs-lts && npm i -g omniroute` | [`TERMUX_GUIDE.md`](docs/TERMUX_GUIDE.md) |-| **Docker** | `docker compose up` (base/cli/host/cliproxyapi profiles) | [`DOCKER_GUIDE.md`](docs/DOCKER_GUIDE.md) |-| **VM / VPS** | Generic Ubuntu/Debian + nginx + systemd | [`VM_DEPLOYMENT_GUIDE.md`](docs/VM_DEPLOYMENT_GUIDE.md) |-| **Fly.io** | `fly deploy` | [`FLY_IO_DEPLOYMENT_GUIDE.md`](docs/FLY_IO_DEPLOYMENT_GUIDE.md) |+| Platform | Install | Doc |+| --------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------- |+| **CLI / Server** | `npm install -g omniroute` | [`SETUP_GUIDE.md`](docs/guides/SETUP_GUIDE.md) |+| **Desktop (Win/Mac/Linux)** | Electron installer from GitHub Releases | [`ELECTRON_GUIDE.md`](docs/guides/ELECTRON_GUIDE.md) |+| **PWA** | Install from any modern browser | [`PWA_GUIDE.md`](docs/guides/PWA_GUIDE.md) |+| **Android (Termux)** | `pkg install nodejs-lts && npm i -g omniroute` | [`TERMUX_GUIDE.md`](docs/guides/TERMUX_GUIDE.md) |+| **Docker** | `docker compose up` (base/cli/host/cliproxyapi profiles) | [`DOCKER_GUIDE.md`](docs/guides/DOCKER_GUIDE.md) |+| **VM / VPS** | Generic Ubuntu/Debian + nginx + systemd | [`VM_DEPLOYMENT_GUIDE.md`](docs/ops/VM_DEPLOYMENT_GUIDE.md) |+| **Fly.io** | `fly deploy` | [`FLY_IO_DEPLOYMENT_GUIDE.md`](docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) |---## 🧩 Extensibility-| System | What it does | Docs |-| ----------------------- | ----------------------------------------------------------------------- | -------------------------------------------- |-| 🧠 **Skills** | Built-in skills + marketplace + sandboxed custom skills (Docker) | [`docs/SKILLS.md`](docs/SKILLS.md) |-| 💾 **Memory** | Persistent conversational memory (SQLite FTS5 + Qdrant vector) | [`docs/MEMORY.md`](docs/MEMORY.md) |-| ☁️ **Cloud Agents** | Submit long tasks to Codex Cloud / Devin / Jules | [`docs/CLOUD_AGENT.md`](docs/CLOUD_AGENT.md) |-| 🪝 **Webhooks** | HMAC-signed event delivery (request.completed, quota.exceeded, etc.) | [`docs/WEBHOOKS.md`](docs/WEBHOOKS.md) |-| 🛡️ **Guardrails** | PII masker, prompt injection guard, vision bridge — hot-reload | [`docs/GUARDRAILS.md`](docs/GUARDRAILS.md) |-| 🧪 **Evals** | Suite-based regression testing (combos/models/cases/rubrics) | [`docs/EVALS.md`](docs/EVALS.md) |-| 🔍 **Compliance/Audit** | `audit_log` table, retention, `noLog` opt-out, SSRF logging | [`docs/COMPLIANCE.md`](docs/COMPLIANCE.md) |-| 🛡️ **MCP Server** | 37 tools, 3 transports (stdio/SSE/Streamable HTTP), ~13 scopes | [`docs/MCP-SERVER.md`](docs/MCP-SERVER.md) |-| 🤝 **A2A Protocol** | v0.3 JSON-RPC, 5 skills (smart-routing, quota, discovery, cost, health) | [`docs/A2A-SERVER.md`](docs/A2A-SERVER.md) |+| System | What it does | Docs |+| ----------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------ |+| 🧠 **Skills** | Built-in skills + marketplace + sandboxed custom skills (Docker) | [`docs/frameworks/SKILLS.md`](docs/frameworks/SKILLS.md) |+| 💾 **Memory** | Persistent conversational memory (SQLite FTS5 + Qdrant vector) | [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md) |+| ☁️ **Cloud Agents** | Submit long tasks to Codex Cloud / Devin / Jules | [`docs/frameworks/CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md) |+| 🪝 **Webhooks** | HMAC-signed event delivery (request.completed, quota.exceeded, etc.) | [`docs/frameworks/WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md) |+| 🛡️ **Guardrails** | PII masker, prompt injection guard, vision bridge — hot-reload | [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md) |+| 🧪 **Evals** | Suite-based regression testing (combos/models/cases/rubrics) | [`docs/frameworks/EVALS.md`](docs/frameworks/EVALS.md) |+| 🔍 **Compliance/Audit** | `audit_log` table, retention, `noLog` opt-out, SSRF logging | [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md) |+| 🛡️ **MCP Server** | 37 tools, 3 transports (stdio/SSE/Streamable HTTP), ~13 scopes | [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md) |+| 🤝 **A2A Protocol** | v0.3 JSON-RPC, 5 skills (smart-routing, quota, discovery, cost, health) | [`docs/frameworks/A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md) |---@@ -295,75 +295,75 @@ Everything you need, organized by area.### 🚀 Start here-- [`SETUP_GUIDE.md`](docs/SETUP_GUIDE.md) — install + connect first provider-- [`USER_GUIDE.md`](docs/USER_GUIDE.md) — end-user manual (modes, combos, CLIs, audio, ~1200 lines)-- [`FREE_TIERS.md`](docs/FREE_TIERS.md) — start free, no card-- [`TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) — common issues + v3.8 known issues+- [`SETUP_GUIDE.md`](docs/guides/SETUP_GUIDE.md) — install + connect first provider+- [`USER_GUIDE.md`](docs/guides/USER_GUIDE.md) — end-user manual (modes, combos, CLIs, audio, ~1200 lines)+- [`FREE_TIERS.md`](docs/reference/FREE_TIERS.md) — start free, no card+- [`TROUBLESHOOTING.md`](docs/guides/TROUBLESHOOTING.md) — common issues + v3.8 known issues### 🏛️ Architecture-- [`ARCHITECTURE.md`](docs/ARCHITECTURE.md) — high-level architecture-- [`CODEBASE_DOCUMENTATION.md`](docs/CODEBASE_DOCUMENTATION.md) — engineering reference-- [`REPOSITORY_MAP.md`](docs/REPOSITORY_MAP.md) — every directory and root file-- [`FEATURES.md`](docs/FEATURES.md) — full feature matrix+- [`ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) — high-level architecture+- [`CODEBASE_DOCUMENTATION.md`](docs/architecture/CODEBASE_DOCUMENTATION.md) — engineering reference+- [`REPOSITORY_MAP.md`](docs/architecture/REPOSITORY_MAP.md) — every directory and root file+- [`FEATURES.md`](docs/guides/FEATURES.md) — full feature matrix### 🔌 API & contracts-- [`API_REFERENCE.md`](docs/API_REFERENCE.md) — endpoint reference-- [`openapi.yaml`](docs/openapi.yaml) — OpenAPI 3.0 spec-- [`PROVIDER_REFERENCE.md`](docs/PROVIDER_REFERENCE.md) — full catalog (auto-generated)-- [`CLI-TOOLS.md`](docs/CLI-TOOLS.md) — CLI integrations + internal CLI-- [`ENVIRONMENT.md`](docs/ENVIRONMENT.md) — all env vars+- [`API_REFERENCE.md`](docs/reference/API_REFERENCE.md) — endpoint reference+- [`openapi.yaml`](docs/reference/openapi.yaml) — OpenAPI 3.0 spec+- [`PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md) — full catalog (auto-generated)+- [`CLI-TOOLS.md`](docs/reference/CLI-TOOLS.md) — CLI integrations + internal CLI+- [`ENVIRONMENT.md`](docs/reference/ENVIRONMENT.md) — all env vars### 🎯 Routing & resilience-- [`AUTO-COMBO.md`](docs/AUTO-COMBO.md) — Auto-Combo (9-factor scoring, 14 strategies)-- [`RESILIENCE_GUIDE.md`](docs/RESILIENCE_GUIDE.md) — circuit breaker + cooldown + lockout-- [`REASONING_REPLAY.md`](docs/REASONING_REPLAY.md) — reasoning cache for DeepSeek/Kimi/Qwen-- [`STEALTH_GUIDE.md`](docs/STEALTH_GUIDE.md) — TLS fingerprinting + obfuscation+- [`AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md) — Auto-Combo (9-factor scoring, 14 strategies)+- [`RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md) — circuit breaker + cooldown + lockout+- [`REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md) — reasoning cache for DeepSeek/Kimi/Qwen+- [`STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md) — TLS fingerprinting + obfuscation### 🤖 Agent protocols-- [`AGENT_PROTOCOLS_GUIDE.md`](docs/AGENT_PROTOCOLS_GUIDE.md) — A2A vs ACP vs Cloud Agents-- [`MCP-SERVER.md`](docs/MCP-SERVER.md) — Model Context Protocol server-- [`A2A-SERVER.md`](docs/A2A-SERVER.md) — Agent-to-Agent protocol-- [`CLOUD_AGENT.md`](docs/CLOUD_AGENT.md) — Codex Cloud / Devin / Jules+- [`AGENT_PROTOCOLS_GUIDE.md`](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) — A2A vs ACP vs Cloud Agents+- [`MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md) — Model Context Protocol server+- [`A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md) — Agent-to-Agent protocol+- [`CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md) — Codex Cloud / Devin / Jules### 🧠 Extensions-- [`SKILLS.md`](docs/SKILLS.md) — Skills framework-- [`MEMORY.md`](docs/MEMORY.md) — Memory system-- [`EVALS.md`](docs/EVALS.md) — Eval framework-- [`GUARDRAILS.md`](docs/GUARDRAILS.md) — PII / injection / vision-- [`WEBHOOKS.md`](docs/WEBHOOKS.md) — Webhook delivery-- [`COMPLIANCE.md`](docs/COMPLIANCE.md) — Audit + retention-- [`AUTHZ_GUIDE.md`](docs/AUTHZ_GUIDE.md) — Authorization pipeline+- [`SKILLS.md`](docs/frameworks/SKILLS.md) — Skills framework+- [`MEMORY.md`](docs/frameworks/MEMORY.md) — Memory system+- [`EVALS.md`](docs/frameworks/EVALS.md) — Eval framework+- [`GUARDRAILS.md`](docs/security/GUARDRAILS.md) — PII / injection / vision+- [`WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md) — Webhook delivery+- [`COMPLIANCE.md`](docs/security/COMPLIANCE.md) — Audit + retention+- [`AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md) — Authorization pipeline### 🗜️ Compression-- [`COMPRESSION_GUIDE.md`](docs/COMPRESSION_GUIDE.md)-- [`COMPRESSION_ENGINES.md`](docs/COMPRESSION_ENGINES.md)-- [`COMPRESSION_RULES_FORMAT.md`](docs/COMPRESSION_RULES_FORMAT.md)-- [`COMPRESSION_LANGUAGE_PACKS.md`](docs/COMPRESSION_LANGUAGE_PACKS.md)-- [`RTK_COMPRESSION.md`](docs/RTK_COMPRESSION.md)+- [`COMPRESSION_GUIDE.md`](docs/compression/COMPRESSION_GUIDE.md)+- [`COMPRESSION_ENGINES.md`](docs/compression/COMPRESSION_ENGINES.md)+- [`COMPRESSION_RULES_FORMAT.md`](docs/compression/COMPRESSION_RULES_FORMAT.md)+- [`COMPRESSION_LANGUAGE_PACKS.md`](docs/compression/COMPRESSION_LANGUAGE_PACKS.md)+- [`RTK_COMPRESSION.md`](docs/compression/RTK_COMPRESSION.md)### 🚀 Deployment-- [`DOCKER_GUIDE.md`](docs/DOCKER_GUIDE.md)-- [`VM_DEPLOYMENT_GUIDE.md`](docs/VM_DEPLOYMENT_GUIDE.md)-- [`FLY_IO_DEPLOYMENT_GUIDE.md`](docs/FLY_IO_DEPLOYMENT_GUIDE.md)-- [`ELECTRON_GUIDE.md`](docs/ELECTRON_GUIDE.md)-- [`PWA_GUIDE.md`](docs/PWA_GUIDE.md)-- [`TERMUX_GUIDE.md`](docs/TERMUX_GUIDE.md)-- [`TUNNELS_GUIDE.md`](docs/TUNNELS_GUIDE.md)-- [`PROXY_GUIDE.md`](docs/PROXY_GUIDE.md)+- [`DOCKER_GUIDE.md`](docs/guides/DOCKER_GUIDE.md)+- [`VM_DEPLOYMENT_GUIDE.md`](docs/ops/VM_DEPLOYMENT_GUIDE.md)+- [`FLY_IO_DEPLOYMENT_GUIDE.md`](docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md)+- [`ELECTRON_GUIDE.md`](docs/guides/ELECTRON_GUIDE.md)+- [`PWA_GUIDE.md`](docs/guides/PWA_GUIDE.md)+- [`TERMUX_GUIDE.md`](docs/guides/TERMUX_GUIDE.md)+- [`TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md)+- [`PROXY_GUIDE.md`](docs/ops/PROXY_GUIDE.md)### 📋 Operations-- [`RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md) — release flow with Claude Code skills-- [`COVERAGE_PLAN.md`](docs/COVERAGE_PLAN.md) — test coverage state (current: 82.58%/82.58%/84.23%/75.22%)-- [`I18N.md`](docs/I18N.md) — 30 supported locales-- [`UNINSTALL.md`](docs/UNINSTALL.md)+- [`RELEASE_CHECKLIST.md`](docs/ops/RELEASE_CHECKLIST.md) — release flow with Claude Code skills+- [`COVERAGE_PLAN.md`](docs/ops/COVERAGE_PLAN.md) — test coverage state (current: 82.58%/82.58%/84.23%/75.22%)+- [`I18N.md`](docs/guides/I18N.md) — 30 supported locales+- [`UNINSTALL.md`](docs/guides/UNINSTALL.md)### 🤝 Contributing & policy@@ -388,7 +388,7 @@ Everything you need, organized by area.| "Multi-agent system" | Expose OmniRoute as A2A node, route via `smart-routing` skill || "Long-running coding task" | Cloud Agents → Devin/Jules with management auth |-→ Detailed playbooks: [`USER_GUIDE.md`](docs/USER_GUIDE.md) · [`AUTO-COMBO.md`](docs/AUTO-COMBO.md)+→ Detailed playbooks: [`USER_GUIDE.md`](docs/guides/USER_GUIDE.md) · [`AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md)---@@ -425,7 +425,7 @@ Client → /v1/chat/completions → [CORS → Zod → Auth → Authz → Guardra- **`src/domain/`** — Pure business logic (policies, fallback, cost rules)- **`src/server/`** — Server-only (authz pipeline, cors)-→ Deep dive: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) · [`docs/CODEBASE_DOCUMENTATION.md`](docs/CODEBASE_DOCUMENTATION.md)+→ Deep dive: [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) · [`docs/architecture/CODEBASE_DOCUMENTATION.md`](docs/architecture/CODEBASE_DOCUMENTATION.md)---@@ -435,7 +435,7 @@ UI translated to **30 languages** with full RTL support for Arabic and Hebrew.🌐 [English](README.md) · [Português](docs/i18n/pt-BR/README.md) · [Español](docs/i18n/es/README.md) · [Français](docs/i18n/fr/README.md) · [Deutsch](docs/i18n/de/README.md) · [中文](docs/i18n/zh-CN/README.md) · [日本語](docs/i18n/ja/README.md) · [한국어](docs/i18n/ko/README.md) · [العربية](docs/i18n/ar/README.md) · [हिन्दी](docs/i18n/hi/README.md) · [Русский](docs/i18n/ru/README.md) · [+ 19 more](docs/i18n/)-→ Adding a language: [`docs/I18N.md`](docs/I18N.md)+→ Adding a language: [`docs/guides/I18N.md`](docs/guides/I18N.md)---@@ -459,9 +459,9 @@ We welcome PRs! Start with:3. Branch from `main` (`feat/*`, `fix/*`, `docs/*`, `refactor/*`, `test/*`, `chore/*`)4. Hooks will run lint + test on commit/push-**Adding a provider?** [`docs/ARCHITECTURE.md § Adding a New Provider`](docs/ARCHITECTURE.md)-**Adding an MCP tool?** [`docs/MCP-SERVER.md`](docs/MCP-SERVER.md)-**Adding an A2A skill?** [`docs/A2A-SERVER.md § Adding a New Skill`](docs/A2A-SERVER.md)+**Adding a provider?** [`docs/architecture/ARCHITECTURE.md § Adding a New Provider`](docs/architecture/ARCHITECTURE.md)+**Adding an MCP tool?** [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md)+**Adding an A2A skill?** [`docs/frameworks/A2A-SERVER.md § Adding a New Skill`](docs/frameworks/A2A-SERVER.md)---@@ -471,7 +471,7 @@ We welcome PRs! Start with:- **Supported versions:** 3.8.x (Active), 3.7.x (Security only)- **Secrets:** never commit. Use `.env` (auto-generated from `.env.example` on first install) or vaults- **Encryption:** credentials at rest with AES-256-GCM-- **Authz:** route-aware classification (`src/server/authz/`) — see [`docs/AUTHZ_GUIDE.md`](docs/AUTHZ_GUIDE.md)+- **Authz:** route-aware classification (`src/server/authz/`) — see [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md)- **Guardrails:** PII masking, prompt injection detection — hot-reloadable---diff --git a/SECURITY.md b/SECURITY.mdindex 0f3f8a57f6..72c81017d4 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -45,8 +45,8 @@ Request → CORS → Authz pipeline (classify → policies → enforce)| **OAuth 2.0 + PKCE** | 14 providers (Claude, Codex, GitHub, Cursor, Antigravity, Gemini, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Windsurf, GitLab Duo) || **Token Refresh** | Automatic OAuth token refresh before expiry || **Secure Cookies** | `AUTH_COOKIE_SECURE=true` for HTTPS environments |-| **Authz Pipeline** | Route classification (PUBLIC / CLIENT_API / MANAGEMENT) — see `docs/AUTHZ_GUIDE.md` |-| **MCP Scopes** | ~13 granular scopes (read:health, write:combos, execute:completions, etc.) — see `docs/MCP-SERVER.md` |+| **Authz Pipeline** | Route classification (PUBLIC / CLIENT_API / MANAGEMENT) — see `docs/architecture/AUTHZ_GUIDE.md` |+| **MCP Scopes** | ~13 granular scopes (read:health, write:combos, execute:completions, etc.) — see `docs/frameworks/MCP-SERVER.md` |### 🛡️ Encryption at Rest@@ -71,7 +71,7 @@ OmniRoute ships a hot-reloadable **guardrails registry** (`src/lib/guardrails/`)| `pii-masker` | 10 | Pre+post call PII redaction (emails, phone, CPF, CNPJ, credit cards, SSN) || `prompt-injection` | 20 | Detects override/role-hijack/jailbreak/leak patterns |-Custom guardrails register via `registerGuardrail(new MyGuardrail())`. The model is fail-open (exceptions never block traffic). Per-request opt-out via `x-omniroute-disabled-guardrails` header. → See [`docs/GUARDRAILS.md`](docs/GUARDRAILS.md).+Custom guardrails register via `registerGuardrail(new MyGuardrail())`. The model is fail-open (exceptions never block traffic). Per-request opt-out via `x-omniroute-disabled-guardrails` header. → See [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md).### 🧠 Prompt Injection Guard@@ -204,9 +204,9 @@ These rules are enforced by tooling and reviewers:## References-- [`docs/AUTHZ_GUIDE.md`](docs/AUTHZ_GUIDE.md) — authorization pipeline-- [`docs/GUARDRAILS.md`](docs/GUARDRAILS.md) — guardrails framework-- [`docs/COMPLIANCE.md`](docs/COMPLIANCE.md) — audit log and retention-- [`docs/RESILIENCE_GUIDE.md`](docs/RESILIENCE_GUIDE.md) — circuit breaker + cooldown + lockout-- [`docs/STEALTH_GUIDE.md`](docs/STEALTH_GUIDE.md) — TLS fingerprinting (legal/ethical notice)+- [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md) — authorization pipeline+- [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md) — guardrails framework+- [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md) — audit log and retention+- [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md) — circuit breaker + cooldown + lockout+- [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md) — TLS fingerprinting (legal/ethical notice)- [`CLAUDE.md`](CLAUDE.md) — hard rules for AI agentsdiff --git a/Tuto_Qdrant.md b/Tuto_Qdrant.mdindex fb9491db65..3abe4a4313 100644--- a/Tuto_Qdrant.md+++ b/Tuto_Qdrant.md@@ -2,11 +2,11 @@> ⚠️ **Status (v3.8.0):** Integração Qdrant está **dormente** no pipeline. As funções de upsert/search/delete existem em `src/lib/memory/qdrant.ts` e a UI de configuração está pronta (`MemorySkillsTab.tsx` + endpoint `/api/settings/qdrant/embedding-models`), mas:>-> - `upsertSemanticMemoryPoint`, `searchSemanticMemory` e `deleteSemanticMemoryPoint` **não são chamadas** pelo pipeline de chat — busca semântica corrente usa apenas o store local em SQLite (ver `docs/MEMORY.md`).+> - `upsertSemanticMemoryPoint`, `searchSemanticMemory` e `deleteSemanticMemoryPoint` **não são chamadas** pelo pipeline de chat — busca semântica corrente usa apenas o store local em SQLite (ver `docs/frameworks/MEMORY.md`).> - As rotas `/api/settings/qdrant/health`, `/api/settings/qdrant/search` e `/api/settings/qdrant/cleanup` mencionadas neste tutorial **ainda não foram implementadas**.> - Os botões "Testar conexão" e "Teste de busca" no painel exigem que essas rotas existam; até lá, são placeholders.>-> Este documento descreve a UX/configuração planejada. Para o sistema de memória ativo hoje, consulte [`docs/MEMORY.md`](docs/MEMORY.md). Acompanhe o status da ativação em issues marcadas com `area:qdrant`.+> Este documento descreve a UX/configuração planejada. Para o sistema de memória ativo hoje, consulte [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md). Acompanhe o status da ativação em issues marcadas com `area:qdrant`.## 1) O que é o Qdrant no OmniRoute@@ -163,7 +163,7 @@ Mensagem final para a galera:- Wire-up no fluxo de chat: `src/lib/memory/retrieval.ts` e `open-sse/handlers/chatCore.ts` precisam chamar `searchSemanticMemory` quando Qdrant estiver habilitado nas settings- Wire-up no save de memória: `src/lib/memory/extraction.ts` (ou camada equivalente) precisa chamar `upsertSemanticMemoryPoint` após persistir cada memória-Para o sistema de memória ativo hoje (SQLite-only), ver [`docs/MEMORY.md`](docs/MEMORY.md).+Para o sistema de memória ativo hoje (SQLite-only), ver [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md).---diff --git a/llm.txt b/llm.txtindex 4425d70668..0ef2a37fd0 100644--- a/llm.txt+++ b/llm.txt@@ -353,11 +353,11 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo### MCP Server (37 Tools)| Category | Tools ||------------|-------|-| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/frameworks/MCP-SERVER.md` for full inventory) || Memory (3) | `memory_search`, `memory_add`, `memory_clear` || Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |-**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/frameworks/MCP-SERVER.md`.### Provider Categories@@ -468,7 +468,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.-21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/architecture/AUTHZ_GUIDE.md`.22. **Three resilience layers** are distinct (do not conflate them):- **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.@@ -485,11 +485,11 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%-- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams+- **Reasoning replay** (`docs/routing/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams- **Compliance + Evals + Webhooks** documentation introduced-- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration-- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management-- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing+- **Stealth guide** (`docs/security/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration+- **Tunnels guide** (`docs/ops/TUNNELS_GUIDE.md`) — Cloudflare tunnel management+- **Electron guide** (`docs/guides/ELECTRON_GUIDE.md`) — desktop app build + signing## Links@@ -501,11 +501,11 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo### Documentation Index-- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`-- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`-- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`-- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`-- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`-- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`-- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`+- **Architecture & Reference**: `docs/architecture/ARCHITECTURE.md`, `docs/architecture/CODEBASE_DOCUMENTATION.md`, `docs/architecture/REPOSITORY_MAP.md`, `docs/reference/API_REFERENCE.md`, `docs/reference/PROVIDER_REFERENCE.md`, `docs/reference/openapi.yaml`+- **Operator guides**: `docs/guides/USER_GUIDE.md`, `docs/reference/CLI-TOOLS.md`, `docs/guides/TROUBLESHOOTING.md`, `docs/ops/COVERAGE_PLAN.md`+- **Protocols**: `docs/frameworks/MCP-SERVER.md`, `docs/frameworks/A2A-SERVER.md`, `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`, `docs/frameworks/CLOUD_AGENT.md`+- **Routing & resilience**: `docs/routing/AUTO-COMBO.md`, `docs/architecture/RESILIENCE_GUIDE.md`+- **Security**: `docs/architecture/AUTHZ_GUIDE.md`, `docs/security/GUARDRAILS.md`, `docs/security/COMPLIANCE.md`, `docs/security/STEALTH_GUIDE.md`+- **Extensibility**: `docs/frameworks/SKILLS.md`, `docs/frameworks/MEMORY.md`, `docs/frameworks/EVALS.md`, `docs/frameworks/WEBHOOKS.md`, `docs/routing/REASONING_REPLAY.md`+- **Platform**: `docs/guides/ELECTRON_GUIDE.md`, `docs/ops/TUNNELS_GUIDE.md`- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`