fix(build): exclude .claude/.worktrees from tsconfig scope to stop next build OOM (#5031)

Root cause of the local build:release OOM/GC-livelock (deploy blocker, 2026-06-25):
tsconfig.json uses include: ["**/*.ts","**/*.tsx","**/*.js","**/*.jsx"] (recursive
glob) but exclude did NOT list .claude — where git worktrees live (.claude/worktrees/).
With 69 active port-* worktrees, the TS scope was 355,215 files (352,261 of them inside
.claude/worktrees) vs 4,547 real source files. next build's type-check/scan processed ~70x
the codebase, OOMing at 4GB AND 16GB and GC-livelocking at 32GB/64GB. CI built fine because
its checkout is clean (no worktrees). After excluding .claude/.worktrees, build:release
completes in 17m with the DEFAULT 4GB heap.

Changes:
- tsconfig.json exclude: + .claude .worktrees .source coverage @omniroute .tmp dist _ideia;
  removed 6 stale entries for dirs that no longer exist.
- .dockerignore: + .claude .source (the _* glob already covered underscore dirs).
- CLAUDE.md: standardize ALL worktrees under .claude/worktrees/ (was split with .worktrees/),
  the single gitignored + build-excluded location the native EnterWorktree tool uses.

.agents/skills/capture-release-evidences/SKILL.md

@@ -1,52 +0,0 @@
----
-name: capture-release-evidences-cx
-description: Automatically run a browser-automation agent to visually validate all new UI features from the current release and capture evidence WebP recordings of the changes.
----
-
-# Capture Release Evidences Workflow
-
-Use this workflow to automatically drive a browser-automation agent to explore the newly deployed or locally running application and record evidence of the UI changes introduced in the latest release.
-
-> **Tool mapping note (v3.8):** The `browser_subagent` tool referenced below is specific to an earlier agent runtime. In Claude Code, substitute with the available browser MCP tools (e.g. `mcp__claude-in-chrome__*`) for navigation/screenshots, plus the `Write` tool for saving artifacts. The high-level steps remain the same regardless of the browser-automation surface in use.
-
-## Prerequisites
-
-- OmniRoute must be actively running and accessible (e.g. locally at `http://localhost:20128` or on the Local VPS at `http://192.168.0.15:20128`).
-- The user must provide the target URL to be tested, or default to `http://192.168.0.15:20128`.
-
-## Workflow Steps
-
-### 1. Identify Target Features
-
-Review the `CHANGELOG.md` for the latest version to map out the new UI elements. For example:
-
-- **CLI Tools Settings**
-- **New Provider/Model Listings (e.g., Gemini 3.1, Qoder PAT)**
-- **New Feature Modals**
-
-### 2. Run the Browser Subagent
-
-For each identified feature, invoke the `browser_subagent` using the `default_api:browser_subagent` tool.
-**Important Task Guidelines for the Subagent:**
-
-- `TaskName`: Give it a clear name like "Validate CLIProxyAPI Tool Tab".
-- `TaskSummary`: "Navigate to the CLI Tools tab and verify the new Integration settings."
-- `Task`: Provide unambiguous instructions for the subagent, such as: "Navigate to http://192.168.0.15:20128/dashboard. Click on the 'Settings' or 'CLI Tools' nav link. Scroll down to find the CLIProxyAPI integration card. Hover over it to trigger UI state. Verify the components render correctly and exit."
-- `RecordingName`: Ensure it describes the feature (e.g. `v3_4_5_cli_proxy_api`). This is required and strictly automatically saved as a WebP artifacts video by the system.
-
-_(Note: The `browser_subagent` automatically creates a WebP recording named by the `RecordingName` parameter. No additional tools for screenshots are needed.)_
-
-### 3. Generate Report Artifact
-
-After the `browser_subagent` finishes its sessions, generate a final Markdown artifact (using `Write` and `IsArtifact=true`) to present the recordings inline to the user using the `![caption](/absolute/path/to/media.webp)` syntax.
-
-### Example Invocation
-
-\```json
-{
-"TaskName": "Validating Qoder PAT Configuration UI",
-"TaskSummary": "Validates the Qoder provider configuration modal",
-"Task": "Go to http://192.168.0.15:20128/dashboard. Click on the 'Providers' tab. Find 'Qoder' in the list. Click 'Add Token' or 'Configure'. Type 'test_token' and submit. Return when done.",
-"RecordingName": "qoder_pat_ui_validation"
-}
-\```

.agents/skills/deploy-vps-local/SKILL.md

@@ -1,45 +0,0 @@
----
-name: deploy-vps-local-cx
-description: Deploy the latest OmniRoute code to the Local VPS (192.168.0.15)
----
-
-# Deploy to Local VPS Workflow
-
-Deploy OmniRoute to the Local VPS using `npm pack + scp` + PM2.
-
-## Codex Execution Notes
-
-- Treat `// turbo` / `// turbo-all` as instructions to use `multi_tool_use.parallel` only for independent commands. Do not parallelize dependent build, copy, install, restart, and verification steps.
-- Report each remote result explicitly before finishing.
-
-**Local VPS:** `192.168.0.15`
-**Process manager:** PM2 (`omniroute`)
-**Port:** `20128`
-
-## Steps
-
-### 1. Build + pack locally
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
-```
-
-### 2. Copy to Local VPS and install
-
-// turbo-all
-
-```bash
-scp omniroute-*.tgz root@192.168.0.15:/tmp/
-```
-
-```bash
-ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
-```
-
-### 3. Verify the deployment
-
-```bash
-curl -s -o /dev/null -w 'LOCAL HTTP %{http_code}\n' http://192.168.0.15:20128/
-```

.agents/skills/generate-release/SKILL.md

@@ -1,362 +0,0 @@
----
-name: generate-release-cx
-description: Create a new release, bump version up to the .10 patch threshold, update changelog, and manage Pull Requests
----
-
-# Generate Release Workflow
-
-Bump version, finalize CHANGELOG, commit, open a **PR to main** and wait for user confirmation before tagging, publishing, and deploying.
-
-## Codex Execution Notes
-
-- Treat `// turbo` / `// turbo-all` as instructions to use `multi_tool_use.parallel` for independent reads, checks, and GitHub calls.
-- When the workflow says `notify_user` or `BlockedOnUser: true`, present the report/status in the final response and stop. Do not continue into the next phase until the user explicitly approves.
-
-> **VERSION RULE: Always use PATCH bumps (3.x.y → 3.x.y+1)**
-> NEVER use `npm version minor` or `npm version major`.
-> Always use: `npm version patch --no-git-tag-version`
-> The threshold rule: when `y` reaches 10, bump to `3.(x+1).0` — e.g. `3.8.10` → `3.9.0`.
-
-> **🔴 SINGLE BRANCH RULE**: The `release/vX.Y.Z` branch is the **ONLY** development branch for the entire release cycle. ALL work — bug fixes, feature implementations, PR integrations, issue resolutions — MUST be committed directly on this branch. Never create separate `fix/`, `feat/`, or topic branches. When running `/resolve-issues`, `/implement-features`, or `/review-prs`, always work on the current release branch.
-
----
-
-## ⚠️ Two-Phase Flow
-
-```
-Phase 1 (automated): bump → docs → i18n → commit → push → open PR
-  ↕  🛑 STOP: Notify user, wait for PR confirmation
-Phase 2 (post-merge): tag → publish → GitHub release → Docker → deploy
-```
-
-**NEVER push directly to main or create tags before the user confirms the PR.**
-
----
-
-## Phase 0: Security Verification (MANDATORY)
-
-Before creating the release, you must ensure the codebase and supply chain are secure and free of known vulnerabilities.
-
-1. **Run Local Dependencies Audit:**
-
-   ```bash
-   npm audit
-   ```
-
-   _Fix any `high` or `critical` vulnerabilities identified._
-
-2. **Check GitHub CodeQL & Dependabot Alerts:**
-   Navigate to the repository's **Security** tab on GitHub, or use the project's `vulnerability-scanner` skill to analyze active alerts. Ensure all static analysis findings (e.g., prototype pollution, insecure randomness, ReDoS, shell injections) are addressed and logically committed on a target branch.
-
----
-
-## Phase 1: Pre-Merge
-
-### 1. Create release branch
-
-```bash
-git checkout -b release/v3.x.y
-```
-
-### 2. Determine and sync version
-
-Check current version in `package.json`:
-
-```bash
-grep '"version"' package.json
-```
-
-> **🔴 BRANCH-VERSION PARITY RULE**: The logical version in `package.json` MUST exactly match the release branch name. For example, if you are on `release/v3.7.0`, the version in `package.json` MUST be `3.7.0`.
->
-> - If this is the FIRST time generating a release for a new minor/major branch (e.g., bumping from 3.6.9 to 3.7.0), you MUST ensure the version is bumped to match the new branch logic.
-> - If you are just bumping a patch on the current branch (e.g., 3.6.9 to 3.6.10), use:
->   `npm version patch --no-git-tag-version`
-
-> **⚠️ ATOMIC COMMIT RULE — Version bump MUST happen before committing feature files.**
->
-> **CORRECT order:**
->
-> 1. `npm version patch --no-git-tag-version` ← bump first
-> 2. implement features / fix bugs
-> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
->
-> **OR if features are already staged:**
->
-> 1. implement features (do NOT commit yet)
-> 2. `npm version patch --no-git-tag-version` ← bump before committing
-> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
->
-> **NEVER do this (creates version mismatch in git history):**
->
-> - ~~commit features → then bump version → commit package.json separately~~
->
-> This ensures that `git show v3.x.y` always contains both code changes and the version bump together.
-> The GitHub release tag will point to a commit that includes ALL changes for that version.
-
-### 3. Regenerate lock file (REQUIRED after version bump)
-
-**Mandatory** — skipping causes `@swc/helpers` lock mismatch and CI failures:
-
-```bash
-npm install
-```
-
-### 4. Finalize CHANGELOG.md
-
-> **🔴 NO MIXUPS RULE**: Ensure you do NOT mix the backlog of the previous version with the new one. The new version section must ONLY contain the features and fixes for the current release.
-
-Replace the `[Unreleased]` header with the new version and date.
-Keep an empty `## [Unreleased]` section above it, separated by a horizontal rule (`---`).
-
-```markdown
-## [Unreleased]
-
----
-
-## [3.7.0] — 2026-04-19
-
-### ✨ New Features
-
-- ...
-
-### 🐛 Bug Fixes
-
-- ...
-
-### 🏆 Hall de Contribuidores
-
-Um agradecimento especial a todos que contribuíram com código, revisões e testes para este release:
-@user1, @user2
-
----
-
-## [3.6.9] — 2026-04-19
-```
-
-> **🔴 HALL DE CONTRIBUIDORES RULE**: You MUST parse all the PR author mentions (e.g., `(thanks @username)`) from the new version's changelog items, deduplicate them, and append them as a "Hall de Contribuidores" section at the end of the new release block, exactly as shown above.
-
-### 5. Update openapi.yaml version ⚠️ MANDATORY
-
-> **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/reference/openapi.yaml
-echo "✓ openapi.yaml → $VERSION"
-
-for dir in electron open-sse; do
-  if [ -d "$dir" ] && [ -f "$dir/package.json" ]; then
-    (cd "$dir" && npm version "$VERSION" --no-git-tag-version --allow-same-version > /dev/null)
-    echo "✓ $dir/package.json → $VERSION"
-  fi
-done
-# Re-run install to assert the workspace lockfile is updated
-npm install
-```
-
-### 6. Update README.md and i18n docs
-
-Manually perform these documentation updates (there is no `/update-docs` workflow — it was deprecated in v3.8):
-
-- 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/<AREA>.md` if architecture or counts changed
-- Re-run `npm run check:docs-sync` and `npm run check:docs-all` to catch drift
-
-### 7. Run tests
-
-// turbo
-
-```bash
-npm test
-```
-
-All tests must pass before creating the PR.
-
-### 8. Stage, commit, and push
-
-// turbo-all
-
-```bash
-git add -A
-git commit -m "chore(release): v3.x.y — summary of changes"
-git push origin release/v3.x.y
-```
-
-### 9. Open PR to main
-
-### 9. Open PR to main
-
-// turbo
-
-```bash
-VERSION=$(node -p "require('./package.json').version")
-
-# Extract the exact changelog entry for this version from the root CHANGELOG.md
-awk "/^## \\[$VERSION\\]/{flag=1; print; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md > /tmp/changelog_body.txt
-
-# Append test status and next steps
-echo "" >> /tmp/changelog_body.txt
-echo "### Tests" >> /tmp/changelog_body.txt
-echo "- All tests pass" >> /tmp/changelog_body.txt
-echo "" >> /tmp/changelog_body.txt
-echo "### ⚠️ After merging: run Phase 2 steps to tag, publish, and deploy." >> /tmp/changelog_body.txt
-
-gh pr create \
-  --repo diegosouzapw/OmniRoute \
-  --base main \
-  --head release/v$VERSION \
-  --title "Release v$VERSION" \
-  --body-file /tmp/changelog_body.txt
-```
-
-### 10. 🛑 STOP — Notify User & Await PR Confirmation
-
-**This is a mandatory stop point.** Present the report in the final response and stop. Do not continue to the next phase until the user explicitly approves.
-
-Inform the user:
-
-- PR URL
-- Summary of changes
-- Test results
-- List of files changed
-
-**DO NOT proceed to Phase 2 until the user confirms the PR looks good and merges it.**
-
----
-
-## Phase 2: Post-Merge Validation (Local VPS)
-
-> Run these steps only AFTER the user has merged the PR into `main` and all CI jobs have passed.
-
-### 11. Deploy to Local VPS for Final Validation (MANDATORY)
-
-Before cutting the official git tag and publishing to the world, deploy the `main` branch to the Local VPS for a final homologation test.
-
-```bash
-git checkout main
-git pull origin main
-
-# Build and pack locally
-cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
-
-# Deploy to LOCAL VPS (192.168.0.15)
-scp omniroute-*.tgz root@192.168.0.15:/tmp/
-ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
-
-# Verify
-curl -s -o /dev/null -w "LOCAL:  HTTP %{http_code}\n" http://192.168.0.15:20128/
-```
-
-### 12. 🛑 STOP — Notify User & Await Final OK
-
-**This is a mandatory stop point.**
-Inform the user that the `main` branch is now running on the Local VPS.
-Wait for the user to manually test and give the **OK**.
-**DO NOT proceed to Phase 3 until the user confirms the local deploy is stable.**
-
----
-
-## Phase 3: Official Launch
-
-> Run these steps only AFTER the user gives the final OK from the Phase 2 local validation.
-
-### 13. Create Git Tag and GitHub Release (MANDATORY)
-
-// turbo
-
-```bash
-git checkout main
-git pull origin main
-VERSION=$(node -p "require('./package.json').version")
-
-# Extracts the changelog section for this version
-NOTES=$(awk "/^## \\[$VERSION\\]/{flag=1; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
-if [ -z "$NOTES" ]; then NOTES="OmniRoute v$VERSION Release"; fi
-
-git tag -a "v$VERSION" -m "Release v$VERSION"
-git push origin "v$VERSION"
-gh release create "v$VERSION" --repo diegosouzapw/OmniRoute --title "v$VERSION" --notes "$NOTES" --target main || gh release edit "v$VERSION" --repo diegosouzapw/OmniRoute --title "v$VERSION" --notes "$NOTES"
-```
-
-### 14. 🐳 Trigger Docker Hub build (MANDATORY — keep npm and Docker in sync)
-
-> **CRITICAL**: Docker Hub and npm MUST always publish the same version.
-> The Docker image is built automatically via GitHub Actions when a new tag is pushed.
-> After pushing the tag in step 13, **verify the workflow runs**:
-
-```bash
-# Verify the Docker workflow triggered
-gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 3
-
-# Wait for the Docker build to complete (usually 5–10 min)
-gh run watch --repo diegosouzapw/OmniRoute
-```
-
-### 15. Publish to NPM (Optional/Automated)
-
-Normally handled by CI, but if manual publish is required:
-
-```bash
-npm publish
-```
-
-## Phase 4: Release Monitoring & Artifact Validation
-
-> After triggering the official release, actively monitor the CI pipelines until all artifacts are successfully generated. If any pipeline fails, stop and apply the necessary corrections before continuing.
-
-### 16. Monitor CI Pipelines
-
-Wait for and verify the successful completion of the following automated jobs:
-
-1. **Docker Hub Publish**
-2. **Electron Build**
-3. **NPM Registry Publish** (Check with `npm info omniroute version`)
-
-```bash
-# Monitor Docker Hub workflow
-gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 1
-gh run watch <RUN_ID>
-
-# Monitor Electron build
-gh run list --repo diegosouzapw/OmniRoute --workflow electron-release.yml --limit 1
-gh run watch <RUN_ID>
-
-# Verify NPM version
-npm info omniroute version
-```
-
-### 17. Handle Failures (If Any)
-
-If a workflow fails:
-
-- Use `gh run view <RUN_ID> --log-failed` to identify the error.
-- Apply the fix on the `main` branch.
-- If necessary, re-trigger the workflow using `gh workflow run <workflow_name.yml> --repo diegosouzapw/OmniRoute --ref v3.x.y`
-
-### 18. Preserve release branch
-
-```bash
-# Branch is kept for historical purposes. Do not delete.
-```
-
----
-
-## Notes
-
-- Ensure CHANGELOG, README and `docs/*` are current BEFORE this workflow — run `npm run check:docs-all` and `/version-bump` first (there is no `/update-docs` workflow anymore)
-- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`
-- After npm publish, verify with `npm info omniroute version`
-- Lock file sync errors are caused by skipping `npm install` after version bump
-- Use `gh auth switch -u diegosouzapw` if git push fails with wrong account
-
-## Known CI Pitfalls
-
-| 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              |

.agents/skills/implement-features/SKILL.md

@@ -1,713 +0,0 @@
----
-name: implement-features-cx
-description: Analyze open feature request issues, implement viable ones on dedicated branches, and respond to authors
----
-
-# /implement-features — Feature Request Harvest, Research & Implementation Workflow
-
-## Overview
-
-A **5-phase** workflow that systematically harvests feature requests from GitHub issues, creates structured idea files, researches solutions across the internet and Git repositories, presents a consolidated report for user approval, then generates detailed implementation plans and executes them.
-
-## Codex Execution Notes
-
-- Treat `// turbo` / `// turbo-all` as instructions to use `multi_tool_use.parallel` for independent reads, checks, and GitHub calls.
-- Approval gates are hard stops. Present the report/plan in the final response and do not move to implementation phases until the user explicitly approves.
-- Keep harvest/research bounded enough to produce the approval report quickly; do not start implementation while still in report phases.
-
-**Output directory structure:**
-
-```
-_ideia/
-├── viable/                  # Features approved for implementation
-│   ├── need_details/        # ❓ Good idea but waiting for author clarification (issues stay OPEN)
-│   │   └── 1015-warp-terminal-mitm.md
-│   ├── 1046-native-playground.md           # ✅ Ready — researched and planned
-│   └── 1046-native-playground.requirements.md
-├── defer/                   # ⏭️ Good ideas deferred for future cycles (issues CLOSED)
-│   └── 1041-smart-auto-combos.md
-└── notfit/                  # ❌ Out of scope / already exists (issues CLOSED)
-    └── 945-telegram-integration.md
-
-_tasks/features-vX.Y.Z/   # Implementation plans (per-release)
-└── 1046-native-playground.plan.md
-```
-
-> **LIFECYCLE RULE:** `viable/` files are **DELETED** once the feature is implemented — they are not moved. Only unimplemented features live in `viable/` (or `viable/need_details/`). Files in `defer/` and `notfit/` remain as permanent reference.
-
-> **BRANCH RULE**: All implementation work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `feat/` branches. If no release branch exists yet, create one first using `/generate-release` Phase 1 steps 1–5.
-
----
-
-## Phase 1 — Harvest: Collect & Catalog Feature Ideas
-
-### 1.1 Identify the Repository
-
-// turbo
-
-- Run: `git -C <project_root> remote get-url origin` to extract owner/repo.
-
-### 1.2 Ensure Release Branch Exists
-
-// turbo
-
-Before doing any work, ensure you are on the current release branch:
-
-```bash
-# Check current branch
-git branch --show-current
-
-# If on main, determine next version and create the release branch
-VERSION=$(node -p "require('./package.json').version")
-NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
-git checkout -b release/v$NEXT
-npm version patch --no-git-tag-version
-npm install
-```
-
-If already on a `release/vX.Y.Z` branch, continue working there.
-
-### 1.3 Fetch ALL Open Feature Requests
-
-// turbo-all
-
-**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. You MUST use the two-step approach below.
-
-**Step 1 — Get Issue numbers only** (small output, never truncated):
-
-```bash
-# Fetch issues with feature/enhancement labels
-gh issue list --repo <owner>/<repo> --state open -l "enhancement" --limit 500 --json number --jq '.[].number'
-
-# Also check for [Feature] in title (common pattern when no labels are set)
-gh issue list --repo <owner>/<repo> --state open --limit 500 --json number,title --jq '.[] | select(.title | test("\\[Feature\\]|\\[feature\\]|feature request"; "i")) | .number'
-```
-
-- Merge both lists, deduplicate. Count and confirm the total.
-
-**Step 2 — Fetch full metadata for each Issue** (one call per issue):
-
-```bash
-gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author,assignees
-```
-
-- Read the **entire body** — including description, use cases, screenshots, mockups, and any embedded images.
-- Read **ALL comments** — community discussion, agreements, restrictions, owner responses, and linked PRs.
-- **Images**: If the body or comments contain image URLs (`![...](...)` or `https://...png/jpg/gif`), note them — they may contain UI mockups, wireframes, or architecture diagrams that are essential to understanding the request.
-- You may batch these into parallel calls (up to 4 at a time).
-- Sort by oldest first (FIFO).
-
-### 1.4 Create Idea Files (initially in `_ideia/` root)
-
-For each feature request, create a structured idea file in `<project_root>/_ideia/`:
-
-**Filename convention**: `<NUMBER>-<kebab-case-short-title>.md`
-Example: `1046-native-playground.md`, `1041-smart-auto-combos.md`
-
-#### 1.4a — If the idea file does NOT exist yet, create it:
-
-```markdown
-# Feature: <Title from Issue>
-
-> GitHub Issue: #<NUMBER> — opened by @<author> on <date>
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-<Paste the FULL issue body here, preserving all formatting, images, and code blocks>
-
-## 💬 Community Discussion
-
-<Summarize ALL comments chronologically, noting who said what and any decisions or objections raised>
-
-### Participants
-
-- @<author> — Original requester
-- @<commenter1> — <brief role/opinion>
-- ...
-
-### Key Points
-
-- <bullet list of the most important discussion points>
-- <agreements reached>
-- <objections raised>
-
-## 🎯 Refined Feature Description
-
-<YOUR interpretation and enrichment of the feature request. Expand on what was asked, fill in logical gaps, provide concrete examples of how it would work. This section should be MORE detailed and clearer than the original request.>
-
-### What it solves
-
-- <problem 1>
-- <problem 2>
-
-### How it should work (high level)
-
-1. <step 1>
-2. <step 2>
-3. ...
-
-### Affected areas
-
-- <list of codebase areas, modules, files likely affected>
-
-## 📎 Attachments & References
-
-- <any image URLs, mockup links, or external references from the issue>
-
-## 🔗 Related Ideas
-
-- <links to related \_ideia/ files if any overlap found>
-```
-
-#### 1.4b — If the idea file ALREADY exists, update it:
-
-- Append new comments from the issue to the **Community Discussion** section.
-- Update the **Refined Feature Description** if new information changes the understanding.
-- Add any new **Related Ideas** cross-references found.
-- **Do NOT overwrite** existing content — append and enrich it.
-
-### 1.5 Cross-Reference & Deduplication
-
-After processing all issues:
-
-- Scan all `_ideia/*.md` files for overlapping features.
-- If two features are substantially the same, add `🔗 Related Ideas` cross-references to both.
-- If one is a strict subset of another, note it in the smaller file: `> ℹ️ This feature is a subset of #<OTHER_NUMBER>. Consider implementing together.`
-
----
-
-## Phase 2 — Research: Find Solutions & Build Requirements
-
-For each cataloged idea that is **viable** (aligns with the project's goals):
-
-### 2.1 Viability Pre-Check
-
-Before investing in research, quickly assess:
-
-- [ ] Does this feature align with the project's goals and architecture?
-- [ ] Is it technically feasible with the current codebase?
-- [ ] Does it duplicate existing functionality?
-- [ ] Would it introduce breaking changes or security risks?
-- [ ] Is there enough detail to understand what's needed?
-
-**Verdict options:**
-
-| Verdict               | When                                  | Action                      |
-| --------------------- | ------------------------------------- | --------------------------- |
-| ✅ **VIABLE**         | Good idea, enough context             | Proceed to Research         |
-| ❓ **NEEDS DETAIL**   | Good idea, insufficient spec          | Skip research, ask author   |
-| ⏭️ **DEFER**          | Good idea, too complex for this cycle | Catalog only, skip research |
-| ❌ **NOT FIT**        | Doesn't fit the project               | Explain why                 |
-| 🔁 **ALREADY EXISTS** | Feature already implemented           | Point to existing feature   |
-
-### 2.2 Internet Research (for VIABLE features)
-
-For each viable feature, perform systematic research:
-
-**Step 1 — Web search for similar implementations:**
-
-```
-WebSearch("how to implement <feature description> in <tech stack>")
-WebSearch("<feature keyword> implementation nextjs typescript 2025 2026")
-WebSearch("<feature keyword> open source library npm")
-```
-
-**Step 2 — Find reference Git repositories:**
-
-```
-WebSearch("site:github.com <feature keyword> <tech stack> stars:>100")
-WebSearch("github <feature keyword> implementation recently updated 2026")
-```
-
-- Find **up to 10 relevant repositories**, sorted by most recently updated.
-- For each repository:
-  - Note the repo URL, star count, last commit date
-  - Read its README and relevant source files via `WebFetch`
-  - Extract the architectural approach, patterns used, and key code snippets
-
-**Step 3 — Read API docs and standards:**
-
-If the feature involves an external API, protocol, or standard:
-
-- Find and read the official documentation
-- Note version requirements, authentication patterns, rate limits
-
-### 2.3 Create Requirements File
-
-For each researched feature, create a requirements file alongside its idea file:
-
-**Filename**: `<NUMBER>-<kebab-case-short-title>.requirements.md`
-
-```markdown
-# Requirements: <Feature Title>
-
-> Feature Idea: [#<NUMBER>](./<NUMBER>-<kebab-case-short-title>.md)
-> Research Date: <YYYY-MM-DD>
-> Verdict: ✅ VIABLE
-
-## 🔍 Research Summary
-
-<Brief summary of what was found during research>
-
-## 📚 Reference Implementations
-
-| #   | Repository       | Stars | Last Updated | Approach | Relevance    |
-| --- | ---------------- | ----- | ------------ | -------- | ------------ |
-| 1   | [repo/name](url) | ⭐ N  | YYYY-MM-DD   | <brief>  | High/Med/Low |
-| 2   | ...              |       |              |          |              |
-
-### Key Patterns Found
-
-- <pattern 1 with code snippet or link>
-- <pattern 2>
-
-## 📐 Proposed Solution Architecture
-
-### Approach
-
-<Describe the chosen approach based on research findings>
-
-### New Files
-
-| File                  | Purpose       |
-| --------------------- | ------------- |
-| `path/to/new/file.ts` | <description> |
-
-### Modified Files
-
-| File                       | Changes        |
-| -------------------------- | -------------- |
-| `path/to/existing/file.ts` | <what changes> |
-
-### Database Changes
-
-- <migrations needed, if any>
-
-### API Changes
-
-- <new/modified endpoints, if any>
-
-### UI Changes
-
-- <new/modified pages/components, if any>
-
-## ⚙️ Implementation Effort
-
-- **Estimated complexity**: Low / Medium / High / Very High
-- **Estimated files changed**: ~N
-- **Dependencies needed**: <new npm packages, if any>
-- **Breaking changes**: Yes/No — <details>
-- **i18n impact**: <number of new translation keys>
-- **Test coverage needed**: <brief description>
-
-## ⚠️ Open Questions
-
-- <question 1>
-- <question 2>
-
-## 🔗 External References
-
-- <documentation URLs>
-- <API references>
-```
-
----
-
-## Phase 2.5 — Organize & Respond: Sort Files and Post GitHub Comments
-
-### 2.5.1 Create Directory Structure
-
-// turbo
-
-```bash
-mkdir -p <project_root>/_ideia/viable
-mkdir -p <project_root>/_ideia/viable/need_details
-mkdir -p <project_root>/_ideia/defer
-mkdir -p <project_root>/_ideia/notfit
-```
-
-### 2.5.2 Move Idea Files to Category Subdirectories
-
-After classification, move EVERY idea file to its correct subdirectory:
-
-```bash
-# ✅ VIABLE — move idea + requirements files
-mv _ideia/<NUMBER>-*.md _ideia/viable/
-mv _ideia/<NUMBER>-*.requirements.md _ideia/viable/
-
-# ❓ NEEDS DETAIL — viable but waiting for author response
-mv _ideia/<NUMBER>-*.md _ideia/viable/need_details/
-
-# ⏭️ DEFER — move idea files only
-mv _ideia/<NUMBER>-*.md _ideia/defer/
-
-# ❌ NOT FIT & 🔁 ALREADY EXISTS — move idea files only
-mv _ideia/<NUMBER>-*.md _ideia/notfit/
-```
-
-No files should remain in `_ideia/` root after this step (except subdirectories).
-
-### 2.5.3 Post GitHub Comments by Category
-
-**Each category has a specific comment template and action:**
-
----
-
-#### For 🔁 ALREADY EXISTS — Comment + CLOSE issue
-
-// turbo
-
-The feature already exists in the system. Explain WHERE it is and HOW to use it.
-
-```markdown
-Hi @<author>! Thanks for the suggestion! 🙏
-
-Great news — this functionality **already exists** in OmniRoute:
-
-**📍 Where to find it:** <exact dashboard path or settings location>
-
-**🔧 How to use it:**
-
-1. <step 1>
-2. <step 2>
-3. <step 3>
-
-If you have any trouble finding or using it, feel free to ask in a Discussion. We're always happy to help!
-
-Closing this as the feature is already available. 🎉
-```
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
-```
-
----
-
-#### For ⏭️ DEFER — Comment + CLOSE issue
-
-// turbo
-
-Thank the user, explain the idea was cataloged, and that we'll study it before implementing.
-
-```markdown
-Hi @<author>! Thanks for this thoughtful feature request! 🙏
-
-We really appreciate the detailed proposal. We've **cataloged your idea** and it's now part of our improvement backlog.
-
-Due to the **significant architectural impact** of this feature, we'll need to conduct thorough use-case studies and architectural analysis before we start development. This ensures we build it right and don't introduce regressions.
-
-**What happens next:**
-
-- Your idea is saved in our internal feature backlog
-- We'll conduct architecture studies when this area is prioritized
-- We'll notify you here when development begins
-
-Thank you for contributing to OmniRoute's roadmap! Your input helps shape the product. 🚀
-```
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
-```
-
----
-
-#### For ❌ NOT FIT — Comment + CLOSE issue
-
-// turbo
-
-Politely explain why the feature doesn't fit the project scope.
-
-```markdown
-Hi @<author>! Thanks for the suggestion! 🙏
-
-After careful analysis, we've determined that this feature **falls outside OmniRoute's core scope** as a proxy/router.
-
-**Reason:** <explain why — e.g., "Telegram integration belongs in the application/orchestrator layer that consumes OmniRoute's API, not inside the router itself.">
-
-**Alternative:** <suggest an alternative approach if possible>
-
-We appreciate you thinking of ways to improve OmniRoute! If you'd like to discuss this further, feel free to open a Discussion. 🙏
-```
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
-```
-
----
-
-#### For ❓ NEEDS DETAIL — Comment (keep OPEN)
-
-// turbo
-
-Ask for the specific missing details needed.
-
-```markdown
-Hi @<author>! Thanks for the feature request — it's an interesting idea and we'd love to explore it further. 🙏
-
-To move forward, we need a few more details:
-
-1. <specific question 1>
-2. <specific question 2>
-3. <specific question 3>
-
-If you know of any **open-source projects or repositories** that implement something similar, please share links — it would help us design the best solution.
-
-Looking forward to your response! 🚀
-```
-
----
-
-#### For ✅ VIABLE — Comment (keep OPEN)
-
-// turbo
-
-Thank the user, confirm we've cataloged their idea, and explain it may be implemented in future versions.
-
-```markdown
-Hi @<author>! Thanks for the great feature suggestion! 🙏
-
-We've analyzed your request and it aligns well with OmniRoute's roadmap. We've **cataloged this feature** and it's in our implementation backlog.
-
-**Status:** 📋 Cataloged for future implementation
-
-This feature may be included in upcoming releases. We'll **respond to this issue and tag you** as soon as implementation begins so you can test it.
-
-Thank you for helping improve OmniRoute! 🚀
-```
-
-**⚠️ Do NOT close viable issues — they remain OPEN for tracking.**
-
----
-
-## Phase 3 — Report: Present Findings to User
-
-### 3.1 🛑 MANDATORY STOP — Present Consolidated Report
-
-After completing Phase 1, Phase 2, and Phase 2.5, **STOP and present the following report** in the chat. Do NOT proceed to implementation.
-
-Present a structured report containing:
-
-#### 3.1a — Feature Summary Table
-
-| #   | Issue | Title | Verdict         | Location                      | Action                        |
-| --- | ----- | ----- | --------------- | ----------------------------- | ----------------------------- |
-| 1   | #N    | Title | ✅ VIABLE       | `_ideia/viable/`              | Issue OPEN, comment posted    |
-| 2   | #N    | Title | ⏭️ DEFER        | `_ideia/defer/`               | Issue CLOSED with explanation |
-| 3   | #N    | Title | ❌ NOT FIT      | `_ideia/notfit/`              | Issue CLOSED with explanation |
-| 4   | #N    | Title | 🔁 EXISTS       | `_ideia/notfit/`              | Issue CLOSED with guidance    |
-| 5   | #N    | Title | ❓ NEEDS DETAIL | `_ideia/viable/need_details/` | Issue OPEN, questions posted  |
-
-#### 3.1b — Viable Features Detail
-
-For each VIABLE feature, provide a brief paragraph:
-
-- What was found during research
-- The proposed approach
-- Key risks or unknowns
-- Which reference repositories were most useful
-
-#### 3.1c — Issues Requiring Author Feedback
-
-For features marked ❓ NEEDS DETAIL, list:
-
-- What specific information is missing
-- What examples or repository references would help
-
-#### 3.1d — Ask for User Confirmation
-
-End the report with:
-
-> **Ready to proceed with implementation?**
->
-> - Reply **"sim"** or **"yes"** to generate full implementation plans for all VIABLE features.
-> - Reply with specific issue numbers to select only certain features.
-> - Reply **"não"** or **"no"** to stop here.
-
----
-
-## Phase 4 — Plan: Generate Implementation Plans (after user says "yes")
-
-> **⚠️ Do NOT enter this phase without explicit user approval from Phase 3.**
-
-### 4.1 Create Task Directory
-
-```bash
-mkdir -p <project_root>/_tasks/features-vX.Y.Z/
-```
-
-### 4.2 Generate One Implementation Plan Per Feature
-
-For each VIABLE feature approved by the user, create:
-
-**Filename**: `_tasks/features-vX.Y.Z/<NUMBER>-<kebab-case-title>.plan.md`
-
-```markdown
-# Implementation Plan: <Feature Title>
-
-> Issue: #<NUMBER>
-> Idea: [\_ideia/viable/<NUMBER>-title.md](../../_ideia/viable/<NUMBER>-title.md)
-> Requirements: [\_ideia/viable/<NUMBER>-title.requirements.md](../../_ideia/viable/<NUMBER>-title.requirements.md)
-> Branch: `release/vX.Y.Z`
-
-## Overview
-
-<Brief description of what will be built>
-
-## Pre-Implementation Checklist
-
-- [ ] Read all related source files listed below
-- [ ] Confirm no conflicts with in-flight PRs
-- [ ] Verify database migration numbering
-
-## Implementation Steps
-
-### Step 1: <Title>
-
-**Files:**
-
-- `path/to/file.ts` — <what to change>
-
-**Details:**
-<Detailed description of the change, including code patterns to follow, function signatures, etc.>
-
-### Step 2: <Title>
-
-...
-
-### Step N: Tests
-
-**New test files:**
-
-- `tests/unit/<test-file>.test.mjs` — <what to test>
-
-**Test cases:**
-
-- [ ] <test case 1>
-- [ ] <test case 2>
-
-### Step N+1: i18n
-
-**Translation keys to add:**
-
-- `<namespace>.<key>` — "<English value>"
-
-### Step N+2: Documentation
-
-- [ ] Update CHANGELOG.md
-- [ ] Update relevant docs/ files
-
-## Verification Plan
-
-1. Run `npm run build` — must pass
-2. Run `npm test` — all tests must pass
-3. Run `npm run lint` — no new errors
-4. <Manual verification steps>
-
-## Commit Plan
-```
-
-feat: <description> (#<NUMBER>)
-
-```
-
-```
-
-### 4.3 Present Plans for Final Approval
-
-Present a summary of all generated plans:
-
-> **Implementation plans generated:**
->
-> | #   | Feature | Plan File                                | Steps   | Effort |
-> | --- | ------- | ---------------------------------------- | ------- | ------ |
-> | 1   | <title> | `_tasks/features-vX.Y.Z/N-title.plan.md` | N steps | Medium |
->
-> Reply **"sim"** or **"yes"** to begin implementation of all features.
-> Reply with specific issue numbers to implement only certain ones.
-
----
-
-## Phase 5 — Execute: Implement the Plans (after user says "yes")
-
-> **⚠️ Do NOT enter this phase without explicit user approval from Phase 4.**
-
-### 5.1 Implement Each Feature
-
-For each approved plan, execute it step by step:
-
-1. **Follow the plan** — implement exactly as specified in the `.plan.md` file
-2. **Build** — Run `npm run build` after each feature to verify compilation
-3. **Test** — Run `npm test` to ensure no regressions
-4. **Commit** — Commit with: `feat: <description> (#<NUMBER>)`
-5. **Update the plan** — Mark completed steps with `[x]` in the plan file
-6. **Continue** — Move to the next feature (do NOT switch branches)
-
-### 5.2 Respond to Authors (Update Viable Issues)
-
-For each implemented feature, **close the issue with a final comment**:
-
-````markdown
-✅ **Implemented in `release/vX.Y.Z`!**
-
-Hi @<author>! Great news — your feature request has been implemented! 🎉
-
-**What was done:**
-
-- <bullet list of what was built>
-
-**How to try it:**
-
-```bash
-git fetch origin && git checkout release/vX.Y.Z
-npm install && npm run dev
-```
-````
-
-This will be included in the upcoming **vX.Y.Z** release. Feel free to reopen if you spot any issues! 🚀
-
-````
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
-````
-
-Then **DELETE the idea file** — it has served its purpose:
-
-```bash
-# ✅ Implemented files are DELETED (not moved)
-rm _ideia/viable/<NUMBER>-<title>.md
-rm _ideia/viable/<NUMBER>-<title>.requirements.md  # if exists
-```
-
-> **Why delete?** `viable/` only holds features that still NEED to be done. Once implemented, the commit history and CHANGELOG are the source of truth. Keeping the file would be confusing.
-
-### 5.3 Finalize & Push
-
-After implementing all approved features:
-
-1. **Update CHANGELOG.md** on the release branch with all new feature entries
-2. Push the release branch: `git push origin release/vX.Y.Z`
-3. Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)
-
-### 5.4 Final Summary Report
-
-Present a final summary report to the user:
-
-| Issue | Title | Verdict         | Action                                             | Commit    |
-| ----- | ----- | --------------- | -------------------------------------------------- | --------- |
-| #N    | Title | ✅ Implemented  | Issue closed, idea file deleted                    | `abc1234` |
-| #N    | Title | ⏭️ Deferred     | Issue closed + saved in `_ideia/defer/`            | —         |
-| #N    | Title | ❌ Not Fit      | Issue closed + saved in `_ideia/notfit/`           | —         |
-| #N    | Title | 🔁 Exists       | Issue closed + saved in `_ideia/notfit/`           | —         |
-| #N    | Title | ❓ Needs Detail | Issue OPEN, moved to `_ideia/viable/need_details/` | —         |
-
-Include:
-
-- Total features harvested
-- Total ideas cataloged (`viable/need_details/` + `defer/` + `notfit/`)
-- Total features implemented (idea files deleted, issues closed)
-- Total features deferred
-- Total issues closed
-- Total issues left open (needs detail only — viable are closed after implementation)
-- Test results (pass/fail count)

.agents/skills/issue-triage/SKILL.md

@@ -1,51 +0,0 @@
----
-name: issue-triage-cx
-description: How to respond to GitHub issues with insufficient information
----
-
-# Issue Triage Workflow
-
-Respond to GitHub issues that need more information before they can be investigated.
-
-## Steps
-
-### 1. Identify issues needing triage
-
-```bash
-gh issue list --state open --limit 20
-```
-
-### 2. Evaluate each issue
-
-Check if the issue has:
-
-- Clear reproduction steps
-- Environment details (OS, Node.js version, OmniRoute version)
-- Error logs/screenshots
-- Expected vs actual behavior
-
-### 3. Respond with triage template
-
-For issues missing information:
-
-```markdown
-Thank you for reporting this issue! To help us investigate, please provide:
-
-1. **OmniRoute version**: (`omniroute --version`)
-2. **Node.js version**: (`node --version`)
-3. **Operating system**: (e.g., Ubuntu 24.04, macOS 15, Windows 11)
-4. **Installation method**: (npm, Docker, source)
-5. **Steps to reproduce**: (exact commands/actions that trigger the issue)
-6. **Error logs**: (paste relevant logs from the console)
-7. **Expected behavior**: (what should happen)
-
-This will help us debug and resolve your issue faster. 🙏
-```
-
-### 4. Label the issue
-
-Add appropriate labels: `needs-info`, `bug`, `enhancement`, `question`, etc.
-
-```bash
-gh issue edit <NUMBER> --add-label "needs-info"
-```

.agents/skills/resolve-issues/SKILL.md

@@ -1,173 +0,0 @@
----
-name: resolve-issues-cx
-description: Fetch all open GitHub issues, analyze bugs, resolve what's possible, triage the rest, wait for user validation, then commit and release
----
-
-# /resolve-issues — Automated Issue Resolution Workflow
-
-## Overview
-
-This workflow fetches all open issues from the project's GitHub repository, classifies them, analyzes bugs, proposes a resolution plan, waits for user validation, and ONLY THEN implements the fixes, commits, and closes the issues on the current release branch (`release/vX.Y.Z`). It does NOT merge or release automatically — the release branch is later merged via PR to main.
-
-## Codex Execution Notes
-
-- Treat `// turbo` / `// turbo-all` as instructions to use `multi_tool_use.parallel` for independent reads, checks, and GitHub calls.
-- The initial report/plan is a hard stop. Do not edit code, close issues, or commit until the user explicitly approves the report.
-- Keep classification and bug analysis bounded enough to produce the user-facing report before deep implementation work.
-
-> **BRANCH RULE**: All work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `fix/` branches. If no release branch exists yet, create one first using `/generate-release` Phase 1 steps 1–5.
-
-> **⛔ PR PROHIBITION**: If a fix is associated with a contributor's PR, you MUST merge their PR — NEVER close it and re-implement the fix yourself. See `/review-prs` workflow for the full policy. The `gh pr close` command is FORBIDDEN unless the repository owner explicitly requests it.
-
-## Steps
-
-### 1. Identify the GitHub Repository
-
-// turbo
-
-- Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
-- Parse the owner and repo name from the URL
-
-### 2. Ensure Release Branch Exists
-
-// turbo
-
-Before doing any work, ensure you are on the current release branch:
-
-```bash
-# Check current branch
-git branch --show-current
-
-# If on main, determine next version and create the release branch
-VERSION=$(node -p "require('./package.json').version")
-NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
-git checkout -b release/v$NEXT
-npm version patch --no-git-tag-version
-npm install
-```
-
-If already on a `release/vX.Y.Z` branch, continue working there.
-
-### 3. Fetch All Open Issues
-
-// turbo-all
-
-**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. You MUST use the two-step approach below to guarantee **all** issues are fetched.
-
-**Step 3a — Get Issue numbers only** (small output, never truncated):
-
-- Run: `gh issue list --repo <owner>/<repo> --state open --limit 500 --json number --jq '.[].number'`
-- This outputs one issue number per line. Count them and confirm total.
-
-**Step 3b — Fetch full metadata for each Issue** (one call per issue):
-
-- For each issue number from step 3a, run:
-  `gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author`
-- You may batch these into parallel calls (up to 4 at a time).
-- Sort by oldest first (FIFO).
-
-### 4. Classify Each Issue
-
-For each issue, determine its type:
-
-- **Bug** — Has `bug` label, or body contains error messages, stack traces, "doesn't work", "broken", "crash", "error"
-- **Feature Request** — Has `enhancement`/`feature` label, or body describes new functionality
-- **Question** — Has `question` label, or is asking "how to" something
-- **Other** — Anything else
-
-Focus ONLY on **Bugs** for resolution. Feature requests and questions should be skipped with a note in the final report.
-
-### 5. Deep-Read Each Bug Issue (One-by-One Analysis)
-
-**IMPORTANT**: Read each bug issue thoroughly, one at a time, before moving to the next. This is NOT a batch process — each issue needs focused attention.
-
-#### 5a. Understand the Problem
-
-For each bug issue, perform the full analysis:
-
-1. **Read the entire body** — including Description, Steps to Reproduce, Expected/Actual Behavior, Error Logs, and Screenshots
-2. **Read ALL comments** — including bot triage comments (Kilo, etc.) and owner/community responses. Pay attention to:
-   - Whether someone already responded with a fix
-   - Whether a community member confirmed the issue is resolved
-   - Whether the issue was marked as duplicate by a bot. **WARNING: DO NOT blindly trust bot duplicate labels (e.g., kilo-duplicate). Bots make mistakes. You MUST read the full conversation and do your own independent analysis to determine if it is truly a duplicate or a distinct bug.**
-3. **Identify the claimed error** — extract the exact error message, status code, and provider/model involved
-
-#### 5b. Check Information Sufficiency
-
-Verify the issue contains enough to act on:
-
-- [ ] Clear description of the problem
-- [ ] Steps to reproduce OR error logs
-- [ ] Provider/model/version information
-- [ ] Expected vs actual behavior
-
-#### 5c. Determine Issue Disposition
-
-For each bug, classify into one of 5 actions:
-
-| Disposition                  | When to Apply                                                                                                          | Action                                                  |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| **✅ CLOSE — Already Fixed** | Owner responded with fix + no user follow-up, OR community confirmed fix                                               | Close with comment citing which version fixed it        |
-| **✅ CLOSE — Duplicate**     | You have independently verified the issue is a duplicate (do NOT rely solely on bot flags) + user provides no new info | Close referencing the original issue                    |
-| **✅ CLOSE — Stale**         | We requested logs/info > 7 days ago with no reply                                                                      | Close thanking the user, invite to reopen if needed     |
-| **📝 RESPOND — Needs Info**  | Issue is real but missing critical reproduction details                                                                | Comment asking for specifics per `/issue-triage`        |
-| **📝 RESPOND — User Config** | Error is caused by unsupported env (Node version, wrong model path, missing API enablement)                            | Comment explaining the user-side fix                    |
-| **🔧 FIX — Code Change**     | Root cause is confirmed in the codebase                                                                                | Research, propose solution in report, wait for approval |
-
-#### 5d. For "FIX — Code Change" Issues
-
-Before coding, perform deep source analysis to formulate a plan:
-
-1. **Search the codebase** — `grep_search` for error strings, relevant function names, affected files
-2. **Search the web** — for upstream API changes, SDK updates, or breaking changes that explain the bug
-3. **Read the full source file** — don't rely on grep snippets; understand the surrounding logic
-4. **Verify the root cause** — confirm the bug is reproducible based on the code, not just a user misconfiguration
-5. **Formulate a proposed solution** — detail the exact files and lines you will change and how you will solve it.
-6. **Create an Implementation Plan file** — write your proposed solution to `_tasks/features-vX.Y.Z/<ISSUE_NUMBER>-<short-description>.plan.md` (e.g. `_tasks/features-v3.7.6/1810-auto-restore-probe-failed-db.plan.md`) where `vX.Y.Z` is the current branch version. The plan should contain an Overview, Pre-Implementation Checklist, and detailed Implementation Steps (Files, Changes).
-7. **DO NOT modify the codebase yet** — wait for user approval on your report and plan first.
-
-#### 5e. For "RESPOND" Issues
-
-Post a substantive comment that:
-
-- Acknowledges the specific error they reported
-- Explains the likely root cause
-- Provides concrete steps to resolve (version upgrade, env var fix, model path correction)
-- Asks for follow-up info if needed
-
-**Do NOT post generic template responses.** Every comment should reference the user's specific error messages and environment.
-
-### 6. Generate Report & Wait for Validation
-
-Present a summary report to the user detailing your proposed actions. For any bugs that need fixing, explicitly explain your proposed solution (files to change and logic) and point out that it will be implemented on the release branch (`release/vX.Y.Z`) after approval.
-
-| Issue | Title | Status        | Proposed Action / Version                 |
-| ----- | ----- | ------------- | ----------------------------------------- |
-| #N    | Title | ✅ Close      | Already fixed / duplicate (explain why)   |
-| #N    | Title | 🔧 Propose    | Explanation of the code fix to be applied |
-| #N    | Title | 📝 Respond    | Guidance comment to be posted             |
-| #N    | Title | ❓ Needs Info | Triage comment to be posted               |
-| #N    | Title | ⏭️ Skip       | Feature request / not a bug               |
-
-> **⚠️ IMPORTANT**: Do NOT implement code changes, commit, push, or close issues at this step.
-> Wait for the user to review the proposed fixes and respond with **OK** before proceeding.
-
-- If the user says **OK** or approves → Proceed to step 7
-- If the user requests changes → Adjust the proposed solution and present the report again
-- If the user rejects → Revert any accidental changes and stop
-
-### 7. Implement Fixes, Run Tests & Commit (only after user approval)
-
-After the user validates and gives the OK:
-
-1. **Implement the fixes** — modify the codebase according to the approved plan.
-2. **Run tests** — `npm run test:all` (or the specific test file) to ensure 100% pass.
-3. **Update CHANGELOG.md** with all new bug fix entries.
-4. **Commit** each fix individually on the release branch with message format: `fix: <description> (#<issue_number>)`.
-5. **Push** the release branch: `git push origin release/vX.Y.Z`.
-6. **Close resolved issues immediately**. For each issue that was marked as Fixed, run:
-   `gh issue close <NUMBER> --repo <owner>/<repo> --comment "Thank you for reporting! This issue has been fixed and will be included in the next release (vX.Y.Z)."`
-7. Likewise, close `Duplicate` issues referencing the original, close `Needs Info` if stale, and post the required comments.
-8. If the project runs automatic releases or needs a PR, proceed to run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user).
-
-If NO fixes were committed, skip closing and source control steps and just conclude the workflow.

.agents/skills/review-discussions/SKILL.md

@@ -1,126 +0,0 @@
----
-name: review-discussions-cx
-description: Read all open GitHub Discussions, summarize them, respond to pending ones, and create issues from actionable feature requests
----
-
-# /review-discussions — GitHub Discussions Review & Response Workflow
-
-## Overview
-
-This workflow reads all open GitHub Discussions, generates a categorized summary, identifies which ones need a response, drafts and posts replies, and optionally creates issues from actionable feature requests. It follows the same flow used for Issues but adapted for the Discussions forum.
-
-> **Tool mapping note (v3.8):** Where steps below say `browser_subagent`, modern runtimes should substitute with the `gh` CLI — `gh api graphql` for reading discussions and mutations for posting comments. `WebFetch` is acceptable for read-only HTML scraping when GraphQL is overkill, but prefer `gh` for any write actions.
-
-## Codex Execution Notes
-
-- Treat `// turbo` / `// turbo-all` as instructions to use `multi_tool_use.parallel` for independent reads and GitHub/browser fetches.
-- The summary report is a hard stop. Do not post discussion replies or create issues until the user explicitly approves.
-
-// turbo-all
-
-## Steps
-
-### 1. Identify the GitHub Repository
-
-- Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
-- Parse the owner and repo name from the URL
-
-### 2. Fetch All Open Discussions
-
-- Use `WebFetch` to fetch `https://github.com/<owner>/<repo>/discussions`
-- Parse the discussion list to get all discussion titles, IDs, authors, categories, and dates
-- For each discussion, fetch the individual page to read the full content and all comments/replies
-
-### 3. Summarize All Discussions
-
-For each discussion, extract:
-
-- **Title** and **#Number**
-- **Author** (GitHub username)
-- **Category** (Announcements, General, Ideas, Q&A, Show and tell)
-- **Date** created
-- **Summary** of the original post (1-2 sentences)
-- **Comments count** and key participants
-- **Your previous response** (if any)
-- **Pending action** — whether a response or follow-up is needed
-
-### 4. Present Summary Report to User
-
-Present the full summary to the user organized by category, using a table:
-
-| #   | Category | Title | Author | Date   | Status            |
-| --- | -------- | ----- | ------ | ------ | ----------------- |
-| #N  | Ideas    | Title | @user  | Mar 23 | ⚠️ Needs response |
-| #N  | Q&A      | Title | @user  | Mar 9  | ✅ Answered       |
-| #N  | General  | Title | @user  | Mar 19 | ⚠️ Needs response |
-
-Highlight:
-
-- **⚠️ Needs response** — No reply from maintainer, or a follow-up comment was left unanswered
-- **✅ Answered** — Maintainer already responded
-- **🐛 Bug reported** — A bug was mentioned that needs tracking
-- **💡 Actionable** — Contains a concrete feature request that could become an issue
-
-### 5. Draft & Post Responses
-
-For each discussion that needs a response, draft a reply following these guidelines:
-
-#### Response Style
-
-- **Friendly and professional** — Start with "Hey @username!"
-- **Acknowledge the contribution** — Thank the user for their input
-- **Be specific** — Reference existing features, settings, or dashboard pages if the feature already exists
-- **Provide workarounds** — If the request isn't implemented yet, suggest current alternatives
-- **Commit to action** — If the request is valid, state that you'll open an issue or add it to the roadmap
-- **Keep it concise** — 3-5 paragraphs max
-
-#### Posting via Browser
-
-- Use `browser_subagent` to navigate to each discussion and post the comment
-- **IMPORTANT**: When typing text in GitHub comment boxes via the browser, use only plain ASCII characters:
-  - Use regular hyphens `-` instead of em-dashes
-  - Use `->` instead of arrow symbols
-  - Do NOT use emoji Unicode characters (the browser keyboard may fail on them)
-  - Use `**bold**` and `\`code\`` markdown formatting
-- Click the green "Comment" button (or "Reply" for threaded replies) after typing
-- Verify the comment was posted by checking the page shows the new comment
-
-### 6. Create Issues from Actionable Feature Requests
-
-For discussions that contain concrete, actionable feature requests:
-
-1. Ask the user which ones should become issues
-2. For each approved request, create a GitHub issue via `browser_subagent`:
-   - Navigate to `https://github.com/<owner>/<repo>/issues/new`
-   - **Title**: `<Feature Name> - <Short description>`
-   - **Body** should include:
-     - `## Feature Request` header
-     - `**Source:** Discussion #N by @author`
-     - `## Problem` — What limitation the user hit
-     - `## Proposed Solution` — How it could work
-     - `### Implementation Ideas` — Technical approach
-     - `### Current Workarounds` — What users can do today
-     - `## Additional Context` — Links to related issues/discussions
-   - Add `enhancement` label
-   - Click "Submit new issue" / "Create"
-3. After creation, go back to the original discussion and post a comment linking to the new issue:
-   - "I've opened Issue #N to track this feature request. Follow along there for updates!"
-
-### 7. Final Report
-
-Present a final summary to the user:
-
-| Discussion | Action Taken                       |
-| ---------- | ---------------------------------- |
-| #N — Title | Responded with workarounds         |
-| #N — Title | Responded + created Issue #N       |
-| #N — Title | Already answered, no action needed |
-| #N — Title | Responded to follow-up comment     |
-
-## Notes
-
-- This workflow is **interactive** — always present the summary and wait for user approval before posting responses or creating issues
-- If the user says "pode responder" (or similar approval), proceed with posting all drafted responses
-- For discussions in non-English languages, respond in the same language as the original post
-- Always reference specific dashboard paths, config options, or code files when explaining existing features
-- When a discussion reveals a bug, note it separately from feature requests

.agents/skills/review-prs/SKILL.md

@@ -1,268 +0,0 @@
----
-name: review-prs-cx
-description: Analyze open Pull Requests from the project's GitHub repository, generate a critical report, and optionally implement approved changes
----
-
-# /review-prs — PR Review & Analysis Workflow
-
-## ⛔ ABSOLUTE PROHIBITION — Read Before Anything Else
-
-> **NEVER close a contributor's PR if you intend to use ANY of their code, ideas, or fixes.**
->
-> **NEVER manually integrate contributor code into a release branch and then close their PR.**
->
-> These actions are **STRICTLY FORBIDDEN** under all circumstances:
->
-> 1. ❌ Closing a PR and cherry-picking/copying its code into a release branch
-> 2. ❌ Closing a PR "because of conflicts" and re-implementing the same fix yourself
-> 3. ❌ Closing a PR and committing a "similar" solution inspired by it
-> 4. ❌ Using `gh pr close` on any PR whose content was or will be used
->
-> **Why**: Closing a PR after taking the contributor's work means they get ZERO credit on GitHub — no "Merged" badge, no contribution graph entry, no public record. This is effectively stealing their contribution. An audit found this happened to **37 PRs** in the past.
->
-> **The ONLY acceptable flow**: Resolve conflicts IN the contributor's branch, push fixes TO their branch, then merge THEIR PR via `gh pr merge`. See Step 7 and Step 8 for the exact procedure.
->
-> **When to close a PR**: ONLY when the user (repository owner) explicitly requests it, OR when the PR is clearly spam/malicious, OR when the author themselves asks to close it. In ALL other cases, leave it open.
-
-## Overview
-
-This workflow fetches all open PRs from the project's GitHub repository, performs a critical analysis of each one, generates a detailed report, and waits for user approval before proceeding with implementation. **All improvements are committed on the current release branch** (`release/vX.Y.Z`).
-
-> **BRANCH RULE**: PRs are ALWAYS merged into the current `release/vX.Y.Z` branch, NEVER directly into `main`. The release branch acts as a staging area — only after all PRs are integrated and tests pass does the release branch get merged into `main` via the `/generate-release` workflow.
-
-## Codex Execution Notes
-
-The source Claude command uses `// turbo` and `// turbo-all` as execution hints. In Codex, treat them explicitly as follows:
-
-- `// turbo`: batch independent local reads and small `gh`/`git` calls with `multi_tool_use.parallel`.
-- `// turbo-all`: fan out independent per-PR/per-issue calls in practical batches, usually up to 4 GitHub calls at a time.
-- Do not expand Step 4 into exhaustive CI-log debugging before Step 6. Fetch numbers, metadata, diffs/review comments, quick merge/conflict status, and only inspect extra logs when they directly affect the verdict.
-- Step 6 is a hard stop. In Codex, present the report in the final response and wait for the user before Step 7/8.
-- Do not checkout PR branches, edit files, post PR comments, close PRs, merge, cherry-pick, or run broad fix/test loops until the user explicitly approves the report.
-- If `gh pr diff` is too large, record the limit and use `gh pr view --json files` plus `git fetch refs/pull/...` with `git diff --stat` / `git diff --name-status`; only read targeted hunks needed for confirmed findings.
-
-## Steps
-
-### 1. Identify the GitHub Repository
-
-- Read `package.json` to get the repository URL, or use the git remote origin URL
-  // turbo
-- Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
-
-### 2. Ensure Release Branch Exists
-
-// turbo
-
-Before doing any work, ensure you are on the current release branch:
-
-```bash
-# Check current branch
-git branch --show-current
-
-# If on main, determine next version and create the release branch
-VERSION=$(node -p "require('./package.json').version")
-# Bump patch: e.g. 3.3.11 → 3.3.12
-NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
-git checkout -b release/v$NEXT
-npm version patch --no-git-tag-version
-npm install
-```
-
-If already on a `release/vX.Y.Z` branch, continue working there.
-
-### 3. Fetch Open Pull Requests
-
-// turbo-all
-
-**⚠️ CRITICAL**: The JSON output of `gh pr list` can be truncated by the tool, silently hiding PRs. You MUST use the two-step approach below to guarantee **all** PRs are fetched.
-
-**Step 3a — Get PR numbers only** (small output, never truncated):
-
-- Run: `gh pr list --repo <owner>/<repo> --state open --limit 500 --json number --jq '.[].number'`
-- This outputs one PR number per line. Count them and confirm total.
-
-**Step 3b — Fetch full metadata for each PR** (one call per PR):
-
-- For each PR number from step 3a, run:
-  `gh pr view <NUMBER> --repo <owner>/<repo> --json number,title,author,headRefName,baseRefName,body,createdAt,additions,deletions,files`
-- You may batch these into parallel calls (up to 4 at a time).
-
-**Step 3c — Fetch diffs for each PR** (one call per PR, saved to /tmp):
-
-- For each PR number, run:
-  `gh pr diff <NUMBER> --repo <owner>/<repo> > /tmp/pr<NUMBER>.diff`
-- Then read each diff file with the appropriate file-read tool (`Read` in Claude Code; equivalent in your agent runtime).
-
-- For each open PR, collect:
-  - PR number, title, author, branch, number of commits, date
-  - PR description/body
-  - Files changed (diff)
-  - Existing review comments (from bots or humans)
-
-**Verification**: Confirm the count of PRs analyzed matches the count from step 3a before proceeding.
-
-### 3.5 Redirect PR Base Branches to Release Branch
-
-// turbo-all
-
-**⚠️ CRITICAL**: Contributors typically open PRs targeting `main`. Before analyzing or merging, redirect ALL open PRs to target the current release branch instead.
-
-```bash
-# Get the current release branch name
-RELEASE_BRANCH=$(git branch --show-current)  # e.g. release/v3.5.4
-
-# For each open PR that targets main, change its base to the release branch
-for PR_NUM in $(gh pr list --repo <owner>/<repo> --state open --json number,baseRefName --jq '.[] | select(.baseRefName == "main") | .number'); do
-  echo "Redirecting PR #$PR_NUM → $RELEASE_BRANCH"
-  gh pr edit "$PR_NUM" --repo <owner>/<repo> --base "$RELEASE_BRANCH"
-done
-```
-
-This ensures:
-
-1. PRs merge into the release branch, not directly into `main`
-2. Merge conflict detection is accurate against the release branch
-3. The release branch accumulates all changes before the final merge to `main`
-4. If the release branch doesn't exist on remote yet, push it first: `git push origin $RELEASE_BRANCH`
-
-### 4. Analyze Each PR — For each open PR, perform the following analysis:
-
-#### 4a. Feature Assessment
-
-- **Does it make sense?** Evaluate if the feature fills a real gap or solves a valid problem
-- **Alignment** — Check if it aligns with the project's architecture and roadmap
-- **Complexity** — Assess if the scope is reasonable or if it should be split
-
-#### 4b. Code Quality Review
-
-- Check for code duplication
-- Evaluate error handling patterns (consistent with existing codebase?)
-- Check naming conventions and code style
-- Verify TypeScript types (any `any` usage, missing types?)
-
-#### 4c. Security Review
-
-- Check for missing authentication/authorization on new endpoints
-- Check for injection vulnerabilities (URL params, SQL, XSS)
-- Verify input validation on all user-controlled data
-- Check for hardcoded secrets or credentials
-
-#### 4d. Architecture Review
-
-- Does the change follow existing patterns?
-- Are there any breaking changes to public APIs?
-- Is the database schema affected? Migration needed?
-- Impact on performance (N+1 queries, missing indexes?)
-
-#### 4e. Test Coverage
-
-- Does the PR include tests?
-- Are edge cases covered?
-- Would existing tests break?
-
-#### 4f. Cross-Layer (Global) Analysis
-
-Perform a **global impact assessment** to verify whether the PR changes are complete across all layers of the application:
-
-- **Backend → Frontend check**: If the PR adds or modifies backend-only resources (new endpoints, services, data models), evaluate whether corresponding frontend changes are missing:
-  - Does a new endpoint require a new screen/page in the dashboard?
-  - Should there be a new action button, menu item, or navigation link?
-  - Are there new data fields that should be displayed or editable in the UI?
-  - Does a new feature need a toggle, configuration panel, or status indicator?
-- **Frontend → Backend check**: If the PR adds frontend elements, verify the backend support exists:
-  - Are the required API endpoints implemented?
-  - Is the data model sufficient for the new UI components?
-- **Cross-cutting concerns**: Check shared layers (types, DTOs, validation schemas, routes, middleware) for completeness
-- **Document gaps** — If missing layers are detected, list them as **IMPORTANT** issues in the report with concrete suggestions for what should be added
-
-### 5. Generate Report — Create a markdown report for each PR including:
-
-- **PR Summary** — What it does, files affected, commit count
-- **Improvements/Benefits** — Numbered list with impact level (HIGH/MEDIUM/LOW)
-- **Risks & Issues** — Categorized as CRITICAL / IMPORTANT / MINOR
-- **Scoring Table** — Rate across: Feature Relevance, Code Quality, Security, Robustness, Tests
-- **Verdict** — Ready to merge? With mandatory vs optional fixes
-- **Next Steps** — What will happen if approved
-
-### 6. Present to User
-
-- Show the report in the final response and stop. Mark this as a blocking checkpoint awaiting explicit user approval before continuing.
-- Wait for user decision:
-  - **Approved** → Proceed to step 7
-  - **Approved with changes** → Implement the fixes and corrections before merging
-  - **Rejected** → Close the PR or leave a review comment
-
-### 7. Pre-Merge Fixes & CI Green-Lighting (if approved)
-
-> **⚠️ Fixes and Conflict Resolutions MUST be pushed back to the PR branch before merging.** We want the PR itself to be green and fully valid before it integrates.
-
-- **Sync latest fixes & Resolve Conflicts:** Merge the current `release` branch into the PR branch. If there are merge conflicts, you MUST resolve them inside the author's PR branch. NEVER resolve conflicts by closing their PR and doing the work in a separate branch, as this steals credit from the original author.
-- **Implement improvements:** Apply the required fixes identified in the analysis directly on the PR branch (e.g., adding missing API routes, fixing SSRF, applying comments from other agents).
-- **Pushing changes to PR branches:**
-
-  ```bash
-  # Checkout the PR locally
-  gh pr checkout <NUMBER>
-
-  # Apply fixes, commit your changes
-  git commit -m "chore: apply review suggestions and missing layers"
-
-  # Attempt to push directly to the PR branch
-  git push
-  ```
-
-- **Fallback (ONLY for external forks without maintainer edit access):**
-  Using `cherry-pick` instead of fixing the contributor's PR directly is a **LAST RESORT**. You MUST ALWAYS attempt to `git push` your fixes to their branch first.
-  **ONLY if `git push` explicitly fails with a permission/access error** (meaning the contributor unchecked "Allow edits from maintainers" or it's a locked fork), you may use `git cherry-pick` to bring their changes into the release branch and fix the issues locally.
-  Even then, ensure you preserve the contributor's authorship (`git commit --author="Contributor Name <email>"` if creating new commits).
-  Once you have integrated their work into the release branch, **DO NOT close their PR**. Leave it open so the contributor retains credit. Under NO CIRCUMSTANCES should you use `gh pr close`.
-
-- Run the project's test suite locally to verify nothing breaks:
-  // turbo
-- Run: `npm test` or equivalent test command
-
-### 8. Merge into Release Branch (NEVER CLOSE!)
-
-> **⚠️ CRITICAL**: NEVER use `gh pr close` for a PR whose idea or code was accepted. Closing a PR in a contributor's face after taking their idea—or closing it just because it had conflicts—is unacceptable.
-> You MUST ALWAYS resolve conflicts and apply fixes ON THE AUTHOR'S PR BRANCH (unless explicitly locked from edits), and then merge the PR using GitHub so the contributor gets the official "Merged" badge and proper credit on their profile. **Do not use cherry-pick just because it is "easier" than resolving conflicts on their branch.**
-
-Even if the PR had severe conflicts or required significant architectural adjustments, you MUST:
-
-1. Resolve any conflicts and apply the fixes directly to their PR branch (as detailed in step 7) or use cherry-picking into the release branch.
-2. If you managed to fix their branch, merge it into the release branch using the GitHub CLI:
-   `gh pr merge <NUMBER> --repo <owner>/<repo> --squash --body "Integrated into release/vX.Y.Z"`
-3. If you had to use cherry-picking because you couldn't push to their branch, DO NOT close the PR. GitHub will sometimes auto-detect the cherry-picked commits and mark it as Merged. If it doesn't, leave it open. The repository owner will handle it. NEVER run `gh pr close`.
-
-In ALL cases:
-
-- Post a **thank-you comment** on the PR via the GitHub API before or immediately after merging.
-- The message should:
-  - Thank the author by name/username for their contribution.
-  - Explain what was adjusted or improved (if we pushed fixes to their branch or cherry-picked).
-  - Note it will be included in the upcoming release.
-  - Be friendly, professional, and encouraging.
-
-> **⚠️ MANDATORY CHANGELOG CREDIT**: When cherry-picking is used (because the PR branch couldn't be pushed to or `gh pr merge` failed), the contributor does NOT get the automatic GitHub "Merged" badge. In this case, you MUST compensate by adding an explicit entry to `CHANGELOG.md` in the `[Unreleased]` section with `(#PR_NUMBER — thanks @username)` format. This ensures the contributor gets public credit in the release notes even if GitHub doesn't auto-detect the cherry-pick. This is NOT optional — skipping it effectively erases the contributor's work from the release record.
-
-### 9. Sync Local Release Branch
-
-After merging PRs, sync the local release branch to include the new changes:
-
-```bash
-git fetch origin
-git pull origin release/vX.Y.Z
-```
-
-### 10. Continue or Finalize
-
-After processing all approved PRs:
-
-- If more PRs remain, go back to step 7
-- When all PRs are processed, **update CHANGELOG.md** on the release branch with all new entries
-- Run **test coverage** to verify the gate (≥75% statements/lines/functions, ≥70% branches — measured ~82%):
-  ```bash
-  npm run test:coverage
-  ```
-- Fix any test regressions introduced by merged PRs
-- Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)
-- The `/generate-release` workflow handles the final merge from `release/vX.Y.Z` → `main`

.agents/skills/version-bump/SKILL.md

@@ -1,347 +0,0 @@
----
-name: version-bump-cx
-description: Bump version, auto-generate CHANGELOG from git commits, update all versioned files, and refresh root + docs/ documentation to reflect the current project state
----
-
-# Version Bump Workflow
-
-Automatically bump the project version, generate CHANGELOG entries from git history since the last tag, update every file that references the version, and refresh project documentation to reflect the current state.
-
-## Codex Execution Notes
-
-- Treat `// turbo` / `// turbo-all` as instructions to use `multi_tool_use.parallel` for independent reads, checks, and GitHub calls.
-- Any user-approval phase is a hard stop: present the report/status in the final response and wait before committing, pushing, tagging, publishing, or deploying.
-
-> **VERSION RULE: Always use PATCH bumps (3.x.y → 3.x.y+1)**
-> NEVER use `npm version minor` or `npm version major`.
-> Always use: `npm version patch --no-git-tag-version`
-> The threshold rule: when `y` reaches 10, bump to `3.(x+1).0` — e.g. `3.4.10` → `3.5.0`.
-
----
-
-## Phase 1: Determine Version
-
-### 1. Read current version and last tag
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-CURRENT_VERSION=$(node -p "require('./package.json').version")
-LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
-CURRENT_BRANCH=$(git branch --show-current)
-echo "Current version: $CURRENT_VERSION"
-echo "Last tag: $LAST_TAG"
-echo "Current branch: $CURRENT_BRANCH"
-```
-
-### 2. Calculate new version
-
-Apply the patch bump rule:
-
-- If the current patch number is `9`, the new version is `3.(minor+1).0`
-- Otherwise, increment patch: `3.x.y` → `3.x.(y+1)`
-
-If the version was ALREADY bumped (e.g. you are on a release branch and package.json already has the new version), **skip the npm version bump** and use the existing version.
-
-### 3. Bump package.json (if needed)
-
-// turbo
-
-```bash
-# Only if version hasn't been bumped yet
-npm version patch --no-git-tag-version
-```
-
-Or for threshold (y=10):
-
-```bash
-# Manual threshold bump
-VERSION="3.X.0"  # compute manually
-npm version "$VERSION" --no-git-tag-version
-```
-
----
-
-## Phase 2: Generate CHANGELOG from Git History
-
-### 4. Collect commits since last tag
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
-echo "=== Commits since $LAST_TAG ==="
-git log "$LAST_TAG"..HEAD --pretty=format:"%h %s" --no-merges | head -100
-echo ""
-echo "=== Merge commits ==="
-git log "$LAST_TAG"..HEAD --merges --pretty=format:"%h %s" | head -50
-```
-
-### 5. Classify commits and generate CHANGELOG section
-
-Analyze each commit message and classify into categories based on the conventional-commit prefix and content:
-
-| Category            | Patterns                                         |
-| ------------------- | ------------------------------------------------ |
-| ✨ New Features     | `feat:`, `feat(*):`                              |
-| 🐛 Bug Fixes        | `fix:`, `fix(*):`                                |
-| ⚠️ Breaking Changes | `BREAKING CHANGE`, `!:` suffix                   |
-| 🛠️ Maintenance      | `chore:`, `refactor:`, `perf:`, `build:`         |
-| 🧪 Tests            | `test:`, `tests:`                                |
-| 📝 Documentation    | `docs:`                                          |
-| 🔒 Security         | `security:`, CVE references, vulnerability fixes |
-| 🌍 i18n             | translation updates, locale changes              |
-
-For each category with entries, create a markdown section with descriptive bullet points. Use the commit messages but rewrite them to be human-readable and descriptive (not raw commit messages).
-
-**If a commit references a PR number** (e.g. `#880`, `PR #885`), include it in the description.
-
-### 6. Update CHANGELOG.md
-
-Replace the `## [Unreleased]` section content with the generated entries, then add the new versioned section:
-
-```markdown
-## [Unreleased]
-
----
-
-## [NEW_VERSION] — YYYY-MM-DD
-
-### ✨ New Features
-
-- **Feature name:** Description (#PR)
-
-### 🐛 Bug Fixes
-
-- **Fix name:** Description (#PR)
-
-### 🛠️ Maintenance
-
-- **Item:** Description
-
----
-
-## [PREVIOUS_VERSION] — YYYY-MM-DD
-
-...
-```
-
-The date must be today's date in `YYYY-MM-DD` format.
-
----
-
-## Phase 3: Sync Version Across All Files
-
-### 7. Update workspace package.json files and openapi.yaml
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-VERSION=$(node -p "require('./package.json').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
-  if [ -d "$dir" ] && [ -f "$dir/package.json" ]; then
-    (cd "$dir" && npm version "$VERSION" --no-git-tag-version --allow-same-version > /dev/null)
-    echo "✓ $dir/package.json → $VERSION"
-  fi
-done
-
-echo "✓ All workspace packages synced to $VERSION"
-```
-
-### 8. Update llm.txt version references
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-VERSION=$(node -p "require('./package.json').version")
-OLD_VERSION_PATTERN='[0-9]\+\.[0-9]\+\.[0-9]\+'
-
-# Update "Current version:" line
-sed -i "s/\*\*Current version:\*\* $OLD_VERSION_PATTERN/**Current version:** $VERSION/" llm.txt
-
-# Update "Key Features (vX.Y.Z)" header
-sed -i "s/## Key Features (v$OLD_VERSION_PATTERN)/## Key Features (v$VERSION)/" llm.txt
-
-echo "✓ llm.txt → $VERSION"
-```
-
-### 9. Regenerate lock file
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-npm install
-echo "✓ Lock file regenerated"
-```
-
----
-
-## Phase 4: Update Root Documentation
-
-Based on the CHANGELOG entries generated in Phase 2, review and update these root-level files if relevant changes warrant updates:
-
-### 10. Review and update root documentation files
-
-For each file below, read the current content and determine if the CHANGELOG entries require any updates. Only modify files where substantive changes have occurred:
-
-| File              | When to update                                                                                                              |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `README.md`       | New providers, major features, stats changes (test count, provider count), badges, installation instructions, feature table |
-| `AGENTS.md`       | Architecture changes, new modules, new commands, new providers, new services/handlers/executors                             |
-| `CONTRIBUTING.md` | Dev workflow changes, new tooling, test infrastructure changes                                                              |
-| `SECURITY.md`     | Security fixes, new auth mechanisms, vulnerability disclosures                                                              |
-| `llm.txt`         | Provider count changes, new features, architecture changes                                                                  |
-
-**Update rules:**
-
-- **README.md**: Update provider count, test count, feature highlights table, badges if any numbers changed. If a new provider was added, add it to the provider table. If a major feature was added, add it to the features section.
-- **AGENTS.md**: If new architecture components (handlers, executors, services, DB modules) were added, update the Architecture section. If new commands were added, update the Build/Test table.
-- **SECURITY.md**: Add new vulnerability fixes or security improvements to the relevant section.
-- **llm.txt**: Update provider count, feature list, version references.
-
-### 11. Review and update docs/ files (excluding i18n/)
-
-For each file in `docs/` (excluding `docs/i18n/`), review if CHANGELOG changes affect it:
-
-| 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.
-
----
-
-## Phase 5: Verify
-
-### 12. Run lint check
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-npm run lint
-```
-
-### 13. Run tests
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-npm test
-```
-
-### 14. Verify version sync across all files
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-VERSION=$(node -p "require('./package.json').version")
-echo "Expected version: $VERSION"
-echo ""
-
-echo "--- package.json ---"
-grep '"version"' package.json | head -1
-
-echo "--- open-sse/package.json ---"
-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/reference/openapi.yaml ---"
-grep "  version:" docs/reference/openapi.yaml | head -1
-
-echo "--- llm.txt ---"
-grep "Current version:" llm.txt
-
-echo "--- CHANGELOG.md (first versioned entry) ---"
-grep "^## \[" CHANGELOG.md | head -2
-```
-
-### 15. 🛑 STOP — Present Summary to User
-
-**STOP** and present a summary to the user including:
-
-- Old version → New version
-- CHANGELOG entries generated
-- Files modified
-- Test results
-- Any documentation updates made
-
-**Wait for the user to confirm before committing.**
-
----
-
-## Phase 6: Commit (only after user approval)
-
-### 16. Stage and commit
-
-// turbo-all
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-git add -A
-VERSION=$(node -p "require('./package.json').version")
-git commit -m "chore(release): bump to v$VERSION — changelog, docs, version sync"
-```
-
----
-
-## Notes
-
-- This workflow does **NOT** create tags, releases, or deploy. Use `/generate-release` for the full release cycle after this.
-- This workflow does **NOT** update `docs/i18n/` translations. Translation updates are handled manually or via release tooling — there is no `/update-i18n` workflow shipped in this repo.
-- The CHANGELOG generation is based on git commits since the last tag. If there are no new commits, the workflow should inform the user and stop.
-- Always verify the generated CHANGELOG entries make sense — raw commit messages may need rewriting for clarity.
-- If the version was already bumped (e.g. you're on a `release/vX.Y.Z` branch), skip the `npm version` step and use the existing version.
-
-## 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/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`                                   |

.agents/workflows/capture-release-evidences-ag.md

@@ -1,51 +0,0 @@
----
-description: Automatically run a browser-automation agent to visually validate all new UI features from the current release and capture evidence WebP recordings of the changes.
----
-
-# Capture Release Evidences Workflow
-
-Use this workflow to automatically drive a browser-automation agent to explore the newly deployed or locally running application and record evidence of the UI changes introduced in the latest release.
-
-> **Tool mapping note (v3.8):** The `browser_subagent` tool referenced below is specific to an earlier agent runtime. In Claude Code, substitute with the available browser MCP tools (e.g. `mcp__claude-in-chrome__*`) for navigation/screenshots, plus the `Write` tool for saving artifacts. The high-level steps remain the same regardless of the browser-automation surface in use.
-
-## Prerequisites
-
-- OmniRoute must be actively running and accessible (e.g. locally at `http://localhost:20128` or on the Local VPS at `http://192.168.0.15:20128`).
-- The user must provide the target URL to be tested, or default to `http://192.168.0.15:20128`.
-
-## Workflow Steps
-
-### 1. Identify Target Features
-
-Review the `CHANGELOG.md` for the latest version to map out the new UI elements. For example:
-
-- **CLI Tools Settings**
-- **New Provider/Model Listings (e.g., Gemini 3.1, Qoder PAT)**
-- **New Feature Modals**
-
-### 2. Run the Browser Subagent
-
-For each identified feature, invoke the `browser_subagent` using the `default_api:browser_subagent` tool.
-**Important Task Guidelines for the Subagent:**
-
-- `TaskName`: Give it a clear name like "Validate CLIProxyAPI Tool Tab".
-- `TaskSummary`: "Navigate to the CLI Tools tab and verify the new Integration settings."
-- `Task`: Provide unambiguous instructions for the subagent, such as: "Navigate to http://192.168.0.15:20128/dashboard. Click on the 'Settings' or 'CLI Tools' nav link. Scroll down to find the CLIProxyAPI integration card. Hover over it to trigger UI state. Verify the components render correctly and exit."
-- `RecordingName`: Ensure it describes the feature (e.g. `v3_4_5_cli_proxy_api`). This is required and strictly automatically saved as a WebP artifacts video by the system.
-
-_(Note: The `browser_subagent` automatically creates a WebP recording named by the `RecordingName` parameter. No additional tools for screenshots are needed.)_
-
-### 3. Generate Report Artifact
-
-After the `browser_subagent` finishes its sessions, generate a final Markdown artifact (using `Write` and `IsArtifact=true`) to present the recordings inline to the user using the `![caption](/absolute/path/to/media.webp)` syntax.
-
-### Example Invocation
-
-\```json
-{
-"TaskName": "Validating Qoder PAT Configuration UI",
-"TaskSummary": "Validates the Qoder provider configuration modal",
-"Task": "Go to http://192.168.0.15:20128/dashboard. Click on the 'Providers' tab. Find 'Qoder' in the list. Click 'Add Token' or 'Configure'. Type 'test_token' and submit. Return when done.",
-"RecordingName": "qoder_pat_ui_validation"
-}
-\```

.agents/workflows/deploy-vps-local-ag.md

@@ -1,39 +0,0 @@
----
-description: Deploy the latest OmniRoute code to the Local VPS (192.168.0.15)
----
-
-# Deploy to Local VPS Workflow
-
-Deploy OmniRoute to the Local VPS using `npm pack + scp` + PM2.
-
-**Local VPS:** `192.168.0.15`
-**Process manager:** PM2 (`omniroute`)
-**Port:** `20128`
-
-## Steps
-
-### 1. Build + pack locally
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
-```
-
-### 2. Copy to Local VPS and install
-
-// turbo-all
-
-```bash
-scp omniroute-*.tgz root@192.168.0.15:/tmp/
-```
-
-```bash
-ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
-```
-
-### 3. Verify the deployment
-
-```bash
-curl -s -o /dev/null -w 'LOCAL HTTP %{http_code}\n' http://192.168.0.15:20128/
-```

.agents/workflows/generate-release-ag.md

@@ -1,356 +0,0 @@
----
-description: Create a new release, bump version up to the .10 patch threshold, update changelog, and manage Pull Requests
----
-
-# Generate Release Workflow
-
-Bump version, finalize CHANGELOG, commit, open a **PR to main** and wait for user confirmation before tagging, publishing, and deploying.
-
-> **VERSION RULE: Always use PATCH bumps (3.x.y → 3.x.y+1)**
-> NEVER use `npm version minor` or `npm version major`.
-> Always use: `npm version patch --no-git-tag-version`
-> The threshold rule: when `y` reaches 10, bump to `3.(x+1).0` — e.g. `3.8.10` → `3.9.0`.
-
-> **🔴 SINGLE BRANCH RULE**: The `release/vX.Y.Z` branch is the **ONLY** development branch for the entire release cycle. ALL work — bug fixes, feature implementations, PR integrations, issue resolutions — MUST be committed directly on this branch. Never create separate `fix/`, `feat/`, or topic branches. When running `/resolve-issues`, `/implement-features`, or `/review-prs`, always work on the current release branch.
-
----
-
-## ⚠️ Two-Phase Flow
-
-```
-Phase 1 (automated): bump → docs → i18n → commit → push → open PR
-  ↕  🛑 STOP: Notify user, wait for PR confirmation
-Phase 2 (post-merge): tag → publish → GitHub release → Docker → deploy
-```
-
-**NEVER push directly to main or create tags before the user confirms the PR.**
-
----
-
-## Phase 0: Security Verification (MANDATORY)
-
-Before creating the release, you must ensure the codebase and supply chain are secure and free of known vulnerabilities.
-
-1. **Run Local Dependencies Audit:**
-
-   ```bash
-   npm audit
-   ```
-
-   _Fix any `high` or `critical` vulnerabilities identified._
-
-2. **Check GitHub CodeQL & Dependabot Alerts:**
-   Navigate to the repository's **Security** tab on GitHub, or use the project's `vulnerability-scanner` skill to analyze active alerts. Ensure all static analysis findings (e.g., prototype pollution, insecure randomness, ReDoS, shell injections) are addressed and logically committed on a target branch.
-
----
-
-## Phase 1: Pre-Merge
-
-### 1. Create release branch
-
-```bash
-git checkout -b release/v3.x.y
-```
-
-### 2. Determine and sync version
-
-Check current version in `package.json`:
-
-```bash
-grep '"version"' package.json
-```
-
-> **🔴 BRANCH-VERSION PARITY RULE**: The logical version in `package.json` MUST exactly match the release branch name. For example, if you are on `release/v3.7.0`, the version in `package.json` MUST be `3.7.0`.
->
-> - If this is the FIRST time generating a release for a new minor/major branch (e.g., bumping from 3.6.9 to 3.7.0), you MUST ensure the version is bumped to match the new branch logic.
-> - If you are just bumping a patch on the current branch (e.g., 3.6.9 to 3.6.10), use:
->   `npm version patch --no-git-tag-version`
-
-> **⚠️ ATOMIC COMMIT RULE — Version bump MUST happen before committing feature files.**
->
-> **CORRECT order:**
->
-> 1. `npm version patch --no-git-tag-version` ← bump first
-> 2. implement features / fix bugs
-> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
->
-> **OR if features are already staged:**
->
-> 1. implement features (do NOT commit yet)
-> 2. `npm version patch --no-git-tag-version` ← bump before committing
-> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
->
-> **NEVER do this (creates version mismatch in git history):**
->
-> - ~~commit features → then bump version → commit package.json separately~~
->
-> This ensures that `git show v3.x.y` always contains both code changes and the version bump together.
-> The GitHub release tag will point to a commit that includes ALL changes for that version.
-
-### 3. Regenerate lock file (REQUIRED after version bump)
-
-**Mandatory** — skipping causes `@swc/helpers` lock mismatch and CI failures:
-
-```bash
-npm install
-```
-
-### 4. Finalize CHANGELOG.md
-
-> **🔴 NO MIXUPS RULE**: Ensure you do NOT mix the backlog of the previous version with the new one. The new version section must ONLY contain the features and fixes for the current release.
-
-Replace the `[Unreleased]` header with the new version and date.
-Keep an empty `## [Unreleased]` section above it, separated by a horizontal rule (`---`).
-
-```markdown
-## [Unreleased]
-
----
-
-## [3.7.0] — 2026-04-19
-
-### ✨ New Features
-
-- ...
-
-### 🐛 Bug Fixes
-
-- ...
-
-### 🏆 Hall de Contribuidores
-
-Um agradecimento especial a todos que contribuíram com código, revisões e testes para este release:
-@user1, @user2
-
----
-
-## [3.6.9] — 2026-04-19
-```
-
-> **🔴 HALL DE CONTRIBUIDORES RULE**: You MUST parse all the PR author mentions (e.g., `(thanks @username)`) from the new version's changelog items, deduplicate them, and append them as a "Hall de Contribuidores" section at the end of the new release block, exactly as shown above.
-
-### 5. Update openapi.yaml version ⚠️ MANDATORY
-
-> **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/reference/openapi.yaml
-echo "✓ openapi.yaml → $VERSION"
-
-for dir in electron open-sse; do
-  if [ -d "$dir" ] && [ -f "$dir/package.json" ]; then
-    (cd "$dir" && npm version "$VERSION" --no-git-tag-version --allow-same-version > /dev/null)
-    echo "✓ $dir/package.json → $VERSION"
-  fi
-done
-# Re-run install to assert the workspace lockfile is updated
-npm install
-```
-
-### 6. Update README.md and i18n docs
-
-Manually perform these documentation updates (there is no `/update-docs` workflow — it was deprecated in v3.8):
-
-- 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/<AREA>.md` if architecture or counts changed
-- Re-run `npm run check:docs-sync` and `npm run check:docs-all` to catch drift
-
-### 7. Run tests
-
-// turbo
-
-```bash
-npm test
-```
-
-All tests must pass before creating the PR.
-
-### 8. Stage, commit, and push
-
-// turbo-all
-
-```bash
-git add -A
-git commit -m "chore(release): v3.x.y — summary of changes"
-git push origin release/v3.x.y
-```
-
-### 9. Open PR to main
-
-### 9. Open PR to main
-
-// turbo
-
-```bash
-VERSION=$(node -p "require('./package.json').version")
-
-# Extract the exact changelog entry for this version from the root CHANGELOG.md
-awk "/^## \\[$VERSION\\]/{flag=1; print; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md > /tmp/changelog_body.txt
-
-# Append test status and next steps
-echo "" >> /tmp/changelog_body.txt
-echo "### Tests" >> /tmp/changelog_body.txt
-echo "- All tests pass" >> /tmp/changelog_body.txt
-echo "" >> /tmp/changelog_body.txt
-echo "### ⚠️ After merging: run Phase 2 steps to tag, publish, and deploy." >> /tmp/changelog_body.txt
-
-gh pr create \
-  --repo diegosouzapw/OmniRoute \
-  --base main \
-  --head release/v$VERSION \
-  --title "Release v$VERSION" \
-  --body-file /tmp/changelog_body.txt
-```
-
-### 10. 🛑 STOP — Notify User & Await PR Confirmation
-
-**This is a mandatory stop point.** Present the report in the final response and stop. Do not continue to the next phase until the user explicitly approves.
-
-Inform the user:
-
-- PR URL
-- Summary of changes
-- Test results
-- List of files changed
-
-**DO NOT proceed to Phase 2 until the user confirms the PR looks good and merges it.**
-
----
-
-## Phase 2: Post-Merge Validation (Local VPS)
-
-> Run these steps only AFTER the user has merged the PR into `main` and all CI jobs have passed.
-
-### 11. Deploy to Local VPS for Final Validation (MANDATORY)
-
-Before cutting the official git tag and publishing to the world, deploy the `main` branch to the Local VPS for a final homologation test.
-
-```bash
-git checkout main
-git pull origin main
-
-# Build and pack locally
-cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
-
-# Deploy to LOCAL VPS (192.168.0.15)
-scp omniroute-*.tgz root@192.168.0.15:/tmp/
-ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
-
-# Verify
-curl -s -o /dev/null -w "LOCAL:  HTTP %{http_code}\n" http://192.168.0.15:20128/
-```
-
-### 12. 🛑 STOP — Notify User & Await Final OK
-
-**This is a mandatory stop point.**
-Inform the user that the `main` branch is now running on the Local VPS.
-Wait for the user to manually test and give the **OK**.
-**DO NOT proceed to Phase 3 until the user confirms the local deploy is stable.**
-
----
-
-## Phase 3: Official Launch
-
-> Run these steps only AFTER the user gives the final OK from the Phase 2 local validation.
-
-### 13. Create Git Tag and GitHub Release (MANDATORY)
-
-// turbo
-
-```bash
-git checkout main
-git pull origin main
-VERSION=$(node -p "require('./package.json').version")
-
-# Extracts the changelog section for this version
-NOTES=$(awk "/^## \\[$VERSION\\]/{flag=1; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
-if [ -z "$NOTES" ]; then NOTES="OmniRoute v$VERSION Release"; fi
-
-git tag -a "v$VERSION" -m "Release v$VERSION"
-git push origin "v$VERSION"
-gh release create "v$VERSION" --repo diegosouzapw/OmniRoute --title "v$VERSION" --notes "$NOTES" --target main || gh release edit "v$VERSION" --repo diegosouzapw/OmniRoute --title "v$VERSION" --notes "$NOTES"
-```
-
-### 14. 🐳 Trigger Docker Hub build (MANDATORY — keep npm and Docker in sync)
-
-> **CRITICAL**: Docker Hub and npm MUST always publish the same version.
-> The Docker image is built automatically via GitHub Actions when a new tag is pushed.
-> After pushing the tag in step 13, **verify the workflow runs**:
-
-```bash
-# Verify the Docker workflow triggered
-gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 3
-
-# Wait for the Docker build to complete (usually 5–10 min)
-gh run watch --repo diegosouzapw/OmniRoute
-```
-
-### 15. Publish to NPM (Optional/Automated)
-
-Normally handled by CI, but if manual publish is required:
-
-```bash
-npm publish
-```
-
-## Phase 4: Release Monitoring & Artifact Validation
-
-> After triggering the official release, actively monitor the CI pipelines until all artifacts are successfully generated. If any pipeline fails, stop and apply the necessary corrections before continuing.
-
-### 16. Monitor CI Pipelines
-
-Wait for and verify the successful completion of the following automated jobs:
-
-1. **Docker Hub Publish**
-2. **Electron Build**
-3. **NPM Registry Publish** (Check with `npm info omniroute version`)
-
-```bash
-# Monitor Docker Hub workflow
-gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 1
-gh run watch <RUN_ID>
-
-# Monitor Electron build
-gh run list --repo diegosouzapw/OmniRoute --workflow electron-release.yml --limit 1
-gh run watch <RUN_ID>
-
-# Verify NPM version
-npm info omniroute version
-```
-
-### 17. Handle Failures (If Any)
-
-If a workflow fails:
-
-- Use `gh run view <RUN_ID> --log-failed` to identify the error.
-- Apply the fix on the `main` branch.
-- If necessary, re-trigger the workflow using `gh workflow run <workflow_name.yml> --repo diegosouzapw/OmniRoute --ref v3.x.y`
-
-### 18. Preserve release branch
-
-```bash
-# Branch is kept for historical purposes. Do not delete.
-```
-
----
-
-## Notes
-
-- Ensure CHANGELOG, README and `docs/*` are current BEFORE this workflow — run `npm run check:docs-all` and `/version-bump` first (there is no `/update-docs` workflow anymore)
-- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`
-- After npm publish, verify with `npm info omniroute version`
-- Lock file sync errors are caused by skipping `npm install` after version bump
-- Use `gh auth switch -u diegosouzapw` if git push fails with wrong account
-
-## Known CI Pitfalls
-
-| 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              |

.agents/workflows/implement-features-ag.md

@@ -1,706 +0,0 @@
----
-description: Analyze open feature request issues, implement viable ones on dedicated branches, and respond to authors
----
-
-# /implement-features — Feature Request Harvest, Research & Implementation Workflow
-
-## Overview
-
-A **5-phase** workflow that systematically harvests feature requests from GitHub issues, creates structured idea files, researches solutions across the internet and Git repositories, presents a consolidated report for user approval, then generates detailed implementation plans and executes them.
-
-**Output directory structure:**
-
-```
-_ideia/
-├── viable/                  # Features approved for implementation
-│   ├── need_details/        # ❓ Good idea but waiting for author clarification (issues stay OPEN)
-│   │   └── 1015-warp-terminal-mitm.md
-│   ├── 1046-native-playground.md           # ✅ Ready — researched and planned
-│   └── 1046-native-playground.requirements.md
-├── defer/                   # ⏭️ Good ideas deferred for future cycles (issues CLOSED)
-│   └── 1041-smart-auto-combos.md
-└── notfit/                  # ❌ Out of scope / already exists (issues CLOSED)
-    └── 945-telegram-integration.md
-
-_tasks/features-vX.Y.Z/   # Implementation plans (per-release)
-└── 1046-native-playground.plan.md
-```
-
-> **LIFECYCLE RULE:** `viable/` files are **DELETED** once the feature is implemented — they are not moved. Only unimplemented features live in `viable/` (or `viable/need_details/`). Files in `defer/` and `notfit/` remain as permanent reference.
-
-> **BRANCH RULE**: All implementation work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `feat/` branches. If no release branch exists yet, create one first using `/generate-release` Phase 1 steps 1–5.
-
----
-
-## Phase 1 — Harvest: Collect & Catalog Feature Ideas
-
-### 1.1 Identify the Repository
-
-// turbo
-
-- Run: `git -C <project_root> remote get-url origin` to extract owner/repo.
-
-### 1.2 Ensure Release Branch Exists
-
-// turbo
-
-Before doing any work, ensure you are on the current release branch:
-
-```bash
-# Check current branch
-git branch --show-current
-
-# If on main, determine next version and create the release branch
-VERSION=$(node -p "require('./package.json').version")
-NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
-git checkout -b release/v$NEXT
-npm version patch --no-git-tag-version
-npm install
-```
-
-If already on a `release/vX.Y.Z` branch, continue working there.
-
-### 1.3 Fetch ALL Open Feature Requests
-
-// turbo-all
-
-**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. You MUST use the two-step approach below.
-
-**Step 1 — Get Issue numbers only** (small output, never truncated):
-
-```bash
-# Fetch issues with feature/enhancement labels
-gh issue list --repo <owner>/<repo> --state open -l "enhancement" --limit 500 --json number --jq '.[].number'
-
-# Also check for [Feature] in title (common pattern when no labels are set)
-gh issue list --repo <owner>/<repo> --state open --limit 500 --json number,title --jq '.[] | select(.title | test("\\[Feature\\]|\\[feature\\]|feature request"; "i")) | .number'
-```
-
-- Merge both lists, deduplicate. Count and confirm the total.
-
-**Step 2 — Fetch full metadata for each Issue** (one call per issue):
-
-```bash
-gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author,assignees
-```
-
-- Read the **entire body** — including description, use cases, screenshots, mockups, and any embedded images.
-- Read **ALL comments** — community discussion, agreements, restrictions, owner responses, and linked PRs.
-- **Images**: If the body or comments contain image URLs (`![...](...)` or `https://...png/jpg/gif`), note them — they may contain UI mockups, wireframes, or architecture diagrams that are essential to understanding the request.
-- You may batch these into parallel calls (up to 4 at a time).
-- Sort by oldest first (FIFO).
-
-### 1.4 Create Idea Files (initially in `_ideia/` root)
-
-For each feature request, create a structured idea file in `<project_root>/_ideia/`:
-
-**Filename convention**: `<NUMBER>-<kebab-case-short-title>.md`
-Example: `1046-native-playground.md`, `1041-smart-auto-combos.md`
-
-#### 1.4a — If the idea file does NOT exist yet, create it:
-
-```markdown
-# Feature: <Title from Issue>
-
-> GitHub Issue: #<NUMBER> — opened by @<author> on <date>
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-<Paste the FULL issue body here, preserving all formatting, images, and code blocks>
-
-## 💬 Community Discussion
-
-<Summarize ALL comments chronologically, noting who said what and any decisions or objections raised>
-
-### Participants
-
-- @<author> — Original requester
-- @<commenter1> — <brief role/opinion>
-- ...
-
-### Key Points
-
-- <bullet list of the most important discussion points>
-- <agreements reached>
-- <objections raised>
-
-## 🎯 Refined Feature Description
-
-<YOUR interpretation and enrichment of the feature request. Expand on what was asked, fill in logical gaps, provide concrete examples of how it would work. This section should be MORE detailed and clearer than the original request.>
-
-### What it solves
-
-- <problem 1>
-- <problem 2>
-
-### How it should work (high level)
-
-1. <step 1>
-2. <step 2>
-3. ...
-
-### Affected areas
-
-- <list of codebase areas, modules, files likely affected>
-
-## 📎 Attachments & References
-
-- <any image URLs, mockup links, or external references from the issue>
-
-## 🔗 Related Ideas
-
-- <links to related \_ideia/ files if any overlap found>
-```
-
-#### 1.4b — If the idea file ALREADY exists, update it:
-
-- Append new comments from the issue to the **Community Discussion** section.
-- Update the **Refined Feature Description** if new information changes the understanding.
-- Add any new **Related Ideas** cross-references found.
-- **Do NOT overwrite** existing content — append and enrich it.
-
-### 1.5 Cross-Reference & Deduplication
-
-After processing all issues:
-
-- Scan all `_ideia/*.md` files for overlapping features.
-- If two features are substantially the same, add `🔗 Related Ideas` cross-references to both.
-- If one is a strict subset of another, note it in the smaller file: `> ℹ️ This feature is a subset of #<OTHER_NUMBER>. Consider implementing together.`
-
----
-
-## Phase 2 — Research: Find Solutions & Build Requirements
-
-For each cataloged idea that is **viable** (aligns with the project's goals):
-
-### 2.1 Viability Pre-Check
-
-Before investing in research, quickly assess:
-
-- [ ] Does this feature align with the project's goals and architecture?
-- [ ] Is it technically feasible with the current codebase?
-- [ ] Does it duplicate existing functionality?
-- [ ] Would it introduce breaking changes or security risks?
-- [ ] Is there enough detail to understand what's needed?
-
-**Verdict options:**
-
-| Verdict               | When                                  | Action                      |
-| --------------------- | ------------------------------------- | --------------------------- |
-| ✅ **VIABLE**         | Good idea, enough context             | Proceed to Research         |
-| ❓ **NEEDS DETAIL**   | Good idea, insufficient spec          | Skip research, ask author   |
-| ⏭️ **DEFER**          | Good idea, too complex for this cycle | Catalog only, skip research |
-| ❌ **NOT FIT**        | Doesn't fit the project               | Explain why                 |
-| 🔁 **ALREADY EXISTS** | Feature already implemented           | Point to existing feature   |
-
-### 2.2 Internet Research (for VIABLE features)
-
-For each viable feature, perform systematic research:
-
-**Step 1 — Web search for similar implementations:**
-
-```
-WebSearch("how to implement <feature description> in <tech stack>")
-WebSearch("<feature keyword> implementation nextjs typescript 2025 2026")
-WebSearch("<feature keyword> open source library npm")
-```
-
-**Step 2 — Find reference Git repositories:**
-
-```
-WebSearch("site:github.com <feature keyword> <tech stack> stars:>100")
-WebSearch("github <feature keyword> implementation recently updated 2026")
-```
-
-- Find **up to 10 relevant repositories**, sorted by most recently updated.
-- For each repository:
-  - Note the repo URL, star count, last commit date
-  - Read its README and relevant source files via `WebFetch`
-  - Extract the architectural approach, patterns used, and key code snippets
-
-**Step 3 — Read API docs and standards:**
-
-If the feature involves an external API, protocol, or standard:
-
-- Find and read the official documentation
-- Note version requirements, authentication patterns, rate limits
-
-### 2.3 Create Requirements File
-
-For each researched feature, create a requirements file alongside its idea file:
-
-**Filename**: `<NUMBER>-<kebab-case-short-title>.requirements.md`
-
-```markdown
-# Requirements: <Feature Title>
-
-> Feature Idea: [#<NUMBER>](./<NUMBER>-<kebab-case-short-title>.md)
-> Research Date: <YYYY-MM-DD>
-> Verdict: ✅ VIABLE
-
-## 🔍 Research Summary
-
-<Brief summary of what was found during research>
-
-## 📚 Reference Implementations
-
-| #   | Repository       | Stars | Last Updated | Approach | Relevance    |
-| --- | ---------------- | ----- | ------------ | -------- | ------------ |
-| 1   | [repo/name](url) | ⭐ N  | YYYY-MM-DD   | <brief>  | High/Med/Low |
-| 2   | ...              |       |              |          |              |
-
-### Key Patterns Found
-
-- <pattern 1 with code snippet or link>
-- <pattern 2>
-
-## 📐 Proposed Solution Architecture
-
-### Approach
-
-<Describe the chosen approach based on research findings>
-
-### New Files
-
-| File                  | Purpose       |
-| --------------------- | ------------- |
-| `path/to/new/file.ts` | <description> |
-
-### Modified Files
-
-| File                       | Changes        |
-| -------------------------- | -------------- |
-| `path/to/existing/file.ts` | <what changes> |
-
-### Database Changes
-
-- <migrations needed, if any>
-
-### API Changes
-
-- <new/modified endpoints, if any>
-
-### UI Changes
-
-- <new/modified pages/components, if any>
-
-## ⚙️ Implementation Effort
-
-- **Estimated complexity**: Low / Medium / High / Very High
-- **Estimated files changed**: ~N
-- **Dependencies needed**: <new npm packages, if any>
-- **Breaking changes**: Yes/No — <details>
-- **i18n impact**: <number of new translation keys>
-- **Test coverage needed**: <brief description>
-
-## ⚠️ Open Questions
-
-- <question 1>
-- <question 2>
-
-## 🔗 External References
-
-- <documentation URLs>
-- <API references>
-```
-
----
-
-## Phase 2.5 — Organize & Respond: Sort Files and Post GitHub Comments
-
-### 2.5.1 Create Directory Structure
-
-// turbo
-
-```bash
-mkdir -p <project_root>/_ideia/viable
-mkdir -p <project_root>/_ideia/viable/need_details
-mkdir -p <project_root>/_ideia/defer
-mkdir -p <project_root>/_ideia/notfit
-```
-
-### 2.5.2 Move Idea Files to Category Subdirectories
-
-After classification, move EVERY idea file to its correct subdirectory:
-
-```bash
-# ✅ VIABLE — move idea + requirements files
-mv _ideia/<NUMBER>-*.md _ideia/viable/
-mv _ideia/<NUMBER>-*.requirements.md _ideia/viable/
-
-# ❓ NEEDS DETAIL — viable but waiting for author response
-mv _ideia/<NUMBER>-*.md _ideia/viable/need_details/
-
-# ⏭️ DEFER — move idea files only
-mv _ideia/<NUMBER>-*.md _ideia/defer/
-
-# ❌ NOT FIT & 🔁 ALREADY EXISTS — move idea files only
-mv _ideia/<NUMBER>-*.md _ideia/notfit/
-```
-
-No files should remain in `_ideia/` root after this step (except subdirectories).
-
-### 2.5.3 Post GitHub Comments by Category
-
-**Each category has a specific comment template and action:**
-
----
-
-#### For 🔁 ALREADY EXISTS — Comment + CLOSE issue
-
-// turbo
-
-The feature already exists in the system. Explain WHERE it is and HOW to use it.
-
-```markdown
-Hi @<author>! Thanks for the suggestion! 🙏
-
-Great news — this functionality **already exists** in OmniRoute:
-
-**📍 Where to find it:** <exact dashboard path or settings location>
-
-**🔧 How to use it:**
-
-1. <step 1>
-2. <step 2>
-3. <step 3>
-
-If you have any trouble finding or using it, feel free to ask in a Discussion. We're always happy to help!
-
-Closing this as the feature is already available. 🎉
-```
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
-```
-
----
-
-#### For ⏭️ DEFER — Comment + CLOSE issue
-
-// turbo
-
-Thank the user, explain the idea was cataloged, and that we'll study it before implementing.
-
-```markdown
-Hi @<author>! Thanks for this thoughtful feature request! 🙏
-
-We really appreciate the detailed proposal. We've **cataloged your idea** and it's now part of our improvement backlog.
-
-Due to the **significant architectural impact** of this feature, we'll need to conduct thorough use-case studies and architectural analysis before we start development. This ensures we build it right and don't introduce regressions.
-
-**What happens next:**
-
-- Your idea is saved in our internal feature backlog
-- We'll conduct architecture studies when this area is prioritized
-- We'll notify you here when development begins
-
-Thank you for contributing to OmniRoute's roadmap! Your input helps shape the product. 🚀
-```
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
-```
-
----
-
-#### For ❌ NOT FIT — Comment + CLOSE issue
-
-// turbo
-
-Politely explain why the feature doesn't fit the project scope.
-
-```markdown
-Hi @<author>! Thanks for the suggestion! 🙏
-
-After careful analysis, we've determined that this feature **falls outside OmniRoute's core scope** as a proxy/router.
-
-**Reason:** <explain why — e.g., "Telegram integration belongs in the application/orchestrator layer that consumes OmniRoute's API, not inside the router itself.">
-
-**Alternative:** <suggest an alternative approach if possible>
-
-We appreciate you thinking of ways to improve OmniRoute! If you'd like to discuss this further, feel free to open a Discussion. 🙏
-```
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
-```
-
----
-
-#### For ❓ NEEDS DETAIL — Comment (keep OPEN)
-
-// turbo
-
-Ask for the specific missing details needed.
-
-```markdown
-Hi @<author>! Thanks for the feature request — it's an interesting idea and we'd love to explore it further. 🙏
-
-To move forward, we need a few more details:
-
-1. <specific question 1>
-2. <specific question 2>
-3. <specific question 3>
-
-If you know of any **open-source projects or repositories** that implement something similar, please share links — it would help us design the best solution.
-
-Looking forward to your response! 🚀
-```
-
----
-
-#### For ✅ VIABLE — Comment (keep OPEN)
-
-// turbo
-
-Thank the user, confirm we've cataloged their idea, and explain it may be implemented in future versions.
-
-```markdown
-Hi @<author>! Thanks for the great feature suggestion! 🙏
-
-We've analyzed your request and it aligns well with OmniRoute's roadmap. We've **cataloged this feature** and it's in our implementation backlog.
-
-**Status:** 📋 Cataloged for future implementation
-
-This feature may be included in upcoming releases. We'll **respond to this issue and tag you** as soon as implementation begins so you can test it.
-
-Thank you for helping improve OmniRoute! 🚀
-```
-
-**⚠️ Do NOT close viable issues — they remain OPEN for tracking.**
-
----
-
-## Phase 3 — Report: Present Findings to User
-
-### 3.1 🛑 MANDATORY STOP — Present Consolidated Report
-
-After completing Phase 1, Phase 2, and Phase 2.5, **STOP and present the following report** in the chat. Do NOT proceed to implementation.
-
-Present a structured report containing:
-
-#### 3.1a — Feature Summary Table
-
-| #   | Issue | Title | Verdict         | Location                      | Action                        |
-| --- | ----- | ----- | --------------- | ----------------------------- | ----------------------------- |
-| 1   | #N    | Title | ✅ VIABLE       | `_ideia/viable/`              | Issue OPEN, comment posted    |
-| 2   | #N    | Title | ⏭️ DEFER        | `_ideia/defer/`               | Issue CLOSED with explanation |
-| 3   | #N    | Title | ❌ NOT FIT      | `_ideia/notfit/`              | Issue CLOSED with explanation |
-| 4   | #N    | Title | 🔁 EXISTS       | `_ideia/notfit/`              | Issue CLOSED with guidance    |
-| 5   | #N    | Title | ❓ NEEDS DETAIL | `_ideia/viable/need_details/` | Issue OPEN, questions posted  |
-
-#### 3.1b — Viable Features Detail
-
-For each VIABLE feature, provide a brief paragraph:
-
-- What was found during research
-- The proposed approach
-- Key risks or unknowns
-- Which reference repositories were most useful
-
-#### 3.1c — Issues Requiring Author Feedback
-
-For features marked ❓ NEEDS DETAIL, list:
-
-- What specific information is missing
-- What examples or repository references would help
-
-#### 3.1d — Ask for User Confirmation
-
-End the report with:
-
-> **Ready to proceed with implementation?**
->
-> - Reply **"sim"** or **"yes"** to generate full implementation plans for all VIABLE features.
-> - Reply with specific issue numbers to select only certain features.
-> - Reply **"não"** or **"no"** to stop here.
-
----
-
-## Phase 4 — Plan: Generate Implementation Plans (after user says "yes")
-
-> **⚠️ Do NOT enter this phase without explicit user approval from Phase 3.**
-
-### 4.1 Create Task Directory
-
-```bash
-mkdir -p <project_root>/_tasks/features-vX.Y.Z/
-```
-
-### 4.2 Generate One Implementation Plan Per Feature
-
-For each VIABLE feature approved by the user, create:
-
-**Filename**: `_tasks/features-vX.Y.Z/<NUMBER>-<kebab-case-title>.plan.md`
-
-```markdown
-# Implementation Plan: <Feature Title>
-
-> Issue: #<NUMBER>
-> Idea: [\_ideia/viable/<NUMBER>-title.md](../../_ideia/viable/<NUMBER>-title.md)
-> Requirements: [\_ideia/viable/<NUMBER>-title.requirements.md](../../_ideia/viable/<NUMBER>-title.requirements.md)
-> Branch: `release/vX.Y.Z`
-
-## Overview
-
-<Brief description of what will be built>
-
-## Pre-Implementation Checklist
-
-- [ ] Read all related source files listed below
-- [ ] Confirm no conflicts with in-flight PRs
-- [ ] Verify database migration numbering
-
-## Implementation Steps
-
-### Step 1: <Title>
-
-**Files:**
-
-- `path/to/file.ts` — <what to change>
-
-**Details:**
-<Detailed description of the change, including code patterns to follow, function signatures, etc.>
-
-### Step 2: <Title>
-
-...
-
-### Step N: Tests
-
-**New test files:**
-
-- `tests/unit/<test-file>.test.mjs` — <what to test>
-
-**Test cases:**
-
-- [ ] <test case 1>
-- [ ] <test case 2>
-
-### Step N+1: i18n
-
-**Translation keys to add:**
-
-- `<namespace>.<key>` — "<English value>"
-
-### Step N+2: Documentation
-
-- [ ] Update CHANGELOG.md
-- [ ] Update relevant docs/ files
-
-## Verification Plan
-
-1. Run `npm run build` — must pass
-2. Run `npm test` — all tests must pass
-3. Run `npm run lint` — no new errors
-4. <Manual verification steps>
-
-## Commit Plan
-```
-
-feat: <description> (#<NUMBER>)
-
-```
-
-```
-
-### 4.3 Present Plans for Final Approval
-
-Present a summary of all generated plans:
-
-> **Implementation plans generated:**
->
-> | #   | Feature | Plan File                                | Steps   | Effort |
-> | --- | ------- | ---------------------------------------- | ------- | ------ |
-> | 1   | <title> | `_tasks/features-vX.Y.Z/N-title.plan.md` | N steps | Medium |
->
-> Reply **"sim"** or **"yes"** to begin implementation of all features.
-> Reply with specific issue numbers to implement only certain ones.
-
----
-
-## Phase 5 — Execute: Implement the Plans (after user says "yes")
-
-> **⚠️ Do NOT enter this phase without explicit user approval from Phase 4.**
-
-### 5.1 Implement Each Feature
-
-For each approved plan, execute it step by step:
-
-1. **Follow the plan** — implement exactly as specified in the `.plan.md` file
-2. **Build** — Run `npm run build` after each feature to verify compilation
-3. **Test** — Run `npm test` to ensure no regressions
-4. **Commit** — Commit with: `feat: <description> (#<NUMBER>)`
-5. **Update the plan** — Mark completed steps with `[x]` in the plan file
-6. **Continue** — Move to the next feature (do NOT switch branches)
-
-### 5.2 Respond to Authors (Update Viable Issues)
-
-For each implemented feature, **close the issue with a final comment**:
-
-````markdown
-✅ **Implemented in `release/vX.Y.Z`!**
-
-Hi @<author>! Great news — your feature request has been implemented! 🎉
-
-**What was done:**
-
-- <bullet list of what was built>
-
-**How to try it:**
-
-```bash
-git fetch origin && git checkout release/vX.Y.Z
-npm install && npm run dev
-```
-````
-
-This will be included in the upcoming **vX.Y.Z** release. Feel free to reopen if you spot any issues! 🚀
-
-````
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
-````
-
-Then **DELETE the idea file** — it has served its purpose:
-
-```bash
-# ✅ Implemented files are DELETED (not moved)
-rm _ideia/viable/<NUMBER>-<title>.md
-rm _ideia/viable/<NUMBER>-<title>.requirements.md  # if exists
-```
-
-> **Why delete?** `viable/` only holds features that still NEED to be done. Once implemented, the commit history and CHANGELOG are the source of truth. Keeping the file would be confusing.
-
-### 5.3 Finalize & Push
-
-After implementing all approved features:
-
-1. **Update CHANGELOG.md** on the release branch with all new feature entries
-2. Push the release branch: `git push origin release/vX.Y.Z`
-3. Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)
-
-### 5.4 Final Summary Report
-
-Present a final summary report to the user:
-
-| Issue | Title | Verdict         | Action                                             | Commit    |
-| ----- | ----- | --------------- | -------------------------------------------------- | --------- |
-| #N    | Title | ✅ Implemented  | Issue closed, idea file deleted                    | `abc1234` |
-| #N    | Title | ⏭️ Deferred     | Issue closed + saved in `_ideia/defer/`            | —         |
-| #N    | Title | ❌ Not Fit      | Issue closed + saved in `_ideia/notfit/`           | —         |
-| #N    | Title | 🔁 Exists       | Issue closed + saved in `_ideia/notfit/`           | —         |
-| #N    | Title | ❓ Needs Detail | Issue OPEN, moved to `_ideia/viable/need_details/` | —         |
-
-Include:
-
-- Total features harvested
-- Total ideas cataloged (`viable/need_details/` + `defer/` + `notfit/`)
-- Total features implemented (idea files deleted, issues closed)
-- Total features deferred
-- Total issues closed
-- Total issues left open (needs detail only — viable are closed after implementation)
-- Test results (pass/fail count)

.agents/workflows/issue-triage-ag.md

@@ -1,50 +0,0 @@
----
-description: How to respond to GitHub issues with insufficient information
----
-
-# Issue Triage Workflow
-
-Respond to GitHub issues that need more information before they can be investigated.
-
-## Steps
-
-### 1. Identify issues needing triage
-
-```bash
-gh issue list --state open --limit 20
-```
-
-### 2. Evaluate each issue
-
-Check if the issue has:
-
-- Clear reproduction steps
-- Environment details (OS, Node.js version, OmniRoute version)
-- Error logs/screenshots
-- Expected vs actual behavior
-
-### 3. Respond with triage template
-
-For issues missing information:
-
-```markdown
-Thank you for reporting this issue! To help us investigate, please provide:
-
-1. **OmniRoute version**: (`omniroute --version`)
-2. **Node.js version**: (`node --version`)
-3. **Operating system**: (e.g., Ubuntu 24.04, macOS 15, Windows 11)
-4. **Installation method**: (npm, Docker, source)
-5. **Steps to reproduce**: (exact commands/actions that trigger the issue)
-6. **Error logs**: (paste relevant logs from the console)
-7. **Expected behavior**: (what should happen)
-
-This will help us debug and resolve your issue faster. 🙏
-```
-
-### 4. Label the issue
-
-Add appropriate labels: `needs-info`, `bug`, `enhancement`, `question`, etc.
-
-```bash
-gh issue edit <NUMBER> --add-label "needs-info"
-```

.agents/workflows/resolve-issues-ag.md

@@ -1,166 +0,0 @@
----
-description: Fetch all open GitHub issues, analyze bugs, resolve what's possible, triage the rest, wait for user validation, then commit and release
----
-
-# /resolve-issues — Automated Issue Resolution Workflow
-
-## Overview
-
-This workflow fetches all open issues from the project's GitHub repository, classifies them, analyzes bugs, proposes a resolution plan, waits for user validation, and ONLY THEN implements the fixes, commits, and closes the issues on the current release branch (`release/vX.Y.Z`). It does NOT merge or release automatically — the release branch is later merged via PR to main.
-
-> **BRANCH RULE**: All work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `fix/` branches. If no release branch exists yet, create one first using `/generate-release` Phase 1 steps 1–5.
-
-> **⛔ PR PROHIBITION**: If a fix is associated with a contributor's PR, you MUST merge their PR — NEVER close it and re-implement the fix yourself. See `/review-prs` workflow for the full policy. The `gh pr close` command is FORBIDDEN unless the repository owner explicitly requests it.
-
-## Steps
-
-### 1. Identify the GitHub Repository
-
-// turbo
-
-- Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
-- Parse the owner and repo name from the URL
-
-### 2. Ensure Release Branch Exists
-
-// turbo
-
-Before doing any work, ensure you are on the current release branch:
-
-```bash
-# Check current branch
-git branch --show-current
-
-# If on main, determine next version and create the release branch
-VERSION=$(node -p "require('./package.json').version")
-NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
-git checkout -b release/v$NEXT
-npm version patch --no-git-tag-version
-npm install
-```
-
-If already on a `release/vX.Y.Z` branch, continue working there.
-
-### 3. Fetch All Open Issues
-
-// turbo-all
-
-**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. You MUST use the two-step approach below to guarantee **all** issues are fetched.
-
-**Step 3a — Get Issue numbers only** (small output, never truncated):
-
-- Run: `gh issue list --repo <owner>/<repo> --state open --limit 500 --json number --jq '.[].number'`
-- This outputs one issue number per line. Count them and confirm total.
-
-**Step 3b — Fetch full metadata for each Issue** (one call per issue):
-
-- For each issue number from step 3a, run:
-  `gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author`
-- You may batch these into parallel calls (up to 4 at a time).
-- Sort by oldest first (FIFO).
-
-### 4. Classify Each Issue
-
-For each issue, determine its type:
-
-- **Bug** — Has `bug` label, or body contains error messages, stack traces, "doesn't work", "broken", "crash", "error"
-- **Feature Request** — Has `enhancement`/`feature` label, or body describes new functionality
-- **Question** — Has `question` label, or is asking "how to" something
-- **Other** — Anything else
-
-Focus ONLY on **Bugs** for resolution. Feature requests and questions should be skipped with a note in the final report.
-
-### 5. Deep-Read Each Bug Issue (One-by-One Analysis)
-
-**IMPORTANT**: Read each bug issue thoroughly, one at a time, before moving to the next. This is NOT a batch process — each issue needs focused attention.
-
-#### 5a. Understand the Problem
-
-For each bug issue, perform the full analysis:
-
-1. **Read the entire body** — including Description, Steps to Reproduce, Expected/Actual Behavior, Error Logs, and Screenshots
-2. **Read ALL comments** — including bot triage comments (Kilo, etc.) and owner/community responses. Pay attention to:
-   - Whether someone already responded with a fix
-   - Whether a community member confirmed the issue is resolved
-   - Whether the issue was marked as duplicate by a bot. **WARNING: DO NOT blindly trust bot duplicate labels (e.g., kilo-duplicate). Bots make mistakes. You MUST read the full conversation and do your own independent analysis to determine if it is truly a duplicate or a distinct bug.**
-3. **Identify the claimed error** — extract the exact error message, status code, and provider/model involved
-
-#### 5b. Check Information Sufficiency
-
-Verify the issue contains enough to act on:
-
-- [ ] Clear description of the problem
-- [ ] Steps to reproduce OR error logs
-- [ ] Provider/model/version information
-- [ ] Expected vs actual behavior
-
-#### 5c. Determine Issue Disposition
-
-For each bug, classify into one of 5 actions:
-
-| Disposition                  | When to Apply                                                                                                          | Action                                                  |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| **✅ CLOSE — Already Fixed** | Owner responded with fix + no user follow-up, OR community confirmed fix                                               | Close with comment citing which version fixed it        |
-| **✅ CLOSE — Duplicate**     | You have independently verified the issue is a duplicate (do NOT rely solely on bot flags) + user provides no new info | Close referencing the original issue                    |
-| **✅ CLOSE — Stale**         | We requested logs/info > 7 days ago with no reply                                                                      | Close thanking the user, invite to reopen if needed     |
-| **📝 RESPOND — Needs Info**  | Issue is real but missing critical reproduction details                                                                | Comment asking for specifics per `/issue-triage`        |
-| **📝 RESPOND — User Config** | Error is caused by unsupported env (Node version, wrong model path, missing API enablement)                            | Comment explaining the user-side fix                    |
-| **🔧 FIX — Code Change**     | Root cause is confirmed in the codebase                                                                                | Research, propose solution in report, wait for approval |
-
-#### 5d. For "FIX — Code Change" Issues
-
-Before coding, perform deep source analysis to formulate a plan:
-
-1. **Search the codebase** — `grep_search` for error strings, relevant function names, affected files
-2. **Search the web** — for upstream API changes, SDK updates, or breaking changes that explain the bug
-3. **Read the full source file** — don't rely on grep snippets; understand the surrounding logic
-4. **Verify the root cause** — confirm the bug is reproducible based on the code, not just a user misconfiguration
-5. **Formulate a proposed solution** — detail the exact files and lines you will change and how you will solve it.
-6. **Create an Implementation Plan file** — write your proposed solution to `_tasks/features-vX.Y.Z/<ISSUE_NUMBER>-<short-description>.plan.md` (e.g. `_tasks/features-v3.7.6/1810-auto-restore-probe-failed-db.plan.md`) where `vX.Y.Z` is the current branch version. The plan should contain an Overview, Pre-Implementation Checklist, and detailed Implementation Steps (Files, Changes).
-7. **DO NOT modify the codebase yet** — wait for user approval on your report and plan first.
-
-#### 5e. For "RESPOND" Issues
-
-Post a substantive comment that:
-
-- Acknowledges the specific error they reported
-- Explains the likely root cause
-- Provides concrete steps to resolve (version upgrade, env var fix, model path correction)
-- Asks for follow-up info if needed
-
-**Do NOT post generic template responses.** Every comment should reference the user's specific error messages and environment.
-
-### 6. Generate Report & Wait for Validation
-
-Present a summary report to the user detailing your proposed actions. For any bugs that need fixing, explicitly explain your proposed solution (files to change and logic) and point out that it will be implemented on the release branch (`release/vX.Y.Z`) after approval.
-
-| Issue | Title | Status        | Proposed Action / Version                 |
-| ----- | ----- | ------------- | ----------------------------------------- |
-| #N    | Title | ✅ Close      | Already fixed / duplicate (explain why)   |
-| #N    | Title | 🔧 Propose    | Explanation of the code fix to be applied |
-| #N    | Title | 📝 Respond    | Guidance comment to be posted             |
-| #N    | Title | ❓ Needs Info | Triage comment to be posted               |
-| #N    | Title | ⏭️ Skip       | Feature request / not a bug               |
-
-> **⚠️ IMPORTANT**: Do NOT implement code changes, commit, push, or close issues at this step.
-> Wait for the user to review the proposed fixes and respond with **OK** before proceeding.
-
-- If the user says **OK** or approves → Proceed to step 7
-- If the user requests changes → Adjust the proposed solution and present the report again
-- If the user rejects → Revert any accidental changes and stop
-
-### 7. Implement Fixes, Run Tests & Commit (only after user approval)
-
-After the user validates and gives the OK:
-
-1. **Implement the fixes** — modify the codebase according to the approved plan.
-2. **Run tests** — `npm run test:all` (or the specific test file) to ensure 100% pass.
-3. **Update CHANGELOG.md** with all new bug fix entries.
-4. **Commit** each fix individually on the release branch with message format: `fix: <description> (#<issue_number>)`.
-5. **Push** the release branch: `git push origin release/vX.Y.Z`.
-6. **Close resolved issues immediately**. For each issue that was marked as Fixed, run:
-   `gh issue close <NUMBER> --repo <owner>/<repo> --comment "Thank you for reporting! This issue has been fixed and will be included in the next release (vX.Y.Z)."`
-7. Likewise, close `Duplicate` issues referencing the original, close `Needs Info` if stale, and post the required comments.
-8. If the project runs automatic releases or needs a PR, proceed to run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user).
-
-If NO fixes were committed, skip closing and source control steps and just conclude the workflow.

.agents/workflows/review-discussions-ag.md

@@ -1,120 +0,0 @@
----
-description: Read all open GitHub Discussions, summarize them, respond to pending ones, and create issues from actionable feature requests
----
-
-# /review-discussions — GitHub Discussions Review & Response Workflow
-
-## Overview
-
-This workflow reads all open GitHub Discussions, generates a categorized summary, identifies which ones need a response, drafts and posts replies, and optionally creates issues from actionable feature requests. It follows the same flow used for Issues but adapted for the Discussions forum.
-
-> **Tool mapping note (v3.8):** Where steps below say `browser_subagent`, in modern Claude Code substitute with the `gh` CLI via Bash — `gh api graphql` for reading discussions and mutations for posting comments. `WebFetch` is acceptable for read-only HTML scraping when GraphQL is overkill, but prefer `gh` for any write actions.
-
-// turbo-all
-
-## Steps
-
-### 1. Identify the GitHub Repository
-
-- Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
-- Parse the owner and repo name from the URL
-
-### 2. Fetch All Open Discussions
-
-- Use `WebFetch` to fetch `https://github.com/<owner>/<repo>/discussions`
-- Parse the discussion list to get all discussion titles, IDs, authors, categories, and dates
-- For each discussion, fetch the individual page to read the full content and all comments/replies
-
-### 3. Summarize All Discussions
-
-For each discussion, extract:
-
-- **Title** and **#Number**
-- **Author** (GitHub username)
-- **Category** (Announcements, General, Ideas, Q&A, Show and tell)
-- **Date** created
-- **Summary** of the original post (1-2 sentences)
-- **Comments count** and key participants
-- **Your previous response** (if any)
-- **Pending action** — whether a response or follow-up is needed
-
-### 4. Present Summary Report to User
-
-Present the full summary to the user organized by category, using a table:
-
-| #   | Category | Title | Author | Date   | Status            |
-| --- | -------- | ----- | ------ | ------ | ----------------- |
-| #N  | Ideas    | Title | @user  | Mar 23 | ⚠️ Needs response |
-| #N  | Q&A      | Title | @user  | Mar 9  | ✅ Answered       |
-| #N  | General  | Title | @user  | Mar 19 | ⚠️ Needs response |
-
-Highlight:
-
-- **⚠️ Needs response** — No reply from maintainer, or a follow-up comment was left unanswered
-- **✅ Answered** — Maintainer already responded
-- **🐛 Bug reported** — A bug was mentioned that needs tracking
-- **💡 Actionable** — Contains a concrete feature request that could become an issue
-
-### 5. Draft & Post Responses
-
-For each discussion that needs a response, draft a reply following these guidelines:
-
-#### Response Style
-
-- **Friendly and professional** — Start with "Hey @username!"
-- **Acknowledge the contribution** — Thank the user for their input
-- **Be specific** — Reference existing features, settings, or dashboard pages if the feature already exists
-- **Provide workarounds** — If the request isn't implemented yet, suggest current alternatives
-- **Commit to action** — If the request is valid, state that you'll open an issue or add it to the roadmap
-- **Keep it concise** — 3-5 paragraphs max
-
-#### Posting via Browser
-
-- Use `browser_subagent` to navigate to each discussion and post the comment
-- **IMPORTANT**: When typing text in GitHub comment boxes via the browser, use only plain ASCII characters:
-  - Use regular hyphens `-` instead of em-dashes
-  - Use `->` instead of arrow symbols
-  - Do NOT use emoji Unicode characters (the browser keyboard may fail on them)
-  - Use `**bold**` and `\`code\`` markdown formatting
-- Click the green "Comment" button (or "Reply" for threaded replies) after typing
-- Verify the comment was posted by checking the page shows the new comment
-
-### 6. Create Issues from Actionable Feature Requests
-
-For discussions that contain concrete, actionable feature requests:
-
-1. Ask the user which ones should become issues
-2. For each approved request, create a GitHub issue via `browser_subagent`:
-   - Navigate to `https://github.com/<owner>/<repo>/issues/new`
-   - **Title**: `<Feature Name> - <Short description>`
-   - **Body** should include:
-     - `## Feature Request` header
-     - `**Source:** Discussion #N by @author`
-     - `## Problem` — What limitation the user hit
-     - `## Proposed Solution` — How it could work
-     - `### Implementation Ideas` — Technical approach
-     - `### Current Workarounds` — What users can do today
-     - `## Additional Context` — Links to related issues/discussions
-   - Add `enhancement` label
-   - Click "Submit new issue" / "Create"
-3. After creation, go back to the original discussion and post a comment linking to the new issue:
-   - "I've opened Issue #N to track this feature request. Follow along there for updates!"
-
-### 7. Final Report
-
-Present a final summary to the user:
-
-| Discussion | Action Taken                       |
-| ---------- | ---------------------------------- |
-| #N — Title | Responded with workarounds         |
-| #N — Title | Responded + created Issue #N       |
-| #N — Title | Already answered, no action needed |
-| #N — Title | Responded to follow-up comment     |
-
-## Notes
-
-- This workflow is **interactive** — always present the summary and wait for user approval before posting responses or creating issues
-- If the user says "pode responder" (or similar approval), proceed with posting all drafted responses
-- For discussions in non-English languages, respond in the same language as the original post
-- Always reference specific dashboard paths, config options, or code files when explaining existing features
-- When a discussion reveals a bug, note it separately from feature requests

.agents/workflows/review-prs-ag.md

@@ -1,256 +0,0 @@
----
-description: Analyze open Pull Requests from the project's GitHub repository, generate a critical report, and optionally implement approved changes
----
-
-# /review-prs — PR Review & Analysis Workflow
-
-## ⛔ ABSOLUTE PROHIBITION — Read Before Anything Else
-
-> **NEVER close a contributor's PR if you intend to use ANY of their code, ideas, or fixes.**
->
-> **NEVER manually integrate contributor code into a release branch and then close their PR.**
->
-> These actions are **STRICTLY FORBIDDEN** under all circumstances:
->
-> 1. ❌ Closing a PR and cherry-picking/copying its code into a release branch
-> 2. ❌ Closing a PR "because of conflicts" and re-implementing the same fix yourself
-> 3. ❌ Closing a PR and committing a "similar" solution inspired by it
-> 4. ❌ Using `gh pr close` on any PR whose content was or will be used
->
-> **Why**: Closing a PR after taking the contributor's work means they get ZERO credit on GitHub — no "Merged" badge, no contribution graph entry, no public record. This is effectively stealing their contribution. An audit found this happened to **37 PRs** in the past.
->
-> **The ONLY acceptable flow**: Resolve conflicts IN the contributor's branch, push fixes TO their branch, then merge THEIR PR via `gh pr merge`. See Step 7 and Step 8 for the exact procedure.
->
-> **When to close a PR**: ONLY when the user (repository owner) explicitly requests it, OR when the PR is clearly spam/malicious, OR when the author themselves asks to close it. In ALL other cases, leave it open.
-
-## Overview
-
-This workflow fetches all open PRs from the project's GitHub repository, performs a critical analysis of each one, generates a detailed report, and waits for user approval before proceeding with implementation. **All improvements are committed on the current release branch** (`release/vX.Y.Z`).
-
-> **BRANCH RULE**: PRs are ALWAYS merged into the current `release/vX.Y.Z` branch, NEVER directly into `main`. The release branch acts as a staging area — only after all PRs are integrated and tests pass does the release branch get merged into `main` via the `/generate-release` workflow.
-
-## Steps
-
-### 1. Identify the GitHub Repository
-
-- Read `package.json` to get the repository URL, or use the git remote origin URL
-  // turbo
-- Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
-
-### 2. Ensure Release Branch Exists
-
-// turbo
-
-Before doing any work, ensure you are on the current release branch:
-
-```bash
-# Check current branch
-git branch --show-current
-
-# If on main, determine next version and create the release branch
-VERSION=$(node -p "require('./package.json').version")
-# Bump patch: e.g. 3.3.11 → 3.3.12
-NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
-git checkout -b release/v$NEXT
-npm version patch --no-git-tag-version
-npm install
-```
-
-If already on a `release/vX.Y.Z` branch, continue working there.
-
-### 3. Fetch Open Pull Requests
-
-// turbo-all
-
-**⚠️ CRITICAL**: The JSON output of `gh pr list` can be truncated by the tool, silently hiding PRs. You MUST use the two-step approach below to guarantee **all** PRs are fetched.
-
-**Step 3a — Get PR numbers only** (small output, never truncated):
-
-- Run: `gh pr list --repo <owner>/<repo> --state open --limit 500 --json number --jq '.[].number'`
-- This outputs one PR number per line. Count them and confirm total.
-
-**Step 3b — Fetch full metadata for each PR** (one call per PR):
-
-- For each PR number from step 3a, run:
-  `gh pr view <NUMBER> --repo <owner>/<repo> --json number,title,author,headRefName,baseRefName,body,createdAt,additions,deletions,files`
-- You may batch these into parallel calls (up to 4 at a time).
-
-**Step 3c — Fetch diffs for each PR** (one call per PR, saved to /tmp):
-
-- For each PR number, run:
-  `gh pr diff <NUMBER> --repo <owner>/<repo> > /tmp/pr<NUMBER>.diff`
-- Then read each diff file with the appropriate file-read tool (`Read` in Claude Code; equivalent in your agent runtime).
-
-- For each open PR, collect:
-  - PR number, title, author, branch, number of commits, date
-  - PR description/body
-  - Files changed (diff)
-  - Existing review comments (from bots or humans)
-
-**Verification**: Confirm the count of PRs analyzed matches the count from step 3a before proceeding.
-
-### 3.5 Redirect PR Base Branches to Release Branch
-
-// turbo-all
-
-**⚠️ CRITICAL**: Contributors typically open PRs targeting `main`. Before analyzing or merging, redirect ALL open PRs to target the current release branch instead.
-
-```bash
-# Get the current release branch name
-RELEASE_BRANCH=$(git branch --show-current)  # e.g. release/v3.5.4
-
-# For each open PR that targets main, change its base to the release branch
-for PR_NUM in $(gh pr list --repo <owner>/<repo> --state open --json number,baseRefName --jq '.[] | select(.baseRefName == "main") | .number'); do
-  echo "Redirecting PR #$PR_NUM → $RELEASE_BRANCH"
-  gh pr edit "$PR_NUM" --repo <owner>/<repo> --base "$RELEASE_BRANCH"
-done
-```
-
-This ensures:
-
-1. PRs merge into the release branch, not directly into `main`
-2. Merge conflict detection is accurate against the release branch
-3. The release branch accumulates all changes before the final merge to `main`
-4. If the release branch doesn't exist on remote yet, push it first: `git push origin $RELEASE_BRANCH`
-
-### 4. Analyze Each PR — For each open PR, perform the following analysis:
-
-#### 4a. Feature Assessment
-
-- **Does it make sense?** Evaluate if the feature fills a real gap or solves a valid problem
-- **Alignment** — Check if it aligns with the project's architecture and roadmap
-- **Complexity** — Assess if the scope is reasonable or if it should be split
-
-#### 4b. Code Quality Review
-
-- Check for code duplication
-- Evaluate error handling patterns (consistent with existing codebase?)
-- Check naming conventions and code style
-- Verify TypeScript types (any `any` usage, missing types?)
-
-#### 4c. Security Review
-
-- Check for missing authentication/authorization on new endpoints
-- Check for injection vulnerabilities (URL params, SQL, XSS)
-- Verify input validation on all user-controlled data
-- Check for hardcoded secrets or credentials
-
-#### 4d. Architecture Review
-
-- Does the change follow existing patterns?
-- Are there any breaking changes to public APIs?
-- Is the database schema affected? Migration needed?
-- Impact on performance (N+1 queries, missing indexes?)
-
-#### 4e. Test Coverage
-
-- Does the PR include tests?
-- Are edge cases covered?
-- Would existing tests break?
-
-#### 4f. Cross-Layer (Global) Analysis
-
-Perform a **global impact assessment** to verify whether the PR changes are complete across all layers of the application:
-
-- **Backend → Frontend check**: If the PR adds or modifies backend-only resources (new endpoints, services, data models), evaluate whether corresponding frontend changes are missing:
-  - Does a new endpoint require a new screen/page in the dashboard?
-  - Should there be a new action button, menu item, or navigation link?
-  - Are there new data fields that should be displayed or editable in the UI?
-  - Does a new feature need a toggle, configuration panel, or status indicator?
-- **Frontend → Backend check**: If the PR adds frontend elements, verify the backend support exists:
-  - Are the required API endpoints implemented?
-  - Is the data model sufficient for the new UI components?
-- **Cross-cutting concerns**: Check shared layers (types, DTOs, validation schemas, routes, middleware) for completeness
-- **Document gaps** — If missing layers are detected, list them as **IMPORTANT** issues in the report with concrete suggestions for what should be added
-
-### 5. Generate Report — Create a markdown report for each PR including:
-
-- **PR Summary** — What it does, files affected, commit count
-- **Improvements/Benefits** — Numbered list with impact level (HIGH/MEDIUM/LOW)
-- **Risks & Issues** — Categorized as CRITICAL / IMPORTANT / MINOR
-- **Scoring Table** — Rate across: Feature Relevance, Code Quality, Security, Robustness, Tests
-- **Verdict** — Ready to merge? With mandatory vs optional fixes
-- **Next Steps** — What will happen if approved
-
-### 6. Present to User
-
-- Show the report in the final response and stop. Mark this as a blocking checkpoint awaiting explicit user approval.
-- Wait for user decision:
-  - **Approved** → Proceed to step 7
-  - **Approved with changes** → Implement the fixes and corrections before merging
-  - **Rejected** → Close the PR or leave a review comment
-
-### 7. Pre-Merge Fixes & CI Green-Lighting (if approved)
-
-> **⚠️ Fixes and Conflict Resolutions MUST be pushed back to the PR branch before merging.** We want the PR itself to be green and fully valid before it integrates.
-
-- **Sync latest fixes & Resolve Conflicts:** Merge the current `release` branch into the PR branch. If there are merge conflicts, you MUST resolve them inside the author's PR branch. NEVER resolve conflicts by closing their PR and doing the work in a separate branch, as this steals credit from the original author.
-- **Implement improvements:** Apply the required fixes identified in the analysis directly on the PR branch (e.g., adding missing API routes, fixing SSRF, applying comments from other agents).
-- **Pushing changes to PR branches:**
-
-  ```bash
-  # Checkout the PR locally
-  gh pr checkout <NUMBER>
-
-  # Apply fixes, commit your changes
-  git commit -m "chore: apply review suggestions and missing layers"
-
-  # Attempt to push directly to the PR branch
-  git push
-  ```
-
-- **Fallback (ONLY for external forks without maintainer edit access):**
-  Using `cherry-pick` instead of fixing the contributor's PR directly is a **LAST RESORT**. You MUST ALWAYS attempt to `git push` your fixes to their branch first.
-  **ONLY if `git push` explicitly fails with a permission/access error** (meaning the contributor unchecked "Allow edits from maintainers" or it's a locked fork), you may use `git cherry-pick` to bring their changes into the release branch and fix the issues locally.
-  Even then, ensure you preserve the contributor's authorship (`git commit --author="Contributor Name <email>"` if creating new commits).
-  Once you have integrated their work into the release branch, **DO NOT close their PR**. Leave it open so the contributor retains credit. Under NO CIRCUMSTANCES should you use `gh pr close`.
-
-- Run the project's test suite locally to verify nothing breaks:
-  // turbo
-- Run: `npm test` or equivalent test command
-
-### 8. Merge into Release Branch (NEVER CLOSE!)
-
-> **⚠️ CRITICAL**: NEVER use `gh pr close` for a PR whose idea or code was accepted. Closing a PR in a contributor's face after taking their idea—or closing it just because it had conflicts—is unacceptable.
-> You MUST ALWAYS resolve conflicts and apply fixes ON THE AUTHOR'S PR BRANCH (unless explicitly locked from edits), and then merge the PR using GitHub so the contributor gets the official "Merged" badge and proper credit on their profile. **Do not use cherry-pick just because it is "easier" than resolving conflicts on their branch.**
-
-Even if the PR had severe conflicts or required significant architectural adjustments, you MUST:
-
-1. Resolve any conflicts and apply the fixes directly to their PR branch (as detailed in step 7) or use cherry-picking into the release branch.
-2. If you managed to fix their branch, merge it into the release branch using the GitHub CLI:
-   `gh pr merge <NUMBER> --repo <owner>/<repo> --squash --body "Integrated into release/vX.Y.Z"`
-3. If you had to use cherry-picking because you couldn't push to their branch, DO NOT close the PR. GitHub will sometimes auto-detect the cherry-picked commits and mark it as Merged. If it doesn't, leave it open. The repository owner will handle it. NEVER run `gh pr close`.
-
-In ALL cases:
-
-- Post a **thank-you comment** on the PR via the GitHub API before or immediately after merging.
-- The message should:
-  - Thank the author by name/username for their contribution.
-  - Explain what was adjusted or improved (if we pushed fixes to their branch or cherry-picked).
-  - Note it will be included in the upcoming release.
-  - Be friendly, professional, and encouraging.
-
-> **⚠️ MANDATORY CHANGELOG CREDIT**: When cherry-picking is used (because the PR branch couldn't be pushed to or `gh pr merge` failed), the contributor does NOT get the automatic GitHub "Merged" badge. In this case, you MUST compensate by adding an explicit entry to `CHANGELOG.md` in the `[Unreleased]` section with `(#PR_NUMBER — thanks @username)` format. This ensures the contributor gets public credit in the release notes even if GitHub doesn't auto-detect the cherry-pick. This is NOT optional — skipping it effectively erases the contributor's work from the release record.
-
-### 9. Sync Local Release Branch
-
-After merging PRs, sync the local release branch to include the new changes:
-
-```bash
-git fetch origin
-git pull origin release/vX.Y.Z
-```
-
-### 10. Continue or Finalize
-
-After processing all approved PRs:
-
-- If more PRs remain, go back to step 7
-- When all PRs are processed, **update CHANGELOG.md** on the release branch with all new entries
-- Run **test coverage** to verify the gate (≥75% statements/lines/functions, ≥70% branches — measured ~82%):
-  ```bash
-  npm run test:coverage
-  ```
-- Fix any test regressions introduced by merged PRs
-- Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)
-- The `/generate-release` workflow handles the final merge from `release/vX.Y.Z` → `main`

.agents/workflows/version-bump-ag.md

@@ -1,341 +0,0 @@
----
-description: Bump version, auto-generate CHANGELOG from git commits, update all versioned files, and refresh root + docs/ documentation to reflect the current project state
----
-
-# Version Bump Workflow
-
-Automatically bump the project version, generate CHANGELOG entries from git history since the last tag, update every file that references the version, and refresh project documentation to reflect the current state.
-
-> **VERSION RULE: Always use PATCH bumps (3.x.y → 3.x.y+1)**
-> NEVER use `npm version minor` or `npm version major`.
-> Always use: `npm version patch --no-git-tag-version`
-> The threshold rule: when `y` reaches 10, bump to `3.(x+1).0` — e.g. `3.4.10` → `3.5.0`.
-
----
-
-## Phase 1: Determine Version
-
-### 1. Read current version and last tag
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-CURRENT_VERSION=$(node -p "require('./package.json').version")
-LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
-CURRENT_BRANCH=$(git branch --show-current)
-echo "Current version: $CURRENT_VERSION"
-echo "Last tag: $LAST_TAG"
-echo "Current branch: $CURRENT_BRANCH"
-```
-
-### 2. Calculate new version
-
-Apply the patch bump rule:
-
-- If the current patch number is `9`, the new version is `3.(minor+1).0`
-- Otherwise, increment patch: `3.x.y` → `3.x.(y+1)`
-
-If the version was ALREADY bumped (e.g. you are on a release branch and package.json already has the new version), **skip the npm version bump** and use the existing version.
-
-### 3. Bump package.json (if needed)
-
-// turbo
-
-```bash
-# Only if version hasn't been bumped yet
-npm version patch --no-git-tag-version
-```
-
-Or for threshold (y=10):
-
-```bash
-# Manual threshold bump
-VERSION="3.X.0"  # compute manually
-npm version "$VERSION" --no-git-tag-version
-```
-
----
-
-## Phase 2: Generate CHANGELOG from Git History
-
-### 4. Collect commits since last tag
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
-echo "=== Commits since $LAST_TAG ==="
-git log "$LAST_TAG"..HEAD --pretty=format:"%h %s" --no-merges | head -100
-echo ""
-echo "=== Merge commits ==="
-git log "$LAST_TAG"..HEAD --merges --pretty=format:"%h %s" | head -50
-```
-
-### 5. Classify commits and generate CHANGELOG section
-
-Analyze each commit message and classify into categories based on the conventional-commit prefix and content:
-
-| Category            | Patterns                                         |
-| ------------------- | ------------------------------------------------ |
-| ✨ New Features     | `feat:`, `feat(*):`                              |
-| 🐛 Bug Fixes        | `fix:`, `fix(*):`                                |
-| ⚠️ Breaking Changes | `BREAKING CHANGE`, `!:` suffix                   |
-| 🛠️ Maintenance      | `chore:`, `refactor:`, `perf:`, `build:`         |
-| 🧪 Tests            | `test:`, `tests:`                                |
-| 📝 Documentation    | `docs:`                                          |
-| 🔒 Security         | `security:`, CVE references, vulnerability fixes |
-| 🌍 i18n             | translation updates, locale changes              |
-
-For each category with entries, create a markdown section with descriptive bullet points. Use the commit messages but rewrite them to be human-readable and descriptive (not raw commit messages).
-
-**If a commit references a PR number** (e.g. `#880`, `PR #885`), include it in the description.
-
-### 6. Update CHANGELOG.md
-
-Replace the `## [Unreleased]` section content with the generated entries, then add the new versioned section:
-
-```markdown
-## [Unreleased]
-
----
-
-## [NEW_VERSION] — YYYY-MM-DD
-
-### ✨ New Features
-
-- **Feature name:** Description (#PR)
-
-### 🐛 Bug Fixes
-
-- **Fix name:** Description (#PR)
-
-### 🛠️ Maintenance
-
-- **Item:** Description
-
----
-
-## [PREVIOUS_VERSION] — YYYY-MM-DD
-
-...
-```
-
-The date must be today's date in `YYYY-MM-DD` format.
-
----
-
-## Phase 3: Sync Version Across All Files
-
-### 7. Update workspace package.json files and openapi.yaml
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-VERSION=$(node -p "require('./package.json').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
-  if [ -d "$dir" ] && [ -f "$dir/package.json" ]; then
-    (cd "$dir" && npm version "$VERSION" --no-git-tag-version --allow-same-version > /dev/null)
-    echo "✓ $dir/package.json → $VERSION"
-  fi
-done
-
-echo "✓ All workspace packages synced to $VERSION"
-```
-
-### 8. Update llm.txt version references
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-VERSION=$(node -p "require('./package.json').version")
-OLD_VERSION_PATTERN='[0-9]\+\.[0-9]\+\.[0-9]\+'
-
-# Update "Current version:" line
-sed -i "s/\*\*Current version:\*\* $OLD_VERSION_PATTERN/**Current version:** $VERSION/" llm.txt
-
-# Update "Key Features (vX.Y.Z)" header
-sed -i "s/## Key Features (v$OLD_VERSION_PATTERN)/## Key Features (v$VERSION)/" llm.txt
-
-echo "✓ llm.txt → $VERSION"
-```
-
-### 9. Regenerate lock file
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-npm install
-echo "✓ Lock file regenerated"
-```
-
----
-
-## Phase 4: Update Root Documentation
-
-Based on the CHANGELOG entries generated in Phase 2, review and update these root-level files if relevant changes warrant updates:
-
-### 10. Review and update root documentation files
-
-For each file below, read the current content and determine if the CHANGELOG entries require any updates. Only modify files where substantive changes have occurred:
-
-| File              | When to update                                                                                                              |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `README.md`       | New providers, major features, stats changes (test count, provider count), badges, installation instructions, feature table |
-| `AGENTS.md`       | Architecture changes, new modules, new commands, new providers, new services/handlers/executors                             |
-| `CONTRIBUTING.md` | Dev workflow changes, new tooling, test infrastructure changes                                                              |
-| `SECURITY.md`     | Security fixes, new auth mechanisms, vulnerability disclosures                                                              |
-| `llm.txt`         | Provider count changes, new features, architecture changes                                                                  |
-
-**Update rules:**
-
-- **README.md**: Update provider count, test count, feature highlights table, badges if any numbers changed. If a new provider was added, add it to the provider table. If a major feature was added, add it to the features section.
-- **AGENTS.md**: If new architecture components (handlers, executors, services, DB modules) were added, update the Architecture section. If new commands were added, update the Build/Test table.
-- **SECURITY.md**: Add new vulnerability fixes or security improvements to the relevant section.
-- **llm.txt**: Update provider count, feature list, version references.
-
-### 11. Review and update docs/ files (excluding i18n/)
-
-For each file in `docs/` (excluding `docs/i18n/`), review if CHANGELOG changes affect it:
-
-| 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.
-
----
-
-## Phase 5: Verify
-
-### 12. Run lint check
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-npm run lint
-```
-
-### 13. Run tests
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-npm test
-```
-
-### 14. Verify version sync across all files
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-VERSION=$(node -p "require('./package.json').version")
-echo "Expected version: $VERSION"
-echo ""
-
-echo "--- package.json ---"
-grep '"version"' package.json | head -1
-
-echo "--- open-sse/package.json ---"
-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/reference/openapi.yaml ---"
-grep "  version:" docs/reference/openapi.yaml | head -1
-
-echo "--- llm.txt ---"
-grep "Current version:" llm.txt
-
-echo "--- CHANGELOG.md (first versioned entry) ---"
-grep "^## \[" CHANGELOG.md | head -2
-```
-
-### 15. 🛑 STOP — Present Summary to User
-
-**STOP** and present a summary to the user including:
-
-- Old version → New version
-- CHANGELOG entries generated
-- Files modified
-- Test results
-- Any documentation updates made
-
-**Wait for the user to confirm before committing.**
-
----
-
-## Phase 6: Commit (only after user approval)
-
-### 16. Stage and commit
-
-// turbo-all
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-git add -A
-VERSION=$(node -p "require('./package.json').version")
-git commit -m "chore(release): bump to v$VERSION — changelog, docs, version sync"
-```
-
----
-
-## Notes
-
-- This workflow does **NOT** create tags, releases, or deploy. Use `/generate-release` for the full release cycle after this.
-- This workflow does **NOT** update `docs/i18n/` translations. Translation updates are handled manually or via release tooling — there is no `/update-i18n` workflow shipped in this repo.
-- The CHANGELOG generation is based on git commits since the last tag. If there are no new commits, the workflow should inform the user and stop.
-- Always verify the generated CHANGELOG entries make sense — raw commit messages may need rewriting for clarity.
-- If the version was already bumped (e.g. you're on a `release/vX.Y.Z` branch), skip the `npm version` step and use the existing version.
-
-## 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/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`                                   |

.claude/commands/capture-release-evidences-cc.md

@@ -1,51 +0,0 @@
----
-description: Automatically run a browser-automation agent to visually validate all new UI features from the current release and capture evidence WebP recordings of the changes.
----
-
-# Capture Release Evidences Workflow
-
-Use this workflow to automatically drive a browser-automation agent to explore the newly deployed or locally running application and record evidence of the UI changes introduced in the latest release.
-
-> **Tool mapping note (v3.8):** This workflow references a `browser_subagent` tool that was specific to an earlier agent runtime. In Claude Code, substitute with the available browser MCP tools (e.g. `mcp__claude-in-chrome__*`) for navigation/screenshots, plus the `Write` tool for saving artifacts. The high-level steps below remain the same regardless of which browser-automation surface is used.
-
-## Prerequisites
-
-- OmniRoute must be actively running and accessible (e.g. locally at `http://localhost:20128` or on the Local VPS at `http://192.168.0.15:20128`).
-- The user must provide the target URL to be tested, or default to `http://192.168.0.15:20128`.
-
-## Workflow Steps
-
-### 1. Identify Target Features
-
-Review the `CHANGELOG.md` for the latest version to map out the new UI elements. For example:
-
-- **CLI Tools Settings**
-- **New Provider/Model Listings (e.g., Gemini 3.1, Qoder PAT)**
-- **New Feature Modals**
-
-### 2. Run the Browser Subagent
-
-For each identified feature, invoke the `browser_subagent` using the `default_api:browser_subagent` tool.
-**Important Task Guidelines for the Subagent:**
-
-- `TaskName`: Give it a clear name like "Validate CLIProxyAPI Tool Tab".
-- `TaskSummary`: "Navigate to the CLI Tools tab and verify the new Integration settings."
-- `Task`: Provide unambiguous instructions for the subagent, such as: "Navigate to http://192.168.0.15:20128/dashboard. Click on the 'Settings' or 'CLI Tools' nav link. Scroll down to find the CLIProxyAPI integration card. Hover over it to trigger UI state. Verify the components render correctly and exit."
-- `RecordingName`: Ensure it describes the feature (e.g. `v3_4_5_cli_proxy_api`). This is required and strictly automatically saved as a WebP artifacts video by the system.
-
-_(Note: The `browser_subagent` automatically creates a WebP recording named by the `RecordingName` parameter. No additional tools for screenshots are needed.)_
-
-### 3. Generate Report Artifact
-
-After the `browser_subagent` finishes its sessions, generate a final Markdown artifact (using `Write` and `IsArtifact=true`) to present the recordings inline to the user using the `![caption](/absolute/path/to/media.webp)` syntax.
-
-### Example Invocation
-
-\```json
-{
-"TaskName": "Validating Qoder PAT Configuration UI",
-"TaskSummary": "Validates the Qoder provider configuration modal",
-"Task": "Go to http://192.168.0.15:20128/dashboard. Click on the 'Providers' tab. Find 'Qoder' in the list. Click 'Add Token' or 'Configure'. Type 'test_token' and submit. Return when done.",
-"RecordingName": "qoder_pat_ui_validation"
-}
-\```

.claude/commands/deploy-vps-akamai-cc.md

@@ -1,39 +0,0 @@
----
-description: Deploy the latest OmniRoute code to the Akamai VPS (69.164.221.35)
----
-
-# Deploy to Akamai VPS Workflow
-
-Deploy OmniRoute to the Akamai VPS using `npm pack + scp` + PM2.
-
-**Akamai VPS:** `69.164.221.35`
-**Process manager:** PM2 (`omniroute`)
-**Port:** `20128`
-
-## Steps
-
-### 1. Build + pack locally
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
-```
-
-### 2. Copy to Akamai VPS and install
-
-// turbo-all
-
-```bash
-scp omniroute-*.tgz root@69.164.221.35:/tmp/
-```
-
-```bash
-ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Akamai done'"
-```
-
-### 3. Verify the deployment
-
-```bash
-curl -s -o /dev/null -w 'AKAMAI HTTP %{http_code}\n' http://69.164.221.35:20128/
-```

.claude/commands/deploy-vps-both-cc.md

@@ -1,49 +0,0 @@
----
-description: Deploy the latest OmniRoute code to BOTH the Akamai VPS and the Local VPS
----
-
-# Deploy to VPS (Both) Workflow
-
-Deploy OmniRoute to the production VPSs using `npm pack + scp` + PM2.
-
-**Akamai VPS:** `69.164.221.35`
-**Local VPS:** `192.168.0.15`
-**Process manager:** PM2 (`omniroute`)
-**Port:** `20128`
-**PM2 entry:** `/usr/lib/node_modules/omniroute/app/server.js`
-
-> [!IMPORTANT]
-> The npm registry rejects packages > 100MB, so deployment uses **npm pack + scp**.
-
-## Steps
-
-### 1. Build + pack locally
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
-```
-
-### 2. Copy to both VPS and install
-
-// turbo-all
-
-```bash
-scp omniroute-*.tgz root@69.164.221.35:/tmp/ && scp omniroute-*.tgz root@192.168.0.15:/tmp/
-```
-
-```bash
-ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Akamai done'"
-```
-
-```bash
-ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
-```
-
-### 3. Verify the deployment
-
-```bash
-curl -s -o /dev/null -w 'AKAMAI HTTP %{http_code}\n' http://69.164.221.35:20128/
-curl -s -o /dev/null -w 'LOCAL HTTP %{http_code}\n' http://192.168.0.15:20128/
-```

.claude/commands/deploy-vps-local-cc.md

@@ -1,39 +0,0 @@
----
-description: Deploy the latest OmniRoute code to the Local VPS (192.168.0.15)
----
-
-# Deploy to Local VPS Workflow
-
-Deploy OmniRoute to the Local VPS using `npm pack + scp` + PM2.
-
-**Local VPS:** `192.168.0.15`
-**Process manager:** PM2 (`omniroute`)
-**Port:** `20128`
-
-## Steps
-
-### 1. Build + pack locally
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
-```
-
-### 2. Copy to Local VPS and install
-
-// turbo-all
-
-```bash
-scp omniroute-*.tgz root@192.168.0.15:/tmp/
-```
-
-```bash
-ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
-```
-
-### 3. Verify the deployment
-
-```bash
-curl -s -o /dev/null -w 'LOCAL HTTP %{http_code}\n' http://192.168.0.15:20128/
-```

.claude/commands/generate-release-cc.md

@@ -1,362 +0,0 @@
----
-description: Create a new release, bump version up to the .10 patch threshold, update changelog, and manage Pull Requests
----
-
-# Generate Release Workflow
-
-Bump version, finalize CHANGELOG, commit, open a **PR to main** and wait for user confirmation before tagging, publishing, and deploying.
-
-> **VERSION RULE: Always use PATCH bumps (3.x.y → 3.x.y+1)**
-> NEVER use `npm version minor` or `npm version major`.
-> Always use: `npm version patch --no-git-tag-version`
-> The threshold rule: when `y` reaches 10, bump to `3.(x+1).0` — e.g. `3.8.10` → `3.9.0`.
-
-> **🔴 SINGLE BRANCH RULE**: The `release/vX.Y.Z` branch is the **ONLY** development branch for the entire release cycle. ALL work — bug fixes, feature implementations, PR integrations, issue resolutions — MUST be committed directly on this branch. Never create separate `fix/`, `feat/`, or topic branches. When running `/resolve-issues`, `/implement-features`, or `/review-prs`, always work on the current release branch.
-
----
-
-## ⚠️ Two-Phase Flow
-
-```
-Phase 1 (automated): bump → docs → i18n → commit → push → open PR
-  ↕  🛑 STOP: Notify user, wait for PR confirmation
-Phase 2 (post-merge): tag → publish → GitHub release → Docker → deploy
-```
-
-**NEVER push directly to main or create tags before the user confirms the PR.**
-
----
-
-## Phase 0: Security Verification (MANDATORY)
-
-Before creating the release, you must ensure the codebase and supply chain are secure and free of known vulnerabilities.
-
-1. **Run Local Dependencies Audit:**
-
-   ```bash
-   npm audit
-   ```
-
-   _Fix any `high` or `critical` vulnerabilities identified._
-
-2. **Check GitHub CodeQL & Dependabot Alerts:**
-   Navigate to the repository's **Security** tab on GitHub, or use the project's `vulnerability-scanner` skill to analyze active alerts. Ensure all static analysis findings (e.g., prototype pollution, insecure randomness, ReDoS, shell injections) are addressed and logically committed on a target branch.
-
----
-
-## Phase 1: Pre-Merge
-
-### 1. Create release branch
-
-```bash
-git checkout -b release/v3.x.y
-```
-
-### 2. Determine and sync version
-
-Check current version in `package.json`:
-
-```bash
-grep '"version"' package.json
-```
-
-> **🔴 BRANCH-VERSION PARITY RULE**: The logical version in `package.json` MUST exactly match the release branch name. For example, if you are on `release/v3.7.0`, the version in `package.json` MUST be `3.7.0`.
->
-> - If this is the FIRST time generating a release for a new minor/major branch (e.g., bumping from 3.6.9 to 3.7.0), you MUST ensure the version is bumped to match the new branch logic.
-> - If you are just bumping a patch on the current branch (e.g., 3.6.9 to 3.6.10), use:
->   `npm version patch --no-git-tag-version`
-
-> **⚠️ ATOMIC COMMIT RULE — Version bump MUST happen before committing feature files.**
->
-> **CORRECT order:**
->
-> 1. `npm version patch --no-git-tag-version` ← bump first
-> 2. implement features / fix bugs
-> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
->
-> **OR if features are already staged:**
->
-> 1. implement features (do NOT commit yet)
-> 2. `npm version patch --no-git-tag-version` ← bump before committing
-> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
->
-> **NEVER do this (creates version mismatch in git history):**
->
-> - ~~commit features → then bump version → commit package.json separately~~
->
-> This ensures that `git show v3.x.y` always contains both code changes and the version bump together.
-> The GitHub release tag will point to a commit that includes ALL changes for that version.
-
-### 3. Regenerate lock file (REQUIRED after version bump)
-
-**Mandatory** — skipping causes `@swc/helpers` lock mismatch and CI failures:
-
-```bash
-npm install
-```
-
-### 4. Finalize CHANGELOG.md
-
-> **🔴 NO MIXUPS RULE**: Ensure you do NOT mix the backlog of the previous version with the new one. The new version section must ONLY contain the features and fixes for the current release.
-
-Replace the `[Unreleased]` header with the new version and date.
-Keep an empty `## [Unreleased]` section above it, separated by a horizontal rule (`---`).
-
-```markdown
-## [Unreleased]
-
----
-
-## [3.7.0] — 2026-04-19
-
-### ✨ New Features
-
-- ...
-
-### 🐛 Bug Fixes
-
-- ...
-
----
-
-## [3.6.9] — 2026-04-19
-```
-
-### 5. Update openapi.yaml version ⚠️ MANDATORY
-
-> **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/reference/openapi.yaml
-echo "✓ openapi.yaml → $VERSION"
-
-for dir in electron open-sse; do
-  if [ -d "$dir" ] && [ -f "$dir/package.json" ]; then
-    (cd "$dir" && npm version "$VERSION" --no-git-tag-version --allow-same-version > /dev/null)
-    echo "✓ $dir/package.json → $VERSION"
-  fi
-done
-# Re-run install to assert the workspace lockfile is updated
-npm install
-```
-
-### 6. Update README.md and i18n docs
-
-Manually perform these documentation updates (there is no `/update-docs` slash command — it was deprecated in v3.8):
-
-- 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/<AREA>.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
-
-// turbo
-
-```bash
-npm test
-```
-
-All tests must pass before creating the PR.
-
-### 8. Stage, commit, and push
-
-// turbo-all
-
-```bash
-git add -A
-git commit -m "chore(release): v3.x.y — summary of changes"
-git push origin release/v3.x.y
-```
-
-### 9. Open PR to main
-
-### 9. Open PR to main
-
-// turbo
-
-```bash
-VERSION=$(node -p "require('./package.json').version")
-
-# Extract the exact changelog entry for this version from the root CHANGELOG.md
-awk "/^## \\[$VERSION\\]/{flag=1; print; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md > /tmp/changelog_body.txt
-
-# Append test status and next steps
-echo "" >> /tmp/changelog_body.txt
-echo "### Tests" >> /tmp/changelog_body.txt
-echo "- All tests pass" >> /tmp/changelog_body.txt
-echo "" >> /tmp/changelog_body.txt
-echo "### ⚠️ After merging: run Phase 2 steps to tag, publish, and deploy." >> /tmp/changelog_body.txt
-
-gh pr create \
-  --repo diegosouzapw/OmniRoute \
-  --base main \
-  --head release/v$VERSION \
-  --title "Release v$VERSION" \
-  --body-file /tmp/changelog_body.txt
-```
-
-### 10. 🛑 STOP — Notify User & Await PR Confirmation
-
-**This is a mandatory stop point.** Present the report in the final response and stop. Do not continue to the next phase until the user explicitly approves.
-
-Inform the user:
-
-- PR URL
-- Summary of changes
-- Test results
-- List of files changed
-
-**DO NOT proceed to Phase 2 until the user confirms the PR looks good and merges it.**
-
----
-
-## Phase 2: Post-Merge Validation (Local VPS)
-
-> Run these steps only AFTER the user has merged the PR into `main` and all CI jobs have passed.
-
-### 11. Deploy to Local VPS for Final Validation (MANDATORY)
-
-Before cutting the official git tag and publishing to the world, deploy the `main` branch to the Local VPS for a final homologation test.
-
-```bash
-git checkout main
-git pull origin main
-
-# Build and pack locally
-cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
-
-# Deploy to LOCAL VPS (192.168.0.15)
-scp omniroute-*.tgz root@192.168.0.15:/tmp/
-ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
-
-# Verify
-curl -s -o /dev/null -w "LOCAL:  HTTP %{http_code}\n" http://192.168.0.15:20128/
-```
-
-### 12. 🛑 STOP — Notify User & Await Final OK
-
-**This is a mandatory stop point.**
-Inform the user that the `main` branch is now running on the Local VPS.
-Wait for the user to manually test and give the **OK**.
-**DO NOT proceed to Phase 3 until the user confirms the local deploy is stable.**
-
----
-
-## Phase 3: Official Launch
-
-> Run these steps only AFTER the user gives the final OK from the Phase 2 local validation.
-
-### 13. Create Git Tag and GitHub Release (MANDATORY)
-
-// turbo
-
-```bash
-git checkout main
-git pull origin main
-VERSION=$(node -p "require('./package.json').version")
-
-# Extracts the changelog section for this version
-NOTES=$(awk "/^## \\[$VERSION\\]/{flag=1; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
-if [ -z "$NOTES" ]; then NOTES="OmniRoute v$VERSION Release"; fi
-
-git tag -a "v$VERSION" -m "Release v$VERSION"
-git push origin "v$VERSION"
-gh release create "v$VERSION" --repo diegosouzapw/OmniRoute --title "v$VERSION" --notes "$NOTES" --target main || gh release edit "v$VERSION" --repo diegosouzapw/OmniRoute --title "v$VERSION" --notes "$NOTES"
-```
-
-### 14. 🐳 Trigger Docker Hub build (MANDATORY — keep npm and Docker in sync)
-
-> **CRITICAL**: Docker Hub and npm MUST always publish the same version.
-> The Docker image is built automatically via GitHub Actions when a new tag is pushed.
-> After pushing the tag in step 13, **verify the workflow runs**:
-
-```bash
-# Verify the Docker workflow triggered
-gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 3
-
-# Wait for the Docker build to complete (usually 5–10 min)
-gh run watch --repo diegosouzapw/OmniRoute
-```
-
-### 15. Publish to NPM (Optional/Automated)
-
-Normally handled by CI, but if manual publish is required:
-
-```bash
-npm publish
-```
-
-### 16. Deploy to AKAMAI VPS (Production)
-
-Now that the release is officially cut, deploy it to the Akamai VPS.
-
-```bash
-# Deploy to AKAMAI VPS (69.164.221.35)
-scp omniroute-*.tgz root@69.164.221.35:/tmp/
-ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Akamai done'"
-
-# Verify
-curl -s -o /dev/null -w "AKAMAI: HTTP %{http_code}\n" http://69.164.221.35:20128/
-```
-
-## Phase 4: Release Monitoring & Artifact Validation
-
-> After triggering the official release, actively monitor the CI pipelines until all artifacts are successfully generated. If any pipeline fails, stop and apply the necessary corrections before continuing.
-
-### 18. Monitor CI Pipelines
-
-Wait for and verify the successful completion of the following automated jobs:
-
-1. **Docker Hub Publish**
-2. **Electron Build**
-3. **NPM Registry Publish** (Check with `npm info omniroute version`)
-
-```bash
-# Monitor Docker Hub workflow
-gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 1
-gh run watch <RUN_ID>
-
-# Monitor Electron build
-gh run list --repo diegosouzapw/OmniRoute --workflow electron-release.yml --limit 1
-gh run watch <RUN_ID>
-
-# Verify NPM version
-npm info omniroute version
-```
-
-### 19. Handle Failures (If Any)
-
-If a workflow fails:
-
-- Use `gh run view <RUN_ID> --log-failed` to identify the error.
-- Apply the fix on the `main` branch.
-- If necessary, re-trigger the workflow using `gh workflow run <workflow_name.yml> --repo diegosouzapw/OmniRoute --ref v3.x.y`
-
-### 20. Preserve release branch
-
-```bash
-# Branch is kept for historical purposes. Do not delete.
-```
-
----
-
-## Notes
-
-- Ensure CHANGELOG, README and `docs/*` are current BEFORE this workflow — run `npm run check:docs-all` and `/version-bump` first (there is no `/update-docs` slash command anymore)
-- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`
-- After npm publish, verify with `npm info omniroute version`
-- Lock file sync errors are caused by skipping `npm install` after version bump
-- Use `gh auth switch -u diegosouzapw` if git push fails with wrong account
-
-## Known CI Pitfalls
-
-| 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              |

.claude/commands/implement-features-cc.md

@@ -1,706 +0,0 @@
----
-description: Analyze open feature request issues, implement viable ones on dedicated branches, and respond to authors
----
-
-# /implement-features — Feature Request Harvest, Research & Implementation Workflow
-
-## Overview
-
-A **5-phase** workflow that systematically harvests feature requests from GitHub issues, creates structured idea files, researches solutions across the internet and Git repositories, presents a consolidated report for user approval, then generates detailed implementation plans and executes them.
-
-**Output directory structure:**
-
-```
-_ideia/
-├── viable/                  # Features approved for implementation
-│   ├── need_details/        # ❓ Good idea but waiting for author clarification (issues stay OPEN)
-│   │   └── 1015-warp-terminal-mitm.md
-│   ├── 1046-native-playground.md           # ✅ Ready — researched and planned
-│   └── 1046-native-playground.requirements.md
-├── defer/                   # ⏭️ Good ideas deferred for future cycles (issues CLOSED)
-│   └── 1041-smart-auto-combos.md
-└── notfit/                  # ❌ Out of scope / already exists (issues CLOSED)
-    └── 945-telegram-integration.md
-
-_tasks/features-vX.Y.Z/   # Implementation plans (per-release)
-└── 1046-native-playground.plan.md
-```
-
-> **LIFECYCLE RULE:** `viable/` files are **DELETED** once the feature is implemented — they are not moved. Only unimplemented features live in `viable/` (or `viable/need_details/`). Files in `defer/` and `notfit/` remain as permanent reference.
-
-> **BRANCH RULE**: All implementation work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `feat/` branches. If no release branch exists yet, create one first using `/generate-release` Phase 1 steps 1–5.
-
----
-
-## Phase 1 — Harvest: Collect & Catalog Feature Ideas
-
-### 1.1 Identify the Repository
-
-// turbo
-
-- Run: `git -C <project_root> remote get-url origin` to extract owner/repo.
-
-### 1.2 Ensure Release Branch Exists
-
-// turbo
-
-Before doing any work, ensure you are on the current release branch:
-
-```bash
-# Check current branch
-git branch --show-current
-
-# If on main, determine next version and create the release branch
-VERSION=$(node -p "require('./package.json').version")
-NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
-git checkout -b release/v$NEXT
-npm version patch --no-git-tag-version
-npm install
-```
-
-If already on a `release/vX.Y.Z` branch, continue working there.
-
-### 1.3 Fetch ALL Open Feature Requests
-
-// turbo-all
-
-**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. You MUST use the two-step approach below.
-
-**Step 1 — Get Issue numbers only** (small output, never truncated):
-
-```bash
-# Fetch issues with feature/enhancement labels
-gh issue list --repo <owner>/<repo> --state open -l "enhancement" --limit 500 --json number --jq '.[].number'
-
-# Also check for [Feature] in title (common pattern when no labels are set)
-gh issue list --repo <owner>/<repo> --state open --limit 500 --json number,title --jq '.[] | select(.title | test("\\[Feature\\]|\\[feature\\]|feature request"; "i")) | .number'
-```
-
-- Merge both lists, deduplicate. Count and confirm the total.
-
-**Step 2 — Fetch full metadata for each Issue** (one call per issue):
-
-```bash
-gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author,assignees
-```
-
-- Read the **entire body** — including description, use cases, screenshots, mockups, and any embedded images.
-- Read **ALL comments** — community discussion, agreements, restrictions, owner responses, and linked PRs.
-- **Images**: If the body or comments contain image URLs (`![...](...)` or `https://...png/jpg/gif`), note them — they may contain UI mockups, wireframes, or architecture diagrams that are essential to understanding the request.
-- You may batch these into parallel calls (up to 4 at a time).
-- Sort by oldest first (FIFO).
-
-### 1.4 Create Idea Files (initially in `_ideia/` root)
-
-For each feature request, create a structured idea file in `<project_root>/_ideia/`:
-
-**Filename convention**: `<NUMBER>-<kebab-case-short-title>.md`
-Example: `1046-native-playground.md`, `1041-smart-auto-combos.md`
-
-#### 1.4a — If the idea file does NOT exist yet, create it:
-
-```markdown
-# Feature: <Title from Issue>
-
-> GitHub Issue: #<NUMBER> — opened by @<author> on <date>
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-<Paste the FULL issue body here, preserving all formatting, images, and code blocks>
-
-## 💬 Community Discussion
-
-<Summarize ALL comments chronologically, noting who said what and any decisions or objections raised>
-
-### Participants
-
-- @<author> — Original requester
-- @<commenter1> — <brief role/opinion>
-- ...
-
-### Key Points
-
-- <bullet list of the most important discussion points>
-- <agreements reached>
-- <objections raised>
-
-## 🎯 Refined Feature Description
-
-<YOUR interpretation and enrichment of the feature request. Expand on what was asked, fill in logical gaps, provide concrete examples of how it would work. This section should be MORE detailed and clearer than the original request.>
-
-### What it solves
-
-- <problem 1>
-- <problem 2>
-
-### How it should work (high level)
-
-1. <step 1>
-2. <step 2>
-3. ...
-
-### Affected areas
-
-- <list of codebase areas, modules, files likely affected>
-
-## 📎 Attachments & References
-
-- <any image URLs, mockup links, or external references from the issue>
-
-## 🔗 Related Ideas
-
-- <links to related \_ideia/ files if any overlap found>
-```
-
-#### 1.4b — If the idea file ALREADY exists, update it:
-
-- Append new comments from the issue to the **Community Discussion** section.
-- Update the **Refined Feature Description** if new information changes the understanding.
-- Add any new **Related Ideas** cross-references found.
-- **Do NOT overwrite** existing content — append and enrich it.
-
-### 1.5 Cross-Reference & Deduplication
-
-After processing all issues:
-
-- Scan all `_ideia/*.md` files for overlapping features.
-- If two features are substantially the same, add `🔗 Related Ideas` cross-references to both.
-- If one is a strict subset of another, note it in the smaller file: `> ℹ️ This feature is a subset of #<OTHER_NUMBER>. Consider implementing together.`
-
----
-
-## Phase 2 — Research: Find Solutions & Build Requirements
-
-For each cataloged idea that is **viable** (aligns with the project's goals):
-
-### 2.1 Viability Pre-Check
-
-Before investing in research, quickly assess:
-
-- [ ] Does this feature align with the project's goals and architecture?
-- [ ] Is it technically feasible with the current codebase?
-- [ ] Does it duplicate existing functionality?
-- [ ] Would it introduce breaking changes or security risks?
-- [ ] Is there enough detail to understand what's needed?
-
-**Verdict options:**
-
-| Verdict               | When                                  | Action                      |
-| --------------------- | ------------------------------------- | --------------------------- |
-| ✅ **VIABLE**         | Good idea, enough context             | Proceed to Research         |
-| ❓ **NEEDS DETAIL**   | Good idea, insufficient spec          | Skip research, ask author   |
-| ⏭️ **DEFER**          | Good idea, too complex for this cycle | Catalog only, skip research |
-| ❌ **NOT FIT**        | Doesn't fit the project               | Explain why                 |
-| 🔁 **ALREADY EXISTS** | Feature already implemented           | Point to existing feature   |
-
-### 2.2 Internet Research (for VIABLE features)
-
-For each viable feature, perform systematic research:
-
-**Step 1 — Web search for similar implementations:**
-
-```
-WebSearch("how to implement <feature description> in <tech stack>")
-WebSearch("<feature keyword> implementation nextjs typescript 2025 2026")
-WebSearch("<feature keyword> open source library npm")
-```
-
-**Step 2 — Find reference Git repositories:**
-
-```
-WebSearch("site:github.com <feature keyword> <tech stack> stars:>100")
-WebSearch("github <feature keyword> implementation recently updated 2026")
-```
-
-- Find **up to 10 relevant repositories**, sorted by most recently updated.
-- For each repository:
-  - Note the repo URL, star count, last commit date
-  - Read its README and relevant source files via `WebFetch`
-  - Extract the architectural approach, patterns used, and key code snippets
-
-**Step 3 — Read API docs and standards:**
-
-If the feature involves an external API, protocol, or standard:
-
-- Find and read the official documentation
-- Note version requirements, authentication patterns, rate limits
-
-### 2.3 Create Requirements File
-
-For each researched feature, create a requirements file alongside its idea file:
-
-**Filename**: `<NUMBER>-<kebab-case-short-title>.requirements.md`
-
-```markdown
-# Requirements: <Feature Title>
-
-> Feature Idea: [#<NUMBER>](./<NUMBER>-<kebab-case-short-title>.md)
-> Research Date: <YYYY-MM-DD>
-> Verdict: ✅ VIABLE
-
-## 🔍 Research Summary
-
-<Brief summary of what was found during research>
-
-## 📚 Reference Implementations
-
-| #   | Repository       | Stars | Last Updated | Approach | Relevance    |
-| --- | ---------------- | ----- | ------------ | -------- | ------------ |
-| 1   | [repo/name](url) | ⭐ N  | YYYY-MM-DD   | <brief>  | High/Med/Low |
-| 2   | ...              |       |              |          |              |
-
-### Key Patterns Found
-
-- <pattern 1 with code snippet or link>
-- <pattern 2>
-
-## 📐 Proposed Solution Architecture
-
-### Approach
-
-<Describe the chosen approach based on research findings>
-
-### New Files
-
-| File                  | Purpose       |
-| --------------------- | ------------- |
-| `path/to/new/file.ts` | <description> |
-
-### Modified Files
-
-| File                       | Changes        |
-| -------------------------- | -------------- |
-| `path/to/existing/file.ts` | <what changes> |
-
-### Database Changes
-
-- <migrations needed, if any>
-
-### API Changes
-
-- <new/modified endpoints, if any>
-
-### UI Changes
-
-- <new/modified pages/components, if any>
-
-## ⚙️ Implementation Effort
-
-- **Estimated complexity**: Low / Medium / High / Very High
-- **Estimated files changed**: ~N
-- **Dependencies needed**: <new npm packages, if any>
-- **Breaking changes**: Yes/No — <details>
-- **i18n impact**: <number of new translation keys>
-- **Test coverage needed**: <brief description>
-
-## ⚠️ Open Questions
-
-- <question 1>
-- <question 2>
-
-## 🔗 External References
-
-- <documentation URLs>
-- <API references>
-```
-
----
-
-## Phase 2.5 — Organize & Respond: Sort Files and Post GitHub Comments
-
-### 2.5.1 Create Directory Structure
-
-// turbo
-
-```bash
-mkdir -p <project_root>/_ideia/viable
-mkdir -p <project_root>/_ideia/viable/need_details
-mkdir -p <project_root>/_ideia/defer
-mkdir -p <project_root>/_ideia/notfit
-```
-
-### 2.5.2 Move Idea Files to Category Subdirectories
-
-After classification, move EVERY idea file to its correct subdirectory:
-
-```bash
-# ✅ VIABLE — move idea + requirements files
-mv _ideia/<NUMBER>-*.md _ideia/viable/
-mv _ideia/<NUMBER>-*.requirements.md _ideia/viable/
-
-# ❓ NEEDS DETAIL — viable but waiting for author response
-mv _ideia/<NUMBER>-*.md _ideia/viable/need_details/
-
-# ⏭️ DEFER — move idea files only
-mv _ideia/<NUMBER>-*.md _ideia/defer/
-
-# ❌ NOT FIT & 🔁 ALREADY EXISTS — move idea files only
-mv _ideia/<NUMBER>-*.md _ideia/notfit/
-```
-
-No files should remain in `_ideia/` root after this step (except subdirectories).
-
-### 2.5.3 Post GitHub Comments by Category
-
-**Each category has a specific comment template and action:**
-
----
-
-#### For 🔁 ALREADY EXISTS — Comment + CLOSE issue
-
-// turbo
-
-The feature already exists in the system. Explain WHERE it is and HOW to use it.
-
-```markdown
-Hi @<author>! Thanks for the suggestion! 🙏
-
-Great news — this functionality **already exists** in OmniRoute:
-
-**📍 Where to find it:** <exact dashboard path or settings location>
-
-**🔧 How to use it:**
-
-1. <step 1>
-2. <step 2>
-3. <step 3>
-
-If you have any trouble finding or using it, feel free to ask in a Discussion. We're always happy to help!
-
-Closing this as the feature is already available. 🎉
-```
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
-```
-
----
-
-#### For ⏭️ DEFER — Comment + CLOSE issue
-
-// turbo
-
-Thank the user, explain the idea was cataloged, and that we'll study it before implementing.
-
-```markdown
-Hi @<author>! Thanks for this thoughtful feature request! 🙏
-
-We really appreciate the detailed proposal. We've **cataloged your idea** and it's now part of our improvement backlog.
-
-Due to the **significant architectural impact** of this feature, we'll need to conduct thorough use-case studies and architectural analysis before we start development. This ensures we build it right and don't introduce regressions.
-
-**What happens next:**
-
-- Your idea is saved in our internal feature backlog
-- We'll conduct architecture studies when this area is prioritized
-- We'll notify you here when development begins
-
-Thank you for contributing to OmniRoute's roadmap! Your input helps shape the product. 🚀
-```
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
-```
-
----
-
-#### For ❌ NOT FIT — Comment + CLOSE issue
-
-// turbo
-
-Politely explain why the feature doesn't fit the project scope.
-
-```markdown
-Hi @<author>! Thanks for the suggestion! 🙏
-
-After careful analysis, we've determined that this feature **falls outside OmniRoute's core scope** as a proxy/router.
-
-**Reason:** <explain why — e.g., "Telegram integration belongs in the application/orchestrator layer that consumes OmniRoute's API, not inside the router itself.">
-
-**Alternative:** <suggest an alternative approach if possible>
-
-We appreciate you thinking of ways to improve OmniRoute! If you'd like to discuss this further, feel free to open a Discussion. 🙏
-```
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
-```
-
----
-
-#### For ❓ NEEDS DETAIL — Comment (keep OPEN)
-
-// turbo
-
-Ask for the specific missing details needed.
-
-```markdown
-Hi @<author>! Thanks for the feature request — it's an interesting idea and we'd love to explore it further. 🙏
-
-To move forward, we need a few more details:
-
-1. <specific question 1>
-2. <specific question 2>
-3. <specific question 3>
-
-If you know of any **open-source projects or repositories** that implement something similar, please share links — it would help us design the best solution.
-
-Looking forward to your response! 🚀
-```
-
----
-
-#### For ✅ VIABLE — Comment (keep OPEN)
-
-// turbo
-
-Thank the user, confirm we've cataloged their idea, and explain it may be implemented in future versions.
-
-```markdown
-Hi @<author>! Thanks for the great feature suggestion! 🙏
-
-We've analyzed your request and it aligns well with OmniRoute's roadmap. We've **cataloged this feature** and it's in our implementation backlog.
-
-**Status:** 📋 Cataloged for future implementation
-
-This feature may be included in upcoming releases. We'll **respond to this issue and tag you** as soon as implementation begins so you can test it.
-
-Thank you for helping improve OmniRoute! 🚀
-```
-
-**⚠️ Do NOT close viable issues — they remain OPEN for tracking.**
-
----
-
-## Phase 3 — Report: Present Findings to User
-
-### 3.1 🛑 MANDATORY STOP — Present Consolidated Report
-
-After completing Phase 1, Phase 2, and Phase 2.5, **STOP and present the following report** in the chat. Do NOT proceed to implementation.
-
-Present a structured report containing:
-
-#### 3.1a — Feature Summary Table
-
-| #   | Issue | Title | Verdict         | Location                      | Action                        |
-| --- | ----- | ----- | --------------- | ----------------------------- | ----------------------------- |
-| 1   | #N    | Title | ✅ VIABLE       | `_ideia/viable/`              | Issue OPEN, comment posted    |
-| 2   | #N    | Title | ⏭️ DEFER        | `_ideia/defer/`               | Issue CLOSED with explanation |
-| 3   | #N    | Title | ❌ NOT FIT      | `_ideia/notfit/`              | Issue CLOSED with explanation |
-| 4   | #N    | Title | 🔁 EXISTS       | `_ideia/notfit/`              | Issue CLOSED with guidance    |
-| 5   | #N    | Title | ❓ NEEDS DETAIL | `_ideia/viable/need_details/` | Issue OPEN, questions posted  |
-
-#### 3.1b — Viable Features Detail
-
-For each VIABLE feature, provide a brief paragraph:
-
-- What was found during research
-- The proposed approach
-- Key risks or unknowns
-- Which reference repositories were most useful
-
-#### 3.1c — Issues Requiring Author Feedback
-
-For features marked ❓ NEEDS DETAIL, list:
-
-- What specific information is missing
-- What examples or repository references would help
-
-#### 3.1d — Ask for User Confirmation
-
-End the report with:
-
-> **Ready to proceed with implementation?**
->
-> - Reply **"sim"** or **"yes"** to generate full implementation plans for all VIABLE features.
-> - Reply with specific issue numbers to select only certain features.
-> - Reply **"não"** or **"no"** to stop here.
-
----
-
-## Phase 4 — Plan: Generate Implementation Plans (after user says "yes")
-
-> **⚠️ Do NOT enter this phase without explicit user approval from Phase 3.**
-
-### 4.1 Create Task Directory
-
-```bash
-mkdir -p <project_root>/_tasks/features-vX.Y.Z/
-```
-
-### 4.2 Generate One Implementation Plan Per Feature
-
-For each VIABLE feature approved by the user, create:
-
-**Filename**: `_tasks/features-vX.Y.Z/<NUMBER>-<kebab-case-title>.plan.md`
-
-```markdown
-# Implementation Plan: <Feature Title>
-
-> Issue: #<NUMBER>
-> Idea: [\_ideia/viable/<NUMBER>-title.md](../../_ideia/viable/<NUMBER>-title.md)
-> Requirements: [\_ideia/viable/<NUMBER>-title.requirements.md](../../_ideia/viable/<NUMBER>-title.requirements.md)
-> Branch: `release/vX.Y.Z`
-
-## Overview
-
-<Brief description of what will be built>
-
-## Pre-Implementation Checklist
-
-- [ ] Read all related source files listed below
-- [ ] Confirm no conflicts with in-flight PRs
-- [ ] Verify database migration numbering
-
-## Implementation Steps
-
-### Step 1: <Title>
-
-**Files:**
-
-- `path/to/file.ts` — <what to change>
-
-**Details:**
-<Detailed description of the change, including code patterns to follow, function signatures, etc.>
-
-### Step 2: <Title>
-
-...
-
-### Step N: Tests
-
-**New test files:**
-
-- `tests/unit/<test-file>.test.mjs` — <what to test>
-
-**Test cases:**
-
-- [ ] <test case 1>
-- [ ] <test case 2>
-
-### Step N+1: i18n
-
-**Translation keys to add:**
-
-- `<namespace>.<key>` — "<English value>"
-
-### Step N+2: Documentation
-
-- [ ] Update CHANGELOG.md
-- [ ] Update relevant docs/ files
-
-## Verification Plan
-
-1. Run `npm run build` — must pass
-2. Run `npm test` — all tests must pass
-3. Run `npm run lint` — no new errors
-4. <Manual verification steps>
-
-## Commit Plan
-```
-
-feat: <description> (#<NUMBER>)
-
-```
-
-```
-
-### 4.3 Present Plans for Final Approval
-
-Present a summary of all generated plans:
-
-> **Implementation plans generated:**
->
-> | #   | Feature | Plan File                                | Steps   | Effort |
-> | --- | ------- | ---------------------------------------- | ------- | ------ |
-> | 1   | <title> | `_tasks/features-vX.Y.Z/N-title.plan.md` | N steps | Medium |
->
-> Reply **"sim"** or **"yes"** to begin implementation of all features.
-> Reply with specific issue numbers to implement only certain ones.
-
----
-
-## Phase 5 — Execute: Implement the Plans (after user says "yes")
-
-> **⚠️ Do NOT enter this phase without explicit user approval from Phase 4.**
-
-### 5.1 Implement Each Feature
-
-For each approved plan, execute it step by step:
-
-1. **Follow the plan** — implement exactly as specified in the `.plan.md` file
-2. **Build** — Run `npm run build` after each feature to verify compilation
-3. **Test** — Run `npm test` to ensure no regressions
-4. **Commit** — Commit with: `feat: <description> (#<NUMBER>)`
-5. **Update the plan** — Mark completed steps with `[x]` in the plan file
-6. **Continue** — Move to the next feature (do NOT switch branches)
-
-### 5.2 Respond to Authors (Update Viable Issues)
-
-For each implemented feature, **close the issue with a final comment**:
-
-````markdown
-✅ **Implemented in `release/vX.Y.Z`!**
-
-Hi @<author>! Great news — your feature request has been implemented! 🎉
-
-**What was done:**
-
-- <bullet list of what was built>
-
-**How to try it:**
-
-```bash
-git fetch origin && git checkout release/vX.Y.Z
-npm install && npm run dev
-```
-````
-
-This will be included in the upcoming **vX.Y.Z** release. Feel free to reopen if you spot any issues! 🚀
-
-````
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
-````
-
-Then **DELETE the idea file** — it has served its purpose:
-
-```bash
-# ✅ Implemented files are DELETED (not moved)
-rm _ideia/viable/<NUMBER>-<title>.md
-rm _ideia/viable/<NUMBER>-<title>.requirements.md  # if exists
-```
-
-> **Why delete?** `viable/` only holds features that still NEED to be done. Once implemented, the commit history and CHANGELOG are the source of truth. Keeping the file would be confusing.
-
-### 5.3 Finalize & Push
-
-After implementing all approved features:
-
-1. **Update CHANGELOG.md** on the release branch with all new feature entries
-2. Push the release branch: `git push origin release/vX.Y.Z`
-3. Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)
-
-### 5.4 Final Summary Report
-
-Present a final summary report to the user:
-
-| Issue | Title | Verdict         | Action                                             | Commit    |
-| ----- | ----- | --------------- | -------------------------------------------------- | --------- |
-| #N    | Title | ✅ Implemented  | Issue closed, idea file deleted                    | `abc1234` |
-| #N    | Title | ⏭️ Deferred     | Issue closed + saved in `_ideia/defer/`            | —         |
-| #N    | Title | ❌ Not Fit      | Issue closed + saved in `_ideia/notfit/`           | —         |
-| #N    | Title | 🔁 Exists       | Issue closed + saved in `_ideia/notfit/`           | —         |
-| #N    | Title | ❓ Needs Detail | Issue OPEN, moved to `_ideia/viable/need_details/` | —         |
-
-Include:
-
-- Total features harvested
-- Total ideas cataloged (`viable/need_details/` + `defer/` + `notfit/`)
-- Total features implemented (idea files deleted, issues closed)
-- Total features deferred
-- Total issues closed
-- Total issues left open (needs detail only — viable are closed after implementation)
-- Test results (pass/fail count)

.claude/commands/issue-triage-cc.md

@@ -1,50 +0,0 @@
----
-description: How to respond to GitHub issues with insufficient information
----
-
-# Issue Triage Workflow
-
-Respond to GitHub issues that need more information before they can be investigated.
-
-## Steps
-
-### 1. Identify issues needing triage
-
-```bash
-gh issue list --state open --limit 20
-```
-
-### 2. Evaluate each issue
-
-Check if the issue has:
-
-- Clear reproduction steps
-- Environment details (OS, Node.js version, OmniRoute version)
-- Error logs/screenshots
-- Expected vs actual behavior
-
-### 3. Respond with triage template
-
-For issues missing information:
-
-```markdown
-Thank you for reporting this issue! To help us investigate, please provide:
-
-1. **OmniRoute version**: (`omniroute --version`)
-2. **Node.js version**: (`node --version`)
-3. **Operating system**: (e.g., Ubuntu 24.04, macOS 15, Windows 11)
-4. **Installation method**: (npm, Docker, source)
-5. **Steps to reproduce**: (exact commands/actions that trigger the issue)
-6. **Error logs**: (paste relevant logs from the console)
-7. **Expected behavior**: (what should happen)
-
-This will help us debug and resolve your issue faster. 🙏
-```
-
-### 4. Label the issue
-
-Add appropriate labels: `needs-info`, `bug`, `enhancement`, `question`, etc.
-
-```bash
-gh issue edit <NUMBER> --add-label "needs-info"
-```

.claude/commands/resolve-issues-cc.md

@@ -1,166 +0,0 @@
----
-description: Fetch all open GitHub issues, analyze bugs, resolve what's possible, triage the rest, wait for user validation, then commit and release
----
-
-# /resolve-issues — Automated Issue Resolution Workflow
-
-## Overview
-
-This workflow fetches all open issues from the project's GitHub repository, classifies them, analyzes bugs, proposes a resolution plan, waits for user validation, and ONLY THEN implements the fixes, commits, and closes the issues on the current release branch (`release/vX.Y.Z`). It does NOT merge or release automatically — the release branch is later merged via PR to main.
-
-> **BRANCH RULE**: All work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `fix/` branches. If no release branch exists yet, create one first using `/generate-release` Phase 1 steps 1–5.
-
-> **⛔ PR PROHIBITION**: If a fix is associated with a contributor's PR, you MUST merge their PR — NEVER close it and re-implement the fix yourself. See `/review-prs` workflow for the full policy. The `gh pr close` command is FORBIDDEN unless the repository owner explicitly requests it.
-
-## Steps
-
-### 1. Identify the GitHub Repository
-
-// turbo
-
-- Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
-- Parse the owner and repo name from the URL
-
-### 2. Ensure Release Branch Exists
-
-// turbo
-
-Before doing any work, ensure you are on the current release branch:
-
-```bash
-# Check current branch
-git branch --show-current
-
-# If on main, determine next version and create the release branch
-VERSION=$(node -p "require('./package.json').version")
-NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
-git checkout -b release/v$NEXT
-npm version patch --no-git-tag-version
-npm install
-```
-
-If already on a `release/vX.Y.Z` branch, continue working there.
-
-### 3. Fetch All Open Issues
-
-// turbo-all
-
-**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. You MUST use the two-step approach below to guarantee **all** issues are fetched.
-
-**Step 3a — Get Issue numbers only** (small output, never truncated):
-
-- Run: `gh issue list --repo <owner>/<repo> --state open --limit 500 --json number --jq '.[].number'`
-- This outputs one issue number per line. Count them and confirm total.
-
-**Step 3b — Fetch full metadata for each Issue** (one call per issue):
-
-- For each issue number from step 3a, run:
-  `gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author`
-- You may batch these into parallel calls (up to 4 at a time).
-- Sort by oldest first (FIFO).
-
-### 4. Classify Each Issue
-
-For each issue, determine its type:
-
-- **Bug** — Has `bug` label, or body contains error messages, stack traces, "doesn't work", "broken", "crash", "error"
-- **Feature Request** — Has `enhancement`/`feature` label, or body describes new functionality
-- **Question** — Has `question` label, or is asking "how to" something
-- **Other** — Anything else
-
-Focus ONLY on **Bugs** for resolution. Feature requests and questions should be skipped with a note in the final report.
-
-### 5. Deep-Read Each Bug Issue (One-by-One Analysis)
-
-**IMPORTANT**: Read each bug issue thoroughly, one at a time, before moving to the next. This is NOT a batch process — each issue needs focused attention.
-
-#### 5a. Understand the Problem
-
-For each bug issue, perform the full analysis:
-
-1. **Read the entire body** — including Description, Steps to Reproduce, Expected/Actual Behavior, Error Logs, and Screenshots
-2. **Read ALL comments** — including bot triage comments (Kilo, etc.) and owner/community responses. Pay attention to:
-   - Whether someone already responded with a fix
-   - Whether a community member confirmed the issue is resolved
-   - Whether the issue was marked as duplicate by a bot. **WARNING: DO NOT blindly trust bot duplicate labels (e.g., kilo-duplicate). Bots make mistakes. You MUST read the full conversation and do your own independent analysis to determine if it is truly a duplicate or a distinct bug.**
-3. **Identify the claimed error** — extract the exact error message, status code, and provider/model involved
-
-#### 5b. Check Information Sufficiency
-
-Verify the issue contains enough to act on:
-
-- [ ] Clear description of the problem
-- [ ] Steps to reproduce OR error logs
-- [ ] Provider/model/version information
-- [ ] Expected vs actual behavior
-
-#### 5c. Determine Issue Disposition
-
-For each bug, classify into one of 5 actions:
-
-| Disposition                  | When to Apply                                                                                                          | Action                                                  |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| **✅ CLOSE — Already Fixed** | Owner responded with fix + no user follow-up, OR community confirmed fix                                               | Close with comment citing which version fixed it        |
-| **✅ CLOSE — Duplicate**     | You have independently verified the issue is a duplicate (do NOT rely solely on bot flags) + user provides no new info | Close referencing the original issue                    |
-| **✅ CLOSE — Stale**         | We requested logs/info > 7 days ago with no reply                                                                      | Close thanking the user, invite to reopen if needed     |
-| **📝 RESPOND — Needs Info**  | Issue is real but missing critical reproduction details                                                                | Comment asking for specifics per `/issue-triage`        |
-| **📝 RESPOND — User Config** | Error is caused by unsupported env (Node version, wrong model path, missing API enablement)                            | Comment explaining the user-side fix                    |
-| **🔧 FIX — Code Change**     | Root cause is confirmed in the codebase                                                                                | Research, propose solution in report, wait for approval |
-
-#### 5d. For "FIX — Code Change" Issues
-
-Before coding, perform deep source analysis to formulate a plan:
-
-1. **Search the codebase** — `grep_search` for error strings, relevant function names, affected files
-2. **Search the web** — for upstream API changes, SDK updates, or breaking changes that explain the bug
-3. **Read the full source file** — don't rely on grep snippets; understand the surrounding logic
-4. **Verify the root cause** — confirm the bug is reproducible based on the code, not just a user misconfiguration
-5. **Formulate a proposed solution** — detail the exact files and lines you will change and how you will solve it.
-6. **Create an Implementation Plan file** — write your proposed solution to `_tasks/features-vX.Y.Z/<ISSUE_NUMBER>-<short-description>.plan.md` (e.g. `_tasks/features-v3.7.6/1810-auto-restore-probe-failed-db.plan.md`) where `vX.Y.Z` is the current branch version. The plan should contain an Overview, Pre-Implementation Checklist, and detailed Implementation Steps (Files, Changes).
-7. **DO NOT modify the codebase yet** — wait for user approval on your report and plan first.
-
-#### 5e. For "RESPOND" Issues
-
-Post a substantive comment that:
-
-- Acknowledges the specific error they reported
-- Explains the likely root cause
-- Provides concrete steps to resolve (version upgrade, env var fix, model path correction)
-- Asks for follow-up info if needed
-
-**Do NOT post generic template responses.** Every comment should reference the user's specific error messages and environment.
-
-### 6. Generate Report & Wait for Validation
-
-Present a summary report to the user detailing your proposed actions. For any bugs that need fixing, explicitly explain your proposed solution (files to change and logic) and point out that it will be implemented on the release branch (`release/vX.Y.Z`) after approval.
-
-| Issue | Title | Status        | Proposed Action / Version                 |
-| ----- | ----- | ------------- | ----------------------------------------- |
-| #N    | Title | ✅ Close      | Already fixed / duplicate (explain why)   |
-| #N    | Title | 🔧 Propose    | Explanation of the code fix to be applied |
-| #N    | Title | 📝 Respond    | Guidance comment to be posted             |
-| #N    | Title | ❓ Needs Info | Triage comment to be posted               |
-| #N    | Title | ⏭️ Skip       | Feature request / not a bug               |
-
-> **⚠️ IMPORTANT**: Do NOT implement code changes, commit, push, or close issues at this step.
-> Wait for the user to review the proposed fixes and respond with **OK** before proceeding.
-
-- If the user says **OK** or approves → Proceed to step 7
-- If the user requests changes → Adjust the proposed solution and present the report again
-- If the user rejects → Revert any accidental changes and stop
-
-### 7. Implement Fixes, Run Tests & Commit (only after user approval)
-
-After the user validates and gives the OK:
-
-1. **Implement the fixes** — modify the codebase according to the approved plan.
-2. **Run tests** — `npm run test:all` (or the specific test file) to ensure 100% pass.
-3. **Update CHANGELOG.md** with all new bug fix entries.
-4. **Commit** each fix individually on the release branch with message format: `fix: <description> (#<issue_number>)`.
-5. **Push** the release branch: `git push origin release/vX.Y.Z`.
-6. **Close resolved issues immediately**. For each issue that was marked as Fixed, run:
-   `gh issue close <NUMBER> --repo <owner>/<repo> --comment "Thank you for reporting! This issue has been fixed and will be included in the next release (vX.Y.Z)."`
-7. Likewise, close `Duplicate` issues referencing the original, close `Needs Info` if stale, and post the required comments.
-8. If the project runs automatic releases or needs a PR, proceed to run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user).
-
-If NO fixes were committed, skip closing and source control steps and just conclude the workflow.

.claude/commands/review-discussions-cc.md

@@ -1,120 +0,0 @@
----
-description: Read all open GitHub Discussions, summarize them, respond to pending ones, and create issues from actionable feature requests
----
-
-# /review-discussions — GitHub Discussions Review & Response Workflow
-
-## Overview
-
-This workflow reads all open GitHub Discussions, generates a categorized summary, identifies which ones need a response, drafts and posts replies, and optionally creates issues from actionable feature requests. It follows the same flow used for Issues but adapted for the Discussions forum.
-
-> **Tool mapping note (v3.8):** Where steps below say `browser_subagent` (an earlier-runtime tool), in Claude Code use the `gh` CLI via the `Bash` tool — `gh api graphql` for reading discussions and `gh api graphql -F query=...` mutations for posting comments. `WebFetch` is acceptable for read-only HTML scraping when GraphQL is overkill, but prefer `gh` for any write actions.
-
-// turbo-all
-
-## Steps
-
-### 1. Identify the GitHub Repository
-
-- Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
-- Parse the owner and repo name from the URL
-
-### 2. Fetch All Open Discussions
-
-- Use `WebFetch` to fetch `https://github.com/<owner>/<repo>/discussions`
-- Parse the discussion list to get all discussion titles, IDs, authors, categories, and dates
-- For each discussion, fetch the individual page to read the full content and all comments/replies
-
-### 3. Summarize All Discussions
-
-For each discussion, extract:
-
-- **Title** and **#Number**
-- **Author** (GitHub username)
-- **Category** (Announcements, General, Ideas, Q&A, Show and tell)
-- **Date** created
-- **Summary** of the original post (1-2 sentences)
-- **Comments count** and key participants
-- **Your previous response** (if any)
-- **Pending action** — whether a response or follow-up is needed
-
-### 4. Present Summary Report to User
-
-Present the full summary to the user organized by category, using a table:
-
-| #   | Category | Title | Author | Date   | Status            |
-| --- | -------- | ----- | ------ | ------ | ----------------- |
-| #N  | Ideas    | Title | @user  | Mar 23 | ⚠️ Needs response |
-| #N  | Q&A      | Title | @user  | Mar 9  | ✅ Answered       |
-| #N  | General  | Title | @user  | Mar 19 | ⚠️ Needs response |
-
-Highlight:
-
-- **⚠️ Needs response** — No reply from maintainer, or a follow-up comment was left unanswered
-- **✅ Answered** — Maintainer already responded
-- **🐛 Bug reported** — A bug was mentioned that needs tracking
-- **💡 Actionable** — Contains a concrete feature request that could become an issue
-
-### 5. Draft & Post Responses
-
-For each discussion that needs a response, draft a reply following these guidelines:
-
-#### Response Style
-
-- **Friendly and professional** — Start with "Hey @username!"
-- **Acknowledge the contribution** — Thank the user for their input
-- **Be specific** — Reference existing features, settings, or dashboard pages if the feature already exists
-- **Provide workarounds** — If the request isn't implemented yet, suggest current alternatives
-- **Commit to action** — If the request is valid, state that you'll open an issue or add it to the roadmap
-- **Keep it concise** — 3-5 paragraphs max
-
-#### Posting via Browser
-
-- Use `browser_subagent` to navigate to each discussion and post the comment
-- **IMPORTANT**: When typing text in GitHub comment boxes via the browser, use only plain ASCII characters:
-  - Use regular hyphens `-` instead of em-dashes
-  - Use `->` instead of arrow symbols
-  - Do NOT use emoji Unicode characters (the browser keyboard may fail on them)
-  - Use `**bold**` and `\`code\`` markdown formatting
-- Click the green "Comment" button (or "Reply" for threaded replies) after typing
-- Verify the comment was posted by checking the page shows the new comment
-
-### 6. Create Issues from Actionable Feature Requests
-
-For discussions that contain concrete, actionable feature requests:
-
-1. Ask the user which ones should become issues
-2. For each approved request, create a GitHub issue via `browser_subagent`:
-   - Navigate to `https://github.com/<owner>/<repo>/issues/new`
-   - **Title**: `<Feature Name> - <Short description>`
-   - **Body** should include:
-     - `## Feature Request` header
-     - `**Source:** Discussion #N by @author`
-     - `## Problem` — What limitation the user hit
-     - `## Proposed Solution` — How it could work
-     - `### Implementation Ideas` — Technical approach
-     - `### Current Workarounds` — What users can do today
-     - `## Additional Context` — Links to related issues/discussions
-   - Add `enhancement` label
-   - Click "Submit new issue" / "Create"
-3. After creation, go back to the original discussion and post a comment linking to the new issue:
-   - "I've opened Issue #N to track this feature request. Follow along there for updates!"
-
-### 7. Final Report
-
-Present a final summary to the user:
-
-| Discussion | Action Taken                       |
-| ---------- | ---------------------------------- |
-| #N — Title | Responded with workarounds         |
-| #N — Title | Responded + created Issue #N       |
-| #N — Title | Already answered, no action needed |
-| #N — Title | Responded to follow-up comment     |
-
-## Notes
-
-- This workflow is **interactive** — always present the summary and wait for user approval before posting responses or creating issues
-- If the user says "pode responder" (or similar approval), proceed with posting all drafted responses
-- For discussions in non-English languages, respond in the same language as the original post
-- Always reference specific dashboard paths, config options, or code files when explaining existing features
-- When a discussion reveals a bug, note it separately from feature requests

.claude/commands/review-prs-cc.md

@@ -1,256 +0,0 @@
----
-description: Analyze open Pull Requests from the project's GitHub repository, generate a critical report, and optionally implement approved changes
----
-
-# /review-prs — PR Review & Analysis Workflow
-
-## ⛔ ABSOLUTE PROHIBITION — Read Before Anything Else
-
-> **NEVER close a contributor's PR if you intend to use ANY of their code, ideas, or fixes.**
->
-> **NEVER manually integrate contributor code into a release branch and then close their PR.**
->
-> These actions are **STRICTLY FORBIDDEN** under all circumstances:
->
-> 1. ❌ Closing a PR and cherry-picking/copying its code into a release branch
-> 2. ❌ Closing a PR "because of conflicts" and re-implementing the same fix yourself
-> 3. ❌ Closing a PR and committing a "similar" solution inspired by it
-> 4. ❌ Using `gh pr close` on any PR whose content was or will be used
->
-> **Why**: Closing a PR after taking the contributor's work means they get ZERO credit on GitHub — no "Merged" badge, no contribution graph entry, no public record. This is effectively stealing their contribution. An audit found this happened to **37 PRs** in the past.
->
-> **The ONLY acceptable flow**: Resolve conflicts IN the contributor's branch, push fixes TO their branch, then merge THEIR PR via `gh pr merge`. See Step 7 and Step 8 for the exact procedure.
->
-> **When to close a PR**: ONLY when the user (repository owner) explicitly requests it, OR when the PR is clearly spam/malicious, OR when the author themselves asks to close it. In ALL other cases, leave it open.
-
-## Overview
-
-This workflow fetches all open PRs from the project's GitHub repository, performs a critical analysis of each one, generates a detailed report, and waits for user approval before proceeding with implementation. **All improvements are committed on the current release branch** (`release/vX.Y.Z`).
-
-> **BRANCH RULE**: PRs are ALWAYS merged into the current `release/vX.Y.Z` branch, NEVER directly into `main`. The release branch acts as a staging area — only after all PRs are integrated and tests pass does the release branch get merged into `main` via the `/generate-release` workflow.
-
-## Steps
-
-### 1. Identify the GitHub Repository
-
-- Read `package.json` to get the repository URL, or use the git remote origin URL
-  // turbo
-- Run: `git -C <project_root> remote get-url origin` to extract the owner/repo
-
-### 2. Ensure Release Branch Exists
-
-// turbo
-
-Before doing any work, ensure you are on the current release branch:
-
-```bash
-# Check current branch
-git branch --show-current
-
-# If on main, determine next version and create the release branch
-VERSION=$(node -p "require('./package.json').version")
-# Bump patch: e.g. 3.3.11 → 3.3.12
-NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
-git checkout -b release/v$NEXT
-npm version patch --no-git-tag-version
-npm install
-```
-
-If already on a `release/vX.Y.Z` branch, continue working there.
-
-### 3. Fetch Open Pull Requests
-
-// turbo-all
-
-**⚠️ CRITICAL**: The JSON output of `gh pr list` can be truncated by the tool, silently hiding PRs. You MUST use the two-step approach below to guarantee **all** PRs are fetched.
-
-**Step 3a — Get PR numbers only** (small output, never truncated):
-
-- Run: `gh pr list --repo <owner>/<repo> --state open --limit 500 --json number --jq '.[].number'`
-- This outputs one PR number per line. Count them and confirm total.
-
-**Step 3b — Fetch full metadata for each PR** (one call per PR):
-
-- For each PR number from step 3a, run:
-  `gh pr view <NUMBER> --repo <owner>/<repo> --json number,title,author,headRefName,baseRefName,body,createdAt,additions,deletions,files`
-- You may batch these into parallel calls (up to 4 at a time).
-
-**Step 3c — Fetch diffs for each PR** (one call per PR, saved to /tmp):
-
-- For each PR number, run:
-  `gh pr diff <NUMBER> --repo <owner>/<repo> > /tmp/pr<NUMBER>.diff`
-- Then read each diff file with the `Read` tool.
-
-- For each open PR, collect:
-  - PR number, title, author, branch, number of commits, date
-  - PR description/body
-  - Files changed (diff)
-  - Existing review comments (from bots or humans)
-
-**Verification**: Confirm the count of PRs analyzed matches the count from step 3a before proceeding.
-
-### 3.5 Redirect PR Base Branches to Release Branch
-
-// turbo-all
-
-**⚠️ CRITICAL**: Contributors typically open PRs targeting `main`. Before analyzing or merging, redirect ALL open PRs to target the current release branch instead.
-
-```bash
-# Get the current release branch name
-RELEASE_BRANCH=$(git branch --show-current)  # e.g. release/v3.5.4
-
-# For each open PR that targets main, change its base to the release branch
-for PR_NUM in $(gh pr list --repo <owner>/<repo> --state open --json number,baseRefName --jq '.[] | select(.baseRefName == "main") | .number'); do
-  echo "Redirecting PR #$PR_NUM → $RELEASE_BRANCH"
-  gh pr edit "$PR_NUM" --repo <owner>/<repo> --base "$RELEASE_BRANCH"
-done
-```
-
-This ensures:
-
-1. PRs merge into the release branch, not directly into `main`
-2. Merge conflict detection is accurate against the release branch
-3. The release branch accumulates all changes before the final merge to `main`
-4. If the release branch doesn't exist on remote yet, push it first: `git push origin $RELEASE_BRANCH`
-
-### 4. Analyze Each PR — For each open PR, perform the following analysis:
-
-#### 4a. Feature Assessment
-
-- **Does it make sense?** Evaluate if the feature fills a real gap or solves a valid problem
-- **Alignment** — Check if it aligns with the project's architecture and roadmap
-- **Complexity** — Assess if the scope is reasonable or if it should be split
-
-#### 4b. Code Quality Review
-
-- Check for code duplication
-- Evaluate error handling patterns (consistent with existing codebase?)
-- Check naming conventions and code style
-- Verify TypeScript types (any `any` usage, missing types?)
-
-#### 4c. Security Review
-
-- Check for missing authentication/authorization on new endpoints
-- Check for injection vulnerabilities (URL params, SQL, XSS)
-- Verify input validation on all user-controlled data
-- Check for hardcoded secrets or credentials
-
-#### 4d. Architecture Review
-
-- Does the change follow existing patterns?
-- Are there any breaking changes to public APIs?
-- Is the database schema affected? Migration needed?
-- Impact on performance (N+1 queries, missing indexes?)
-
-#### 4e. Test Coverage
-
-- Does the PR include tests?
-- Are edge cases covered?
-- Would existing tests break?
-
-#### 4f. Cross-Layer (Global) Analysis
-
-Perform a **global impact assessment** to verify whether the PR changes are complete across all layers of the application:
-
-- **Backend → Frontend check**: If the PR adds or modifies backend-only resources (new endpoints, services, data models), evaluate whether corresponding frontend changes are missing:
-  - Does a new endpoint require a new screen/page in the dashboard?
-  - Should there be a new action button, menu item, or navigation link?
-  - Are there new data fields that should be displayed or editable in the UI?
-  - Does a new feature need a toggle, configuration panel, or status indicator?
-- **Frontend → Backend check**: If the PR adds frontend elements, verify the backend support exists:
-  - Are the required API endpoints implemented?
-  - Is the data model sufficient for the new UI components?
-- **Cross-cutting concerns**: Check shared layers (types, DTOs, validation schemas, routes, middleware) for completeness
-- **Document gaps** — If missing layers are detected, list them as **IMPORTANT** issues in the report with concrete suggestions for what should be added
-
-### 5. Generate Report — Create a markdown report for each PR including:
-
-- **PR Summary** — What it does, files affected, commit count
-- **Improvements/Benefits** — Numbered list with impact level (HIGH/MEDIUM/LOW)
-- **Risks & Issues** — Categorized as CRITICAL / IMPORTANT / MINOR
-- **Scoring Table** — Rate across: Feature Relevance, Code Quality, Security, Robustness, Tests
-- **Verdict** — Ready to merge? With mandatory vs optional fixes
-- **Next Steps** — What will happen if approved
-
-### 6. Present to User
-
-- Show the report in the final response and stop. This is a mandatory checkpoint awaiting explicit user approval before continuing.
-- Wait for user decision:
-  - **Approved** → Proceed to step 7
-  - **Approved with changes** → Implement the fixes and corrections before merging
-  - **Rejected** → Close the PR or leave a review comment
-
-### 7. Pre-Merge Fixes & CI Green-Lighting (if approved)
-
-> **⚠️ Fixes and Conflict Resolutions MUST be pushed back to the PR branch before merging.** We want the PR itself to be green and fully valid before it integrates.
-
-- **Sync latest fixes & Resolve Conflicts:** Merge the current `release` branch into the PR branch. If there are merge conflicts, you MUST resolve them inside the author's PR branch. NEVER resolve conflicts by closing their PR and doing the work in a separate branch, as this steals credit from the original author.
-- **Implement improvements:** Apply the required fixes identified in the analysis directly on the PR branch (e.g., adding missing API routes, fixing SSRF, applying comments from other agents).
-- **Pushing changes to PR branches:**
-
-  ```bash
-  # Checkout the PR locally
-  gh pr checkout <NUMBER>
-
-  # Apply fixes, commit your changes
-  git commit -m "chore: apply review suggestions and missing layers"
-
-  # Attempt to push directly to the PR branch
-  git push
-  ```
-
-- **Fallback (ONLY for external forks without maintainer edit access):**
-  Using `cherry-pick` instead of fixing the contributor's PR directly is a **LAST RESORT**. You MUST ALWAYS attempt to `git push` your fixes to their branch first.
-  **ONLY if `git push` explicitly fails with a permission/access error** (meaning the contributor unchecked "Allow edits from maintainers" or it's a locked fork), you may use `git cherry-pick` to bring their changes into the release branch and fix the issues locally.
-  Even then, ensure you preserve the contributor's authorship (`git commit --author="Contributor Name <email>"` if creating new commits).
-  Once you have integrated their work into the release branch, **DO NOT close their PR**. Leave it open so the contributor retains credit. Under NO CIRCUMSTANCES should you use `gh pr close`.
-
-- Run the project's test suite locally to verify nothing breaks:
-  // turbo
-- Run: `npm test` or equivalent test command
-
-### 8. Merge into Release Branch (NEVER CLOSE!)
-
-> **⚠️ CRITICAL**: NEVER use `gh pr close` for a PR whose idea or code was accepted. Closing a PR in a contributor's face after taking their idea—or closing it just because it had conflicts—is unacceptable.
-> You MUST ALWAYS resolve conflicts and apply fixes ON THE AUTHOR'S PR BRANCH (unless explicitly locked from edits), and then merge the PR using GitHub so the contributor gets the official "Merged" badge and proper credit on their profile. **Do not use cherry-pick just because it is "easier" than resolving conflicts on their branch.**
-
-Even if the PR had severe conflicts or required significant architectural adjustments, you MUST:
-
-1. Resolve any conflicts and apply the fixes directly to their PR branch (as detailed in step 7) or use cherry-picking into the release branch.
-2. If you managed to fix their branch, merge it into the release branch using the GitHub CLI:
-   `gh pr merge <NUMBER> --repo <owner>/<repo> --squash --body "Integrated into release/vX.Y.Z"`
-3. If you had to use cherry-picking because you couldn't push to their branch, DO NOT close the PR. GitHub will sometimes auto-detect the cherry-picked commits and mark it as Merged. If it doesn't, leave it open. The repository owner will handle it. NEVER run `gh pr close`.
-
-In ALL cases:
-
-- Post a **thank-you comment** on the PR via the GitHub API before or immediately after merging.
-- The message should:
-  - Thank the author by name/username for their contribution.
-  - Explain what was adjusted or improved (if we pushed fixes to their branch or cherry-picked).
-  - Note it will be included in the upcoming release.
-  - Be friendly, professional, and encouraging.
-
-> **⚠️ MANDATORY CHANGELOG CREDIT**: When cherry-picking is used (because the PR branch couldn't be pushed to or `gh pr merge` failed), the contributor does NOT get the automatic GitHub "Merged" badge. In this case, you MUST compensate by adding an explicit entry to `CHANGELOG.md` in the `[Unreleased]` section with `(#PR_NUMBER — thanks @username)` format. This ensures the contributor gets public credit in the release notes even if GitHub doesn't auto-detect the cherry-pick. This is NOT optional — skipping it effectively erases the contributor's work from the release record.
-
-### 9. Sync Local Release Branch
-
-After merging PRs, sync the local release branch to include the new changes:
-
-```bash
-git fetch origin
-git pull origin release/vX.Y.Z
-```
-
-### 10. Continue or Finalize
-
-After processing all approved PRs:
-
-- If more PRs remain, go back to step 7
-- When all PRs are processed, **update CHANGELOG.md** on the release branch with all new entries
-- Run **test coverage** to verify the gate (≥75% statements/lines/functions, ≥70% branches — measured ~82%):
-  ```bash
-  npm run test:coverage
-  ```
-- Fix any test regressions introduced by merged PRs
-- Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)
-- The `/generate-release` workflow handles the final merge from `release/vX.Y.Z` → `main`

.claude/commands/version-bump-cc.md

@@ -1,341 +0,0 @@
----
-description: Bump version, auto-generate CHANGELOG from git commits, update all versioned files, and refresh root + docs/ documentation to reflect the current project state
----
-
-# Version Bump Workflow
-
-Automatically bump the project version, generate CHANGELOG entries from git history since the last tag, update every file that references the version, and refresh project documentation to reflect the current state.
-
-> **VERSION RULE: Always use PATCH bumps (3.x.y → 3.x.y+1)**
-> NEVER use `npm version minor` or `npm version major`.
-> Always use: `npm version patch --no-git-tag-version`
-> The threshold rule: when `y` reaches 10, bump to `3.(x+1).0` — e.g. `3.4.10` → `3.5.0`.
-
----
-
-## Phase 1: Determine Version
-
-### 1. Read current version and last tag
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-CURRENT_VERSION=$(node -p "require('./package.json').version")
-LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
-CURRENT_BRANCH=$(git branch --show-current)
-echo "Current version: $CURRENT_VERSION"
-echo "Last tag: $LAST_TAG"
-echo "Current branch: $CURRENT_BRANCH"
-```
-
-### 2. Calculate new version
-
-Apply the patch bump rule:
-
-- If the current patch number is `9`, the new version is `3.(minor+1).0`
-- Otherwise, increment patch: `3.x.y` → `3.x.(y+1)`
-
-If the version was ALREADY bumped (e.g. you are on a release branch and package.json already has the new version), **skip the npm version bump** and use the existing version.
-
-### 3. Bump package.json (if needed)
-
-// turbo
-
-```bash
-# Only if version hasn't been bumped yet
-npm version patch --no-git-tag-version
-```
-
-Or for threshold (y=10):
-
-```bash
-# Manual threshold bump
-VERSION="3.X.0"  # compute manually
-npm version "$VERSION" --no-git-tag-version
-```
-
----
-
-## Phase 2: Generate CHANGELOG from Git History
-
-### 4. Collect commits since last tag
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
-echo "=== Commits since $LAST_TAG ==="
-git log "$LAST_TAG"..HEAD --pretty=format:"%h %s" --no-merges | head -100
-echo ""
-echo "=== Merge commits ==="
-git log "$LAST_TAG"..HEAD --merges --pretty=format:"%h %s" | head -50
-```
-
-### 5. Classify commits and generate CHANGELOG section
-
-Analyze each commit message and classify into categories based on the conventional-commit prefix and content:
-
-| Category            | Patterns                                         |
-| ------------------- | ------------------------------------------------ |
-| ✨ New Features     | `feat:`, `feat(*):`                              |
-| 🐛 Bug Fixes        | `fix:`, `fix(*):`                                |
-| ⚠️ Breaking Changes | `BREAKING CHANGE`, `!:` suffix                   |
-| 🛠️ Maintenance      | `chore:`, `refactor:`, `perf:`, `build:`         |
-| 🧪 Tests            | `test:`, `tests:`                                |
-| 📝 Documentation    | `docs:`                                          |
-| 🔒 Security         | `security:`, CVE references, vulnerability fixes |
-| 🌍 i18n             | translation updates, locale changes              |
-
-For each category with entries, create a markdown section with descriptive bullet points. Use the commit messages but rewrite them to be human-readable and descriptive (not raw commit messages).
-
-**If a commit references a PR number** (e.g. `#880`, `PR #885`), include it in the description.
-
-### 6. Update CHANGELOG.md
-
-Replace the `## [Unreleased]` section content with the generated entries, then add the new versioned section:
-
-```markdown
-## [Unreleased]
-
----
-
-## [NEW_VERSION] — YYYY-MM-DD
-
-### ✨ New Features
-
-- **Feature name:** Description (#PR)
-
-### 🐛 Bug Fixes
-
-- **Fix name:** Description (#PR)
-
-### 🛠️ Maintenance
-
-- **Item:** Description
-
----
-
-## [PREVIOUS_VERSION] — YYYY-MM-DD
-
-...
-```
-
-The date must be today's date in `YYYY-MM-DD` format.
-
----
-
-## Phase 3: Sync Version Across All Files
-
-### 7. Update workspace package.json files and openapi.yaml
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-VERSION=$(node -p "require('./package.json').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
-  if [ -d "$dir" ] && [ -f "$dir/package.json" ]; then
-    (cd "$dir" && npm version "$VERSION" --no-git-tag-version --allow-same-version > /dev/null)
-    echo "✓ $dir/package.json → $VERSION"
-  fi
-done
-
-echo "✓ All workspace packages synced to $VERSION"
-```
-
-### 8. Update llm.txt version references
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-VERSION=$(node -p "require('./package.json').version")
-OLD_VERSION_PATTERN='[0-9]\+\.[0-9]\+\.[0-9]\+'
-
-# Update "Current version:" line
-sed -i "s/\*\*Current version:\*\* $OLD_VERSION_PATTERN/**Current version:** $VERSION/" llm.txt
-
-# Update "Key Features (vX.Y.Z)" header
-sed -i "s/## Key Features (v$OLD_VERSION_PATTERN)/## Key Features (v$VERSION)/" llm.txt
-
-echo "✓ llm.txt → $VERSION"
-```
-
-### 9. Regenerate lock file
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-npm install
-echo "✓ Lock file regenerated"
-```
-
----
-
-## Phase 4: Update Root Documentation
-
-Based on the CHANGELOG entries generated in Phase 2, review and update these root-level files if relevant changes warrant updates:
-
-### 10. Review and update root documentation files
-
-For each file below, read the current content and determine if the CHANGELOG entries require any updates. Only modify files where substantive changes have occurred:
-
-| File              | When to update                                                                                                              |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `README.md`       | New providers, major features, stats changes (test count, provider count), badges, installation instructions, feature table |
-| `AGENTS.md`       | Architecture changes, new modules, new commands, new providers, new services/handlers/executors                             |
-| `CONTRIBUTING.md` | Dev workflow changes, new tooling, test infrastructure changes                                                              |
-| `SECURITY.md`     | Security fixes, new auth mechanisms, vulnerability disclosures                                                              |
-| `llm.txt`         | Provider count changes, new features, architecture changes                                                                  |
-
-**Update rules:**
-
-- **README.md**: Update provider count, test count, feature highlights table, badges if any numbers changed. If a new provider was added, add it to the provider table. If a major feature was added, add it to the features section.
-- **AGENTS.md**: If new architecture components (handlers, executors, services, DB modules) were added, update the Architecture section. If new commands were added, update the Build/Test table.
-- **SECURITY.md**: Add new vulnerability fixes or security improvements to the relevant section.
-- **llm.txt**: Update provider count, feature list, version references.
-
-### 11. Review and update docs/ files (excluding i18n/)
-
-For each file in `docs/` (excluding `docs/i18n/`), review if CHANGELOG changes affect it:
-
-| 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.
-
----
-
-## Phase 5: Verify
-
-### 12. Run lint check
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-npm run lint
-```
-
-### 13. Run tests
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-npm test
-```
-
-### 14. Verify version sync across all files
-
-// turbo
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-VERSION=$(node -p "require('./package.json').version")
-echo "Expected version: $VERSION"
-echo ""
-
-echo "--- package.json ---"
-grep '"version"' package.json | head -1
-
-echo "--- open-sse/package.json ---"
-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/reference/openapi.yaml ---"
-grep "  version:" docs/reference/openapi.yaml | head -1
-
-echo "--- llm.txt ---"
-grep "Current version:" llm.txt
-
-echo "--- CHANGELOG.md (first versioned entry) ---"
-grep "^## \[" CHANGELOG.md | head -2
-```
-
-### 15. 🛑 STOP — Present Summary to User
-
-**STOP** and present a summary to the user including:
-
-- Old version → New version
-- CHANGELOG entries generated
-- Files modified
-- Test results
-- Any documentation updates made
-
-**Wait for the user to confirm before committing.**
-
----
-
-## Phase 6: Commit (only after user approval)
-
-### 16. Stage and commit
-
-// turbo-all
-
-```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute
-git add -A
-VERSION=$(node -p "require('./package.json').version")
-git commit -m "chore(release): bump to v$VERSION — changelog, docs, version sync"
-```
-
----
-
-## Notes
-
-- This workflow does **NOT** create tags, releases, or deploy. Use `/generate-release` for the full release cycle after this.
-- This workflow does **NOT** update `docs/i18n/` translations. Translation updates are handled manually or via release tooling — the `/update-i18n` command does not currently exist as a Claude Code slash command.
-- The CHANGELOG generation is based on git commits since the last tag. If there are no new commits, the workflow should inform the user and stop.
-- Always verify the generated CHANGELOG entries make sense — raw commit messages may need rewriting for clarity.
-- If the version was already bumped (e.g. you're on a `release/vX.Y.Z` branch), skip the `npm version` step and use the existing version.
-
-## 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/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`                                   |

.dockerignore

@@ -9,6 +9,7 @@
 # Dependencies and build output
 node_modules
 .next
+.build
 out
 build
 dist
@@ -41,20 +42,18 @@ blob-report
 # Issue #2348: The Dashboard Docs viewer reads markdown from `/app/docs` at
 # runtime. The previous `docs/*` block hid every file except openapi.yaml,
 # so the in-product help screen failed with ENOENT for every page.
-# We now keep the English markdown tree but drop the bulky assets
-# (translations, screenshots, raster diagrams) that account for ~45 MB
+# We now keep the English markdown tree plus the docs assets imported by MDX
+# during `next build`, while still dropping the bulky translated docs and
+# extra raster diagram sources that account for most of the docs footprint
 # of the ~50 MB docs directory. The Docs viewer reads the default-locale
 # (English) sources at runtime, so translations are not required in the
 # container image.
 docs/i18n/**
-docs/screenshots/**
-docs/diagrams/exported/**
 docs/diagrams/**/*.png
 docs/diagrams/**/*.jpg
 docs/diagrams/**/*.jpeg
 docs/diagrams/**/*.gif
 docs/diagrams/**/*.webp
-docs/diagrams/**/*.svg
 # Note: `*.md` matches the root only (Go filepath.Match does not cross /),
 # so nested docs/**/*.md is implicitly kept without a re-include rule.
 *.md
@@ -78,6 +77,8 @@ bun.lock
 # Agent config
 .agents
 .gemini
+.claude
+.source
 
 # Misc
 llm.txt

.github/FUNDING.yml

@@ -0,0 +1,5 @@
+# Funding links for OmniRoute — rendered as the "Sponsor" button on GitHub.
+# Docs: https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository
+github: diegosouzapw
+# Additional platforms (uncomment and fill in before enabling):
+# custom: ["https://omniroute.online/donate"]

.github/actions/npm-ci-retry/action.yml

@@ -0,0 +1,29 @@
+name: npm ci with retry
+description: Run npm ci with retries for transient registry/network failures.
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      run: |
+        set -euo pipefail
+
+        max_attempts=3
+        delay_seconds=20
+
+        for attempt in $(seq 1 "$max_attempts"); do
+          if [ "$attempt" -gt 1 ]; then
+            echo "npm ci attempt $attempt/$max_attempts after transient failure"
+          fi
+
+          if npm ci; then
+            exit 0
+          fi
+
+          exit_code=$?
+          if [ "$attempt" -eq "$max_attempts" ]; then
+            exit "$exit_code"
+          fi
+
+          sleep "$delay_seconds"
+          delay_seconds=$((delay_seconds * 2))
+        done

.github/dependabot.yml

@@ -24,6 +24,20 @@ updates:
         update-types: ["version-update:semver-major"]
       - dependency-name: "eslint-config-next"
         update-types: ["version-update:semver-major"]
+      # jscpd v5 is a Rust rewrite (native binary, no Node.js programmatic API).
+      # scripts/check/check-duplication.mjs is deliberately pinned to jscpd@4 (it
+      # parses jscpd-report.json against a frozen baseline). A v5 major would break
+      # the duplication gate — migrate the gate intentionally, not via dependabot.
+      - dependency-name: "jscpd"
+        update-types: ["version-update:semver-major"]
+      # @huggingface/transformers is HARD-PINNED at 3.5.2 (exact, no caret) — FROZEN.
+      # It is load-bearing for the LLMLingua ONNX compression engine (open-sse/services/
+      # compression/engines/llmlingua/ — worker.ts pins @huggingface/transformers@3.5.2)
+      # and for local memory embeddings (src/lib/memory/embedding/transformersLocal.ts),
+      # and was VPS-validated at 3.5.2 (#4014). 4.x breaks both, and even 3.x minors must
+      # be re-validated on the VPS — so freeze ALL auto-bumps (no update-types = ignore
+      # every version). Migrate it intentionally, not via dependabot (#4050).
+      - dependency-name: "@huggingface/transformers"
 
   - package-ecosystem: "github-actions"
     directory: "/"

.github/workflows/build-fork.yml

@@ -7,9 +7,10 @@ on:
       - "v*"
   workflow_dispatch:
 
+# Least-privilege default: read-only at the top level; the build job that pushes to
+# GHCR grants packages: write itself (Scorecard TokenPermissions).
 permissions:
   contents: read
-  packages: write
 
 env:
   IMAGE_NAME: ghcr.io/kang-heewon/omniroute
@@ -19,9 +20,14 @@ jobs:
     name: Build and Push Fork Image
     if: github.repository == 'kang-heewon/OmniRoute'
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v4

.github/workflows/claude.yml

@@ -10,6 +10,10 @@ on:
   pull_request_review:
     types: [submitted]
 
+# Least-privilege default: no token permissions at the top level; the `claude` job
+# grants exactly what it needs below (Scorecard TokenPermissions).
+permissions: {}
+
 jobs:
   claude:
     if: |
@@ -26,8 +30,9 @@ jobs:
       actions: read # Required for Claude to read CI results on PRs
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
+          persist-credentials: false
           fetch-depth: 1
 
       - name: Run Claude Code

.github/workflows/codeql.yml

@@ -0,0 +1,31 @@
+name: CodeQL
+# OWNER ACTION REQUIRED before enabling auto-triggers: advanced CodeQL conflicts with
+# GitHub "default setup" — the analyze step fails with "CodeQL analyses from advanced
+# configurations cannot be processed when the default setup is enabled". Switch repo
+# Settings → Code security → CodeQL from Default to Advanced, THEN restore the
+# push/pull_request/schedule triggers below. Until then this only runs on manual dispatch
+# so it never produces a red check on PRs. (The codeqlAlerts ratchet keeps working via the
+# default setup's alerts in the meantime.)
+on:
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  analyze:
+    name: Analyze (javascript-typescript)
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      actions: read
+      contents: read
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        with:
+          languages: javascript-typescript
+          queries: security-extended
+      - uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        with:
+          category: "/language:javascript-typescript"

.github/workflows/dast-smoke.yml

@@ -0,0 +1,62 @@
+name: DAST smoke (PR)
+on:
+  pull_request:
+    branches: ["main", "release/**"]
+permissions:
+  contents: read
+jobs:
+  dast-smoke:
+    runs-on: ubuntu-latest
+    # ADVISORY while this new gate matures (repo convention: advisory -> blocking).
+    # Flip to blocking (remove continue-on-error) once it's proven stable across a few PRs.
+    continue-on-error: true
+    timeout-minutes: 12
+    env:
+      JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-api-key-secret-with-sufficient-length-aaaa
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "24"
+          cache: npm
+      - run: npm ci
+      - name: Build CLI bundle
+        run: npm run build:cli
+      - name: Start OmniRoute
+        env:
+          PORT: "20128"
+          INJECTION_GUARD_MODE: block
+        run: |
+          node dist/server.js > server.log 2>&1 &
+          echo $! > server.pid
+          for _ in $(seq 1 30); do
+            if curl -sf http://localhost:20128/api/monitoring/health >/dev/null; then echo up; break; fi
+            sleep 2
+          done
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+      - run: pip install schemathesis
+      - name: Schemathesis smoke (high-risk endpoints, blocking)
+        run: |
+          schemathesis run docs/openapi.yaml --url http://localhost:20128 \
+            --include-path-regex '^/v1/(chat/completions|models)$|^/api/(auth|keys)' \
+            --max-examples 8 --workers 4 --checks all --max-response-time 30 \
+            --request-timeout 20 --suppress-health-check all --no-color
+      - name: promptfoo injection-guard (blocking)
+        env:
+          OMNIROUTE_URL: http://localhost:20128
+          OMNIROUTE_API_KEY: not-needed-blocked-before-upstream
+        run: npx --yes promptfoo@latest eval -c promptfooconfig.yaml --no-cache
+      - name: Stop server
+        if: always()
+        run: kill "$(cat server.pid)" || true
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: always()
+        with:
+          name: dast-smoke-logs
+          path: server.log
+          retention-days: 7

.github/workflows/deploy-vps.yml

@@ -17,27 +17,82 @@ jobs:
     name: Deploy OmniRoute to VPS
     runs-on: ubuntu-latest
     steps:
+      - name: Check VPS SSH reachability from runner
+        id: reach
+        env:
+          # Pass the host via env (never interpolate a secret straight into the
+          # script body) so /dev/tcp gets a shell variable, not inlined text.
+          VPS_HOST: ${{ secrets.VPS_HOST }}
+        run: |
+          set -uo pipefail
+          # A GitHub-hosted runner can only deploy when it can actually open a TCP
+          # connection to the VPS SSH port. The Local VPS lives on a private LAN and
+          # the Akamai host firewalls :22 to known IPs, so the runner is routinely
+          # unable to reach it (`dial tcp ***:22: i/o timeout`). Treat "unreachable
+          # from the runner" as a SKIP — the real deploys are run manually from an
+          # allowed network via the deploy-vps-local / deploy-vps-akamai skills — so
+          # an unreachable host no longer red-fails every release/push pipeline.
+          # When the host IS reachable, the deploy step below still runs in full and
+          # its health gate surfaces any genuine deploy failure.
+          if timeout 15 bash -c 'exec 3<>"/dev/tcp/${VPS_HOST}/22"' 2>/dev/null; then
+            echo "reachable=true" >> "$GITHUB_OUTPUT"
+            echo "✅ VPS_HOST:22 reachable from the runner — proceeding with deploy."
+          else
+            echo "reachable=false" >> "$GITHUB_OUTPUT"
+            echo "::warning title=Auto-deploy skipped::VPS_HOST:22 is not reachable from this GitHub runner (private LAN / firewalled). Deploy manually with the deploy-vps-local or deploy-vps-akamai skill."
+          fi
+
       - name: Deploy via SSH
+        if: steps.reach.outputs.reachable == 'true'
         uses: appleboy/ssh-action@v1
-        continue-on-error: true
         with:
           host: ${{ secrets.VPS_HOST }}
           username: ${{ secrets.VPS_USER }}
           key: ${{ secrets.VPS_SSH_KEY }}
           port: 22
-          timeout: 30s
-          command_timeout: 5m
+          timeout: 60s
+          command_timeout: 15m
           script: |
-            echo "=== Updating OmniRoute ==="
-            npm install -g omniroute@latest 2>&1
-            INSTALLED_VERSION=$(omniroute --version 2>/dev/null || echo "unknown")
-            echo "Installed version: $INSTALLED_VERSION"
+            set -euo pipefail
 
-            echo "=== Restarting PM2 ==="
-            pm2 restart omniroute || pm2 start omniroute --name omniroute -- --port 20128
+            echo "=== Updating OmniRoute ==="
+            npm install -g omniroute@latest
+            INSTALLED_VERSION=$(omniroute --version 2>/dev/null | tr -d '[:space:]' || echo "unknown")
+            echo "Installed CLI version: $INSTALLED_VERSION"
+
+            # Recreate the PM2 process instead of `pm2 restart`. A bare restart
+            # re-runs whatever script path was saved earlier; after the build-output
+            # reorg (app/ -> dist/, .next -> .build/next) a process pinned to the old
+            # app/server-ws.mjs path can no longer start, and the node process dies
+            # while PM2 still reports "online" — so the box never binds :20128.
+            # Always launch via the `omniroute` bin so .env is loaded and the dist/
+            # layout is resolved correctly.
+            echo "=== (Re)creating PM2 process via bin ==="
+            pm2 delete omniroute 2>/dev/null || true
+            pm2 start omniroute --name omniroute -- --port 20128
             pm2 save
 
-            echo "=== Health Check ==="
-            sleep 3
-            curl -sf http://localhost:20128/api/settings > /dev/null && echo "✅ OmniRoute is healthy" || echo "❌ Health check failed"
+            # Health gate: fail the deploy unless the box actually reports healthy.
+            # Poll /api/monitoring/health for "status":"healthy" (a deeper signal than
+            # a static page 200 — it confirms the app booted, not just that a port is
+            # bound). Boot can take a while after a native-module/build-layout change,
+            # so poll up to ~3min before giving up.
+            echo "=== Health Check (gates the deploy) ==="
+            ok=0
+            for i in $(seq 1 36); do
+              BODY=$(curl -sf -m 5 http://localhost:20128/api/monitoring/health 2>/dev/null || true)
+              if printf '%s' "$BODY" | grep -q '"status":"healthy"'; then
+                ok=1
+                echo "✅ /api/monitoring/health -> healthy (attempt $i) — version $INSTALLED_VERSION"
+                break
+              fi
+              echo "… not healthy yet (attempt $i/36), retrying in 5s"
+              sleep 5
+            done
+            if [ "$ok" != "1" ]; then
+              echo "❌ Health check failed — /api/monitoring/health never reported healthy after ~3min"
+              echo "--- recent PM2 logs ---"
+              pm2 logs omniroute --lines 40 --nostream || true
+              exit 1
+            fi
             echo "=== Deploy complete ==="

.github/workflows/docker-publish.yml

@@ -8,33 +8,146 @@ on:
       - "v*"
     paths-ignore:
       - ".github/workflows/**"
+  # Use 'released' instead of 'published' so editing/re-publishing old releases
+  # does NOT re-trigger this workflow. 'released' fires only on the initial
+  # release publication (and pre-release → release transition).
   release:
-    types: [published]
+    types: [released]
   workflow_dispatch:
     inputs:
       version:
-        description: "Version tag to build (e.g. 2.6.0)"
+        description: "Version tag to build (e.g. 3.8.4)"
         required: true
         type: string
+      promote_latest:
+        description: "Also tag :latest (only if this is the highest semver)"
+        required: false
+        type: boolean
+        default: false
 
+# Least-privilege default: read-only at the top level; the build and merge jobs that
+# push to GHCR grant packages: write themselves (Scorecard TokenPermissions).
 permissions:
   contents: read
-  packages: write
 
 jobs:
-  docker:
-    name: Build and Push Docker (multi-arch)
+  prepare:
+    name: Resolve Docker release metadata
     runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      promote_latest: ${{ steps.version.outputs.promote_latest }}
+      skip: ${{ steps.version.outputs.skip }}
     env:
       IMAGE_NAME: diegosouzapw/omniroute
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
+          persist-credentials: false
           ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/v{0}', inputs.version) || '' }}
+          # Need full tag history for semver comparison when deciding :latest.
+          fetch-depth: 0
 
-      - name: Set up QEMU (for multi-arch builds)
-        uses: docker/setup-qemu-action@v4
+      - name: Resolve version, latest-promotion, and skip flag
+        id: version
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          REF_NAME: ${{ github.ref_name }}
+          REF_TYPE: ${{ github.ref_type }}
+          INPUT_VERSION: ${{ inputs.version }}
+          PROMOTE_INPUT: ${{ inputs.promote_latest }}
+        run: |
+          set -euo pipefail
+
+          # 1) Resolve version string from the trigger (all inputs come via env).
+          case "$EVENT_NAME" in
+            workflow_dispatch)
+              VERSION="${INPUT_VERSION#v}"
+              ;;
+            push)
+              if [ "$REF_TYPE" = "tag" ]; then
+                VERSION="${REF_NAME#v}"
+              else
+                # Push to main → build & tag as `main` only. Never touch :latest.
+                VERSION="main"
+              fi
+              ;;
+            release)
+              VERSION="${REF_NAME#v}"
+              ;;
+            *)
+              VERSION="${REF_NAME#v}"
+              ;;
+          esac
+          # Sanity-check: only allow [A-Za-z0-9._-] in VERSION (defense in depth).
+          if ! printf '%s' "$VERSION" | grep -qE '^[A-Za-z0-9._-]+$'; then
+            echo "Refusing to use unsafe VERSION value: $VERSION" >&2
+            exit 1
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+          # 2) Decide whether to promote :latest.
+          PROMOTE="false"
+          if [ "$VERSION" = "main" ]; then
+            PROMOTE="false"
+          elif printf '%s' "$VERSION" | grep -qE -- '-(rc|alpha|beta|pre|next)'; then
+            echo "Pre-release identifier detected — skipping :latest."
+            PROMOTE="false"
+          elif [ "$EVENT_NAME" = "workflow_dispatch" ]; then
+            PROMOTE="${PROMOTE_INPUT:-false}"
+          else
+            git fetch --tags --quiet || true
+            HIGHEST=$(git tag -l 'v[0-9]*' | sed 's/^v//' | grep -vE -- '-(rc|alpha|beta|pre|next)' | sort -V | tail -1 || echo "")
+            if [ -n "$HIGHEST" ] && [ "$VERSION" = "$HIGHEST" ]; then
+              PROMOTE="true"
+            else
+              echo "Version $VERSION is not the highest semver tag (highest=${HIGHEST:-<none>}). Not promoting :latest."
+            fi
+          fi
+          echo "promote_latest=$PROMOTE" >> "$GITHUB_OUTPUT"
+
+          # 3) Skip if this exact version is already published in Docker Hub.
+          #    `main` is always rebuilt (mutable floating tag).
+          SKIP="false"
+          if [ "$VERSION" != "main" ]; then
+            if docker manifest inspect "diegosouzapw/omniroute:${VERSION}" >/dev/null 2>&1; then
+              echo "Image diegosouzapw/omniroute:${VERSION} already exists on Docker Hub — skipping rebuild."
+              SKIP="true"
+            fi
+          fi
+          echo "skip=$SKIP" >> "$GITHUB_OUTPUT"
+
+          echo "Publishing diegosouzapw/omniroute:$VERSION (promote_latest=$PROMOTE, skip=$SKIP)"
+
+  build:
+    name: Build Docker (${{ matrix.platform }})
+    needs: prepare
+    if: needs.prepare.outputs.skip != 'true'
+    runs-on: ${{ matrix.runner }}
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-24.04
+            arch: amd64
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+            arch: arm64
+    env:
+      IMAGE_NAME: diegosouzapw/omniroute
+      GHCR_IMAGE_NAME: ghcr.io/diegosouzapw/omniroute
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/v{0}', inputs.version) || '' }}
+          fetch-depth: 0
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
@@ -52,41 +165,227 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Extract version from release tag or input
-        id: version
-        run: |
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            VERSION="${{ inputs.version }}"
-          else
-            VERSION="${GITHUB_REF_NAME}"
-            VERSION="${VERSION#v}"
-          fi
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "Publishing Docker image: $IMAGE_NAME:$VERSION"
-
-      - name: Build and push multi-arch image
+      - name: Build and push platform image by digest
+        id: build
         uses: docker/build-push-action@v7
         with:
           context: .
           target: runner-base
-          platforms: linux/amd64,linux/arm64
-          push: true
+          platforms: ${{ matrix.platform }}
+          outputs: type=image,push-by-digest=true,name-canonical=true,push=true
           tags: |
-            ${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }}
-            ${{ env.IMAGE_NAME }}:latest
-            ghcr.io/diegosouzapw/omniroute:${{ steps.version.outputs.version }}
-            ghcr.io/diegosouzapw/omniroute:latest
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+            ${{ env.IMAGE_NAME }}
+            ${{ env.GHCR_IMAGE_NAME }}
+          cache-from: type=gha,scope=docker-${{ matrix.arch }}
+          cache-to: type=gha,scope=docker-${{ matrix.arch }},mode=max
           no-cache: false
         env:
           DOCKER_BUILDKIT_INLINE_CACHE: 1
 
-      - name: Inspect image
+      - name: Build and push WEB platform image by digest
+        id: build-web
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          target: runner-web
+          platforms: ${{ matrix.platform }}
+          outputs: type=image,push-by-digest=true,name-canonical=true,push=true
+          tags: |
+            ${{ env.IMAGE_NAME }}
+            ${{ env.GHCR_IMAGE_NAME }}
+          cache-from: type=gha,scope=docker-web-${{ matrix.arch }}
+          cache-to: type=gha,scope=docker-web-${{ matrix.arch }},mode=max
+          no-cache: false
+        env:
+          DOCKER_BUILDKIT_INLINE_CACHE: 1
+
+      - name: Export digests
+        env:
+          DIGEST_BASE: ${{ steps.build.outputs.digest }}
+          DIGEST_WEB: ${{ steps.build-web.outputs.digest }}
         run: |
-          docker buildx imagetools inspect "${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }}"
+          set -euo pipefail
+          mkdir -p /tmp/digests/base /tmp/digests/web
+          touch "/tmp/digests/base/${DIGEST_BASE#sha256:}"
+          touch "/tmp/digests/web/${DIGEST_WEB#sha256:}"
+
+      - name: Upload base digests
+        uses: actions/upload-artifact@v7
+        with:
+          name: digests-base-${{ matrix.arch }}
+          path: /tmp/digests/base/*
+          if-no-files-found: error
+          retention-days: 1
+
+      - name: Upload web digests
+        uses: actions/upload-artifact@v7
+        with:
+          name: digests-web-${{ matrix.arch }}
+          path: /tmp/digests/web/*
+          if-no-files-found: error
+          retention-days: 1
+
+  merge:
+    name: Publish multi-arch manifests
+    needs:
+      - prepare
+      - build
+    if: needs.prepare.outputs.skip != 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      security-events: write
+    env:
+      IMAGE_NAME: diegosouzapw/omniroute
+      GHCR_IMAGE_NAME: ghcr.io/diegosouzapw/omniroute
+      VERSION: ${{ needs.prepare.outputs.version }}
+      PROMOTE_LATEST: ${{ needs.prepare.outputs.promote_latest }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/v{0}', inputs.version) || '' }}
+          fetch-depth: 0
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Download base digests
+        uses: actions/download-artifact@v8
+        with:
+          pattern: digests-base-*
+          path: /tmp/digests/base
+          merge-multiple: true
+
+      - name: Download web digests
+        uses: actions/download-artifact@v8
+        with:
+          pattern: digests-web-*
+          path: /tmp/digests/web
+          merge-multiple: true
+
+      - name: Create Docker Hub manifest
+        run: |
+          set -euo pipefail
+
+          create_manifest() {
+            local image="$1" suffix="$2" dir="$3"
+            local tags=(-t "${image}:${VERSION}${suffix}")
+            if [ "$PROMOTE_LATEST" = "true" ]; then
+              tags+=(-t "${image}:latest${suffix}")
+            fi
+            local refs=()
+            while IFS= read -r digest_file; do
+              refs+=("${image}@sha256:$(basename "$digest_file")")
+            done < <(find "$dir" -type f | sort)
+            if [ "${#refs[@]}" -eq 0 ]; then
+              echo "No image digests in $dir" >&2
+              exit 1
+            fi
+            docker buildx imagetools create "${tags[@]}" "${refs[@]}"
+          }
+
+          create_manifest "${IMAGE_NAME}" "" /tmp/digests/base
+          create_manifest "${IMAGE_NAME}" "-web" /tmp/digests/web
+
+      - name: Create GHCR manifest
+        run: |
+          set -euo pipefail
+
+          create_manifest() {
+            local image="$1" suffix="$2" dir="$3"
+            local tags=(-t "${image}:${VERSION}${suffix}")
+            if [ "$PROMOTE_LATEST" = "true" ]; then
+              tags+=(-t "${image}:latest${suffix}")
+            fi
+            local refs=()
+            while IFS= read -r digest_file; do
+              refs+=("${image}@sha256:$(basename "$digest_file")")
+            done < <(find "$dir" -type f | sort)
+            if [ "${#refs[@]}" -eq 0 ]; then
+              echo "No image digests in $dir" >&2
+              exit 1
+            fi
+            docker buildx imagetools create "${tags[@]}" "${refs[@]}"
+          }
+
+          create_manifest "${GHCR_IMAGE_NAME}" "" /tmp/digests/base
+          create_manifest "${GHCR_IMAGE_NAME}" "-web" /tmp/digests/web
+
+      - name: Inspect image
+        if: needs.prepare.outputs.version != 'main'
+        run: |
+          docker buildx imagetools inspect "${IMAGE_NAME}:${VERSION}"
+
+      - name: Generate CycloneDX SBOM (image, advisory)
+        if: needs.prepare.outputs.version != 'main'
+        continue-on-error: true
+        uses: anchore/sbom-action@v0
+        with:
+          image: ${{ env.GHCR_IMAGE_NAME }}:${{ env.VERSION }}
+          format: cyclonedx-json
+          output-file: sbom-image.cdx.json
+          artifact-name: sbom-image.cdx.json
+
+      # Visibility scan: reports HIGH + CRITICAL into the SARIF (Security tab) but
+      # never blocks (exit-code 0). The blocking gate below narrows to CRITICAL.
+      - name: Trivy image scan (SARIF, advisory)
+        if: needs.prepare.outputs.version != 'main'
+        continue-on-error: true
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+        with:
+          image-ref: ${{ env.GHCR_IMAGE_NAME }}:${{ env.VERSION }}
+          format: sarif
+          output: trivy-results.sarif
+          severity: HIGH,CRITICAL
+          exit-code: "0"
+
+      # BLOCKING gate (v3.8.27 cycle-end): fail the release on a CRITICAL CVE in the
+      # published image. Narrowed to severity CRITICAL (HIGH stays visible in the
+      # SARIF step above, not blocking). ignore-unfixed:true so an unfixable base-image
+      # CVE with no upstream patch does not red the release (reduces false-blocks);
+      # a fixable CRITICAL still blocks. Per docs/security/SUPPLY_CHAIN.md. NB: Trivy
+      # scans against a CVE DB that grows continuously — a newly-disclosed CRITICAL on
+      # an unchanged base image can red this gate; the fix is to rebuild on a patched
+      # base, bump the dep, or add a justified .trivyignore entry (see the CVE-variance
+      # note in docs/security/SUPPLY_CHAIN.md).
+      - name: Trivy CRITICAL gate (blocking)
+        if: needs.prepare.outputs.version != 'main'
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+        with:
+          image-ref: ${{ env.GHCR_IMAGE_NAME }}:${{ env.VERSION }}
+          format: table
+          severity: CRITICAL
+          ignore-unfixed: true
+          exit-code: "1"
+
+      - name: Upload Trivy SARIF to Security tab
+        if: needs.prepare.outputs.version != 'main'
+        continue-on-error: true
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: trivy-results.sarif
+          category: trivy-image
 
       - name: Update Docker Hub description
+        # Only refresh README/description when we actually promote :latest
+        # (avoids overwriting from main pushes or back-fill builds).
+        if: needs.prepare.outputs.promote_latest == 'true'
         uses: peter-evans/dockerhub-description@v5
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}

.github/workflows/electron-release.yml

@@ -11,43 +11,56 @@ on:
         required: true
         type: string
 
+# Least-privilege default: read-only at the top level; each job grants the writes it
+# needs (build/release upload assets, publish-npm forwards npm provenance / packages
+# to the reusable workflow) — Scorecard TokenPermissions.
 permissions:
-  contents: write
-  id-token: write
-  packages: write
+  contents: read
 
 jobs:
   validate:
     name: Validate version
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     outputs:
       version: ${{ steps.validate.outputs.version }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
+          persist-credentials: false
           fetch-depth: 0
 
       - name: Validate version format
         id: validate
+        env:
+          # Pass workflow context via env (never interpolate ${{ ... }} straight
+          # into the run: script body) so the shell receives variables, not
+          # inlined text — zizmor template-injection mitigation. INPUT_VERSION is
+          # the operator-supplied value and is regex-validated below before use.
+          EVENT_NAME: ${{ github.event_name }}
+          INPUT_VERSION: ${{ inputs.version }}
         run: |
-          if [[ "${{ github.event_name }}" == "push" ]]; then
+          if [[ "$EVENT_NAME" == "push" ]]; then
             VERSION="${GITHUB_REF#refs/tags/}"
           else
-            VERSION="${{ inputs.version }}"
+            VERSION="$INPUT_VERSION"
           fi
 
           if [[ ! "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
             echo "Error: Invalid version format. Expected: v1.6.8"
             exit 1
           fi
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
           echo "✓ Valid version: $VERSION"
 
   build:
     name: Build Electron (${{ matrix.platform }})
     needs: validate
     runs-on: ${{ matrix.runner }}
+    permissions:
+      contents: write # electron-builder may publish artifacts with GH_TOKEN
     strategy:
       fail-fast: false
       matrix:
@@ -71,7 +84,9 @@ jobs:
             deb_ext: .deb
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
       - name: Setup Node
         uses: actions/setup-node@v6
         with:
@@ -79,7 +94,7 @@ jobs:
           cache: npm
 
       - name: Cache node_modules
-        uses: actions/cache@v5
+        uses: actions/cache@v5.0.5
         with:
           path: node_modules
           key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
@@ -99,17 +114,23 @@ jobs:
           # that cause EPERM errors during Next.js standalone build glob scans.
           # Create a clean temp profile directory to avoid this.
           mkdir -p "$RUNNER_TEMP/home"
-          echo "USERPROFILE=$RUNNER_TEMP/home" >> $GITHUB_ENV
+          echo "USERPROFILE=$RUNNER_TEMP/home" >> "$GITHUB_ENV"
 
       - name: Build Next.js standalone
         env:
           JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
+          NODE_OPTIONS: "--max_old_space_size=6144"
         run: npm run build
 
       - name: Sync version in electron/package.json
         shell: bash
+        env:
+          # Pass the validated version via env (never interpolate ${{ ... }}
+          # straight into the run: script body) — zizmor template-injection
+          # mitigation. Already regex-validated (^v[0-9]+\.[0-9]+\.[0-9]+$) in
+          # the `validate` job, so it cannot carry shell metacharacters.
+          VERSION: ${{ needs.validate.outputs.version }}
         run: |
-          VERSION="${{ needs.validate.outputs.version }}"
           VERSION_NO_V="${VERSION#v}"
           node -e "
             const fs = require('fs');
@@ -135,9 +156,16 @@ jobs:
 
       - name: Smoke packaged Electron app
         if: matrix.platform != 'linux'
-        # Windows CI: requestSingleInstanceLock() fails due to USERPROFILE
-        # sanitization needed for the build step. Smoke is best-effort there.
-        continue-on-error: ${{ matrix.platform == 'windows' }}
+        # Best-effort smoke on Windows + macos-arm64:
+        #  - Windows: requestSingleInstanceLock() fails due to USERPROFILE
+        #    sanitization needed for the build step.
+        #  - macos-arm64: the headless GitHub arm64 runner crashes Electron's GPU
+        #    process (gpu_process_host exit_code=15 → network service crash →
+        #    "No rendezvous client, terminating process"), so the app can't bind
+        #    127.0.0.1:20128 in time. The identical bundle is smoke-gated on
+        #    macos-intel + linux, so packaging is still verified per-OS; we don't
+        #    let the arm64 runner's GPU flakiness block the desktop release.
+        continue-on-error: ${{ matrix.platform == 'windows' || matrix.platform == 'macos-arm64' }}
         env:
           ELECTRON_SMOKE_TIMEOUT_MS: 60000
           ELECTRON_SMOKE_STREAM_LOGS: "1"
@@ -184,10 +212,13 @@ jobs:
     name: Create Release
     needs: [validate, build]
     runs-on: ubuntu-latest
+    permissions:
+      contents: write # softprops/action-gh-release creates the GitHub Release
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
+          persist-credentials: false
           fetch-depth: 0
 
       - name: Download all artifacts
@@ -197,14 +228,20 @@ jobs:
           merge-multiple: true
 
       - name: Create source archives
+        env:
+          # Pass the validated version via env (never interpolate ${{ ... }}
+          # straight into the run: script body) — zizmor template-injection
+          # mitigation. Already regex-validated (^v[0-9]+\.[0-9]+\.[0-9]+$) in
+          # the `validate` job, so it cannot carry shell metacharacters.
+          VERSION: ${{ needs.validate.outputs.version }}
         run: |
           # Create source code archives (excluding dev dependencies and build artifacts)
-          export TARBALL="OmniRoute-${{ needs.validate.outputs.version }}.source.tar.gz"
-          export ZIPBALL="OmniRoute-${{ needs.validate.outputs.version }}.source.zip"
+          export TARBALL="OmniRoute-${VERSION}.source.tar.gz"
+          export ZIPBALL="OmniRoute-${VERSION}.source.zip"
 
           # Use git archive for clean source export
-          git archive --format=tar.gz --prefix=OmniRoute-${{ needs.validate.outputs.version }}/ HEAD -o "release-assets/$TARBALL"
-          git archive --format=zip --prefix=OmniRoute-${{ needs.validate.outputs.version }}/ HEAD -o "release-assets/$ZIPBALL"
+          git archive --format=tar.gz --prefix="OmniRoute-${VERSION}/" HEAD -o "release-assets/$TARBALL"
+          git archive --format=zip --prefix="OmniRoute-${VERSION}/" HEAD -o "release-assets/$ZIPBALL"
 
           echo "✓ Created source archives:"
           ls -lh "release-assets/$TARBALL" "release-assets/$ZIPBALL"
@@ -234,6 +271,14 @@ jobs:
   publish-npm:
     name: Publish to npm
     needs: [validate, release]
+    permissions:
+      # Must be `write`, not `read`: this job calls the reusable npm-publish.yml whose
+      # `publish` job needs `contents: write` (gh release upload — attach the SBOM, #3874).
+      # A reusable workflow's job cannot request more permission than the caller grants,
+      # so a `read` here makes GitHub reject the run at startup (startup_failure).
+      contents: write
+      id-token: write # npm provenance (forwarded to the reusable workflow)
+      packages: write # publish to npm.pkg.github.com
     uses: ./.github/workflows/npm-publish.yml
     with:
       version: ${{ needs.validate.outputs.version }}

.github/workflows/lock-released-branch.yml

@@ -1,14 +1,29 @@
 name: Lock released branch
 
-# When a GitHub Release is published (e.g. tag v3.8.2), make the matching
-# release/<tag> branch read-only so no further commits can land on a shipped
-# version. Uses branch protection's lock_branch + enforce_admins so the freeze
-# applies even to repository admins. To reopen a branch later:
-#   gh api -X DELETE repos/<owner>/<repo>/branches/release/<tag>/protection
+# Two responsibilities (defense in depth — Hard Rule #18 enforcement):
+#
+# 1. `on: release: published` — when a GitHub Release publishes tag v3.X.Y,
+#    apply branch protection (lock_branch + enforce_admins) to release/v3.X.Y
+#    so no further commits can land on a shipped version. To reopen later:
+#      gh api -X DELETE repos/<owner>/<repo>/branches/release/<tag>/protection
+#
+# 2. `on: push: branches: ['release/v*']` — verify that no push lands on a
+#    release/* branch whose matching tag already exists. This is the preventive
+#    guard: if the lock didn't apply (workflow bug, missing PAT, race), this
+#    job FAILS the push run so the operator gets paged immediately.
+#
+# `permissions:` cannot grant the `Administration` scope to GITHUB_TOKEN — that
+# scope only exists on PATs. Set BRANCH_LOCK_TOKEN as a repo secret pointing to
+# a PAT/fine-grained token with `Administration: read & write`. Without it, the
+# lock step will fail loudly (which is what we want — silent failure caused the
+# v3.8.3 incident on 2026-05-26 where 6 commits landed post-release).
 
 on:
   release:
     types: [published]
+  push:
+    branches:
+      - "release/v*"
   workflow_dispatch:
     inputs:
       tag:
@@ -17,23 +32,30 @@ on:
         type: string
 
 permissions:
-  # Editing branch protection requires the administration scope.
-  administration: write
   contents: read
 
 jobs:
+  # ─────────────────────────────────────────────────────────────────────────
+  # Job 1 — Lock the release branch when a Release is published.
+  # ─────────────────────────────────────────────────────────────────────────
   lock-branch:
+    if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     steps:
       - name: Lock release/<tag> branch
         env:
-          GH_TOKEN: ${{ secrets.BRANCH_LOCK_TOKEN || secrets.GITHUB_TOKEN }}
-          # release event -> github.event.release.tag_name; manual -> inputs.tag
+          # Administration scope is required to PUT branch protection. Default
+          # GITHUB_TOKEN cannot do this — operator must provision BRANCH_LOCK_TOKEN.
+          GH_TOKEN: ${{ secrets.BRANCH_LOCK_TOKEN }}
           TAG: ${{ github.event.release.tag_name || inputs.tag }}
           REPO: ${{ github.repository }}
         run: |
           set -euo pipefail
 
+          if [ -z "${GH_TOKEN}" ]; then
+            echo "::error::BRANCH_LOCK_TOKEN secret is not set. Create a PAT with Administration:write and add it as repo secret."
+            exit 1
+          fi
           if [ -z "${TAG}" ]; then
             echo "::error::No tag provided; cannot determine release branch."
             exit 1
@@ -42,7 +64,6 @@ jobs:
           BRANCH="release/${TAG}"
           echo "Target branch: ${BRANCH} (repo: ${REPO})"
 
-          # Skip gracefully if the release branch does not exist.
           if ! gh api "repos/${REPO}/branches/${BRANCH}" >/dev/null 2>&1; then
             echo "::warning::Branch ${BRANCH} not found — nothing to lock."
             exit 0
@@ -68,3 +89,37 @@ jobs:
             exit 1
           fi
           echo "✅ ${BRANCH} is now locked (read-only)."
+
+  # ─────────────────────────────────────────────────────────────────────────
+  # Job 2 — Preventive guard: fail if a push lands on release/vX.Y.Z whose
+  # tag already exists. This catches the case where the lock didn't apply
+  # (PAT missing, race window, workflow bug) and pages the operator.
+  # ─────────────────────────────────────────────────────────────────────────
+  guard-no-push-after-release:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Reject push if matching release tag exists
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          REF: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+
+          # Extract version from ref: release/v3.8.3 -> v3.8.3
+          if [[ ! "${REF}" =~ ^release/(v[0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+            echo "Ref ${REF} does not match release/vX.Y.Z — nothing to guard."
+            exit 0
+          fi
+          TAG="${BASH_REMATCH[1]}"
+          echo "Checking if tag ${TAG} already exists on ${REPO}..."
+
+          if gh api "repos/${REPO}/git/refs/tags/${TAG}" >/dev/null 2>&1; then
+            echo "::error::Hard Rule #18 violation — push to ${REF} but tag ${TAG} is already released."
+            echo "::error::Hotfixes for a released version must go on a NEW branch: release/v$(echo "${TAG#v}" | awk -F. '{$3=$3+1; print $1"."$2"."$3}' OFS=.)"
+            echo "::error::To undo this push: revert the offending commits, or contact an admin to lock the branch if it wasn't already."
+            exit 1
+          fi
+
+          echo "✅ No release tag for ${TAG} yet — push is OK."

.github/workflows/mutation-redundancy.yml

@@ -0,0 +1,63 @@
+name: Mutation Redundancy (disableBail, on-demand)
+# One-off measurement to UNBLOCK R1 (test-redundancy prune). The nightly mutation run
+# (nightly-mutation.yml) bails on the first kill, so `killedBy` lists only the FIRST
+# killer — 🟠 redundant is understated and 🟢 unique overstated (see the caveat in
+# scripts/quality/mutation-radiography.mjs). This workflow re-runs the SAME combo +
+# chatCore leaf batches with stryker.disablebail.json (disableBail:true, incremental:false)
+# so `killedBy` lists EVERY killer. Feed the uploaded reports to
+# `node scripts/quality/mutation-radiography.mjs --candidates mutation-nobail-*/mutation.json`
+# to get the accurate R1 prune-candidate list (🔴 empty ∪ 🟠 redundant) for human review.
+#
+# Batches mirror the nightly's leaf decomposition (d/e/f/g/h/i) rather than 2 mega-batches:
+# disableBail is MORE expensive than bail (it never stops early), and Stryker only writes
+# mutation.json on a SUCCESSFUL finish — a batch cancelled at the cap produces NO data — so
+# smaller batches each fit the 300min headroom and run in parallel. auth/accountFallback and
+# the security quartet are out of scope: R1 targets the combo/chatCore leaves.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  stryker-nobail:
+    name: Stryker disableBail (batch ${{ matrix.batch.name }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        batch:
+          - name: d
+            mutate: "open-sse/services/combo/comboStructure.ts,open-sse/services/combo/autoStrategy.ts,open-sse/services/combo/validateQuality.ts"
+          - name: e
+            mutate: "open-sse/services/combo/shadowRouting.ts,open-sse/services/combo/targetSorters.ts,open-sse/services/combo/comboPredicates.ts,open-sse/services/combo/rrState.ts,open-sse/services/combo/comboData.ts"
+          - name: f
+            mutate: "open-sse/services/combo/quotaScoring.ts,open-sse/services/combo/quotaStrategies.ts"
+          - name: g
+            mutate: "open-sse/handlers/chatCore/comboContextCache.ts,open-sse/handlers/chatCore/idempotency.ts,open-sse/handlers/chatCore/passthroughHelpers.ts,open-sse/handlers/chatCore/responseHeaders.ts,open-sse/handlers/chatCore/sanitization.ts,open-sse/handlers/chatCore/upstreamTimeouts.ts"
+          - name: h
+            mutate: "open-sse/handlers/chatCore/headers.ts,open-sse/handlers/chatCore/logTruncation.ts,open-sse/handlers/chatCore/memoryExtraction.ts,open-sse/handlers/chatCore/nonStreamingSse.ts,open-sse/handlers/chatCore/passthroughToolNames.ts,open-sse/handlers/chatCore/executorHelpers.ts"
+          - name: i
+            mutate: "open-sse/handlers/chatCore/telemetryHelpers.ts,open-sse/handlers/chatCore/memorySkillsInjection.ts,open-sse/handlers/chatCore/semanticCache.ts"
+    timeout-minutes: 300
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+      - run: npm ci
+      - name: Run Stryker (disableBail)
+        env:
+          BATCH_MUTATE: ${{ matrix.batch.mutate }}
+        run: npx stryker run --config-file stryker.disablebail.json --mutate "$BATCH_MUTATE"
+      - name: Upload mutation report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: mutation-nobail-${{ matrix.batch.name }}
+          path: reports/mutation/
+          if-no-files-found: warn
+          retention-days: 14

.github/workflows/nightly-llm-security.yml

@@ -0,0 +1,102 @@
+name: Nightly LLM Security
+on:
+  schedule:
+    - cron: "53 5 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  promptfoo-guard:
+    name: promptfoo — injection guard (block mode, no secret)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with: { node-version: "24", cache: npm }
+      - run: npm ci
+      - name: Build CLI bundle
+        env: { JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation }
+        run: npm run build:cli
+      - name: Start OmniRoute (block mode)
+        env:
+          JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
+          PORT: "20128"
+          INJECTION_GUARD_MODE: block
+        run: |
+          node dist/server.js > server.log 2>&1 &
+          echo $! > server.pid
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:20128/api/monitoring/health >/dev/null; then echo up; break; fi
+            sleep 2
+          done
+      - name: promptfoo guard-validation
+        run: npx --yes promptfoo@latest eval -c promptfooconfig.yaml --no-cache
+        env:
+          OMNIROUTE_URL: http://localhost:20128
+          OMNIROUTE_API_KEY: not-needed-blocked-before-upstream
+      - name: Stop server
+        if: always()
+        run: kill "$(cat server.pid)" || true
+
+  garak:
+    name: garak probes (skip without provider secret)
+    runs-on: ubuntu-latest
+    # NOTE: the `secrets` context is NOT available in a job-level `if:` — referencing
+    # it there makes GitHub reject the file on push (startup_failure on every push).
+    # Map the secret into a job-level env and gate each step on a presence check, so
+    # the job stays green and simply skips the probes when the secret is absent.
+    env:
+      PROMPTFOO_PROVIDER_KEY: ${{ secrets.PROMPTFOO_PROVIDER_KEY }}
+    steps:
+      - name: Gate on provider secret
+        id: gate
+        run: |
+          if [ -n "$PROMPTFOO_PROVIDER_KEY" ]; then
+            echo "run=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "run=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::PROMPTFOO_PROVIDER_KEY not set — skipping garak probes (advisory)."
+          fi
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+        if: steps.gate.outputs.run == 'true'
+      - uses: actions/setup-node@v6
+        if: steps.gate.outputs.run == 'true'
+        with: { node-version: "24", cache: npm }
+      - run: npm ci
+        if: steps.gate.outputs.run == 'true'
+      - name: Build CLI bundle
+        if: steps.gate.outputs.run == 'true'
+        env: { JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation }
+        run: npm run build:cli
+      - name: Start OmniRoute
+        if: steps.gate.outputs.run == 'true'
+        env:
+          JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
+          PORT: "20128"
+        run: |
+          node dist/server.js > server.log 2>&1 &
+          echo $! > server.pid
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:20128/api/monitoring/health >/dev/null; then echo up; break; fi
+            sleep 2
+          done
+      - uses: actions/setup-python@v6
+        if: steps.gate.outputs.run == 'true'
+        with: { python-version: "3.12" }
+      - run: pip install garak
+        if: steps.gate.outputs.run == 'true'
+      - name: garak limited probes
+        if: steps.gate.outputs.run == 'true'
+        env:
+          OPENAI_API_KEY: ${{ secrets.PROMPTFOO_PROVIDER_KEY }}
+          OPENAI_BASE_URL: http://localhost:20128/v1
+        run: garak --model_type openai --model_name gpt-4o-mini --probes promptinject,dan,leakreplay --report_prefix garak-omniroute || true
+      - name: Stop server
+        if: always() && steps.gate.outputs.run == 'true'
+        run: kill "$(cat server.pid)" || true

.github/workflows/nightly-mutation.yml

@@ -0,0 +1,163 @@
+name: Nightly Mutation
+on:
+  schedule:
+    - cron: "17 3 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  stryker:
+    name: Stryker mutation (batch ${{ matrix.batch.name }} — advisory)
+    runs-on: ubuntu-latest
+    # Mutation testing is expensive. History of the budget:
+    #   - Full 8-module set TIMED OUT at the 180min cap (run 27705123780 = exactly 180min).
+    #     The two god-files chatCore.ts/combo.ts dominated ~2/3 of the mutants and were
+    #     removed from stryker.conf.json `mutate`.
+    #   - The remaining 6 modules in 3 batches: auth.ts and accountFallback.ts are large; the
+    #     a (auth+publicCreds) and b (accountFallback+error) batches still ran near the 180min
+    #     cap (the perTest dry-run over ~130 covering test files is itself costly), so the two
+    #     big modules are now ISOLATED into their own batches (a=auth, b=accountFallback).
+    #   - Onda 3 / Fase 9 T5 re-add: combo.ts was split into 11 leaves; the 8 well-covered
+    #     combo/* leaves are back in `mutate` (covered by the 24 combo-*.test.ts), grouped into
+    #     2 batches (d=heavy, e=light). After #4204 (D7b) merged, the reset-aware quota pair
+    #     quotaScoring/quotaStrategies was added as batch f. A covering-test audit then added the
+    #     6 chatCore/* leaves with direct unit coverage as batch g. A follow-up then wrote dedicated
+    #     unit tests for 6 more leaves and added them as batch h. A final follow-up added dedicated
+    #     tests (no mock.module — fetch-override + crafted inputs + temp-DATA_DIR) for telemetryHelpers
+    #     + memorySkillsInjection + semanticCache (its cache-HIT block now has a setCachedResponse
+    #     fixture) as batch i — ALL 15/15 chatCore leaves are now mutated. See
+    #     _mutate_godfiles_excluded_comment in stryker.conf.json.
+    # 9 PARALLEL batches, each overriding the mutate set via `--mutate` (Stryker 9 CLI:
+    # `-m, --mutate <comma-list>`; the conf's `mutate[]` remains the local-run default/union).
+    #   - Cold-seeding budget (per-batch `timeout-minutes: ${{ matrix.batch.timeout || 180 }}`):
+    #     a COLD run must COMPLETE once to write stryker-incremental.json (Stryker writes it only on
+    #     a successful finish); a job cancelled at the cap writes nothing, so the next run is cold
+    #     again — an infinite never-seeds loop. actions/cache is also branch-scoped, so each branch
+    #     (incl. release) must seed its OWN cache via a run with enough headroom. Measured cold runs
+    #     Measured cold totals (run 27801802713, extrapolated from the % at the 180/350 cancel point):
+    #     auth ~375min (2301 mutants — EXCEEDS the 360min job max even isolated), accountFallback
+    #     ~358min (1441), the c security quartet ~348min (1163), d ~197min (1316), g=142, h=132, e=66,
+    #     f=45, i=33. The widely-covered modules blow the budget because the tap-runner re-runs every
+    #     covering test file per mutant (a perTest fixed cost over ~138 test files, times thousands of
+    #     mutants). A flat timeout bump cannot rescue auth (>360min max) — so the three over-budget
+    #     batches are SPLIT so each half fits: auth->a1/a2 and accountFallback->b1/b2 by mutation range
+    #     (`file:startLine-endLine`), the c quartet->c1/c2 by module pair. Splitting also seeds each
+    #     sub-batch's own incremental cache, after which nightlies re-test only changed mutants.
+    # Full coverage every night in parallel; wall-clock = the slowest batch's cold run until seeded.
+    # Runs at stryker concurrency=4 with per-process DATA_DIR isolation
+    # (tests/_setup/isolateDataDir.ts) — see _concurrency_comment in stryker.conf.json.
+    strategy:
+      fail-fast: false
+      matrix:
+        batch:
+          # Per-batch `timeout` (minutes) tiers the cold-seeding budget by measured cost; batches
+          # without the key default to 180. Cold-run profiling (run 27801802713) showed the
+          # widely-covered modules need FAR more than the 180 cap because the tap-runner re-runs every
+          # covering test file per mutant: auth ~375min (2301 mutants, EXCEEDS the 360min GitHub job
+          # max even isolated), accountFallback ~358min, the c security quartet ~348min — none fit a
+          # single job. So auth/accountFallback are split by MUTATION RANGE (`file:startLine-endLine`,
+          # ~half the mutants each) into a1/a2, b1/b2; the c quartet is split by MODULE pair into
+          # c1/c2. d (3 combo modules, ~197min) stays whole. Split-heavy batches get 300min headroom
+          # for their cold seeding run; once each batch completes once and writes
+          # stryker-incremental.json, later runs re-test only changed mutants and finish far faster.
+          # g/h (142/132min cold) keep a 240 buffer; e/f/i (33-66min) keep the 180 default.
+          - name: a1
+            mutate: "src/sse/services/auth.ts:1-1109"
+            timeout: 300
+          - name: a2
+            mutate: "src/sse/services/auth.ts:1110-2218"
+            timeout: 300
+          - name: b1
+            mutate: "open-sse/services/accountFallback.ts:1-863"
+            timeout: 300
+          - name: b2
+            mutate: "open-sse/services/accountFallback.ts:864-1726"
+            timeout: 300
+          - name: c1
+            mutate: "src/server/authz/routeGuard.ts,src/shared/utils/circuitBreaker.ts"
+            timeout: 300
+          - name: c2
+            mutate: "open-sse/utils/error.ts,open-sse/utils/publicCreds.ts"
+            timeout: 300
+          - name: d
+            mutate: "open-sse/services/combo/comboStructure.ts,open-sse/services/combo/autoStrategy.ts,open-sse/services/combo/validateQuality.ts"
+            timeout: 300
+          - name: e
+            mutate: "open-sse/services/combo/shadowRouting.ts,open-sse/services/combo/targetSorters.ts,open-sse/services/combo/comboPredicates.ts,open-sse/services/combo/rrState.ts,open-sse/services/combo/comboData.ts"
+          - name: f
+            mutate: "open-sse/services/combo/quotaScoring.ts,open-sse/services/combo/quotaStrategies.ts"
+          - name: g
+            mutate: "open-sse/handlers/chatCore/comboContextCache.ts,open-sse/handlers/chatCore/idempotency.ts,open-sse/handlers/chatCore/passthroughHelpers.ts,open-sse/handlers/chatCore/responseHeaders.ts,open-sse/handlers/chatCore/sanitization.ts,open-sse/handlers/chatCore/upstreamTimeouts.ts"
+            timeout: 240
+          - name: h
+            mutate: "open-sse/handlers/chatCore/headers.ts,open-sse/handlers/chatCore/logTruncation.ts,open-sse/handlers/chatCore/memoryExtraction.ts,open-sse/handlers/chatCore/nonStreamingSse.ts,open-sse/handlers/chatCore/passthroughToolNames.ts,open-sse/handlers/chatCore/executorHelpers.ts"
+            timeout: 240
+          - name: i
+            mutate: "open-sse/handlers/chatCore/telemetryHelpers.ts,open-sse/handlers/chatCore/memorySkillsInjection.ts,open-sse/handlers/chatCore/semanticCache.ts"
+    # Per-batch budget: split-heavy batches (a1/a2/b1/b2/c1/c2/d) override to 300min, g/h to 240min;
+    # the rest default to 180min. `matrix.batch.timeout` is null for batches without the key -> `|| 180`.
+    # NOTE: a1+a2 both mutate auth.ts (disjoint line ranges) and b1+b2 both mutate accountFallback.ts;
+    # when merging the per-batch mutation.json for radiography/scores, same-file mutants from sibling
+    # ranges must be UNIONED (scripts/check/check-mutation-ratchet.mjs::measureMutationScores and
+    # scripts/quality/mutation-radiography.mjs both merge per file).
+    timeout-minutes: ${{ matrix.batch.timeout || 180 }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+      - run: npm ci
+      - name: Restore Stryker incremental cache
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: reports/mutation/stryker-incremental.json
+          key: stryker-incremental-${{ matrix.batch.name }}-${{ github.run_id }}
+          restore-keys: stryker-incremental-${{ matrix.batch.name }}-
+      - name: Run Stryker (advisory)
+        id: stryker
+        continue-on-error: true
+        env:
+          BATCH_MUTATE: ${{ matrix.batch.mutate }}
+        run: npx stryker run --mutate "$BATCH_MUTATE"
+      - name: Upload mutation report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: mutation-report-${{ matrix.batch.name }}
+          path: reports/mutation/
+          if-no-files-found: warn
+          retention-days: 14
+
+  # Aggregation gate (T3): each split batch emits a PARTIAL view of a mutated file
+  # (auth.ts lives in a1+a2, accountFallback in b1+b2), so a PER-BATCH ratchet would
+  # only ever see half a file vs the whole-file baseline. This job runs AFTER every
+  # batch, downloads all reports, and ratchets the MERGED per-module scores
+  # (check-mutation-ratchet UNIONS same-file mutants across reports) against the
+  # dedicatedGate `mutationScore.*` floors in quality-baseline.json (seeded ~2pt below
+  # the first full measurement). Blocking: a module dropping below its floor fails the
+  # run. Missing reports (e.g. an artifact-upload flake) are skipped, never failed.
+  mutation-ratchet:
+    name: Mutation score ratchet (blocking)
+    needs: stryker
+    if: always()
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+      - name: Download all mutation reports
+        uses: actions/download-artifact@v8
+        with:
+          pattern: mutation-report-*
+          path: reports/all
+      - name: Ratchet merged per-module mutation scores
+        run: node scripts/check/check-mutation-ratchet.mjs reports/all/*/mutation.json --ratchet

.github/workflows/nightly-property.yml

@@ -0,0 +1,35 @@
+name: Nightly Property Discovery
+on:
+  schedule:
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+permissions:
+  contents: read
+  issues: write
+jobs:
+  property-random-seed:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+      - run: npm ci
+      - name: fast-check random seed (high runs)
+        id: prop
+        run: FC_SEED=random FC_NUM_RUNS=2000 npm run test:property
+      - name: Open issue on failure
+        if: failure()
+        uses: actions/github-script@v9
+        with:
+          script: |
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: "Nightly property-test failure (Fase 8 B)",
+              body: "fast-check found a counterexample with a random seed. Check the run logs for the reproducible seed + minimal case, then add it as a fixture.\n\nRun: " + context.serverUrl + "/" + context.repo.owner + "/" + context.repo.repo + "/actions/runs/" + context.runId,
+              labels: ["quality-gate-finding"],
+            });

.github/workflows/nightly-release-green.yml

@@ -0,0 +1,137 @@
+name: Nightly Release-Green
+
+# Solution D — continuous, NON-BLOCKING drift signal for the active release branch.
+#
+# WHY: the full gate (ci.yml) only runs on the release PR (PR → main), so reds
+# accrue silently on release/** and explode — in layers — at release time. This
+# nightly reproduces the release-equivalent validation on the active release branch
+# HEAD and, when there are HARD failures, opens/updates a single tracking issue.
+#
+# It is NOT a required status check and never touches a contributor PR — it only
+# reports. Ratchet drift (eslint warnings / cognitive-complexity / file-size) is
+# expected mid-cycle and is reported but never raises the alarm on its own; only
+# real defects (typecheck / lint errors / unit / vitest / db-rules / public-creds /
+# package-artifact) flip the issue open.
+
+on:
+  schedule:
+    - cron: "23 5 * * *" # 05:23 UTC daily — off-peak, distinct from other nightlies
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: "Release branch to validate (default: highest release/vX.Y.Z)"
+        required: false
+        type: string
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: nightly-release-green
+  cancel-in-progress: true
+
+jobs:
+  release-green:
+    name: Validate active release branch
+    runs-on: ubuntu-latest
+    env:
+      JWT_SECRET: ci-nightly-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-nightly-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Resolve active release branch
+        id: branch
+        env:
+          INPUT_BRANCH: ${{ github.event.inputs.branch }}
+        run: |
+          set -euo pipefail
+          if [ -n "${INPUT_BRANCH:-}" ]; then
+            TARGET="$INPUT_BRANCH"
+          else
+            # highest release/vX.Y.Z by semver among remote branches
+            TARGET=$(git for-each-ref --format='%(refname:short)' 'refs/remotes/origin/release/v*' \
+              | sed 's#origin/##' \
+              | sort -t/ -k2 -V \
+              | tail -1)
+          fi
+          if [ -z "$TARGET" ]; then echo "No release/v* branch found"; exit 1; fi
+          # Strict format guard — reject anything that isn't release/vX.Y.Z (blocks
+          # ref/command injection via the workflow_dispatch input).
+          if ! printf '%s' "$TARGET" | grep -qE '^release/v[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "Refusing non-canonical branch name: $TARGET"; exit 1
+          fi
+          echo "target=$TARGET" >> "$GITHUB_OUTPUT"
+          echo "Active release branch: $TARGET"
+
+      - name: Checkout the release branch
+        env:
+          TARGET: ${{ steps.branch.outputs.target }}
+        run: |
+          set -euo pipefail
+          git checkout "$TARGET"
+          git log -1 --oneline
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+
+      - uses: ./.github/actions/npm-ci-retry
+
+      - name: Release-green validation (full)
+        id: validate
+        run: |
+          set +e
+          node scripts/quality/validate-release-green.mjs --json --with-build \
+            1> release-green.json 2> release-green.log
+          echo "exit=$?" >> "$GITHUB_OUTPUT"
+          echo "------- report -------"
+          cat release-green.log
+
+      - name: Open / update tracking issue on HARD failure
+        if: steps.validate.outputs.exit != '0'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TARGET: ${{ steps.branch.outputs.target }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          TITLE="🔴 Release branch not green: ${TARGET}"
+          {
+            echo "The nightly **release-green** validation found HARD failures on \`${TARGET}\`."
+            echo "These are real defects that would block the release PR — fix them in the"
+            echo "originating PR branch (via co-authorship), not by demanding it from contributors."
+            echo ""
+            echo "**Run:** ${RUN_URL}"
+            echo ""
+            echo '```'
+            sed -n '/──────── verdict ────────/,$p' release-green.log || tail -40 release-green.log
+            echo '```'
+            echo ""
+            echo "_Ratchet drift (eslint warnings / cognitive-complexity / file-size) listed above is expected mid-cycle and is rebaselined at release — it is NOT a contributor concern and did not, on its own, open this issue._"
+          } > issue-body.md
+
+          EXISTING=$(gh issue list --repo "$GITHUB_REPOSITORY" --state open \
+            --search "in:title $TITLE" --json number --jq '.[0].number' 2>/dev/null || echo "")
+          if [ -n "$EXISTING" ]; then
+            gh issue comment "$EXISTING" --repo "$GITHUB_REPOSITORY" --body-file issue-body.md
+            echo "Updated existing issue #$EXISTING"
+          else
+            gh issue create --repo "$GITHUB_REPOSITORY" --title "$TITLE" --body-file issue-body.md
+          fi
+
+      - name: Upload report artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-green-report
+          path: |
+            release-green.json
+            release-green.log
+          if-no-files-found: ignore

.github/workflows/nightly-resilience.yml

@@ -0,0 +1,110 @@
+name: Nightly Resilience
+on:
+  schedule:
+    - cron: "41 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  heap:
+    name: Heap-growth gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+      - run: npm ci
+      - run: npm run test:heap
+
+  chaos:
+    name: Resilience chaos (fault injection)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+      - run: npm ci
+      - run: npm run test:chaos
+
+  k6-soak:
+    name: k6 load/soak
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+      - run: npm ci
+      - name: Build CLI bundle
+        env:
+          JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
+        run: npm run build:cli
+      - name: Start OmniRoute (background)
+        env:
+          JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
+          PORT: "20128"
+        run: |
+          node dist/server.js > server.log 2>&1 &
+          echo $! > server.pid
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:20128/api/monitoring/health >/dev/null; then echo "server up"; break; fi
+            sleep 2
+          done
+      - name: Install k6
+        uses: grafana/setup-k6-action@v1
+      - name: Run k6 soak
+        run: k6 run tests/load/k6-soak.js
+        env:
+          BASE_URL: http://localhost:20128
+          SOAK_DURATION: "3m"
+          SOAK_VUS: "10"
+      - name: Stop server
+        if: always()
+        run: kill "$(cat server.pid)" || true
+
+  a11y:
+    name: A11y axe (nightly, freeze-and-alert)
+    runs-on: ubuntu-latest
+    # The Playwright webServer (`start` mode) builds Next via build-next-isolated.mjs and
+    # boots the standalone server itself (waits on /api/monitoring/health, 15min webServer
+    # timeout). Unlike the per-PR test-e2e job, this nightly job has no pre-built artifact,
+    # so it self-builds — hence the generous job timeout. REQUIRE_AXE=1 makes the suite run
+    # the real axe analysis (the 4 page tests are gated to nightly so per-PR e2e stays fast)
+    # and makes the meta-test fail loudly if @axe-core/playwright ever goes missing.
+    timeout-minutes: 30
+    env:
+      JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-test-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+      REQUIRE_AXE: "1"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+      - run: npm ci
+      - name: Cache Playwright browsers
+        uses: actions/cache@v5.0.5
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-chromium-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          restore-keys: playwright-chromium-${{ runner.os }}-
+      - run: npx playwright install --with-deps chromium
+      - name: Run axe a11y suite (self-building webServer)
+        run: npx playwright test tests/e2e/a11y.spec.ts

.github/workflows/nightly-schemathesis.yml

@@ -0,0 +1,72 @@
+name: Nightly Schemathesis
+on:
+  schedule:
+    - cron: "23 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  schemathesis:
+    name: Schemathesis — OpenAPI contract fuzz (advisory)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with: { node-version: "24", cache: npm }
+      - run: npm ci
+      - name: Build CLI bundle
+        env: { JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation }
+        run: npm run build:cli
+      - name: Start OmniRoute (background)
+        env:
+          JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
+          PORT: "20128"
+        run: |
+          node dist/server.js > server.log 2>&1 &
+          echo $! > server.pid
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:20128/api/monitoring/health >/dev/null; then echo "server up"; break; fi
+            sleep 2
+          done
+      - uses: actions/setup-python@v6
+        with: { python-version: "3.12" }
+      - name: Install schemathesis
+        run: pip install schemathesis
+      - name: Schemathesis contract fuzz (advisory)
+        # Advisory gate: never fails the job. `continue-on-error` covers a crash of the
+        # step itself; `|| true` covers schemathesis exiting non-zero when it finds spec
+        # violations / upstream 500s — both are expected here (most /v1 endpoints proxy an
+        # upstream that has no provider configured in CI). The point of the nightly is to
+        # PROVE the contract is fuzzable and surface regressions, not to gate the build.
+        continue-on-error: true
+        run: |
+          schemathesis run docs/openapi.yaml \
+            --url http://localhost:20128 \
+            --max-examples 20 \
+            --workers 4 \
+            --checks all \
+            --max-response-time 30 \
+            --request-timeout 30 \
+            --suppress-health-check all \
+            --report junit \
+            --report-junit-path schemathesis-report/junit.xml \
+            --no-color \
+            || true
+      - name: Stop server
+        if: always()
+        run: kill "$(cat server.pid)" || true
+      - name: Upload schemathesis report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: schemathesis-report
+          path: |
+            schemathesis-report/
+            server.log
+          if-no-files-found: warn
+          retention-days: 14

.github/workflows/npm-publish.yml

@@ -1,8 +1,11 @@
 name: Publish to npm
 
 on:
+  # 'released' (not 'published') so editing/re-publishing old releases does NOT
+  # re-trigger this workflow. Pairs with the semver guard below as defense in
+  # depth against accidental dist-tag clobbering by old releases.
   release:
-    types: [published]
+    types: [released]
   workflow_dispatch:
     inputs:
       version:
@@ -10,13 +13,15 @@ on:
         required: true
         type: string
       tag:
-        description: "npm dist-tag (latest / next)"
+        description: "npm dist-tag (auto / latest / next / historic)"
         required: false
-        default: "latest"
+        default: "auto"
         type: choice
         options:
+          - auto
           - latest
           - next
+          - historic
   workflow_call:
     inputs:
       version:
@@ -24,18 +29,19 @@ on:
         required: true
         type: string
       tag:
-        description: "npm dist-tag (latest / next)"
+        description: "npm dist-tag (auto / latest / next / historic)"
         required: false
-        default: "latest"
+        default: "auto"
         type: string
     secrets:
       NPM_TOKEN:
         required: true
 
+# Least-privilege default: read-only at the top level; each publish job grants the
+# id-token (npm provenance) / packages (GitHub Packages) writes it needs (Scorecard
+# TokenPermissions).
 permissions:
   contents: read
-  id-token: write
-  packages: write
 
 env:
   NPM_PUBLISH_NODE_VERSION: "24"
@@ -43,10 +49,18 @@ env:
 jobs:
   publish:
     runs-on: ubuntu-latest
-    environment: NPM_TOKEN
+    permissions:
+      contents: write # gh release upload (attach SBOM to the GitHub Release)
+      id-token: write # npm provenance
+      packages: write # publish to npm.pkg.github.com
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          # Need full tag history to compare against highest semver when
+          # deciding whether this release should claim dist-tag `latest`.
+          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
@@ -57,87 +71,140 @@ jobs:
       - name: Install dependencies (skip scripts to avoid heavy build)
         run: npm install --ignore-scripts --no-audit --no-fund
 
-      - name: Resolve version and dist-tag
+      - name: Resolve version, dist-tag and skip flag
         id: resolve
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          REF_NAME: ${{ github.ref_name }}
+          INPUT_VERSION: ${{ inputs.version }}
+          INPUT_TAG: ${{ inputs.tag }}
         run: |
-          VERSION="${{ inputs.version }}"
-          TAG="${{ inputs.tag }}"
+          set -euo pipefail
 
-          if [ -z "$VERSION" ]; then
-            if [ "${{ github.event_name }}" = "release" ]; then
-              VERSION="${GITHUB_REF_NAME}"
-            fi
+          # 1) Resolve VERSION from the trigger (all inputs come via env).
+          VERSION="${INPUT_VERSION:-}"
+          if [ -z "$VERSION" ] && [ "$EVENT_NAME" = "release" ]; then
+            VERSION="$REF_NAME"
+          fi
+          VERSION="${VERSION#v}"
+          if ! printf '%s' "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+([.-][A-Za-z0-9.-]+)?$'; then
+            echo "Refusing to publish unsafe VERSION value: $VERSION" >&2
+            exit 1
           fi
 
-          # Strip v prefix if present
-          VERSION="${VERSION#v}"
-
-          # Default dist-tag logic
-          if [ -z "$TAG" ]; then
-            if [[ "$VERSION" == *-* ]]; then
+          # 2) Resolve dist-tag.
+          #    - explicit 'latest'/'next'/'historic' is honored
+          #    - 'auto' (or empty): pre-release identifiers → 'next';
+          #      stable versions → 'latest' only if VERSION is the highest
+          #      stable semver among `v*` tags (otherwise → 'historic').
+          REQUESTED_TAG="${INPUT_TAG:-auto}"
+          TAG="$REQUESTED_TAG"
+          if [ "$TAG" = "auto" ] || [ -z "$TAG" ]; then
+            if printf '%s' "$VERSION" | grep -qE -- '-(rc|alpha|beta|pre|next)'; then
               TAG="next"
             else
-              TAG="latest"
+              git fetch --tags --quiet || true
+              HIGHEST=$(git tag -l 'v[0-9]*' | sed 's/^v//' | grep -vE -- '-(rc|alpha|beta|pre|next)' | sort -V | tail -1 || echo "")
+              if [ -n "$HIGHEST" ] && [ "$VERSION" = "$HIGHEST" ]; then
+                TAG="latest"
+              else
+                echo "Version $VERSION is not the highest semver tag (highest=${HIGHEST:-<none>}). Using dist-tag 'historic' to avoid clobbering @latest."
+                TAG="historic"
+              fi
             fi
           fi
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
-          echo "tag=$TAG" >> $GITHUB_OUTPUT
-          echo "📦 Publishing omniroute@$VERSION with tag=$TAG"
+
+          # 3) Skip-if-already-published. NOTE: do NOT pass `--silent` to
+          #    `npm view` — it suppresses stdout and breaks the grep, which
+          #    caused old releases (3.2.8) to be re-published and steal
+          #    dist-tag `latest`. See incident notes in CHANGELOG.
+          PUBLISHED="$(npm view "omniroute@${VERSION}" version 2>/dev/null || true)"
+          SKIP="false"
+          if [ "$PUBLISHED" = "$VERSION" ]; then
+            echo "⚠️ omniroute@${VERSION} is already on npm — skipping publish."
+            SKIP="true"
+          fi
+
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=$TAG"          >> "$GITHUB_OUTPUT"
+          echo "skip=$SKIP"        >> "$GITHUB_OUTPUT"
+          echo "📦 Resolved omniroute@$VERSION dist-tag=$TAG skip=$SKIP"
 
       - name: Sync package.json version
+        if: steps.resolve.outputs.skip != 'true'
+        env:
+          VERSION: ${{ steps.resolve.outputs.version }}
         run: |
-          npm version "${{ steps.resolve.outputs.version }}" --no-git-tag-version --allow-same-version
+          npm version "$VERSION" --no-git-tag-version --allow-same-version
 
       - name: Build CLI bundle (standalone app)
+        if: steps.resolve.outputs.skip != 'true'
         env:
           JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
         run: npm run build:cli
 
       - name: Validate npm package artifact
+        if: steps.resolve.outputs.skip != 'true'
         run: npm run check:pack-artifact
 
-      - name: Publish to npm
-        run: |
-          VERSION="${{ steps.resolve.outputs.version }}"
-          TAG="${{ steps.resolve.outputs.tag }}"
-          # Check if this version is already published — skip instead of failing with E403
-          if npm view "omniroute@${VERSION}" version --silent 2>/dev/null | grep -q "^${VERSION}$"; then
-            echo "⚠️ Version ${VERSION} is already published on npm — skipping."
-            exit 0
-          fi
-          if [ "$TAG" = "latest" ]; then
-            npm publish --access public
-          else
-            npm publish --access public --tag "$TAG"
-          fi
-          echo "✅ Published omniroute@$VERSION (tag: $TAG)"
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Generate CycloneDX SBOM (npm)
+        if: steps.resolve.outputs.skip != 'true'
+        run: npx @cyclonedx/cyclonedx-npm --ignore-npm-errors --output-format JSON --output-file sbom-npm.cdx.json
 
-      - name: Publish to GitHub Packages
-        run: |
-          VERSION="${{ steps.resolve.outputs.version }}"
-          TAG="${{ steps.resolve.outputs.tag }}"
+      - name: Upload SBOM (npm) as workflow artifact
+        if: steps.resolve.outputs.skip != 'true'
+        uses: actions/upload-artifact@v7
+        with:
+          name: sbom-npm
+          path: sbom-npm.cdx.json
+          if-no-files-found: error
 
-          echo "Configuring for GitHub Packages..."
-          echo "//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" > .npmrc
-          npm pkg set name="@diegosouzapw/omniroute"
-
-          if [ "$TAG" = "latest" ]; then
-            npm publish --registry=https://npm.pkg.github.com || echo "⚠️ Version ${VERSION} might already be published on GitHub."
-          else
-            npm publish --registry=https://npm.pkg.github.com --tag "$TAG" || echo "⚠️ Version ${VERSION} might already be published on GitHub."
-          fi
-          echo "✅ Action finished for GitHub Packages"
+      - name: Attach SBOM to GitHub Release
+        if: steps.resolve.outputs.skip != 'true' && github.event_name == 'release'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.ref_name }}
+        run: gh release upload "$TAG" sbom-npm.cdx.json --clobber
+
+      - name: Publish to npm
+        if: steps.resolve.outputs.skip != 'true'
+        env:
+          VERSION: ${{ steps.resolve.outputs.version }}
+          TAG: ${{ steps.resolve.outputs.tag }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          set -euo pipefail
+          # Always pass --tag explicitly. Defense in depth: even if VERSION is
+          # accidentally an older release, `npm publish --tag historic` will
+          # NOT promote it to `@latest`.
+          npm publish --provenance --access public --tag "$TAG"
+          echo "✅ Published omniroute@$VERSION (dist-tag=$TAG)"
+
+      - name: Publish to GitHub Packages
+        if: steps.resolve.outputs.skip != 'true'
+        env:
+          VERSION: ${{ steps.resolve.outputs.version }}
+          TAG: ${{ steps.resolve.outputs.tag }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          echo "Configuring for GitHub Packages..."
+          echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" > .npmrc
+          npm pkg set name="@diegosouzapw/omniroute"
+          npm publish --registry=https://npm.pkg.github.com --tag "$TAG" \
+            || echo "⚠️ omniroute@${VERSION} might already be published on GitHub Packages."
+          echo "✅ Action finished for GitHub Packages"
 
   publish-opencode-plugin:
     runs-on: ubuntu-latest
-    environment: NPM_TOKEN
+    permissions:
+      contents: read
+      id-token: write # npm provenance
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
@@ -159,14 +226,17 @@ jobs:
 
       - name: Publish @omniroute/opencode-plugin to npm
         working-directory: "@omniroute/opencode-plugin"
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
+          set -euo pipefail
           PKG_VERSION=$(node -p "require('./package.json').version")
           PKG_NAME=$(node -p "require('./package.json').name")
-          if npm view "${PKG_NAME}@${PKG_VERSION}" version --silent 2>/dev/null | grep -q "^${PKG_VERSION}$"; then
+          # Same hardened skip-check as the main job (no --silent flag).
+          PUBLISHED="$(npm view "${PKG_NAME}@${PKG_VERSION}" version 2>/dev/null || true)"
+          if [ "$PUBLISHED" = "$PKG_VERSION" ]; then
             echo "⚠️ ${PKG_NAME}@${PKG_VERSION} is already published on npm — skipping."
             exit 0
           fi
-          npm publish --access public --ignore-scripts
+          npm publish --provenance --access public --ignore-scripts
           echo "✅ Published ${PKG_NAME}@${PKG_VERSION}"
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/opencode-plugin-ci.yml

@@ -32,8 +32,10 @@ jobs:
       matrix:
         node: ["22", "24"]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node }}
           cache: npm
@@ -47,15 +49,17 @@ jobs:
     runs-on: ubuntu-latest
     needs: test
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
         with:
           node-version: "22"
           cache: npm
           cache-dependency-path: "@omniroute/opencode-plugin/package-lock.json"
       - run: npm install --no-audit --no-fund
       - run: npm run build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: opencode-plugin-dist
           path: "@omniroute/opencode-plugin/dist"

.github/workflows/opencode-provider-ci.yml

@@ -32,7 +32,9 @@ jobs:
       matrix:
         node: ["20", "22", "24"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
       - uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node }}
@@ -46,7 +48,9 @@ jobs:
     runs-on: ubuntu-latest
     needs: test
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
       - uses: actions/setup-node@v6
         with:
           node-version: "20"

.github/workflows/quality.yml

@@ -0,0 +1,132 @@
+name: Quality Gates
+
+on:
+  pull_request:
+    branches: ["release/**"]
+    types: [opened, synchronize, reopened, ready_for_review]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  CI_NODE_VERSION: "24"
+
+jobs:
+  fast-gates:
+    name: Fast Quality Gates
+    runs-on: ubuntu-latest
+    # tsx gates (known-symbols, route-guard-membership) import modules that open
+    # SQLite on load; provide DB env so a fresh CI DB initializes cleanly.
+    env:
+      JWT_SECRET: ci-lint-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-lint-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      - run: npm run check:provider-consistency
+      - run: npm run check:fetch-targets
+      - run: npm run check:openapi-routes
+      - run: npm run check:docs-symbols
+      - name: Docs accuracy (fabricated-docs + i18n mirrors, strict)
+        run: npm run check:docs-all
+      - run: npm run check:deps
+      - run: npm run check:file-size
+      - run: npm run check:error-helper
+      - run: npm run check:migration-numbering
+      - run: npm run check:public-creds
+      - run: npm run check:db-rules
+      - run: npm run check:known-symbols
+      - run: npm run check:route-guard-membership
+      - run: npm run check:test-discovery
+      - run: npm run check:test-runner-api
+      - run: npm run check:any-budget:t11
+      - name: Typecheck (core)
+        run: npm run typecheck:core
+      # TIA: build the impact map at runtime (gitignored, ~21MB) and run only the
+      # unit tests impacted by this PR's changed files. Fail-safe runs the FULL
+      # unit suite on hub/unmapped changes — TIA accelerates, never replaces, the net.
+      #
+      # BLOCKING (flipped 2026-06-17). The pre-existing release unit test-debt that kept
+      # this advisory was cleared: #4030 (16 Zod/registry reds, lossless restore) and
+      # #4063 (the last red — the LiveWS boot test — root-caused as a real event-loop
+      # stall in the WS sidecar, fixed + relocated to the integration suite). A full
+      # ci.yml run on release/v3.8.28 then showed all 8 unit shards green, so PR->release
+      # now blocks on unit-test regressions in the impacted set (typecheck:core already
+      # blocked above). Fail-safe still runs the FULL unit suite on hub/unmapped changes.
+      - name: Impacted unit tests (TIA, fail-safe full; blocking)
+        env:
+          GITHUB_BASE_REF: ${{ github.base_ref }}
+        run: |
+          git fetch --no-tags origin "$GITHUB_BASE_REF" || true
+          node scripts/quality/build-test-impact-map.mjs
+          SEL="$(node scripts/quality/select-impacted-tests.mjs)"
+          if [ -z "$SEL" ]; then echo "No source/test changes — skipping unit tests"; exit 0; fi
+          # CI runners are 4-vCPU; run at --test-concurrency=4 (matching the ci.yml unit
+          # job) rather than test:unit's local-tuned concurrency=20. Oversubscribing the
+          # runner makes timing-sensitive tests (db-backup, upstream-timeout, ...) flake,
+          # which must not happen on a blocking gate. DATA_DIR isolation keeps the parallel
+          # run race-free regardless of concurrency.
+          if echo "$SEL" | grep -q "__RUN_ALL__"; then
+            echo "Fail-safe: running FULL unit suite (CI concurrency)"; npm run test:unit:ci; exit $?
+          fi
+          echo "Running impacted tests:"; echo "$SEL"
+          mapfile -t FILES <<< "$SEL"
+          node --import tsx --import ./open-sse/utils/setupPolyfill.ts --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 "${FILES[@]}"
+
+  fast-vitest:
+    name: Vitest (fast-path)
+    runs-on: ubuntu-latest
+    env:
+      JWT_SECRET: ci-lint-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-lint-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      - run: npm run test:vitest
+
+  fast-unit:
+    name: Unit Tests fast-path (${{ matrix.shard }}/2)
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2]
+    env:
+      JWT_SECRET: ci-lint-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-lint-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      - run: >
+          node --max-old-space-size=4096 --import tsx
+          --import ./tests/_setup/isolateDataDir.ts
+          --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/2
+          tests/unit/*.test.ts
+          "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui}/**/*.test.ts"

.github/workflows/scorecard.yml

@@ -0,0 +1,40 @@
+name: OpenSSF Scorecard
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: "27 7 * * 1"
+  push:
+    branches: ["main"]
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      # security-events: write removed — Scorecard findings are advisory and no longer
+      # uploaded to the code-scanning Security tab (they are supply-chain/posture scores,
+      # not code vulnerabilities, and drowned out real CodeQL alerts). The run still
+      # produces the OpenSSF badge (publish_results) and a downloadable SARIF artifact.
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Run analysis
+        uses: ossf/scorecard-action@v2.4.3
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5

.github/workflows/semgrep.yml

@@ -0,0 +1,29 @@
+name: semgrep
+on:
+  pull_request:
+    branches: ["main", "release/**"]
+  push:
+    branches: ["main"]
+permissions:
+  contents: read
+jobs:
+  semgrep:
+    runs-on: ubuntu-latest
+    container:
+      image: semgrep/semgrep
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - name: Run semgrep (advisory)
+        continue-on-error: true
+        run: |
+          semgrep scan --config p/owasp-top-ten --config p/secrets \
+            --sarif --output semgrep.sarif --metrics off || true
+          python -c "import json; d=json.load(open('semgrep.sarif')); print('semgrepFindings=%d' % len(d['runs'][0]['results']))" || echo "semgrepFindings=SKIP"
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: always()
+        with:
+          name: semgrep-sarif
+          path: semgrep.sarif
+          retention-days: 14

.github/workflows/wiki-sync.yml

@@ -0,0 +1,69 @@
+name: Wiki Sync
+
+# Keeps the GitHub wiki in sync with docs/ on every release that lands on main.
+# The wiki has no native generator and historically drifts (it sat at "212+ providers /
+# 14 strategies / 37 MCP tools" while code was at 226 / 15 / 87, and new docs like
+# SUPPLY_CHAIN never appeared). This runs scripts/docs/sync-wiki.mjs, which:
+#   - ADDS any docs/ page missing from the wiki (curated; internal reports excluded),
+#   - syncs the four cover-page counts on Home.md.
+# It does NOT overwrite existing wiki pages by default: several docs sources still carry
+# stale counts (e.g. ARCHITECTURE.md says "177 providers" while the wiki cover is 226),
+# so blind overwrite would regress the wiki. Full content parity (--update-existing) is
+# gated on regenerating those sources — see docs/ops/DOCUMENTATION_AUDIT_REPORT.md.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "README.md"
+      - "AGENTS.md"
+      - "src/shared/constants/routingStrategies.ts"
+      - "config/i18n.json"
+      - "open-sse/mcp-server/server.ts"
+      - "scripts/docs/sync-wiki.mjs"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: wiki-sync
+  cancel-in-progress: false
+
+jobs:
+  sync-wiki:
+    name: Sync wiki with docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v7
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+
+      - name: Clone wiki
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          git clone "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.wiki.git" wiki
+
+      - name: Sync wiki (add missing pages + cover counts)
+        run: node scripts/docs/sync-wiki.mjs --wiki-dir wiki
+
+      - name: Commit & push if changed
+        run: |
+          cd wiki
+          if [ -n "$(git status --porcelain)" ]; then
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git add -A
+            git commit -m "docs(wiki): auto-sync pages + cover counts with docs"
+            git push
+            echo "Wiki updated."
+          else
+            echo "Wiki already in sync — nothing to push."
+          fi

.gitignore

@@ -4,6 +4,30 @@
 .omnivscodeagent/
 omnirouteCloud/
 omnirouteSite/
+_cache/
+_ideia/
+_mono_repo/
+_references/
+_tasks/
+.agents/**
+.claude/**
+.gemini/**
+.config/**
+.data/**
+.logs/**
+.tests/**
+.coverage/**
+coverage/
+.dist/**
+.next/**
+.build/**
+.out/**
+
+# Stryker mutation testing — ephemeral sandbox + generated reports (never commit)
+.stryker-tmp/
+reports/mutation/
+stryker-output-*.json
+
 
 # Memory Bank and Cursor rules (local-only AI agent context)
 memory-bank/
@@ -15,6 +39,7 @@ memory-bank/
 .claude/scheduled_tasks/
 .claude/sessions/
 .claude/state.json
+.claude/settings.local.json
 
 # Root-level underscore-prefixed directories (private/draft — never commit)
 /_*/
@@ -24,32 +49,19 @@ docs/new-features/
 
 # dependencies
 node_modules/
-/.pnp
-.pnp.*
-.yarn/*
-!.yarn/patches
-!.yarn/plugins
-!.yarn/releases
-!.yarn/versions
-.data/
-.next-playwright/
-
-# testing
-coverage/
-coverage**
-
-# next.js
-.next/
-/out/
-
-# production
-/build
-/app
-cloud/*
-
-# misc
+# Also ignore a root node_modules SYMLINK (worktree setups symlink it from the main
+# checkout). The trailing-slash pattern above only matches a directory, so without this
+# a symlink named node_modules could be staged by `git add -A` and committed.
+/node_modules
+*.map
 .DS_Store
-*.pem
+
+# Obsidian sync plugin — committed for community distribution
+!obsidian-plugin/
+obsidian-plugin/node_modules/
+
+# Serena AI assistant config (local-only tool, not project code)
+.serena/
 
 # debug
 npm-debug.log*
@@ -60,6 +72,9 @@ yarn-error.log*
 # env files (can opt-in for committing if needed)
 .env*
 !.env.example
+# Provider API keys (never commit)
+*.api-key
+.nvidia-api-key
 
 # vercel
 .vercel
@@ -111,10 +126,13 @@ app.__qa_backup/
 .app-build-backup-*/
 backup/
 
-# Production standalone build (created by scripts/prepublish.mjs)
-# Conflicts with Next.js App Router detection in dev (root app/ shadows src/app/)
-# npm publish still includes it via package.json "files" field
-/app/
+# Build intermediates (.build/) and shippable standalone (dist/).
+# These are fully reproducible from source; never committed.
+# Layer 1: Next.js now writes to .build/next (was .next); assembled bundle → dist/
+# (Previously /app/ was the standalone output; renamed to /dist/ in Layer 1.)
+/.build/
+/dist/
+/.next/
 
 # Electron
 electron/dist-electron/
@@ -129,9 +147,6 @@ vscode-extension/
 *.sqlite-wal
 *.sqlite-journal
 
-# Compiled npm-package build artifact (not source, should not be in git)
-/app
-
 # IDEA
 .idea/
 
@@ -147,6 +162,9 @@ typescript
 # Superpowers plans/specs (internal tooling, not project code)
 docs/superpowers/
 
+# TIA test-impact map — generated at runtime in CI (build-test-impact-map.mjs), never committed (~21MB)
+config/quality/test-impact-map.json
+
 # GitNexus local index
 .gitnexus
 .worktrees
@@ -181,3 +199,31 @@ scripts/i18n/_pending-keys.json
 
 # Fumadocs generated source
 .source/
+
+# AI agent local settings and configs
+.agents/
+.antigravitycli/
+.claude/
+
+# PR Reviews and local feedback files
+pr_reviews*.json
+
+#hidden local data directories (never commit)
+.local-data/
+.data-dev/
+/.junie/
+
+# internal setup prompts with personal credentials — never commit
+CODEX-SETUP-PROMPT.md
+# Quality ratchet — métricas efêmeras (baseline commitado em config/quality/; métricas não)
+config/quality/quality-metrics.json
+
+# Runtime logs (diretório local, nunca versionado)
+/logs/
+-home-diegosouzapw-dev-automações-bots-yt-downloader-20260504 .txt
+-home-diegosouzapw-dev-automações-bots-yt-downloader-20260410 .txt
+docs/prompts/AGENT-OWNERSHIP-PROTOCOL.omniroute.md
+docs/prompts/AGENT-OWNERSHIP-PROTOCOL.md
+docs/prompts/AGENT-OWNERSHIP-PROTOCOL.omniroute-mim.md
+docs/prompts/AGENT-OWNERSHIP-PROTOCOL.omniroute-mid.md
+omniroute.md

.gitleaks.toml

@@ -0,0 +1,76 @@
+# .gitleaks.toml — Configuração do gitleaks para OmniRoute
+# Task 7.18 — PLANO-QUALITY-GATES-FASE7.md
+#
+# Estende as regras padrão do gitleaks com allowlists específicas do projeto.
+#
+# INSTRUÇÕES para allowlists:
+#   Findings legítimos (fixtures de teste, creds OAuth públicas já cobertas pelo
+#   check-public-creds.mjs, valores de exemplo em docs) devem ser registrados abaixo
+#   em [[allowlist]] com um comentário explicativo obrigatório.
+#
+#   NÃO adicione uma entrada de allowlist sem justificativa. Cada entrada é revisada
+#   a cada release (stale-enforcement). Regra: se o finding é um valor real que o
+#   sistema usa em produção, é um verdadeiro positivo — não allowliste, corrija.
+#
+# Referência: docs/security/PUBLIC_CREDS.md (credenciais OAuth públicas conhecidas)
+#             CLAUDE.md Hard Rule #11 (resolvePublicCred obrigatório)
+
+# Herdar TODAS as regras padrão do gitleaks. ATENÇÃO: um config customizado
+# SEM [extend].useDefault = true (e sem [[rules]] próprias) resulta em ZERO
+# regras — o gitleaks SUBSTITUI o ruleset padrão pelo arquivo, não o estende
+# automaticamente. Sem esta seção, `gitleaks --config .gitleaks.toml` nunca
+# detecta nada (todo finding vira 0), tornando o gate inerte. Com useDefault,
+# a allowlist abaixo é aplicada POR CIMA das ~170 regras padrão.
+[extend]
+  useDefault = true
+
+# Para desabilitar uma regra específica, usar:
+# [[rules]]
+#   id = "rule-id"
+#   [rules.allowlist]
+#     description = "..."
+
+# ---------------------------------------------------------------------------
+# Allowlist global do projeto
+# Entradas aqui são ignoradas em TODAS as varreduras.
+# ---------------------------------------------------------------------------
+[allowlist]
+  description = "OmniRoute project-level allowlist — fixtures, test vectors, public OAuth creds"
+
+  # Paths a ignorar completamente (node_modules, builds, etc.)
+  paths = [
+    '''node_modules''',
+    '''\.next''',
+    '''dist''',
+    '''\.git''',
+    '''coverage''',
+    '''\.nyc_output''',
+  ]
+
+  # Commits específicos a ignorar (ex: commit que introduziu fixtures de teste)
+  # commits = []
+
+  # Regexes de stopwords — linhas que contêm estes padrões são ignoradas.
+  # Usar apenas para falsos positivos comprovados com justificativa abaixo.
+  # stopwords = []
+
+  # Regexes de targets (paths de arquivos) que podem ser allowlistados por regra.
+  # Ver [[allowlist]] por-regra abaixo para granularidade.
+
+# ---------------------------------------------------------------------------
+# Allowlist por-regra (adicionar conforme necessário durante o stale review)
+# ---------------------------------------------------------------------------
+#
+# Exemplo (REMOVER / SUBSTITUIR por entradas reais quando necessário):
+#
+# [[rules]]
+#   # Allowlistar fixtures de teste que contêm tokens OAuth de exemplo/inválidos
+#   # Adicionado: 2026-06-13 | Revisar em: v3.9.0 | Justificativa: valores não-reais de teste
+#   id = "github-fine-grained-pat"
+#   [rules.allowlist]
+#     description = "Test fixture PATs — valores sintéticos, não funcionais"
+#     paths = [
+#       '''tests/fixtures/''',
+#       '''tests/unit/''',
+#     ]
+#

.husky/pre-commit

@@ -5,20 +5,9 @@ if ! command -v npx >/dev/null 2>&1; then
   exit 0
 fi
 
+# Cheap, deterministic local gates (re-enabled). Slower checks (i18n drift,
+# openapi coverage/security-tiers, env-doc sync) run in CI to keep commits fast.
 npx lint-staged
 node scripts/check/check-docs-sync.mjs
 npm run check:any-budget:t11
-
-# Strict env-doc sync (FASE 2)
-node scripts/check/check-env-doc-sync.mjs
-
-# CLI i18n consistency check — all t() keys must exist in en.json (FASE 8.3)
-node scripts/check/check-cli-i18n.mjs
-
-# i18n docs drift advisory (FASE 5) — warn-only on pre-commit; CI enforces strict.
-node scripts/i18n/check-translation-drift.mjs --warn || \
-  echo "⚠️  i18n drift detected. Run 'npm run i18n:run' to update locale mirrors."
-
-# i18n UI coverage advisory (FASE 6) — pre-commit warns; CI enforces strict.
-node scripts/i18n/check-ui-keys-coverage.mjs --threshold=80 || \
-  echo "⚠️  UI i18n coverage below 80% for at least one locale."
+node scripts/check/check-tracked-artifacts.mjs

.husky/pre-push

@@ -1,8 +1,12 @@
 #!/usr/bin/env sh
-#if ! command -v npm >/dev/null 2>&1; then
-#  echo "⚠️  npm not found in PATH — skipping pre-push hooks"
-#  echo "   Run 'npm test' manually before pushing."
-#  exit 0
-#fi
+# .husky/pre-push — fast deterministic gates (<10s total)
+# Intentionally excludes test:unit (slow; covered by CI pre-push remote run).
+# Activated: 2026-06-13 (6A.12 — replaced commented-out test:unit stub)
 
-#npm run test:unit
+if ! command -v npm >/dev/null 2>&1; then
+  echo "⚠️  npm not found in PATH — skipping pre-push hooks"
+  echo "   Run 'npm run check:any-budget:t11 && npm run check:tracked-artifacts' manually before pushing."
+  exit 0
+fi
+
+npm run check:any-budget:t11 && npm run check:tracked-artifacts

.i18n-state.json

@@ -1,219 +0,0 @@
-{
-  "sources": {
-    "CLAUDE.md": {
-      "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-      "locales": {
-        "pt-BR": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "301b997e936b1d476e6094042666b96b33f42a4372fd2d9ccf904aacbfd7f023",
-          "updated_at": "2026-05-22T20:13:39.165Z"
-        },
-        "az": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "c26844ec50b2abfbb002767fb5c6c9c3982ec65789435bbc134bf1a7b50bf84a",
-          "updated_at": "2026-05-22T20:13:39.166Z"
-        },
-        "bn": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "0b1416ec3b5af8cc6415d12a9ff12ce078acca4a7bb52a7422ebde3b6ae22832",
-          "updated_at": "2026-05-22T20:13:39.166Z"
-        },
-        "ar": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "bc747c5ea2a387dd37dea9dc1337d9734f2ec0da38a7134573d9743e3f4d2aef",
-          "updated_at": "2026-05-22T20:13:39.167Z"
-        },
-        "cs": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "e37dce45820b53be9d3d5ead08cadb8d13e4c77597b3009bb0be4e485917f5c6",
-          "updated_at": "2026-05-22T20:13:39.167Z"
-        },
-        "da": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "645c382bebe0931eaad6747e33667fd094b92b3f4042549b953db798de6b1f46",
-          "updated_at": "2026-05-22T20:13:39.168Z"
-        },
-        "de": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "b6558f82eb67676baf4d78946a8d1e1b808f7763e5ebaf9f57948cbd1641dc0f",
-          "updated_at": "2026-05-22T20:13:39.168Z"
-        },
-        "es": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "afb2a2dfa74a74c3105b0ac70181d33f5eefd201efe7edb6aba0740864639fe5",
-          "updated_at": "2026-05-22T20:13:39.169Z"
-        },
-        "fa": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "58966769aeb71d23c55cf4aeb452f2bbe32036df8fba1d7596f3e861897d507b",
-          "updated_at": "2026-05-22T20:13:39.169Z"
-        },
-        "fi": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "04cf72a3b370edcb3d54361c6cc250b3af227ba183376827006c7998839740aa",
-          "updated_at": "2026-05-22T20:13:39.169Z"
-        },
-        "fr": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "8dca6de87c88e04396f1139ac8b6328d188defaa5abc99eeb4026f53de772ba1",
-          "updated_at": "2026-05-22T20:13:39.170Z"
-        },
-        "he": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "0308a2c8c5a6b6261474a76c160f3c0658c75f56a633a57bd7300b83ccb32c9d",
-          "updated_at": "2026-05-22T20:13:39.170Z"
-        },
-        "hi": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "a3e902c3b1812a41ccb14c9f16d2cf2e42b8c005a5d557043e582d48eda024c4",
-          "updated_at": "2026-05-22T20:13:39.170Z"
-        },
-        "gu": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "1bc2419db39c7c7960b065222a3e3990e9e53c4d3427ec02422e3e506aa53733",
-          "updated_at": "2026-05-22T20:13:39.171Z"
-        },
-        "hu": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "ec30f54810f8b5b84e3ac8bf7bc8d05acc8616d71801b672ec02f0bc225cf607",
-          "updated_at": "2026-05-22T20:13:39.171Z"
-        },
-        "id": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "aebd8fdad7ec4857aa1b958cda37f59681846525207d71d98d729775031afb94",
-          "updated_at": "2026-05-22T20:13:39.172Z"
-        },
-        "in": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "ac70a1282877f8c4f792e9235f7a6fbce3cbec4a424ce4947074bb210fe12d67",
-          "updated_at": "2026-05-22T20:13:39.172Z"
-        },
-        "it": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "260f10dd121441d08e15a8d511789d8f8f7a788995305ab5e8dc6d0c1a3db06e",
-          "updated_at": "2026-05-22T20:13:39.173Z"
-        },
-        "ja": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "83871c13e99d13d7928409b2aef182f55fe36fbb2425f8fa4bd0df0466afed28",
-          "updated_at": "2026-05-22T20:13:39.173Z"
-        },
-        "mr": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "0c35c5261dd3b6c6b729d14653f95cc112f3ed9829d2d41b61e5a960abc68556",
-          "updated_at": "2026-05-22T20:13:39.173Z"
-        },
-        "ko": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "4ea4079b37d90e90e9a32d0da290e04e38bcd6426512b50ca7be7139354bc329",
-          "updated_at": "2026-05-22T20:13:39.174Z"
-        },
-        "ms": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "0e8031cd987766a69afc7aaf7c3560a57736d37e7238ddccfb848d6fbeb3f212",
-          "updated_at": "2026-05-22T20:13:39.174Z"
-        },
-        "nl": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "27e554c3a9b86db1f04539fcac18d3e75e6599d4de9f5ac0cf789a136b5737d4",
-          "updated_at": "2026-05-22T20:13:39.174Z"
-        },
-        "phi": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "f955af44cc0e8e87a2a7b12313f0dfad9aae1a50d7855e74c8155df3601279ad",
-          "updated_at": "2026-05-22T20:13:39.175Z"
-        },
-        "no": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "de4e3d940ae485c85da13db4471fcc68926ec53e660d92633f01293c5db0a04d",
-          "updated_at": "2026-05-22T20:13:39.175Z"
-        },
-        "pl": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "de5be8961e5184431404d0021e31c3ef0857f7439fbd1c71ddc0c6828bed86bb",
-          "updated_at": "2026-05-22T20:13:39.175Z"
-        },
-        "ro": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "19d98b22bc77c1870b749fad6e62a41c6ef53f3cad303d1c471fba4bf7012797",
-          "updated_at": "2026-05-22T20:13:39.175Z"
-        },
-        "ru": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "25e0c70ec25bd24b073b9d693299c3c3d32d66a410569362719e9c9ecacd759d",
-          "updated_at": "2026-05-22T20:13:39.176Z"
-        },
-        "pt": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "0d31647b21af967d8d4e9ecbcfc4901a66db377a6853d7b59296a2d73f0cab12",
-          "updated_at": "2026-05-22T20:13:39.176Z"
-        },
-        "sk": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "9d5d0ce1c51da4959d1c306969bff0bf36d3a3492ccdbdbd82e4f4d951f32c8b",
-          "updated_at": "2026-05-22T20:13:39.176Z"
-        },
-        "sw": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "11cd3dc7a605eebddf4a34c13de66c713d67adb32e4242962a65c71e5a034c7e",
-          "updated_at": "2026-05-22T20:13:39.177Z"
-        },
-        "sv": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "93b679feb6415315ab96e08298217e66be84265a277e267ecefd25b2cef04026",
-          "updated_at": "2026-05-22T20:13:39.177Z"
-        },
-        "ta": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "55f3df128513a1b4a8cc3f58eb84769814589d80e1c8b8f03ab0635750a76d2d",
-          "updated_at": "2026-05-22T20:13:39.177Z"
-        },
-        "te": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "81019604dd1fb38dfda55c1b8cf5cf8243347be08221a5e1eb11e8c76e095fab",
-          "updated_at": "2026-05-22T20:13:39.178Z"
-        },
-        "tr": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "b67efd07b179be016b388dff4b8979597c0a7b2db602629cef539dbec14913ab",
-          "updated_at": "2026-05-22T20:13:39.178Z"
-        },
-        "th": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "a793a12dc0cba5e3641cd544f63ab23e9cfe1b80568a08770a81ffd890287eda",
-          "updated_at": "2026-05-22T20:13:39.179Z"
-        },
-        "ur": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "6c03049aee6d85b6fd4a3bf9b89a6204e461d3f05e9cb767e36c80af796452df",
-          "updated_at": "2026-05-22T20:13:39.179Z"
-        },
-        "vi": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "4d35c6898f98913a02551dcfbf4d3748b2461e2d8206d292f292acacf0fc7133",
-          "updated_at": "2026-05-22T20:13:39.180Z"
-        },
-        "zh-CN": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "d3f574c244d157c1fe1b9fc86192d1565df2dc6343ac9ef63c0fd3f91d97f492",
-          "updated_at": "2026-05-22T20:13:39.180Z"
-        },
-        "uk-UA": {
-          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
-          "target_hash": "ffe6357e38d56ba2595e8fb8e21db4ae91bf03d10fca50a2b722e0d0bb6c01d9",
-          "updated_at": "2026-05-22T20:13:39.181Z"
-        }
-      }
-    },
-    "docs/architecture/ARCHITECTURE.md": {
-      "source_hash": "f9b4f17a1b0331fb5500768943438411ed88a38278381680caacc37c90bfb869",
-      "locales": {
-        "pt-BR": {
-          "source_hash": "f9b4f17a1b0331fb5500768943438411ed88a38278381680caacc37c90bfb869",
-          "target_hash": "e320c6172a88a0f3b698ba1a2e9e938424ece66625765395837bcf55cc29454e",
-          "updated_at": "2026-05-22T20:13:39.183Z"
-        }
-      }
-    }
-  }
-}

.markdownlint.json

@@ -0,0 +1,14 @@
+{
+  "_comment": "Advisory markdown lint for docs/ + root *.md. Rules that conflict with the existing doc style (heavy inline HTML, long lines, centered headings) are disabled so the gate stays signal-not-noise. Run: npm run lint:md",
+  "default": true,
+  "MD013": false,
+  "MD033": false,
+  "MD041": false,
+  "MD024": { "siblings_only": true },
+  "MD026": false,
+  "MD036": false,
+  "MD040": false,
+  "MD029": false,
+  "MD007": { "indent": 2 },
+  "MD046": false
+}

.mcp.json.example

@@ -0,0 +1,17 @@
+{
+  "$comment_purpose": "OPT-IN agent-lsp / LSP-in-the-loop (Quality Gates Fase 7 Task 15). Copy this file to `.mcp.json` to enable. It exposes a TypeScript language server to coding agents (Claude Code, etc.) so they get diagnostics / hover / go-to-definition / blast-radius BEFORE writing code — turning 'invented symbol' review-catches into impossible-at-edit-time. Pairs with `npm run typecheck:core` as a compile-before-claim check.",
+  "$comment_safety": "Shipped as `.example` (NOT `.mcp.json`) on purpose so it never auto-loads an unvetted server into everyone's session. Pick an MCP<->LSP bridge you trust and have verified locally, then drop in its package + args below. A broken MCP entry only logs a connection error; it does not break agent sessions. The underlying language server is `typescript-language-server` (npm, mature) — install via `npm i -g typescript-language-server typescript` or rely on npx.",
+  "mcpServers": {
+    "typescript-lsp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "<your-mcp-lsp-bridge>",
+        "--lsp",
+        "typescript-language-server",
+        "--stdio"
+      ],
+      "$note": "Replace <your-mcp-lsp-bridge> with the concrete MCP<->LSP adapter you chose. It must speak MCP on stdio and proxy to `typescript-language-server --stdio`. Scope it to this repo's tsconfig (open-sse/tsconfig.json / tsconfig.json) for accurate diagnostics."
+    }
+  }
+}

.npmignore

@@ -9,6 +9,16 @@ app/vscode-extension/
 **/db.json
 
 # Source code (pre-built app/ is published instead)
+#
+# NOTE (#3578 / #3821-review): package.json "files" is the source of truth for what
+# ships. It now allowlists the backend source closure the MCP server needs at runtime
+# (open-sse/, src/lib, src/server, ...) and OVERRIDES the broad src/ + open-sse/ excludes
+# below — npm honors files[] over .npmignore for inclusion. These lines are kept only as
+# intent/back-stop: if files[] is ever trimmed back to specific paths, they must NOT be
+# allowed to re-hide the MCP closure (that would silently reintroduce the --mcp
+# ERR_MODULE_NOT_FOUND #3578 fixed). The closure gate in
+# tests/unit/mcp-published-files-closure-3578.test.ts asserts the real `npm pack` output
+# in both directions (closure present + zero test files), catching such a regression.
 src/
 open-sse/
 docs/
@@ -18,6 +28,17 @@ images/
 logs/
 scripts/
 
+# Co-located tests must never ship even when their parent dir is allowlisted by files[].
+# (Primary guard is the "!**/*.test.*" negations in package.json files[]; this is defense
+# in depth for any nested dir the allowlist pulls in.)
+**/__tests__/
+**/*.test.ts
+**/*.test.tsx
+**/*.test.js
+**/*.test.mjs
+**/*.spec.ts
+**/*.spec.tsx
+
 # Config/dev files
 *.md
 !README.md

.semgrep/rules/cli-no-sqlite.yaml

@@ -1,31 +0,0 @@
-rules:
-  - id: cli-no-sqlite-direct
-    patterns:
-      - pattern: new Database(...)
-    paths:
-      include:
-        - "/bin/**"
-      exclude:
-        - "/bin/cli/sqlite.mjs"
-    message: >
-      Direct SQLite access in bin/ is banned. Use src/lib/db/* helpers or
-      withRuntime() from bin/cli/runtime.mjs. See CLAUDE.md hard rule #5 and
-      bin/cli/CONVENTIONS.md.
-    languages: [js]
-    severity: ERROR
-
-  - id: cli-no-raw-sql
-    patterns:
-      - pattern: $DB.prepare("INSERT INTO ...")
-      - pattern: $DB.prepare("DELETE FROM ...")
-      - pattern: $DB.prepare("UPDATE $TABLE SET ...")
-    paths:
-      include:
-        - "/bin/**"
-      exclude:
-        - "/bin/cli/sqlite.mjs"
-    message: >
-      Raw SQL in bin/ is banned. Use src/lib/db/* helpers. See CLAUDE.md
-      hard rule #5 and bin/cli/CONVENTIONS.md.
-    languages: [js]
-    severity: ERROR

.size-limit.json

@@ -0,0 +1,22 @@
+[
+  {
+    "name": "CLI entry (omniroute.mjs)",
+    "path": "bin/omniroute.mjs",
+    "limit": "15 KB"
+  },
+  {
+    "name": "MCP server entry (mcp-server.mjs)",
+    "path": "bin/mcp-server.mjs",
+    "limit": "5 KB"
+  },
+  {
+    "name": "Node runtime support (nodeRuntimeSupport.mjs)",
+    "path": "bin/nodeRuntimeSupport.mjs",
+    "limit": "8 KB"
+  },
+  {
+    "name": "Reset password entry (reset-password.mjs)",
+    "path": "bin/reset-password.mjs",
+    "limit": "6 KB"
+  }
+]

.source/server.ts

@@ -1,74 +0,0 @@
-// @ts-nocheck
-import { default as __fd_glob_63 } from "../docs/security/meta.json?collection=docs"
-import { default as __fd_glob_62 } from "../docs/routing/meta.json?collection=docs"
-import { default as __fd_glob_61 } from "../docs/reference/openapi.yaml?collection=docs"
-import { default as __fd_glob_60 } from "../docs/reference/meta.json?collection=docs"
-import { default as __fd_glob_59 } from "../docs/ops/meta.json?collection=docs"
-import { default as __fd_glob_58 } from "../docs/guides/meta.json?collection=docs"
-import { default as __fd_glob_57 } from "../docs/frameworks/meta.json?collection=docs"
-import { default as __fd_glob_56 } from "../docs/compression/meta.json?collection=docs"
-import { default as __fd_glob_55 } from "../docs/architecture/meta.json?collection=docs"
-import { default as __fd_glob_54 } from "../docs/meta.json?collection=docs"
-import * as __fd_glob_53 from "../docs/security/STEALTH_GUIDE.md?collection=docs"
-import * as __fd_glob_52 from "../docs/security/ROUTE_GUARD_TIERS.md?collection=docs"
-import * as __fd_glob_51 from "../docs/security/PUBLIC_CREDS.md?collection=docs"
-import * as __fd_glob_50 from "../docs/security/GUARDRAILS.md?collection=docs"
-import * as __fd_glob_49 from "../docs/security/ERROR_SANITIZATION.md?collection=docs"
-import * as __fd_glob_48 from "../docs/security/COMPLIANCE.md?collection=docs"
-import * as __fd_glob_47 from "../docs/security/CLI_TOKEN_AUTH.md?collection=docs"
-import * as __fd_glob_46 from "../docs/security/CLI_TOKEN.md?collection=docs"
-import * as __fd_glob_45 from "../docs/routing/REASONING_REPLAY.md?collection=docs"
-import * as __fd_glob_44 from "../docs/routing/AUTO-COMBO.md?collection=docs"
-import * as __fd_glob_43 from "../docs/reference/PROVIDER_REFERENCE.md?collection=docs"
-import * as __fd_glob_42 from "../docs/reference/FREE_TIERS.md?collection=docs"
-import * as __fd_glob_41 from "../docs/reference/ENVIRONMENT.md?collection=docs"
-import * as __fd_glob_40 from "../docs/reference/CLI-TOOLS.md?collection=docs"
-import * as __fd_glob_39 from "../docs/reference/API_REFERENCE.md?collection=docs"
-import * as __fd_glob_38 from "../docs/ops/VM_DEPLOYMENT_GUIDE.md?collection=docs"
-import * as __fd_glob_37 from "../docs/ops/TUNNELS_GUIDE.md?collection=docs"
-import * as __fd_glob_36 from "../docs/ops/SQLITE_RUNTIME.md?collection=docs"
-import * as __fd_glob_35 from "../docs/ops/RELEASE_CHECKLIST.md?collection=docs"
-import * as __fd_glob_34 from "../docs/ops/PROXY_GUIDE.md?collection=docs"
-import * as __fd_glob_33 from "../docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md?collection=docs"
-import * as __fd_glob_32 from "../docs/ops/E2E_DASHBOARD_SHAKEDOWN_v3.8.0.md?collection=docs"
-import * as __fd_glob_31 from "../docs/ops/COVERAGE_PLAN.md?collection=docs"
-import * as __fd_glob_30 from "../docs/guides/USER_GUIDE.md?collection=docs"
-import * as __fd_glob_29 from "../docs/guides/UNINSTALL.md?collection=docs"
-import * as __fd_glob_28 from "../docs/guides/TROUBLESHOOTING.md?collection=docs"
-import * as __fd_glob_27 from "../docs/guides/TERMUX_GUIDE.md?collection=docs"
-import * as __fd_glob_26 from "../docs/guides/SETUP_GUIDE.md?collection=docs"
-import * as __fd_glob_25 from "../docs/guides/PWA_GUIDE.md?collection=docs"
-import * as __fd_glob_24 from "../docs/guides/KIRO_SETUP.md?collection=docs"
-import * as __fd_glob_23 from "../docs/guides/I18N.md?collection=docs"
-import * as __fd_glob_22 from "../docs/guides/FEATURES.md?collection=docs"
-import * as __fd_glob_21 from "../docs/guides/ELECTRON_GUIDE.md?collection=docs"
-import * as __fd_glob_20 from "../docs/guides/DOCKER_GUIDE.md?collection=docs"
-import * as __fd_glob_19 from "../docs/frameworks/WEBHOOKS.md?collection=docs"
-import * as __fd_glob_18 from "../docs/frameworks/SKILLS.md?collection=docs"
-import * as __fd_glob_17 from "../docs/frameworks/OPENCODE.md?collection=docs"
-import * as __fd_glob_16 from "../docs/frameworks/MEMORY.md?collection=docs"
-import * as __fd_glob_15 from "../docs/frameworks/MCP-SERVER.md?collection=docs"
-import * as __fd_glob_14 from "../docs/frameworks/GAMIFICATION.md?collection=docs"
-import * as __fd_glob_13 from "../docs/frameworks/EVALS.md?collection=docs"
-import * as __fd_glob_12 from "../docs/frameworks/CLOUD_AGENT.md?collection=docs"
-import * as __fd_glob_11 from "../docs/frameworks/AGENT_PROTOCOLS_GUIDE.md?collection=docs"
-import * as __fd_glob_10 from "../docs/frameworks/A2A-SERVER.md?collection=docs"
-import * as __fd_glob_9 from "../docs/compression/RTK_COMPRESSION.md?collection=docs"
-import * as __fd_glob_8 from "../docs/compression/COMPRESSION_RULES_FORMAT.md?collection=docs"
-import * as __fd_glob_7 from "../docs/compression/COMPRESSION_LANGUAGE_PACKS.md?collection=docs"
-import * as __fd_glob_6 from "../docs/compression/COMPRESSION_GUIDE.md?collection=docs"
-import * as __fd_glob_5 from "../docs/compression/COMPRESSION_ENGINES.md?collection=docs"
-import * as __fd_glob_4 from "../docs/architecture/RESILIENCE_GUIDE.md?collection=docs"
-import * as __fd_glob_3 from "../docs/architecture/REPOSITORY_MAP.md?collection=docs"
-import * as __fd_glob_2 from "../docs/architecture/CODEBASE_DOCUMENTATION.md?collection=docs"
-import * as __fd_glob_1 from "../docs/architecture/AUTHZ_GUIDE.md?collection=docs"
-import * as __fd_glob_0 from "../docs/architecture/ARCHITECTURE.md?collection=docs"
-import { server } from 'fumadocs-mdx/runtime/server';
-import type * as Config from '../source.config';
-
-const create = server<typeof Config, import("fumadocs-mdx/runtime/types").InternalTypeConfig & {
-  DocData: {
-  }
-}>({"doc":{"passthroughs":["extractedReferences"]}});
-
-export const docs = await create.docs("docs", "docs", {"meta.json": __fd_glob_54, "architecture/meta.json": __fd_glob_55, "compression/meta.json": __fd_glob_56, "frameworks/meta.json": __fd_glob_57, "guides/meta.json": __fd_glob_58, "ops/meta.json": __fd_glob_59, "reference/meta.json": __fd_glob_60, "reference/openapi.yaml": __fd_glob_61, "routing/meta.json": __fd_glob_62, "security/meta.json": __fd_glob_63, }, {"architecture/ARCHITECTURE.md": __fd_glob_0, "architecture/AUTHZ_GUIDE.md": __fd_glob_1, "architecture/CODEBASE_DOCUMENTATION.md": __fd_glob_2, "architecture/REPOSITORY_MAP.md": __fd_glob_3, "architecture/RESILIENCE_GUIDE.md": __fd_glob_4, "compression/COMPRESSION_ENGINES.md": __fd_glob_5, "compression/COMPRESSION_GUIDE.md": __fd_glob_6, "compression/COMPRESSION_LANGUAGE_PACKS.md": __fd_glob_7, "compression/COMPRESSION_RULES_FORMAT.md": __fd_glob_8, "compression/RTK_COMPRESSION.md": __fd_glob_9, "frameworks/A2A-SERVER.md": __fd_glob_10, "frameworks/AGENT_PROTOCOLS_GUIDE.md": __fd_glob_11, "frameworks/CLOUD_AGENT.md": __fd_glob_12, "frameworks/EVALS.md": __fd_glob_13, "frameworks/GAMIFICATION.md": __fd_glob_14, "frameworks/MCP-SERVER.md": __fd_glob_15, "frameworks/MEMORY.md": __fd_glob_16, "frameworks/OPENCODE.md": __fd_glob_17, "frameworks/SKILLS.md": __fd_glob_18, "frameworks/WEBHOOKS.md": __fd_glob_19, "guides/DOCKER_GUIDE.md": __fd_glob_20, "guides/ELECTRON_GUIDE.md": __fd_glob_21, "guides/FEATURES.md": __fd_glob_22, "guides/I18N.md": __fd_glob_23, "guides/KIRO_SETUP.md": __fd_glob_24, "guides/PWA_GUIDE.md": __fd_glob_25, "guides/SETUP_GUIDE.md": __fd_glob_26, "guides/TERMUX_GUIDE.md": __fd_glob_27, "guides/TROUBLESHOOTING.md": __fd_glob_28, "guides/UNINSTALL.md": __fd_glob_29, "guides/USER_GUIDE.md": __fd_glob_30, "ops/COVERAGE_PLAN.md": __fd_glob_31, "ops/E2E_DASHBOARD_SHAKEDOWN_v3.8.0.md": __fd_glob_32, "ops/FLY_IO_DEPLOYMENT_GUIDE.md": __fd_glob_33, "ops/PROXY_GUIDE.md": __fd_glob_34, "ops/RELEASE_CHECKLIST.md": __fd_glob_35, "ops/SQLITE_RUNTIME.md": __fd_glob_36, "ops/TUNNELS_GUIDE.md": __fd_glob_37, "ops/VM_DEPLOYMENT_GUIDE.md": __fd_glob_38, "reference/API_REFERENCE.md": __fd_glob_39, "reference/CLI-TOOLS.md": __fd_glob_40, "reference/ENVIRONMENT.md": __fd_glob_41, "reference/FREE_TIERS.md": __fd_glob_42, "reference/PROVIDER_REFERENCE.md": __fd_glob_43, "routing/AUTO-COMBO.md": __fd_glob_44, "routing/REASONING_REPLAY.md": __fd_glob_45, "security/CLI_TOKEN.md": __fd_glob_46, "security/CLI_TOKEN_AUTH.md": __fd_glob_47, "security/COMPLIANCE.md": __fd_glob_48, "security/ERROR_SANITIZATION.md": __fd_glob_49, "security/GUARDRAILS.md": __fd_glob_50, "security/PUBLIC_CREDS.md": __fd_glob_51, "security/ROUTE_GUARD_TIERS.md": __fd_glob_52, "security/STEALTH_GUIDE.md": __fd_glob_53, });

.vale.ini

@@ -0,0 +1,15 @@
+# Advisory prose lint for OmniRoute docs (Vale — https://vale.sh).
+# Warning-first: surfaces vague language, passive voice, and terminology drift without
+# blocking CI. The Microsoft style is pulled by the CI step (vale sync / vale-action).
+# Project terms live in the OmniRoute vocabulary so they never read as misspellings.
+StylesPath = .vale/styles
+MinAlertLevel = warning
+Packages = Microsoft
+Vocab = OmniRoute
+
+[*.md]
+BasedOnStyles = Vale, Microsoft
+
+# Code-heavy reference docs and auto-generated catalogs are noisy under prose rules.
+[docs/reference/PROVIDER_REFERENCE.md]
+BasedOnStyles = Vale

.vale/styles/Vocab/OmniRoute/accept.txt

@@ -0,0 +1,50 @@
+OmniRoute
+combo
+combos
+[Cc]ombo
+[Aa]uto-[Cc]ombo
+MCP
+A2A
+ACP
+RTK
+Caveman
+Troglodita
+Qdrant
+FTS5
+SQLite
+LowDB
+OAuth
+PKCE
+SSE
+JSON-RPC
+LKGP
+P2C
+Antigravity
+Codex
+Kiro
+Qoder
+Pollinations
+LongCat
+Cerebras
+DeepSeek
+Groq
+Cline
+OpenCode
+Termux
+Electron
+Fumadocs
+Notion
+Obsidian
+WebDAV
+IPv4
+IPv6
+SOCKS5
+loopback
+backoff
+changelog
+i18n
+locale
+locales
+roadmap
+[Ww]ildcard
+upstream

.vscode/launch.json

@@ -1,31 +0,0 @@
-{
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "name": "Debug Dev Server",
-      "type": "node",
-      "request": "launch",
-      "runtimeExecutable": "${env:HOME}/.nvm/versions/node/v22.22.2/bin/node",
-      "program": "${workspaceFolder}/scripts/run-next.mjs",
-      "args": ["dev"],
-      "console": "integratedTerminal",
-      "skipFiles": ["<node_internals>/**", "node_modules/**"]
-    },
-    {
-      "name": "Debug Prod Server",
-      "type": "node",
-      "request": "launch",
-      "program": "${workspaceFolder}/scripts/run-next.mjs",
-      "args": ["start"],
-      "console": "integratedTerminal",
-      "skipFiles": ["<node_internals>/**", "node_modules/**"]
-    },
-    {
-      "name": "Attach to Running Server",
-      "type": "node",
-      "request": "attach",
-      "port": 9229,
-      "skipFiles": ["<node_internals>/**", "node_modules/**"]
-    }
-  ]
-}

.vscode/settings.json

@@ -19,32 +19,116 @@
     }
   },
   "git.ignoreLimitWarning": true,
+
+  // ─── Git: não adicionar os ~44 repos aninhados (9 worktrees + _references/* +
+  // _mono_repo/* + _ideia/_tasks/.agents) ao Source Control. Era a causa do
+  // "validando muito": um git status + watcher por repo. Só o repo raiz fica. ───
+  "git.autoRepositoryDetection": false,
+  "git.repositoryScanMaxDepth": 0,
+  "git.detectSubmodules": false,
+  "git.autofetch": false,
+  "git.autorefresh": true,
+
+  // ─── Performance: não seguir o symlink de node_modules criado pelas worktrees ───
+  // As worktrees em .worktrees/ apontam node_modules para o checkout principal;
+  // sem isto a busca atravessa o symlink mesmo com node_modules excluído.
+  "search.followSymlinks": false,
+
+  // ─── TypeScript server (monorepo grande: ~6,6k arquivos rastreados, Next.js 16) ───
+  "typescript.tsserver.maxTsServerMemory": 4096,
+  "typescript.disableAutomaticTypeAcquisition": true,
+  "typescript.tsc.autoDetect": "off",
+  "npm.autoDetect": "off",
+  // O tsserver tem o próprio watcher (independente de files.watcherExclude).
+  // excludeDirectories evita que ele vigie as árvores pesadas.
+  "typescript.tsserver.watchOptions": {
+    "excludeDirectories": [
+      "**/node_modules",
+      "**/.next",
+      "**/.build",
+      "**/dist",
+      "**/coverage",
+      "**/.worktrees"
+    ]
+  },
+
+  // Para esconder os diretórios gerados da árvore do Explorer, descomente:
   // "files.exclude": {
+  //   "**/.worktrees": true,
+  //   "**/coverage": true,
+  //   "**/dist": true,
+  //   "**/.build": true,
+  //   "**/.next": true,
   //   "**/_references": true,
   //   "**/_mono_repo": true,
-  //   "**/electron": true,
-  //   "**/node_modules": true,
-  //   "**/.next": true,
-  //   "**/coverage": true,
-  //   "**/omniroute-*.tgz": true,
-  //   "**/_tasks": true
+  //   "**/_tasks": true,
+  //   "**/omniroute-*.tgz": true
   // },
   "files.watcherExclude": {
-    "**/_references/**": true,
-    "**/_mono_repo/**": true,
-    "**/electron/**": true,
+    "**/.git/objects/**": true,
+    "**/.git/subtree-cache/**": true,
     "**/node_modules/**": true,
     "**/.next/**": true,
+    "**/.build/**": true,
+    "**/dist/**": true,
+    "**/build/**": true,
+    "**/out/**": true,
     "**/coverage/**": true,
-    "**/_tasks/**": true
+    "**/.coverage/**": true,
+    "**/.nyc_output/**": true,
+    "**/.cache/**": true,
+    "**/.turbo/**": true,
+    "**/.swc/**": true,
+    "**/.stryker-tmp/**": true,
+    "**/stryker-output-*/**": true,
+    "**/playwright-report/**": true,
+    "**/test-results/**": true,
+    "**/.worktrees/**": true,
+    "**/.claude/worktrees/**": true,
+    "**/electron/**": true,
+    "**/_references/**": true,
+    "**/_mono_repo/**": true,
+    "**/_tasks/**": true,
+    "**/logs/**": true,
+    "**/*.tgz": true,
+    "**/*.tsbuildinfo": true,
+    "**/OmniRoute-*/**": true,
+    "**/*-merge-*/**": true,
+    "**/*-worktree-*/**": true,
+    "**/*-issues-*/**": true,
+    "**/*-reorg*/**": true
   },
   "search.exclude": {
-    "**/_references": true,
-    "**/_mono_repo": true,
-    "**/electron": true,
     "**/node_modules": true,
     "**/.next": true,
+    "**/.build": true,
+    "**/dist": true,
+    "**/build": true,
+    "**/out": true,
     "**/coverage": true,
-    "**/_tasks": true
+    "**/.coverage": true,
+    "**/.nyc_output": true,
+    "**/.cache": true,
+    "**/.turbo": true,
+    "**/.swc": true,
+    "**/.stryker-tmp": true,
+    "**/stryker-output-*": true,
+    "**/playwright-report": true,
+    "**/test-results": true,
+    "**/.worktrees": true,
+    "**/.claude/worktrees": true,
+    "**/electron": true,
+    "**/_references": true,
+    "**/_mono_repo": true,
+    "**/_tasks": true,
+    "**/logs": true,
+    "**/*.tgz": true,
+    "**/*.tsbuildinfo": true,
+    "**/package-lock.json": true,
+    "**/OmniRoute-*": true,
+    "**/*-merge-*": true,
+    "**/*-worktree-*": true,
+    "**/*-issues-*": true,
+    "**/*-reorg*": true
   }
 }

.zizmor.yml

@@ -0,0 +1,104 @@
+# .zizmor.yml — zizmor security audit configuration
+# https://github.com/woodruffw/zizmor
+#
+# zizmor audits GitHub Actions workflows for security anti-patterns:
+#   • Unpinned third-party actions (supply-chain risk)
+#   • Script injection via ${{ github.* }} in run: steps
+#   • pull_request_target misuse (allows untrusted code to reach secrets)
+#   • Excessive permissions / overly broad GITHUB_TOKEN scopes
+#   • Cache poisoning via actions/cache with unguarded keys
+#   • … 20+ additional audits
+#
+# MOTIVATION (2026-03 incident): the trivy-action/LiteLLM supply-chain attack
+# exploited exactly the kind of pull_request_target misconfiguration that zizmor
+# detects statically. OmniRoute's npm/Docker/Electron publish workflows are high-
+# value targets that warrant proactive audit.
+#
+# BASELINE STRATEGY: this file starts with an EMPTY ignores list. As zizmor is
+# first run against the existing workflows, findings will be reviewed:
+#   • True positives → fix the workflow (preferred)
+#   • Accepted risk  → add an entry below with a justification comment
+# This enforces the same stale-enforcement discipline as other allowlists in
+# this project: every ignore requires human sign-off and is subject to review
+# at each release cycle.
+#
+# RATCHET: zizmorFindings metric in quality-baseline.json (direction: down)
+# starts advisory; current baseline is frozen at first green run; new findings
+# must be remediated or explicitly ignored here.
+
+# ── Global settings ──────────────────────────────────────────────────────────
+# Uncomment to pin to a specific minimum severity level.
+# min-severity: low       # low | medium | high | critical (default: low = all)
+
+# ── Per-rule ignores ─────────────────────────────────────────────────────────
+# zizmor ≥1.0 replaced the old top-level `ignores:` list with a `rules:` map
+# keyed by audit id. Per-rule config lives under `rules.<audit-id>.ignore`,
+# where each entry is `filename` or `filename:line` (line optional, column
+# further-optional). See: https://docs.zizmor.sh/configuration/
+#
+# Format:
+#   rules:
+#     <zizmor-audit-id>:          # e.g. "unpinned-uses", "template-injection"
+#       ignore:
+#         - <workflow-filename>            # ignore this audit across the file
+#         - <workflow-filename>:<line>     # or scope to a specific line
+#
+# Example (do not uncomment without real justification):
+#
+#   rules:
+#     unpinned-uses:
+#       # actions/checkout@v6 is pinned at the major-version tag intentionally:
+#       # GitHub-managed first-party action; SHA pinning buys little against a
+#       # GitHub-side compromise and adds significant maintenance burden.
+#       ignore:
+#         - ci.yml
+
+# Every entry below is an explicit, justified ignore (same stale-review
+# discipline as the other allowlists in this project). New ignores require a
+# per-rule entry with a justification comment.
+rules:
+  dangerous-triggers:
+    # deploy-vps.yml uses `on: workflow_run` (after "Publish to Docker Hub").
+    # zizmor flags workflow_run as "almost always used insecurely", but this one
+    # is guarded and not exploitable:
+    #   • The deploy job is gated on `github.event.workflow_run.conclusion ==
+    #     'success'` (deploy-vps.yml job `if:`, L15), so it only runs after a
+    #     successful, trusted upstream run — never on a forked/PR-triggered
+    #     failure.
+    #   • It does NOT checkout or execute untrusted code: the deploy runs over SSH
+    #     using repository secrets; there is no `actions/checkout` of an attacker
+    #     ref in the privileged context.
+    # Accepted risk, re-review at the next release cycle (added 2026-06-15).
+    ignore:
+      - deploy-vps.yml
+
+  cache-poisoning:
+    # zizmor's cache-poisoning audit flags `actions/setup-node` (cache: npm) and
+    # `actions/cache` steps that populate a cache which a later artifact-publishing
+    # job could consume — the attack is: a fork PR seeds a poisoned cache that a
+    # trusted publish run then restores and ships. None of the four entries below
+    # are exploitable in that way:
+    #
+    #   • electron-release.yml / npm-publish.yml — PUBLISH workflows that trigger
+    #     ONLY on trusted events: `push: tags v*` + `workflow_dispatch` (electron)
+    #     and `release: [released]` + `workflow_dispatch` + `workflow_call`
+    #     (npm). They NEVER run on a `pull_request` from a fork, so an untrusted
+    #     ref can never populate the npm/node_modules cache they restore. The
+    #     cache key is `hashFiles('package-lock.json')` / `runner.os-node-…`, a
+    #     first-party, lockfile-pinned key on trusted events.
+    #
+    #   • opencode-plugin-ci.yml / opencode-provider-ci.yml — CI-only workflows
+    #     (lint/test of the two opencode packages). They DO run on `pull_request`,
+    #     but (a) they publish NO artifacts — there is no downstream publish job
+    #     that restores their cache, and (b) GitHub Actions cache is branch-scoped:
+    #     a fork-PR run writes to a PR-isolated cache that base-branch / release
+    #     runs cannot read. The `cache: npm` here only speeds up `npm ci` within
+    #     the same ephemeral CI run.
+    #
+    # Accepted risk (first-party caching on trusted/isolated events), re-review at
+    # the next release cycle (added 2026-06-16).
+    ignore:
+      - electron-release.yml
+      - npm-publish.yml
+      - opencode-plugin-ci.yml
+      - opencode-provider-ci.yml

@omniroute/opencode-plugin/README.md

@@ -1,26 +1,67 @@
 # @omniroute/opencode-plugin
 
-First-class OpenCode plugin for the [OmniRoute AI Gateway](https://github.com/diegosouzapw/OmniRoute). Pulls a live model catalog from `/v1/models` (including `-low`/`-medium`/`-high`/`-thinking` variants as first-class IDs), aggregates combos via `/api/combos` using a least-common-denominator capability/limit join, sanitizes Gemini tool schemas in flight, and supports multiple side-by-side OmniRoute instances out of the box.
+> **Recommended way to use OmniRoute with OpenCode.** Pulls a live model catalog from `/v1/models` (including `-low`/`-medium`/`-high`/`-thinking` variants as first-class IDs), aggregates combos via `/api/combos` using a least-common-denominator capability/limit join, sanitizes Gemini tool schemas in flight, and supports multiple side-by-side OmniRoute instances out of the box.
+
+## Why this and not `@omniroute/opencode-provider`?
+
+`@omniroute/opencode-provider` is the legacy config-generator package — it writes a frozen `provider.omniroute` block into `opencode.json` with a **hardcoded list of 8 models** ([`OMNIROUTE_DEFAULT_OPENCODE_MODELS`](https://github.com/diegosouzapw/OmniRoute/blob/main/%40omniroute/opencode-provider/src/index.ts#L48-L56)). It works on the CLI but in the **OpenCode Desktop / Web** builds (Tauri / Electron) the runtime re-runs the model picker and the static block surfaces only a few of those — and they drift behind the live OmniRoute catalog.
+
+This plugin solves that by:
+
+- Fetching `/v1/models` and `/api/combos` **at OpenCode startup, in Node.js** — no CORS, no WebView restrictions
+- Emitting the provider block **dynamically** in the plugin's `config`/`provider` hook — so `opencode.json` only needs the plugin entry, not a static `provider.omniroute`
+- Re-fetching on a configurable TTL (default 5 min), so new models / combo changes in the OmniRoute UI appear without restarting OpenCode
+- Computing `limit.context` for combos as `min(member.context_length)` from the live catalog (no more `null` values that cause 4K-token truncation)
+- **Auto-pickup of `interleaved` capability** for thinking models (merged via PR #3138)
+
+**If you only have the legacy `opencode-provider` block in your `opencode.json`, replace it with a single plugin entry.** No other config changes required — the same `auth.json` API key works.
 
 ## Install
 
-Once published to npm:
+The plugin ships **pre-built inside the `omniroute` npm package** since v3.8.23.
+If you have OmniRoute installed, the plugin is already on disk:
 
 ```sh
-npm install @omniroute/opencode-plugin
+# 1. One command — copy the plugin into OpenCode and update opencode.json
+omniroute setup opencode --auth
+
+# 2. Follow the interactive prompt to enter your OmniRoute API key
+# 3. Restart OpenCode — /models lists the full live catalog
 ```
 
-Until then (or for local development), reference the built artifact directly. Either extract the package into your OpenCode plugins dir and point at the extracted `dist/index.js`:
+The `--auth` flag runs `opencode auth login --provider omniroute` automatically.
+Use `--base-url` to point at a non-default OmniRoute address:
+
+```sh
+omniroute setup opencode --base-url https://or.example.com --auth
+```
+
+### What it does
+
+1. Locates the bundled plugin inside the omniroute installation
+2. Copies `dist/` + `package.json` to `~/.config/opencode/plugins/omniroute/`
+3. Writes/updates `opencode.json` with the plugin entry (idempotent, replaces legacy entries)
+4. (With `--auth`) runs `opencode auth login` so the API key is stored
+
+Re-run any time to update the plugin or change the base URL. Older entries for
+`@omniroute/opencode-provider` or the legacy `opencode-omniroute-auth` package are
+automatically cleaned up.
+
+### Manual install (without omniroute CLI)
+
+If you cannot run `omniroute setup opencode` (local dev, CI, air-gapped), reference
+the built artifact directly:
 
 ```sh
-# from inside the OmniRoute repo
 cd @omniroute/opencode-plugin && npm run build && npm pack
 # then extract into ~/.config/opencode/plugins/omniroute-opencode-plugin/
 ```
 
+And add the entry to `opencode.json` manually (see Quick Start below).
+
 Peer dep: `@opencode-ai/plugin` (managed by your OpenCode install).
 
-## Quick start (single instance)
+## Quick start (single instance, manual)
 
 ```jsonc
 // opencode.json
@@ -28,7 +69,7 @@ Peer dep: `@opencode-ai/plugin` (managed by your OpenCode install).
   "$schema": "https://opencode.ai/config.json",
   "plugin": [
     [
-      "@omniroute/opencode-plugin",
+      "./plugins/omniroute-opencode-plugin/dist/index.js",
       {
         "providerId": "omniroute",
         "baseURL": "https://or.example.com",

@omniroute/opencode-plugin/package-lock.json

@@ -26,9 +26,9 @@
       }
     },
     "node_modules/@esbuild/aix-ppc64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz",
-      "integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.1.tgz",
+      "integrity": "sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==",
       "cpu": [
         "ppc64"
       ],
@@ -43,9 +43,9 @@
       }
     },
     "node_modules/@esbuild/android-arm": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz",
-      "integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.1.tgz",
+      "integrity": "sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==",
       "cpu": [
         "arm"
       ],
@@ -60,9 +60,9 @@
       }
     },
     "node_modules/@esbuild/android-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz",
-      "integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.1.tgz",
+      "integrity": "sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==",
       "cpu": [
         "arm64"
       ],
@@ -77,9 +77,9 @@
       }
     },
     "node_modules/@esbuild/android-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.7.tgz",
-      "integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.1.tgz",
+      "integrity": "sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==",
       "cpu": [
         "x64"
       ],
@@ -94,9 +94,9 @@
       }
     },
     "node_modules/@esbuild/darwin-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.7.tgz",
-      "integrity": "sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.1.tgz",
+      "integrity": "sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==",
       "cpu": [
         "arm64"
       ],
@@ -111,9 +111,9 @@
       }
     },
     "node_modules/@esbuild/darwin-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz",
-      "integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.1.tgz",
+      "integrity": "sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==",
       "cpu": [
         "x64"
       ],
@@ -128,9 +128,9 @@
       }
     },
     "node_modules/@esbuild/freebsd-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz",
-      "integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==",
       "cpu": [
         "arm64"
       ],
@@ -145,9 +145,9 @@
       }
     },
     "node_modules/@esbuild/freebsd-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz",
-      "integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.1.tgz",
+      "integrity": "sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==",
       "cpu": [
         "x64"
       ],
@@ -162,9 +162,9 @@
       }
     },
     "node_modules/@esbuild/linux-arm": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz",
-      "integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.1.tgz",
+      "integrity": "sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==",
       "cpu": [
         "arm"
       ],
@@ -179,9 +179,9 @@
       }
     },
     "node_modules/@esbuild/linux-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz",
-      "integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.1.tgz",
+      "integrity": "sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==",
       "cpu": [
         "arm64"
       ],
@@ -196,9 +196,9 @@
       }
     },
     "node_modules/@esbuild/linux-ia32": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz",
-      "integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.1.tgz",
+      "integrity": "sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==",
       "cpu": [
         "ia32"
       ],
@@ -213,9 +213,9 @@
       }
     },
     "node_modules/@esbuild/linux-loong64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz",
-      "integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.1.tgz",
+      "integrity": "sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==",
       "cpu": [
         "loong64"
       ],
@@ -230,9 +230,9 @@
       }
     },
     "node_modules/@esbuild/linux-mips64el": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz",
-      "integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.1.tgz",
+      "integrity": "sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==",
       "cpu": [
         "mips64el"
       ],
@@ -247,9 +247,9 @@
       }
     },
     "node_modules/@esbuild/linux-ppc64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz",
-      "integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.1.tgz",
+      "integrity": "sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==",
       "cpu": [
         "ppc64"
       ],
@@ -264,9 +264,9 @@
       }
     },
     "node_modules/@esbuild/linux-riscv64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz",
-      "integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.1.tgz",
+      "integrity": "sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==",
       "cpu": [
         "riscv64"
       ],
@@ -281,9 +281,9 @@
       }
     },
     "node_modules/@esbuild/linux-s390x": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz",
-      "integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.1.tgz",
+      "integrity": "sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==",
       "cpu": [
         "s390x"
       ],
@@ -298,9 +298,9 @@
       }
     },
     "node_modules/@esbuild/linux-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz",
-      "integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.1.tgz",
+      "integrity": "sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==",
       "cpu": [
         "x64"
       ],
@@ -315,9 +315,9 @@
       }
     },
     "node_modules/@esbuild/netbsd-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz",
-      "integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==",
       "cpu": [
         "arm64"
       ],
@@ -332,9 +332,9 @@
       }
     },
     "node_modules/@esbuild/netbsd-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz",
-      "integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.1.tgz",
+      "integrity": "sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==",
       "cpu": [
         "x64"
       ],
@@ -349,9 +349,9 @@
       }
     },
     "node_modules/@esbuild/openbsd-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz",
-      "integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==",
       "cpu": [
         "arm64"
       ],
@@ -366,9 +366,9 @@
       }
     },
     "node_modules/@esbuild/openbsd-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz",
-      "integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.1.tgz",
+      "integrity": "sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==",
       "cpu": [
         "x64"
       ],
@@ -383,9 +383,9 @@
       }
     },
     "node_modules/@esbuild/openharmony-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz",
-      "integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.1.tgz",
+      "integrity": "sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==",
       "cpu": [
         "arm64"
       ],
@@ -400,9 +400,9 @@
       }
     },
     "node_modules/@esbuild/sunos-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz",
-      "integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.1.tgz",
+      "integrity": "sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==",
       "cpu": [
         "x64"
       ],
@@ -417,9 +417,9 @@
       }
     },
     "node_modules/@esbuild/win32-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz",
-      "integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.1.tgz",
+      "integrity": "sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==",
       "cpu": [
         "arm64"
       ],
@@ -434,9 +434,9 @@
       }
     },
     "node_modules/@esbuild/win32-ia32": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz",
-      "integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.1.tgz",
+      "integrity": "sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==",
       "cpu": [
         "ia32"
       ],
@@ -451,9 +451,9 @@
       }
     },
     "node_modules/@esbuild/win32-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz",
-      "integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.1.tgz",
+      "integrity": "sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==",
       "cpu": [
         "x64"
       ],
@@ -1165,9 +1165,9 @@
       }
     },
     "node_modules/esbuild": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz",
-      "integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.1.tgz",
+      "integrity": "sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==",
       "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
@@ -1178,32 +1178,32 @@
         "node": ">=18"
       },
       "optionalDependencies": {
-        "@esbuild/aix-ppc64": "0.27.7",
-        "@esbuild/android-arm": "0.27.7",
-        "@esbuild/android-arm64": "0.27.7",
-        "@esbuild/android-x64": "0.27.7",
-        "@esbuild/darwin-arm64": "0.27.7",
-        "@esbuild/darwin-x64": "0.27.7",
-        "@esbuild/freebsd-arm64": "0.27.7",
-        "@esbuild/freebsd-x64": "0.27.7",
-        "@esbuild/linux-arm": "0.27.7",
-        "@esbuild/linux-arm64": "0.27.7",
-        "@esbuild/linux-ia32": "0.27.7",
-        "@esbuild/linux-loong64": "0.27.7",
-        "@esbuild/linux-mips64el": "0.27.7",
-        "@esbuild/linux-ppc64": "0.27.7",
-        "@esbuild/linux-riscv64": "0.27.7",
-        "@esbuild/linux-s390x": "0.27.7",
-        "@esbuild/linux-x64": "0.27.7",
-        "@esbuild/netbsd-arm64": "0.27.7",
-        "@esbuild/netbsd-x64": "0.27.7",
-        "@esbuild/openbsd-arm64": "0.27.7",
-        "@esbuild/openbsd-x64": "0.27.7",
-        "@esbuild/openharmony-arm64": "0.27.7",
-        "@esbuild/sunos-x64": "0.27.7",
-        "@esbuild/win32-arm64": "0.27.7",
-        "@esbuild/win32-ia32": "0.27.7",
-        "@esbuild/win32-x64": "0.27.7"
+        "@esbuild/aix-ppc64": "0.28.1",
+        "@esbuild/android-arm": "0.28.1",
+        "@esbuild/android-arm64": "0.28.1",
+        "@esbuild/android-x64": "0.28.1",
+        "@esbuild/darwin-arm64": "0.28.1",
+        "@esbuild/darwin-x64": "0.28.1",
+        "@esbuild/freebsd-arm64": "0.28.1",
+        "@esbuild/freebsd-x64": "0.28.1",
+        "@esbuild/linux-arm": "0.28.1",
+        "@esbuild/linux-arm64": "0.28.1",
+        "@esbuild/linux-ia32": "0.28.1",
+        "@esbuild/linux-loong64": "0.28.1",
+        "@esbuild/linux-mips64el": "0.28.1",
+        "@esbuild/linux-ppc64": "0.28.1",
+        "@esbuild/linux-riscv64": "0.28.1",
+        "@esbuild/linux-s390x": "0.28.1",
+        "@esbuild/linux-x64": "0.28.1",
+        "@esbuild/netbsd-arm64": "0.28.1",
+        "@esbuild/netbsd-x64": "0.28.1",
+        "@esbuild/openbsd-arm64": "0.28.1",
+        "@esbuild/openbsd-x64": "0.28.1",
+        "@esbuild/openharmony-arm64": "0.28.1",
+        "@esbuild/sunos-x64": "0.28.1",
+        "@esbuild/win32-arm64": "0.28.1",
+        "@esbuild/win32-ia32": "0.28.1",
+        "@esbuild/win32-x64": "0.28.1"
       }
     },
     "node_modules/fast-check": {
@@ -1843,490 +1843,6 @@
         "fsevents": "~2.3.3"
       }
     },
-    "node_modules/tsx/node_modules/@esbuild/aix-ppc64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.0.tgz",
-      "integrity": "sha512-lhRUCeuOyJQURhTxl4WkpFTjIsbDayJHih5kZC1giwE+MhIzAb7mEsQMqMf18rHLsrb5qI1tafG20mLxEWcWlA==",
-      "cpu": [
-        "ppc64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "aix"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/android-arm": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.0.tgz",
-      "integrity": "sha512-wqh0ByljabXLKHeWXYLqoJ5jKC4XBaw6Hk08OfMrCRd2nP2ZQ5eleDZC41XHyCNgktBGYMbqnrJKq/K/lzPMSQ==",
-      "cpu": [
-        "arm"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "android"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/android-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.0.tgz",
-      "integrity": "sha512-+WzIXQOSaGs33tLEgYPYe/yQHf0WTU0X42Jca3y8NWMbUVhp7rUnw+vAsRC/QiDrdD31IszMrZy+qwPOPjd+rw==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "android"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/android-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.0.tgz",
-      "integrity": "sha512-+VJggoaKhk2VNNqVL7f6S189UzShHC/mR9EE8rDdSkdpN0KflSwWY/gWjDrNxxisg8Fp1ZCD9jLMo4m0OUfeUA==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "android"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/darwin-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.0.tgz",
-      "integrity": "sha512-0T+A9WZm+bZ84nZBtk1ckYsOvyA3x7e2Acj1KdVfV4/2tdG4fzUp91YHx+GArWLtwqp77pBXVCPn2We7Letr0Q==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/darwin-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.0.tgz",
-      "integrity": "sha512-fyzLm/DLDl/84OCfp2f/XQ4flmORsjU7VKt8HLjvIXChJoFFOIL6pLJPH4Yhd1n1gGFF9mPwtlN5Wf82DZs+LQ==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/freebsd-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.0.tgz",
-      "integrity": "sha512-l9GeW5UZBT9k9brBYI+0WDffcRxgHQD8ShN2Ur4xWq/NFzUKm3k5lsH4PdaRgb2w7mI9u61nr2gI2mLI27Nh3Q==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "freebsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/freebsd-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.0.tgz",
-      "integrity": "sha512-BXoQai/A0wPO6Es3yFJ7APCiKGc1tdAEOgeTNy3SsB491S3aHn4S4r3e976eUnPdU+NbdtmBuLncYir2tMU9Nw==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "freebsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-arm": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.0.tgz",
-      "integrity": "sha512-CjaaREJagqJp7iTaNQjjidaNbCKYcd4IDkzbwwxtSvjI7NZm79qiHc8HqciMddQ6CKvJT6aBd8lO9kN/ZudLlw==",
-      "cpu": [
-        "arm"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.0.tgz",
-      "integrity": "sha512-RVyzfb3FWsGA55n6WY0MEIEPURL1FcbhFE6BffZEMEekfCzCIMtB5yyDcFnVbTnwk+CLAgTujmV/Lgvih56W+A==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-ia32": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.0.tgz",
-      "integrity": "sha512-KBnSTt1kxl9x70q+ydterVdl+Cn0H18ngRMRCEQfrbqdUuntQQ0LoMZv47uB97NljZFzY6HcfqEZ2SAyIUTQBQ==",
-      "cpu": [
-        "ia32"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-loong64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.0.tgz",
-      "integrity": "sha512-zpSlUce1mnxzgBADvxKXX5sl8aYQHo2ezvMNI8I0lbblJtp8V4odlm3Yzlj7gPyt3T8ReksE6bK+pT3WD+aJRg==",
-      "cpu": [
-        "loong64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-mips64el": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.0.tgz",
-      "integrity": "sha512-2jIfP6mmjkdmeTlsX/9vmdmhBmKADrWqN7zcdtHIeNSCH1SqIoNI63cYsjQR8J+wGa4Y5izRcSHSm8K3QWmk3w==",
-      "cpu": [
-        "mips64el"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-ppc64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.0.tgz",
-      "integrity": "sha512-bc0FE9wWeC0WBm49IQMPSPILRocGTQt3j5KPCA8os6VprfuJ7KD+5PzESSrJ6GmPIPJK965ZJHTUlSA6GNYEhg==",
-      "cpu": [
-        "ppc64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-riscv64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.0.tgz",
-      "integrity": "sha512-SQPZOwoTTT/HXFXQJG/vBX8sOFagGqvZyXcgLA3NhIqcBv1BJU1d46c0rGcrij2B56Z2rNiSLaZOYW5cUk7yLQ==",
-      "cpu": [
-        "riscv64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-s390x": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.0.tgz",
-      "integrity": "sha512-SCfR0HN8CEEjnYnySJTd2cw0k9OHB/YFzt5zgJEwa+wL/T/raGWYMBqwDNAC6dqFKmJYZoQBRfHjgwLHGSrn3Q==",
-      "cpu": [
-        "s390x"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.0.tgz",
-      "integrity": "sha512-us0dSb9iFxIi8srnpl931Nvs65it/Jd2a2K3qs7fz2WfGPHqzfzZTfec7oxZJRNPXPnNYZtanmRc4AL/JwVzHQ==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/netbsd-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.0.tgz",
-      "integrity": "sha512-CR/RYotgtCKwtftMwJlUU7xCVNg3lMYZ0RzTmAHSfLCXw3NtZtNpswLEj/Kkf6kEL3Gw+BpOekRX0BYCtklhUw==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "netbsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/netbsd-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.0.tgz",
-      "integrity": "sha512-nU1yhmYutL+fQ71Kxnhg8uEOdC0pwEW9entHykTgEbna2pw2dkbFSMeqjjyHZoCmt8SBkOSvV+yNmm94aUrrqw==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "netbsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/openbsd-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.0.tgz",
-      "integrity": "sha512-cXb5vApOsRsxsEl4mcZ1XY3D4DzcoMxR/nnc4IyqYs0rTI8ZKmW6kyyg+11Z8yvgMfAEldKzP7AdP64HnSC/6g==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "openbsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/openbsd-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.0.tgz",
-      "integrity": "sha512-8wZM2qqtv9UP3mzy7HiGYNH/zjTA355mpeuA+859TyR+e+Tc08IHYpLJuMsfpDJwoLo1ikIJI8jC3GFjnRClzA==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "openbsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/openharmony-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.0.tgz",
-      "integrity": "sha512-FLGfyizszcef5C3YtoyQDACyg95+dndv79i2EekILBofh5wpCa1KuBqOWKrEHZg3zrL3t5ouE5jgr94vA+Wb2w==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "openharmony"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/sunos-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.0.tgz",
-      "integrity": "sha512-1ZgjUoEdHZZl/YlV76TSCz9Hqj9h9YmMGAgAPYd+q4SicWNX3G5GCyx9uhQWSLcbvPW8Ni7lj4gDa1T40akdlw==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "sunos"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/win32-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.0.tgz",
-      "integrity": "sha512-Q9StnDmQ/enxnpxCCLSg0oo4+34B9TdXpuyPeTedN/6+iXBJ4J+zwfQI28u/Jl40nOYAxGoNi7mFP40RUtkmUA==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/win32-ia32": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.0.tgz",
-      "integrity": "sha512-zF3ag/gfiCe6U2iczcRzSYJKH1DCI+ByzSENHlM2FcDbEeo5Zd2C86Aq0tKUYAJJ1obRP84ymxIAksZUcdztHA==",
-      "cpu": [
-        "ia32"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/win32-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.0.tgz",
-      "integrity": "sha512-pEl1bO9mfAmIC+tW5btTmrKaujg3zGtUmWNdCw/xs70FBjwAL3o9OEKNHvNmnyylD6ubxUERiEhdsL0xBQ9efw==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/esbuild": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.0.tgz",
-      "integrity": "sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==",
-      "dev": true,
-      "hasInstallScript": true,
-      "license": "MIT",
-      "bin": {
-        "esbuild": "bin/esbuild"
-      },
-      "engines": {
-        "node": ">=18"
-      },
-      "optionalDependencies": {
-        "@esbuild/aix-ppc64": "0.28.0",
-        "@esbuild/android-arm": "0.28.0",
-        "@esbuild/android-arm64": "0.28.0",
-        "@esbuild/android-x64": "0.28.0",
-        "@esbuild/darwin-arm64": "0.28.0",
-        "@esbuild/darwin-x64": "0.28.0",
-        "@esbuild/freebsd-arm64": "0.28.0",
-        "@esbuild/freebsd-x64": "0.28.0",
-        "@esbuild/linux-arm": "0.28.0",
-        "@esbuild/linux-arm64": "0.28.0",
-        "@esbuild/linux-ia32": "0.28.0",
-        "@esbuild/linux-loong64": "0.28.0",
-        "@esbuild/linux-mips64el": "0.28.0",
-        "@esbuild/linux-ppc64": "0.28.0",
-        "@esbuild/linux-riscv64": "0.28.0",
-        "@esbuild/linux-s390x": "0.28.0",
-        "@esbuild/linux-x64": "0.28.0",
-        "@esbuild/netbsd-arm64": "0.28.0",
-        "@esbuild/netbsd-x64": "0.28.0",
-        "@esbuild/openbsd-arm64": "0.28.0",
-        "@esbuild/openbsd-x64": "0.28.0",
-        "@esbuild/openharmony-arm64": "0.28.0",
-        "@esbuild/sunos-x64": "0.28.0",
-        "@esbuild/win32-arm64": "0.28.0",
-        "@esbuild/win32-ia32": "0.28.0",
-        "@esbuild/win32-x64": "0.28.0"
-      }
-    },
     "node_modules/typescript": {
       "version": "5.9.3",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",

@omniroute/opencode-plugin/package.json

@@ -3,19 +3,16 @@
   "version": "0.1.0",
   "description": "OpenCode plugin for the OmniRoute AI Gateway. Drives dynamic model discovery, /connect auth flow, and multi-instance OmniRoute providers via the official @opencode-ai/plugin contract.",
   "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
+  "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
   "files": [
@@ -26,7 +23,7 @@
   "scripts": {
     "build": "tsup",
     "clean": "rm -rf dist",
-    "test": "node --import tsx/esm --test tests/scaffold.test.ts tests/auth.test.ts tests/options-schema.test.ts tests/multi-instance.test.ts tests/fetch-interceptor.test.ts tests/provider.test.ts tests/gemini-sanitize.test.ts tests/combos.test.ts tests/config-shim.test.ts tests/features.test.ts tests/usable-combo.test.ts tests/disk-snapshot-perms.test.ts",
+    "test": "node --import tsx/esm --test tests/scaffold.test.ts tests/auth.test.ts tests/options-schema.test.ts tests/multi-instance.test.ts tests/fetch-interceptor.test.ts tests/provider.test.ts tests/gemini-sanitize.test.ts tests/combos.test.ts tests/config-shim.test.ts tests/features.test.ts tests/usable-combo.test.ts tests/disk-snapshot-perms.test.ts tests/fork-features.test.ts tests/auto-combo-context.test.ts",
     "prepublishOnly": "npm run clean && npm run build && npm test"
   },
   "keywords": [
@@ -69,5 +66,8 @@
     "tsup": "^8.5.1",
     "tsx": "^4.22.3",
     "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "esbuild": "^0.28.1"
   }
 }

@omniroute/opencode-plugin/src/logger.ts

@@ -0,0 +1,74 @@
+/**
+ * Structured logger for the OmniRoute plugin.
+ *
+ * Levels: error < warn < info < debug
+ * Default: warn (matches current console.warn behavior)
+ * Set via features.logLevel in plugin options.
+ */
+
+export type LogLevel = "error" | "warn" | "info" | "debug";
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3,
+};
+
+const TAG = "[omniroute-plugin]";
+
+function shouldLog(current: LogLevel, target: LogLevel): boolean {
+  return LEVEL_ORDER[current] >= LEVEL_ORDER[target];
+}
+
+let _level: LogLevel = "warn";
+
+export function setLogLevel(level: LogLevel): void {
+  _level = level;
+}
+
+export function getLogLevel(): LogLevel {
+  return _level;
+}
+
+function fmt(level: LogLevel, msg: string, tag?: string): string {
+  const prefix = tag ? `${TAG}${tag}` : TAG;
+  return `${prefix} [${level.toUpperCase()}] ${msg}`;
+}
+
+export const logger = {
+  error(msg: string, ...args: unknown[]): void {
+    if (shouldLog(_level, "error")) console.error(fmt("error", msg), ...args);
+  },
+  warn(msg: string, ...args: unknown[]): void {
+    if (shouldLog(_level, "warn")) console.warn(fmt("warn", msg), ...args);
+  },
+  info(msg: string, ...args: unknown[]): void {
+    if (shouldLog(_level, "info")) console.warn(fmt("info", msg), ...args);
+  },
+  debug(msg: string, ...args: unknown[]): void {
+    if (shouldLog(_level, "debug")) console.warn(fmt("debug", msg), ...args);
+  },
+  /** Always emit regardless of level (for critical init breadcrumbs). */
+  always(msg: string, ...args: unknown[]): void {
+    console.warn(TAG, msg, ...args);
+  },
+
+  // ── Tagged child loggers ──────────────────────────────────────────────
+  child(tag: string) {
+    return {
+      error: (msg: string, ...args: unknown[]) =>
+        shouldLog(_level, "error") &&
+        console.error(fmt("error", msg, tag), ...args),
+      warn: (msg: string, ...args: unknown[]) =>
+        shouldLog(_level, "warn") &&
+        console.warn(fmt("warn", msg, tag), ...args),
+      info: (msg: string, ...args: unknown[]) =>
+        shouldLog(_level, "info") &&
+        console.warn(fmt("info", msg, tag), ...args),
+      debug: (msg: string, ...args: unknown[]) =>
+        shouldLog(_level, "debug") &&
+        console.warn(fmt("debug", msg, tag), ...args),
+    };
+  },
+};

@omniroute/opencode-plugin/src/naming.ts

@@ -0,0 +1,301 @@
+/**
+ * Universal model naming template for the OmniRoute plugin.
+ *
+ * Naming pipeline:
+ *   [tag] <provider-label><separator><display-name><suffix>
+ *
+ *   [Free] <provider> - <name> · <budget>     ← free model
+ *   Auto: <variant> (<N>p)                     ← auto combo
+ *   Combo: <name>                              ← DB combo
+ *   <provider> - <name>                        ← regular model
+ */
+
+// ── Constants ────────────────────────────────────────────────────────────
+
+/** Separator between provider label and model display name. */
+export const PROVIDER_TAG_SEPARATOR = " - ";
+
+/** Threshold beyond which providerDisplayName is abbreviated. */
+const PROVIDER_LABEL_MAX_CHARS = 12;
+
+/** Aliases longer than this get title-case instead of UPPER. */
+const ALIAS_UPPER_MAX_CHARS = 5;
+
+// ── Auto Combo Types ─────────────────────────────────────────────────────
+
+export type AutoVariant =
+  | "coding"
+  | "fast"
+  | "cheap"
+  | "offline"
+  | "smart"
+  | "lkgp";
+
+export const AUTO_VARIANTS: AutoVariant[] = [
+  "coding",
+  "fast",
+  "cheap",
+  "offline",
+  "smart",
+  "lkgp",
+];
+
+export const AUTO_VARIANT_DESCRIPTIONS: Record<
+  AutoVariant | "default",
+  string
+> = {
+  default: "Best provider via scoring",
+  coding: "Quality-first for code tasks",
+  fast: "Latency-optimized routing",
+  cheap: "Cost-optimized routing",
+  offline: "Offline-friendly providers",
+  smart: "Quality-first with exploration",
+  lkgp: "Last-Known-Good-Provider routing",
+};
+
+// ── Free Model Types ─────────────────────────────────────────────────────
+
+export type FreeModelFreeType =
+  | "recurring-daily"
+  | "recurring-monthly"
+  | "recurring-credit"
+  | "one-time-initial"
+  | "keyless"
+  | "discontinued";
+
+// ── Provider Label ────────────────────────────────────────────────────────
+
+/**
+ * Title-case a long, lowercase-looking alias.
+ * `antigravity` → `Antigravity`
+ */
+function titleCaseAlias(alias: string): string {
+  if (alias.length === 0) return alias;
+  return alias.charAt(0).toUpperCase() + alias.slice(1).toLowerCase();
+}
+
+/**
+ * Pick the short label for an upstream provider.
+ *
+ * Rules:
+ *   1. Trim `providerDisplayName`. If ≤12 chars → use verbatim.
+ *   2. Alias ≤5 chars → UPPER(alias). Alias >5 → titleCase.
+ *   3. Neither → undefined.
+ */
+export function shortProviderLabel(
+  enrichment:
+    | { providerDisplayName?: string; providerAlias?: string }
+    | undefined,
+): string | undefined {
+  if (!enrichment) return undefined;
+  const raw =
+    typeof enrichment.providerDisplayName === "string"
+      ? enrichment.providerDisplayName.trim()
+      : "";
+  if (raw.length > 0 && raw.length <= PROVIDER_LABEL_MAX_CHARS) return raw;
+  const alias =
+    typeof enrichment.providerAlias === "string"
+      ? enrichment.providerAlias.trim()
+      : "";
+  if (alias.length > 0) {
+    return alias.length <= ALIAS_UPPER_MAX_CHARS
+      ? alias.toUpperCase()
+      : titleCaseAlias(alias);
+  }
+  // Long displayName with no alias to fall back on: keep the long label
+  // rather than dropping the provider prefix entirely.
+  return raw.length > 0 ? raw : undefined;
+}
+
+// ── Free Label ────────────────────────────────────────────────────────────
+
+/**
+ * Normalise display name so free-tier models get a consistent `[Free] ` prefix.
+ *
+ * "GPT-4.1 (Free)"          → "[Free] GPT-4.1"
+ * "DeepSeek V4 Flash Free"  → "[Free] DeepSeek V4 Flash"
+ * "Claude Opus 4.7"         → "Claude Opus 4.7"  (unchanged)
+ */
+export function normaliseFreeLabel(name: string): string {
+  // Bounded whitespace quantifiers ({0,8}/{1,8}) avoid the polynomial-ReDoS
+  // backtracking that unbounded \s* before an anchored \s*$ would allow on
+  // attacker-influenced display names. 8 covers any realistic label spacing.
+  const cleaned = name
+    .replace(/\s{0,8}\(free\)\s{0,8}$/i, "")
+    .replace(/[\s-]{1,8}free\s{0,8}$/i, "")
+    .trim();
+  const wasFree = cleaned.length < name.trim().length;
+  if (!wasFree) return name;
+  return `[Free] ${cleaned}`;
+}
+
+// ── Free Budget Formatting ────────────────────────────────────────────────
+
+function fmtTokens(n: number): string {
+  if (n >= 1e9) return (n / 1e9).toFixed(1).replace(/\.0$/, "") + "B";
+  if (n >= 1e6) return (n / 1e6).toFixed(1).replace(/\.0$/, "") + "M";
+  if (n >= 1e3) return (n / 1e3).toFixed(1).replace(/\.0$/, "") + "K";
+  return String(n);
+}
+
+/**
+ * Format a free model budget into a short human-readable suffix.
+ *
+ * recurring-daily   → "25M tokens/day"
+ * recurring-monthly → "25M tokens/month"
+ * recurring-credit  → "10M credits"
+ * one-time-initial  → "1M credits (one-time)"
+ * keyless           → "(keyless)"
+ * discontinued      → "(discontinued)"
+ */
+export function formatFreeBudget(params: {
+  freeType: FreeModelFreeType;
+  monthlyTokens?: number;
+  creditTokens?: number;
+}): string {
+  const { freeType, monthlyTokens = 0, creditTokens = 0 } = params;
+
+  switch (freeType) {
+    case "recurring-daily":
+      return `${fmtTokens(monthlyTokens)} tokens/day`;
+    case "recurring-monthly":
+      return `${fmtTokens(monthlyTokens)} tokens/month`;
+    case "recurring-credit":
+      return `${fmtTokens(creditTokens)} credits`;
+    case "one-time-initial":
+      return `${fmtTokens(creditTokens)} credits (one-time)`;
+    case "keyless":
+      return "(keyless)";
+    case "discontinued":
+      return "(discontinued)";
+    default:
+      return "";
+  }
+}
+
+// ── Auto Combo Naming ─────────────────────────────────────────────────────
+
+/**
+ * Format auto combo display name.
+ *
+ * "Auto: Coding (4p)"
+ * "Auto: Default (6p)"
+ * "Auto" (no candidate count when unknown)
+ */
+export function formatAutoComboName(
+  variant: AutoVariant | undefined,
+  candidateCount?: number,
+): string {
+  const label = variant
+    ? variant.charAt(0).toUpperCase() + variant.slice(1)
+    : "Default";
+  const count =
+    typeof candidateCount === "number" && candidateCount > 0
+      ? ` (${candidateCount}p)`
+      : "";
+  return `Auto: ${label}${count}`;
+}
+
+/**
+ * Build the model ID for an auto combo entry.
+ * "auto/coding", "auto/fast", "auto" (default).
+ */
+export function autoComboModelId(variant: AutoVariant | undefined): string {
+  return variant ? `auto/${variant}` : "auto";
+}
+
+// ── Universal Display Name Builder ────────────────────────────────────────
+
+export interface ModelDisplayNameParams {
+  /** Raw model ID (e.g. "cc/claude-sonnet-4-6"). */
+  rawId: string;
+  /** Enrichment display name (e.g. "Claude Sonnet 4.6"). */
+  enrichmentName?: string;
+  /** Provider tag enrichment. */
+  providerAlias?: string;
+  /** Human-readable upstream provider label. */
+  providerDisplayName?: string;
+  /** Whether model is free tier. */
+  isFree?: boolean;
+  /** Free model budget info. */
+  freeType?: FreeModelFreeType;
+  /** Monthly token budget (for recurring free models). */
+  monthlyTokens?: number;
+  /** Credit token budget (for credit-based free models). */
+  creditTokens?: number;
+  /** Whether this is a combo entry (skip provider tag). */
+  isCombo?: boolean;
+  /** Whether this is an auto combo entry. */
+  isAutoCombo?: boolean;
+  /** Auto combo variant. */
+  autoVariant?: AutoVariant;
+  /** Auto combo candidate count. */
+  autoCandidateCount?: number;
+}
+
+/**
+ * Build the final display name following the universal template.
+ *
+ * Priority:
+ *   1. Auto combo → "Auto: <variant> (<N>p)"
+ *   2. DB combo → "Combo: <name>"
+ *   3. Free + enrichment + provider tag → "[Free] <label> - <name> · <budget>"
+ *   4. Free + enrichment → "[Free] <name> · <budget>"
+ *   5. Free + raw → "[Free] <rawId> · <budget>"
+ *   6. Enrichment + provider tag → "<label> - <name>"
+ *   7. Enrichment only → "<name>"
+ *   8. Raw fallback → normaliseFreeLabel(rawId)
+ */
+export function buildModelDisplayName(params: ModelDisplayNameParams): string {
+  // Auto combos
+  if (params.isAutoCombo) {
+    return formatAutoComboName(params.autoVariant, params.autoCandidateCount);
+  }
+
+  // Determine base name — strip any existing free suffix first
+  const rawBase =
+    params.enrichmentName && params.enrichmentName.trim().length > 0
+      ? params.enrichmentName
+      : params.rawId;
+  const cleanedBase = rawBase
+    .replace(/\s*\(free\)\s*$/i, "")
+    .replace(/[\s-]+free\s*$/i, "")
+    .trim();
+  const wasFree = cleanedBase.length < rawBase.trim().length;
+  const isFree = !!params.isFree || wasFree;
+
+  let baseName = cleanedBase;
+
+  // Provider tag (skip for combos)
+  if (!params.isCombo) {
+    const label = shortProviderLabel({
+      providerDisplayName: params.providerDisplayName,
+      providerAlias: params.providerAlias,
+    });
+    if (label) {
+      const prefix = `${label}${PROVIDER_TAG_SEPARATOR}`;
+      if (!baseName.startsWith(prefix)) {
+        baseName = `${prefix}${baseName}`;
+      }
+    }
+  }
+
+  // Prepend [Free] if applicable (AFTER provider tag for correct ordering)
+  if (isFree) {
+    baseName = `[Free] ${baseName}`;
+  }
+
+  // Free budget suffix
+  if (isFree && params.freeType) {
+    const budget = formatFreeBudget({
+      freeType: params.freeType,
+      monthlyTokens: params.monthlyTokens,
+      creditTokens: params.creditTokens,
+    });
+    if (budget) {
+      baseName = `${baseName} · ${budget}`;
+    }
+  }
+
+  return baseName;
+}

@omniroute/opencode-plugin/tests/auth.test.ts

@@ -13,12 +13,12 @@ import { createOmniRouteAuthHook } from "../src/index.js";
 
 test("createOmniRouteAuthHook: default providerId is 'omniroute'", () => {
   const hook = createOmniRouteAuthHook();
-  assert.equal(hook.provider, "omniroute");
+  assert.equal(hook.provider, "opencode-omniroute");
 });
 
 test("createOmniRouteAuthHook: custom providerId binds to hook.provider (multi-instance)", () => {
   const hook = createOmniRouteAuthHook({ providerId: "omniroute-preprod" });
-  assert.equal(hook.provider, "omniroute-preprod");
+  assert.equal(hook.provider, "opencode-omniroute-preprod");
 });
 
 test("createOmniRouteAuthHook: methods[0] is type 'api' with label including displayName", () => {
@@ -30,7 +30,7 @@ test("createOmniRouteAuthHook: methods[0] is type 'api' with label including dis
   assert.equal(m.label, "OmniRoute API Key");
 
   const custom = createOmniRouteAuthHook({ providerId: "omniroute-preprod" });
-  assert.equal(custom.methods[0].label, "OmniRoute (omniroute-preprod) API Key");
+  assert.equal(custom.methods[0].label, "OmniRoute (opencode-omniroute-preprod) API Key");
 });
 
 test("createOmniRouteAuthHook: prompts[0] uses key='apiKey' per @opencode-ai/plugin contract", () => {

@omniroute/opencode-plugin/tests/auto-combo-context.test.ts

@@ -0,0 +1,74 @@
+/**
+ * TDD regression — auto combos must never advertise `limit.context: 0`.
+ *
+ * opencode's overflow guard (packages/opencode/src/session/overflow.ts)
+ * short-circuits when `model.limit.context === 0`:
+ *
+ *   if (input.model.limit.context === 0) return false  // never overflow
+ *
+ * so a zero context silently DISABLES opencode's smart auto-compaction for
+ * auto combos. The session then grows unbounded until OmniRoute's
+ * server-side purifyHistory() destructively drops old messages — the
+ * "coding agent keeps forgetting things" bug.
+ *
+ * Fix under test: mapAutoComboToStaticEntry consumes the context_length /
+ * max_output_tokens now served by GET /api/combos/auto, and falls back to a
+ * safe positive default (128000 / 8192) for older servers that do not send
+ * the fields yet.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { mapAutoComboToStaticEntry } from "../src/index.ts";
+import type { OmniRouteRawAutoCombo } from "../src/index.ts";
+
+test("uses server-provided context_length and max_output_tokens", () => {
+  const raw = {
+    id: "auto/coding",
+    name: "Auto Coding",
+    variant: "coding",
+    candidateCount: 5,
+    context_length: 1048576,
+    max_output_tokens: 65536,
+  } as OmniRouteRawAutoCombo;
+
+  const entry = mapAutoComboToStaticEntry(raw);
+  assert.equal(entry.limit?.context, 1048576);
+  assert.equal(entry.limit?.output, 65536);
+});
+
+test("falls back to a safe positive default when the server omits limits (old servers)", () => {
+  const raw = {
+    id: "auto",
+    name: "Auto",
+    candidateCount: 3,
+  } as OmniRouteRawAutoCombo;
+
+  const entry = mapAutoComboToStaticEntry(raw);
+  assert.ok(
+    typeof entry.limit?.context === "number" && entry.limit.context > 0,
+    `context must be a positive number (never 0 — zero disables opencode auto-compaction), got ${entry.limit?.context}`
+  );
+  assert.ok(
+    typeof entry.limit?.output === "number" && entry.limit.output > 0,
+    `output must be a positive number, got ${entry.limit?.output}`
+  );
+});
+
+test("ignores non-positive server values and keeps the safe fallback", () => {
+  const raw = {
+    id: "auto/fast",
+    name: "Auto Fast",
+    variant: "fast",
+    candidateCount: 2,
+    context_length: 0,
+    max_output_tokens: -1,
+  } as OmniRouteRawAutoCombo;
+
+  const entry = mapAutoComboToStaticEntry(raw);
+  assert.ok(
+    typeof entry.limit?.context === "number" && entry.limit.context > 0,
+    "zero/negative server values must not propagate"
+  );
+  assert.ok(typeof entry.limit?.output === "number" && entry.limit.output > 0);
+});

@omniroute/opencode-plugin/tests/combos.test.ts

@@ -447,14 +447,14 @@ test("models() returns combo entries merged into the map", async () => {
 
   // 3 raw models + 1 combo = 4 entries
   assert.equal(Object.keys(out).length, 4);
-  assert.ok(out["claude-primary"]);
-  assert.ok(out["claude-secondary"]);
-  assert.ok(out["gemini-3-flash"]);
-  assert.ok(out["combo/claude-tier"]);
+  assert.ok(out["opencode-omniroute/claude-primary"]);
+  assert.ok(out["opencode-omniroute/claude-secondary"]);
+  assert.ok(out["opencode-omniroute/gemini-3-flash"]);
+  assert.ok(out["opencode-omniroute/claude-tier"]);
 
-  const combo = out["combo/claude-tier"];
-  assert.equal(combo.name, "Combo: Claude Tier");
-  assert.equal(combo.providerID, "omniroute");
+  const combo = out["opencode-omniroute/claude-tier"];
+  assert.equal(combo.name, "Claude Tier");
+  assert.equal(combo.providerID, "opencode-omniroute");
   // LCD over claude-primary (200k, reasoning) + claude-secondary (100k, no reasoning)
   assert.equal(combo.limit.context, 100_000);
   assert.equal(combo.capabilities.reasoning, false);
@@ -478,11 +478,11 @@ test("models(): combo with unknown member ids degrades to all-false LCD posture"
     { fetcher: modelsFetcher, combosFetcher }
   );
   const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
-  assert.ok(out["combo/phantom-combo"]);
+  assert.ok(out["opencode-omniroute/phantom-combo"]);
   // With zero resolvable members, LCD = all-false (defensive posture).
-  assert.equal(out["combo/phantom-combo"].capabilities.toolcall, false);
-  assert.equal(out["combo/phantom-combo"].capabilities.reasoning, false);
-  assert.equal(out["combo/phantom-combo"].limit.context, 0);
+  assert.equal(out["opencode-omniroute/phantom-combo"].capabilities.toolcall, false);
+  assert.equal(out["opencode-omniroute/phantom-combo"].capabilities.reasoning, false);
+  assert.equal(out["opencode-omniroute/phantom-combo"].limit.context, 0);
 });
 
 test("models(): hidden combos are excluded from the map", async () => {
@@ -505,11 +505,11 @@ test("models(): hidden combos are excluded from the map", async () => {
     { fetcher: modelsFetcher, combosFetcher }
   );
   const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
-  assert.ok(out["combo/visible"]);
-  assert.ok(!out["combo/hidden"], "hidden combo must be omitted");
+  assert.ok(out["opencode-omniroute/visible"]);
+  assert.ok(!out["opencode-omniroute/hidden"], "hidden combo must be omitted");
 });
 
-test("models(): combo name exactly matches raw model id → raw deleted, combo lives at combo/ key, no warn", async () => {
+test("models(): combo name exactly matches raw model id → raw deleted, raw deleted, no warn", async () => {
   // Combo.name === raw model id triggers the dedup deletion. This mirrors
   // the real OmniRoute payload where /v1/models pre-mirrors combos as
   // no-slash raw entries whose ids match /api/combos friendly names.
@@ -529,10 +529,9 @@ test("models(): combo name exactly matches raw model id → raw deleted, combo l
     return hook.models!({} as never, { auth: apiAuth("sk-z") as never });
   });
 
-  // Raw model deleted by combo-name dedup; combo surfaces under combo/<slug>.
-  assert.equal(out["claude-primary"], undefined, "raw deleted by combo-name dedup");
-  assert.ok(out["combo/claude-primary"], "combo surfaces under combo/ namespace");
-  assert.equal(out["combo/claude-primary"].name, "Combo: claude-primary");
+  // Raw model replaced by combo of the same key; combo now lives at the bare slug.
+  assert.ok(out["opencode-omniroute/claude-primary"], "combo surfaces under prefixed key");
+  assert.equal(out["opencode-omniroute/claude-primary"].name, "claude-primary");
 
   // No collision warning fires — dedup makes keys disjoint.
   const collisionWarns = warnings.filter((w) => {
@@ -543,7 +542,7 @@ test("models(): combo name exactly matches raw model id → raw deleted, combo l
 });
 
 test("models(): two combos with same slug → second gets disambiguator suffix", async () => {
-  // Both combos slug to `claude` — second must get `combo/claude-<id-prefix>`.
+  // Both combos slug to `claude` — second must get `claude-<id-prefix>`.
   const combos: OmniRouteRawCombo[] = [
     {
       id: "uuid-a",
@@ -566,8 +565,8 @@ test("models(): two combos with same slug → second gets disambiguator suffix",
 
   const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
   // First combo gets the bare slug; second gets disambiguated.
-  assert.ok(out["combo/claude"], "first combo at bare slug");
-  assert.ok(out["combo/claude-uuid"], "second combo disambiguated by id prefix");
+  assert.ok(out["opencode-omniroute/claude"], "first combo at prefixed slug");
+  assert.ok(out["opencode-omniroute/claude-uuid"], "second combo disambiguated by id prefix");
 });
 
 test("models(): combos fetch fails → falls back to models-only, warn emitted, no throw", async () => {
@@ -584,8 +583,8 @@ test("models(): combos fetch fails → falls back to models-only, warn emitted,
 
   // Catalog includes the models but NOT any combo entries.
   assert.equal(Object.keys(out).length, 2);
-  assert.ok(out["claude-primary"]);
-  assert.ok(out["claude-secondary"]);
+  assert.ok(out["opencode-omniroute/claude-primary"]);
+  assert.ok(out["opencode-omniroute/claude-secondary"]);
 
   // Soft-fail warning surfaced.
   const softFail = warnings.find((w) => {
@@ -610,7 +609,7 @@ test("models(): combos cached + reused within TTL (one combo fetch per TTL windo
   const second = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
   assert.equal(combosFetcher.callCount(), 1, "combos fetched only once within TTL");
   assert.equal(modelsFetcher.callCount(), 1, "models fetched only once within TTL");
-  assert.ok(second["combo/claude-tier"]);
+  assert.ok(second["opencode-omniroute/claude-tier"]);
 });
 
 test("models(): combos refetched after TTL expiry (same key as models)", async () => {
@@ -639,3 +638,74 @@ test("models(): combos fetcher receives the resolved baseURL + apiKey", async ()
   await hook.models!({} as never, { auth: apiAuth("sk-spy") as never });
   assert.deepEqual(combosFetcher.callsBy()[0], ["https://or.example.com/v1", "sk-spy"]);
 });
+
+test("models(): nested combo-ref context is the min of nested + raw members", async () => {
+  // Top-level combo MASTER-LIGHT has 1 raw model (claude-primary, 200k)
+  // and 2 combo-refs: OldLLM (8k member) and KIRO (32k member). The OLD
+  // plugin would advertise 200k (only the raw model); the fix should
+  // make it advertise 8k (the bottleneck across the member graph).
+  const modelsFetcher = stubModelsFetcher([
+    MODEL_PRIMARY,
+    {
+      id: "oldllm-member-1",
+      context_length: 8_000,
+      max_output_tokens: 4_000,
+      capabilities: {
+        tool_calling: false,
+        reasoning: false,
+        vision: false,
+        thinking: false,
+        temperature: true,
+      },
+      input_modalities: ["text"],
+      output_modalities: ["text"],
+    },
+    {
+      id: "kiro-member-1",
+      context_length: 32_000,
+      max_output_tokens: 8_000,
+      capabilities: {
+        tool_calling: true,
+        reasoning: false,
+        vision: false,
+        thinking: false,
+        temperature: true,
+      },
+      input_modalities: ["text"],
+      output_modalities: ["text"],
+    },
+  ]);
+  const combosFetcher = stubCombosFetcher([
+    {
+      id: "oldllm",
+      name: "OldLLM",
+      models: [{ id: "s1", kind: "model", model: "oldllm-member-1", weight: 100 }],
+    },
+    {
+      id: "kiro",
+      name: "KIRO",
+      models: [{ id: "s1", kind: "model", model: "kiro-member-1", weight: 100 }],
+    },
+    {
+      id: "master-light",
+      name: "MASTER-LIGHT",
+      models: [
+        { id: "r1", kind: "model", model: "claude-primary", weight: 50 },
+        { id: "r2", kind: "combo-ref", comboName: "OldLLM", weight: 25 },
+        { id: "r3", kind: "combo-ref", comboName: "KIRO", weight: 25 },
+      ],
+    },
+  ]);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher: modelsFetcher, combosFetcher }
+  );
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  const masterLight = out["opencode-omniroute/master-light"];
+  assert.ok(masterLight, "MASTER-LIGHT entry must exist");
+  assert.equal(
+    masterLight.limit.context,
+    8_000,
+    `expected 8_000 (OldLLM bottleneck), got ${masterLight.limit.context}`
+  );
+});

@omniroute/opencode-plugin/tests/config-shim.test.ts

@@ -203,7 +203,7 @@ function makeInput(initialProvider: Record<string, unknown> = {}): Config {
 
 test("config: with valid auth.json + apiKey + baseURL → mutates input.provider[id] with stripped models block", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test-1", baseURL: "https://or.example.com/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test-1", baseURL: "https://or.example.com/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE, MODEL_GEMINI]);
   const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
@@ -217,8 +217,8 @@ test("config: with valid auth.json + apiKey + baseURL → mutates input.provider
   await hook(input);
 
   const provider = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider;
-  const entry = provider.omniroute;
-  assert.ok(entry, "input.provider.omniroute set");
+  const entry = provider["opencode-omniroute"];
+  assert.ok(entry, "input.provider['opencode-omniroute'] set");
   assert.equal(entry.npm, "@ai-sdk/openai-compatible");
   assert.equal(entry.name, "OmniRoute");
   assert.equal(entry.options.baseURL, "https://or.example.com/v1");
@@ -227,7 +227,7 @@ test("config: with valid auth.json + apiKey + baseURL → mutates input.provider
   // Stripped per-model shape: name + cap flags + modalities + (optional)
   // cost. OC's SDK static schema accepts only `limit.{context,output}` —
   // `limit.input` is NOT in the SDK shape and gets dropped silently.
-  const claude = entry.models["claude-sonnet-4-6"];
+  const claude = entry.models["opencode-omniroute/claude-sonnet-4-6"];
   assert.ok(claude, "claude model surfaced");
   assert.equal(claude.name, "claude-sonnet-4-6");
   assert.equal(claude.attachment, true);
@@ -246,16 +246,75 @@ test("config: with valid auth.json + apiKey + baseURL → mutates input.provider
   assert.deepEqual(claude.modalities?.input, ["text", "image"]);
   assert.deepEqual(claude.modalities?.output, ["text"]);
 
-  // Combo surfaces under `combo/<friendly-name>` namespace + LCD'd
+  // Combo surfaces under bare key + LCD'd
   // (gemini's reasoning=false → combo reasoning=false).
-  const combo = entry.models["combo/claude-tier"];
-  assert.ok(combo, "combo surfaced under combo/ namespace");
-  assert.equal(combo.name, "Combo: Claude Tier");
+  const combo = entry.models["opencode-omniroute/claude-tier"];
+  assert.ok(combo, "combo surfaced under bare key");
+  assert.equal(combo.name, "Claude Tier");
   assert.equal(combo.reasoning, false, "LCD: any member reasoning=false → combo reasoning=false");
   assert.equal(combo.tool_call, true);
   assert.equal(combo.limit?.context, 200_000, "LCD: min(200_000, 1_000_000)");
 });
 
+// ────────────────────────────────────────────────────────────────────────────
+// 1b. Dual-key fallback (#5027) — auth.json stored under the BARE providerId
+//     (pre-auto-prefix login) must still resolve when the active providerId is
+//     prefixed (`opencode-omniroute`). Without the fallback the lookup misses
+//     the stored key and the user is forced to re-auth.
+// ────────────────────────────────────────────────────────────────────────────
+
+test("config: auth.json under bare key (pre-prefix login) resolves via dual-key fallback", async () => {
+  // Stored under bare `omniroute` (the key OC wrote before the auto-prefix fix),
+  // but the resolved providerId is now `opencode-omniroute`.
+  const readAuthJson = stubReadAuthJson({
+    omniroute: { type: "api", key: "sk-bare-1", baseURL: "https://or.example.com/v1" },
+  });
+  const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
+  const combosFetcher = stubCombosFetcher([]);
+  const logger = captureWarn();
+
+  const hook = createOmniRouteConfigHook(
+    { providerId: "omniroute" }, // resolves to opencode-omniroute internally
+    { readAuthJson, fetcher, combosFetcher, logger }
+  );
+  const input = makeInput();
+  await hook(input);
+
+  const provider = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider;
+  const entry = provider["opencode-omniroute"];
+  assert.ok(entry, "provider entry published from bare-key apiKey");
+  assert.equal(entry.options.apiKey, "sk-bare-1", "apiKey resolved from the bare auth.json key");
+  assert.equal(entry.options.baseURL, "https://or.example.com/v1");
+});
+
+test("config: prefixed key wins over bare key when both present (dual-key precedence)", async () => {
+  const readAuthJson = stubReadAuthJson({
+    "opencode-omniroute": { type: "api", key: "sk-prefixed", baseURL: "https://pref.example/v1" },
+    omniroute: { type: "api", key: "sk-bare", baseURL: "https://bare.example/v1" },
+  });
+  const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
+  const combosFetcher = stubCombosFetcher([]);
+  const logger = captureWarn();
+
+  const hook = createOmniRouteConfigHook(
+    { providerId: "omniroute" },
+    { readAuthJson, fetcher, combosFetcher, logger }
+  );
+  const input = makeInput();
+  await hook(input);
+
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
+  assert.ok(entry);
+  assert.equal(
+    entry.options.apiKey,
+    "sk-prefixed",
+    "prefixed key takes precedence (looked up first)"
+  );
+  assert.equal(entry.options.baseURL, "https://pref.example/v1");
+});
+
 // ────────────────────────────────────────────────────────────────────────────
 // 2. Missing auth.json → no-op, no throw, no mutation
 // ────────────────────────────────────────────────────────────────────────────
@@ -323,7 +382,7 @@ test("config: existing input.provider[id] → no overwrite (respect manual overr
     models: { "manual-model": { name: "manual-model" } },
   };
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -333,11 +392,11 @@ test("config: existing input.provider[id] → no overwrite (respect manual overr
     { providerId: "omniroute" },
     { readAuthJson, fetcher, combosFetcher, logger }
   );
-  const input = makeInput({ omniroute: manual });
+  const input = makeInput({ "opencode-omniroute": manual });
   await hook(input);
 
   const provider = (input as { provider: Record<string, unknown> }).provider;
-  assert.equal(provider.omniroute, manual, "manual override preserved by reference");
+  assert.equal(provider["opencode-omniroute"], manual, "manual override preserved by reference");
   assert.equal(fetcher.callCount(), 0, "no fetch — short-circuited before I/O");
   assert.equal(readAuthJson.callCount(), 0, "no auth.json read either");
   assert.ok(
@@ -352,7 +411,7 @@ test("config: existing input.provider[id] → no overwrite (respect manual overr
 
 test("config: fetchers throw → warn + emit stub entry with models: {}", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = throwingModelsFetcher();
   const combosFetcher = throwingCombosFetcher();
@@ -368,8 +427,9 @@ test("config: fetchers throw → warn + emit stub entry with models: {}", async
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry, "stub provider entry published even when fetchers fail");
   assert.equal(entry.npm, "@ai-sdk/openai-compatible");
   assert.deepEqual(entry.models, {}, "models stub is empty object");
@@ -392,7 +452,7 @@ test("config: fetchers throw → warn + emit stub entry with models: {}", async
 
 test("config: combos fetcher throws → emit models-only catalog (no combos in models block)", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE, MODEL_GEMINI]);
   const combosFetcher = throwingCombosFetcher();
@@ -405,12 +465,16 @@ test("config: combos fetcher throws → emit models-only catalog (no combos in m
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry);
   const ids = Object.keys(entry.models).sort();
-  assert.deepEqual(ids, ["claude-sonnet-4-6", "gemini-3-flash"]);
-  assert.equal(entry.models["combo-claude-tier"], undefined, "no combo entry");
+  assert.deepEqual(ids, [
+    "opencode-omniroute/claude-sonnet-4-6",
+    "opencode-omniroute/gemini-3-flash",
+  ]);
+  assert.equal(entry.models["opencode-omniroute/claude-tier"], undefined, "no combo entry");
   assert.ok(
     logger.entries.some((e) => String(e[0]).includes("/api/combos fetch failed")),
     "combos-fetch breadcrumb emitted"
@@ -423,7 +487,7 @@ test("config: combos fetcher throws → emit models-only catalog (no combos in m
 
 test("config: baseURL from auth.json takes precedence when opts.baseURL absent", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://creds.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://creds.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -437,14 +501,15 @@ test("config: baseURL from auth.json takes precedence when opts.baseURL absent",
   await hook(input);
 
   assert.equal(fetcher.callsBy()[0][0], "https://creds.example/v1");
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.equal(entry.options.baseURL, "https://creds.example/v1");
 });
 
 test("config: opts.baseURL wins over auth.json's stored baseURL", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://creds.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://creds.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -458,14 +523,15 @@ test("config: opts.baseURL wins over auth.json's stored baseURL", async () => {
   await hook(input);
 
   assert.equal(fetcher.callsBy()[0][0], "https://opts.example/v1");
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.equal(entry.options.baseURL, "https://opts.example/v1");
 });
 
 test("config: no baseURL resolvable (no opts, no auth.json baseURL) → no-op", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test" }, // NO baseURL on the credential
+    "opencode-omniroute": { type: "api", key: "sk-test" }, // NO baseURL on the credential
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -493,12 +559,12 @@ test("config: no baseURL resolvable (no opts, no auth.json baseURL) → no-op",
 
 test("config: multi-instance — two plugins with different providerIds publish to their own keys without collision", async () => {
   const readAuthJson = stubReadAuthJson({
-    "omniroute-prod": {
+    "opencode-omniroute-prod": {
       type: "api",
       key: "sk-prod",
       baseURL: "https://prod.example/v1",
     },
-    "omniroute-preprod": {
+    "opencode-omniroute-preprod": {
       type: "api",
       key: "sk-preprod",
       baseURL: "https://preprod.example/v1",
@@ -522,15 +588,18 @@ test("config: multi-instance — two plugins with different providerIds publish
   await hookB(input);
 
   const provider = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider;
-  assert.ok(provider["omniroute-prod"], "prod block present");
-  assert.ok(provider["omniroute-preprod"], "preprod block present");
-  assert.equal(provider["omniroute-prod"].options.apiKey, "sk-prod");
-  assert.equal(provider["omniroute-preprod"].options.apiKey, "sk-preprod");
-  assert.equal(provider["omniroute-prod"].options.baseURL, "https://prod.example/v1");
-  assert.equal(provider["omniroute-preprod"].options.baseURL, "https://preprod.example/v1");
+  assert.ok(provider["opencode-omniroute-prod"], "prod block present");
+  assert.ok(provider["opencode-omniroute-preprod"], "preprod block present");
+  assert.equal(provider["opencode-omniroute-prod"].options.apiKey, "sk-prod");
+  assert.equal(provider["opencode-omniroute-preprod"].options.apiKey, "sk-preprod");
+  assert.equal(provider["opencode-omniroute-prod"].options.baseURL, "https://prod.example/v1");
+  assert.equal(
+    provider["opencode-omniroute-preprod"].options.baseURL,
+    "https://preprod.example/v1"
+  );
   assert.notEqual(
-    provider["omniroute-prod"],
-    provider["omniroute-preprod"],
+    provider["opencode-omniroute-prod"],
+    provider["opencode-omniroute-preprod"],
     "blocks are distinct references"
   );
 });
@@ -542,7 +611,7 @@ test("config: multi-instance — two plugins with different providerIds publish
 
 test("config + provider share cache: second call uses cached fetch result (single fetch per TTL)", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-shared", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-shared", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
@@ -574,7 +643,7 @@ test("config + provider share cache: second call uses cached fetch result (singl
 
 test("provider → config order also dedupes (cache populated by provider, consumed by config)", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-reverse", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-reverse", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -638,6 +707,7 @@ test("buildStaticProviderEntry: stripped per-model shape matches sibling @omniro
     "cost",
     "limit",
     "modalities",
+    "providerID",
   ]);
   for (const [id, entry] of Object.entries(block.models)) {
     for (const key of Object.keys(entry)) {
@@ -653,7 +723,7 @@ test("buildStaticProviderEntry: stripped per-model shape matches sibling @omniro
   }
 
   // Sanity: claude entry has all expected stripped fields.
-  const claude = block.models["claude-sonnet-4-6"];
+  const claude = block.models["opencode-omniroute/claude-sonnet-4-6"];
   assert.equal(typeof claude.name, "string");
   assert.equal(typeof claude.attachment, "boolean");
   assert.equal(typeof claude.reasoning, "boolean");
@@ -678,8 +748,8 @@ test("buildStaticProviderEntry: hidden combos are excluded", () => {
     "https://or.example/v1",
     "sk-test"
   );
-  assert.equal(block.models["combo-claude-tier"], undefined);
-  assert.ok(block.models["claude-sonnet-4-6"]);
+  assert.equal(block.models["opencode-omniroute/claude-tier"], undefined);
+  assert.ok(block.models["opencode-omniroute/claude-sonnet-4-6"]);
 });
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -695,7 +765,7 @@ test("buildStaticProviderEntry: emits modalities.input from raw.input_modalities
     "https://or.example/v1",
     "sk-test"
   );
-  const claude = block.models["claude-sonnet-4-6"];
+  const claude = block.models["opencode-omniroute/claude-sonnet-4-6"];
   assert.deepEqual(claude.modalities?.input, ["text", "image"]);
   assert.deepEqual(claude.modalities?.output, ["text"]);
 });
@@ -709,7 +779,7 @@ test("buildStaticProviderEntry: never emits limit.input (OC SDK rejects it)", ()
     "https://or.example/v1",
     "sk-test"
   );
-  const claude = block.models["claude-sonnet-4-6"];
+  const claude = block.models["opencode-omniroute/claude-sonnet-4-6"];
   assert.equal((claude.limit as Record<string, unknown>).input, undefined);
   assert.equal(typeof claude.limit?.context, "number");
   assert.equal(typeof claude.limit?.output, "number");
@@ -737,7 +807,7 @@ test("buildStaticProviderEntry: emits cost when enrichment carries pricing", ()
     "sk-test",
     enrichment
   );
-  const claude = block.models["claude-sonnet-4-6"];
+  const claude = block.models["opencode-omniroute/claude-sonnet-4-6"];
   assert.equal(claude.cost?.input, 3);
   assert.equal(claude.cost?.output, 15);
   assert.equal(claude.cost?.cache_read, 0.3);
@@ -758,8 +828,8 @@ test("buildStaticProviderEntry: emits release_date when raw carries it; omits wh
     "https://or.example/v1",
     "sk-test"
   );
-  assert.equal(block.models["claude-with-date"].release_date, "2026-02-19");
-  assert.equal(block.models["gemini-3-flash"].release_date, undefined);
+  assert.equal(block.models["opencode-omniroute/claude-with-date"].release_date, "2026-02-19");
+  assert.equal(block.models["opencode-omniroute/gemini-3-flash"].release_date, undefined);
 });
 
 test("buildStaticProviderEntry: combo modalities = intersection of members (LCD)", () => {
@@ -788,7 +858,7 @@ test("buildStaticProviderEntry: combo modalities = intersection of members (LCD)
     "https://or.example/v1",
     "sk-test"
   );
-  const combo = block.models["combo/mixed-tier"];
+  const combo = block.models["opencode-omniroute/mixed-tier"];
   assert.ok(combo, "combo emitted under slug key");
   // claude has text+image, text-only has text → intersection drops image.
   assert.deepEqual(combo.modalities?.input, ["text"]);
@@ -812,7 +882,7 @@ test("OmniRoutePlugin factory exposes config hook alongside auth + provider", as
 
 test("config: auth.json entry of wrong type (oauth) → no-op", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "oauth", refresh: "r", access: "a", expires: 0 },
+    "opencode-omniroute": { type: "oauth", refresh: "r", access: "a", expires: 0 },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -849,7 +919,7 @@ test("config: readAuthJson throws → treat as missing file (silent fallback)",
 
 test("config: initialises input.provider when undefined", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -864,7 +934,7 @@ test("config: initialises input.provider when undefined", async () => {
   await hook(input);
   const provider = (input as { provider?: Record<string, unknown> }).provider;
   assert.ok(provider, "provider bag initialised");
-  assert.ok(provider!.omniroute);
+  assert.ok(provider!["opencode-omniroute"]);
 });
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -874,7 +944,7 @@ test("config: initialises input.provider when undefined", async () => {
 
 test("config: enrichment fetched + name overlaid on raw-model entries", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE, MODEL_GEMINI]);
   const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
@@ -893,19 +963,20 @@ test("config: enrichment fetched + name overlaid on raw-model entries", async ()
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry);
-  assert.equal(entry.models["claude-sonnet-4-6"].name, "Claude Sonnet 4.6");
-  assert.equal(entry.models["gemini-3-flash"].name, "Gemini 3 Flash");
+  assert.equal(entry.models["opencode-omniroute/claude-sonnet-4-6"].name, "Claude Sonnet 4.6");
+  assert.equal(entry.models["opencode-omniroute/gemini-3-flash"].name, "Gemini 3 Flash");
   // Combo names still come from /api/combos — enrichment overlay does NOT touch combos.
-  assert.equal(entry.models["combo/claude-tier"].name, "Combo: Claude Tier");
+  assert.equal(entry.models["opencode-omniroute/claude-tier"].name, "Claude Tier");
   assert.equal(enrichmentFetcher.callCount(), 1);
 });
 
 test("config: features.enrichment=false skips enrichment fetch + keeps raw-id names", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -923,16 +994,21 @@ test("config: features.enrichment=false skips enrichment fetch + keeps raw-id na
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry);
   assert.equal(enrichmentFetcher.callCount(), 0, "enrichment fetch suppressed by feature flag");
-  assert.equal(entry.models["claude-sonnet-4-6"].name, "claude-sonnet-4-6", "raw id retained");
+  assert.equal(
+    entry.models["opencode-omniroute/claude-sonnet-4-6"].name,
+    "claude-sonnet-4-6",
+    "raw id retained"
+  );
 });
 
 test("config: enrichment fetcher throws → soft-fail (warn + raw-id static catalog)", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -946,10 +1022,15 @@ test("config: enrichment fetcher throws → soft-fail (warn + raw-id static cata
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry, "static block still published on enrichment failure");
-  assert.equal(entry.models["claude-sonnet-4-6"].name, "claude-sonnet-4-6", "raw id retained");
+  assert.equal(
+    entry.models["opencode-omniroute/claude-sonnet-4-6"].name,
+    "claude-sonnet-4-6",
+    "raw id retained"
+  );
   assert.equal(enrichmentFetcher.callCount(), 1);
   assert.ok(
     logger.entries.some((e) => String(e[0]).includes("/api/pricing/models fetch failed")),
@@ -990,7 +1071,7 @@ const MODEL_NV_LLAMA: OmniRouteRawModelEntry = {
 
 test("config: usableOnly=false → no filter (existing behavior)", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CC_OPUS, MODEL_NV_LLAMA]);
   const combosFetcher = stubCombosFetcher([]);
@@ -1012,8 +1093,9 @@ test("config: usableOnly=false → no filter (existing behavior)", async () => {
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry.models["cc/claude-opus-4-7"], "claude kept");
   assert.ok(entry.models["nvidia/llama-3-70b"], "nvidia kept (filter off)");
   assert.equal(providersFetcher.callCount(), 0, "providers fetch not called when feature off");
@@ -1021,7 +1103,7 @@ test("config: usableOnly=false → no filter (existing behavior)", async () => {
 
 test("config: usableOnly=true → drops models for non-usable providers, keeps usable + unknown", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([
     MODEL_CC_OPUS,
@@ -1061,8 +1143,9 @@ test("config: usableOnly=true → drops models for non-usable providers, keeps u
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry.models["cc/claude-opus-4-7"], "claude kept (active)");
   assert.equal(entry.models["nvidia/llama-3-70b"], undefined, "nvidia dropped (error status)");
   assert.ok(entry.models["agentrouter/synthetic-1"], "unknown prefix kept (subtract-filter)");
@@ -1071,7 +1154,7 @@ test("config: usableOnly=true → drops models for non-usable providers, keeps u
 
 test("config: usableOnly=true + providers fetch fails → soft-fail keeps everything", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CC_OPUS, MODEL_NV_LLAMA]);
   const combosFetcher = stubCombosFetcher([]);
@@ -1092,8 +1175,9 @@ test("config: usableOnly=true + providers fetch fails → soft-fail keeps everyt
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry.models["cc/claude-opus-4-7"]);
   assert.ok(entry.models["nvidia/llama-3-70b"], "soft-fail keeps both");
   assert.ok(
@@ -1104,7 +1188,7 @@ test("config: usableOnly=true + providers fetch fails → soft-fail keeps everyt
 
 test("config: diskCache hydrates stale snapshot when /v1/models throws", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = throwingModelsFetcher();
   const combosFetcher = stubCombosFetcher([]);
@@ -1141,11 +1225,15 @@ test("config: diskCache hydrates stale snapshot when /v1/models throws", async (
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
-  assert.ok(entry.models["claude-sonnet-4-6"], "stale snapshot hydrated into static block");
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
+  assert.ok(
+    entry.models["opencode-omniroute/claude-sonnet-4-6"],
+    "stale snapshot hydrated into static block"
+  );
   assert.equal(
-    entry.models["claude-sonnet-4-6"].name,
+    entry.models["opencode-omniroute/claude-sonnet-4-6"].name,
     "Claude Sonnet 4.6 (cached)",
     "stale enrichment also reused"
   );
@@ -1158,7 +1246,7 @@ test("config: diskCache hydrates stale snapshot when /v1/models throws", async (
 
 test("config: cached rawEnrichment from earlier provider hook is reused (no refetch)", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-shared", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-shared", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -1190,9 +1278,10 @@ test("config: cached rawEnrichment from earlier provider hook is reused (no refe
   await configHook(input);
   assert.equal(enrichmentFetcher.callCount(), 1, "config reused cached enrichment");
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
-  assert.equal(entry.models["claude-sonnet-4-6"].name, "Claude Sonnet 4.6");
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
+  assert.equal(entry.models["opencode-omniroute/claude-sonnet-4-6"].name, "Claude Sonnet 4.6");
 });
 
 // ─────────────────────────────────────────────────────────────────────
@@ -1203,7 +1292,7 @@ test("config: cached rawEnrichment from earlier provider hook is reused (no refe
 
 test("config: providerTag (default-on) prepends '<provider> - ' to enriched raw-model names", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE, MODEL_GEMINI]);
   const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
@@ -1238,18 +1327,25 @@ test("config: providerTag (default-on) prepends '<provider> - ' to enriched raw-
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.ok(entry);
-  assert.equal(entry.models["claude-sonnet-4-6"].name, "Claude - Claude Sonnet 4.6");
-  assert.equal(entry.models["gemini-3-flash"].name, "Gemini-cli - Gemini 3 Flash");
+  assert.equal(
+    entry.models["opencode-omniroute/claude-sonnet-4-6"].name,
+    "Claude - Claude Sonnet 4.6"
+  );
+  assert.equal(
+    entry.models["opencode-omniroute/gemini-3-flash"].name,
+    "Gemini-cli - Gemini 3 Flash"
+  );
   // Combos stay untouched — `Combo: ` prefix already conveys multi-upstream.
-  assert.equal(entry.models["combo/claude-tier"].name, "Combo: Claude Tier");
+  assert.equal(entry.models["opencode-omniroute/claude-tier"].name, "Claude Tier");
 });
 
 test("config: providerTag=false suppresses the suffix", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -1267,10 +1363,11 @@ test("config: providerTag=false suppresses the suffix", async () => {
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
   assert.equal(
-    entry.models["claude-sonnet-4-6"].name,
+    entry.models["opencode-omniroute/claude-sonnet-4-6"].name,
     "Claude Sonnet 4.6",
     "enriched name kept, provider tag suppressed"
   );
@@ -1278,7 +1375,7 @@ test("config: providerTag=false suppresses the suffix", async () => {
 
 test("config: providerTag falls back to UPPER(alias) when providerDisplayName missing", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -1299,14 +1396,15 @@ test("config: providerTag falls back to UPPER(alias) when providerDisplayName mi
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
-  assert.equal(entry.models["claude-sonnet-4-6"].name, "CC - Claude Sonnet 4.6");
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
+  assert.equal(entry.models["opencode-omniroute/claude-sonnet-4-6"].name, "CC - Claude Sonnet 4.6");
 });
 
 test("config: providerTag skipped entirely when neither providerDisplayName nor providerAlias set", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -1325,14 +1423,15 @@ test("config: providerTag skipped entirely when neither providerDisplayName nor
   const input = makeInput();
   await hook(input);
 
-  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
-  assert.equal(entry.models["claude-sonnet-4-6"].name, "Claude Sonnet 4.6");
+  const entry = (input as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
+  assert.equal(entry.models["opencode-omniroute/claude-sonnet-4-6"].name, "Claude Sonnet 4.6");
 });
 
 test("config: providerTag is idempotent — second hook call doesn't double-suffix", async () => {
   const readAuthJson = stubReadAuthJson({
-    omniroute: { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
+    "opencode-omniroute": { type: "api", key: "sk-test", baseURL: "https://or.example/v1" },
   });
   const fetcher = stubModelsFetcher([MODEL_CLAUDE]);
   const combosFetcher = stubCombosFetcher([]);
@@ -1351,14 +1450,76 @@ test("config: providerTag is idempotent — second hook call doesn't double-suff
 
   const inputA = makeInput();
   await hook(inputA);
-  const entryA = (inputA as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
-  assert.equal(entryA.models["claude-sonnet-4-6"].name, "Claude - Claude Sonnet 4.6");
+  const entryA = (inputA as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
+  assert.equal(
+    entryA.models["opencode-omniroute/claude-sonnet-4-6"].name,
+    "Claude - Claude Sonnet 4.6"
+  );
 
   // Second invocation (cache hit) — name must still be single-suffixed.
   const inputB = makeInput();
   await hook(inputB);
-  const entryB = (inputB as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider
-    .omniroute;
-  assert.equal(entryB.models["claude-sonnet-4-6"].name, "Claude - Claude Sonnet 4.6");
+  const entryB = (inputB as { provider: Record<string, OmniRouteStaticProviderEntry> }).provider[
+    "opencode-omniroute"
+  ];
+  assert.equal(
+    entryB.models["opencode-omniroute/claude-sonnet-4-6"].name,
+    "Claude - Claude Sonnet 4.6"
+  );
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// T-NN: nested combo-ref resolution in the static catalog
+// (mirrors the dynamic-catalog fix in combos.test.ts)
+// ────────────────────────────────────────────────────────────────────────────
+
+test("buildStaticProviderEntry: nested combo-ref context is the bottleneck across the graph", () => {
+  const resolved = resolveOmniRoutePluginOptions({ providerId: "omniroute" });
+  const rawModels: OmniRouteRawModelEntry[] = [
+    {
+      id: "raw-big",
+      context_length: 200_000,
+      max_output_tokens: 64_000,
+      capabilities: { tool_calling: true, reasoning: true, vision: false, temperature: true },
+      input_modalities: ["text"],
+      output_modalities: ["text"],
+    },
+    {
+      id: "raw-tiny",
+      context_length: 8_000,
+      max_output_tokens: 4_000,
+      capabilities: { tool_calling: false, reasoning: false, vision: false, temperature: true },
+      input_modalities: ["text"],
+      output_modalities: ["text"],
+    },
+  ];
+  const rawCombos: OmniRouteRawCombo[] = [
+    {
+      id: "tiny-combo",
+      name: "TinyCombo",
+      models: [{ id: "m1", kind: "model", model: "raw-tiny", weight: 100 }],
+    },
+    {
+      id: "parent",
+      name: "Parent",
+      models: [
+        { id: "p1", kind: "model", model: "raw-big", weight: 50 },
+        { id: "p2", kind: "combo-ref", comboName: "TinyCombo", weight: 50 },
+      ],
+    },
+  ];
+  const block = buildStaticProviderEntry(
+    rawModels,
+    rawCombos,
+    resolved,
+    "https://or.example/v1",
+    "sk-test"
+  );
+  // Pre-fix: Parent would advertise 200_000 (only raw-big counted).
+  // Post-fix: Parent should advertise 8_000 (TinyCombo bottleneck).
+  const parent = block.models["opencode-omniroute/parent"];
+  assert.ok(parent, "Parent combo must be in the static catalog");
+  assert.equal(parent.limit?.context, 8_000);
 });

@omniroute/opencode-plugin/tests/features.test.ts

@@ -376,7 +376,7 @@ test("provider hook: enrichment fetcher called when features.enrichment !== fals
   );
   const out = await hook.models!({} as never, { auth: apiAuth("sk") as never });
   assert.equal(called, 1, "enrichment fetcher called once");
-  const m = out["claude-sonnet-4-6"];
+  const m = out["opencode-omniroute/claude-sonnet-4-6"];
   assert.equal(m.name, "Claude Sonnet 4.6", "enrichment name overlay applied");
   assert.equal(m.cost.input, 3, "enrichment pricing applied");
   assert.equal(m.cost.output, 15);
@@ -401,7 +401,11 @@ test("provider hook: enrichment fetcher NOT called when features.enrichment:fals
   );
   const out = await hook.models!({} as never, { auth: apiAuth("sk") as never });
   assert.equal(called, 0, "enrichment fetcher NOT called when gated off");
-  assert.equal(out["claude-sonnet-4-6"].name, "claude-sonnet-4-6", "raw id preserved");
+  assert.equal(
+    out["opencode-omniroute/claude-sonnet-4-6"].name,
+    "claude-sonnet-4-6",
+    "raw id preserved"
+  );
 });
 
 test("provider hook: compression metadata fetcher NOT called by default (opt-in)", async () => {
@@ -459,7 +463,7 @@ test("provider hook: compression metadata fetcher called when opted in", async (
   );
   const out = await hook.models!({} as never, { auth: apiAuth("sk") as never });
   assert.equal(called, 1, "compression metadata fetcher called");
-  const combo = out["combo/claude-primary"];
+  const combo = out["opencode-omniroute/claude-primary"];
   assert.ok(combo, "combo entry present");
   assert.match(
     combo.name,
@@ -473,7 +477,7 @@ test("provider hook: compression metadata fetcher called when opted in", async (
 // ─────────────────────────────────────────────────────────────────────────
 
 const stubAuthJson = (apiKey: string) => async () => ({
-  omniroute: { type: "api" as const, key: apiKey },
+  "opencode-omniroute": { type: "api" as const, key: apiKey },
 });
 
 test("config hook: MCP auto-emit OFF by default (no mcp entry)", async () => {
@@ -488,7 +492,7 @@ test("config hook: MCP auto-emit OFF by default (no mcp entry)", async () => {
   );
   const input: { provider?: Record<string, unknown>; mcp?: Record<string, unknown> } = {};
   await hook(input as never);
-  assert.ok(input.provider?.omniroute, "provider block written");
+  assert.ok(input.provider?.["opencode-omniroute"], "provider block written");
   assert.equal(input.mcp, undefined, "no mcp block written");
 });
 
@@ -508,7 +512,7 @@ test("config hook: features.mcpAutoEmit:true writes mcp entry with provider apiK
   );
   const input: { provider?: Record<string, unknown>; mcp?: Record<string, unknown> } = {};
   await hook(input as never);
-  const entry = input.mcp?.omniroute as
+  const entry = input.mcp?.["opencode-omniroute"] as
     | { type: string; url: string; enabled: boolean; headers: Record<string, string> }
     | undefined;
   assert.ok(entry, "mcp entry written");
@@ -538,7 +542,7 @@ test("config hook: features.mcpToken overrides provider apiKey in mcp Bearer", a
   );
   const input: { provider?: Record<string, unknown>; mcp?: Record<string, unknown> } = {};
   await hook(input as never);
-  const entry = input.mcp?.omniroute as { headers: Record<string, string> };
+  const entry = input.mcp?.["opencode-omniroute"] as { headers: Record<string, string> };
   assert.equal(
     entry.headers.Authorization,
     "Bearer sk-mcp-narrower",
@@ -561,11 +565,11 @@ test("config hook: existing operator mcp.<providerId> wins (no overwrite)", asyn
     }
   );
   const input: { provider?: Record<string, unknown>; mcp?: Record<string, unknown> } = {
-    mcp: { omniroute: { type: "custom-user-entry", url: "https://manual.example/mcp" } },
+    mcp: { "opencode-omniroute": { type: "custom-user-entry", url: "https://manual.example/mcp" } },
   };
   await hook(input as never);
   assert.deepEqual(
-    input.mcp?.omniroute,
+    input.mcp?.["opencode-omniroute"],
     { type: "custom-user-entry", url: "https://manual.example/mcp" },
     "operator override preserved"
   );
@@ -580,7 +584,7 @@ test("config hook: features.mcpAutoEmit:true with /v1 in baseURL → strips corr
     },
     {
       readAuthJson: async () => ({
-        "omniroute-preprod": { type: "api" as const, key: "sk-preprod" },
+        "opencode-omniroute-preprod": { type: "api" as const, key: "sk-preprod" },
       }),
       fetcher: async () => SAMPLE_RAW,
       combosFetcher: async () => [],
@@ -589,7 +593,7 @@ test("config hook: features.mcpAutoEmit:true with /v1 in baseURL → strips corr
   );
   const input: { provider?: Record<string, unknown>; mcp?: Record<string, unknown> } = {};
   await hook(input as never);
-  const entry = input.mcp?.["omniroute-preprod"] as { url: string };
+  const entry = input.mcp?.["opencode-omniroute-preprod"] as { url: string };
   assert.equal(
     entry.url,
     "https://or-preprod.example.com/api/mcp/stream",

@omniroute/opencode-plugin/tests/fork-features.test.ts

@@ -0,0 +1,291 @@
+/**
+ * Tests for the 3 mrmm-fork features backported to @omniroute/opencode-plugin:
+ *
+ *   1. `normaliseFreeLabel` — free-tier model display names get a consistent
+ *      `[Free] ` prefix instead of trailing "(Free)" or ad-hoc "free" words.
+ *
+ *   2. `resolveApiBlock` — per-provider-prefix API format routing. Anthropic
+ *      prefixes (`cc/`, `claude/`, `anthropic/`, `kiro/`, `kr/`) get the
+ *      Anthropic SDK block; everything else gets OpenAI-compat.
+ *
+ *   3. `debugLog` — JSONL request/response capture, gated by
+ *      `features.debugLog` and togglable at runtime via
+ *      `debugLogEnabled/SetEnabled`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  normaliseFreeLabel,
+  resolveApiBlock,
+  DEFAULT_ANTHROPIC_PREFIXES,
+  ensureV1Suffix,
+  debugLogEnabled,
+  debugLogSetEnabled,
+  debugLogClear,
+  debugLogRead,
+  debugLogAppend,
+  createDebugLoggingFetch,
+  DebugLogEntry,
+} from "../src/index.js";
+
+// ── 1. normaliseFreeLabel ────────────────────────────────────────────────────
+
+test("normaliseFreeLabel: '(Free)' suffix becomes [Free] prefix", () => {
+  assert.equal(normaliseFreeLabel("GPT-4.1 (Free)"), "[Free] GPT-4.1");
+});
+
+test("normaliseFreeLabel: trailing ' Free' word becomes [Free] prefix", () => {
+  assert.equal(
+    normaliseFreeLabel("DeepSeek V4 Flash Free"),
+    "[Free] DeepSeek V4 Flash"
+  );
+});
+
+test("normaliseFreeLabel: trailing '-free' (hyphen) becomes [Free] prefix", () => {
+  assert.equal(normaliseFreeLabel("Llama 4 Scout-free"), "[Free] Llama 4 Scout");
+});
+
+test("normaliseFreeLabel: case-insensitive (FREE, Free, free all match)", () => {
+  assert.equal(normaliseFreeLabel("Model A FREE"), "[Free] Model A");
+  assert.equal(normaliseFreeLabel("Model A free"), "[Free] Model A");
+  assert.equal(normaliseFreeLabel("Model A Free"), "[Free] Model A");
+});
+
+test("normaliseFreeLabel: names without 'free' pass through unchanged", () => {
+  assert.equal(normaliseFreeLabel("Claude 4.7 Opus"), "Claude 4.7 Opus");
+  assert.equal(normaliseFreeLabel("GPT-5"), "GPT-5");
+});
+
+test("normaliseFreeLabel: 'free' in the middle of a name is NOT rewritten", () => {
+  // Only trailing/standalone "free" markers count; embedded "freedom" stays
+  assert.equal(
+    normaliseFreeLabel("Freedom Model"),
+    "Freedom Model"
+  );
+});
+
+test("normaliseFreeLabel: empty / whitespace-only inputs are handled", () => {
+  // Empty input returns empty; pure whitespace input passes through (no Free marker)
+  assert.equal(normaliseFreeLabel(""), "");
+  assert.equal(normaliseFreeLabel("   "), "   ");
+});
+
+// ── 2. resolveApiBlock ───────────────────────────────────────────────────────
+
+test("resolveApiBlock: cc/* models get the Anthropic SDK block (no /v1)", () => {
+  const block = resolveApiBlock("cc/claude-opus-4-7", "https://api.example.com");
+  assert.equal(block.id, "anthropic");
+  assert.equal(block.npm, "@ai-sdk/anthropic");
+  assert.equal(block.url, "https://api.example.com"); // NO /v1 suffix
+});
+
+test("resolveApiBlock: claude/*, anthropic/*, kiro/*, kr/* all route to Anthropic", () => {
+  for (const id of [
+    "claude/claude-opus-4-7",
+    "anthropic/claude-sonnet-4",
+    "kiro/claude-sonnet-4-5",
+    "kr/claude-opus-4-6",
+  ]) {
+    const block = resolveApiBlock(id, "https://api.example.com");
+    assert.equal(block.id, "anthropic", `${id} should route to Anthropic`);
+    assert.equal(block.npm, "@ai-sdk/anthropic");
+  }
+});
+
+test("resolveApiBlock: non-Anthropic models get OpenAI-compat with /v1", () => {
+  const block = resolveApiBlock("gpt-4o", "https://api.example.com");
+  assert.equal(block.id, "openai-compatible");
+  assert.equal(block.npm, "@ai-sdk/openai-compatible");
+  assert.equal(block.url, "https://api.example.com/v1");
+});
+
+test("resolveApiBlock: user can override anthropicPrefixes to add custom prefixes", () => {
+  const block = resolveApiBlock("myproxy/claude-opus", "https://api.example.com", {
+    anthropicPrefixes: ["myproxy"],
+  });
+  assert.equal(block.id, "anthropic");
+  assert.equal(block.npm, "@ai-sdk/anthropic");
+});
+
+test("resolveApiBlock: empty anthropicPrefixes forces OpenAI-compat for everything", () => {
+  const block = resolveApiBlock("cc/claude-opus", "https://api.example.com", {
+    anthropicPrefixes: [],
+  });
+  assert.equal(block.id, "openai-compatible");
+});
+
+test("resolveApiBlock: baseURL that already ends in /v1 is not double-suffixed (OpenAI path)", () => {
+  const block = resolveApiBlock("gpt-4o", "https://api.example.com/v1");
+  assert.equal(block.url, "https://api.example.com/v1"); // idempotent
+});
+
+test("resolveApiBlock: model id without '/' uses the id as prefix", () => {
+  const block = resolveApiBlock("claude-opus-4-7", "https://api.example.com");
+  // The whole id is the prefix, which doesn't match "cc"/"claude" etc.
+  // So it falls through to OpenAI-compat.
+  assert.equal(block.id, "openai-compatible");
+});
+
+test("DEFAULT_ANTHROPIC_PREFIXES: contains the canonical Anthropic aliases", () => {
+  assert.deepEqual(DEFAULT_ANTHROPIC_PREFIXES, [
+    "cc",
+    "claude",
+    "anthropic",
+    "kiro",
+    "kr",
+  ]);
+});
+
+test("ensureV1Suffix: idempotent for URLs that already end in /v1", () => {
+  assert.equal(ensureV1Suffix("https://api.example.com/v1"), "https://api.example.com/v1");
+  assert.equal(
+    ensureV1Suffix("https://api.example.com/v1/"),
+    "https://api.example.com/v1" // trailing slash is stripped
+  );
+});
+
+test("ensureV1Suffix: appends /v1 when missing", () => {
+  assert.equal(ensureV1Suffix("https://api.example.com"), "https://api.example.com/v1");
+  assert.equal(ensureV1Suffix("https://api.example.com/"), "https://api.example.com/v1");
+});
+
+// ── 3. debugLog ──────────────────────────────────────────────────────────────
+
+test("debugLog: default state is disabled", () => {
+  debugLogClear("test-provider-disabled-default");
+  assert.equal(debugLogEnabled("test-provider-disabled-default"), false);
+});
+
+test("debugLogSetEnabled + debugLogEnabled: roundtrip", () => {
+  debugLogSetEnabled("test-provider-toggle", true);
+  assert.equal(debugLogEnabled("test-provider-toggle"), true);
+  debugLogSetEnabled("test-provider-toggle", false);
+  assert.equal(debugLogEnabled("test-provider-toggle"), false);
+});
+
+test("debugLogAppend + debugLogRead: roundtrip preserves entry shape", () => {
+  const providerId = "test-provider-readroundtrip";
+  debugLogClear(providerId);
+  const entry: DebugLogEntry = {
+    reqId: "req-1",
+    providerId,
+    ts: 1700000000000,
+    url: "https://api.example.com/v1/chat",
+    method: "POST",
+    reqHeaders: { "content-type": "application/json" },
+    reqBody: { model: "gpt-4o", messages: [] },
+    resStatus: 200,
+    resHeaders: { "content-type": "application/json" },
+    resBody: { choices: [] },
+    durationMs: 42,
+  };
+  debugLogAppend(entry);
+  const read = debugLogRead(providerId, 10);
+  assert.equal(read.length, 1);
+  assert.deepEqual(read[0], entry);
+});
+
+test("createDebugLoggingFetch: passes through when disabled", async () => {
+  const providerId = "test-provider-passthrough";
+  debugLogClear(providerId);
+  debugLogSetEnabled(providerId, false);
+  const calls: unknown[] = [];
+  const inner: typeof fetch = async (input) => {
+    calls.push(input);
+    return new Response("ok", { status: 200 });
+  };
+  const wrapped = createDebugLoggingFetch(inner, providerId, false);
+  const res = await wrapped("https://api.example.com/v1/chat");
+  assert.equal(res.status, 200);
+  assert.equal(calls.length, 1);
+  // No log entry should be written when disabled
+  assert.equal(debugLogRead(providerId).length, 0);
+});
+
+test("createDebugLoggingFetch: captures request/response when enabled", async () => {
+  const providerId = "test-provider-captures";
+  debugLogClear(providerId);
+  const inner: typeof fetch = async () =>
+    new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  const wrapped = createDebugLoggingFetch(inner, providerId, true);
+  const res = await wrapped("https://api.example.com/v1/chat", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ model: "gpt-4o" }),
+  });
+  assert.equal(res.status, 200);
+  const entries = debugLogRead(providerId);
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].method, "POST");
+  assert.equal(entries[0].resStatus, 200);
+  assert.equal(entries[0].url, "https://api.example.com/v1/chat");
+  assert.deepEqual(entries[0].reqBody, { model: "gpt-4o" });
+});
+
+test("createDebugLoggingFetch: records error without crashing the wrapped fetch", async () => {
+  const providerId = "test-provider-error";
+  debugLogClear(providerId);
+  const inner: typeof fetch = async () => {
+    throw new Error("network down");
+  };
+  const wrapped = createDebugLoggingFetch(inner, providerId, true);
+  await assert.rejects(wrapped("https://api.example.com/v1/chat"), /network down/);
+  const entries = debugLogRead(providerId);
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].resStatus, null);
+  assert.equal(entries[0].error, "network down");
+});
+
+// ── Regression tests for the 3 HIGH-priority bot review fixes ───────────────
+
+test("createDebugLoggingFetch: URL instance input is captured (not 'undefined')", async () => {
+  const providerId = "test-provider-url-input";
+  debugLogClear(providerId);
+  const inner: typeof fetch = async () =>
+    new Response("ok", { status: 200 });
+  const wrapped = createDebugLoggingFetch(inner, providerId, true);
+  await wrapped(new URL("https://api.example.com/v1/chat"));
+  const entries = debugLogRead(providerId);
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].url, "https://api.example.com/v1/chat");
+  assert.notEqual(entries[0].url, undefined);
+});
+
+test("createDebugLoggingFetch: Request object input captures URL and headers", async () => {
+  const providerId = "test-provider-request-input";
+  debugLogClear(providerId);
+  const inner: typeof fetch = async () =>
+    new Response("ok", { status: 200 });
+  const wrapped = createDebugLoggingFetch(inner, providerId, true);
+  const req = new Request("https://api.example.com/v1/chat", {
+    method: "POST",
+    headers: { "x-test": "yes" },
+  });
+  await wrapped(req);
+  const entries = debugLogRead(providerId);
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].url, "https://api.example.com/v1/chat");
+  assert.equal(entries[0].reqHeaders["x-test"], "yes");
+});
+
+test("createDebugLoggingFetch: SSE response is NOT buffered (resBody is the stream marker)", async () => {
+  const providerId = "test-provider-sse";
+  debugLogClear(providerId);
+  const inner: typeof fetch = async () =>
+    new Response("data: hello\n\n", {
+      status: 200,
+      headers: { "content-type": "text/event-stream" },
+    });
+  const wrapped = createDebugLoggingFetch(inner, providerId, true);
+  const res = await wrapped("https://api.example.com/v1/stream");
+  // The response body must remain readable downstream
+  const txt = await res.text();
+  assert.equal(txt, "data: hello\n\n");
+  const entries = debugLogRead(providerId);
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].resBody, "[stream]", "SSE responses must not be buffered");
+});

@omniroute/opencode-plugin/tests/multi-instance.test.ts

@@ -38,8 +38,8 @@ test("multi-instance: two plugin invocations bind to their own providerId", asyn
     baseURL: "https://b.example/v1",
   });
 
-  assert.equal(a.auth?.provider, "omniroute-prod");
-  assert.equal(b.auth?.provider, "omniroute-preprod");
+  assert.equal(a.auth?.provider, "opencode-omniroute-prod");
+  assert.equal(b.auth?.provider, "opencode-omniroute-preprod");
 });
 
 test("multi-instance: hook objects + nested arrays are independent references", async () => {
@@ -70,8 +70,8 @@ test("multi-instance: identical opts twice still yield independent objects", asy
   assert.notEqual(first.auth, second.auth);
   assert.notEqual(first.auth?.methods, second.auth?.methods);
   // Same provider id is fine — what matters is no shared mutable state.
-  assert.equal(first.auth?.provider, "twin");
-  assert.equal(second.auth?.provider, "twin");
+  assert.equal(first.auth?.provider, "opencode-twin");
+  assert.equal(second.auth?.provider, "opencode-twin");
 });
 
 test("multi-instance: mutating instance A's auth.methods does not affect instance B", async () => {
@@ -132,5 +132,5 @@ test("multi-instance: invalid opts on one instance does not poison the other", a
     providerId: "recovered",
     baseURL: "https://ok.example/v1",
   });
-  assert.equal(ok.auth?.provider, "recovered");
+  assert.equal(ok.auth?.provider, "opencode-recovered");
 });

@omniroute/opencode-plugin/tests/provider.test.ts

@@ -75,7 +75,7 @@ const apiAuth = (key: string, baseURL?: string): unknown =>
 
 test("createOmniRouteProviderHook: default providerId is 'omniroute'", () => {
   const hook = createOmniRouteProviderHook(undefined, { combosFetcher: async () => [] });
-  assert.equal(hook.id, "omniroute");
+  assert.equal(hook.id, "opencode-omniroute");
 });
 
 test("createOmniRouteProviderHook: custom providerId binds to hook.id (multi-instance)", () => {
@@ -87,8 +87,8 @@ test("createOmniRouteProviderHook: custom providerId binds to hook.id (multi-ins
     { providerId: "omniroute-local" },
     { combosFetcher: async () => [] }
   );
-  assert.equal(a.id, "omniroute-preprod");
-  assert.equal(b.id, "omniroute-local");
+  assert.equal(a.id, "opencode-omniroute-preprod");
+  assert.equal(b.id, "opencode-omniroute-local");
 });
 
 test("models: extracts apiKey from ctx.auth (type=api) and calls fetcher with it", async () => {
@@ -101,7 +101,7 @@ test("models: extracts apiKey from ctx.auth (type=api) and calls fetcher with it
   assert.equal(fetcher.callCount(), 1);
   assert.deepEqual(fetcher.callsBy()[0], ["https://or.example.com/v1", "sk-abc"]);
   assert.equal(Object.keys(out).length, 3);
-  assert.ok(out["claude-primary"]);
+  assert.ok(out["opencode-omniroute/claude-primary"]);
 });
 
 test("models: returns {} when ctx.auth is null/undefined/wrong-type/empty-key", async () => {
@@ -152,11 +152,13 @@ test("models: maps a sample /v1/models entry to ModelV2 (sanity)", async () => {
     { fetcher, combosFetcher: async () => [] }
   );
   const out = await hook.models!({} as never, { auth: apiAuth("sk-abc") as never });
-  const claude = out["claude-primary"];
+  const claude = out["opencode-omniroute/claude-primary"];
   assert.ok(claude, "claude-primary present");
-  assert.equal(claude.id, "claude-primary");
+  // `mapRawModelToModelV2` stamps the provider prefix on the id so OC's
+  // static-catalog reader resolves `(providerID, modelID)` from the key.
+  assert.equal(claude.id, "opencode-omniroute/claude-primary");
   assert.equal(claude.name, "claude-primary");
-  assert.equal(claude.providerID, "omniroute");
+  assert.equal(claude.providerID, "opencode-omniroute");
   assert.equal(claude.api.id, "openai-compatible");
   assert.equal(claude.api.url, "https://or.example.com/v1");
   assert.equal(claude.api.npm, "@ai-sdk/openai-compatible");

@omniroute/opencode-plugin/tests/scaffold.test.ts

@@ -1,6 +1,5 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { createRequire } from "node:module";
 import {
   OmniRoutePlugin,
   OMNIROUTE_PROVIDER_KEY,
@@ -27,7 +26,7 @@ test("scaffold: default export is v1 plugin shape { id, server: OmniRoutePlugin
 
 test("resolveOmniRoutePluginOptions: defaults", () => {
   const r = resolveOmniRoutePluginOptions();
-  assert.equal(r.providerId, "omniroute");
+  assert.equal(r.providerId, "opencode-omniroute");
   assert.equal(r.displayName, "OmniRoute");
   assert.equal(r.modelCacheTtl, 300_000);
   assert.equal(r.baseURL, undefined);
@@ -35,8 +34,8 @@ test("resolveOmniRoutePluginOptions: defaults", () => {
 
 test("resolveOmniRoutePluginOptions: custom providerId derives displayName", () => {
   const r = resolveOmniRoutePluginOptions({ providerId: "omniroute-preprod" });
-  assert.equal(r.providerId, "omniroute-preprod");
-  assert.equal(r.displayName, "OmniRoute (omniroute-preprod)");
+  assert.equal(r.providerId, "opencode-omniroute-preprod");
+  assert.equal(r.displayName, "OmniRoute (opencode-omniroute-preprod)");
 });
 
 test("resolveOmniRoutePluginOptions: explicit displayName wins", () => {
@@ -63,11 +62,12 @@ test("OmniRoutePlugin: returns an empty hooks object (scaffold)", async () => {
   assert.notEqual(hooks, null);
 });
 
-test("scaffold: CJS default export resolves via require() with v1 shape", () => {
-  const require_ = createRequire(import.meta.url);
-  const cjs = require_("../dist/index.cjs");
-  // after cjsInterop:true, default export is on cjs.default
-  assert.strictEqual(typeof cjs.default, "object");
-  assert.strictEqual(cjs.default.id, "@omniroute/opencode-plugin");
-  assert.strictEqual(typeof cjs.default.server, "function");
+test("scaffold: built ESM default export resolves with the v1 plugin shape", async () => {
+  // The plugin is ESM-only now — the CJS bundle was dropped to fix the OpenCode
+  // loader (#3883), so there is no more ../dist/index.cjs. Validate that the built
+  // distributable's default export still carries the OpenCode v1 { id, server } shape.
+  const mod = await import("../dist/index.js");
+  assert.strictEqual(typeof mod.default, "object");
+  assert.strictEqual(mod.default.id, "@omniroute/opencode-plugin");
+  assert.strictEqual(typeof mod.default.server, "function");
 });

@omniroute/opencode-plugin/tsup.config.ts

@@ -2,7 +2,7 @@ import { defineConfig } from "tsup";
 
 export default defineConfig({
   entry: ["src/index.ts"],
-  format: ["esm", "cjs"],
+  format: ["esm"],
   dts: true,
   clean: true,
   sourcemap: false,
@@ -11,7 +11,7 @@ export default defineConfig({
   target: "node22",
   outDir: "dist",
   minify: false,
-  cjsInterop: true,
+  cjsInterop: false,
   // Bundle runtime deps so the .tgz / npm install is self-contained.
   // `zod` is required at runtime by the options schema and would otherwise
   // need a peer install when the plugin is loaded directly from a file path

@omniroute/opencode-provider/README.md

@@ -1,5 +1,23 @@
 # @omniroute/opencode-provider
 
+> ## ⚠️ Deprecated — use [`@omniroute/opencode-plugin`](https://www.npmjs.com/package/@omniroute/opencode-plugin) instead
+>
+> This package writes a **static** `provider.omniroute` block to `opencode.json` from a hardcoded default model list, so it **drifts behind your live OmniRoute catalog** — adding a model in OmniRoute won't show up in OpenCode until you re-run the generator, and OpenCode Desktop/Web only surfaces a subset of the static models.
+>
+> **`@omniroute/opencode-plugin`** solves this by fetching `GET /v1/models` from your OmniRoute instance at OpenCode startup, so the model list is always live (see [#3419](https://github.com/diegosouzapw/OmniRoute/issues/3419)). It is now the recommended path.
+>
+> **One-line migration** — replace the static `provider.omniroute` block in `opencode.json` with a single plugin entry:
+>
+> ```jsonc
+> // opencode.json
+> {
+>   "$schema": "https://opencode.ai/config.json",
+>   "plugin": ["@omniroute/opencode-plugin"]
+> }
+> ```
+>
+> This package is **not removed** and still works for static/offline config generation, but it is no longer actively recommended and won't track new models automatically.
+
 Helper for connecting [OpenCode](https://opencode.ai) to a running [OmniRoute](https://github.com/diegosouzapw/OmniRoute) AI gateway.
 
 The package emits a **schema-valid entry** for `opencode.json` (`https://opencode.ai/config.json`) that delegates the actual runtime to [`@ai-sdk/openai-compatible`](https://www.npmjs.com/package/@ai-sdk/openai-compatible). It does not ship any new HTTP client — OmniRoute already exposes an OpenAI-compatible surface, and OpenCode already speaks it through the AI SDK.
@@ -100,7 +118,7 @@ Exported for completeness. Strips trailing `/`, deduplicates a trailing `/v1`, a
 - `OMNIROUTE_PROVIDER_KEY` — `"omniroute"` (the key used under `provider.*`).
 - `OMNIROUTE_PROVIDER_NPM` — `"@ai-sdk/openai-compatible"` (the runtime delegate).
 - `OPENCODE_CONFIG_SCHEMA` — `"https://opencode.ai/config.json"`.
-- `OMNIROUTE_DEFAULT_OPENCODE_MODELS` — readonly list of 4 default model ids.
+- `OMNIROUTE_DEFAULT_OPENCODE_MODELS` — readonly list of default model ids.
 
 ## Custom model catalog
 
@@ -110,10 +128,10 @@ import { createOmniRouteProvider } from "@omniroute/opencode-provider";
 createOmniRouteProvider({
   baseURL: "http://localhost:20128",
   apiKey: "sk_omniroute",
-  models: ["auto", "claude-opus-4-7", "gpt-5.5"],
+  models: ["auto", "claude-opus-4-8", "gpt-5.5"],
   modelLabels: {
     auto: "Auto-Combo (recommended)",
-    "claude-opus-4-7": "Claude Opus 4.7",
+    "claude-opus-4-8": "Claude Opus 4.8",
     "gpt-5.5": "GPT-5.5",
   },
 });

@omniroute/opencode-provider/package-lock.json

@@ -19,9 +19,9 @@
       }
     },
     "node_modules/@esbuild/aix-ppc64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz",
-      "integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.1.tgz",
+      "integrity": "sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==",
       "cpu": [
         "ppc64"
       ],
@@ -36,9 +36,9 @@
       }
     },
     "node_modules/@esbuild/android-arm": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz",
-      "integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.1.tgz",
+      "integrity": "sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==",
       "cpu": [
         "arm"
       ],
@@ -53,9 +53,9 @@
       }
     },
     "node_modules/@esbuild/android-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz",
-      "integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.1.tgz",
+      "integrity": "sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==",
       "cpu": [
         "arm64"
       ],
@@ -70,9 +70,9 @@
       }
     },
     "node_modules/@esbuild/android-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.7.tgz",
-      "integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.1.tgz",
+      "integrity": "sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==",
       "cpu": [
         "x64"
       ],
@@ -87,9 +87,9 @@
       }
     },
     "node_modules/@esbuild/darwin-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.7.tgz",
-      "integrity": "sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.1.tgz",
+      "integrity": "sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==",
       "cpu": [
         "arm64"
       ],
@@ -104,9 +104,9 @@
       }
     },
     "node_modules/@esbuild/darwin-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz",
-      "integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.1.tgz",
+      "integrity": "sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==",
       "cpu": [
         "x64"
       ],
@@ -121,9 +121,9 @@
       }
     },
     "node_modules/@esbuild/freebsd-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz",
-      "integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==",
       "cpu": [
         "arm64"
       ],
@@ -138,9 +138,9 @@
       }
     },
     "node_modules/@esbuild/freebsd-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz",
-      "integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.1.tgz",
+      "integrity": "sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==",
       "cpu": [
         "x64"
       ],
@@ -155,9 +155,9 @@
       }
     },
     "node_modules/@esbuild/linux-arm": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz",
-      "integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.1.tgz",
+      "integrity": "sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==",
       "cpu": [
         "arm"
       ],
@@ -172,9 +172,9 @@
       }
     },
     "node_modules/@esbuild/linux-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz",
-      "integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.1.tgz",
+      "integrity": "sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==",
       "cpu": [
         "arm64"
       ],
@@ -189,9 +189,9 @@
       }
     },
     "node_modules/@esbuild/linux-ia32": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz",
-      "integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.1.tgz",
+      "integrity": "sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==",
       "cpu": [
         "ia32"
       ],
@@ -206,9 +206,9 @@
       }
     },
     "node_modules/@esbuild/linux-loong64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz",
-      "integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.1.tgz",
+      "integrity": "sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==",
       "cpu": [
         "loong64"
       ],
@@ -223,9 +223,9 @@
       }
     },
     "node_modules/@esbuild/linux-mips64el": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz",
-      "integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.1.tgz",
+      "integrity": "sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==",
       "cpu": [
         "mips64el"
       ],
@@ -240,9 +240,9 @@
       }
     },
     "node_modules/@esbuild/linux-ppc64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz",
-      "integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.1.tgz",
+      "integrity": "sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==",
       "cpu": [
         "ppc64"
       ],
@@ -257,9 +257,9 @@
       }
     },
     "node_modules/@esbuild/linux-riscv64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz",
-      "integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.1.tgz",
+      "integrity": "sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==",
       "cpu": [
         "riscv64"
       ],
@@ -274,9 +274,9 @@
       }
     },
     "node_modules/@esbuild/linux-s390x": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz",
-      "integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.1.tgz",
+      "integrity": "sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==",
       "cpu": [
         "s390x"
       ],
@@ -291,9 +291,9 @@
       }
     },
     "node_modules/@esbuild/linux-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz",
-      "integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.1.tgz",
+      "integrity": "sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==",
       "cpu": [
         "x64"
       ],
@@ -308,9 +308,9 @@
       }
     },
     "node_modules/@esbuild/netbsd-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz",
-      "integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==",
       "cpu": [
         "arm64"
       ],
@@ -325,9 +325,9 @@
       }
     },
     "node_modules/@esbuild/netbsd-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz",
-      "integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.1.tgz",
+      "integrity": "sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==",
       "cpu": [
         "x64"
       ],
@@ -342,9 +342,9 @@
       }
     },
     "node_modules/@esbuild/openbsd-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz",
-      "integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==",
       "cpu": [
         "arm64"
       ],
@@ -359,9 +359,9 @@
       }
     },
     "node_modules/@esbuild/openbsd-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz",
-      "integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.1.tgz",
+      "integrity": "sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==",
       "cpu": [
         "x64"
       ],
@@ -376,9 +376,9 @@
       }
     },
     "node_modules/@esbuild/openharmony-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz",
-      "integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.1.tgz",
+      "integrity": "sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==",
       "cpu": [
         "arm64"
       ],
@@ -393,9 +393,9 @@
       }
     },
     "node_modules/@esbuild/sunos-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz",
-      "integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.1.tgz",
+      "integrity": "sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==",
       "cpu": [
         "x64"
       ],
@@ -410,9 +410,9 @@
       }
     },
     "node_modules/@esbuild/win32-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz",
-      "integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.1.tgz",
+      "integrity": "sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==",
       "cpu": [
         "arm64"
       ],
@@ -427,9 +427,9 @@
       }
     },
     "node_modules/@esbuild/win32-ia32": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz",
-      "integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.1.tgz",
+      "integrity": "sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==",
       "cpu": [
         "ia32"
       ],
@@ -444,9 +444,9 @@
       }
     },
     "node_modules/@esbuild/win32-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz",
-      "integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.1.tgz",
+      "integrity": "sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==",
       "cpu": [
         "x64"
       ],
@@ -974,9 +974,9 @@
       }
     },
     "node_modules/esbuild": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz",
-      "integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.1.tgz",
+      "integrity": "sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==",
       "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
@@ -987,32 +987,32 @@
         "node": ">=18"
       },
       "optionalDependencies": {
-        "@esbuild/aix-ppc64": "0.27.7",
-        "@esbuild/android-arm": "0.27.7",
-        "@esbuild/android-arm64": "0.27.7",
-        "@esbuild/android-x64": "0.27.7",
-        "@esbuild/darwin-arm64": "0.27.7",
-        "@esbuild/darwin-x64": "0.27.7",
-        "@esbuild/freebsd-arm64": "0.27.7",
-        "@esbuild/freebsd-x64": "0.27.7",
-        "@esbuild/linux-arm": "0.27.7",
-        "@esbuild/linux-arm64": "0.27.7",
-        "@esbuild/linux-ia32": "0.27.7",
-        "@esbuild/linux-loong64": "0.27.7",
-        "@esbuild/linux-mips64el": "0.27.7",
-        "@esbuild/linux-ppc64": "0.27.7",
-        "@esbuild/linux-riscv64": "0.27.7",
-        "@esbuild/linux-s390x": "0.27.7",
-        "@esbuild/linux-x64": "0.27.7",
-        "@esbuild/netbsd-arm64": "0.27.7",
-        "@esbuild/netbsd-x64": "0.27.7",
-        "@esbuild/openbsd-arm64": "0.27.7",
-        "@esbuild/openbsd-x64": "0.27.7",
-        "@esbuild/openharmony-arm64": "0.27.7",
-        "@esbuild/sunos-x64": "0.27.7",
-        "@esbuild/win32-arm64": "0.27.7",
-        "@esbuild/win32-ia32": "0.27.7",
-        "@esbuild/win32-x64": "0.27.7"
+        "@esbuild/aix-ppc64": "0.28.1",
+        "@esbuild/android-arm": "0.28.1",
+        "@esbuild/android-arm64": "0.28.1",
+        "@esbuild/android-x64": "0.28.1",
+        "@esbuild/darwin-arm64": "0.28.1",
+        "@esbuild/darwin-x64": "0.28.1",
+        "@esbuild/freebsd-arm64": "0.28.1",
+        "@esbuild/freebsd-x64": "0.28.1",
+        "@esbuild/linux-arm": "0.28.1",
+        "@esbuild/linux-arm64": "0.28.1",
+        "@esbuild/linux-ia32": "0.28.1",
+        "@esbuild/linux-loong64": "0.28.1",
+        "@esbuild/linux-mips64el": "0.28.1",
+        "@esbuild/linux-ppc64": "0.28.1",
+        "@esbuild/linux-riscv64": "0.28.1",
+        "@esbuild/linux-s390x": "0.28.1",
+        "@esbuild/linux-x64": "0.28.1",
+        "@esbuild/netbsd-arm64": "0.28.1",
+        "@esbuild/netbsd-x64": "0.28.1",
+        "@esbuild/openbsd-arm64": "0.28.1",
+        "@esbuild/openbsd-x64": "0.28.1",
+        "@esbuild/openharmony-arm64": "0.28.1",
+        "@esbuild/sunos-x64": "0.28.1",
+        "@esbuild/win32-arm64": "0.28.1",
+        "@esbuild/win32-ia32": "0.28.1",
+        "@esbuild/win32-x64": "0.28.1"
       }
     },
     "node_modules/fdir": {
@@ -1482,490 +1482,6 @@
         "fsevents": "~2.3.3"
       }
     },
-    "node_modules/tsx/node_modules/@esbuild/aix-ppc64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.0.tgz",
-      "integrity": "sha512-lhRUCeuOyJQURhTxl4WkpFTjIsbDayJHih5kZC1giwE+MhIzAb7mEsQMqMf18rHLsrb5qI1tafG20mLxEWcWlA==",
-      "cpu": [
-        "ppc64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "aix"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/android-arm": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.0.tgz",
-      "integrity": "sha512-wqh0ByljabXLKHeWXYLqoJ5jKC4XBaw6Hk08OfMrCRd2nP2ZQ5eleDZC41XHyCNgktBGYMbqnrJKq/K/lzPMSQ==",
-      "cpu": [
-        "arm"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "android"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/android-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.0.tgz",
-      "integrity": "sha512-+WzIXQOSaGs33tLEgYPYe/yQHf0WTU0X42Jca3y8NWMbUVhp7rUnw+vAsRC/QiDrdD31IszMrZy+qwPOPjd+rw==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "android"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/android-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.0.tgz",
-      "integrity": "sha512-+VJggoaKhk2VNNqVL7f6S189UzShHC/mR9EE8rDdSkdpN0KflSwWY/gWjDrNxxisg8Fp1ZCD9jLMo4m0OUfeUA==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "android"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/darwin-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.0.tgz",
-      "integrity": "sha512-0T+A9WZm+bZ84nZBtk1ckYsOvyA3x7e2Acj1KdVfV4/2tdG4fzUp91YHx+GArWLtwqp77pBXVCPn2We7Letr0Q==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/darwin-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.0.tgz",
-      "integrity": "sha512-fyzLm/DLDl/84OCfp2f/XQ4flmORsjU7VKt8HLjvIXChJoFFOIL6pLJPH4Yhd1n1gGFF9mPwtlN5Wf82DZs+LQ==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/freebsd-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.0.tgz",
-      "integrity": "sha512-l9GeW5UZBT9k9brBYI+0WDffcRxgHQD8ShN2Ur4xWq/NFzUKm3k5lsH4PdaRgb2w7mI9u61nr2gI2mLI27Nh3Q==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "freebsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/freebsd-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.0.tgz",
-      "integrity": "sha512-BXoQai/A0wPO6Es3yFJ7APCiKGc1tdAEOgeTNy3SsB491S3aHn4S4r3e976eUnPdU+NbdtmBuLncYir2tMU9Nw==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "freebsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-arm": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.0.tgz",
-      "integrity": "sha512-CjaaREJagqJp7iTaNQjjidaNbCKYcd4IDkzbwwxtSvjI7NZm79qiHc8HqciMddQ6CKvJT6aBd8lO9kN/ZudLlw==",
-      "cpu": [
-        "arm"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.0.tgz",
-      "integrity": "sha512-RVyzfb3FWsGA55n6WY0MEIEPURL1FcbhFE6BffZEMEekfCzCIMtB5yyDcFnVbTnwk+CLAgTujmV/Lgvih56W+A==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-ia32": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.0.tgz",
-      "integrity": "sha512-KBnSTt1kxl9x70q+ydterVdl+Cn0H18ngRMRCEQfrbqdUuntQQ0LoMZv47uB97NljZFzY6HcfqEZ2SAyIUTQBQ==",
-      "cpu": [
-        "ia32"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-loong64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.0.tgz",
-      "integrity": "sha512-zpSlUce1mnxzgBADvxKXX5sl8aYQHo2ezvMNI8I0lbblJtp8V4odlm3Yzlj7gPyt3T8ReksE6bK+pT3WD+aJRg==",
-      "cpu": [
-        "loong64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-mips64el": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.0.tgz",
-      "integrity": "sha512-2jIfP6mmjkdmeTlsX/9vmdmhBmKADrWqN7zcdtHIeNSCH1SqIoNI63cYsjQR8J+wGa4Y5izRcSHSm8K3QWmk3w==",
-      "cpu": [
-        "mips64el"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-ppc64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.0.tgz",
-      "integrity": "sha512-bc0FE9wWeC0WBm49IQMPSPILRocGTQt3j5KPCA8os6VprfuJ7KD+5PzESSrJ6GmPIPJK965ZJHTUlSA6GNYEhg==",
-      "cpu": [
-        "ppc64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-riscv64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.0.tgz",
-      "integrity": "sha512-SQPZOwoTTT/HXFXQJG/vBX8sOFagGqvZyXcgLA3NhIqcBv1BJU1d46c0rGcrij2B56Z2rNiSLaZOYW5cUk7yLQ==",
-      "cpu": [
-        "riscv64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-s390x": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.0.tgz",
-      "integrity": "sha512-SCfR0HN8CEEjnYnySJTd2cw0k9OHB/YFzt5zgJEwa+wL/T/raGWYMBqwDNAC6dqFKmJYZoQBRfHjgwLHGSrn3Q==",
-      "cpu": [
-        "s390x"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/linux-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.0.tgz",
-      "integrity": "sha512-us0dSb9iFxIi8srnpl931Nvs65it/Jd2a2K3qs7fz2WfGPHqzfzZTfec7oxZJRNPXPnNYZtanmRc4AL/JwVzHQ==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/netbsd-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.0.tgz",
-      "integrity": "sha512-CR/RYotgtCKwtftMwJlUU7xCVNg3lMYZ0RzTmAHSfLCXw3NtZtNpswLEj/Kkf6kEL3Gw+BpOekRX0BYCtklhUw==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "netbsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/netbsd-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.0.tgz",
-      "integrity": "sha512-nU1yhmYutL+fQ71Kxnhg8uEOdC0pwEW9entHykTgEbna2pw2dkbFSMeqjjyHZoCmt8SBkOSvV+yNmm94aUrrqw==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "netbsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/openbsd-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.0.tgz",
-      "integrity": "sha512-cXb5vApOsRsxsEl4mcZ1XY3D4DzcoMxR/nnc4IyqYs0rTI8ZKmW6kyyg+11Z8yvgMfAEldKzP7AdP64HnSC/6g==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "openbsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/openbsd-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.0.tgz",
-      "integrity": "sha512-8wZM2qqtv9UP3mzy7HiGYNH/zjTA355mpeuA+859TyR+e+Tc08IHYpLJuMsfpDJwoLo1ikIJI8jC3GFjnRClzA==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "openbsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/openharmony-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.0.tgz",
-      "integrity": "sha512-FLGfyizszcef5C3YtoyQDACyg95+dndv79i2EekILBofh5wpCa1KuBqOWKrEHZg3zrL3t5ouE5jgr94vA+Wb2w==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "openharmony"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/sunos-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.0.tgz",
-      "integrity": "sha512-1ZgjUoEdHZZl/YlV76TSCz9Hqj9h9YmMGAgAPYd+q4SicWNX3G5GCyx9uhQWSLcbvPW8Ni7lj4gDa1T40akdlw==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "sunos"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/win32-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.0.tgz",
-      "integrity": "sha512-Q9StnDmQ/enxnpxCCLSg0oo4+34B9TdXpuyPeTedN/6+iXBJ4J+zwfQI28u/Jl40nOYAxGoNi7mFP40RUtkmUA==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/win32-ia32": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.0.tgz",
-      "integrity": "sha512-zF3ag/gfiCe6U2iczcRzSYJKH1DCI+ByzSENHlM2FcDbEeo5Zd2C86Aq0tKUYAJJ1obRP84ymxIAksZUcdztHA==",
-      "cpu": [
-        "ia32"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/@esbuild/win32-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.0.tgz",
-      "integrity": "sha512-pEl1bO9mfAmIC+tW5btTmrKaujg3zGtUmWNdCw/xs70FBjwAL3o9OEKNHvNmnyylD6ubxUERiEhdsL0xBQ9efw==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/tsx/node_modules/esbuild": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.0.tgz",
-      "integrity": "sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==",
-      "dev": true,
-      "hasInstallScript": true,
-      "license": "MIT",
-      "bin": {
-        "esbuild": "bin/esbuild"
-      },
-      "engines": {
-        "node": ">=18"
-      },
-      "optionalDependencies": {
-        "@esbuild/aix-ppc64": "0.28.0",
-        "@esbuild/android-arm": "0.28.0",
-        "@esbuild/android-arm64": "0.28.0",
-        "@esbuild/android-x64": "0.28.0",
-        "@esbuild/darwin-arm64": "0.28.0",
-        "@esbuild/darwin-x64": "0.28.0",
-        "@esbuild/freebsd-arm64": "0.28.0",
-        "@esbuild/freebsd-x64": "0.28.0",
-        "@esbuild/linux-arm": "0.28.0",
-        "@esbuild/linux-arm64": "0.28.0",
-        "@esbuild/linux-ia32": "0.28.0",
-        "@esbuild/linux-loong64": "0.28.0",
-        "@esbuild/linux-mips64el": "0.28.0",
-        "@esbuild/linux-ppc64": "0.28.0",
-        "@esbuild/linux-riscv64": "0.28.0",
-        "@esbuild/linux-s390x": "0.28.0",
-        "@esbuild/linux-x64": "0.28.0",
-        "@esbuild/netbsd-arm64": "0.28.0",
-        "@esbuild/netbsd-x64": "0.28.0",
-        "@esbuild/openbsd-arm64": "0.28.0",
-        "@esbuild/openbsd-x64": "0.28.0",
-        "@esbuild/openharmony-arm64": "0.28.0",
-        "@esbuild/sunos-x64": "0.28.0",
-        "@esbuild/win32-arm64": "0.28.0",
-        "@esbuild/win32-ia32": "0.28.0",
-        "@esbuild/win32-x64": "0.28.0"
-      }
-    },
     "node_modules/typescript": {
       "version": "5.9.3",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",

@omniroute/opencode-provider/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@omniroute/opencode-provider",
   "version": "0.1.0",
-  "description": "OpenCode provider helper for the OmniRoute AI Gateway. Generates a schema-valid provider entry for opencode.json that delegates the runtime to @ai-sdk/openai-compatible.",
+  "description": "DEPRECATED — use @omniroute/opencode-plugin instead (it fetches the live OmniRoute /v1/models catalog at startup, so models never drift). This static-config generator still works but is no longer the recommended path. OpenCode provider helper for the OmniRoute AI Gateway.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -56,5 +56,8 @@
     "tsup": "^8.5.1",
     "tsx": "^4.22.3",
     "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "esbuild": "^0.28.1"
   }
 }

@omniroute/opencode-provider/src/index.ts

@@ -46,6 +46,7 @@ export const OPENCODE_CONFIG_SCHEMA = "https://opencode.ai/config.json" as const
  * with Claude Code passthrough models (`cc/` prefix).
  */
 export const OMNIROUTE_DEFAULT_OPENCODE_MODELS = [
+  "cc/claude-opus-4-8",
   "cc/claude-opus-4-7",
   "cc/claude-sonnet-4-6",
   "cc/claude-haiku-4-5-20251001",
@@ -83,7 +84,8 @@ export interface ModelCapabilities {
  * Matches the context lengths used by OmniRoute's provider registry.
  */
 export const OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS: Record<string, number> = {
-  "cc/claude-opus-4-7": 200_000,
+  "cc/claude-opus-4-8": 1_000_000,
+  "cc/claude-opus-4-7": 1_000_000,
   "cc/claude-sonnet-4-6": 200_000,
   "cc/claude-haiku-4-5-20251001": 200_000,
   "claude-opus-4-5-thinking": 200_000,
@@ -100,6 +102,7 @@ export const OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS: Record<string, number> = {
  * model via `OmniRouteProviderOptions.modelCapabilities`.
  */
 export const OMNIROUTE_DEFAULT_MODEL_CAPABILITIES: Record<string, ModelCapabilities> = {
+  "cc/claude-opus-4-8": { attachment: true, reasoning: true, temperature: true, tool_call: true },
   "cc/claude-opus-4-7": { attachment: true, reasoning: true, temperature: true, tool_call: true },
   "cc/claude-sonnet-4-6": { attachment: true, reasoning: true, temperature: true, tool_call: true },
   "cc/claude-haiku-4-5-20251001": { attachment: true, temperature: true, tool_call: true },
@@ -126,8 +129,8 @@ export interface OmniRouteProviderOptions {
   apiKey: string;
   /** Override the display name shown in OpenCode. Default: `"OmniRoute"`. */
   displayName?: string;
-  /** Override the model catalog. Defaults to `OMNIROUTE_DEFAULT_OPENCODE_MODELS`. */
-  models?: readonly string[];
+  /** Override the model catalog. Accepts model ids (strings) or live model entries from `fetchLiveModels`. When entries carry a `contextLength`, it is used directly — no hardcoded map needed. */
+  models?: readonly (string | { id: string; contextLength?: number })[];
   /** Optional human-readable labels keyed by model id. Overridden by `modelCapabilities[id].label`. */
   modelLabels?: Record<string, string>;
   /**
@@ -136,6 +139,12 @@ export interface OmniRouteProviderOptions {
    * for custom ids the override is used verbatim.
    */
   modelCapabilities?: Record<string, ModelCapabilities>;
+  /**
+   * Optional per-model context-length overrides (tokens). Takes precedence
+   * over the static `OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS` map but is
+   * superseded by `contextLength` on live model entries passed via `models`.
+   */
+  modelContextLengths?: Record<string, string | number>;
   /**
    * Primary model for OpenCode (top-level `model` key).
    * Emitted as `"omniroute/<id>"`. When omitted the key is not written.
@@ -245,7 +254,12 @@ export function createOmniRouteProvider(options: OmniRouteProviderOptions): Open
   const models: Record<string, OpenCodeModelEntry> = {};
   const seen = new Set<string>();
   for (const raw of modelList) {
-    const id = typeof raw === "string" ? raw.trim() : "";
+    const id =
+      typeof raw === "object" && raw !== null && "id" in raw && typeof (raw as any).id === "string"
+        ? (raw as { id: string }).id.trim()
+        : typeof raw === "string"
+          ? raw.trim()
+          : "";
     if (!id || seen.has(id)) continue;
     seen.add(id);
     const defaults = OMNIROUTE_DEFAULT_MODEL_CAPABILITIES[id] ?? {};
@@ -263,10 +277,18 @@ export function createOmniRouteProvider(options: OmniRouteProviderOptions): Open
     if (typeof merged.temperature === "boolean") entry.temperature = merged.temperature;
     if (typeof merged.tool_call === "boolean") entry.tool_call = merged.tool_call;
 
-    // Include context window limit when known — OpenCode reads this to
-    // determine usable context length for compaction & overflow detection.
-    const contextLength = OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS[id];
-    if (typeof contextLength === "number" && contextLength > 0) {
+    // Context window: live model entry (from API catalog) > modelContextLengths > static defaults
+    const liveContext =
+      typeof raw === "object" && raw !== null
+        ? (raw as { contextLength?: number }).contextLength
+        : undefined;
+    const rawContextLength =
+      liveContext ??
+      options.modelContextLengths?.[id] ??
+      OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS[id];
+    const contextLength =
+      typeof rawContextLength === "string" ? parseInt(rawContextLength, 10) : rawContextLength;
+    if (typeof contextLength === "number" && !isNaN(contextLength) && contextLength > 0) {
       entry.limit = { context: contextLength };
     }
 
@@ -505,7 +527,7 @@ export interface OmniRouteLiveModel {
  * const config = buildOmniRouteOpenCodeConfig({
  *   baseURL: "http://localhost:20128",
  *   apiKey: "sk_omniroute",
- *   models: models.map((m) => m.id),
+ *   models,                    // OmniRouteLiveModel[] — contextLength auto-extracted
  *   modelLabels: Object.fromEntries(models.map((m) => [m.id, m.name])),
  * });
  * ```

@omniroute/opencode-provider/tests/index.test.ts

@@ -2,6 +2,9 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { createServer } from "node:http";
 import type { Server } from "node:http";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 
 import {
   buildOmniRouteOpenCodeConfig,
@@ -388,6 +391,7 @@ test("createOmniRouteComboConfig includes optional fields when supplied", () =>
 
 test("OMNIROUTE_DEFAULT_OPENCODE_MODELS includes cc/ prefixed models", () => {
   const defaults = [...OMNIROUTE_DEFAULT_OPENCODE_MODELS];
+  assert.ok(defaults.includes("cc/claude-opus-4-8"));
   assert.ok(
     defaults.some((m) => m.startsWith("cc/")),
     "should have cc/ prefixed models"
@@ -413,9 +417,10 @@ test("createOmniRouteProvider emits limit.context on default model entries", ()
     baseURL: "http://localhost:20128",
     apiKey: "sk_omniroute",
   });
-  const entry = provider.models["cc/claude-opus-4-7"];
+  const entry = provider.models["cc/claude-opus-4-8"];
   assert.ok(entry.limit, "model entry should have a limit field");
-  assert.equal(entry.limit!.context, 200_000);
+  assert.equal(entry.limit!.context, 1_000_000);
+  assert.equal(provider.models["cc/claude-opus-4-7"].limit!.context, 1_000_000);
 });
 
 test("createOmniRouteProvider omits limit.context for unknown model ids", () => {
@@ -428,6 +433,34 @@ test("createOmniRouteProvider omits limit.context for unknown model ids", () =>
   assert.equal(entry.limit, undefined);
 });
 
+test("createOmniRouteProvider reads contextLength from a live model entry for ids absent from the static map", () => {
+  // #3298 regression guard: the static OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS
+  // map only covers the legacy 8 Claude/Gemini ids. Before this change, any
+  // other model got `undefined` context (see the test above, string form) and
+  // OpenCode silently fell back to its 128K internal default. A live model
+  // entry carrying `contextLength` must now surface as `limit.context`.
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+    models: [{ id: "completely-unknown-model", contextLength: 262_144 }],
+  });
+  const entry = provider.models["completely-unknown-model"];
+  assert.ok(entry.limit, "a live contextLength should produce a limit field even for ids absent from the static map");
+  assert.equal(entry.limit!.context, 262_144);
+});
+
+test("createOmniRouteProvider: a live model contextLength wins over the static default map", () => {
+  // `cc/claude-opus-4-8` has a static default (1_000_000). A live entry carrying
+  // a different contextLength must take precedence (live > modelContextLengths >
+  // static defaults).
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+    models: [{ id: "cc/claude-opus-4-8", contextLength: 524_288 }],
+  });
+  assert.equal(provider.models["cc/claude-opus-4-8"].limit!.context, 524_288);
+});
+
 test("createOmniRouteProvider serialises limit.context to JSON", () => {
   const provider = createOmniRouteProvider({
     baseURL: "http://localhost:20128",
@@ -480,8 +513,8 @@ test("createOmniRouteProvider emits default capability flags inline with the mod
     baseURL: "http://localhost:20128",
     apiKey: "sk_omniroute",
   });
-  const entry = provider.models["cc/claude-opus-4-7"];
-  assert.equal(entry.name, "cc/claude-opus-4-7");
+  const entry = provider.models["cc/claude-opus-4-8"];
+  assert.equal(entry.name, "cc/claude-opus-4-8");
   assert.equal(entry.attachment, true);
   assert.equal(entry.reasoning, true);
   assert.equal(entry.temperature, true);
@@ -637,3 +670,17 @@ test("createOmniRouteModesBlock honours numeric overrides limited to OC schema",
   assert.equal(block.build.temperature, 0.7);
   assert.equal(block.build.top_p, 0.9);
 });
+
+// #3419 — soft-deprecation in favour of @omniroute/opencode-plugin. Guard the
+// deprecation notice so it can't be silently dropped while the package is kept
+// publishing (it still works; it is just no longer the recommended path).
+test("package is marked deprecated in favour of @omniroute/opencode-plugin (#3419)", () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+  assert.match(pkg.description, /DEPRECATED/);
+  assert.match(pkg.description, /@omniroute\/opencode-plugin/);
+
+  const readme = readFileSync(join(here, "..", "README.md"), "utf8");
+  assert.match(readme, /Deprecated/i);
+  assert.match(readme, /@omniroute\/opencode-plugin/);
+});

AGENTS.md

@@ -3,19 +3,53 @@
 ## Project
 
 Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support
-with **212 providers** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks,
+with **231 provider entries** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks,
 Cohere, NVIDIA, Cerebras, Pollinations, Puter, Cloudflare AI, HuggingFace, DeepInfra,
 SambaNova, Meta Llama API, Moonshot AI, AI21 Labs, Databricks, Snowflake, and many more)
-with **MCP Server** (37 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.
+with **MCP Server** (87 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.
+
+> **Live counts (v3.8.31)**: providers 231 · MCP tools 87 · MCP scopes 30 · A2A skills 6 ·
+> open-sse services 115 · routing strategies 15 · auto-combo scoring factors 9 ·
+> DB modules 83 · DB migrations 97 · base tables 17 · search providers 11 ·
+> i18n locales 42. **Refresh with `npm run check:docs-all`.**
+
+## Doc Accuracy Discipline (read before writing any doc)
+
+> **If `grep -rn "name" src/ open-sse/ bin/` returns nothing, the name does not exist. Do not document it.**
+
+The recurring failure mode in AI-generated docs is _plausible-but-unverified specifics_.
+Every claim in a `.md` file under `docs/` should be verifiable against the source.
+
+**Rules (enforced by `npm run check:fabricated-docs`):**
+
+1. **Never state an API name, endpoint, path, CLI command, or env var without grepping for it first.**
+   ```bash
+   grep -rn "theName" src/ open-sse/ bin/
+   # 0 hits → do not document
+   ```
+2. **Never write a line count, file size, migration count, provider count, or strategy count from memory.**
+   ```bash
+   wc -l <file>           # exact line count
+   ls <dir>/*.ts | wc -l  # file count
+   ```
+3. **Every code example should be copy-pasted from real usage or actually run** — not synthesized.
+   Link to a real call site (`path:line`) instead of inventing a signature.
+4. **Prefer citing real source (`file.ts:line`) over paraphrasing behavior** — verifiable and self-correcting.
+5. **A shorter doc that is 100% accurate beats a comprehensive one with fabrications.**
+   Wrong docs cost more than missing docs, because people trust and act on them.
+
+The script `scripts/check/check-fabricated-docs.mjs` extracts every route path, env var, hook
+name, function name, and file reference from `docs/**/*.md` and verifies each one against the
+codebase. Run it locally before pushing docs; it runs in CI via `npm run check:docs-all`.
 
 ## Stack
 
-- **Runtime**: Next.js 16 (App Router), Node.js `>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25`, ES Modules (`"type": "module"`)
-- **Language**: TypeScript 5.9 (`src/`) + JavaScript (`open-sse/`, `electron/`)
+- **Runtime**: Next.js 16 (App Router), Node.js `>=22.0.0 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
+- **Language**: TypeScript 6.0 (`src/`) + JavaScript (`open-sse/`, `electron/`)
 - **Database**: better-sqlite3 (SQLite) — `DATA_DIR` configurable, default `~/.omniroute/`
 - **Streaming**: SSE via `open-sse` internal workspace package
 - **Styling**: Tailwind CSS v4
-- **i18n**: next-intl with 40+ languages
+- **i18n**: next-intl with 42 locales (`src/i18n/messages/`) — refresh with `ls src/i18n/messages/*.json | wc -l`
 - **Desktop**: Electron (cross-platform: Windows, macOS, Linux)
 - **Schemas**: Zod v4 for all API / MCP input validation
 
@@ -23,19 +57,32 @@ with **MCP Server** (37 tools), **A2A v0.3 Protocol**, and **Electron desktop ap
 
 ## Build, Lint, and Test Commands
 
-| Command                             | Description                       |
-| ----------------------------------- | --------------------------------- |
-| `npm run dev`                       | Start Next.js dev server          |
-| `npm run build`                     | Production build (isolated)       |
-| `npm run start`                     | Run production build              |
-| `npm run build:cli`                 | Build CLI package                 |
-| `npm run lint`                      | ESLint on all source files        |
-| `npm run typecheck:core`            | TypeScript core type checking     |
-| `npm run typecheck:noimplicit:core` | Strict checking (no implicit any) |
-| `npm run check`                     | Run lint + test                   |
-| `npm run check:cycles`              | Check for circular dependencies   |
-| `npm run electron:dev`              | Run Electron app in dev mode      |
-| `npm run electron:build`            | Build Electron app for current OS |
+| Command                             | Description                                                        |
+| ----------------------------------- | ------------------------------------------------------------------ |
+| `npm run dev`                       | Start Next.js dev server                                           |
+| `npm run build`                     | Production build: `next build` → `.build/next/` + assemble `dist/` |
+| `npm run build:release`             | Clean rebuild + HEAD sentinel (`dist/BUILD_SHA`) — use for deploy  |
+| `npm run start`                     | Run production build                                               |
+| `npm run build:cli`                 | Build CLI package                                                  |
+| `npm run lint`                      | ESLint on all source files                                         |
+| `npm run typecheck:core`            | TypeScript core type checking                                      |
+| `npm run typecheck:noimplicit:core` | Strict checking (no implicit any)                                  |
+| `npm run check`                     | Run lint + test                                                    |
+| `npm run check:cycles`              | Check for circular dependencies                                    |
+| `npm run electron:dev`              | Run Electron app in dev mode                                       |
+| `npm run electron:build`            | Build Electron app for current OS                                  |
+
+**Build output layout:**
+
+| Directory | Purpose                                            | Gitignored |
+| --------- | -------------------------------------------------- | ---------- |
+| `src/`    | Application source (TypeScript / TSX)              | No         |
+| `.build/` | Build intermediates (`distDir = .build/next`)      | Yes        |
+| `dist/`   | Shippable bundle assembled by `assembleStandalone` | Yes        |
+
+The pipeline is a single `next build` pass — intermediates land in `.build/next/`, the
+assembled bundle in `dist/`. VPS deploys rsync `dist/` into the remote
+`/usr/lib/node_modules/omniroute/app/` directory (VPS image path is unchanged).
 
 ### Running Tests
 
@@ -131,7 +178,7 @@ Always run `prettier --write` on changed files.
 
 ### Data Layer (`src/lib/db/`)
 
-All persistence uses SQLite through **45+ domain-specific modules** in `src/lib/db/`. Top modules:
+All persistence uses SQLite through **83 domain-specific modules** in `src/lib/db/`. Top modules:
 
 - Core: `core.ts`, `migrationRunner.ts`, `encryption.ts`, `stateReset.ts`
 - Providers / catalog: `providers.ts`, `models.ts`, `providerLimits.ts`, `compressionAnalytics.ts`
@@ -141,17 +188,17 @@ All persistence uses SQLite through **45+ domain-specific modules** in `src/lib/
 - Storage: `backup.ts`, `cleanup.ts`, `jsonMigration.ts`, `healthCheck.ts`, `databaseSettings.ts`
 - Extension modules: `evals.ts`, `webhooks.ts`, `reasoningCache.ts`, `readCache.ts`, `tierConfig.ts`, `compressionCombos.ts`, `compressionScheduler.ts`, `batches.ts`, `files.ts`, `syncTokens.ts`, `proxies.ts`, `oneproxy.ts`, `upstreamProxy.ts`, `versionManager.ts`, `cliToolState.ts`, `prompts.ts`, `detailedLogs.ts`, `contextHandoffs.ts`, `compression.ts`, `stats.ts`
 
-Live count: `ls src/lib/db/*.ts | wc -l` (currently 45).
-Schema migrations live in `db/migrations/` (55 files) and run via `migrationRunner.ts`.
+Live count: `ls src/lib/db/*.ts | wc -l` (currently 83). Drift detection: `npm run check:docs-counts`.
+Schema migrations live in `db/migrations/` (**97 files** as of v3.8.24) and run via `migrationRunner.ts`.
 `src/lib/localDb.ts` is a **re-export layer only** — never add logic there.
 
 #### DB Internals
 
 - **`core.ts`**: `getDbInstance()` returns a singleton `better-sqlite3` instance with WAL
-  journaling. `SCHEMA_SQL` defines 15 base tables. Helpers: `rowToCamel`, `encryptConnectionFields`.
+  journaling. `SCHEMA_SQL` defines **17 base tables** (verify with `grep -c "CREATE TABLE" src/lib/db/core.ts` minus 1 for the bookkeeping `_omniroute_migrations` table). Helpers: `rowToCamel`, `encryptConnectionFields`.
 - **`migrationRunner.ts`**: Applies versioned SQL files from `db/migrations/` inside transactions.
   Tracks applied migrations in `_omniroute_migrations` table.
-- **Migrations**: 55 files (`001_initial_schema.sql` → `055_command_code_auth_sessions.sql`).
+- **Migrations**: 97 files (`001_initial_schema.sql` → `099_*.sql`).
   Each migration is idempotent and runs in a transaction. Live count: `ls src/lib/db/migrations/*.sql | wc -l`.
 - **Domain modules** import `getDbInstance()` from `core.ts` for all CRUD operations.
   Each module owns a specific table/set of tables (e.g., `providers.ts` → `provider_connections`,
@@ -167,19 +214,19 @@ Route → CORS preflight → Body validation (Zod) → Optional auth (extractApi
   → API key policy enforcement (enforceApiKeyPolicy) → Handler delegation (open-sse)
 ```
 
-| Route                           | Handler                   | Notes                                     |
-| ------------------------------- | ------------------------- | ----------------------------------------- |
-| `chat/completions/route.ts`     | `handleChat()`            | + prompt injection guard (clones request) |
-| `responses/route.ts`            | `handleChat()` (unified)  | Responses API format                      |
-| `embeddings/route.ts`           | `handleEmbedding()`       | Model listing + creation                  |
-| `images/generations/route.ts`   | `handleImageGeneration()` | Model listing + creation                  |
-| `audio/transcriptions/route.ts` | audio handler             | Multipart form data                       |
-| `audio/speech/route.ts`         | TTS handler               | Binary audio response                     |
-| `videos/generations/route.ts`   | video handler             | ComfyUI/SD WebUI                          |
-| `music/generations/route.ts`    | music handler             | ComfyUI workflows                         |
-| `moderations/route.ts`          | moderation handler        | Content safety                            |
-| `rerank/route.ts`               | rerank handler            | Document relevance                        |
-| `search/route.ts`               | search handler            | Web search (5 providers)                  |
+| Route                           | Handler                   | Notes                                                         |
+| ------------------------------- | ------------------------- | ------------------------------------------------------------- |
+| `chat/completions/route.ts`     | `handleChat()`            | + prompt injection guard (clones request)                     |
+| `responses/route.ts`            | `handleChat()` (unified)  | Responses API format                                          |
+| `embeddings/route.ts`           | `handleEmbedding()`       | Model listing + creation                                      |
+| `images/generations/route.ts`   | `handleImageGeneration()` | Model listing + creation                                      |
+| `audio/transcriptions/route.ts` | audio handler             | Multipart form data                                           |
+| `audio/speech/route.ts`         | TTS handler               | Binary audio response                                         |
+| `videos/generations/route.ts`   | video handler             | ComfyUI/SD WebUI                                              |
+| `music/generations/route.ts`    | music handler             | ComfyUI workflows                                             |
+| `moderations/route.ts`          | moderation handler        | Content safety                                                |
+| `rerank/route.ts`               | rerank handler            | Document relevance                                            |
+| `search/route.ts`               | search handler            | Web search (12 providers per `open-sse/handlers/search.ts:6`) |
 
 **No global Next.js middleware file** — interception is route-specific. Auth is optional
 (controlled by `REQUIRE_API_KEY` env). Prompt injection guard is unique to chat completions.
@@ -289,7 +336,8 @@ Includes request/response translators with helpers for image handling.
 
 ### Services (`open-sse/services/`)
 
-36+ service modules including: `combo.ts` (routing engine), `usage.ts`, `tokenRefresh.ts`,
+115 service modules in `open-sse/services/` (top-level only; 184 including sub-dirs like `autoCombo/` and `compression/`). Refresh: `ls open-sse/services/*.ts | wc -l`. Key modules:
+`combo.ts` (routing engine), `usage.ts`, `tokenRefresh.ts`,
 `rateLimitManager.ts`, `accountFallback.ts`, `sessionManager.ts`, `wildcardRouter.ts`,
 `autoCombo/`, `intentClassifier.ts`, `taskAwareRouter.ts`, `thinkingBudget.ts`,
 `contextManager.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`,
@@ -330,8 +378,8 @@ Modular prompt compression that runs proactively before the existing reactive co
   and iterates through targets in order until one succeeds or all fail.
 - **`resolveComboTargets()`**: Expands a combo configuration into an ordered array of
   `ResolvedComboTarget[]`, each specifying provider + model + account + credentials.
-- **Strategies** (14): priority, weighted, fill-first, round-robin, P2C, random, least-used, reset-aware (v3.8),
-  cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay.
+- **Strategies** (15): priority, weighted, fill-first, round-robin, P2C, random, least-used, reset-aware (v3.8),
+  reset-window, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay. Source: `ROUTING_STRATEGY_VALUES` in `src/shared/constants/routingStrategies.ts`.
 - Each target calls **`handleSingleModel()`** which wraps `handleChatCore()` with
   per-target error handling and circuit breaker checks.
 
@@ -343,7 +391,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/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md).
+**87 tools** total (`TOTAL_MCP_TOOL_COUNT`, `open-sse/mcp-server/server.ts`): a 33-entry base registry (`MCP_TOOLS` in `schemas/tools.ts`, bundling the core / cache / compression / 1proxy / advanced tools) **plus** standalone module sets — memory (3), skill (4), agentSkill (3), gamification (8), plugin (8), notion (6), obsidian (22). 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (30 scopes — see `OMNIROUTE_MCP_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,
@@ -361,6 +409,14 @@ list_compression_combos, compression_combo_stats.
 
 **Skill tools** (4): skills_list, skills_enable, skills_execute, skills_executions.
 
+**Agent-skill tools** (3): A2A skill discovery / invocation bridges.
+
+**Gamification tools** (8): levels, badges, leaderboard, and community-federation queries.
+
+**Plugin tools** (8): plugin marketplace listing, install/enable/disable, and runtime inspection.
+
+**Notion tools** (6) + **Obsidian tools** (22): knowledge-base read/write integrations (the largest tool family — vault search, note CRUD, WebDAV-backed file ops).
+
 #### MCP Internals
 
 - **Tool registration**: Each tool is an object with `{ name, description, inputSchema: ZodSchema,
@@ -369,7 +425,7 @@ handler: async (args) => {...} }`. Zod validates inputs before the handler fires
   `createMcpServer()` wires all tool sets; `startMcpStdio()` launches the stdio transport.
 - **Transports**: stdio (CLI `omniroute --mcp`), SSE (`/api/mcp/sse`), Streamable HTTP
   (`/api/mcp/stream`). All share the same tool/scope engine.
-- **Scopes** (10): Control which tool categories an API key can access. Enforcement happens
+- **Scopes** (30): Control which tool categories an API key can access. Enforcement happens
   before handler dispatch.
 - **Audit**: Every tool invocation is logged to SQLite (`mcp_audit` table) with tool name,
   args, success/failure, API key attribution, and timestamp.
@@ -378,7 +434,7 @@ handler: async (args) => {...} }`. Zod validates inputs before the handler fires
 
 JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup.
 Agent Card at `/.well-known/agent.json`.
-Skills (5): `smartRouting.ts`, `quotaManagement.ts`, `providerDiscovery.ts`, `costAnalysis.ts`, `healthReport.ts`.
+Skills (6): `smartRouting.ts`, `quotaManagement.ts`, `providerDiscovery.ts`, `costAnalysis.ts`, `healthReport.ts`, `listCapabilities.ts`.
 
 #### A2A Internals
 
@@ -471,7 +527,6 @@ Cloudflare Quick/Named, ngrok, Tailscale Funnel. See [`docs/ops/TUNNELS_GUIDE.md
 
 ## Subdirectory AGENTS.md Files
 
-- **[`open-sse/AGENTS.md`](open-sse/AGENTS.md)** — Streaming engine, request pipeline, handlers, and executors
 - **[`src/lib/db/AGENTS.md`](src/lib/db/AGENTS.md)** — SQLite persistence, domain modules, migrations
 - **[`open-sse/services/AGENTS.md`](open-sse/services/AGENTS.md)** — Routing engine, combo resolution, strategy selection
 
@@ -479,31 +534,33 @@ Cloudflare Quick/Named, ngrok, Tailscale Funnel. See [`docs/ops/TUNNELS_GUIDE.md
 
 For any non-trivial change, read the matching deep-dive first:
 
-| 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)                                                                    |
+| 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 (12-factor, 15 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/openapi.yaml`](docs/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)                                                                    |
+| Quality gates (35 gates, allowlist policy) | [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md)                                                          |
+| Cluster opt-in profiles (memory, bifrost)  | [`docs/architecture/cluster-decisions.md`](docs/architecture/cluster-decisions.md)                                                  |
 
 ---
 

CLAUDE.md

@@ -11,7 +11,7 @@ npm run build                  # Production build (Next.js 16 standalone)
 npm run lint                   # ESLint (0 errors expected; warnings are pre-existing)
 npm run typecheck:core         # TypeScript check (should be clean)
 npm run typecheck:noimplicit:core  # Strict check (no implicit any)
-npm run test:coverage          # Unit tests + coverage gate (75/75/75/70 — statements/lines/functions/branches)
+npm run test:coverage          # Unit tests + coverage gate (60/60/60/60 — statements/lines/functions/branches)
 npm run check                  # lint + test combined
 npm run check:cycles           # Detect circular dependencies
 ```
@@ -35,22 +35,22 @@ For full test matrix, see `CONTRIBUTING.md` → "Running Tests". For deep archit
 
 ## Project at a Glance
 
-**OmniRoute** — unified AI proxy/router. One endpoint, 160+ LLM providers, auto-fallback.
+**OmniRoute** — unified AI proxy/router. One endpoint, 231 LLM providers, auto-fallback.
 
-| Layer         | Location                | Purpose                                                            |
-| ------------- | ----------------------- | ------------------------------------------------------------------ |
-| API Routes    | `src/app/api/v1/`       | Next.js App Router — entry points                                  |
-| Handlers      | `open-sse/handlers/`    | Request processing (chat, embeddings, etc)                         |
-| Executors     | `open-sse/executors/`   | Provider-specific HTTP dispatch                                    |
-| Translators   | `open-sse/translator/`  | Format conversion (OpenAI↔Claude↔Gemini)                           |
-| Transformer   | `open-sse/transformer/` | Responses API ↔ Chat Completions                                   |
-| Services      | `open-sse/services/`    | Combo routing, rate limits, caching, etc                           |
-| Database      | `src/lib/db/`           | SQLite domain modules (45+ files, 55 migrations)                   |
-| Domain/Policy | `src/domain/`           | Policy engine, cost rules, fallback logic                          |
-| MCP Server    | `open-sse/mcp-server/`  | 37 tools (30 base + 3 memory + 4 skills), 3 transports, ~13 scopes |
-| A2A Server    | `src/lib/a2a/`          | JSON-RPC 2.0 agent protocol                                        |
-| Skills        | `src/lib/skills/`       | Extensible skill framework                                         |
-| Memory        | `src/lib/memory/`       | Persistent conversational memory                                   |
+| Layer         | Location                | Purpose                                                                                                                                |
+| ------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| API Routes    | `src/app/api/v1/`       | Next.js App Router — entry points                                                                                                      |
+| Handlers      | `open-sse/handlers/`    | Request processing (chat, embeddings, etc)                                                                                             |
+| Executors     | `open-sse/executors/`   | Provider-specific HTTP dispatch                                                                                                        |
+| Translators   | `open-sse/translator/`  | Format conversion (OpenAI↔Claude↔Gemini)                                                                                               |
+| Transformer   | `open-sse/transformer/` | Responses API ↔ Chat Completions                                                                                                       |
+| Services      | `open-sse/services/`    | Combo routing, rate limits, caching, etc                                                                                               |
+| Database      | `src/lib/db/`           | SQLite domain modules (83 files, 97 migrations)                                                                                        |
+| Domain/Policy | `src/domain/`           | Policy engine, cost rules, fallback logic                                                                                              |
+| MCP Server    | `open-sse/mcp-server/`  | 87 tools (33 base + memory/skill/notion/obsidian/gamification/plugin modules), 3 transports (stdio / SSE / Streamable HTTP), 30 scopes |
+| A2A Server    | `src/lib/a2a/`          | JSON-RPC 2.0 agent protocol                                                                                                            |
+| Skills        | `src/lib/skills/`       | Extensible skill framework                                                                                                             |
+| Memory        | `src/lib/memory/`       | Persistent conversational memory                                                                                                       |
 
 Monorepo: `src/` (Next.js 16 app), `open-sse/` (streaming engine workspace), `electron/` (desktop app), `tests/`, `bin/` (CLI entry point).
 
@@ -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/routing/AUTO-COMBO.md` for the 9-factor Auto-Combo scoring and `docs/architecture/RESILIENCE_GUIDE.md` for the 3 resilience layers.
+**Combo routing** (`open-sse/services/combo.ts`): 15 strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, reset-aware, reset-window, 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.
 
 ---
 
@@ -303,6 +303,17 @@ connection continue serving other models.
 4. Add OAuth/credentials handling if needed (`src/lib/oauth/providers/`)
 5. Tests + document in `docs/frameworks/CLOUD_AGENT.md`
 
+### Adding a New Embedded Service
+
+1. Create installer in `src/lib/services/installers/{name}.ts` modeled on `ninerouter.ts` (use `runNpm` from `installers/utils.ts` — no shell interpolation, hard rule #13).
+2. Register the service in `src/lib/services/bootstrap.ts` (add to `SERVICES[]` array and extend `buildSpawnArgsFactory()`).
+3. Add a DB seed row for the new service in `src/lib/db/migrations/` (`version_manager` table, `status='not_installed'`, `auto_start=0`).
+4. Create 7 API endpoints under `src/app/api/services/{name}/` (`_lib.ts`, `install`, `start`, `stop`, `restart`, `update`, `status`, `auto-start`). All delegate errors through `createErrorResponse()`. The shared `logs` endpoint is already wired via `[name]/logs/route.ts`.
+5. Verify `/api/services/` is in `LOCAL_ONLY_API_PREFIXES` in `src/server/authz/routeGuard.ts`; add a test asserting `isLocalOnlyPath()` returns `true` for the new prefix if you add one (hard rule #17).
+6. Add a UI tab in `src/app/(dashboard)/dashboard/providers/services/tabs/` reusing `ServiceStatusCard`, `ServiceLifecycleButtons`, `ServiceLogsPanel`.
+7. Document in `docs/frameworks/EMBEDDED-SERVICES.md` (update §1 service table + §4 API reference) and `docs/openapi.yaml`.
+8. Write tests: unit (`tests/unit/services/`), integration (`tests/integration/services/`, gated by `RUN_SERVICES_INT=1`), and update `docs/ops/RELEASE_CHECKLIST.md` smoke section.
+
 ### Adding a New Guardrail / Eval / Skill / Webhook event
 
 - Guardrail: `src/lib/guardrails/` → docs: `docs/security/GUARDRAILS.md`
@@ -316,31 +327,33 @@ connection continue serving other models.
 
 For any non-trivial change, read the matching deep-dive first:
 
-| 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`                                     |
-| Public upstream credentials (Gemini/etc.)    | `docs/security/PUBLIC_CREDS.md`                                   |
-| Error message sanitization                   | `docs/security/ERROR_SANITIZATION.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`                                   |
+| 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, 15 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`                                     |
+| Public upstream credentials (Gemini/etc.)     | `docs/security/PUBLIC_CREDS.md`                                   |
+| Error message sanitization                    | `docs/security/ERROR_SANITIZATION.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/openapi.yaml` |
+| Provider catalog (auto-generated)             | `docs/reference/PROVIDER_REFERENCE.md`                            |
+| Release flow                                  | `docs/ops/RELEASE_CHECKLIST.md`                                   |
+| Embedded services                             | `docs/frameworks/EMBEDDED-SERVICES.md`                            |
+| Quality gates (~48 scripts, allowlist policy) | `docs/architecture/QUALITY_GATES.md`                              |
 
 ---
 
@@ -354,14 +367,24 @@ For any non-trivial change, read the matching deep-dive first:
 | E2E (Playwright)        | `npm run test:e2e`                                                          |
 | Protocol E2E (MCP+A2A)  | `npm run test:protocols:e2e`                                                |
 | Ecosystem               | `npm run test:ecosystem`                                                    |
-| Coverage gate           | `npm run test:coverage` (75/75/75/70 — statements/lines/functions/branches) |
+| Coverage gate           | `npm run test:coverage` (60/60/60/60 — statements/lines/functions/branches) |
 | Coverage report         | `npm run coverage:report`                                                   |
 
 **PR rule**: If you change production code in `src/`, `open-sse/`, `electron/`, or `bin/`, you must include or update tests in the same PR.
 
 **Test layer preference**: unit first → integration (multi-module or DB state) → e2e (UI/workflow only). Encode bug reproductions as automated tests before or alongside the fix.
 
-**Copilot coverage policy**: When a PR changes production code and coverage is below 75% (statements/lines/functions) or 70% (branches), do not just report — add or update tests, rerun the coverage gate, then ask for confirmation. Include commands run, changed test files, and final coverage result in the PR report.
+**Both test runners must pass**: `npm run test:unit` (Node native — most tests) AND `npm run test:vitest` (MCP server, autoCombo, cache) cover **non-overlapping files**. Both are wired in CI (jobs `test-unit` and `test-vitest`) and must be green before merging. A PR where only one suite passes may silently ship broken MCP tools or routing regressions.
+
+**Bug fix / issue triage protocol (Hard Rule #18)**: Every fix for a reported issue must be validated by one of the following — no exceptions:
+
+1. **TDD (preferred)** — write a failing test reproducing the bug → fix it → confirm the test passes. The test becomes the permanent regression guard. Touch only the files the test proves need changing; nothing more.
+2. **Real-environment test (when TDD is not possible)** — deploy to the production VPS (`root@192.168.0.15`) and run a documented live test. Record the exact command + result in the PR description. Applies to: OAuth upstream flows, Cloudflare/WS upstream behavior, UI-only regressions, hardware-dependent behavior.
+3. "It worked locally without a test" does not count. A fix without a test or a VPS validation record is not a fix — it is a guess.
+
+Why this matters: fixing bug A while opening bug B is worse than not fixing at all. The TDD/VPS gate enforces surgical scope — you touch only what the failing test proves is broken. Examples where this paid off: #3090 (claude-web 403), #3113 (WS HTTP fallback), #3052 (heap-guard auto-calibration).
+
+**Copilot coverage policy**: When a PR changes production code and coverage is below 60% (statements/lines/functions/branches), do not just report — add or update tests, rerun the coverage gate, then ask for confirmation. Include commands run, changed test files, and final coverage result in the PR report.
 
 ---
 
@@ -381,14 +404,59 @@ git push -u origin feat/your-feature
 **Husky hooks**:
 
 - **pre-commit**: lint-staged + `check-docs-sync` + `check:any-budget:t11`
-- **pre-push**: `npm run test:unit`
+- **pre-push**: fast deterministic gates (`check:any-budget:t11` + `check:tracked-artifacts`); intentionally excludes `test:unit` (slow — covered by the CI `test-unit` job). Activated 2026-06-13 (Quality Gates Fase 6A.12).
+
+### Worktree isolation (MANDATORY for every development task)
+
+Multiple sessions/agents work this repo in parallel. The main checkout is **shared**, so a
+`git checkout`/branch switch in it silently discards another session's uncommitted work and
+yanks the branch out from under whatever else is running (incidents: 2026-06-05, 2026-06-13).
+
+**Rule: never develop on the shared main checkout. Every task gets its own git worktree on its
+own dedicated branch, and you MUST confirm the base branch with the operator before creating it.**
+
+1. **Ask first — which base branch?** Before creating anything, ask the operator (via
+   `AskUserQuestion`, unless they already told you) from which branch the new worktree/branch
+   should be cut. Do NOT assume `main` or "whatever I'm on" — the answer is usually the active
+   `release/vX.Y.Z`, but it can be another feature/release branch. Get the base explicitly.
+2. **Create an isolated worktree + branch off that base** (never reuse the main checkout).
+   **🔴 MANDATORY PATH: every worktree lives under `.claude/worktrees/` — and nowhere else.**
+   This is the single canonical location (the same dir the native `EnterWorktree` tool uses). It
+   is gitignored AND in the `tsconfig.json` / `.dockerignore` excludes, so worktrees never leak
+   into the build scope. **Never** use `.worktrees/`, repo-root, or any other path — a worktree
+   outside `.claude/worktrees/` (a) escapes the build-scope excludes and poisons `next build` (the
+   `tsconfig` `include: **/*` globs ~70× the codebase → OOM; incident 2026-06-25) and (b) scatters
+   worktrees across two dirs.
+
+   ```bash
+   BASE_BRANCH="release/vX.Y.Z"          # ← the branch the operator confirmed in step 1
+   TASK="feat/your-feature"               # feat/ fix/ refactor/ docs/ test/ chore/
+   git fetch origin "$BASE_BRANCH"
+   git worktree add ".claude/worktrees/${TASK##*/}" -b "$TASK" "origin/$BASE_BRANCH"
+   cd ".claude/worktrees/${TASK##*/}"
+   # symlink node_modules from the main checkout to skip a per-worktree npm install:
+   ln -s "$(git -C <main_checkout> rev-parse --show-toplevel)/node_modules" node_modules
+   ```
+
+   In Claude Code prefer the native `EnterWorktree` tool (it already creates worktrees under
+   `.claude/worktrees/`): create the worktree with the command above, then call `EnterWorktree`
+   with its `path`.
+
+3. **Work, commit, push, open the PR — all from inside the worktree.** Never `git checkout` a
+   different branch inside a worktree another session might share.
+4. **Tear down only your own** worktree + branch when done, from the main checkout:
+   `git worktree remove .claude/worktrees/<dir>` then `git branch -D <task>`. Never blanket-delete
+   `fix/*`/`feat/*` — other sessions keep their own; delete only the branches you created, by name.
+5. **Never touch another session's worktree, branch, or uncommitted changes.** If `git worktree
+list` shows worktrees you didn't create, leave them alone. End every session with the main
+   checkout back on the branch it started on (the active `release/vX.Y.Z`, never `main`).
 
 ---
 
 ## Environment
 
-- **Runtime**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Modules
-- **TypeScript**: 5.9+, target ES2022, module esnext, resolution bundler
+- **Runtime**: Node.js ≥22.0.0 <23 || ≥24.0.0 <27, ES Modules
+- **TypeScript**: 6.0+, target ES2022, module esnext, resolution bundler
 - **Path aliases**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
 - **Default port**: 20128 (API + dashboard on same port)
 - **Data directory**: `DATA_DIR` env var, defaults to `~/.omniroute/`
@@ -397,6 +465,33 @@ git push -u origin feat/your-feature
 
 ---
 
+## Quality Gates & Ratchets
+
+OmniRoute has **~48 quality-gate scripts** (`scripts/check/` + `scripts/quality/`) wired
+across **9 gate-running jobs** in `.github/workflows/ci.yml` (`lint`, `quality-gate`,
+`quality-extended`, `docs-sync-strict`, `i18n-ui-coverage`, `i18n`, `pr-test-policy`,
+`test-vitest`, `sonarqube`), plus the `quality.yml` fast-gates job (PR→`release/**`) and
+3 nightly workflows (`nightly-property`, `nightly-resilience`, `nightly-llm-security`;
+`nightly-mutation` once merged). Full inventory, per-job breakdown, and operational
+procedures are in [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md).
+
+**Quick reference:**
+
+- Gates in jobs `lint` + `docs-sync-strict`: pass/fail policy gates —
+  fix the violation or add an allowlist entry with a justification comment + tracking issue.
+- Gates in job `quality-gate`: ratchet — metrics (ESLint warnings, code coverage, duplication,
+  complexity) must not regress vs `quality-baseline.json`. Update via
+  `npm run quality:ratchet -- --update` when a metric genuinely improves.
+- Job `test-vitest` runs `npm run test:vitest` (MCP tools, autoCombo, cache) — blocking.
+  `test:vitest:ui` is advisory until UI component tests are triaged.
+
+**Allowlist policy (short form):** Fix the cause; use the allowlist only for pre-existing
+violations you cannot fix in the same PR. Add a comment with justification + issue number.
+Stale allowlist entries (suppressing a violation that no longer exists) will be caught by
+the stale-enforcement added in Fase 6A.3.
+
+---
+
 ## Hard Rules
 
 1. Never commit secrets or credentials
@@ -407,11 +502,30 @@ git push -u origin feat/your-feature
 6. Never silently swallow errors in SSE streams
 7. Always validate inputs with Zod schemas
 8. Always include tests when changing production code
-9. Coverage must stay ≥75% (statements, lines, functions) / ≥70% (branches). Current measured: ~82%.
+9. Coverage must not regress below the baseline frozen in `quality-baseline.json` (ratchet); absolute floor is 60% (statements/lines/functions/branches). Update the baseline via `npm run quality:ratchet -- --update` only when coverage genuinely improves. See `docs/architecture/QUALITY_GATES.md`.
 10. Never bypass Husky hooks (`--no-verify`, `--no-gpg-sign`) without explicit operator approval.
 11. Never embed public upstream OAuth client_id/secret or Firebase Web keys as string literals — always go through `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`). See `docs/security/PUBLIC_CREDS.md`.
 12. Never return raw `err.stack` / `err.message` in HTTP / SSE / executor responses — always route through `buildErrorBody()` or `sanitizeErrorMessage()` (`open-sse/utils/error.ts`). See `docs/security/ERROR_SANITIZATION.md`.
 13. Never string-interpolate external paths or runtime values into shell scripts passed to `exec()`/`spawn()` — pass via the `env` option instead. Reference: `src/mitm/cert/install.ts::updateNssDatabases`.
 14. Never dismiss a CodeQL / Secret-Scanning alert without (a) first checking the pattern docs above to see if the helper applies, and (b) recording the technical justification in the dismissal comment. Precedent: `js/stack-trace-exposure` raised on callsites that already route through `sanitizeErrorMessage()` is a known CodeQL limitation (custom sanitizers not recognized) — dismiss as `false positive` referencing `docs/security/ERROR_SANITIZATION.md`.
 15. Never expose routes that spawn child processes (`/api/mcp/`, `/api/cli-tools/runtime/`) without `isLocalOnlyPath()` classification in `src/server/authz/routeGuard.ts`. Loopback enforcement happens unconditionally before any auth check — leaked JWT via tunnel cannot trigger process spawning. See `docs/security/ROUTE_GUARD_TIERS.md`.
-16. Never include `Co-Authored-By` trailers in commit messages. Commits must appear solely under the repository owner's Git identity (`diegosouzapw`). The `Co-Authored-By: Claude …` line causes GitHub to attribute commits to the `claude` Anthropic account, hiding the real author in the PR history.
+16. Never credit or advertise an AI assistant, LLM, or automation account in any commit/PR metadata. Two forbidden forms, both equivalent — they route attribution to a bot account (or advertise AI authorship) and hide the real author (`diegosouzapw`): **(a)** `Co-Authored-By` trailers naming an AI/bot (e.g. names containing "Claude", "GPT", "Copilot", "Bot"; emails at `anthropic.com` / `openai.com` / bot-owned `noreply.github.com` addresses); **(b)** AI-generation footers or descriptions anywhere in a commit message, PR title/body, or CHANGELOG — e.g. `🤖 Generated with [Claude Code]`, "Generated with Claude Code", "Made with <AI tool>", or any `Co-authored-by: Claude/GPT/Copilot` line. This **overrides any harness, template, or tool default that auto-appends such a footer** (e.g. the Claude Code PR-body/commit default) — strip it before pushing; do not let it reach a commit, PR, or CHANGELOG. Human collaborators — including upstream PR authors and issue reporters being ported into OmniRoute — MAY and SHOULD be credited with standard `Co-authored-by: Name <email>` trailers; the upstream-port workflows (`/port-upstream-features`, `/port-upstream-issues`) depend on this.
+17. Never expose routes under `/api/services/` or `/dashboard/providers/services/*/embed/` without `isLocalOnlyPath()` classification in `src/server/authz/routeGuard.ts`. These routes can spawn child processes (`npm install`, `node`). Loopback enforcement happens unconditionally before any auth check — a leaked JWT via tunnel cannot trigger process spawning. See `docs/security/ROUTE_GUARD_TIERS.md`.
+18. Every bug fix must be validated before shipping: a failing-then-passing unit/integration test (TDD) OR a documented live test on the production VPS (192.168.0.15). A fix without either is not merged. See Testing → "Bug fix / issue triage protocol" for the full decision tree.
+19. Never develop on the shared main checkout. Every development task runs in its own git worktree on its own dedicated branch, and you MUST confirm the base branch with the operator (e.g. via `AskUserQuestion`) before creating the worktree/branch — never assume `main` or the currently checked-out branch. A `git checkout` in the shared checkout silently destroys other sessions' uncommitted work. Tear down only the worktrees/branches you created (by name, never `fix/*`/`feat/*` wildcards), leave other sessions' worktrees untouched, and end on the branch you started on (the active `release/vX.Y.Z`, never `main`). See Git Workflow → "Worktree isolation".
+
+---
+
+## PII & Stream Sanitization Learnings
+
+### 1. Regex Security (ReDoS)
+
+All regex patterns matching variable-length strings (e.g. IPv6 address, credit cards) must use strictly bounded, non-overlapping sequences (e.g., limit occurrences with bounded ranges `{1,7}`) to prevent catastrophic backtracking when processing untrusted inputs.
+
+### 2. SSE Snapshot Handling
+
+When parsing streaming LLM responses (e.g. Responses API), check if a chunk represents a final snapshot (`done` or `completed` events). Snapshot text must be sanitized directly as a standalone string (bypassing rolling delta buffers) to prevent text duplication at the end of the stream.
+
+### 3. Database Handles in Tests
+
+Ensure that any unit tests that trigger database migrations or establish SQLite connections call `resetDbInstance()` and properly clean up/close all DB handles in a `test.after(...)` hook. Failure to release database connection handles will cause Node's native test runner to hang indefinitely.

CONTRIBUTING.md

@@ -59,13 +59,40 @@ These settings are stored in the database and persist across restarts, overridin
 npm run dev
 
 # Production build
-npm run build
+npm run build    # next build → .build/next/ then assembleStandalone → dist/
 npm run start
 
+# Release build (clean rebuild + HEAD sentinel — required for deploy)
+npm run build:release   # rm -rf .build dist && build + writes dist/BUILD_SHA
+
 # Common port configuration
 PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
 ```
 
+### Build Output Layout
+
+| Directory | Contents                                                                  | Tracked |
+| --------- | ------------------------------------------------------------------------- | ------- |
+| `src/`    | Application source (TypeScript / TSX)                                     | Yes     |
+| `.build/` | Intermediates — `next build` output (gitignored, `distDir = .build/next`) | No      |
+| `dist/`   | Shippable bundle — assembled by `assembleStandalone` (gitignored)         | No      |
+
+The build pipeline is a single pass:
+
+```
+npm run build
+  └─ next build → .build/next/standalone  (Next.js output)
+  └─ assembleStandalone()                 (copies standalone + static + public + native assets)
+       └─ output: dist/                   (server.js, .next/static/, public/, node_modules/)
+```
+
+`npm run build:release` additionally cleans both directories first and writes
+`dist/BUILD_SHA` (= `git rev-parse --short HEAD`) as a deploy integrity sentinel.
+
+> **VPS deploy note:** the remote image directory `/usr/lib/node_modules/omniroute/app/`
+> is unchanged. The deploy skills rsync the contents of `dist/` into it.
+> Only the in-repo build output path moved (`app/` → `dist/`).
+
 Default URLs:
 
 - **Dashboard**: `http://localhost:20128/dashboard`
@@ -225,25 +252,32 @@ open-sse/                   # @omniroute/open-sse workspace
 electron/                   # Electron desktop app (cross-platform)
 
 tests/
-├── unit/                   # Node.js test runner (122 test files)
+├── unit/                   # Node.js test runner (1,574 test files)
 ├── integration/            # Integration tests
 ├── e2e/                    # Playwright tests
 ├── security/               # Security tests
 ├── translator/             # Translator-specific tests
 └── load/                   # Load tests
 
-docs/                       # Documentation
-├── ARCHITECTURE.md         # System architecture
-├── API_REFERENCE.md        # All endpoints
-├── USER_GUIDE.md           # Provider setup, CLI integration
-├── TROUBLESHOOTING.md      # Common issues
-├── MCP-SERVER.md           # MCP server (25 tools)
-├── A2A-SERVER.md           # A2A agent protocol
-├── AUTO-COMBO.md           # Auto-combo engine
-├── CLI-TOOLS.md            # CLI tools integration
-├── COVERAGE_PLAN.md        # Test coverage improvement plan
-├── openapi.yaml            # OpenAPI specification
-└── adr/                    # Architecture Decision Records
+docs/
+├── adr/                     # Architecture Decision Records
+├── architecture/            # System architecture & resilience
+├── comparison/              # OmniRoute vs alternatives
+├── compression/             # Compression guides & rules
+├── dev/                     # Development guides
+├── diagrams/                # Architecture diagrams
+├── frameworks/              # MCP, A2A, OpenCode, Memory, Skills
+├── guides/                  # User guide, Docker, setup, troubleshooting
+├── i18n/                    # Internationalized README translations
+├── marketing/               # Marketing materials
+├── ops/                     # Deployment, proxy, coverage, releases
+├── providers/               # Provider-specific docs
+├── reference/               # API reference, env vars, CLI tools, free tiers
+├── releases/                # Release notes
+├── routing/                 # Auto-combo engine, reasoning replay
+├── screenshots/             # Dashboard screenshots
+├── security/                # Guardrails, compliance, stealth, tokens
+└── specs/                   # Design specs
 ```
 
 ---
@@ -307,6 +341,10 @@ Write unit tests in `tests/unit/` covering at minimum:
 
 Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions.
 
+For VPS deploys, use `npm run build:release` (not `npm run build`) — it performs a clean
+rebuild, assembles the bundle into `dist/`, and writes the `dist/BUILD_SHA` sentinel.
+Then use the `/deploy-vps-*-cc` skills which rsync `dist/` to the remote `app/` directory.
+
 ---
 
 ## Getting Help