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/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 c9a2f7988c..8133893e26 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/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", () => {