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 24f3401c4d..64525f17e2 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/audit-report.json b/audit-report.json
deleted file mode 100644
index 0d8c271630..0000000000
--- a/audit-report.json
+++ /dev/null
@@ -1,48 +0,0 @@
-{
- "auditReportVersion": 2,
- "vulnerabilities": {
- "follow-redirects": {
- "name": "follow-redirects",
- "severity": "moderate",
- "isDirect": false,
- "via": [
- {
- "source": 1116560,
- "name": "follow-redirects",
- "dependency": "follow-redirects",
- "title": "follow-redirects leaks Custom Authentication Headers to Cross-Domain Redirect Targets",
- "url": "https://github.com/advisories/GHSA-r4q5-vmmm-2653",
- "severity": "moderate",
- "cwe": ["CWE-200"],
- "cvss": {
- "score": 0,
- "vectorString": null
- },
- "range": "<=1.15.11"
- }
- ],
- "effects": [],
- "range": "<=1.15.11",
- "nodes": ["node_modules/follow-redirects"],
- "fixAvailable": true
- }
- },
- "metadata": {
- "vulnerabilities": {
- "info": 0,
- "low": 0,
- "moderate": 1,
- "high": 0,
- "critical": 0,
- "total": 1
- },
- "dependencies": {
- "prod": 421,
- "dev": 480,
- "optional": 158,
- "peer": 480,
- "peerOptional": 0,
- "total": 1462
- }
- }
-}
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000000..9ad7f89490
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,111 @@
+# OmniRoute Documentation
+
+Navigable index of the OmniRoute documentation set. Topics are grouped by intent so you can find what you need quickly.
+
+> Looking for the project overview, install steps, or release notes? See the root [README.md](../README.md), [CHANGELOG.md](../CHANGELOG.md), and [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+---
+
+## architecture/
+
+How the system is put together — read these to understand the runtime, code layout, and resilience model.
+
+- [ARCHITECTURE.md](architecture/ARCHITECTURE.md) — high-level system architecture (request pipeline, layers, modules).
+- [CODEBASE_DOCUMENTATION.md](architecture/CODEBASE_DOCUMENTATION.md) — engineering reference for the codebase.
+- [REPOSITORY_MAP.md](architecture/REPOSITORY_MAP.md) — directory-by-directory navigation guide.
+- [AUTHZ_GUIDE.md](architecture/AUTHZ_GUIDE.md) — authorization pipeline (route classifier + policy engine).
+- [RESILIENCE_GUIDE.md](architecture/RESILIENCE_GUIDE.md) — provider circuit breaker, connection cooldown, and model lockout.
+
+## guides/
+
+Task-focused walkthroughs for operators and end users.
+
+- [SETUP_GUIDE.md](guides/SETUP_GUIDE.md) — first-time setup of OmniRoute.
+- [USER_GUIDE.md](guides/USER_GUIDE.md) — daily usage of the dashboard and API.
+- [DOCKER_GUIDE.md](guides/DOCKER_GUIDE.md) — running OmniRoute under Docker.
+- [ELECTRON_GUIDE.md](guides/ELECTRON_GUIDE.md) — desktop (Electron) builds.
+- [TERMUX_GUIDE.md](guides/TERMUX_GUIDE.md) — running on Android via Termux.
+- [PWA_GUIDE.md](guides/PWA_GUIDE.md) — installing the dashboard as a PWA.
+- [TROUBLESHOOTING.md](guides/TROUBLESHOOTING.md) — common issues and fixes.
+- [UNINSTALL.md](guides/UNINSTALL.md) — clean removal steps.
+- [I18N.md](guides/I18N.md) — translation and locale workflow.
+- [FEATURES.md](guides/FEATURES.md) — dashboard feature gallery.
+
+## reference/
+
+Lookup material — API surface, environment variables, CLI flags, provider catalog.
+
+- [API_REFERENCE.md](reference/API_REFERENCE.md) — REST API endpoints and shapes.
+- [PROVIDER_REFERENCE.md](reference/PROVIDER_REFERENCE.md) — auto-generated provider catalog.
+- [openapi.yaml](reference/openapi.yaml) — OpenAPI 3.1 spec for the public API.
+- [ENVIRONMENT.md](reference/ENVIRONMENT.md) — environment variables reference.
+- [CLI-TOOLS.md](reference/CLI-TOOLS.md) — bundled CLI commands.
+- [FREE_TIERS.md](reference/FREE_TIERS.md) — free-tier LLM provider directory.
+
+## frameworks/
+
+Pluggable subsystems exposed to clients, agents, and operators.
+
+- [MCP-SERVER.md](frameworks/MCP-SERVER.md) — Model Context Protocol server.
+- [A2A-SERVER.md](frameworks/A2A-SERVER.md) — Agent-to-Agent (A2A) JSON-RPC server.
+- [AGENT_PROTOCOLS_GUIDE.md](frameworks/AGENT_PROTOCOLS_GUIDE.md) — A2A / ACP / Cloud agent overview.
+- [CLOUD_AGENT.md](frameworks/CLOUD_AGENT.md) — cloud agent runtime and providers.
+- [SKILLS.md](frameworks/SKILLS.md) — Skills framework (sandboxed extension).
+- [MEMORY.md](frameworks/MEMORY.md) — persistent memory (FTS5 + Qdrant).
+- [WEBHOOKS.md](frameworks/WEBHOOKS.md) — webhook events and dispatch.
+- [EVALS.md](frameworks/EVALS.md) — eval suites.
+
+## routing/
+
+Combo routing, scoring, and replay.
+
+- [AUTO-COMBO.md](routing/AUTO-COMBO.md) — Auto-Combo (9-factor scoring, 14 strategies).
+- [REASONING_REPLAY.md](routing/REASONING_REPLAY.md) — reasoning replay flow.
+
+## security/
+
+Guardrails, compliance, and stealth.
+
+- [GUARDRAILS.md](security/GUARDRAILS.md) — PII, prompt injection, vision guardrails.
+- [COMPLIANCE.md](security/COMPLIANCE.md) — audit trails and compliance.
+- [STEALTH_GUIDE.md](security/STEALTH_GUIDE.md) — TLS / fingerprint stealth.
+
+## compression/
+
+Prompt compression engines, rules, and language packs.
+
+- [COMPRESSION_GUIDE.md](compression/COMPRESSION_GUIDE.md) — top-level compression overview.
+- [COMPRESSION_ENGINES.md](compression/COMPRESSION_ENGINES.md) — available compression engines.
+- [COMPRESSION_RULES_FORMAT.md](compression/COMPRESSION_RULES_FORMAT.md) — rule file format.
+- [COMPRESSION_LANGUAGE_PACKS.md](compression/COMPRESSION_LANGUAGE_PACKS.md) — language packs.
+- [RTK_COMPRESSION.md](compression/RTK_COMPRESSION.md) — RTK engine deep dive.
+
+## ops/
+
+Release, deployment, proxies, tunnels, coverage.
+
+- [RELEASE_CHECKLIST.md](ops/RELEASE_CHECKLIST.md) — release flow checklist.
+- [COVERAGE_PLAN.md](ops/COVERAGE_PLAN.md) — test coverage plan.
+- [FLY_IO_DEPLOYMENT_GUIDE.md](ops/FLY_IO_DEPLOYMENT_GUIDE.md) — Fly.io deployment.
+- [VM_DEPLOYMENT_GUIDE.md](ops/VM_DEPLOYMENT_GUIDE.md) — generic VM deployment.
+- [PROXY_GUIDE.md](ops/PROXY_GUIDE.md) — upstream proxy configuration.
+- [TUNNELS_GUIDE.md](ops/TUNNELS_GUIDE.md) — Cloudflare tunnel and friends.
+
+## diagrams/
+
+Mermaid sources and exported SVG/PNG diagrams referenced from the docs above. Populated incrementally — see [diagrams/README.md](diagrams/README.md).
+
+## i18n/
+
+Translated mirrors of the documentation in 40 locales. See [i18n/README.md](i18n/README.md) for the supported language list.
+
+## screenshots/
+
+Static screenshots used by the dashboard and the README. Not part of the doc body.
+
+---
+
+## Auto-generated artifacts
+
+- [reference/PROVIDER_REFERENCE.md](reference/PROVIDER_REFERENCE.md) is generated by `scripts/gen-provider-reference.ts` from `src/shared/constants/providers.ts`. Do not edit by hand.
+- The dashboard sidebar (`/docs` UI) is generated by `scripts/generate-docs-index.mjs`, which walks the subfolders above.
diff --git a/docs/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md
similarity index 96%
rename from docs/ARCHITECTURE.md
rename to docs/architecture/ARCHITECTURE.md
index 719c530dcd..3b1d15c68c 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/architecture/ARCHITECTURE.md
@@ -1,6 +1,6 @@
# OmniRoute Architecture
-🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) | 🇨🇿 [Čeština](i18n/cs/ARCHITECTURE.md)
+🌐 **Languages:** 🇺🇸 [English](./ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) | 🇨🇿 [Čeština](i18n/cs/ARCHITECTURE.md)
_Last updated: 2026-05-13_
@@ -334,7 +334,7 @@ Key capabilities:
configurations callable from the dashboard.
For full algorithmic detail (factor formulas, weight tuning), see
-[`docs/AUTO-COMBO.md`](AUTO-COMBO.md).
+[`docs/routing/AUTO-COMBO.md`](../routing/AUTO-COMBO.md).
### B. Cloud Agents
@@ -351,7 +351,7 @@ endpoints require management authentication.
- Storage: `cloud_agent_tasks` table
For per-agent provisioning and OAuth specifics, see
-[`docs/CLOUD_AGENT.md`](CLOUD_AGENT.md).
+[`docs/frameworks/CLOUD_AGENT.md`](../frameworks/CLOUD_AGENT.md).
### C. Guardrails
@@ -367,7 +367,7 @@ downstream callers to retry or branch.
- HTTP contract: violations surface as `503` with `error.code = "GUARDRAIL_VIOLATION"`
For ruleset authoring and threshold tuning, see
-[`docs/GUARDRAILS.md`](GUARDRAILS.md).
+[`docs/security/GUARDRAILS.md`](../security/GUARDRAILS.md).
### D. Domain Layer
@@ -410,7 +410,7 @@ Public vs management routes are a hard boundary: agent/cooldown APIs and
provider mutations require management auth (HTTP 401 if missing).
For the full route classification rules, see
-[`docs/AUTHZ_GUIDE.md`](AUTHZ_GUIDE.md).
+[`docs/architecture/AUTHZ_GUIDE.md`](./AUTHZ_GUIDE.md).
### F. Workflow FSM and Task-Aware Router
@@ -447,7 +447,7 @@ the global circuit breaker / connection cooldown / model lockout layers:
- ChatGPT image cache: `open-sse/services/chatgptImageCache.ts`
For the full stealth playbook and operational guidance, see
-[`docs/STEALTH_GUIDE.md`](STEALTH_GUIDE.md).
+[`docs/security/STEALTH_GUIDE.md`](../security/STEALTH_GUIDE.md).
### H. Webhooks, Reasoning Cache, Read Cache
@@ -455,12 +455,12 @@ For the full stealth playbook and operational guidance, see
- Dispatcher: `src/lib/webhookDispatcher.ts`
- Storage: `webhooks` SQLite table (via `src/lib/db/webhooks.ts`)
- Dashboard: `/dashboard/webhooks` (subscriptions, secrets, retry history)
- - For event taxonomy and retry semantics, see [`docs/WEBHOOKS.md`](WEBHOOKS.md).
+ - For event taxonomy and retry semantics, see [`docs/frameworks/WEBHOOKS.md`](../frameworks/WEBHOOKS.md).
- **Reasoning Cache** — replayable reasoning blocks for providers that emit
thinking tokens (Claude, GLMT, etc.) so consecutive turns can skip re-thinking.
- DB layer: `src/lib/db/reasoningCache.ts`
- Service layer: `open-sse/services/reasoningCache.ts`
- - For replay semantics, see [`docs/REASONING_REPLAY.md`](REASONING_REPLAY.md).
+ - For replay semantics, see [`docs/routing/REASONING_REPLAY.md`](../routing/REASONING_REPLAY.md).
- **Read Cache** — short-lived response cache keyed by signature and used to
collapse identical retries from broken upstream SDKs.
- DB layer: `src/lib/db/readCache.ts`
@@ -890,7 +890,7 @@ All other providers (including custom compatible nodes) use the `DefaultExecutor
> **Note:** The matrix below is a representative sample of the 179 registered providers in
> OmniRoute v3.8.0. For the canonical and continuously-updated list, refer to
-> [`docs/PROVIDER_REFERENCE.md`](PROVIDER_REFERENCE.md) (auto-generated) or the source of
+> [`docs/reference/PROVIDER_REFERENCE.md`](../reference/PROVIDER_REFERENCE.md) (auto-generated) or the source of
> truth at `src/shared/constants/providers.ts` (Zod-validated at load).
| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API |
diff --git a/docs/AUTHZ_GUIDE.md b/docs/architecture/AUTHZ_GUIDE.md
similarity index 97%
rename from docs/AUTHZ_GUIDE.md
rename to docs/architecture/AUTHZ_GUIDE.md
index 6043be9aa4..6f3a18575c 100644
--- a/docs/AUTHZ_GUIDE.md
+++ b/docs/architecture/AUTHZ_GUIDE.md
@@ -195,7 +195,7 @@ Use `assertAuth(req, expectedClass)` inside handlers — it throws `AuthzAsserti
## See Also
-- [API_REFERENCE.md](./API_REFERENCE.md) — auth marker per endpoint
-- [COMPLIANCE.md](./COMPLIANCE.md) — audit log for auth events
-- [MCP-SERVER.md](./MCP-SERVER.md) — MCP scope enforcement details
+- [API_REFERENCE.md](../reference/API_REFERENCE.md) — auth marker per endpoint
+- [COMPLIANCE.md](../security/COMPLIANCE.md) — audit log for auth events
+- [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — MCP scope enforcement details
- Source: `src/server/authz/`, `src/lib/api/requireManagementAuth.ts`
diff --git a/docs/CODEBASE_DOCUMENTATION.md b/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 97%
rename from docs/CODEBASE_DOCUMENTATION.md
rename to docs/architecture/CODEBASE_DOCUMENTATION.md
index 305c769176..95608bb023 100644
--- a/docs/CODEBASE_DOCUMENTATION.md
+++ b/docs/architecture/CODEBASE_DOCUMENTATION.md
@@ -501,7 +501,7 @@ Highlights (full list under `open-sse/services/`):
`runtimeHeartbeat.ts`, `descriptionCompressor.ts`, `schemas/{tools, a2a, audit, index}.ts`,
`tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts`,
plus tests under `__tests__/`.
-- See [MCP-SERVER.md](./MCP-SERVER.md) for the full tool catalog.
+- See [MCP-SERVER.md](../frameworks/MCP-SERVER.md) for the full tool catalog.
### 4.7 `open-sse/config/`
@@ -701,7 +701,7 @@ See [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) and the dedicated section in
4. If management-only: add the path to `src/shared/constants/publicApiRoutes.ts`
(denylist for the public API surface).
5. Add tests under `tests/unit/`.
-6. Update `docs/API_REFERENCE.md` and `docs/openapi.yaml`.
+6. Update `docs/reference/API_REFERENCE.md` and `docs/reference/openapi.yaml`.
### Add a new DB module
@@ -719,11 +719,11 @@ See [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) and the dedicated section in
2. Assign the appropriate scope(s) in `src/shared/constants/mcpScopes.ts`.
3. Register the tool in `open-sse/mcp-server/server.ts`.
4. Add tests under `open-sse/mcp-server/__tests__/`.
-5. Update [MCP-SERVER.md](./MCP-SERVER.md).
+5. Update [MCP-SERVER.md](../frameworks/MCP-SERVER.md).
### Add a new A2A skill
-See [A2A-SERVER.md § Adding a New Skill](./A2A-SERVER.md). Skills live in
+See [A2A-SERVER.md § Adding a New Skill](../frameworks/A2A-SERVER.md). Skills live in
`src/lib/a2a/skills/` and are registered through the A2A task manager.
---
@@ -775,17 +775,17 @@ See [A2A-SERVER.md § Adding a New Skill](./A2A-SERVER.md). Skills live in
- [ARCHITECTURE.md](./ARCHITECTURE.md) — high-level architecture and module
responsibilities.
-- [API_REFERENCE.md](./API_REFERENCE.md) — public + management API reference.
-- [FEATURES.md](./FEATURES.md) — feature matrix and version highlights.
+- [API_REFERENCE.md](../reference/API_REFERENCE.md) — public + management API reference.
+- [FEATURES.md](../guides/FEATURES.md) — feature matrix and version highlights.
- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — circuit breaker, cooldown,
lockout deep dive.
-- [AUTO-COMBO.md](./AUTO-COMBO.md) — Auto Combo scoring and strategies.
-- [MCP-SERVER.md](./MCP-SERVER.md) — full MCP tool catalog + transports.
-- [A2A-SERVER.md](./A2A-SERVER.md) — A2A protocol skills and discovery.
-- [COMPRESSION_GUIDE.md](./COMPRESSION_GUIDE.md) — RTK + Caveman compression.
-- [CLI-TOOLS.md](./CLI-TOOLS.md) — CLI integrations.
-- [ELECTRON_GUIDE.md](./ELECTRON_GUIDE.md) (if present), [DOCKER_GUIDE.md](./DOCKER_GUIDE.md), [FLY_IO_DEPLOYMENT_GUIDE.md](./FLY_IO_DEPLOYMENT_GUIDE.md), [VM_DEPLOYMENT_GUIDE.md](./VM_DEPLOYMENT_GUIDE.md), [TERMUX_GUIDE.md](./TERMUX_GUIDE.md), [PWA_GUIDE.md](./PWA_GUIDE.md) — deployment targets.
-- [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) — common operational issues.
+- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — Auto Combo scoring and strategies.
+- [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — full MCP tool catalog + transports.
+- [A2A-SERVER.md](../frameworks/A2A-SERVER.md) — A2A protocol skills and discovery.
+- [COMPRESSION_GUIDE.md](../compression/COMPRESSION_GUIDE.md) — RTK + Caveman compression.
+- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — CLI integrations.
+- [ELECTRON_GUIDE.md](../guides/ELECTRON_GUIDE.md) (if present), [DOCKER_GUIDE.md](../guides/DOCKER_GUIDE.md), [FLY_IO_DEPLOYMENT_GUIDE.md](../ops/FLY_IO_DEPLOYMENT_GUIDE.md), [VM_DEPLOYMENT_GUIDE.md](../ops/VM_DEPLOYMENT_GUIDE.md), [TERMUX_GUIDE.md](../guides/TERMUX_GUIDE.md), [PWA_GUIDE.md](../guides/PWA_GUIDE.md) — deployment targets.
+- [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — common operational issues.
- [CONTRIBUTING.md](../CONTRIBUTING.md) — contributor workflow.
- [CLAUDE.md](../CLAUDE.md) — repo rules for Claude Code (the source of truth
for many of the conventions above).
diff --git a/docs/REPOSITORY_MAP.md b/docs/architecture/REPOSITORY_MAP.md
similarity index 88%
rename from docs/REPOSITORY_MAP.md
rename to docs/architecture/REPOSITORY_MAP.md
index e16bdcd892..532936cdcd 100644
--- a/docs/REPOSITORY_MAP.md
+++ b/docs/architecture/REPOSITORY_MAP.md
@@ -42,45 +42,45 @@ OmniRoute/
## Root files
-| File | Purpose |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| **README.md** | Marketing landing page + quick start + feature matrix (see also `llm.txt`) |
-| **CHANGELOG.md** | Per-release changelog (auto-generated by `/version-bump-cc` skill) |
-| **LICENSE** | MIT license text |
-| **CLAUDE.md** | Project rules for Claude Code agents (hard rules, conventions, scenarios) |
-| **AGENTS.md** | Same as CLAUDE.md but for non-Claude AI agents (Codex, Cursor, etc.) |
-| **GEMINI.md** | Concise rules for Gemini-based agents (subset of CLAUDE.md) |
-| **CONTRIBUTING.md** | Contributor guide: setup, conventional commits, testing, PR flow |
-| **SECURITY.md** | Vulnerability reporting policy, supported versions, threat model |
-| **CODE_OF_CONDUCT.md** | Contributor Covenant — community behavior expectations |
-| **llm.txt** | Plain-text landing optimized for LLM crawlers (SEO for AI assistants) |
-| **Tuto_Qdrant.md** | Tutorial for enabling Qdrant vector memory — **integration currently dormant** (see banner; primary memory docs in `docs/MEMORY.md`) |
-| **package.json** | npm manifest, scripts, dependencies, engines, c8 coverage gate |
-| **package-lock.json** | Locked dependency tree |
-| **tsconfig.json** | Root TypeScript config |
-| **tsconfig.typecheck-core.json** | Typecheck config for `src/` core |
-| **tsconfig.typecheck-noimplicit-core.json** | Strict (`noImplicitAny`) typecheck |
-| **tsconfig.tsbuildinfo** | TS incremental build cache (gitignored) |
-| **next.config.mjs** | Next.js 16 build configuration (standalone output) |
-| **next-env.d.ts** | Next.js auto-generated env types |
-| **eslint.config.mjs** | ESLint flat config (rules per project area) |
-| **prettier.config.mjs** | Prettier formatting rules |
-| **postcss.config.mjs** | PostCSS config for Tailwind/CSS pipeline |
-| **playwright.config.ts** | Playwright E2E test config |
-| **vitest.config.ts** | Vitest config (default suite) |
-| **vitest.mcp.config.ts** | Vitest config for MCP server / autoCombo / cache suites |
-| **sonar-project.properties** | SonarQube/SonarCloud config (code quality) |
-| **Dockerfile** | Multi-stage Docker build (builder → runner-base → runner-cli) |
-| **docker-compose.yml** | Dev compose with 4 profiles (base, cli, host, cliproxyapi) + redis sidecar |
-| **docker-compose.prod.yml** | Production compose (port 20130, redis, named volumes) |
-| **.dockerignore** | Files excluded from Docker context |
-| **fly.toml** | Fly.io deployment config (region `sin`, port 20128, /data volume) |
-| **.env.example** | Template env file (815 lines, auto-copied to `.env` on first install) |
-| **.gitignore** | Git ignore patterns |
-| **.npmignore** | npm publish exclusion list |
-| **.npmrc** | npm config (registry, lockfile policy) |
-| **.node-version** | Node version pin (used by nvm-compatible tools) |
-| **.nvmrc** | Node version pin for nvm |
+| File | Purpose |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| **README.md** | Marketing landing page + quick start + feature matrix (see also `llm.txt`) |
+| **CHANGELOG.md** | Per-release changelog (auto-generated by `/version-bump-cc` skill) |
+| **LICENSE** | MIT license text |
+| **CLAUDE.md** | Project rules for Claude Code agents (hard rules, conventions, scenarios) |
+| **AGENTS.md** | Same as CLAUDE.md but for non-Claude AI agents (Codex, Cursor, etc.) |
+| **GEMINI.md** | Concise rules for Gemini-based agents (subset of CLAUDE.md) |
+| **CONTRIBUTING.md** | Contributor guide: setup, conventional commits, testing, PR flow |
+| **SECURITY.md** | Vulnerability reporting policy, supported versions, threat model |
+| **CODE_OF_CONDUCT.md** | Contributor Covenant — community behavior expectations |
+| **llm.txt** | Plain-text landing optimized for LLM crawlers (SEO for AI assistants) |
+| **Tuto_Qdrant.md** | Tutorial for enabling Qdrant vector memory — **integration currently dormant** (see banner; primary memory docs in `docs/frameworks/MEMORY.md`) |
+| **package.json** | npm manifest, scripts, dependencies, engines, c8 coverage gate |
+| **package-lock.json** | Locked dependency tree |
+| **tsconfig.json** | Root TypeScript config |
+| **tsconfig.typecheck-core.json** | Typecheck config for `src/` core |
+| **tsconfig.typecheck-noimplicit-core.json** | Strict (`noImplicitAny`) typecheck |
+| **tsconfig.tsbuildinfo** | TS incremental build cache (gitignored) |
+| **next.config.mjs** | Next.js 16 build configuration (standalone output) |
+| **next-env.d.ts** | Next.js auto-generated env types |
+| **eslint.config.mjs** | ESLint flat config (rules per project area) |
+| **prettier.config.mjs** | Prettier formatting rules |
+| **postcss.config.mjs** | PostCSS config for Tailwind/CSS pipeline |
+| **playwright.config.ts** | Playwright E2E test config |
+| **vitest.config.ts** | Vitest config (default suite) |
+| **vitest.mcp.config.ts** | Vitest config for MCP server / autoCombo / cache suites |
+| **sonar-project.properties** | SonarQube/SonarCloud config (code quality) |
+| **Dockerfile** | Multi-stage Docker build (builder → runner-base → runner-cli) |
+| **docker-compose.yml** | Dev compose with 4 profiles (base, cli, host, cliproxyapi) + redis sidecar |
+| **docker-compose.prod.yml** | Production compose (port 20130, redis, named volumes) |
+| **.dockerignore** | Files excluded from Docker context |
+| **fly.toml** | Fly.io deployment config (region `sin`, port 20128, /data volume) |
+| **.env.example** | Template env file (815 lines, auto-copied to `.env` on first install) |
+| **.gitignore** | Git ignore patterns |
+| **.npmignore** | npm publish exclusion list |
+| **.npmrc** | npm config (registry, lockfile policy) |
+| **.node-version** | Node version pin (used by nvm-compatible tools) |
+| **.nvmrc** | Node version pin for nvm |
---
@@ -130,32 +130,32 @@ src/
| Module | Purpose |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `a2a/` | A2A protocol task manager, skills (5), streaming |
-| `acp/` | CLI Agent Registry (local CLI discovery — see `docs/AGENT_PROTOCOLS_GUIDE.md`) |
+| `acp/` | CLI Agent Registry (local CLI discovery — see `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`) |
| `api/` | Shared API helpers (`requireManagementAuth`, validation) |
| `auth/` | Session, password hashing, token validation |
| `batches/` | OpenAI Batches API handlers |
| `catalog/` | Provider catalog Zod validation + capability resolution |
-| `cloudAgent/` | Cloud Agents (Codex Cloud, Devin, Jules) — see `docs/CLOUD_AGENT.md` |
+| `cloudAgent/` | Cloud Agents (Codex Cloud, Devin, Jules) — see `docs/frameworks/CLOUD_AGENT.md` |
| `combos/` | Combo resolution + reorder helpers |
-| `compliance/` | Audit log + provider audit — see `docs/COMPLIANCE.md` |
+| `compliance/` | Audit log + provider audit — see `docs/security/COMPLIANCE.md` |
| `compression/` | Compression engine glue (engines live in `open-sse/services/compression/`) |
| `config/` | Runtime config helpers |
| `db/` | 45+ domain DB modules + 55 migrations (always go through here for SQLite) |
| `display/` | UI formatting helpers (cost, latency, etc.) |
| `embeddings/` | Embeddings service helpers |
| `env/` | Env variable parsing + validation |
-| `evals/` | Eval framework (suites, runner, runtime) — see `docs/EVALS.md` |
-| `guardrails/` | PII masker, prompt injection, vision bridge — see `docs/GUARDRAILS.md` |
+| `evals/` | Eval framework (suites, runner, runtime) — see `docs/frameworks/EVALS.md` |
+| `guardrails/` | PII masker, prompt injection, vision bridge — see `docs/security/GUARDRAILS.md` |
| `jobs/` | Background jobs (cron-like) |
-| `memory/` | Conversational memory (SQLite FTS5 + Qdrant) — see `docs/MEMORY.md` |
+| `memory/` | Conversational memory (SQLite FTS5 + Qdrant) — see `docs/frameworks/MEMORY.md` |
| `monitoring/` | Health checks, metrics emission |
| `oauth/` | OAuth flows for 14 providers (claude, codex, antigravity, cursor, github, gemini, kimi-coding, kilocode, cline, qwen, kiro, qoder, gitlab-duo, windsurf) |
| `plugins/` | Plugin registry |
| `promptCache/` | Anthropic-style prompt cache breakpoints |
-| `skills/` | Skills framework (built-in + marketplace + SkillsSH) — see `docs/SKILLS.md` |
-| `webhookDispatcher.ts` | HMAC webhook delivery — see `docs/WEBHOOKS.md` |
-| `cloudflaredTunnel.ts`, `ngrokTunnel.ts` | Tunnel managers — see `docs/TUNNELS_GUIDE.md` |
-| `oneproxySync.ts`, `oneproxyRotator.ts` | 1proxy free proxy marketplace — see `docs/PROXY_GUIDE.md` |
+| `skills/` | Skills framework (built-in + marketplace + SkillsSH) — see `docs/frameworks/SKILLS.md` |
+| `webhookDispatcher.ts` | HMAC webhook delivery — see `docs/frameworks/WEBHOOKS.md` |
+| `cloudflaredTunnel.ts`, `ngrokTunnel.ts` | Tunnel managers — see `docs/ops/TUNNELS_GUIDE.md` |
+| `oneproxySync.ts`, `oneproxyRotator.ts` | 1proxy free proxy marketplace — see `docs/ops/PROXY_GUIDE.md` |
| `cloudSync.ts`, `initCloudSync.ts` | Optional cloud sync of state |
| `localDb.ts` | Re-export barrel for db modules (no logic — re-exports only) |
| `cacheLayer.ts`, `idempotencyLayer.ts` | Request caching + idempotency |
@@ -184,28 +184,28 @@ src/
### `src/server/`
-| Module | Purpose |
-| -------- | --------------------------------------------------------------------------------------- |
-| `authz/` | Authorization pipeline: `classify` → `policies` → `enforce` — see `docs/AUTHZ_GUIDE.md` |
-| `cors/` | CORS configuration |
-| `auth/` | Session middleware |
+| Module | Purpose |
+| -------- | ---------------------------------------------------------------------------------------------------- |
+| `authz/` | Authorization pipeline: `classify` → `policies` → `enforce` — see `docs/architecture/AUTHZ_GUIDE.md` |
+| `cors/` | CORS configuration |
+| `auth/` | Session middleware |
### `src/shared/`
-| Module | Purpose |
-| -------------------------------- | ------------------------------------------------------------- |
-| `constants/providers.ts` | **177 providers** with Zod validation (source of truth) |
-| `constants/cliTools.ts` | External CLI tool registry |
-| `constants/routingStrategies.ts` | **14 routing strategies** with priorities |
-| `constants/publicApiRoutes.ts` | Routes that require Bearer (vs management) auth |
-| `constants/upstreamHeaders.ts` | Header denylist for upstream requests |
-| `validation/schemas.ts` | ~80 Zod schemas (single source of truth for API contracts) |
-| `validation/helpers.ts` | Zod validation helpers (`validateBody`, etc.) |
-| `types/` | Shared TS types |
-| `contracts/` | Public API contracts (consumed by `files:` in `package.json`) |
-| `utils/circuitBreaker.ts` | Provider circuit breaker (see `docs/RESILIENCE_GUIDE.md`) |
-| `utils/apiAuth.ts` | API key validation, scope checking |
-| `utils/fetchTimeout.ts` | Timeout/abort wrappers for upstream fetch |
+| Module | Purpose |
+| -------------------------------- | ---------------------------------------------------------------------- |
+| `constants/providers.ts` | **177 providers** with Zod validation (source of truth) |
+| `constants/cliTools.ts` | External CLI tool registry |
+| `constants/routingStrategies.ts` | **14 routing strategies** with priorities |
+| `constants/publicApiRoutes.ts` | Routes that require Bearer (vs management) auth |
+| `constants/upstreamHeaders.ts` | Header denylist for upstream requests |
+| `validation/schemas.ts` | ~80 Zod schemas (single source of truth for API contracts) |
+| `validation/helpers.ts` | Zod validation helpers (`validateBody`, etc.) |
+| `types/` | Shared TS types |
+| `contracts/` | Public API contracts (consumed by `files:` in `package.json`) |
+| `utils/circuitBreaker.ts` | Provider circuit breaker (see `docs/architecture/RESILIENCE_GUIDE.md`) |
+| `utils/apiAuth.ts` | API key validation, scope checking |
+| `utils/fetchTimeout.ts` | Timeout/abort wrappers for upstream fetch |
---
@@ -231,20 +231,20 @@ open-sse/
### `open-sse/mcp-server/`
-| Path | Purpose |
-| --------------------------- | -------------------------------------------------------------------- |
-| `server.ts` | MCP server lifecycle (stdio + HTTP transports) |
-| `httpTransport.ts` | HTTP Streamable + SSE transports (`/api/mcp/sse`, `/api/mcp/stream`) |
-| `audit.ts` | Audit logging to `mcp_tool_audit` table |
-| `scopeEnforcement.ts` | Per-tool scope validation |
-| `runtimeHeartbeat.ts` | Health heartbeat to `DATA_DIR/runtime/mcp-heartbeat.json` |
-| `descriptionCompressor.ts` | Compress tool description metadata to save context |
-| `schemas/tools.ts` | 30 base tool definitions + scopes |
-| `tools/advancedTools.ts` | Advanced tool implementations |
-| `tools/memoryTools.ts` | 3 memory tools (search/add/clear) |
-| `tools/skillTools.ts` | 4 skill tools (list/enable/execute/executions) |
-| `tools/compressionTools.ts` | 5 compression tools |
-| `README.md` | Internal MCP server README (cross-linked from `docs/MCP-SERVER.md`) |
+| Path | Purpose |
+| --------------------------- | ------------------------------------------------------------------------------ |
+| `server.ts` | MCP server lifecycle (stdio + HTTP transports) |
+| `httpTransport.ts` | HTTP Streamable + SSE transports (`/api/mcp/sse`, `/api/mcp/stream`) |
+| `audit.ts` | Audit logging to `mcp_tool_audit` table |
+| `scopeEnforcement.ts` | Per-tool scope validation |
+| `runtimeHeartbeat.ts` | Health heartbeat to `DATA_DIR/runtime/mcp-heartbeat.json` |
+| `descriptionCompressor.ts` | Compress tool description metadata to save context |
+| `schemas/tools.ts` | 30 base tool definitions + scopes |
+| `tools/advancedTools.ts` | Advanced tool implementations |
+| `tools/memoryTools.ts` | 3 memory tools (search/add/clear) |
+| `tools/skillTools.ts` | 4 skill tools (list/enable/execute/executions) |
+| `tools/compressionTools.ts` | 5 compression tools |
+| `README.md` | Internal MCP server README (cross-linked from `docs/frameworks/MCP-SERVER.md`) |
---
@@ -258,7 +258,7 @@ open-sse/
| `assets/` | App icons (Windows .ico, macOS .icns, Linux .png) |
| `dist-electron/` | Build output (gitignored) |
| `types.d.ts` | Type declarations for renderer bridge |
-| `README.md` | Internal Electron README (see also `docs/ELECTRON_GUIDE.md`) |
+| `README.md` | Internal Electron README (see also `docs/guides/ELECTRON_GUIDE.md`) |
---
@@ -294,7 +294,7 @@ open-sse/
| **`check-deprecated-versions.mjs`** | NEW: flag stale versions/dates in docs |
| `check-supported-node-runtime.ts` | Validate current Node version is supported |
| `check-pr-test-policy.mjs` | Enforce "tests required" rule on production code changes |
-| **`gen-provider-reference.ts`** | NEW: auto-generate `docs/PROVIDER_REFERENCE.md` from catalog |
+| **`gen-provider-reference.ts`** | NEW: auto-generate `docs/reference/PROVIDER_REFERENCE.md` from catalog |
| `generate-docs-index.mjs` | Build `src/app/docs/lib/docs-auto-generated.ts` from `docs/*.md` |
| `i18n/generate-multilang.mjs` | Translate UI strings + docs via Google Translate |
| `i18n_autotranslate.py` | LLM-based doc translation pipeline |
@@ -496,11 +496,11 @@ Not included in `npm pack` output. See `.npmignore`.
## Navigation tips
-- **New contributor?** Read `CONTRIBUTING.md` → `CLAUDE.md` → `docs/ARCHITECTURE.md` → `docs/CODEBASE_DOCUMENTATION.md`.
-- **Adding a provider?** Follow `docs/ARCHITECTURE.md § Adding a New Provider` + cross-check `docs/PROVIDER_REFERENCE.md`.
-- **Adding a route?** `docs/ARCHITECTURE.md § Adding a New API Route` + `src/shared/validation/schemas.ts`.
-- **Adding an MCP tool?** `docs/MCP-SERVER.md § Adding a Tool`.
-- **Adding an A2A skill?** `docs/A2A-SERVER.md § Adding a New Skill`.
-- **Running locally?** `docs/SETUP_GUIDE.md`.
-- **Deploying?** `docs/DOCKER_GUIDE.md` / `docs/VM_DEPLOYMENT_GUIDE.md` / `docs/FLY_IO_DEPLOYMENT_GUIDE.md`.
-- **Releasing?** `docs/RELEASE_CHECKLIST.md` (and `/generate-release-cc` Claude Code skill).
+- **New contributor?** Read `CONTRIBUTING.md` → `CLAUDE.md` → `docs/architecture/ARCHITECTURE.md` → `docs/architecture/CODEBASE_DOCUMENTATION.md`.
+- **Adding a provider?** Follow `docs/architecture/ARCHITECTURE.md § Adding a New Provider` + cross-check `docs/reference/PROVIDER_REFERENCE.md`.
+- **Adding a route?** `docs/architecture/ARCHITECTURE.md § Adding a New API Route` + `src/shared/validation/schemas.ts`.
+- **Adding an MCP tool?** `docs/frameworks/MCP-SERVER.md § Adding a Tool`.
+- **Adding an A2A skill?** `docs/frameworks/A2A-SERVER.md § Adding a New Skill`.
+- **Running locally?** `docs/guides/SETUP_GUIDE.md`.
+- **Deploying?** `docs/guides/DOCKER_GUIDE.md` / `docs/ops/VM_DEPLOYMENT_GUIDE.md` / `docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md`.
+- **Releasing?** `docs/ops/RELEASE_CHECKLIST.md` (and `/generate-release-cc` Claude Code skill).
diff --git a/docs/RESILIENCE_GUIDE.md b/docs/architecture/RESILIENCE_GUIDE.md
similarity index 93%
rename from docs/RESILIENCE_GUIDE.md
rename to docs/architecture/RESILIENCE_GUIDE.md
index 1e630d85d8..e851f07498 100644
--- a/docs/RESILIENCE_GUIDE.md
+++ b/docs/architecture/RESILIENCE_GUIDE.md
@@ -107,7 +107,7 @@ Lists active lockouts with: provider, connection, model, reason, expiresAt. Oper
## Other Resilience Features
-- **14 routing strategies** (priority, weighted, round-robin, context-relay, fill-first, p2c, random, least-used, cost-optimized, reset-aware, strict-random, auto, lkgp, context-optimized) — see [AUTO-COMBO.md](./AUTO-COMBO.md).
+- **14 routing strategies** (priority, weighted, round-robin, context-relay, fill-first, p2c, random, least-used, cost-optimized, reset-aware, strict-random, auto, lkgp, context-optimized) — see [AUTO-COMBO.md](../routing/AUTO-COMBO.md).
- **Reset-aware routing** (v3.8.0) — prioritizes connections by quota reset time.
- **Background mode degradation** — Responses API `background: true` degraded to sync with warning.
- **Dynamic tool limit detection** — backs off providers when tool count limits hit.
@@ -126,12 +126,12 @@ Lists active lockouts with: provider, connection, model, reason, expiresAt. Oper
## TLS Fingerprinting & Stealth
-Provider-specific stealth (JA3/JA4, CCH, obfuscation) is separately documented — see [STEALTH_GUIDE.md](./STEALTH_GUIDE.md).
+Provider-specific stealth (JA3/JA4, CCH, obfuscation) is separately documented — see [STEALTH_GUIDE.md](../security/STEALTH_GUIDE.md).
---
## See Also
-- [Architecture Guide](ARCHITECTURE.md) — System architecture and internals
-- [User Guide](USER_GUIDE.md) — Providers, combos, CLI integration
-- [Auto-Combo Engine](AUTO-COMBO.md) — 6-factor scoring, mode packs
+- [Architecture Guide](./ARCHITECTURE.md) — System architecture and internals
+- [User Guide](../guides/USER_GUIDE.md) — Providers, combos, CLI integration
+- [Auto-Combo Engine](../routing/AUTO-COMBO.md) — 6-factor scoring, mode packs
diff --git a/docs/COMPRESSION_ENGINES.md b/docs/compression/COMPRESSION_ENGINES.md
similarity index 98%
rename from docs/COMPRESSION_ENGINES.md
rename to docs/compression/COMPRESSION_ENGINES.md
index a4c56eb6bd..a5703e3e5c 100644
--- a/docs/COMPRESSION_ENGINES.md
+++ b/docs/compression/COMPRESSION_ENGINES.md
@@ -36,7 +36,7 @@ runtime compression, stacked mode, tests, and future engines use the same execut
### MCP description compression (related)
A separate registry compresses MCP tool description metadata at registry-level — see
-`open-sse/mcp-server/descriptionCompressor.ts` and [MCP-SERVER.md](./MCP-SERVER.md). It reuses
+`open-sse/mcp-server/descriptionCompressor.ts` and [MCP-SERVER.md](../frameworks/MCP-SERVER.md). It reuses
Caveman rules but operates on tool metadata, not request payloads.
## Caveman
@@ -75,7 +75,7 @@ RTK mode focuses on command and tool output:
The dashboard surface is `Dashboard -> Context & Cache -> RTK`.
Operational details for custom filters, trust, verify, and raw-output recovery live in
-[`RTK_COMPRESSION.md`](RTK_COMPRESSION.md).
+[`RTK_COMPRESSION.md`](./RTK_COMPRESSION.md).
RTK upstream reports `60-90%` savings for command-output compression. Its README example shows a
30-minute Claude Code session going from `~118,000` tokens to `~23,900`, or `79.7%` saved.
diff --git a/docs/COMPRESSION_GUIDE.md b/docs/compression/COMPRESSION_GUIDE.md
similarity index 94%
rename from docs/COMPRESSION_GUIDE.md
rename to docs/compression/COMPRESSION_GUIDE.md
index 88213bfc63..a602832f92 100644
--- a/docs/COMPRESSION_GUIDE.md
+++ b/docs/compression/COMPRESSION_GUIDE.md
@@ -267,10 +267,10 @@ RTK mode is inspired by **[RTK - Rust Token Killer](https://github.com/rtk-ai/rt
## See Also
-- [Environment Config](ENVIRONMENT.md) — Compression environment variables
-- [Architecture Guide](ARCHITECTURE.md) — Compression pipeline internals
-- [User Guide](USER_GUIDE.md) — Getting started with compression
-- [RTK Compression](RTK_COMPRESSION.md) — RTK filters, trust model, verify gate, raw-output recovery
-- [Compression Engines](COMPRESSION_ENGINES.md) — Caveman, RTK, stacked, APIs, MCP, dashboard
-- [Compression Rules Format](COMPRESSION_RULES_FORMAT.md) — JSON rule-pack format
-- [Compression Language Packs](COMPRESSION_LANGUAGE_PACKS.md) — Language-specific Caveman rules
+- [Environment Config](../reference/ENVIRONMENT.md) — Compression environment variables
+- [Architecture Guide](../architecture/ARCHITECTURE.md) — Compression pipeline internals
+- [User Guide](../guides/USER_GUIDE.md) — Getting started with compression
+- [RTK Compression](./RTK_COMPRESSION.md) — RTK filters, trust model, verify gate, raw-output recovery
+- [Compression Engines](./COMPRESSION_ENGINES.md) — Caveman, RTK, stacked, APIs, MCP, dashboard
+- [Compression Rules Format](./COMPRESSION_RULES_FORMAT.md) — JSON rule-pack format
+- [Compression Language Packs](./COMPRESSION_LANGUAGE_PACKS.md) — Language-specific Caveman rules
diff --git a/docs/COMPRESSION_LANGUAGE_PACKS.md b/docs/compression/COMPRESSION_LANGUAGE_PACKS.md
similarity index 97%
rename from docs/COMPRESSION_LANGUAGE_PACKS.md
rename to docs/compression/COMPRESSION_LANGUAGE_PACKS.md
index 95c8f216aa..73bb21339d 100644
--- a/docs/COMPRESSION_LANGUAGE_PACKS.md
+++ b/docs/compression/COMPRESSION_LANGUAGE_PACKS.md
@@ -62,7 +62,7 @@ used when Caveman compresses message text.
## Adding a Language Pack
1. Create `open-sse/services/compression/rules//.json`.
-2. Use the Caveman rule format from `docs/COMPRESSION_RULES_FORMAT.md`.
+2. Use the Caveman rule format from `docs/compression/COMPRESSION_RULES_FORMAT.md`.
3. Keep replacements conservative and avoid changing code, identifiers, URLs, or JSON.
4. Add or update tests for language selection and replacement behavior.
5. Expose new dashboard/i18n labels if the language appears in UI selectors.
diff --git a/docs/COMPRESSION_RULES_FORMAT.md b/docs/compression/COMPRESSION_RULES_FORMAT.md
similarity index 100%
rename from docs/COMPRESSION_RULES_FORMAT.md
rename to docs/compression/COMPRESSION_RULES_FORMAT.md
diff --git a/docs/RTK_COMPRESSION.md b/docs/compression/RTK_COMPRESSION.md
similarity index 99%
rename from docs/RTK_COMPRESSION.md
rename to docs/compression/RTK_COMPRESSION.md
index f675c93d25..0b9437abbd 100644
--- a/docs/RTK_COMPRESSION.md
+++ b/docs/compression/RTK_COMPRESSION.md
@@ -70,7 +70,7 @@ skipped and reported by `/api/context/rtk/filters` diagnostics. Invalid built-in
## Filter DSL
-Filters use the JSON schema described in [Compression Rules Format](COMPRESSION_RULES_FORMAT.md).
+Filters use the JSON schema described in [Compression Rules Format](./COMPRESSION_RULES_FORMAT.md).
The runtime applies these stages in order:
```txt
diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md
new file mode 100644
index 0000000000..33560b242c
--- /dev/null
+++ b/docs/diagrams/README.md
@@ -0,0 +1,13 @@
+# Diagrams
+
+Mermaid sources (`.mmd`) and exported SVGs/PNGs for architecture flows.
+
+Populated incrementally — FASE 4 of the platform overhaul creates 8 canonical diagrams.
+
+Source diagrams: link from architecture docs using:
+
+```markdown
+
+
+> [Mermaid source](./diagram-name.mmd)
+```
diff --git a/docs/A2A-SERVER.md b/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/A2A-SERVER.md
rename to docs/frameworks/A2A-SERVER.md
diff --git a/docs/AGENT_PROTOCOLS_GUIDE.md b/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
similarity index 98%
rename from docs/AGENT_PROTOCOLS_GUIDE.md
rename to docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
index 2d34cdbc6f..80be7a642b 100644
--- a/docs/AGENT_PROTOCOLS_GUIDE.md
+++ b/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
@@ -71,7 +71,7 @@ See [A2A-SERVER.md](./A2A-SERVER.md) for transport details, agent card structure
ACP is OmniRoute's **local CLI agent inventory**. It detects which coding CLIs are installed on the host (Cursor, Cline, Claude Code, Codex CLI, Continue, etc.), resolves their versions, and surfaces them to the dashboard so the user can wire each CLI to point at OmniRoute.
-This is NOT an external protocol — it's an internal registry that powers the "CLI Tools" UI and the CLI fingerprint tracking (see [CLI-TOOLS.md](./CLI-TOOLS.md)).
+This is NOT an external protocol — it's an internal registry that powers the "CLI Tools" UI and the CLI fingerprint tracking (see [CLI-TOOLS.md](../reference/CLI-TOOLS.md)).
### What it does
@@ -270,7 +270,7 @@ curl http://localhost:20128/api/v1/agents/tasks/ \
- [A2A-SERVER.md](./A2A-SERVER.md) — A2A deep dive
- [CLOUD_AGENT.md](./CLOUD_AGENT.md) — Cloud Agents deep dive
-- [CLI-TOOLS.md](./CLI-TOOLS.md) — External CLI integrations (uses ACP)
+- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — External CLI integrations (uses ACP)
- [SKILLS.md](./SKILLS.md) — Skills framework (different from A2A skills — local execution sandbox)
-- [API_REFERENCE.md](./API_REFERENCE.md#agents-protocol) — endpoint reference
+- [API_REFERENCE.md](../reference/API_REFERENCE.md#agents-protocol) — endpoint reference
- Source: `src/lib/{a2a,acp,cloudAgent}/`
diff --git a/docs/CLOUD_AGENT.md b/docs/frameworks/CLOUD_AGENT.md
similarity index 99%
rename from docs/CLOUD_AGENT.md
rename to docs/frameworks/CLOUD_AGENT.md
index f0c538284d..f585efe629 100644
--- a/docs/CLOUD_AGENT.md
+++ b/docs/frameworks/CLOUD_AGENT.md
@@ -364,7 +364,7 @@ No Cloud-Agent-specific env vars exist today — every secret lives in the
## See Also
- [A2A-SERVER.md](./A2A-SERVER.md)
-- [API_REFERENCE.md](./API_REFERENCE.md)
+- [API_REFERENCE.md](../reference/API_REFERENCE.md)
- [SKILLS.md](./SKILLS.md)
- [MEMORY.md](./MEMORY.md)
- Source: `src/lib/cloudAgent/`
diff --git a/docs/EVALS.md b/docs/frameworks/EVALS.md
similarity index 98%
rename from docs/EVALS.md
rename to docs/frameworks/EVALS.md
index 37f36d9a99..d60e0b52b9 100644
--- a/docs/EVALS.md
+++ b/docs/frameworks/EVALS.md
@@ -237,8 +237,8 @@ Common changes and where to make them:
## See Also
-- [USER_GUIDE.md](./USER_GUIDE.md) — overall product walkthrough
-- [ARCHITECTURE.md](./ARCHITECTURE.md) — request pipeline reference
+- [USER_GUIDE.md](../guides/USER_GUIDE.md) — overall product walkthrough
+- [ARCHITECTURE.md](../architecture/ARCHITECTURE.md) — request pipeline reference
- [RFC-AUTO-ASSESSMENT.md](./RFC-AUTO-ASSESSMENT.md) — Auto Combo scoring
- Source: `src/lib/evals/`, `src/lib/db/evals.ts`, `src/app/api/evals/`
- UI: `src/app/(dashboard)/dashboard/usage/components/EvalsTab.tsx`
diff --git a/docs/MCP-SERVER.md b/docs/frameworks/MCP-SERVER.md
similarity index 98%
rename from docs/MCP-SERVER.md
rename to docs/frameworks/MCP-SERVER.md
index fe91b6bd2e..92f2120b61 100644
--- a/docs/MCP-SERVER.md
+++ b/docs/frameworks/MCP-SERVER.md
@@ -33,7 +33,7 @@ The active HTTP transport (`sse` or `streamable-http`) is selected by the `mcpTr
## IDE Configuration
-See [MCP Client Configuration](SETUP_GUIDE.md#mcp-client-configuration) for Claude Desktop,
+See [MCP Client Configuration](../guides/SETUP_GUIDE.md#mcp-client-configuration) for Claude Desktop,
Cursor, Cline, and compatible MCP client setup.
---
@@ -95,7 +95,7 @@ Cursor, Cline, and compatible MCP client setup.
descriptions (`tools`, `prompts`, `resources`, and `resourceTemplates`); they are not provider usage
receipts and are marked with `source: "mcp_metadata_estimate"`.
-See [Compression Engines](COMPRESSION_ENGINES.md) and [RTK Compression](RTK_COMPRESSION.md) for
+See [Compression Engines](../compression/COMPRESSION_ENGINES.md) and [RTK Compression](../compression/RTK_COMPRESSION.md) for
the runtime compression model behind these tools.
## 1Proxy Tools (3)
diff --git a/docs/MEMORY.md b/docs/frameworks/MEMORY.md
similarity index 99%
rename from docs/MEMORY.md
rename to docs/frameworks/MEMORY.md
index 8453762308..9aaa74f051 100644
--- a/docs/MEMORY.md
+++ b/docs/frameworks/MEMORY.md
@@ -307,7 +307,7 @@ default TTL 5 min).
- [SKILLS.md](./SKILLS.md) — the `skillsEnabled` setting injects tool
definitions alongside memory.
- [MCP-SERVER.md](./MCP-SERVER.md) — MCP transport / scopes.
-- [API_REFERENCE.md](./API_REFERENCE.md) — broader API surface.
+- [API_REFERENCE.md](../reference/API_REFERENCE.md) — broader API surface.
- [Tuto_Qdrant.md](../Tuto_Qdrant.md) — repository-root Qdrant setup tutorial (integration currently dormant — see status banner at top of that file).
- Source modules:
- `src/lib/memory/types.ts`, `schemas.ts`
diff --git a/docs/SKILLS.md b/docs/frameworks/SKILLS.md
similarity index 98%
rename from docs/SKILLS.md
rename to docs/frameworks/SKILLS.md
index 2878776b95..b90ce4f77d 100644
--- a/docs/SKILLS.md
+++ b/docs/frameworks/SKILLS.md
@@ -276,7 +276,7 @@ See [MCP-SERVER.md](./MCP-SERVER.md) for transport setup and scope assignments.
- [MCP-SERVER.md](./MCP-SERVER.md) — MCP tool registration and transports
- [A2A-SERVER.md](./A2A-SERVER.md) — A2A task lifecycle and skill dispatch
-- [USER_GUIDE.md](./USER_GUIDE.md#-skills-system) — user-facing introduction
-- [ARCHITECTURE.md](./ARCHITECTURE.md) — request pipeline and component map
+- [USER_GUIDE.md](../guides/USER_GUIDE.md#-skills-system) — user-facing introduction
+- [ARCHITECTURE.md](../architecture/ARCHITECTURE.md) — request pipeline and component map
- Source: `src/lib/skills/`, `src/app/api/skills/`, `open-sse/mcp-server/tools/skillTools.ts`
- Tests: `src/lib/skills/__tests__/integration.test.ts`
diff --git a/docs/WEBHOOKS.md b/docs/frameworks/WEBHOOKS.md
similarity index 98%
rename from docs/WEBHOOKS.md
rename to docs/frameworks/WEBHOOKS.md
index 809d1fc125..066e9f6623 100644
--- a/docs/WEBHOOKS.md
+++ b/docs/frameworks/WEBHOOKS.md
@@ -247,7 +247,7 @@ absence).
## See Also
-- [API_REFERENCE.md](./API_REFERENCE.md) — full management API surface
-- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — circuit breaker / cooldown
+- [API_REFERENCE.md](../reference/API_REFERENCE.md) — full management API surface
+- [RESILIENCE_GUIDE.md](../architecture/RESILIENCE_GUIDE.md) — circuit breaker / cooldown
semantics that drive `provider.error` / `provider.recovered`
- Source: `src/lib/webhookDispatcher.ts`, `src/lib/db/webhooks.ts`
diff --git a/docs/DOCKER_GUIDE.md b/docs/guides/DOCKER_GUIDE.md
similarity index 96%
rename from docs/DOCKER_GUIDE.md
rename to docs/guides/DOCKER_GUIDE.md
index 6af1872d8b..01d59b1897 100644
--- a/docs/DOCKER_GUIDE.md
+++ b/docs/guides/DOCKER_GUIDE.md
@@ -150,7 +150,7 @@ Defaults exported by `runner-base`: `PORT=20128`, `HOSTNAME=0.0.0.0`, `NODE_OPTI
## Critical Environment Variables
-Beyond the defaults documented in [ENVIRONMENT.md](ENVIRONMENT.md), the following variables matter most when running under Docker:
+Beyond the defaults documented in [ENVIRONMENT.md](../reference/ENVIRONMENT.md), the following variables matter most when running under Docker:
| Variable | Purpose | Default |
| ----------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------- |
@@ -225,6 +225,6 @@ Multi-platform manifest: `linux/amd64` + `linux/arm64` native (Apple Silicon, AW
## See Also
-- [VM Deployment Guide](VM_DEPLOYMENT_GUIDE.md) — VM + nginx + Cloudflare setup
-- [Fly.io Deployment Guide](FLY_IO_DEPLOYMENT_GUIDE.md) — Deploy to Fly.io
-- [Environment Config](ENVIRONMENT.md) — Complete `.env` reference
+- [VM Deployment Guide](../ops/VM_DEPLOYMENT_GUIDE.md) — VM + nginx + Cloudflare setup
+- [Fly.io Deployment Guide](../ops/FLY_IO_DEPLOYMENT_GUIDE.md) — Deploy to Fly.io
+- [Environment Config](../reference/ENVIRONMENT.md) — Complete `.env` reference
diff --git a/docs/ELECTRON_GUIDE.md b/docs/guides/ELECTRON_GUIDE.md
similarity index 99%
rename from docs/ELECTRON_GUIDE.md
rename to docs/guides/ELECTRON_GUIDE.md
index 0892a8f1d6..7da196f30a 100644
--- a/docs/ELECTRON_GUIDE.md
+++ b/docs/guides/ELECTRON_GUIDE.md
@@ -266,6 +266,6 @@ Releases are published to GitHub Releases (`diegosouzapw/OmniRoute`), which is a
## See Also
- [SETUP_GUIDE.md](./SETUP_GUIDE.md)
-- [RELEASE_CHECKLIST.md](./RELEASE_CHECKLIST.md)
+- [RELEASE_CHECKLIST.md](../ops/RELEASE_CHECKLIST.md)
- Source: `electron/main.js`, `electron/preload.js`, `electron/package.json`
- Helpers: `scripts/build/prepare-electron-standalone.mjs`, `scripts/dev/smoke-electron-packaged.mjs`
diff --git a/docs/FEATURES.md b/docs/guides/FEATURES.md
similarity index 97%
rename from docs/FEATURES.md
rename to docs/guides/FEATURES.md
index d4bab1d197..18e2ad5850 100644
--- a/docs/FEATURES.md
+++ b/docs/guides/FEATURES.md
@@ -39,7 +39,7 @@ The v3.7.x → v3.8.0 cycle added zero-config auto routing, new providers, OAuth
- 🤝 **GitLab Duo OAuth provider** — login with GitLab credentials
- 🧠 **Reasoning Replay Cache** — hybrid in-memory + SQLite persistence of reasoning traces
-📚 **Related docs:** [Skills Framework](./SKILLS.md) · [Memory System](./MEMORY.md) · [Cloud Agents](./CLOUD_AGENT.md) · [Webhooks](./WEBHOOKS.md) · [Reasoning Replay Cache](./REASONING_REPLAY.md)
+📚 **Related docs:** [Skills Framework](../frameworks/SKILLS.md) · [Memory System](../frameworks/MEMORY.md) · [Cloud Agents](../frameworks/CLOUD_AGENT.md) · [Webhooks](../frameworks/WEBHOOKS.md) · [Reasoning Replay Cache](../routing/REASONING_REPLAY.md)
---
@@ -148,7 +148,7 @@ Configurable via combo-level or global settings:
- **Max Messages For Summary** — How much recent history to condense
- **Summary Model** — Optional override model for generating the handoff summary
-Currently supports Codex account rotation. See [Context Relay documentation](ARCHITECTURE.md).
+Currently supports Codex account rotation. See [Context Relay documentation](../architecture/ARCHITECTURE.md).
---
@@ -161,8 +161,8 @@ Context & Cache now exposes dedicated pages for Caveman, RTK, and Compression Co
- **Compression Combos** — named pipelines such as `rtk -> caveman` assigned to routing combos; the default stacked math reaches `~89%` average and `78-95%` eligible-context savings when both engines apply
- **Raw-output recovery** — optional redacted RTK raw-output pointers for debugging compressed failures
-See [Compression Guide](COMPRESSION_GUIDE.md), [RTK Compression](RTK_COMPRESSION.md), and
-[Compression Engines](COMPRESSION_ENGINES.md).
+See [Compression Guide](../compression/COMPRESSION_GUIDE.md), [RTK Compression](../compression/RTK_COMPRESSION.md), and
+[Compression Engines](../compression/COMPRESSION_ENGINES.md).
---
diff --git a/docs/I18N.md b/docs/guides/I18N.md
similarity index 92%
rename from docs/I18N.md
rename to docs/guides/I18N.md
index c14b71a98a..7564f66197 100644
--- a/docs/I18N.md
+++ b/docs/guides/I18N.md
@@ -2,7 +2,7 @@
OmniRoute supports **30 languages** with full dashboard UI translation, translated documentation, and RTL support for Arabic and Hebrew.
-🌐 **Languages:** 🇺🇸 [English](../I18N.md) | 🇧🇷 [Português (Brasil)](./pt-BR/I18N.md) | 🇪🇸 [Español](./es/I18N.md) | 🇫🇷 [Français](./fr/I18N.md) | 🇩🇪 [Deutsch](./de/I18N.md) | 🇮🇹 [Italiano](./it/I18N.md) | 🇷🇺 [Русский](./ru/I18N.md) | 🇨🇳 [中文 (简体)](./zh-CN/I18N.md) | 🇯🇵 [日本語](./ja/I18N.md) | 🇰🇷 [한국어](./ko/I18N.md) | 🇸🇦 [العربية](./ar/I18N.md) | 🇮🇳 [हिन्दी](./hi/I18N.md) | 🇹🇭 [ไทย](./th/I18N.md) | 🇹🇷 [Türkçe](./tr/I18N.md) | 🇺🇦 [Українська](./uk-UA/I18N.md) | 🇻🇳 [Tiếng Việt](./vi/I18N.md) | 🇧🇬 [Български](./bg/I18N.md) | 🇩🇰 [Dansk](./da/I18N.md) | 🇫🇮 [Suomi](./fi/I18N.md) | 🇮🇱 [עברית](./he/I18N.md) | 🇭🇺 [Magyar](./hu/I18N.md) | 🇮🇩 [Bahasa Indonesia](./id/I18N.md) | 🇲🇾 [Bahasa Melayu](./ms/I18N.md) | 🇳🇱 [Nederlands](./nl/I18N.md) | 🇳🇴 [Norsk](./no/I18N.md) | 🇵🇹 [Português (Portugal)](./pt/I18N.md) | 🇷🇴 [Română](./ro/I18N.md) | 🇵🇱 [Polski](./pl/I18N.md) | 🇸🇰 [Slovenčina](./sk/I18N.md) | 🇸🇪 [Svenska](./sv/I18N.md) | 🇵🇭 [Filipino](./phi/I18N.md) | 🇨🇿 [Čeština](./cs/I18N.md)
+🌐 **Languages:** 🇺🇸 [English](./I18N.md) | 🇧🇷 [Português (Brasil)](./pt-BR/I18N.md) | 🇪🇸 [Español](./es/I18N.md) | 🇫🇷 [Français](./fr/I18N.md) | 🇩🇪 [Deutsch](./de/I18N.md) | 🇮🇹 [Italiano](./it/I18N.md) | 🇷🇺 [Русский](./ru/I18N.md) | 🇨🇳 [中文 (简体)](./zh-CN/I18N.md) | 🇯🇵 [日本語](./ja/I18N.md) | 🇰🇷 [한국어](./ko/I18N.md) | 🇸🇦 [العربية](./ar/I18N.md) | 🇮🇳 [हिन्दी](./hi/I18N.md) | 🇹🇭 [ไทย](./th/I18N.md) | 🇹🇷 [Türkçe](./tr/I18N.md) | 🇺🇦 [Українська](./uk-UA/I18N.md) | 🇻🇳 [Tiếng Việt](./vi/I18N.md) | 🇧🇬 [Български](./bg/I18N.md) | 🇩🇰 [Dansk](./da/I18N.md) | 🇫🇮 [Suomi](./fi/I18N.md) | 🇮🇱 [עברית](./he/I18N.md) | 🇭🇺 [Magyar](./hu/I18N.md) | 🇮🇩 [Bahasa Indonesia](./id/I18N.md) | 🇲🇾 [Bahasa Melayu](./ms/I18N.md) | 🇳🇱 [Nederlands](./nl/I18N.md) | 🇳🇴 [Norsk](./no/I18N.md) | 🇵🇹 [Português (Portugal)](./pt/I18N.md) | 🇷🇴 [Română](./ro/I18N.md) | 🇵🇱 [Polski](./pl/I18N.md) | 🇸🇰 [Slovenčina](./sk/I18N.md) | 🇸🇪 [Svenska](./sv/I18N.md) | 🇵🇭 [Filipino](./phi/I18N.md) | 🇨🇿 [Čeština](./cs/I18N.md)
## Quick Reference
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/PWA_GUIDE.md b/docs/guides/PWA_GUIDE.md
similarity index 100%
rename from docs/PWA_GUIDE.md
rename to docs/guides/PWA_GUIDE.md
diff --git a/docs/SETUP_GUIDE.md b/docs/guides/SETUP_GUIDE.md
similarity index 98%
rename from docs/SETUP_GUIDE.md
rename to docs/guides/SETUP_GUIDE.md
index fa03745643..2183af3570 100644
--- a/docs/SETUP_GUIDE.md
+++ b/docs/guides/SETUP_GUIDE.md
@@ -55,7 +55,7 @@ PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm
### Docker
-See the [Docker Guide](DOCKER_GUIDE.md) for complete Docker setup including Compose profiles and Caddy HTTPS.
+See the [Docker Guide](./DOCKER_GUIDE.md) for complete Docker setup including Compose profiles and Caddy HTTPS.
### Desktop App (Electron)
@@ -144,7 +144,7 @@ Model: if/kimi-k2-thinking (or any provider/model prefix)
Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
-For detailed per-tool configuration (Claude Code, Codex CLI, Cursor, Cline, OpenClaw, Kilo Code, Copilot, and more), see the dedicated **[CLI Tools Guide](CLI-TOOLS.md)**.
+For detailed per-tool configuration (Claude Code, Codex CLI, Cursor, Cline, OpenClaw, Kilo Code, Copilot, and more), see the dedicated **[CLI Tools Guide](../reference/CLI-TOOLS.md)**.
---
@@ -368,4 +368,4 @@ post_install() {
| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
-> For detailed uninstall instructions across all methods, see [UNINSTALL.md](UNINSTALL.md).
+> For detailed uninstall instructions across all methods, see [UNINSTALL.md](./UNINSTALL.md).
diff --git a/docs/TERMUX_GUIDE.md b/docs/guides/TERMUX_GUIDE.md
similarity index 100%
rename from docs/TERMUX_GUIDE.md
rename to docs/guides/TERMUX_GUIDE.md
diff --git a/docs/TROUBLESHOOTING.md b/docs/guides/TROUBLESHOOTING.md
similarity index 90%
rename from docs/TROUBLESHOOTING.md
rename to docs/guides/TROUBLESHOOTING.md
index c0b3577a73..4918697c5a 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/guides/TROUBLESHOOTING.md
@@ -1,6 +1,6 @@
# Troubleshooting
-🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) | 🇨🇿 [Čeština](i18n/cs/TROUBLESHOOTING.md)
+🌐 **Languages:** 🇺🇸 [English](./TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) | 🇨🇿 [Čeština](i18n/cs/TROUBLESHOOTING.md)
Common problems and solutions for OmniRoute.
@@ -447,7 +447,7 @@ Issues specific to the v3.8.0 release and their current workarounds. If a fix la
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](../architecture/ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](../reference/API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/UNINSTALL.md b/docs/guides/UNINSTALL.md
similarity index 71%
rename from docs/UNINSTALL.md
rename to docs/guides/UNINSTALL.md
index faab403be4..0d87fb711f 100644
--- a/docs/UNINSTALL.md
+++ b/docs/guides/UNINSTALL.md
@@ -1,6 +1,6 @@
# OmniRoute — Uninstall Guide
-🌐 **Languages:** 🇺🇸 [English](UNINSTALL.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/UNINSTALL.md) | 🇪🇸 [Español](i18n/es/UNINSTALL.md) | 🇫🇷 [Français](i18n/fr/UNINSTALL.md) | 🇮🇹 [Italiano](i18n/it/UNINSTALL.md) | 🇷🇺 [Русский](i18n/ru/UNINSTALL.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/UNINSTALL.md) | 🇩🇪 [Deutsch](i18n/de/UNINSTALL.md) | 🇮🇳 [हिन्दी](i18n/in/UNINSTALL.md) | 🇹🇭 [ไทย](i18n/th/UNINSTALL.md) | 🇺🇦 [Українська](i18n/uk-UA/UNINSTALL.md) | 🇸🇦 [العربية](i18n/ar/UNINSTALL.md) | 🇯🇵 [日本語](i18n/ja/UNINSTALL.md) | 🇻🇳 [Tiếng Việt](i18n/vi/UNINSTALL.md) | 🇧🇬 [Български](i18n/bg/UNINSTALL.md) | 🇩🇰 [Dansk](i18n/da/UNINSTALL.md) | 🇫🇮 [Suomi](i18n/fi/UNINSTALL.md) | 🇮🇱 [עברית](i18n/he/UNINSTALL.md) | 🇭🇺 [Magyar](i18n/hu/UNINSTALL.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/UNINSTALL.md) | 🇰🇷 [한국어](i18n/ko/UNINSTALL.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/UNINSTALL.md) | 🇳🇱 [Nederlands](i18n/nl/UNINSTALL.md) | 🇳🇴 [Norsk](i18n/no/UNINSTALL.md) | 🇵🇹 [Português (Portugal)](i18n/pt/UNINSTALL.md) | 🇷🇴 [Română](i18n/ro/UNINSTALL.md) | 🇵🇱 [Polski](i18n/pl/UNINSTALL.md) | 🇸🇰 [Slovenčina](i18n/sk/UNINSTALL.md) | 🇸🇪 [Svenska](i18n/sv/UNINSTALL.md) | 🇵🇭 [Filipino](i18n/phi/UNINSTALL.md) | 🇨🇿 [Čeština](i18n/cs/UNINSTALL.md)
+🌐 **Languages:** 🇺🇸 [English](./UNINSTALL.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/UNINSTALL.md) | 🇪🇸 [Español](i18n/es/UNINSTALL.md) | 🇫🇷 [Français](i18n/fr/UNINSTALL.md) | 🇮🇹 [Italiano](i18n/it/UNINSTALL.md) | 🇷🇺 [Русский](i18n/ru/UNINSTALL.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/UNINSTALL.md) | 🇩🇪 [Deutsch](i18n/de/UNINSTALL.md) | 🇮🇳 [हिन्दी](i18n/in/UNINSTALL.md) | 🇹🇭 [ไทย](i18n/th/UNINSTALL.md) | 🇺🇦 [Українська](i18n/uk-UA/UNINSTALL.md) | 🇸🇦 [العربية](i18n/ar/UNINSTALL.md) | 🇯🇵 [日本語](i18n/ja/UNINSTALL.md) | 🇻🇳 [Tiếng Việt](i18n/vi/UNINSTALL.md) | 🇧🇬 [Български](i18n/bg/UNINSTALL.md) | 🇩🇰 [Dansk](i18n/da/UNINSTALL.md) | 🇫🇮 [Suomi](i18n/fi/UNINSTALL.md) | 🇮🇱 [עברית](i18n/he/UNINSTALL.md) | 🇭🇺 [Magyar](i18n/hu/UNINSTALL.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/UNINSTALL.md) | 🇰🇷 [한국어](i18n/ko/UNINSTALL.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/UNINSTALL.md) | 🇳🇱 [Nederlands](i18n/nl/UNINSTALL.md) | 🇳🇴 [Norsk](i18n/no/UNINSTALL.md) | 🇵🇹 [Português (Portugal)](i18n/pt/UNINSTALL.md) | 🇷🇴 [Română](i18n/ro/UNINSTALL.md) | 🇵🇱 [Polski](i18n/pl/UNINSTALL.md) | 🇸🇰 [Slovenčina](i18n/sk/UNINSTALL.md) | 🇸🇪 [Svenska](i18n/sv/UNINSTALL.md) | 🇵🇭 [Filipino](i18n/phi/UNINSTALL.md) | 🇨🇿 [Čeština](i18n/cs/UNINSTALL.md)
This guide covers how to cleanly remove OmniRoute from your system.
diff --git a/docs/USER_GUIDE.md b/docs/guides/USER_GUIDE.md
similarity index 95%
rename from docs/USER_GUIDE.md
rename to docs/guides/USER_GUIDE.md
index d47b2cc3bd..d03b3cb5bb 100644
--- a/docs/USER_GUIDE.md
+++ b/docs/guides/USER_GUIDE.md
@@ -1,6 +1,6 @@
# User Guide
-🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) | 🇨🇿 [Čeština](i18n/cs/USER_GUIDE.md)
+🌐 **Languages:** 🇺🇸 [English](./USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) | 🇨🇿 [Čeština](i18n/cs/USER_GUIDE.md)
Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
@@ -747,7 +747,7 @@ Configure via **Dashboard → Settings → Routing**. The dashboard exposes the
| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-**Advanced combo and auto strategies** (configurable per combo or via `auto/*` prefixes — see [AUTO-COMBO.md](AUTO-COMBO.md)):
+**Advanced combo and auto strategies** (configurable per combo or via `auto/*` prefixes — see [AUTO-COMBO.md](../routing/AUTO-COMBO.md)):
- `priority` — strict order, never round-robins
- `weighted` — proportional traffic split by per-model weights
@@ -1014,7 +1014,7 @@ curl -X POST http://localhost:20128/v1/chat/completions \
}'
```
-The auto-router is fully described in [AUTO-COMBO.md](AUTO-COMBO.md) — including how to tune scoring weights, blacklist providers, and inspect routing decisions in **Dashboard → Auto Combo**.
+The auto-router is fully described in [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — including how to tune scoring weights, blacklist providers, and inspect routing decisions in **Dashboard → Auto Combo**.
---
@@ -1049,7 +1049,7 @@ Use the SSE URL `http://localhost:20128/api/mcp/sse` and a Bearer API key genera
### Scopes
-MCP tools are grouped into 10 scopes: `analytics`, `auth`, `billing`, `combos`, `health`, `keys`, `memory`, `models`, `providers`, `system`. Each Bearer key can be limited to specific scopes — see [MCP-SERVER.md](MCP-SERVER.md) for the full tool catalog and [A2A-SERVER.md](A2A-SERVER.md) for the JSON-RPC schema.
+MCP tools are grouped into 10 scopes: `analytics`, `auth`, `billing`, `combos`, `health`, `keys`, `memory`, `models`, `providers`, `system`. Each Bearer key can be limited to specific scopes — see [MCP-SERVER.md](../frameworks/MCP-SERVER.md) for the full tool catalog and [A2A-SERVER.md](../frameworks/A2A-SERVER.md) for the JSON-RPC schema.
---
@@ -1061,7 +1061,7 @@ OmniRoute exposes an extensible **skill framework** (`src/lib/skills/`) so agent
- **Per-key scopes** — Restrict which API keys can invoke which skills
- **Custom skills** — Drop a TypeScript file in `src/lib/a2a/skills/`, register it, and it becomes immediately invocable over A2A
-Full reference: [SKILLS.md](SKILLS.md).
+Full reference: [SKILLS.md](../frameworks/SKILLS.md).
---
@@ -1074,7 +1074,7 @@ OmniRoute persists **long-term conversational memory** with hybrid retrieval:
- **Automatic fact extraction** — entities, preferences, and decisions are summarized after each session and stored in the `memory_facts` table
- Memories are scoped per API key and per session
-Manage memories in **Dashboard → Memory** (search, edit, export, purge). The HTTP surface (`/api/memory/*`) lets agents push and query facts programmatically — see [MEMORY.md](MEMORY.md).
+Manage memories in **Dashboard → Memory** (search, edit, export, purge). The HTTP surface (`/api/memory/*`) lets agents push and query facts programmatically — see [MEMORY.md](../frameworks/MEMORY.md).
---
@@ -1087,7 +1087,7 @@ Subscribe to OmniRoute events for real-time monitoring and automation.
- Every payload includes `X-OmniRoute-Signature` (HMAC-SHA256) for verification
- Retries: 3 attempts with exponential backoff, then dead-letter queue
-Full schema in [WEBHOOKS.md](WEBHOOKS.md).
+Full schema in [WEBHOOKS.md](../frameworks/WEBHOOKS.md).
---
@@ -1099,7 +1099,7 @@ OmniRoute integrates with cloud coding agents (**OpenAI Codex Cloud**, **Devin**
- Track status, logs, and artifacts per task
- Bring-your-own API key per provider — credentials never leave the OmniRoute instance
-Full reference: [CLOUD_AGENT.md](CLOUD_AGENT.md).
+Full reference: [CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md).
---
@@ -1132,7 +1132,7 @@ curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUT
-d '{ "name": "ci-bot", "scopes": ["chat"] }'
```
-See [API_REFERENCE.md](API_REFERENCE.md) for the full endpoint catalog and request/response schemas.
+See [API_REFERENCE.md](../reference/API_REFERENCE.md) for the full endpoint catalog and request/response schemas.
---
diff --git a/docs/i18n/ar/CHANGELOG.md b/docs/i18n/ar/CHANGELOG.md
index 538f4faa10..eefda2a1d8 100644
--- a/docs/i18n/ar/CHANGELOG.md
+++ b/docs/i18n/ar/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/ar/CONTRIBUTING.md b/docs/i18n/ar/CONTRIBUTING.md
index 99445d9934..2f576a9f93 100644
--- a/docs/i18n/ar/CONTRIBUTING.md
+++ b/docs/i18n/ar/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/ar/README.md b/docs/i18n/ar/README.md
index 2979af725a..72df057567 100644
--- a/docs/i18n/ar/README.md
+++ b/docs/i18n/ar/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## التوثيق
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/ar/docs/ARCHITECTURE.md b/docs/i18n/ar/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/ar/docs/ARCHITECTURE.md
rename to docs/i18n/ar/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/ar/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/ar/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/ar/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/ar/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/ar/docs/A2A-SERVER.md b/docs/i18n/ar/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/ar/docs/A2A-SERVER.md
rename to docs/i18n/ar/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/ar/docs/MCP-SERVER.md b/docs/i18n/ar/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/ar/docs/MCP-SERVER.md
rename to docs/i18n/ar/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/ar/docs/FEATURES.md b/docs/i18n/ar/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/ar/docs/FEATURES.md
rename to docs/i18n/ar/docs/guides/FEATURES.md
diff --git a/docs/i18n/ar/docs/I18N.md b/docs/i18n/ar/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/ar/docs/I18N.md
rename to docs/i18n/ar/docs/guides/I18N.md
index b06c7fcfde..12c918a5c0 100644
--- a/docs/i18n/ar/docs/I18N.md
+++ b/docs/i18n/ar/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/ar/docs/TROUBLESHOOTING.md b/docs/i18n/ar/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/ar/docs/TROUBLESHOOTING.md
rename to docs/i18n/ar/docs/guides/TROUBLESHOOTING.md
index 43fb904f44..8ed817811a 100644
--- a/docs/i18n/ar/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/ar/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/ar/docs/UNINSTALL.md b/docs/i18n/ar/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/ar/docs/UNINSTALL.md
rename to docs/i18n/ar/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/ar/docs/USER_GUIDE.md b/docs/i18n/ar/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/ar/docs/USER_GUIDE.md
rename to docs/i18n/ar/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/ar/docs/COVERAGE_PLAN.md b/docs/i18n/ar/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/ar/docs/COVERAGE_PLAN.md
rename to docs/i18n/ar/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/ar/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/ar/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ar/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ar/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ar/docs/RELEASE_CHECKLIST.md b/docs/i18n/ar/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/ar/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/ar/docs/ops/RELEASE_CHECKLIST.md
index c4230bf085..755d2d1f09 100644
--- a/docs/i18n/ar/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/ar/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/ar/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ar/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ar/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ar/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ar/docs/API_REFERENCE.md b/docs/i18n/ar/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/ar/docs/API_REFERENCE.md
rename to docs/i18n/ar/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/ar/docs/CLI-TOOLS.md b/docs/i18n/ar/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/ar/docs/CLI-TOOLS.md
rename to docs/i18n/ar/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/ar/docs/ENVIRONMENT.md b/docs/i18n/ar/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/ar/docs/ENVIRONMENT.md
rename to docs/i18n/ar/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/ar/docs/AUTO-COMBO.md b/docs/i18n/ar/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/ar/docs/AUTO-COMBO.md
rename to docs/i18n/ar/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/ar/llm.txt b/docs/i18n/ar/llm.txt
index f632acf7a0..30d8e0afe8 100644
--- a/docs/i18n/ar/llm.txt
+++ b/docs/i18n/ar/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/bg/CHANGELOG.md b/docs/i18n/bg/CHANGELOG.md
index faeb5ab80c..4e0dc7fdb9 100644
--- a/docs/i18n/bg/CHANGELOG.md
+++ b/docs/i18n/bg/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/bg/CONTRIBUTING.md b/docs/i18n/bg/CONTRIBUTING.md
index 37916a0c71..4d9aee0886 100644
--- a/docs/i18n/bg/CONTRIBUTING.md
+++ b/docs/i18n/bg/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/bg/README.md b/docs/i18n/bg/README.md
index e8812921d9..5fa29ec06e 100644
--- a/docs/i18n/bg/README.md
+++ b/docs/i18n/bg/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Документация
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/bg/docs/ARCHITECTURE.md b/docs/i18n/bg/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/bg/docs/ARCHITECTURE.md
rename to docs/i18n/bg/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/bg/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/bg/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/bg/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/bg/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/bg/docs/A2A-SERVER.md b/docs/i18n/bg/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/bg/docs/A2A-SERVER.md
rename to docs/i18n/bg/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/bg/docs/MCP-SERVER.md b/docs/i18n/bg/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/bg/docs/MCP-SERVER.md
rename to docs/i18n/bg/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/bg/docs/FEATURES.md b/docs/i18n/bg/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/bg/docs/FEATURES.md
rename to docs/i18n/bg/docs/guides/FEATURES.md
diff --git a/docs/i18n/bg/docs/I18N.md b/docs/i18n/bg/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/bg/docs/I18N.md
rename to docs/i18n/bg/docs/guides/I18N.md
index 0ceaabc575..e72d17e859 100644
--- a/docs/i18n/bg/docs/I18N.md
+++ b/docs/i18n/bg/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/bg/docs/TROUBLESHOOTING.md b/docs/i18n/bg/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/bg/docs/TROUBLESHOOTING.md
rename to docs/i18n/bg/docs/guides/TROUBLESHOOTING.md
index e45a1a1257..84d2d262bc 100644
--- a/docs/i18n/bg/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/bg/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/bg/docs/UNINSTALL.md b/docs/i18n/bg/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/bg/docs/UNINSTALL.md
rename to docs/i18n/bg/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/bg/docs/USER_GUIDE.md b/docs/i18n/bg/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/bg/docs/USER_GUIDE.md
rename to docs/i18n/bg/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/bg/docs/COVERAGE_PLAN.md b/docs/i18n/bg/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/bg/docs/COVERAGE_PLAN.md
rename to docs/i18n/bg/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/bg/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/bg/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/bg/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/bg/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/bg/docs/RELEASE_CHECKLIST.md b/docs/i18n/bg/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/bg/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/bg/docs/ops/RELEASE_CHECKLIST.md
index ea33f5c610..725dbb5c2e 100644
--- a/docs/i18n/bg/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/bg/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/bg/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/bg/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/bg/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/bg/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/bg/docs/API_REFERENCE.md b/docs/i18n/bg/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/bg/docs/API_REFERENCE.md
rename to docs/i18n/bg/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/bg/docs/CLI-TOOLS.md b/docs/i18n/bg/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/bg/docs/CLI-TOOLS.md
rename to docs/i18n/bg/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/bg/docs/ENVIRONMENT.md b/docs/i18n/bg/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/bg/docs/ENVIRONMENT.md
rename to docs/i18n/bg/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/bg/docs/AUTO-COMBO.md b/docs/i18n/bg/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/bg/docs/AUTO-COMBO.md
rename to docs/i18n/bg/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/bg/llm.txt b/docs/i18n/bg/llm.txt
index a3cf0bc811..d752b57e3e 100644
--- a/docs/i18n/bg/llm.txt
+++ b/docs/i18n/bg/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/bn/CHANGELOG.md b/docs/i18n/bn/CHANGELOG.md
index ff78a5c462..571671965b 100644
--- a/docs/i18n/bn/CHANGELOG.md
+++ b/docs/i18n/bn/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/bn/CONTRIBUTING.md b/docs/i18n/bn/CONTRIBUTING.md
index c1b2e77012..94f31022e0 100644
--- a/docs/i18n/bn/CONTRIBUTING.md
+++ b/docs/i18n/bn/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/bn/README.md b/docs/i18n/bn/README.md
index bc77d9bbcf..af9bdf9703 100644
--- a/docs/i18n/bn/README.md
+++ b/docs/i18n/bn/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentación
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/bn/docs/ARCHITECTURE.md b/docs/i18n/bn/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/bn/docs/ARCHITECTURE.md
rename to docs/i18n/bn/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/bn/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/bn/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/bn/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/bn/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/bn/docs/A2A-SERVER.md b/docs/i18n/bn/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/bn/docs/A2A-SERVER.md
rename to docs/i18n/bn/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/bn/docs/MCP-SERVER.md b/docs/i18n/bn/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/bn/docs/MCP-SERVER.md
rename to docs/i18n/bn/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/bn/docs/FEATURES.md b/docs/i18n/bn/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/bn/docs/FEATURES.md
rename to docs/i18n/bn/docs/guides/FEATURES.md
diff --git a/docs/i18n/bn/docs/I18N.md b/docs/i18n/bn/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/bn/docs/I18N.md
rename to docs/i18n/bn/docs/guides/I18N.md
index 0bfd210478..f1a5ad5def 100644
--- a/docs/i18n/bn/docs/I18N.md
+++ b/docs/i18n/bn/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/bn/docs/TROUBLESHOOTING.md b/docs/i18n/bn/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/bn/docs/TROUBLESHOOTING.md
rename to docs/i18n/bn/docs/guides/TROUBLESHOOTING.md
index 93e367deb6..e1d40bff3f 100644
--- a/docs/i18n/bn/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/bn/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/bn/docs/UNINSTALL.md b/docs/i18n/bn/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/bn/docs/UNINSTALL.md
rename to docs/i18n/bn/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/bn/docs/USER_GUIDE.md b/docs/i18n/bn/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/bn/docs/USER_GUIDE.md
rename to docs/i18n/bn/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/bn/docs/COVERAGE_PLAN.md b/docs/i18n/bn/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/bn/docs/COVERAGE_PLAN.md
rename to docs/i18n/bn/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/bn/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/bn/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/bn/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/bn/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/bn/docs/RELEASE_CHECKLIST.md b/docs/i18n/bn/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/bn/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/bn/docs/ops/RELEASE_CHECKLIST.md
index 035f637fb9..adc8b94d58 100644
--- a/docs/i18n/bn/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/bn/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/bn/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/bn/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/bn/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/bn/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/bn/docs/API_REFERENCE.md b/docs/i18n/bn/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/bn/docs/API_REFERENCE.md
rename to docs/i18n/bn/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/bn/docs/CLI-TOOLS.md b/docs/i18n/bn/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/bn/docs/CLI-TOOLS.md
rename to docs/i18n/bn/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/bn/docs/ENVIRONMENT.md b/docs/i18n/bn/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/bn/docs/ENVIRONMENT.md
rename to docs/i18n/bn/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/bn/docs/AUTO-COMBO.md b/docs/i18n/bn/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/bn/docs/AUTO-COMBO.md
rename to docs/i18n/bn/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/bn/llm.txt b/docs/i18n/bn/llm.txt
index 3e3a618682..5390b06bf3 100644
--- a/docs/i18n/bn/llm.txt
+++ b/docs/i18n/bn/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/cs/CHANGELOG.md b/docs/i18n/cs/CHANGELOG.md
index 81f60f41a1..66d6e4d36e 100644
--- a/docs/i18n/cs/CHANGELOG.md
+++ b/docs/i18n/cs/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/cs/CONTRIBUTING.md b/docs/i18n/cs/CONTRIBUTING.md
index 1621756f93..1f739e5a3c 100644
--- a/docs/i18n/cs/CONTRIBUTING.md
+++ b/docs/i18n/cs/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/cs/README.md b/docs/i18n/cs/README.md
index 50f1ba2567..4595656fe9 100644
--- a/docs/i18n/cs/README.md
+++ b/docs/i18n/cs/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Dokumentace
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/cs/docs/ARCHITECTURE.md b/docs/i18n/cs/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/cs/docs/ARCHITECTURE.md
rename to docs/i18n/cs/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/cs/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/cs/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/cs/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/cs/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/cs/docs/A2A-SERVER.md b/docs/i18n/cs/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/cs/docs/A2A-SERVER.md
rename to docs/i18n/cs/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/cs/docs/MCP-SERVER.md b/docs/i18n/cs/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/cs/docs/MCP-SERVER.md
rename to docs/i18n/cs/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/cs/docs/FEATURES.md b/docs/i18n/cs/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/cs/docs/FEATURES.md
rename to docs/i18n/cs/docs/guides/FEATURES.md
diff --git a/docs/i18n/cs/docs/I18N.md b/docs/i18n/cs/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/cs/docs/I18N.md
rename to docs/i18n/cs/docs/guides/I18N.md
index 3a15f4f051..ccf62650b5 100644
--- a/docs/i18n/cs/docs/I18N.md
+++ b/docs/i18n/cs/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/cs/docs/TROUBLESHOOTING.md b/docs/i18n/cs/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/cs/docs/TROUBLESHOOTING.md
rename to docs/i18n/cs/docs/guides/TROUBLESHOOTING.md
index 7846a571e7..d4562b2259 100644
--- a/docs/i18n/cs/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/cs/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/cs/docs/UNINSTALL.md b/docs/i18n/cs/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/cs/docs/UNINSTALL.md
rename to docs/i18n/cs/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/cs/docs/USER_GUIDE.md b/docs/i18n/cs/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/cs/docs/USER_GUIDE.md
rename to docs/i18n/cs/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/cs/docs/COVERAGE_PLAN.md b/docs/i18n/cs/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/cs/docs/COVERAGE_PLAN.md
rename to docs/i18n/cs/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/cs/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/cs/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/cs/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/cs/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/cs/docs/RELEASE_CHECKLIST.md b/docs/i18n/cs/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/cs/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/cs/docs/ops/RELEASE_CHECKLIST.md
index 3357cc9ff7..6c09e74932 100644
--- a/docs/i18n/cs/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/cs/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/cs/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/cs/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/cs/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/cs/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/cs/docs/API_REFERENCE.md b/docs/i18n/cs/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/cs/docs/API_REFERENCE.md
rename to docs/i18n/cs/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/cs/docs/CLI-TOOLS.md b/docs/i18n/cs/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/cs/docs/CLI-TOOLS.md
rename to docs/i18n/cs/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/cs/docs/ENVIRONMENT.md b/docs/i18n/cs/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/cs/docs/ENVIRONMENT.md
rename to docs/i18n/cs/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/cs/docs/AUTO-COMBO.md b/docs/i18n/cs/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/cs/docs/AUTO-COMBO.md
rename to docs/i18n/cs/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/cs/llm.txt b/docs/i18n/cs/llm.txt
index d75cfb0f73..7c1d81ff91 100644
--- a/docs/i18n/cs/llm.txt
+++ b/docs/i18n/cs/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/da/CHANGELOG.md b/docs/i18n/da/CHANGELOG.md
index 9cf4b6a14a..3233dde285 100644
--- a/docs/i18n/da/CHANGELOG.md
+++ b/docs/i18n/da/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/da/CONTRIBUTING.md b/docs/i18n/da/CONTRIBUTING.md
index d70bd4813a..4b27f5e962 100644
--- a/docs/i18n/da/CONTRIBUTING.md
+++ b/docs/i18n/da/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/da/README.md b/docs/i18n/da/README.md
index 9a88f9af24..39f75a1bf7 100644
--- a/docs/i18n/da/README.md
+++ b/docs/i18n/da/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Dokumentation
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/da/docs/ARCHITECTURE.md b/docs/i18n/da/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/da/docs/ARCHITECTURE.md
rename to docs/i18n/da/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/da/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/da/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/da/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/da/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/da/docs/A2A-SERVER.md b/docs/i18n/da/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/da/docs/A2A-SERVER.md
rename to docs/i18n/da/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/da/docs/MCP-SERVER.md b/docs/i18n/da/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/da/docs/MCP-SERVER.md
rename to docs/i18n/da/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/da/docs/FEATURES.md b/docs/i18n/da/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/da/docs/FEATURES.md
rename to docs/i18n/da/docs/guides/FEATURES.md
diff --git a/docs/i18n/da/docs/I18N.md b/docs/i18n/da/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/da/docs/I18N.md
rename to docs/i18n/da/docs/guides/I18N.md
index 506128beaf..54632fa3f3 100644
--- a/docs/i18n/da/docs/I18N.md
+++ b/docs/i18n/da/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/da/docs/TROUBLESHOOTING.md b/docs/i18n/da/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/da/docs/TROUBLESHOOTING.md
rename to docs/i18n/da/docs/guides/TROUBLESHOOTING.md
index 28962ce9e6..82639d666e 100644
--- a/docs/i18n/da/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/da/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/da/docs/UNINSTALL.md b/docs/i18n/da/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/da/docs/UNINSTALL.md
rename to docs/i18n/da/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/da/docs/USER_GUIDE.md b/docs/i18n/da/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/da/docs/USER_GUIDE.md
rename to docs/i18n/da/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/da/docs/COVERAGE_PLAN.md b/docs/i18n/da/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/da/docs/COVERAGE_PLAN.md
rename to docs/i18n/da/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/da/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/da/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/da/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/da/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/da/docs/RELEASE_CHECKLIST.md b/docs/i18n/da/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/da/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/da/docs/ops/RELEASE_CHECKLIST.md
index cff8961e27..8e07b36937 100644
--- a/docs/i18n/da/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/da/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/da/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/da/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/da/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/da/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/da/docs/API_REFERENCE.md b/docs/i18n/da/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/da/docs/API_REFERENCE.md
rename to docs/i18n/da/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/da/docs/CLI-TOOLS.md b/docs/i18n/da/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/da/docs/CLI-TOOLS.md
rename to docs/i18n/da/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/da/docs/ENVIRONMENT.md b/docs/i18n/da/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/da/docs/ENVIRONMENT.md
rename to docs/i18n/da/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/da/docs/AUTO-COMBO.md b/docs/i18n/da/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/da/docs/AUTO-COMBO.md
rename to docs/i18n/da/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/da/llm.txt b/docs/i18n/da/llm.txt
index ac343ef264..5b779adac3 100644
--- a/docs/i18n/da/llm.txt
+++ b/docs/i18n/da/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/de/CHANGELOG.md b/docs/i18n/de/CHANGELOG.md
index 3ac010af16..3fe31391c0 100644
--- a/docs/i18n/de/CHANGELOG.md
+++ b/docs/i18n/de/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/de/CONTRIBUTING.md b/docs/i18n/de/CONTRIBUTING.md
index 5497d29106..37ed7ce173 100644
--- a/docs/i18n/de/CONTRIBUTING.md
+++ b/docs/i18n/de/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/de/README.md b/docs/i18n/de/README.md
index 2db62bf6c2..6834c1de04 100644
--- a/docs/i18n/de/README.md
+++ b/docs/i18n/de/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Dokumentation
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/de/docs/ARCHITECTURE.md b/docs/i18n/de/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/de/docs/ARCHITECTURE.md
rename to docs/i18n/de/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/de/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/de/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/de/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/de/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/de/docs/A2A-SERVER.md b/docs/i18n/de/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/de/docs/A2A-SERVER.md
rename to docs/i18n/de/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/de/docs/MCP-SERVER.md b/docs/i18n/de/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/de/docs/MCP-SERVER.md
rename to docs/i18n/de/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/de/docs/FEATURES.md b/docs/i18n/de/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/de/docs/FEATURES.md
rename to docs/i18n/de/docs/guides/FEATURES.md
diff --git a/docs/i18n/de/docs/I18N.md b/docs/i18n/de/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/de/docs/I18N.md
rename to docs/i18n/de/docs/guides/I18N.md
index 84097d26c7..4236e2c2ee 100644
--- a/docs/i18n/de/docs/I18N.md
+++ b/docs/i18n/de/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/de/docs/TROUBLESHOOTING.md b/docs/i18n/de/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/de/docs/TROUBLESHOOTING.md
rename to docs/i18n/de/docs/guides/TROUBLESHOOTING.md
index 7cf0a646e8..d7873c8243 100644
--- a/docs/i18n/de/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/de/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/de/docs/UNINSTALL.md b/docs/i18n/de/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/de/docs/UNINSTALL.md
rename to docs/i18n/de/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/de/docs/USER_GUIDE.md b/docs/i18n/de/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/de/docs/USER_GUIDE.md
rename to docs/i18n/de/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/de/docs/COVERAGE_PLAN.md b/docs/i18n/de/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/de/docs/COVERAGE_PLAN.md
rename to docs/i18n/de/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/de/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/de/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/de/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/de/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/de/docs/RELEASE_CHECKLIST.md b/docs/i18n/de/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/de/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/de/docs/ops/RELEASE_CHECKLIST.md
index 3f69840951..f4eb8a8402 100644
--- a/docs/i18n/de/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/de/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/de/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/de/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/de/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/de/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/de/docs/API_REFERENCE.md b/docs/i18n/de/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/de/docs/API_REFERENCE.md
rename to docs/i18n/de/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/de/docs/CLI-TOOLS.md b/docs/i18n/de/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/de/docs/CLI-TOOLS.md
rename to docs/i18n/de/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/de/docs/ENVIRONMENT.md b/docs/i18n/de/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/de/docs/ENVIRONMENT.md
rename to docs/i18n/de/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/de/docs/AUTO-COMBO.md b/docs/i18n/de/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/de/docs/AUTO-COMBO.md
rename to docs/i18n/de/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/de/llm.txt b/docs/i18n/de/llm.txt
index 55c98f2226..db7fd0b695 100644
--- a/docs/i18n/de/llm.txt
+++ b/docs/i18n/de/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/es/CHANGELOG.md b/docs/i18n/es/CHANGELOG.md
index 913b323c61..1c039bb37e 100644
--- a/docs/i18n/es/CHANGELOG.md
+++ b/docs/i18n/es/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/es/CONTRIBUTING.md b/docs/i18n/es/CONTRIBUTING.md
index e5f054b239..b8ac893ed2 100644
--- a/docs/i18n/es/CONTRIBUTING.md
+++ b/docs/i18n/es/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/es/README.md b/docs/i18n/es/README.md
index 6ecc419bbd..00609d63d5 100644
--- a/docs/i18n/es/README.md
+++ b/docs/i18n/es/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentación
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/es/docs/ARCHITECTURE.md b/docs/i18n/es/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/es/docs/ARCHITECTURE.md
rename to docs/i18n/es/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/es/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/es/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/es/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/es/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/es/docs/A2A-SERVER.md b/docs/i18n/es/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/es/docs/A2A-SERVER.md
rename to docs/i18n/es/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/es/docs/MCP-SERVER.md b/docs/i18n/es/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/es/docs/MCP-SERVER.md
rename to docs/i18n/es/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/es/docs/FEATURES.md b/docs/i18n/es/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/es/docs/FEATURES.md
rename to docs/i18n/es/docs/guides/FEATURES.md
diff --git a/docs/i18n/es/docs/I18N.md b/docs/i18n/es/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/es/docs/I18N.md
rename to docs/i18n/es/docs/guides/I18N.md
index 628065c212..c9f3a93945 100644
--- a/docs/i18n/es/docs/I18N.md
+++ b/docs/i18n/es/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/es/docs/TROUBLESHOOTING.md b/docs/i18n/es/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/es/docs/TROUBLESHOOTING.md
rename to docs/i18n/es/docs/guides/TROUBLESHOOTING.md
index fc65ae406a..bd261b22d2 100644
--- a/docs/i18n/es/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/es/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/es/docs/UNINSTALL.md b/docs/i18n/es/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/es/docs/UNINSTALL.md
rename to docs/i18n/es/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/es/docs/USER_GUIDE.md b/docs/i18n/es/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/es/docs/USER_GUIDE.md
rename to docs/i18n/es/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/es/docs/COVERAGE_PLAN.md b/docs/i18n/es/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/es/docs/COVERAGE_PLAN.md
rename to docs/i18n/es/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/es/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/es/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/es/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/es/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/es/docs/RELEASE_CHECKLIST.md b/docs/i18n/es/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/es/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/es/docs/ops/RELEASE_CHECKLIST.md
index 2d4c11840e..7f0e5ff56d 100644
--- a/docs/i18n/es/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/es/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/es/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/es/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/es/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/es/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/es/docs/API_REFERENCE.md b/docs/i18n/es/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/es/docs/API_REFERENCE.md
rename to docs/i18n/es/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/es/docs/CLI-TOOLS.md b/docs/i18n/es/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/es/docs/CLI-TOOLS.md
rename to docs/i18n/es/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/es/docs/ENVIRONMENT.md b/docs/i18n/es/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/es/docs/ENVIRONMENT.md
rename to docs/i18n/es/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/es/docs/AUTO-COMBO.md b/docs/i18n/es/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/es/docs/AUTO-COMBO.md
rename to docs/i18n/es/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/es/llm.txt b/docs/i18n/es/llm.txt
index 2dbf99212d..d822c3352e 100644
--- a/docs/i18n/es/llm.txt
+++ b/docs/i18n/es/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/fa/CHANGELOG.md b/docs/i18n/fa/CHANGELOG.md
index bcfe7dd067..c620c1adda 100644
--- a/docs/i18n/fa/CHANGELOG.md
+++ b/docs/i18n/fa/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/fa/CONTRIBUTING.md b/docs/i18n/fa/CONTRIBUTING.md
index 30a6e8caba..d57949243e 100644
--- a/docs/i18n/fa/CONTRIBUTING.md
+++ b/docs/i18n/fa/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/fa/README.md b/docs/i18n/fa/README.md
index 57b1f66938..74436b40be 100644
--- a/docs/i18n/fa/README.md
+++ b/docs/i18n/fa/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentación
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/fa/docs/ARCHITECTURE.md b/docs/i18n/fa/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/fa/docs/ARCHITECTURE.md
rename to docs/i18n/fa/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/fa/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/fa/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/fa/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/fa/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/fa/docs/A2A-SERVER.md b/docs/i18n/fa/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/fa/docs/A2A-SERVER.md
rename to docs/i18n/fa/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/fa/docs/MCP-SERVER.md b/docs/i18n/fa/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/fa/docs/MCP-SERVER.md
rename to docs/i18n/fa/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/fa/docs/FEATURES.md b/docs/i18n/fa/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/fa/docs/FEATURES.md
rename to docs/i18n/fa/docs/guides/FEATURES.md
diff --git a/docs/i18n/fa/docs/I18N.md b/docs/i18n/fa/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/fa/docs/I18N.md
rename to docs/i18n/fa/docs/guides/I18N.md
index fd8a3bce37..00d108904a 100644
--- a/docs/i18n/fa/docs/I18N.md
+++ b/docs/i18n/fa/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/fa/docs/TROUBLESHOOTING.md b/docs/i18n/fa/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/fa/docs/TROUBLESHOOTING.md
rename to docs/i18n/fa/docs/guides/TROUBLESHOOTING.md
index e573b1b007..2c0ee1b9c1 100644
--- a/docs/i18n/fa/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/fa/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/fa/docs/UNINSTALL.md b/docs/i18n/fa/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/fa/docs/UNINSTALL.md
rename to docs/i18n/fa/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/fa/docs/USER_GUIDE.md b/docs/i18n/fa/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/fa/docs/USER_GUIDE.md
rename to docs/i18n/fa/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/fa/docs/COVERAGE_PLAN.md b/docs/i18n/fa/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/fa/docs/COVERAGE_PLAN.md
rename to docs/i18n/fa/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/fa/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/fa/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/fa/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/fa/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/fa/docs/RELEASE_CHECKLIST.md b/docs/i18n/fa/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/fa/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/fa/docs/ops/RELEASE_CHECKLIST.md
index 545a1c7eb9..8193817209 100644
--- a/docs/i18n/fa/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/fa/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/fa/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/fa/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/fa/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/fa/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/fa/docs/API_REFERENCE.md b/docs/i18n/fa/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/fa/docs/API_REFERENCE.md
rename to docs/i18n/fa/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/fa/docs/CLI-TOOLS.md b/docs/i18n/fa/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/fa/docs/CLI-TOOLS.md
rename to docs/i18n/fa/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/fa/docs/ENVIRONMENT.md b/docs/i18n/fa/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/fa/docs/ENVIRONMENT.md
rename to docs/i18n/fa/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/fa/docs/AUTO-COMBO.md b/docs/i18n/fa/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/fa/docs/AUTO-COMBO.md
rename to docs/i18n/fa/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/fa/llm.txt b/docs/i18n/fa/llm.txt
index 43d14c5164..a0da959704 100644
--- a/docs/i18n/fa/llm.txt
+++ b/docs/i18n/fa/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/fi/CHANGELOG.md b/docs/i18n/fi/CHANGELOG.md
index f7f5a57c95..3b254b82f9 100644
--- a/docs/i18n/fi/CHANGELOG.md
+++ b/docs/i18n/fi/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/fi/CONTRIBUTING.md b/docs/i18n/fi/CONTRIBUTING.md
index 92e4f26deb..4f717a16e0 100644
--- a/docs/i18n/fi/CONTRIBUTING.md
+++ b/docs/i18n/fi/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/fi/README.md b/docs/i18n/fi/README.md
index c74cafde9a..7fb1ace251 100644
--- a/docs/i18n/fi/README.md
+++ b/docs/i18n/fi/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Dokumentaatio
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/fi/docs/ARCHITECTURE.md b/docs/i18n/fi/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/fi/docs/ARCHITECTURE.md
rename to docs/i18n/fi/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/fi/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/fi/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/fi/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/fi/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/fi/docs/A2A-SERVER.md b/docs/i18n/fi/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/fi/docs/A2A-SERVER.md
rename to docs/i18n/fi/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/fi/docs/MCP-SERVER.md b/docs/i18n/fi/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/fi/docs/MCP-SERVER.md
rename to docs/i18n/fi/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/fi/docs/FEATURES.md b/docs/i18n/fi/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/fi/docs/FEATURES.md
rename to docs/i18n/fi/docs/guides/FEATURES.md
diff --git a/docs/i18n/fi/docs/I18N.md b/docs/i18n/fi/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/fi/docs/I18N.md
rename to docs/i18n/fi/docs/guides/I18N.md
index 7ef69aba8f..f75d692c16 100644
--- a/docs/i18n/fi/docs/I18N.md
+++ b/docs/i18n/fi/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/fi/docs/TROUBLESHOOTING.md b/docs/i18n/fi/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/fi/docs/TROUBLESHOOTING.md
rename to docs/i18n/fi/docs/guides/TROUBLESHOOTING.md
index a4a2994239..52ebbb2a8d 100644
--- a/docs/i18n/fi/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/fi/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/fi/docs/UNINSTALL.md b/docs/i18n/fi/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/fi/docs/UNINSTALL.md
rename to docs/i18n/fi/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/fi/docs/USER_GUIDE.md b/docs/i18n/fi/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/fi/docs/USER_GUIDE.md
rename to docs/i18n/fi/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/fi/docs/COVERAGE_PLAN.md b/docs/i18n/fi/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/fi/docs/COVERAGE_PLAN.md
rename to docs/i18n/fi/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/fi/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/fi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/fi/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/fi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/fi/docs/RELEASE_CHECKLIST.md b/docs/i18n/fi/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/fi/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/fi/docs/ops/RELEASE_CHECKLIST.md
index a83ed9f9f2..12ae28efb8 100644
--- a/docs/i18n/fi/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/fi/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/fi/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/fi/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/fi/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/fi/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/fi/docs/API_REFERENCE.md b/docs/i18n/fi/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/fi/docs/API_REFERENCE.md
rename to docs/i18n/fi/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/fi/docs/CLI-TOOLS.md b/docs/i18n/fi/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/fi/docs/CLI-TOOLS.md
rename to docs/i18n/fi/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/fi/docs/ENVIRONMENT.md b/docs/i18n/fi/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/fi/docs/ENVIRONMENT.md
rename to docs/i18n/fi/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/fi/docs/AUTO-COMBO.md b/docs/i18n/fi/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/fi/docs/AUTO-COMBO.md
rename to docs/i18n/fi/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/fi/llm.txt b/docs/i18n/fi/llm.txt
index 3b8fd6ceb2..d955612ef5 100644
--- a/docs/i18n/fi/llm.txt
+++ b/docs/i18n/fi/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/fr/CHANGELOG.md b/docs/i18n/fr/CHANGELOG.md
index 14f650e21f..280428cc05 100644
--- a/docs/i18n/fr/CHANGELOG.md
+++ b/docs/i18n/fr/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/fr/CONTRIBUTING.md b/docs/i18n/fr/CONTRIBUTING.md
index 01170fa187..53d22d8c58 100644
--- a/docs/i18n/fr/CONTRIBUTING.md
+++ b/docs/i18n/fr/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/fr/README.md b/docs/i18n/fr/README.md
index 8648ea364e..4621a0d668 100644
--- a/docs/i18n/fr/README.md
+++ b/docs/i18n/fr/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentation
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/fr/docs/ARCHITECTURE.md b/docs/i18n/fr/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/fr/docs/ARCHITECTURE.md
rename to docs/i18n/fr/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/fr/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/fr/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/fr/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/fr/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/fr/docs/A2A-SERVER.md b/docs/i18n/fr/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/fr/docs/A2A-SERVER.md
rename to docs/i18n/fr/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/fr/docs/MCP-SERVER.md b/docs/i18n/fr/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/fr/docs/MCP-SERVER.md
rename to docs/i18n/fr/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/fr/docs/FEATURES.md b/docs/i18n/fr/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/fr/docs/FEATURES.md
rename to docs/i18n/fr/docs/guides/FEATURES.md
diff --git a/docs/i18n/fr/docs/I18N.md b/docs/i18n/fr/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/fr/docs/I18N.md
rename to docs/i18n/fr/docs/guides/I18N.md
index 6e3741d440..2e7c2f2451 100644
--- a/docs/i18n/fr/docs/I18N.md
+++ b/docs/i18n/fr/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/fr/docs/TROUBLESHOOTING.md b/docs/i18n/fr/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/fr/docs/TROUBLESHOOTING.md
rename to docs/i18n/fr/docs/guides/TROUBLESHOOTING.md
index 8f6f96dc22..b5483677da 100644
--- a/docs/i18n/fr/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/fr/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/fr/docs/UNINSTALL.md b/docs/i18n/fr/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/fr/docs/UNINSTALL.md
rename to docs/i18n/fr/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/fr/docs/USER_GUIDE.md b/docs/i18n/fr/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/fr/docs/USER_GUIDE.md
rename to docs/i18n/fr/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/fr/docs/COVERAGE_PLAN.md b/docs/i18n/fr/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/fr/docs/COVERAGE_PLAN.md
rename to docs/i18n/fr/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/fr/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/fr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/fr/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/fr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/fr/docs/RELEASE_CHECKLIST.md b/docs/i18n/fr/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/fr/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/fr/docs/ops/RELEASE_CHECKLIST.md
index 060f96aed5..d0e8d91740 100644
--- a/docs/i18n/fr/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/fr/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/fr/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/fr/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/fr/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/fr/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/fr/docs/API_REFERENCE.md b/docs/i18n/fr/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/fr/docs/API_REFERENCE.md
rename to docs/i18n/fr/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/fr/docs/CLI-TOOLS.md b/docs/i18n/fr/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/fr/docs/CLI-TOOLS.md
rename to docs/i18n/fr/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/fr/docs/ENVIRONMENT.md b/docs/i18n/fr/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/fr/docs/ENVIRONMENT.md
rename to docs/i18n/fr/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/fr/docs/AUTO-COMBO.md b/docs/i18n/fr/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/fr/docs/AUTO-COMBO.md
rename to docs/i18n/fr/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/fr/llm.txt b/docs/i18n/fr/llm.txt
index 3805843928..d7605da05a 100644
--- a/docs/i18n/fr/llm.txt
+++ b/docs/i18n/fr/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/gu/CHANGELOG.md b/docs/i18n/gu/CHANGELOG.md
index 2349d186b8..ff126fc75f 100644
--- a/docs/i18n/gu/CHANGELOG.md
+++ b/docs/i18n/gu/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/gu/CONTRIBUTING.md b/docs/i18n/gu/CONTRIBUTING.md
index 18ee49601d..e59338a470 100644
--- a/docs/i18n/gu/CONTRIBUTING.md
+++ b/docs/i18n/gu/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/gu/README.md b/docs/i18n/gu/README.md
index 000aa2895c..ab7af0355a 100644
--- a/docs/i18n/gu/README.md
+++ b/docs/i18n/gu/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentación
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/gu/docs/ARCHITECTURE.md b/docs/i18n/gu/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/gu/docs/ARCHITECTURE.md
rename to docs/i18n/gu/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/gu/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/gu/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/gu/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/gu/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/gu/docs/A2A-SERVER.md b/docs/i18n/gu/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/gu/docs/A2A-SERVER.md
rename to docs/i18n/gu/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/gu/docs/MCP-SERVER.md b/docs/i18n/gu/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/gu/docs/MCP-SERVER.md
rename to docs/i18n/gu/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/gu/docs/FEATURES.md b/docs/i18n/gu/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/gu/docs/FEATURES.md
rename to docs/i18n/gu/docs/guides/FEATURES.md
diff --git a/docs/i18n/gu/docs/I18N.md b/docs/i18n/gu/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/gu/docs/I18N.md
rename to docs/i18n/gu/docs/guides/I18N.md
index 5888d16a6b..9c5d55e353 100644
--- a/docs/i18n/gu/docs/I18N.md
+++ b/docs/i18n/gu/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/gu/docs/TROUBLESHOOTING.md b/docs/i18n/gu/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/gu/docs/TROUBLESHOOTING.md
rename to docs/i18n/gu/docs/guides/TROUBLESHOOTING.md
index 5d46baabbe..72735de524 100644
--- a/docs/i18n/gu/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/gu/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/gu/docs/UNINSTALL.md b/docs/i18n/gu/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/gu/docs/UNINSTALL.md
rename to docs/i18n/gu/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/gu/docs/USER_GUIDE.md b/docs/i18n/gu/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/gu/docs/USER_GUIDE.md
rename to docs/i18n/gu/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/gu/docs/COVERAGE_PLAN.md b/docs/i18n/gu/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/gu/docs/COVERAGE_PLAN.md
rename to docs/i18n/gu/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/gu/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/gu/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/gu/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/gu/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/gu/docs/RELEASE_CHECKLIST.md b/docs/i18n/gu/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/gu/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/gu/docs/ops/RELEASE_CHECKLIST.md
index 9958ba56db..19b13c7330 100644
--- a/docs/i18n/gu/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/gu/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/gu/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/gu/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/gu/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/gu/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/gu/docs/API_REFERENCE.md b/docs/i18n/gu/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/gu/docs/API_REFERENCE.md
rename to docs/i18n/gu/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/gu/docs/CLI-TOOLS.md b/docs/i18n/gu/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/gu/docs/CLI-TOOLS.md
rename to docs/i18n/gu/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/gu/docs/ENVIRONMENT.md b/docs/i18n/gu/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/gu/docs/ENVIRONMENT.md
rename to docs/i18n/gu/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/gu/docs/AUTO-COMBO.md b/docs/i18n/gu/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/gu/docs/AUTO-COMBO.md
rename to docs/i18n/gu/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/gu/llm.txt b/docs/i18n/gu/llm.txt
index efdebba7db..b264d4bd77 100644
--- a/docs/i18n/gu/llm.txt
+++ b/docs/i18n/gu/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/he/CHANGELOG.md b/docs/i18n/he/CHANGELOG.md
index 86de7f2cd1..4a3b9155ba 100644
--- a/docs/i18n/he/CHANGELOG.md
+++ b/docs/i18n/he/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/he/CONTRIBUTING.md b/docs/i18n/he/CONTRIBUTING.md
index 41057457dd..9601204b67 100644
--- a/docs/i18n/he/CONTRIBUTING.md
+++ b/docs/i18n/he/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/he/README.md b/docs/i18n/he/README.md
index a3f9901683..a3284424a3 100644
--- a/docs/i18n/he/README.md
+++ b/docs/i18n/he/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## תיעוד
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/he/docs/ARCHITECTURE.md b/docs/i18n/he/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/he/docs/ARCHITECTURE.md
rename to docs/i18n/he/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/he/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/he/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/he/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/he/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/he/docs/A2A-SERVER.md b/docs/i18n/he/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/he/docs/A2A-SERVER.md
rename to docs/i18n/he/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/he/docs/MCP-SERVER.md b/docs/i18n/he/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/he/docs/MCP-SERVER.md
rename to docs/i18n/he/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/he/docs/FEATURES.md b/docs/i18n/he/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/he/docs/FEATURES.md
rename to docs/i18n/he/docs/guides/FEATURES.md
diff --git a/docs/i18n/he/docs/I18N.md b/docs/i18n/he/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/he/docs/I18N.md
rename to docs/i18n/he/docs/guides/I18N.md
index 1c2907f68d..02db6a375e 100644
--- a/docs/i18n/he/docs/I18N.md
+++ b/docs/i18n/he/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/he/docs/TROUBLESHOOTING.md b/docs/i18n/he/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/he/docs/TROUBLESHOOTING.md
rename to docs/i18n/he/docs/guides/TROUBLESHOOTING.md
index 19c167b042..083e96091b 100644
--- a/docs/i18n/he/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/he/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/he/docs/UNINSTALL.md b/docs/i18n/he/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/he/docs/UNINSTALL.md
rename to docs/i18n/he/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/he/docs/USER_GUIDE.md b/docs/i18n/he/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/he/docs/USER_GUIDE.md
rename to docs/i18n/he/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/he/docs/COVERAGE_PLAN.md b/docs/i18n/he/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/he/docs/COVERAGE_PLAN.md
rename to docs/i18n/he/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/he/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/he/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/he/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/he/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/he/docs/RELEASE_CHECKLIST.md b/docs/i18n/he/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/he/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/he/docs/ops/RELEASE_CHECKLIST.md
index 5962d37525..e9c052da06 100644
--- a/docs/i18n/he/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/he/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/he/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/he/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/he/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/he/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/he/docs/API_REFERENCE.md b/docs/i18n/he/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/he/docs/API_REFERENCE.md
rename to docs/i18n/he/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/he/docs/CLI-TOOLS.md b/docs/i18n/he/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/he/docs/CLI-TOOLS.md
rename to docs/i18n/he/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/he/docs/ENVIRONMENT.md b/docs/i18n/he/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/he/docs/ENVIRONMENT.md
rename to docs/i18n/he/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/he/docs/AUTO-COMBO.md b/docs/i18n/he/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/he/docs/AUTO-COMBO.md
rename to docs/i18n/he/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/he/llm.txt b/docs/i18n/he/llm.txt
index ea3add4736..96aa52741c 100644
--- a/docs/i18n/he/llm.txt
+++ b/docs/i18n/he/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/hi/CHANGELOG.md b/docs/i18n/hi/CHANGELOG.md
index bbbbfd6766..9062bf5e09 100644
--- a/docs/i18n/hi/CHANGELOG.md
+++ b/docs/i18n/hi/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/hi/CONTRIBUTING.md b/docs/i18n/hi/CONTRIBUTING.md
index 2a03264ea0..a2b59099b8 100644
--- a/docs/i18n/hi/CONTRIBUTING.md
+++ b/docs/i18n/hi/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/hi/README.md b/docs/i18n/hi/README.md
index be8b2e4647..e9150cc01a 100644
--- a/docs/i18n/hi/README.md
+++ b/docs/i18n/hi/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## दस्तावेज़
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/hi/docs/ARCHITECTURE.md b/docs/i18n/hi/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/hi/docs/ARCHITECTURE.md
rename to docs/i18n/hi/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/hi/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/hi/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/hi/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/hi/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/hi/docs/A2A-SERVER.md b/docs/i18n/hi/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/hi/docs/A2A-SERVER.md
rename to docs/i18n/hi/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/hi/docs/MCP-SERVER.md b/docs/i18n/hi/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/hi/docs/MCP-SERVER.md
rename to docs/i18n/hi/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/hi/docs/FEATURES.md b/docs/i18n/hi/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/hi/docs/FEATURES.md
rename to docs/i18n/hi/docs/guides/FEATURES.md
diff --git a/docs/i18n/hi/docs/I18N.md b/docs/i18n/hi/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/hi/docs/I18N.md
rename to docs/i18n/hi/docs/guides/I18N.md
index 4b35d190b0..99819dea66 100644
--- a/docs/i18n/hi/docs/I18N.md
+++ b/docs/i18n/hi/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/hi/docs/TROUBLESHOOTING.md b/docs/i18n/hi/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/hi/docs/TROUBLESHOOTING.md
rename to docs/i18n/hi/docs/guides/TROUBLESHOOTING.md
index 9b2aa8e809..b0a1a63de1 100644
--- a/docs/i18n/hi/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/hi/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/hi/docs/UNINSTALL.md b/docs/i18n/hi/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/hi/docs/UNINSTALL.md
rename to docs/i18n/hi/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/hi/docs/USER_GUIDE.md b/docs/i18n/hi/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/hi/docs/USER_GUIDE.md
rename to docs/i18n/hi/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/hi/docs/COVERAGE_PLAN.md b/docs/i18n/hi/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/hi/docs/COVERAGE_PLAN.md
rename to docs/i18n/hi/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/hi/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/hi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/hi/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/hi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/hi/docs/RELEASE_CHECKLIST.md b/docs/i18n/hi/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/hi/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/hi/docs/ops/RELEASE_CHECKLIST.md
index f406a0d7ad..7a114ea0b9 100644
--- a/docs/i18n/hi/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/hi/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/hi/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/hi/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/hi/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/hi/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/hi/docs/API_REFERENCE.md b/docs/i18n/hi/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/hi/docs/API_REFERENCE.md
rename to docs/i18n/hi/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/hi/docs/CLI-TOOLS.md b/docs/i18n/hi/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/hi/docs/CLI-TOOLS.md
rename to docs/i18n/hi/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/hi/docs/ENVIRONMENT.md b/docs/i18n/hi/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/hi/docs/ENVIRONMENT.md
rename to docs/i18n/hi/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/hi/docs/AUTO-COMBO.md b/docs/i18n/hi/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/hi/docs/AUTO-COMBO.md
rename to docs/i18n/hi/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/hi/llm.txt b/docs/i18n/hi/llm.txt
index 4c1fd0e7b5..940e48983e 100644
--- a/docs/i18n/hi/llm.txt
+++ b/docs/i18n/hi/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/hu/CHANGELOG.md b/docs/i18n/hu/CHANGELOG.md
index a00a13ec91..aaaa8aad8a 100644
--- a/docs/i18n/hu/CHANGELOG.md
+++ b/docs/i18n/hu/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/hu/CONTRIBUTING.md b/docs/i18n/hu/CONTRIBUTING.md
index ce8e5b0845..d9c56d890e 100644
--- a/docs/i18n/hu/CONTRIBUTING.md
+++ b/docs/i18n/hu/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/hu/README.md b/docs/i18n/hu/README.md
index 97ffb36ab0..2d136ac7bb 100644
--- a/docs/i18n/hu/README.md
+++ b/docs/i18n/hu/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Dokumentáció
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/hu/docs/ARCHITECTURE.md b/docs/i18n/hu/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/hu/docs/ARCHITECTURE.md
rename to docs/i18n/hu/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/hu/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/hu/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/hu/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/hu/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/hu/docs/A2A-SERVER.md b/docs/i18n/hu/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/hu/docs/A2A-SERVER.md
rename to docs/i18n/hu/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/hu/docs/MCP-SERVER.md b/docs/i18n/hu/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/hu/docs/MCP-SERVER.md
rename to docs/i18n/hu/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/hu/docs/FEATURES.md b/docs/i18n/hu/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/hu/docs/FEATURES.md
rename to docs/i18n/hu/docs/guides/FEATURES.md
diff --git a/docs/i18n/hu/docs/I18N.md b/docs/i18n/hu/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/hu/docs/I18N.md
rename to docs/i18n/hu/docs/guides/I18N.md
index 0b698c8c1e..5ce84e3a10 100644
--- a/docs/i18n/hu/docs/I18N.md
+++ b/docs/i18n/hu/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/hu/docs/TROUBLESHOOTING.md b/docs/i18n/hu/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/hu/docs/TROUBLESHOOTING.md
rename to docs/i18n/hu/docs/guides/TROUBLESHOOTING.md
index b778c8e1dd..ab2f0809e0 100644
--- a/docs/i18n/hu/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/hu/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/hu/docs/UNINSTALL.md b/docs/i18n/hu/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/hu/docs/UNINSTALL.md
rename to docs/i18n/hu/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/hu/docs/USER_GUIDE.md b/docs/i18n/hu/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/hu/docs/USER_GUIDE.md
rename to docs/i18n/hu/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/hu/docs/COVERAGE_PLAN.md b/docs/i18n/hu/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/hu/docs/COVERAGE_PLAN.md
rename to docs/i18n/hu/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/hu/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/hu/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/hu/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/hu/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/hu/docs/RELEASE_CHECKLIST.md b/docs/i18n/hu/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/hu/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/hu/docs/ops/RELEASE_CHECKLIST.md
index 338230d9a7..87e24c3438 100644
--- a/docs/i18n/hu/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/hu/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/hu/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/hu/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/hu/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/hu/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/hu/docs/API_REFERENCE.md b/docs/i18n/hu/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/hu/docs/API_REFERENCE.md
rename to docs/i18n/hu/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/hu/docs/CLI-TOOLS.md b/docs/i18n/hu/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/hu/docs/CLI-TOOLS.md
rename to docs/i18n/hu/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/hu/docs/ENVIRONMENT.md b/docs/i18n/hu/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/hu/docs/ENVIRONMENT.md
rename to docs/i18n/hu/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/hu/docs/AUTO-COMBO.md b/docs/i18n/hu/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/hu/docs/AUTO-COMBO.md
rename to docs/i18n/hu/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/hu/llm.txt b/docs/i18n/hu/llm.txt
index 962b33e890..a5174b82ba 100644
--- a/docs/i18n/hu/llm.txt
+++ b/docs/i18n/hu/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/id/CHANGELOG.md b/docs/i18n/id/CHANGELOG.md
index b1753e51e4..d66c092655 100644
--- a/docs/i18n/id/CHANGELOG.md
+++ b/docs/i18n/id/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/id/CONTRIBUTING.md b/docs/i18n/id/CONTRIBUTING.md
index b3ffe11a1b..b1a724553a 100644
--- a/docs/i18n/id/CONTRIBUTING.md
+++ b/docs/i18n/id/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/id/README.md b/docs/i18n/id/README.md
index e308128367..71d5194ecd 100644
--- a/docs/i18n/id/README.md
+++ b/docs/i18n/id/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Dokumentasi
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/id/docs/ARCHITECTURE.md b/docs/i18n/id/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/id/docs/ARCHITECTURE.md
rename to docs/i18n/id/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/id/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/id/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/id/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/id/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/id/docs/A2A-SERVER.md b/docs/i18n/id/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/id/docs/A2A-SERVER.md
rename to docs/i18n/id/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/id/docs/MCP-SERVER.md b/docs/i18n/id/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/id/docs/MCP-SERVER.md
rename to docs/i18n/id/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/id/docs/FEATURES.md b/docs/i18n/id/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/id/docs/FEATURES.md
rename to docs/i18n/id/docs/guides/FEATURES.md
diff --git a/docs/i18n/id/docs/I18N.md b/docs/i18n/id/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/id/docs/I18N.md
rename to docs/i18n/id/docs/guides/I18N.md
index 77df794c42..910370dcae 100644
--- a/docs/i18n/id/docs/I18N.md
+++ b/docs/i18n/id/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/id/docs/TROUBLESHOOTING.md b/docs/i18n/id/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/id/docs/TROUBLESHOOTING.md
rename to docs/i18n/id/docs/guides/TROUBLESHOOTING.md
index 8c07300e1b..ae8156e5ef 100644
--- a/docs/i18n/id/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/id/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/id/docs/UNINSTALL.md b/docs/i18n/id/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/id/docs/UNINSTALL.md
rename to docs/i18n/id/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/id/docs/USER_GUIDE.md b/docs/i18n/id/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/id/docs/USER_GUIDE.md
rename to docs/i18n/id/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/id/docs/COVERAGE_PLAN.md b/docs/i18n/id/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/id/docs/COVERAGE_PLAN.md
rename to docs/i18n/id/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/id/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/id/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/id/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/id/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/id/docs/RELEASE_CHECKLIST.md b/docs/i18n/id/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/id/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/id/docs/ops/RELEASE_CHECKLIST.md
index a0126b813b..f57f20d897 100644
--- a/docs/i18n/id/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/id/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/id/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/id/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/id/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/id/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/id/docs/API_REFERENCE.md b/docs/i18n/id/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/id/docs/API_REFERENCE.md
rename to docs/i18n/id/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/id/docs/CLI-TOOLS.md b/docs/i18n/id/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/id/docs/CLI-TOOLS.md
rename to docs/i18n/id/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/id/docs/ENVIRONMENT.md b/docs/i18n/id/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/id/docs/ENVIRONMENT.md
rename to docs/i18n/id/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/id/docs/AUTO-COMBO.md b/docs/i18n/id/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/id/docs/AUTO-COMBO.md
rename to docs/i18n/id/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/id/llm.txt b/docs/i18n/id/llm.txt
index dc159223f9..a7326adc95 100644
--- a/docs/i18n/id/llm.txt
+++ b/docs/i18n/id/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/in/CHANGELOG.md b/docs/i18n/in/CHANGELOG.md
index 5fff2412bf..8af184dd43 100644
--- a/docs/i18n/in/CHANGELOG.md
+++ b/docs/i18n/in/CHANGELOG.md
@@ -1196,7 +1196,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/docs/i18n/in/CONTRIBUTING.md b/docs/i18n/in/CONTRIBUTING.md
index 8aa93179c3..da6c1d8ac0 100644
--- a/docs/i18n/in/CONTRIBUTING.md
+++ b/docs/i18n/in/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/in/README.md b/docs/i18n/in/README.md
index 70c65182ff..486d3210ce 100644
--- a/docs/i18n/in/README.md
+++ b/docs/i18n/in/README.md
@@ -2256,25 +2256,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## दस्तावेज़
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/in/docs/ARCHITECTURE.md b/docs/i18n/in/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/in/docs/ARCHITECTURE.md
rename to docs/i18n/in/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/in/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/in/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/in/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/in/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/in/docs/A2A-SERVER.md b/docs/i18n/in/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/in/docs/A2A-SERVER.md
rename to docs/i18n/in/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/in/docs/MCP-SERVER.md b/docs/i18n/in/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/in/docs/MCP-SERVER.md
rename to docs/i18n/in/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/in/docs/FEATURES.md b/docs/i18n/in/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/in/docs/FEATURES.md
rename to docs/i18n/in/docs/guides/FEATURES.md
diff --git a/docs/i18n/in/docs/I18N.md b/docs/i18n/in/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/in/docs/I18N.md
rename to docs/i18n/in/docs/guides/I18N.md
index 142bd074b2..c2676241d3 100644
--- a/docs/i18n/in/docs/I18N.md
+++ b/docs/i18n/in/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/in/docs/TROUBLESHOOTING.md b/docs/i18n/in/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/in/docs/TROUBLESHOOTING.md
rename to docs/i18n/in/docs/guides/TROUBLESHOOTING.md
index 78a93de8bb..fab97adffe 100644
--- a/docs/i18n/in/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/in/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/in/docs/UNINSTALL.md b/docs/i18n/in/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/in/docs/UNINSTALL.md
rename to docs/i18n/in/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/in/docs/USER_GUIDE.md b/docs/i18n/in/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/in/docs/USER_GUIDE.md
rename to docs/i18n/in/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/in/docs/COVERAGE_PLAN.md b/docs/i18n/in/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/in/docs/COVERAGE_PLAN.md
rename to docs/i18n/in/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/in/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/in/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/in/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/in/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/in/docs/RELEASE_CHECKLIST.md b/docs/i18n/in/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/in/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/in/docs/ops/RELEASE_CHECKLIST.md
index 21bcce8589..1108a3ad61 100644
--- a/docs/i18n/in/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/in/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/in/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/in/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/in/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/in/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/in/docs/API_REFERENCE.md b/docs/i18n/in/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/in/docs/API_REFERENCE.md
rename to docs/i18n/in/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/in/docs/CLI-TOOLS.md b/docs/i18n/in/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/in/docs/CLI-TOOLS.md
rename to docs/i18n/in/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/in/docs/ENVIRONMENT.md b/docs/i18n/in/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/in/docs/ENVIRONMENT.md
rename to docs/i18n/in/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/in/docs/AUTO-COMBO.md b/docs/i18n/in/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/in/docs/AUTO-COMBO.md
rename to docs/i18n/in/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/in/llm.txt b/docs/i18n/in/llm.txt
index dfc141a97c..7a335876a5 100644
--- a/docs/i18n/in/llm.txt
+++ b/docs/i18n/in/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/it/CHANGELOG.md b/docs/i18n/it/CHANGELOG.md
index 348d38da98..80ed4a317d 100644
--- a/docs/i18n/it/CHANGELOG.md
+++ b/docs/i18n/it/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/it/CONTRIBUTING.md b/docs/i18n/it/CONTRIBUTING.md
index 98278a77db..e3cb62b317 100644
--- a/docs/i18n/it/CONTRIBUTING.md
+++ b/docs/i18n/it/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/it/README.md b/docs/i18n/it/README.md
index 500239cb69..6a6e645ef3 100644
--- a/docs/i18n/it/README.md
+++ b/docs/i18n/it/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentazione
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/it/docs/ARCHITECTURE.md b/docs/i18n/it/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/it/docs/ARCHITECTURE.md
rename to docs/i18n/it/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/it/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/it/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/it/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/it/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/it/docs/A2A-SERVER.md b/docs/i18n/it/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/it/docs/A2A-SERVER.md
rename to docs/i18n/it/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/it/docs/MCP-SERVER.md b/docs/i18n/it/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/it/docs/MCP-SERVER.md
rename to docs/i18n/it/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/it/docs/FEATURES.md b/docs/i18n/it/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/it/docs/FEATURES.md
rename to docs/i18n/it/docs/guides/FEATURES.md
diff --git a/docs/i18n/it/docs/I18N.md b/docs/i18n/it/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/it/docs/I18N.md
rename to docs/i18n/it/docs/guides/I18N.md
index 3d1a1de63d..7b648f8385 100644
--- a/docs/i18n/it/docs/I18N.md
+++ b/docs/i18n/it/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/it/docs/TROUBLESHOOTING.md b/docs/i18n/it/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/it/docs/TROUBLESHOOTING.md
rename to docs/i18n/it/docs/guides/TROUBLESHOOTING.md
index 8c47be6737..85b2d850ba 100644
--- a/docs/i18n/it/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/it/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/it/docs/UNINSTALL.md b/docs/i18n/it/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/it/docs/UNINSTALL.md
rename to docs/i18n/it/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/it/docs/USER_GUIDE.md b/docs/i18n/it/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/it/docs/USER_GUIDE.md
rename to docs/i18n/it/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/it/docs/COVERAGE_PLAN.md b/docs/i18n/it/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/it/docs/COVERAGE_PLAN.md
rename to docs/i18n/it/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/it/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/it/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/it/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/it/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/it/docs/RELEASE_CHECKLIST.md b/docs/i18n/it/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/it/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/it/docs/ops/RELEASE_CHECKLIST.md
index d0cc4e3887..45b9e81833 100644
--- a/docs/i18n/it/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/it/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/it/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/it/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/it/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/it/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/it/docs/API_REFERENCE.md b/docs/i18n/it/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/it/docs/API_REFERENCE.md
rename to docs/i18n/it/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/it/docs/CLI-TOOLS.md b/docs/i18n/it/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/it/docs/CLI-TOOLS.md
rename to docs/i18n/it/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/it/docs/ENVIRONMENT.md b/docs/i18n/it/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/it/docs/ENVIRONMENT.md
rename to docs/i18n/it/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/it/docs/AUTO-COMBO.md b/docs/i18n/it/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/it/docs/AUTO-COMBO.md
rename to docs/i18n/it/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/it/llm.txt b/docs/i18n/it/llm.txt
index c9bb401e7b..1ec48fb907 100644
--- a/docs/i18n/it/llm.txt
+++ b/docs/i18n/it/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/ja/CHANGELOG.md b/docs/i18n/ja/CHANGELOG.md
index dec6ed89f1..6a4450202e 100644
--- a/docs/i18n/ja/CHANGELOG.md
+++ b/docs/i18n/ja/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/ja/CONTRIBUTING.md b/docs/i18n/ja/CONTRIBUTING.md
index 307d2dcb24..6d8f76191e 100644
--- a/docs/i18n/ja/CONTRIBUTING.md
+++ b/docs/i18n/ja/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/ja/README.md b/docs/i18n/ja/README.md
index fb03fcd72d..34ee6a7308 100644
--- a/docs/i18n/ja/README.md
+++ b/docs/i18n/ja/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## ドキュメント
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/ja/docs/ARCHITECTURE.md b/docs/i18n/ja/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/ja/docs/ARCHITECTURE.md
rename to docs/i18n/ja/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/ja/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/ja/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/ja/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/ja/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/ja/docs/A2A-SERVER.md b/docs/i18n/ja/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/ja/docs/A2A-SERVER.md
rename to docs/i18n/ja/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/ja/docs/MCP-SERVER.md b/docs/i18n/ja/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/ja/docs/MCP-SERVER.md
rename to docs/i18n/ja/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/ja/docs/FEATURES.md b/docs/i18n/ja/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/ja/docs/FEATURES.md
rename to docs/i18n/ja/docs/guides/FEATURES.md
diff --git a/docs/i18n/ja/docs/I18N.md b/docs/i18n/ja/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/ja/docs/I18N.md
rename to docs/i18n/ja/docs/guides/I18N.md
index f2c5375bcb..b3c49f1c77 100644
--- a/docs/i18n/ja/docs/I18N.md
+++ b/docs/i18n/ja/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/ja/docs/TROUBLESHOOTING.md b/docs/i18n/ja/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/ja/docs/TROUBLESHOOTING.md
rename to docs/i18n/ja/docs/guides/TROUBLESHOOTING.md
index e2b27bc989..ba7b61683d 100644
--- a/docs/i18n/ja/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/ja/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/ja/docs/UNINSTALL.md b/docs/i18n/ja/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/ja/docs/UNINSTALL.md
rename to docs/i18n/ja/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/ja/docs/USER_GUIDE.md b/docs/i18n/ja/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/ja/docs/USER_GUIDE.md
rename to docs/i18n/ja/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/ja/docs/COVERAGE_PLAN.md b/docs/i18n/ja/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/ja/docs/COVERAGE_PLAN.md
rename to docs/i18n/ja/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/ja/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/ja/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ja/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ja/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ja/docs/RELEASE_CHECKLIST.md b/docs/i18n/ja/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/ja/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/ja/docs/ops/RELEASE_CHECKLIST.md
index ea7d0f993b..dc46e0a613 100644
--- a/docs/i18n/ja/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/ja/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/ja/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ja/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ja/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ja/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ja/docs/API_REFERENCE.md b/docs/i18n/ja/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/ja/docs/API_REFERENCE.md
rename to docs/i18n/ja/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/ja/docs/CLI-TOOLS.md b/docs/i18n/ja/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/ja/docs/CLI-TOOLS.md
rename to docs/i18n/ja/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/ja/docs/ENVIRONMENT.md b/docs/i18n/ja/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/ja/docs/ENVIRONMENT.md
rename to docs/i18n/ja/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/ja/docs/AUTO-COMBO.md b/docs/i18n/ja/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/ja/docs/AUTO-COMBO.md
rename to docs/i18n/ja/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/ja/llm.txt b/docs/i18n/ja/llm.txt
index 16f03cfc0f..1fd93f3d68 100644
--- a/docs/i18n/ja/llm.txt
+++ b/docs/i18n/ja/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/ko/CHANGELOG.md b/docs/i18n/ko/CHANGELOG.md
index dc62bdbbd3..5d5dcb3990 100644
--- a/docs/i18n/ko/CHANGELOG.md
+++ b/docs/i18n/ko/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/ko/CONTRIBUTING.md b/docs/i18n/ko/CONTRIBUTING.md
index d5de24574b..ebe73c8fb3 100644
--- a/docs/i18n/ko/CONTRIBUTING.md
+++ b/docs/i18n/ko/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/ko/README.md b/docs/i18n/ko/README.md
index ffe4cd20fd..63e601edc6 100644
--- a/docs/i18n/ko/README.md
+++ b/docs/i18n/ko/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## 문서
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/ko/docs/ARCHITECTURE.md b/docs/i18n/ko/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/ko/docs/ARCHITECTURE.md
rename to docs/i18n/ko/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/ko/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/ko/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/ko/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/ko/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/ko/docs/A2A-SERVER.md b/docs/i18n/ko/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/ko/docs/A2A-SERVER.md
rename to docs/i18n/ko/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/ko/docs/MCP-SERVER.md b/docs/i18n/ko/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/ko/docs/MCP-SERVER.md
rename to docs/i18n/ko/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/ko/docs/FEATURES.md b/docs/i18n/ko/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/ko/docs/FEATURES.md
rename to docs/i18n/ko/docs/guides/FEATURES.md
diff --git a/docs/i18n/ko/docs/I18N.md b/docs/i18n/ko/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/ko/docs/I18N.md
rename to docs/i18n/ko/docs/guides/I18N.md
index af5e4fd0bb..fea5b6e87b 100644
--- a/docs/i18n/ko/docs/I18N.md
+++ b/docs/i18n/ko/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/ko/docs/TROUBLESHOOTING.md b/docs/i18n/ko/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/ko/docs/TROUBLESHOOTING.md
rename to docs/i18n/ko/docs/guides/TROUBLESHOOTING.md
index 245f52fdb2..5e5fcfe9ae 100644
--- a/docs/i18n/ko/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/ko/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/ko/docs/UNINSTALL.md b/docs/i18n/ko/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/ko/docs/UNINSTALL.md
rename to docs/i18n/ko/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/ko/docs/USER_GUIDE.md b/docs/i18n/ko/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/ko/docs/USER_GUIDE.md
rename to docs/i18n/ko/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/ko/docs/COVERAGE_PLAN.md b/docs/i18n/ko/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/ko/docs/COVERAGE_PLAN.md
rename to docs/i18n/ko/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/ko/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/ko/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ko/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ko/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ko/docs/RELEASE_CHECKLIST.md b/docs/i18n/ko/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/ko/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/ko/docs/ops/RELEASE_CHECKLIST.md
index dbfe24caa9..f2d95b262e 100644
--- a/docs/i18n/ko/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/ko/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/ko/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ko/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ko/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ko/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ko/docs/API_REFERENCE.md b/docs/i18n/ko/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/ko/docs/API_REFERENCE.md
rename to docs/i18n/ko/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/ko/docs/CLI-TOOLS.md b/docs/i18n/ko/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/ko/docs/CLI-TOOLS.md
rename to docs/i18n/ko/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/ko/docs/ENVIRONMENT.md b/docs/i18n/ko/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/ko/docs/ENVIRONMENT.md
rename to docs/i18n/ko/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/ko/docs/AUTO-COMBO.md b/docs/i18n/ko/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/ko/docs/AUTO-COMBO.md
rename to docs/i18n/ko/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/ko/llm.txt b/docs/i18n/ko/llm.txt
index f0315b1d54..1a20747f59 100644
--- a/docs/i18n/ko/llm.txt
+++ b/docs/i18n/ko/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/mr/CHANGELOG.md b/docs/i18n/mr/CHANGELOG.md
index 29f28182c6..0fb797a8b4 100644
--- a/docs/i18n/mr/CHANGELOG.md
+++ b/docs/i18n/mr/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/mr/CONTRIBUTING.md b/docs/i18n/mr/CONTRIBUTING.md
index a4dedc4578..2245c3f831 100644
--- a/docs/i18n/mr/CONTRIBUTING.md
+++ b/docs/i18n/mr/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/mr/README.md b/docs/i18n/mr/README.md
index 57ec532cab..cda2a91b5c 100644
--- a/docs/i18n/mr/README.md
+++ b/docs/i18n/mr/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentación
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/mr/docs/ARCHITECTURE.md b/docs/i18n/mr/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/mr/docs/ARCHITECTURE.md
rename to docs/i18n/mr/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/mr/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/mr/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/mr/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/mr/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/mr/docs/A2A-SERVER.md b/docs/i18n/mr/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/mr/docs/A2A-SERVER.md
rename to docs/i18n/mr/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/mr/docs/MCP-SERVER.md b/docs/i18n/mr/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/mr/docs/MCP-SERVER.md
rename to docs/i18n/mr/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/mr/docs/FEATURES.md b/docs/i18n/mr/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/mr/docs/FEATURES.md
rename to docs/i18n/mr/docs/guides/FEATURES.md
diff --git a/docs/i18n/mr/docs/I18N.md b/docs/i18n/mr/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/mr/docs/I18N.md
rename to docs/i18n/mr/docs/guides/I18N.md
index a1c23e03e7..1604a3fbcf 100644
--- a/docs/i18n/mr/docs/I18N.md
+++ b/docs/i18n/mr/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/mr/docs/TROUBLESHOOTING.md b/docs/i18n/mr/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/mr/docs/TROUBLESHOOTING.md
rename to docs/i18n/mr/docs/guides/TROUBLESHOOTING.md
index 18bfb5a393..42b85cd959 100644
--- a/docs/i18n/mr/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/mr/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/mr/docs/UNINSTALL.md b/docs/i18n/mr/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/mr/docs/UNINSTALL.md
rename to docs/i18n/mr/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/mr/docs/USER_GUIDE.md b/docs/i18n/mr/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/mr/docs/USER_GUIDE.md
rename to docs/i18n/mr/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/mr/docs/COVERAGE_PLAN.md b/docs/i18n/mr/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/mr/docs/COVERAGE_PLAN.md
rename to docs/i18n/mr/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/mr/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/mr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/mr/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/mr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/mr/docs/RELEASE_CHECKLIST.md b/docs/i18n/mr/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/mr/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/mr/docs/ops/RELEASE_CHECKLIST.md
index 7ec2d34f16..5028558782 100644
--- a/docs/i18n/mr/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/mr/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/mr/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/mr/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/mr/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/mr/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/mr/docs/API_REFERENCE.md b/docs/i18n/mr/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/mr/docs/API_REFERENCE.md
rename to docs/i18n/mr/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/mr/docs/CLI-TOOLS.md b/docs/i18n/mr/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/mr/docs/CLI-TOOLS.md
rename to docs/i18n/mr/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/mr/docs/ENVIRONMENT.md b/docs/i18n/mr/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/mr/docs/ENVIRONMENT.md
rename to docs/i18n/mr/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/mr/docs/AUTO-COMBO.md b/docs/i18n/mr/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/mr/docs/AUTO-COMBO.md
rename to docs/i18n/mr/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/mr/llm.txt b/docs/i18n/mr/llm.txt
index 2d4b0c2b8f..be205b03e8 100644
--- a/docs/i18n/mr/llm.txt
+++ b/docs/i18n/mr/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/ms/CHANGELOG.md b/docs/i18n/ms/CHANGELOG.md
index 19807106c2..0a7b677bad 100644
--- a/docs/i18n/ms/CHANGELOG.md
+++ b/docs/i18n/ms/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/ms/CONTRIBUTING.md b/docs/i18n/ms/CONTRIBUTING.md
index 01ff8cea11..c1d1b075cc 100644
--- a/docs/i18n/ms/CONTRIBUTING.md
+++ b/docs/i18n/ms/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/ms/README.md b/docs/i18n/ms/README.md
index e72f4836aa..77cd80d5a2 100644
--- a/docs/i18n/ms/README.md
+++ b/docs/i18n/ms/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Dokumentasi
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/ms/docs/ARCHITECTURE.md b/docs/i18n/ms/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/ms/docs/ARCHITECTURE.md
rename to docs/i18n/ms/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/ms/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/ms/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/ms/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/ms/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/ms/docs/A2A-SERVER.md b/docs/i18n/ms/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/ms/docs/A2A-SERVER.md
rename to docs/i18n/ms/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/ms/docs/MCP-SERVER.md b/docs/i18n/ms/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/ms/docs/MCP-SERVER.md
rename to docs/i18n/ms/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/ms/docs/FEATURES.md b/docs/i18n/ms/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/ms/docs/FEATURES.md
rename to docs/i18n/ms/docs/guides/FEATURES.md
diff --git a/docs/i18n/ms/docs/I18N.md b/docs/i18n/ms/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/ms/docs/I18N.md
rename to docs/i18n/ms/docs/guides/I18N.md
index 32a7ae2666..3f10814344 100644
--- a/docs/i18n/ms/docs/I18N.md
+++ b/docs/i18n/ms/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/ms/docs/TROUBLESHOOTING.md b/docs/i18n/ms/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/ms/docs/TROUBLESHOOTING.md
rename to docs/i18n/ms/docs/guides/TROUBLESHOOTING.md
index 783753adda..60d6c32989 100644
--- a/docs/i18n/ms/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/ms/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/ms/docs/UNINSTALL.md b/docs/i18n/ms/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/ms/docs/UNINSTALL.md
rename to docs/i18n/ms/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/ms/docs/USER_GUIDE.md b/docs/i18n/ms/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/ms/docs/USER_GUIDE.md
rename to docs/i18n/ms/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/ms/docs/COVERAGE_PLAN.md b/docs/i18n/ms/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/ms/docs/COVERAGE_PLAN.md
rename to docs/i18n/ms/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/ms/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/ms/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ms/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ms/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ms/docs/RELEASE_CHECKLIST.md b/docs/i18n/ms/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/ms/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/ms/docs/ops/RELEASE_CHECKLIST.md
index 5ce7ee2a1d..0b72bdea50 100644
--- a/docs/i18n/ms/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/ms/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/ms/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ms/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ms/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ms/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ms/docs/API_REFERENCE.md b/docs/i18n/ms/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/ms/docs/API_REFERENCE.md
rename to docs/i18n/ms/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/ms/docs/CLI-TOOLS.md b/docs/i18n/ms/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/ms/docs/CLI-TOOLS.md
rename to docs/i18n/ms/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/ms/docs/ENVIRONMENT.md b/docs/i18n/ms/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/ms/docs/ENVIRONMENT.md
rename to docs/i18n/ms/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/ms/docs/AUTO-COMBO.md b/docs/i18n/ms/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/ms/docs/AUTO-COMBO.md
rename to docs/i18n/ms/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/ms/llm.txt b/docs/i18n/ms/llm.txt
index 1832e506f9..d2ddd056e4 100644
--- a/docs/i18n/ms/llm.txt
+++ b/docs/i18n/ms/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/nl/CHANGELOG.md b/docs/i18n/nl/CHANGELOG.md
index b7d1d9ddb9..67fba02475 100644
--- a/docs/i18n/nl/CHANGELOG.md
+++ b/docs/i18n/nl/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/nl/CONTRIBUTING.md b/docs/i18n/nl/CONTRIBUTING.md
index c4f98b51dd..ca6e96dde6 100644
--- a/docs/i18n/nl/CONTRIBUTING.md
+++ b/docs/i18n/nl/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/nl/README.md b/docs/i18n/nl/README.md
index 785745103c..466bb310a3 100644
--- a/docs/i18n/nl/README.md
+++ b/docs/i18n/nl/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentatie
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/nl/docs/ARCHITECTURE.md b/docs/i18n/nl/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/nl/docs/ARCHITECTURE.md
rename to docs/i18n/nl/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/nl/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/nl/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/nl/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/nl/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/nl/docs/A2A-SERVER.md b/docs/i18n/nl/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/nl/docs/A2A-SERVER.md
rename to docs/i18n/nl/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/nl/docs/MCP-SERVER.md b/docs/i18n/nl/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/nl/docs/MCP-SERVER.md
rename to docs/i18n/nl/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/nl/docs/FEATURES.md b/docs/i18n/nl/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/nl/docs/FEATURES.md
rename to docs/i18n/nl/docs/guides/FEATURES.md
diff --git a/docs/i18n/nl/docs/I18N.md b/docs/i18n/nl/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/nl/docs/I18N.md
rename to docs/i18n/nl/docs/guides/I18N.md
index 9fd7cf8177..3dd44035b2 100644
--- a/docs/i18n/nl/docs/I18N.md
+++ b/docs/i18n/nl/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/nl/docs/TROUBLESHOOTING.md b/docs/i18n/nl/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/nl/docs/TROUBLESHOOTING.md
rename to docs/i18n/nl/docs/guides/TROUBLESHOOTING.md
index 3d9b54fd47..17d12ce29c 100644
--- a/docs/i18n/nl/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/nl/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/nl/docs/UNINSTALL.md b/docs/i18n/nl/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/nl/docs/UNINSTALL.md
rename to docs/i18n/nl/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/nl/docs/USER_GUIDE.md b/docs/i18n/nl/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/nl/docs/USER_GUIDE.md
rename to docs/i18n/nl/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/nl/docs/COVERAGE_PLAN.md b/docs/i18n/nl/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/nl/docs/COVERAGE_PLAN.md
rename to docs/i18n/nl/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/nl/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/nl/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/nl/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/nl/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/nl/docs/RELEASE_CHECKLIST.md b/docs/i18n/nl/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/nl/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/nl/docs/ops/RELEASE_CHECKLIST.md
index 43e0525388..18744d5607 100644
--- a/docs/i18n/nl/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/nl/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/nl/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/nl/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/nl/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/nl/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/nl/docs/API_REFERENCE.md b/docs/i18n/nl/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/nl/docs/API_REFERENCE.md
rename to docs/i18n/nl/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/nl/docs/CLI-TOOLS.md b/docs/i18n/nl/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/nl/docs/CLI-TOOLS.md
rename to docs/i18n/nl/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/nl/docs/ENVIRONMENT.md b/docs/i18n/nl/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/nl/docs/ENVIRONMENT.md
rename to docs/i18n/nl/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/nl/docs/AUTO-COMBO.md b/docs/i18n/nl/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/nl/docs/AUTO-COMBO.md
rename to docs/i18n/nl/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/nl/llm.txt b/docs/i18n/nl/llm.txt
index dca3cd438e..6836a11da2 100644
--- a/docs/i18n/nl/llm.txt
+++ b/docs/i18n/nl/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/no/CHANGELOG.md b/docs/i18n/no/CHANGELOG.md
index 9766c019d6..7c8a3d4dea 100644
--- a/docs/i18n/no/CHANGELOG.md
+++ b/docs/i18n/no/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/no/CONTRIBUTING.md b/docs/i18n/no/CONTRIBUTING.md
index a801aeb9dd..5459dfed5a 100644
--- a/docs/i18n/no/CONTRIBUTING.md
+++ b/docs/i18n/no/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/no/README.md b/docs/i18n/no/README.md
index 9e62629c89..9420865d74 100644
--- a/docs/i18n/no/README.md
+++ b/docs/i18n/no/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Dokumentasjon
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/no/docs/ARCHITECTURE.md b/docs/i18n/no/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/no/docs/ARCHITECTURE.md
rename to docs/i18n/no/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/no/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/no/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/no/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/no/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/no/docs/A2A-SERVER.md b/docs/i18n/no/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/no/docs/A2A-SERVER.md
rename to docs/i18n/no/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/no/docs/MCP-SERVER.md b/docs/i18n/no/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/no/docs/MCP-SERVER.md
rename to docs/i18n/no/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/no/docs/FEATURES.md b/docs/i18n/no/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/no/docs/FEATURES.md
rename to docs/i18n/no/docs/guides/FEATURES.md
diff --git a/docs/i18n/no/docs/I18N.md b/docs/i18n/no/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/no/docs/I18N.md
rename to docs/i18n/no/docs/guides/I18N.md
index e4d19f8df8..748bbcc3c4 100644
--- a/docs/i18n/no/docs/I18N.md
+++ b/docs/i18n/no/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/no/docs/TROUBLESHOOTING.md b/docs/i18n/no/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/no/docs/TROUBLESHOOTING.md
rename to docs/i18n/no/docs/guides/TROUBLESHOOTING.md
index e90f23b8c9..7cb3399476 100644
--- a/docs/i18n/no/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/no/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/no/docs/UNINSTALL.md b/docs/i18n/no/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/no/docs/UNINSTALL.md
rename to docs/i18n/no/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/no/docs/USER_GUIDE.md b/docs/i18n/no/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/no/docs/USER_GUIDE.md
rename to docs/i18n/no/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/no/docs/COVERAGE_PLAN.md b/docs/i18n/no/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/no/docs/COVERAGE_PLAN.md
rename to docs/i18n/no/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/no/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/no/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/no/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/no/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/no/docs/RELEASE_CHECKLIST.md b/docs/i18n/no/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/no/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/no/docs/ops/RELEASE_CHECKLIST.md
index 025006df1e..19919c4f96 100644
--- a/docs/i18n/no/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/no/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/no/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/no/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/no/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/no/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/no/docs/API_REFERENCE.md b/docs/i18n/no/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/no/docs/API_REFERENCE.md
rename to docs/i18n/no/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/no/docs/CLI-TOOLS.md b/docs/i18n/no/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/no/docs/CLI-TOOLS.md
rename to docs/i18n/no/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/no/docs/ENVIRONMENT.md b/docs/i18n/no/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/no/docs/ENVIRONMENT.md
rename to docs/i18n/no/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/no/docs/AUTO-COMBO.md b/docs/i18n/no/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/no/docs/AUTO-COMBO.md
rename to docs/i18n/no/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/no/llm.txt b/docs/i18n/no/llm.txt
index 0471d80fed..0016785cb5 100644
--- a/docs/i18n/no/llm.txt
+++ b/docs/i18n/no/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/phi/CHANGELOG.md b/docs/i18n/phi/CHANGELOG.md
index 9960f024ef..e1f5376827 100644
--- a/docs/i18n/phi/CHANGELOG.md
+++ b/docs/i18n/phi/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/phi/CONTRIBUTING.md b/docs/i18n/phi/CONTRIBUTING.md
index b776a35afb..e7de589cb4 100644
--- a/docs/i18n/phi/CONTRIBUTING.md
+++ b/docs/i18n/phi/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/phi/README.md b/docs/i18n/phi/README.md
index b85c193aeb..82149249e4 100644
--- a/docs/i18n/phi/README.md
+++ b/docs/i18n/phi/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Dokumentasyon
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/phi/docs/ARCHITECTURE.md b/docs/i18n/phi/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/phi/docs/ARCHITECTURE.md
rename to docs/i18n/phi/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/phi/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/phi/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/phi/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/phi/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/phi/docs/A2A-SERVER.md b/docs/i18n/phi/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/phi/docs/A2A-SERVER.md
rename to docs/i18n/phi/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/phi/docs/MCP-SERVER.md b/docs/i18n/phi/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/phi/docs/MCP-SERVER.md
rename to docs/i18n/phi/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/phi/docs/FEATURES.md b/docs/i18n/phi/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/phi/docs/FEATURES.md
rename to docs/i18n/phi/docs/guides/FEATURES.md
diff --git a/docs/i18n/phi/docs/I18N.md b/docs/i18n/phi/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/phi/docs/I18N.md
rename to docs/i18n/phi/docs/guides/I18N.md
index fbd3ac9fd7..d65bd52e3e 100644
--- a/docs/i18n/phi/docs/I18N.md
+++ b/docs/i18n/phi/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/phi/docs/TROUBLESHOOTING.md b/docs/i18n/phi/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/phi/docs/TROUBLESHOOTING.md
rename to docs/i18n/phi/docs/guides/TROUBLESHOOTING.md
index 48964c3a28..645dbd210d 100644
--- a/docs/i18n/phi/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/phi/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/phi/docs/UNINSTALL.md b/docs/i18n/phi/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/phi/docs/UNINSTALL.md
rename to docs/i18n/phi/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/phi/docs/USER_GUIDE.md b/docs/i18n/phi/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/phi/docs/USER_GUIDE.md
rename to docs/i18n/phi/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/phi/docs/COVERAGE_PLAN.md b/docs/i18n/phi/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/phi/docs/COVERAGE_PLAN.md
rename to docs/i18n/phi/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/phi/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/phi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/phi/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/phi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/phi/docs/RELEASE_CHECKLIST.md b/docs/i18n/phi/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/phi/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/phi/docs/ops/RELEASE_CHECKLIST.md
index f480c3a133..da3b33e633 100644
--- a/docs/i18n/phi/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/phi/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/phi/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/phi/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/phi/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/phi/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/phi/docs/API_REFERENCE.md b/docs/i18n/phi/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/phi/docs/API_REFERENCE.md
rename to docs/i18n/phi/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/phi/docs/CLI-TOOLS.md b/docs/i18n/phi/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/phi/docs/CLI-TOOLS.md
rename to docs/i18n/phi/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/phi/docs/ENVIRONMENT.md b/docs/i18n/phi/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/phi/docs/ENVIRONMENT.md
rename to docs/i18n/phi/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/phi/docs/AUTO-COMBO.md b/docs/i18n/phi/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/phi/docs/AUTO-COMBO.md
rename to docs/i18n/phi/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/phi/llm.txt b/docs/i18n/phi/llm.txt
index 920c658f14..159e12a77e 100644
--- a/docs/i18n/phi/llm.txt
+++ b/docs/i18n/phi/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/pl/CHANGELOG.md b/docs/i18n/pl/CHANGELOG.md
index b6891cc7f8..95c895bb31 100644
--- a/docs/i18n/pl/CHANGELOG.md
+++ b/docs/i18n/pl/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/pl/CONTRIBUTING.md b/docs/i18n/pl/CONTRIBUTING.md
index 6645c79b33..5522097225 100644
--- a/docs/i18n/pl/CONTRIBUTING.md
+++ b/docs/i18n/pl/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/pl/README.md b/docs/i18n/pl/README.md
index 06a6f3c00e..37bcec15fa 100644
--- a/docs/i18n/pl/README.md
+++ b/docs/i18n/pl/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Dokumentacja
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/pl/docs/ARCHITECTURE.md b/docs/i18n/pl/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/pl/docs/ARCHITECTURE.md
rename to docs/i18n/pl/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/pl/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/pl/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/pl/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/pl/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/pl/docs/A2A-SERVER.md b/docs/i18n/pl/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/pl/docs/A2A-SERVER.md
rename to docs/i18n/pl/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/pl/docs/MCP-SERVER.md b/docs/i18n/pl/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/pl/docs/MCP-SERVER.md
rename to docs/i18n/pl/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/pl/docs/FEATURES.md b/docs/i18n/pl/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/pl/docs/FEATURES.md
rename to docs/i18n/pl/docs/guides/FEATURES.md
diff --git a/docs/i18n/pl/docs/I18N.md b/docs/i18n/pl/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/pl/docs/I18N.md
rename to docs/i18n/pl/docs/guides/I18N.md
index 50b29f62a9..fed5b2efc9 100644
--- a/docs/i18n/pl/docs/I18N.md
+++ b/docs/i18n/pl/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/pl/docs/TROUBLESHOOTING.md b/docs/i18n/pl/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/pl/docs/TROUBLESHOOTING.md
rename to docs/i18n/pl/docs/guides/TROUBLESHOOTING.md
index 602fb51932..03529c71ed 100644
--- a/docs/i18n/pl/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/pl/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/pl/docs/UNINSTALL.md b/docs/i18n/pl/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/pl/docs/UNINSTALL.md
rename to docs/i18n/pl/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/pl/docs/USER_GUIDE.md b/docs/i18n/pl/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/pl/docs/USER_GUIDE.md
rename to docs/i18n/pl/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/pl/docs/COVERAGE_PLAN.md b/docs/i18n/pl/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/pl/docs/COVERAGE_PLAN.md
rename to docs/i18n/pl/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/pl/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/pl/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/pl/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/pl/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/pl/docs/RELEASE_CHECKLIST.md b/docs/i18n/pl/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/pl/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/pl/docs/ops/RELEASE_CHECKLIST.md
index b170aa3341..26fb590869 100644
--- a/docs/i18n/pl/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/pl/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/pl/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/pl/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/pl/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/pl/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/pl/docs/API_REFERENCE.md b/docs/i18n/pl/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/pl/docs/API_REFERENCE.md
rename to docs/i18n/pl/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/pl/docs/CLI-TOOLS.md b/docs/i18n/pl/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/pl/docs/CLI-TOOLS.md
rename to docs/i18n/pl/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/pl/docs/ENVIRONMENT.md b/docs/i18n/pl/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/pl/docs/ENVIRONMENT.md
rename to docs/i18n/pl/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/pl/docs/AUTO-COMBO.md b/docs/i18n/pl/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/pl/docs/AUTO-COMBO.md
rename to docs/i18n/pl/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/pl/llm.txt b/docs/i18n/pl/llm.txt
index bc6d82e0c3..80d86112b4 100644
--- a/docs/i18n/pl/llm.txt
+++ b/docs/i18n/pl/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/pt-BR/CHANGELOG.md b/docs/i18n/pt-BR/CHANGELOG.md
index 03722be51a..0b95df31f5 100644
--- a/docs/i18n/pt-BR/CHANGELOG.md
+++ b/docs/i18n/pt-BR/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/pt-BR/CONTRIBUTING.md b/docs/i18n/pt-BR/CONTRIBUTING.md
index 675d966ac9..edb8c7bd71 100644
--- a/docs/i18n/pt-BR/CONTRIBUTING.md
+++ b/docs/i18n/pt-BR/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/pt-BR/README.md b/docs/i18n/pt-BR/README.md
index 1c31271e86..77e48d0334 100644
--- a/docs/i18n/pt-BR/README.md
+++ b/docs/i18n/pt-BR/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentação
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/pt-BR/docs/ARCHITECTURE.md b/docs/i18n/pt-BR/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/pt-BR/docs/ARCHITECTURE.md
rename to docs/i18n/pt-BR/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/pt-BR/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/pt-BR/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/pt-BR/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/pt-BR/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/pt-BR/docs/A2A-SERVER.md b/docs/i18n/pt-BR/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/pt-BR/docs/A2A-SERVER.md
rename to docs/i18n/pt-BR/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/pt-BR/docs/MCP-SERVER.md b/docs/i18n/pt-BR/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/pt-BR/docs/MCP-SERVER.md
rename to docs/i18n/pt-BR/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/pt-BR/docs/FEATURES.md b/docs/i18n/pt-BR/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/pt-BR/docs/FEATURES.md
rename to docs/i18n/pt-BR/docs/guides/FEATURES.md
diff --git a/docs/i18n/pt-BR/docs/I18N.md b/docs/i18n/pt-BR/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/pt-BR/docs/I18N.md
rename to docs/i18n/pt-BR/docs/guides/I18N.md
index 2faef1c2c4..4c31b74476 100644
--- a/docs/i18n/pt-BR/docs/I18N.md
+++ b/docs/i18n/pt-BR/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/pt-BR/docs/TROUBLESHOOTING.md b/docs/i18n/pt-BR/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/pt-BR/docs/TROUBLESHOOTING.md
rename to docs/i18n/pt-BR/docs/guides/TROUBLESHOOTING.md
index 6392bd7189..f951053005 100644
--- a/docs/i18n/pt-BR/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/pt-BR/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/pt-BR/docs/UNINSTALL.md b/docs/i18n/pt-BR/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/pt-BR/docs/UNINSTALL.md
rename to docs/i18n/pt-BR/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/pt-BR/docs/USER_GUIDE.md b/docs/i18n/pt-BR/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/pt-BR/docs/USER_GUIDE.md
rename to docs/i18n/pt-BR/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/pt-BR/docs/COVERAGE_PLAN.md b/docs/i18n/pt-BR/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/pt-BR/docs/COVERAGE_PLAN.md
rename to docs/i18n/pt-BR/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/pt-BR/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/pt-BR/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/pt-BR/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/pt-BR/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/pt-BR/docs/RELEASE_CHECKLIST.md b/docs/i18n/pt-BR/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/pt-BR/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/pt-BR/docs/ops/RELEASE_CHECKLIST.md
index 61a72634a5..8154882016 100644
--- a/docs/i18n/pt-BR/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/pt-BR/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/pt-BR/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/pt-BR/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/pt-BR/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/pt-BR/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/pt-BR/docs/API_REFERENCE.md b/docs/i18n/pt-BR/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/pt-BR/docs/API_REFERENCE.md
rename to docs/i18n/pt-BR/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/pt-BR/docs/CLI-TOOLS.md b/docs/i18n/pt-BR/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/pt-BR/docs/CLI-TOOLS.md
rename to docs/i18n/pt-BR/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/pt-BR/docs/ENVIRONMENT.md b/docs/i18n/pt-BR/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/pt-BR/docs/ENVIRONMENT.md
rename to docs/i18n/pt-BR/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/pt-BR/docs/AUTO-COMBO.md b/docs/i18n/pt-BR/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/pt-BR/docs/AUTO-COMBO.md
rename to docs/i18n/pt-BR/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/pt-BR/llm.txt b/docs/i18n/pt-BR/llm.txt
index d2de5e8572..632fc7135f 100644
--- a/docs/i18n/pt-BR/llm.txt
+++ b/docs/i18n/pt-BR/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/pt/CHANGELOG.md b/docs/i18n/pt/CHANGELOG.md
index 75de8ee268..04d780a2d0 100644
--- a/docs/i18n/pt/CHANGELOG.md
+++ b/docs/i18n/pt/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/pt/CONTRIBUTING.md b/docs/i18n/pt/CONTRIBUTING.md
index f1cc28f27a..9ee21156f9 100644
--- a/docs/i18n/pt/CONTRIBUTING.md
+++ b/docs/i18n/pt/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/pt/README.md b/docs/i18n/pt/README.md
index 492246346b..ac2ed33e74 100644
--- a/docs/i18n/pt/README.md
+++ b/docs/i18n/pt/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentação
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/pt/docs/ARCHITECTURE.md b/docs/i18n/pt/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/pt/docs/ARCHITECTURE.md
rename to docs/i18n/pt/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/pt/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/pt/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/pt/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/pt/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/pt/docs/A2A-SERVER.md b/docs/i18n/pt/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/pt/docs/A2A-SERVER.md
rename to docs/i18n/pt/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/pt/docs/MCP-SERVER.md b/docs/i18n/pt/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/pt/docs/MCP-SERVER.md
rename to docs/i18n/pt/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/pt/docs/FEATURES.md b/docs/i18n/pt/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/pt/docs/FEATURES.md
rename to docs/i18n/pt/docs/guides/FEATURES.md
diff --git a/docs/i18n/pt/docs/I18N.md b/docs/i18n/pt/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/pt/docs/I18N.md
rename to docs/i18n/pt/docs/guides/I18N.md
index 868e52eca5..d3561b3f39 100644
--- a/docs/i18n/pt/docs/I18N.md
+++ b/docs/i18n/pt/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/pt/docs/TROUBLESHOOTING.md b/docs/i18n/pt/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/pt/docs/TROUBLESHOOTING.md
rename to docs/i18n/pt/docs/guides/TROUBLESHOOTING.md
index 859151adc6..00914abc61 100644
--- a/docs/i18n/pt/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/pt/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/pt/docs/UNINSTALL.md b/docs/i18n/pt/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/pt/docs/UNINSTALL.md
rename to docs/i18n/pt/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/pt/docs/USER_GUIDE.md b/docs/i18n/pt/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/pt/docs/USER_GUIDE.md
rename to docs/i18n/pt/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/pt/docs/COVERAGE_PLAN.md b/docs/i18n/pt/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/pt/docs/COVERAGE_PLAN.md
rename to docs/i18n/pt/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/pt/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/pt/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/pt/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/pt/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/pt/docs/RELEASE_CHECKLIST.md b/docs/i18n/pt/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/pt/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/pt/docs/ops/RELEASE_CHECKLIST.md
index 7da2fdeee8..025b360d9c 100644
--- a/docs/i18n/pt/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/pt/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/pt/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/pt/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/pt/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/pt/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/pt/docs/API_REFERENCE.md b/docs/i18n/pt/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/pt/docs/API_REFERENCE.md
rename to docs/i18n/pt/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/pt/docs/CLI-TOOLS.md b/docs/i18n/pt/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/pt/docs/CLI-TOOLS.md
rename to docs/i18n/pt/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/pt/docs/ENVIRONMENT.md b/docs/i18n/pt/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/pt/docs/ENVIRONMENT.md
rename to docs/i18n/pt/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/pt/docs/AUTO-COMBO.md b/docs/i18n/pt/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/pt/docs/AUTO-COMBO.md
rename to docs/i18n/pt/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/pt/llm.txt b/docs/i18n/pt/llm.txt
index 5a996733a1..b580eb63e5 100644
--- a/docs/i18n/pt/llm.txt
+++ b/docs/i18n/pt/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/ro/CHANGELOG.md b/docs/i18n/ro/CHANGELOG.md
index 280978130b..1b9740a6df 100644
--- a/docs/i18n/ro/CHANGELOG.md
+++ b/docs/i18n/ro/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/ro/CONTRIBUTING.md b/docs/i18n/ro/CONTRIBUTING.md
index 8b8057ed7c..3b590380db 100644
--- a/docs/i18n/ro/CONTRIBUTING.md
+++ b/docs/i18n/ro/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/ro/README.md b/docs/i18n/ro/README.md
index 2c71b54ebd..d093296081 100644
--- a/docs/i18n/ro/README.md
+++ b/docs/i18n/ro/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentație
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/ro/docs/ARCHITECTURE.md b/docs/i18n/ro/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/ro/docs/ARCHITECTURE.md
rename to docs/i18n/ro/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/ro/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/ro/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/ro/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/ro/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/ro/docs/A2A-SERVER.md b/docs/i18n/ro/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/ro/docs/A2A-SERVER.md
rename to docs/i18n/ro/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/ro/docs/MCP-SERVER.md b/docs/i18n/ro/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/ro/docs/MCP-SERVER.md
rename to docs/i18n/ro/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/ro/docs/FEATURES.md b/docs/i18n/ro/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/ro/docs/FEATURES.md
rename to docs/i18n/ro/docs/guides/FEATURES.md
diff --git a/docs/i18n/ro/docs/I18N.md b/docs/i18n/ro/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/ro/docs/I18N.md
rename to docs/i18n/ro/docs/guides/I18N.md
index 75177748a1..e7f6e94720 100644
--- a/docs/i18n/ro/docs/I18N.md
+++ b/docs/i18n/ro/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/ro/docs/TROUBLESHOOTING.md b/docs/i18n/ro/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/ro/docs/TROUBLESHOOTING.md
rename to docs/i18n/ro/docs/guides/TROUBLESHOOTING.md
index 81043c9a37..298dc196f9 100644
--- a/docs/i18n/ro/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/ro/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/ro/docs/UNINSTALL.md b/docs/i18n/ro/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/ro/docs/UNINSTALL.md
rename to docs/i18n/ro/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/ro/docs/USER_GUIDE.md b/docs/i18n/ro/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/ro/docs/USER_GUIDE.md
rename to docs/i18n/ro/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/ro/docs/COVERAGE_PLAN.md b/docs/i18n/ro/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/ro/docs/COVERAGE_PLAN.md
rename to docs/i18n/ro/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/ro/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/ro/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ro/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ro/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ro/docs/RELEASE_CHECKLIST.md b/docs/i18n/ro/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/ro/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/ro/docs/ops/RELEASE_CHECKLIST.md
index b2bc96dcde..905d05a5da 100644
--- a/docs/i18n/ro/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/ro/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/ro/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ro/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ro/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ro/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ro/docs/API_REFERENCE.md b/docs/i18n/ro/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/ro/docs/API_REFERENCE.md
rename to docs/i18n/ro/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/ro/docs/CLI-TOOLS.md b/docs/i18n/ro/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/ro/docs/CLI-TOOLS.md
rename to docs/i18n/ro/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/ro/docs/ENVIRONMENT.md b/docs/i18n/ro/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/ro/docs/ENVIRONMENT.md
rename to docs/i18n/ro/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/ro/docs/AUTO-COMBO.md b/docs/i18n/ro/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/ro/docs/AUTO-COMBO.md
rename to docs/i18n/ro/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/ro/llm.txt b/docs/i18n/ro/llm.txt
index 820e67516a..4b5e16c1ab 100644
--- a/docs/i18n/ro/llm.txt
+++ b/docs/i18n/ro/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/ru/CHANGELOG.md b/docs/i18n/ru/CHANGELOG.md
index 6accb1e881..6219c06149 100644
--- a/docs/i18n/ru/CHANGELOG.md
+++ b/docs/i18n/ru/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/ru/CONTRIBUTING.md b/docs/i18n/ru/CONTRIBUTING.md
index d9c4fa94e1..4e57f76533 100644
--- a/docs/i18n/ru/CONTRIBUTING.md
+++ b/docs/i18n/ru/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/ru/README.md b/docs/i18n/ru/README.md
index 4a2a384558..2273678d9b 100644
--- a/docs/i18n/ru/README.md
+++ b/docs/i18n/ru/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Документация
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/ru/docs/ARCHITECTURE.md b/docs/i18n/ru/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/ru/docs/ARCHITECTURE.md
rename to docs/i18n/ru/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/ru/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/ru/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/ru/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/ru/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/ru/docs/A2A-SERVER.md b/docs/i18n/ru/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/ru/docs/A2A-SERVER.md
rename to docs/i18n/ru/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/ru/docs/MCP-SERVER.md b/docs/i18n/ru/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/ru/docs/MCP-SERVER.md
rename to docs/i18n/ru/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/ru/docs/FEATURES.md b/docs/i18n/ru/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/ru/docs/FEATURES.md
rename to docs/i18n/ru/docs/guides/FEATURES.md
diff --git a/docs/i18n/ru/docs/I18N.md b/docs/i18n/ru/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/ru/docs/I18N.md
rename to docs/i18n/ru/docs/guides/I18N.md
index cfa5f8d303..87279292f0 100644
--- a/docs/i18n/ru/docs/I18N.md
+++ b/docs/i18n/ru/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/ru/docs/TROUBLESHOOTING.md b/docs/i18n/ru/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/ru/docs/TROUBLESHOOTING.md
rename to docs/i18n/ru/docs/guides/TROUBLESHOOTING.md
index 9095358ebc..9fa7cd15ad 100644
--- a/docs/i18n/ru/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/ru/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/ru/docs/UNINSTALL.md b/docs/i18n/ru/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/ru/docs/UNINSTALL.md
rename to docs/i18n/ru/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/ru/docs/USER_GUIDE.md b/docs/i18n/ru/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/ru/docs/USER_GUIDE.md
rename to docs/i18n/ru/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/ru/docs/COVERAGE_PLAN.md b/docs/i18n/ru/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/ru/docs/COVERAGE_PLAN.md
rename to docs/i18n/ru/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/ru/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/ru/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ru/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ru/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ru/docs/RELEASE_CHECKLIST.md b/docs/i18n/ru/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/ru/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/ru/docs/ops/RELEASE_CHECKLIST.md
index 71c8666811..5a75c470f4 100644
--- a/docs/i18n/ru/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/ru/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/ru/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ru/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ru/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ru/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ru/docs/API_REFERENCE.md b/docs/i18n/ru/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/ru/docs/API_REFERENCE.md
rename to docs/i18n/ru/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/ru/docs/CLI-TOOLS.md b/docs/i18n/ru/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/ru/docs/CLI-TOOLS.md
rename to docs/i18n/ru/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/ru/docs/ENVIRONMENT.md b/docs/i18n/ru/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/ru/docs/ENVIRONMENT.md
rename to docs/i18n/ru/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/ru/docs/AUTO-COMBO.md b/docs/i18n/ru/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/ru/docs/AUTO-COMBO.md
rename to docs/i18n/ru/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/ru/llm.txt b/docs/i18n/ru/llm.txt
index 05de9ed5e8..a523e0186d 100644
--- a/docs/i18n/ru/llm.txt
+++ b/docs/i18n/ru/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/sk/CHANGELOG.md b/docs/i18n/sk/CHANGELOG.md
index 4a39586fb5..ea1db32aa7 100644
--- a/docs/i18n/sk/CHANGELOG.md
+++ b/docs/i18n/sk/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/sk/CONTRIBUTING.md b/docs/i18n/sk/CONTRIBUTING.md
index bd838f7196..677750df6f 100644
--- a/docs/i18n/sk/CONTRIBUTING.md
+++ b/docs/i18n/sk/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/sk/README.md b/docs/i18n/sk/README.md
index aa3c743a3d..acb0194cec 100644
--- a/docs/i18n/sk/README.md
+++ b/docs/i18n/sk/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Dokumentácia
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/sk/docs/ARCHITECTURE.md b/docs/i18n/sk/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/sk/docs/ARCHITECTURE.md
rename to docs/i18n/sk/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/sk/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/sk/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/sk/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/sk/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/sk/docs/A2A-SERVER.md b/docs/i18n/sk/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/sk/docs/A2A-SERVER.md
rename to docs/i18n/sk/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/sk/docs/MCP-SERVER.md b/docs/i18n/sk/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/sk/docs/MCP-SERVER.md
rename to docs/i18n/sk/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/sk/docs/FEATURES.md b/docs/i18n/sk/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/sk/docs/FEATURES.md
rename to docs/i18n/sk/docs/guides/FEATURES.md
diff --git a/docs/i18n/sk/docs/I18N.md b/docs/i18n/sk/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/sk/docs/I18N.md
rename to docs/i18n/sk/docs/guides/I18N.md
index 730fb28193..a606ffe0a0 100644
--- a/docs/i18n/sk/docs/I18N.md
+++ b/docs/i18n/sk/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/sk/docs/TROUBLESHOOTING.md b/docs/i18n/sk/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/sk/docs/TROUBLESHOOTING.md
rename to docs/i18n/sk/docs/guides/TROUBLESHOOTING.md
index cc0df932fd..69e37c671d 100644
--- a/docs/i18n/sk/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/sk/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/sk/docs/UNINSTALL.md b/docs/i18n/sk/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/sk/docs/UNINSTALL.md
rename to docs/i18n/sk/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/sk/docs/USER_GUIDE.md b/docs/i18n/sk/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/sk/docs/USER_GUIDE.md
rename to docs/i18n/sk/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/sk/docs/COVERAGE_PLAN.md b/docs/i18n/sk/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/sk/docs/COVERAGE_PLAN.md
rename to docs/i18n/sk/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/sk/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/sk/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/sk/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/sk/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/sk/docs/RELEASE_CHECKLIST.md b/docs/i18n/sk/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/sk/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/sk/docs/ops/RELEASE_CHECKLIST.md
index 9ed21278c1..80ec87e341 100644
--- a/docs/i18n/sk/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/sk/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/sk/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/sk/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/sk/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/sk/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/sk/docs/API_REFERENCE.md b/docs/i18n/sk/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/sk/docs/API_REFERENCE.md
rename to docs/i18n/sk/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/sk/docs/CLI-TOOLS.md b/docs/i18n/sk/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/sk/docs/CLI-TOOLS.md
rename to docs/i18n/sk/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/sk/docs/ENVIRONMENT.md b/docs/i18n/sk/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/sk/docs/ENVIRONMENT.md
rename to docs/i18n/sk/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/sk/docs/AUTO-COMBO.md b/docs/i18n/sk/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/sk/docs/AUTO-COMBO.md
rename to docs/i18n/sk/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/sk/llm.txt b/docs/i18n/sk/llm.txt
index a52e4424f0..6bf44b5000 100644
--- a/docs/i18n/sk/llm.txt
+++ b/docs/i18n/sk/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/sv/CHANGELOG.md b/docs/i18n/sv/CHANGELOG.md
index c5ea260133..4baacbf190 100644
--- a/docs/i18n/sv/CHANGELOG.md
+++ b/docs/i18n/sv/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/sv/CONTRIBUTING.md b/docs/i18n/sv/CONTRIBUTING.md
index badf89519f..6509c1f5c3 100644
--- a/docs/i18n/sv/CONTRIBUTING.md
+++ b/docs/i18n/sv/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/sv/README.md b/docs/i18n/sv/README.md
index 298d243955..887ef03464 100644
--- a/docs/i18n/sv/README.md
+++ b/docs/i18n/sv/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Dokumentation
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/sv/docs/ARCHITECTURE.md b/docs/i18n/sv/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/sv/docs/ARCHITECTURE.md
rename to docs/i18n/sv/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/sv/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/sv/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/sv/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/sv/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/sv/docs/A2A-SERVER.md b/docs/i18n/sv/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/sv/docs/A2A-SERVER.md
rename to docs/i18n/sv/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/sv/docs/MCP-SERVER.md b/docs/i18n/sv/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/sv/docs/MCP-SERVER.md
rename to docs/i18n/sv/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/sv/docs/FEATURES.md b/docs/i18n/sv/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/sv/docs/FEATURES.md
rename to docs/i18n/sv/docs/guides/FEATURES.md
diff --git a/docs/i18n/sv/docs/I18N.md b/docs/i18n/sv/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/sv/docs/I18N.md
rename to docs/i18n/sv/docs/guides/I18N.md
index fb4cc6724e..327e647112 100644
--- a/docs/i18n/sv/docs/I18N.md
+++ b/docs/i18n/sv/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/sv/docs/TROUBLESHOOTING.md b/docs/i18n/sv/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/sv/docs/TROUBLESHOOTING.md
rename to docs/i18n/sv/docs/guides/TROUBLESHOOTING.md
index f9d04efd71..aafabe2f6f 100644
--- a/docs/i18n/sv/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/sv/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/sv/docs/UNINSTALL.md b/docs/i18n/sv/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/sv/docs/UNINSTALL.md
rename to docs/i18n/sv/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/sv/docs/USER_GUIDE.md b/docs/i18n/sv/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/sv/docs/USER_GUIDE.md
rename to docs/i18n/sv/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/sv/docs/COVERAGE_PLAN.md b/docs/i18n/sv/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/sv/docs/COVERAGE_PLAN.md
rename to docs/i18n/sv/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/sv/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/sv/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/sv/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/sv/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/sv/docs/RELEASE_CHECKLIST.md b/docs/i18n/sv/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/sv/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/sv/docs/ops/RELEASE_CHECKLIST.md
index 27a3be9488..8d03464d6e 100644
--- a/docs/i18n/sv/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/sv/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/sv/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/sv/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/sv/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/sv/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/sv/docs/API_REFERENCE.md b/docs/i18n/sv/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/sv/docs/API_REFERENCE.md
rename to docs/i18n/sv/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/sv/docs/CLI-TOOLS.md b/docs/i18n/sv/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/sv/docs/CLI-TOOLS.md
rename to docs/i18n/sv/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/sv/docs/ENVIRONMENT.md b/docs/i18n/sv/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/sv/docs/ENVIRONMENT.md
rename to docs/i18n/sv/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/sv/docs/AUTO-COMBO.md b/docs/i18n/sv/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/sv/docs/AUTO-COMBO.md
rename to docs/i18n/sv/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/sv/llm.txt b/docs/i18n/sv/llm.txt
index 9763509bf5..07e2cebb81 100644
--- a/docs/i18n/sv/llm.txt
+++ b/docs/i18n/sv/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/sw/CHANGELOG.md b/docs/i18n/sw/CHANGELOG.md
index e3c94ea81d..847e10ff90 100644
--- a/docs/i18n/sw/CHANGELOG.md
+++ b/docs/i18n/sw/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/sw/CONTRIBUTING.md b/docs/i18n/sw/CONTRIBUTING.md
index 165f664ff1..f05d33b53a 100644
--- a/docs/i18n/sw/CONTRIBUTING.md
+++ b/docs/i18n/sw/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/sw/README.md b/docs/i18n/sw/README.md
index db067e44ac..3a399c0b72 100644
--- a/docs/i18n/sw/README.md
+++ b/docs/i18n/sw/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentación
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/sw/docs/ARCHITECTURE.md b/docs/i18n/sw/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/sw/docs/ARCHITECTURE.md
rename to docs/i18n/sw/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/sw/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/sw/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/sw/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/sw/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/sw/docs/A2A-SERVER.md b/docs/i18n/sw/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/sw/docs/A2A-SERVER.md
rename to docs/i18n/sw/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/sw/docs/MCP-SERVER.md b/docs/i18n/sw/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/sw/docs/MCP-SERVER.md
rename to docs/i18n/sw/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/sw/docs/FEATURES.md b/docs/i18n/sw/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/sw/docs/FEATURES.md
rename to docs/i18n/sw/docs/guides/FEATURES.md
diff --git a/docs/i18n/sw/docs/I18N.md b/docs/i18n/sw/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/sw/docs/I18N.md
rename to docs/i18n/sw/docs/guides/I18N.md
index 74b495c242..ec2ad43df7 100644
--- a/docs/i18n/sw/docs/I18N.md
+++ b/docs/i18n/sw/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/sw/docs/TROUBLESHOOTING.md b/docs/i18n/sw/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/sw/docs/TROUBLESHOOTING.md
rename to docs/i18n/sw/docs/guides/TROUBLESHOOTING.md
index d627ca0715..2e501b3b0d 100644
--- a/docs/i18n/sw/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/sw/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/sw/docs/UNINSTALL.md b/docs/i18n/sw/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/sw/docs/UNINSTALL.md
rename to docs/i18n/sw/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/sw/docs/USER_GUIDE.md b/docs/i18n/sw/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/sw/docs/USER_GUIDE.md
rename to docs/i18n/sw/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/sw/docs/COVERAGE_PLAN.md b/docs/i18n/sw/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/sw/docs/COVERAGE_PLAN.md
rename to docs/i18n/sw/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/sw/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/sw/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/sw/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/sw/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/sw/docs/RELEASE_CHECKLIST.md b/docs/i18n/sw/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/sw/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/sw/docs/ops/RELEASE_CHECKLIST.md
index 2c25414513..f2e36d0e84 100644
--- a/docs/i18n/sw/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/sw/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/sw/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/sw/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/sw/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/sw/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/sw/docs/API_REFERENCE.md b/docs/i18n/sw/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/sw/docs/API_REFERENCE.md
rename to docs/i18n/sw/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/sw/docs/CLI-TOOLS.md b/docs/i18n/sw/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/sw/docs/CLI-TOOLS.md
rename to docs/i18n/sw/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/sw/docs/ENVIRONMENT.md b/docs/i18n/sw/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/sw/docs/ENVIRONMENT.md
rename to docs/i18n/sw/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/sw/docs/AUTO-COMBO.md b/docs/i18n/sw/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/sw/docs/AUTO-COMBO.md
rename to docs/i18n/sw/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/sw/llm.txt b/docs/i18n/sw/llm.txt
index 5bc44125ea..0c8165bf65 100644
--- a/docs/i18n/sw/llm.txt
+++ b/docs/i18n/sw/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/ta/CHANGELOG.md b/docs/i18n/ta/CHANGELOG.md
index 51ced7a4b1..9d804825ce 100644
--- a/docs/i18n/ta/CHANGELOG.md
+++ b/docs/i18n/ta/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/ta/CONTRIBUTING.md b/docs/i18n/ta/CONTRIBUTING.md
index cd3facbcae..188e0d7f56 100644
--- a/docs/i18n/ta/CONTRIBUTING.md
+++ b/docs/i18n/ta/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/ta/README.md b/docs/i18n/ta/README.md
index 0be49d8e50..b1ff3cc743 100644
--- a/docs/i18n/ta/README.md
+++ b/docs/i18n/ta/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentación
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/ta/docs/ARCHITECTURE.md b/docs/i18n/ta/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/ta/docs/ARCHITECTURE.md
rename to docs/i18n/ta/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/ta/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/ta/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/ta/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/ta/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/ta/docs/A2A-SERVER.md b/docs/i18n/ta/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/ta/docs/A2A-SERVER.md
rename to docs/i18n/ta/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/ta/docs/MCP-SERVER.md b/docs/i18n/ta/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/ta/docs/MCP-SERVER.md
rename to docs/i18n/ta/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/ta/docs/FEATURES.md b/docs/i18n/ta/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/ta/docs/FEATURES.md
rename to docs/i18n/ta/docs/guides/FEATURES.md
diff --git a/docs/i18n/ta/docs/I18N.md b/docs/i18n/ta/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/ta/docs/I18N.md
rename to docs/i18n/ta/docs/guides/I18N.md
index 13d2f896c0..679e0ae54e 100644
--- a/docs/i18n/ta/docs/I18N.md
+++ b/docs/i18n/ta/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/ta/docs/TROUBLESHOOTING.md b/docs/i18n/ta/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/ta/docs/TROUBLESHOOTING.md
rename to docs/i18n/ta/docs/guides/TROUBLESHOOTING.md
index cd6d0db066..9ee7d18489 100644
--- a/docs/i18n/ta/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/ta/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/ta/docs/UNINSTALL.md b/docs/i18n/ta/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/ta/docs/UNINSTALL.md
rename to docs/i18n/ta/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/ta/docs/USER_GUIDE.md b/docs/i18n/ta/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/ta/docs/USER_GUIDE.md
rename to docs/i18n/ta/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/ta/docs/COVERAGE_PLAN.md b/docs/i18n/ta/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/ta/docs/COVERAGE_PLAN.md
rename to docs/i18n/ta/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/ta/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/ta/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ta/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ta/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ta/docs/RELEASE_CHECKLIST.md b/docs/i18n/ta/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/ta/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/ta/docs/ops/RELEASE_CHECKLIST.md
index a275cb136a..0e679b7a4b 100644
--- a/docs/i18n/ta/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/ta/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/ta/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ta/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ta/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ta/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ta/docs/API_REFERENCE.md b/docs/i18n/ta/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/ta/docs/API_REFERENCE.md
rename to docs/i18n/ta/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/ta/docs/CLI-TOOLS.md b/docs/i18n/ta/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/ta/docs/CLI-TOOLS.md
rename to docs/i18n/ta/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/ta/docs/ENVIRONMENT.md b/docs/i18n/ta/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/ta/docs/ENVIRONMENT.md
rename to docs/i18n/ta/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/ta/docs/AUTO-COMBO.md b/docs/i18n/ta/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/ta/docs/AUTO-COMBO.md
rename to docs/i18n/ta/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/ta/llm.txt b/docs/i18n/ta/llm.txt
index a6c818cf92..62f0392dfc 100644
--- a/docs/i18n/ta/llm.txt
+++ b/docs/i18n/ta/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/te/CHANGELOG.md b/docs/i18n/te/CHANGELOG.md
index b76ad099d0..223be5d4ca 100644
--- a/docs/i18n/te/CHANGELOG.md
+++ b/docs/i18n/te/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/te/CONTRIBUTING.md b/docs/i18n/te/CONTRIBUTING.md
index 9898b8ff2e..a543a9422a 100644
--- a/docs/i18n/te/CONTRIBUTING.md
+++ b/docs/i18n/te/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/te/README.md b/docs/i18n/te/README.md
index fa7c3c41ac..a4df895043 100644
--- a/docs/i18n/te/README.md
+++ b/docs/i18n/te/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentación
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/te/docs/ARCHITECTURE.md b/docs/i18n/te/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/te/docs/ARCHITECTURE.md
rename to docs/i18n/te/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/te/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/te/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/te/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/te/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/te/docs/A2A-SERVER.md b/docs/i18n/te/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/te/docs/A2A-SERVER.md
rename to docs/i18n/te/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/te/docs/MCP-SERVER.md b/docs/i18n/te/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/te/docs/MCP-SERVER.md
rename to docs/i18n/te/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/te/docs/FEATURES.md b/docs/i18n/te/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/te/docs/FEATURES.md
rename to docs/i18n/te/docs/guides/FEATURES.md
diff --git a/docs/i18n/te/docs/I18N.md b/docs/i18n/te/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/te/docs/I18N.md
rename to docs/i18n/te/docs/guides/I18N.md
index 336c3be722..41a3fde528 100644
--- a/docs/i18n/te/docs/I18N.md
+++ b/docs/i18n/te/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/te/docs/TROUBLESHOOTING.md b/docs/i18n/te/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/te/docs/TROUBLESHOOTING.md
rename to docs/i18n/te/docs/guides/TROUBLESHOOTING.md
index 5a13f106b3..b2421aaa15 100644
--- a/docs/i18n/te/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/te/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/te/docs/UNINSTALL.md b/docs/i18n/te/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/te/docs/UNINSTALL.md
rename to docs/i18n/te/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/te/docs/USER_GUIDE.md b/docs/i18n/te/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/te/docs/USER_GUIDE.md
rename to docs/i18n/te/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/te/docs/COVERAGE_PLAN.md b/docs/i18n/te/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/te/docs/COVERAGE_PLAN.md
rename to docs/i18n/te/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/te/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/te/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/te/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/te/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/te/docs/RELEASE_CHECKLIST.md b/docs/i18n/te/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/te/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/te/docs/ops/RELEASE_CHECKLIST.md
index f3e0f7d363..172905ed12 100644
--- a/docs/i18n/te/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/te/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/te/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/te/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/te/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/te/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/te/docs/API_REFERENCE.md b/docs/i18n/te/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/te/docs/API_REFERENCE.md
rename to docs/i18n/te/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/te/docs/CLI-TOOLS.md b/docs/i18n/te/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/te/docs/CLI-TOOLS.md
rename to docs/i18n/te/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/te/docs/ENVIRONMENT.md b/docs/i18n/te/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/te/docs/ENVIRONMENT.md
rename to docs/i18n/te/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/te/docs/AUTO-COMBO.md b/docs/i18n/te/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/te/docs/AUTO-COMBO.md
rename to docs/i18n/te/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/te/llm.txt b/docs/i18n/te/llm.txt
index ed29612aad..90bfc5ed3f 100644
--- a/docs/i18n/te/llm.txt
+++ b/docs/i18n/te/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/th/CHANGELOG.md b/docs/i18n/th/CHANGELOG.md
index e9006ce8cb..1c18e1a99f 100644
--- a/docs/i18n/th/CHANGELOG.md
+++ b/docs/i18n/th/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/th/CONTRIBUTING.md b/docs/i18n/th/CONTRIBUTING.md
index 81f73ea9c3..40d412c63f 100644
--- a/docs/i18n/th/CONTRIBUTING.md
+++ b/docs/i18n/th/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/th/README.md b/docs/i18n/th/README.md
index 791cc41173..3310941bc0 100644
--- a/docs/i18n/th/README.md
+++ b/docs/i18n/th/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## เอกสาร
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/th/docs/ARCHITECTURE.md b/docs/i18n/th/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/th/docs/ARCHITECTURE.md
rename to docs/i18n/th/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/th/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/th/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/th/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/th/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/th/docs/A2A-SERVER.md b/docs/i18n/th/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/th/docs/A2A-SERVER.md
rename to docs/i18n/th/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/th/docs/MCP-SERVER.md b/docs/i18n/th/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/th/docs/MCP-SERVER.md
rename to docs/i18n/th/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/th/docs/FEATURES.md b/docs/i18n/th/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/th/docs/FEATURES.md
rename to docs/i18n/th/docs/guides/FEATURES.md
diff --git a/docs/i18n/th/docs/I18N.md b/docs/i18n/th/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/th/docs/I18N.md
rename to docs/i18n/th/docs/guides/I18N.md
index 72b1081f7e..ffb13810a5 100644
--- a/docs/i18n/th/docs/I18N.md
+++ b/docs/i18n/th/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/th/docs/TROUBLESHOOTING.md b/docs/i18n/th/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/th/docs/TROUBLESHOOTING.md
rename to docs/i18n/th/docs/guides/TROUBLESHOOTING.md
index e0343f007f..d26154aaad 100644
--- a/docs/i18n/th/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/th/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/th/docs/UNINSTALL.md b/docs/i18n/th/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/th/docs/UNINSTALL.md
rename to docs/i18n/th/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/th/docs/USER_GUIDE.md b/docs/i18n/th/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/th/docs/USER_GUIDE.md
rename to docs/i18n/th/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/th/docs/COVERAGE_PLAN.md b/docs/i18n/th/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/th/docs/COVERAGE_PLAN.md
rename to docs/i18n/th/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/th/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/th/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/th/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/th/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/th/docs/RELEASE_CHECKLIST.md b/docs/i18n/th/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/th/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/th/docs/ops/RELEASE_CHECKLIST.md
index 9f31a4e1b7..7295220227 100644
--- a/docs/i18n/th/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/th/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/th/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/th/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/th/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/th/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/th/docs/API_REFERENCE.md b/docs/i18n/th/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/th/docs/API_REFERENCE.md
rename to docs/i18n/th/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/th/docs/CLI-TOOLS.md b/docs/i18n/th/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/th/docs/CLI-TOOLS.md
rename to docs/i18n/th/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/th/docs/ENVIRONMENT.md b/docs/i18n/th/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/th/docs/ENVIRONMENT.md
rename to docs/i18n/th/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/th/docs/AUTO-COMBO.md b/docs/i18n/th/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/th/docs/AUTO-COMBO.md
rename to docs/i18n/th/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/th/llm.txt b/docs/i18n/th/llm.txt
index 2c76b7e3aa..175e0a0551 100644
--- a/docs/i18n/th/llm.txt
+++ b/docs/i18n/th/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/tr/CHANGELOG.md b/docs/i18n/tr/CHANGELOG.md
index 5b86d20a6b..6a76f5d58b 100644
--- a/docs/i18n/tr/CHANGELOG.md
+++ b/docs/i18n/tr/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/tr/CONTRIBUTING.md b/docs/i18n/tr/CONTRIBUTING.md
index 01cb7453ee..2d5a1cf7b1 100644
--- a/docs/i18n/tr/CONTRIBUTING.md
+++ b/docs/i18n/tr/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/tr/README.md b/docs/i18n/tr/README.md
index 9e73fd82af..7913d08756 100644
--- a/docs/i18n/tr/README.md
+++ b/docs/i18n/tr/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Belgeler
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/tr/docs/ARCHITECTURE.md b/docs/i18n/tr/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/tr/docs/ARCHITECTURE.md
rename to docs/i18n/tr/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/tr/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/tr/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/tr/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/tr/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/tr/docs/A2A-SERVER.md b/docs/i18n/tr/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/tr/docs/A2A-SERVER.md
rename to docs/i18n/tr/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/tr/docs/MCP-SERVER.md b/docs/i18n/tr/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/tr/docs/MCP-SERVER.md
rename to docs/i18n/tr/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/tr/docs/FEATURES.md b/docs/i18n/tr/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/tr/docs/FEATURES.md
rename to docs/i18n/tr/docs/guides/FEATURES.md
diff --git a/docs/i18n/tr/docs/I18N.md b/docs/i18n/tr/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/tr/docs/I18N.md
rename to docs/i18n/tr/docs/guides/I18N.md
index 372ee8fbe6..6ecb94e2af 100644
--- a/docs/i18n/tr/docs/I18N.md
+++ b/docs/i18n/tr/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/tr/docs/TROUBLESHOOTING.md b/docs/i18n/tr/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/tr/docs/TROUBLESHOOTING.md
rename to docs/i18n/tr/docs/guides/TROUBLESHOOTING.md
index 982b8ab94e..626660e0ee 100644
--- a/docs/i18n/tr/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/tr/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/tr/docs/UNINSTALL.md b/docs/i18n/tr/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/tr/docs/UNINSTALL.md
rename to docs/i18n/tr/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/tr/docs/USER_GUIDE.md b/docs/i18n/tr/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/tr/docs/USER_GUIDE.md
rename to docs/i18n/tr/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/tr/docs/COVERAGE_PLAN.md b/docs/i18n/tr/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/tr/docs/COVERAGE_PLAN.md
rename to docs/i18n/tr/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/tr/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/tr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/tr/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/tr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/tr/docs/RELEASE_CHECKLIST.md b/docs/i18n/tr/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/tr/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/tr/docs/ops/RELEASE_CHECKLIST.md
index a9ed14e791..23b681a69e 100644
--- a/docs/i18n/tr/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/tr/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/tr/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/tr/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/tr/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/tr/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/tr/docs/API_REFERENCE.md b/docs/i18n/tr/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/tr/docs/API_REFERENCE.md
rename to docs/i18n/tr/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/tr/docs/CLI-TOOLS.md b/docs/i18n/tr/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/tr/docs/CLI-TOOLS.md
rename to docs/i18n/tr/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/tr/docs/ENVIRONMENT.md b/docs/i18n/tr/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/tr/docs/ENVIRONMENT.md
rename to docs/i18n/tr/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/tr/docs/AUTO-COMBO.md b/docs/i18n/tr/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/tr/docs/AUTO-COMBO.md
rename to docs/i18n/tr/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/tr/llm.txt b/docs/i18n/tr/llm.txt
index 94e60c1ba6..ba869b155c 100644
--- a/docs/i18n/tr/llm.txt
+++ b/docs/i18n/tr/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/uk-UA/CHANGELOG.md b/docs/i18n/uk-UA/CHANGELOG.md
index bd741fc54a..3dbc00245a 100644
--- a/docs/i18n/uk-UA/CHANGELOG.md
+++ b/docs/i18n/uk-UA/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/uk-UA/CONTRIBUTING.md b/docs/i18n/uk-UA/CONTRIBUTING.md
index 3429c4b314..62ca1f5c6b 100644
--- a/docs/i18n/uk-UA/CONTRIBUTING.md
+++ b/docs/i18n/uk-UA/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/uk-UA/README.md b/docs/i18n/uk-UA/README.md
index 164291d59e..2b7cd0488e 100644
--- a/docs/i18n/uk-UA/README.md
+++ b/docs/i18n/uk-UA/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Документація
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/uk-UA/docs/ARCHITECTURE.md b/docs/i18n/uk-UA/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/uk-UA/docs/ARCHITECTURE.md
rename to docs/i18n/uk-UA/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/uk-UA/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/uk-UA/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/uk-UA/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/uk-UA/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/uk-UA/docs/A2A-SERVER.md b/docs/i18n/uk-UA/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/uk-UA/docs/A2A-SERVER.md
rename to docs/i18n/uk-UA/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/uk-UA/docs/MCP-SERVER.md b/docs/i18n/uk-UA/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/uk-UA/docs/MCP-SERVER.md
rename to docs/i18n/uk-UA/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/uk-UA/docs/FEATURES.md b/docs/i18n/uk-UA/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/uk-UA/docs/FEATURES.md
rename to docs/i18n/uk-UA/docs/guides/FEATURES.md
diff --git a/docs/i18n/uk-UA/docs/I18N.md b/docs/i18n/uk-UA/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/uk-UA/docs/I18N.md
rename to docs/i18n/uk-UA/docs/guides/I18N.md
index b468c09940..0b0e77329b 100644
--- a/docs/i18n/uk-UA/docs/I18N.md
+++ b/docs/i18n/uk-UA/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/uk-UA/docs/TROUBLESHOOTING.md b/docs/i18n/uk-UA/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/uk-UA/docs/TROUBLESHOOTING.md
rename to docs/i18n/uk-UA/docs/guides/TROUBLESHOOTING.md
index 067ef13b9b..e1a0a4d0b1 100644
--- a/docs/i18n/uk-UA/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/uk-UA/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/uk-UA/docs/UNINSTALL.md b/docs/i18n/uk-UA/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/uk-UA/docs/UNINSTALL.md
rename to docs/i18n/uk-UA/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/uk-UA/docs/USER_GUIDE.md b/docs/i18n/uk-UA/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/uk-UA/docs/USER_GUIDE.md
rename to docs/i18n/uk-UA/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/uk-UA/docs/COVERAGE_PLAN.md b/docs/i18n/uk-UA/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/uk-UA/docs/COVERAGE_PLAN.md
rename to docs/i18n/uk-UA/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/uk-UA/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/uk-UA/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/uk-UA/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/uk-UA/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/uk-UA/docs/RELEASE_CHECKLIST.md b/docs/i18n/uk-UA/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/uk-UA/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/uk-UA/docs/ops/RELEASE_CHECKLIST.md
index c2461ce436..c3905bef2f 100644
--- a/docs/i18n/uk-UA/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/uk-UA/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/uk-UA/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/uk-UA/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/uk-UA/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/uk-UA/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/uk-UA/docs/API_REFERENCE.md b/docs/i18n/uk-UA/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/uk-UA/docs/API_REFERENCE.md
rename to docs/i18n/uk-UA/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/uk-UA/docs/CLI-TOOLS.md b/docs/i18n/uk-UA/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/uk-UA/docs/CLI-TOOLS.md
rename to docs/i18n/uk-UA/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/uk-UA/docs/ENVIRONMENT.md b/docs/i18n/uk-UA/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/uk-UA/docs/ENVIRONMENT.md
rename to docs/i18n/uk-UA/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/uk-UA/docs/AUTO-COMBO.md b/docs/i18n/uk-UA/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/uk-UA/docs/AUTO-COMBO.md
rename to docs/i18n/uk-UA/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/uk-UA/llm.txt b/docs/i18n/uk-UA/llm.txt
index 7547505898..6f3fc024b0 100644
--- a/docs/i18n/uk-UA/llm.txt
+++ b/docs/i18n/uk-UA/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/ur/CHANGELOG.md b/docs/i18n/ur/CHANGELOG.md
index 814e6bd3ba..c2f5801582 100644
--- a/docs/i18n/ur/CHANGELOG.md
+++ b/docs/i18n/ur/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/ur/CONTRIBUTING.md b/docs/i18n/ur/CONTRIBUTING.md
index 007cd4b863..c9716461fb 100644
--- a/docs/i18n/ur/CONTRIBUTING.md
+++ b/docs/i18n/ur/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/ur/README.md b/docs/i18n/ur/README.md
index 49c4759369..08020c01b0 100644
--- a/docs/i18n/ur/README.md
+++ b/docs/i18n/ur/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Documentación
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/ur/docs/ARCHITECTURE.md b/docs/i18n/ur/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/ur/docs/ARCHITECTURE.md
rename to docs/i18n/ur/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/ur/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/ur/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/ur/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/ur/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/ur/docs/A2A-SERVER.md b/docs/i18n/ur/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/ur/docs/A2A-SERVER.md
rename to docs/i18n/ur/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/ur/docs/MCP-SERVER.md b/docs/i18n/ur/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/ur/docs/MCP-SERVER.md
rename to docs/i18n/ur/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/ur/docs/FEATURES.md b/docs/i18n/ur/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/ur/docs/FEATURES.md
rename to docs/i18n/ur/docs/guides/FEATURES.md
diff --git a/docs/i18n/ur/docs/I18N.md b/docs/i18n/ur/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/ur/docs/I18N.md
rename to docs/i18n/ur/docs/guides/I18N.md
index d2724aef25..793396ba59 100644
--- a/docs/i18n/ur/docs/I18N.md
+++ b/docs/i18n/ur/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/ur/docs/TROUBLESHOOTING.md b/docs/i18n/ur/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/ur/docs/TROUBLESHOOTING.md
rename to docs/i18n/ur/docs/guides/TROUBLESHOOTING.md
index 41dff9595d..43089bfd01 100644
--- a/docs/i18n/ur/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/ur/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/ur/docs/UNINSTALL.md b/docs/i18n/ur/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/ur/docs/UNINSTALL.md
rename to docs/i18n/ur/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/ur/docs/USER_GUIDE.md b/docs/i18n/ur/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/ur/docs/USER_GUIDE.md
rename to docs/i18n/ur/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/ur/docs/COVERAGE_PLAN.md b/docs/i18n/ur/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/ur/docs/COVERAGE_PLAN.md
rename to docs/i18n/ur/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/ur/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/ur/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ur/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ur/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ur/docs/RELEASE_CHECKLIST.md b/docs/i18n/ur/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/ur/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/ur/docs/ops/RELEASE_CHECKLIST.md
index 48dde6bfe8..2d95ec1545 100644
--- a/docs/i18n/ur/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/ur/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/ur/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ur/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/ur/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/ur/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/ur/docs/API_REFERENCE.md b/docs/i18n/ur/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/ur/docs/API_REFERENCE.md
rename to docs/i18n/ur/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/ur/docs/CLI-TOOLS.md b/docs/i18n/ur/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/ur/docs/CLI-TOOLS.md
rename to docs/i18n/ur/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/ur/docs/ENVIRONMENT.md b/docs/i18n/ur/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/ur/docs/ENVIRONMENT.md
rename to docs/i18n/ur/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/ur/docs/AUTO-COMBO.md b/docs/i18n/ur/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/ur/docs/AUTO-COMBO.md
rename to docs/i18n/ur/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/ur/llm.txt b/docs/i18n/ur/llm.txt
index 5a161021e2..7a90c7ce3f 100644
--- a/docs/i18n/ur/llm.txt
+++ b/docs/i18n/ur/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/vi/CHANGELOG.md b/docs/i18n/vi/CHANGELOG.md
index 8229604aeb..d3e965b790 100644
--- a/docs/i18n/vi/CHANGELOG.md
+++ b/docs/i18n/vi/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/vi/CONTRIBUTING.md b/docs/i18n/vi/CONTRIBUTING.md
index 900af1478e..bcfc476f46 100644
--- a/docs/i18n/vi/CONTRIBUTING.md
+++ b/docs/i18n/vi/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/vi/README.md b/docs/i18n/vi/README.md
index 430c018158..01a5942e79 100644
--- a/docs/i18n/vi/README.md
+++ b/docs/i18n/vi/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## Tài liệu
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/vi/docs/ARCHITECTURE.md b/docs/i18n/vi/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/vi/docs/ARCHITECTURE.md
rename to docs/i18n/vi/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/vi/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/vi/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/vi/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/vi/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/vi/docs/A2A-SERVER.md b/docs/i18n/vi/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/vi/docs/A2A-SERVER.md
rename to docs/i18n/vi/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/vi/docs/MCP-SERVER.md b/docs/i18n/vi/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/vi/docs/MCP-SERVER.md
rename to docs/i18n/vi/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/vi/docs/FEATURES.md b/docs/i18n/vi/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/vi/docs/FEATURES.md
rename to docs/i18n/vi/docs/guides/FEATURES.md
diff --git a/docs/i18n/vi/docs/I18N.md b/docs/i18n/vi/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/vi/docs/I18N.md
rename to docs/i18n/vi/docs/guides/I18N.md
index ba60c90883..6c5492915e 100644
--- a/docs/i18n/vi/docs/I18N.md
+++ b/docs/i18n/vi/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/vi/docs/TROUBLESHOOTING.md b/docs/i18n/vi/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/vi/docs/TROUBLESHOOTING.md
rename to docs/i18n/vi/docs/guides/TROUBLESHOOTING.md
index 1b98324743..3bf2e68129 100644
--- a/docs/i18n/vi/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/vi/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/vi/docs/UNINSTALL.md b/docs/i18n/vi/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/vi/docs/UNINSTALL.md
rename to docs/i18n/vi/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/vi/docs/USER_GUIDE.md b/docs/i18n/vi/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/vi/docs/USER_GUIDE.md
rename to docs/i18n/vi/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/vi/docs/COVERAGE_PLAN.md b/docs/i18n/vi/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/vi/docs/COVERAGE_PLAN.md
rename to docs/i18n/vi/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/vi/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/vi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/vi/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/vi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/vi/docs/RELEASE_CHECKLIST.md b/docs/i18n/vi/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/vi/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/vi/docs/ops/RELEASE_CHECKLIST.md
index da7adf8571..f72ba6c251 100644
--- a/docs/i18n/vi/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/vi/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/vi/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/vi/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/vi/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/vi/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/vi/docs/API_REFERENCE.md b/docs/i18n/vi/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/vi/docs/API_REFERENCE.md
rename to docs/i18n/vi/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/vi/docs/CLI-TOOLS.md b/docs/i18n/vi/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/vi/docs/CLI-TOOLS.md
rename to docs/i18n/vi/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/vi/docs/ENVIRONMENT.md b/docs/i18n/vi/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/vi/docs/ENVIRONMENT.md
rename to docs/i18n/vi/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/vi/docs/AUTO-COMBO.md b/docs/i18n/vi/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/vi/docs/AUTO-COMBO.md
rename to docs/i18n/vi/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/vi/llm.txt b/docs/i18n/vi/llm.txt
index 1d81a277ab..688a0ffcf3 100644
--- a/docs/i18n/vi/llm.txt
+++ b/docs/i18n/vi/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/i18n/zh-CN/CHANGELOG.md b/docs/i18n/zh-CN/CHANGELOG.md
index 81c84439ad..2751b31000 100644
--- a/docs/i18n/zh-CN/CHANGELOG.md
+++ b/docs/i18n/zh-CN/CHANGELOG.md
@@ -1310,7 +1310,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/docs/i18n/zh-CN/CONTRIBUTING.md b/docs/i18n/zh-CN/CONTRIBUTING.md
index 2ee612ad35..59ed06cb8a 100644
--- a/docs/i18n/zh-CN/CONTRIBUTING.md
+++ b/docs/i18n/zh-CN/CONTRIBUTING.md
@@ -153,7 +153,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
@@ -305,7 +305,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/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md
index 246cd3bc1f..2152d28b8b 100644
--- a/docs/i18n/zh-CN/README.md
+++ b/docs/i18n/zh-CN/README.md
@@ -2267,25 +2267,25 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux
## 文档
-| Document | Description |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
-| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+| Document | Description |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |
+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
+| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
+| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |
+| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
+| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
+| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
diff --git a/docs/i18n/zh-CN/docs/ARCHITECTURE.md b/docs/i18n/zh-CN/docs/architecture/ARCHITECTURE.md
similarity index 100%
rename from docs/i18n/zh-CN/docs/ARCHITECTURE.md
rename to docs/i18n/zh-CN/docs/architecture/ARCHITECTURE.md
diff --git a/docs/i18n/zh-CN/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/zh-CN/docs/architecture/CODEBASE_DOCUMENTATION.md
similarity index 100%
rename from docs/i18n/zh-CN/docs/CODEBASE_DOCUMENTATION.md
rename to docs/i18n/zh-CN/docs/architecture/CODEBASE_DOCUMENTATION.md
diff --git a/docs/i18n/zh-CN/docs/A2A-SERVER.md b/docs/i18n/zh-CN/docs/frameworks/A2A-SERVER.md
similarity index 100%
rename from docs/i18n/zh-CN/docs/A2A-SERVER.md
rename to docs/i18n/zh-CN/docs/frameworks/A2A-SERVER.md
diff --git a/docs/i18n/zh-CN/docs/MCP-SERVER.md b/docs/i18n/zh-CN/docs/frameworks/MCP-SERVER.md
similarity index 100%
rename from docs/i18n/zh-CN/docs/MCP-SERVER.md
rename to docs/i18n/zh-CN/docs/frameworks/MCP-SERVER.md
diff --git a/docs/i18n/zh-CN/docs/FEATURES.md b/docs/i18n/zh-CN/docs/guides/FEATURES.md
similarity index 100%
rename from docs/i18n/zh-CN/docs/FEATURES.md
rename to docs/i18n/zh-CN/docs/guides/FEATURES.md
diff --git a/docs/i18n/zh-CN/docs/I18N.md b/docs/i18n/zh-CN/docs/guides/I18N.md
similarity index 99%
rename from docs/i18n/zh-CN/docs/I18N.md
rename to docs/i18n/zh-CN/docs/guides/I18N.md
index 955d694262..d613d8db72 100644
--- a/docs/i18n/zh-CN/docs/I18N.md
+++ b/docs/i18n/zh-CN/docs/guides/I18N.md
@@ -420,7 +420,7 @@ The generator originally used `code: "in"` (deprecated Google Translate code) fo
### `docs/i18n/README.md` Is Auto-Generated
-The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/I18N.md` (this file) for hand-written documentation that should persist.
+The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### External Untranslatable Keys List
diff --git a/docs/i18n/zh-CN/docs/TROUBLESHOOTING.md b/docs/i18n/zh-CN/docs/guides/TROUBLESHOOTING.md
similarity index 98%
rename from docs/i18n/zh-CN/docs/TROUBLESHOOTING.md
rename to docs/i18n/zh-CN/docs/guides/TROUBLESHOOTING.md
index dbac2c443f..40cb6e53ef 100644
--- a/docs/i18n/zh-CN/docs/TROUBLESHOOTING.md
+++ b/docs/i18n/zh-CN/docs/guides/TROUBLESHOOTING.md
@@ -335,7 +335,7 @@ You can ignore this section if you do not run RAG or agent pipelines behind Omni
## Still Stuck?
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
-- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
+- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
+- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
diff --git a/docs/i18n/zh-CN/docs/UNINSTALL.md b/docs/i18n/zh-CN/docs/guides/UNINSTALL.md
similarity index 100%
rename from docs/i18n/zh-CN/docs/UNINSTALL.md
rename to docs/i18n/zh-CN/docs/guides/UNINSTALL.md
diff --git a/docs/i18n/zh-CN/docs/USER_GUIDE.md b/docs/i18n/zh-CN/docs/guides/USER_GUIDE.md
similarity index 100%
rename from docs/i18n/zh-CN/docs/USER_GUIDE.md
rename to docs/i18n/zh-CN/docs/guides/USER_GUIDE.md
diff --git a/docs/i18n/zh-CN/docs/COVERAGE_PLAN.md b/docs/i18n/zh-CN/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/i18n/zh-CN/docs/COVERAGE_PLAN.md
rename to docs/i18n/zh-CN/docs/ops/COVERAGE_PLAN.md
diff --git a/docs/i18n/zh-CN/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/zh-CN/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/zh-CN/docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/i18n/zh-CN/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/zh-CN/docs/RELEASE_CHECKLIST.md b/docs/i18n/zh-CN/docs/ops/RELEASE_CHECKLIST.md
similarity index 94%
rename from docs/i18n/zh-CN/docs/RELEASE_CHECKLIST.md
rename to docs/i18n/zh-CN/docs/ops/RELEASE_CHECKLIST.md
index 218b7a6fc2..5f60e67283 100644
--- a/docs/i18n/zh-CN/docs/RELEASE_CHECKLIST.md
+++ b/docs/i18n/zh-CN/docs/ops/RELEASE_CHECKLIST.md
@@ -16,14 +16,14 @@ Use this checklist before tagging or publishing a new OmniRoute release.
## API Docs
-1. Update `docs/openapi.yaml`:
+1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
## Runtime Docs
-1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
-2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
+1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
+2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
diff --git a/docs/i18n/zh-CN/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/zh-CN/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/i18n/zh-CN/docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/i18n/zh-CN/docs/ops/VM_DEPLOYMENT_GUIDE.md
diff --git a/docs/i18n/zh-CN/docs/API_REFERENCE.md b/docs/i18n/zh-CN/docs/reference/API_REFERENCE.md
similarity index 100%
rename from docs/i18n/zh-CN/docs/API_REFERENCE.md
rename to docs/i18n/zh-CN/docs/reference/API_REFERENCE.md
diff --git a/docs/i18n/zh-CN/docs/CLI-TOOLS.md b/docs/i18n/zh-CN/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/i18n/zh-CN/docs/CLI-TOOLS.md
rename to docs/i18n/zh-CN/docs/reference/CLI-TOOLS.md
diff --git a/docs/i18n/zh-CN/docs/ENVIRONMENT.md b/docs/i18n/zh-CN/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/i18n/zh-CN/docs/ENVIRONMENT.md
rename to docs/i18n/zh-CN/docs/reference/ENVIRONMENT.md
diff --git a/docs/i18n/zh-CN/docs/AUTO-COMBO.md b/docs/i18n/zh-CN/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/i18n/zh-CN/docs/AUTO-COMBO.md
rename to docs/i18n/zh-CN/docs/routing/AUTO-COMBO.md
diff --git a/docs/i18n/zh-CN/llm.txt b/docs/i18n/zh-CN/llm.txt
index 8dd20af3fc..e834391ef4 100644
--- a/docs/i18n/zh-CN/llm.txt
+++ b/docs/i18n/zh-CN/llm.txt
@@ -357,11 +357,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
@@ -472,7 +472,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.
@@ -489,11 +489,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
@@ -505,11 +505,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`
diff --git a/docs/COVERAGE_PLAN.md b/docs/ops/COVERAGE_PLAN.md
similarity index 100%
rename from docs/COVERAGE_PLAN.md
rename to docs/ops/COVERAGE_PLAN.md
diff --git a/docs/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
similarity index 100%
rename from docs/FLY_IO_DEPLOYMENT_GUIDE.md
rename to docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
diff --git a/docs/PROXY_GUIDE.md b/docs/ops/PROXY_GUIDE.md
similarity index 99%
rename from docs/PROXY_GUIDE.md
rename to docs/ops/PROXY_GUIDE.md
index 2660c56553..6955c168f7 100644
--- a/docs/PROXY_GUIDE.md
+++ b/docs/ops/PROXY_GUIDE.md
@@ -595,6 +595,6 @@ CREATE TABLE proxy_assignments (
> 📖 **Related documentation:**
>
-> - [User Guide](USER_GUIDE.md) — General setup and configuration
-> - [API Reference](API_REFERENCE.md) — Full API documentation
-> - [Environment Config](ENVIRONMENT.md) — All environment variables
+> - [User Guide](../guides/USER_GUIDE.md) — General setup and configuration
+> - [API Reference](../reference/API_REFERENCE.md) — Full API documentation
+> - [Environment Config](../reference/ENVIRONMENT.md) — All environment variables
diff --git a/docs/RELEASE_CHECKLIST.md b/docs/ops/RELEASE_CHECKLIST.md
similarity index 92%
rename from docs/RELEASE_CHECKLIST.md
rename to docs/ops/RELEASE_CHECKLIST.md
index bb450c9b6b..6c9d73edc5 100644
--- a/docs/RELEASE_CHECKLIST.md
+++ b/docs/ops/RELEASE_CHECKLIST.md
@@ -46,7 +46,7 @@ npm run test:e2e # optional but recommended
- [ ] Manually review CHANGELOG.md and clean up commit messages if needed
- [ ] Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version
- [ ] Keep `## [Unreleased]` as the first changelog section for upcoming work
-- [ ] Update `docs/openapi.yaml` → `info.version` must equal `package.json` version
+- [ ] Update `docs/reference/openapi.yaml` → `info.version` must equal `package.json` version
### Code Quality
@@ -91,13 +91,13 @@ Breaking changes: add `BREAKING CHANGE:` footer or `!` after the scope (e.g. `fe
### Documentation
- [ ] `npm run check:docs-sync` passes (auto-run by pre-commit)
-- [ ] `docs/ARCHITECTURE.md` reviewed for storage/runtime drift
-- [ ] `docs/TROUBLESHOOTING.md` reviewed for env var and operational drift
-- [ ] If `.env.example` changed: `docs/ENVIRONMENT.md` updated
-- [ ] If new feature has a UI: `docs/USER_GUIDE.md` mentions it
-- [ ] If new feature has API: `docs/API_REFERENCE.md` + `docs/openapi.yaml` updated
+- [ ] `docs/architecture/ARCHITECTURE.md` reviewed for storage/runtime drift
+- [ ] `docs/guides/TROUBLESHOOTING.md` reviewed for env var and operational drift
+- [ ] If `.env.example` changed: `docs/reference/ENVIRONMENT.md` updated
+- [ ] If new feature has a UI: `docs/guides/USER_GUIDE.md` mentions it
+- [ ] If new feature has API: `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` updated
- [ ] If new feature is a module: dedicated `docs/.md` exists
-- [ ] If breaking change: `docs/TROUBLESHOOTING.md` has migration note
+- [ ] If breaking change: `docs/guides/TROUBLESHOOTING.md` has migration note
### i18n
diff --git a/docs/TUNNELS_GUIDE.md b/docs/ops/TUNNELS_GUIDE.md
similarity index 98%
rename from docs/TUNNELS_GUIDE.md
rename to docs/ops/TUNNELS_GUIDE.md
index 3d1e3f136e..a3d8f8284b 100644
--- a/docs/TUNNELS_GUIDE.md
+++ b/docs/ops/TUNNELS_GUIDE.md
@@ -272,10 +272,10 @@ or run the daemon yourself (`sudo systemctl start tailscaled`).
- [PROXY_GUIDE.md](./PROXY_GUIDE.md) — outbound proxy (1proxy, SOCKS5, HTTP) for
egress traffic.
-- [ENVIRONMENT.md](./ENVIRONMENT.md) — full list of env vars including
+- [ENVIRONMENT.md](../reference/ENVIRONMENT.md) — full list of env vars including
`NEXT_PUBLIC_BASE_URL`.
- [FLY_IO_DEPLOYMENT_GUIDE.md](./FLY_IO_DEPLOYMENT_GUIDE.md),
- [DOCKER_GUIDE.md](./DOCKER_GUIDE.md) — alternatives to tunneling for stable
+ [DOCKER_GUIDE.md](../guides/DOCKER_GUIDE.md) — alternatives to tunneling for stable
public hosting.
- Source: `src/lib/{cloudflaredTunnel,ngrokTunnel,tailscaleTunnel}.ts`,
`src/app/api/tunnels/`.
diff --git a/docs/VM_DEPLOYMENT_GUIDE.md b/docs/ops/VM_DEPLOYMENT_GUIDE.md
similarity index 84%
rename from docs/VM_DEPLOYMENT_GUIDE.md
rename to docs/ops/VM_DEPLOYMENT_GUIDE.md
index 19dc21f150..3c334def6e 100644
--- a/docs/VM_DEPLOYMENT_GUIDE.md
+++ b/docs/ops/VM_DEPLOYMENT_GUIDE.md
@@ -1,6 +1,6 @@
# OmniRoute — Deployment Guide on VM with Cloudflare
-🌐 **Languages:** 🇺🇸 [English](VM_DEPLOYMENT_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/VM_DEPLOYMENT_GUIDE.md) | 🇪🇸 [Español](i18n/es/VM_DEPLOYMENT_GUIDE.md) | 🇫🇷 [Français](i18n/fr/VM_DEPLOYMENT_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/VM_DEPLOYMENT_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/VM_DEPLOYMENT_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/VM_DEPLOYMENT_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/VM_DEPLOYMENT_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/VM_DEPLOYMENT_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/VM_DEPLOYMENT_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/VM_DEPLOYMENT_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/VM_DEPLOYMENT_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/VM_DEPLOYMENT_GUIDE.md) | 🇧🇬 [Български](i18n/bg/VM_DEPLOYMENT_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/VM_DEPLOYMENT_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/VM_DEPLOYMENT_GUIDE.md) | 🇮🇱 [עברית](i18n/he/VM_DEPLOYMENT_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/VM_DEPLOYMENT_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/VM_DEPLOYMENT_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/VM_DEPLOYMENT_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/VM_DEPLOYMENT_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/VM_DEPLOYMENT_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/VM_DEPLOYMENT_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/VM_DEPLOYMENT_GUIDE.md) | 🇷🇴 [Română](i18n/ro/VM_DEPLOYMENT_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/VM_DEPLOYMENT_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/VM_DEPLOYMENT_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/VM_DEPLOYMENT_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/VM_DEPLOYMENT_GUIDE.md) | 🇨🇿 [Čeština](i18n/cs/VM_DEPLOYMENT_GUIDE.md)
+🌐 **Languages:** 🇺🇸 [English](./VM_DEPLOYMENT_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/VM_DEPLOYMENT_GUIDE.md) | 🇪🇸 [Español](i18n/es/VM_DEPLOYMENT_GUIDE.md) | 🇫🇷 [Français](i18n/fr/VM_DEPLOYMENT_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/VM_DEPLOYMENT_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/VM_DEPLOYMENT_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/VM_DEPLOYMENT_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/VM_DEPLOYMENT_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/VM_DEPLOYMENT_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/VM_DEPLOYMENT_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/VM_DEPLOYMENT_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/VM_DEPLOYMENT_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/VM_DEPLOYMENT_GUIDE.md) | 🇧🇬 [Български](i18n/bg/VM_DEPLOYMENT_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/VM_DEPLOYMENT_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/VM_DEPLOYMENT_GUIDE.md) | 🇮🇱 [עברית](i18n/he/VM_DEPLOYMENT_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/VM_DEPLOYMENT_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/VM_DEPLOYMENT_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/VM_DEPLOYMENT_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/VM_DEPLOYMENT_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/VM_DEPLOYMENT_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/VM_DEPLOYMENT_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/VM_DEPLOYMENT_GUIDE.md) | 🇷🇴 [Română](i18n/ro/VM_DEPLOYMENT_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/VM_DEPLOYMENT_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/VM_DEPLOYMENT_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/VM_DEPLOYMENT_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/VM_DEPLOYMENT_GUIDE.md) | 🇨🇿 [Čeština](i18n/cs/VM_DEPLOYMENT_GUIDE.md)
Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare.
diff --git a/docs/API_REFERENCE.md b/docs/reference/API_REFERENCE.md
similarity index 96%
rename from docs/API_REFERENCE.md
rename to docs/reference/API_REFERENCE.md
index dd73bacb21..861bd0cf07 100644
--- a/docs/API_REFERENCE.md
+++ b/docs/reference/API_REFERENCE.md
@@ -1,6 +1,6 @@
# API Reference
-🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) | 🇨🇿 [Čeština](i18n/cs/API_REFERENCE.md)
+🌐 **Languages:** 🇺🇸 [English](./API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) | 🇨🇿 [Čeština](i18n/cs/API_REFERENCE.md)
Complete reference for all OmniRoute API endpoints.
@@ -597,7 +597,7 @@ Content-Type: application/json
9. Usage, compression analytics, and request logs are recorded
10. Fallback applies on errors according to combo rules
-Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md)
+Full architecture reference: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)
---
diff --git a/docs/CLI-TOOLS.md b/docs/reference/CLI-TOOLS.md
similarity index 100%
rename from docs/CLI-TOOLS.md
rename to docs/reference/CLI-TOOLS.md
diff --git a/docs/ENVIRONMENT.md b/docs/reference/ENVIRONMENT.md
similarity index 100%
rename from docs/ENVIRONMENT.md
rename to docs/reference/ENVIRONMENT.md
diff --git a/docs/FREE_TIERS.md b/docs/reference/FREE_TIERS.md
similarity index 100%
rename from docs/FREE_TIERS.md
rename to docs/reference/FREE_TIERS.md
diff --git a/docs/PROVIDER_REFERENCE.md b/docs/reference/PROVIDER_REFERENCE.md
similarity index 99%
rename from docs/PROVIDER_REFERENCE.md
rename to docs/reference/PROVIDER_REFERENCE.md
index d9a4fc7923..ad0abb554d 100644
--- a/docs/PROVIDER_REFERENCE.md
+++ b/docs/reference/PROVIDER_REFERENCE.md
@@ -262,5 +262,5 @@ Use the dashboard at `/dashboard/providers` to enable, configure, and test each
## See Also
- [FREE_TIERS.md](./FREE_TIERS.md) — curated free-tier guide
-- [USER_GUIDE.md](./USER_GUIDE.md) — provider setup walkthrough
-- [ARCHITECTURE.md](./ARCHITECTURE.md) — overall architecture
+- [USER_GUIDE.md](../guides/USER_GUIDE.md) — provider setup walkthrough
+- [ARCHITECTURE.md](../architecture/ARCHITECTURE.md) — overall architecture
diff --git a/docs/openapi.yaml b/docs/reference/openapi.yaml
similarity index 100%
rename from docs/openapi.yaml
rename to docs/reference/openapi.yaml
diff --git a/docs/AUTO-COMBO.md b/docs/routing/AUTO-COMBO.md
similarity index 100%
rename from docs/AUTO-COMBO.md
rename to docs/routing/AUTO-COMBO.md
diff --git a/docs/REASONING_REPLAY.md b/docs/routing/REASONING_REPLAY.md
similarity index 97%
rename from docs/REASONING_REPLAY.md
rename to docs/routing/REASONING_REPLAY.md
index db67c3093b..e7a8811df7 100644
--- a/docs/REASONING_REPLAY.md
+++ b/docs/routing/REASONING_REPLAY.md
@@ -151,8 +151,8 @@ The cache exposes two endpoints under `src/app/api/cache/reasoning/route.ts`. Bo
## See Also
-- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — circuit breakers, cooldowns, model lockouts
-- [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) — diagnosing upstream 400s
+- [RESILIENCE_GUIDE.md](../architecture/RESILIENCE_GUIDE.md) — circuit breakers, cooldowns, model lockouts
+- [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — diagnosing upstream 400s
- Source: `src/lib/db/reasoningCache.ts`, `open-sse/services/reasoningCache.ts`, `open-sse/translator/index.ts`
- Migration: `src/lib/db/migrations/033_create_reasoning_cache.sql`
- API route: `src/app/api/cache/reasoning/route.ts`
diff --git a/docs/COMPLIANCE.md b/docs/security/COMPLIANCE.md
similarity index 97%
rename from docs/COMPLIANCE.md
rename to docs/security/COMPLIANCE.md
index 877f46710f..982369313f 100644
--- a/docs/COMPLIANCE.md
+++ b/docs/security/COMPLIANCE.md
@@ -217,8 +217,8 @@ provider-management routes when they emit credential events:
## See Also
-- [`docs/GUARDRAILS.md`](./GUARDRAILS.md) — PII masking, prompt injection
-- [`docs/MCP-SERVER.md`](./MCP-SERVER.md) — MCP tool catalog and scopes
-- [`docs/ENVIRONMENT.md`](./ENVIRONMENT.md) — full env var reference
+- [`docs/security/GUARDRAILS.md`](./GUARDRAILS.md) — PII masking, prompt injection
+- [`docs/frameworks/MCP-SERVER.md`](../frameworks/MCP-SERVER.md) — MCP tool catalog and scopes
+- [`docs/reference/ENVIRONMENT.md`](../reference/ENVIRONMENT.md) — full env var reference
- Source: `src/lib/compliance/`, `src/app/api/compliance/`,
`src/app/api/mcp/audit/`, `src/lib/logEnv.ts`
diff --git a/docs/GUARDRAILS.md b/docs/security/GUARDRAILS.md
similarity index 98%
rename from docs/GUARDRAILS.md
rename to docs/security/GUARDRAILS.md
index bb4b1e15ae..6185dd08f2 100644
--- a/docs/GUARDRAILS.md
+++ b/docs/security/GUARDRAILS.md
@@ -259,5 +259,5 @@ exercise the full flow without DB or network access.
prompt-injection and PII masking
- `src/shared/constants/visionBridgeDefaults.ts` — Vision Bridge defaults and
forced-bridge model list
-- `docs/RESILIENCE_GUIDE.md` — orthogonal layer (circuit breaker, cooldowns)
-- `docs/ENVIRONMENT.md` — full env var reference
+- `docs/architecture/RESILIENCE_GUIDE.md` — orthogonal layer (circuit breaker, cooldowns)
+- `docs/reference/ENVIRONMENT.md` — full env var reference
diff --git a/docs/STEALTH_GUIDE.md b/docs/security/STEALTH_GUIDE.md
similarity index 97%
rename from docs/STEALTH_GUIDE.md
rename to docs/security/STEALTH_GUIDE.md
index e9a4ad6038..308d663e6c 100644
--- a/docs/STEALTH_GUIDE.md
+++ b/docs/security/STEALTH_GUIDE.md
@@ -238,7 +238,7 @@ OmniRoute scrubs inbound client headers before forwarding so a request that arri
## See Also
-- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — what happens when a stealth path gets a `403`
-- [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
-- [ENVIRONMENT.md](./ENVIRONMENT.md) — full env reference
-- [CLI-TOOLS.md](./CLI-TOOLS.md) — operator view of the MITM workflow
+- [RESILIENCE_GUIDE.md](../architecture/RESILIENCE_GUIDE.md) — what happens when a stealth path gets a `403`
+- [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md)
+- [ENVIRONMENT.md](../reference/ENVIRONMENT.md) — full env reference
+- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — operator view of the MITM workflow
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`
diff --git a/open-sse/mcp-server/README.md b/open-sse/mcp-server/README.md
index 03a3774580..9c358d6599 100644
--- a/open-sse/mcp-server/README.md
+++ b/open-sse/mcp-server/README.md
@@ -2,7 +2,7 @@
> **Model Context Protocol server** that exposes OmniRoute's gateway intelligence as **37 tools** for AI agents.
>
-> **Source of truth for the full tool catalog and REST surface:** [`docs/MCP-SERVER.md`](../../docs/MCP-SERVER.md). This README focuses on architecture, configuration, and integration examples; the catalog below is a summary subset.
+> **Source of truth for the full tool catalog and REST surface:** [`docs/frameworks/MCP-SERVER.md`](../../docs/MCP-SERVER.md). This README focuses on architecture, configuration, and integration examples; the catalog below is a summary subset.
The MCP Server allows any AI agent (Claude Desktop, Cursor, VS Code Copilot, custom agents) to **monitor, control, and optimize** the OmniRoute AI gateway programmatically.
diff --git a/pr_metadata.json b/pr_metadata.json
deleted file mode 100644
index 37ad0c69a5..0000000000
--- a/pr_metadata.json
+++ /dev/null
@@ -1,2102 +0,0 @@
-[
- {
- "additions": 149,
- "author": {
- "id": "MDQ6VXNlcjM1NzM4Ng==",
- "is_bot": false,
- "login": "andrewmunsell",
- "name": "Andrew Munsell"
- },
- "baseRefName": "main",
- "body": "## Summary\r\n\r\n- Add tokens_compressed INTEGER column to call_logs (migration 041)\r\n- Capture compression savings from both legacy compressContext() and modular applyCompression() pipelines in chatCore.ts\r\n- Display inline ↓N purple badge in log list view tokens cell\r\n- Show \"Compressed: FROM → TO (-X%)\" badge in detail modal Input section\r\n- Bump CallLogArtifact schemaVersion from 4 to 5\r\n\r\n![\"CleanShot](\"https://github.com/user-attachments/assets/b8f9b623-0615-4bd3-b71a-1810eb6e41c4\")
\r\n![\"CleanShot](\"https://github.com/user-attachments/assets/58ebb33b-e7cb-417a-909e-99d9d58375b2\")
\r\n\r\n## Tests Added Or Updated\r\n\r\n- Add compression tokens unit tests\r\n",
- "createdAt": "2026-05-04T03:48:16Z",
- "deletions": 7,
- "files": [
- {
- "path": "open-sse/handlers/chatCore.ts",
- "additions": 7,
- "deletions": 0,
- "changeType": "MODIFIED"
- },
- {
- "path": "src/i18n/messages/en.json",
- "additions": 1,
- "deletions": 0,
- "changeType": "MODIFIED"
- },
- {
- "path": "src/lib/db/core.ts",
- "additions": 4,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "src/lib/db/migrationRunner.ts",
- "additions": 2,
- "deletions": 0,
- "changeType": "MODIFIED"
- },
- {
- "path": "src/lib/db/migrations/041_compression_tokens.sql",
- "additions": 4,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "src/lib/usage/callLogArtifacts.ts",
- "additions": 2,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "src/lib/usage/callLogs.ts",
- "additions": 8,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "src/lib/usage/migrations.ts",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "src/shared/components/RequestLoggerDetail.tsx",
- "additions": 10,
- "deletions": 0,
- "changeType": "MODIFIED"
- },
- {
- "path": "src/shared/components/RequestLoggerV2.tsx",
- "additions": 11,
- "deletions": 0,
- "changeType": "MODIFIED"
- },
- {
- "path": "tests/unit/call-log-cap.test.ts",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "tests/unit/compression-tokens.test.ts",
- "additions": 98,
- "deletions": 0,
- "changeType": "ADDED"
- }
- ],
- "headRefName": "emdash/indicate-compression-in-logs-use9w",
- "number": 1923,
- "title": "feat(logs): show compression tokens in request log UI"
- },
- {
- "additions": 1698,
- "author": {
- "id": "MDQ6VXNlcjE0OTIxOTgz",
- "is_bot": false,
- "login": "oyi77",
- "name": "Paijo"
- },
- "baseRefName": "release/v3.7.9",
- "body": "Adds automated model assessment, categorization, and self-healing system for omniroute combos.\n\n## The Problem\nWhen providers fail (rate limits, auth errors, model deprecation), combos silently degrade. Our production experience: 2+ hours manually testing models and updating 44 combos because most returned errors.\n\n## The Solution\nThree new domain modules:\n1. **Assessor** - Probes every provider/model pair (quick/standard/deep tiers)\n2. **Categorizer** - Classifies models by capability with fitness scores\n3. **SelfHealer** - Auto-fixes combos: removes dead models, reduces weights for rate-limited, emergency-adds working alternatives\n\n## New Files\n- src/domain/assessment/assessor.ts\n- src/domain/assessment/categorizer.ts\n- src/domain/assessment/selfHealer.ts\n- src/domain/assessment/types.ts\n- src/domain/assessment/migration.ts\n- src/domain/assessment/index.ts\n- src/app/api/assess/route.ts\n- docs/RFC-AUTO-ASSESSMENT.md (full RFC)\n\n## New DB Tables\n- model_assessments, assessment_runs, combo_health, heal_actions\n\n## API\nPOST /api/assess/models - Run assessment\nGET /api/assess/models?action=working - Get working models\nGET /api/assess/models?action=combo-health - Get combo health\n\n> [!NOTE]\n> **OmniRoute Maintainer Note:** This PR has been deferred and will be accepted and redirected for the `v4.0.0` (or greater) release cycle. Please skip this PR during `v3.x` stabilization reviews.",
- "createdAt": "2026-05-03T20:53:04Z",
- "deletions": 0,
- "files": [
- {
- "path": "docs/RFC-AUTO-ASSESSMENT.md",
- "additions": 518,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "src/app/api/assess/route.ts",
- "additions": 110,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "src/domain/assessment/assessor.ts",
- "additions": 206,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "src/domain/assessment/categorizer.ts",
- "additions": 118,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "src/domain/assessment/index.ts",
- "additions": 24,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "src/domain/assessment/migration.ts",
- "additions": 109,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "src/domain/assessment/selfHealer.ts",
- "additions": 261,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "src/domain/assessment/types.ts",
- "additions": 352,
- "deletions": 0,
- "changeType": "ADDED"
- }
- ],
- "headRefName": "feat/auto-assessment-engine",
- "number": 1918,
- "title": "feat: Auto-Assessment and Self-Healing Combo Engine"
- },
- {
- "additions": 22666,
- "author": {
- "id": "MDQ6VXNlcjgwMTY4NDE=",
- "is_bot": false,
- "login": "diegosouzapw",
- "name": "Diego Rodrigues de Sa e Souza"
- },
- "baseRefName": "main",
- "body": "### ✨ New Features\n\n- **feat(compression):** major upgrade to Caveman and RTK compression pipelines (#1876, #1889):\n - Add RTK tool-output compression, stacked Caveman + RTK pipelines, compression combo assignments, dashboard context pages, MCP management tools, and language-aware Caveman rule packs.\n - Expand RTK parity with a 39-filter catalog, RTK-style JSON DSL stages, inline verify/benchmark coverage, trust-gated custom filters, expanded command detection, and redacted raw-output recovery.\n - Expose rule intensities, track USD savings, unify config validation, and persist MCP savings.\n - Expand Caveman parity and MCP metadata compression.\n- **feat(provider):** update Jina AI model catalog to support Embeddings and Rerank natively (#1874 — thanks @backryun)\n- **feat(provider):** add NanoGPT image generation provider (#1899 — thanks @Aculeasis)\n- **feat(ui):** move proxy configuration to dedicated System → Proxy page (#1907 — thanks @oyi77)\n- **feat(ui):** add K/M/B/T cost shortener utility (#1902 — thanks @oyi77)\n- **feat(providers):** implement bulk paste for extra API keys (#1916 — thanks @0xtbug)\n- **feat(analytics):** usage history API key backfill + dark mode pricing (#1896 — thanks @Gi99lin)\n\n### 🐛 Bug Fixes\n\n- **fix(providers):** allow local OpenAI-compatible endpoints (like Ollama) to be added without an API key (fixes #1893)\n- **fix(copilot):** emit compatible reasoning text deltas (#1919 — thanks @ivan-mezentsev)\n- **fix(api-manager):** show validation errors inline in modals, not behind (#1920 — thanks @andrewmunsell)\n- **fix(compression):** align seeded standard savings combo with stacked default, preserve stacked defaults, and secure metadata routes.\n- **fix(gemini-cli):** separate Cloud Code transport from Antigravity (#1869 — thanks @dhaern)\n- **fix(codex):** map prompt field to input array for Cursor compatibility (fixes #1872)\n- **fix(core):** align stream parameter default to false per strict OpenAI spec (fixes #1873)\n- **fix(ui):** restore Next.js CSP `unsafe-eval` in production `script-src` to fix unresponsive Onboarding button (fixes #1883)\n- **fix(proxy):** globally strip `prompt_cache_retention` in `BaseExecutor` to prevent upstream 400 errors from strict endpoints like droid/gemini-2-pro (fixes #1884)\n- **fix(ui):** include `isOpen` dependency in `EditConnectionModal` state sync to ensure `maxConcurrent` is properly hydrated when reopening the modal (fixes #1859)\n- **fix(security):** remediate 4 polynomial-redos CodeQL alerts in compression regexes by bounding repetitions and removing overlapping quantifiers\n- **fix(codex):** flatten Chat Completions tool format to Codex Responses format in `normalizeCodexTools` — prevents `Missing required parameter: tools[0].name` upstream errors (#1914 — thanks @tranduykhanh030)\n- **fix(proxy):** add proxy-aware execution context to image generation route — proxy settings are now correctly applied for image providers behind restricted networks (#1904 — thanks @Aculeasis)\n- **fix(translator):** inject `properties: {}` into zero-argument MCP tool schemas during Anthropic→OpenAI translation — prevents 400 errors from OpenAI strict schema validation (#1898 — thanks @bryceIT)\n- **fix(codex):** sanitize raw responses input (#1895 — thanks @dhaern)\n- **fix(combos):** align strategy contracts (#1892 — thanks @dhaern)\n- **fix(combos):** fix combo provider breaker profile handling (#1891 — thanks @rdself)\n- **fix(migrations):** duplicate-column no-op fix (#1886 — thanks @smartenok-ops)\n- **fix(auth):** per-connection OAuth refresh mutex (#1885 — thanks @smartenok-ops)\n- **fix(auth):** require dashboard management auth for compression preview\n\n### 📝 Documentation\n\n- **docs(compression):** document RTK+Caveman stacked savings ranges\n\n### 🏆 Release Attribution & Retroactive Credits\n\n- **@payne0420** (PR #1828 / #1839) — Implementation of the **Rate Limit Watchdog** and environment overrides. (This feature was manually backported to v3.7.8, causing the automatic GitHub Release notes to omit the author's credit).\n",
- "createdAt": "2026-05-03T20:35:53Z",
- "deletions": 1470,
- "files": [
- {
- "path": ".agents/workflows/deploy-vps-akamai.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": ".agents/workflows/deploy-vps-both.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": ".agents/workflows/deploy-vps-local.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": ".agents/workflows/generate-release.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": ".agents/workflows/version-bump.md",
- "additions": 9,
- "deletions": 9,
- "changeType": "MODIFIED"
- },
- {
- "path": "AGENTS.md",
- "additions": 25,
- "deletions": 9,
- "changeType": "MODIFIED"
- },
- {
- "path": "CHANGELOG.md",
- "additions": 47,
- "deletions": 0,
- "changeType": "MODIFIED"
- },
- {
- "path": "README.md",
- "additions": 71,
- "deletions": 29,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/API_REFERENCE.md",
- "additions": 32,
- "deletions": 13,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/ARCHITECTURE.md",
- "additions": 16,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/COMPRESSION_ENGINES.md",
- "additions": 143,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "docs/COMPRESSION_GUIDE.md",
- "additions": 105,
- "deletions": 12,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/COMPRESSION_LANGUAGE_PACKS.md",
- "additions": 96,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "docs/COMPRESSION_RULES_FORMAT.md",
- "additions": 186,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "docs/ENVIRONMENT.md",
- "additions": 6,
- "deletions": 0,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/FEATURES.md",
- "additions": 16,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/MCP-SERVER.md",
- "additions": 55,
- "deletions": 19,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/RTK_COMPRESSION.md",
- "additions": 234,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "docs/SETUP_GUIDE.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/openapi.yaml",
- "additions": 199,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "electron/package-lock.json",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "electron/package.json",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "llm.txt",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "next.config.mjs",
- "additions": 8,
- "deletions": 95,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/config/embeddingRegistry.ts",
- "additions": 62,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/config/imageRegistry.ts",
- "additions": 14,
- "deletions": 0,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/config/rerankRegistry.ts",
- "additions": 44,
- "deletions": 8,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/executors/base.ts",
- "additions": 3,
- "deletions": 0,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/executors/codex.ts",
- "additions": 75,
- "deletions": 5,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/handlers/chatCore.ts",
- "additions": 338,
- "deletions": 68,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/handlers/imageGeneration.ts",
- "additions": 1,
- "deletions": 0,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/handlers/responseSanitizer.ts",
- "additions": 3,
- "deletions": 0,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/mcp-server/README.md",
- "additions": 17,
- "deletions": 9,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/mcp-server/descriptionCompressor.ts",
- "additions": 243,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/mcp-server/schemas/tools.ts",
- "additions": 121,
- "deletions": 32,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/mcp-server/server.ts",
- "additions": 41,
- "deletions": 0,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/mcp-server/tools/advancedTools.ts",
- "additions": 15,
- "deletions": 16,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/mcp-server/tools/compressionTools.ts",
- "additions": 157,
- "deletions": 11,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/package.json",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/services/AGENTS.md",
- "additions": 5,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/services/accountFallback.ts",
- "additions": 21,
- "deletions": 5,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/services/autoCombo/index.ts",
- "additions": 1,
- "deletions": 10,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/services/combo.ts",
- "additions": 56,
- "deletions": 7,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/services/compression/aggressive.ts",
- "additions": 19,
- "deletions": 29,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/services/compression/caveman.ts",
- "additions": 310,
- "deletions": 31,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/services/compression/cavemanRules.ts",
- "additions": 189,
- "deletions": 15,
- "changeType": "MODIFIED"
- },
- {
- "path": "open-sse/services/compression/diffHelper.ts",
- "additions": 117,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/cavemanAdapter.ts",
- "additions": 408,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/index.ts",
- "additions": 14,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/registry.ts",
- "additions": 87,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/codeStripper.ts",
- "additions": 128,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/commandDetector.ts",
- "additions": 465,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/deduplicator.ts",
- "additions": 37,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filterLoader.ts",
- "additions": 220,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filterSchema.ts",
- "additions": 182,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/aws.json",
- "additions": 34,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/biome.json",
- "additions": 35,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/build-eslint.json",
- "additions": 37,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/build-typescript.json",
- "additions": 33,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/build-vite.json",
- "additions": 41,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/build-webpack.json",
- "additions": 34,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/bundle-install.json",
- "additions": 35,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/curl.json",
- "additions": 34,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/df.json",
- "additions": 34,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/docker-logs.json",
- "additions": 42,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/docker-ps.json",
- "additions": 33,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/du.json",
- "additions": 33,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/error-stacktrace.json",
- "additions": 41,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/gcloud.json",
- "additions": 34,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/generic-output.json",
- "additions": 32,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/git-branch.json",
- "additions": 45,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/git-diff.json",
- "additions": 33,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/git-log.json",
- "additions": 33,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/git-status.json",
- "additions": 40,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/golangci-lint.json",
- "additions": 34,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/json-output.json",
- "additions": 40,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/make.json",
- "additions": 38,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/mypy.json",
- "additions": 34,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/npm-audit.json",
- "additions": 43,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/npm-install.json",
- "additions": 41,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/nx.json",
- "additions": 34,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/pip.json",
- "additions": 41,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/playwright.json",
- "additions": 42,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/poetry-install.json",
- "additions": 35,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/prettier.json",
- "additions": 40,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/ps.json",
- "additions": 34,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/rsync.json",
- "additions": 33,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/rubocop.json",
- "additions": 34,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/ruff.json",
- "additions": 40,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/shell-find.json",
- "additions": 33,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/shell-grep.json",
- "additions": 37,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/shell-ls.json",
- "additions": 33,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/ssh.json",
- "additions": 43,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/systemctl-status.json",
- "additions": 43,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/terraform-plan.json",
- "additions": 34,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/test-cargo.json",
- "additions": 42,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/test-go.json",
- "additions": 41,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/test-jest.json",
- "additions": 43,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/test-pytest.json",
- "additions": 41,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "open-sse/services/compression/engines/rtk/filters/test-vitest.json",
- "additions": 43,
- "deletions": 0,
- "changeType": "ADDED"
- }
- ],
- "headRefName": "release/v3.7.9",
- "number": 1917,
- "title": "Release v3.7.9"
- },
- {
- "additions": 788,
- "author": {
- "id": "MDQ6VXNlcjI0MTk4NDIy",
- "is_bot": false,
- "login": "backryun",
- "name": "backryun"
- },
- "baseRefName": "release/v3.7.9",
- "body": "## Summary\r\n\r\ncompletely removing support for Node.js 20.\r\nNode.js 20 has reached EOL.\r\n![\"image\"](\"https://github.com/user-attachments/assets/f88758e4-fd6e-478e-88e4-8819d0c5e8e0\")
\r\n\r\n## Validation\r\n\r\n- [x] `npm run lint`\r\n- [x] `npm run test:unit`\r\n- [ ] `npm run test:coverage`\r\n- [ ] Coverage is still `>= 60%` for statements, lines, functions, and branches\r\n\r\n## Tests Added Or Updated\r\n\r\nUpdated automated test files:\r\n\r\n- `tests/unit/node-runtime-support.test.ts`\r\n- `tests/unit/chatcore-sanitization.test.ts`\r\n- `tests/unit/codex-stream-false.test.ts`\r\n- `tests/unit/t26-ai-sdk-accept-header-compat.test.ts`\r\n- `tests/integration/chat-pipeline.test.ts`\r\n- `tests/e2e/protocol-clients.test.ts`\r\n\r\nProduction code changed: Node runtime support logic was updated in `src/shared/utils/nodeRuntimeSupport.ts` and `bin/nodeRuntimeSupport.mjs`.\r\n\r\n## Coverage Notes\r\n\r\nThis PR changes `src/` and `bin/`.\r\n\r\nCoverage for the runtime support change is primarily provided by:\r\n\r\n- `tests/unit/node-runtime-support.test.ts`\r\n- `npm run check:node-runtime`\r\n\r\nAdditional regression coverage was run through:\r\n\r\n- `npm run test:unit`\r\n- `npm run test:integration`\r\n- `npm run test:e2e`\r\n- `npm run test:protocols:e2e`\r\n\r\n`npm run test:coverage` was not run, so coverage movement for touched files has not been measured yet. Follow-up before merge: run `npm run test:coverage` and confirm statements, lines, functions, and branches remain `>= 60%`.\r\n\r\n## Reviewer Notes\r\n\r\n- Node.js 20 support is removed from runtime policy, package engines, CI, docs, and runtime warning copy.\r\n- Supported runtime policy is now Node.js `>=22.22.2 <23 || >=24.0.0 <25`.\r\n- CI matrix and local version files now target Node 22/24 support.\r\n- Docs and i18n runtime wording were updated broadly; reviewers should expect many documentation-only diffs.\r\n- `tests/e2e/protocol-clients.test.ts` now explicitly enables A2A before validating the A2A flow, matching the current default where A2A starts disabled.\r\n- Manual validation was performed on Node `v22.22.2`.\n\n> [!NOTE]\n> **OmniRoute Maintainer Note:** This PR has been deferred and will be accepted and redirected for the `v4.0.0` (or greater) release cycle. Please skip this PR during `v3.x` stabilization reviews.",
- "createdAt": "2026-05-03T14:11:25Z",
- "deletions": 776,
- "files": [
- {
- "path": ".dockerignore",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": ".env.example",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": ".github/workflows/ci.yml",
- "additions": 8,
- "deletions": 5,
- "changeType": "MODIFIED"
- },
- {
- "path": ".npmignore",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "AGENTS.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "CLAUDE.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "CONTRIBUTING.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "Dockerfile",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "README.md",
- "additions": 10,
- "deletions": 10,
- "changeType": "MODIFIED"
- },
- {
- "path": "bin/nodeRuntimeSupport.mjs",
- "additions": 3,
- "deletions": 5,
- "changeType": "MODIFIED"
- },
- {
- "path": "compose.prod.yaml",
- "additions": 3,
- "deletions": 3,
- "changeType": "RENAMED"
- },
- {
- "path": "compose.yaml",
- "additions": 0,
- "deletions": 0,
- "changeType": "RENAMED"
- },
- {
- "path": "docs/CLI-TOOLS.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/ENVIRONMENT.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/FEATURES.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/RELEASE_CHECKLIST.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/TROUBLESHOOTING.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/ar/CONTRIBUTING.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/ar/README.md",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/ar/docs/CLI-TOOLS.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/ar/docs/ENVIRONMENT.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/ar/docs/FEATURES.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/ar/docs/RELEASE_CHECKLIST.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/ar/docs/TROUBLESHOOTING.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/ar/llm.txt",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bg/CONTRIBUTING.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bg/README.md",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bg/docs/CLI-TOOLS.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bg/docs/ENVIRONMENT.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bg/docs/FEATURES.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bg/docs/RELEASE_CHECKLIST.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bg/docs/TROUBLESHOOTING.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bg/llm.txt",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bn/CONTRIBUTING.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bn/README.md",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bn/docs/CLI-TOOLS.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bn/docs/ENVIRONMENT.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bn/docs/FEATURES.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bn/docs/RELEASE_CHECKLIST.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/bn/docs/TROUBLESHOOTING.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/CONTRIBUTING.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/README.md",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/CLI-TOOLS.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/ENVIRONMENT.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/FEATURES.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/RELEASE_CHECKLIST.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/TROUBLESHOOTING.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/llm.txt",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/da/CONTRIBUTING.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/da/README.md",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/da/docs/CLI-TOOLS.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/da/docs/ENVIRONMENT.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/da/docs/FEATURES.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/da/docs/RELEASE_CHECKLIST.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/da/docs/TROUBLESHOOTING.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/da/llm.txt",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/de/CONTRIBUTING.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/de/README.md",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/de/docs/CLI-TOOLS.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/de/docs/ENVIRONMENT.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/de/docs/FEATURES.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/de/docs/RELEASE_CHECKLIST.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/de/docs/TROUBLESHOOTING.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/de/llm.txt",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/es/CONTRIBUTING.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/es/README.md",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/es/docs/CLI-TOOLS.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/es/docs/ENVIRONMENT.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/es/docs/FEATURES.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/es/docs/RELEASE_CHECKLIST.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/es/docs/TROUBLESHOOTING.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/es/llm.txt",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fa/CONTRIBUTING.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fa/README.md",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fa/docs/CLI-TOOLS.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fa/docs/ENVIRONMENT.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fa/docs/FEATURES.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fa/docs/RELEASE_CHECKLIST.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fa/docs/TROUBLESHOOTING.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fi/CONTRIBUTING.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fi/README.md",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fi/docs/CLI-TOOLS.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fi/docs/ENVIRONMENT.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fi/docs/FEATURES.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fi/docs/RELEASE_CHECKLIST.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fi/docs/TROUBLESHOOTING.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fi/llm.txt",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fr/CONTRIBUTING.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fr/README.md",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fr/docs/CLI-TOOLS.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fr/docs/ENVIRONMENT.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fr/docs/FEATURES.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fr/docs/RELEASE_CHECKLIST.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fr/docs/TROUBLESHOOTING.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/fr/llm.txt",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/gu/CONTRIBUTING.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/gu/README.md",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/gu/docs/CLI-TOOLS.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/gu/docs/ENVIRONMENT.md",
- "additions": 3,
- "deletions": 3,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/gu/docs/FEATURES.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- }
- ],
- "headRefName": "release/v3.7.9",
- "number": 1915,
- "title": "[will be merge 4.0 update] (Security Fix): Drop node.js 20 support + Update docker files to lastest docker standards"
- },
- {
- "additions": 1119,
- "author": {
- "id": "U_kgDODPQT-Q",
- "is_bot": false,
- "login": "vrdons",
- "name": ""
- },
- "baseRefName": "release/v3.7.9",
- "body": "## Summary\r\n\r\nTo allow using on bun interface, faster typescript checks\r\n\r\n## Related Issues\r\nNone\r\n\r\n## Validation\r\n\r\n- [x] `npm run lint`\r\n- [ ] `npm run test:unit`\r\nNo, because last tests stucks\r\n- [x] `npm run test:coverage`\r\n- [ ] Coverage is still `>= 60%` for statements, lines, functions, and branches\r\n- [ ] SonarQube PR analysis is green or any remaining issues are explicitly documented below\r\n\r\n## Tests Added Or Updated\r\n\r\n- List every changed or added automated test file.\r\n- If no production code changed, state that here.\r\n\r\n## Coverage Notes\r\n\r\n- If this PR changes `src/`, `open-sse/`, `electron/`, or `bin/`, explain which tests cover the change.\r\n- If coverage moved down in any touched file, explain why and what follow-up task will recover it.\r\n\r\n## Reviewer Notes\r\n\r\n- Call out any risky areas, migrations, feature flags, or manual validation that reviewers should know about.\r\n\n> [!NOTE]\n> **OmniRoute Maintainer Note:** This PR has been deferred and will be accepted and redirected for the `v4.0.0` (or greater) release cycle. Please skip this PR during `v3.x` stabilization reviews.",
- "createdAt": "2026-05-02T17:57:46Z",
- "deletions": 231022,
- "files": [
- {
- "path": ".agents/workflows/deploy-vps-akamai.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": ".agents/workflows/deploy-vps-both.md",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": ".agents/workflows/deploy-vps-local.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": ".agents/workflows/generate-release.md",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "AGENTS.md",
- "additions": 4,
- "deletions": 4,
- "changeType": "MODIFIED"
- },
- {
- "path": "CLAUDE.md",
- "additions": 1,
- "deletions": 218,
- "changeType": "MODIFIED"
- },
- {
- "path": "GEMINI.md",
- "additions": 1,
- "deletions": 21,
- "changeType": "MODIFIED"
- },
- {
- "path": "README.md",
- "additions": 63,
- "deletions": 36,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/API_REFERENCE.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/ARCHITECTURE.md",
- "additions": 2,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/CODEBASE_DOCUMENTATION.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/ENVIRONMENT.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/FEATURES.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/I18N.md",
- "additions": 82,
- "deletions": 52,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/SETUP_GUIDE.md",
- "additions": 9,
- "deletions": 8,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/TERMUX_GUIDE.md",
- "additions": 2,
- "deletions": 10,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/TROUBLESHOOTING.md",
- "additions": 17,
- "deletions": 41,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/UNINSTALL.md",
- "additions": 12,
- "deletions": 12,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/USER_GUIDE.md",
- "additions": 2,
- "deletions": 10,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/VM_DEPLOYMENT_GUIDE.md",
- "additions": 1,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/ar/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/ar/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/ar/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/ar/README.md",
- "additions": 2,
- "deletions": 13,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/ar/llm.txt",
- "additions": 0,
- "deletions": 476,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/bg/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/bg/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/bg/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/bg/llm.txt",
- "additions": 0,
- "deletions": 476,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/bn/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/bn/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/bn/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/cs/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/cs/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/cs/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/cs/README.md",
- "additions": 0,
- "deletions": 2379,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/A2A-SERVER.md",
- "additions": 0,
- "deletions": 200,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/API_REFERENCE.md",
- "additions": 0,
- "deletions": 469,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/ARCHITECTURE.md",
- "additions": 0,
- "deletions": 891,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/AUTO-COMBO.md",
- "additions": 0,
- "deletions": 67,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/CLI-TOOLS.md",
- "additions": 0,
- "deletions": 398,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/CODEBASE_DOCUMENTATION.md",
- "additions": 0,
- "deletions": 591,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/COVERAGE_PLAN.md",
- "additions": 0,
- "deletions": 170,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/ENVIRONMENT.md",
- "additions": 0,
- "deletions": 669,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/FEATURES.md",
- "additions": 0,
- "deletions": 270,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/FLY_IO_DEPLOYMENT_GUIDE.md",
- "additions": 0,
- "deletions": 455,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/I18N.md",
- "additions": 0,
- "deletions": 441,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/MCP-SERVER.md",
- "additions": 0,
- "deletions": 87,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/RELEASE_CHECKLIST.md",
- "additions": 0,
- "deletions": 44,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/TROUBLESHOOTING.md",
- "additions": 0,
- "deletions": 341,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/UNINSTALL.md",
- "additions": 0,
- "deletions": 157,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/USER_GUIDE.md",
- "additions": 0,
- "deletions": 966,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/VM_DEPLOYMENT_GUIDE.md",
- "additions": 0,
- "deletions": 407,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/cloudflare-zero-trust-guide.md",
- "additions": 0,
- "deletions": 106,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/docs/features/context-relay.md",
- "additions": 0,
- "deletions": 130,
- "changeType": "MODIFIED"
- },
- {
- "path": "docs/i18n/cs/llm.txt",
- "additions": 0,
- "deletions": 476,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/da/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/da/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/da/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/da/llm.txt",
- "additions": 0,
- "deletions": 476,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/de/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/de/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/de/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/de/llm.txt",
- "additions": 0,
- "deletions": 476,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/es/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/es/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/es/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/es/llm.txt",
- "additions": 0,
- "deletions": 476,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/fa/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/fa/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/fa/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/fi/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/fi/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/fi/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/fi/llm.txt",
- "additions": 0,
- "deletions": 476,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/fr/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/fr/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/fr/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/fr/llm.txt",
- "additions": 0,
- "deletions": 476,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/gu/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/gu/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/gu/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/he/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/he/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/he/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/he/llm.txt",
- "additions": 0,
- "deletions": 476,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/hi/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/hi/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/hi/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/hi/llm.txt",
- "additions": 0,
- "deletions": 476,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/hu/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/hu/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/hu/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/hu/llm.txt",
- "additions": 0,
- "deletions": 476,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/id/CHANGELOG.md",
- "additions": 0,
- "deletions": 4921,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/id/CLAUDE.md",
- "additions": 0,
- "deletions": 233,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/id/GEMINI.md",
- "additions": 0,
- "deletions": 25,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/id/llm.txt",
- "additions": 0,
- "deletions": 476,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/in/CHANGELOG.md",
- "additions": 0,
- "deletions": 3232,
- "changeType": "DELETED"
- },
- {
- "path": "docs/i18n/in/CLAUDE.md",
- "additions": 0,
- "deletions": 229,
- "changeType": "DELETED"
- }
- ],
- "headRefName": "main",
- "number": 1894,
- "title": "refactor(db): migrate from better-sqlite3 to node:sqlite, use tsgo"
- },
- {
- "additions": 276,
- "author": {
- "id": "U_kgDOD9eSjQ",
- "is_bot": false,
- "login": "smartenok-ops",
- "name": ""
- },
- "baseRefName": "release/v3.7.9",
- "body": "When a codex SSE stream hits 429 mid-task, OmniRoute previously gave up (maxAttempts=1, no rotation). Add retry with account rotation when session affinity allows.\r\n\r\nDepends on: per-session sticky routing PR (extractSessionAffinityKey, deleteSessionAccountAffinity).\r\n\r\n## Summary\r\n\r\n- Describe the user-facing or operational change.\r\n\r\n## Related Issues\r\n\r\n- Closes #\r\n- Related to #\r\n\r\n## Validation\r\n\r\n- [ ] `npm run lint`\r\n- [ ] `npm run test:unit`\r\n- [ ] `npm run test:coverage`\r\n- [ ] Coverage is still `>= 60%` for statements, lines, functions, and branches\r\n- [ ] SonarQube PR analysis is green or any remaining issues are explicitly documented below\r\n\r\n## Tests Added Or Updated\r\n\r\n- List every changed or added automated test file.\r\n- If no production code changed, state that here.\r\n\r\n## Coverage Notes\r\n\r\n- If this PR changes `src/`, `open-sse/`, `electron/`, or `bin/`, explain which tests cover the change.\r\n- If coverage moved down in any touched file, explain why and what follow-up task will recover it.\r\n\r\n## Reviewer Notes\r\n\r\n- Call out any risky areas, migrations, feature flags, or manual validation that reviewers should know about.\r\n\n> [!NOTE]\n> **OmniRoute Maintainer Note:** This PR has been deferred and will be accepted and redirected for the `v4.0.0` (or greater) release cycle. Please skip this PR during `v3.x` stabilization reviews.",
- "createdAt": "2026-05-02T16:06:11Z",
- "deletions": 2,
- "files": [
- {
- "path": "open-sse/handlers/chatCore.ts",
- "additions": 84,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "tests/unit/codex-failover.test.ts",
- "additions": 192,
- "deletions": 0,
- "changeType": "ADDED"
- }
- ],
- "headRefName": "feat/codex-429-mid-task-failover",
- "number": 1888,
- "title": "feat(sse): codex 429 mid-task failover with account rotation"
- },
- {
- "additions": 461,
- "author": {
- "id": "U_kgDOD9eSjQ",
- "is_bot": false,
- "login": "smartenok-ops",
- "name": ""
- },
- "baseRefName": "release/v3.7.9",
- "body": "When concurrent SSE clients use a shared OmniRoute key, randomized account selection causes per-session inconsistencies (one stream hits account A, next request from same logical session hits B). Adds session_account_affinity table + extractSessionAffinityKey helper so a session_key (e.g. SHA of input headers) deterministically pins to one account for its lifetime.\r\n\r\nMigration: 041_session_account_affinity.sql (renumbered from local 026 — please confirm next available slot).\r\n\r\n## Summary\r\n\r\n- Describe the user-facing or operational change.\r\n\r\n## Related Issues\r\n\r\n- Closes #\r\n- Related to #\r\n\r\n## Validation\r\n\r\n- [ ] `npm run lint`\r\n- [ ] `npm run test:unit`\r\n- [ ] `npm run test:coverage`\r\n- [ ] Coverage is still `>= 60%` for statements, lines, functions, and branches\r\n- [ ] SonarQube PR analysis is green or any remaining issues are explicitly documented below\r\n\r\n## Tests Added Or Updated\r\n\r\n- List every changed or added automated test file.\r\n- If no production code changed, state that here.\r\n\r\n## Coverage Notes\r\n\r\n- If this PR changes `src/`, `open-sse/`, `electron/`, or `bin/`, explain which tests cover the change.\r\n- If coverage moved down in any touched file, explain why and what follow-up task will recover it.\r\n\r\n## Reviewer Notes\r\n\r\n- Call out any risky areas, migrations, feature flags, or manual validation that reviewers should know about.\r\n\n> [!NOTE]\n> **OmniRoute Maintainer Note:** This PR has been deferred and will be accepted and redirected for the `v4.0.0` (or greater) release cycle. Please skip this PR during `v3.x` stabilization reviews.",
- "createdAt": "2026-05-02T16:05:53Z",
- "deletions": 122,
- "files": [
- {
- "path": "src/instrumentation-node.ts",
- "additions": 10,
- "deletions": 5,
- "changeType": "MODIFIED"
- },
- {
- "path": "src/lib/db/migrations/041_session_account_affinity.sql",
- "additions": 11,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "src/lib/db/sessionAccountAffinity.ts",
- "additions": 122,
- "deletions": 0,
- "changeType": "ADDED"
- },
- {
- "path": "src/lib/localDb.ts",
- "additions": 10,
- "deletions": 0,
- "changeType": "MODIFIED"
- },
- {
- "path": "src/sse/handlers/chat.ts",
- "additions": 14,
- "deletions": 1,
- "changeType": "MODIFIED"
- },
- {
- "path": "src/sse/services/auth.ts",
- "additions": 177,
- "deletions": 2,
- "changeType": "MODIFIED"
- },
- {
- "path": "tests/unit/sse-auth.test.ts",
- "additions": 117,
- "deletions": 114,
- "changeType": "MODIFIED"
- }
- ],
- "headRefName": "feat/per-session-sticky-routing",
- "number": 1887,
- "title": "feat(auth): per-session sticky routing for codex"
- }
-]
diff --git a/scripts/build/pack-artifact-policy.ts b/scripts/build/pack-artifact-policy.ts
index 2a78ec3fce..f06a00e90e 100644
--- a/scripts/build/pack-artifact-policy.ts
+++ b/scripts/build/pack-artifact-policy.ts
@@ -29,7 +29,7 @@ export const APP_STAGING_REMOVAL_PATHS: string[] = [
export const APP_STAGING_ALLOWED_EXACT_PATHS: string[] = [
".env.example",
- "docs/openapi.yaml",
+ "docs/reference/openapi.yaml",
"open-sse/mcp-server/server.js",
"package.json",
"responses-ws-proxy.mjs",
diff --git a/scripts/check/check-docs-counts-sync.mjs b/scripts/check/check-docs-counts-sync.mjs
index 7f84a1a784..c3e6e95f63 100644
--- a/scripts/check/check-docs-counts-sync.mjs
+++ b/scripts/check/check-docs-counts-sync.mjs
@@ -59,31 +59,31 @@ const checks = [
label: "Executors count",
actual: countFiles("open-sse/executors"),
docKey: "executors",
- docs: ["ARCHITECTURE.md", "CODEBASE_DOCUMENTATION.md"],
+ docs: ["architecture/ARCHITECTURE.md", "architecture/CODEBASE_DOCUMENTATION.md"],
},
{
label: "Routing strategies count",
actual: countRoutingStrategies(),
docKey: "strategies",
- docs: ["AUTO-COMBO.md", "RESILIENCE_GUIDE.md"],
+ docs: ["routing/AUTO-COMBO.md", "architecture/RESILIENCE_GUIDE.md"],
},
{
label: "OAuth providers count",
actual: countFiles("src/lib/oauth/providers"),
docKey: "OAuth providers",
- docs: ["ARCHITECTURE.md"],
+ docs: ["architecture/ARCHITECTURE.md"],
},
{
label: "A2A skills count",
actual: countFiles("src/lib/a2a/skills"),
docKey: "A2A skills",
- docs: ["A2A-SERVER.md"],
+ docs: ["frameworks/A2A-SERVER.md"],
},
{
label: "Cloud agents count",
actual: countFiles("src/lib/cloudAgent/agents"),
docKey: "cloud agents",
- docs: ["CLOUD_AGENT.md", "AGENT_PROTOCOLS_GUIDE.md"],
+ docs: ["frameworks/CLOUD_AGENT.md", "frameworks/AGENT_PROTOCOLS_GUIDE.md"],
},
];
diff --git a/scripts/check/check-docs-sync.mjs b/scripts/check/check-docs-sync.mjs
index c8434fa185..05c1bbbb09 100644
--- a/scripts/check/check-docs-sync.mjs
+++ b/scripts/check/check-docs-sync.mjs
@@ -5,7 +5,7 @@ import path from "node:path";
const cwd = process.cwd();
const packageJsonPath = path.resolve(cwd, "package.json");
-const openApiPath = path.resolve(cwd, "docs/openapi.yaml");
+const openApiPath = path.resolve(cwd, "docs/reference/openapi.yaml");
const changelogPath = path.resolve(cwd, "CHANGELOG.md");
const llmPath = path.resolve(cwd, "llm.txt");
const i18nDocsPath = path.resolve(cwd, "docs/i18n");
@@ -209,7 +209,7 @@ try {
const openApiVersion = extractOpenApiVersion(readText(openApiPath));
if (!openApiVersion) {
- fail("could not extract docs/openapi.yaml info.version");
+ fail("could not extract docs/reference/openapi.yaml info.version");
} else if (openApiVersion !== packageVersion) {
fail(`OpenAPI version (${openApiVersion}) differs from package.json (${packageVersion})`);
} else {
diff --git a/scripts/check/check-env-doc-sync.mjs b/scripts/check/check-env-doc-sync.mjs
index f68fea2eb7..a69d0f94ef 100644
--- a/scripts/check/check-env-doc-sync.mjs
+++ b/scripts/check/check-env-doc-sync.mjs
@@ -3,7 +3,7 @@
* Strict environment variable contract checker.
*
* Enforces that every env var referenced in OmniRoute source code appears in
- * both `.env.example` and `docs/ENVIRONMENT.md`, and that the two files agree
+ * both `.env.example` and `docs/reference/ENVIRONMENT.md`, and that the two files agree
* on the documented var set. Falls back to a small allowlist for variables
* that are intentionally documented but not literally referenced (legacy
* aliases, future-supported hooks) or vice versa.
@@ -199,7 +199,7 @@ export function runEnvDocSync(options = {}) {
options.envDocText ??
(options.envDocPath
? fs.readFileSync(options.envDocPath, "utf8")
- : fs.readFileSync(path.join(REPO_ROOT, "docs", "ENVIRONMENT.md"), "utf8"));
+ : fs.readFileSync(path.join(REPO_ROOT, "docs", "reference", "ENVIRONMENT.md"), "utf8"));
const envVars = parseEnvExampleVars(envExampleText);
const docVars = parseEnvDocVars(envDocText);
@@ -250,7 +250,7 @@ function main() {
console.log("============================");
console.log(`Code references: ${result.summary.code} unique vars`);
console.log(`In .env.example: ${result.summary.envExample} unique vars`);
- console.log(`In docs/ENVIRONMENT.md: ${result.summary.doc} unique vars`);
+ console.log(`In docs/reference/ENVIRONMENT.md: ${result.summary.doc} unique vars`);
console.log();
printList("In code but missing from .env.example", result.problems.codeMissingEnv);
@@ -267,7 +267,9 @@ function main() {
process.exit(0);
}
- console.log("\n✗ Env / docs contract is out of sync. Update .env.example, docs/ENVIRONMENT.md,");
+ console.log(
+ "\n✗ Env / docs contract is out of sync. Update .env.example, docs/reference/ENVIRONMENT.md,"
+ );
console.log(" or the allowlists in scripts/check/check-env-doc-sync.mjs and try again.");
process.exit(1);
}
diff --git a/scripts/docs/fix-internal-links.mjs b/scripts/docs/fix-internal-links.mjs
new file mode 100644
index 0000000000..abe933f94b
--- /dev/null
+++ b/scripts/docs/fix-internal-links.mjs
@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+// One-shot: FASE 3 helper, safe to delete after merge.
+//
+// Rewrites doc-file references after the docs/ flat -> subfolder restructure.
+//
+// Modes:
+// --internal Rewrite relative links inside docs//*.md to point at
+// the new subfolder paths (e.g. ./AUTO-COMBO.md -> ../routing/AUTO-COMBO.md).
+// --external Rewrite absolute-style `docs/.md` references in files
+// outside docs/ (README, CLAUDE.md, .agents, .claude, scripts, src,
+// tests, etc.) to `docs//.md`.
+//
+// Usage:
+// node scripts/docs/fix-internal-links.mjs --internal
+// node scripts/docs/fix-internal-links.mjs --external
+// node scripts/docs/fix-internal-links.mjs --internal --external --dry
+//
+// Notes:
+// - Idempotent: rerunning does not double-rewrite (it only matches the old shape).
+// - openapi.yaml lives under docs/reference/ — also handled.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..", "..");
+const DOCS = path.join(ROOT, "docs");
+
+const args = new Set(process.argv.slice(2));
+const RUN_INTERNAL = args.has("--internal");
+const RUN_EXTERNAL = args.has("--external");
+const DRY = args.has("--dry");
+if (!RUN_INTERNAL && !RUN_EXTERNAL) {
+ console.error("Pass --internal and/or --external (and optionally --dry).");
+ process.exit(2);
+}
+
+// ----------------------------------------------------------------------
+// Mapping: stem -> subfolder
+// ----------------------------------------------------------------------
+const DOC_TO_SUBFOLDER = {
+ // architecture
+ "ARCHITECTURE.md": "architecture",
+ "CODEBASE_DOCUMENTATION.md": "architecture",
+ "REPOSITORY_MAP.md": "architecture",
+ "AUTHZ_GUIDE.md": "architecture",
+ "RESILIENCE_GUIDE.md": "architecture",
+ // guides
+ "SETUP_GUIDE.md": "guides",
+ "USER_GUIDE.md": "guides",
+ "DOCKER_GUIDE.md": "guides",
+ "ELECTRON_GUIDE.md": "guides",
+ "TERMUX_GUIDE.md": "guides",
+ "PWA_GUIDE.md": "guides",
+ "TROUBLESHOOTING.md": "guides",
+ "UNINSTALL.md": "guides",
+ "I18N.md": "guides",
+ "FEATURES.md": "guides",
+ // reference
+ "API_REFERENCE.md": "reference",
+ "PROVIDER_REFERENCE.md": "reference",
+ "openapi.yaml": "reference",
+ "ENVIRONMENT.md": "reference",
+ "CLI-TOOLS.md": "reference",
+ "FREE_TIERS.md": "reference",
+ // frameworks
+ "MCP-SERVER.md": "frameworks",
+ "A2A-SERVER.md": "frameworks",
+ "AGENT_PROTOCOLS_GUIDE.md": "frameworks",
+ "CLOUD_AGENT.md": "frameworks",
+ "SKILLS.md": "frameworks",
+ "MEMORY.md": "frameworks",
+ "WEBHOOKS.md": "frameworks",
+ "EVALS.md": "frameworks",
+ // routing
+ "AUTO-COMBO.md": "routing",
+ "REASONING_REPLAY.md": "routing",
+ // security
+ "GUARDRAILS.md": "security",
+ "COMPLIANCE.md": "security",
+ "STEALTH_GUIDE.md": "security",
+ // compression
+ "COMPRESSION_GUIDE.md": "compression",
+ "COMPRESSION_ENGINES.md": "compression",
+ "COMPRESSION_RULES_FORMAT.md": "compression",
+ "COMPRESSION_LANGUAGE_PACKS.md": "compression",
+ "RTK_COMPRESSION.md": "compression",
+ // ops
+ "RELEASE_CHECKLIST.md": "ops",
+ "COVERAGE_PLAN.md": "ops",
+ "FLY_IO_DEPLOYMENT_GUIDE.md": "ops",
+ "VM_DEPLOYMENT_GUIDE.md": "ops",
+ "PROXY_GUIDE.md": "ops",
+ "TUNNELS_GUIDE.md": "ops",
+};
+
+// Build alternation regex (longest-first) of file basenames we know about.
+const FILES_ALT = Object.keys(DOC_TO_SUBFOLDER)
+ .sort((a, b) => b.length - a.length)
+ .map((s) => s.replace(/\./g, "\\."))
+ .join("|");
+
+// ----------------------------------------------------------------------
+// Internal rewriter (within docs/**)
+// ----------------------------------------------------------------------
+
+function listDocFiles() {
+ const out = [];
+ // walk subfolders we created
+ for (const sub of new Set(Object.values(DOC_TO_SUBFOLDER))) {
+ const dir = path.join(DOCS, sub);
+ if (!fs.existsSync(dir)) continue;
+ for (const f of fs.readdirSync(dir)) {
+ if (!f.endsWith(".md") && !f.endsWith(".yaml")) continue;
+ out.push(path.join(dir, f));
+ }
+ }
+ // also rewrite the new README and diagrams README
+ out.push(path.join(DOCS, "README.md"));
+ return out;
+}
+
+function relativeFromTo(fromAbsFile, targetSub, targetBasename) {
+ const fromDir = path.dirname(fromAbsFile);
+ const toAbs = path.join(DOCS, targetSub, targetBasename);
+ let rel = path.relative(fromDir, toAbs);
+ // posix-style
+ rel = rel.split(path.sep).join("/");
+ if (!rel.startsWith(".")) rel = "./" + rel;
+ return rel;
+}
+
+function rewriteInternal(filePath) {
+ const src = fs.readFileSync(filePath, "utf8");
+ let out = src;
+
+ // Pattern A: relative refs like ./FOO.md, ../FOO.md, or bare FOO.md inside (... ).
+ // We match `]( )` and `]( )`.
+ // Captures: prefix (=./ or ../ chains, may be empty), basename.
+ const reA = new RegExp(`\\]\\(\\s*((?:\\.{1,2}/)*)(${FILES_ALT})((?:#[^\\s)]+)?)\\s*\\)`, "g");
+ out = out.replace(reA, (full, prefix, basename, anchor) => {
+ const subFolder = DOC_TO_SUBFOLDER[basename];
+ if (!subFolder) return full;
+ const newRel = relativeFromTo(filePath, subFolder, basename);
+ return `](${newRel}${anchor || ""})`;
+ });
+
+ // Pattern B: absolute-style `docs/FOO.md` inside markdown links — convert
+ // to `docs//FOO.md`. We avoid double-rewriting if a subfolder is
+ // already present.
+ const reB = new RegExp(`docs/(${FILES_ALT})((?:#[^\\s)\"']+)?)`, "g");
+ out = out.replace(reB, (full, basename, anchor) => {
+ const subFolder = DOC_TO_SUBFOLDER[basename];
+ if (!subFolder) return full;
+ // If preceded by `/` already, skip — but the regex won't capture that
+ // because it only matches `docs/`. So this is safe.
+ return `docs/${subFolder}/${basename}${anchor || ""}`;
+ });
+
+ if (out !== src) {
+ if (!DRY) fs.writeFileSync(filePath, out, "utf8");
+ return true;
+ }
+ return false;
+}
+
+// ----------------------------------------------------------------------
+// External rewriter (files outside docs/)
+// ----------------------------------------------------------------------
+
+function listExternalFiles() {
+ // We rewrite a curated set of paths to avoid wandering into vendor / build dirs.
+ const candidates = [];
+
+ // 1) Root-level documentation files
+ for (const f of fs.readdirSync(ROOT)) {
+ const full = path.join(ROOT, f);
+ if (!fs.statSync(full).isFile()) continue;
+ if (/\.(md|txt)$/i.test(f)) candidates.push(full);
+ }
+
+ // 2) Specific directories we know contain doc references
+ const dirs = [
+ ".agents",
+ ".claude",
+ ".github",
+ "bin",
+ "electron",
+ "open-sse",
+ "scripts",
+ "src",
+ "tests",
+ "vscode-extension",
+ // i18n mirrors — root-level locale files (llm.txt, CHANGELOG.md, etc.) reference
+ // the root /docs/ paths and must stay in sync after restructure.
+ "docs/i18n",
+ ];
+ for (const d of dirs) {
+ const full = path.join(ROOT, d);
+ if (!fs.existsSync(full)) continue;
+ walk(full, candidates);
+ }
+ return candidates;
+}
+
+function walk(dir, out) {
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+ if (entry.name === "node_modules" || entry.name === ".next") continue;
+ if (entry.name.startsWith(".git")) continue;
+ const full = path.join(dir, entry.name);
+ if (entry.isDirectory()) {
+ walk(full, out);
+ } else if (entry.isFile()) {
+ // accept text-y file types
+ if (/\.(md|txt|ts|tsx|mjs|cjs|js|json|yaml|yml|sh)$/i.test(entry.name)) {
+ out.push(full);
+ }
+ }
+ }
+}
+
+function rewriteExternal(filePath) {
+ const src = fs.readFileSync(filePath, "utf8");
+ let out = src;
+
+ // Rewrite any `docs/FOO.md` (only the bare-basename form, not already
+ // pointing into a subfolder) to `docs//FOO.md`.
+ // Word-boundary lookbehind/lookahead-ish: use (? {
+ const subFolder = DOC_TO_SUBFOLDER[basename];
+ if (!subFolder) return full;
+ return `docs/${subFolder}/${basename}${anchor || ""}`;
+ });
+
+ if (out !== src) {
+ if (!DRY) fs.writeFileSync(filePath, out, "utf8");
+ return true;
+ }
+ return false;
+}
+
+// ----------------------------------------------------------------------
+// Run
+// ----------------------------------------------------------------------
+
+let internalChanged = 0;
+let externalChanged = 0;
+let internalScanned = 0;
+let externalScanned = 0;
+
+if (RUN_INTERNAL) {
+ const files = listDocFiles();
+ for (const f of files) {
+ internalScanned++;
+ if (rewriteInternal(f)) internalChanged++;
+ }
+ console.log(
+ `[internal] scanned=${internalScanned} changed=${internalChanged}${DRY ? " (dry-run)" : ""}`
+ );
+}
+
+if (RUN_EXTERNAL) {
+ const files = listExternalFiles();
+ for (const f of files) {
+ externalScanned++;
+ if (rewriteExternal(f)) externalChanged++;
+ }
+ console.log(
+ `[external] scanned=${externalScanned} changed=${externalChanged}${DRY ? " (dry-run)" : ""}`
+ );
+}
diff --git a/scripts/docs/gen-provider-reference.ts b/scripts/docs/gen-provider-reference.ts
index 823d9f19d5..39bdc09558 100644
--- a/scripts/docs/gen-provider-reference.ts
+++ b/scripts/docs/gen-provider-reference.ts
@@ -1,5 +1,5 @@
#!/usr/bin/env node
-// Generates docs/PROVIDER_REFERENCE.md from src/shared/constants/providers.ts.
+// Generates docs/reference/PROVIDER_REFERENCE.md from src/shared/constants/providers.ts.
// Run: node --import tsx/esm scripts/docs/gen-provider-reference.ts
import fs from "node:fs";
@@ -26,7 +26,7 @@ import {
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const ROOT = path.resolve(__dirname, "..", "..");
-const OUT_FILE = path.join(ROOT, "docs", "PROVIDER_REFERENCE.md");
+const OUT_FILE = path.join(ROOT, "docs", "reference", "PROVIDER_REFERENCE.md");
type ProviderRecord = {
id: string;
diff --git a/scripts/docs/generate-docs-index.mjs b/scripts/docs/generate-docs-index.mjs
index 85015cea42..24a83c1ef9 100644
--- a/scripts/docs/generate-docs-index.mjs
+++ b/scripts/docs/generate-docs-index.mjs
@@ -1,12 +1,15 @@
#!/usr/bin/env node
/**
- * Build-time script: scans docs/*.md and generates
+ * Build-time script: scans docs//*.md and generates
* src/app/docs/lib/docs-auto-generated.ts with static navigation + search data.
*
* This file is imported by both client and server components — NO fs/path imports.
* Run via: node scripts/docs/generate-docs-index.mjs
* Automatically runs as prebuild step.
+ *
+ * Sections come from the on-disk subfolder layout introduced in FASE 3 of the
+ * platform overhaul. Order is fixed by SECTION_ORDER below.
*/
import fs from "node:fs";
@@ -19,64 +22,19 @@ const ROOT = path.resolve(__dirname, "..", "..");
const DOCS_DIR = path.join(ROOT, "docs");
const OUT_FILE = path.join(ROOT, "src", "app", "docs", "lib", "docs-auto-generated.ts");
-const SECTION_CATEGORIES = {
- "Getting Started": [
- "SETUP_GUIDE",
- "USER_GUIDE",
- "CLI_TOOLS",
- "ARCHITECTURE",
- "QUICK_START",
- "GETTING_STARTED",
- ],
- Features: [
- "FEATURES",
- "AUTO_COMBO",
- "COMPRESSION_GUIDE",
- "RTK_COMPRESSION",
- "COMPRESSION_ENGINES",
- "COMPRESSION_RULES_FORMAT",
- "COMPRESSION_LANGUAGE_PACKS",
- "FREE_TIERS",
- ],
- "API & Protocols": ["API_REFERENCE", "MCP_SERVER", "A2A_SERVER"],
- Deployment: [
- "DOCKER_GUIDE",
- "VM_DEPLOYMENT_GUIDE",
- "FLY_IO_DEPLOYMENT_GUIDE",
- "TERMUX_GUIDE",
- "PWA_GUIDE",
- ],
- Operations: ["PROXY_GUIDE", "RESILIENCE_GUIDE", "ENVIRONMENT", "TROUBLESHOOTING"],
- Development: [
- "CODEBASE_DOCUMENTATION",
- "COVERAGE_PLAN",
- "I18N",
- "RELEASE_CHECKLIST",
- "UNINSTALL",
- "CONTRIBUTING",
- "CHANGELOG",
- "CODE_OF_CONDUCT",
- ],
-};
+// Subfolder -> nav section title, in the order they should appear in the sidebar.
+const SECTION_ORDER = [
+ { dir: "architecture", title: "Architecture" },
+ { dir: "guides", title: "Guides" },
+ { dir: "reference", title: "Reference" },
+ { dir: "frameworks", title: "Frameworks" },
+ { dir: "routing", title: "Routing" },
+ { dir: "security", title: "Security" },
+ { dir: "compression", title: "Compression" },
+ { dir: "ops", title: "Ops" },
+];
-const SECTION_ORDER = {
- "Getting Started": 1,
- Features: 2,
- "API & Protocols": 3,
- Deployment: 4,
- Operations: 5,
- Development: 6,
-};
-
-function categorizeFile(fileName) {
- const stem = fileName.replace(/\.md$/i, "").toUpperCase().replace(/-/g, "_");
- for (const [section, patterns] of Object.entries(SECTION_CATEGORIES)) {
- if (patterns.some((p) => stem === p)) {
- return section;
- }
- }
- return "Other";
-}
+const SECTION_INDEX = Object.fromEntries(SECTION_ORDER.map((s, i) => [s.title, i + 1]));
function extractTitleFromContent(content) {
const match = content.match(/^#\s+(.+)$/m);
@@ -114,16 +72,7 @@ function extractContentPreview(content) {
return stripped.slice(0, 300);
}
-// ---------- Main ----------
-
-if (!fs.existsSync(DOCS_DIR)) {
- if (fs.existsSync(OUT_FILE)) {
- console.warn(
- `[generate-docs-index] ${DOCS_DIR} not found; keeping existing generated docs index.`
- );
- process.exit(0);
- }
-
+function emitEmpty(reason) {
fs.mkdirSync(path.dirname(OUT_FILE), { recursive: true });
fs.writeFileSync(
OUT_FILE,
@@ -158,51 +107,88 @@ export const autoAllSlugs: string[] = [];
`,
"utf8"
);
- console.warn(`[generate-docs-index] ${DOCS_DIR} not found; generated empty docs index.`);
+ console.warn(`[generate-docs-index] ${reason}; generated empty docs index.`);
+}
+
+// ---------- Main ----------
+
+if (!fs.existsSync(DOCS_DIR)) {
+ if (fs.existsSync(OUT_FILE)) {
+ console.warn(
+ `[generate-docs-index] ${DOCS_DIR} not found; keeping existing generated docs index.`
+ );
+ process.exit(0);
+ }
+ emitEmpty(`${DOCS_DIR} not found`);
process.exit(0);
}
-const files = fs.readdirSync(DOCS_DIR).filter((f) => f.endsWith(".md") || f.endsWith(".mdx"));
-
const docs = [];
-for (const fileName of files) {
- const filePath = path.join(DOCS_DIR, fileName);
- const fileContent = fs.readFileSync(filePath, "utf8");
- const { data: frontmatter, content } = matter(fileContent);
- const slug =
- frontmatter.slug ||
- fileName
- .replace(/\.mdx?$/i, "")
- .toLowerCase()
- .replace(/_/g, "-");
- const title = frontmatter.title || extractTitleFromContent(content) || slug.replace(/-/g, " ");
- const section = frontmatter.section || categorizeFile(fileName);
- const order = frontmatter.order ?? 999;
- const headings = extractHeadings(content);
- const contentPreview = frontmatter.description || extractContentPreview(content);
+for (const { dir, title } of SECTION_ORDER) {
+ const fullDir = path.join(DOCS_DIR, dir);
+ if (!fs.existsSync(fullDir)) continue;
+ const entries = fs.readdirSync(fullDir, { withFileTypes: true });
+ for (const entry of entries) {
+ if (!entry.isFile()) continue;
+ if (!entry.name.endsWith(".md") && !entry.name.endsWith(".mdx")) continue;
+ if (entry.name === "README.md") continue; // section index, not a doc page
- docs.push({ slug, title, fileName, section, order, content: contentPreview, headings });
+ const absPath = path.join(fullDir, entry.name);
+ const fileContent = fs.readFileSync(absPath, "utf8");
+ const { data: frontmatter, content } = matter(fileContent);
+
+ const slug =
+ frontmatter.slug ||
+ entry.name
+ .replace(/\.mdx?$/i, "")
+ .toLowerCase()
+ .replace(/_/g, "-");
+
+ // fileName is relative to docs/ — used by the slug page to read content.
+ const fileName = path.posix.join(dir, entry.name);
+
+ const titleStr =
+ frontmatter.title || extractTitleFromContent(content) || slug.replace(/-/g, " ");
+ const section = frontmatter.section || title;
+ const order = frontmatter.order ?? 999;
+ const headings = extractHeadings(content);
+ const contentPreview = frontmatter.description || extractContentPreview(content);
+
+ docs.push({
+ slug,
+ title: titleStr,
+ fileName,
+ section,
+ order,
+ content: contentPreview,
+ headings,
+ });
+ }
+}
+
+if (docs.length === 0) {
+ emitEmpty("no docs discovered in subfolders");
+ process.exit(0);
}
docs.sort((a, b) => {
- const sectionA = SECTION_ORDER[a.section] ?? 99;
- const sectionB = SECTION_ORDER[b.section] ?? 99;
+ const sectionA = SECTION_INDEX[a.section] ?? 99;
+ const sectionB = SECTION_INDEX[b.section] ?? 99;
if (sectionA !== sectionB) return sectionA - sectionB;
return a.order - b.order;
});
-// Build navigation sections
+// Build navigation sections in the configured order.
const sectionMap = new Map();
for (const doc of docs) {
const items = sectionMap.get(doc.section) || [];
items.push(doc);
sectionMap.set(doc.section, items);
}
-const orderedSections = [...new Set([...Object.keys(SECTION_ORDER), ...sectionMap.keys()])];
-const navSections = orderedSections
- .filter((s) => sectionMap.has(s))
- .sort((a, b) => (SECTION_ORDER[a] ?? 99) - (SECTION_ORDER[b] ?? 99))
+
+const navSections = SECTION_ORDER.map(({ title }) => title)
+ .filter((t) => sectionMap.has(t))
.map((title) => ({
title,
items: sectionMap.get(title).map((doc) => ({
@@ -228,8 +214,8 @@ if (searchIndex.some((item) => item.slug === "api-reference")) {
searchIndex.push({
slug: "api-explorer",
title: "API Explorer",
- fileName: "API_REFERENCE.md",
- section: "API & Protocols",
+ fileName: "reference/API_REFERENCE.md",
+ section: "Reference",
content: "interactive try it live api explorer endpoint test request response curl example",
headings: ["Try It", "Endpoints"],
});
diff --git a/scripts/docs/move-i18n-mirrors.mjs b/scripts/docs/move-i18n-mirrors.mjs
new file mode 100644
index 0000000000..110f3dfda2
--- /dev/null
+++ b/scripts/docs/move-i18n-mirrors.mjs
@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// One-shot: FASE 3 helper, safe to delete after merge.
+//
+// Moves existing i18n mirror docs from `docs/i18n//docs/X.md` into the
+// matching subfolder `docs/i18n//docs//X.md`, mirroring the new
+// docs/ layout. Uses `git mv` to preserve history.
+//
+// Usage:
+// node scripts/docs/move-i18n-mirrors.mjs [--dry]
+//
+// Notes:
+// - Skips files that don't appear in DOC_TO_SUBFOLDER (e.g., the legacy
+// `cloudflare-zero-trust-guide.md` or `features/` subfolder — those will be
+// handled in FASE 5 when translations are regenerated).
+// - Idempotent: if the target already lives under a subfolder, the entry is
+// skipped.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..", "..");
+const I18N_DIR = path.join(ROOT, "docs", "i18n");
+
+const DRY = process.argv.includes("--dry");
+
+const DOC_TO_SUBFOLDER = {
+ // architecture
+ "ARCHITECTURE.md": "architecture",
+ "CODEBASE_DOCUMENTATION.md": "architecture",
+ "REPOSITORY_MAP.md": "architecture",
+ "AUTHZ_GUIDE.md": "architecture",
+ "RESILIENCE_GUIDE.md": "architecture",
+ // guides
+ "SETUP_GUIDE.md": "guides",
+ "USER_GUIDE.md": "guides",
+ "DOCKER_GUIDE.md": "guides",
+ "ELECTRON_GUIDE.md": "guides",
+ "TERMUX_GUIDE.md": "guides",
+ "PWA_GUIDE.md": "guides",
+ "TROUBLESHOOTING.md": "guides",
+ "UNINSTALL.md": "guides",
+ "I18N.md": "guides",
+ "FEATURES.md": "guides",
+ // reference
+ "API_REFERENCE.md": "reference",
+ "PROVIDER_REFERENCE.md": "reference",
+ "openapi.yaml": "reference",
+ "ENVIRONMENT.md": "reference",
+ "CLI-TOOLS.md": "reference",
+ "FREE_TIERS.md": "reference",
+ // frameworks
+ "MCP-SERVER.md": "frameworks",
+ "A2A-SERVER.md": "frameworks",
+ "AGENT_PROTOCOLS_GUIDE.md": "frameworks",
+ "CLOUD_AGENT.md": "frameworks",
+ "SKILLS.md": "frameworks",
+ "MEMORY.md": "frameworks",
+ "WEBHOOKS.md": "frameworks",
+ "EVALS.md": "frameworks",
+ // routing
+ "AUTO-COMBO.md": "routing",
+ "REASONING_REPLAY.md": "routing",
+ // security
+ "GUARDRAILS.md": "security",
+ "COMPLIANCE.md": "security",
+ "STEALTH_GUIDE.md": "security",
+ // compression
+ "COMPRESSION_GUIDE.md": "compression",
+ "COMPRESSION_ENGINES.md": "compression",
+ "COMPRESSION_RULES_FORMAT.md": "compression",
+ "COMPRESSION_LANGUAGE_PACKS.md": "compression",
+ "RTK_COMPRESSION.md": "compression",
+ // ops
+ "RELEASE_CHECKLIST.md": "ops",
+ "COVERAGE_PLAN.md": "ops",
+ "FLY_IO_DEPLOYMENT_GUIDE.md": "ops",
+ "VM_DEPLOYMENT_GUIDE.md": "ops",
+ "PROXY_GUIDE.md": "ops",
+ "TUNNELS_GUIDE.md": "ops",
+};
+
+let moved = 0;
+let skipped = 0;
+const seenLocales = [];
+
+for (const locale of fs.readdirSync(I18N_DIR)) {
+ const localeDir = path.join(I18N_DIR, locale);
+ const stat = fs.statSync(localeDir);
+ if (!stat.isDirectory()) continue;
+ const docsDir = path.join(localeDir, "docs");
+ if (!fs.existsSync(docsDir)) continue;
+ seenLocales.push(locale);
+
+ for (const fname of fs.readdirSync(docsDir)) {
+ const sub = DOC_TO_SUBFOLDER[fname];
+ if (!sub) continue; // not in our mapping (e.g. features/, cloudflare-zero-trust-guide.md)
+
+ const src = path.join(docsDir, fname);
+ if (!fs.statSync(src).isFile()) continue;
+
+ const subDir = path.join(docsDir, sub);
+ const dst = path.join(subDir, fname);
+
+ if (fs.existsSync(dst)) {
+ skipped++;
+ continue;
+ }
+
+ if (DRY) {
+ console.log(`would move: ${path.relative(ROOT, src)} -> ${path.relative(ROOT, dst)}`);
+ moved++;
+ continue;
+ }
+
+ if (!fs.existsSync(subDir)) fs.mkdirSync(subDir, { recursive: true });
+ try {
+ execSync(`git mv -k -- "${path.relative(ROOT, src)}" "${path.relative(ROOT, dst)}"`, {
+ cwd: ROOT,
+ stdio: "pipe",
+ });
+ moved++;
+ } catch (e) {
+ // fallback: copy + delete
+ fs.renameSync(src, dst);
+ execSync(
+ `git rm --cached -- "${path.relative(ROOT, src)}" 2>/dev/null || true; git add -- "${path.relative(ROOT, dst)}"`,
+ { cwd: ROOT, stdio: "pipe", shell: "/bin/bash" }
+ );
+ moved++;
+ }
+ }
+}
+
+console.log(
+ `[i18n-mirrors] locales=${seenLocales.length} moved=${moved} skipped=${skipped}${DRY ? " (dry-run)" : ""}`
+);
diff --git a/src/app/api/openapi/spec/route.ts b/src/app/api/openapi/spec/route.ts
index c4798b3a92..31ef74abb9 100644
--- a/src/app/api/openapi/spec/route.ts
+++ b/src/app/api/openapi/spec/route.ts
@@ -10,6 +10,9 @@ import yaml from "js-yaml";
let cachedSpec: { data: any; mtime: number } | null = null;
const OPENAPI_SPEC_CANDIDATES = [
+ path.join(/* turbopackIgnore: true */ process.cwd(), "docs", "reference", "openapi.yaml"),
+ path.join(/* turbopackIgnore: true */ process.cwd(), "app", "docs", "reference", "openapi.yaml"),
+ // Legacy locations kept as fallback for old standalone bundles.
path.join(/* turbopackIgnore: true */ process.cwd(), "docs", "openapi.yaml"),
path.join(/* turbopackIgnore: true */ process.cwd(), "app", "docs", "openapi.yaml"),
];
diff --git a/src/app/docs/lib/docs-auto-generated.ts b/src/app/docs/lib/docs-auto-generated.ts
index 380e932c3b..274c67f6f0 100644
--- a/src/app/docs/lib/docs-auto-generated.ts
+++ b/src/app/docs/lib/docs-auto-generated.ts
@@ -23,187 +23,262 @@ export interface AutoGenSearchItem {
export const autoNavSections: AutoGenNavSection[] = [
{
- title: "Getting Started",
+ title: "Architecture",
items: [
{
slug: "architecture",
title: "OmniRoute Architecture",
- fileName: "ARCHITECTURE.md",
+ fileName: "architecture/ARCHITECTURE.md",
},
{
- slug: "cli-tools",
- title: "CLI Tools Setup Guide",
- fileName: "CLI-TOOLS.md",
+ slug: "authz-guide",
+ title: "Authorization Guide",
+ fileName: "architecture/AUTHZ_GUIDE.md",
},
{
- slug: "setup-guide",
- title: "Setup Guide",
- fileName: "SETUP_GUIDE.md",
+ slug: "codebase-documentation",
+ title: "OmniRoute Codebase Documentation",
+ fileName: "architecture/CODEBASE_DOCUMENTATION.md",
},
{
- slug: "user-guide",
- title: "User Guide",
- fileName: "USER_GUIDE.md",
+ slug: "repository-map",
+ title: "Repository Map",
+ fileName: "architecture/REPOSITORY_MAP.md",
+ },
+ {
+ slug: "resilience-guide",
+ title: "Resilience Guide",
+ fileName: "architecture/RESILIENCE_GUIDE.md",
},
],
},
{
- title: "Features",
- items: [
- {
- slug: "auto-combo",
- title: "OmniRoute Auto-Combo Engine",
- fileName: "AUTO-COMBO.md",
- },
- {
- slug: "compression-engines",
- title: "Compression Engines",
- fileName: "COMPRESSION_ENGINES.md",
- },
- {
- slug: "compression-guide",
- title: "🗜️ Prompt Compression Guide",
- fileName: "COMPRESSION_GUIDE.md",
- },
- {
- slug: "compression-language-packs",
- title: "Compression Language Packs",
- fileName: "COMPRESSION_LANGUAGE_PACKS.md",
- },
- {
- slug: "compression-rules-format",
- title: "Compression Rules Format",
- fileName: "COMPRESSION_RULES_FORMAT.md",
- },
- {
- slug: "features",
- title: "OmniRoute — Dashboard Features Gallery",
- fileName: "FEATURES.md",
- },
- {
- slug: "free-tiers",
- title: "🆓 Free LLM API Providers — Consolidated Directory",
- fileName: "FREE_TIERS.md",
- },
- {
- slug: "rtk-compression",
- title: "RTK Compression",
- fileName: "RTK_COMPRESSION.md",
- },
- ],
- },
- {
- title: "API & Protocols",
- items: [
- {
- slug: "a2a-server",
- title: "OmniRoute A2A Server Documentation",
- fileName: "A2A-SERVER.md",
- },
- {
- slug: "api-reference",
- title: "API Reference",
- fileName: "API_REFERENCE.md",
- },
- {
- slug: "mcp-server",
- title: "OmniRoute MCP Server Documentation",
- fileName: "MCP-SERVER.md",
- },
- ],
- },
- {
- title: "Deployment",
+ title: "Guides",
items: [
{
slug: "docker-guide",
title: "🐳 Docker Guide",
- fileName: "DOCKER_GUIDE.md",
+ fileName: "guides/DOCKER_GUIDE.md",
},
{
- slug: "fly-io-deployment-guide",
- title: "OmniRoute Fly.io 部署指南",
- fileName: "FLY_IO_DEPLOYMENT_GUIDE.md",
+ slug: "electron-guide",
+ title: "Electron Desktop Guide",
+ fileName: "guides/ELECTRON_GUIDE.md",
},
{
- slug: "pwa-guide",
- title: "Progressive Web App (PWA) Guide",
- fileName: "PWA_GUIDE.md",
- },
- {
- slug: "termux-guide",
- title: "Termux Headless Setup",
- fileName: "TERMUX_GUIDE.md",
- },
- {
- slug: "vm-deployment-guide",
- title: "OmniRoute — Deployment Guide on VM with Cloudflare",
- fileName: "VM_DEPLOYMENT_GUIDE.md",
- },
- ],
- },
- {
- title: "Operations",
- items: [
- {
- slug: "environment",
- title: "Environment Variables Reference",
- fileName: "ENVIRONMENT.md",
- },
- {
- slug: "proxy-guide",
- title: "OmniRoute Proxy Guide",
- fileName: "PROXY_GUIDE.md",
- },
- {
- slug: "resilience-guide",
- title: "🛡️ Resilience Guide",
- fileName: "RESILIENCE_GUIDE.md",
- },
- {
- slug: "troubleshooting",
- title: "Troubleshooting",
- fileName: "TROUBLESHOOTING.md",
- },
- ],
- },
- {
- title: "Development",
- items: [
- {
- slug: "codebase-documentation",
- title: "omniroute — Codebase Documentation",
- fileName: "CODEBASE_DOCUMENTATION.md",
- },
- {
- slug: "coverage-plan",
- title: "Test Coverage Plan",
- fileName: "COVERAGE_PLAN.md",
+ slug: "features",
+ title: "OmniRoute — Dashboard Features Gallery",
+ fileName: "guides/FEATURES.md",
},
{
slug: "i18n",
title: "i18n — Internationalization Guide",
- fileName: "I18N.md",
+ fileName: "guides/I18N.md",
},
{
- slug: "release-checklist",
- title: "Release Checklist",
- fileName: "RELEASE_CHECKLIST.md",
+ slug: "pwa-guide",
+ title: "Progressive Web App (PWA) Guide",
+ fileName: "guides/PWA_GUIDE.md",
+ },
+ {
+ slug: "setup-guide",
+ title: "Setup Guide",
+ fileName: "guides/SETUP_GUIDE.md",
+ },
+ {
+ slug: "termux-guide",
+ title: "Termux Headless Setup",
+ fileName: "guides/TERMUX_GUIDE.md",
+ },
+ {
+ slug: "troubleshooting",
+ title: "Troubleshooting",
+ fileName: "guides/TROUBLESHOOTING.md",
},
{
slug: "uninstall",
title: "OmniRoute — Uninstall Guide",
- fileName: "UNINSTALL.md",
+ fileName: "guides/UNINSTALL.md",
+ },
+ {
+ slug: "user-guide",
+ title: "User Guide",
+ fileName: "guides/USER_GUIDE.md",
},
],
},
{
- title: "Other",
+ title: "Reference",
items: [
{
- slug: "rfc-auto-assessment",
- title: "RFC: Auto-Assessment & Self-Healing Combo Engine",
- fileName: "RFC-AUTO-ASSESSMENT.md",
+ slug: "api-reference",
+ title: "API Reference",
+ fileName: "reference/API_REFERENCE.md",
+ },
+ {
+ slug: "cli-tools",
+ title: "CLI Tools — OmniRoute v3.8.0",
+ fileName: "reference/CLI-TOOLS.md",
+ },
+ {
+ slug: "environment",
+ title: "Environment Variables Reference",
+ fileName: "reference/ENVIRONMENT.md",
+ },
+ {
+ slug: "free-tiers",
+ title: "Free Tiers",
+ fileName: "reference/FREE_TIERS.md",
+ },
+ {
+ slug: "provider-reference",
+ title: "Provider Reference",
+ fileName: "reference/PROVIDER_REFERENCE.md",
+ },
+ ],
+ },
+ {
+ title: "Frameworks",
+ items: [
+ {
+ slug: "a2a-server",
+ title: "OmniRoute A2A Server Documentation",
+ fileName: "frameworks/A2A-SERVER.md",
+ },
+ {
+ slug: "agent-protocols-guide",
+ title: "Agent Protocols Guide",
+ fileName: "frameworks/AGENT_PROTOCOLS_GUIDE.md",
+ },
+ {
+ slug: "cloud-agent",
+ title: "Cloud Agents",
+ fileName: "frameworks/CLOUD_AGENT.md",
+ },
+ {
+ slug: "evals",
+ title: "Evaluations (Evals)",
+ fileName: "frameworks/EVALS.md",
+ },
+ {
+ slug: "mcp-server",
+ title: "OmniRoute MCP Server Documentation",
+ fileName: "frameworks/MCP-SERVER.md",
+ },
+ {
+ slug: "memory",
+ title: "Memory System",
+ fileName: "frameworks/MEMORY.md",
+ },
+ {
+ slug: "skills",
+ title: "Skills Framework",
+ fileName: "frameworks/SKILLS.md",
+ },
+ {
+ slug: "webhooks",
+ title: "Webhooks",
+ fileName: "frameworks/WEBHOOKS.md",
+ },
+ ],
+ },
+ {
+ title: "Routing",
+ items: [
+ {
+ slug: "auto-combo",
+ title: "OmniRoute Auto-Combo Engine",
+ fileName: "routing/AUTO-COMBO.md",
+ },
+ {
+ slug: "reasoning-replay",
+ title: "Reasoning Replay Cache",
+ fileName: "routing/REASONING_REPLAY.md",
+ },
+ ],
+ },
+ {
+ title: "Security",
+ items: [
+ {
+ slug: "compliance",
+ title: "Compliance & Audit",
+ fileName: "security/COMPLIANCE.md",
+ },
+ {
+ slug: "guardrails",
+ title: "Guardrails",
+ fileName: "security/GUARDRAILS.md",
+ },
+ {
+ slug: "stealth-guide",
+ title: "Stealth Guide",
+ fileName: "security/STEALTH_GUIDE.md",
+ },
+ ],
+ },
+ {
+ title: "Compression",
+ items: [
+ {
+ slug: "compression-engines",
+ title: "Compression Engines",
+ fileName: "compression/COMPRESSION_ENGINES.md",
+ },
+ {
+ slug: "compression-guide",
+ title: "🗜️ Prompt Compression Guide",
+ fileName: "compression/COMPRESSION_GUIDE.md",
+ },
+ {
+ slug: "compression-language-packs",
+ title: "Compression Language Packs",
+ fileName: "compression/COMPRESSION_LANGUAGE_PACKS.md",
+ },
+ {
+ slug: "compression-rules-format",
+ title: "Compression Rules Format",
+ fileName: "compression/COMPRESSION_RULES_FORMAT.md",
+ },
+ {
+ slug: "rtk-compression",
+ title: "RTK Compression",
+ fileName: "compression/RTK_COMPRESSION.md",
+ },
+ ],
+ },
+ {
+ title: "Ops",
+ items: [
+ {
+ slug: "coverage-plan",
+ title: "Test Coverage Plan",
+ fileName: "ops/COVERAGE_PLAN.md",
+ },
+ {
+ slug: "fly-io-deployment-guide",
+ title: "OmniRoute Fly.io 部署指南",
+ fileName: "ops/FLY_IO_DEPLOYMENT_GUIDE.md",
+ },
+ {
+ slug: "proxy-guide",
+ title: "OmniRoute Proxy Guide",
+ fileName: "ops/PROXY_GUIDE.md",
+ },
+ {
+ slug: "release-checklist",
+ title: "Release Checklist",
+ fileName: "ops/RELEASE_CHECKLIST.md",
+ },
+ {
+ slug: "tunnels-guide",
+ title: "Tunnels Guide",
+ fileName: "ops/TUNNELS_GUIDE.md",
+ },
+ {
+ slug: "vm-deployment-guide",
+ title: "OmniRoute — Deployment Guide on VM with Cloudflare",
+ fileName: "ops/VM_DEPLOYMENT_GUIDE.md",
},
],
},
@@ -213,8 +288,8 @@ export const autoSearchIndex: AutoGenSearchItem[] = [
{
slug: "architecture",
title: "OmniRoute Architecture",
- fileName: "ARCHITECTURE.md",
- section: "Getting Started",
+ fileName: "architecture/ARCHITECTURE.md",
+ section: "Architecture",
content:
"🌐 Languages: 🇺🇸 English 🇧🇷 Português (Brasil) 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇷🇺 Русский 🇨🇳 中文 (简体) 🇩🇪 Deutsch 🇮🇳 हिन्दी 🇹🇭 ไทย 🇺🇦 Українська 🇸🇦 العربية 🇯🇵 日本語 🇻🇳 Tiếng Việt 🇧🇬 Български 🇩🇰 Dansk 🇫🇮 Suomi 🇮🇱 עברית 🇭🇺 Magyar 🇮🇩 Bahasa Indonesia 🇰🇷 한국어 🇲\ud83c",
headings: [
@@ -227,34 +302,192 @@ export const autoSearchIndex: AutoGenSearchItem[] = [
"Core Runtime Components",
"1) API and Routing Layer (Next.js App Routes)",
"2) SSE + Translation Core",
- "3) Persistence Layer",
+ "Major Subsystems (v3.8.0)",
],
},
{
- slug: "cli-tools",
- title: "CLI Tools Setup Guide",
- fileName: "CLI-TOOLS.md",
- section: "Getting Started",
+ slug: "authz-guide",
+ title: "Authorization Guide",
+ fileName: "architecture/AUTHZ_GUIDE.md",
+ section: "Architecture",
content:
- "This guide explains how to install and configure all supported AI coding CLI tools to use OmniRoute as the unified backend, giving you centralized key management, cost tracking, model switching, and request logging across every tool. The dashboard cards in /dashboard/cli-tools are generated from src",
+ "Source of truth: src/server/authz/, src/shared/constants/publicApiRoutes.ts, src/lib/api/requireManagementAuth.ts, src/shared/utils/apiAuth.ts Last updated: 2026-05-13 — v3.8.0 OmniRoute has a route-aware authorization pipeline that gates every API request. Classification is deterministic and fail-c",
headings: [
- "How It Works",
- "Supported Tools (Dashboard Source of Truth)",
- "CLI fingerprint sync (Agents + Settings)",
- "Step 1 — Get an OmniRoute API Key",
- "Step 2 — Install CLI Tools",
- "Step 3 — Set Global Environment Variables",
- "Step 4 — Configure Each Tool",
- "Claude Code",
- "OpenAI Codex",
- "OpenCode",
+ "Two Auth Modes",
+ "1. API Key (Bearer)",
+ "2. Dashboard Session (auth_token cookie)",
+ "Route Classes",
+ "Pipeline",
+ "Policy contracts",
+ "Public Routes List",
+ "Adding a New Route",
+ "Pattern 1 — Public client API endpoint (Bearer-auth)",
+ "Pattern 2 — Management endpoint (session or Bearer + manage)",
+ ],
+ },
+ {
+ slug: "codebase-documentation",
+ title: "OmniRoute Codebase Documentation",
+ fileName: "architecture/CODEBASE_DOCUMENTATION.md",
+ section: "Architecture",
+ content:
+ "Version: v3.8.0 Last updated: 2026-05-13 Audience: Engineers contributing to OmniRoute or building integrations on top of it. For high-level architecture diagrams and the reasoning behind each subsystem, read ARCHITECTURE.md. For deep dives on individual subsystems (Auto Combo, MCP server, A2A serve",
+ headings: [
+ "1. Tech Stack",
+ "2. Repository Layout",
+ "3. src/ — Next.js Application",
+ "3.1 src/app/ — App Router",
+ "3.1.1 src/app/(dashboard)/dashboard/ — UI pages",
+ "3.1.2 src/app/api/ — Top-level API groups",
+ "3.1.3 src/app/api/v1/ — OpenAI-compatible public API",
+ "3.2 src/lib/ — Core libraries",
+ "3.2.1 src/lib/db/",
+ "3.3 src/domain/ — Domain layer",
+ ],
+ },
+ {
+ slug: "repository-map",
+ title: "Repository Map",
+ fileName: "architecture/REPOSITORY_MAP.md",
+ section: "Architecture",
+ content:
+ "One-line description for every directory and root file. Last updated: 2026-05-13 — OmniRoute v3.8.0 Use this map to navigate the codebase quickly. For deep dives, follow links to dedicated docs. ---------------------------------------- ----------------------------------------------------------------",
+ headings: [
+ "Top-level tree",
+ "Root files",
+ "src/ — Next.js application",
+ "src/app/ — App Router (Next.js 16)",
+ "src/lib/ — Core libraries (~50 modules)",
+ "src/db/ — Database (45+ modules + 55 migrations)",
+ "src/domain/",
+ "src/server/",
+ "src/shared/",
+ "open-sse/ — Streaming Engine Workspace",
+ ],
+ },
+ {
+ slug: "resilience-guide",
+ title: "Resilience Guide",
+ fileName: "architecture/RESILIENCE_GUIDE.md",
+ section: "Architecture",
+ content:
+ "OmniRoute has three distinct but related resilience mechanisms. Each has a different scope and purpose. Keep them separate when debugging routing behavior. Scope: entire provider (e.g., glm, openai, anthropic). Purpose: stop sending traffic to a provider that is repeatedly failing at the upstream/se",
+ headings: [
+ "1. Provider Circuit Breaker",
+ "2. Connection Cooldown",
+ "3. Model Lockout",
+ "Model Cooldowns Dashboard (v3.8.0)",
+ "Other Resilience Features",
+ "Debugging",
+ "TLS Fingerprinting & Stealth",
+ "See Also",
+ ],
+ },
+ {
+ slug: "docker-guide",
+ title: "🐳 Docker Guide",
+ fileName: "guides/DOCKER_GUIDE.md",
+ section: "Guides",
+ content:
+ "Complete Docker deployment reference. For a quick start, see the README Docker section. - Quick Run - With Environment File - Docker Compose - Available Profiles - Redis Sidecar - Production Compose - Dockerfile Stages - Critical Environment Variables - Docker Compose with Caddy (HTTPS) - Cloudflare",
+ headings: [
+ "Table of Contents",
+ "Quick Run",
+ "With Environment File",
+ "Docker Compose",
+ "Available Profiles",
+ "Redis Sidecar",
+ "Production Compose",
+ "Dockerfile Stages",
+ "Critical Environment Variables",
+ "Docker Compose with Caddy (HTTPS Auto-TLS)",
+ ],
+ },
+ {
+ slug: "electron-guide",
+ title: "Electron Desktop Guide",
+ fileName: "guides/ELECTRON_GUIDE.md",
+ section: "Guides",
+ content:
+ "Source of truth: electron/ workspace Last updated: 2026-05-13 — v3.8.0 OmniRoute ships a cross-platform desktop app (Windows / macOS / Linux) built on Electron 41 + electron-builder 26.10. The desktop app spawns the Next.js standalone server as a child process, points a BrowserWindow at it, and adds",
+ headings: [
+ "Architecture",
+ "Versions",
+ "Scripts (root package.json)",
+ "Directory Layout",
+ "IPC Bridge (preload.js)",
+ "Server Lifecycle",
+ "Zero-config Secret Bootstrap",
+ "Window & Tray",
+ "Content Security Policy",
+ "Auto-update",
+ ],
+ },
+ {
+ slug: "features",
+ title: "OmniRoute — Dashboard Features Gallery",
+ fileName: "guides/FEATURES.md",
+ section: "Guides",
+ content:
+ "🌐 Main README translations: 🇺🇸 English 🇧🇷 Português (Brasil) 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇷🇺 Русский 🇨🇳 中文 (简体) 🇩🇪 Deutsch 🇮🇳 हिन्दी 🇹🇭 ไทย 🇺🇦 Українська 🇸🇦 العربية 🇯🇵 日本語 🇻🇳 Tiếng Việt 🇧🇬 Български 🇩🇰 Dansk 🇫🇮 Suomi 🇮🇱 עברית 🇭🇺 Magyar 🇮🇩 Bahasa Indones",
+ headings: [
+ "✨ v3.8.0 Highlights",
+ "🔌 Providers",
+ "🎨 Combos",
+ "📊 Analytics",
+ "🏥 System Health",
+ "🔧 Translator Playground",
+ "🎮 Model Playground _(v2.0.9+)_",
+ "🎨 Themes _(v2.0.5+)_",
+ "⚙️ Settings",
+ "🔧 CLI Tools",
+ ],
+ },
+ {
+ slug: "i18n",
+ title: "i18n — Internationalization Guide",
+ fileName: "guides/I18N.md",
+ section: "Guides",
+ content:
+ "OmniRoute supports 30 languages with full dashboard UI translation, translated documentation, and RTL support for Arabic and Hebrew. 🌐 Languages: 🇺🇸 English 🇧🇷 Português (Brasil) 🇪🇸 Español 🇫🇷 Français 🇩🇪 Deutsch 🇮🇹 Italiano 🇷🇺 Русский 🇨🇳 中文 (简体) 🇯🇵 日本語 🇰🇷 한국어 🇸🇦 العربية 🇮🇳 ",
+ headings: [
+ "Quick Reference",
+ "Architecture",
+ "Source of Truth",
+ "Runtime Flow",
+ "Supported Locales",
+ "Adding a New Language",
+ "1. Register the Locale",
+ "2. Add to Generator",
+ "3. Generate Initial Translation",
+ "4. Review & Fix Auto-Translations",
+ ],
+ },
+ {
+ slug: "pwa-guide",
+ title: "Progressive Web App (PWA) Guide",
+ fileName: "guides/PWA_GUIDE.md",
+ section: "Guides",
+ content:
+ 'OmniRoute ships as a fully installable Progressive Web App. When you access the dashboard from any mobile browser — Android (Chrome) or iOS (Safari) — you can "Add to Home Screen" and get a native app-like experience with no app store required. A Progressive Web App turns the OmniRoute web dashboard',
+ headings: [
+ "What Is a PWA?",
+ "Installation",
+ "Android (Chrome)",
+ "iOS (Safari)",
+ "Desktop (Chrome / Edge)",
+ "Features",
+ "Fullscreen Experience",
+ "Offline Support",
+ "Offline Page",
+ "App Icons",
],
},
{
slug: "setup-guide",
title: "Setup Guide",
- fileName: "SETUP_GUIDE.md",
- section: "Getting Started",
+ fileName: "guides/SETUP_GUIDE.md",
+ section: "Guides",
content:
"Complete setup reference for OmniRoute. For the quick version, see the Quick Start in README. - Install Methods - CLI Tool Configuration - Protocol Setup (MCP + A2A) - Timeout Configuration - Split-Port Mode - Void Linux (xbps-src) - Uninstalling -------------------- --------------------------------",
headings: [
@@ -265,16 +498,76 @@ export const autoSearchIndex: AutoGenSearchItem[] = [
"Arch Linux (AUR)",
"From Source",
"Docker",
+ "Desktop App (Electron)",
+ "Headless server (CI/automation)",
"CLI Options",
- "CLI Tool Configuration",
- "1) Connect Providers and Create API Key",
+ ],
+ },
+ {
+ slug: "termux-guide",
+ title: "Termux Headless Setup",
+ fileName: "guides/TERMUX_GUIDE.md",
+ section: "Guides",
+ content:
+ "OmniRoute can run as a headless server on Android through Termux. The Electron desktop app is not supported in Termux, but the web dashboard and OpenAI-compatible API work from the local browser or from other devices on the same network. Install Termux from F-Droid or GitHub releases, then update pa",
+ headings: [
+ "Prerequisites",
+ "Install",
+ "Run",
+ "Background Execution",
+ "Access From Other Devices",
+ "Data Directory",
+ "Limitations",
+ "Troubleshooting",
+ "better-sqlite3 Build Errors",
+ "Port Already In Use",
+ ],
+ },
+ {
+ slug: "troubleshooting",
+ title: "Troubleshooting",
+ fileName: "guides/TROUBLESHOOTING.md",
+ section: "Guides",
+ content:
+ "🌐 Languages: 🇺🇸 English 🇧🇷 Português (Brasil) 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇷🇺 Русский 🇨🇳 中文 (简体) 🇩🇪 Deutsch 🇮🇳 हिन्दी 🇹🇭 ไทย 🇺🇦 Українська 🇸🇦 العربية 🇯🇵 日本語 🇻🇳 Tiếng Việt 🇧🇬 Български 🇩🇰 Dansk 🇫🇮 Suomi 🇮🇱 עברית 🇭🇺 Magyar 🇮🇩 Bahasa Indonesia 🇰🇷 한국어 🇲\ud83c",
+ headings: [
+ "Quick Fixes",
+ "Node.js Compatibility",
+ 'Login page crashes or shows "Module self-registration" error',
+ 'macOS: dlopen / "slice is not valid mach-o file"',
+ "Proxy Issues",
+ 'Provider validation shows "fetch failed"',
+ 'Token health check fails with "fetch failed"',
+ 'SOCKS5 proxy returns "invalid onRequestStart method"',
+ "Provider Issues",
+ '"Language model did not provide messages"',
+ ],
+ },
+ {
+ slug: "uninstall",
+ title: "OmniRoute — Uninstall Guide",
+ fileName: "guides/UNINSTALL.md",
+ section: "Guides",
+ content:
+ "🌐 Languages: 🇺🇸 English 🇧🇷 Português (Brasil) 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇷🇺 Русский 🇨🇳 中文 (简体) 🇩🇪 Deutsch 🇮🇳 हिन्दी 🇹🇭 ไทย 🇺🇦 Українська 🇸🇦 العربية 🇯🇵 日本語 🇻🇳 Tiếng Việt 🇧🇬 Български 🇩🇰 Dansk 🇫🇮 Suomi 🇮🇱 עברית 🇭🇺 Magyar 🇮🇩 Bahasa Indonesia 🇰🇷 한국어 🇲\ud83c",
+ headings: [
+ "Quick Uninstall (v3.6.2+)",
+ "Keep Your Data",
+ "Full Removal",
+ "Manual Uninstall",
+ "NPM Global Install",
+ "pnpm Global Install",
+ "Docker",
+ "Docker Compose",
+ "Electron Desktop App",
+ "Source Install (git clone)",
],
},
{
slug: "user-guide",
title: "User Guide",
- fileName: "USER_GUIDE.md",
- section: "Getting Started",
+ fileName: "guides/USER_GUIDE.md",
+ section: "Guides",
content:
"🌐 Languages: 🇺🇸 English 🇧🇷 Português (Brasil) 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇷🇺 Русский 🇨🇳 中文 (简体) 🇩🇪 Deutsch 🇮🇳 हिन्दी 🇹🇭 ไทย 🇺🇦 Українська 🇸🇦 العربية 🇯🇵 日本語 🇻🇳 Tiếng Việt 🇧🇬 Български 🇩🇰 Dansk 🇫🇮 Suomi 🇮🇱 עברית 🇭🇺 Magyar 🇮🇩 Bahasa Indonesia 🇰🇷 한국어 🇲\ud83c",
headings: [
@@ -290,11 +583,271 @@ export const autoSearchIndex: AutoGenSearchItem[] = [
"Claude Code (Pro/Max)",
],
},
+ {
+ slug: "api-reference",
+ title: "API Reference",
+ fileName: "reference/API_REFERENCE.md",
+ section: "Reference",
+ content:
+ "🌐 Languages: 🇺🇸 English 🇧🇷 Português (Brasil) 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇷🇺 Русский 🇨🇳 中文 (简体) 🇩🇪 Deutsch 🇮🇳 हिन्दी 🇹🇭 ไทย 🇺🇦 Українська 🇸🇦 العربية 🇯🇵 日本語 🇻🇳 Tiếng Việt 🇧🇬 Български 🇩🇰 Dansk 🇫🇮 Suomi 🇮🇱 עברית 🇭🇺 Magyar 🇮🇩 Bahasa Indonesia 🇰🇷 한국어 🇲\ud83c",
+ headings: [
+ "Table of Contents",
+ "Chat Completions",
+ "Custom Headers",
+ "Embeddings",
+ "Image Generation",
+ "List Models",
+ "Compatibility Endpoints",
+ "Dedicated Provider Routes",
+ "Files API",
+ "Batches API",
+ ],
+ },
+ {
+ slug: "cli-tools",
+ title: "CLI Tools — OmniRoute v3.8.0",
+ fileName: "reference/CLI-TOOLS.md",
+ section: "Reference",
+ content:
+ "Last updated: 2026-05-13 OmniRoute integrates with two categories of CLI tools: 1. External CLI integrations — third-party CLIs (Cursor, Cline, Codex, Claude Code, Qwen Code, Windsurf, Hermes, Amp, etc.) that you point at OmniRoute's local OpenAI-compatible endpoint. 2. Internal OmniRoute CLI — comm",
+ headings: [
+ "How It Works",
+ "1. External CLI Integrations",
+ "Source of Truth",
+ "Current Catalog (v3.8.0)",
+ "CLI fingerprint sync (Agents + Settings)",
+ "Step 1 — Get an OmniRoute API Key",
+ "Step 2 — Install CLI Tools",
+ "Step 3 — Set Global Environment Variables",
+ "Step 4 — Configure Each Tool",
+ "Claude Code",
+ ],
+ },
+ {
+ slug: "environment",
+ title: "Environment Variables Reference",
+ fileName: "reference/ENVIRONMENT.md",
+ section: "Reference",
+ content:
+ "Complete reference for every environment variable recognized by OmniRoute. For a quick-start template, see .env.example. These must be set before the first run. Without them, the application will either refuse to start or operate with insecure defaults. Variable Required Default Source File Descript",
+ headings: [
+ "Table of Contents",
+ "1. Required Secrets",
+ "Generation Commands",
+ "2. Storage & Database",
+ "Scenarios",
+ "3. Network & Ports",
+ "Port Modes",
+ "4. Security & Authentication",
+ "Hardening Checklist",
+ "5. Input Sanitization & PII Protection",
+ ],
+ },
+ {
+ slug: "free-tiers",
+ title: "Free Tiers",
+ fileName: "reference/FREE_TIERS.md",
+ section: "Reference",
+ content:
+ "Last consolidated: 2026-05-13 — OmniRoute v3.8.0 Source of truth: src/shared/constants/providers.ts (FREEPROVIDERS, OAUTHPROVIDERS, and APIKEYPROVIDERS entries flagged with hasFree: true + freeNote) This page lists providers with usable free tiers shipped in OmniRoute v3.8.0. The data is derived fro",
+ headings: [
+ "How free providers are wired",
+ "Quick reference (API key providers with hasFree: true)",
+ "OAuth-based free tiers",
+ "Always-free OAuth providers (in FREE_PROVIDERS)",
+ "OAuth providers with vendor-controlled free tiers (in OAUTH_PROVIDERS)",
+ "Deprecated / discontinued",
+ "Qwen Code (qwen)",
+ "Command Code",
+ "Environment variables",
+ "How to use",
+ ],
+ },
+ {
+ slug: "provider-reference",
+ title: "Provider Reference",
+ fileName: "reference/PROVIDER_REFERENCE.md",
+ section: "Reference",
+ content:
+ "Auto-generated from src/shared/constants/providers.ts — do not edit by hand. Regenerate with: npm run gen:provider-reference Last generated: 2026-05-13 Total providers: 177. See category breakdown below. - Free — free tier with API key (configured via dashboard) - OAuth — sign-in flow handled by Omn",
+ headings: [
+ "Categories",
+ "Free Tier (OAuth-first or no-key) (5)",
+ "OAuth Providers (11)",
+ "Web Cookie Providers (5)",
+ "API Key Providers (paid / paid-with-free-credits) (123)",
+ "Local Providers (10)",
+ "Search Providers (11)",
+ "Audio-only Providers (7)",
+ "Upstream Proxy Providers (1)",
+ "Cloud Agent Providers (3)",
+ ],
+ },
+ {
+ slug: "a2a-server",
+ title: "OmniRoute A2A Server Documentation",
+ fileName: "frameworks/A2A-SERVER.md",
+ section: "Frameworks",
+ content:
+ "Agent-to-Agent Protocol v0.3 — OmniRoute as an intelligent routing agent The A2A surface has two faces: - JSON-RPC 2.0 at POST /a2a (canonical entry point, defined in src/app/a2a/route.ts). - REST under /api/a2a/ for dashboards and tooling (status, task list, cancel). Tasks are tracked by A2ATaskMan",
+ headings: [
+ "Agent Discovery",
+ "Authentication",
+ "Enablement",
+ "JSON-RPC 2.0 Methods",
+ "message/send — Synchronous Execution",
+ "message/stream — SSE Streaming",
+ "tasks/get — Query Task Status",
+ "tasks/cancel — Cancel a Task",
+ "Available Skills",
+ "REST API (auxiliary)",
+ ],
+ },
+ {
+ slug: "agent-protocols-guide",
+ title: "Agent Protocols Guide",
+ fileName: "frameworks/AGENT_PROTOCOLS_GUIDE.md",
+ section: "Frameworks",
+ content:
+ "Source: src/lib/{a2a,acp,cloudAgent}/, src/app/api/{a2a,acp,cloud}/, src/app/api/v1/agents/ Last updated: 2026-05-13 — v3.8.0 OmniRoute exposes three different agent-related surfaces. They look similar at first glance but solve different problems. Use this page to pick the right one. Surface Best fo",
+ headings: [
+ "TL;DR",
+ "Decision Tree",
+ "1. A2A — Agent-to-Agent",
+ "When to use",
+ "Methods",
+ "Built-in skills (5)",
+ "Deep dive",
+ "2. ACP — CLI Agents Registry",
+ "What it is",
+ "What it does",
+ ],
+ },
+ {
+ slug: "cloud-agent",
+ title: "Cloud Agents",
+ fileName: "frameworks/CLOUD_AGENT.md",
+ section: "Frameworks",
+ content:
+ "Source of truth: src/lib/cloudAgent/ and src/app/api/v1/agents/tasks/ Last updated: 2026-05-13 — v3.8.0 OmniRoute orchestrates third-party cloud-hosted coding agents (Codex Cloud, Devin, Jules) as long-running tasks. Each agent is wrapped behind a uniform interface so clients can submit a prompt + r",
+ headings: [
+ "Supported Agents",
+ "Architecture",
+ "CloudAgentBase Interface",
+ "Domain Types",
+ "Database",
+ "REST API — Task Lifecycle",
+ "Create task",
+ "Approve a plan",
+ "Send a follow-up message",
+ "Cancel (local status only)",
+ ],
+ },
+ {
+ slug: "evals",
+ title: "Evaluations (Evals)",
+ fileName: "frameworks/EVALS.md",
+ section: "Frameworks",
+ content:
+ 'Source of truth: src/lib/evals/, src/lib/db/evals.ts, src/app/api/evals/ Last updated: 2026-05-13 — v3.8.0 OmniRoute ships a generic evaluation framework you can use to benchmark routing configurations, single providers/models, or the bundled "golden set" suites. Use it to verify routing changes, va',
+ headings: [
+ "Concepts",
+ "Suite",
+ "Case",
+ "Target",
+ "Scoring Rubrics",
+ "Database Schema",
+ "REST API",
+ "Running a suite",
+ "Creating a custom suite",
+ "Dispatch Pipeline",
+ ],
+ },
+ {
+ slug: "mcp-server",
+ title: "OmniRoute MCP Server Documentation",
+ fileName: "frameworks/MCP-SERVER.md",
+ section: "Frameworks",
+ content:
+ "Model Context Protocol server with 37 tools across routing, cache, compression, memory, skills, and proxy operations. Source of truth: open-sse/mcp-server/schemas/tools.ts (30 tools) + open-sse/mcp-server/tools/memoryTools.ts (3 tools) + open-sse/mcp-server/tools/skillTools.ts (4 tools). Tool regist",
+ headings: [
+ "Installation",
+ "Transports",
+ "IDE Configuration",
+ "Essential Tools (8) — Phase 1",
+ "Phase 1 — Search",
+ "Advanced Tools (11) — Phase 2",
+ "Cache Tools (2)",
+ "Compression Tools (5)",
+ "1Proxy Tools (3)",
+ "Memory Tools (3)",
+ ],
+ },
+ {
+ slug: "memory",
+ title: "Memory System",
+ fileName: "frameworks/MEMORY.md",
+ section: "Frameworks",
+ content:
+ "Source of truth: src/lib/memory/ and src/app/api/memory/ Last updated: 2026-05-13 — v3.8.0 OmniRoute provides persistent conversational memory keyed by API key (and optionally session id). Memories are extracted automatically from LLM responses via lightweight regex pattern matching and injected bac",
+ headings: [
+ "Architecture",
+ "Storage Layers",
+ "Primary: SQLite (memories table)",
+ "Full-text Search (memory_fts virtual table)",
+ "Optional: Qdrant (vector store)",
+ "Memory Types",
+ "Fact Extraction (extraction.ts)",
+ "Retrieval (retrieval.ts)",
+ "Injection (injection.ts)",
+ "Settings (settings.ts)",
+ ],
+ },
+ {
+ slug: "skills",
+ title: "Skills Framework",
+ fileName: "frameworks/SKILLS.md",
+ section: "Frameworks",
+ content:
+ "Source of truth: src/lib/skills/ and src/app/api/skills/ Last updated: 2026-05-13 — v3.8.0 OmniRoute exposes an extensible Skills framework that lets language models (and operators) compose reusable capabilities — from filesystem reads and HTTP requests to sandboxed code execution and curated market",
+ headings: [
+ "Concepts",
+ "Skill Sources",
+ "Skill Identity",
+ "Skill Mode",
+ "Status (executions)",
+ "Registry Cache",
+ "Provider-Aware Injection",
+ "AUTO Scoring",
+ "Tool Call Interception",
+ "Docker Sandbox",
+ ],
+ },
+ {
+ slug: "webhooks",
+ title: "Webhooks",
+ fileName: "frameworks/WEBHOOKS.md",
+ section: "Frameworks",
+ content:
+ "Source of truth: src/lib/webhookDispatcher.ts, src/lib/db/webhooks.ts, src/app/api/webhooks/ Last updated: 2026-05-13 — v3.8.0 OmniRoute can fire HTTP webhooks on platform events. Use them to integrate with Slack, PagerDuty, Datadog, internal alerting services, or any HTTP receiver. The dispatcher s",
+ headings: [
+ "Supported Events",
+ "Architecture",
+ "HMAC Signing",
+ "Verifying on the receiver",
+ "Retry & Failure Policy",
+ "Database",
+ "REST API",
+ "Create webhook",
+ "Test webhook",
+ "Dashboard",
+ ],
+ },
{
slug: "auto-combo",
title: "OmniRoute Auto-Combo Engine",
- fileName: "AUTO-COMBO.md",
- section: "Features",
+ fileName: "routing/AUTO-COMBO.md",
+ section: "Routing",
content:
"Self-managing model chains with adaptive scoring + zero-config auto-routing NEW: No combo creation required. Use auto/ prefix directly in any client. Model ID Variant Behavior -------------- ------- ------------------------------------------------------------------------ auto default All connected p",
headings: [
@@ -302,23 +855,103 @@ export const autoSearchIndex: AutoGenSearchItem[] = [
"Quick Examples",
"How It Works (Persisted Auto-Combos)",
"Mode Packs",
+ "All Routing Strategies",
+ "Virtual Auto-Combo Factory",
"Self-Healing",
"Bandit Exploration",
"API",
"Task Fitness",
- "Files",
+ ],
+ },
+ {
+ slug: "reasoning-replay",
+ title: "Reasoning Replay Cache",
+ fileName: "routing/REASONING_REPLAY.md",
+ section: "Routing",
+ content:
+ "Source of truth: src/lib/db/reasoningCache.ts, open-sse/services/reasoningCache.ts Last updated: 2026-05-13 — v3.8.0 OmniRoute captures assistant reasoningcontent produced by thinking-mode models and replays it transparently on multi-turn requests when the upstream provider requires it. This elimina",
+ headings: [
+ "Why This Exists",
+ "Architecture",
+ "Storage — Hybrid Memory + SQLite",
+ "Database Schema",
+ "Provider / Model Detection",
+ "REST API",
+ "Operational Notes",
+ "See Also",
+ ],
+ },
+ {
+ slug: "compliance",
+ title: "Compliance & Audit",
+ fileName: "security/COMPLIANCE.md",
+ section: "Security",
+ content:
+ "Source of truth: src/lib/compliance/, src/app/api/compliance/ Last updated: 2026-05-13 — v3.8.0 OmniRoute records administrative actions, authentication events, provider credential lifecycle changes, and MCP tool invocations to SQLite-backed audit tables. This page covers what gets logged, where it ",
+ headings: [
+ "What Gets Logged",
+ "Administrative audit events (audit_log)",
+ "MCP tool calls (mcp_tool_audit)",
+ "Request / usage logs",
+ "Storage Schema",
+ "Retention & Cleanup",
+ "noLog Opt-Out (per API key)",
+ "REST API",
+ "Querying /api/compliance/audit-log",
+ "Dashboard",
+ ],
+ },
+ {
+ slug: "guardrails",
+ title: "Guardrails",
+ fileName: "security/GUARDRAILS.md",
+ section: "Security",
+ content:
+ "Source of truth: src/lib/guardrails/ Last updated: 2026-05-13 — v3.8.0 Guardrails enforce safety, policy, and content transformations at the boundary between OmniRoute and upstream providers. Each guardrail can inspect (and optionally reject, transform, or annotate) request payloads (preCall) and up",
+ headings: [
+ "Built-in Guardrails",
+ "Vision Bridge (visionBridge.ts)",
+ "PII Masker (piiMasker.ts)",
+ "Prompt Injection (promptInjection.ts)",
+ "Base Contract (base.ts)",
+ "Registry (registry.ts)",
+ "Disabling Guardrails Per-Request",
+ "Execution Order",
+ "Configuration",
+ "Custom Guardrails",
+ ],
+ },
+ {
+ slug: "stealth-guide",
+ title: "Stealth Guide",
+ fileName: "security/STEALTH_GUIDE.md",
+ section: "Security",
+ content:
+ "Source of truth: open-sse/utils/tlsClient.ts, open-sse/services/{chatgptTlsClient,claudeCodeCCH,claudeCodeFingerprint,claudeCodeObfuscation,claudeCodeCompatible,antigravityObfuscation}.ts, open-sse/config/cliFingerprints.ts, src/mitm/ Last updated: 2026-05-13 — v3.8.0 Audience: Engineers maintaining",
+ headings: [
+ "Legal and Ethical Notice",
+ "TLS Fingerprinting Layer",
+ "open-sse/utils/tlsClient.ts — wreq-js (Chrome 124)",
+ "open-sse/services/chatgptTlsClient.ts — tls-client-node (Firefox 148)",
+ "Claude Code Stealth Bundle",
+ "claudeCodeFingerprint.ts",
+ "claudeCodeCCH.ts (Client Content Hash)",
+ "claudeCodeObfuscation.ts",
+ "claudeCodeCompatible.ts — anthropic-compatible-cc- providers",
+ "Antigravity Stealth",
],
},
{
slug: "compression-engines",
title: "Compression Engines",
- fileName: "COMPRESSION_ENGINES.md",
- section: "Features",
+ fileName: "compression/COMPRESSION_ENGINES.md",
+ section: "Compression",
content:
"OmniRoute compression is built around engine contracts. A mode can run one engine directly (caveman or rtk) or a deterministic stacked pipeline that executes multiple engines in order. Mode Engine path Intended input ------------ ---------------------------------- -----------------------------------",
headings: [
"Modes",
"Engine Registry",
+ "MCP description compression (related)",
"Caveman",
"RTK",
"Stacked Pipelines",
@@ -331,8 +964,8 @@ export const autoSearchIndex: AutoGenSearchItem[] = [
{
slug: "compression-guide",
title: "🗜️ Prompt Compression Guide",
- fileName: "COMPRESSION_GUIDE.md",
- section: "Features",
+ fileName: "compression/COMPRESSION_GUIDE.md",
+ section: "Compression",
content:
"Save 15-95% on eligible context automatically. For a quick overview, see the README Compression section. OmniRoute implements a modular prompt compression pipeline that runs proactively before requests hit upstream providers. This means your token savings happen transparently — no changes needed to ",
headings: [
@@ -351,10 +984,10 @@ export const autoSearchIndex: AutoGenSearchItem[] = [
{
slug: "compression-language-packs",
title: "Compression Language Packs",
- fileName: "COMPRESSION_LANGUAGE_PACKS.md",
- section: "Features",
+ fileName: "compression/COMPRESSION_LANGUAGE_PACKS.md",
+ section: "Compression",
content:
- "Caveman compression can load language-specific rule packs in addition to the built-in English rules. This keeps the core engine stable while allowing Portuguese, Spanish, German, French, Japanese, and future language packs to evolve independently. Language packs live under: Current shipped packs inc",
+ "Caveman compression can load language-specific rule packs in addition to the built-in English rules. This keeps the core engine stable while allowing Portuguese, Spanish, German, French, Japanese, and future language packs to evolve independently. Language packs live under: Current shipped packs (ve",
headings: [
"Location",
"Language Detection",
@@ -367,10 +1000,10 @@ export const autoSearchIndex: AutoGenSearchItem[] = [
{
slug: "compression-rules-format",
title: "Compression Rules Format",
- fileName: "COMPRESSION_RULES_FORMAT.md",
- section: "Features",
+ fileName: "compression/COMPRESSION_RULES_FORMAT.md",
+ section: "Compression",
content:
- "Compression rules are JSON files loaded at runtime. They are intentionally data-only so new language packs and RTK command filters can be reviewed without changing engine code. Caveman rule packs live under: Each pack contains replacements that apply to normal prose after protected regions are isola",
+ "Compression rules are JSON files loaded at runtime. They are intentionally data-only so new language packs and RTK command filters can be reviewed without changing engine code. Canonical schema (source of truth): open-sse/services/compression/rules/schema.json (JSON Schema draft 2020-12). The exampl",
headings: [
"Caveman Rule Packs",
"Caveman Fields",
@@ -380,51 +1013,11 @@ export const autoSearchIndex: AutoGenSearchItem[] = [
"Validation",
],
},
- {
- slug: "features",
- title: "OmniRoute — Dashboard Features Gallery",
- fileName: "FEATURES.md",
- section: "Features",
- content:
- "🌐 Main README translations: 🇺🇸 English 🇧🇷 Português (Brasil) 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇷🇺 Русский 🇨🇳 中文 (简体) 🇩🇪 Deutsch 🇮🇳 हिन्दी 🇹🇭 ไทย 🇺🇦 Українська 🇸🇦 العربية 🇯🇵 日本語 🇻🇳 Tiếng Việt 🇧🇬 Български 🇩🇰 Dansk 🇫🇮 Suomi 🇮🇱 עברית 🇭🇺 Magyar 🇮🇩 Bahasa Indones",
- headings: [
- "🔌 Providers",
- "🎨 Combos",
- "📊 Analytics",
- "🏥 System Health",
- "🔧 Translator Playground",
- "🎮 Model Playground _(v2.0.9+)_",
- "🎨 Themes _(v2.0.5+)_",
- "⚙️ Settings",
- "🔧 CLI Tools",
- "🤖 CLI Agents _(v2.0.11+)_",
- ],
- },
- {
- slug: "free-tiers",
- title: "🆓 Free LLM API Providers — Consolidated Directory",
- fileName: "FREE_TIERS.md",
- section: "Features",
- content:
- "The ultimate aggregated reference for all permanently free LLM API providers. Consolidated from 6 community repositories. Use with OmniRoute to route through 25+ free providers simultaneously. Last consolidated: May 2026 · Sources: awesome-free-llm-apis, awesome-free-llm-apis2, free-llm-api-resource",
- headings: [
- "Table of Contents",
- "Quick Comparison",
- "Provider APIs (First-Party)",
- "Google Gemini 🇺🇸",
- "Mistral AI 🇫🇷",
- "Cohere 🇨🇦",
- "Z.AI (Zhipu AI) 🇨🇳",
- "IBM watsonx 🇺🇸",
- "Inference Providers (Third-Party)",
- "Groq 🇺🇸",
- ],
- },
{
slug: "rtk-compression",
title: "RTK Compression",
- fileName: "RTK_COMPRESSION.md",
- section: "Features",
+ fileName: "compression/RTK_COMPRESSION.md",
+ section: "Compression",
content:
"RTK compression is OmniRoute's command-aware compression engine for terminal and tool output. It is designed for coding-agent sessions where most context growth comes from test logs, build output, package manager noise, shell transcripts, Docker output, git output, and stack traces. RTK can run dire",
headings: [
@@ -439,90 +1032,30 @@ export const autoSearchIndex: AutoGenSearchItem[] = [
],
},
{
- slug: "a2a-server",
- title: "OmniRoute A2A Server Documentation",
- fileName: "A2A-SERVER.md",
- section: "API & Protocols",
+ slug: "coverage-plan",
+ title: "Test Coverage Plan",
+ fileName: "ops/COVERAGE_PLAN.md",
+ section: "Ops",
content:
- "Agent-to-Agent Protocol v0.3 — OmniRoute as an intelligent routing agent Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. Sends a message to a skill and waits for the complete response. Response: Same as message/send but returns Server-Sent Events ",
+ "Last updated: 2026-05-13 Status measured on 2026-05-13: lines 82.58%, statements 82.58%, functions 84.23%, branches 75.22%. Phases 1-5 are complete. Current focus is Phase 6 (=85%) and Phase 7 (=90%). There are multiple coverage numbers depending on how the report is computed. For planning, only one",
headings: [
- "Agent Discovery",
- "Authentication",
- "Enablement",
- "JSON-RPC 2.0 Methods",
- "message/send — Synchronous Execution",
- "message/stream — SSE Streaming",
- "tasks/get — Query Task Status",
- "tasks/cancel — Cancel a Task",
- "Available Skills",
- "Task Lifecycle",
- ],
- },
- {
- slug: "api-reference",
- title: "API Reference",
- fileName: "API_REFERENCE.md",
- section: "API & Protocols",
- content:
- "🌐 Languages: 🇺🇸 English 🇧🇷 Português (Brasil) 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇷🇺 Русский 🇨🇳 中文 (简体) 🇩🇪 Deutsch 🇮🇳 हिन्दी 🇹🇭 ไทย 🇺🇦 Українська 🇸🇦 العربية 🇯🇵 日本語 🇻🇳 Tiếng Việt 🇧🇬 Български 🇩🇰 Dansk 🇫🇮 Suomi 🇮🇱 עברית 🇭🇺 Magyar 🇮🇩 Bahasa Indonesia 🇰🇷 한국어 🇲\ud83c",
- headings: [
- "Table of Contents",
- "Chat Completions",
- "Custom Headers",
- "Embeddings",
- "Image Generation",
- "List Models",
- "Compatibility Endpoints",
- "Dedicated Provider Routes",
- "Semantic Cache",
- "Dashboard & Management",
- ],
- },
- {
- slug: "mcp-server",
- title: "OmniRoute MCP Server Documentation",
- fileName: "MCP-SERVER.md",
- section: "API & Protocols",
- content:
- "Model Context Protocol server with 37 tools across routing, cache, compression, memory, skills, and proxy operations OmniRoute MCP is built-in. Start it with: Or via the open-sse transport: See MCP Client Configuration for Claude Desktop, Cursor, Cline, and compatible MCP client setup. -------------",
- headings: [
- "Installation",
- "IDE Configuration",
- "Essential Tools (8)",
- "Advanced Tools (8)",
- "Cache Tools (2)",
- "Compression Tools (5)",
- "Other Tool Groups",
- "Authentication",
- "Audit Logging",
- "Files",
- ],
- },
- {
- slug: "docker-guide",
- title: "🐳 Docker Guide",
- fileName: "DOCKER_GUIDE.md",
- section: "Deployment",
- content:
- "Complete Docker deployment reference. For a quick start, see the README Docker section. - Quick Run - With Environment File - Docker Compose - Docker Compose with Caddy (HTTPS) - Cloudflare Quick Tunnel - Image Tags - Important Notes --------------------- -------- ------ --------------------- diegos",
- headings: [
- "Table of Contents",
- "Quick Run",
- "With Environment File",
- "Docker Compose",
- "Docker Compose with Caddy (HTTPS Auto-TLS)",
- "Cloudflare Quick Tunnel",
- "Tunnel Notes",
- "Image Tags",
- "Important Notes",
- "See Also",
+ "Baseline",
+ "Rules",
+ "Current command set",
+ "Milestones",
+ "Priority hotspots",
+ "Execution checklist",
+ "Phase 1: 56.95% -> 60%",
+ "Phase 2: 60% -> 65%",
+ "Phase 3: 65% -> 70%",
+ "Phase 4: 70% -> 75%",
],
},
{
slug: "fly-io-deployment-guide",
title: "OmniRoute Fly.io 部署指南",
- fileName: "FLY_IO_DEPLOYMENT_GUIDE.md",
- section: "Deployment",
+ fileName: "ops/FLY_IO_DEPLOYMENT_GUIDE.md",
+ section: "Ops",
content:
"本文档记录 OmniRoute 在 Fly.io 上的实际部署方法，适用于两类场景： - 首次把当前项目部署到 Fly.io - 后续代码更新后继续发布 - 新项目参考同样流程部署 本文基于当前项目已经验证通过的配置整理，应用名为 omniroute。 当前仓库中的 fly.toml 已确认包含以下关键项： 说明： - app = 'omniroute' 决定实际部署到哪个 Fly 应用 - destination = '/data' 决定持久卷挂载目录 - 本项目必须让 DATADIR=/data，否则数据库和密钥会写到容器临时目录 --- Windows PowerShell： 如果安装脚",
headings: [
@@ -539,50 +1072,70 @@ export const autoSearchIndex: AutoGenSearchItem[] = [
],
},
{
- slug: "pwa-guide",
- title: "Progressive Web App (PWA) Guide",
- fileName: "PWA_GUIDE.md",
- section: "Deployment",
+ slug: "proxy-guide",
+ title: "OmniRoute Proxy Guide",
+ fileName: "ops/PROXY_GUIDE.md",
+ section: "Ops",
content:
- 'OmniRoute ships as a fully installable Progressive Web App. When you access the dashboard from any mobile browser — Android (Chrome) or iOS (Safari) — you can "Add to Home Screen" and get a native app-like experience with no app store required. A Progressive Web App turns the OmniRoute web dashboard',
+ "Bypass geographic blocks, protect your identity, and route AI traffic through any proxy — with zero configuration complexity. OmniRoute includes a full-featured proxy management system that lets you route upstream AI provider traffic through HTTP, HTTPS, or SOCKS5 proxies. Whether you're in a blocke",
headings: [
- "What Is a PWA?",
- "Installation",
- "Android (Chrome)",
- "iOS (Safari)",
- "Desktop (Chrome / Edge)",
- "Features",
- "Fullscreen Experience",
- "Offline Support",
- "Offline Page",
- "App Icons",
+ "Table of Contents",
+ "Why Use Proxies?",
+ "Architecture Overview",
+ "Key Components",
+ "4-Level Proxy System",
+ "How Resolution Works",
+ "What Gets Proxied",
+ "Proxy Registry (CRUD)",
+ "Creating a Proxy",
+ "Updating a Proxy",
],
},
{
- slug: "termux-guide",
- title: "Termux Headless Setup",
- fileName: "TERMUX_GUIDE.md",
- section: "Deployment",
+ slug: "release-checklist",
+ title: "Release Checklist",
+ fileName: "ops/RELEASE_CHECKLIST.md",
+ section: "Ops",
content:
- "OmniRoute can run as a headless server on Android through Termux. The Electron desktop app is not supported in Termux, but the web dashboard and OpenAI-compatible API work from the local browser or from other devices on the same network. Install Termux from F-Droid or GitHub releases, then update pa",
+ "Last updated: 2026-05-13 — v3.8.0 Streamlined release flow that leverages Claude Code skills for automation. - [ ] All PRs targeted to this release are merged to release/vX.Y.0 - [ ] All open Linear/issue items for this version are closed or pushed to next milestone - [ ] CI green on release/vX.Y.0 ",
headings: [
+ "TL;DR",
+ "Detailed Checklist",
+ "Pre-release",
+ "Version & Changelog",
+ "Code Quality",
+ "Testing",
+ "Hooks (Husky validated)",
+ "Conventional Commits",
+ "Documentation",
+ "i18n",
+ ],
+ },
+ {
+ slug: "tunnels-guide",
+ title: "Tunnels Guide",
+ fileName: "ops/TUNNELS_GUIDE.md",
+ section: "Ops",
+ content:
+ "Source of truth: src/lib/{cloudflaredTunnel,ngrokTunnel,tailscaleTunnel}.ts, src/app/api/tunnels/ Last updated: 2026-05-13 — v3.8.0 OmniRoute can expose its local server (http://localhost:20128) to the public internet via three tunnel backends. This is useful for: - OAuth callbacks from cloud provid",
+ headings: [
+ "Backends at a glance",
+ "1. Cloudflare Tunnel (Quick Tunnel)",
+ "Enable / disable via REST",
+ "Optional env vars",
+ "2. ngrok",
"Prerequisites",
- "Install",
- "Run",
- "Background Execution",
- "Access From Other Devices",
- "Data Directory",
- "Limitations",
- "Troubleshooting",
- "better-sqlite3 Build Errors",
- "Port Already In Use",
+ "Enable / disable via REST",
+ "3. Tailscale Funnel",
+ "Prerequisites",
+ "REST endpoints",
],
},
{
slug: "vm-deployment-guide",
title: "OmniRoute — Deployment Guide on VM with Cloudflare",
- fileName: "VM_DEPLOYMENT_GUIDE.md",
- section: "Deployment",
+ fileName: "ops/VM_DEPLOYMENT_GUIDE.md",
+ section: "Ops",
content:
"🌐 Languages: 🇺🇸 English 🇧🇷 Português (Brasil) 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇷🇺 Русский 🇨🇳 中文 (简体) 🇩🇪 Deutsch 🇮🇳 हिन्दी 🇹🇭 ไทย 🇺🇦 Українська 🇸🇦 العربية 🇯🇵 日本語 🇻🇳 Tiếng Việt 🇧🇬 Български 🇩🇰 Dansk 🇫🇮 Suomi 🇮🇱 עברית 🇭🇺 Magyar 🇮🇩 Bahasa Indonesia 🇰🇷 한국어 🇲\ud83c",
headings: [
@@ -598,200 +1151,11 @@ export const autoSearchIndex: AutoGenSearchItem[] = [
"2.1 Create configuration directory",
],
},
- {
- slug: "environment",
- title: "Environment Variables Reference",
- fileName: "ENVIRONMENT.md",
- section: "Operations",
- content:
- "Complete reference for every environment variable recognized by OmniRoute. For a quick-start template, see .env.example. These must be set before the first run. Without them, the application will either refuse to start or operate with insecure defaults. Variable Required Default Source File Descript",
- headings: [
- "Table of Contents",
- "1. Required Secrets",
- "Generation Commands",
- "2. Storage & Database",
- "Scenarios",
- "3. Network & Ports",
- "Port Modes",
- "4. Security & Authentication",
- "Hardening Checklist",
- "5. Input Sanitization & PII Protection",
- ],
- },
- {
- slug: "proxy-guide",
- title: "OmniRoute Proxy Guide",
- fileName: "PROXY_GUIDE.md",
- section: "Operations",
- content:
- "Bypass geographic blocks, protect your identity, and route AI traffic through any proxy — with zero configuration complexity. OmniRoute includes a full-featured proxy management system that lets you route upstream AI provider traffic through HTTP, HTTPS, or SOCKS5 proxies. Whether you're in a blocke",
- headings: [
- "Table of Contents",
- "Why Use Proxies?",
- "Architecture Overview",
- "Key Components",
- "3-Level Proxy System",
- "How Resolution Works",
- "What Gets Proxied",
- "Proxy Registry (CRUD)",
- "Creating a Proxy",
- "Updating a Proxy",
- ],
- },
- {
- slug: "resilience-guide",
- title: "🛡️ Resilience Guide",
- fileName: "RESILIENCE_GUIDE.md",
- section: "Operations",
- content:
- "How OmniRoute keeps your AI coding workflow running when providers fail. OmniRoute implements a multi-layered resilience system that ensures zero downtime: ------------ ------- ------------------------------------ Queue Size 10 Max queued requests per connection Pacing Interval 0ms Minimum gap betwe",
- headings: [
- "Overview",
- "Request Queue & Pacing",
- "Connection Cooldown",
- "Circuit Breaker",
- "Wait For Cooldown",
- "Anti-Thundering Herd",
- "Combo Fallback Chains",
- "13 Routing Strategies",
- "TLS Fingerprint Spoofing",
- "Health Dashboard",
- ],
- },
- {
- slug: "troubleshooting",
- title: "Troubleshooting",
- fileName: "TROUBLESHOOTING.md",
- section: "Operations",
- content:
- "🌐 Languages: 🇺🇸 English 🇧🇷 Português (Brasil) 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇷🇺 Русский 🇨🇳 中文 (简体) 🇩🇪 Deutsch 🇮🇳 हिन्दी 🇹🇭 ไทย 🇺🇦 Українська 🇸🇦 العربية 🇯🇵 日本語 🇻🇳 Tiếng Việt 🇧🇬 Български 🇩🇰 Dansk 🇫🇮 Suomi 🇮🇱 עברית 🇭🇺 Magyar 🇮🇩 Bahasa Indonesia 🇰🇷 한국어 🇲\ud83c",
- headings: [
- "Quick Fixes",
- "Node.js Compatibility",
- 'Login page crashes or shows "Module self-registration" error',
- 'macOS: dlopen / "slice is not valid mach-o file"',
- "Proxy Issues",
- 'Provider validation shows "fetch failed"',
- 'Token health check fails with "fetch failed"',
- 'SOCKS5 proxy returns "invalid onRequestStart method"',
- "Provider Issues",
- '"Language model did not provide messages"',
- ],
- },
- {
- slug: "codebase-documentation",
- title: "omniroute — Codebase Documentation",
- fileName: "CODEBASE_DOCUMENTATION.md",
- section: "Development",
- content:
- "🌐 Languages: 🇺🇸 English 🇧🇷 Português (Brasil) 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇷🇺 Русский 🇨🇳 中文 (简体) 🇩🇪 Deutsch 🇮🇳 हिन्दी 🇹🇭 ไทย 🇺🇦 Українська 🇸🇦 العربية 🇯🇵 日本語 🇻🇳 Tiếng Việt 🇧🇬 Български 🇩🇰 Dansk 🇫🇮 Suomi 🇮🇱 עברית 🇭🇺 Magyar 🇮🇩 Bahasa Indonesia 🇰🇷 한국어 🇲\ud83c",
- headings: [
- "1. What Is omniroute?",
- "2. Architecture Overview",
- "Core Principle: Hub-and-Spoke Translation",
- "3. Project Structure",
- "4. Module-by-Module Breakdown",
- "4.1 Config (open-sse/config/)",
- "Credential Loading Flow",
- "4.2 Executors (open-sse/executors/)",
- "4.3 Handlers (open-sse/handlers/)",
- "Request Lifecycle (chatCore.ts)",
- ],
- },
- {
- slug: "coverage-plan",
- title: "Test Coverage Plan",
- fileName: "COVERAGE_PLAN.md",
- section: "Development",
- content:
- "Last updated: 2026-03-28 There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. Metric Scope Statements / Lines Branches Functions Notes -------------------- ----------------------------------------------------- -----------------: -----",
- headings: [
- "Baseline",
- "Rules",
- "Current command set",
- "Milestones",
- "Priority hotspots",
- "Execution checklist",
- "Phase 1: 56.95% -> 60%",
- "Phase 2: 60% -> 65%",
- "Phase 3: 65% -> 70%",
- "Phase 4: 70% -> 75%",
- ],
- },
- {
- slug: "i18n",
- title: "i18n — Internationalization Guide",
- fileName: "I18N.md",
- section: "Development",
- content:
- "OmniRoute supports 30 languages with full dashboard UI translation, translated documentation, and RTL support for Arabic and Hebrew. 🌐 Languages: 🇺🇸 English 🇧🇷 Português (Brasil) 🇪🇸 Español 🇫🇷 Français 🇩🇪 Deutsch 🇮🇹 Italiano 🇷🇺 Русский 🇨🇳 中文 (简体) 🇯🇵 日本語 🇰🇷 한국어 🇸🇦 العربية 🇮🇳 ",
- headings: [
- "Quick Reference",
- "Architecture",
- "Source of Truth",
- "Runtime Flow",
- "Supported Locales",
- "Adding a New Language",
- "1. Register the Locale",
- "2. Add to Generator",
- "3. Generate Initial Translation",
- "4. Review & Fix Auto-Translations",
- ],
- },
- {
- slug: "release-checklist",
- title: "Release Checklist",
- fileName: "RELEASE_CHECKLIST.md",
- section: "Development",
- content:
- "Use this checklist before tagging or publishing a new OmniRoute release. 1. Bump package.json version (x.y.z) in the release branch. 2. Move release notes from [Unreleased] in CHANGELOG.md to a dated section: - [x.y.z] — YYYY-MM-DD 3. Keep [Unreleased] as the first changelog section for upcoming wor",
- headings: ["Version and Changelog", "API Docs", "Runtime Docs", "Automated Check"],
- },
- {
- slug: "uninstall",
- title: "OmniRoute — Uninstall Guide",
- fileName: "UNINSTALL.md",
- section: "Development",
- content:
- "🌐 Languages: 🇺🇸 English 🇧🇷 Português (Brasil) 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇷🇺 Русский 🇨🇳 中文 (简体) 🇩🇪 Deutsch 🇮🇳 हिन्दी 🇹🇭 ไทย 🇺🇦 Українська 🇸🇦 العربية 🇯🇵 日本語 🇻🇳 Tiếng Việt 🇧🇬 Български 🇩🇰 Dansk 🇫🇮 Suomi 🇮🇱 עברית 🇭🇺 Magyar 🇮🇩 Bahasa Indonesia 🇰🇷 한국어 🇲\ud83c",
- headings: [
- "Quick Uninstall (v3.6.2+)",
- "Keep Your Data",
- "Full Removal",
- "Manual Uninstall",
- "NPM Global Install",
- "pnpm Global Install",
- "Docker",
- "Docker Compose",
- "Electron Desktop App",
- "Source Install (git clone)",
- ],
- },
- {
- slug: "rfc-auto-assessment",
- title: "RFC: Auto-Assessment & Self-Healing Combo Engine",
- fileName: "RFC-AUTO-ASSESSMENT.md",
- section: "Other",
- content:
- "Omniroute's combo system currently requires manual configuration: users must know which providers and models are actually working, then manually wire them into combo chains. When providers fail (rate limits, auth errors, model deprecation), combos silently degrade — routing to dead endpoints that ti",
- headings: [
- "Summary",
- "Problem Statement",
- "What we encountered (real production incident)",
- "Current flow (broken)",
- "Proposed flow (self-healing)",
- "Architecture",
- "New Components",
- "Detailed Design",
- "1. Assessor — src/domain/assessor.ts",
- "2. Categorizer — src/domain/categorizer.ts",
- ],
- },
{
slug: "api-explorer",
title: "API Explorer",
- fileName: "API_REFERENCE.md",
- section: "API & Protocols",
+ fileName: "reference/API_REFERENCE.md",
+ section: "Reference",
content: "interactive try it live api explorer endpoint test request response curl example",
headings: ["Try It", "Endpoints"],
},
@@ -799,33 +1163,47 @@ export const autoSearchIndex: AutoGenSearchItem[] = [
export const autoAllSlugs: string[] = [
"architecture",
- "cli-tools",
+ "authz-guide",
+ "codebase-documentation",
+ "repository-map",
+ "resilience-guide",
+ "docker-guide",
+ "electron-guide",
+ "features",
+ "i18n",
+ "pwa-guide",
"setup-guide",
+ "termux-guide",
+ "troubleshooting",
+ "uninstall",
"user-guide",
+ "api-reference",
+ "cli-tools",
+ "environment",
+ "free-tiers",
+ "provider-reference",
+ "a2a-server",
+ "agent-protocols-guide",
+ "cloud-agent",
+ "evals",
+ "mcp-server",
+ "memory",
+ "skills",
+ "webhooks",
"auto-combo",
+ "reasoning-replay",
+ "compliance",
+ "guardrails",
+ "stealth-guide",
"compression-engines",
"compression-guide",
"compression-language-packs",
"compression-rules-format",
- "features",
- "free-tiers",
"rtk-compression",
- "a2a-server",
- "api-reference",
- "mcp-server",
- "docker-guide",
- "fly-io-deployment-guide",
- "pwa-guide",
- "termux-guide",
- "vm-deployment-guide",
- "environment",
- "proxy-guide",
- "resilience-guide",
- "troubleshooting",
- "codebase-documentation",
"coverage-plan",
- "i18n",
+ "fly-io-deployment-guide",
+ "proxy-guide",
"release-checklist",
- "uninstall",
- "rfc-auto-assessment",
+ "tunnels-guide",
+ "vm-deployment-guide",
];
diff --git a/test-kiro.ts b/test-kiro.ts
deleted file mode 100644
index 943462dbd2..0000000000
--- a/test-kiro.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-import { buildKiroPayload } from "./open-sse/translator/request/openai-to-kiro.js";
-
-const messages = [];
-for (let i = 0; i < 2; i++) {
- messages.push({ role: "user", content: `user ${i}` });
- messages.push({ role: "assistant", content: `assistant ${i}` });
-}
-messages.push({ role: "user", content: "use tool" });
-messages.push({
- role: "assistant",
- tool_calls: [{ id: "call_1", function: { name: "test", arguments: "{}" } }],
-});
-messages.push({ role: "tool", tool_call_id: "call_1", content: "ok" });
-messages.push({ role: "user", content: "last user" });
-
-const payload = buildKiroPayload("kr/claude-sonnet-4.5", { messages, tools: [] }, false, {});
-console.log(JSON.stringify(payload, null, 2));
diff --git a/tests/integration/integration-wiring.test.ts b/tests/integration/integration-wiring.test.ts
index 8dfface716..9842e1c39d 100644
--- a/tests/integration/integration-wiring.test.ts
+++ b/tests/integration/integration-wiring.test.ts
@@ -294,8 +294,8 @@ describe("API Routes — dashboard and tool consumers", () => {
it("keeps legacy usage history and raw request-log APIs explicitly classified", () => {
const usageStats = readProjectFile("src/shared/components/UsageStats.tsx");
- const apiReference = readProjectFile("docs/API_REFERENCE.md");
- const openApi = readProjectFile("docs/openapi.yaml");
+ const apiReference = readProjectFile("docs/reference/API_REFERENCE.md");
+ const openApi = readProjectFile("docs/reference/openapi.yaml");
assert.ok(usageStats, "UsageStats compatibility component should exist");
assert.ok(apiReference, "API reference should exist");
@@ -343,7 +343,7 @@ describe("Dashboard Wiring — T05 payload rules", () => {
const payloadRulesTabSrc = readProjectFile(
"src/app/(dashboard)/dashboard/settings/components/PayloadRulesTab.tsx"
);
- const openapiSrc = readProjectFile("docs/openapi.yaml");
+ const openapiSrc = readProjectFile("docs/reference/openapi.yaml");
it("settings page should surface payload rules inside advanced settings", () => {
assert.ok(settingsPageSrc, "settings page source should exist");
@@ -361,7 +361,7 @@ describe("Dashboard Wiring — T05 payload rules", () => {
});
it("openapi should document the payload rules management surface", () => {
- assert.ok(openapiSrc, "docs/openapi.yaml should exist");
+ assert.ok(openapiSrc, "docs/reference/openapi.yaml should exist");
assert.match(openapiSrc, /\/api\/settings\/payload-rules:/);
assert.match(openapiSrc, /summary:\s+Get payload rules configuration/);
assert.match(openapiSrc, /ManagementSessionAuth:/);
diff --git a/tests/unit/docs-site-overhaul.test.ts b/tests/unit/docs-site-overhaul.test.ts
index 202422f4e0..e2f25d3e20 100644
--- a/tests/unit/docs-site-overhaul.test.ts
+++ b/tests/unit/docs-site-overhaul.test.ts
@@ -18,13 +18,14 @@ test("docsNavigation has expected sections", () => {
assert.deepEqual(
docsNavigation.map((section) => section.title),
[
- "Getting Started",
- "Features",
- "API & Protocols",
- "Deployment",
- "Operations",
- "Development",
- "Other",
+ "Architecture",
+ "Guides",
+ "Reference",
+ "Frameworks",
+ "Routing",
+ "Security",
+ "Compression",
+ "Ops",
]
);
});
@@ -55,7 +56,7 @@ test("getDocItemBySlug returns section title and item for known slug", () => {
const result = getDocItemBySlug("setup-guide");
assert.ok(result, "setup-guide should be found");
assert.equal(result.item.slug, "setup-guide");
- assert.equal(result.sectionTitle, "Getting Started");
+ assert.equal(result.sectionTitle, "Guides");
});
test("getDocItemBySlug returns null for unknown slug", () => {