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 bf8bdf5d31..b9dc8d9f2e 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/` @@ -696,7 +696,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 @@ -714,11 +714,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. --- @@ -770,17 +770,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 +![Diagram name](./exported/diagram-name.svg) + +> [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 d5ad443a4a..a9909eeb22 100644 --- a/docs/ELECTRON_GUIDE.md +++ b/docs/guides/ELECTRON_GUIDE.md @@ -264,6 +264,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/prepare-electron-standalone.mjs`, `scripts/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 a38213546a..730fed2554 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 458e5df371..948755bec5 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/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 142d992f15..b2aade04f0 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