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