diff --git a/.agents/skills/generate-release/SKILL.md b/.agents/skills/generate-release/SKILL.md
index 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
```bash
VERSION=$(node -p "require('./package.json').version")
-sed -i "s/ version: .*/ version: $VERSION/" docs/openapi.yaml
+sed -i "s/ version: .*/ version: $VERSION/" docs/reference/openapi.yaml
echo "✓ 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.md
index 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/OmniRoute
VERSION=$(node -p "require('./package.json').version")
-# Update docs/openapi.yaml version
-sed -i "s/ version: .*/ version: $VERSION/" docs/openapi.yaml
-echo "✓ docs/openapi.yaml → $VERSION"
+# Update 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 ent
For each file in `docs/` (excluding `docs/i18n/`), review if CHANGELOG changes affect it:
-| File | When to update |
-| -------------------------------- | ------------------------------------------------------------------ |
-| `docs/API_REFERENCE.md` | New API endpoints, changed request/response formats |
-| `docs/ARCHITECTURE.md` | New modules, new services, changed data flow |
-| `docs/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 -1
echo "--- electron/package.json ---"
[ -f electron/package.json ] && grep '"version"' electron/package.json | head -1
-echo "--- docs/openapi.yaml ---"
-grep " version:" docs/openapi.yaml | head -1
+echo "--- docs/reference/openapi.yaml ---"
+grep " version:" docs/reference/openapi.yaml | head -1
echo "--- 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.md
index 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
```bash
VERSION=$(node -p "require('./package.json').version")
-sed -i "s/ version: .*/ version: $VERSION/" docs/openapi.yaml
+sed -i "s/ version: .*/ version: $VERSION/" docs/reference/openapi.yaml
echo "✓ 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.md
index 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/OmniRoute
VERSION=$(node -p "require('./package.json').version")
-# Update docs/openapi.yaml version
-sed -i "s/ version: .*/ version: $VERSION/" docs/openapi.yaml
-echo "✓ docs/openapi.yaml → $VERSION"
+# Update 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 ent
For each file in `docs/` (excluding `docs/i18n/`), review if CHANGELOG changes affect it:
-| File | When to update |
-| -------------------------------- | ------------------------------------------------------------------ |
-| `docs/API_REFERENCE.md` | New API endpoints, changed request/response formats |
-| `docs/ARCHITECTURE.md` | New modules, new services, changed data flow |
-| `docs/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 -1
echo "--- electron/package.json ---"
[ -f electron/package.json ] && grep '"version"' electron/package.json | head -1
-echo "--- docs/openapi.yaml ---"
-grep " version:" docs/openapi.yaml | head -1
+echo "--- docs/reference/openapi.yaml ---"
+grep " version:" docs/reference/openapi.yaml | head -1
echo "--- 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.md
index 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
```bash
VERSION=$(node -p "require('./package.json').version")
-sed -i "s/ version: .*/ version: $VERSION/" docs/openapi.yaml
+sed -i "s/ version: .*/ version: $VERSION/" docs/reference/openapi.yaml
echo "✓ 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/.md` if architecture or counts changed (e.g. `docs/MCP-SERVER.md` when MCP tools change)
+- Update the relevant `docs/.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.md
index 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/OmniRoute
VERSION=$(node -p "require('./package.json').version")
-# Update docs/openapi.yaml version
-sed -i "s/ version: .*/ version: $VERSION/" docs/openapi.yaml
-echo "✓ docs/openapi.yaml → $VERSION"
+# Update 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 ent
For each file in `docs/` (excluding `docs/i18n/`), review if CHANGELOG changes affect it:
-| File | When to update |
-| -------------------------------- | ------------------------------------------------------------------ |
-| `docs/API_REFERENCE.md` | New API endpoints, changed request/response formats |
-| `docs/ARCHITECTURE.md` | New modules, new services, changed data flow |
-| `docs/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 -1
echo "--- electron/package.json ---"
[ -f electron/package.json ] && grep '"version"' electron/package.json | head -1
-echo "--- docs/openapi.yaml ---"
-grep " version:" docs/openapi.yaml | head -1
+echo "--- docs/reference/openapi.yaml ---"
+grep " version:" docs/reference/openapi.yaml | head -1
echo "--- 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.md
index 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`](d
For 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.md
index 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 Fixes
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.md
index 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 records
diff --git a/GEMINI.md b/GEMINI.md
index 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/.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/.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 access
diff --git a/README.md b/README.md
index 13853697cc..5ea1659691 100644
--- a/README.md
+++ b/README.md
@@ -122,7 +122,7 @@ export OPENAI_BASE_URL=http://localhost:20128/v1
export OPENAI_API_KEY=or_
```
-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.md
index 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 agents
diff --git a/Tuto_Qdrant.md b/Tuto_Qdrant.md
index 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.txt
index 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, quo
20. **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`