fix(ci): pack-artifact policy + maxBuffer fixes for npm publish

Cherry-pick of #3622 + #3624: aligns PACK_ARTIFACT_ROOT_ALLOWED_PATH_PREFIXES
with the v3.8.21 package.json files expansion, and increases execFileSync
maxBuffer to 64 MB to avoid ENOBUFS on npm pack --dry-run --json.

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

@@ -1,52 +0,0 @@
----
-name: capture-release-evidences-ag
-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/capture-release-evidences-cc/SKILL.md

@@ -1,52 +0,0 @@
----
-name: capture-release-evidences-cc
-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"
-}
-\```

.agents/skills/capture-release-evidences-cx/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-akamai-cc/SKILL.md

@@ -1,40 +0,0 @@
----
-name: deploy-vps-akamai-cc
-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 --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && 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/
-```

.agents/skills/deploy-vps-both-cc/SKILL.md

@@ -1,50 +0,0 @@
----
-name: deploy-vps-both-cc
-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 --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && 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 --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && 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/
-```

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

@@ -1,40 +0,0 @@
----
-name: deploy-vps-local-ag
-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 --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && 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/deploy-vps-local-cc/SKILL.md

@@ -1,40 +0,0 @@
----
-name: deploy-vps-local-cc
-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 --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && 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/deploy-vps-local-cx/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 --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && 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-ag/SKILL.md

@@ -1,427 +0,0 @@
----
-name: generate-release-ag
-description: Create a new release, bump version up to the .999 patch threshold, generate a complete CHANGELOG (with PR co-authors + every commit since the last tag), and manage Pull Requests
----
-
-# Generate Release Workflow
-
-Bump version, build a **complete CHANGELOG** from every commit since the last tag (with PR back-reference and contributor attribution), 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 1000, bump to `3.(x+1).0` — e.g. `3.8.999` → `3.9.0`.
-
-> **🔴 INTEGRATION BRANCH RULE**: The `release/vX.Y.Z` branch is the **integration target** for the entire release cycle. Bug fixes and feature implementations land here **via per-issue PRs from short-lived `fix/<ISSUE>-<short>` or `feat/<ISSUE>-<short>` worktrees** (see `/resolve-issues`, `/implement-features`). Contributor PRs from `/review-prs` likewise merge into this branch. The release branch is then merged to `main` via a single release PR at the end of the cycle.
-
----
-
-## ⚠️ Four-Phase Flow
-
-```
-Phase 0 → security audit (npm + CodeQL + Dependabot)
-Phase 1 → bump → full quality gate → changelog from commits → commit → push → open PR
-  ↕  🛑 STOP: notify user, wait for PR merge
-Phase 2 → deploy main to Local VPS for homologation
-  ↕  🛑 STOP: notify user, wait for OK
-Phase 3 → tag → GitHub release → Docker → npm → Akamai
-Phase 4 → monitor CI pipelines and validate artifacts
-```
-
-**NEVER push directly to main or create tags before the user confirms the PR.**
-
----
-
-## Phase 0: Security Verification (MANDATORY)
-
-```bash
-# 1. Local dependency audit
-npm audit --production --audit-level=high
-
-# 2. GitHub CodeQL alerts (open + high severity)
-gh api '/repos/diegosouzapw/OmniRoute/code-scanning/alerts?state=open&severity=high' \
-  --jq '.[] | {rule: .rule.id, path: .most_recent_instance.location.path, msg: .most_recent_instance.message.text}' \
-  2>/dev/null || echo "(no CodeQL access or no alerts)"
-
-# 3. Dependabot alerts (open + high/critical)
-gh api '/repos/diegosouzapw/OmniRoute/dependabot/alerts?state=open' \
-  --jq '.[] | select(.security_advisory.severity == "high" or .security_advisory.severity == "critical") | {pkg: .dependency.package.name, sev: .security_advisory.severity, summary: .security_advisory.summary}' \
-  2>/dev/null || echo "(no Dependabot access or no alerts)"
-```
-
-Fix or justify (per Hard Rule #14) any `high`/`critical` findings before proceeding.
-
----
-
-## Phase 1: Pre-Merge
-
-### 1. Create or confirm release branch
-
-```bash
-# To create a new release branch (MUST always be created from main):
-git checkout main
-git pull origin main
-git checkout -b release/v3.9.0
-
-# If continuing the current cycle, just verify:
-git branch --show-current
-```
-
-### 2. Determine and sync version
-
-```bash
-grep '"version"' package.json
-```
-
-> **🔴 BRANCH-VERSION PARITY GATE**:
-
-```bash
-BRANCH=$(git branch --show-current)
-BRANCH_VER=${BRANCH#release/v}
-PKG_VER=$(node -p "require('./package.json').version")
-
-if [[ "$BRANCH" != release/v* ]]; then
-  echo "❌ Not on a release/v* branch (current: $BRANCH). Aborting."; exit 1
-fi
-
-echo "Branch target: $BRANCH_VER"
-echo "package.json:  $PKG_VER"
-```
-
-> **⚠️ ATOMIC COMMIT RULE** — bump and feature/fix code MUST land in the same commit so that `git show vX.Y.Z` always contains both. NEVER commit features first and bump in a separate commit.
-
-```bash
-npm version patch --no-git-tag-version
-```
-
-### 3. Regenerate lock file (REQUIRED after version bump)
-
-```bash
-npm install
-```
-
-### 4. Build CHANGELOG from EVERY commit since the last tag
-
-> **🎯 Goal**: produce a complete CHANGELOG section — emoji-grouped sections, PR back-reference, and `— thanks @user` attribution. Nothing must slip through.
-
-> **🔴 NO MIXUPS RULE**: do not mix backlog of the previous version. The new section must contain ONLY commits whose merge/landing happened after the previous tag.
-
-#### 4a. Collect raw commit log since last tag
-
-```bash
-LAST_TAG=$(git describe --tags --abbrev=0)
-NEW_VERSION=$(node -p "require('./package.json').version")
-TODAY=$(date -u +%F)
-echo "Range: $LAST_TAG..HEAD  →  v$NEW_VERSION ($TODAY)"
-
-git log --no-merges "$LAST_TAG..HEAD" --pretty=format:'%h %s' > /tmp/release_commits.txt
-wc -l /tmp/release_commits.txt
-
-git log --merges "$LAST_TAG..HEAD" --pretty=format:'%h %s%n  author=%an <%ae>' > /tmp/release_merges.txt
-
-git log "$LAST_TAG..HEAD" --pretty=format:'---%n%h | %s%n  author=%an <%ae>%n  body=%b' > /tmp/release_detailed.txt
-```
-
-#### 4b. Enrich with PR metadata + co-authors
-
-```bash
-grep -oE '#[0-9]+' /tmp/release_commits.txt | sort -u > /tmp/release_prs.txt
-
-> /tmp/release_pr_meta.json
-while read -r PR; do
-  N=${PR#\#}
-  gh pr view "$N" --repo diegosouzapw/OmniRoute \
-    --json number,title,author,mergeCommit,body \
-    >> /tmp/release_pr_meta.json 2>/dev/null || echo "(skip $PR — not found)"
-  echo "" >> /tmp/release_pr_meta.json
-done < /tmp/release_prs.txt
-```
-
-#### 4c. Assemble the new CHANGELOG section
-
-Using `/tmp/release_commits.txt` + `/tmp/release_pr_meta.json` + `/tmp/release_detailed.txt`, build a new entry that:
-
-1. **Covers every commit** — read the full list and group by Conventional Commit type. A commit is "covered" iff it appears (or is intentionally rolled-up) in the new section.
-2. **Groups using these section headers**:
-   - `### ✨ New Features` — `feat(*)`
-   - `### 🔧 Bug Fixes` — `fix(*)`
-   - `### 📝 Maintenance` — `chore(*)`, `refactor(*)`, `docs(*)`, `test(*)`, `ci(*)`, `build(*)`
-   - `### 🔒 Security` — security-flagged commits (only if any)
-3. **Entry format**:
-   ```
-   - **type(scope):** human-friendly description — extra context if useful. ([#PR](https://github.com/diegosouzapw/OmniRoute/pull/PR) — thanks @author / @coauthor1 / @coauthor2)
-   ```
-   - No PR referenced (direct commit on release branch): `(thanks @author)`.
-   - PR closed an external contributor's PR via cherry-pick or re-implementation: attribute BOTH (`thanks @originalAuthor / @diegosouzapw`).
-   - **Co-authors** extracted from merge commit body and from PR participants who supplied commits.
-4. **Coverage check** — diff the section against `/tmp/release_commits.txt`. Any unlisted commit must either be explicitly added or consolidated under a roll-up bullet. Do NOT silently drop commits.
-
-Layout in `CHANGELOG.md` (right below `## [Unreleased]`):
-
-```markdown
-## [Unreleased]
-
----
-
-## [3.9.0] — 2026-05-27
-
-### ✨ New Features
-
-- **feat(scope):** description ([#1234](https://github.com/diegosouzapw/OmniRoute/pull/1234) — thanks @author)
-
-### 🔧 Bug Fixes
-
-- **fix(scope):** description ([#1235](https://github.com/diegosouzapw/OmniRoute/pull/1235) — thanks @author / @diegosouzapw)
-
-### 📝 Maintenance
-
-- **chore(scope):** description (thanks @diegosouzapw)
-
----
-
-## [3.8.999] — 2026-05-20
-```
-
-#### 4d. Coverage assertion
-
-```bash
-NEW_VERSION=$(node -p "require('./package.json').version")
-COMMITS=$(wc -l < /tmp/release_commits.txt)
-BULLETS=$(awk "/^## \\[$NEW_VERSION\\]/{flag=1;next} /^## \\[/{flag=0} flag" CHANGELOG.md | grep -c '^- ')
-
-echo "Commits in range: $COMMITS"
-echo "Changelog bullets: $BULLETS"
-if [ "$BULLETS" -lt $(( COMMITS / 3 )) ]; then
-  echo "⚠️  Bullet count looks low (< commits/3). Re-review /tmp/release_commits.txt for missed entries."
-fi
-```
-
-### 5. Sync versioned files ⚠️ MANDATORY
-
-```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
-
-npm install
-```
-
-### 6. Sync README.md and i18n docs
-
-No `/update-docs` workflow exists (deprecated in v3.8). Apply manually OR via parallel agents:
-
-1. Apply the substantive change to `README.md` first (feature table row + "What's new in vX.Y.Z" section).
-2. Capture the diff: `git diff README.md > /tmp/readme.patch`.
-3. Dispatch 5-10 parallel agents, each handling a slice of the 40 `docs/i18n/*/README.md`, translating the diff into the target language.
-4. Update `docs/<AREA>.md` if architecture/counts changed.
-5. Validate: `npm run check:docs-sync && npm run check:docs-all`.
-
-### 7. Full quality gate (MANDATORY — replaces the old `npm test`)
-
-> **Precedent**: v3.8.2 landed with 49 broken tests because only `npm test` was running. Lint + typecheck + cycles caught zero of those regressions.
-
-```bash
-set -e
-npm run lint
-npm run typecheck:core
-npm run check:cycles
-npm run check:docs-all
-npm test
-```
-
-All five must pass before opening the PR.
-
-### 8. Stage, commit, and push (atomic — bump + features + changelog + i18n in ONE commit)
-
-```bash
-VERSION=$(node -p "require('./package.json').version")
-git add -A
-git commit -m "chore(release): v$VERSION — $(date -u +%F)"
-git push origin "release/v$VERSION"
-```
-
-> **NEVER** include `Co-Authored-By:` trailers in the release commit (Hard Rule #16). Attribution lives inside the CHANGELOG entries.
-
-### 9. Open PR to main
-
-```bash
-VERSION=$(node -p "require('./package.json').version")
-
-awk "/^## \\[$VERSION\\]/{flag=1; print; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md > /tmp/changelog_body.txt
-
-{
-  echo ""
-  echo "---"
-  echo ""
-  echo "### Quality Gate"
-  echo "- lint: pass"
-  echo "- typecheck:core: pass"
-  echo "- check:cycles: pass"
-  echo "- check:docs-all: pass"
-  echo "- tests: pass"
-  echo ""
-  echo "### Coverage of commits since previous tag"
-  LAST_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "(no previous tag)")
-  COMMITS=$(git rev-list --no-merges "$LAST_TAG..HEAD" | wc -l)
-  echo "- Range: \`$LAST_TAG..HEAD\`"
-  echo "- Commits inspected: $COMMITS"
-  echo ""
-  echo "### ⚠️ After merging: run Phase 2 (Local VPS homologation) before tagging."
-} >> /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
-
-Present the report and stop. Provide:
-
-- PR URL
-- Summary of changes (top 5 from CHANGELOG)
-- Quality gate results
-- `git diff --stat $LAST_TAG..HEAD`
-- Coverage count vs commits-in-range
-
-**DO NOT proceed to Phase 2 until the user confirms.**
-
----
-
-## Phase 2: Post-Merge Validation (Local VPS)
-
-> Run only AFTER the user has merged the PR into `main` and all CI jobs pass.
-
-### 11. Deploy `main` to the Local VPS
-
-Delegate to the `deploy-vps-local-ag` workflow (single source of truth — do NOT inline SCP/SSH here):
-
-```
-/deploy-vps-local-ag
-```
-
-### 12. 🛑 STOP — Notify user & await final OK
-
-Provide smoke-test checklist:
-
-- [ ] `GET /` returns 200
-- [ ] Dashboard login works (`/dashboard`)
-- [ ] `/v1/chat/completions` with default provider returns a stream
-- [ ] No critical errors in `pm2 logs omniroute --lines 100`
-- [ ] Any release-specific UI features are reachable
-
-Wait for user **OK** before Phase 3.
-
----
-
-## Phase 3: Official Launch
-
-### 13. Create git tag and GitHub Release
-
-```bash
-git checkout main
-git pull origin main
-VERSION=$(node -p "require('./package.json').version")
-
-NOTES=$(awk "/^## \\[$VERSION\\]/{flag=1; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
-[ -z "$NOTES" ] && NOTES="OmniRoute v$VERSION Release"
-
-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 / verify Docker Hub build
-
-```bash
-gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 3
-gh run watch --repo diegosouzapw/OmniRoute
-```
-
-### 15. Publish to npm (usually CI)
-
-```bash
-npm publish
-npm info omniroute version
-```
-
-### 16. Deploy to Akamai VPS (Production)
-
-Delegate to `deploy-vps-akamai-ag` workflow if available, or run the inline equivalent of `deploy-vps-local-ag` against `69.164.221.35`. Do NOT duplicate the procedure here.
-
-### 17. Rollback playbook (use only if Phase 3 fails after tag push)
-
-```bash
-VERSION=$(node -p "require('./package.json').version")
-PREV=$(git describe --tags --abbrev=0 "v$VERSION^")
-
-gh release edit "v$VERSION" --repo diegosouzapw/OmniRoute --prerelease
-git checkout "$PREV" && /deploy-vps-akamai-ag
-npm deprecate "omniroute@$VERSION" "broken release — use $PREV"
-```
-
----
-
-## Phase 4: Release Monitoring & Artifact Validation
-
-### 18. Monitor CI pipelines
-
-```bash
-gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 1
-gh run list --repo diegosouzapw/OmniRoute --workflow electron-release.yml --limit 1
-gh run watch <RUN_ID>
-
-npm info omniroute version
-```
-
-### 19. Handle failures
-
-```bash
-gh run view <RUN_ID> --log-failed
-VERSION=$(node -p "require('./package.json').version")
-gh workflow run <workflow.yml> --repo diegosouzapw/OmniRoute --ref "v$VERSION"
-```
-
-### 20. Preserve release branch
-
-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` first.
-- 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 the wrong account.
-- Deploy procedures live in dedicated workflows (`deploy-vps-local-ag`, `deploy-vps-akamai-ag` if present). Never inline SCP/SSH commands here.
-
-## 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              |
-| Coverage gate fails (statements/lines < 75% or branches < 70%)            | Production code changed without tests                              | Add tests, re-run `npm run test:coverage` (see CLAUDE.md hard rule #9) |

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

@@ -1,513 +0,0 @@
----
-name: generate-release-cc
-description: Create a new release, bump version up to the .999 patch threshold, generate a complete CHANGELOG (with PR co-authors + every commit since the last tag), and manage Pull Requests
----
-
-# Generate Release Workflow
-
-Bump version, build a **complete CHANGELOG** from every commit since the last tag (with PR back-reference and contributor attribution), 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 1000, bump to `3.(x+1).0` — e.g. `3.8.999` → `3.9.0`.
-
-> **🔴 INTEGRATION BRANCH RULE**: The `release/vX.Y.Z` branch is the **integration target** for the entire release cycle. Bug fixes and feature implementations land here **via per-issue PRs from short-lived `fix/<ISSUE>-<short>` or `feat/<ISSUE>-<short>` worktrees** (see `/resolve-issues`, `/implement-features`). Contributor PRs from `/review-prs` likewise merge into this branch. The release branch is then merged to `main` via a single release PR at the end of the cycle.
-
----
-
-## ⚠️ Four-Phase Flow
-
-```
-Phase 0 → security audit (npm + CodeQL + Dependabot)
-Phase 1 → bump → full quality gate → changelog from commits → commit → push → open PR
-  ↕  🛑 STOP: notify user, wait for PR merge
-Phase 2 → deploy main to Local VPS for homologation
-  ↕  🛑 STOP: notify user, wait for OK
-Phase 3 → tag → GitHub release → Docker → npm → Akamai
-Phase 4 → monitor CI pipelines and validate artifacts
-```
-
-**NEVER push directly to main or create tags before the user confirms the PR.**
-
----
-
-## Phase 0: Security Verification (MANDATORY)
-
-Before creating the release, ensure the codebase and supply chain are clean.
-
-```bash
-# 1. Local dependency audit
-npm audit --production --audit-level=high
-
-# 2. GitHub CodeQL alerts (open + high severity)
-gh api '/repos/diegosouzapw/OmniRoute/code-scanning/alerts?state=open&severity=high' \
-  --jq '.[] | {rule: .rule.id, path: .most_recent_instance.location.path, msg: .most_recent_instance.message.text}' \
-  2>/dev/null || echo "(no CodeQL access or no alerts)"
-
-# 3. Dependabot alerts (open + high/critical)
-gh api '/repos/diegosouzapw/OmniRoute/dependabot/alerts?state=open' \
-  --jq '.[] | select(.security_advisory.severity == "high" or .security_advisory.severity == "critical") | {pkg: .dependency.package.name, sev: .security_advisory.severity, summary: .security_advisory.summary}' \
-  2>/dev/null || echo "(no Dependabot access or no alerts)"
-```
-
-Fix or justify (with `vulnerability-scanner` skill or dismissal comment per Hard Rule #14) any `high`/`critical` findings before proceeding.
-
----
-
-## Phase 1: Pre-Merge
-
-### 1. Create or confirm release branch
-
-```bash
-# To create a new release branch (MUST always be created from main):
-git checkout main
-git pull origin main
-git checkout -b release/v3.9.0
-
-# If continuing the current cycle, just verify:
-git branch --show-current
-```
-
-### 2. Determine and sync version
-
-```bash
-grep '"version"' package.json
-```
-
-> **🔴 BRANCH-VERSION PARITY GATE** — auto-checked before any work:
-
-// turbo
-
-```bash
-BRANCH=$(git branch --show-current)
-BRANCH_VER=${BRANCH#release/v}
-PKG_VER=$(node -p "require('./package.json').version")
-
-if [[ "$BRANCH" != release/v* ]]; then
-  echo "❌ Not on a release/v* branch (current: $BRANCH). Aborting."; exit 1
-fi
-
-# Allow first-bump scenario (branch declares a not-yet-bumped target)
-echo "Branch target: $BRANCH_VER"
-echo "package.json:  $PKG_VER"
-```
-
-> **⚠️ ATOMIC COMMIT RULE** — bump and feature/fix code MUST land in the same commit so that `git show vX.Y.Z` always contains both.
->
-> **CORRECT order**: bump → (or already-staged changes) → single commit.
-> **NEVER**: commit features first, then bump in a separate commit.
-
-```bash
-npm version patch --no-git-tag-version
-```
-
-### 3. Regenerate lock file (REQUIRED after version bump)
-
-```bash
-npm install
-```
-
-Skipping this causes `@swc/helpers` lock mismatch and CI failures.
-
-### 4. Build CHANGELOG from EVERY commit since the last tag
-
-> **🎯 Goal**: produce a complete CHANGELOG section following the format of PR #2617 — emoji-grouped sections, PR back-reference, and `— thanks @user` attribution. Nothing must slip through.
-
-> **🔴 NO MIXUPS RULE**: do not mix backlog of the previous version. The new section must contain ONLY commits whose merge/landing happened after the previous tag.
-
-#### 4a. Collect raw commit log since last tag
-
-// turbo
-
-```bash
-LAST_TAG=$(git describe --tags --abbrev=0)
-NEW_VERSION=$(node -p "require('./package.json').version")
-TODAY=$(date -u +%F)
-echo "Range: $LAST_TAG..HEAD  →  v$NEW_VERSION ($TODAY)"
-
-# Full commit list (oneline)
-git log --no-merges "$LAST_TAG..HEAD" --pretty=format:'%h %s' > /tmp/release_commits.txt
-wc -l /tmp/release_commits.txt
-
-# Merge commits (preserve PR numbers + authors)
-git log --merges "$LAST_TAG..HEAD" --pretty=format:'%h %s%n  author=%an <%ae>' > /tmp/release_merges.txt
-
-# Per-commit detailed list (PR refs, co-authors, body)
-git log "$LAST_TAG..HEAD" --pretty=format:'---%n%h | %s%n  author=%an <%ae>%n  body=%b' > /tmp/release_detailed.txt
-```
-
-#### 4b. Enrich with PR metadata + co-authors
-
-For each commit referencing a PR (e.g. `(#2617)` or merge commit `Merge pull request #N`), fetch the PR author and any additional contributors so the entry follows the model below.
-
-// turbo
-
-```bash
-# Extract all PR numbers referenced in the range
-grep -oE '#[0-9]+' /tmp/release_commits.txt | sort -u > /tmp/release_prs.txt
-echo "PRs in range:"; cat /tmp/release_prs.txt
-
-# Fetch author + co-author info for every PR
-> /tmp/release_pr_meta.json
-while read -r PR; do
-  N=${PR#\#}
-  gh pr view "$N" --repo diegosouzapw/OmniRoute \
-    --json number,title,author,mergeCommit,body \
-    >> /tmp/release_pr_meta.json 2>/dev/null || echo "(skip $PR — not found)"
-  echo "" >> /tmp/release_pr_meta.json
-done < /tmp/release_prs.txt
-```
-
-#### 4c. Assemble the new CHANGELOG section
-
-Using `/tmp/release_commits.txt` + `/tmp/release_pr_meta.json` + `/tmp/release_detailed.txt`, build a new entry that:
-
-1. **Covers every commit** — read the full list and group by Conventional Commit type. A commit is "covered" iff it appears (or is intentionally rolled-up) in the new section.
-2. **Groups using these section headers (model from PR #2617)**:
-   - `### ✨ New Features` — `feat(*)`
-   - `### 🔧 Bug Fixes` — `fix(*)`
-   - `### 📝 Maintenance` — `chore(*)`, `refactor(*)`, `docs(*)`, `test(*)`, `ci(*)`, `build(*)`
-   - `### 🔒 Security` — security-flagged commits (only if any)
-3. **Entry format**:
-   ```
-   - **type(scope):** human-friendly description — extra context if useful. ([#PR](https://github.com/diegosouzapw/OmniRoute/pull/PR) — thanks @author / @coauthor1 / @coauthor2)
-   ```
-   - When **no PR** is referenced (direct commit on release branch): `(thanks @author)`.
-   - When the PR closed an external contributor's PR via cherry-pick or re-implementation, attribute BOTH the original author AND the implementer: `thanks @originalAuthor / @diegosouzapw`.
-   - **Co-authors** must be extracted from the merge commit body (`Co-Authored-By:` lines that pre-date Hard Rule #16) and from PR participants who supplied commits.
-4. **Coverage check** — after drafting, diff the section against `/tmp/release_commits.txt`. Any unlisted commit must either be explicitly added or consolidated under a roll-up bullet (e.g. "various lint and test alignments"). Do NOT silently drop commits.
-
-Place the new section in `CHANGELOG.md` right below `## [Unreleased]`, separated by `---`:
-
-```markdown
-## [Unreleased]
-
----
-
-## [3.9.0] — 2026-05-27
-
-### ✨ New Features
-
-- **feat(scope):** description ([#1234](https://github.com/diegosouzapw/OmniRoute/pull/1234) — thanks @author)
-- ...
-
-### 🔧 Bug Fixes
-
-- **fix(scope):** description ([#1235](https://github.com/diegosouzapw/OmniRoute/pull/1235) — thanks @author / @diegosouzapw)
-- ...
-
-### 📝 Maintenance
-
-- **chore(scope):** description (thanks @diegosouzapw)
-- ...
-
----
-
-## [3.8.999] — 2026-05-20
-```
-
-#### 4d. Coverage assertion
-
-// turbo
-
-```bash
-NEW_VERSION=$(node -p "require('./package.json').version")
-
-# Count commits in range
-COMMITS=$(wc -l < /tmp/release_commits.txt)
-
-# Count bullets under the new section
-BULLETS=$(awk "/^## \\[$NEW_VERSION\\]/{flag=1;next} /^## \\[/{flag=0} flag" CHANGELOG.md | grep -c '^- ')
-
-echo "Commits in range: $COMMITS"
-echo "Changelog bullets: $BULLETS"
-if [ "$BULLETS" -lt $(( COMMITS / 3 )) ]; then
-  echo "⚠️  Bullet count looks low (< commits/3). Re-review /tmp/release_commits.txt for missed entries."
-fi
-```
-
-> If a commit cannot be matched to a bullet, EITHER add it or explicitly justify the omission in this session before continuing.
-
-### 5. Sync versioned files ⚠️ 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 so workspace lockfile picks up the bumps
-npm install
-```
-
-### 6. Sync README.md and i18n docs
-
-There is **no `/update-docs` slash command** (deprecated in v3.8). Updates must happen manually OR via parallel subagents.
-
-**Recommended automation** — dispatch parallel agents to apply the same diff across the 40 translations (see `superpowers:dispatching-parallel-agents`):
-
-1. Apply the substantive change to `README.md` first (feature table row + "What's new in vX.Y.Z" section).
-2. Capture the diff: `git diff README.md > /tmp/readme.patch`.
-3. Dispatch 5-10 parallel agents, each handling a slice of the 40 `docs/i18n/*/README.md`, translating the diff into the target language.
-4. Update `docs/<AREA>.md` if architecture/counts changed (e.g. `docs/frameworks/MCP-SERVER.md` when MCP tools change).
-5. Validate: `npm run check:docs-sync && npm run check:docs-all`.
-
-### 7. Full quality gate (MANDATORY — replaces the old `npm test`)
-
-> **Precedent**: the v3.8.2 cycle landed with 49 broken tests because only `npm test` was running. Lint + typecheck + cycles caught zero of those regressions.
-
-// turbo
-
-```bash
-set -e
-npm run lint
-npm run typecheck:core
-npm run check:cycles
-npm run check:docs-all
-npm test
-```
-
-All five must pass before opening the PR. If any fail, fix and re-run.
-
-### 8. Stage, commit, and push (atomic — bump + features + changelog + i18n in ONE commit)
-
-// turbo
-
-```bash
-VERSION=$(node -p "require('./package.json').version")
-git add -A
-git commit -m "chore(release): v$VERSION — $(date -u +%F)"
-git push origin "release/v$VERSION"
-```
-
-> **NEVER** include `Co-Authored-By:` trailers in the release commit (Hard Rule #16). Co-author attribution lives inside the CHANGELOG entries.
-
-### 9. Open PR to main
-
-// turbo
-
-```bash
-VERSION=$(node -p "require('./package.json').version")
-
-# Extract the exact changelog entry for this version
-awk "/^## \\[$VERSION\\]/{flag=1; print; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md > /tmp/changelog_body.txt
-
-# Append PR-only metadata (test status + reviewer instructions)
-{
-  echo ""
-  echo "---"
-  echo ""
-  echo "### Quality Gate"
-  echo "- lint: pass"
-  echo "- typecheck:core: pass"
-  echo "- check:cycles: pass"
-  echo "- check:docs-all: pass"
-  echo "- tests: pass"
-  echo ""
-  echo "### Coverage of commits since previous tag"
-  LAST_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "(no previous tag)")
-  COMMITS=$(git rev-list --no-merges "$LAST_TAG..HEAD" | wc -l)
-  echo "- Range: \`$LAST_TAG..HEAD\`"
-  echo "- Commits inspected: $COMMITS"
-  echo ""
-  echo "### ⚠️ After merging: run Phase 2 (Local VPS homologation) before tagging."
-} >> /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
-
-Present in the final response and stop. Do not continue to Phase 2 until the user explicitly approves.
-
-Provide:
-
-- PR URL
-- Summary of changes (top 5 from CHANGELOG)
-- Quality gate results
-- List of files changed (`git diff --stat $LAST_TAG..HEAD`)
-- Coverage count vs commits-in-range
-
-**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 only AFTER the user has merged the PR into `main` and all CI jobs pass.
-
-### 11. Deploy `main` to the Local VPS
-
-Delegate to the `deploy-vps-local-cc` skill (single source of truth for the deploy procedure — do NOT duplicate the SCP/SSH commands here):
-
-```
-/deploy-vps-local-cc
-```
-
-The skill handles: checkout `main`, `npm pack`, scp to `192.168.0.15`, install, pm2 restart, and HTTP probe.
-
-### 12. 🛑 STOP — Notify user & await final OK
-
-Inform the user that `main` is running on `192.168.0.15:20128`. Provide a smoke-test checklist:
-
-- [ ] `GET /` returns 200
-- [ ] Dashboard login works (`/dashboard`)
-- [ ] `/v1/chat/completions` with default provider returns a stream
-- [ ] No critical errors in `pm2 logs omniroute --lines 100`
-- [ ] Any release-specific UI features are reachable
-
-Wait for user **OK** before Phase 3.
-
----
-
-## Phase 3: Official Launch
-
-> Run only AFTER the user gives the final OK from Phase 2.
-
-### 13. Create git tag and GitHub Release
-
-// turbo
-
-```bash
-git checkout main
-git pull origin main
-VERSION=$(node -p "require('./package.json').version")
-
-# Extract release notes section from CHANGELOG
-NOTES=$(awk "/^## \\[$VERSION\\]/{flag=1; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
-[ -z "$NOTES" ] && NOTES="OmniRoute v$VERSION Release"
-
-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 / verify Docker Hub build
-
-> **CRITICAL**: Docker Hub and npm MUST publish the same version.
-
-```bash
-VERSION=$(node -p "require('./package.json').version")
-gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 3
-gh run watch --repo diegosouzapw/OmniRoute
-```
-
-### 15. Publish to npm (usually CI)
-
-`prepublishOnly` runs `npm run build:cli`. Manual fallback:
-
-```bash
-npm publish
-npm info omniroute version  # verify
-```
-
-### 16. Deploy to Akamai VPS (Production)
-
-Delegate to the `deploy-vps-akamai-cc` skill:
-
-```
-/deploy-vps-akamai-cc
-```
-
-The skill handles: build, pack, scp to `69.164.221.35`, install, pm2 restart, HTTP probe.
-
-### 17. Rollback playbook (use only if Phase 3 fails after tag push)
-
-If a fatal regression surfaces after the tag is pushed:
-
-```bash
-VERSION=$(node -p "require('./package.json').version")
-PREV=$(git describe --tags --abbrev=0 "v$VERSION^")
-
-# 1. Mark GitHub release as pre-release (do not delete history)
-gh release edit "v$VERSION" --repo diegosouzapw/OmniRoute --prerelease
-
-# 2. Re-deploy previous version to Akamai
-git checkout "$PREV" && /deploy-vps-akamai-cc
-
-# 3. Deprecate the broken npm version
-npm deprecate "omniroute@$VERSION" "broken release — use $PREV"
-
-# 4. Open follow-up issue and start a new patch cycle from main
-```
-
----
-
-## Phase 4: Release Monitoring & Artifact Validation
-
-> Actively monitor the CI pipelines until all artifacts succeed. If any fail, stop and fix before continuing.
-
-### 18. Monitor CI pipelines
-
-Verify successful completion of:
-
-1. **Docker Hub Publish**
-2. **Electron Build**
-3. **npm Registry Publish**
-
-```bash
-gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 1
-gh run list --repo diegosouzapw/OmniRoute --workflow electron-release.yml --limit 1
-gh run watch <RUN_ID>
-
-npm info omniroute version
-```
-
-### 19. Handle failures
-
-```bash
-gh run view <RUN_ID> --log-failed
-# Fix on main, then re-trigger:
-VERSION=$(node -p "require('./package.json').version")
-gh workflow run <workflow.yml> --repo diegosouzapw/OmniRoute --ref "v$VERSION"
-```
-
-### 20. Preserve release branch
-
-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` first.
-- 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 the wrong account.
-- Deploy procedures live in dedicated skills (`deploy-vps-local-cc`, `deploy-vps-akamai-cc`, `deploy-vps-both-cc`) — never inline the SCP/SSH commands here, to avoid drift.
-
-## 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              |
-| Coverage gate fails (statements/lines < 75% or branches < 70%)            | Production code changed without tests                              | Add tests, re-run `npm run test:coverage` (see CLAUDE.md hard rule #9) |

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

@@ -1,515 +0,0 @@
----
-name: generate-release-cx
-description: Create a new release, bump version up to the .999 patch threshold, generate a complete CHANGELOG (with PR co-authors + every commit since the last tag), and manage Pull Requests
----
-
-# Generate Release Workflow
-
-Bump version, build a **complete CHANGELOG** from every commit since the last tag (with PR back-reference and contributor attribution), 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 1000, bump to `3.(x+1).0` — e.g. `3.8.999` → `3.9.0`.
-
-> **🔴 INTEGRATION BRANCH RULE**: The `release/vX.Y.Z` branch is the **integration target** for the entire release cycle. Bug fixes and feature implementations land here **via per-issue PRs from short-lived `fix/<ISSUE>-<short>` or `feat/<ISSUE>-<short>` worktrees** (see `/resolve-issues`, `/implement-features`). Contributor PRs from `/review-prs` likewise merge into this branch. The release branch is then merged to `main` via a single release PR at the end of the cycle.
-
----
-
-## ⚠️ Four-Phase Flow
-
-```
-Phase 0 → security audit (npm + CodeQL + Dependabot)
-Phase 1 → bump → full quality gate → changelog from commits → commit → push → open PR
-  ↕  🛑 STOP (BlockedOnUser: true): notify user, wait for PR merge
-Phase 2 → deploy main to Local VPS for homologation
-  ↕  🛑 STOP (BlockedOnUser: true): notify user, wait for OK
-Phase 3 → tag → GitHub release → Docker → npm → Akamai
-Phase 4 → monitor CI pipelines and validate artifacts
-```
-
-**NEVER push directly to main or create tags before the user confirms the PR.**
-
----
-
-## Phase 0: Security Verification (MANDATORY)
-
-// turbo
-
-```bash
-# 1. Local dependency audit
-npm audit --production --audit-level=high
-
-# 2. GitHub CodeQL alerts (open + high severity)
-gh api '/repos/diegosouzapw/OmniRoute/code-scanning/alerts?state=open&severity=high' \
-  --jq '.[] | {rule: .rule.id, path: .most_recent_instance.location.path, msg: .most_recent_instance.message.text}' \
-  2>/dev/null || echo "(no CodeQL access or no alerts)"
-
-# 3. Dependabot alerts (open + high/critical)
-gh api '/repos/diegosouzapw/OmniRoute/dependabot/alerts?state=open' \
-  --jq '.[] | select(.security_advisory.severity == "high" or .security_advisory.severity == "critical") | {pkg: .dependency.package.name, sev: .security_advisory.severity, summary: .security_advisory.summary}' \
-  2>/dev/null || echo "(no Dependabot access or no alerts)"
-```
-
-Fix or justify (with `vulnerability-scanner` skill, or dismissal comment per Hard Rule #14) any `high`/`critical` findings before proceeding.
-
----
-
-## Phase 1: Pre-Merge
-
-### 1. Create or confirm release branch
-
-```bash
-# To create a new release branch (MUST always be created from main):
-git checkout main
-git pull origin main
-git checkout -b release/v3.9.0
-
-# If continuing the current cycle, just verify:
-git branch --show-current
-```
-
-### 2. Determine and sync version
-
-```bash
-grep '"version"' package.json
-```
-
-> **🔴 BRANCH-VERSION PARITY GATE** — auto-checked before any work:
-
-// turbo
-
-```bash
-BRANCH=$(git branch --show-current)
-BRANCH_VER=${BRANCH#release/v}
-PKG_VER=$(node -p "require('./package.json').version")
-
-if [[ "$BRANCH" != release/v* ]]; then
-  echo "❌ Not on a release/v* branch (current: $BRANCH). Aborting."; exit 1
-fi
-
-echo "Branch target: $BRANCH_VER"
-echo "package.json:  $PKG_VER"
-```
-
-> **⚠️ ATOMIC COMMIT RULE** — bump and feature/fix code MUST land in the same commit so that `git show vX.Y.Z` always contains both. NEVER commit features first and bump in a separate commit.
-
-```bash
-npm version patch --no-git-tag-version
-```
-
-### 3. Regenerate lock file (REQUIRED after version bump)
-
-```bash
-npm install
-```
-
-Skipping causes `@swc/helpers` lock mismatch and CI failures.
-
-### 4. Build CHANGELOG from EVERY commit since the last tag
-
-> **🎯 Goal**: produce a complete CHANGELOG section following the format of PR #2617 — emoji-grouped sections, PR back-reference, and `— thanks @user` attribution. Nothing must slip through.
-
-> **🔴 NO MIXUPS RULE**: do not mix backlog of the previous version. The new section must contain ONLY commits whose merge/landing happened after the previous tag.
-
-#### 4a. Collect raw commit log since last tag
-
-// turbo
-
-```bash
-LAST_TAG=$(git describe --tags --abbrev=0)
-NEW_VERSION=$(node -p "require('./package.json').version")
-TODAY=$(date -u +%F)
-echo "Range: $LAST_TAG..HEAD  →  v$NEW_VERSION ($TODAY)"
-
-# Full commit list (oneline)
-git log --no-merges "$LAST_TAG..HEAD" --pretty=format:'%h %s' > /tmp/release_commits.txt
-wc -l /tmp/release_commits.txt
-
-# Merge commits (preserve PR numbers + authors)
-git log --merges "$LAST_TAG..HEAD" --pretty=format:'%h %s%n  author=%an <%ae>' > /tmp/release_merges.txt
-
-# Per-commit detailed list (PR refs, co-authors, body)
-git log "$LAST_TAG..HEAD" --pretty=format:'---%n%h | %s%n  author=%an <%ae>%n  body=%b' > /tmp/release_detailed.txt
-```
-
-#### 4b. Enrich with PR metadata + co-authors
-
-For each commit referencing a PR (e.g. `(#2617)` or merge commit `Merge pull request #N`), fetch the PR author and any additional contributors. Use `multi_tool_use.parallel` to fan out the `gh pr view` calls.
-
-// turbo
-
-```bash
-# Extract all PR numbers referenced in the range
-grep -oE '#[0-9]+' /tmp/release_commits.txt | sort -u > /tmp/release_prs.txt
-echo "PRs in range:"; cat /tmp/release_prs.txt
-
-# Fetch author + co-author info for every PR
-> /tmp/release_pr_meta.json
-while read -r PR; do
-  N=${PR#\#}
-  gh pr view "$N" --repo diegosouzapw/OmniRoute \
-    --json number,title,author,mergeCommit,body \
-    >> /tmp/release_pr_meta.json 2>/dev/null || echo "(skip $PR — not found)"
-  echo "" >> /tmp/release_pr_meta.json
-done < /tmp/release_prs.txt
-```
-
-#### 4c. Assemble the new CHANGELOG section
-
-Using `/tmp/release_commits.txt` + `/tmp/release_pr_meta.json` + `/tmp/release_detailed.txt`, build a new entry that:
-
-1. **Covers every commit** — read the full list and group by Conventional Commit type. A commit is "covered" iff it appears (or is intentionally rolled-up) in the new section.
-2. **Groups using these section headers (model from PR #2617)**:
-   - `### ✨ New Features` — `feat(*)`
-   - `### 🔧 Bug Fixes` — `fix(*)`
-   - `### 📝 Maintenance` — `chore(*)`, `refactor(*)`, `docs(*)`, `test(*)`, `ci(*)`, `build(*)`
-   - `### 🔒 Security` — security-flagged commits (only if any)
-3. **Entry format**:
-   ```
-   - **type(scope):** human-friendly description — extra context if useful. ([#PR](https://github.com/diegosouzapw/OmniRoute/pull/PR) — thanks @author / @coauthor1 / @coauthor2)
-   ```
-   - When **no PR** is referenced (direct commit on release branch): `(thanks @author)`.
-   - When the PR closed an external contributor's PR via cherry-pick or re-implementation, attribute BOTH the original author AND the implementer: `thanks @originalAuthor / @diegosouzapw`.
-   - **Co-authors** must be extracted from the merge commit body (`Co-Authored-By:` lines that pre-date Hard Rule #16) and from PR participants who supplied commits.
-4. **Coverage check** — after drafting, diff the section against `/tmp/release_commits.txt`. Any unlisted commit must either be explicitly added or consolidated under a roll-up bullet (e.g. "various lint and test alignments"). Do NOT silently drop commits.
-
-Place the new section in `CHANGELOG.md` right below `## [Unreleased]`, separated by `---`:
-
-```markdown
-## [Unreleased]
-
----
-
-## [3.9.0] — 2026-05-27
-
-### ✨ New Features
-
-- **feat(scope):** description ([#1234](https://github.com/diegosouzapw/OmniRoute/pull/1234) — thanks @author)
-- ...
-
-### 🔧 Bug Fixes
-
-- **fix(scope):** description ([#1235](https://github.com/diegosouzapw/OmniRoute/pull/1235) — thanks @author / @diegosouzapw)
-- ...
-
-### 📝 Maintenance
-
-- **chore(scope):** description (thanks @diegosouzapw)
-- ...
-
-### 🏆 Hall of Contributors
-
-A special thanks to everyone who contributed code, reviews, and tests for this release:
-@user1, @user2, @user3
-
----
-
-## [3.8.999] — 2026-05-20
-```
-
-> **🔴 HALL OF CONTRIBUTORS RULE**: After drafting all section bullets, parse every `@username` mention from the bullets (PR authors AND co-authors), deduplicate, sort, and append them as a `### 🏆 Hall of Contributors` block at the end of the new release section (before the trailing `---`).
-
-#### 4d. Coverage assertion
-
-// turbo
-
-```bash
-NEW_VERSION=$(node -p "require('./package.json').version")
-
-# Count commits in range
-COMMITS=$(wc -l < /tmp/release_commits.txt)
-
-# Count bullets under the new section
-BULLETS=$(awk "/^## \\[$NEW_VERSION\\]/{flag=1;next} /^## \\[/{flag=0} flag" CHANGELOG.md | grep -c '^- ')
-
-echo "Commits in range: $COMMITS"
-echo "Changelog bullets: $BULLETS"
-if [ "$BULLETS" -lt $(( COMMITS / 3 )) ]; then
-  echo "⚠️  Bullet count looks low (< commits/3). Re-review /tmp/release_commits.txt for missed entries."
-fi
-```
-
-> If a commit cannot be matched to a bullet, EITHER add it or explicitly justify the omission in this session before continuing.
-
-### 5. Sync versioned files ⚠️ 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 so workspace lockfile picks up the bumps
-npm install
-```
-
-### 6. Sync README.md and i18n docs
-
-There is **no `/update-docs` workflow** (deprecated in v3.8). Updates must happen manually OR via parallel agents.
-
-**Recommended automation** — fan out via `multi_tool_use.parallel`:
-
-1. Apply the substantive change to `README.md` first (feature table row + "What's new in vX.Y.Z" section).
-2. Capture the diff: `git diff README.md > /tmp/readme.patch`.
-3. Dispatch 5-10 parallel sub-tasks, each handling a slice of the 40 `docs/i18n/*/README.md`, translating the diff into the target language.
-4. Update `docs/<AREA>.md` if architecture/counts changed (e.g. `docs/frameworks/MCP-SERVER.md` when MCP tools change).
-5. Validate: `npm run check:docs-sync && npm run check:docs-all`.
-
-### 7. Full quality gate (MANDATORY — replaces the old `npm test`)
-
-> **Precedent**: the v3.8.2 cycle landed with 49 broken tests because only `npm test` was running. Lint + typecheck + cycles caught zero of those regressions.
-
-// turbo
-
-```bash
-set -e
-npm run lint
-npm run typecheck:core
-npm run check:cycles
-npm run check:docs-all
-npm test
-```
-
-All five must pass before opening the PR. If any fail, fix and re-run.
-
-### 8. Stage, commit, and push (atomic — bump + features + changelog + i18n in ONE commit)
-
-// turbo-all
-
-```bash
-VERSION=$(node -p "require('./package.json').version")
-git add -A
-git commit -m "chore(release): v$VERSION — $(date -u +%F)"
-git push origin "release/v$VERSION"
-```
-
-> **NEVER** include `Co-Authored-By:` trailers in the release commit (Hard Rule #16). Co-author attribution lives inside the CHANGELOG entries and the Hall of Contributors block.
-
-### 9. Open PR to main
-
-// turbo
-
-```bash
-VERSION=$(node -p "require('./package.json').version")
-
-# Extract the exact changelog entry for this version
-awk "/^## \\[$VERSION\\]/{flag=1; print; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md > /tmp/changelog_body.txt
-
-# Append PR-only metadata (test status + reviewer instructions)
-{
-  echo ""
-  echo "---"
-  echo ""
-  echo "### Quality Gate"
-  echo "- lint: pass"
-  echo "- typecheck:core: pass"
-  echo "- check:cycles: pass"
-  echo "- check:docs-all: pass"
-  echo "- tests: pass"
-  echo ""
-  echo "### Coverage of commits since previous tag"
-  LAST_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "(no previous tag)")
-  COMMITS=$(git rev-list --no-merges "$LAST_TAG..HEAD" | wc -l)
-  echo "- Range: \`$LAST_TAG..HEAD\`"
-  echo "- Commits inspected: $COMMITS"
-  echo ""
-  echo "### ⚠️ After merging: run Phase 2 (Local VPS homologation) before tagging."
-} >> /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 (`BlockedOnUser: true`)
-
-Present in the final response and stop. Do not continue to Phase 2 until the user explicitly approves.
-
-Provide:
-
-- PR URL
-- Summary of changes (top 5 from CHANGELOG)
-- Quality gate results
-- List of files changed (`git diff --stat $LAST_TAG..HEAD`)
-- Coverage count vs commits-in-range
-
-**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 only AFTER the user has merged the PR into `main` and all CI jobs pass.
-
-### 11. Deploy `main` to the Local VPS
-
-Delegate to the `deploy-vps-local-cx` skill (single source of truth for the deploy procedure — do NOT duplicate SCP/SSH commands here):
-
-```
-/deploy-vps-local-cx
-```
-
-The skill handles: checkout `main`, `npm pack`, scp to `192.168.0.15`, install, pm2 restart, and HTTP probe.
-
-### 12. 🛑 STOP — Notify user & await final OK (`BlockedOnUser: true`)
-
-Inform the user that `main` is running on `192.168.0.15:20128`. Provide a smoke-test checklist:
-
-- [ ] `GET /` returns 200
-- [ ] Dashboard login works (`/dashboard`)
-- [ ] `/v1/chat/completions` with default provider returns a stream
-- [ ] No critical errors in `pm2 logs omniroute --lines 100`
-- [ ] Any release-specific UI features are reachable
-
-Wait for user **OK** before Phase 3.
-
----
-
-## Phase 3: Official Launch
-
-> Run only AFTER the user gives the final OK from Phase 2.
-
-### 13. Create git tag and GitHub Release
-
-// turbo
-
-```bash
-git checkout main
-git pull origin main
-VERSION=$(node -p "require('./package.json').version")
-
-# Extract release notes section from CHANGELOG
-NOTES=$(awk "/^## \\[$VERSION\\]/{flag=1; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
-[ -z "$NOTES" ] && NOTES="OmniRoute v$VERSION Release"
-
-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 / verify Docker Hub build
-
-> **CRITICAL**: Docker Hub and npm MUST publish the same version.
-
-```bash
-VERSION=$(node -p "require('./package.json').version")
-gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 3
-gh run watch --repo diegosouzapw/OmniRoute
-```
-
-### 15. Publish to npm (usually CI)
-
-`prepublishOnly` runs `npm run build:cli`. Manual fallback:
-
-```bash
-npm publish
-npm info omniroute version  # verify
-```
-
-### 16. Deploy to Akamai VPS (Production)
-
-Delegate to the `deploy-vps-akamai-cx` skill if present, or run the inline equivalent of `deploy-vps-local-cx` against `69.164.221.35`. Do NOT duplicate the procedure here.
-
-### 17. Rollback playbook (use only if Phase 3 fails after tag push)
-
-If a fatal regression surfaces after the tag is pushed:
-
-```bash
-VERSION=$(node -p "require('./package.json').version")
-PREV=$(git describe --tags --abbrev=0 "v$VERSION^")
-
-# 1. Mark GitHub release as pre-release (do not delete history)
-gh release edit "v$VERSION" --repo diegosouzapw/OmniRoute --prerelease
-
-# 2. Re-deploy previous version to Akamai
-git checkout "$PREV" && /deploy-vps-akamai-cx
-
-# 3. Deprecate the broken npm version
-npm deprecate "omniroute@$VERSION" "broken release — use $PREV"
-
-# 4. Open follow-up issue and start a new patch cycle from main
-```
-
----
-
-## Phase 4: Release Monitoring & Artifact Validation
-
-> Actively monitor the CI pipelines until all artifacts succeed. If any fail, stop and fix before continuing.
-
-### 18. Monitor CI pipelines
-
-Verify successful completion of:
-
-1. **Docker Hub Publish**
-2. **Electron Build**
-3. **npm Registry Publish**
-
-```bash
-gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 1
-gh run list --repo diegosouzapw/OmniRoute --workflow electron-release.yml --limit 1
-gh run watch <RUN_ID>
-
-npm info omniroute version
-```
-
-### 19. Handle failures
-
-```bash
-gh run view <RUN_ID> --log-failed
-# Fix on main, then re-trigger:
-VERSION=$(node -p "require('./package.json').version")
-gh workflow run <workflow.yml> --repo diegosouzapw/OmniRoute --ref "v$VERSION"
-```
-
-### 20. Preserve release branch
-
-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` first.
-- 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 the wrong account.
-- Deploy procedures live in dedicated skills (`deploy-vps-local-cx`, `deploy-vps-akamai-cx` if present) — never inline the SCP/SSH commands here, to avoid drift.
-
-## 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              |
-| Coverage gate fails (statements/lines < 75% or branches < 70%)            | Production code changed without tests                              | Add tests, re-run `npm run test:coverage` (see CLAUDE.md hard rule #9) |

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

@@ -1,891 +0,0 @@
----
-name: implement-features-ag
-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/                  # ✅ Approved, awaiting implementation
-│   ├── 1046-native-playground.md
-│   └── 1046-native-playground.requirements.md
-├── implemented/             # ✅ Implemented but release PR not yet merged to main (transient)
-│   └── 1046-native-playground.md
-├── need_details/            # ❓ Issue OPEN — awaiting author clarification (permanent archive)
-│   └── 1015-warp-terminal-mitm.md
-├── defer/                   # ⏭️ Issue CLOSED — good idea, deferred for future cycles (permanent)
-│   └── 1041-smart-auto-combos.md
-├── notfit/                  # ❌ Issue CLOSED — out of scope (permanent)
-│   └── 945-telegram-integration.md
-├── exists/                  # 🔁 Issue CLOSED — feature already shipped (permanent, kept separate from notfit)
-│   └── 812-rate-limit-dashboard.md
-└── in_flight/               # 🚧 Issue OPEN — third-party PR already addresses it (permanent until reclaim or merge)
-    └── 988-batch-export.md
-
-_tasks/features-vX.Y.Z/   # Implementation plans (per-release)
-└── 1046-native-playground.plan.md
-```
-
-> **LIFECYCLE RULE:**
-> - `viable/` files are **MOVED** to `implemented/` once code lands on the release branch.
-> - `implemented/` files are **DELETED** only after the release PR is merged to `main`.
-> - All other buckets — `need_details/`, `defer/`, `notfit/`, `exists/`, `in_flight/` — are **permanent archives**. Even when the upstream issue is CLOSED, the local file stays. Future cycles can revisit any of them (Phase 1.7 stale-reclaim turns `in_flight/` and `need_details/` back into VIABLE after 15 days of upstream inactivity).
-> - This preserves recovery context if implementation fails partially AND lets us re-evaluate old decisions when the project matures.
-
-> **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, delegate creation to `/generate-release` (see Phase 1.2) — do NOT reimplement bump logic here.
-
-> **LANGUAGE RULE** (per `feedback_reply_language` memory): GitHub comments MUST match the language of the original issue body. Detect language by sampling the issue body + first 2 comments. Default to English when uncertain. All comment templates below are in English — translate to the detected language before posting. Internal docs, plan files, and idea files stay in English regardless.
-
----
-
-## 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
-
-Before doing any work, ensure you are on the current release branch:
-
-```bash
-git branch --show-current
-```
-
-**Decision tree:**
-
-- If already on a `release/vX.Y.Z` branch → continue working there.
-- If on `main` or any other branch → **delegate to `/generate-release`** by invoking its Phase 1 (steps 1–5: detect current version, bump, create branch, install). Do NOT reimplement the bump formula here — `/generate-release` owns the canonical version policy (patch bumps allowed up to `.999`; minor bump only when patch reaches `999`).
-
-> **Why delegate?** Duplicating the bump formula caused divergence in the past. `/generate-release` is the single source of truth for version arithmetic and now allows patches up to `.999` before bumping minor.
-
-### 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.
-- If the count hits the `--limit 500` ceiling, raise the limit and re-run — never proceed with a truncated set.
-
-**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`), **download and analyze them with the Read tool** (Claude can read PNG/JPG/GIF directly). Mockups and wireframes are often the most informative artifact — do NOT just "note" them, actually inspect their content and incorporate findings into the refined description.
-- **Detect issue language** from body + first 2 comments and record it in the idea file front-matter (`reply_lang: pt-BR | en | es | ...`). This will drive comment translation in Phases 2.5 and 5.
-- 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
----
-reply_lang: <detected-lang, e.g. pt-BR | en | es>
----
-
-# 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>
-
-## 🖼️ Mockup / Image Analysis
-
-<For each image embedded in the issue, summarize what it depicts: UI layout, data flow, architecture diagram, etc. Cite source URL.>
-
-## 🎯 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.
-- Re-detect `reply_lang` only if the issue language clearly changed (uncommon).
-- **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.`
-
-### 1.6 Detect In-Flight Work (avoid duplicate effort)
-
-For each issue number, check whether an open PR or branch already targets it:
-
-```bash
-# Open PRs that link the issue
-gh pr list --repo <owner>/<repo> --state open --search "linked:#<NUMBER>" --json number,title,headRefName,updatedAt,author
-
-# Local branches that mention the issue number
-git branch -a | grep -E "(^|/)(feat|fix|refactor)/.*-?<NUMBER>(-|$)" || true
-```
-
-If a PR or branch already exists:
-
-- Mark the idea file with `> ⚠️ In-flight: PR #<PR_NUMBER> by @<author> / branch <name> (last activity <date>)` near the top.
-- **Skip Phase 2 research and Phase 4 planning** for this feature — the implementation is already in motion.
-- In the Phase 3 report, list it under a separate "🚧 Already in progress" bucket; do NOT count it as VIABLE for implementation.
-- The idea file will be moved to `_ideia/in_flight/` in Phase 2.5.2 (it stays there permanently, but Phase 1.7 may reclaim it later).
-
-### 1.7 Stale Reclaim (15-day rule)
-
-Some issues sit in `in_flight/` or `need_details/` forever — third-party PRs go cold, authors disappear, the world moves on. This phase reclaims them when they go quiet.
-
-**Trigger conditions** (run for each issue currently in `_ideia/in_flight/` or `_ideia/need_details/`):
-
-```bash
-# For IN FLIGHT — last activity on the linked PR (commit OR comment)
-gh pr view <PR_NUMBER> --repo <owner>/<repo> --json updatedAt,commits,comments \
-  --jq '[.updatedAt, (.commits[-1].committedDate // ""), (.comments[-1].createdAt // "")] | max'
-
-# For NEEDS DETAIL — last activity from the issue author (any comment by them)
-gh issue view <NUMBER> --repo <owner>/<repo> --json comments,author \
-  --jq '.author.login as $a | [.comments[] | select(.author.login == $a) | .createdAt] | max // (.createdAt)'
-```
-
-Compute the gap in days between the timestamp above and today.
-
-**Reclaim rule:**
-
-| Bucket          | Trigger                                                            | Action                                                                                              |
-| --------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
-| 🚧 IN FLIGHT    | ≥15 days since last PR activity (commit OR comment by PR author)   | Post **intent-to-take-over comment** (template below), wait **48h**, then reclaim if no response    |
-| ❓ NEEDS DETAIL | ≥15 days since last comment by the issue author                    | Post **gentle nudge** (template below), wait **48h**, then reclaim as VIABLE if no response         |
-
-**Intent-to-take-over comment (🚧 IN FLIGHT path)** — translate to `reply_lang`:
-
-```markdown
-Hi @<pr_author> and @<issue_author>! 👋
-
-This PR (#<PR>) addressing issue #<NUMBER> hasn't had updates in <N> days. We'd love to ship this feature in our next release.
-
-**Plan:** if there are no updates in the next **48 hours**, our team will take over the work and merge it as part of `release/vX.Y.Z`. The original PR will be referenced and authorship preserved in the commit trailer.
-
-If you're still working on it, just drop a comment here and we'll hold off. Thanks for the contribution either way! 🙏
-```
-
-**Gentle nudge (❓ NEEDS DETAIL path)** — translate to `reply_lang`:
-
-```markdown
-Hi @<author>! 👋
-
-It's been <N> days since we asked for more details on this feature request. We'd still love to move forward.
-
-**Plan:** if we don't hear back in the next **48 hours**, we'll proceed with our best interpretation of the original request and add it to our backlog for implementation. We'll tag you on the implementation PR so you can review before it ships.
-
-If you still want to provide the details, just reply here — we'll wait. 🙏
-```
-
-**Reclaim execution** (only after the 48h grace period, with no new author/PR-author activity):
-
-1. Move the idea file to `_ideia/viable/` (preserve any prior content + add a `> ♻️ Reclaimed on <date> after 15-day inactivity` banner near the top).
-2. If it was IN FLIGHT and a research file does not yet exist, run Phase 2 (Research) for it now.
-3. Otherwise create the requirements file based on the existing content + a quick research pass.
-4. Add a `viable_origin: stale_reclaim` line to the front-matter so the Phase 3 report can flag it.
-5. In Phase 5 (commit / PR), include a commit trailer crediting the original PR author if applicable:
-   ```
-   Originally-proposed-by: @<pr_author> in #<original_pr_number>
-   ```
-   (This is NOT `Co-Authored-By` — hard rule #16 still applies. It is a free-form trailer that preserves credit without GitHub re-attributing the commit.)
-
-> **Why 15 days + 48h grace?** Long enough that the original contributor has truly moved on; short enough that the feature still ships in the same release cycle. Grace period is documented in `feedback_issue_triage_independence` so we don't default to "trust prior triage" — we verify the silence is real.
-
----
-
-## Phase 2 — Research: Find Solutions & Build Requirements
-
-For each cataloged idea that is **viable** (aligns with the project's goals) AND not already in flight (per 1.6):
-
-### 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   |
-| 🚧 **IN FLIGHT**      | PR/branch already exists (from 1.6)   | Skip — track only           |
-
-### 2.2 Internet Research (for VIABLE features)
-
-For each viable feature, perform systematic research with an **early-stopping criterion**:
-
-> **Stop as soon as EITHER condition is met:**
-> - 3 reference implementations show a consistent pattern, OR
-> - 1 high-quality repo (≥1k stars, updated within the last 12 months) already solves the problem cleanly.
->
-> Cap at 10 repos total. Do NOT exhaustively browse — depth over breadth.
-
-**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")
-```
-
-- Sort by most recently updated.
-- For each repository (until stop criterion hit):
-  - 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: Sort Files into Category Directories
-
-> **⚠️ This phase only moves files. It does NOT post comments or close issues.** All GitHub-visible actions are deferred to Phase 3.2 (after human approval).
-
-### 2.5.1 Create Directory Structure
-
-// turbo
-
-```bash
-mkdir -p <project_root>/_ideia/viable
-mkdir -p <project_root>/_ideia/implemented
-mkdir -p <project_root>/_ideia/need_details
-mkdir -p <project_root>/_ideia/defer
-mkdir -p <project_root>/_ideia/notfit
-mkdir -p <project_root>/_ideia/exists
-mkdir -p <project_root>/_ideia/in_flight
-```
-
-> **Permanent archives**: `need_details/`, `defer/`, `notfit/`, `exists/`, `in_flight/`. Even after the upstream issue is closed, the local file stays — future cycles may revisit.
-
-### 2.5.2 Move Idea Files to Category Subdirectories
-
-After classification, move EVERY idea file to its correct subdirectory (still local-only — no GitHub side-effects):
-
-```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 (issue stays OPEN)
-mv _ideia/<NUMBER>-*.md _ideia/need_details/
-
-# ⏭️ DEFER — issue will be CLOSED but file is kept permanently for future re-evaluation
-mv _ideia/<NUMBER>-*.md _ideia/defer/
-
-# ❌ NOT FIT — issue will be CLOSED but file is kept permanently
-mv _ideia/<NUMBER>-*.md _ideia/notfit/
-
-# 🔁 ALREADY EXISTS — issue will be CLOSED but file is kept permanently (separate bucket from NOT FIT)
-mv _ideia/<NUMBER>-*.md _ideia/exists/
-
-# 🚧 IN FLIGHT — issue stays OPEN, third-party PR is handling it; file kept permanently for Phase 1.7 stale-reclaim
-mv _ideia/<NUMBER>-*.md _ideia/in_flight/
-```
-
-No idea files should remain in `_ideia/` root after this step.
-
----
-
-## Phase 3 — Report: Present Findings & Get Human Approval
-
-### 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. **No comments have been posted to GitHub yet** — that happens in 3.2 after approval.
-
-Present a structured report containing:
-
-#### 3.1a — Feature Summary Table
-
-| #   | Issue | Title | Verdict           | Local Location          | Planned GitHub Action                  |
-| --- | ----- | ----- | ----------------- | ----------------------- | -------------------------------------- |
-| 1   | #N    | Title | ✅ VIABLE         | `_ideia/viable/`        | Comment + keep OPEN                    |
-| 2   | #N    | Title | ⏭️ DEFER          | `_ideia/defer/`         | Comment + CLOSE                        |
-| 3   | #N    | Title | ❌ NOT FIT        | `_ideia/notfit/`        | Comment + CLOSE                        |
-| 4   | #N    | Title | 🔁 EXISTS         | `_ideia/exists/`        | Comment with location + CLOSE          |
-| 5   | #N    | Title | ❓ NEEDS DETAIL   | `_ideia/need_details/`  | Comment with questions + keep OPEN     |
-| 6   | #N    | Title | 🚧 IN FLIGHT      | `_ideia/in_flight/`     | None — PR #M handles it                |
-| 7   | #N    | Title | ♻️ RECLAIMED      | `_ideia/viable/`        | Intent comment posted in Phase 1.7     |
-
-#### 3.1b — Viable Features Detail
-
-For each VIABLE feature, provide a brief paragraph:
-
-- What was found during research (with stop reason: "3-pattern consistency" or "dominant repo")
-- 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
-- Detected `reply_lang` for the question post
-
-#### 3.1d — Ask for User Confirmation
-
-End the report with:
-
-> **Ready to proceed?**
->
-> Approving will (a) post comments on GitHub in the detected language of each issue and (b) close DEFER / NOT FIT / EXISTS issues. VIABLE and NEEDS DETAIL stay open.
->
-> - Reply **"sim"** / **"yes"** to post all comments AND generate implementation plans for all VIABLE features.
-> - Reply **"only comments"** to post comments without generating plans yet.
-> - Reply with specific issue numbers to scope the action.
-> - Reply **"não"** / **"no"** to stop without touching GitHub.
-
-### 3.2 Post GitHub Comments & Close Issues (only after approval)
-
-> **⚠️ Do NOT execute this step without explicit user approval from 3.1d.**
-
-For each issue, translate the appropriate template below into the `reply_lang` recorded in its idea file front-matter, then post. The English templates are reference only — never post the English version verbatim to a non-English issue.
-
----
-
-#### For 🔁 ALREADY EXISTS — Comment + CLOSE issue
-
-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 "<translated comment>"
-```
-
----
-
-#### For ⏭️ DEFER — Comment + CLOSE issue
-
-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
-
-If you want to track progress, please **subscribe to the repository releases** — every implemented feature is announced in the CHANGELOG.
-
-Thank you for contributing to OmniRoute's roadmap! 🚀
-```
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<translated comment>"
-```
-
----
-
-#### For ❌ NOT FIT — Comment + CLOSE issue
-
-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 "<translated comment>"
-```
-
----
-
-#### For ❓ NEEDS DETAIL — Comment (keep OPEN)
-
-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)
-
-Thank the user, confirm we've cataloged their idea, and explain that progress is tracked in releases.
-
-```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 issue will be **closed automatically by the merge commit** when the feature ships. To follow along, you can subscribe to repository releases or watch this issue.
-
-Thank you for helping improve OmniRoute! 🚀
-```
-
-**⚠️ Do NOT close viable issues — they remain OPEN until the implementation PR closes them via commit message.**
-
----
-
-## Phase 4 — Plan: Generate Implementation Plans (after user says "yes")
-
-> **⚠️ Do NOT enter this phase without explicit user approval from Phase 3.**
-
-### 4.1 Pre-Plan Context Load (mandatory)
-
-Before writing ANY plan, read:
-
-1. `docs/architecture/REPOSITORY_MAP.md` — to know which directory owns what.
-2. `docs/architecture/CODEBASE_DOCUMENTATION.md` — for the engineering reference.
-3. The matching "Adding a New X" scenario from `CLAUDE.md` (provider, API route, DB module, MCP tool, A2A skill, cloud agent, embedded service, guardrail, eval, skill, webhook event).
-4. Any docs linked from the requirements file's "External References" section.
-
-This ensures plans cite real paths and follow the established add-a-X recipe, instead of inventing structure.
-
-### 4.2 Create Task Directory
-
-```bash
-mkdir -p <project_root>/_tasks/features-vX.Y.Z/
-```
-
-### 4.3 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`
-> Matching CLAUDE.md recipe: <e.g. "Adding a New Provider">
-
-## 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 (re-run Phase 1.6 lookup)
-- [ ] Verify database migration numbering (next free integer in `src/lib/db/migrations/`)
-
-## 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 (MANDATORY per CLAUDE.md hard rule #8)
-
-**New test files:**
-
-- `tests/unit/<test-file>.test.mjs` — <what to test>
-
-**Test cases:**
-
-- [ ] <test case 1>
-- [ ] <test case 2>
-- [ ] Coverage check: confirm overall coverage stays ≥75% statements/lines/functions, ≥70% branches (hard rule #9)
-
-### Step N+1: i18n
-
-**Translation keys to add:**
-
-- `<namespace>.<key>` — "<English value>"
-
-### Step N+2: Documentation
-
-- [ ] Update CHANGELOG.md (current release section)
-- [ ] Update relevant docs/ files
-- [ ] If touching error responses, follow `docs/security/ERROR_SANITIZATION.md`
-- [ ] If touching upstream credentials, follow `docs/security/PUBLIC_CREDS.md`
-
-## Verification Plan (Trust-but-Verify — mandatory before declaring done)
-
-1. `git status` + `git diff --stat` — review every changed file; flag anything outside the plan's declared scope
-2. `npm run lint` — 0 new errors
-3. `npm run typecheck:core` — clean
-4. `npm run typecheck:noimplicit:core` — clean
-5. `npm run check:cycles` — no new circular deps
-6. `npm run build` — must pass
-7. `npm run test:coverage` — coverage gate respected
-8. `npm run check-docs-sync` (via pre-commit hook) — passes
-9. Manual UI verification if the feature touches frontend (start dev server, exercise golden path + 1 edge case)
-
-## Commit Plan
-
-```
-feat: <description> (#<NUMBER>)
-```
-```
-
-### 4.4 Present Plans for Final Approval
-
-Present a summary of all generated plans:
-
-> **Implementation plans generated:**
->
-> | #   | Feature | Plan File                                | Steps   | Effort | CLAUDE.md recipe       |
-> | --- | ------- | ---------------------------------------- | ------- | ------ | ---------------------- |
-> | 1   | <title> | `_tasks/features-vX.Y.Z/N-title.plan.md` | N steps | Medium | Adding a New Provider  |
->
-> Reply **"sim"** / **"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. **Mark progress** — flip checkboxes to `[x]` in the plan as each step completes
-
-### 5.2 Trust-but-Verify Audit (mandatory before commit)
-
-> Aligned with `~/.claude/CLAUDE.md` global rule: never trust a subagent's summary alone.
-
-Run the full audit checklist from the plan's "Verification Plan" section AND inspect the diff yourself:
-
-```bash
-git status
-git diff --stat
-git diff                       # full diff, scan for out-of-scope changes
-npm run lint
-npm run typecheck:core
-npm run typecheck:noimplicit:core
-npm run check:cycles
-npm run build
-npm run test:coverage
-```
-
-**Block-on-failure checklist:**
-
-- [ ] No files changed outside the plan's declared scope (or scope expansion explicitly justified)
-- [ ] No deleted symbols/routes/files without a documented replacement (grep to confirm)
-- [ ] No weakened or removed test assertions (only additions or alignments with real behavior)
-- [ ] Coverage gate green (75/75/75/70)
-- [ ] All commands above exit 0
-- [ ] If UI was touched: manual smoke test passed and noted
-
-If any item fails, **fix root cause** before committing. Do NOT bypass with `--no-verify` (hard rule #10).
-
-### 5.3 Commit (one feature, one commit)
-
-```bash
-git add <only files in the plan>
-git commit -m "feat: <description> (#<NUMBER>)"
-```
-
-> **No `Co-Authored-By` trailers** (hard rule #16). Commits go solely under `diegosouzapw`.
-
-Then move (do NOT delete yet) the idea file to `_ideia/implemented/`:
-
-```bash
-mv _ideia/viable/<NUMBER>-<title>.md _ideia/implemented/
-mv _ideia/viable/<NUMBER>-<title>.requirements.md _ideia/implemented/ 2>/dev/null || true
-```
-
-> **Why move, not delete?** If the release PR is reverted or rebased, we still have the context. The file is deleted only after the PR merges to `main` (see 5.6).
-
-Continue to the next feature on the same branch — do NOT switch branches between features.
-
-### 5.4 Respond to Authors
-
-For each implemented feature, post a final close-comment **translated into the issue's `reply_lang`**:
-
-```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 (after the release PR merges):**
-
-```bash
-git fetch origin && git checkout main && git pull
-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 "<translated comment>"
-```
-
-### 5.5 Finalize the Release Branch
-
-After implementing all approved features:
-
-1. **Update CHANGELOG.md** on the release branch with all new feature entries
-2. Push: `git push origin release/vX.Y.Z`
-3. Hand off to `/generate-release` for the "Tests → Commit → Push → PR to main" stage. Refer to it **by stage name**, not step number, so this command does not break if `/generate-release` renumbers steps.
-
-### 5.6 Post-Merge Cleanup (only after release PR merges to main)
-
-Once the release PR is merged:
-
-```bash
-# Now safe to delete — commit history + CHANGELOG are the source of truth
-rm _ideia/implemented/<NUMBER>-*.md
-```
-
-> If running this command before the merge: STOP at 5.5 and skip 5.6. Re-enter the workflow later just for the cleanup.
-
-### 5.7 Final Summary Report
-
-Present a final summary report to the user:
-
-| Issue | Title | Verdict          | Action                                                          | Commit    |
-| ----- | ----- | ---------------- | --------------------------------------------------------------- | --------- |
-| #N    | Title | ✅ Implemented   | Issue closed, idea file in `_ideia/implemented/` (until merge)  | `abc1234` |
-| #N    | Title | ♻️ Reclaimed     | Was IN FLIGHT / NEEDS DETAIL, reclaimed after 15d → implemented | `abc1234` |
-| #N    | Title | ⏭️ Deferred      | Issue closed + permanent archive in `_ideia/defer/`             | —         |
-| #N    | Title | ❌ Not Fit       | Issue closed + permanent archive in `_ideia/notfit/`            | —         |
-| #N    | Title | 🔁 Exists        | Issue closed + permanent archive in `_ideia/exists/`            | —         |
-| #N    | Title | ❓ Needs Detail  | Issue OPEN, archive in `_ideia/need_details/`                   | —         |
-| #N    | Title | 🚧 In Flight     | Issue OPEN, archive in `_ideia/in_flight/`, tracked by PR #M    | —         |
-
-Include:
-
-- Total features harvested
-- Total ideas archived per bucket (`need_details/` / `defer/` / `notfit/` / `exists/` / `in_flight/`)
-- Total features implemented (idea files in `_ideia/implemented/`, awaiting post-merge cleanup)
-- Total reclaimed via Phase 1.7 (stale 15-day rule)
-- Total issues closed
-- Total issues left open (NEEDS DETAIL + VIABLE-pending + IN FLIGHT)
-- Audit results: lint / typecheck / cycles / build / coverage (pass-count per phase)
-- Languages used in posted comments (e.g. "3× pt-BR, 5× en, 1× es")

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

@@ -1,903 +0,0 @@
----
-name: implement-features-cc
-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/                  # ✅ Approved, awaiting implementation
-│   ├── 1046-native-playground.md
-│   └── 1046-native-playground.requirements.md
-├── implemented/             # ✅ Implemented but release PR not yet merged to main (transient)
-│   └── 1046-native-playground.md
-├── need_details/            # ❓ Issue OPEN — awaiting author clarification (permanent archive)
-│   └── 1015-warp-terminal-mitm.md
-├── defer/                   # ⏭️ Issue CLOSED — good idea, deferred for future cycles (permanent)
-│   └── 1041-smart-auto-combos.md
-├── notfit/                  # ❌ Issue CLOSED — out of scope (permanent)
-│   └── 945-telegram-integration.md
-├── exists/                  # 🔁 Issue CLOSED — feature already shipped (permanent, kept separate from notfit)
-│   └── 812-rate-limit-dashboard.md
-└── in_flight/               # 🚧 Issue OPEN — third-party PR already addresses it (permanent until reclaim or merge)
-    └── 988-batch-export.md
-
-_tasks/features-vX.Y.Z/   # Implementation plans (per-release)
-└── 1046-native-playground.plan.md
-```
-
-> **LIFECYCLE RULE:**
-> - `viable/` files are **MOVED** to `implemented/` once code lands on the release branch.
-> - `implemented/` files are **DELETED** only after the release PR is merged to `main`.
-> - All other buckets — `need_details/`, `defer/`, `notfit/`, `exists/`, `in_flight/` — are **permanent archives**. Even when the upstream issue is CLOSED, the local file stays. Future cycles can revisit any of them (Phase 1.7 stale-reclaim turns `in_flight/` and `need_details/` back into VIABLE after 15 days of upstream inactivity).
-> - This preserves recovery context if implementation fails partially AND lets us re-evaluate old decisions when the project matures.
-
-> **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, delegate creation to `/generate-release` (see Phase 1.2) — do NOT reimplement bump logic here.
-
-> **LANGUAGE RULE** (per `feedback_reply_language` memory): GitHub comments MUST match the language of the original issue body. Detect language by sampling the issue body + first 2 comments. Default to English when uncertain. All comment templates below are in English — translate to the detected language before posting. Internal docs, plan files, and idea files stay in English regardless.
-
----
-
-## 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
-
-Before doing any work, ensure you are on the current release branch:
-
-```bash
-git branch --show-current
-```
-
-**Decision tree:**
-
-- If already on a `release/vX.Y.Z` branch → continue working there.
-- If on `main` or any other branch → **delegate to `/generate-release`** by invoking its Phase 1 (steps 1–5: detect current version, bump, create branch, install). Do NOT reimplement the bump formula here — `/generate-release` owns the canonical version policy (patch bumps allowed up to `.999`; minor bump only when patch reaches `999`).
-
-> **Why delegate?** Duplicating the bump formula caused divergence in the past. `/generate-release` is the single source of truth for version arithmetic and now allows patches up to `.999` before bumping minor.
-
-### 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.
-- If the count hits the `--limit 500` ceiling, raise the limit and re-run — never proceed with a truncated set.
-
-**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`), **download and analyze them with the Read tool** (Claude can read PNG/JPG/GIF directly). Mockups and wireframes are often the most informative artifact — do NOT just "note" them, actually inspect their content and incorporate findings into the refined description.
-- **Detect issue language** from body + first 2 comments and record it in the idea file front-matter (`reply_lang: pt-BR | en | es | ...`). This will drive comment translation in Phases 2.5 and 5.
-- 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
----
-reply_lang: <detected-lang, e.g. pt-BR | en | es>
----
-
-# 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>
-
-## 🖼️ Mockup / Image Analysis
-
-<For each image embedded in the issue, summarize what it depicts: UI layout, data flow, architecture diagram, etc. Cite source URL.>
-
-## 🎯 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.
-- Re-detect `reply_lang` only if the issue language clearly changed (uncommon).
-- **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.`
-
-### 1.6 Detect In-Flight Work (avoid duplicate effort)
-
-For each issue number, check whether an open PR or branch already targets it:
-
-```bash
-# Open PRs that link the issue
-gh pr list --repo <owner>/<repo> --state open --search "linked:#<NUMBER>" --json number,title,headRefName,updatedAt,author
-
-# Local branches that mention the issue number
-git branch -a | grep -E "(^|/)(feat|fix|refactor)/.*-?<NUMBER>(-|$)" || true
-```
-
-If a PR or branch already exists:
-
-- Mark the idea file with `> ⚠️ In-flight: PR #<PR_NUMBER> by @<author> / branch <name> (last activity <date>)` near the top.
-- **Skip Phase 2 research and Phase 4 planning** for this feature — the implementation is already in motion.
-- In the Phase 3 report, list it under a separate "🚧 Already in progress" bucket; do NOT count it as VIABLE for implementation.
-- The idea file will be moved to `_ideia/in_flight/` in Phase 2.5.2 (it stays there permanently, but Phase 1.7 may reclaim it later).
-
-### 1.7 Stale Reclaim (15-day rule)
-
-Some issues sit in `in_flight/` or `need_details/` forever — third-party PRs go cold, authors disappear, the world moves on. This phase reclaims them when they go quiet.
-
-**Trigger conditions** (run for each issue currently in `_ideia/in_flight/` or `_ideia/need_details/`):
-
-```bash
-# For IN FLIGHT — last activity on the linked PR (commit OR comment)
-gh pr view <PR_NUMBER> --repo <owner>/<repo> --json updatedAt,commits,comments \
-  --jq '[.updatedAt, (.commits[-1].committedDate // ""), (.comments[-1].createdAt // "")] | max'
-
-# For NEEDS DETAIL — last activity from the issue author (any comment by them)
-gh issue view <NUMBER> --repo <owner>/<repo> --json comments,author \
-  --jq '.author.login as $a | [.comments[] | select(.author.login == $a) | .createdAt] | max // (.createdAt)'
-```
-
-Compute the gap in days between the timestamp above and today.
-
-**Reclaim rule:**
-
-| Bucket          | Trigger                                                            | Action                                                                                              |
-| --------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
-| 🚧 IN FLIGHT    | ≥15 days since last PR activity (commit OR comment by PR author)   | Post **intent-to-take-over comment** (template below), wait **48h**, then reclaim if no response    |
-| ❓ NEEDS DETAIL | ≥15 days since last comment by the issue author                    | Post **gentle nudge** (template below), wait **48h**, then reclaim as VIABLE if no response         |
-
-**Intent-to-take-over comment (🚧 IN FLIGHT path)** — translate to `reply_lang`:
-
-```markdown
-Hi @<pr_author> and @<issue_author>! 👋
-
-This PR (#<PR>) addressing issue #<NUMBER> hasn't had updates in <N> days. We'd love to ship this feature in our next release.
-
-**Plan:** if there are no updates in the next **48 hours**, our team will take over the work and merge it as part of `release/vX.Y.Z`. The original PR will be referenced and authorship preserved in the commit trailer.
-
-If you're still working on it, just drop a comment here and we'll hold off. Thanks for the contribution either way! 🙏
-```
-
-**Gentle nudge (❓ NEEDS DETAIL path)** — translate to `reply_lang`:
-
-```markdown
-Hi @<author>! 👋
-
-It's been <N> days since we asked for more details on this feature request. We'd still love to move forward.
-
-**Plan:** if we don't hear back in the next **48 hours**, we'll proceed with our best interpretation of the original request and add it to our backlog for implementation. We'll tag you on the implementation PR so you can review before it ships.
-
-If you still want to provide the details, just reply here — we'll wait. 🙏
-```
-
-**Reclaim execution** (only after the 48h grace period, with no new author/PR-author activity):
-
-1. Move the idea file to `_ideia/viable/` (preserve any prior content + add a `> ♻️ Reclaimed on <date> after 15-day inactivity` banner near the top).
-2. If it was IN FLIGHT and a research file does not yet exist, run Phase 2 (Research) for it now.
-3. Otherwise create the requirements file based on the existing content + a quick research pass.
-4. Add a `viable_origin: stale_reclaim` line to the front-matter so the Phase 3 report can flag it.
-5. In Phase 5 (commit / PR), include a commit trailer crediting the original PR author if applicable:
-   ```
-   Originally-proposed-by: @<pr_author> in #<original_pr_number>
-   ```
-   (This is NOT `Co-Authored-By` — hard rule #16 still applies. It is a free-form trailer that preserves credit without GitHub re-attributing the commit.)
-
-> **Why 15 days + 48h grace?** Long enough that the original contributor has truly moved on; short enough that the feature still ships in the same release cycle. Grace period is documented in `feedback_issue_triage_independence` so we don't default to "trust prior triage" — we verify the silence is real.
-
----
-
-## Phase 2 — Research: Find Solutions & Build Requirements
-
-For each cataloged idea that is **viable** (aligns with the project's goals) AND not already in flight (per 1.6):
-
-### 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   |
-| 🚧 **IN FLIGHT**      | PR/branch already exists (from 1.6)   | Skip — track only           |
-
-### 2.2 Internet Research (for VIABLE features)
-
-For each viable feature, perform systematic research with an **early-stopping criterion**:
-
-> **Stop as soon as EITHER condition is met:**
-> - 3 reference implementations show a consistent pattern, OR
-> - 1 high-quality repo (≥1k stars, updated within the last 12 months) already solves the problem cleanly.
->
-> Cap at 10 repos total. Do NOT exhaustively browse — depth over breadth.
-
-**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")
-```
-
-- Sort by most recently updated.
-- For each repository (until stop criterion hit):
-  - 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: Sort Files into Category Directories
-
-> **⚠️ This phase only moves files. It does NOT post comments or close issues.** All GitHub-visible actions are deferred to Phase 3.2 (after human approval).
-
-### 2.5.1 Create Directory Structure
-
-// turbo
-
-```bash
-mkdir -p <project_root>/_ideia/viable
-mkdir -p <project_root>/_ideia/implemented
-mkdir -p <project_root>/_ideia/need_details
-mkdir -p <project_root>/_ideia/defer
-mkdir -p <project_root>/_ideia/notfit
-mkdir -p <project_root>/_ideia/exists
-mkdir -p <project_root>/_ideia/in_flight
-```
-
-> **Permanent archives**: `need_details/`, `defer/`, `notfit/`, `exists/`, `in_flight/`. Even after the upstream issue is closed, the local file stays — future cycles may revisit.
-
-### 2.5.2 Move Idea Files to Category Subdirectories
-
-After classification, move EVERY idea file to its correct subdirectory (still local-only — no GitHub side-effects):
-
-```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 (issue stays OPEN)
-mv _ideia/<NUMBER>-*.md _ideia/need_details/
-
-# ⏭️ DEFER — issue will be CLOSED but file is kept permanently for future re-evaluation
-mv _ideia/<NUMBER>-*.md _ideia/defer/
-
-# ❌ NOT FIT — issue will be CLOSED but file is kept permanently
-mv _ideia/<NUMBER>-*.md _ideia/notfit/
-
-# 🔁 ALREADY EXISTS — issue will be CLOSED but file is kept permanently (separate bucket from NOT FIT)
-mv _ideia/<NUMBER>-*.md _ideia/exists/
-
-# 🚧 IN FLIGHT — issue stays OPEN, third-party PR is handling it; file kept permanently for Phase 1.7 stale-reclaim
-mv _ideia/<NUMBER>-*.md _ideia/in_flight/
-```
-
-No idea files should remain in `_ideia/` root after this step.
-
----
-
-## Phase 3 — Report: Present Findings & Get Human Approval
-
-### 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. **No comments have been posted to GitHub yet** — that happens in 3.2 after approval.
-
-Present a structured report containing:
-
-#### 3.1a — Feature Summary Table
-
-| #   | Issue | Title | Verdict           | Local Location          | Planned GitHub Action                  |
-| --- | ----- | ----- | ----------------- | ----------------------- | -------------------------------------- |
-| 1   | #N    | Title | ✅ VIABLE         | `_ideia/viable/`        | Comment + keep OPEN                    |
-| 2   | #N    | Title | ⏭️ DEFER          | `_ideia/defer/`         | Comment + CLOSE                        |
-| 3   | #N    | Title | ❌ NOT FIT        | `_ideia/notfit/`        | Comment + CLOSE                        |
-| 4   | #N    | Title | 🔁 EXISTS         | `_ideia/exists/`        | Comment with location + CLOSE          |
-| 5   | #N    | Title | ❓ NEEDS DETAIL   | `_ideia/need_details/`  | Comment with questions + keep OPEN     |
-| 6   | #N    | Title | 🚧 IN FLIGHT      | `_ideia/in_flight/`     | None — PR #M handles it                |
-| 7   | #N    | Title | ♻️ RECLAIMED      | `_ideia/viable/`        | Intent comment posted in Phase 1.7     |
-
-#### 3.1b — Viable Features Detail
-
-For each VIABLE feature, provide a brief paragraph:
-
-- What was found during research (with stop reason: "3-pattern consistency" or "dominant repo")
-- 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
-- Detected `reply_lang` for the question post
-
-#### 3.1d — Ask for User Confirmation
-
-End the report with:
-
-> **Ready to proceed?**
->
-> Approving will (a) post comments on GitHub in the detected language of each issue and (b) close DEFER / NOT FIT / EXISTS issues. VIABLE and NEEDS DETAIL stay open.
->
-> - Reply **"sim"** / **"yes"** to post all comments AND generate implementation plans for all VIABLE features.
-> - Reply **"only comments"** to post comments without generating plans yet.
-> - Reply with specific issue numbers to scope the action.
-> - Reply **"não"** / **"no"** to stop without touching GitHub.
-
-### 3.2 Post GitHub Comments & Close Issues (only after approval)
-
-> **⚠️ Do NOT execute this step without explicit user approval from 3.1d.**
-
-For each issue, translate the appropriate template below into the `reply_lang` recorded in its idea file front-matter, then post. The English templates are reference only — never post the English version verbatim to a non-English issue.
-
----
-
-#### For 🔁 ALREADY EXISTS — Comment + CLOSE issue
-
-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 "<translated comment>"
-```
-
----
-
-#### For ⏭️ DEFER — Comment + CLOSE issue
-
-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
-
-If you want to track progress, please **subscribe to the repository releases** — every implemented feature is announced in the CHANGELOG.
-
-Thank you for contributing to OmniRoute's roadmap! 🚀
-```
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<translated comment>"
-```
-
----
-
-#### For ❌ NOT FIT — Comment + CLOSE issue (soft-archive)
-
-Politely explain the current limitation, but make clear the idea is **archived, not discarded**. If the situation changes (provider opens a public API, scope shifts, etc.), we revisit and tag the author.
-
-```markdown
-Hi @<author>! Thanks for the suggestion! 🙏
-
-After researching, we've determined this feature isn't viable right now:
-
-**Reason:** <explain why — e.g., "CodeBuddy has no public API; YepApi is fronted by Cloudflare bot detection that we won't evade.">
-
-**Alternative:** <suggest an alternative if one exists, otherwise omit this line>
-
-That said, **we've saved your suggestion** to our internal archive rather than discarding it. If circumstances change (a public API is released, the provider opens up, our scope shifts, etc.), we'll revisit it and tag you here.
-
-Closing for now, but the idea isn't lost — we'll let you know if things change. 🙏
-```
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<translated comment>"
-```
-
----
-
-#### For ❓ NEEDS DETAIL — Comment (keep OPEN)
-
-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 + CLOSE issue (cataloged for future implementation)
-
-When we **know how to implement** the feature, we accept + catalog + close the issue right away (to keep the open-issue list focused on items still awaiting input). A separate post-implementation comment will reopen the conversation later when code ships. Include a 1-2 sentence summary of what we plan to build so the author knows we understood the request.
-
-```markdown
-Hi @<author>! Thanks for the great feature suggestion! 🙏
-
-We've analyzed your request — it aligns with OmniRoute's roadmap and we have a clear implementation path:
-
-> <one to two sentence summary of what we plan to build>
-
-We've **cataloged it internally** and it will be picked up in an upcoming release.
-
-**Status:** ✅ Accepted — cataloged for future implementation
-
-We'll respond here and tag you once the implementation lands so you can test it before it ships.
-
-Closing for now to keep our open-issue list focused on items still awaiting input. The feature is tracked in our internal backlog and won't be forgotten.
-
-Thank you for helping improve OmniRoute! 🚀
-```
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<translated comment>"
-```
-
-**⚠️ Important**: The VIABLE comment **CLOSES** the issue. When implementation ships later, Phase 5.4 will REOPEN the issue, post the implementation comment, and CLOSE it again. The author still gets the @-mention notification.
-
----
-
-## Phase 4 — Plan: Generate Implementation Plans (after user says "yes")
-
-> **⚠️ Do NOT enter this phase without explicit user approval from Phase 3.**
-
-### 4.1 Pre-Plan Context Load (mandatory)
-
-Before writing ANY plan, read:
-
-1. `docs/architecture/REPOSITORY_MAP.md` — to know which directory owns what.
-2. `docs/architecture/CODEBASE_DOCUMENTATION.md` — for the engineering reference.
-3. The matching "Adding a New X" scenario from `CLAUDE.md` (provider, API route, DB module, MCP tool, A2A skill, cloud agent, embedded service, guardrail, eval, skill, webhook event).
-4. Any docs linked from the requirements file's "External References" section.
-
-This ensures plans cite real paths and follow the established add-a-X recipe, instead of inventing structure.
-
-### 4.2 Create Task Directory
-
-```bash
-mkdir -p <project_root>/_tasks/features-vX.Y.Z/
-```
-
-### 4.3 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`
-> Matching CLAUDE.md recipe: <e.g. "Adding a New Provider">
-
-## 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 (re-run Phase 1.6 lookup)
-- [ ] Verify database migration numbering (next free integer in `src/lib/db/migrations/`)
-
-## 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 (MANDATORY per CLAUDE.md hard rule #8)
-
-**New test files:**
-
-- `tests/unit/<test-file>.test.mjs` — <what to test>
-
-**Test cases:**
-
-- [ ] <test case 1>
-- [ ] <test case 2>
-- [ ] Coverage check: confirm overall coverage stays ≥75% statements/lines/functions, ≥70% branches (hard rule #9)
-
-### Step N+1: i18n
-
-**Translation keys to add:**
-
-- `<namespace>.<key>` — "<English value>"
-
-### Step N+2: Documentation
-
-- [ ] Update CHANGELOG.md (current release section)
-- [ ] Update relevant docs/ files
-- [ ] If touching error responses, follow `docs/security/ERROR_SANITIZATION.md`
-- [ ] If touching upstream credentials, follow `docs/security/PUBLIC_CREDS.md`
-
-## Verification Plan (Trust-but-Verify — mandatory before declaring done)
-
-1. `git status` + `git diff --stat` — review every changed file; flag anything outside the plan's declared scope
-2. `npm run lint` — 0 new errors
-3. `npm run typecheck:core` — clean
-4. `npm run typecheck:noimplicit:core` — clean
-5. `npm run check:cycles` — no new circular deps
-6. `npm run build` — must pass
-7. `npm run test:coverage` — coverage gate respected
-8. `npm run check-docs-sync` (via pre-commit hook) — passes
-9. Manual UI verification if the feature touches frontend (start dev server, exercise golden path + 1 edge case)
-
-## Commit Plan
-
-```
-feat: <description> (#<NUMBER>)
-```
-```
-
-### 4.4 Present Plans for Final Approval
-
-Present a summary of all generated plans:
-
-> **Implementation plans generated:**
->
-> | #   | Feature | Plan File                                | Steps   | Effort | CLAUDE.md recipe       |
-> | --- | ------- | ---------------------------------------- | ------- | ------ | ---------------------- |
-> | 1   | <title> | `_tasks/features-vX.Y.Z/N-title.plan.md` | N steps | Medium | Adding a New Provider  |
->
-> Reply **"sim"** / **"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. **Mark progress** — flip checkboxes to `[x]` in the plan as each step completes
-
-### 5.2 Trust-but-Verify Audit (mandatory before commit)
-
-> Aligned with `~/.claude/CLAUDE.md` global rule: never trust a subagent's summary alone.
-
-Run the full audit checklist from the plan's "Verification Plan" section AND inspect the diff yourself:
-
-```bash
-git status
-git diff --stat
-git diff                       # full diff, scan for out-of-scope changes
-npm run lint
-npm run typecheck:core
-npm run typecheck:noimplicit:core
-npm run check:cycles
-npm run build
-npm run test:coverage
-```
-
-**Block-on-failure checklist:**
-
-- [ ] No files changed outside the plan's declared scope (or scope expansion explicitly justified)
-- [ ] No deleted symbols/routes/files without a documented replacement (grep to confirm)
-- [ ] No weakened or removed test assertions (only additions or alignments with real behavior)
-- [ ] Coverage gate green (75/75/75/70)
-- [ ] All commands above exit 0
-- [ ] If UI was touched: manual smoke test passed and noted
-
-If any item fails, **fix root cause** before committing. Do NOT bypass with `--no-verify` (hard rule #10).
-
-### 5.3 Commit (one feature, one commit)
-
-```bash
-git add <only files in the plan>
-git commit -m "feat: <description> (#<NUMBER>)"
-```
-
-> **No `Co-Authored-By` trailers** (hard rule #16). Commits go solely under `diegosouzapw`.
-
-Then move (do NOT delete yet) the idea file to `_ideia/implemented/`:
-
-```bash
-mv _ideia/viable/<NUMBER>-<title>.md _ideia/implemented/
-mv _ideia/viable/<NUMBER>-<title>.requirements.md _ideia/implemented/ 2>/dev/null || true
-```
-
-> **Why move, not delete?** If the release PR is reverted or rebased, we still have the context. The file is deleted only after the PR merges to `main` (see 5.6).
-
-Continue to the next feature on the same branch — do NOT switch branches between features.
-
-### 5.4 Respond to Authors
-
-For each implemented feature, post a final close-comment **translated into the issue's `reply_lang`**:
-
-```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 (after the release PR merges):**
-
-```bash
-git fetch origin && git checkout main && git pull
-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 "<translated comment>"
-```
-
-### 5.5 Finalize the Release Branch
-
-After implementing all approved features:
-
-1. **Update CHANGELOG.md** on the release branch with all new feature entries
-2. Push: `git push origin release/vX.Y.Z`
-3. Hand off to `/generate-release` for the "Tests → Commit → Push → PR to main" stage. Refer to it **by stage name**, not step number, so this command does not break if `/generate-release` renumbers steps.
-
-### 5.6 Post-Merge Cleanup (only after release PR merges to main)
-
-Once the release PR is merged:
-
-```bash
-# Now safe to delete — commit history + CHANGELOG are the source of truth
-rm _ideia/implemented/<NUMBER>-*.md
-```
-
-> If running this command before the merge: STOP at 5.5 and skip 5.6. Re-enter the workflow later just for the cleanup.
-
-### 5.7 Final Summary Report
-
-Present a final summary report to the user:
-
-| Issue | Title | Verdict          | Action                                                          | Commit    |
-| ----- | ----- | ---------------- | --------------------------------------------------------------- | --------- |
-| #N    | Title | ✅ Implemented   | Issue closed, idea file in `_ideia/implemented/` (until merge)  | `abc1234` |
-| #N    | Title | ♻️ Reclaimed     | Was IN FLIGHT / NEEDS DETAIL, reclaimed after 15d → implemented | `abc1234` |
-| #N    | Title | ⏭️ Deferred      | Issue closed + permanent archive in `_ideia/defer/`             | —         |
-| #N    | Title | ❌ Not Fit       | Issue closed + permanent archive in `_ideia/notfit/`            | —         |
-| #N    | Title | 🔁 Exists        | Issue closed + permanent archive in `_ideia/exists/`            | —         |
-| #N    | Title | ❓ Needs Detail  | Issue OPEN, archive in `_ideia/need_details/`                   | —         |
-| #N    | Title | 🚧 In Flight     | Issue OPEN, archive in `_ideia/in_flight/`, tracked by PR #M    | —         |
-
-Include:
-
-- Total features harvested
-- Total ideas archived per bucket (`need_details/` / `defer/` / `notfit/` / `exists/` / `in_flight/`)
-- Total features implemented (idea files in `_ideia/implemented/`, awaiting post-merge cleanup)
-- Total reclaimed via Phase 1.7 (stale 15-day rule)
-- Total issues closed
-- Total issues left open (NEEDS DETAIL + VIABLE-pending + IN FLIGHT)
-- Audit results: lint / typecheck / cycles / build / coverage (pass-count per phase)
-- Languages used in posted comments (e.g. "3× pt-BR, 5× en, 1× es")

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

@@ -1,899 +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 (Phase 3 and Phase 4 → 5) 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.
-- The trust-but-verify audit in Phase 5.2 is mandatory before any commit — full lint + typecheck + cycles + build + coverage, plus a real `git diff` review for out-of-scope changes.
-- Phase 1.7 stale-reclaim (15-day rule) is opt-in per run: only execute when the user asks for a "reclaim pass" or when the harvest report explicitly flags eligible IN FLIGHT / NEEDS DETAIL items.
-
-**Output directory structure:**
-
-```
-_ideia/
-├── viable/                  # ✅ Approved, awaiting implementation
-│   ├── 1046-native-playground.md
-│   └── 1046-native-playground.requirements.md
-├── implemented/             # ✅ Implemented but release PR not yet merged to main (transient)
-│   └── 1046-native-playground.md
-├── need_details/            # ❓ Issue OPEN — awaiting author clarification (permanent archive)
-│   └── 1015-warp-terminal-mitm.md
-├── defer/                   # ⏭️ Issue CLOSED — good idea, deferred for future cycles (permanent)
-│   └── 1041-smart-auto-combos.md
-├── notfit/                  # ❌ Issue CLOSED — out of scope (permanent)
-│   └── 945-telegram-integration.md
-├── exists/                  # 🔁 Issue CLOSED — feature already shipped (permanent, kept separate from notfit)
-│   └── 812-rate-limit-dashboard.md
-└── in_flight/               # 🚧 Issue OPEN — third-party PR already addresses it (permanent until reclaim or merge)
-    └── 988-batch-export.md
-
-_tasks/features-vX.Y.Z/   # Implementation plans (per-release)
-└── 1046-native-playground.plan.md
-```
-
-> **LIFECYCLE RULE:**
-> - `viable/` files are **MOVED** to `implemented/` once code lands on the release branch.
-> - `implemented/` files are **DELETED** only after the release PR is merged to `main`.
-> - All other buckets — `need_details/`, `defer/`, `notfit/`, `exists/`, `in_flight/` — are **permanent archives**. Even when the upstream issue is CLOSED, the local file stays. Future cycles can revisit any of them (Phase 1.7 stale-reclaim turns `in_flight/` and `need_details/` back into VIABLE after 15 days of upstream inactivity).
-> - This preserves recovery context if implementation fails partially AND lets us re-evaluate old decisions when the project matures.
-
-> **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, delegate creation to `/generate-release` (see Phase 1.2) — do NOT reimplement bump logic here.
-
-> **LANGUAGE RULE** (per `feedback_reply_language` memory): GitHub comments MUST match the language of the original issue body. Detect language by sampling the issue body + first 2 comments. Default to English when uncertain. All comment templates below are in English — translate to the detected language before posting. Internal docs, plan files, and idea files stay in English regardless.
-
----
-
-## 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
-
-Before doing any work, ensure you are on the current release branch:
-
-```bash
-git branch --show-current
-```
-
-**Decision tree:**
-
-- If already on a `release/vX.Y.Z` branch → continue working there.
-- If on `main` or any other branch → **delegate to `/generate-release`** by invoking its Phase 1 (steps 1–5: detect current version, bump, create branch, install). Do NOT reimplement the bump formula here — `/generate-release` owns the canonical version policy (patch bumps allowed up to `.999`; minor bump only when patch reaches `999`).
-
-> **Why delegate?** Duplicating the bump formula caused divergence in the past. `/generate-release` is the single source of truth for version arithmetic and now allows patches up to `.999` before bumping minor.
-
-### 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.
-- If the count hits the `--limit 500` ceiling, raise the limit and re-run — never proceed with a truncated set.
-
-**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`), **download and analyze them with the Read tool** (Claude can read PNG/JPG/GIF directly). Mockups and wireframes are often the most informative artifact — do NOT just "note" them, actually inspect their content and incorporate findings into the refined description.
-- **Detect issue language** from body + first 2 comments and record it in the idea file front-matter (`reply_lang: pt-BR | en | es | ...`). This will drive comment translation in Phases 2.5 and 5.
-- 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
----
-reply_lang: <detected-lang, e.g. pt-BR | en | es>
----
-
-# 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>
-
-## 🖼️ Mockup / Image Analysis
-
-<For each image embedded in the issue, summarize what it depicts: UI layout, data flow, architecture diagram, etc. Cite source URL.>
-
-## 🎯 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.
-- Re-detect `reply_lang` only if the issue language clearly changed (uncommon).
-- **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.`
-
-### 1.6 Detect In-Flight Work (avoid duplicate effort)
-
-For each issue number, check whether an open PR or branch already targets it:
-
-```bash
-# Open PRs that link the issue
-gh pr list --repo <owner>/<repo> --state open --search "linked:#<NUMBER>" --json number,title,headRefName,updatedAt,author
-
-# Local branches that mention the issue number
-git branch -a | grep -E "(^|/)(feat|fix|refactor)/.*-?<NUMBER>(-|$)" || true
-```
-
-If a PR or branch already exists:
-
-- Mark the idea file with `> ⚠️ In-flight: PR #<PR_NUMBER> by @<author> / branch <name> (last activity <date>)` near the top.
-- **Skip Phase 2 research and Phase 4 planning** for this feature — the implementation is already in motion.
-- In the Phase 3 report, list it under a separate "🚧 Already in progress" bucket; do NOT count it as VIABLE for implementation.
-- The idea file will be moved to `_ideia/in_flight/` in Phase 2.5.2 (it stays there permanently, but Phase 1.7 may reclaim it later).
-
-### 1.7 Stale Reclaim (15-day rule)
-
-Some issues sit in `in_flight/` or `need_details/` forever — third-party PRs go cold, authors disappear, the world moves on. This phase reclaims them when they go quiet.
-
-**Trigger conditions** (run for each issue currently in `_ideia/in_flight/` or `_ideia/need_details/`):
-
-```bash
-# For IN FLIGHT — last activity on the linked PR (commit OR comment)
-gh pr view <PR_NUMBER> --repo <owner>/<repo> --json updatedAt,commits,comments \
-  --jq '[.updatedAt, (.commits[-1].committedDate // ""), (.comments[-1].createdAt // "")] | max'
-
-# For NEEDS DETAIL — last activity from the issue author (any comment by them)
-gh issue view <NUMBER> --repo <owner>/<repo> --json comments,author \
-  --jq '.author.login as $a | [.comments[] | select(.author.login == $a) | .createdAt] | max // (.createdAt)'
-```
-
-Compute the gap in days between the timestamp above and today.
-
-**Reclaim rule:**
-
-| Bucket          | Trigger                                                            | Action                                                                                              |
-| --------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
-| 🚧 IN FLIGHT    | ≥15 days since last PR activity (commit OR comment by PR author)   | Post **intent-to-take-over comment** (template below), wait **48h**, then reclaim if no response    |
-| ❓ NEEDS DETAIL | ≥15 days since last comment by the issue author                    | Post **gentle nudge** (template below), wait **48h**, then reclaim as VIABLE if no response         |
-
-**Intent-to-take-over comment (🚧 IN FLIGHT path)** — translate to `reply_lang`:
-
-```markdown
-Hi @<pr_author> and @<issue_author>! 👋
-
-This PR (#<PR>) addressing issue #<NUMBER> hasn't had updates in <N> days. We'd love to ship this feature in our next release.
-
-**Plan:** if there are no updates in the next **48 hours**, our team will take over the work and merge it as part of `release/vX.Y.Z`. The original PR will be referenced and authorship preserved in the commit trailer.
-
-If you're still working on it, just drop a comment here and we'll hold off. Thanks for the contribution either way! 🙏
-```
-
-**Gentle nudge (❓ NEEDS DETAIL path)** — translate to `reply_lang`:
-
-```markdown
-Hi @<author>! 👋
-
-It's been <N> days since we asked for more details on this feature request. We'd still love to move forward.
-
-**Plan:** if we don't hear back in the next **48 hours**, we'll proceed with our best interpretation of the original request and add it to our backlog for implementation. We'll tag you on the implementation PR so you can review before it ships.
-
-If you still want to provide the details, just reply here — we'll wait. 🙏
-```
-
-**Reclaim execution** (only after the 48h grace period, with no new author/PR-author activity):
-
-1. Move the idea file to `_ideia/viable/` (preserve any prior content + add a `> ♻️ Reclaimed on <date> after 15-day inactivity` banner near the top).
-2. If it was IN FLIGHT and a research file does not yet exist, run Phase 2 (Research) for it now.
-3. Otherwise create the requirements file based on the existing content + a quick research pass.
-4. Add a `viable_origin: stale_reclaim` line to the front-matter so the Phase 3 report can flag it.
-5. In Phase 5 (commit / PR), include a commit trailer crediting the original PR author if applicable:
-   ```
-   Originally-proposed-by: @<pr_author> in #<original_pr_number>
-   ```
-   (This is NOT `Co-Authored-By` — hard rule #16 still applies. It is a free-form trailer that preserves credit without GitHub re-attributing the commit.)
-
-> **Why 15 days + 48h grace?** Long enough that the original contributor has truly moved on; short enough that the feature still ships in the same release cycle. Grace period is documented in `feedback_issue_triage_independence` so we don't default to "trust prior triage" — we verify the silence is real.
-
----
-
-## Phase 2 — Research: Find Solutions & Build Requirements
-
-For each cataloged idea that is **viable** (aligns with the project's goals) AND not already in flight (per 1.6):
-
-### 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   |
-| 🚧 **IN FLIGHT**      | PR/branch already exists (from 1.6)   | Skip — track only           |
-
-### 2.2 Internet Research (for VIABLE features)
-
-For each viable feature, perform systematic research with an **early-stopping criterion**:
-
-> **Stop as soon as EITHER condition is met:**
-> - 3 reference implementations show a consistent pattern, OR
-> - 1 high-quality repo (≥1k stars, updated within the last 12 months) already solves the problem cleanly.
->
-> Cap at 10 repos total. Do NOT exhaustively browse — depth over breadth.
-
-**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")
-```
-
-- Sort by most recently updated.
-- For each repository (until stop criterion hit):
-  - 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: Sort Files into Category Directories
-
-> **⚠️ This phase only moves files. It does NOT post comments or close issues.** All GitHub-visible actions are deferred to Phase 3.2 (after human approval).
-
-### 2.5.1 Create Directory Structure
-
-// turbo
-
-```bash
-mkdir -p <project_root>/_ideia/viable
-mkdir -p <project_root>/_ideia/implemented
-mkdir -p <project_root>/_ideia/need_details
-mkdir -p <project_root>/_ideia/defer
-mkdir -p <project_root>/_ideia/notfit
-mkdir -p <project_root>/_ideia/exists
-mkdir -p <project_root>/_ideia/in_flight
-```
-
-> **Permanent archives**: `need_details/`, `defer/`, `notfit/`, `exists/`, `in_flight/`. Even after the upstream issue is closed, the local file stays — future cycles may revisit.
-
-### 2.5.2 Move Idea Files to Category Subdirectories
-
-After classification, move EVERY idea file to its correct subdirectory (still local-only — no GitHub side-effects):
-
-```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 (issue stays OPEN)
-mv _ideia/<NUMBER>-*.md _ideia/need_details/
-
-# ⏭️ DEFER — issue will be CLOSED but file is kept permanently for future re-evaluation
-mv _ideia/<NUMBER>-*.md _ideia/defer/
-
-# ❌ NOT FIT — issue will be CLOSED but file is kept permanently
-mv _ideia/<NUMBER>-*.md _ideia/notfit/
-
-# 🔁 ALREADY EXISTS — issue will be CLOSED but file is kept permanently (separate bucket from NOT FIT)
-mv _ideia/<NUMBER>-*.md _ideia/exists/
-
-# 🚧 IN FLIGHT — issue stays OPEN, third-party PR is handling it; file kept permanently for Phase 1.7 stale-reclaim
-mv _ideia/<NUMBER>-*.md _ideia/in_flight/
-```
-
-No idea files should remain in `_ideia/` root after this step.
-
----
-
-## Phase 3 — Report: Present Findings & Get Human Approval
-
-### 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. **No comments have been posted to GitHub yet** — that happens in 3.2 after approval.
-
-Present a structured report containing:
-
-#### 3.1a — Feature Summary Table
-
-| #   | Issue | Title | Verdict           | Local Location          | Planned GitHub Action                  |
-| --- | ----- | ----- | ----------------- | ----------------------- | -------------------------------------- |
-| 1   | #N    | Title | ✅ VIABLE         | `_ideia/viable/`        | Comment + keep OPEN                    |
-| 2   | #N    | Title | ⏭️ DEFER          | `_ideia/defer/`         | Comment + CLOSE                        |
-| 3   | #N    | Title | ❌ NOT FIT        | `_ideia/notfit/`        | Comment + CLOSE                        |
-| 4   | #N    | Title | 🔁 EXISTS         | `_ideia/exists/`        | Comment with location + CLOSE          |
-| 5   | #N    | Title | ❓ NEEDS DETAIL   | `_ideia/need_details/`  | Comment with questions + keep OPEN     |
-| 6   | #N    | Title | 🚧 IN FLIGHT      | `_ideia/in_flight/`     | None — PR #M handles it                |
-| 7   | #N    | Title | ♻️ RECLAIMED      | `_ideia/viable/`        | Intent comment posted in Phase 1.7     |
-
-#### 3.1b — Viable Features Detail
-
-For each VIABLE feature, provide a brief paragraph:
-
-- What was found during research (with stop reason: "3-pattern consistency" or "dominant repo")
-- 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
-- Detected `reply_lang` for the question post
-
-#### 3.1d — Ask for User Confirmation
-
-End the report with:
-
-> **Ready to proceed?**
->
-> Approving will (a) post comments on GitHub in the detected language of each issue and (b) close DEFER / NOT FIT / EXISTS issues. VIABLE and NEEDS DETAIL stay open.
->
-> - Reply **"sim"** / **"yes"** to post all comments AND generate implementation plans for all VIABLE features.
-> - Reply **"only comments"** to post comments without generating plans yet.
-> - Reply with specific issue numbers to scope the action.
-> - Reply **"não"** / **"no"** to stop without touching GitHub.
-
-### 3.2 Post GitHub Comments & Close Issues (only after approval)
-
-> **⚠️ Do NOT execute this step without explicit user approval from 3.1d.**
-
-For each issue, translate the appropriate template below into the `reply_lang` recorded in its idea file front-matter, then post. The English templates are reference only — never post the English version verbatim to a non-English issue.
-
----
-
-#### For 🔁 ALREADY EXISTS — Comment + CLOSE issue
-
-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 "<translated comment>"
-```
-
----
-
-#### For ⏭️ DEFER — Comment + CLOSE issue
-
-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
-
-If you want to track progress, please **subscribe to the repository releases** — every implemented feature is announced in the CHANGELOG.
-
-Thank you for contributing to OmniRoute's roadmap! 🚀
-```
-
-```bash
-gh issue close <NUMBER> --repo <owner>/<repo> --comment "<translated comment>"
-```
-
----
-
-#### For ❌ NOT FIT — Comment + CLOSE issue
-
-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 "<translated comment>"
-```
-
----
-
-#### For ❓ NEEDS DETAIL — Comment (keep OPEN)
-
-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)
-
-Thank the user, confirm we've cataloged their idea, and explain that progress is tracked in releases.
-
-```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 issue will be **closed automatically by the merge commit** when the feature ships. To follow along, you can subscribe to repository releases or watch this issue.
-
-Thank you for helping improve OmniRoute! 🚀
-```
-
-**⚠️ Do NOT close viable issues — they remain OPEN until the implementation PR closes them via commit message.**
-
----
-
-## Phase 4 — Plan: Generate Implementation Plans (after user says "yes")
-
-> **⚠️ Do NOT enter this phase without explicit user approval from Phase 3.**
-
-### 4.1 Pre-Plan Context Load (mandatory)
-
-Before writing ANY plan, read:
-
-1. `docs/architecture/REPOSITORY_MAP.md` — to know which directory owns what.
-2. `docs/architecture/CODEBASE_DOCUMENTATION.md` — for the engineering reference.
-3. The matching "Adding a New X" scenario from `CLAUDE.md` (provider, API route, DB module, MCP tool, A2A skill, cloud agent, embedded service, guardrail, eval, skill, webhook event).
-4. Any docs linked from the requirements file's "External References" section.
-
-This ensures plans cite real paths and follow the established add-a-X recipe, instead of inventing structure.
-
-### 4.2 Create Task Directory
-
-```bash
-mkdir -p <project_root>/_tasks/features-vX.Y.Z/
-```
-
-### 4.3 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`
-> Matching CLAUDE.md recipe: <e.g. "Adding a New Provider">
-
-## 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 (re-run Phase 1.6 lookup)
-- [ ] Verify database migration numbering (next free integer in `src/lib/db/migrations/`)
-
-## 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 (MANDATORY per CLAUDE.md hard rule #8)
-
-**New test files:**
-
-- `tests/unit/<test-file>.test.mjs` — <what to test>
-
-**Test cases:**
-
-- [ ] <test case 1>
-- [ ] <test case 2>
-- [ ] Coverage check: confirm overall coverage stays ≥75% statements/lines/functions, ≥70% branches (hard rule #9)
-
-### Step N+1: i18n
-
-**Translation keys to add:**
-
-- `<namespace>.<key>` — "<English value>"
-
-### Step N+2: Documentation
-
-- [ ] Update CHANGELOG.md (current release section)
-- [ ] Update relevant docs/ files
-- [ ] If touching error responses, follow `docs/security/ERROR_SANITIZATION.md`
-- [ ] If touching upstream credentials, follow `docs/security/PUBLIC_CREDS.md`
-
-## Verification Plan (Trust-but-Verify — mandatory before declaring done)
-
-1. `git status` + `git diff --stat` — review every changed file; flag anything outside the plan's declared scope
-2. `npm run lint` — 0 new errors
-3. `npm run typecheck:core` — clean
-4. `npm run typecheck:noimplicit:core` — clean
-5. `npm run check:cycles` — no new circular deps
-6. `npm run build` — must pass
-7. `npm run test:coverage` — coverage gate respected
-8. `npm run check-docs-sync` (via pre-commit hook) — passes
-9. Manual UI verification if the feature touches frontend (start dev server, exercise golden path + 1 edge case)
-
-## Commit Plan
-
-```
-feat: <description> (#<NUMBER>)
-```
-```
-
-### 4.4 Present Plans for Final Approval
-
-Present a summary of all generated plans:
-
-> **Implementation plans generated:**
->
-> | #   | Feature | Plan File                                | Steps   | Effort | CLAUDE.md recipe       |
-> | --- | ------- | ---------------------------------------- | ------- | ------ | ---------------------- |
-> | 1   | <title> | `_tasks/features-vX.Y.Z/N-title.plan.md` | N steps | Medium | Adding a New Provider  |
->
-> Reply **"sim"** / **"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. **Mark progress** — flip checkboxes to `[x]` in the plan as each step completes
-
-### 5.2 Trust-but-Verify Audit (mandatory before commit)
-
-> Aligned with `~/.claude/CLAUDE.md` global rule: never trust a subagent's summary alone.
-
-Run the full audit checklist from the plan's "Verification Plan" section AND inspect the diff yourself:
-
-```bash
-git status
-git diff --stat
-git diff                       # full diff, scan for out-of-scope changes
-npm run lint
-npm run typecheck:core
-npm run typecheck:noimplicit:core
-npm run check:cycles
-npm run build
-npm run test:coverage
-```
-
-**Block-on-failure checklist:**
-
-- [ ] No files changed outside the plan's declared scope (or scope expansion explicitly justified)
-- [ ] No deleted symbols/routes/files without a documented replacement (grep to confirm)
-- [ ] No weakened or removed test assertions (only additions or alignments with real behavior)
-- [ ] Coverage gate green (75/75/75/70)
-- [ ] All commands above exit 0
-- [ ] If UI was touched: manual smoke test passed and noted
-
-If any item fails, **fix root cause** before committing. Do NOT bypass with `--no-verify` (hard rule #10).
-
-### 5.3 Commit (one feature, one commit)
-
-```bash
-git add <only files in the plan>
-git commit -m "feat: <description> (#<NUMBER>)"
-```
-
-> **No `Co-Authored-By` trailers** (hard rule #16). Commits go solely under `diegosouzapw`.
-
-Then move (do NOT delete yet) the idea file to `_ideia/implemented/`:
-
-```bash
-mv _ideia/viable/<NUMBER>-<title>.md _ideia/implemented/
-mv _ideia/viable/<NUMBER>-<title>.requirements.md _ideia/implemented/ 2>/dev/null || true
-```
-
-> **Why move, not delete?** If the release PR is reverted or rebased, we still have the context. The file is deleted only after the PR merges to `main` (see 5.6).
-
-Continue to the next feature on the same branch — do NOT switch branches between features.
-
-### 5.4 Respond to Authors
-
-For each implemented feature, post a final close-comment **translated into the issue's `reply_lang`**:
-
-```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 (after the release PR merges):**
-
-```bash
-git fetch origin && git checkout main && git pull
-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 "<translated comment>"
-```
-
-### 5.5 Finalize the Release Branch
-
-After implementing all approved features:
-
-1. **Update CHANGELOG.md** on the release branch with all new feature entries
-2. Push: `git push origin release/vX.Y.Z`
-3. Hand off to `/generate-release` for the "Tests → Commit → Push → PR to main" stage. Refer to it **by stage name**, not step number, so this command does not break if `/generate-release` renumbers steps.
-
-### 5.6 Post-Merge Cleanup (only after release PR merges to main)
-
-Once the release PR is merged:
-
-```bash
-# Now safe to delete — commit history + CHANGELOG are the source of truth
-rm _ideia/implemented/<NUMBER>-*.md
-```
-
-> If running this command before the merge: STOP at 5.5 and skip 5.6. Re-enter the workflow later just for the cleanup.
-
-### 5.7 Final Summary Report
-
-Present a final summary report to the user:
-
-| Issue | Title | Verdict          | Action                                                          | Commit    |
-| ----- | ----- | ---------------- | --------------------------------------------------------------- | --------- |
-| #N    | Title | ✅ Implemented   | Issue closed, idea file in `_ideia/implemented/` (until merge)  | `abc1234` |
-| #N    | Title | ♻️ Reclaimed     | Was IN FLIGHT / NEEDS DETAIL, reclaimed after 15d → implemented | `abc1234` |
-| #N    | Title | ⏭️ Deferred      | Issue closed + permanent archive in `_ideia/defer/`             | —         |
-| #N    | Title | ❌ Not Fit       | Issue closed + permanent archive in `_ideia/notfit/`            | —         |
-| #N    | Title | 🔁 Exists        | Issue closed + permanent archive in `_ideia/exists/`            | —         |
-| #N    | Title | ❓ Needs Detail  | Issue OPEN, archive in `_ideia/need_details/`                   | —         |
-| #N    | Title | 🚧 In Flight     | Issue OPEN, archive in `_ideia/in_flight/`, tracked by PR #M    | —         |
-
-Include:
-
-- Total features harvested
-- Total ideas archived per bucket (`need_details/` / `defer/` / `notfit/` / `exists/` / `in_flight/`)
-- Total features implemented (idea files in `_ideia/implemented/`, awaiting post-merge cleanup)
-- Total reclaimed via Phase 1.7 (stale 15-day rule)
-- Total issues closed
-- Total issues left open (NEEDS DETAIL + VIABLE-pending + IN FLIGHT)
-- Audit results: lint / typecheck / cycles / build / coverage (pass-count per phase)
-- Languages used in posted comments (e.g. "3× pt-BR, 5× en, 1× es")

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

@@ -1,51 +0,0 @@
----
-name: issue-triage-ag
-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/issue-triage-cc/SKILL.md

@@ -1,51 +0,0 @@
----
-name: issue-triage-cc
-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/issue-triage-cx/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/port-upstream-features-ag/SKILL.md

@@ -1,545 +0,0 @@
----
-name: port-upstream-features-ag
-description: Migrated command port-upstream-features-ag
----
-
-# /port-upstream-features — Port Features from Upstream Projects
-
-## ⚠️ CONFIDENTIAL — This workflow is `.gitignored` and must NEVER be committed.
-
-## Overview
-
-Port features from upstream open-source projects (e.g. [`decolua/9router`](https://github.com/decolua/9router))
-into OmniRoute, adapting them for TypeScript and the OmniRoute architecture,
-while giving full attribution to the original authors.
-
-The user provides one or more upstream PR identifiers (numbers or URLs).
-The agent fetches the source, plans the adaptation, and generates a
-structured task file for implementation, then opens a per-port PR on
-**`diegosouzapw/OmniRoute`** (never on the upstream tracker).
-
-Companion: `port-upstream-issues-ag.md` (covers upstream **issues**, not PRs).
-
-## Inputs
-
-The user provides:
-
-- One or more **upstream PR identifiers** — bare numbers (`1317 1320`),
-  full URLs (`https://github.com/decolua/9router/pull/1317`), or a mix.
-- Optionally, notes about scope or which strategies to use.
-
-If no input is provided, the agent harvests open upstream PRs and asks
-the user which to port before doing anything else.
-
-## Constants (hard-coded — do not infer)
-
-- **Upstream**: `decolua/9router` (JavaScript, Next.js 16)
-- **Fork (origin)**: `diegosouzapw/OmniRoute` (TypeScript, Next.js 16)
-- **Worktree root**: `.claude/worktrees/`
-- **Task notes dir**: `_tasks/features-v${VERSION}/port-tasks/`
-- **Dedupe ledger**: `_tasks/features-v${VERSION}/port-tasks/_ported.jsonl`
-- **Upstream sources mirror (read-only)**: `_references/9router/`
-
-## Architecture mapping (upstream → OmniRoute)
-
-This table is the single source of truth for where upstream files land in
-OmniRoute. OmniRoute has layers that don't exist upstream (a2a, memory,
-cloudAgent, guardrails, evals, services bootstrap); when an upstream PR
-touches functionality routed through one of those layers downstream, MAP
-IT and note it in the task note.
-
-| Upstream (9router, JS)                                  | OmniRoute (TS)                                                                                                    | Notes                                                |
-| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
-| `src/app/api/v1/...`                                    | `src/app/api/v1/...`                                                                                              | Public LLM API surface — same shape                  |
-| `src/app/api/...` (dashboard / cli-tools / oauth)       | `src/app/api/...`                                                                                                 | Internal dashboard API                               |
-| `src/app/(dashboard)/dashboard/...`                     | `src/app/(dashboard)/dashboard/...`                                                                               | UI                                                   |
-| `src/app/landing/`                                      | `src/app/landing/`                                                                                                | Marketing pages                                      |
-| `src/sse/handlers/` `src/sse/services/`                 | `src/sse/handlers/` `src/sse/services/`                                                                           | Legacy streaming layer (still active in both)        |
-| `open-sse/handlers/`                                    | `open-sse/handlers/`                                                                                              | Modern handler layer                                 |
-| `open-sse/executors/*.js`                               | `open-sse/executors/*.ts`                                                                                         | One per provider — JS → TS rewrite                   |
-| `open-sse/services/`                                    | `open-sse/services/`                                                                                              | Combo, accountFallback, model, etc.                  |
-| `open-sse/translator/` `open-sse/transformer/`          | `open-sse/translator/` `open-sse/transformer/`                                                                    | Format conversion + Responses API                    |
-| `open-sse/rtk/` (request toolkit)                       | `open-sse/services/` or `open-sse/utils/`                                                                         | No 1:1 — fold into nearest service                   |
-| `open-sse/config/` `open-sse/utils/` `open-sse/lib/`    | `open-sse/config/` `open-sse/utils/` `open-sse/lib/`                                                              |                                                      |
-| `src/lib/mcp/`                                          | `open-sse/mcp-server/`                                                                                            | MCP moved into open-sse workspace                    |
-| `src/lib/db/` (adapters / helpers / migrations / repos) | `src/lib/db/` (45+ domain modules, 55 migrations)                                                                 | `localDb.ts` is RE-EXPORT ONLY (hard rule #2)        |
-| `src/lib/oauth/`                                        | `src/lib/oauth/`                                                                                                  |                                                      |
-| `src/lib/auth/`                                         | `src/server/authz/` + `src/lib/auth*`                                                                             | OmniRoute splits server-side vs lib helpers          |
-| `src/lib/network/`                                      | `src/shared/utils/` or `open-sse/utils/`                                                                          | Fold by purpose                                      |
-| `src/lib/tunnel/` `src/lib/updater/` `src/lib/usage/`   | `src/lib/services/` (bootstrap) + module per concern                                                              | OmniRoute consolidates as embedded services          |
-| `src/mitm/`                                             | `src/mitm/`                                                                                                       | Cert / dns / handlers preserved                      |
-| `src/models/`                                           | `src/models/`                                                                                                     | Domain models                                        |
-| `src/shared/`                                           | `src/shared/`                                                                                                     | Constants, components, hooks, services, utils        |
-| `src/store/` (Zustand)                                  | `src/store/`                                                                                                      |                                                      |
-| `src/i18n/` + `public/i18n/literals/`                   | `src/i18n/` + `public/i18n/literals/`                                                                             | i18n keys MUST be added in ALL locales               |
-| `skills/9router-*` (top-level spec dirs)                | `src/lib/skills/` (framework) + `skills/` (specs)                                                                 | Different shape — framework vs spec files            |
-| `cli/`                                                  | `bin/` (entry) + `src/lib/services/` modules                                                                      | OmniRoute folded most CLI into the main app          |
-| `gitbook/`                                              | `docs/`                                                                                                           | Markdown only; no gitbook in OmniRoute               |
-| (no equivalent upstream)                                | `src/lib/a2a/` `src/lib/memory/` `src/lib/cloudAgent/` `src/lib/guardrails/` `src/lib/evals/` `electron/` `tests/` | OmniRoute-only — never port AWAY from these          |
-
-## Steps
-
-### 1. Sanity + setup
-
-```bash
-git -C . remote get-url origin       # must end in diegosouzapw/OmniRoute
-git branch --show-current            # must be release/vX.Y.Z
-gh auth status
-
-VERSION=$(node -p "require('./package.json').version")
-RELEASE_BRANCH=$(git branch --show-current)
-
-# Idempotent upstream remote for Strategy B (cherry-pick)
-git remote get-url upstream 2>/dev/null \
-  || git remote add upstream https://github.com/decolua/9router.git
-git fetch upstream --quiet
-
-# License gate — confirm once per session, cache the LICENSE blob hash
-UPSTREAM_LICENSE_SHA=$(git -C _references/9router rev-parse HEAD:LICENSE 2>/dev/null)
-echo "Upstream LICENSE blob: $UPSTREAM_LICENSE_SHA"
-# Read _references/9router/LICENSE and confirm permissive (MIT / Apache-2.0 / BSD-style).
-# If unsure or the hash changed since last session, ESCALATE TO USER before continuing.
-
-mkdir -p "_tasks/features-v${VERSION}/port-tasks"
-touch    "_tasks/features-v${VERSION}/port-tasks/_ported.jsonl"
-```
-
-The task folder uses the **current development version** (always 1 patch
-above the last released). If on `main`, follow `/generate-release` Phase
-1 steps 1–5 to create the next `release/vX.Y.Z` before continuing. All
-work BRANCHES off the release branch.
-
-### 2. Discover open upstream PRs (only if no input)
-
-`gh ... --json` can silently truncate large result sets. Use the
-numbers-only → batched-metadata pattern:
-
-```bash
-TARGETS="_tasks/features-v${VERSION}/port-tasks/_discovery.txt"
-
-# 2a — numbers only, never truncated
-gh pr list --repo decolua/9router --state open --limit 500 \
-  --json number --jq '.[].number' \
-  > "$TARGETS"
-
-# 2b — full metadata per PR, batched
-while read N; do
-  gh pr view "$N" --repo decolua/9router \
-    --json number,title,author,createdAt,additions,deletions,labels,mergeable
-done < "$TARGETS" > "_tasks/features-v${VERSION}/port-tasks/_discovery.jsonl"
-
-# 2c — open upstream issues for cross-reference (which PR closes which issue)
-gh issue list --repo decolua/9router --state open --limit 500 \
-  --json number,title --jq 'sort_by(.number)' \
-  > "_tasks/features-v${VERSION}/port-tasks/_open_issues.json"
-```
-
-Group results by intent (fix / feat / chore / docs), summarise risk and
-size, then ask the user which PRs to port. Wait for explicit selection.
-
-### 3. Read Upstream PR Source Code (per PR)
-
-For each PR — first normalize input (URL → bare number) and run the
-dedupe pre-check BEFORE any expensive fetch / diff work:
-
-```bash
-# normalize: "https://github.com/decolua/9router/pull/1317" → "1317"
-N=$(echo "$arg" | sed -E 's|.*/pull/([0-9]+).*|\1|; s|^#||')
-
-# dedupe — defense in depth (JSONL snapshot + git log as source of truth)
-LEDGER="_tasks/features-v${VERSION}/port-tasks/_ported.jsonl"
-if grep -q "\"upstream\":${N}\b" "$LEDGER" 2>/dev/null \
-   || git log --all --grep "Inspired-by:.*decolua/9router/pull/${N}\b" --oneline | grep -q .; then
-  echo "PR #${N} already ported — skipping"; continue
-fi
-```
-
-Then fetch metadata, diff, commits, and author identity for attribution:
-
-```bash
-gh pr view "$N" --repo decolua/9router \
-  --json number,title,author,body,files,additions,deletions,baseRefOid,headRefOid,mergeable,state
-
-gh pr diff "$N" --repo decolua/9router \
-  > "_tasks/features-v${VERSION}/port-tasks/diff-${N}.patch"
-
-gh api "repos/decolua/9router/pulls/${N}/commits" \
-  --jq '.[] | {sha, message: .commit.message, author: .commit.author}'
-
-# Author identity used in the Co-authored-by trailer. Prefer the first
-# commit's author (PR author may differ — e.g. a maintainer who pushed it).
-gh api "repos/decolua/9router/pulls/${N}/commits" \
-  --jq '.[0].commit.author | "\(.name) <\(.email)>"'
-
-# Cross-ref: upstream issues this PR closes (GraphQL — REST `gh pr view`
-# does NOT expose `closingIssuesReferences`).
-gh api graphql -f query='
-  query($owner: String!, $repo: String!, $num: Int!) {
-    repository(owner: $owner, name: $repo) {
-      pullRequest(number: $num) {
-        closingIssuesReferences(first: 20) { nodes { number } }
-      }
-    }
-  }' -F owner=decolua -F repo=9router -F num="$N" \
-  --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[]?.number'
-```
-
-### 4. Analyze Compatibility
-
-For each upstream PR, analyse using the **Architecture mapping** table at
-the top of this file:
-
-- **Architecture mapping**: which upstream files land in which OmniRoute
-  files? Read each equivalent OmniRoute file (not just the upstream
-  copy in `_references/9router/`).
-- **Language adaptation**: JS → TS — type signatures, null/undefined,
-  `unknown` vs `any`, ESM vs CJS quirks.
-- **Dependencies**: new npm packages? Check `package.json` of both.
-- **Schema changes**: DB migrations required? How do they interact with
-  the existing 55 migrations?
-- **Tests**: which OmniRoute test suite covers this? Default to
-  `tests/unit/<scope>.test.ts` using `node:test`; MCP via
-  `vitest.mcp.config.ts`.
-- **Security**: any security considerations during adaptation (input
-  validation, public-cred handling, error sanitization)?
-- **i18n**: new UI strings → translation keys in ALL locales
-  (`src/i18n/` + `public/i18n/literals/`).
-- **OmniRoute-only impact**: does this touch a2a / memory / cloudAgent /
-  guardrails / evals? Note in the task plan.
-
-### 5. Create Task Directory & Generate Task File
-
-```bash
-TASK_DIR="_tasks/features-v${VERSION}/port-tasks"
-SEQ=$(printf "%02d" $(( $(ls "$TASK_DIR"/*.plan.md 2>/dev/null | wc -l) + 1 )))
-```
-
-File naming: `<seq>-<short-kebab-name>.plan.md`, e.g.
-`01-provider-quota-grouped-layout.plan.md`. Sequence is zero-padded so
-files sort lexicographically.
-
-#### Task file template
-
-```markdown
-# Port: <Feature Name>
-
-## Source
-
-| Field | Value |
-|-------|-------|
-| **Upstream project** | [9router](https://github.com/decolua/9router) |
-| **Upstream PR** | [#<number>](https://github.com/decolua/9router/pull/<number>) |
-| **PR author** | [@<pr-username>](https://github.com/<pr-username>) |
-| **First-commit author** | `<Name> <<email>>` (used in `Co-authored-by` trailer) |
-| **Closing upstream issues** | <list from GraphQL `closingIssuesReferences`, or "none"> |
-| **Date analyzed** | <YYYY-MM-DD> |
-
-## Summary
-
-<What the feature does in the upstream project.>
-
-## Adaptation plan
-
-### Files to create/modify in OmniRoute
-
-| OmniRoute file | Action | Based on (upstream)            |
-|----------------|--------|--------------------------------|
-| `src/...`      | Create | `src/...` (upstream path)      |
-| `open-sse/...` | Modify | `lib/...` (upstream path)      |
-
-### Selected strategy
-
-`A — Manual re-implementation` | `B — Cherry-pick with adaptation` | `C — Direct apply`
-
-### Key adaptations
-
-1. <JS → TS conversion details.>
-2. <Architecture differences and how we bridge them.>
-3. <OmniRoute-specific integrations (a2a / memory / cloudAgent / guardrails / evals).>
-
-### Dependencies
-
-- [ ] New npm packages: <none / list>
-- [ ] DB migration: <none / describe>
-- [ ] i18n keys: <none / list — ALL locales>
-
-### Reference files to read during implementation
-
-- `_references/9router/<path1>` (local mirror — preferred)
-- `https://github.com/decolua/9router/blob/<branch>/<path1>` (fallback)
-
-## Attribution
-
-When implementing this feature, use these attribution methods:
-
-### 1. Git commit trailer (ONLY place with upstream PR reference)
-
-```
-Co-authored-by: <Name> <<email>>
-Inspired-by: https://github.com/decolua/9router/pull/<number>
-```
-
-> Per CLAUDE.md hard rule #16: `Co-authored-by` is allowed and required
-> for human upstream authors; it is forbidden only for AI/bot trailers
-> (Claude / GPT / Copilot / etc.).
-
-### 2. CHANGELOG entry (author only — NO upstream link)
-
-```
-- **feat(<scope>):** <description>. (thanks @<username>)
-```
-
-### 3. PR description block (author only — NO upstream link)
-
-```
-## Attribution
-
-Thanks to [@<username>](https://github.com/<username>) for the original implementation.
-```
-
-> **Rule**: the upstream PR link is an internal implementation detail.
-> It lives ONLY in the commit trailer (`Inspired-by`). The CHANGELOG
-> and PR description credit the author naturally, as if they were a
-> direct contributor.
-
-## Implementation checklist
-
-- [ ] Read upstream PR diff and reference files
-- [ ] Worktree branched off current `release/vX.Y.Z`
-- [ ] Files created/modified per adaptation plan
-- [ ] TypeScript types added
-- [ ] Unit tests added at `tests/unit/<scope>.test.ts`
-- [ ] i18n keys added in all locales (if UI-facing)
-- [ ] Manual UI smoke on `npm run dev` (if dashboard touched)
-- [ ] Commit with `Co-authored-by` + `Inspired-by` trailers
-- [ ] CHANGELOG entry inside the PR with `(thanks @<username>)`
-- [ ] PR description includes Attribution block (author only)
-- [ ] Ledger entry written on PR creation
-```
-
-### 6. Present Task to User
-
-After generating the task file(s):
-
-- Show the task file path(s)
-- Summarise total LOC, blockers, recommended order
-- Explicitly flag:
-  - New dependencies in `package.json`
-  - DB migrations
-  - New i18n keys (all locales)
-  - Any change to `src/app/api/v1/...` route shapes (public surface)
-  - Any change to `src/shared/contracts/` (downstream consumers)
-  - OmniRoute-only layers impacted
-- Ask if the user wants to proceed now or save for later
-
-**Do NOT touch code until the user explicitly names which PRs to port.**
-
-### 7. Implementation (one worktree per PR)
-
-#### 7.1 Worktree
-
-```bash
-BRANCH="feat/port-pr-${N}-<short-kebab>"   # or fix/port-pr-... matching upstream intent
-git worktree add ".claude/worktrees/${BRANCH}" -b "$BRANCH" "$RELEASE_BRANCH"
-cd ".claude/worktrees/${BRANCH}"
-npm install
-```
-
-#### 7.2 Strategy decision tree
-
-| Condition                                                       | Strategy                                  |
-| --------------------------------------------------------------- | ----------------------------------------- |
-| Upstream change is JS code → needs TS rewrite (the common case) | **A — Manual re-implementation** (default) |
-| Upstream is already TS-compatible AND file paths align 1:1      | **B — Cherry-pick with adaptation**       |
-| Docs / config / static-asset-only (no executable code)          | **C — Direct apply**                      |
-
-```bash
-# Strategy A: re-write upstream change against OmniRoute types & architecture.
-#   Read _references/9router/<path> for source-of-truth context.
-#   Attribute upstream author in commit trailer regardless.
-
-# Strategy B: fetch upstream PR head and cherry-pick
-git fetch upstream "pull/${N}/head:upstream-pr-${N}"
-git cherry-pick upstream-pr-${N}  # resolve TS / architecture conflicts manually
-
-# Strategy C: only for docs/config (use 3-way merge so conflicts surface)
-git apply --3way "../../_tasks/features-v${VERSION}/port-tasks/diff-${N}.patch"
-```
-
-#### 7.3 Implement the feature
-
-Follow the task plan. Keep or port upstream tests, translating them to
-OmniRoute conventions:
-
-- Unit: `tests/unit/<scope>.test.ts` with `node:test`
-- MCP: via `vitest.mcp.config.ts`
-- Integration: `tests/integration/`
-- E2E: `tests/e2e/` (Playwright)
-
-#### 7.4 Validate locally — mandatory
-
-```bash
-npm run check                 # lint + test:unit
-npm run typecheck:core
-npm run typecheck:noimplicit:core
-npm run test:vitest           # MCP server tests
-npm run check:docs-all        # docs-sync gates
-npm run check:cycles          # always — ports often introduce cross-layer imports
-```
-
-If contracts / providers / schemas were touched:
-
-```bash
-npm run check:route-validation:t06
-npm run check:any-budget:t11
-```
-
-If end-to-end behaviour is plausibly impacted:
-
-```bash
-npm run test:e2e
-```
-
-If the diff touches `src/app/(dashboard)/` (UI), manual smoke is
-**mandatory** per CLAUDE.md "For UI or frontend changes":
-
-```bash
-npm run dev   # http://localhost:20128
-# Exercise the new/changed UI in a browser. Verify the golden path AND
-# at least one edge case. Watch the console for regressions in other tabs.
-# Run /capture-release-evidences afterwards if release-evidence is needed.
-```
-
-NO `--no-verify`. Do NOT weaken existing tests. Investigate root cause
-if anything pre-existing fails.
-
-#### 7.5 Commit with attribution (upstream ref ONLY here)
-
-```bash
-git commit -m "$(cat <<'EOF'
-<type>(<scope>): <description>
-
-<optional body — root cause / mechanism / user-visible effect>
-
-Co-authored-by: <Name> <<email>>
-Inspired-by: https://github.com/decolua/9router/pull/<N>
-EOF
-)"
-```
-
-- The `Inspired-by` link is the ONLY place the upstream PR is referenced.
-  It MUST NOT appear in the PR body or `CHANGELOG.md`.
-- The `Co-authored-by` trailer credits the **human** upstream author.
-  This is allowed and required by CLAUDE.md hard rule #16 — that rule
-  bans AI/bot trailers (Claude / GPT / Copilot / etc.), not humans.
-- Use lowercase `Co-authored-by:` and `Inspired-by:` (GitHub canonical
-  render form).
-
-#### 7.6 Update CHANGELOG.md (inside the PR, no upstream link)
-
-In the worktree, append to the current release's section in `CHANGELOG.md`:
-
-```markdown
-- **<type>(<scope>):** <description>. (thanks @<upstream-username>)
-```
-
-Commit this change in the same PR — either as a separate commit or amended
-into the feat/fix commit (operator choice). Credit the upstream author
-naturally; **never** reference the upstream PR URL or `decolua/9router`
-here.
-
-#### 7.7 Push & open PR (author only, no upstream link)
-
-> **⚠️ FORK-PR GOTCHA**: bare `gh pr create` defaults to the fork's
-> PARENT (upstream `decolua/9router`). ALWAYS pass `--repo
-> diegosouzapw/OmniRoute`. Verified gotcha (2026-05-23 on ghostty-web).
-> Verify with `gh pr view <N> --repo diegosouzapw/OmniRoute` after
-> creation.
-
-```bash
-git push -u origin "$BRANCH"
-OUR_PR_URL=$(gh pr create --repo diegosouzapw/OmniRoute --base "$RELEASE_BRANCH" \
-  --title "<type>(<scope>): <description>" \
-  --body "$(cat <<'EOF'
-## Summary
-
-<1–3 bullets>
-
-## Attribution
-
-Thanks to [@<upstream-username>](https://github.com/<upstream-username>) for the original implementation.
-
-## Changes
-
-- <list>
-
-## Test plan
-
-- [ ] npm run check
-- [ ] npm run typecheck:core && npm run typecheck:noimplicit:core
-- [ ] npm run test:vitest
-- [ ] npm run check:docs-all
-- [ ] npm run check:cycles
-- [ ] npm run test:e2e (if relevant)
-- [ ] Manual UI smoke (if dashboard touched)
-EOF
-)")
-```
-
-#### 7.8 Record in dedupe ledger
-
-```bash
-echo "{\"upstream\":${N},\"our_pr\":\"${OUR_PR_URL}\",\"branch\":\"${BRANCH}\",\"at\":\"$(date -Iseconds)\"}" \
-  >> "_tasks/features-v${VERSION}/port-tasks/_ported.jsonl"
-```
-
-Step 3's dedupe pre-check reads this on the next run; the `Inspired-by`
-trailer in the commit serves as the redundant source of truth.
-
-#### 7.9 Cleanup (after merge / abandonment)
-
-```bash
-PR_STATE=$(gh pr view "$OUR_PR_URL" --json state --jq .state)
-git worktree remove ".claude/worktrees/${BRANCH}"
-if [ "$PR_STATE" = "MERGED" ]; then
-  git branch -d "$BRANCH"
-else
-  echo "PR not merged (state=$PR_STATE) — keeping branch '$BRANCH'"
-fi
-```
-
-Task note and ledger entry stay as durable local documentation.
-
-## Hard rules
-
-- All work BRANCHES off `release/vX.Y.Z`. Never off `main`. Never push to
-  `main` directly.
-- One PR per ported upstream PR. Do NOT bundle multiple ports in one PR.
-- The upstream PR URL appears ONLY in the commit `Inspired-by` trailer.
-  Never in PR body, CHANGELOG, or any other surface.
-- `Co-authored-by` trailers MUST credit the human upstream author (CLAUDE.md
-  rule #16 allows humans, bans AI/bot trailers).
-- Never widen `src/shared/contracts/` or public route shapes without
-  explicit user OK.
-- Never use `--no-verify`, force-push to release/main, or `--reject` /
-  `--theirs` / `--ours` to shortcut conflicts.
-- Never overwrite a previously-ported PR — the Step 3 dedupe guard
-  (JSONL + git log on `Inspired-by:`) exists for this; never disable it.
-- Verify subagent work yourself per CLAUDE.md: `git status` + `git diff
-  --stat`, sanity-check scope, and re-run the full validation suite
-  before accepting any agent-authored change.
-- License gate is enforced in Step 1; if the upstream LICENSE blob hash
-  changes between sessions, re-confirm before continuing.
-
-## Notes
-
-- This workflow is **local-only** and must never be committed to the
-  repository. The `.md` file is individually listed in `.gitignore`
-  alongside `port-upstream-issues-ag.md`, and the `_tasks/` directory is
-  covered by the `/_*/` gitignore rule.
-- Task files serve as persistent documentation of what was ported and
-  from where.
-- The dedupe ledger (`_ported.jsonl`) is local-only documentation, NOT
-  tracked. The git `Inspired-by:` trailer is the authoritative record.
-- Companion sibling: `port-upstream-issues-ag.md` for upstream issue
-  triage and fix porting.

.agents/skills/port-upstream-features-cc/SKILL.md

@@ -1,396 +0,0 @@
----
-name: port-upstream-features-cc
-description: Port one or more open PRs from upstream decolua/9router into OmniRoute, adapt JS→TS, attribute the original author, land via release-branch worktree + per-feature PR.
----
-
-# /port-upstream-features — Port upstream PRs into OmniRoute
-
-## ⚠️ CONFIDENTIAL — this command is `.gitignored` and must NEVER be committed.
-
-Full reference: `.agents/workflows/port-upstream-features-ag.md`.
-Sibling command (issue tracker, not PRs): `/port-upstream-issues`.
-
-## Inputs
-
-Arguments: `$ARGUMENTS` (optional). Accepts a space-separated list of
-upstream PR identifiers — bare numbers (`1317 1320`), full URLs
-(`https://github.com/decolua/9router/pull/1317`), or a mix.
-
-If empty, the command MUST list candidate open upstream PRs first and ask
-the user which to port before doing anything else.
-
-## Constants (hard-coded — do not infer)
-
-- Upstream: `decolua/9router` (JavaScript, Next.js 16)
-- Fork (origin): `diegosouzapw/OmniRoute` (TypeScript, Next.js 16)
-- Worktree root: `.claude/worktrees/`
-- Task notes dir: `_tasks/features-v${VERSION}/port-tasks/`
-- Dedupe ledger: `_tasks/features-v${VERSION}/port-tasks/_ported.jsonl`
-- Upstream sources mirror (read-only): `_references/9router/`
-
-## Architecture mapping (upstream → OmniRoute)
-
-Use this table when planning each port. OmniRoute has layers that don't
-exist upstream (a2a, memory, cloudAgent, guardrails, evals, services
-bootstrap); when an upstream change touches functionality that lives in
-those layers downstream, MAP IT and note it in the task note.
-
-| Upstream (9router, JS)                                | OmniRoute (TS)                                                                                                    | Notes                                                |
-| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
-| `src/app/api/v1/...`                                  | `src/app/api/v1/...`                                                                                              | Public LLM API surface — same shape                  |
-| `src/app/api/...` (dashboard / cli-tools / oauth)     | `src/app/api/...`                                                                                                 | Internal dashboard API                               |
-| `src/app/(dashboard)/dashboard/...`                   | `src/app/(dashboard)/dashboard/...`                                                                               | UI                                                   |
-| `src/app/landing/`                                    | `src/app/landing/`                                                                                                | Marketing pages                                      |
-| `src/sse/handlers/` `src/sse/services/`               | `src/sse/handlers/` `src/sse/services/`                                                                           | Legacy streaming layer (still active in both)        |
-| `open-sse/handlers/`                                  | `open-sse/handlers/`                                                                                              | Modern handler layer                                 |
-| `open-sse/executors/*.js`                             | `open-sse/executors/*.ts`                                                                                         | One per provider — JS → TS rewrite                   |
-| `open-sse/services/`                                  | `open-sse/services/`                                                                                              | Combo, accountFallback, model, etc.                  |
-| `open-sse/translator/` `open-sse/transformer/`        | `open-sse/translator/` `open-sse/transformer/`                                                                    | Format conversion + Responses API                    |
-| `open-sse/rtk/` (request toolkit)                     | `open-sse/services/` or `open-sse/utils/`                                                                         | No 1:1 — fold into nearest service                   |
-| `open-sse/config/` `open-sse/utils/` `open-sse/lib/`  | `open-sse/config/` `open-sse/utils/` `open-sse/lib/`                                                              |                                                      |
-| `src/lib/mcp/`                                        | `open-sse/mcp-server/`                                                                                            | MCP moved into open-sse workspace                    |
-| `src/lib/db/` (adapters / helpers / migrations / repos) | `src/lib/db/` (45+ domain modules, 55 migrations)                                                               | `localDb.ts` is RE-EXPORT ONLY (hard rule #2)        |
-| `src/lib/oauth/`                                      | `src/lib/oauth/`                                                                                                  |                                                      |
-| `src/lib/auth/`                                       | `src/server/authz/` + `src/lib/auth*`                                                                             | OmniRoute splits server-side vs lib helpers          |
-| `src/lib/network/`                                    | `src/shared/utils/` or `open-sse/utils/`                                                                          | Fold by purpose                                      |
-| `src/lib/tunnel/` `src/lib/updater/` `src/lib/usage/` | `src/lib/services/` (bootstrap) + module per concern                                                              | OmniRoute consolidates as embedded services          |
-| `src/mitm/`                                           | `src/mitm/`                                                                                                       | Cert / dns / handlers preserved                      |
-| `src/models/`                                         | `src/models/`                                                                                                     | Domain models                                        |
-| `src/shared/`                                         | `src/shared/`                                                                                                     | Constants, components, hooks, services, utils        |
-| `src/store/` (Zustand)                                | `src/store/`                                                                                                      |                                                      |
-| `src/i18n/` + `public/i18n/literals/`                 | `src/i18n/` + `public/i18n/literals/`                                                                             | i18n keys MUST be added in ALL locales               |
-| `skills/9router-*` (top-level spec dirs)              | `src/lib/skills/` (framework) + `skills/` (specs)                                                                 | Different shape — framework vs spec files            |
-| `cli/`                                                | `bin/` (entry) + `src/lib/services/` modules                                                                      | OmniRoute folded most CLI into the main app          |
-| `gitbook/`                                            | `docs/`                                                                                                           | Markdown only; no gitbook in OmniRoute               |
-| (no equivalent upstream)                              | `src/lib/a2a/` `src/lib/memory/` `src/lib/cloudAgent/` `src/lib/guardrails/` `src/lib/evals/` `electron/` `tests/` | OmniRoute-only — never port AWAY from these          |
-
-When a port touches an `(no equivalent)` row downstream, the upstream
-change either does not apply, OR you must wire it through one of those
-layers. Flag in the task note.
-
-## Execution
-
-### Step 0 — Sanity + setup
-
-```bash
-git -C . remote get-url origin       # must end in diegosouzapw/OmniRoute
-git branch --show-current            # must be release/vX.Y.Z (or create one via /generate-release)
-gh auth status
-
-VERSION=$(node -p "require('./package.json').version")
-RELEASE_BRANCH=$(git branch --show-current)
-
-# Idempotent upstream remote for Strategy B (cherry-pick)
-git remote get-url upstream 2>/dev/null \
-  || git remote add upstream https://github.com/decolua/9router.git
-git fetch upstream --quiet
-
-# License gate — confirm once per session, cache the LICENSE blob hash
-UPSTREAM_LICENSE_SHA=$(git -C _references/9router rev-parse HEAD:LICENSE 2>/dev/null)
-echo "Upstream LICENSE blob: $UPSTREAM_LICENSE_SHA"
-# Read _references/9router/LICENSE and confirm permissive (MIT / Apache-2.0 / BSD-style).
-# If unsure or the hash changed since last session, ESCALATE TO USER before continuing.
-
-mkdir -p "_tasks/features-v${VERSION}/port-tasks"
-touch    "_tasks/features-v${VERSION}/port-tasks/_ported.jsonl"
-```
-
-If on `main`, follow `/generate-release` Phase 1 steps 1–5 to create the
-next `release/vX.Y.Z` first.
-
-### Step 1 — Discover (only if no $ARGUMENTS) — two-step harvest
-
-`gh ... --json` can silently truncate large result sets. Use the
-numbers-only → batched-metadata pattern:
-
-```bash
-TARGETS="_tasks/features-v${VERSION}/port-tasks/_discovery.txt"
-
-# 1a — numbers only, never truncated
-gh pr list --repo decolua/9router --state open --limit 500 \
-  --json number --jq '.[].number' \
-  > "$TARGETS"
-
-# 1b — full metadata per PR, batched
-while read N; do
-  gh pr view "$N" --repo decolua/9router \
-    --json number,title,author,createdAt,additions,deletions,labels,mergeable
-done < "$TARGETS" > "_tasks/features-v${VERSION}/port-tasks/_discovery.jsonl"
-
-# 1c — open upstream issues for cross-reference (which PR closes which issue)
-gh issue list --repo decolua/9router --state open --limit 500 \
-  --json number,title --jq 'sort_by(.number)' \
-  > "_tasks/features-v${VERSION}/port-tasks/_open_issues.json"
-```
-
-Group results by intent (fix / feat / chore / docs), summarise risk and
-size, then ask the user which PRs to port. Wait for explicit selection.
-
-### Step 2 — Per-PR analysis (loop)
-
-For each PR — first normalize input (URL → bare number) and run a dedupe
-pre-check BEFORE any expensive fetch / diff work:
-
-```bash
-# normalize: "https://github.com/decolua/9router/pull/1317" → "1317"
-N=$(echo "$arg" | sed -E 's|.*/pull/([0-9]+).*|\1|; s|^#||')
-
-# dedupe — defense in depth (JSONL snapshot + git log as source of truth)
-LEDGER="_tasks/features-v${VERSION}/port-tasks/_ported.jsonl"
-if grep -q "\"upstream\":${N}\b" "$LEDGER" 2>/dev/null \
-   || git log --all --grep "Inspired-by:.*decolua/9router/pull/${N}\b" --oneline | grep -q .; then
-  echo "PR #${N} already ported — skipping"; continue
-fi
-```
-
-Then fetch metadata, diff, commits, author:
-
-```bash
-gh pr view "$N" --repo decolua/9router \
-  --json number,title,author,body,files,additions,deletions,baseRefOid,headRefOid,mergeable,state
-
-gh pr diff "$N" --repo decolua/9router \
-  > "_tasks/features-v${VERSION}/port-tasks/diff-${N}.patch"
-
-gh api "repos/decolua/9router/pulls/${N}/commits" \
-  --jq '.[] | {sha, message: .commit.message, author: .commit.author}'
-
-# Author identity used in the Co-authored-by trailer. Prefer the first
-# commit's author (PR author may differ — e.g. a maintainer who pushed it).
-gh api "repos/decolua/9router/pulls/${N}/commits" \
-  --jq '.[0].commit.author | "\(.name) <\(.email)>"'
-
-# Cross-ref: upstream issues this PR closes (GraphQL — REST `gh pr view`
-# does NOT expose `closingIssuesReferences`).
-gh api graphql -f query='
-  query($owner: String!, $repo: String!, $num: Int!) {
-    repository(owner: $owner, name: $repo) {
-      pullRequest(number: $num) {
-        closingIssuesReferences(first: 20) { nodes { number } }
-      }
-    }
-  }' -F owner=decolua -F repo=9router -F num="$N" \
-  --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[]?.number'
-```
-
-Read the diff. Map each upstream file to its OmniRoute equivalent using
-the **architecture mapping** table above. Note local commits that overlap
-(`git log --oneline -- <our-path>`) and any `_references/9router/<path>`
-file you needed to read for source-of-truth context.
-
-Write a task note at
-`_tasks/features-v${VERSION}/port-tasks/<seq>-<short-kebab>.plan.md`.
-Sequence number = `printf "%02d" $((max_existing + 1))` (zero-padded so
-files sort lexicographically). Required fields:
-
-- Upstream source (PR #, title, author, first-commit author identity)
-- Files touched (upstream → OmniRoute, per the architecture mapping)
-- JS→TS conversion notes
-- Dependencies added (npm packages)
-- Schema / migration impact
-- i18n keys added (with locale coverage checklist)
-- OmniRoute-only layers impacted (a2a / memory / cloudAgent / guardrails / evals)
-- Selected strategy (A / B / C — see Step 4)
-- Closing upstream issues (via GraphQL `closingIssuesReferences`)
-- Attribution checklist
-
-### Step 3 — Present plan and wait
-
-Summarise all task notes to the user: total LOC, blockers, recommended
-order, and explicitly flag:
-
-- New dependencies in `package.json`
-- DB migrations (and how they interact with the 55 existing migrations)
-- New i18n keys (MUST be added in ALL locales — `src/i18n/` + `public/i18n/literals/`)
-- Any change to `src/app/api/v1/...` route shapes (public surface)
-- Any change to `src/shared/contracts/` (downstream consumers)
-- OmniRoute-only layers impacted
-
-**Do not touch code until the user names which PRs to port.**
-
-### Step 4 — Implement (one worktree per PR)
-
-For each approved PR:
-
-```bash
-BRANCH="feat/port-pr-${N}-<short>"     # or fix/port-pr-... matching upstream intent
-git worktree add ".claude/worktrees/${BRANCH}" -b "$BRANCH" "$RELEASE_BRANCH"
-cd ".claude/worktrees/${BRANCH}"
-npm install
-```
-
-**Strategy decision tree** (record choice in task note):
-
-| Condition                                                  | Strategy                                  |
-| ---------------------------------------------------------- | ----------------------------------------- |
-| Upstream change is JS code → needs TS rewrite (the common case) | **A — Manual re-implementation** (default) |
-| Upstream is already TS-compatible AND file paths align 1:1 | **B — Cherry-pick with adaptation**       |
-| Docs / config / static-asset-only (no executable code)     | **C — Direct apply**                      |
-
-```bash
-# Strategy A: re-write upstream change against OmniRoute types & architecture.
-#   Read _references/9router/<path> for source-of-truth context.
-#   Attribute upstream author in commit trailer regardless.
-
-# Strategy B: fetch upstream PR head and cherry-pick
-git fetch upstream "pull/${N}/head:upstream-pr-${N}"
-git cherry-pick upstream-pr-${N}  # resolve TS / architecture conflicts manually
-
-# Strategy C: only for docs/config (use 3-way merge so conflicts surface)
-git apply --3way "../../_tasks/features-v${VERSION}/port-tasks/diff-${N}.patch"
-```
-
-Keep / port upstream tests. Translate them to OmniRoute test conventions
-(`tests/unit/*.test.ts` using `node:test`; MCP via `vitest.mcp.config.ts`).
-
-### Step 5 — Validate (mandatory)
-
-```bash
-npm run check                 # lint + test:unit
-npm run typecheck:core
-npm run typecheck:noimplicit:core
-npm run test:vitest
-npm run check:docs-all
-npm run check:cycles          # always — ports often introduce cross-layer imports
-```
-
-If contracts / providers / schemas were touched:
-
-```bash
-npm run check:route-validation:t06
-npm run check:any-budget:t11
-```
-
-If E2E behaviour was plausibly impacted:
-
-```bash
-npm run test:e2e
-```
-
-If the diff touches `src/app/(dashboard)/` (UI), manual smoke is
-**mandatory** per CLAUDE.md "For UI or frontend changes":
-
-```bash
-npm run dev   # http://localhost:20128
-# Exercise the new/changed UI in a browser. Verify the golden path AND
-# at least one edge case. Watch the console for regressions in other tabs.
-# For release-evidence capture, run /capture-release-evidences afterwards.
-```
-
-No `--no-verify`. No weakening of tests. If something fails, fix the root
-cause.
-
-### Step 6 — Commit with attribution
-
-```bash
-git commit -m "$(cat <<'EOF'
-<type>(<scope>): <description>
-
-<optional body — root cause / mechanism / user-visible effect>
-
-Co-authored-by: <Original Author Name> <author@email>
-Inspired-by: https://github.com/decolua/9router/pull/<N>
-EOF
-)"
-```
-
-- The `Inspired-by` link is the ONLY place the upstream PR is referenced.
-  It MUST NOT appear in the PR body or `CHANGELOG.md`.
-- The `Co-authored-by` trailer credits the **human** upstream author.
-  This is allowed and expected by CLAUDE.md hard rule #16 — that rule
-  bans AI/bot trailers (Claude / GPT / Copilot / etc.), not humans.
-- Use lowercase `Co-authored-by:` (GitHub canonical render form).
-
-### Step 7 — Update CHANGELOG.md (inside the PR, no upstream link)
-
-In the worktree, append to the current release's section in `CHANGELOG.md`:
-
-```markdown
-- **<type>(<scope>):** <description>. (thanks @<upstream-username>)
-```
-
-Commit this change in the same PR — either as a separate commit or amended
-into the feat/fix commit (operator choice). Credit the upstream author
-naturally as a direct contributor; **never** reference the upstream PR URL
-or `decolua/9router` here.
-
-### Step 8 — Push & open PR
-
-> **⚠️ ALWAYS pass `--repo diegosouzapw/OmniRoute`.** Without it,
-> `gh pr create` defaults to the **parent** of a GitHub fork — here that
-> is upstream `decolua/9router`. Verified gotcha (2026-05-23 on
-> ghostty-web): a bare `gh pr create` opened a PR on the upstream
-> tracker by accident. Always set `--repo` and verify with
-> `gh pr view <N> --repo diegosouzapw/OmniRoute` after creation.
-
-```bash
-git push -u origin "$BRANCH"
-OUR_PR_URL=$(gh pr create --repo diegosouzapw/OmniRoute --base "$RELEASE_BRANCH" \
-  --title "<type>(<scope>): <description>" \
-  --body "$(cat <<'EOF'
-## Summary
-
-<1–3 bullets>
-
-## Attribution
-
-Thanks to [@<upstream-username>](https://github.com/<upstream-username>) for the original implementation.
-
-## Changes
-
-- <list>
-
-## Test plan
-
-- [ ] npm run check
-- [ ] npm run typecheck:core && npm run typecheck:noimplicit:core
-- [ ] npm run test:vitest
-- [ ] npm run check:docs-all
-- [ ] npm run check:cycles
-- [ ] npm run test:e2e (if relevant)
-- [ ] Manual UI smoke (if dashboard touched)
-EOF
-)")
-
-# Record in dedupe ledger (Step 2 reads this on next run)
-echo "{\"upstream\":${N},\"our_pr\":\"${OUR_PR_URL}\",\"branch\":\"${BRANCH}\",\"at\":\"$(date -Iseconds)\"}" \
-  >> "_tasks/features-v${VERSION}/port-tasks/_ported.jsonl"
-```
-
-Return the PR URL to the user.
-
-### Step 9 — Cleanup (after merge / abandonment)
-
-```bash
-PR_STATE=$(gh pr view "$OUR_PR_URL" --json state --jq .state)
-git worktree remove ".claude/worktrees/${BRANCH}"
-if [ "$PR_STATE" = "MERGED" ]; then
-  git branch -d "$BRANCH"
-else
-  echo "PR not merged (state=$PR_STATE) — keeping branch '$BRANCH'"
-fi
-```
-
-Task note and ledger entry in `_tasks/features-v${VERSION}/port-tasks/`
-stay as durable local documentation.
-
-## Hard rules
-
-- All work BRANCHES off `release/vX.Y.Z`. Never off `main`. Never push to
-  `main` directly.
-- One PR per ported upstream PR. Do NOT bundle multiple ports in one PR.
-- The upstream PR URL appears ONLY in the commit `Inspired-by` trailer.
-  Never in PR body, CHANGELOG, or any other surface.
-- `Co-authored-by` trailers MUST credit the human upstream author (CLAUDE.md
-  rule #16 allows humans, bans AI/bot trailers).
-- Never widen `src/shared/contracts/` or public route shapes without
-  explicit user OK.
-- Never use `--no-verify`, force-push to release/main, or `--reject` /
-  `--theirs` / `--ours` to shortcut conflicts.
-- Never overwrite a previously-ported PR — the Step 2 dedupe guard
-  (JSONL + git log on `Inspired-by:`) exists for this; never disable it.
-- Verify subagent work yourself per CLAUDE.md: `git status` + `git diff
-  --stat`, sanity-check scope, and re-run the full validation suite
-  before accepting any agent-authored change.
-- License gate is enforced in Step 0; if the upstream LICENSE blob hash
-  changes between sessions, re-confirm before continuing.

.agents/skills/port-upstream-issues-ag/SKILL.md

@@ -1,521 +0,0 @@
----
-name: port-upstream-issues-ag
-description: Migrated command port-upstream-issues-ag
----
-
-# /port-upstream-issues — Resolve issues reported on upstream `decolua/9router`
-
-## ⚠️ CONFIDENTIAL — This workflow is `.gitignored` and must NEVER be committed.
-
-## Overview
-
-Companion to `port-upstream-features-ag.md`. While that workflow ports
-upstream **PRs**, this one harvests upstream **open issues** (bugs filed on
-[`decolua/9router`](https://github.com/decolua/9router)), reproduces them
-against OmniRoute, and lands fixes in OmniRoute with full attribution to
-the upstream reporter.
-
-This is NOT the same as `/resolve-issues`:
-
-| Workflow | Repo whose issues we read | Issues we close on |
-|----------|---------------------------|--------------------|
-| `/resolve-issues` | `diegosouzapw/OmniRoute` (our own) | our own |
-| `/port-upstream-issues` (this) | `decolua/9router` (upstream, JS) | NONE — we never touch upstream tracker |
-
-> **NEVER comment, close, or react on `decolua/9router`'s issue tracker.**
-> Upstream is owned by the original maintainer. Our work is local to
-> OmniRoute.
-
-## Inputs
-
-The user provides:
-
-- One or more **upstream issue identifiers** — bare numbers (`1317 1320`),
-  full URLs (`https://github.com/decolua/9router/issues/1317`), or a mix.
-- Optionally, notes about scope or which buckets to skip.
-
-If no input is provided, the agent harvests ALL open upstream issues and
-triages before any code change.
-
-## Constants (hard-coded — do not infer)
-
-- **Upstream**: `decolua/9router` (JavaScript, Next.js 16)
-- **Fork (origin)**: `diegosouzapw/OmniRoute` (TypeScript, Next.js 16)
-- **Worktree root**: `.claude/worktrees/`
-- **Task notes**: `_tasks/features-v${VERSION}/port-upstream-issues/`
-- **Dedupe ledger**: `_tasks/features-v${VERSION}/port-upstream-issues/_resolved.jsonl`
-- **Upstream sources mirror (read-only)**: `_references/9router/`
-
-## Architecture mapping (upstream → OmniRoute)
-
-Single source of truth for where upstream files land in OmniRoute. Use it
-when reproducing each bug and planning the fix. OmniRoute has layers that
-don't exist upstream (a2a, memory, cloudAgent, guardrails, evals); when
-an upstream bug touches functionality routed through one of those layers
-downstream, MAP IT and note it in the triage.
-
-| Upstream (9router, JS)                                  | OmniRoute (TS)                                                                                                    | Notes                                                |
-| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
-| `src/app/api/v1/...`                                    | `src/app/api/v1/...`                                                                                              | Public LLM API surface — same shape                  |
-| `src/app/api/...` (dashboard / cli-tools / oauth)       | `src/app/api/...`                                                                                                 | Internal dashboard API                               |
-| `src/app/(dashboard)/dashboard/...`                     | `src/app/(dashboard)/dashboard/...`                                                                               | UI                                                   |
-| `src/app/landing/`                                      | `src/app/landing/`                                                                                                | Marketing pages                                      |
-| `src/sse/handlers/` `src/sse/services/`                 | `src/sse/handlers/` `src/sse/services/`                                                                           | Legacy streaming layer (still active in both)        |
-| `open-sse/handlers/`                                    | `open-sse/handlers/`                                                                                              | Modern handler layer                                 |
-| `open-sse/executors/*.js`                               | `open-sse/executors/*.ts`                                                                                         | One per provider — TS in OmniRoute                   |
-| `open-sse/services/`                                    | `open-sse/services/`                                                                                              | Combo, accountFallback, model, etc.                  |
-| `open-sse/translator/` `open-sse/transformer/`          | `open-sse/translator/` `open-sse/transformer/`                                                                    | Format conversion + Responses API                    |
-| `open-sse/rtk/` (request toolkit)                       | `open-sse/services/` or `open-sse/utils/`                                                                         | No 1:1 — fold into nearest service                   |
-| `open-sse/config/` `open-sse/utils/` `open-sse/lib/`    | `open-sse/config/` `open-sse/utils/` `open-sse/lib/`                                                              |                                                      |
-| `src/lib/mcp/`                                          | `open-sse/mcp-server/`                                                                                            | MCP moved into open-sse workspace                    |
-| `src/lib/db/` (adapters / helpers / migrations / repos) | `src/lib/db/` (45+ domain modules, 55 migrations)                                                                 | `localDb.ts` is RE-EXPORT ONLY (hard rule #2)        |
-| `src/lib/oauth/`                                        | `src/lib/oauth/`                                                                                                  |                                                      |
-| `src/lib/auth/`                                         | `src/server/authz/` + `src/lib/auth*`                                                                             | OmniRoute splits server-side vs lib helpers          |
-| `src/lib/network/`                                      | `src/shared/utils/` or `open-sse/utils/`                                                                          | Fold by purpose                                      |
-| `src/lib/tunnel/` `src/lib/updater/` `src/lib/usage/`   | `src/lib/services/` (bootstrap) + module per concern                                                              | OmniRoute consolidates as embedded services          |
-| `src/mitm/`                                             | `src/mitm/`                                                                                                       | Cert / dns / handlers preserved                      |
-| `src/models/`                                           | `src/models/`                                                                                                     | Domain models                                        |
-| `src/shared/`                                           | `src/shared/`                                                                                                     | Constants, components, hooks, services, utils        |
-| `src/store/` (Zustand)                                  | `src/store/`                                                                                                      |                                                      |
-| `src/i18n/` + `public/i18n/literals/`                   | `src/i18n/` + `public/i18n/literals/`                                                                             | i18n keys MUST be added in ALL locales               |
-| `skills/9router-*` (top-level spec dirs)                | `src/lib/skills/` (framework) + `skills/` (specs)                                                                 | Different shape — framework vs spec files            |
-| `cli/`                                                  | `bin/` (entry) + `src/lib/services/` modules                                                                      | OmniRoute folded most CLI into the main app          |
-| `gitbook/`                                              | `docs/`                                                                                                           | Markdown only; no gitbook in OmniRoute               |
-| (no equivalent upstream)                                | `src/lib/a2a/` `src/lib/memory/` `src/lib/cloudAgent/` `src/lib/guardrails/` `src/lib/evals/` `electron/` `tests/` | OmniRoute-only — bugs here are downstream-specific   |
-
-## Steps
-
-### 1. Sanity + setup
-
-```bash
-git -C . remote get-url origin     # must end in diegosouzapw/OmniRoute
-git branch --show-current          # must be release/vX.Y.Z
-gh auth status
-
-VERSION=$(node -p "require('./package.json').version")
-RELEASE_BRANCH=$(git branch --show-current)
-
-# Idempotent upstream remote (may be needed to inspect specific upstream commits when reproducing)
-git remote get-url upstream 2>/dev/null \
-  || git remote add upstream https://github.com/decolua/9router.git
-git fetch upstream --quiet
-
-# License gate — confirm once per session, cache the LICENSE blob hash
-UPSTREAM_LICENSE_SHA=$(git -C _references/9router rev-parse HEAD:LICENSE 2>/dev/null)
-echo "Upstream LICENSE blob: $UPSTREAM_LICENSE_SHA"
-# Read _references/9router/LICENSE and confirm permissive (MIT / Apache-2.0 / BSD-style).
-# If unsure or the hash changed since last session, ESCALATE TO USER before continuing.
-
-mkdir -p "_tasks/features-v${VERSION}/port-upstream-issues"
-touch    "_tasks/features-v${VERSION}/port-upstream-issues/_resolved.jsonl"
-```
-
-If on `main`, follow `/generate-release` Phase 1 steps 1–5 to create the
-next `release/vX.Y.Z` before continuing. All work BRANCHES off the release
-branch.
-
-### 2. Harvest Open Upstream Issues
-
-⚠️ The JSON output of `gh issue list` can be silently truncated. Use the
-two-step approach:
-
-**2a — Numbers only** (small, never truncated):
-
-```bash
-HARV="_tasks/features-v${VERSION}/port-upstream-issues"
-gh issue list --repo decolua/9router --state open --limit 500 \
-  --json number --jq '.[].number' \
-  > "$HARV/_numbers.txt"
-wc -l "$HARV/_numbers.txt"
-```
-
-**2b — Full metadata per issue** (sequential to avoid rate-limit bursts):
-
-```bash
-for N in $(cat "$HARV/_numbers.txt"); do
-  gh issue view "$N" --repo decolua/9router \
-    --json number,title,labels,body,comments,createdAt,updatedAt,author,reactionGroups
-done > "$HARV/_raw.jsonl"
-```
-
-### 3. Cross-Reference Upstream Open PRs
-
-For every issue, check whether an open upstream PR already addresses it
-(`fixes #N`, `closes #N`, `for #N`, body mentions). If yes, the canonical
-path is **`/port-upstream-features`** with that PR, NOT a re-implementation
-here.
-
-```bash
-gh pr list --repo decolua/9router --state open --limit 500 \
-  --json number,title,body \
-  > "$HARV/_open_prs.json"
-```
-
-### 4. Triage Each Issue (NO code yet)
-
-For every issue — first normalize input and run the dedupe pre-check
-BEFORE any expensive analysis:
-
-```bash
-# normalize: "https://github.com/decolua/9router/issues/1317" → "1317"
-N=$(echo "$arg" | sed -E 's|.*/issues/([0-9]+).*|\1|; s|^#||')
-
-# dedupe — defense in depth (JSONL snapshot + git log as source of truth)
-LEDGER="$HARV/_resolved.jsonl"
-if grep -q "\"upstream\":${N}\b" "$LEDGER" 2>/dev/null \
-   || git log --all --grep "Reported-by:.*decolua/9router/issues/${N}\b" --oneline | grep -q .; then
-  echo "Issue #${N} already resolved here — skipping"; continue
-fi
-```
-
-Then produce `$HARV/<N>-<short-kebab>.triage.md` using the template at the
-bottom of this file. Classify each into ONE bucket:
-
-| Bucket | Meaning | Next action |
-|--------|---------|-------------|
-| `security`       | Security-sensitive (RCE, auth bypass, SSRF, etc.) | Handle FIRST, alone, with its own PR |
-| `viable-self`    | Bug, reproducible against OmniRoute, fix in scope | Phase 5+ |
-| `viable-port`    | Already addressed by an open upstream PR | Hand off to `/port-upstream-features` |
-| `not-applicable` | Bug specific to 9router internals not mirrored in OmniRoute | Document and skip |
-| `needs-repro`    | Cannot reproduce locally / not enough info | Document; skip until repro |
-| `out-of-scope`   | Requires native module changes, new infra, etc. | Document and skip |
-| `wontfix`        | Conflicts with OmniRoute's direction | Document with reason |
-
-**Reproduction is mandatory before `viable-self`.** OmniRoute is TypeScript
-on Next.js; many 9router bugs simply do not exist here because the
-implementation is different. If you cannot reproduce against OmniRoute,
-the bucket is `not-applicable` or `needs-repro`, never `viable-self`.
-
-Use the architecture mapping above to locate the equivalent OmniRoute
-file(s) and read them (NOT just the upstream `_references/9router/` copy)
-when deciding reproducibility.
-
-### 5. Analyse Compatibility (for `viable-self`)
-
-For each `viable-self` issue, before writing a fix plan, map:
-
-- **Affected area**: which row of the architecture mapping is hit?
-- **Code locality**: read the 9router source files referenced (or implied)
-  by the issue and the equivalent OmniRoute file(s). Note divergence.
-- **JS → TS adaptation**: type signatures, null/undefined handling,
-  `unknown` vs `any`, ESM vs CJS specifics.
-- **DB / schema impact**: any migration needed? How does it interact with
-  the existing 55 migrations?
-- **i18n keys**: any new UI strings → translation keys in ALL locales?
-- **OmniRoute-only impact**: does this surface through a2a / memory /
-  cloudAgent / guardrails / evals?
-- **Tests**: which OmniRoute test suite must cover the regression?
-  Default to `tests/unit/<scope>.test.ts`.
-
-### 6. Present Plan & Wait
-
-Summarise to the user, in this order:
-
-1. **Security findings first** with severity and proposed handling.
-2. Counts per bucket and totals.
-3. Top `viable-self` ranked by user impact and fix size.
-4. Top `viable-port` candidates with upstream PR numbers (hand-off to
-   `/port-upstream-features`).
-5. Open questions for the user (anything ambiguous in `out-of-scope` /
-   `wontfix` / `not-applicable` that may need re-bucketing).
-
-> **⚠️ Do NOT touch code until the user explicitly names which issues to
-> fix in this batch.**
-
-### 7. Implementation (one worktree per fix)
-
-For each approved issue `N`:
-
-```bash
-BRANCH="fix/port-issue-${N}-<short-kebab>"
-git worktree add ".claude/worktrees/${BRANCH}" -b "$BRANCH" "$RELEASE_BRANCH"
-cd ".claude/worktrees/${BRANCH}"
-npm install
-```
-
-#### 7.1 Write the failing regression test FIRST
-
-Default to `tests/unit/<scope>.test.ts`. For network/E2E-shaped bugs use
-`tests/integration/` or `tests/e2e/`. Iterate against the specific file:
-
-```bash
-npm run test:unit -- --test tests/unit/<scope>.test.ts
-```
-
-#### 7.2 Smallest possible fix
-
-- Do not refactor unrelated code in the same commit.
-- Do not change public route shapes unless the issue requires it.
-- Match the existing TypeScript style. Run `npm run lint` after editing.
-
-#### 7.3 Validate locally — mandatory
-
-```bash
-npm run check                 # lint + test:unit
-npm run typecheck:core
-npm run typecheck:noimplicit:core
-npm run test:vitest           # MCP server tests
-npm run check:docs-all        # docs-sync gates
-npm run check:cycles          # always — fixes sometimes add imports
-```
-
-If the change touches contracts, providers, or schemas, also:
-
-```bash
-npm run check:route-validation:t06
-npm run check:any-budget:t11
-```
-
-If end-to-end behaviour is plausibly impacted:
-
-```bash
-npm run test:e2e
-```
-
-If the fix touches `src/app/(dashboard)/` (UI), manual smoke is
-**mandatory** per CLAUDE.md "For UI or frontend changes":
-
-```bash
-npm run dev   # http://localhost:20128
-# Reproduce the original bug scenario and verify it's gone.
-# Watch the console for regressions in other tabs.
-```
-
-NO `--no-verify`. Do NOT weaken existing tests. Investigate root cause if
-something pre-existing fails.
-
-#### 7.4 Commit
-
-```bash
-git commit -m "$(cat <<'EOF'
-fix(<scope>): <description> (port from 9router#<N>)
-
-<short body — root cause and user-visible effect>
-
-Reported-by: <Reporter Name> (https://github.com/decolua/9router/issues/<N>)
-EOF
-)"
-```
-
-- The upstream issue link lives ONLY in this commit trailer. It does NOT
-  appear in the PR body or in `CHANGELOG.md`.
-- If a third party contributed a substantive patch/fix in the upstream
-  issue comments, add `Co-authored-by: <Name> <email>` as well.
-- Per CLAUDE.md hard rule #16: `Co-authored-by` is allowed and required
-  for human contributors; it is forbidden only for AI/bot trailers
-  (Claude / GPT / Copilot / etc.).
-- Use lowercase `Reported-by:` and `Co-authored-by:` (GitHub canonical
-  render form).
-
-#### 7.5 Update CHANGELOG.md (inside the PR, no upstream link)
-
-In the worktree, append to the current release's section in `CHANGELOG.md`:
-
-```markdown
-- **fix(<scope>):** <description>. (thanks @<upstream-reporter-username>)
-```
-
-Commit this change in the same PR — either as a separate commit or amended
-into the fix commit (operator choice). Credit the reporter naturally;
-**never** reference `decolua/9router` in `CHANGELOG.md`.
-
-#### 7.6 Push & open PR
-
-> **⚠️ FORK-PR GOTCHA**: bare `gh pr create` defaults to the fork's
-> PARENT (upstream `decolua/9router`). ALWAYS pass `--repo
-> diegosouzapw/OmniRoute`. Verified gotcha (2026-05-23 on ghostty-web).
-
-```bash
-git push -u origin "$BRANCH"
-OUR_PR_URL=$(gh pr create --repo diegosouzapw/OmniRoute --base "$RELEASE_BRANCH" \
-  --title "fix(<scope>): <description>" \
-  --body "$(cat <<'EOF'
-## Summary
-
-<bullets>
-
-## Root cause
-
-<what was actually broken>
-
-## Fix
-
-<what changed>
-
-## Attribution
-
-Thanks to [@<reporter-username>](https://github.com/<reporter-username>) for the original report.
-
-## Test plan
-
-- [ ] New regression test at tests/unit/<scope>.test.ts
-- [ ] npm run check
-- [ ] npm run typecheck:core && npm run typecheck:noimplicit:core
-- [ ] npm run test:vitest
-- [ ] npm run check:docs-all
-- [ ] npm run check:cycles
-- [ ] Manual UI smoke (if dashboard touched)
-EOF
-)")
-```
-
-#### 7.7 Record in dedupe ledger
-
-```bash
-echo "{\"upstream\":${N},\"our_pr\":\"${OUR_PR_URL}\",\"branch\":\"${BRANCH}\",\"at\":\"$(date -Iseconds)\"}" \
-  >> "$HARV/_resolved.jsonl"
-```
-
-Step 4's dedupe pre-check reads this on the next run; the `Reported-by`
-trailer in the commit serves as the redundant source of truth.
-
-Mark the triage note: set `Status: resolved` and record the merged PR URL.
-
-#### 7.8 Cleanup (after merge / abandonment)
-
-```bash
-PR_STATE=$(gh pr view "$OUR_PR_URL" --json state --jq .state)
-git worktree remove ".claude/worktrees/${BRANCH}"
-if [ "$PR_STATE" = "MERGED" ]; then
-  git branch -d "$BRANCH"
-else
-  echo "PR not merged (state=$PR_STATE) — keeping branch '$BRANCH'"
-fi
-```
-
-### 8. Roll-up
-
-Once the batch is merged, report to the user:
-
-- Fixed (with our PR URLs on `diegosouzapw/OmniRoute`)
-- Handed off to `/port-upstream-features` (with upstream PR numbers)
-- Deferred (with reasons)
-- New issues opened on **our** fork (`diegosouzapw/OmniRoute`) for any
-  remaining work worth tracking — **never** open issues on
-  `decolua/9router`.
-
----
-
-## Triage Note Template
-
-```markdown
-# Upstream Issue #<N>: <Title>
-
-## Source
-
-| Field | Value |
-|-------|-------|
-| Upstream issue | [decolua/9router#<N>](https://github.com/decolua/9router/issues/<N>) |
-| Reporter | [@<username>](https://github.com/<username>) |
-| Filed | <YYYY-MM-DD> |
-| Last activity | <YYYY-MM-DD> |
-| Labels | <list> |
-
-## Bucket
-
-`security` | `viable-self` | `viable-port` | `not-applicable` | `needs-repro` | `out-of-scope` | `wontfix`
-
-## Summary
-
-<2–4 sentence restatement of the bug, in our words.>
-
-## Reproduction against OmniRoute
-
-- [ ] Reproduced locally on `release/vX.Y.Z`
-- Steps:
-  1. ...
-  2. ...
-- Expected: ...
-- Actual: ...
-
-## Architecture mapping
-
-- 9router file(s): `<upstream path>` (also visible in `_references/9router/<path>`)
-- OmniRoute file(s): `<our path>` (per the architecture mapping table at the top of this workflow)
-- OmniRoute-only layers involved: `<a2a / memory / cloudAgent / guardrails / evals / none>`
-
-## Related upstream PR
-
-<#NNN — if `viable-port`, link here and STOP this workflow for that issue. Otherwise: none.>
-
-## JS → TS notes
-
-<Type signatures, null handling, ESM specifics that differ from 9router.>
-
-## Fix plan
-
-<Bullet plan, OR reason for the chosen non-fix bucket.>
-
-## Risks
-
-- Public API change: no / yes (describe)
-- Schema / migration: no / yes (describe)
-- i18n keys: no / yes (list — ALL locales)
-- Performance: no / yes (describe)
-
-## Validation checklist
-
-- [ ] Failing regression test added first
-- [ ] `npm run check`
-- [ ] `npm run typecheck:core`
-- [ ] `npm run typecheck:noimplicit:core`
-- [ ] `npm run test:vitest`
-- [ ] `npm run check:docs-all`
-- [ ] `npm run check:cycles`
-- [ ] `npm run test:e2e` (if E2E impacted)
-- [ ] Manual UI smoke on `npm run dev` (if dashboard touched)
-
-## Attribution applied
-
-- [ ] Commit trailer: `Reported-by` (+ `Co-authored-by` if upstream comment patch)
-- [ ] CHANGELOG.md inside the PR: `(thanks @<reporter>)` — NO upstream link
-- [ ] PR body: thanks block (reporter only, NO upstream link)
-- [ ] Ledger entry written on PR creation
-
-## Status
-
-`triaged` | `in-progress` | `resolved` | `deferred` | `wontfix`
-
-## Resolution
-
-<Filled in when status = resolved. Include the merged PR URL on our fork.>
-```
-
----
-
-## Hard rules
-
-- Security first. Always. Alone, on its own worktree, its own PR.
-- Reproduce before claiming a fix. No "blind" fixes.
-- All work BRANCHES off `release/vX.Y.Z`. Never off `main`. Never push to
-  `main` directly.
-- One PR per fix. Do NOT bundle.
-- Never weaken existing tests to go green.
-- Never use `--no-verify`, force-push to release/main, or `--reject` /
-  `--theirs` / `--ours` to shortcut conflicts.
-- Never interact with `decolua/9router`'s issue tracker (no comments,
-  closes, reactions, or referenced fixes from our commits).
-- Never widen `src/shared/contracts/` or public route shapes without
-  explicit user OK.
-- Upstream issue URL lives ONLY in the `Reported-by` commit trailer.
-  Never in PR body, CHANGELOG, or any other surface.
-- `Co-authored-by` trailers MUST credit human contributors only (CLAUDE.md
-  rule #16 allows humans, bans AI/bot trailers).
-- Never overwrite a previously-resolved issue — the Step 4 dedupe guard
-  (JSONL + git log on `Reported-by:`) exists for this; never disable it.
-- Verify subagent work yourself per CLAUDE.md: `git status` + `git diff
-  --stat`, sanity-check scope, full validation suite before accepting.
-- License gate is enforced in Step 1; if the upstream LICENSE blob hash
-  changes between sessions, re-confirm before continuing.
-
-## Notes
-
-- This workflow is **local-only**. The `_tasks/` directory is covered by
-  the `/_*/` gitignore rule, and this `.md` file is individually listed in
-  `.gitignore` alongside `port-upstream-features-ag.md`.
-- The dedupe ledger (`_resolved.jsonl`) is local-only documentation, NOT
-  tracked. The git `Reported-by:` trailer is the authoritative record.
-- If a downstream consumer (another project of yours) is blocked by a
-  specific upstream issue, prioritise it regardless of bucket size.
-- Companion sibling: `port-upstream-features-ag.md` for upstream PR
-  porting.

.agents/skills/port-upstream-issues-cc/SKILL.md

@@ -1,366 +0,0 @@
----
-name: port-upstream-issues-cc
-description: Triage and fix open issues from upstream decolua/9router against OmniRoute. Reproduce first, security first, one worktree per fix, attribution preserved.
----
-
-# /port-upstream-issues — Resolve upstream-reported bugs in OmniRoute
-
-## ⚠️ CONFIDENTIAL — this command is `.gitignored` and must NEVER be committed.
-
-Full reference: `.agents/workflows/port-upstream-issues-ag.md`.
-Sibling command (PR tracker, not issues): `/port-upstream-features`.
-
-> **NOT THE SAME AS `/resolve-issues`.** `/resolve-issues` works on
-> **OmniRoute's own** issue tracker. This command reads issues filed on
-> **`decolua/9router`** (upstream) and lands fixes here, without ever
-> touching the upstream tracker.
-
-## Inputs
-
-Arguments: `$ARGUMENTS` (optional). Accepts a space-separated list of
-upstream issue identifiers — bare numbers (`1317 1320`), full URLs
-(`https://github.com/decolua/9router/issues/1317`), or a mix. If empty,
-the command harvests ALL open upstream issues and triages before any code
-change.
-
-## Constants (hard-coded — do not infer)
-
-- Upstream: `decolua/9router` (JavaScript, Next.js 16)
-- Fork (origin): `diegosouzapw/OmniRoute` (TypeScript, Next.js 16)
-- Worktree root: `.claude/worktrees/`
-- Task notes: `_tasks/features-v${VERSION}/port-upstream-issues/`
-- Dedupe ledger: `_tasks/features-v${VERSION}/port-upstream-issues/_resolved.jsonl`
-- Upstream sources mirror (read-only): `_references/9router/`
-- We NEVER comment, close, or react on `decolua/9router`'s issue tracker.
-
-## Architecture mapping (upstream → OmniRoute)
-
-Use this table when reproducing each bug and planning the fix. OmniRoute
-has layers that don't exist upstream (a2a, memory, cloudAgent, guardrails,
-evals); when an upstream bug touches functionality routed through one of
-those layers downstream, MAP IT and note it in the triage.
-
-| Upstream (9router, JS)                                | OmniRoute (TS)                                                                                                    | Notes                                                |
-| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
-| `src/app/api/v1/...`                                  | `src/app/api/v1/...`                                                                                              | Public LLM API surface — same shape                  |
-| `src/app/api/...` (dashboard / cli-tools / oauth)     | `src/app/api/...`                                                                                                 | Internal dashboard API                               |
-| `src/app/(dashboard)/dashboard/...`                   | `src/app/(dashboard)/dashboard/...`                                                                               | UI                                                   |
-| `src/app/landing/`                                    | `src/app/landing/`                                                                                                | Marketing pages                                      |
-| `src/sse/handlers/` `src/sse/services/`               | `src/sse/handlers/` `src/sse/services/`                                                                           | Legacy streaming layer (still active in both)        |
-| `open-sse/handlers/`                                  | `open-sse/handlers/`                                                                                              | Modern handler layer                                 |
-| `open-sse/executors/*.js`                             | `open-sse/executors/*.ts`                                                                                         | One per provider — TS in OmniRoute                   |
-| `open-sse/services/`                                  | `open-sse/services/`                                                                                              | Combo, accountFallback, model, etc.                  |
-| `open-sse/translator/` `open-sse/transformer/`        | `open-sse/translator/` `open-sse/transformer/`                                                                    | Format conversion + Responses API                    |
-| `open-sse/rtk/` (request toolkit)                     | `open-sse/services/` or `open-sse/utils/`                                                                         | No 1:1 — fold into nearest service                   |
-| `open-sse/config/` `open-sse/utils/` `open-sse/lib/`  | `open-sse/config/` `open-sse/utils/` `open-sse/lib/`                                                              |                                                      |
-| `src/lib/mcp/`                                        | `open-sse/mcp-server/`                                                                                            | MCP moved into open-sse workspace                    |
-| `src/lib/db/` (adapters / helpers / migrations / repos) | `src/lib/db/` (45+ domain modules, 55 migrations)                                                               | `localDb.ts` is RE-EXPORT ONLY (hard rule #2)        |
-| `src/lib/oauth/`                                      | `src/lib/oauth/`                                                                                                  |                                                      |
-| `src/lib/auth/`                                       | `src/server/authz/` + `src/lib/auth*`                                                                             | OmniRoute splits server-side vs lib helpers          |
-| `src/lib/network/`                                    | `src/shared/utils/` or `open-sse/utils/`                                                                          | Fold by purpose                                      |
-| `src/lib/tunnel/` `src/lib/updater/` `src/lib/usage/` | `src/lib/services/` (bootstrap) + module per concern                                                              | OmniRoute consolidates as embedded services          |
-| `src/mitm/`                                           | `src/mitm/`                                                                                                       | Cert / dns / handlers preserved                      |
-| `src/models/`                                         | `src/models/`                                                                                                     | Domain models                                        |
-| `src/shared/`                                         | `src/shared/`                                                                                                     | Constants, components, hooks, services, utils        |
-| `src/store/` (Zustand)                                | `src/store/`                                                                                                      |                                                      |
-| `src/i18n/` + `public/i18n/literals/`                 | `src/i18n/` + `public/i18n/literals/`                                                                             | i18n keys MUST be added in ALL locales               |
-| `skills/9router-*` (top-level spec dirs)              | `src/lib/skills/` (framework) + `skills/` (specs)                                                                 | Different shape — framework vs spec files            |
-| `cli/`                                                | `bin/` (entry) + `src/lib/services/` modules                                                                      | OmniRoute folded most CLI into the main app          |
-| `gitbook/`                                            | `docs/`                                                                                                           | Markdown only; no gitbook in OmniRoute               |
-| (no equivalent upstream)                              | `src/lib/a2a/` `src/lib/memory/` `src/lib/cloudAgent/` `src/lib/guardrails/` `src/lib/evals/` `electron/` `tests/` | OmniRoute-only — bugs here are downstream-specific   |
-
-## Execution
-
-### Step 0 — Sanity + setup
-
-```bash
-git -C . remote get-url origin     # must end in diegosouzapw/OmniRoute
-git branch --show-current          # must be release/vX.Y.Z
-gh auth status
-
-VERSION=$(node -p "require('./package.json').version")
-RELEASE_BRANCH=$(git branch --show-current)
-
-# Idempotent upstream remote (we may need to inspect specific upstream commits to reproduce)
-git remote get-url upstream 2>/dev/null \
-  || git remote add upstream https://github.com/decolua/9router.git
-git fetch upstream --quiet
-
-# License gate — confirm once per session, cache the LICENSE blob hash
-UPSTREAM_LICENSE_SHA=$(git -C _references/9router rev-parse HEAD:LICENSE 2>/dev/null)
-echo "Upstream LICENSE blob: $UPSTREAM_LICENSE_SHA"
-# Read _references/9router/LICENSE and confirm permissive (MIT / Apache-2.0 / BSD-style).
-# If unsure or the hash changed since last session, ESCALATE TO USER before continuing.
-
-mkdir -p "_tasks/features-v${VERSION}/port-upstream-issues"
-touch    "_tasks/features-v${VERSION}/port-upstream-issues/_resolved.jsonl"
-```
-
-If on `main`, follow `/generate-release` Phase 1 steps 1–5 to create the
-next `release/vX.Y.Z` first.
-
-### Step 1 — Harvest (two-step pattern to avoid JSON truncation)
-
-```bash
-HARV="_tasks/features-v${VERSION}/port-upstream-issues"
-
-# 1a — numbers only, never truncated
-gh issue list --repo decolua/9router --state open --limit 500 \
-  --json number --jq '.[].number' \
-  > "$HARV/_numbers.txt"
-
-# 1b — full metadata per issue, batched (sequential to avoid rate-limit bursts)
-for N in $(cat "$HARV/_numbers.txt"); do
-  gh issue view "$N" --repo decolua/9router \
-    --json number,title,labels,body,comments,createdAt,updatedAt,author,reactionGroups
-done > "$HARV/_raw.jsonl"
-
-# 1c — open upstream PRs for cross-reference
-gh pr list --repo decolua/9router --state open --limit 500 \
-  --json number,title,body \
-  > "$HARV/_open_prs.json"
-```
-
-For each issue, scan `_open_prs.json` for `fixes #N`, `closes #N`, `for
-#N`. Issues with an open PR are `viable-port` — they belong to
-`/port-upstream-features`, not here.
-
-### Step 2 — Triage (no code yet)
-
-For each issue, first normalize input and dedupe-check:
-
-```bash
-# normalize: "https://github.com/decolua/9router/issues/1317" → "1317"
-N=$(echo "$arg" | sed -E 's|.*/issues/([0-9]+).*|\1|; s|^#||')
-
-# dedupe — defense in depth (JSONL snapshot + git log as source of truth)
-LEDGER="_tasks/features-v${VERSION}/port-upstream-issues/_resolved.jsonl"
-if grep -q "\"upstream\":${N}\b" "$LEDGER" 2>/dev/null \
-   || git log --all --grep "Reported-by:.*decolua/9router/issues/${N}\b" --oneline | grep -q .; then
-  echo "Issue #${N} already resolved here — skipping"; continue
-fi
-```
-
-Then write
-`_tasks/features-v${VERSION}/port-upstream-issues/<N>-<short-kebab>.triage.md`
-using the template in the reference workflow. Buckets:
-
-- `security`        — handled FIRST, alone, with its own PR
-- `viable-self`     — bug, reproducible against OmniRoute, fix in scope
-- `viable-port`     — already addressed by an open upstream PR → hand-off
-- `not-applicable`  — 9router-only bug; OmniRoute architecture diverges
-- `needs-repro`     — cannot reproduce / not enough info
-- `out-of-scope`    — needs infra change / new module
-- `wontfix`         — conflicts with OmniRoute direction
-
-**Reproduce before promising a fix.** OmniRoute is TS / Next.js; many
-9router bugs don't exist here (different runtime, different layer, fixed
-already). If you cannot reproduce, the bucket is `not-applicable` or
-`needs-repro`, NEVER `viable-self`.
-
-Use the architecture mapping above to locate the equivalent OmniRoute
-file(s) and read them (NOT the upstream `_references/9router/` copy) when
-deciding reproducibility.
-
-### Step 3 — Present plan and wait
-
-Summarise in this order:
-
-1. **Security findings first**, with severity.
-2. Counts per bucket.
-3. Top `viable-self` ranked by impact / fix size.
-4. Top `viable-port` with upstream PR numbers (hand-off to
-   `/port-upstream-features`).
-5. `out-of-scope` / `wontfix` items the user might want to re-bucket.
-
-**Do not touch code until the user names which issues to fix in this batch.**
-
-### Step 4 — Implement (one worktree per fix)
-
-For each approved issue `N`:
-
-```bash
-BRANCH="fix/port-issue-${N}-<short>"
-git worktree add ".claude/worktrees/${BRANCH}" -b "$BRANCH" "$RELEASE_BRANCH"
-cd ".claude/worktrees/${BRANCH}"
-npm install
-```
-
-#### 4.1 Write the failing regression test FIRST
-
-Default suite is `tests/unit/<scope>.test.ts` using `node:test`. For
-network-shaped bugs use `tests/integration/`. MCP-shaped issues use
-`vitest.mcp.config.ts`. Iterate against the single file:
-
-```bash
-npm run test:unit -- --test tests/unit/<scope>.test.ts
-```
-
-#### 4.2 Smallest possible fix
-
-- One commit, one concern. No drive-by refactors.
-- No public route / contract shape changes unless the issue demands it
-  (flag first).
-- Match the existing TS style. Run `npm run lint` after editing.
-
-#### 4.3 Validate locally — mandatory
-
-```bash
-npm run check                 # lint + test:unit
-npm run typecheck:core
-npm run typecheck:noimplicit:core
-npm run test:vitest
-npm run check:docs-all
-npm run check:cycles          # always — fixes sometimes add imports
-```
-
-If contracts / providers / schemas were touched:
-
-```bash
-npm run check:route-validation:t06
-npm run check:any-budget:t11
-```
-
-If E2E behaviour was plausibly impacted:
-
-```bash
-npm run test:e2e
-```
-
-If the fix touches `src/app/(dashboard)/` (UI), manual smoke is
-**mandatory** per CLAUDE.md "For UI or frontend changes":
-
-```bash
-npm run dev   # http://localhost:20128
-# Reproduce the original bug scenario and verify it's gone.
-# Watch the console for regressions in other tabs.
-```
-
-NO `--no-verify`. Do not weaken pre-existing tests. Debug root cause.
-
-#### 4.4 Commit
-
-```bash
-git commit -m "$(cat <<'EOF'
-fix(<scope>): <description> (port from 9router#<N>)
-
-<short body — root cause and user-visible effect>
-
-Reported-by: <Reporter Name> (https://github.com/decolua/9router/issues/<N>)
-EOF
-)"
-```
-
-- The upstream issue URL lives ONLY in this trailer.
-- Add `Co-authored-by: <Name> <email>` ONLY if a third party contributed
-  a substantive patch in the upstream issue comments — not for the report
-  alone. Per CLAUDE.md rule #16, human co-authors are allowed; AI/bot
-  trailers (Claude / GPT / Copilot / etc.) are not.
-- Use lowercase `Co-authored-by:` / `Reported-by:` (GitHub canonical
-  render form).
-
-#### 4.5 Update CHANGELOG.md (inside the PR, no upstream link)
-
-In the worktree, append to the current release's section in `CHANGELOG.md`:
-
-```markdown
-- **fix(<scope>):** <description>. (thanks @<reporter-username>)
-```
-
-Commit this change in the same PR — either as a separate commit or amended
-into the fix commit (operator choice). Credit the reporter naturally;
-**never** reference `decolua/9router` in `CHANGELOG.md`.
-
-#### 4.6 Push & open PR
-
-> **⚠️ CRITICAL**: pass `--repo diegosouzapw/OmniRoute`. Bare `gh pr
-> create` defaults to the fork's PARENT (upstream `decolua/9router`).
-> Verified gotcha (2026-05-23 on ghostty-web).
-
-```bash
-git push -u origin "$BRANCH"
-OUR_PR_URL=$(gh pr create --repo diegosouzapw/OmniRoute --base "$RELEASE_BRANCH" \
-  --title "fix(<scope>): <description>" \
-  --body "$(cat <<'EOF'
-## Summary
-
-<bullets>
-
-## Root cause
-
-<what was actually broken>
-
-## Fix
-
-<what changed>
-
-## Attribution
-
-Thanks to [@<reporter-username>](https://github.com/<reporter-username>) for the original report.
-
-## Test plan
-
-- [ ] New regression test at tests/unit/<scope>.test.ts
-- [ ] npm run check
-- [ ] npm run typecheck:core && npm run typecheck:noimplicit:core
-- [ ] npm run test:vitest
-- [ ] npm run check:docs-all
-- [ ] npm run check:cycles
-- [ ] Manual UI smoke (if dashboard touched)
-EOF
-)")
-
-# Record in dedupe ledger (Step 2 reads this on next run)
-echo "{\"upstream\":${N},\"our_pr\":\"${OUR_PR_URL}\",\"branch\":\"${BRANCH}\",\"at\":\"$(date -Iseconds)\"}" \
-  >> "_tasks/features-v${VERSION}/port-upstream-issues/_resolved.jsonl"
-```
-
-Return the PR URL to the user. Update the triage note: `Status: resolved`
-+ merged PR URL.
-
-#### 4.7 Cleanup (after merge / abandonment)
-
-```bash
-PR_STATE=$(gh pr view "$OUR_PR_URL" --json state --jq .state)
-git worktree remove ".claude/worktrees/${BRANCH}"
-if [ "$PR_STATE" = "MERGED" ]; then
-  git branch -d "$BRANCH"
-else
-  echo "PR not merged (state=$PR_STATE) — keeping branch '$BRANCH'"
-fi
-```
-
-### Step 5 — Roll-up
-
-Once the batch is merged, report:
-
-- Fixed (with PR URLs on `diegosouzapw/OmniRoute`)
-- Handed off to `/port-upstream-features` (with upstream PR numbers)
-- Deferred (with reasons)
-- New issues opened on **our** fork for remaining work — NEVER on
-  `decolua/9router`.
-
-## Hard rules
-
-- Security first. Always. Alone, on its own worktree, its own PR.
-- Reproduce before claiming a fix. No "blind" fixes.
-- All work BRANCHES off `release/vX.Y.Z`. Never off `main`. Never push to
-  `main` directly.
-- One PR per fix. Do NOT bundle.
-- Never weaken existing tests to go green.
-- Never use `--no-verify`, force-push to release/main, or `--reject` /
-  `--theirs` / `--ours` to shortcut conflicts.
-- Never interact with `decolua/9router`'s issue tracker (no comments,
-  closes, reactions, or referenced fixes from our commits).
-- Never widen `src/shared/contracts/` or public route shapes without
-  explicit user OK.
-- Upstream issue URL lives ONLY in the `Reported-by` commit trailer.
-  Never in PR body, CHANGELOG, or any other surface.
-- `Co-authored-by` trailers MUST credit human contributors only (CLAUDE.md
-  rule #16 allows humans, bans AI/bot trailers).
-- Never overwrite a previously-resolved issue — the Step 2 dedupe guard
-  (JSONL + git log on `Reported-by:`) exists for this; never disable it.
-- Verify subagent work yourself per CLAUDE.md: `git status` + `git diff
-  --stat`, sanity-check scope, full validation suite before accepting.
-- License gate is enforced in Step 0; if the upstream LICENSE blob hash
-  changes between sessions, re-confirm before continuing.

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

@@ -1,262 +0,0 @@
----
-name: resolve-issues-ag
-description: Fetch all open GitHub issues, analyze bugs, resolve up to 30 per batch via per-issue worktrees + PRs into the release branch, triage the rest, wait for user validation
----
-
-# /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 fixes. The current `release/vX.Y.Z` branch is the integration target — each individual fix is implemented on its own short-lived `fix/<issue>-<short>` branch inside its own git worktree, merged into the release branch via PR, then the worktree and local branch are deleted. The release branch is later merged to `main` via `/generate-release`.
-
-> **BRANCH RULE**: The current `release/vX.Y.Z` branch is the integration target. Each fix MUST live on its own `fix/<ISSUE>-<short>` branch cut from the release branch, inside its own worktree under `.worktrees/`. After the per-issue PR is merged into the release branch, the worktree and local branch are deleted. Never commit fixes directly to the release branch. 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.
-
-> **🌐 REPLY LANGUAGE**: All comments posted to issues (close messages, RESPOND comments, PR descriptions visible to the reporter) MUST match the reporter's language. When in doubt, default to **English**. The reporter's language is detected from the issue body and prior comments by that author.
-
-## 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 a `release/vX.Y.Z` branch exists. If you are currently on `main`, create one:
-
-```bash
-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>=999?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
-git checkout -b release/v$NEXT
-npm version patch --no-git-tag-version
-npm install
-```
-
-> Threshold: patches climb to `.999` before rolling. Example: `3.4.999` → `3.5.0`.
-
-If already on a `release/vX.Y.Z` branch, continue working there.
-
-### 3. Fetch All Open Issues (cap 30 per batch)
-
-// turbo-all
-
-**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. Use the two-step approach below.
-
-**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'`
-- Count them and remember the total.
-
-**Step 3b — Fetch full metadata for each Issue** (parallel, validated against 3a):
-
-- For each issue number from step 3a, run:
-  `gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author,url`
-- Batch in parallel (8–12 concurrent calls). After completion, assert `fetched_count == count_from_3a`; if mismatch, retry the missing IDs.
-- Sort by oldest first (FIFO).
-
-**Step 3c — Cap at 30 per run**:
-
-- If more than 30 open issues qualify as bugs after step 4, ask the user which subset of up to 30 to handle now. The remainder is deferred to the next run.
-
-### 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 are skipped with a note in the final report.
-
-#### 4.5. PR-Linked Check (mandatory)
-
-For every bug, query linked PRs:
-
-```bash
-gh issue view <NUMBER> --repo <owner>/<repo> --json closedByPullRequestsReferences,body
-```
-
-If the issue is referenced by an **open** contributor PR (or the body links to one), do NOT plan a self-implemented fix. Mark the issue as `🤝 PR-LINKED — redirect to /review-prs` in the report and stop deeper analysis for it. **NEVER close the contributor PR.**
-
-### 5. Deep-Read Each Bug Issue (One-by-One Analysis)
-
-Read each bug issue thoroughly, one at a time. Each issue gets focused attention.
-
-#### 5a. Understand the Problem
-
-1. **Read the entire body** — Description, Steps to Reproduce, Expected/Actual Behavior, Error Logs, Screenshots
-2. **Read ALL comments** — bot triage (Kilo, etc.) and owner/community responses. Look for:
-   - Someone already responded with a fix
-   - Community member confirmed it is resolved
-   - Bot duplicate flag. **DO NOT blindly trust bot labels (e.g., `kilo-duplicate`).** Re-verify independently from current source + web research.
-3. **Identify the claimed error** — exact error message, status code, provider/model, OS, Node version.
-
-#### 5b. Check Information Sufficiency
-
-Verify the issue contains:
-
-- [ ] Clear description of the problem
-- [ ] Steps to reproduce OR error logs
-- [ ] Provider/model/version information
-- [ ] Expected vs actual behavior
-
-**If ANY item is missing → auto-classify as `📝 RESPOND — Needs Info` and skip 5d.** Do not attempt root-cause analysis on under-specified issues.
-
-#### 5c. Determine Issue Disposition
-
-| 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 (also triggered by 5b)                                         | 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                    |
-| **🤝 PR-LINKED**             | An open contributor PR already targets this issue (from step 4.5)                                                      | Redirect to `/review-prs`; do not re-implement          |
-| **🔧 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:
-
-1. **Search the codebase** — grep for error strings, function names, affected files
-2. **Search the web** — upstream API changes, SDK updates, breaking changes
-3. **Read the full source file** — don't rely on grep snippets
-4. **Verify the root cause** is in our code, not user misconfiguration
-5. **Formulate a proposed solution** — exact files/lines/logic
-6. **Create an Implementation Plan file** at `_tasks/fixes-vX.Y.Z/<ISSUE>-<short-description>.plan.md` (`vX.Y.Z` = current release branch version). Create the directory first: `mkdir -p _tasks/fixes-vX.Y.Z`. The plan contains: Overview, Reproduction Steps, Regression Test Outline, Implementation Steps (files/changes), Rollout Notes.
-7. **DO NOT modify the codebase yet** — wait for user approval.
-
-#### 5e. For "RESPOND" Issues
-
-Post a substantive comment that:
-
-- Acknowledges the specific error reported
-- Explains the likely root cause
-- Provides concrete steps (version upgrade, env var fix, model path correction)
-- Asks for follow-up info if needed
-
-**No generic templates.** Every comment references the user's specific error and environment, and is written in the reporter's language (English default).
-
-### 6. Generate Report & Wait for Validation
-
-Present a summary report. For FIX bugs, explicitly explain the proposed solution (files to change + logic) and confirm it will land via per-issue worktree → PR → release branch after approval. Include the reporter's detected language per row so the user can verify.
-
-| Issue | Title | Status         | Reply Lang | Proposed Action / Version                  |
-| ----- | ----- | -------------- | ---------- | ------------------------------------------ |
-| #N    | Title | ✅ Close       | en         | Already fixed / duplicate (explain why)    |
-| #N    | Title | 🔧 Propose     | pt-BR      | Code fix plan summary + worktree branch    |
-| #N    | Title | 📝 Respond     | en         | Guidance comment to be posted              |
-| #N    | Title | ❓ Needs Info  | en         | Triage comment to be posted                |
-| #N    | Title | 🤝 PR-Linked   | en         | Redirect to /review-prs (PR #M)            |
-| #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** → Proceed to step 7
-- If the user requests changes → Adjust and re-present the report
-- If the user rejects → Revert any accidental changes and stop
-
-### 7. Implement Fixes via Per-Issue Worktrees + PRs (only after user approval)
-
-For each approved FIX issue (up to 30 per batch), repeat the following sequence. Issues can be processed sequentially or in parallel (one worktree each — never two fixes in the same worktree).
-
-#### 7.1. Spin up an isolated worktree on a fresh fix branch
-
-```bash
-ISSUE=<NUMBER>
-SHORT=<short-kebab-desc>
-RELEASE_BRANCH=$(git -C <project_root> branch --show-current)   # release/vX.Y.Z
-WT_DIR=".worktrees/fix-${ISSUE}-${SHORT}"
-BRANCH="fix/${ISSUE}-${SHORT}"
-
-git fetch origin "$RELEASE_BRANCH"
-git worktree add "$WT_DIR" -b "$BRANCH" "origin/$RELEASE_BRANCH"
-cd "$WT_DIR"
-```
-
-#### 7.2. Write the regression test first (TDD)
-
-- Author a unit/integration test that reproduces the bug. **It must fail on the unfixed code.** Run it and confirm the failure.
-- Hard rule #8: any production change must ship with tests in the same PR. The regression test is non-negotiable.
-
-#### 7.3. Implement the fix
-
-- Apply the approved plan from `_tasks/fixes-vX.Y.Z/<ISSUE>-<short>.plan.md`.
-- Keep the diff scoped to this issue. No drive-by refactors.
-
-#### 7.4. Run the test suite
-
-- `npm run test:all` (or the appropriate suite for the touched area; the regression test MUST be included).
-- All tests must pass before commit. Also run the relevant `lint` / `typecheck` per CLAUDE.md trust-but-verify checklist.
-
-#### 7.5. Update CHANGELOG.md and commit (single commit, same diff)
-
-- Add the new bug-fix entry under the current `vX.Y.Z` section of CHANGELOG.md.
-- CHANGELOG entry + code + test go in **one** commit on the fix branch:
-
-```bash
-git add <changed files> CHANGELOG.md
-git commit -m "fix: <description> (#${ISSUE})"
-```
-
-#### 7.6. Push and open a PR into the release branch
-
-```bash
-git push -u origin "$BRANCH"
-gh pr create \
-  --base "$RELEASE_BRANCH" \
-  --head "$BRANCH" \
-  --title "fix: <description> (#${ISSUE})" \
-  --body "Closes #${ISSUE}\n\n<short summary, plan link, regression test reference>"
-```
-
-#### 7.7. Merge the PR into the release branch
-
-- Wait for CI green, then merge with the project's default merge strategy.
-- The PR title becomes the release-branch commit.
-
-#### 7.8. Clean up worktree and local branch
-
-```bash
-cd <project_root>
-git worktree remove "$WT_DIR"
-git branch -D "$BRANCH"
-```
-
-#### 7.9. Close the issue with a localized comment
-
-Match the reporter's language (English default). Template:
-
-> **EN**: Thanks for reporting! Fixed in `release/vX.Y.Z` (already merged into the active development branch — feel free to pull and test it now). It will ship in the next release (vX.Y.Z).
->
-> **pt-BR**: Obrigado pelo report! Corrigido em `release/vX.Y.Z` (já mergeado na branch de desenvolvimento atual — pode dar pull e testar). Vai sair na próxima release (vX.Y.Z).
-
-```bash
-gh issue close "$ISSUE" --repo <owner>/<repo> --comment "<localized message above>"
-```
-
-#### 7.10. Close non-FIX dispositions
-
-After all FIX issues are merged:
-
-- `Duplicate`: close referencing the original issue (localized).
-- `Stale`: close thanking the user and inviting reopen (localized).
-- `RESPOND — Needs Info` / `RESPOND — User Config`: post the substantive comment from 5e (localized).
-- `PR-LINKED`: leave the issue open; comment redirecting to the contributor PR if not already linked.
-
-#### 7.11. Hand off to release flow (optional)
-
-If a release PR to `main` is desired now, run `/generate-release` Phase 1 steps 7–10 (tests → commit version bump → push → open PR to main → wait for user).
-
-If NO fixes were committed, skip 7.7–7.11 and just conclude the workflow.

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

@@ -1,263 +0,0 @@
----
-name: resolve-issues-cc
-description: Fetch all open GitHub issues, analyze bugs, resolve up to 30 per batch via per-issue worktrees + PRs into the release branch, triage the rest, wait for user validation
-allowed-tools: Bash, Read, Edit, Write, Grep, Glob, WebFetch, WebSearch, AskUserQuestion, Agent
----
-
-# /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 fixes. The current `release/vX.Y.Z` branch is the integration target — each individual fix is implemented on its own short-lived `fix/<issue>-<short>` branch inside its own git worktree, merged into the release branch via PR, then the worktree and local branch are deleted. The release branch is later merged to `main` via `/generate-release`.
-
-> **BRANCH RULE**: The current `release/vX.Y.Z` branch is the integration target. Each fix MUST live on its own `fix/<ISSUE>-<short>` branch cut from the release branch, inside its own worktree under `.worktrees/`. After the per-issue PR is merged into the release branch, the worktree and local branch are deleted. Never commit fixes directly to the release branch. 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.
-
-> **🌐 REPLY LANGUAGE**: All comments posted to issues (close messages, RESPOND comments, PR descriptions visible to the reporter) MUST match the reporter's language. When in doubt, default to **English**. The reporter's language is detected from the issue body and prior comments by that author.
-
-## 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 a `release/vX.Y.Z` branch exists. If you are currently on `main`, create one:
-
-```bash
-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>=999?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
-git checkout -b release/v$NEXT
-npm version patch --no-git-tag-version
-npm install
-```
-
-> Threshold: patches climb to `.999` before rolling. Example: `3.4.999` → `3.5.0`.
-
-If already on a `release/vX.Y.Z` branch, continue working there.
-
-### 3. Fetch All Open Issues (cap 30 per batch)
-
-// turbo-all
-
-**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. Use the two-step approach below.
-
-**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'`
-- Count them and remember the total.
-
-**Step 3b — Fetch full metadata for each Issue** (parallel, validated against 3a):
-
-- For each issue number from step 3a, run:
-  `gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author,url`
-- Batch in parallel (8–12 concurrent calls). After completion, assert `fetched_count == count_from_3a`; if mismatch, retry the missing IDs.
-- Sort by oldest first (FIFO).
-
-**Step 3c — Cap at 30 per run**:
-
-- If more than 30 open issues qualify as bugs after step 4, ask the user (via AskUserQuestion) which subset of up to 30 to handle now. The remainder is deferred to the next run.
-
-### 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 are skipped with a note in the final report.
-
-#### 4.5. PR-Linked Check (mandatory)
-
-For every bug, query linked PRs:
-
-```bash
-gh issue view <NUMBER> --repo <owner>/<repo> --json closedByPullRequestsReferences,body
-```
-
-If the issue is referenced by an **open** contributor PR (or the body links to one), do NOT plan a self-implemented fix. Mark the issue as `🤝 PR-LINKED — redirect to /review-prs` in the report and stop deeper analysis for it. **NEVER close the contributor PR.**
-
-### 5. Deep-Read Each Bug Issue (One-by-One Analysis)
-
-Read each bug issue thoroughly, one at a time. Each issue gets focused attention.
-
-#### 5a. Understand the Problem
-
-1. **Read the entire body** — Description, Steps to Reproduce, Expected/Actual Behavior, Error Logs, Screenshots
-2. **Read ALL comments** — bot triage (Kilo, etc.) and owner/community responses. Look for:
-   - Someone already responded with a fix
-   - Community member confirmed it is resolved
-   - Bot duplicate flag. **DO NOT blindly trust bot labels (e.g., `kilo-duplicate`).** Re-verify independently from current source + web research.
-3. **Identify the claimed error** — exact error message, status code, provider/model, OS, Node version.
-
-#### 5b. Check Information Sufficiency
-
-Verify the issue contains:
-
-- [ ] Clear description of the problem
-- [ ] Steps to reproduce OR error logs
-- [ ] Provider/model/version information
-- [ ] Expected vs actual behavior
-
-**If ANY item is missing → auto-classify as `📝 RESPOND — Needs Info` and skip 5d.** Do not attempt root-cause analysis on under-specified issues.
-
-#### 5c. Determine Issue Disposition
-
-| 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 (also triggered by 5b)                                         | 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                    |
-| **🤝 PR-LINKED**             | An open contributor PR already targets this issue (from step 4.5)                                                      | Redirect to `/review-prs`; do not re-implement          |
-| **🔧 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:
-
-1. **Search the codebase** — `grep`/`Grep` for error strings, function names, affected files
-2. **Search the web** — upstream API changes, SDK updates, breaking changes
-3. **Read the full source file** — don't rely on grep snippets
-4. **Verify the root cause** is in our code, not user misconfiguration
-5. **Formulate a proposed solution** — exact files/lines/logic
-6. **Create an Implementation Plan file** at `_tasks/fixes-vX.Y.Z/<ISSUE>-<short-description>.plan.md` (`vX.Y.Z` = current release branch version). Create the directory first: `mkdir -p _tasks/fixes-vX.Y.Z`. The plan contains: Overview, Reproduction Steps, Regression Test Outline, Implementation Steps (files/changes), Rollout Notes.
-7. **DO NOT modify the codebase yet** — wait for user approval.
-
-#### 5e. For "RESPOND" Issues
-
-Post a substantive comment that:
-
-- Acknowledges the specific error reported
-- Explains the likely root cause
-- Provides concrete steps (version upgrade, env var fix, model path correction)
-- Asks for follow-up info if needed
-
-**No generic templates.** Every comment references the user's specific error and environment, and is written in the reporter's language (English default).
-
-### 6. Generate Report & Wait for Validation
-
-Present a summary report. For FIX bugs, explicitly explain the proposed solution (files to change + logic) and confirm it will land via per-issue worktree → PR → release branch after approval. Include the reporter's detected language per row so the user can verify.
-
-| Issue | Title | Status         | Reply Lang | Proposed Action / Version                  |
-| ----- | ----- | -------------- | ---------- | ------------------------------------------ |
-| #N    | Title | ✅ Close       | en         | Already fixed / duplicate (explain why)    |
-| #N    | Title | 🔧 Propose     | pt-BR      | Code fix plan summary + worktree branch    |
-| #N    | Title | 📝 Respond     | en         | Guidance comment to be posted              |
-| #N    | Title | ❓ Needs Info  | en         | Triage comment to be posted                |
-| #N    | Title | 🤝 PR-Linked   | en         | Redirect to /review-prs (PR #M)            |
-| #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** → Proceed to step 7
-- If the user requests changes → Adjust and re-present the report
-- If the user rejects → Revert any accidental changes and stop
-
-### 7. Implement Fixes via Per-Issue Worktrees + PRs (only after user approval)
-
-For each approved FIX issue (up to 30 per batch), repeat the following sequence. Issues can be processed sequentially or in parallel (one worktree each — never two fixes in the same worktree).
-
-#### 7.1. Spin up an isolated worktree on a fresh fix branch
-
-```bash
-ISSUE=<NUMBER>
-SHORT=<short-kebab-desc>
-RELEASE_BRANCH=$(git -C <project_root> branch --show-current)   # release/vX.Y.Z
-WT_DIR=".worktrees/fix-${ISSUE}-${SHORT}"
-BRANCH="fix/${ISSUE}-${SHORT}"
-
-git fetch origin "$RELEASE_BRANCH"
-git worktree add "$WT_DIR" -b "$BRANCH" "origin/$RELEASE_BRANCH"
-cd "$WT_DIR"
-```
-
-#### 7.2. Write the regression test first (TDD)
-
-- Author a unit/integration test that reproduces the bug. **It must fail on the unfixed code.** Run it and confirm the failure.
-- Hard rule #8: any production change must ship with tests in the same PR. The regression test is non-negotiable.
-
-#### 7.3. Implement the fix
-
-- Apply the approved plan from `_tasks/fixes-vX.Y.Z/<ISSUE>-<short>.plan.md`.
-- Keep the diff scoped to this issue. No drive-by refactors.
-
-#### 7.4. Run the test suite
-
-- `npm run test:all` (or the appropriate suite for the touched area; the regression test MUST be included).
-- All tests must pass before commit. Also run the relevant `lint` / `typecheck` per CLAUDE.md trust-but-verify checklist.
-
-#### 7.5. Update CHANGELOG.md and commit (single commit, same diff)
-
-- Add the new bug-fix entry under the current `vX.Y.Z` section of CHANGELOG.md.
-- CHANGELOG entry + code + test go in **one** commit on the fix branch:
-
-```bash
-git add <changed files> CHANGELOG.md
-git commit -m "fix: <description> (#${ISSUE})"
-```
-
-#### 7.6. Push and open a PR into the release branch
-
-```bash
-git push -u origin "$BRANCH"
-gh pr create \
-  --base "$RELEASE_BRANCH" \
-  --head "$BRANCH" \
-  --title "fix: <description> (#${ISSUE})" \
-  --body "Closes #${ISSUE}\n\n<short summary, plan link, regression test reference>"
-```
-
-#### 7.7. Merge the PR into the release branch
-
-- Wait for CI green, then merge with the project's default merge strategy.
-- The PR title becomes the release-branch commit.
-
-#### 7.8. Clean up worktree and local branch
-
-```bash
-cd <project_root>
-git worktree remove "$WT_DIR"
-git branch -D "$BRANCH"
-```
-
-#### 7.9. Close the issue with a localized comment
-
-Match the reporter's language (English default). Template:
-
-> **EN**: Thanks for reporting! Fixed in `release/vX.Y.Z` (already merged into the active development branch — feel free to pull and test it now). It will ship in the next release (vX.Y.Z).
->
-> **pt-BR**: Obrigado pelo report! Corrigido em `release/vX.Y.Z` (já mergeado na branch de desenvolvimento atual — pode dar pull e testar). Vai sair na próxima release (vX.Y.Z).
-
-```bash
-gh issue close "$ISSUE" --repo <owner>/<repo> --comment "<localized message above>"
-```
-
-#### 7.10. Close non-FIX dispositions
-
-After all FIX issues are merged:
-
-- `Duplicate`: close referencing the original issue (localized).
-- `Stale`: close thanking the user and inviting reopen (localized).
-- `RESPOND — Needs Info` / `RESPOND — User Config`: post the substantive comment from 5e (localized).
-- `PR-LINKED`: leave the issue open; comment redirecting to the contributor PR if not already linked.
-
-#### 7.11. Hand off to release flow (optional)
-
-If a release PR to `main` is desired now, run `/generate-release` Phase 1 steps 7–10 (tests → commit version bump → push → open PR to main → wait for user).
-
-If NO fixes were committed, skip 7.7–7.11 and just conclude the workflow.

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

@@ -1,269 +0,0 @@
----
-name: resolve-issues-cx
-description: Fetch all open GitHub issues, analyze bugs, resolve up to 30 per batch via per-issue worktrees + PRs into the release branch, triage the rest, wait for user validation
----
-
-# /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 fixes. The current `release/vX.Y.Z` branch is the integration target — each individual fix is implemented on its own short-lived `fix/<issue>-<short>` branch inside its own git worktree, merged into the release branch via PR, then the worktree and local branch are deleted. The release branch is later merged to `main` via `/generate-release`.
-
-## 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.
-- One worktree per fix — never reuse a worktree for two different issues, even sequentially in the same session.
-
-> **BRANCH RULE**: The current `release/vX.Y.Z` branch is the integration target. Each fix MUST live on its own `fix/<ISSUE>-<short>` branch cut from the release branch, inside its own worktree under `.worktrees/`. After the per-issue PR is merged into the release branch, the worktree and local branch are deleted. Never commit fixes directly to the release branch. 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.
-
-> **🌐 REPLY LANGUAGE**: All comments posted to issues (close messages, RESPOND comments, PR descriptions visible to the reporter) MUST match the reporter's language. When in doubt, default to **English**. The reporter's language is detected from the issue body and prior comments by that author.
-
-## 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 a `release/vX.Y.Z` branch exists. If you are currently on `main`, create one:
-
-```bash
-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>=999?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
-git checkout -b release/v$NEXT
-npm version patch --no-git-tag-version
-npm install
-```
-
-> Threshold: patches climb to `.999` before rolling. Example: `3.4.999` → `3.5.0`.
-
-If already on a `release/vX.Y.Z` branch, continue working there.
-
-### 3. Fetch All Open Issues (cap 30 per batch)
-
-// turbo-all
-
-**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. Use the two-step approach below.
-
-**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'`
-- Count them and remember the total.
-
-**Step 3b — Fetch full metadata for each Issue** (parallel, validated against 3a):
-
-- For each issue number from step 3a, run:
-  `gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author,url`
-- Batch in parallel (8–12 concurrent calls). After completion, assert `fetched_count == count_from_3a`; if mismatch, retry the missing IDs.
-- Sort by oldest first (FIFO).
-
-**Step 3c — Cap at 30 per run**:
-
-- If more than 30 open issues qualify as bugs after step 4, ask the user which subset of up to 30 to handle now. The remainder is deferred to the next run.
-
-### 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 are skipped with a note in the final report.
-
-#### 4.5. PR-Linked Check (mandatory)
-
-For every bug, query linked PRs:
-
-```bash
-gh issue view <NUMBER> --repo <owner>/<repo> --json closedByPullRequestsReferences,body
-```
-
-If the issue is referenced by an **open** contributor PR (or the body links to one), do NOT plan a self-implemented fix. Mark the issue as `🤝 PR-LINKED — redirect to /review-prs` in the report and stop deeper analysis for it. **NEVER close the contributor PR.**
-
-### 5. Deep-Read Each Bug Issue (One-by-One Analysis)
-
-Read each bug issue thoroughly, one at a time. Each issue gets focused attention.
-
-#### 5a. Understand the Problem
-
-1. **Read the entire body** — Description, Steps to Reproduce, Expected/Actual Behavior, Error Logs, Screenshots
-2. **Read ALL comments** — bot triage (Kilo, etc.) and owner/community responses. Look for:
-   - Someone already responded with a fix
-   - Community member confirmed it is resolved
-   - Bot duplicate flag. **DO NOT blindly trust bot labels (e.g., `kilo-duplicate`).** Re-verify independently from current source + web research.
-3. **Identify the claimed error** — exact error message, status code, provider/model, OS, Node version.
-
-#### 5b. Check Information Sufficiency
-
-Verify the issue contains:
-
-- [ ] Clear description of the problem
-- [ ] Steps to reproduce OR error logs
-- [ ] Provider/model/version information
-- [ ] Expected vs actual behavior
-
-**If ANY item is missing → auto-classify as `📝 RESPOND — Needs Info` and skip 5d.** Do not attempt root-cause analysis on under-specified issues.
-
-#### 5c. Determine Issue Disposition
-
-| 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 (also triggered by 5b)                                         | 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                    |
-| **🤝 PR-LINKED**             | An open contributor PR already targets this issue (from step 4.5)                                                      | Redirect to `/review-prs`; do not re-implement          |
-| **🔧 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:
-
-1. **Search the codebase** — grep for error strings, function names, affected files
-2. **Search the web** — upstream API changes, SDK updates, breaking changes
-3. **Read the full source file** — don't rely on grep snippets
-4. **Verify the root cause** is in our code, not user misconfiguration
-5. **Formulate a proposed solution** — exact files/lines/logic
-6. **Create an Implementation Plan file** at `_tasks/fixes-vX.Y.Z/<ISSUE>-<short-description>.plan.md` (`vX.Y.Z` = current release branch version). Create the directory first: `mkdir -p _tasks/fixes-vX.Y.Z`. The plan contains: Overview, Reproduction Steps, Regression Test Outline, Implementation Steps (files/changes), Rollout Notes.
-7. **DO NOT modify the codebase yet** — wait for user approval.
-
-#### 5e. For "RESPOND" Issues
-
-Post a substantive comment that:
-
-- Acknowledges the specific error reported
-- Explains the likely root cause
-- Provides concrete steps (version upgrade, env var fix, model path correction)
-- Asks for follow-up info if needed
-
-**No generic templates.** Every comment references the user's specific error and environment, and is written in the reporter's language (English default).
-
-### 6. Generate Report & Wait for Validation
-
-Present a summary report. For FIX bugs, explicitly explain the proposed solution (files to change + logic) and confirm it will land via per-issue worktree → PR → release branch after approval. Include the reporter's detected language per row so the user can verify.
-
-| Issue | Title | Status         | Reply Lang | Proposed Action / Version                  |
-| ----- | ----- | -------------- | ---------- | ------------------------------------------ |
-| #N    | Title | ✅ Close       | en         | Already fixed / duplicate (explain why)    |
-| #N    | Title | 🔧 Propose     | pt-BR      | Code fix plan summary + worktree branch    |
-| #N    | Title | 📝 Respond     | en         | Guidance comment to be posted              |
-| #N    | Title | ❓ Needs Info  | en         | Triage comment to be posted                |
-| #N    | Title | 🤝 PR-Linked   | en         | Redirect to /review-prs (PR #M)            |
-| #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** → Proceed to step 7
-- If the user requests changes → Adjust and re-present the report
-- If the user rejects → Revert any accidental changes and stop
-
-### 7. Implement Fixes via Per-Issue Worktrees + PRs (only after user approval)
-
-For each approved FIX issue (up to 30 per batch), repeat the following sequence. Issues can be processed sequentially or in parallel (one worktree each — never two fixes in the same worktree).
-
-#### 7.1. Spin up an isolated worktree on a fresh fix branch
-
-```bash
-ISSUE=<NUMBER>
-SHORT=<short-kebab-desc>
-RELEASE_BRANCH=$(git -C <project_root> branch --show-current)   # release/vX.Y.Z
-WT_DIR=".worktrees/fix-${ISSUE}-${SHORT}"
-BRANCH="fix/${ISSUE}-${SHORT}"
-
-git fetch origin "$RELEASE_BRANCH"
-git worktree add "$WT_DIR" -b "$BRANCH" "origin/$RELEASE_BRANCH"
-cd "$WT_DIR"
-```
-
-#### 7.2. Write the regression test first (TDD)
-
-- Author a unit/integration test that reproduces the bug. **It must fail on the unfixed code.** Run it and confirm the failure.
-- Hard rule #8: any production change must ship with tests in the same PR. The regression test is non-negotiable.
-
-#### 7.3. Implement the fix
-
-- Apply the approved plan from `_tasks/fixes-vX.Y.Z/<ISSUE>-<short>.plan.md`.
-- Keep the diff scoped to this issue. No drive-by refactors.
-
-#### 7.4. Run the test suite
-
-- `npm run test:all` (or the appropriate suite for the touched area; the regression test MUST be included).
-- All tests must pass before commit. Also run the relevant `lint` / `typecheck` per CLAUDE.md trust-but-verify checklist.
-
-#### 7.5. Update CHANGELOG.md and commit (single commit, same diff)
-
-- Add the new bug-fix entry under the current `vX.Y.Z` section of CHANGELOG.md.
-- CHANGELOG entry + code + test go in **one** commit on the fix branch:
-
-```bash
-git add <changed files> CHANGELOG.md
-git commit -m "fix: <description> (#${ISSUE})"
-```
-
-#### 7.6. Push and open a PR into the release branch
-
-```bash
-git push -u origin "$BRANCH"
-gh pr create \
-  --base "$RELEASE_BRANCH" \
-  --head "$BRANCH" \
-  --title "fix: <description> (#${ISSUE})" \
-  --body "Closes #${ISSUE}\n\n<short summary, plan link, regression test reference>"
-```
-
-#### 7.7. Merge the PR into the release branch
-
-- Wait for CI green, then merge with the project's default merge strategy.
-- The PR title becomes the release-branch commit.
-
-#### 7.8. Clean up worktree and local branch
-
-```bash
-cd <project_root>
-git worktree remove "$WT_DIR"
-git branch -D "$BRANCH"
-```
-
-#### 7.9. Close the issue with a localized comment
-
-Match the reporter's language (English default). Template:
-
-> **EN**: Thanks for reporting! Fixed in `release/vX.Y.Z` (already merged into the active development branch — feel free to pull and test it now). It will ship in the next release (vX.Y.Z).
->
-> **pt-BR**: Obrigado pelo report! Corrigido em `release/vX.Y.Z` (já mergeado na branch de desenvolvimento atual — pode dar pull e testar). Vai sair na próxima release (vX.Y.Z).
-
-```bash
-gh issue close "$ISSUE" --repo <owner>/<repo> --comment "<localized message above>"
-```
-
-#### 7.10. Close non-FIX dispositions
-
-After all FIX issues are merged:
-
-- `Duplicate`: close referencing the original issue (localized).
-- `Stale`: close thanking the user and inviting reopen (localized).
-- `RESPOND — Needs Info` / `RESPOND — User Config`: post the substantive comment from 5e (localized).
-- `PR-LINKED`: leave the issue open; comment redirecting to the contributor PR if not already linked.
-
-#### 7.11. Hand off to release flow (optional)
-
-If a release PR to `main` is desired now, run `/generate-release` Phase 1 steps 7–10 (tests → commit version bump → push → open PR to main → wait for user).
-
-If NO fixes were committed, skip 7.7–7.11 and just conclude the workflow.

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

@@ -1,271 +0,0 @@
----
-name: review-discussions-ag
-description: Read all open GitHub Discussions, summarize them, respond to pending ones, create issues from actionable feature requests, and triage stale threads for closure
----
-
-# /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, optionally creates issues from actionable feature requests, and triages stale threads for closure.
-
-**Modern tooling (replaces deprecated `browser_subagent` flow):**
-
-- Reads use `gh api graphql` — one query returns 50 discussions with full bodies, comments, replies, IDs, and `updatedAt`.
-- Writes (post comment, create issue, close discussion) use `gh api graphql` mutations or `gh issue create`.
-- Pace at ~1s between writes to avoid abuse-detection throttling.
-- `WebFetch` is acceptable only for read-only HTML scraping when GraphQL is unavailable — never for write actions.
-
-// turbo-all
-
-## Steps
-
-### 1. Identify the GitHub Repository
-
-- Run: `git -C <project_root> remote get-url origin` to extract `owner/repo`.
-- Parse owner and repo name from the URL (https or ssh form).
-
-### 2. Fetch All Open Discussions (paginated GraphQL)
-
-GraphQL caps each `discussions` query at 50 nodes — repos with more than 50 open discussions **must paginate**. Loop with `first: 50, after: $cursor` until `pageInfo.hasNextPage` is `false`. Skipping pagination silently drops the older half of the backlog, which is exactly where most stale-candidates and unanswered follow-ups live (regression observed 2026-05-28: page-1-only fetch missed 5 follow-ups and 4 stale candidates ranging from 23d to 56d).
-
-Each page request must return the **same field set** — easy mistake is to fetch page 2 without `body` (because the cursor query was hand-edited). Define one query string with `body` on both the discussion and every comment/reply, and reuse it across pages.
-
-Critical fields per discussion: `id` (node ID, **not** the visible `number`), `number`, `title`, `url`, `createdAt`, `updatedAt`, `author.login`, `category.name`, `body`, `answerChosenAt`, `labels(first: 10) { nodes { name } }`, plus nested `comments(first: 50) { totalCount, nodes { id, author.login, body, createdAt, replies(first: 20) { nodes { author.login, body, createdAt } } } }`. Must also include `pageInfo { hasNextPage endCursor }` on the discussions connection.
-
-Persist the **merged** result (all pages concatenated) to `/tmp/discussions-<repo>-<date>.json` so re-runs in the same session avoid a re-fetch. Build an `id → number` map for the post phase — the GraphQL `addDiscussionComment` mutation requires the node ID, not the number.
-
-Capture **image attachments** present in body or comments (`<img src="...">` or markdown `![...](...)`). Surface their count in the per-discussion summary (e.g., `📷 3 screenshots`) so the user can decide if visual context matters before approving a draft.
-
-### 3. Summarize All Discussions
-
-For each discussion, extract:
-
-- **Title** and **#Number**
-- **Author** (GitHub username)
-- **Category** (Announcements, General, Ideas, Q&A, Show and tell)
-- **Created** + **Last updated** (ISO date)
-- **Summary** of original post (1-2 sentences)
-- **Comment count** + **last commenter** + **last comment date** — determine these by **chronological `createdAt`**, not iteration order. Comments and their nested replies must be merged into a single sorted timeline before picking the latest event (otherwise a recent top-level reply gets shadowed by an older nested reply of an earlier comment, and the discussion is misclassified).
-- **Maintainer involvement**: whether the repo owner already replied, and how many times
-- **Pending action** — derived state, see categories below
-- **Attachments**: count of screenshots / videos / pastebin links
-- **Detected language** of the reporter (for reply-language matching)
-
-### 4. Present Summary Report to User
-
-Group by **pending action**, not by category, so the human sees triage buckets at a glance:
-
-| State                   | Meaning                                                                                                          |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| ⚠️ Needs first response | Zero comments, or all comments are from non-maintainers                                                          |
-| 🔄 Follow-up pending    | Maintainer replied, but reporter or third party added a new comment maintainer has not addressed                 |
-| 🕒 Stale (>15d)         | Maintainer was last to comment, no activity for 15+ days — candidate for soft-close or reporter-ping (see step 8)|
-| ✅ Answered             | Maintainer already replied AND last commenter is the maintainer AND age < 15d                                    |
-| 🏁 Resolved             | `answerChosenAt` is set                                                                                          |
-
-Within each bucket, present a table:
-
-| #   | Category | Title              | Author | Updated | Notes                  |
-| --- | -------- | ------------------ | ------ | ------- | ---------------------- |
-| #N  | Q&A      | short title (60ch) | @user  | YYYY-MM-DD | 📷2 · 🐛bug · 💡FR    |
-
-Tag rows with content hints when detected: `🐛bug` (`[BUG]` / `error` / stacktrace in body), `💡FR` (`feature request` / `add support for`), `❓support` (config/usage question), `🙏thanks` (short ack-only follow-up).
-
-### 5. Draft & Post Responses
-
-#### Reply templates by intent
-
-Pick the template that matches the discussion intent — do NOT use a single generic format.
-
-**A. Bug confirmed** — ack + root cause + tracking + workaround
-```
-Hey @user! Confirmed -- {root cause in one sentence}. I traced it to `path/to/file.ts:line`.
-
-{Why it happens: 2-4 sentences of technical detail}
-
-I have opened {issue #N} to track the fix. Workaround until it ships: {concrete steps}. Will update here when the patch lands.
-```
-
-**B. Feature Request** — ack + status + scope + commit
-```
-Hey @user! {Status: "Already exists" / "Tracked in #N" / "Reasonable, opening an issue"}.
-
-{If already exists: pointer to dashboard page or doc}
-{If tracked: link to umbrella, summarize order/priority}
-{If new: open issue + post link back}
-
-{Optional: short technical note on feasibility / trade-offs}
-```
-
-**C. Support / config question** — direct answer + reference + offer to dig deeper
-```
-Hey @user! {One-sentence answer}.
-
-Steps:
-1. ...
-2. ...
-3. ...
-
-Reference: `docs/<path>.md`. If it still fails after that, paste {specific thing} and I will trace it.
-```
-
-**D. Thank-you / short follow-up** — 1-2 sentences
-```
-Glad it helps, @user! {Concrete next marker — when patch ships / when to expect next update}.
-```
-
-**E. Stale / closing** — see step 8
-
-#### Posting via gh (replaces deprecated browser flow)
-
-```bash
-gh api graphql -f query='
-mutation($id: ID!, $body: String!) {
-  addDiscussionComment(input: {discussionId: $id, body: $body}) {
-    comment { id url }
-  }
-}' -f id="$NODE_ID" -f body="$BODY"
-```
-
-For **threaded replies** (recommended when responding to a specific comment in a long thread), add `replyToId: $parentCommentId` to the input.
-
-**Output hygiene** (still applies even via API — the comment renders in GitHub UI):
-
-- ASCII-safe punctuation: regular hyphens `-`, `->` for arrows
-- Markdown OK: `**bold**`, fenced code blocks, `[text](url)` links
-- No bare error messages with stack traces from internal logs — sanitize
-- Match reporter's language (pt-BR reporter → pt-BR reply; ru reporter → ru reply); default to English when uncertain
-
-**Pacing**: `sleep 1` between mutations. GitHub abuse-detection trips around 10/sec for the same actor.
-
-**Verification**: capture the returned `comment.url` from each mutation. Failed posts (returncode != 0 or `errors` in response) get logged separately and retried once after a 5s pause.
-
-### 6. Create Issues from Actionable Feature Requests
-
-For discussions that contain concrete, actionable feature requests:
-
-1. **Deduplicate FIRST** — before drafting, search existing issues:
-   ```bash
-   gh issue list --repo $OWNER/$REPO --search "<keywords from FR>" --state open --json number,title,labels
-   ```
-   If a matching issue (or umbrella) already exists, reuse it — never create a duplicate. Post a comment in the discussion linking to the existing issue.
-
-2. **Ask the user which to create** — even after dedup, the human approves the final list.
-
-3. **Create the issue** with `gh issue create`:
-   ```bash
-   gh issue create --repo $OWNER/$REPO \
-     --title "[feature] <short imperative>" \
-     --label enhancement \
-     --body @/tmp/issue-body.md
-   ```
-   Body template:
-   ```markdown
-   ## Feature Request
-
-   **Source:** Discussion #N by @author
-
-   ## Problem
-   What limitation the user hit (in their words, paraphrased)
-
-   ## Proposed Solution
-   How it could work
-
-   ### Implementation Ideas
-   - File paths likely to touch
-   - Related modules / patterns already in the codebase
-
-   ### Current Workarounds
-   What users can do today
-
-   ## Additional Context
-   - Discussion: #N
-   - Related issues/PRs: #X, #Y
-   - Upstream references: link to similar implementations in `_references/` if applicable
-   ```
-
-4. **Generate task file in `_ideia/`** when the feature needs deeper investigation before implementation:
-   ```
-   _ideia/<short-kebab-slug>.md
-   ```
-   Contains: problem statement, current OmniRoute state, how upstream (`_references/9router`, `_references/CLIProxyAPI`, etc.) handles it, proposed implementation levels (short/medium/long term), acceptance criteria.
-
-5. **Link back to discussion** with the real URL:
-   ```
-   Follow-up @reporter — I've opened issue #N to track this. {1-line summary of what the issue covers}.
-   ```
-
-### 7. Final Report
-
-| Discussion | Action Taken                                                  |
-| ---------- | ------------------------------------------------------------- |
-| #N — Title | Responded (bug confirmed, tracking #M)                        |
-| #N — Title | Responded + created issue #M + task file `_ideia/X.md`        |
-| #N — Title | Responded (support answered with workaround)                  |
-| #N — Title | Responded to follow-up comment                                |
-| #N — Title | Closed (stale 15+d, no reply from reporter)                   |
-| #N — Title | Ping sent (stale 15+d, will close in 7d if no response)       |
-
-Include totals: comments posted, issues created, discussions closed, discussions pinged. Capture median response time for the batch.
-
-### 8. Stale Discussion Triage (auto-close candidates)
-
-Identify discussions matching **all** of:
-
-- `updatedAt > 15 days ago`
-- Maintainer already replied at least once
-- Last commenter is the maintainer (the ball is on the reporter's side)
-- `answerChosenAt` is null (not formally resolved)
-- Category in `{Q&A, General}` — skip `Ideas` / `Show and tell` / `Announcements` (those serve as community references and shouldn't be closed)
-- `comments.totalCount >= 2` — there was actual conversation, not a drive-by post
-- No label named `keep-open` (escape hatch)
-
-For each candidate, present to the user with a recommended action:
-
-| Action          | When                                                                          |
-| --------------- | ----------------------------------------------------------------------------- |
-| **Soft-close**  | Default — maintainer answered concretely and reporter went silent             |
-| **Ping reporter** | Maintainer asked for more info (log dump, screenshot) and never got it      |
-| **Keep open**   | Conversation is mid-debug and closing would lose context — operator override  |
-
-**Soft-close mutation:**
-```bash
-gh api graphql -f query='
-mutation($id: ID!) {
-  closeDiscussion(input: {discussionId: $id, reason: RESOLVED}) {
-    discussion { id closed }
-  }
-}' -f id="$NODE_ID"
-```
-Valid `reason` values: `RESOLVED`, `OUTDATED`, `DUPLICATE`. Default to `OUTDATED` for "no response" closures, `RESOLVED` for answered-but-not-confirmed.
-
-Before closing, post a closing comment:
-```
-Closing for inactivity -- feel free to reopen if you still hit this, or open a fresh issue with a current log. Thanks!
-```
-
-**Ping flow** (alternative):
-```
-@reporter -- still happening on the latest version? Otherwise I'll close this in 7 days for inactivity.
-```
-Persist the ping in `_cache/discussions-pinged-<date>.json` so the next run knows to close discussions that were pinged 7+ days ago without a reply.
-
-## Notes
-
-- This workflow is **interactive** — always present the summary and wait for user approval before posting responses, creating issues, or closing discussions.
-- Gather batched approval — separate consents for "reply scope", "create issues for?", "close stale?". Stale handling is a distinct consent from reply posting.
-- For discussions in non-English languages (`pt-BR`, `ru`, `zh`, `es`), respond in the same language as the original post. Default to English when uncertain.
-- Always reference specific dashboard paths, config options, doc files, or code locations (`file:line`) when explaining existing features — never wave hands.
-- When a discussion reveals a bug, separate it from feature requests in the report. Bugs need a tracking issue + workaround; FRs need scoping.
-- Before recommending a workaround that mentions a file/flag/setting, verify it exists in the **current** codebase (the previous turn's memory may be stale).
-- Trust-but-verify: after a batch post, spot-check 2-3 random `comment.url` returns in the browser to confirm the comments rendered cleanly (no Unicode mojibake, no broken markdown).
-
-## Anti-patterns to avoid
-
-- ❌ Posting via `browser_subagent` clicks — slow, flaky, and obsolete since `gh api graphql` mutations exist.
-- ❌ N+1 fetches (one per discussion) — use one GraphQL query for all 50.
-- ❌ Creating an issue without checking for an existing umbrella / similar one first.
-- ❌ Generic "thanks, I'll look into it!" responses — every reply must reference a file, doc, or concrete action.
-- ❌ Closing a stale discussion without posting a closing comment first.
-- ❌ Skipping the user approval gate ("turbo-all" never bypasses interactive consent for writes).

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

@@ -1,272 +0,0 @@
----
-name: review-discussions-cc
-description: Read all open GitHub Discussions, summarize them, respond to pending ones, create issues from actionable feature requests, and triage stale threads for closure
----
-
-# /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, optionally creates issues from actionable feature requests, and triages stale threads for closure.
-
-**Modern tooling (replaces deprecated `browser_subagent` flow):**
-
-- Reads use `gh api graphql` — one query returns 50 discussions with full bodies, comments, replies, IDs, and `updatedAt`.
-- Writes (post comment, create issue, close discussion) use `gh api graphql` mutations or `gh issue create`.
-- Pace at ~1s between writes to avoid abuse-detection throttling.
-- `WebFetch` is acceptable only for read-only HTML scraping when GraphQL is unavailable — never for write actions.
-
-// turbo-all
-
-## Steps
-
-### 1. Identify the GitHub Repository
-
-- Run: `git -C <project_root> remote get-url origin` to extract `owner/repo`.
-- Parse owner and repo name from the URL (https or ssh form).
-
-### 2. Fetch All Open Discussions (paginated GraphQL)
-
-GraphQL caps each `discussions` query at 50 nodes — repos with more than 50 open discussions **must paginate**. Loop with `first: 50, after: $cursor` until `pageInfo.hasNextPage` is `false`. Skipping pagination silently drops the older half of the backlog, which is exactly where most stale-candidates and unanswered follow-ups live (regression observed 2026-05-28: page-1-only fetch missed 5 follow-ups and 4 stale candidates ranging from 23d to 56d).
-
-Each page request must return the **same field set** — easy mistake is to fetch page 2 without `body` (because the cursor query was hand-edited). Define one query string with `body` on both the discussion and every comment/reply, and reuse it across pages.
-
-Critical fields per discussion: `id` (node ID, **not** the visible `number`), `number`, `title`, `url`, `createdAt`, `updatedAt`, `author.login`, `category.name`, `body`, `answerChosenAt`, `labels(first: 10) { nodes { name } }`, plus nested `comments(first: 50) { totalCount, nodes { id, author.login, body, createdAt, replies(first: 20) { nodes { author.login, body, createdAt } } } }`. Must also include `pageInfo { hasNextPage endCursor }` on the discussions connection.
-
-Persist the **merged** result (all pages concatenated) to `/tmp/discussions-<repo>-<date>.json` so re-runs in the same session avoid a re-fetch. Build an `id → number` map for the post phase — the GraphQL `addDiscussionComment` mutation requires the node ID, not the number.
-
-Capture **image attachments** present in body or comments (`<img src="...">` or markdown `![...](...)`). Surface their count in the per-discussion summary (e.g., `📷 3 screenshots`) so the user can decide if visual context matters before approving a draft.
-
-### 3. Summarize All Discussions
-
-For each discussion, extract:
-
-- **Title** and **#Number**
-- **Author** (GitHub username)
-- **Category** (Announcements, General, Ideas, Q&A, Show and tell)
-- **Created** + **Last updated** (ISO date)
-- **Summary** of original post (1-2 sentences)
-- **Comment count** + **last commenter** + **last comment date** — determine these by **chronological `createdAt`**, not iteration order. Comments and their nested replies must be merged into a single sorted timeline before picking the latest event (otherwise a recent top-level reply gets shadowed by an older nested reply of an earlier comment, and the discussion is misclassified).
-- **Maintainer involvement**: whether the repo owner already replied, and how many times
-- **Pending action** — derived state, see categories below
-- **Attachments**: count of screenshots / videos / pastebin links
-- **Detected language** of the reporter (for reply-language matching)
-
-### 4. Present Summary Report to User
-
-Group by **pending action**, not by category, so the human sees triage buckets at a glance:
-
-| State                   | Meaning                                                                                                          |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| ⚠️ Needs first response | Zero comments, or all comments are from non-maintainers                                                          |
-| 🔄 Follow-up pending    | Maintainer replied, but reporter or third party added a new comment maintainer has not addressed                 |
-| 🕒 Stale (>15d)         | Maintainer was last to comment, no activity for 15+ days — candidate for soft-close or reporter-ping (see step 8)|
-| ✅ Answered             | Maintainer already replied AND last commenter is the maintainer AND age < 15d                                    |
-| 🏁 Resolved             | `answerChosenAt` is set                                                                                          |
-
-Within each bucket, present a table:
-
-| #   | Category | Title              | Author | Updated | Notes                  |
-| --- | -------- | ------------------ | ------ | ------- | ---------------------- |
-| #N  | Q&A      | short title (60ch) | @user  | YYYY-MM-DD | 📷2 · 🐛bug · 💡FR    |
-
-Tag rows with content hints when detected: `🐛bug` (`[BUG]` / `error` / stacktrace in body), `💡FR` (`feature request` / `add support for`), `❓support` (config/usage question), `🙏thanks` (short ack-only follow-up).
-
-### 5. Draft & Post Responses
-
-#### Reply templates by intent
-
-Pick the template that matches the discussion intent — do NOT use a single generic format.
-
-**A. Bug confirmed** — ack + root cause + tracking + workaround
-```
-Hey @user! Confirmed -- {root cause in one sentence}. I traced it to `path/to/file.ts:line`.
-
-{Why it happens: 2-4 sentences of technical detail}
-
-I have opened {issue #N} to track the fix. Workaround until it ships: {concrete steps}. Will update here when the patch lands.
-```
-
-**B. Feature Request** — ack + status + scope + commit
-```
-Hey @user! {Status: "Already exists" / "Tracked in #N" / "Reasonable, opening an issue"}.
-
-{If already exists: pointer to dashboard page or doc}
-{If tracked: link to umbrella, summarize order/priority}
-{If new: open issue + post link back}
-
-{Optional: short technical note on feasibility / trade-offs}
-```
-
-**C. Support / config question** — direct answer + reference + offer to dig deeper
-```
-Hey @user! {One-sentence answer}.
-
-Steps:
-1. ...
-2. ...
-3. ...
-
-Reference: `docs/<path>.md`. If it still fails after that, paste {specific thing} and I will trace it.
-```
-
-**D. Thank-you / short follow-up** — 1-2 sentences
-```
-Glad it helps, @user! {Concrete next marker — when patch ships / when to expect next update}.
-```
-
-**E. Stale / closing** — see step 8
-
-#### Posting via gh (replaces deprecated browser flow)
-
-```bash
-gh api graphql -f query='
-mutation($id: ID!, $body: String!) {
-  addDiscussionComment(input: {discussionId: $id, body: $body}) {
-    comment { id url }
-  }
-}' -f id="$NODE_ID" -f body="$BODY"
-```
-
-For **threaded replies** (recommended when responding to a specific comment in a long thread), add `replyToId: $parentCommentId` to the input.
-
-**Output hygiene** (still applies even via API — the comment renders in GitHub UI):
-
-- ASCII-safe punctuation: regular hyphens `-`, `->` for arrows
-- Markdown OK: `**bold**`, fenced code blocks, `[text](url)` links
-- No bare error messages with stack traces from internal logs — sanitize
-- Match reporter's language (pt-BR reporter → pt-BR reply; ru reporter → ru reply); default to English when uncertain
-
-**Pacing**: `sleep 1` between mutations. GitHub abuse-detection trips around 10/sec for the same actor.
-
-**Verification**: capture the returned `comment.url` from each mutation. Failed posts (returncode != 0 or `errors` in response) get logged separately and retried once after a 5s pause.
-
-### 6. Create Issues from Actionable Feature Requests
-
-For discussions that contain concrete, actionable feature requests:
-
-1. **Deduplicate FIRST** — before drafting, search existing issues:
-   ```bash
-   gh issue list --repo $OWNER/$REPO --search "<keywords from FR>" --state open --json number,title,labels
-   ```
-   If a matching issue (or umbrella) already exists, reuse it — never create a duplicate. Post a comment in the discussion linking to the existing issue.
-
-2. **Ask the user which to create** — even after dedup, the human approves the final list.
-
-3. **Create the issue** with `gh issue create`:
-   ```bash
-   gh issue create --repo $OWNER/$REPO \
-     --title "[feature] <short imperative>" \
-     --label enhancement \
-     --body @/tmp/issue-body.md
-   ```
-   Body template:
-   ```markdown
-   ## Feature Request
-
-   **Source:** Discussion #N by @author
-
-   ## Problem
-   What limitation the user hit (in their words, paraphrased)
-
-   ## Proposed Solution
-   How it could work
-
-   ### Implementation Ideas
-   - File paths likely to touch (use `Grep` if needed to confirm)
-   - Related modules / patterns already in the codebase
-
-   ### Current Workarounds
-   What users can do today
-
-   ## Additional Context
-   - Discussion: #N
-   - Related issues/PRs: #X, #Y
-   - Upstream references: link to similar implementations in `_references/` if applicable
-   ```
-
-4. **Generate task file in `_ideia/`** when the feature needs deeper investigation before implementation:
-   ```
-   _ideia/<short-kebab-slug>.md
-   ```
-   Contains: problem statement, current OmniRoute state, how upstream (`_references/9router`, `_references/CLIProxyAPI`, etc.) handles it, proposed implementation levels (short/medium/long term), acceptance criteria.
-
-5. **Link back to discussion** with the real URL:
-   ```
-   Follow-up @reporter — I've opened issue #N to track this. {1-line summary of what the issue covers}.
-   ```
-
-### 7. Final Report
-
-| Discussion | Action Taken                                                  |
-| ---------- | ------------------------------------------------------------- |
-| #N — Title | Responded (bug confirmed, tracking #M)                        |
-| #N — Title | Responded + created issue #M + task file `_ideia/X.md`        |
-| #N — Title | Responded (support answered with workaround)                  |
-| #N — Title | Responded to follow-up comment                                |
-| #N — Title | Closed (stale 15+d, no reply from reporter)                   |
-| #N — Title | Ping sent (stale 15+d, will close in 7d if no response)       |
-
-Include totals: comments posted, issues created, discussions closed, discussions pinged. Capture median response time for the batch.
-
-### 8. Stale Discussion Triage (auto-close candidates)
-
-Identify discussions matching **all** of:
-
-- `updatedAt > 15 days ago`
-- Maintainer already replied at least once
-- Last commenter is the maintainer (the ball is on the reporter's side)
-- `answerChosenAt` is null (not formally resolved)
-- Category in `{Q&A, General}` — skip `Ideas` / `Show and tell` / `Announcements` (those serve as community references and shouldn't be closed)
-- `comments.totalCount >= 2` — there was actual conversation, not a drive-by post
-- No label named `keep-open` (escape hatch)
-
-For each candidate, present to the user with a recommended action:
-
-| Action          | When                                                                          |
-| --------------- | ----------------------------------------------------------------------------- |
-| **Soft-close**  | Default — maintainer answered concretely and reporter went silent             |
-| **Ping reporter** | Maintainer asked for more info (log dump, screenshot) and never got it      |
-| **Keep open**   | Conversation is mid-debug and closing would lose context — operator override  |
-
-**Soft-close mutation:**
-```bash
-gh api graphql -f query='
-mutation($id: ID!) {
-  closeDiscussion(input: {discussionId: $id, reason: RESOLVED}) {
-    discussion { id closed }
-  }
-}' -f id="$NODE_ID"
-```
-Valid `reason` values: `RESOLVED`, `OUTDATED`, `DUPLICATE`. Default to `OUTDATED` for "no response" closures, `RESOLVED` for answered-but-not-confirmed.
-
-Before closing, post a closing comment:
-```
-Closing for inactivity -- feel free to reopen if you still hit this, or open a fresh issue with a current log. Thanks!
-```
-
-**Ping flow** (alternative):
-```
-@reporter -- still happening on the latest version? Otherwise I'll close this in 7 days for inactivity.
-```
-Persist the ping in `_cache/discussions-pinged-<date>.json` so the next run knows to close discussions that were pinged 7+ days ago without a reply.
-
-## Notes
-
-- This workflow is **interactive** — always present the summary and wait for user approval before posting responses, creating issues, or closing discussions.
-- Use `AskUserQuestion` to gather batched approval — separate questions for "reply scope", "create issues for?", "close stale?". Stale handling is a separate consent from reply posting.
-- For discussions in non-English languages (`pt-BR`, `ru`, `zh`, `es`), respond in the same language as the original post. Default to English when uncertain.
-- Always reference specific dashboard paths, config options, doc files, or code locations (`file:line`) when explaining existing features — never wave hands.
-- When a discussion reveals a bug, separate it from feature requests in the report. Bugs need a tracking issue + workaround; FRs need scoping.
-- Before recommending a workaround that mentions a file/flag/setting, verify it exists in the **current** codebase (the previous turn's memory may be stale).
-- Trust-but-verify: after a batch post, spot-check 2-3 random `comment.url` returns in the browser to confirm the comments rendered cleanly (no Unicode mojibake, no broken markdown).
-- **Secure-by-default guidance** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): when responses recommend security-relevant code (auth, crypto, SSRF, XSS sanitization), prefer well-tested libraries (Helmet.js, DOMPurify, Google Tink, ssrf-req-filter, safe-regex) over hand-rolled solutions.
-
-## Anti-patterns to avoid
-
-- ❌ Posting via `browser_subagent` clicks — slow, flaky, and obsolete since `gh api graphql` mutations exist.
-- ❌ N+1 fetches (one per discussion) — use one GraphQL query for all 50.
-- ❌ Creating an issue without checking for an existing umbrella / similar one first.
-- ❌ Generic "thanks, I'll look into it!" responses — every reply must reference a file, doc, or concrete action.
-- ❌ Closing a stale discussion without posting a closing comment first.
-- ❌ Skipping the user approval gate ("turbo-all" never bypasses interactive consent for writes).

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

@@ -1,278 +0,0 @@
----
-name: review-discussions-cx
-description: Read all open GitHub Discussions, summarize them, respond to pending ones, create issues from actionable feature requests, and triage stale threads for closure
----
-
-# /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, optionally creates issues from actionable feature requests, and triages stale threads for closure.
-
-**Modern tooling (replaces deprecated `browser_subagent` flow):**
-
-- Reads use `gh api graphql` — one query returns 50 discussions with full bodies, comments, replies, IDs, and `updatedAt`.
-- Writes (post comment, create issue, close discussion) use `gh api graphql` mutations or `gh issue create`.
-- Pace at ~1s between writes to avoid abuse-detection throttling.
-- `WebFetch` is acceptable only for read-only HTML scraping when GraphQL is unavailable — never for write actions.
-
-## Codex Execution Notes
-
-- Treat `// turbo` / `// turbo-all` as instructions to use `multi_tool_use.parallel` for independent reads (e.g., parallel `gh issue list` dedup searches across multiple FRs) — never for write actions.
-- The summary report is a hard stop. Do not post discussion replies, create issues, or close discussions until the user explicitly approves each phase.
-- Use the `apply_patch` tool to write reply bodies to `/tmp/reply-<num>.md` before invoking `gh api graphql -F body=@/tmp/reply-<num>.md` if the body contains tricky shell-escape characters.
-- Stop after step 4 (summary), step 6 (issue creation), and step 8 (stale triage). Three explicit consents per run.
-
-// turbo-all
-
-## Steps
-
-### 1. Identify the GitHub Repository
-
-- Run: `git -C <project_root> remote get-url origin` to extract `owner/repo`.
-- Parse owner and repo name from the URL (https or ssh form).
-
-### 2. Fetch All Open Discussions (paginated GraphQL)
-
-GraphQL caps each `discussions` query at 50 nodes — repos with more than 50 open discussions **must paginate**. Loop with `first: 50, after: $cursor` until `pageInfo.hasNextPage` is `false`. Skipping pagination silently drops the older half of the backlog, which is exactly where most stale-candidates and unanswered follow-ups live (regression observed 2026-05-28: page-1-only fetch missed 5 follow-ups and 4 stale candidates ranging from 23d to 56d).
-
-Each page request must return the **same field set** — easy mistake is to fetch page 2 without `body` (because the cursor query was hand-edited). Define one query string with `body` on both the discussion and every comment/reply, and reuse it across pages.
-
-Critical fields per discussion: `id` (node ID, **not** the visible `number`), `number`, `title`, `url`, `createdAt`, `updatedAt`, `author.login`, `category.name`, `body`, `answerChosenAt`, `labels(first: 10) { nodes { name } }`, plus nested `comments(first: 50) { totalCount, nodes { id, author.login, body, createdAt, replies(first: 20) { nodes { author.login, body, createdAt } } } }`. Must also include `pageInfo { hasNextPage endCursor }` on the discussions connection.
-
-Persist the **merged** result (all pages concatenated) to `/tmp/discussions-<repo>-<date>.json` so re-runs in the same session avoid a re-fetch. Build an `id → number` map for the post phase — the GraphQL `addDiscussionComment` mutation requires the node ID, not the number.
-
-Capture **image attachments** present in body or comments (`<img src="...">` or markdown `![...](...)`). Surface their count in the per-discussion summary (e.g., `📷 3 screenshots`) so the user can decide if visual context matters before approving a draft.
-
-### 3. Summarize All Discussions
-
-For each discussion, extract:
-
-- **Title** and **#Number**
-- **Author** (GitHub username)
-- **Category** (Announcements, General, Ideas, Q&A, Show and tell)
-- **Created** + **Last updated** (ISO date)
-- **Summary** of original post (1-2 sentences)
-- **Comment count** + **last commenter** + **last comment date** — determine these by **chronological `createdAt`**, not iteration order. Comments and their nested replies must be merged into a single sorted timeline before picking the latest event (otherwise a recent top-level reply gets shadowed by an older nested reply of an earlier comment, and the discussion is misclassified).
-- **Maintainer involvement**: whether the repo owner already replied, and how many times
-- **Pending action** — derived state, see categories below
-- **Attachments**: count of screenshots / videos / pastebin links
-- **Detected language** of the reporter (for reply-language matching)
-
-### 4. Present Summary Report to User
-
-Group by **pending action**, not by category, so the human sees triage buckets at a glance:
-
-| State                   | Meaning                                                                                                          |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| ⚠️ Needs first response | Zero comments, or all comments are from non-maintainers                                                          |
-| 🔄 Follow-up pending    | Maintainer replied, but reporter or third party added a new comment maintainer has not addressed                 |
-| 🕒 Stale (>15d)         | Maintainer was last to comment, no activity for 15+ days — candidate for soft-close or reporter-ping (see step 8)|
-| ✅ Answered             | Maintainer already replied AND last commenter is the maintainer AND age < 15d                                    |
-| 🏁 Resolved             | `answerChosenAt` is set                                                                                          |
-
-Within each bucket, present a table:
-
-| #   | Category | Title              | Author | Updated | Notes                  |
-| --- | -------- | ------------------ | ------ | ------- | ---------------------- |
-| #N  | Q&A      | short title (60ch) | @user  | YYYY-MM-DD | 📷2 · 🐛bug · 💡FR    |
-
-Tag rows with content hints when detected: `🐛bug` (`[BUG]` / `error` / stacktrace in body), `💡FR` (`feature request` / `add support for`), `❓support` (config/usage question), `🙏thanks` (short ack-only follow-up).
-
-### 5. Draft & Post Responses
-
-#### Reply templates by intent
-
-Pick the template that matches the discussion intent — do NOT use a single generic format.
-
-**A. Bug confirmed** — ack + root cause + tracking + workaround
-```
-Hey @user! Confirmed -- {root cause in one sentence}. I traced it to `path/to/file.ts:line`.
-
-{Why it happens: 2-4 sentences of technical detail}
-
-I have opened {issue #N} to track the fix. Workaround until it ships: {concrete steps}. Will update here when the patch lands.
-```
-
-**B. Feature Request** — ack + status + scope + commit
-```
-Hey @user! {Status: "Already exists" / "Tracked in #N" / "Reasonable, opening an issue"}.
-
-{If already exists: pointer to dashboard page or doc}
-{If tracked: link to umbrella, summarize order/priority}
-{If new: open issue + post link back}
-
-{Optional: short technical note on feasibility / trade-offs}
-```
-
-**C. Support / config question** — direct answer + reference + offer to dig deeper
-```
-Hey @user! {One-sentence answer}.
-
-Steps:
-1. ...
-2. ...
-3. ...
-
-Reference: `docs/<path>.md`. If it still fails after that, paste {specific thing} and I will trace it.
-```
-
-**D. Thank-you / short follow-up** — 1-2 sentences
-```
-Glad it helps, @user! {Concrete next marker — when patch ships / when to expect next update}.
-```
-
-**E. Stale / closing** — see step 8
-
-#### Posting via gh (replaces deprecated browser flow)
-
-```bash
-gh api graphql -f query='
-mutation($id: ID!, $body: String!) {
-  addDiscussionComment(input: {discussionId: $id, body: $body}) {
-    comment { id url }
-  }
-}' -f id="$NODE_ID" -f body="$BODY"
-```
-
-For **threaded replies** (recommended when responding to a specific comment in a long thread), add `replyToId: $parentCommentId` to the input.
-
-**Output hygiene** (still applies even via API — the comment renders in GitHub UI):
-
-- ASCII-safe punctuation: regular hyphens `-`, `->` for arrows
-- Markdown OK: `**bold**`, fenced code blocks, `[text](url)` links
-- No bare error messages with stack traces from internal logs — sanitize
-- Match reporter's language (pt-BR reporter → pt-BR reply; ru reporter → ru reply); default to English when uncertain
-
-**Pacing**: `sleep 1` between mutations. GitHub abuse-detection trips around 10/sec for the same actor.
-
-**Verification**: capture the returned `comment.url` from each mutation. Failed posts (returncode != 0 or `errors` in response) get logged separately and retried once after a 5s pause.
-
-### 6. Create Issues from Actionable Feature Requests
-
-For discussions that contain concrete, actionable feature requests:
-
-1. **Deduplicate FIRST** — before drafting, search existing issues:
-   ```bash
-   gh issue list --repo $OWNER/$REPO --search "<keywords from FR>" --state open --json number,title,labels
-   ```
-   If a matching issue (or umbrella) already exists, reuse it — never create a duplicate. Post a comment in the discussion linking to the existing issue.
-
-2. **Ask the user which to create** — even after dedup, the human approves the final list.
-
-3. **Create the issue** with `gh issue create`:
-   ```bash
-   gh issue create --repo $OWNER/$REPO \
-     --title "[feature] <short imperative>" \
-     --label enhancement \
-     --body @/tmp/issue-body.md
-   ```
-   Body template:
-   ```markdown
-   ## Feature Request
-
-   **Source:** Discussion #N by @author
-
-   ## Problem
-   What limitation the user hit (in their words, paraphrased)
-
-   ## Proposed Solution
-   How it could work
-
-   ### Implementation Ideas
-   - File paths likely to touch
-   - Related modules / patterns already in the codebase
-
-   ### Current Workarounds
-   What users can do today
-
-   ## Additional Context
-   - Discussion: #N
-   - Related issues/PRs: #X, #Y
-   - Upstream references: link to similar implementations in `_references/` if applicable
-   ```
-
-4. **Generate task file in `_ideia/`** when the feature needs deeper investigation before implementation:
-   ```
-   _ideia/<short-kebab-slug>.md
-   ```
-   Contains: problem statement, current OmniRoute state, how upstream (`_references/9router`, `_references/CLIProxyAPI`, etc.) handles it, proposed implementation levels (short/medium/long term), acceptance criteria.
-
-5. **Link back to discussion** with the real URL:
-   ```
-   Follow-up @reporter — I've opened issue #N to track this. {1-line summary of what the issue covers}.
-   ```
-
-### 7. Final Report
-
-| Discussion | Action Taken                                                  |
-| ---------- | ------------------------------------------------------------- |
-| #N — Title | Responded (bug confirmed, tracking #M)                        |
-| #N — Title | Responded + created issue #M + task file `_ideia/X.md`        |
-| #N — Title | Responded (support answered with workaround)                  |
-| #N — Title | Responded to follow-up comment                                |
-| #N — Title | Closed (stale 15+d, no reply from reporter)                   |
-| #N — Title | Ping sent (stale 15+d, will close in 7d if no response)       |
-
-Include totals: comments posted, issues created, discussions closed, discussions pinged. Capture median response time for the batch.
-
-### 8. Stale Discussion Triage (auto-close candidates)
-
-Identify discussions matching **all** of:
-
-- `updatedAt > 15 days ago`
-- Maintainer already replied at least once
-- Last commenter is the maintainer (the ball is on the reporter's side)
-- `answerChosenAt` is null (not formally resolved)
-- Category in `{Q&A, General}` — skip `Ideas` / `Show and tell` / `Announcements` (those serve as community references and shouldn't be closed)
-- `comments.totalCount >= 2` — there was actual conversation, not a drive-by post
-- No label named `keep-open` (escape hatch)
-
-For each candidate, present to the user with a recommended action:
-
-| Action          | When                                                                          |
-| --------------- | ----------------------------------------------------------------------------- |
-| **Soft-close**  | Default — maintainer answered concretely and reporter went silent             |
-| **Ping reporter** | Maintainer asked for more info (log dump, screenshot) and never got it      |
-| **Keep open**   | Conversation is mid-debug and closing would lose context — operator override  |
-
-**Soft-close mutation:**
-```bash
-gh api graphql -f query='
-mutation($id: ID!) {
-  closeDiscussion(input: {discussionId: $id, reason: RESOLVED}) {
-    discussion { id closed }
-  }
-}' -f id="$NODE_ID"
-```
-Valid `reason` values: `RESOLVED`, `OUTDATED`, `DUPLICATE`. Default to `OUTDATED` for "no response" closures, `RESOLVED` for answered-but-not-confirmed.
-
-Before closing, post a closing comment:
-```
-Closing for inactivity -- feel free to reopen if you still hit this, or open a fresh issue with a current log. Thanks!
-```
-
-**Ping flow** (alternative):
-```
-@reporter -- still happening on the latest version? Otherwise I'll close this in 7 days for inactivity.
-```
-Persist the ping in `_cache/discussions-pinged-<date>.json` so the next run knows to close discussions that were pinged 7+ days ago without a reply.
-
-## Notes
-
-- This workflow is **interactive** — always present the summary and wait for user approval before posting responses, creating issues, or closing discussions.
-- Three explicit consents per run: reply scope (after step 4), issue creation list (in step 6), stale-close list (in step 8).
-- For discussions in non-English languages (`pt-BR`, `ru`, `zh`, `es`), respond in the same language as the original post. Default to English when uncertain.
-- Always reference specific dashboard paths, config options, doc files, or code locations (`file:line`) when explaining existing features — never wave hands.
-- When a discussion reveals a bug, separate it from feature requests in the report. Bugs need a tracking issue + workaround; FRs need scoping.
-- Before recommending a workaround that mentions a file/flag/setting, verify it exists in the **current** codebase (the previous turn's memory may be stale).
-- Trust-but-verify: after a batch post, spot-check 2-3 random `comment.url` returns to confirm the comments rendered cleanly (no Unicode mojibake, no broken markdown).
-
-## Anti-patterns to avoid
-
-- ❌ Posting via `browser_subagent` clicks — slow, flaky, and obsolete since `gh api graphql` mutations exist.
-- ❌ N+1 fetches (one per discussion) — use one GraphQL query for all 50.
-- ❌ Creating an issue without checking for an existing umbrella / similar one first.
-- ❌ Generic "thanks, I'll look into it!" responses — every reply must reference a file, doc, or concrete action.
-- ❌ Closing a stale discussion without posting a closing comment first.
-- ❌ Skipping the user approval gate ("turbo-all" never bypasses interactive consent for writes).

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

@@ -1,257 +0,0 @@
----
-name: review-prs-ag
-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>=999?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/skills/review-prs-cc/SKILL.md

@@ -1,257 +0,0 @@
----
-name: review-prs-cc
-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>=999?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`

.agents/skills/review-prs-cx/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>=999?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-ag/SKILL.md

@@ -1,342 +0,0 @@
----
-name: version-bump-ag
-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 1000, bump to `3.(x+1).0` — e.g. `3.4.999` → `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/skills/version-bump-cc/SKILL.md

@@ -1,342 +0,0 @@
----
-name: version-bump-cc
-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 1000, bump to `3.(x+1).0` — e.g. `3.4.999` → `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`                                   |

.agents/skills/version-bump-cx/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 1000, bump to `3.(x+1).0` — e.g. `3.4.999` → `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`                                   |

.antigravitycli/0db0ca8e-3c51-48d9-83e2-da62c6f0a02b.json

@@ -1 +0,0 @@
-/home/diegosouzapw/.gemini/config/projects/0db0ca8e-3c51-48d9-83e2-da62c6f0a02b.json

.dockerignore

@@ -9,6 +9,7 @@
 # Dependencies and build output
 node_modules
 .next
+.build
 out
 build
 dist
@@ -38,10 +39,15 @@ playwright-report
 blob-report
 
 # Documentation
-# Translations (~51 MB) are excluded — the Docs viewer reads English sources.
-# Screenshots (~1.7 MB) and SVGs (~250 KB) are needed at build time for MDX
-# image resolution (fumadocs-mdx bundles them).
-# Raster sources under docs/diagrams/ only (exported SVGs are required).
+# 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 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/diagrams/**/*.png
 docs/diagrams/**/*.jpg

.env.example

@@ -6,7 +6,6 @@
 # │  Reference: docs/ENVIRONMENT.md for full details and usage scenarios.       │
 # └─────────────────────────────────────────────────────────────────────────────┘
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 1. REQUIRED SECRETS — Must be set before first run!
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -62,7 +61,6 @@ DISABLE_SQLITE_AUTO_BACKUP=false
 # Default: redis://localhost:6379 (or redis://redis:6379 in Docker)
 REDIS_URL=redis://localhost:6379
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 3. NETWORK & PORTS
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -159,6 +157,11 @@ OMNIROUTE_USE_TURBOPACK=1
 # Values: production | development  |  Default: production
 NODE_ENV=production
 
+# Container runtime — controls startup script behavior (permissions, advice).
+# Values: docker | podman  |  Default: docker
+# Set to "podman" when running under rootless Podman so the entrypoint
+# gives the correct fix instructions (podman unshare chown vs sudo chown).
+CONTAINER_HOST=docker
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # 4. SECURITY & AUTHENTICATION
@@ -238,7 +241,6 @@ ALLOW_API_KEY_REVEAL=false
 # When unset, OmniRoute uses the per-feature defaults. Set to "false"/"0" to disable.
 # OUTBOUND_SSRF_GUARD_ENABLED=true
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 5. INPUT SANITIZATION & PII PROTECTION (FASE-01)
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -271,7 +273,6 @@ ALLOW_API_KEY_REVEAL=false
 # PII_RESPONSE_SANITIZATION=false
 # PII_RESPONSE_SANITIZATION_MODE=redact  # redact = mask PII | warn = log only | block = drop response
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 6. TOOL & ROUTING POLICIES
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -291,7 +292,6 @@ ALLOW_API_KEY_REVEAL=false
 # Default: 5000  |  Minimum: 1000
 # OMNIROUTE_PAYLOAD_RULES_RELOAD_MS=5000
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 7. URLS & CLOUD SYNC
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -365,7 +365,6 @@ NEXT_PUBLIC_CLOUD_URL=
 #OMNIROUTE_OPENCODE_QUOTA_URL=https://opencode.ai/zen/go/v1/quota
 #OMNIROUTE_OPENCODE_GO_QUOTA_URL=https://api.z.ai/api/monitor/usage/quota/limit
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 8. OUTBOUND PROXY (Upstream Provider Calls)
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -393,7 +392,6 @@ NEXT_PUBLIC_ENABLE_SOCKS5_PROXY=true
 # Used by: open-sse/services/claudeTurnstileSolver.ts
 # OMNIROUTE_TURNSTILE_IGNORE_TLS_ERRORS=false
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 9. CLI TOOL INTEGRATION
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -423,7 +421,6 @@ NEXT_PUBLIC_ENABLE_SOCKS5_PROXY=true
 # CLI_QODER_BIN=qoder
 # CLI_QWEN_BIN=qwen
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 10. INTERNAL AGENT & MCP INTEGRATIONS
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -473,6 +470,17 @@ NEXT_PUBLIC_ENABLE_SOCKS5_PROXY=true
 # Default: 70
 PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70
 
+# Gap (ms) between consecutive OAuth quota fetches in a bulk provider-limits sync.
+# OAuth providers are fetched one at a time with this spacing so a single host
+# never bursts simultaneous usage/refresh requests to the same upstream. Set to 0
+# to opt out (restores fully concurrent fetches). Default: 1500
+PROVIDER_LIMITS_SYNC_SPACING_MS=1500
+
+# Delay (ms) before refreshing provider limits after a real usage event (e.g. a
+# completed request). Gives the upstream quota API time to register the consumption
+# before the dashboard polls. Default: 5000
+#PROVIDER_LIMITS_POST_USAGE_REFRESH_DELAY_MS=5000
+
 # Disable all background services (sync, pricing, model refresh).
 # Used by: src/instrumentation-node.ts, src/lib/initCloudSync.ts
 # Useful for: CI builds, test environments, or resource-constrained containers.
@@ -554,7 +562,6 @@ PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70
 # Default: ~/.gemini/antigravity-cli/antigravity-oauth-token
 #AGY_TOKEN_FILE=
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 11. OAUTH PROVIDER CREDENTIALS
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -583,6 +590,11 @@ CODEX_OAUTH_CLIENT_ID=app_EMoamEEZ73f0CkXaXp7hrann
 # Trae OAuth token override. Used by: open-sse/executors/trae.ts.
 # TRAE_TOKEN=
 
+# ── The Old LLM (theoldllm) ──
+# Playwright navigation timeout (ms) for the browser-backed token capture.
+# Used by: open-sse/executors/theoldllm.ts. Default: 30000 (30s).
+# THEOLDLLM_NAV_TIMEOUT_MS=30000
+
 # ── Gemini / Gemini CLI / Antigravity / Windsurf (all Google-based) ──
 # These providers ship public OAuth client_id/secret values (or Firebase Web
 # keys) embedded in their public CLIs/binaries. Defaults are baked into the
@@ -701,7 +713,6 @@ GITHUB_OAUTH_CLIENT_ID=Iv1.b507a08c87ecfe98
 # CLI_USER_ID=      # legacy alias for OMNIROUTE_USER_ID
 # SERVER_URL=       # legacy alias for OMNIROUTE_SERVER
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 12. PROVIDER USER-AGENT OVERRIDES
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -737,7 +748,6 @@ GEMINI_CLI_USER_AGENT="google-api-nodejs-client/10.3.0"
 # CODEX_USER_AGENT string. Used by: open-sse/config/codexClient.ts.
 # CODEX_CLIENT_VERSION=0.132.0
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 13. CLI FINGERPRINT COMPATIBILITY (Anti-Detection)
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -766,7 +776,6 @@ GEMINI_CLI_USER_AGENT="google-api-nodejs-client/10.3.0"
 #KIMI_CLI_VERSION=1.36.0
 #KIMI_CODING_DEVICE_ID=
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 14. API KEY PROVIDERS
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -789,7 +798,6 @@ GEMINI_CLI_USER_AGENT="google-api-nodejs-client/10.3.0"
 # OpenAI/Mistral/Together/Fireworks/NVIDIA configured via Dashboard → Providers
 # also work for embeddings.
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 15. TIMEOUT SETTINGS
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -836,6 +844,22 @@ GEMINI_CLI_USER_AGENT="google-api-nodejs-client/10.3.0"
 # OMNIROUTE_PPLX_TLS_TIMEOUT_MS=30000
 # OMNIROUTE_PPLX_TLS_GRACE_MS=10000
 
+# ── Grok web TLS sidecar (Chrome-fingerprinted client) ──
+# Used by: open-sse/services/grokTlsClient.ts — wire-level timeout for the
+# bogdanfinn/tls-client koffi binding and the JS-side grace window layered on
+# top of it when the native library is wedged.
+# OMNIROUTE_GROK_TLS_TIMEOUT_MS=60000
+# OMNIROUTE_GROK_TLS_GRACE_MS=10000
+
+# ── Browser-backed web-cookie chat (Playwright shared pool) ──
+# Used by: open-sse/services/browserPool.ts + browserBackedChat.ts. The shared
+# browser pool warms a headless context for web-cookie providers (e.g. claude-web)
+# that need a real browser to satisfy anti-bot challenges. Set OMNIROUTE_BROWSER_POOL=off
+# to fully disable the pool; set WEB_COOKIE_USE_BROWSER=1 to opt a web-cookie chat
+# request into the browser-backed path.
+# OMNIROUTE_BROWSER_POOL=on
+# WEB_COOKIE_USE_BROWSER=0
+
 # ── Circuit breaker thresholds and reset windows ──
 # Used by: open-sse/config/constants.ts → src/lib/resilience/settings.ts.
 # Defaults match historical PROVIDER_PROFILES values (post-scaling for
@@ -868,7 +892,6 @@ GEMINI_CLI_USER_AGENT="google-api-nodejs-client/10.3.0"
 # Default: 30000 (30 seconds)
 # SHUTDOWN_TIMEOUT_MS=30000
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 16. LOGGING
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -942,7 +965,6 @@ APP_LOG_TO_FILE=true
 # Default: 100000
 # PROXY_LOGS_TABLE_MAX_ROWS=100000
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 17. MEMORY OPTIMIZATION (Low-RAM / Docker)
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -1022,7 +1044,6 @@ APP_LOG_TO_FILE=true
 # Used by: open-sse/utils/usageTracking.ts
 # USAGE_TOKEN_BUFFER=100
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 18. PRICING SYNC
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -1038,7 +1059,6 @@ APP_LOG_TO_FILE=true
 # Comma-separated data sources.  Default: litellm
 # PRICING_SYNC_SOURCES=litellm
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 19. MODEL SYNC (Dev)
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -1047,7 +1067,6 @@ APP_LOG_TO_FILE=true
 # Default: 86400 (24 hours)
 # MODELS_DEV_SYNC_INTERVAL=86400
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 20. PROVIDER-SPECIFIC SETTINGS
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -1058,6 +1077,14 @@ APP_LOG_TO_FILE=true
 # Default: 86400000 (24 hours)
 # OPENROUTER_CATALOG_TTL_MS=86400000
 
+# ── Model catalog response shape ──
+# Include display-friendly name fields in /v1/models responses.
+# Disable for clients that expect model IDs only.
+# Defined in: src/shared/constants/featureFlagDefinitions.ts
+# Used by: src/app/api/v1/models/catalog.ts
+# Default: true
+# MODEL_CATALOG_INCLUDE_NAMES=true
+
 # ── NanoBanana (Image Generation) ──
 # Polling config for async image generation jobs.
 # Used by: open-sse/handlers/imageGeneration.ts
@@ -1128,7 +1155,6 @@ APP_LOG_TO_FILE=true
 # Used by: open-sse/config/providerRegistry.ts — allows Docker service names.
 # LOCAL_HOSTNAMES=omlx,mlx-audio
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 21. PROXY HEALTH
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -1150,11 +1176,29 @@ APP_LOG_TO_FILE=true
 # Accepted values: true|1|on (force on), false|0|off (force off), unset (use Dashboard).
 # RATE_LIMIT_AUTO_ENABLE=
 
+# Provider cooldown tracking: minimum time (ms) before a failed provider/connection
+# can be retried. Prevents subsequent requests from re-walking failing providers.
+# Scaled exponentially: minCooldown * 2^(failures-1), capped at maxRetryCooldownMs.
+# Used by: open-sse/services/providerCooldownTracker.ts
+# PROVIDER_COOLDOWN_MIN_MS=5000
+
+# Provider cooldown tracking: maximum time (ms) before a failed provider/connection
+# is retried regardless. Hard cap to prevent providers from being skipped indefinitely.
+# Used by: open-sse/services/providerCooldownTracker.ts
+# PROVIDER_COOLDOWN_MAX_MS=300000
+
+# Enable/disable global provider cooldown tracking. Opt-in: this global
+# cross-request cooldown overlaps the existing Connection Cooldown / Provider
+# Circuit Breaker layers, so it is OFF by default. When disabled, only the
+# existing per-request/per-connection cooldown state is used (previous behavior).
+# Used by: open-sse/services/providerCooldownTracker.ts
+# Accepted values: true|1|on (enable). Unset or anything else = disabled (default).
+# PROVIDER_COOLDOWN_ENABLED=true
+
 # Stagger interval (ms) between provider token healthchecks at startup.
 # Used by: src/lib/tokenHealthCheck.ts.  Default: 3000.
 # HEALTHCHECK_STAGGER_MS=3000
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 22. DEBUGGING
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -1167,9 +1211,9 @@ APP_LOG_TO_FILE=true
 
 # Enable verbose trace logging for OmniRoute internals.
 # Used by: open-sse/handlers/chatCore.ts.
-# OMNIRROUTE_TRACE=true
+# OMNIROUTE_TRACE=true
 
-# Standard DEBUG flag (same effect as OMNIRROUTE_TRACE).
+# Standard DEBUG flag (same effect as OMNIROUTE_TRACE).
 # DEBUG=true
 # CURSOR_STREAM_DEBUG=1
 
@@ -1180,6 +1224,16 @@ APP_LOG_TO_FILE=true
 # Used by: open-sse/executors/cursor.ts.
 # CURSOR_STREAM_TIMEOUT_MS=300000
 
+# Cursor tool-commit directive toggle. Default-on: when a request declares
+# tools, a directive is prepended so composer-2.5 reliably issues tool calls
+# instead of narrating intent. Set to 0 to disable.
+# Used by: open-sse/executors/cursor.ts.
+# CURSOR_TOOL_DIRECTIVE=1
+
+# Per-image fetch timeout (ms) for remote image_url vision input. Default: 15000.
+# Used by: open-sse/utils/cursorImages.ts.
+# CURSOR_IMAGE_FETCH_TIMEOUT_MS=15000
+
 # Cursor state DB path override (for cursor version detection).
 # Used by: open-sse/utils/cursorVersionDetector.ts. Default: probed automatically.
 # CURSOR_STATE_DB_PATH=
@@ -1204,7 +1258,6 @@ APP_LOG_TO_FILE=true
 # Enable E2E test mode — relaxes auth and enables test harness hooks.
 # NEXT_PUBLIC_OMNIROUTE_E2E_MODE=true
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 23. GITHUB INTEGRATION (Issue Reporting)
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -1222,7 +1275,6 @@ APP_LOG_TO_FILE=true
 # GITHUB_ISSUES_TOKEN when unset.
 # GITHUB_TOKEN=
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 24. PROVIDER QUOTAS, TUNNELS & SANDBOXED SKILLS
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -1255,6 +1307,13 @@ APP_LOG_TO_FILE=true
 # Used by: src/app/api/providers/command-code/auth/shared.ts.
 # COMMAND_CODE_CALLBACK_PORT=
 
+# ── Command Code CLI version header ──
+# Value sent as the x-command-code-version header to the Command Code upstream.
+# Overrides the built-in default; bump if the upstream requires a newer CLI version.
+# Used by: open-sse/executors/commandCode.ts
+# Default: 0.33.2
+# COMMAND_CODE_VERSION=0.33.2
+
 # ── MITM debug proxy (development only) ──
 # Used by: src/mitm/server.cjs — captures upstream traffic for inspection.
 # MITM_LOCAL_PORT=443
@@ -1327,7 +1386,6 @@ APP_LOG_TO_FILE=true
 # SKILLS_SANDBOX_NETWORK_ENABLED=0
 # SKILLS_ALLOWED_SANDBOX_IMAGES=
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # 25. TEST & E2E
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -1349,6 +1407,12 @@ APP_LOG_TO_FILE=true
 # Disable the OAuth token healthcheck loop during tests (default: true).
 # OMNIROUTE_DISABLE_TOKEN_HEALTHCHECK=true
 
+# Exclude specific providers from the PROACTIVE token-refresh sweep (comma-separated,
+# case-insensitive). Targeted alternative to OMNIROUTE_DISABLE_TOKEN_HEALTHCHECK: keeps
+# rotating-cascade providers (Codex/OpenAI share one Auth0 family) on the reactive 401
+# path only, while short-TTL providers like Kimi-coding keep being refreshed proactively.
+# OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS=codex,openai
+
 # Silence healthcheck noise in Playwright stdout (default: true).
 # OMNIROUTE_HIDE_HEALTHCHECK_LOGS=true
 
@@ -1438,8 +1502,21 @@ INSPECTOR_MASK_SECRETS=true
 INSPECTOR_LLM_HOSTS_EXTRA=
 INSPECTOR_INTERNAL_INGEST_TOKEN=
 # Quota Sharing (Group B — planos 16+22)
-QUOTA_STORE_DRIVER=sqlite                   # sqlite | redis
-# QUOTA_STORE_REDIS_URL=                    # ex.: redis://localhost:6379 (apenas quando driver=redis)
-# QUOTA_SATURATION_THRESHOLD=0.5            # 0..1; >= threshold ativa modo strict (sem empréstimo)
-# QUOTA_SOFT_DEPRIORITIZE_FACTOR=0.7        # 0..1; multiplicador do score quando soft policy ativa
-# QUOTA_CONSUMPTION_RETENTION_DAYS=14       # GC de buckets quota_consumption.updated_at antigos
+QUOTA_STORE_DRIVER=sqlite              # sqlite | redis
+# QUOTA_STORE_REDIS_URL=               # ex.: redis://localhost:6379 (apenas quando driver=redis)
+# QUOTA_SATURATION_THRESHOLD=0.5       # 0..1; >= threshold ativa modo strict (sem empréstimo)
+# QUOTA_SOFT_DEPRIORITIZE_FACTOR=0.7   # 0..1; multiplicador do score quando soft policy ativa
+# QUOTA_CONSUMPTION_RETENTION_DAYS=14  # GC de buckets quota_consumption.updated_at antigos
+
+# ─── OpenCode config regeneration (scripts/ad-hoc/regen-opencode-config.ts) ───
+# Base URL of the OmniRoute instance to query for /v1/models when regenerating
+# an opencode.json with accurate limit.context values. Used by:
+# scripts/ad-hoc/regen-opencode-config.ts. Default: http://localhost:20128
+# OMNIROUTE_URL=
+# API key to authenticate against the OmniRoute /v1/models endpoint. Falls back
+# to OPENCODE_API_KEY when unset. Used by: scripts/ad-hoc/regen-opencode-config.ts.
+# OMNIROUTE_KEY=
+# OpenCode-style API key (sk-...) for the regenerated opencode.json. Used by:
+# scripts/ad-hoc/regen-opencode-config.ts. Falls back to OMNIROUTE_KEY.
+# OPENCODE_API_KEY=
+

.github/workflows/ci.yml

@@ -24,6 +24,12 @@ jobs:
   lint:
     name: Lint
     runs-on: ubuntu-latest
+    env:
+      # tsx gates below (known-symbols, route-guard-membership) import modules that
+      # open SQLite on load; provide DB env so a fresh CI DB initializes cleanly.
+      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@v6
       - uses: actions/setup-node@v6
@@ -37,6 +43,17 @@ jobs:
       - run: npm run check:cycles
       - run: npm run check:route-validation:t06
       - run: npm run check:any-budget:t11
+      - run: npm run check:provider-consistency
+      - run: npm run check:fetch-targets
+      - 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:docs-sync
       - run: npm run typecheck:core
       # typecheck:noimplicit:core is a forward-looking gate (noImplicitAny).
@@ -45,6 +62,46 @@ jobs:
       - run: npm run typecheck:noimplicit:core
         continue-on-error: true
 
+  quality-gate:
+    name: Quality Ratchet
+    runs-on: ubuntu-latest
+    needs: test-coverage
+    if: ${{ always() && needs.test-coverage.result == 'success' }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      # Coverage mergeada (coverage-summary.json) p/ o ratchet de cobertura.
+      - uses: actions/download-artifact@v8
+        with:
+          name: coverage-report
+          path: coverage/
+      - run: npm run quality:collect
+      # Catraca: falha se qualquer métrica regredir vs quality-baseline.json (commitado).
+      # Hoje: contagem de warnings do ESLint. Fase 4 estende com cobertura (lida do
+      # coverage mergeado). Tamanho de arquivo e duplicação têm gates dedicados.
+      - name: Ratchet check
+        run: node scripts/quality/check-quality-ratchet.mjs --summary .artifacts/quality-ratchet.md
+      # Catraca de duplicação (jscpd@4 sobre src+open-sse). Roda neste job (paralelo)
+      # para não pesar no caminho crítico do lint.
+      - name: Duplication ratchet
+        run: npm run check:duplication
+      - name: Complexity ratchet
+        run: npm run check:complexity
+      - name: Append summary
+        if: always()
+        run: cat .artifacts/quality-ratchet.md >> "$GITHUB_STEP_SUMMARY"
+      - name: Upload ratchet report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: quality-ratchet
+          path: .artifacts/quality-ratchet.md
+          if-no-files-found: warn
+
   docs-sync-strict:
     name: Docs Sync (Strict)
     runs-on: ubuntu-latest
@@ -56,6 +113,19 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run check:docs-all
+      # Previously-orphaned contract gates (existed as files, never wired anywhere).
+      # All exit 0 today: cli-i18n is a hard gate, openapi-coverage is a ratchet
+      # (floor ~36), openapi-security-tiers is advisory (Hard Rules #15/#17).
+      - name: CLI i18n consistency
+        run: npm run check:cli-i18n
+      - name: OpenAPI route coverage (ratchet)
+        run: npm run check:openapi-coverage
+      - name: OpenAPI security-tier consistency (advisory)
+        run: npm run check:openapi-security-tiers
+      - name: OpenAPI spec paths resolve to real routes (anti-hallucination)
+        run: npm run check:openapi-routes
+      - name: Doc /api refs resolve to real routes (anti-hallucination)
+        run: npm run check:docs-symbols
       - name: i18n translation drift (warn)
         run: node scripts/i18n/check-translation-drift.mjs --warn
 
@@ -125,6 +195,9 @@ jobs:
         run: git fetch --no-tags origin "${GITHUB_BASE_REF}" --depth=1
       - name: Validate source changes include tests
         run: node scripts/check/check-pr-test-policy.mjs --summary-file .artifacts/pr-test-policy.md
+      # Anti test-masking: flag net assert removal / new assert.ok(true) in changed tests.
+      - name: Detect test-masking (weakened assertions)
+        run: npm run check:test-masking
       - name: Publish PR test policy summary
         if: always()
         run: |
@@ -144,6 +217,21 @@ jobs:
       - run: npm ci
       - run: npm run check:node-runtime
       - run: npm run build
+      - name: Archive Next.js build for E2E shards
+        # Use tar so the archive preserves paths relative to CWD (.build/next/...).
+        # upload-artifact path-stripping is ambiguous when exclude patterns are used;
+        # an explicit tar avoids the double-nesting issue (.build/next/next/...).
+        run: |
+          tar -czf /tmp/e2e-build.tar.gz \
+            --exclude='.build/next/standalone/node_modules' \
+            --exclude='.build/next/cache' \
+            .build/next
+      - name: Upload Next.js build for E2E shards
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-next-build
+          path: /tmp/e2e-build.tar.gz
+          retention-days: 1
 
   package-artifact:
     name: Package Artifact
@@ -159,7 +247,11 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run check:node-runtime
+      # build:cli runs a clean build into .build/next and assembles dist/
+      # For release builds prefer: npm run build:release (clean rebuild + HEAD sentinel)
       - run: npm run build:cli
+      - name: Assert dist/server.js exists
+        run: test -f dist/server.js || (echo "dist/server.js missing — build:cli did not assemble correctly" && exit 1)
       - run: npm run check:pack-artifact
 
   electron-package-smoke:
@@ -211,7 +303,32 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run check:node-runtime
-      - run: node --max-old-space-size=4096 --import tsx --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/8 tests/unit/*.test.ts
+      - run: node --max-old-space-size=4096 --import tsx --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/8 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,compression,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui}/**/*.test.ts"
+
+  test-vitest:
+    name: Vitest (MCP / autoCombo / UI components)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: build
+    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"
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      # The second test runner (CLAUDE.md: "Both test runners must pass") — was never
+      # wired into CI until the 2026-06-09 quality audit (Fase 6A.2).
+      - run: npm run test:vitest
+      # vitest:ui is RED today (14 fails — UI component drift accumulated while the
+      # suite never ran in CI). Informational until the Fase 6A triage (2026-06-16+)
+      # fixes the components/tests; then drop continue-on-error to make it blocking.
+      - run: npm run test:vitest:ui
+        continue-on-error: true
 
   node-24-compat:
     name: Node 24 Compatibility (${{ matrix.shard }}/2)
@@ -235,7 +352,7 @@ jobs:
       - run: npm ci
       - run: npm run check:node-runtime
       - run: npm run build
-      - run: node --import tsx --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/2 tests/unit/*.test.ts
+      - run: node --import tsx --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,compression,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui}/**/*.test.ts"
 
   node-26-compat:
     name: Node 26 Compatibility (${{ matrix.shard }}/2)
@@ -259,7 +376,7 @@ jobs:
       - run: npm ci
       - run: npm run check:node-runtime
       - run: npm run build
-      - run: node --import tsx --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/2 tests/unit/*.test.ts
+      - run: node --import tsx --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,compression,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui}/**/*.test.ts"
 
   test-coverage-shard:
     name: Coverage Shard (${{ matrix.shard }}/8)
@@ -298,7 +415,7 @@ jobs:
             --exclude=tests/** \
             --exclude=**/*.test.* \
             node --max-old-space-size=4096 --import tsx --test --test-force-exit --test-concurrency=4 \
-              --test-shard=${{ matrix.shard }}/8 tests/unit/*.test.ts
+              --test-shard=${{ matrix.shard }}/8 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,compression,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui}/**/*.test.ts"
       - name: Upload raw shard coverage
         if: always()
         uses: actions/upload-artifact@v7
@@ -341,10 +458,12 @@ jobs:
             find . -maxdepth 3 -type f | sort
             exit 1
           fi
-          # Gate aligned to the project's local coverage bar (npm run test:coverage
-          # uses 40/40/40/40). The previous 75/70 gate never ran on main (the
-          # coverage shards always failed → this job was skipped), so it was never
-          # actually enforced and is inconsistent with the repo's real standard.
+          # Gate aligned to the project's local coverage bar: `npm run test:coverage`
+          # gates at 60/60/60/60, so CI must match it (the previous CI floor of 40
+          # silently undershot the local bar — a real drift). Real merged coverage is
+          # ~79/79/82/75, so 60 is a conservative floor with headroom; the Fase-4
+          # coverage ratchet (quality-baseline.json) layers "must not drop vs baseline"
+          # on top of this floor.
           npx c8 report \
             --temp-directory coverage-shards \
             --reports-dir coverage \
@@ -355,7 +474,7 @@ jobs:
             --exclude=tests/** \
             --exclude=**/*.test.* \
             --check-coverage \
-            --statements 40 --lines 40 --functions 40 --branches 40
+            --statements 60 --lines 60 --functions 60 --branches 60
       - name: Build coverage summary
         if: always()
         run: |
@@ -494,14 +613,18 @@ jobs:
             }
 
   test-e2e:
-    name: E2E Tests (${{ matrix.shard }}/6)
+    name: E2E Tests (${{ matrix.shard }}/9)
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    # Build artifact from the `build` job is downloaded instead of rebuilding
+    # (~5min saved per shard). 9 shards (up from 6) reduces tests per shard by
+    # ~33%. Playwright browser is cached across runs (~1.5min saved per shard).
+    # Heavy shard target: ≤20min (was ~40min). Timeout 45min to cover slow runners.
+    timeout-minutes: 45
     needs: build
     strategy:
       fail-fast: false
       matrix:
-        shard: [1, 2, 3, 4, 5, 6]
+        shard: [1, 2, 3, 4, 5, 6, 7, 8, 9]
     env:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
@@ -515,9 +638,23 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run check:node-runtime
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        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
-      - run: npm run build
-      - run: npx playwright test tests/e2e/*.spec.ts --shard=${{ matrix.shard }}/6
+      - name: Download Next.js build artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: e2e-next-build
+          path: /tmp/
+      - name: Extract Next.js build and restore standalone node_modules
+        run: |
+          tar -xzf /tmp/e2e-build.tar.gz
+          cp -r node_modules .build/next/standalone/node_modules
+      - run: npx playwright test tests/e2e/*.spec.ts --shard=${{ matrix.shard }}/9
 
   test-integration:
     name: Integration Tests (${{ matrix.shard }}/2)

.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

@@ -176,20 +176,46 @@ jobs:
         env:
           DOCKER_BUILDKIT_INLINE_CACHE: 1
 
-      - name: Export digest
+      - 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:
-          DIGEST: ${{ steps.build.outputs.digest }}
+          DOCKER_BUILDKIT_INLINE_CACHE: 1
+
+      - name: Export digests
+        env:
+          DIGEST_BASE: ${{ steps.build.outputs.digest }}
+          DIGEST_WEB: ${{ steps.build-web.outputs.digest }}
         run: |
           set -euo pipefail
-          mkdir -p /tmp/digests
-          digest="${DIGEST#sha256:}"
-          touch "/tmp/digests/${digest}"
+          mkdir -p /tmp/digests/base /tmp/digests/web
+          touch "/tmp/digests/base/${DIGEST_BASE#sha256:}"
+          touch "/tmp/digests/web/${DIGEST_WEB#sha256:}"
 
-      - name: Upload digest
+      - name: Upload base digests
         uses: actions/upload-artifact@v7
         with:
-          name: digests-${{ matrix.arch }}
-          path: /tmp/digests/*
+          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
 
@@ -228,54 +254,67 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Download digests
+      - name: Download base digests
         uses: actions/download-artifact@v8
         with:
-          pattern: digests-*
-          path: /tmp/digests
+          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
 
-          tags=(-t "${IMAGE_NAME}:${VERSION}")
-          if [ "$PROMOTE_LATEST" = "true" ]; then
-            tags+=(-t "${IMAGE_NAME}:latest")
-          fi
+          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[@]}"
+          }
 
-          refs=()
-          while IFS= read -r digest_file; do
-            refs+=("${IMAGE_NAME}@sha256:$(basename "$digest_file")")
-          done < <(find /tmp/digests -type f | sort)
-
-          if [ "${#refs[@]}" -eq 0 ]; then
-            echo "No image digests were downloaded." >&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
 
-          tags=(-t "${GHCR_IMAGE_NAME}:${VERSION}")
-          if [ "$PROMOTE_LATEST" = "true" ]; then
-            tags+=(-t "${GHCR_IMAGE_NAME}:latest")
-          fi
+          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[@]}"
+          }
 
-          refs=()
-          while IFS= read -r digest_file; do
-            refs+=("${GHCR_IMAGE_NAME}@sha256:$(basename "$digest_file")")
-          done < <(find /tmp/digests -type f | sort)
-
-          if [ "${#refs[@]}" -eq 0 ]; then
-            echo "No image digests were downloaded." >&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'

.github/workflows/electron-release.yml

@@ -136,9 +136,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"

.gitignore

@@ -9,6 +9,19 @@ _ideia/
 _mono_repo/
 _references/
 _tasks/
+.agents/**
+.claude/**
+.gemini/**
+.config/**
+.data/**
+.logs/**
+.tests/**
+.coverage/**
+coverage/
+.dist/**
+.next/**
+.build/**
+.out/**
 
 
 # Memory Bank and Cursor rules (local-only AI agent context)
@@ -31,38 +44,15 @@ docs/new-features/
 
 # dependencies
 node_modules/
-/.pnp
-.pnp.*
-.yarn/*
-!.yarn/patches
-!.yarn/plugins
-!.yarn/releases
-!.yarn/versions
-.data/
-.next-playwright/
-.agents/
-workflows/
-.omo/
-
-# devbox
-.devbox/
-
-# testing
-coverage/
-coverage**
-
-# next.js
-.next/
-/out/
-
-# production
-/build
-/app
-cloud/*
-
-# misc
+*.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*
@@ -73,6 +63,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
@@ -124,10 +117,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/
@@ -142,9 +138,6 @@ vscode-extension/
 *.sqlite-wal
 *.sqlite-journal
 
-# Compiled npm-package build artifact (not source, should not be in git)
-/app
-
 # IDEA
 .idea/
 
@@ -203,3 +196,19 @@ scripts/i18n/_pending-keys.json
 # 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, métricas não)
+quality-metrics.json
+-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

.husky/pre-commit

@@ -1,31 +1,12 @@
-# #!/usr/bin/env sh
-# if ! command -v npx >/dev/null 2>&1; then
-#   echo "⚠️  npx not found in PATH — skipping pre-commit hooks"
-#   echo "   Run 'npm run lint && npm run check:any-budget:t11' manually before pushing."
-#   exit 0
-# fi
+#!/usr/bin/env sh
+if ! command -v npx >/dev/null 2>&1; then
+  echo "⚠️  npx not found in PATH — skipping pre-commit hooks"
+  echo "   Run 'npm run lint && npm run check:any-budget:t11' manually before pushing."
+  exit 0
+fi
 
-# 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."
-
-# # OpenAPI coverage check — fails if coverage < 99% (FASE 08 content audit)
-# node scripts/check/check-openapi-coverage.mjs
-
-# # OpenAPI security tier consistency check — fails if x-loopback-only / x-always-protected
-# # annotations diverge from routeGuard.ts compile-time constants (FASE 08 content audit)
-# node scripts/check/check-openapi-security-tiers.mjs
+# 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

.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"
-        }
-      }
-    }
-  }
-}

.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

.source/source.config.mjs

@@ -4,6 +4,7 @@ var docs = defineDocs({
   dir: "docs",
   docs: {
     files: [
+      "./getting-started/**/*.md",
       "./architecture/**/*.md",
       "./guides/**/*.md",
       "./reference/**/*.md",

.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

@@ -36,7 +36,18 @@
     "**/node_modules/**": true,
     "**/.next/**": true,
     "**/coverage/**": true,
-    "**/_tasks/**": true
+    "**/_tasks/**": true,
+    "**/.git/objects/**": true,
+    "**/dist/**": true,
+    "**/build/**": true,
+    "**/out/**": true,
+    "**/.cache/**": true,
+    "**/.turbo/**": true,
+    "**/OmniRoute-*/**": true,
+    "**/*-merge-*/**": true,
+    "**/*-worktree-*/**": true,
+    "**/*-issues-*/**": true,
+    "**/*-reorg*/**": true
   },
   "search.exclude": {
     "**/_references": true,
@@ -45,6 +56,14 @@
     "**/node_modules": true,
     "**/.next": true,
     "**/coverage": true,
-    "**/_tasks": true
+    "**/_tasks": true,
+    "**/dist": true,
+    "**/build": true,
+    "**/out": true,
+    "**/OmniRoute-*": true,
+    "**/*-merge-*": true,
+    "**/*-worktree-*": true,
+    "**/*-issues-*": true,
+    "**/*-reorg*": true
   }
 }

@omniroute/opencode-plugin/README.md

@@ -1,6 +1,20 @@
 # @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
 

@omniroute/opencode-plugin/package.json

@@ -26,7 +26,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",
     "prepublishOnly": "npm run clean && npm run build && npm test"
   },
   "keywords": [

@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/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-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.

@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",

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

@@ -129,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>;
   /**
@@ -139,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.
@@ -248,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] ?? {};
@@ -266,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 };
     }
 
@@ -508,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,
@@ -430,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",
@@ -639,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,10 +3,44 @@
 ## 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 **229 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** (69 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.
+
+> **Live counts (v3.8.16)**: providers 229 · MCP tools 69 · MCP scopes 13 · A2A skills 6 ·
+> open-sse services 111 · routing strategies 15 · auto-combo scoring factors 12 ·
+> DB modules 76 · DB migrations 94 · base tables 17 · search providers 12 ·
+> 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
 
@@ -15,7 +49,7 @@ with **MCP Server** (37 tools), **A2A v0.3 Protocol**, and **Electron desktop ap
 - **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 **76 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 76). Drift detection: `npm run check:docs-counts`.
+Schema migrations live in `db/migrations/` (**94 files** as of v3.8.16) 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**: 94 files (`001_initial_schema.sql` → `094_*.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`,
+111 service modules in `open-sse/services/` (top-level only; 171 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).
+69 tools across 10 tool files (advancedTools: 5, agentSkillTools: 3, compressionTools: 5, gamificationTools: 8, memoryTools: 3, notionTools: 6, obsidianTools: 22, pluginTools: 8, poolTools: 5, skillTools: 4), 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (13 scopes — see `OMNIROUTE_MCP_SCOPES` in `open-sse/mcp-server/README.md:51`), 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,
@@ -369,7 +417,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** (13): 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 +426,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
 
@@ -479,31 +527,31 @@ 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/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)                                                                    |
 
 ---
 

CHANGELOG.md

@@ -4,6 +4,590 @@
 
 ---
 
+## [3.8.21] — 2026-06-11
+
+### ✨ Added
+
+- **feat(cli):** `omniroute autostart` now accepts the shorthand the headless / `omniroute serve` path was missing — `omniroute autostart on` / `... true` (aliases of `enable`), `... off` / `... false` (aliases of `disable`), a new `... toggle`, and a default `... status` (bare `omniroute autostart` is a safe read-only). Previously autostart could only be toggled from the tray (`serve --tray`) or the Electron Appearance tab, so a plain `omniroute serve` user had no way to enable it. (The cross-platform launchd/systemd/registry logic is unchanged — this only wires the ergonomic CLI surface.) ([#3331](https://github.com/diegosouzapw/OmniRoute/issues/3331) — thanks @uniQta)
+
+### ♻️ Code Quality
+
+- **refactor(chatCore):** extract the chatCore request phases — idempotency check, semantic cache check, common request sanitization, and memory/skills injection — into dedicated `open-sse/handlers/chatCore/` modules (`idempotency.ts`, `semanticCache.ts`, `sanitization.ts`, `memorySkillsInjection.ts`), slimming the monolithic handler with no behavior change. (Maintainer follow-up: re-derive `idempotencyKey` at the Phase 9.2 save site after the check moved into the module, fixing a `ReferenceError` on successful non-cached responses.) ([#3598](https://github.com/diegosouzapw/OmniRoute/pull/3598) — thanks @oyi77)
+- **docs(opencode-provider):** soft-deprecate `@omniroute/opencode-provider` in favour of `@omniroute/opencode-plugin`. The provider package writes a **static** model list to `opencode.json` that drifts behind the live OmniRoute catalog, whereas the plugin fetches `/v1/models` at OpenCode startup. The package keeps working (no code/behavior change), but its npm description and README now carry a deprecation banner with the one-line migration, and a guard test pins the notice. ([#3419](https://github.com/diegosouzapw/OmniRoute/issues/3419) — thanks @herjarsa)
+- **chore(review):** pre-release hardening from a multi-reviewer `/review-reviews` battery over the v3.8.21 diff (7 Opus reviewers; zero blocker/high). Resolved findings: npm tarball no longer ships co-located test files (`files[]` negations + reconciled `.npmignore`; the #3578 closure gate now asserts the real `npm pack` output in both directions); `getSanitizedCachedProviderLimitsMap` scopes its connection scan to antigravity/agy instead of decrypting every active connection on each dashboard poll; the Antigravity quota-tier remap (`toClientAntigravityQuotaModelId`) is centralized in `antigravityModelAliases.ts` (was an inline if-ladder in `usage.ts`); the chatCore idempotency check returns its resolved key so the save site reuses a single derivation; and new tests pin the chatCore extracted modules, the Antigravity `usage_history` fallback contract, the reasoning-wrapper prefix-preservation heuristic, the Antigravity SSE `markdown` branch, and the upstream-ca/test no-persist guarantee. (Live-verified that agy consumer tokens are accepted by the non-daily `cloudcode-pa` host used by `retrieveUserQuota`, so #3604 is not agy-host-limited.)
+
+### 🔧 Bug Fixes
+
+- **fix(routing):** reasoning models (deepseek-v4-flash, nemotron, etc.) no longer return empty content in combo routing when they spend all of `max_tokens` on reasoning — `validateResponseQuality` now rejects an empty-content-but-`reasoning_content` response when reasoning consumed ≥90% of completion tokens (so the combo loop retries/falls back), and reasoning models receive a `max_tokens` buffer (+50%, +1000 floor) so reasoning and content both fit. (Maintainer follow-up: the round-robin buffer is applied to a per-attempt copy so it does not compound across models/retries — `4096 → 6144 → 9216 → …`.) ([#3588](https://github.com/diegosouzapw/OmniRoute/pull/3588) — thanks @herjarsa)
+- **fix(routing):** a valid `max_tokens`-truncated upstream response is no longer misclassified as empty content and rewritten into a fake 502 — `isEmptyContentResponse()` flagged any Claude `content:[]` / OpenAI empty-choice payload regardless of `stop_reason`/`finish_reason`, so a Claude Code `max_tokens: 1` connectivity ping (HTTP 200, `stop_reason:"max_tokens"`, empty content) became a synthetic `502 "Provider returned empty content"` and triggered a needless family fallback. The guard now treats a terminal truncation/tool signal (Claude `stop_reason` `max_tokens`/`tool_use`, OpenAI `finish_reason` `length`/`tool_calls`) as a legitimate completion; genuinely empty responses (no terminal reason, or `stop`/`end_turn` with empty content) are still caught. ([#3572](https://github.com/diegosouzapw/OmniRoute/issues/3572))
+- **fix(api):** `/v1/completions` now returns the legacy OpenAI Completions shape (`object:"text_completion"`, `choices[].text`) instead of chat payloads (`choices[].message|delta.content`) — the endpoint routes internally through the chat pipeline, so legacy Completion clients like TabbyML's `openai/completion` backend crashed with `missing field "text"`. The response (both non-streaming JSON and the SSE stream) is now translated back to the text-completion shape; `[DONE]` and error bodies pass through unchanged. ([#3571](https://github.com/diegosouzapw/OmniRoute/issues/3571))
+- **fix(usage):** the z.ai/GLM coding-plan quota card no longer shows "Monthly 0%" — coding plans have no monthly cap (only 5-hour windows), so the quota API reports the `TIME_LIMIT` ("Monthly") entry with `total=0`, and the `total>0 ? … : 0` fallback rendered a misleading 0% remaining (which can skew downstream model-choice). With no absolute cap the remaining percentage now falls back to the percentage-derived value (full/100% when 0% used). ([#3580](https://github.com/diegosouzapw/OmniRoute/issues/3580))
+- **docs(discovery):** mark `DISCOVERY_TOOL_DESIGN.md`'s API Endpoints table with an explicit "⚠️ Not yet implemented — Phase 2" banner — the discovery routes are a design proposal (Phase-1 stub only), and the banner makes clear the `KNOWN_STALE_DOC_REFS` gate suppression is intentional, not stale drift. ([#3498](https://github.com/diegosouzapw/OmniRoute/issues/3498))
+- **fix(agent-bridge):** add the missing `POST /api/tools/agent-bridge/upstream-ca/test` route — the UpstreamCaField "Test" button POSTed to it but it didn't exist (404). The new validate-only route checks the CA file exists and is a parseable PEM certificate (returns the subject/expiry) **without** persisting the path or activating it; it inherits the `/api/tools/agent-bridge/` LOCAL_ONLY classification. ([#3488](https://github.com/diegosouzapw/OmniRoute/issues/3488))
+- **fix(gamification):** the dashboard Profile page no longer hits three 404s — added the missing `GET /api/gamification/{level,badges,badges/earned}` routes (management-scoped). The page is operator-wide (no `apiKeyId`), so `level`/`badges/earned` aggregate across all keys (with an optional `?apiKeyId` for a single key), and `badges` seeds the built-in catalog first (idempotent) so the grid is populated even on installs that never seeded it (see #3472). ([#3484](https://github.com/diegosouzapw/OmniRoute/issues/3484))
+- **security(oauth):** migrate the five public OAuth client_ids (Claude, Codex, Qwen, Kimi, GitHub Copilot — 9 server-side call-sites in `providerRegistry.ts` + `oauth.ts`) from string literals to `resolvePublicCred()` (Hard Rule #11), matching the existing Gemini/Antigravity pattern. The values decode byte-for-byte to the same public client_ids (env overrides still win), so OAuth flows are unchanged; the `check-public-creds` allowlist is now empty. The browser-bundled `codexDeviceFlow.ts` copy stays a literal by necessity (it cannot import `open-sse`). ([#3493](https://github.com/diegosouzapw/OmniRoute/issues/3493))
+- **fix(mcp):** `omniroute --mcp` no longer crashes on npm installs with `ERR_MODULE_NOT_FOUND` (e.g. `src/lib/combos/steps.ts`) — the MCP server runs from raw TypeScript and imports across `src/` + `open-sse/`, but the published `files` allowlist only shipped a handful of cherry-picked paths, so the transitive closure (~400 files) was absent from the tarball. `files` now ships the backend source the MCP server needs (`open-sse/` + `src/{domain,lib,mitm,server,shared,sse,types}/`, excluding the `src/app` UI), and a new regression test computes the MCP import closure and fails if any reachable source file is not covered by `files`. ([#3578](https://github.com/diegosouzapw/OmniRoute/issues/3578))
+- **fix(api):** `API_REFERENCE.md` no longer documents a non-existent `/api/guardrails*` / `/api/shadow*` surface (doc-fiction flagged by `check-docs-symbols`, frozen in `KNOWN_STALE_DOC_REFS`). The guardrail pipeline is real (`src/lib/guardrails`), so the two routes that map to actual behavior are now implemented — `GET /api/guardrails` (list the registered guardrails + status) and `POST /api/guardrails/test` (dry-run the pre-call pipeline over a sample input), both management-scoped — while the fictional `enable`/`disable`/`logs` rows and the entire `/api/shadow*` table (shadow A-B comparison is combo-config + `/api/combos/metrics`) were removed from the doc and dropped from the allowlist. ([#3496](https://github.com/diegosouzapw/OmniRoute/issues/3496))
+- **fix(agent-bridge):** the MITM "Start" button no longer reports a misleading "port 443 may be in use" for every failure cause — `startMitm()` only matched the EADDRINUSE stderr line and always threw the port-443 message, so a missing `ROUTER_API_KEY` or an `EACCES` permission error sent users debugging the wrong thing. The startup watcher now buffers the MITM child's stderr and `interpretMitmStartupError()` maps the real `server.cjs` `❌` cause (port-in-use / permission-denied / missing API key / any other diagnostic line) into the surfaced error; with no captured output it stays generic instead of guessing port 443. ([#3606](https://github.com/diegosouzapw/OmniRoute/issues/3606))
+- **fix(oauth):** Kiro "Import Token" no longer reports a bare `Internal server error` that hides the real cause — the import validates/refreshes the pasted refresh token against AWS, and the catch returned a generic 500 string, so an `invalid_grant`, an expired token, or a region mismatch all surfaced identically in the dashboard. The import error now carries the sanitized upstream cause via `sanitizeErrorMessage()` (Hard Rule #12 — no stack, no secrets), keeping the same `{ error: <string> }` response shape, and still falls back to the generic message when there is nothing to report. ([#3589](https://github.com/diegosouzapw/OmniRoute/issues/3589))
+- **fix(antigravity):** the Antigravity/agy Gemini 3.5 Flash catalog now exposes clean public tier IDs (`gemini-3.5-flash-low`/`-medium`/`-high`, matching Antigravity 2.0.4's Low/Medium/High selector) and maps them to the live upstream IDs at the executor boundary, instead of the old confusing `-preview`/`-agent` names. Antigravity model-id normalization moved out of the global model resolver into the executor so client-visible IDs are no longer rewritten before account/credential routing and logging. (Maintainer follow-up: kept `gemini-3.5-flash-preview` as a hidden backward-compat alias routing to the High tier so saved combos/configs keep working; live-validated the tier set via the `agy` CLI catalog.) ([#3603](https://github.com/diegosouzapw/OmniRoute/pull/3603) — thanks @dhaern)
+- **fix(usage):** Antigravity/agy Provider Limits now report accurate consumption — `retrieveUserQuota` (live usage) is preferred over the `fetchAvailableModels` catalog view (which keeps reporting full buckets after real usage), with a local `usage_history` fallback for buckets that are only catalog-visible; cached entries are sanitized so retired upstream IDs are not re-exposed, and a deduplicated post-usage refresh keeps the dashboard fresh after each request. (Maintainer follow-up: the post-usage refresh is decoupled through a lightweight `usageEvents` bus so `usageHistory` no longer imports `providerLimits`/the executors graph, keeping the `typecheck:core` surface stable.) ([#3604](https://github.com/diegosouzapw/OmniRoute/pull/3604) — thanks @dhaern)
+- **fix(gemini):** textual reasoning wrappers emitted as assistant prose (`<think>`/`<thinking>`/`<thought>`/`<internal_thought>`, including malformed/open tags like `<thought\n…` before a tool call) are now routed to `reasoning_content` instead of leaking into visible `content`, in both the non-streaming sanitizer and the Gemini streaming translator (with split-chunk buffering so a tag fragmented across SSE chunks stays hidden). Structured tool calls and the existing textual tool-call conversion are preserved. ([#3605](https://github.com/diegosouzapw/OmniRoute/pull/3605) — thanks @dhaern)
+- **fix(gemini):** a signed native `functionCall` arriving while a textual reasoning wrapper opened in an earlier streaming chunk is still buffered now flushes that buffered reasoning to `reasoning_content` before the tool call, instead of silently discarding it. (Pre-release `/review-reviews` finding.)
+- **fix(api):** `/v1/completions` now drops a stale upstream `content-length` on the SSE branch too (the JSON branch already did) — re-serialization changes the byte length, so a buffered SSE body could otherwise advertise the pre-rewrite length and truncate/hang the client. (Pre-release `/review-reviews` finding.)
+
+---
+
+## [3.8.20] — 2026-06-10
+
+### ✨ New Features
+
+- **feat(providers):** add Claude Fable 5 (`claude-fable-5`) — wires the new flagship model across the full pipeline: `cc` and `kiro` provider registries (1M context, 128k output), pricing at $15/$75 per 1M tokens, model spec (adaptive thinking, vision, tool use), fast mode, 1M-context beta header, fallback chain (`claude-fable-5 → claude-opus-4-8 → claude-opus-4-7 → claude-sonnet-4-6`), and cost data. ([#3524](https://github.com/diegosouzapw/OmniRoute/pull/3524) — thanks @ggiak)
+- **feat(resilience):** add global provider cooldown tracking to prevent combo re-walking — after a provider fails in a combo request, subsequent requests skip it for a configurable exponential backoff (default 5s min, 5min max, doubling per failure), reducing wasted time on known-failing providers. Configurable and opt-out via Settings → Resilience. ([#3556](https://github.com/diegosouzapw/OmniRoute/pull/3556) — thanks @pizzav-xyz)
+- **feat(resilience):** expose provider breaker degradation threshold setting — the consecutive-failure count before a provider enters the DEGRADED state is now configurable in Settings → Resilience alongside the existing open/half-open thresholds. ([#3535](https://github.com/diegosouzapw/OmniRoute/pull/3535) — thanks @rdself)
+
+### 🔧 Bug Fixes
+
+- **fix(translator):** scope the Gemini `thoughtSignature` bypass to the Antigravity/CLI path and unwrap array-shaped Gemini error bodies — signature-less historical tool calls on Antigravity/CLI are emitted as native parts carrying the `skip_thought_signature_validator` sentinel (preventing upstream 400s), while the standard Gemini direct path keeps its existing text/context representation untouched. ([#3560](https://github.com/diegosouzapw/OmniRoute/issues/3560) — thanks @oyi77 and @Six7Day via [#3414](https://github.com/diegosouzapw/OmniRoute/pull/3414))
+
+- **fix(routing):** combo model substitution no longer forwards a client `thinking:{type:"disabled"}` to a target model that rejects it — when a combo/route swaps the upstream model (e.g. `claude-opus-4-8` → `claude-fable-5`), OmniRoute now strips the now-invalid `thinking.type:"disabled"` for models flagged `rejectsThinkingDisabled` (Fable 5 defaults to adaptive and rejects it), preventing the upstream 400 that silently broke Claude Code's internal title/name-generation calls. Models that accept `disabled` (opus/sonnet) are untouched. ([#3554](https://github.com/diegosouzapw/OmniRoute/issues/3554))
+- **fix(usage):** the budget dashboard can now save a budget with some limit fields left empty and clear all limits — `setBudgetSchema` used `.positive()` (rejecting the `0` the form sends for blank fields) plus a superRefine requiring at least one limit `> 0`, so saving with one field filled 400'd and clearing all limits was impossible. Limits now accept `0` (= "no limit for this period"; enforcement only kicks in above 0) and the cross-field minimum was removed; negatives are still rejected. ([#3537](https://github.com/diegosouzapw/OmniRoute/issues/3537))
+- **fix(gamification):** badge-unlock events no longer re-fire on every request — the "already unlocked?" guard used `getBadges()`, which INNER-JOINs `badge_definitions` (empty until seeded), so it always reported "not earned" and re-emitted `events.badge_unlocked` per request. Added a `hasBadge()` helper that reads `user_badges` directly, so dedup is correct regardless of whether definitions are seeded. ([#3472](https://github.com/diegosouzapw/OmniRoute/issues/3472))
+- **fix(routing):** the `auto` model keyword now works on the Codex `/v1/responses` path — `resolveResponsesApiModel` rewrote the bare `auto` keyword to `codex/auto`, which ChatGPT rejects (`The 'auto' model is not supported when using Codex with a ChatGPT account`). `auto` (OmniRoute's zero-config auto-routing keyword) now passes through untouched so combo routing handles it. ([#3509](https://github.com/diegosouzapw/OmniRoute/issues/3509))
+- **fix(cli-tools):** saving the OpenCode/CLI tool config no longer 400s in cloud mode — every CLI tool card posts `apiKey: null` (the real key is resolved server-side from `keyId`), but `guideSettingsSaveSchema` used `z.string().optional()`, which rejects `null`. The schema now normalizes `null` → `undefined`, so the save succeeds and the `keyId`/default path is used. ([#3552](https://github.com/diegosouzapw/OmniRoute/issues/3552))
+- **fix(catalog):** PublicAI is no longer miscatalogued as keyless/free — it requires an API key (registry `authType:"apikey"`; signup grants a one-time credit, then it bills). The three PublicAI models moved from `freeType:"keyless"` (which could pick them into the no-auth pool and dispatch with no `Authorization` header) to `"one-time-initial"`, and the provider's `hasFree` flag is now `false` — matching `freeTierCatalog.ts`, which already excluded publicai. ([#3558](https://github.com/diegosouzapw/OmniRoute/issues/3558))
+- **fix(gemini-web):** a missing Playwright Chromium browser no longer loops and trips the provider breaker — when the browser binary is not installed, `chromium.launch()` threw an error surfaced as a retryable **500**, so accountFallback marked the account unavailable and retry-looped. It is now classified as a host/config problem and returns **503** with an actionable message (`npx playwright install chromium`) and the `X-Omni-Fallback-Hint: connection_cooldown` header, which skips the provider circuit breaker and applies a short non-exponential cooldown. ([#3516](https://github.com/diegosouzapw/OmniRoute/issues/3516))
+- **fix(proxy):** the SOCKS5 proxy option now follows the runtime `ENABLE_SOCKS5_PROXY` env instead of the build-time `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` — Next.js inlines `NEXT_PUBLIC_*` at build time, so a prebuilt Docker image ignored a runtime setting and the SOCKS5 type stayed hidden. The proxy modal now reads `socks5Enabled` from `GET /api/settings/proxies` (server-side `ENABLE_SOCKS5_PROXY`), with the build-time value kept only as a static-deploy fallback. ([#3508](https://github.com/diegosouzapw/OmniRoute/issues/3508))
+- **fix(playground):** the playground model selector now lists models from custom-endpoint (OpenAI/Anthropic-compatible) providers — it filtered `/v1/models` by the provider's connection id, but the catalog emits compatible-provider models under the node's custom prefix (`prefix/model`), so the list came up empty ("None"/"-"). The selector now filters by the node prefix (exposed additively as `modelPrefix` on provider options; the connection id is unchanged, so translator send/translate and connection lookups are unaffected). ([#3505](https://github.com/diegosouzapw/OmniRoute/issues/3505))
+- **fix(usage):** the Kiro quota card no longer renders a blank when the account returns no usage breakdown — `getKiroUsage` returned `quotas:{}` for a successful GetUsageLimits response without a `usageBreakdownList` (observed with some AWS IAM / Builder ID accounts), which the dashboard showed as an unexplained empty card. It now returns an informative message (surfaced via the card's connection-message path). ([#3506](https://github.com/diegosouzapw/OmniRoute/issues/3506))
+- **fix(security):** route raw `err.message` through `sanitizeErrorMessage()` in five web executors (`adapta-web`, `deepseek-web`, `perplexity-web`, `qoder`, `veoaifree-web`) and the embeddings + search handlers (Hard Rule #12) — these built error response bodies from the raw upstream/exception message, which could leak internal detail. ([#3494](https://github.com/diegosouzapw/OmniRoute/issues/3494), [#3495](https://github.com/diegosouzapw/OmniRoute/issues/3495))
+- **fix(dashboard):** correct two dashboard fetches that hit non-existent routes (404) — `CustomHostsManager` called `/api/tools/traffic-inspector/custom-hosts` (the real route is `/hosts`), and `FeatureFlagsGrid`'s post-restart liveness probe called `/api/health` (the real lightweight endpoint is `/api/health/ping`). ([#3486](https://github.com/diegosouzapw/OmniRoute/issues/3486), [#3487](https://github.com/diegosouzapw/OmniRoute/issues/3487))
+- **chore(providers):** remove the dead `krutrim` registry entry — it was half-registered (present in `providerRegistry.ts` with a baseUrl + one model, but absent from `providers.ts`, with no executor/translator/OAuth), so it was never selectable. Dropped its `ProviderIcon` entry and the `KNOWN_REGISTRY_ONLY` exception. ([#3483](https://github.com/diegosouzapw/OmniRoute/issues/3483))
+- **docs(api):** fix the agent-bridge per-agent state route in `openapi.yaml` and `AGENTBRIDGE.md` — both documented `/api/tools/agent-bridge/agents/{id}/state`, which has no route; corrected to the real per-agent `/api/tools/agent-bridge/agents/{id}` (global state remains `/api/tools/agent-bridge/state`). ([#3489](https://github.com/diegosouzapw/OmniRoute/issues/3489))
+- **docs(api):** correct `API_REFERENCE.md` endpoints that documented non-existent routes — skills (`PUT /api/skills/[id]`, `POST`/`GET /api/skills/executions`), plugins (`[id]`→`[name]`, `activate`/`deactivate`), ACP (`DELETE`/`POST /api/acp/agents` via `?id`/`{action:"refresh"}`), cache (`DELETE /api/cache/reasoning`, `/api/cache/entries`), and removed the fabricated `/api/admin/circuit-breaker`, `/api/admin/rate-limits`, and `/api/system-info` (admin only exposes `/concurrency`). ([#3497](https://github.com/diegosouzapw/OmniRoute/issues/3497))
+- **fix(executor):** strip provider prefix from versioned built-in tool model field — Anthropic rejects `tools[N].model: "cc/claude-opus-4-8"` from Claude Code's `advisor_20260301` and similar versioned built-in tools; the native Claude OAuth execute path now strips any provider prefix from `model` on tools whose name matches `name_YYYYMMDD`. ([#3532](https://github.com/diegosouzapw/OmniRoute/pull/3532) — thanks @ggiak)
+- **fix(dashboard):** handle DEGRADED and unknown provider breaker states on the Runtime page — an unrecognised breaker state (e.g. DEGRADED) caused a crash because the styling map had no entry for it; now falls back to a neutral style so the page never throws on unknown states. ([#3533](https://github.com/diegosouzapw/OmniRoute/pull/3533) — thanks @rdself)
+- **fix(usage):** make opencode-go quota fetcher fail-open instead of throwing 500 — the quota API rejects chat API keys with a JSON-401 body even though the same key works for chat; previously this threw and crashed the dashboard with a red error banner. It now returns an informative message and keeps rendering like other connection-message cases. ([#3522](https://github.com/diegosouzapw/OmniRoute/pull/3522) — thanks @wilsonicdev)
+- **fix(translator):** map the Codex `local_shell` tool type — `local_shell` was absent from the translator's tool-type map, causing it to fall through as an unknown type; it is now forwarded correctly to the upstream. ([#3534](https://github.com/diegosouzapw/OmniRoute/pull/3534) — thanks @kamaka)
+- **fix(images):** prefer bare combo names over built-in image model aliases — a user combo named `gpt-image-2` can now shadow the native OpenAI alias so image requests route through the combo; provider-qualified IDs like `openai/gpt-image-2` still resolve via the built-in path. ([#3527](https://github.com/diegosouzapw/OmniRoute/pull/3527) — thanks @AveryanAlex)
+- **fix(translator):** fix OpenAI→Gemini translation of historical tool calls — tool results from earlier turns were being converted to text, causing Gemini to pattern-match the response as prose rather than structured content; they now use the native Gemini `functionResponse` part format. ([#3569](https://github.com/diegosouzapw/OmniRoute/pull/3569) — thanks @hartmark)
+- **fix(plugins):** forward plugin lifecycle hooks (`onInstall`, `onActivate`, `onDeactivate`, `onUninstall`) via IPC and wrap `onDeactivate`/`onUninstall` in try/catch so a buggy plugin handler can no longer brick teardown; also removes redundant `RegExp()` wrappers in `accountFallback.ts` and fixes indentation in `requestLogger.ts`. ([#3562](https://github.com/diegosouzapw/OmniRoute/pull/3562) — thanks @oyi77)
+- **fix(auto-update):** use a stable PROJECT_ROOT walker instead of frozen `process.cwd()` — `resolveProjectRoot` now walks up from `__dirname` to find the nearest directory containing `package.json` or `.git` (bounded at 16 levels), preventing ENOENT errors when the working directory is not the project root. ([#3561](https://github.com/diegosouzapw/OmniRoute/pull/3561) — thanks @oyi77 / @ViFigueiredo via [#3423](https://github.com/diegosouzapw/OmniRoute/pull/3423))
+
+---
+
+## [3.8.19] — 2026-06-09
+
+> Focused quality-infrastructure release: the complete **quality-gate ratchet + anti-hallucination guardrail system** (Phases 0–6 + fast-tracked 6A.1/6A.2). No external PRs were taken this cycle by design — community PRs carry over to the next cycle.
+
+### ✨ New Features
+
+- **feat(quality):** quality-gate ratchet + anti-hallucination/rule-enforcement guardrails (Phases 0–6) — generic multi-metric ratchet engine (`quality-baseline.json` + collector + comparator, regression-only) and ~18 deterministic gates wired into CI: provider-consistency, dashboard `fetch()`→route and OpenAPI/docs→route resolution (anti-hallucination), dependency allowlist (anti-slopsquatting), file-size/duplication/complexity ratchets (frozen debt only shrinks), anti test-masking (assert-removal/tautology detection on PR diffs), error-helper (Hard Rule #12), public-creds (Rule #11), route-guard membership (Rules #15/#17), db-rules (Rules #2/#5), known-symbols (executors/strategies/translators), migration numbering. Re-enabled the cheap pre-commit hook, tiered `npm audit`, reconciled the CI coverage gate (40→60) and wired 3 orphaned contract gates. ([#3471](https://github.com/diegosouzapw/OmniRoute/pull/3471) — thanks @diegosouzapw)
+- **feat(quality):** test-discovery gate + 135 orphan tests re-wired + vitest in CI (fast-tracked Phase 6A.1/6A.2) — new `check:test-discovery` proves every `*.test.ts|tsx` is collected by a runner that actually executes (15 collectors with textual drift-check; orphans frozen in a shrink-only baseline). Found **195 orphan test files** (incl. `authz/routeGuard.test.ts` guarding Rules #15/#17 — already rotten); 135 re-wired into the node runner via explicit-braces recursive globs across all scripts + 4 CI call sites; the remaining 60 are categorized debt. New `test-vitest` CI job: `test:vitest` blocking (146/146), `test:vitest:ui` informational (14 pre-existing UI-drift fails, triage 2026-06-16). ([#3536](https://github.com/diegosouzapw/OmniRoute/pull/3536) — thanks @diegosouzapw)
+
+### 🔧 Bug Fixes
+
+- **fix(authz):** restored the missing `BYPASS_PREFIX_NOT_ALLOWED` schema guard (Hard Rules #15/#17) — the zod refine documented as layer-1 in `routeGuard.ts` was absent from the live `settingsSchemas.ts`, so `PATCH /api/settings` accepted spawn-capable prefixes (e.g. `/api/cli-tools/runtime/`) into the manage-scope bypass list (the layer-2 runtime predicate still refused to honour them). Surfaced by re-wired orphan tests AC-8/AC-10c, which now stand as the permanent regression guard. ([#3536](https://github.com/diegosouzapw/OmniRoute/pull/3536) — thanks @diegosouzapw)
+- **fix(db):** `closeDbInstance()`/`resetDbInstance()` now fire the `stateReset.ts` module-state resetters (previously only backup-restore did) — `apiKeys.ts` kept a process-level schema memo across a recreated DB, so the stale re-prepare exploded with `no such column: is_active` and clients received **503 instead of 403** for an invalid bearer; the same path hit production when restoring an older backup snapshot. Includes a dedicated regression test; a test that had accommodated the buggy 503 now asserts the deterministic 403. ([#3536](https://github.com/diegosouzapw/OmniRoute/pull/3536) — thanks @diegosouzapw)
+
+### 🔒 Security
+
+- **fix(security):** block the cloud-metadata SSRF pivot in the cli-tools catalog fetch (CodeQL `js/request-forgery`, **critical**) — `fetchOmniRouteCatalog()` built its `/v1/models` URL from a user-controlled `baseUrl` and fetched it. Since the legitimate target is the user's own OmniRoute (loopback), the public-only guard can't apply; `assertSafeCatalogUrl()` now blocks the cloud-metadata/link-local pivot (`169.254.169.254`, `metadata.google.internal`, …) unconditionally, plus non-http(s) protocols and embedded credentials, and the request fetches the re-parsed (taint-severed) URL. Loopback and public OmniRoute Cloud targets stay allowed. ([#3544](https://github.com/diegosouzapw/OmniRoute/pull/3544) — thanks @diegosouzapw)
+
+### 📝 Maintenance
+
+- **docs(quality):** Phase 6A critical-audit plan + Phase 7 community-tooling additions, both stored with an activation gate of **2026-06-16** — 6A: stale-allowlist enforcement, ratchet `--require-tighten`, gate scope expansions, remaining orphan/UI-suite triage; Phase 7 additions: gitleaks (Betterleaks noted), actionlint + zizmor, SPDX license compliance. ([#3530](https://github.com/diegosouzapw/OmniRoute/pull/3530) — thanks @diegosouzapw)
+- **chore(quality):** conscious, documented re-baselines so the quality-gate debuts holding the REAL published line — file-size frozen at current sizes for 9 files that grew in the v3.8.18 era (RequestLoggerV2 +281, stream +101, combo +73, chatCore +45, …) and `eslintWarnings` 3482→3501 (the published v3.8.18 tag already measured 3501; this cycle is neutral). Driving both down is Phase 6A work. ([#3538](https://github.com/diegosouzapw/OmniRoute/pull/3538) — thanks @diegosouzapw)
+- **chore(release):** open the v3.8.19 development cycle (version bump + electron lockfile sync) and ignore generated yt-downloader artifacts. (thanks @diegosouzapw)
+- **test:** release-gate stabilization — the re-wired suites + the debuting CI gates surfaced and fixed 6 latent test defects: 2 suites depended on the dev machine's configured password (now hermetic), the breaker reset-timeout test ran on a 5ms margin, the bypass-prefix schema test consecrated the pre-#3536 bug, the chatcore upstream-timeout test had a structurally-broken pending-detail predicate (tested `.providerRequest` on an array — never passed isolated, even at the published v3.8.18 tag), and internal planning docs were excluded from the docs-symbols gate. Coverage floors re-baselined to the honest post-re-wire denominator (78.4% measured: previously-never-imported modules now count). (thanks @diegosouzapw)
+
+---
+
+## [3.8.18] — 2026-06-09
+
+### ✨ New Features
+
+- **feat(ui):** unified Active + Finished requests into a single view — the dashboard now shows in-flight and completed requests in one list with deep-linking, live streaming detail, and a dedicated `/api/logs/[id]` detail route; pending requests are tracked per connection and finalized as they complete. ([#3401](https://github.com/diegosouzapw/OmniRoute/pull/3401) — thanks @hartmark / @diegosouzapw)
+- **feat(plugins):** plugin lifecycle hooks + theme-manager example — adds `onInstall`/`onActivate`/`onDeactivate`/`onUninstall` lifecycle events dispatched by the plugin manager, thins `index.ts` to a backward-compatible re-export shim over `hooks.ts`, and ships theme-manager + request-logger example plugins. ([#3473](https://github.com/diegosouzapw/OmniRoute/pull/3473) — thanks @oyi77 / @diegosouzapw)
+- **feat(browserPool):** Playwright proxy resolved from the proxy registry — browser-backed providers (claude-web/gemini-web) now route through the configured per-provider/global proxy instead of connecting directly, matching how OAuth/token-refresh already honor `resolveProxyForProvider` (closes the VPS IP-rate-limit gap for the browser path). Fully additive with graceful degradation. ([#3492](https://github.com/diegosouzapw/OmniRoute/pull/3492) — thanks @borodulin)
+
+### 🔧 Bug Fixes
+
+- **fix(executor):** Llama / OpenAI-compat base URL normalization — a `baseURL` without a path (e.g. `llama.example.foo`) or with a non-`/v1` path (e.g. `bar.example.com/foo`) now correctly gets `/v1/chat/completions` appended, fixing the 404 on message sends while `GET /model` still worked. ([#3519](https://github.com/diegosouzapw/OmniRoute/pull/3519) — thanks @hartmark)
+- **fix(sse):** empty-choices chunks without usage are dropped instead of injecting retry text — a streamed chunk carrying an empty `choices` array and no `usage` is now silently skipped rather than emitting placeholder retry text into the stream, eliminating spurious content for clients that send such keepalive-style frames. ([#3513](https://github.com/diegosouzapw/OmniRoute/pull/3513) — thanks @diegosouzapw)
+- **fix(types):** restored a clean `typecheck:core` — typed `getPendingRequests()` to its real shape (`Record<string, Record<string, number>>`) so the unified-requests view (#3401) no longer treats pending counts as `unknown`, cast the `streamChunks` log payload to its declared type, and aligned `preScreenTargets` (#3169) to the canonical `IsModelAvailable` signature (sync-or-async, normalized via `Promise.resolve`). (thanks @diegosouzapw)
+- **fix(opencode-plugin):** repaired the corrupted `index.ts` that broke the npm `publish-opencode-plugin` build (introduced by the #3435 branch) — removed two duplicated code blocks (apiFormat + debug-logging), dropped the local `normaliseFreeLabel` superseded by the `naming.ts` extraction, fixed an undefined `sdkBaseURL` reference, declared the missing `startupDebug` / `logLevel` feature-schema fields, and fixed `shortProviderLabel` dropping the prefix on a long displayName with no alias. Plugin now builds (DTS clean) with all 254 tests green. ([#3435](https://github.com/diegosouzapw/OmniRoute/pull/3435) — thanks @diegosouzapw)
+- **fix(catalog):** Codex CLI model-catalog refresh no longer errors — `GET /v1/models` now returns a top-level `models: []` array for Codex clients (detected via the `originator` / `user-agent` = `codex_*` headers it sends on `GET /v1/models?client_version=...`), so `codex_models_manager` stops failing to decode the OpenAI-standard response and no longer logs `failed to refresh available models` on every startup. The array is intentionally empty: Codex replaces its built-in per-model agent prompt (`base_instructions`, ~21k chars) with whatever a populated entry carries for the selected model, so emitting our catalog would break Codex's agent behaviour — an empty list keeps Codex on its built-in model info (same inference as before, minus the error). Non-Codex OpenAI clients receive the unchanged `{object,data}` response. ([#3481](https://github.com/diegosouzapw/OmniRoute/pull/3481) — thanks @diegosouzapw)
+- **fix(provider):** Cursor's Responses-API-shaped bodies on `/chat/completions` are detected and handled — a body with `input` but no `messages` is now classified as `openai-responses` (instead of forcing `openai` and building from undefined `messages` → upstream 400); standard OpenAI clients are unaffected by the `messages===undefined` guard. ([#3490](https://github.com/diegosouzapw/OmniRoute/pull/3490) — thanks @borodulin)
+- **fix(sse):** numeric provider IDs normalized to strings across 4 more surfaces — extends #3427 to the Responses-API SSE passthrough (`response_id`/`item_id`/`call_id`), the buffered/flush path in `stream.ts`, the dedup-key builders, and `sseParser.ts`, preventing `undefined` lookups when IDs arrive as numbers. ([#3451](https://github.com/diegosouzapw/OmniRoute/pull/3451) — thanks @disafronov)
+- **fix(theoldllm):** `X-Request-Token` generated server-side, dropping the Playwright dependency — replicates the site's client `rie()` token (djb2 hash + `oldllm-client-2026` seed + UA prefix + 8-hex `crypto.randomUUID` suffix) directly, so The Old LLM no longer needs a headless browser to mint tokens. ([#3491](https://github.com/diegosouzapw/OmniRoute/pull/3491) — thanks @borodulin / @diegosouzapw)
+- **fix(combo):** parallel pre-screen + circuit-breaker fast-exit for priority combos — provider profiles and model availability for all targets are pre-screened concurrently (max 5), and targets whose circuit breaker is OPEN are skipped immediately, reducing first-token latency on multi-target priority combos. ([#3169](https://github.com/diegosouzapw/OmniRoute/pull/3169) — thanks @pizzav-xyz)
+- **fix(authz):** URL-tokenized client endpoints (`/api/v1/vscode/<key>/...`) authenticate again when the caller sends its own non-OmniRoute `Authorization` header — a non-`Bearer <token>` header (e.g. VS Code Copilot's own, or an empty `Bearer `) no longer short-circuits auth; it falls through to the path-scoped URL token (still validated downstream), instead of 401'ing under `REQUIRE_API_KEY=true`. ([#3504](https://github.com/diegosouzapw/OmniRoute/pull/3504) — thanks @zhiru / @diegosouzapw)
+- **fix(playground):** the dashboard provider Test playground works under `REQUIRE_API_KEY=true` — it previously sent the **masked** key (`sk-xxxx****yyyy`) as a bearer (always invalid → 401). It now authenticates via the dashboard session and sends only the key **id** (`x-omniroute-playground-key-id`); the gateway resolves the secret server-side, honored **only** for an authenticated session and never putting the key secret on the wire. ([#3503](https://github.com/diegosouzapw/OmniRoute/pull/3503) — thanks @zhiru / @diegosouzapw)
+
+### 📝 Maintenance
+
+- **feat(docs):** doc-accuracy gate — new `npm run check:fabricated-docs` (`scripts/check/check-fabricated-docs.mjs`) indexes the codebase (api routes, env vars, CLI commands) and flags API-path/env-var/CLI/hook/file-ref claims in `docs/**` + `AGENTS.md` that don't exist in source (soft-fail by default, `--strict` for CI; wired into `check:docs-all`). Also refreshes the AGENTS.md live counts against source. ([#3510](https://github.com/diegosouzapw/OmniRoute/pull/3510) — thanks @oyi77)
+- **chore:** ignore local quality reports and prompt artifacts (`quality-metrics.json`, `PLANO-/RELATORIO-QUALITY-GATES.md`, stray prompt `.txt` files) so they no longer surface in `git status`. (thanks @diegosouzapw)
+
+### 🔒 Security
+
+- **fix(opencode-plugin):** bounded the regex quantifiers in `normaliseFreeLabel` to close a polynomial-ReDoS (CodeQL `js/polynomial-redos`) — an unbounded `\s*` before an anchored `\s*$` allowed O(n²) backtracking on attacker-influenced provider/model display names; bounded to `{0,8}`/`{1,8}`. (thanks @diegosouzapw)
+
+---
+
+## [3.8.17] — 2026-06-09
+
+### ✨ New Features
+
+- **feat(providers):** LMArena provider — routes requests to the LMArena battle platform via the new `lmarena` executor; supports streaming chat completions. ([#3421](https://github.com/diegosouzapw/OmniRoute/pull/3421) — thanks @oyi77)
+- **feat(providers):** ZenMux provider — adds the `zenmux` executor for ZenMux's OpenAI-compatible endpoint with streaming support. ([#3429](https://github.com/diegosouzapw/OmniRoute/pull/3429) — thanks @oyi77)
+- **feat(providers):** Gemini Business provider — adds the `gemini-business` executor (Phase 2C of the Google provider expansion), enabling Gemini models via Google Workspace accounts. ([#3436](https://github.com/diegosouzapw/OmniRoute/pull/3436) — thanks @oyi77)
+- **feat(plugin+api):** auto-combos API + free model quota display — new `GET /api/combos/auto` endpoint lists dynamically scored combos; provider pages now surface free-tier quotas inline; MCP-plugin surface extended to match. ([#3435](https://github.com/diegosouzapw/OmniRoute/pull/3435) — thanks @mrmm)
+- **feat(opencode-plugin):** per-prefix API format selection, debug logging, and free-label normaliser — three backports from the mrmm fork: each route prefix can specify its own wire format (OpenAI / Anthropic / Gemini), structured debug output is toggled via env var, and free-tier labels are normalized across providers. ([#3420](https://github.com/diegosouzapw/OmniRoute/pull/3420) — thanks @herjarsa)
+- **feat(connections):** connection pagination, health filter, batch-delete confirmation, and custom banned keywords — the provider connections table is now paginated; a health-state filter lets operators show only healthy/degraded/failed connections; multi-select + confirm dialog for bulk deletes; per-connection keyword denylist for content safety. ([#3454](https://github.com/diegosouzapw/OmniRoute/pull/3454) — thanks @sdfsdfw2)
+- **feat(settings):** Endpoint Token Saver visibility toggle — operators can now show or hide the Token Saver widget on the endpoint page from Settings → Appearance. ([#3461](https://github.com/diegosouzapw/OmniRoute/pull/3461) — thanks @rdself)
+- **feat(catalog):** model catalog name feature flag — a new feature flag controls whether the catalog exposes provider-prefixed model names, letting deployments opt into the legacy bare-name format for downstream tooling compatibility. ([#3464](https://github.com/diegosouzapw/OmniRoute/pull/3464) — thanks @rdself)
+
+### 🔧 Bug Fixes
+
+- **fix(translator):** Vertex AI tool calls no longer fail with `400 Unknown name "id"` — the OpenAI-style `id` field is stripped from `functionCall`/`functionResponse` parts for `vertex`/`vertex-partner`; the public Gemini API still receives `id` as required for Gemini 3+ signature matching. ([#3457](https://github.com/diegosouzapw/OmniRoute/pull/3457) — thanks @nullbytef0x / @diegosouzapw)
+- **fix(claude):** Claude Code `claude-opus-4-8` tool calls no longer break with `tool call could not be parsed` — OmniRoute no longer force-injects `interleaved-thinking` / `advanced-tool-use` / `effort` beta flags the client never negotiated; clients sending their own `anthropic-beta` header control those betas themselves. ([#3458](https://github.com/diegosouzapw/OmniRoute/pull/3458) — thanks @Forcerecon / @diegosouzapw)
+- **fix(catalog):** imported/custom models on no-auth providers (e.g. The Old LLM) now appear in `GET /api/v1/models` and the Playground model selector — the eligibility gate required a DB connection row which no-auth providers never have, silently dropping every imported model for them. ([#3463](https://github.com/diegosouzapw/OmniRoute/pull/3463) — thanks @tjengbudi / @diegosouzapw)
+- **fix(browser):** optional `cloakbrowser` import no longer causes bundle errors when the package is absent — the import is now wrapped in a dynamic require so the build succeeds on environments that don't install the optional dep. ([#3460](https://github.com/diegosouzapw/OmniRoute/pull/3460) — thanks @rdself)
+- **fix(claude-web):** claude-web session handling cleanup — corrects an edge case where session cookies were not properly refreshed after a Turnstile challenge, and removes stale wrapper code left over from the provider split. ([#3449](https://github.com/diegosouzapw/OmniRoute/pull/3449) — thanks @androw)
+- **fix(analytics):** SQL named params are now scoped per query context — a shared params object was being mutated across concurrent analytics queries, causing `SQLITE_MISUSE: named parameter not found` errors under load. ([#3447](https://github.com/diegosouzapw/OmniRoute/pull/3447) — thanks @ReqX)
+- **fix(command-code):** chat endpoint reverted to `/alpha/generate` and model-sync discovery fixed — a prior refactor incorrectly targeted the wrong path, causing Command Code completions to silently 404; model listing now also resolves from the correct discovery endpoint. ([#3432](https://github.com/diegosouzapw/OmniRoute/pull/3432) — thanks @TapZe)
+- **fix(command-code):** CLI version header aligned to current Command Code release — the `X-Command-Code-Version` header value was pinned to a stale version string, causing upstream version-gated features to be rejected. ([#3462](https://github.com/diegosouzapw/OmniRoute/pull/3462) — thanks @hevener10)
+- **fix(sse):** provider IDs are normalized to strings before lookup — numeric provider IDs (e.g. from legacy DB rows) caused `undefined` lookups in the executor registry; all IDs are now coerced to string at the SSE entry point. ([#3427](https://github.com/diegosouzapw/OmniRoute/pull/3427) — thanks @disafronov)
+- **fix(stream):** textual tool-call slicing index mismatch resolved and `containsTextualToolCallMarker` deduplicated — two related bugs in the rolling-buffer parser caused partial tool-call chunks to be emitted twice or sliced from the wrong offset, producing garbled JSON in streamed tool responses. ([#3413](https://github.com/diegosouzapw/OmniRoute/pull/3413) — thanks @Ardem2025)
+- **fix(stream):** OpenAI usage-only chunks (empty `choices: []`) are now passed through instead of being dropped — some providers emit a trailing stats-only chunk after the last content delta; discarding it caused usage counters to be missing in logged responses. ([#3422](https://github.com/diegosouzapw/OmniRoute/pull/3422) — thanks @xz-dev)
+- **fix(translator):** empty-string `reasoning_content` replaced with placeholder on cache miss — `injectEmptyReasoningContentForToolCalls` pre-sets `reasoning_content=""` before the cache lookup; the old guard checked for `undefined`, never firing on miss and leaving `""` in place, which DeepSeek V4+ rejects with a 400. ([#3433](https://github.com/diegosouzapw/OmniRoute/pull/3433) — thanks @ViFigueiredo)
+- **fix(catalog):** combos auto-compute `context_length` for any provider-ID form — the context-length resolution only matched exact-string provider IDs, missing combos declared with a numeric or aliased ID; the lookup now normalizes before matching. ([#3417](https://github.com/diegosouzapw/OmniRoute/pull/3417) — thanks @herjarsa)
+- **fix(healthcheck):** container bridge network IP probed correctly — the healthcheck script was hard-coded to `localhost` which resolves to IPv6 `::1` inside some container runtimes; it now queries the bridge gateway IP so the probe succeeds on both bridge and host networking modes. ([#3434](https://github.com/diegosouzapw/OmniRoute/pull/3434) — thanks @naimo84)
+- **fix(publish):** onnxruntime CUDA binary removed from npm tarball — the native `.node` binary exceeded npm's 413 payload limit and was never needed at runtime (OmniRoute uses the CPU build); the pack policy now excludes the CUDA artifact. ([#3437](https://github.com/diegosouzapw/OmniRoute/pull/3437) — thanks @herjarsa)
+
+### 📝 Maintenance
+
+- **docs:** critical documentation gaps closed — new guides for ACP protocol, router strategies, compression, REST API reference, and updated AUTO-COMBO deep-dive; getting-started section added with Quick Start, Providers, Free Tiers, Auto-Combo, and Troubleshooting pages. ([#3438](https://github.com/diegosouzapw/OmniRoute/pull/3438) — thanks @oyi77)
+- **docs(opencode-plugin):** plugin README rewritten to lead with the why — positions the plugin as the recommended integration path over the legacy `@omniroute/opencode-provider` package, with migration guidance. ([#3418](https://github.com/diegosouzapw/OmniRoute/pull/3418) — thanks @herjarsa)
+- **docs(env):** `COMMAND_CODE_VERSION` override documented — environment variable added to `.env.example` and reference docs so operators can pin the CLI version header without a code change. ([#3462](https://github.com/diegosouzapw/OmniRoute/pull/3462) — thanks @hevener10)
+- **test(auto-combo):** same-provider connection identity assertion added — regression test covering the case where two connections for the same provider share an account ID, verifying the combo engine selects the correct one. ([#3378](https://github.com/diegosouzapw/OmniRoute/pull/3378) — thanks @oyi77)
+- **deps:** electron upgraded to 42.3.3; electron-builder to 26.15.2; electron-updater to 6.8.9; 4 development-group and 10 production-group packages bumped via Dependabot. ([#3441](https://github.com/diegosouzapw/OmniRoute/pull/3441) / [#3442](https://github.com/diegosouzapw/OmniRoute/pull/3442) / [#3443](https://github.com/diegosouzapw/OmniRoute/pull/3443) / [#3444](https://github.com/diegosouzapw/OmniRoute/pull/3444) / [#3445](https://github.com/diegosouzapw/OmniRoute/pull/3445) — thanks @diegosouzapw)
+- **chore(release):** v3.8.17 development cycle opened from `main`. (thanks @diegosouzapw)
+
+---
+
+## [3.8.16] — 2026-06-08
+
+### ✨ New Features
+
+- **feat(vision-bridge):** auto-routing to the fastest available vision model — when a request carries image content and the selected model does not support vision, OmniRoute now transparently delegates to the best-match vision-capable model instead of returning an error. ([#3377](https://github.com/diegosouzapw/OmniRoute/pull/3377) — thanks @herjarsa)
+- **feat(web-session):** web-session pool observability — new MCP tool `get_web_session_pool_health` and a health-matrix REST response (`GET /api/web-session-pool/health`) expose per-provider slot counts, lease ages, and error budgets so operators can diagnose pool exhaustion without digging through logs. ([#3395](https://github.com/diegosouzapw/OmniRoute/pull/3395) — thanks @oyi77)
+- **feat(web-session):** adaptive keepalive threshold — the keepalive heartbeat interval now self-adjusts based on observed provider idle-disconnect behaviour instead of using a fixed constant, reducing both unnecessary pings and unexpected session drops. ([#3397](https://github.com/diegosouzapw/OmniRoute/pull/3397) — thanks @oyi77)
+- **feat(web-session):** bulk credential import endpoint (`POST /api/web-session/import`) — import a JSON array of session credentials in one call; each entry is validated and inserted atomically, with per-entry success/failure reported in the response. ([#3403](https://github.com/diegosouzapw/OmniRoute/pull/3403) — thanks @oyi77)
+- **feat(api):** REST API for session pool health (`GET /api/session-pool/health`) — a dashboard-facing endpoint that aggregates live slot usage, wait-queue depth, and error rates across all active session pools; wired to a new dashboard widget. ([#3404](https://github.com/diegosouzapw/OmniRoute/pull/3404) — thanks @oyi77)
+
+### 🔧 Bug Fixes
+
+- **fix(sse):** eliminate race window in `usageTokenBuffer` settings update — a concurrent save + stream-start could race to apply stale settings, causing token counts to roll back by up to 2 000 tokens after a restart; the update now uses an atomic read-modify-write on the shared settings ref. ([#3405](https://github.com/diegosouzapw/OmniRoute/pull/3405) — thanks @diegosouzapw)
+- **fix(context-cache):** server-side context-cache pinning now correctly persists across restarts; proxy message content no longer leaks into the upstream prompt; and the `context_cache_protection` toggle is properly saved to the DB on change. ([#3399](https://github.com/diegosouzapw/OmniRoute/pull/3399) — thanks @k0valik)
+- **fix(providers):** the provider settings page now refreshes its model list after a successful `sync-models` call — previously the stale list remained until a full page reload. ([#3402](https://github.com/diegosouzapw/OmniRoute/pull/3402) — thanks @0xtbug)
+- **fix(stream):** empty-choices chunks (choices array present but empty, no `finish_reason`) are now silently dropped rather than emitted as a `retry:` SSE event — removes spurious retry lines from streaming responses for providers that emit heartbeat keep-alive chunks. ([#3400](https://github.com/diegosouzapw/OmniRoute/pull/3400) — thanks @0xtbug)
+- **fix(account-fallback):** the connection cooldown deduplication state is now preserved across the fallback retry chain — previously a second concurrent failure on the same account could clear the dedupe flag set by the first, allowing the cooldown window to be extended twice. ([#3381](https://github.com/diegosouzapw/OmniRoute/pull/3381) — thanks @oyi77)
+- **fix(stream):** false-positive textual tool-call marker truncation — `containsTextualToolCallMarker` now tracks how much of the accumulated streamed content has already been emitted, so it only withholds the unemitted tail rather than re-scanning from the start on every new chunk. ([#3382](https://github.com/diegosouzapw/OmniRoute/pull/3382) — thanks @Ardem2025)
+- **fix(sanitizer):** `containsTextualToolCallContent()` now requires the complete `[Tool call: name]\nArguments:` header pattern instead of a bare `.includes("[Tool call:")` check — prevents the non-streaming response sanitizer from nulling out model responses that merely quote `[Tool call:]` in prose or code examples. ([#3355](https://github.com/diegosouzapw/OmniRoute/pull/3410) — thanks @diegosouzapw)
+- **fix(stream):** the streaming textual tool-call guard now flushes any remaining buffered content as plain text when the stream ends, regardless of whether the buffer contains `"Arguments:"` — previously, a partial/incomplete tool-call header that arrived at end-of-stream was silently dropped. ([#3355](https://github.com/diegosouzapw/OmniRoute/pull/3410) — thanks @diegosouzapw)
+- **fix(executor):** Mistral (and any provider in `PROVIDERS_REQUIRING_USER_LAST_MESSAGE`) no longer receives a trailing `assistant` message with plain text content — `stripTrailingAssistantForProvider` drops it on the upstream-send path, fixing the `400: Expected last role User or Tool … but got assistant` rejection. ([#3396](https://github.com/diegosouzapw/OmniRoute/pull/3409) — thanks @diegosouzapw)
+- **fix(mitm):** `getMitmStatus()` in the build-time stub (Docker image) now returns a graceful `{ running: false }` status instead of throwing, so the Agent Bridge UI shows a clean "stopped" state rather than an error banner in containerised deployments. ([#3390](https://github.com/diegosouzapw/OmniRoute/pull/3408) — thanks @diegosouzapw)
+- **fix(env):** corrected casing of `OMNIROUTE_TRACE` in `.env.example` and all related documentation files — was previously mixed-case in some places, causing the variable to be silently ignored on case-sensitive file systems. ([#3393](https://github.com/diegosouzapw/OmniRoute/pull/3393) — thanks @androw)
+- **fix(featureFlags):** `PRICING_SYNC_ENABLED` description now clearly states that the feature requires the corresponding environment variable to be set — removes the ambiguity that led operators to enable it via the UI only and wonder why sync never ran. ([#3394](https://github.com/diegosouzapw/OmniRoute/pull/3394) — thanks @androw)
+
+### 📝 Maintenance
+
+- **ci(docker):** the CI pipeline now builds and publishes the `-web` image variant in the same Docker publish workflow, so both the standard and browser-backed images stay in sync on every release. ([#3389](https://github.com/diegosouzapw/OmniRoute/pull/3389) — thanks @zhiru)
+- **ci(e2e):** E2E shard suite hardened — timeout raised to 45 min for the heaviest shard; build artifact now uses an explicit `tar` bundle to avoid `upload-artifact@v4` LCA path ambiguity; `node_modules` copied into standalone after download; browser cache added to cut cold-shard time; `sync-models` endpoint mocked in `providers-management.spec.ts` so the import modal reaches "done" immediately. (thanks @diegosouzapw)
+- **docs:** Codex CLI configuration guide added to the dashboard (`/dashboard/codex-config`) — covers profile naming, model selection, and the `CODEX_*` environment variables accepted by OmniRoute. (thanks @diegosouzapw)
+- **chore(agentSkills):** catalog expanded to 43 entries — `config-codex-cli` added as a new `CONFIG_SKILL_IDS` category; all skill-count assertions updated across unit and integration test suites; `next-fetch` opts cast to satisfy the TypeScript overload signature in the skill runner. (thanks @diegosouzapw)
+
+---
+
+## [3.8.15] — 2026-06-07
+
+### ✨ New Features
+
+- **feat(error-rules):** provider-specific error classification with scope — a declarative rules layer lets providers map upstream error shapes to the right resilience action (provider circuit-breaker vs connection cooldown vs model lockout) at the correct scope, instead of relying on generic status-code heuristics. ([#3370](https://github.com/diegosouzapw/OmniRoute/pull/3370) — thanks @herjarsa)
+
+### 🔧 Bug Fixes
+
+- **fix(combo):** add `429` to `PROVIDER_FAILURE_ERROR_CODES` so a rate-limited target no longer drives an infinite retry loop — the combo now cools the target down and moves on. ([#3366](https://github.com/diegosouzapw/OmniRoute/pull/3366) — thanks @herjarsa)
+- **fix(catalog):** add a `getTokenLimit` fallback for combo targets with an unknown context window, so a target whose context can't be resolved no longer breaks token-limit computation for the combo. ([#3369](https://github.com/diegosouzapw/OmniRoute/pull/3369) — thanks @herjarsa)
+- **fix(auto-combo):** include no-auth providers in Auto-Combo declaratively (driven by provider metadata rather than a hard-coded list), so keyless providers are eligible candidates. ([#3365](https://github.com/diegosouzapw/OmniRoute/pull/3365) — thanks @oyi77)
+- **fix(auto-combo):** validate web-session credentials before selecting a web-cookie provider as an Auto-Combo target, so an expired/empty session doesn't get picked. ([#3371](https://github.com/diegosouzapw/OmniRoute/pull/3371) — thanks @oyi77)
+- **fix(command-code):** update the Command Code base URL from `/alpha/` to `/provider/v1/` (upstream moved the endpoint). ([#3372](https://github.com/diegosouzapw/OmniRoute/pull/3372) — thanks @TapZe)
+- **fix(kiro):** probe `%APPDATA%\kiro\storage.db` on Windows during Kiro auto-import, so the import finds the credential store where Kiro actually writes it on Windows. ([#3375](https://github.com/diegosouzapw/OmniRoute/pull/3375), fixes #3363 — thanks @diegosouzapw; reported by @Gerashka2)
+
+### 📝 Maintenance
+
+- **fix(migrations):** restore `095_provider_node_custom_headers.sql` — it was twice deleted from the release branch by a contributor branch's `git rm` of a duplicate getting folded into the squash merge; restored and guarded. (thanks @diegosouzapw)
+
+### 🙌 Contributors
+
+Thanks to everyone whose work landed in v3.8.15:
+
+| Contributor | PRs / Issues |
+| --- | --- |
+| [@herjarsa](https://github.com/herjarsa) | #3366, #3369, #3370 |
+| [@oyi77](https://github.com/oyi77) | #3365, #3371 |
+| [@TapZe](https://github.com/TapZe) | #3372 |
+| [@Gerashka2](https://github.com/Gerashka2) | reported #3363 |
+| [@diegosouzapw](https://github.com/diegosouzapw) | maintainer — #3375 shepherding, migration restores |
+
+---
+
+## [3.8.14] — 2026-06-07
+
+### ✨ New Features
+
+- **feat(api):** per-provider **custom headers** for OpenAI/Anthropic-compatible provider nodes — attach operator-defined headers (e.g. tenant/routing headers) to upstream requests via a new `customHeaders` field on provider nodes (`custom_headers_json` column, migration 095). Hardened on merge: values/names validated through the canonical `upstreamHeadersRecordSchema` (CRLF/control-char/length/16-max) with a single shared `isForbiddenCustomHeaderName()` denylist (hop-by-hop + auth), applied case-insensitively, and honored for `anthropic-compatible-cc-*` nodes too. ([#3338](https://github.com/diegosouzapw/OmniRoute/pull/3338) — thanks @pizzav-xyz / @diegosouzapw)
+
+### 🔒 Security
+
+- **fix(security):** provider auto-sync self-fetch now uses a trusted loopback/env-pinned origin (`getModelSyncInternalBaseUrl()`) instead of `new URL(request.url).origin`, so a management-authenticated caller can no longer redirect the credential-bearing internal request to an arbitrary host via the `Host` header (CodeQL `js/request-forgery`, critical). Shipped to Docker/Electron in v3.8.13; reaches npm here (npm `3.8.13` was immutable). ([#3336](https://github.com/diegosouzapw/OmniRoute/pull/3336), CodeQL #323 — thanks @diegosouzapw)
+
+### 🔧 Bug Fixes
+
+- **fix(translator):** every Gemini/Vertex `functionDeclaration.parameters` is now coerced to an OBJECT-typed schema before cleaning. Clients like GitHub Copilot send some tools (e.g. `terminal_last_command`) whose `parameters` is present but lacks a top-level `type: "object"` (just `{ properties }`, a scalar type, or `{}`); these slipped through `buildGeminiTools`' `params || default` guard and Vertex rejected them with `[400] ... functionDeclaration parameters schema should be of type OBJECT`. Hardens every OpenAI→Gemini tool request (Vertex / antigravity / agy / gemini). (#3357 — thanks @nullbytef0x)
+- **fix(gemini):** normalize Gemini/Antigravity textual `[Tool call: ...]` markers — stop suppressing **false positives** (legitimate assistant prose that merely mentions `[Tool call: terminal]`, e.g. in backticks, is preserved instead of being swallowed) and correctly buffer markers **split across streaming chunks** (`[Tool` + ` call: terminal]` + `Arguments: {...}`), flushing the text when it turns out not to be a tool call. Dedups the parsing/validation into a shared `open-sse/utils/textualToolCall.ts` (new `isValidToolCallHeaderPrefix`) and adds `gemini-2.5-flash`/`gemini-3.5-flash-low` model specs. ([#3358](https://github.com/diegosouzapw/OmniRoute/pull/3358) — thanks @Ardem2025 / @diegosouzapw)
+- **fix(electron):** clicking "Exit" (or applying an update) now terminates the **whole** server process tree, not just the direct child. The embedded server runs as `omniroute.exe`-as-node (`ELECTRON_RUN_AS_NODE`) and spawns grandchildren (embedded services, MITM proxy, tunnels); on Windows `ChildProcess.kill()` only terminates the direct child, so survivors kept `omniroute.exe` locked — the process "hung in memory" after Exit and updates failed with "file in use". New `killProcessTree()` helper uses `taskkill /PID <pid> /T /F` on Windows (signal-based on POSIX); wired into `stopNextServer`, the `waitForServerExit` force-kill, and `installUpdate`. (#3347 — thanks @Flexible78)
+- **fix(proxy):** proxy auto-selection is now **opt-in** (new `PROXY_AUTO_SELECT_ENABLED` flag, default off). Previously a single proxy in the registry silently became a global fallback for **all** provider connections (the Step-11 fallback listed every registry proxy, ignoring assignments and per-connection `proxy_enabled`). It now no-ops unless the operator enables the flag. (#3332 — thanks @hertznsk)
+- **fix(cli):** write the OpenCode config to `~/.config/opencode/opencode.json` on **all** platforms — on Windows OmniRoute wrote to `%APPDATA%\opencode\` but OpenCode reads from `%USERPROFILE%\.config\opencode\` (XDG), so dashboard-saved config silently had no effect. (#3330 — thanks @abdulkadirozyurt)
+- **fix(catalog):** remove `minimaxai/minimax-m3` from the **NVIDIA NIM** tier — NVIDIA does not host it yet, so every request 404'd (`404 page not found`), while sibling `minimax-m2.7` on the same provider works. MiniMax M3 stays available on the tiers that actually serve it. (#3329 — thanks @mikmaneggahommie)
+- **fix(sse):** treat **MiniMax M3** as multimodal so the compression layer no longer strips image parts from vision requests — `lite.ts modelSupportsVision` now keeps images for `minimax-m3*` (see also the registry `supportsVision` alignment in Maintenance). ([#3328](https://github.com/diegosouzapw/OmniRoute/pull/3328) — thanks @diegosouzapw)
+- **fix(oauth):** Kiro **Builder ID** token import no longer fails with "Bad credentials" — `validateImportToken` only ever tried the social-auth refresh; it now uses the cached AWS SSO `clientId`/`clientSecret` (`~/.aws/sso/cache/*.json`) and the OIDC refresh path (`authMethod: "builder-id"`), with a TDD harness. ([#3333](https://github.com/diegosouzapw/OmniRoute/pull/3333) — thanks @quanturbo / @diegosouzapw)
+- **fix(provider-proxy):** honor per-account proxy toggles — a connection with `proxy_enabled = false` is no longer forced through an assigned/registry proxy. ([#3349](https://github.com/diegosouzapw/OmniRoute/pull/3349) — thanks @rdself)
+- **fix(providers):** reduce proxy label noise on the provider page (clearer proxy assignment/state display). ([#3346](https://github.com/diegosouzapw/OmniRoute/pull/3346) — thanks @wilsonicdev)
+- **fix(noauth):** expose only **usable** model aliases for no-auth providers, so the catalog no longer advertises aliases that can't actually be called. ([#3345](https://github.com/diegosouzapw/OmniRoute/pull/3345) — thanks @oyi77)
+- **fix(duckduckgo):** restore the bare `Response` contract for the DuckDuckGo/browser-backed executor (rebased onto the cycle), fixing a wrapping-contract regression. ([#3323](https://github.com/diegosouzapw/OmniRoute/pull/3323) — thanks @oyi77 / @diegosouzapw)
+- **fix(dashboard):** drop the duplicate "Distribute Proxies" button on the provider page — it rendered twice at once (provider toolbar + accounts-list header) whenever connections existed and none were selected. The toolbar button (global) and the per-tag-group buttons remain. ([#3352](https://github.com/diegosouzapw/OmniRoute/pull/3352) — thanks @diegosouzapw)
+- **fix(electron):** ship `loginManager.js` in the packaged app — #3292 added it (and a `require("./loginManager")` in `main.js`) without adding it to electron-builder's `build.files`, so the packaged app crashed at startup with "Cannot find module" on the Linux/macOS smoke tests. Plus a regression test asserting every local `require("./x")` in the Electron entry points is shipped. ([#3334](https://github.com/diegosouzapw/OmniRoute/pull/3334) — thanks @diegosouzapw)
+- **fix(startup):** correct the #3292 auto-refresh daemon import (`@/open-sse/...` → `@omniroute/open-sse/services/autoRefreshDaemon`); the `@/` alias maps to `src/`, so the daemon silently never ran in the built standalone (non-fatal "Cannot find module", caught at runtime). Adds a regression test banning `@/open-sse/*` imports in `src/`. ([#3335](https://github.com/diegosouzapw/OmniRoute/pull/3335) — thanks @diegosouzapw)
+- **fix(electron):** wrap `autoUpdater.checkForUpdates()` so a 404/offline/rate-limited update check can no longer surface as an unhandled rejection (the `error` event still notifies the user); fixes the macOS-intel packaged-app smoke failure. ([#3339](https://github.com/diegosouzapw/OmniRoute/pull/3339) — thanks @diegosouzapw)
+- **fix(dashboard):** stop the infinite render loop on `/dashboard/cli-agents/hermes-agent` — `HermesAgentToolCard` listed `currentRoles` in the config-load effect's deps while `loadCurrentConfig()` set `currentRoles` to a fresh object on every fetch, so the effect re-fired → refetched → re-set forever (the page spun and spammed `GET /api/cli-tools/hermes-agent-settings` in the console; it manifested only on the always-expanded detail page). `loadCurrentConfig` is now memoized and the batch-seed reads `currentRoles` via a functional update, so the effect runs once. Adds a jsdom regression test asserting the settings endpoint is fetched a bounded number of times. ([#3353](https://github.com/diegosouzapw/OmniRoute/pull/3353) — thanks @diegosouzapw)
+- **fix(dashboard):** the Usage Analytics card now surfaces the **real** backend error (status + message) instead of a generic placeholder when `/api/usage/analytics` fails — a new shared `fetchError.ts` helper extracts a useful message. ([#3356](https://github.com/diegosouzapw/OmniRoute/pull/3356) — thanks @diegosouzapw)
+
+### 📝 Maintenance
+
+- **fix(review):** harden the per-provider custom-headers feature surfaced by the `/review-reviews` battery — `updateProviderNode` no longer wipes stored `custom_headers_json` on a partial update that omits the field; `customHeadersSchema` reuses the canonical `upstreamHeadersRecordSchema` guards (CRLF/control-char/length/16-max) and rejects auth header names via a single shared `isForbiddenCustomHeaderName()` denylist (executor + schema no longer keep divergent copies); custom headers now reach the wire for `anthropic-compatible-cc-*` nodes and override the executor's own `Content-Type`/`Accept` case-insensitively instead of duplicating them; and `rowToCamel` normalizes a NULL `_json` column to `baseKey: null`. ([#3350](https://github.com/diegosouzapw/OmniRoute/pull/3350) — thanks @diegosouzapw)
+- **fix(catalog):** flag every `minimax-m3` registry entry `supportsVision` (not just the opencode free tier) so the vision-bridge guardrail and the compression layer agree the model is multimodal on all tiers (completes #3328). (thanks @diegosouzapw)
+- **fix(oauth):** Kiro Builder ID import forwards the requested `region` to the OIDC validation refresh (no longer pinned to `us-east-1`), prefers the region-matching cached SSO client registration over the first file found, and falls `expiresIn` back to 3600 on the OIDC path. (thanks @diegosouzapw)
+- **fix(db):** migration `095` gains an `isSchemaAlreadyApplied` guard so a fresh DB (where `SCHEMA_SQL` already creates `custom_headers_json`) skips it cleanly instead of throwing-then-catching a duplicate-column error. (thanks @diegosouzapw)
+- **test:** align stale cycle tests with shipped behavior — NVIDIA `minimaxai/minimax-m3` removal (#3329), the 29th feature flag (`PROXY_AUTO_SELECT_ENABLED`, #3332), and the OpenCode `~/.config` path on Windows (#3330). (thanks @diegosouzapw)
+- **docs:** add a documentation comment to the exported `GET` handler in the context-analytics route. ([#3337](https://github.com/diegosouzapw/OmniRoute/pull/3337) — thanks @Lang-Qiu)
+- **docs(i18n):** translate 25 core documentation files to Indonesian. ([#3348](https://github.com/diegosouzapw/OmniRoute/pull/3348) — thanks @KrisnaSantosa15)
+
+### 🙌 Contributors
+
+Thanks to everyone whose work landed in v3.8.14:
+
+| Contributor | PRs / Issues |
+| --- | --- |
+| [@pizzav-xyz](https://github.com/pizzav-xyz) | #3338 |
+| [@quanturbo](https://github.com/quanturbo) | #3333 |
+| [@oyi77](https://github.com/oyi77) | #3323, #3345 |
+| [@rdself](https://github.com/rdself) | #3349 |
+| [@wilsonicdev](https://github.com/wilsonicdev) | #3346 |
+| [@hertznsk](https://github.com/hertznsk) | #3332 |
+| [@abdulkadirozyurt](https://github.com/abdulkadirozyurt) | #3330 |
+| [@mikmaneggahommie](https://github.com/mikmaneggahommie) | #3329 |
+| [@Flexible78](https://github.com/Flexible78) | #3347 |
+| [@Lang-Qiu](https://github.com/Lang-Qiu) | #3337 |
+| [@KrisnaSantosa15](https://github.com/KrisnaSantosa15) | #3348 |
+| [@nullbytef0x](https://github.com/nullbytef0x) | #3357 |
+| [@Ardem2025](https://github.com/Ardem2025) | #3358 |
+| [@diegosouzapw](https://github.com/diegosouzapw) | maintainer — #3334, #3335, #3336, #3339, #3350, #3352, #3353, #3356; review/hardening across the cycle |
+
+---
+
+## [3.8.13] — 2026-06-06
+
+### ✨ New Features
+
+- **feat(web-cookie):** self-service login infrastructure for 21 web-cookie providers — three login pathways (Electron BrowserWindow, Playwright dashboard fallback, `POST /api/providers/{id}/login`), token-extraction configs, and a 15-min cookie-validity auto-refresh daemon. Hardened on merge: error bodies sanitized (Hard Rule #12), the spawn-capable login route classified LOCAL_ONLY (Hard Rules #15/#17), and the Electron status listener de-duplicated. ([#3292](https://github.com/diegosouzapw/OmniRoute/pull/3292), closes #3070 — thanks @oyi77 / @diegosouzapw)
+- **feat(api):** accept path-scoped API keys on client API routes — keys may arrive via `/api/v1/vscode/<key>/…` path aliases (incl. `raw`/`combos`); explicit `Authorization`/`x-api-key` headers still take precedence. Split out of #3073. ([#3300](https://github.com/diegosouzapw/OmniRoute/pull/3300) — thanks @zhiru)
+- **feat(api):** model-catalog enrichment + MCP `model-catalog` tools — richer per-model metadata (context window, capabilities) surfaced through `/v1/models` and new MCP tools, plus `readHeaderValue` header-record support. Split out of #3073; reconciled on merge with the #3309 URL-token hardening (kept the security gate — no query-string credential fallback, management auth stays header-only). ([#3306](https://github.com/diegosouzapw/OmniRoute/pull/3306) — thanks @zhiru / @diegosouzapw)
+- **feat(dashboard):** internationalize the proxy settings UI — `ProxyTab` + the proxy `DocumentationTab`/`FreePoolTab`/`VercelRelayModal` now render via `t(...)`, with matching `en`/`pt-BR` message keys. Split out of #3073. ([#3307](https://github.com/diegosouzapw/OmniRoute/pull/3307), [#3310](https://github.com/diegosouzapw/OmniRoute/pull/3310) — thanks @zhiru)
+- **feat(provider):** provider test-all endpoint + per-connection rate-limit overrides + model visibility — `POST /api/models/test-all` runs parallel model tests (chunked, timeout-skip) atop a shared `runSingleModelTest` runner; per-connection rate-limit overrides land via `PATCH /api/providers/:id` (new `rate_limit_overrides_json` column + Zod schema); a dashboard model-visibility toolbar (All / Visible / Hidden) drives a `/v1/models` catalog that excludes user-hidden models; models auto-fetch on every connection add; and passthrough (OpenRouter) models gain test buttons. Folds in dashboard fixes on merge (missing alias/delete handlers, duplicate-model-ID React keys, "Hide all" restored) and a build fix so empty `.env` values no longer override real config. ([#3267](https://github.com/diegosouzapw/OmniRoute/pull/3267) — thanks @Vinayrnani)
+- **feat(api):** VS Code Copilot Ollama-compatible BYOK endpoint — exposes an Ollama-shaped surface so VS Code Copilot's "bring your own key" Ollama provider can target OmniRoute directly, with a `VscodeTokenAliasCard` in the dashboard endpoint tab to generate the path-scoped token alias. ([#3316](https://github.com/diegosouzapw/OmniRoute/pull/3316) — thanks @zhiru)
+- **feat(combo):** Auto-Combo candidate-expansion optimization + playground model dropdown + "only configured" model toggle — reworks the `auto` strategy's candidate selection in `combo.ts` and surfaces a model picker in the playground `StudioConfigPane` / `useAvailableModels`. ([#3322](https://github.com/diegosouzapw/OmniRoute/pull/3322) — thanks @oyi77)
+
+### 🔒 Security
+
+- **fix(auth):** follow-up hardening of the client-API key extractor (#3300) — removed the generic query-string token fallbacks (`?token=`/`?key=`/`?apiKey=`/`?api_key=`), which leak credentials into access logs / Referer headers, and gated URL-borne tokens to client routes only (management auth is now header-only) so a credential in the URL can never authenticate a management route. The path-scoped `/vscode/<key>/…` form the VS Code integration needs is unchanged. (security review follow-up to [#3300](https://github.com/diegosouzapw/OmniRoute/pull/3300) — thanks @zhiru / @diegosouzapw)
+
+### 🔧 Bug Fixes
+
+- **fix(dashboard):** Agent Bridge page (`/dashboard/tools/agent-bridge`) no longer crashes with "Internal Server Error" — the page replaced its well-shaped state with the raw `/api/tools/agent-bridge/state` response (`{ server, agents }`), leaving `serverState` undefined and throwing `Cannot read properties of undefined (reading 'running')`. A shared `normalizeAgentBridgeState()` now maps the route shape into the page contract (incl. `server.certExists → certTrusted`) and always returns safe defaults, used by both the SSR loader and the polling hook. (#3318 — thanks @tycronk20)
+- **fix(codex):** strip client-only params (`prompt_cache_retention`, `safety_identifier`, `user`) on the native `codex/` `/v1/responses` passthrough — Codex upstream rejects them with `400 Unsupported parameter`, which broke Factory Droid and any client injecting those fields. The chat-completions path already stripped them; the responses→responses passthrough now does too. (#3317 — thanks @tycronk20)
+- **fix(theoldllm):** stop the `[502]: Body is unusable: Body has already been read` error on the cached-token path — the executor read the same upstream `Response` body with `.text()` twice; it now reads it once and only re-reads after a token-rejection refetch. (#3296 — thanks @onizukashonan14-png)
+- **fix(dashboard):** keep no-auth providers (opencode, duckduckgo-web, theoldllm, veoaifree-web) visible under the "Show configured only" filter — they never create a connection row (`stats.total === 0`) but are always usable and already appear in `/v1/models`, so the filter now treats `displayAuthType === "no-auth"` as configured. (#3290 — thanks @uniQta)
+- **fix(dashboard):** refresh the connection list after a Codex/Claude/Gemini auth import — the import modals called `fetchData()` (which only reloads provider metadata), so a freshly-imported connection stayed invisible until a manual reload; they now call `fetchConnections()`. ([#3320](https://github.com/diegosouzapw/OmniRoute/pull/3320) — thanks @zhiru)
+- **fix(cli):** `omniroute update` no longer always fails on a global install — `getCurrentVersion()` and `createBackup()` now resolve `package.json`/`bin` relative to the script (`import.meta.url`) instead of `process.cwd()` (the user's working dir on a global npm/brew install → *"Could not determine current version"*), and the backup copies the `cli` directory with `cpSync({recursive:true})` instead of `copyFileSync`, which threw a swallowed `EISDIR` → *"Failed to create backup. Aborting"*. (#3295 — thanks @uniQta)
+- **fix(sse):** harden the passthrough stream against empty upstream responses — emit a synthetic retry chunk on an empty `choices: []` (fixes a Copilot Chat crash) and log empty post-`tool_calls` completions; also registers **MiniMax M3** (1M context) across 8 provider tiers. ([#3297](https://github.com/diegosouzapw/OmniRoute/pull/3297), #3110 — thanks @wilsonicdev)
+- **fix(opencode-provider):** extract `contextLength` from the live `/v1/models` catalog (live > `modelContextLengths` > static map) so passthrough models outside the legacy 8-model map no longer silently truncate to OpenCode's 128K default. ([#3298](https://github.com/diegosouzapw/OmniRoute/pull/3298) — thanks @herjarsa / @diegosouzapw)
+- **fix(dev):** auto-rebuild `better-sqlite3` on a Node ABI mismatch at `npm run dev` startup (nvm 22↔24) — dev-only, no-op on the healthy path, unrelated errors not swallowed. ([#3301](https://github.com/diegosouzapw/OmniRoute/pull/3301) — thanks @zhiru)
+- **fix(api):** remove the bundled **Completions.me** provider preset — empirically verified to return Rick Astley lyrics instead of real completions for every model/prompt. ([#3302](https://github.com/diegosouzapw/OmniRoute/pull/3302), discussion #3293 — thanks @diegosouzapw; reported by @mikmaneggahommie)
+- **fix(ci):** skip the auto-deploy step when the VPS SSH port is unreachable from the GitHub runner (private LAN / firewall) instead of red-failing every release pipeline; genuine deploy/boot failures still fail honestly. ([#3299](https://github.com/diegosouzapw/OmniRoute/pull/3299) — thanks @diegosouzapw)
+- **fix(sse):** strip leaked internal tool-call envelopes (`to=functions.*` / `multi_tool_use.parallel { … }`) from visible assistant text and sanitize Responses-API streaming (drop `commentary`-phase output items) so harness syntax never reaches the client. ([#3311](https://github.com/diegosouzapw/OmniRoute/pull/3311) — thanks @zhiru)
+- **fix(sse):** expose the Claude (`claude-opus-4-6-thinking`, `claude-sonnet-4-6`) and Gemini budget tiers (`gemini-3.1-pro-{high,low}`, `gemini-3.5-flash-{low,extra-low}`) in the Antigravity catalog — they are user-callable on the Antigravity OAuth backend (agy parity), correcting an earlier assumption that Claude had been removed. ([#3303](https://github.com/diegosouzapw/OmniRoute/pull/3303), discussion #3184 — thanks @diegosouzapw)
+- **fix(catalog):** compute a combo's `context_length` from the known targets only — a single target with unknown context no longer collapses the whole combo to `undefined`; also accepts live `{id, contextLength}` model entries in the opencode-provider helper (follow-up to #3298). ([#3304](https://github.com/diegosouzapw/OmniRoute/pull/3304) — thanks @herjarsa / @diegosouzapw)
+
+### 📝 Maintenance
+
+- **test(catalog):** align the Antigravity preview-alias catalog test with the #3303 budget tiers — asserts the restored Claude/Gemini tiers are surfaced, locking in the behavior so a future tier change can't silently drop them again (thanks @diegosouzapw)
+- **docs:** rename the `resolve-issues` skill references to `review-issues` across the docs/skill surfaces, matching the renamed governance skill (thanks @diegosouzapw)
+- **docs:** document the VS Code / Ollama endpoints (API reference + new `docs/reference/CLI-TOOLS.md`) and improve the env-bootstrap + i18n key-coverage tooling. ([#3319](https://github.com/diegosouzapw/OmniRoute/pull/3319) — thanks @zhiru)
+- **chore(release):** open the v3.8.13 development cycle (version bump + cycle bookkeeping) and finalize this changelog (thanks @diegosouzapw)
+
+### 🙌 Contributors
+
+Thanks to everyone whose work landed in v3.8.13:
+
+| Contributor | PRs / Issues |
+| --- | --- |
+| [@zhiru](https://github.com/zhiru) | #3300, #3306, #3307 / #3310, #3309, #3301, #3311, #3320, #3319, #3316 |
+| [@tycronk20](https://github.com/tycronk20) | #3317, #3318 |
+| [@Vinayrnani](https://github.com/Vinayrnani) | #3267 |
+| [@oyi77](https://github.com/oyi77) | #3292 (closes #3070), #3322 |
+| [@onizukashonan14-png](https://github.com/onizukashonan14-png) | #3296 |
+| [@uniQta](https://github.com/uniQta) | #3290, #3295 |
+| [@wilsonicdev](https://github.com/wilsonicdev) | #3297 |
+| [@herjarsa](https://github.com/herjarsa) | #3298, #3304 |
+| [@mikmaneggahommie](https://github.com/mikmaneggahommie) | reported the Completions.me rickroll (discussion #3293) |
+| [@diegosouzapw](https://github.com/diegosouzapw) | maintainer — #3299, #3302, #3303; co-author on #3292 / #3306 / #3298 / #3304 / #3309 |
+
+---
+
+## [3.8.12] — 2026-06-06
+
+### ✨ New Features
+
+- **chipotle:** add Chipotle Pepper AI — a free provider implemented via the reverse-engineered Amelia protocol, with its executor error body routed through `sanitizeErrorMessage()` (Hard Rule #12) ([#3250](https://github.com/diegosouzapw/OmniRoute/pull/3250) — thanks @oyi77)
+- **web-cookie:** add tool-call translation to 8 web-cookie executors via shared `webTools` helpers, so cookie-backed providers can participate in tool/function calling through a single serialize/parse path ([#3259](https://github.com/diegosouzapw/OmniRoute/pull/3259) — thanks @oyi77)
+- **free-tiers:** per-model free-token budget catalog + a Monthly Budget dashboard card surfacing each provider's monthly free allowance (joins the honest free-token catalog/API/headline work from #3257) ([#3263](https://github.com/diegosouzapw/OmniRoute/pull/3263), [#3257](https://github.com/diegosouzapw/OmniRoute/pull/3257) — thanks @diegosouzapw)
+- **dashboard:** bulk activate / deactivate / retest for selected provider connections — multi-select with batch lifecycle actions on the providers page ([#3271](https://github.com/diegosouzapw/OmniRoute/pull/3271) — thanks @leninejunior)
+- **models:** register MiniMax-M3 (frontier coding/agentic model, 1M context, Anthropic-compatible) across 8 provider tiers — `minimax`, `minimax-cn`, `opencode` (free), `opencode-go`, `opencode-zen`, `trae`, `ollama-cloud`, `nvidia` ([#3287](https://github.com/diegosouzapw/OmniRoute/pull/3287), #3110 — thanks @wilsonicdev)
+
+### 🔧 Bug Fixes
+
+- **api/responses:** combo names without a slash (e.g. `paid-premium`, `n8n-text`) are no longer force-rewritten to `codex/<combo>` on `/v1/responses` — `resolveResponsesApiModel` now returns the request unchanged when the model resolves to a combo (regression from the v3.8.9 Codex WS→HTTP fallback) ([#3268](https://github.com/diegosouzapw/OmniRoute/pull/3268), fixes #3227 / #3233 — thanks @wilsonicdev; supersedes the earlier closed #3242)
+- **sse:** strip **every** `<omniModel>` tag before forwarding to the provider, not just the first — a global-regex variant prevents stray routing tags from leaking into the upstream prompt ([#3248](https://github.com/diegosouzapw/OmniRoute/pull/3248), fixes #454 — thanks @MikeTuev)
+- **grok-web:** add TLS fingerprint impersonation to bypass Cloudflare anti-bot on the Grok web endpoint, with the executor's error bodies routed through `sanitizeErrorMessage()` (Hard Rule #12) ([#3249](https://github.com/diegosouzapw/OmniRoute/pull/3249), fixes #3180 — thanks @wilsonicdev)
+- **providers:** improve provider refresh/validation and the model-catalog UI — including the OpenRouter catalog and the proxy UI, plus the NVIDIA NIM `/models`-suffix probe path (real-VPS validated) ([#3261](https://github.com/diegosouzapw/OmniRoute/pull/3261) — thanks @strangersp)
+- **embeddings:** block cross-dimension failover inside embedding combos so a fallback target with a different vector dimension can no longer corrupt results ([#3256](https://github.com/diegosouzapw/OmniRoute/pull/3256) — thanks @diegosouzapw)
+- **sse/web-tools:** web-cookie providers (e.g. `ds-web`/`deepseek-v4-pro`) that wrap tool calls as `<tool_call name="...">{json}</tool_call>` are now parsed correctly — the real tool name is read from the JSON body instead of the tag attribute, and the call is no longer silently dropped when `arguments` is absent ([#3275](https://github.com/diegosouzapw/OmniRoute/pull/3275), fixes #3260 — thanks @diegosouzapw)
+- **sse/groq:** non-reasoning Groq models (`llama-3.3-70b-versatile`, `llama-4-scout`) are now flagged `supportsReasoning: false`, so `reasoning_effort` / `output_config.effort` / `thinking` are stripped before dispatch instead of being forwarded and rejected with HTTP 400 — fixes the Claude Code → Groq regression of #764 ([#3277](https://github.com/diegosouzapw/OmniRoute/pull/3277), fixes #3258 — thanks @diegosouzapw)
+- **api/images:** `POST /v1/images/edits` to a custom OpenAI-compatible provider no longer forwards an empty `model`. The multipart body is now built as a `Buffer` with an explicit boundary instead of a global `FormData` — the patched undici `fetch` serialized a native `FormData` as the literal string `[object FormData]` (text/plain), dropping every field including `model` ([#3278](https://github.com/diegosouzapw/OmniRoute/pull/3278), fixes #3273 — thanks @diegosouzapw)
+- **db:** detect SQLite driver-unavailable errors to avoid a destructive DB rename + an optional FTS5 migration guard, so a transient driver-load failure no longer triggers the backup-and-recreate path on a healthy database (split from #3073) ([#3274](https://github.com/diegosouzapw/OmniRoute/pull/3274) — thanks @zhiru)
+- **quota:** repair the Quota Sharing Engine — `poolUsageWithDimensions()` promoted onto the `QuotaStore` interface (kills the dynamic type-narrowing hack), single-snapshot burn rate via `computeBurnRateFromWindow()` (the dashboard previously always showed 0), zero-weight allocations normalized to equal distribution, Anthropic `anthropic-ratelimit-*` saturation signals, a `quota.exceeded` webhook fired on block, and quota enforcement extended to the embeddings handler ([#3280](https://github.com/diegosouzapw/OmniRoute/pull/3280) — thanks @oyi77)
+- **plugins:** `emitHookBlocking` now chains the payload between handlers — each blocking handler receives the body/metadata as mutated by previous handlers, so a later plugin can observe an earlier plugin's changes (previously every handler got the original static payload) ([#3286](https://github.com/diegosouzapw/OmniRoute/pull/3286) — thanks @oyi77)
+- **api/webhooks:** webhook URLs may now target a private/internal address (e.g. `192.168.x`, a docker-internal host) when `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true` — the webhook guard reuses the same explicit opt-in as private provider URLs (default OFF; protocol and embedded-credential checks stay unconditional). Cloud-metadata / link-local endpoints (`169.254.169.254`, `metadata.google.internal`, `100.100.100.200`, `169.254.0.0/16`) are blocked **unconditionally** even with the opt-in on, and the webhook test endpoint redacts the upstream response body for private targets (no SSRF→IAM-credential pivot, no content exfiltration) ([#3279](https://github.com/diegosouzapw/OmniRoute/pull/3279), [#3281](https://github.com/diegosouzapw/OmniRoute/pull/3281), fixes #3269 — thanks @diegosouzapw)
+- **sse/qoder:** a valid Qoder Personal Access Token is no longer wrongly reported as "expired" when the Cosy validation endpoint returns a generic `Internal Server Error` (HTTP 500). A Cosy 500 only marks the PAT invalid when its body carries an explicit auth signal; a generic server fault now falls back to the #1391 valid-bypass rule ([#3283](https://github.com/diegosouzapw/OmniRoute/pull/3283), fixes #3247 — thanks @wilsonicdev, who independently diagnosed the same root cause and filed [#3282](https://github.com/diegosouzapw/OmniRoute/pull/3282); refined here to keep rejecting on an explicit-auth-signal 500)
+
+### 📝 Maintenance
+
+- **ci:** `deploy-vps` recreates the PM2 process via the `omniroute` bin (instead of a bare `pm2 restart` pinned to the removed `app/server-ws.mjs` path) and gates the deploy on `/api/monitoring/health` reporting `"status":"healthy"`, failing the job (with recent PM2 logs) when the box never becomes healthy — supersedes #3262 ([#3270](https://github.com/diegosouzapw/OmniRoute/pull/3270) — thanks @diegosouzapw)
+- **security:** harden the Chipotle executor against CodeQL findings — `Math.random()` → `crypto.randomInt()`/`crypto.randomUUID()` (imported from `node:crypto`) for session/server IDs, and a strict `new URL().hostname` check (replacing a substring match) in its test ([#3285](https://github.com/diegosouzapw/OmniRoute/pull/3285) — thanks @oyi77)
+- **governance:** raise the coverage gate from 40% to 60% (statements/lines/functions/branches) now that real coverage sits at ~80% — brings the threshold in line with Hard Rule #9 (thanks @diegosouzapw)
+- **docs:** consolidate the community links (Discord + Telegram + WhatsApp) at the top of the README and promote the Free-Token Budget section ([#3289](https://github.com/diegosouzapw/OmniRoute/pull/3289) — thanks @diegosouzapw)
+- **docs:** richer free-tier budget-card image (28 models + first-month strip) and softer ToS framing (caution rather than warning) ([#3284](https://github.com/diegosouzapw/OmniRoute/pull/3284) — thanks @diegosouzapw)
+
+### 🙌 Contributors
+
+Thanks to everyone whose work landed in v3.8.12:
+
+| Contributor | PRs / Issues |
+| --- | --- |
+| [@oyi77](https://github.com/oyi77) | #3250, #3259, #3280, #3285, #3286 |
+| [@wilsonicdev](https://github.com/wilsonicdev) | #3249, #3268, #3282 / #3283 (co-author, #3247 diagnosis), #3287 |
+| [@strangersp](https://github.com/strangersp) | #3261 |
+| [@MikeTuev](https://github.com/MikeTuev) | #3248 |
+| [@leninejunior](https://github.com/leninejunior) | #3271 |
+| [@zhiru](https://github.com/zhiru) | #3274 |
+| [@diegosouzapw](https://github.com/diegosouzapw) | maintainer — #3256, #3263, #3270, #3275, #3277, #3278, #3279, #3281, #3284, #3289 |
+
+---
+
+## [3.8.11] — 2026-06-05
+
+### ✨ New Features
+
+- **theoldllm:** add The Old LLM — a free, Playwright-backed provider with dual-mode operation (cached browser token + direct fetch) bridged through a Vercel relay (#3217 — thanks @oyi77)
+- **codex:** add Codex login via OpenAI's browser-driven device authorization flow, exposed as a shareable "Adicionar Externo" public link (`/connect/codex/{token}`) so a third party can complete the OpenAI device login without dashboard access (#3195 — thanks @zhiru)
+- **proxy:** per-connection proxy distribution — `proxy_enabled` DB schema + Zod-validated resolution backend, automatic proxy-fallback selection when provider validation hits a network error, and a dashboard UI with per-connection toggles and a tag-filtered "Distribute Proxies" button (#3170, #3171, #3172 — thanks @pizzav-xyz)
+- **api:** `/v1/images/generations` and `/v1/images/edits` now resolve a bare combo/alias model name (e.g. `image`) to its single image target, and `/v1/images/edits` forwards multipart edits to custom OpenAI-compatible providers' `{base_url}/images/edits` (also accepting JSON/data-URL edit input) instead of rejecting everything but chatgpt-web (#3214, #3215 — thanks @ngocquynh85)
+
+### 🔧 Bug Fixes
+
+- **api:** combo names sent to `/v1/responses` are no longer force-rewritten to `codex/<name>` — the Codex CLI WS→HTTP fallback rewrite now skips bare names that are combos, so combos (e.g. `n8n-text`, `paid-premium`) route correctly again instead of failing with "No credentials for provider: codex" (regression since v3.8.9) (#3227, #3233 — thanks @Marcus1Pierce, @Dima-Kal)
+- **antigravity:** the `agy` `gemini-3.1-pro-high`/`-low` models now alias to the plain `gemini-3.1-pro` upstream id (the `-high`/`-low` suffix is rejected for gemini-3.x), and non-streaming upstream 4xx/5xx errors surface as real error bodies instead of being masked as an empty `chat.completion` envelope (#3229)
+- **auth:** honor the effective `REQUIRE_API_KEY` feature flag (DB override > env > default) in client API auth instead of reading `process.env` directly, and align the route-local optional-auth checks (`/v1/embeddings`, `/v1/web/fetch`, `/v1/combos`, playground) with it (#3188 — thanks @xz-dev)
+- **oauth:** use `api.anthropic.com` for the Claude OAuth token exchange so self-hosted VPS deployments are no longer blocked by Cloudflare Bot Management on `console.anthropic.com` (#3203, fixes #3192 — thanks @wilsonicdev; the same root cause was independently diagnosed by @ibanunmangun in [#3193](https://github.com/diegosouzapw/OmniRoute/pull/3193), credited here as co-author)
+- **oauth:** validate OAuth client IDs against `resolvePublicCred` so adding an Antigravity / Gemini CLI / AGY connection with the built-in public client no longer fails with a Google `redirect_uri_mismatch` (#3206 — thanks @juandisay)
+- **auto-combo:** include zero-config OpenCode Free in `auto/*` virtual combos even with no `provider_connections` row, reusing the synthetic `noauth` connection id and routing through the `oc/` prefix (#3189, fixes #3155 — thanks @wilsonicdev)
+- **sse:** refine Kimi thinking-block handling and add regression tests for assistant tool-call replay (#3191 — thanks @bypanghu)
+- **openrouter:** report the true upstream `context_length` for passthrough models instead of the 128K default — `normalizeDiscoveredModels` now reads `context_length`/`top_provider.context_length` (and `max_completion_tokens` for output) when `inputTokenLimit` is absent (#3202 — thanks @pulyankote)
+- **images:** custom image-generation providers now use the provider node's base URL (`providerSpecificData.baseUrl`) and resolve the `prefix/model` form, instead of silently falling back to the Gemini endpoint (#3205 — thanks @ngocquynh85)
+- **docker:** the container healthcheck now probes `127.0.0.1`/`localhost`/`::1` and prints the failure to stderr instead of swallowing it, fixing false "unhealthy" status when the server binds to a non-loopback address (#3151 — thanks @naimo84)
+- **docker:** copy `scripts/dev/healthcheck.mjs` into the runner-base image — the Next.js standalone output doesn't trace it, so the `HEALTHCHECK CMD ["node", "healthcheck.mjs"]` probe silently exited 1 (#3201 — thanks @wilsonicdev)
+- **llama-cpp:** fall back to the provider's local default base URL (`127.0.0.1:8080/v1`) when a local connection has no base URL set, instead of silently routing to OpenAI (residual of #3136) (#3197 — thanks @tjengbudi)
+- **provider-models:** allow deleting synced/fetched models (e.g. llama-cpp) via `DELETE /api/provider-models` — the handler now clears the `syncedAvailableModels` namespace, not just `customModels` (#3204, fixes #3199 — thanks @wilsonicdev); and a deleted synced model now stays deleted across an auto-fetch re-import (the DELETE marks it hidden and the re-import skips hidden ids) (#3199 — thanks @tjengbudi)
+- **db/electron:** fix `Cannot find module 'better-sqlite3'` crash when importing a database backup in the packaged Electron app (Windows installer) — the `db-backups/import` route now opens its integrity-check DB through the resilient driver factory (better-sqlite3 → node:sqlite → sql.js) instead of a static native import that is stripped from the standalone server bundle; a guard test prevents any API route from reintroducing a direct native import (#3025 — thanks @yeardie)
+- **dashboard:** the home provider-topology graph now shows the friendly provider name instead of the internal UUID for custom providers — the label precedence let `getProviderConfig`'s `{ name: providerId }` fallback shadow the pre-resolved name (#3198 — thanks @tjengbudi)
+- **providers:** NVIDIA key validation now probes the universally-available `meta/llama-3.1-8b-instruct` instead of the catalog's first model (`z-ai/glm-5.1`), which requires the "Public API Endpoints" account permission and could hang/be DEGRADED — making a valid key fail with a misleading "Upstream Error" (#3116 — thanks @miracuves)
+- **providers:** NVIDIA NIM key validation no longer times out (504) — the probe bypasses the global undici `fetch` proxy patch (`open-sse/utils/proxyFetch.ts`) that is incompatible with NVIDIA's endpoint and made the request hang silently (#3226 — thanks @miracuves)
+- **dashboard:** corrected two misleading provider credential hints — Grok Web now states both `sso` and `sso-rw` cookies are required (was just `sso`), and the Vertex AI Service Account field shows real instructional placeholder text instead of an untranslated stub across 40 locales (#3180, #3091 — thanks @YoursSweetDom, @Guru01100101)
+- **i18n:** normalize dotted `compliance.eventTypes` keys into nested objects at load time so next-intl no longer throws `INVALID_KEY: Namespace keys cannot contain "."` (the same PR also corrects the Codex import-auth provider hint) ([#3185](https://github.com/diegosouzapw/OmniRoute/pull/3185) — thanks @zhiru; the same i18n bug was independently fixed by @androw in [#3167](https://github.com/diegosouzapw/OmniRoute/pull/3167), credited here as co-author)
+- **usage:** route the `agy` provider's quota through the existing Antigravity usage implementation (register `agy` in `USAGE_FETCHER_PROVIDERS`, all four `getUsageForProvider` call sites + `parseQuotaData` + `syncAntigravitySubscriptionIfNeeded`) so it no longer falls through to "Usage API not implemented" (#3232, fixes #3230 — thanks @wilsonicdev)
+- **cli:** show OpenCode Free in the Hermes Agent model picker even with no active connection — new optional `alwaysIncludeProviders` prop on `ModelSelectModal` (defaults to `[]`, so other callers are unaffected) lets zero-config providers like `opencode` surface in the grouped list (#3240 — thanks @wilsonicdev)
+- **gemini:** refresh the Gemini (AI Studio) static fallback so the provider tab exposes current 3.x / 2.5 models on first run, preserving the `gemini-2.0-flash` default ordering; the full catalog still comes from API sync once a key is added (#3241, fixes #3231 — thanks @wilsonicdev)
+
+### 📝 Maintenance
+
+- **build:** finish the build-output-isolation cleanup — `assembleStandalone.mjs` now derives both its async (`syncStandalone*`) and sync copy paths from a single `NATIVE_ASSET_ENTRIES`/`EXTRA_MODULE_ENTRIES` source of truth (previously two hand-maintained lists that could silently drift), guarded by a new parity test; and the `Dockerfile` drops 5 redundant per-module `COPY` overrides (`@swc/helpers`, `pino-abstract-transport`, `pino-pretty`, `split2`, `migrations`) now that `assembleStandalone` bundles them into the standalone regardless of NFT/Turbopack tracing (validated with a real Turbopack `docker build` + boot → `/api/monitoring/health` 200; `better-sqlite3` stays explicit since only its native `build/` is synced) (#3187 — thanks @diegosouzapw)
+- **combo:** add a regression guard asserting the same-provider cascade is short-circuited by the connection-cooldown layer (#3200 — thanks @diegosouzapw)
+- **repo:** housekeeping — ignore the generated `coverage/` output dir and prune deprecated `.agents/skills/*` SKILL definitions superseded by the current workflow skills (thanks @diegosouzapw)
+
+### 🙌 Contributors
+
+Thanks to everyone whose work landed in v3.8.11:
+
+| Contributor | PRs / Issues |
+| --- | --- |
+| [@wilsonicdev](https://github.com/wilsonicdev) | #3189, #3201, #3203, #3204, #3232, #3240, #3241 |
+| [@pizzav-xyz](https://github.com/pizzav-xyz) | #3170, #3171, #3172 |
+| [@zhiru](https://github.com/zhiru) | #3185, #3195 |
+| [@oyi77](https://github.com/oyi77) | #3217 |
+| [@miracuves](https://github.com/miracuves) | #3116, #3226 |
+| [@ngocquynh85](https://github.com/ngocquynh85) | #3205, #3214, #3215 |
+| [@xz-dev](https://github.com/xz-dev) | #3188 |
+| [@bypanghu](https://github.com/bypanghu) | #3191 |
+| [@juandisay](https://github.com/juandisay) | #3206 |
+| [@tjengbudi](https://github.com/tjengbudi) | #3197, #3198, #3199 |
+| [@naimo84](https://github.com/naimo84) | #3151 |
+| [@yeardie](https://github.com/yeardie) | #3025 |
+| [@pulyankote](https://github.com/pulyankote) | #3202 |
+| [@YoursSweetDom](https://github.com/YoursSweetDom) | #3180 |
+| [@Guru01100101](https://github.com/Guru01100101) | #3091 |
+| [@androw](https://github.com/androw) | #3167 (co-author) |
+| [@ibanunmangun](https://github.com/ibanunmangun) | #3193 (co-author) |
+| [@diegosouzapw](https://github.com/diegosouzapw) | maintainer — #3187, #3200, issue-fix batches |
+
+---
+
+## [3.8.10] — 2026-06-04
+
+OAuth resilience & observability release: spaced/sequential quota sync for OAuth accounts, a per-provider proactive-refresh skip list to keep short-TTL providers (Kimi) alive without re-exposing the Codex Auth0 cascade, token-expiry visibility on the provider cards, a new provider-stats dashboard, plus a wide batch of provider fixes (DeepSeek-web tool calls, Antigravity, Qoder, MiniMax, GitHub Copilot, Fireworks, llama.cpp, t3.chat-web, Kiro, Kilocode) and Podman deployment support.
+
+### ✨ New Features
+
+- **dashboard:** new Provider Stats page + `/api/provider-stats` endpoint — per-provider and per-model aggregates from `call_logs` plus live combo/telemetry/tool-latency overlays. (#3175 — thanks @pizzav-xyz / @diegosouzapw)
+- **metrics:** cross-request TTFT and gap-after-tool-call latency tracking, aggregated per provider. (#3173 — thanks @pizzav-xyz / @diegosouzapw)
+- **quota:** show the OAuth token expiry on provider cards (small, blue, informative — "Token expires in …" / "Token expired"). (#3178 — thanks @diegosouzapw)
+- **responses:** strip `previous_response_id` for stateless Responses upstreams, with an auto/strip/preserve setting + UI so stateless clients (e.g. VS Code Custom Endpoint) keep context. (#3143 — thanks @JxnLexn)
+- **deploy:** Podman/rootless deployment support (contrib units + `CONTAINER_HOST` hint) and larger upload body-size limits for `/v1/files`. (#3128 — thanks @hartmark)
+
+### 🔧 Bug Fixes
+
+- **usage:** sequential + spaced OAuth quota sync (`PROVIDER_LIMITS_SYNC_SPACING_MS`) so a host no longer bursts simultaneous usage/refresh requests; reactive forced re-mint after a 401 on the per-card refresh (recovers imported accounts); a genuine 401 now surfaces a re-authenticate hint. (#3156 — thanks @diegosouzapw)
+- **healthcheck:** per-provider proactive-refresh skip list (`OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS`) — keep rotating-cascade providers (Codex/OpenAI) reactive-only while short-TTL providers (Kimi-coding) keep refreshing proactively. (#3159 — thanks @diegosouzapw)
+- **providers:** on `?refresh=true` with no remote models, don't resurface the just-cleared synced cache into the local-catalog fallback. (#3181 — thanks @diegosouzapw)
+- **providers:** use synced models as the authoritative local catalog across all providers (even on connections that didn't run the sync). (#3148 — thanks @herjarsa)
+- **web-tools:** parse bare-JSON tool calls for DeepSeek-web with fuzzy tool-name matching scoped to the requested tools. (#3157 — thanks @wilsonicdev)
+- **responses:** normalize `image_url` parts across every Responses input path (message content, replayed output items, `function_call_output`) to avoid upstream 400s. (#3150 — thanks @wilsonicdev)
+- **antigravity:** dynamic upstream model resolution via the MITM alias table (server-only executor), with a guard against corrupted alias values. (#3144 — thanks @herjarsa)
+- **qoder:** bifurcate validation by token type — PAT (`pt-`) → Cosy, regular API key → dashscope — matching the executor's routing. (#3149 — thanks @herjarsa)
+- **api-manager:** preserve API key expiration in local time (the `datetime-local` input no longer silently shifts to UTC) + a clear button. (#3146 — thanks @xz-dev)
+- **opencode-plugin:** map `caps.thinking → ModelV2.capabilities.interleaved` for single models and combos. (#3138 — thanks @mrmm)
+- **kiro:** optional `targetProvider` on the social-OAuth exchange so Kiro-based providers can reuse the social login flow. (#3176 — thanks @pizzav-xyz)
+- **misc:** broaden the DeepSeek reasoning-replay regex (`-free` / `zen/deepseek-v4`), export `ProviderProfile`, and guard a non-string directory entry in the binary manager. (#3177 — thanks @pizzav-xyz)
+- **providerRegistry:** point kilocode at the OpenAI format + default executor (matching its sibling `kilo-gateway`). (#3166 — thanks @androw)
+- **fireworks:** preserve fully-qualified router/model IDs so Fire Pass router IDs (`accounts/fireworks/routers/...`) are no longer double-prefixed into an upstream 404. (#3133 — thanks @KooshaPari)
+- **llama-cpp:** route requests to the configured local baseUrl instead of OpenAI's API (which returned an OpenAI-worded 401). (#3136 — thanks @tjengbudi)
+- **t3-chat-web:** parse cookies + convexSessionId from the single stored credential so t3.chat web connections work (the executor previously read fields the credential pipeline never produced). (#3007 — thanks @minhtran162)
+- **minimax:** stop capping MiniMax-M3 / MiniMax-M2.7 `max_tokens` at the 8192 default — add the M3 model spec (512K output) and make model-spec lookups case-insensitive. (#3141 — thanks @totaltube)
+- **github-copilot:** discover the model catalog live from `api.githubcopilot.com/models` so Import Models refreshes and only entitled models are listed (with fallback to the static catalog). (#3120, #3121 — thanks @gabrielmoreira)
+- **combo:** invalidate the nested-combo cache on combo edits so removed targets/models stop being served within the 10s window; log the resolved DATA_DIR at startup to diagnose multi-replica volume mismatches. (#3147 — thanks @ViFigueiredo)
+- **providers:** resolve web-provider alias collisions. (thanks @diegosouzapw)
+
+### 📝 Maintenance
+
+- **deps:** bump hono from 4.12.18 to 4.12.23. (#3179 — thanks @dependabot)
+- **ci(electron):** make the macOS-arm64 smoke step best-effort (headless GPU crash). (#3137 — thanks @diegosouzapw)
+- **chore(release):** open the v3.8.10 development cycle. (thanks @diegosouzapw)
+
+---
+
+## [3.8.9] — 2026-06-03
+
+### ✨ New Features
+
+- **Obsidian context source — 24 MCP tools** (`read:obsidian` / `write:obsidian`) — search, read, write, and bidirectional sync against a local Obsidian vault via the [Local REST API community plugin](https://github.com/obsidianmd/obsidian-local-rest-api). Dashboard "Context Sources" tab, settings API, DB config. (#3077 — thanks @branben)
+- **cursor:** vision (`image_url`) input for the Cursor provider — OpenAI image parts are encoded as `SelectedContext.selected_images[]` in the `agent.v1` protobuf, plus a tool-commit directive (lifts composer-2.5's tool-call rate), `tool_choice` none/required/specific handling, and `response_format`/`max_tokens`/`stop` output constraints surfaced to the agent. Hardened with SSRF + DNS-rebinding guards, a 1 MiB pre-decode cap, and a protobuf length-overrun check. (#3104 — thanks @payne0420)
+- **deepseek-web:** opt-in persistent session + rolling-window conversation memory (`persistSession`, `historyWindow` per-connection settings) and bidirectional tool-call translation — tool schemas are injected as a system prompt and `<tool>{…}</tool>` blocks in the reply are parsed back into OpenAI `tool_calls` (replacing the old hard `400`). ([#2942](https://github.com/diegosouzapw/OmniRoute/issues/2942), [#2820](https://github.com/diegosouzapw/OmniRoute/issues/2820))
+- **i18n:** Turkish locale-aware search & sorting — a `turkishText` helper (`normalizeForSearch`, `matchesSearch`, `compareTr`) folds the dotted/dotless İ/ı correctly and uses `Intl.Collator("tr")`, wired across dashboard search/sort call-sites with an ESLint guard (warn) against raw `toLowerCase().includes()`. (#3115 — thanks @osrt91)
+- **kiro:** add Claude Opus 4.8 to the Kiro (AWS CodeWhisperer) model catalog — Kiro previously topped out at Opus 4.7 even though Opus 4.8 was already defined and served by the `claude` provider. (#3131 — thanks @artickc)
+
+### 🔧 Bug Fixes
+
+- **sse:** stop 502'ing streaming requests when a "reasoning" openai-compatible upstream ignores `stream:true` and returns a complete `application/json` body — the streaming readiness check only recognized SSE `data:` frames, so such a JSON body (even with valid `content`/`reasoning_content`) produced a spurious `STREAM_EARLY_EOF`. OmniRoute now detects a non-SSE JSON upstream body on the streaming path and synthesizes an equivalent OpenAI SSE stream (`synthesizeOpenAiSseFromJson`), preserving content + reasoning_content. ([#3089](https://github.com/diegosouzapw/OmniRoute/issues/3089))
+- **cache:** serve semantic-cache hits as SSE for streaming clients — a cache hit returned `application/json` regardless of the `stream` flag, so OpenAI-compatible streaming clients lost `reasoning_content` (and got a non-stream body) on cached responses. Stream requests now SSE-wrap the cached completion. ([#2952](https://github.com/diegosouzapw/OmniRoute/issues/2952))
+- **i18n:** fill the missing Chinese (zh-CN) and Russian (ru) UI translations — both locales were missing 9 entire sections (`quotaPlans`, `activity`, `agentBridge`, `trafficInspector`, `cliCommon`, `cliCode`, `cliAgents`, `acpAgents`, `agentSkills`, ~823 keys each) added after the last translation sweep, so those buttons/labels rendered in English. Both catalogs are now at full key parity with `en.json` (8025 keys). ([#3026](https://github.com/diegosouzapw/OmniRoute/issues/3026), [#3067](https://github.com/diegosouzapw/OmniRoute/issues/3067))
+- **dashboard:** fix "Ambiguous model" error in the provider Playground for vendor-namespaced models — the Playground only prefixed models without a `/`, so ids like `moonshotai/kimi-k2.6` or `nvidia/zyphra/zamba2-7b-instruct` (NVIDIA NIM) were sent bare and rejected when the same id exists under multiple providers. The Playground now always qualifies the selected model with its `providerId/` prefix (without double-prefixing). ([#3050](https://github.com/diegosouzapw/OmniRoute/issues/3050))
+- **db:** stop accepting duplicate API keys for the same provider — `createProviderConnection` now dedups by the decrypted key value (not just by name), so re-adding the same key under a different/blank name updates the existing connection instead of inserting a second row. Whitespace-only differences also dedup. ([#3023](https://github.com/diegosouzapw/OmniRoute/issues/3023))
+- **dashboard:** "Import from /models" now works for no-auth providers (e.g. OpenCode Free) — the button used to silently no-op because no-auth providers have no connection row, so `handleImportModels` returned early and the models route 404'd. The route now serves the provider's model catalog when called with a no-auth provider id, and the dashboard falls back to the provider id when there is no connection. ([#3047](https://github.com/diegosouzapw/OmniRoute/issues/3047))
+- **providers:** forward Grok's paired `sso-rw` cookie for grok-web — both the executor and the connection validator now send `sso=…; sso-rw=…` (via the new `buildGrokCookieHeader` helper) when the pasted blob carries `sso-rw`, fixing the `403` _"Request rejected by anti-bot rules"_ that Grok returns for `sso` alone. The add-account hint now asks for the full cookie line. ([#3063](https://github.com/diegosouzapw/OmniRoute/issues/3063))
+- **providers:** fix claude-web persistent 403 — `execute()` was calling the synchronous `normalizeClaudeSessionCookie()` which never injects `cf_clearance`; changed to async `normalizeClaudeSessionCookieWithAutoRefresh()` with `allowAutoSolve:true`. Also removes dead executor `claude-web-auto-refresh.ts` and correctly reclassifies `duckduckgo-web` and `veoaifree-web` as `NOAUTH_PROVIDERS`. (#3090 — thanks @oyi77)
+- **autoCombo:** rotate across all provider connections, never waste capacity — `buildAutoCandidates` now expands each provider into one candidate per active connection (e.g. 43 Cerebras keys → 43 candidates). Adds `ScoreTierRotator` with per-combo round-robin state, combo-name-aware tier preferences (smart/fast/cheap/coding), `connectionDensity` factor (weight 0.05), and budget-cap degradation using the rotator. (#3078 — thanks @oyi77)
+- **providers:** fix SiliconFlow model sync from configured endpoint — routes model discovery through `providerSpecificData.baseUrl` so CN (`api.siliconflow.cn`) vs Global endpoint selection is respected, and prevents `/sync-models` from treating `source: "local_catalog"` fallback responses as successful remote syncs. (#3094 — thanks @xz-dev)
+- **resilience:** a per-model subscription/permission `403` from a passthrough provider (e.g. Ollama Cloud `deepseek-v4-pro` → _"this model requires a subscription"_) now locks out **only that model** instead of cooling down the whole connection — the free models on the same key keep serving, and repeated paid-model 403s no longer escalate a connection-wide backoff. Generalizes the grok-web 403 precedent to all `hasPerModelQuota` providers; terminal/credential 403s (banned/deactivated key) still deactivate the connection. ([#3027](https://github.com/diegosouzapw/OmniRoute/issues/3027))
+- **cache:** preserve client-side `cache_control` breakpoints for Xiaomi MiMo — added `xiaomi-mimo` to the prompt-caching provider allowlist so Claude Code (via cc-switch) cache hints are no longer stripped by the OpenAI-format translator, restoring cache hits. ([#3088](https://github.com/diegosouzapw/OmniRoute/issues/3088))
+- **tools:** keep opaque object schemas open — empty object schemas (and the `web_search` passthrough shim) now get `additionalProperties: true` so GPT-5.5/Codex stop pruning untyped nested payloads (e.g. `SPLOX_EXECUTE_TOOL.args`). (#3097 — thanks @nmime)
+- **codex:** preserve native Responses passthrough tools and history — `tool_search` and `custom` tools (e.g. `apply_patch`) survive `normalizeCodexTools`, and `phase:"commentary"` history items are kept, only on the native passthrough path (`_nativeCodexPassthrough`). (#3107 — thanks @yinaoxiong)
+- **responses:** resolve bare ChatGPT model ids (e.g. `gpt-5.5`) to `codex/…` on the `/v1/responses` HTTP fallback path, fixing the Codex CLI WS→HTTP fallback that was routing to a credential-less provider (#3113).
+- **sse:** bound the Antigravity 429 short-retry loop (per-URL `MAX_AUTO_RETRIES` guard — no more infinite loop on a persistent 429) and lock quota-exhausted accounts for the full "Resets in XhYmZs" window via model lockout. (#3122 — thanks @ahmet-cetinkaya)
+- **image-gen:** add an AbortController timeout to `fetchImageEndpoint` so a stuck image provider surfaces a `504` instead of hanging until the server timeout. (#3105 — thanks @mgarmash)
+- **logs (perf):** fix browser freeze and network saturation on `/dashboard/logs` — smaller page size, 15s polling, pause polling on a hidden tab / past the first page, and memoized derived lists. (#3109 — thanks @0xtbug)
+- **cli:** handle Windows `.exe` healthchecks with spaces in the path — direct executables skip the shell (so `cmd.exe` doesn't split `C:\…\Name With Spaces\…\claude.exe`) while `.cmd`/`.bat` wrappers still run through it. (#3111 — thanks @EmpRider)
+- **cli:** don't write `STORAGE_ENCRYPTION_KEY` to `.env` on informational commands — `omniroute --version`/`--help` no longer generate a key or create `~/.omniroute/.env`; provisioning is scoped to commands that actually touch encrypted storage (#3129).
+- **tests:** remove a stale lowercase `db-apikeys-crud.test.ts` duplicate that collided with the canonical `db-apiKeys-crud.test.ts` on case-insensitive filesystems (no coverage lost). (#3125 — thanks @juandisay)
+- **kimi:** add a dedicated `KimiExecutor` so Kimi thinking-mode responses no longer drop `reasoning_content` — the reasoning stream is now surfaced instead of being lost. (#3132 — thanks @bypanghu)
+- **handler:** provide a `connectionId` fallback when it is undefined, fixing kilo (kilocode) calls that were silently not being written to `call_logs`. (#3130 — thanks @androw)
+
+### 🔧 Build
+
+- **build-output-isolation:** unified standalone assembly into one shared `assembleStandalone` module; isolated build output into `.build/` (intermediates, gitignored) and `dist/` (shippable bundle, gitignored), replacing the old repo-root `app/` and `.next/` directories; dropped the duplicate `next build` that prepublish previously ran; added `build:release` script for a clean rebuild with a `dist/BUILD_SHA` HEAD sentinel that guards against deploying stale bundles. **Operators using custom `app/` paths:** the published bundle directory on the VPS image (`/usr/lib/node_modules/omniroute/app/`) is unchanged — only the in-repo build output path moved. Update any local scripts that reference the repo-local `app/` build output to `dist/` instead.
+- **build:** re-apply the build-reorg follow-ups that landed after the main refactor merged — the `serve` CLI now falls back from `dist/` to the legacy `app/` location for upgrade safety, and the deploy skills `pm2 stop` before `rsync --delete` to avoid a transient `Cannot find module ./chunks/…` race (#3127).
+- **build:** fix the standalone static-asset path so the dashboard renders after the build-output reorg — `assembleStandalone` was copying `static/` into `<bundle>/.next/static`, but the standalone server (built with `distDir=.build/next`) serves `/_next/static` from `<bundle>/.build/next/static`, so every JS/CSS chunk 404'd and the login UI rendered as a blank page. The static (and `required-server-files.json` / Turbopack chunk) destinations are now derived from the configured `distDir` instead of a hard-coded `.next`.
+
+### 📦 Dependencies
+
+- **electron:** bump to 42.3.2 (crash fix desktopCapturer, Chromium 148.0.7778.218, ThinLTO perf) (#3083)
+- **electron-updater:** bump to 6.8.8 (security: harden auto-update flow against path traversal and env var intercepts) (#3084)
+- **electron-builder:** bump to 26.14.0 (security hardening, pure-JS blockmap/icon migration) (#3082)
+- **dev deps:** bump eslint-config-next 16.2.7, lint-staged 17.0.7, typescript-eslint 8.60.1, vitest 4.1.8 (#3086)
+- **prod deps:** bump next 16.2.7, react/react-dom 19.2.7, tsx 4.22.4, ws 8.21.0, parse5 8.0.1, commander 15.0.0, and 15 other packages (#3085)
+
+### 🙌 Contributors
+
+Huge thanks to everyone whose work shipped in v3.8.9:
+
+@branben (Obsidian context source), @oyi77 (claude-web 403 fix, autoCombo connection rotation), @xz-dev (SiliconFlow model sync), @nmime (open opaque tool schemas), @payne0420 (Cursor vision input), @mgarmash (image-gen fetch timeout), @yinaoxiong (Codex native passthrough tools/history), @0xtbug (logs page perf), @EmpRider (Windows CLI healthcheck paths), @ahmet-cetinkaya (Antigravity 429 retry bound + quota lockout), @juandisay (duplicate test cleanup), @osrt91 (Turkish locale-aware search & sorting), @artickc (Kiro Opus 4.8 catalog), @bypanghu (Kimi thinking-mode reasoning_content fix), and @androw (connectionId fallback + kilo call logging).
+
+And thank you to the OmniRoute community for the bug reports, reproductions, and testing that drove these fixes. 🎉
+
+---
+
 ## [3.8.8] — 2026-06-03
 
 ### Added
@@ -1630,7 +2214,7 @@ Thank you to all **55+ community contributors** who made v3.8.0 possible! 🎉
 
 ### 🧹 Chores
 
-- **chore(workflow):** mandate implementation plan generation in `/resolve-issues` workflow before coding
+- **chore(workflow):** mandate implementation plan generation in `/review-issues` workflow before coding
 - **chore(release):** expand contributor credits to 155 PRs across full project history
 
 ### 🏆 Community Contributors Acknowledgment

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 (40/40/40/40 — 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
 ```
@@ -366,14 +366,23 @@ 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` (40/40/40/40 — 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 40% (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.
+**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 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.
 
 ---
 
@@ -419,7 +428,7 @@ 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 ≥40% (statements, lines, functions, branches).
+9. Coverage must stay ≥60% (statements, lines, functions, branches).
 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`.
@@ -428,6 +437,7 @@ git push -u origin feat/your-feature
 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 that credit an AI assistant, LLM, or automation account (e.g. names containing "Claude", "GPT", "Copilot", "Bot"; emails at `anthropic.com` / `openai.com` / bot-owned `noreply.github.com` addresses). Such trailers route attribution to the bot account on GitHub, hiding the real author (`diegosouzapw`) in PR history. 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.
 
 ---
 

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`
@@ -314,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

Dockerfile

@@ -42,7 +42,7 @@ RUN --mount=type=cache,target=/root/.npm \
 ENV OMNIROUTE_USE_TURBOPACK=1
 
 COPY . ./
-RUN --mount=type=cache,target=/app/.next/cache \
+RUN --mount=type=cache,target=/app/.build/next/cache \
   mkdir -p /app/data && npm run build
 
 # ── Runner base ────────────────────────────────────────────────────────────
@@ -64,25 +64,27 @@ ENV NODE_OPTIONS="--max-old-space-size=${OMNIROUTE_MEMORY_MB}"
 ENV DATA_DIR=/app/data
 RUN mkdir -p /app/data
 
-# The standalone build + syncStandaloneExtraModules bundles all runtime files
-# (.next, node_modules, migrations, scripts, docs, etc.) into .next/standalone/.
-# Explicit overrides below cover modules that NFT tracing may miss.
-COPY --from=builder /app/.next/standalone ./
-# Explicitly copy @swc/helpers — not always traced by standalone output but needed at runtime
-COPY --from=builder /app/node_modules/@swc/helpers ./node_modules/@swc/helpers
-# Explicitly copy better-sqlite3 — native bindings are not reliably traced by
-# Next.js standalone output, but bootstrap-env requires SQLite before startup.
+# `npm run build` (build-next-isolated → assembleStandalone) bundles ALL runtime
+# files into .build/next/standalone/ — .next, node_modules, migrations, scripts,
+# docs, and the previously hand-COPY'd modules below (@swc/helpers, pino-*, split2,
+# migrations). assembleStandalone copies them straight from the builder's
+# node_modules, so they are present regardless of NFT/Turbopack trace behaviour.
+# The old per-module overrides were therefore pure duplication and were removed
+# (build-output-isolation cleanup). See scripts/build/assembleStandalone.mjs
+# (EXTRA_MODULE_ENTRIES) for the single source of truth.
+COPY --from=builder /app/.build/next/standalone ./
+# better-sqlite3 is the one exception still copied explicitly: assembleStandalone
+# only syncs its native build/ dir; the JS wrapper (lib/, package.json) is left to
+# Next.js tracing. bootstrap-env requires SQLite BEFORE the standalone server
+# starts, so guarantee the complete package independent of trace behaviour.
 COPY --from=builder /app/node_modules/better-sqlite3 ./node_modules/better-sqlite3
-# Explicitly copy pino transport dependencies — pino spawns a worker that requires
-# pino-abstract-transport at runtime; Next.js standalone trace does not capture it (#449)
-COPY --from=builder /app/node_modules/pino-abstract-transport ./node_modules/pino-abstract-transport
-COPY --from=builder /app/node_modules/pino-pretty ./node_modules/pino-pretty
-COPY --from=builder /app/node_modules/split2 ./node_modules/split2
-# Migration SQL files are read via fs.readFileSync at runtime and are NOT
-# traced by Next.js standalone output — copy them explicitly.
-COPY --from=builder /app/src/lib/db/migrations ./migrations
+# migrations land at <standalone>/migrations via assembleStandalone; point the runtime at them.
 ENV OMNIROUTE_MIGRATIONS_DIR=/app/migrations
 
+# Docker healthcheck script — not traced by Next.js standalone output, so copy
+# it explicitly. The HEALTHCHECK CMD references it as `node healthcheck.mjs`.
+COPY --from=builder /app/scripts/dev/healthcheck.mjs ./healthcheck.mjs
+
 # Hand /app over to the baked-in `node` non-root user (UID/GID 1000) so the
 # runtime process never holds root privileges. The chown happens after all
 # COPYs so it covers files originally owned by root in the builder stage.
@@ -122,6 +124,14 @@ FROM runner-base AS runner-web
 
 USER root
 
+# Copy playwright and playwright-core from the builder stage.
+# The slim runtime image does not have playwright in node_modules, so npx falls
+# back to a registry download — unreliable on CI runners (exits 127 on failure).
+# Copying from the builder avoids any network access at image-build time and also
+# ensures the same playwright version is available at runtime for web-session providers.
+COPY --from=builder /app/node_modules/playwright-core ./node_modules/playwright-core
+COPY --from=builder /app/node_modules/playwright ./node_modules/playwright
+
 # Install Playwright browser binaries + OS dependencies under root, then hand
 # ownership of the browsers cache to the node user.
 # PLAYWRIGHT_BROWSERS_PATH overrides the default ~/.cache/ms-playwright so the
@@ -131,7 +141,7 @@ ENV PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright
 RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
   --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \
   apt-get update \
-  && npx playwright install chromium --with-deps \
+  && node node_modules/playwright/cli.js install chromium --with-deps \
   && chown -R node:node /home/node/.cache \
   && rm -rf /var/lib/apt/lists/*
 

ONBOARDING.md

@@ -1,72 +0,0 @@
-# Welcome to OmniRoute
-
-## How We Use Claude
-
-Based on diegosouzapw's usage over the last 30 days:
-
-Work Type Breakdown:
-Build Feature ████████████████████ 50%
-Plan Design ██████████░░░░░░░░░░ 25%
-Improve Quality ██████░░░░░░░░░░░░░░ 15%
-Write Docs ████░░░░░░░░░░░░░░░░ 10%
-
-Top Skills & Commands:
-_no slash commands captured in this window_
-
-Top MCP Servers:
-_no MCP usage captured in this window_
-
-## Your Setup Checklist
-
-### Codebases
-
-- [ ] omniroute — https://github.com/diegosouzapw/omniroute
-- [ ] OpenCode_Ecosystem (fork) — https://github.com/diegosouzapw/OpenCode_Ecosystem
-- [ ] OpenCode_Ecosystem (upstream) — https://github.com/MarceloClaro/OpenCode_Ecosystem
-
-### MCP Servers to Activate
-
-- [ ] _none required from current usage. If you'll be working on OmniRoute itself, ask the team about the project's own embedded MCP server at `/api/mcp/stream`._
-
-### Skills to Know About
-
-- _no skills surfaced from usage data. The team's workflow leaned heavily on direct file edits, git/gh CLI, and subagent dispatch for parallel work — Claude figures these out from context._
-
-## Team Tips
-
-- **Read `CLAUDE.md` first.** It has hard rules that override defaults — e.g. never write raw SQL in routes (use `src/lib/db/` modules), never add `Co-Authored-By: Claude` to commits, error responses must go through `buildErrorBody()` / `sanitizeErrorMessage()`.
-- **Subagents for parallel work.** When tasks are independent, dispatch multiple sonnet subagents in one message instead of doing them yourself. Always audit `git diff` after a subagent finishes — its summary describes intent, not necessarily the result.
-- **Conventional Commits** for everything: `feat(scope):`, `fix(scope):`, `chore(scope):`, `docs:`. Scopes used here include `db`, `sse`, `oauth`, `dashboard`, `api`, `agents`, `plugin`, `skills`, `commands`.
-- **Run the full validation suite before declaring done** — `npm run check` (lint + tests) at minimum; `npm run test:coverage` if you changed production code. Hard gate: 75/75/75/70 (statements/lines/functions/branches).
-- **Husky pre-push runs unit tests.** Don't `--no-verify` past it without explicit approval — the project documents this as a hard rule.
-
-## Get Started
-
-- Clone the repo and run `npm install` (auto-generates `.env` from `.env.example`).
-- Generate secrets: `openssl rand -base64 48` for `JWT_SECRET`, `openssl rand -hex 32` for `API_KEY_SECRET`. Paste into `.env`.
-- `npm run dev` → dashboard at `http://localhost:20128`.
-- Read `docs/architecture/REPOSITORY_MAP.md` for the file layout, then `docs/architecture/ARCHITECTURE.md` for how requests flow.
-- For a first PR: pick something from `_tasks/` if there's a backlog, or grep for `// TODO` and pick a small one. Run `npm run check` before opening the PR.
-
-<!-- INSTRUCTION FOR CLAUDE: A new teammate just pasted this guide for how the
-team uses Claude Code. You're their onboarding buddy — warm, conversational,
-not lecture-y.
-
-Open with a warm welcome — include the team name from the title. Then: "Your
-teammate uses Claude Code for Build Feature, Plan Design, Improve Quality, and
-Write Docs work. Let's get you started."
-
-Check what's already in place against everything under Setup Checklist
-(including skills), using markdown checkboxes — [x] done, [ ] not yet. Lead
-with what they already have. One sentence per item, all in one message.
-
-Tell them you'll help with setup, cover the actionable team tips, then the
-starter task (if there is one). Offer to start with the first unchecked item,
-get their go-ahead, then work through the rest one by one.
-
-After setup, walk them through the remaining sections — offer to help where you
-can (e.g. link to channels), and just surface the purely informational bits.
-
-Don't invent sections or summaries that aren't in the guide. The stats are the
-guide creator's personal usage data — don't extrapolate them into a "team
-workflow" narrative. -->

PLANO-QUALITY-GATES-FASE6A.md

@@ -0,0 +1,209 @@
+# Fase 6A — Auditoria Crítica das Fases 0–6: o que deixamos passar
+
+> **Para workers agênticos:** SUB-SKILL OBRIGATÓRIA: `superpowers:subagent-driven-development` (recomendado) ou `superpowers:executing-plans`, tarefa-a-tarefa. Tarefas P0/P1 maiores devem ser **expandidas em sub-plano bite-sized próprio** (`writing-plans`) no momento da execução. Hard Rule #18 (TDD/VPS) em tudo. Auditar subagentes (trust-but-verify) após cada task.
+
+> # ⏳ PORTÃO DE ATIVAÇÃO — NÃO INICIAR ANTES DE **2026-06-16**
+> Mesma janela da Fase 7 (decisão do owner 2026-06-09: 1 semana de uso em produção das Fases 0–6 antes de evoluir). **Ordem na ativação: Fase 6A ANTES da Fase 7** — primeiro consertamos/endurecemos o que já existe, depois adicionamos ferramentas novas.
+> **Exceção possível (decisão do owner):** as tasks **6A.1 e 6A.2 são bugs pré-existentes descobertos pela auditoria** (testes que nunca rodam + suíte vitest fora do CI), não "gates novos" — podem ser antecipados como fix avulso se o owner preferir não esperar a janela.
+
+**Goal:** Fechar os furos que a auditoria crítica pós-implementação (2026-06-09, análise inline dos 18 gates + motor + CI + baselines) encontrou nas Fases 0–6 — antes de adicionar qualquer ferramenta nova na Fase 7.
+
+**Architecture:** Zero ferramenta nova (tudo homegrown, padrão `check-*.mjs` + motor existente). Três frentes: (1) **bugs sistêmicos de runner** descobertos (testes órfãos, vitest fora do CI); (2) **endurecimento do padrão de catraca** (stale-allowlist enforcement + require-tighten, validados pela prática da Notion); (3) **expansão de escopo** dos gates existentes (diretórios/superfícies que ficaram de fora).
+
+**Tech Stack:** Node ≥20 ESM, ESLint 9 flat, c8, jscpd@4 (a pinar), GitHub Actions, Node native test runner, vitest. Nada novo em `dependency-allowlist.json` exceto a promoção do jscpd a devDependency (Task 6A.12).
+
+---
+
+## Origem: o que a auditoria encontrou (resumo dos achados)
+
+Método: releitura inline de todos os `scripts/check/*.{mjs,ts}` criados nas Fases 0–6, `scripts/quality/*`, baselines, `ci.yml`, `package.json`, hooks Husky e docs — sem subagentes — mais validação por pesquisa (sistema de ratcheting da Notion; práticas de suppression-hygiene de linters).
+
+| # | Achado | Gravidade | Task |
+|---|--------|-----------|------|
+| A1 | **≈135 arquivos `*.test.ts` em subdiretórios de `tests/unit/` não são coletados por NENHUM runner** — `test:unit`, `test:coverage` e os shards do CI usam o glob não-recursivo `tests/unit/*.test.ts`; o vitest só inclui `autoCombo/**` (+ `.tsx`). Inclui `authz/routeGuard.test.ts` (Hard Rules #15/#17), 50 testes de `compression/`, 12 de `services/`, 10 de `gamification/`, 6 de `guardrails/`, 5 de `security/`. **Amostra rodada na auditoria: 2 asserts de `routeGuard.test.ts` FALHAM hoje** ("management policy allows /api/services/ (e /api/copilot/chat) from localhost with valid CLI token") — o arquivo apodreceu sem ninguém ver, provavelmente desde o redesign do peer-stamp (2026-05-31) | **P0 — falso verde sistêmico** | 6A.1 |
+| A2 | **Nenhum workflow roda `test:vitest`** (`grep -rln vitest .github/workflows/` = vazio). O CLAUDE.md afirma "Both test runners must pass… before merging", mas a suíte vitest (MCP server 43 tools, autoCombo, cache, componentes) está 100% fora da esteira | **P0** | 6A.2 |
+| B1 | **Nenhum gate falha quando uma entrada de allowlist deixa de ser necessária.** Os 18 gates congelam ~90 violações em `KNOWN_*`; quando alguém corrige a violação (ex.: criar `/api/gamification/level` da issue #3484, remover `krutrim` da #3483), a entrada vira um furo aberto — a regressão pode VOLTAR sem revisão. Só `check-error-helper` tem detecção parcial (WARN de arquivo inexistente, que ninguém lê). Prática validada: linters maduros "yell when an exclusion exists that doesn't break the rule" | **P0 — corrói a catraca com o tempo** | 6A.3 |
+| B2 | **Melhoria não-capturada vira folga permanente no motor**: sem `--update` manual, uma métrica que melhorou pode regredir de volta até o baseline antigo sem ninguém ver. A Notion auto-decrementa budgets no pre-commit; nosso motor não exige aperto | P1 | 6A.5 |
+| B3 | EPS único (0.01) para todas as métricas; o plano da Fase 4 pedia epsilon maior para `coverage.branches` (não-determinismo do v8) e não foi implementado | P1 | 6A.5 |
+| B4 | Métrica coletada sem entrada no baseline é ignorada em silêncio (coletor novo esquecido do baseline = falso conforto) | P2 | 6A.5 |
+| C1 | `check-fetch-targets` só varre `src/app/(dashboard)` — **20+ arquivos com `fetch("/api/…")` fora do escopo**: `src/shared/components/` (Sidebar, CommandPalette, modais…), `src/app/connect/`, `src/app/status/`, `src/lib/evals/` | P1 | 6A.7 |
+| C2 | `check-fetch-targets` ignora 100% dos template literals (`` fetch(`/api/x/${id}`) ``) — nem o prefixo estático é validado | P1 | 6A.7 |
+| C3 | `check-fetch-targets` não valida o método HTTP (fetch `POST` → rota só com `GET` = 405 em runtime, gate verde) | P2 | 6A.7 |
+| C4 | `check-deps` cobre só `package.json` raiz + `electron/` — **`@omniroute/opencode-plugin` (dep `zod` + 5 devDeps, pacote PUBLICADO no npm), `@omniroute/opencode-provider` e `open-sse/` ficam fora** | P1 | 6A.8 |
+| C5 | `check-public-creds` escaneia só 2 arquivos hardcoded — credencial literal em arquivo NOVO (executor, oauth provider) passa batida | P1 | 6A.8 |
+| C6 | `check-error-helper` cobre `open-sse/executors` + `handlers` — a Hard Rule #12 também fala de **MCP handlers** (`open-sse/mcp-server/`) e rotas HTTP (`src/app/api/`), fora do escopo | P1 | 6A.8 |
+| C7 | `check-file-size` e `check-complexity` varrem `src` + `open-sse` — `electron/` e `bin/` fora (god-file pode nascer lá) | P2 | 6A.11 |
+| C8 | `check-known-symbols` cobre executors/strategies/translators — **faltam as 3 superfícies de despacho por-string restantes: MCP tools (43), A2A skills (5, `A2A_SKILL_HANDLERS`), cloud agents (3, registry)** | P1 | 6A.9 |
+| C10 | `check-route-guard-membership` depende da lista manual `SPAWN_CAPABLE_ROUTE_ROOTS` (3 raízes) — rota nova que spawna processo FORA dessas raízes é invisível ao gate | P1 | 6A.8 |
+| C11 | `check-openapi-coverage` (THRESHOLD=36%) e `check-ui-keys-coverage` (65%) são pisos fixos manuais — não ratcheteiam; rotas/strings novas sem doc/i18n passam enquanto o % não cai do piso | P2 | 6A.11 |
+| C12 | `check-test-masking`: (a) `--diff-filter=M` não vê teste **DELETADO** (o masking mais brutal); (b) não vê `.skip`/`.todo`/`.only` adicionados (mantêm os asserts no texto, mas nunca rodam); (c) tautologia só cobre `assert.ok(true)` | P1 | 6A.10 |
+| D1 | **`ci.yml` roda gates apenas em `pull_request → main`** — todo o ciclo de PRs feature→`release/vX` passa SEM gate; as violações acumulam por semanas e estouram juntas no merge release→main (observado no gate da v3.8.18: 4 fixes de typecheck + ReDoS de última hora) | P1 — decisão do owner | 6A.6 |
+| D2 | `.husky/pre-push` está 100% comentado, mas o CLAUDE.md afirma "pre-push: npm run test:unit" (drift doc↔real) | P2 | 6A.12 |
+| D3 | **CLAUDE.md não menciona nenhum dos 18 gates** — um agente futuro não sabe que existem, qual a política de allowlist ("corrija, não congele"), nem como apertar baselines. Hard Rule #9 ainda diz "≥60%" (a catraca real é 80/80/82/73) | **P0 — anti-alucinação para os próprios agentes** | 6A.4 |
+| D4 | `check-duplication` roda `npx --yes jscpd@4` — pacote **não pinado por lockfile**, baixado do registry a cada run do CI (supply-chain + flakiness + latência); contraria o espírito do próprio `check-deps` | P2 | 6A.12 |
+| D5 | A skill `/quality-scan` roda ~20 comandos um a um — falta um runner agregador paralelo | P2 | 6A.12 |
+| D6 | Baselines de coverage com folga de ~2,5pt (80/80/82/73 vs real ~82,6/82,6/84,2/75,2) — a nota "_aperte após o 1º run verde_" existe no JSON mas não é tarefa de ninguém | P1 | 6A.5 |
+| E4 | Sem guarda contra artefato trackeado por engano — `node_modules` symlink já foi commitado 2× neste repo (`git add -A` em worktree) | P2 | 6A.12 |
+
+**Decisões conscientes de NÃO fazer (avaliadas e descartadas, com motivo):**
+- **Gate de idempotência de migrations via regex** — SQLite não tem `ADD COLUMN IF NOT EXISTS`; idempotência vive em try/catch do runner; regex seria frágil (FP/FN). O `check-migration-numbering` + revisão humana bastam.
+- **Endurecer `check-docs-counts-sync` para fail** — contagens em prosa são heurísticas; soft-fail é o design correto. A cobertura de MCP tools entra pela 6A.9 (símbolos, não prosa).
+- **Sentido inverso do provider-consistency (providers.ts → REGISTRY)** — muitos providers canônicos legitimamente não têm entrada no REGISTRY (web/OAuth-only); a allowlist nasceria com dezenas de entradas e baixa razão sinal/ruído. Reavaliar quando o refactor #3501 tocar o split de providers.
+- **Complexidade por-função/por-arquivo (formato any-budget)** — upgrade real, mas o count global + `max-lines-per-function` já bloqueiam o grosso; o formato per-file entra junto com `sonarjs/cognitive-complexity` na Fase 7 Task 5 para não pagar duas migrações de baseline.
+
+---
+
+# Tasks
+
+## P0 — bugs sistêmicos + documentação
+
+### Task 6A.1 — `check-test-discovery` + religamento triado dos ~135 testes órfãos ⭐
+
+**O achado nº1 da auditoria.** Testes que não rodam são o falso verde definitivo — todo o investimento anti test-masking da Fase 4 protege asserts de testes que **nem executam**.
+
+**Files:**
+- Create: `scripts/check/check-test-discovery.mjs` + `tests/unit/check-test-discovery.test.ts`
+- Modify: `package.json` (globs de `test:unit`, `test:coverage`), `.github/workflows/ci.yml` (globs dos shards 8×/node24/node26), `vitest.mcp.config.ts` ou `vitest.config.ts` (se algum subdir for re-homed para vitest)
+- Create: `test-discovery-baseline.json` (órfãos ainda-não-religados, catraca `down` até zerar)
+
+**Approach (expandir em sub-plano na execução):**
+1. **Gate primeiro (TDD):** `check-test-discovery.mjs` enumera todo `**/*.{test,spec}.{ts,tsx}` do repo (fora de `node_modules`/`.next`) e verifica que cada arquivo é coletado por ≥1 runner: (a) globs do node test runner extraídos de `package.json`/`ci.yml`; (b) `include` dos dois `vitest.*config.ts`; (c) projetos Playwright. Órfão fora do baseline → exit 1. O baseline congela os órfãos atuais (catraca: não pode SUBIR; religamentos a fazem cair até `{}`).
+2. **Inventário verde/vermelho:** rodar cada subdir órfão isoladamente (`node --import tsx --test tests/unit/<dir>/*.test.ts`), registrar passa/falha. *Não* ligar tudo de uma vez — a amostra já provou que há vermelhos (`authz/routeGuard.test.ts`: 2 asserts).
+3. **Religar os verdes:** trocar o glob principal para recursivo — `"tests/unit/**/*.test.ts"` ENTRE ASPAS (expandido pelo test runner do Node, não pelo shell; **Step 0: validar o suporte a glob do runner na menor versão de Node suportada pelo repo** — fallback: listar os subdirs explicitamente) — em `test:unit`, `test:coverage` e nos 3 lugares do `ci.yml` (shards 8×, node24, node26). Remover religados do baseline.
+4. **Triar os vermelhos (Hard Rule #18 em cada um):** teste desatualizado → atualizar para o comportamento real (e provar que o comportamento real é o desejado); bug real revelado → fix TDD; teste de feature morta → deletar com justificativa no commit. Os 2 asserts do `routeGuard.test.ts` ("allows … with valid CLI token") são o primeiro caso: provável drift do peer-stamp de 2026-05-31 — MAS, por ser superfície de segurança (#15/#17), confirmar com cuidado que é o teste que está errado, não o guard.
+5. **Recalibrar cobertura:** religar ≈135 arquivos muda o denominador/numerador da cobertura — re-medir e apertar `quality-baseline.json` via `--update` no mesmo PR (resolve também o D6).
+
+**Acceptance:** `check-test-discovery` no CI (job lint); zero órfãos fora do baseline; baseline decrescente documentado; suíte verde com os religados; cobertura recalibrada.
+
+### Task 6A.2 — vitest no CI
+
+**Files:** `.github/workflows/ci.yml` (job novo `test-vitest`, paralelo aos shards; NÃO tocar nos triggers — apenas adicionar job).
+
+**Approach:** job com `npm ci` + `npm run test:vitest` (+ `test:vitest:ui` se o tempo couber; senão segundo step). Rodar localmente primeiro para garantir verde (a suíte passa hoje fora da esteira — confirmar). Se houver vermelho pré-existente, triagem antes do wire (mesmo protocolo da 6A.1 passo 4).
+
+**Acceptance:** PR→main roda as DUAS suítes; o claim do CLAUDE.md ("both must be green") vira verdade mecânica.
+
+### Task 6A.3 — Stale-allowlist enforcement em todos os gates (suppression hygiene)
+
+**O endurecimento sistêmico nº1.** Padrão validado (ESLint `--report-unused-disable-directives`; Notion): exclusão que não exclui nada vivo é dívida fantasma e furo de regressão.
+
+**Files:** todos os gates com allowlist + seus testes:
+`check-fetch-targets` (KNOWN_MISSING, 7) · `check-provider-consistency` (KNOWN_REGISTRY_ONLY, 1) · `check-openapi-routes` (KNOWN_STALE_SPEC, 1) · `check-public-creds` (KNOWN_LITERAL_CREDS, 5) · `check-db-rules` (KNOWN_UNEXPORTED 25 + KNOWN_RAW_SQL 15) · `check-docs-symbols` (KNOWN_STALE_DOC_REFS, 30) · `check-migration-numbering` (KNOWN_GAPS/DUPLICATES) · `check-error-helper` (KNOWN_MISSING_ERROR_HELPER, 7 — promover o WARN existente a FAIL e cobrir também "arquivo existe mas não viola mais") · `check-deps` (dependency-allowlist: entrada sem dep correspondente em manifest algum = stale) · `check-file-size` (entrada `frozen` cujo arquivo foi deletado/renomeado) · `check-route-guard-membership` (KNOWN_UNCLASSIFIED — vazio hoje; implementar o check para quando deixar de ser).
+
+**Approach (mecânica única, TDD por gate):** após a detecção normal, re-avaliar cada entrada da allowlist: *"se esta entrada não existisse, o gate flagaria algo?"* — para allowlists de path/valor isso é `violationsDetectadas.has(entry)`; para arquivos, existência + violação presente. Entrada que não suprime nada → **exit 1** com mensagem `entrada obsoleta — a violação foi corrigida; REMOVA a entrada para travar a correção`. Extrair helper comum `reportStaleEntries(allowlist, liveViolations, gateName)` em `scripts/check/lib/allowlist.mjs` para não duplicar 11×.
+
+**Acceptance:** corrigir qualquer violação congelada (ex.: as issues #3483–#3501) passa a EXIGIR a remoção da entrada no mesmo PR; teste sintético prova fail-on-stale em cada gate.
+
+### Task 6A.4 — Documentar os gates no CLAUDE.md (+ corrigir drifts de doc)
+
+**Files:** `CLAUDE.md`, `AGENTS.md` (se houver seção espelho), `docs/architecture/` (página `QUALITY_GATES.md` referenciada pela tabela de docs).
+
+**Approach:** (1) seção nova "Quality Gates & Ratchets" no CLAUDE.md: tabela dos gates (nome → o que trava → allowlist/baseline), a política **"corrija a causa; allowlist só com justificativa + issue"**, como apertar (`npm run quality:ratchet -- --update`, `check:<gate> -- --update`), e o que fazer quando um gate falha num PR. (2) Corrigir: Hard Rule #9 (60% → "catraca de cobertura: nunca abaixo do baseline congelado em `quality-baseline.json`; piso absoluto 60"), claim do pre-push (refletir o real pós-6A.12), claim "both runners" (verdade pós-6A.2). (3) Página `docs/architecture/QUALITY_GATES.md` com o detalhe operacional (o CLAUDE.md fica curto, linka). Rodar `check:docs-all` após editar (o próprio docs-sync valida).
+
+**Acceptance:** agente novo lendo o CLAUDE.md descobre os gates e a política sem ler scripts; `check:docs-all` verde.
+
+## P1 — endurecimento do motor + escopos
+
+### Task 6A.5 — Motor v2: `--require-tighten`, eps por métrica, métricas órfãs
+
+**Files:** `scripts/quality/check-quality-ratchet.mjs`, `quality-baseline.json` (schema), `tests/unit/quality-ratchet.test.ts`, `.github/workflows/ci.yml` (flag no job quality-gate).
+
+**Approach (TDD):**
+1. Schema por métrica ganha campos opcionais: `eps` (default 0.01) e `tightenSlack` (default: igual a `eps`).
+2. Novo modo `--require-tighten` (ligado no CI): se `atual` melhor que `baseline` além de `tightenSlack`, **exit 1** com `melhorou de X para Y — rode 'npm run quality:ratchet -- --update' e commite o baseline apertado neste PR`. Métricas determinísticas (`eslintWarnings`) usam slack 0; cobertura usa slack 1.5 (flutuação v8). É o "auto-decrement" da Notion adaptado a CI sem bot de commit.
+3. Warning para métricas presentes em `quality-metrics.json` sem entrada no baseline (coletor órfão).
+4. Calibrar os 4 `coverage.*` para o real medido (fecha D6 — coordenar com a 6A.1 passo 5, que muda a base).
+
+**Acceptance:** melhoria sem aperto de baseline falha no CI; flutuação de coverage dentro do slack não falha; testes cobrem os 3 comportamentos novos.
+
+### Task 6A.6 — `quality.yml`: gates rápidos em PRs → `release/**` ⚠️ DECISÃO DO OWNER
+
+**Contexto sensível:** o owner já reverteu mudança de trigger no `ci.yml` ("não mexe na CI"). Esta task **não toca o `ci.yml`** — cria um workflow NOVO e enxuto. Ainda assim, **passo 0 = confirmação explícita do owner**.
+
+**Files:** Create: `.github/workflows/quality.yml`.
+
+**Approach:** `on: pull_request: branches: ["release/**"]`; um job único (~1–2 min) só com os gates determinísticos filesystem-only: provider-consistency, fetch-targets, openapi-routes, docs-symbols, deps, file-size, error-helper, migration-numbering, public-creds, db-rules, known-symbols, route-guard-membership, test-discovery (pós-6A.1) + `check:any-budget:t11`. SEM lint/test/build (continuam só no PR→main). Ganho: a violação aparece no PR que a introduz, não semanas depois no gate do release (padrão observado: 4 fixes de última hora no release da v3.8.18).
+
+**Acceptance:** PR de teste contra a release branch com uma rota inventada falha em <2 min; PRs limpos não ganham mais que ~2 min de CI.
+
+### Task 6A.7 — `check-fetch-targets` v2: escopo completo + prefixo de template + método HTTP
+
+**Files:** `scripts/check/check-fetch-targets.mjs`, `tests/unit/check-fetch-targets.test.ts`.
+
+**Approach (TDD):**
+1. **Escopo:** varrer todo `src/**/*.{ts,tsx}` client-side (excluindo `src/app/api/**`, testes, `src/lib/db`), não só `(dashboard)` — congela os misses pré-existentes que aparecerem em `KNOWN_MISSING` (com triagem/issue por cluster, igual Fase 2).
+2. **Template literals:** extrair o prefixo estático de `` fetch(`/api/x/y/${id}…`) `` e validar por **prefix-match** contra as rotas reais (existe alguma rota cujo path começa com `/api/x/y/`?). Pega diretório inteiro alucinado; não tenta resolver o sufixo dinâmico.
+3. **Método HTTP (heurístico, mesma chamada):** quando o 2º argumento literal contém `method: "POST"` (etc.), verificar que o `route.ts` resolvido exporta a função correspondente (`grep` por `export (async )?function POST` / `export const POST`). Sem method literal → assume GET-ok (rota existe basta). Casos dinâmicos → skip silencioso.
+
+**Acceptance:** fixture com fetch em `src/shared/components` + template com prefixo falso + `method: "DELETE"` para rota só-GET — 3 detecções; repo real verde com os novos congelados documentados.
+
+### Task 6A.8 — Escopo dos gates de segurança: error-helper, public-creds, route-guard, deps
+
+**Files:** `check-error-helper.mjs`, `check-public-creds.mjs`, `check-route-guard-membership.ts`, `check-deps.mjs` + testes.
+
+**Approach (TDD, um sub-commit por gate):**
+1. **error-helper** (+Rule #12 completa): incluir `open-sse/mcp-server/**` e `src/app/api/**/route.ts` no SCAN_DIRS; rodar; congelar os achados novos em KNOWN com comentário-justificativa cada (e issue por cluster).
+2. **public-creds**: além dos 2 arquivos âncora, varrer `open-sse/**` e `src/lib/oauth/**` com a mesma `CRED_KEY_RE` (linha a linha, barato); congelar achados. Limitação documentada: `const CLIENT_ID = "…"` (variável solta) continua fora — o gitleaks da Fase 7 cobre essa classe.
+3. **route-guard**: novo sub-check — todo `route.ts` (qualquer raiz) cujo fonte OU imports de 1º nível relativos contenham `child_process`/`spawn(`/`execFile(`/`worker_threads` deve ser classificado local-only por `isLocalOnlyPath()`. Mata a dependência da lista manual de 3 raízes.
+4. **deps**: `MANIFESTS` → descoberta automática de todo `package.json` do repo (fora `node_modules`/`.next`): hoje raiz, `electron/`, `open-sse/`, `@omniroute/opencode-plugin/` (dep `zod` entra na allowlist), `@omniroute/opencode-provider/`. Workspace novo amanhã entra sozinho.
+
+**Acceptance:** fixtures sintéticas por gate; repo real verde com achados congelados + issues; dep nova em QUALQUER manifest do repo dispara o gate.
+
+### Task 6A.9 — `check-known-symbols` v2: MCP tools, A2A skills, cloud agents
+
+**Files:** `scripts/check/check-known-symbols.ts`, `tests/unit/check-known-symbols.test.ts`.
+
+**Approach (TDD, mesmo padrão das 3 superfícies existentes — Step 0 de verificação dos exports reais antes de codar):**
+1. **MCP tools:** enumerar os tools registrados (via `createMcpServer()` ou parse determinístico do tool-set em `open-sse/mcp-server/tools/`) e congelar o snapshot de nomes (catraca: tool sumir = fail; tool novo = report). Cruzar com os scopes (~13) — tool sem scope atribuído = fail.
+2. **A2A skills:** chaves de `A2A_SKILL_HANDLERS` (`src/lib/a2a/taskExecution.ts`) ↔ skills expostas no Agent Card (`src/app/.well-known/agent.json/route.ts`) — divergência = fail.
+3. **Cloud agents:** entradas do `src/lib/cloudAgent/registry.ts` ↔ classes em `agents/` — incompleto/órfão = fail.
+
+**Acceptance:** remover um tool/skill/agent do registro quebra o gate; adicionar reporta (e `check-docs-counts-sync` continua cuidando da prosa).
+
+## P2 — refinamentos
+
+### Task 6A.10 — `check-test-masking` v2: deleções, skips, tautologias
+
+**Files:** `scripts/check/check-test-masking.mjs`, `tests/unit/check-test-masking.test.ts`.
+
+**Approach (TDD):** (a) `--diff-filter=M` → `MDR` (com `-M` para rename-detection): arquivo de teste **deletado** = flag automático ("N asserts removidos — arquivo deletado"); renamed = comparar contra o path antigo. (b) Contar `\.(skip|todo|only)\s*\(` + `\{\s*skip:\s*true` base vs HEAD — **aumento líquido de skips = flag** (skip novo esconde asserts sem removê-los); `.only` novo = flag sempre (filtra o resto da suíte). (c) Tautologias extras: `expect(true).toBe(true)`, `assert.equal(1, 1)`, `expect(x).toBeDefined()` como ÚNICO assert do teste.
+
+**Acceptance:** fixtures para os 3 bypasses (delete, skip, only) — todos flagados; suíte real verde.
+
+### Task 6A.11 — Pisos manuais → catraca do motor + escopo electron/bin
+
+**Files:** `scripts/quality/collect-metrics.mjs`, `quality-baseline.json`, `check-openapi-coverage.mjs`, `scripts/i18n/check-ui-keys-coverage.mjs` (só leitura do valor), `check-file-size.mjs`, `eslint.complexity.config.mjs` + baselines.
+
+**Approach:** (1) coletor emite `openapiCoverage.pct` e `i18nUiCoverage.pct` → baseline `{direction: up}` com o valor real atual (36→real, 65→real); os THRESHOLDs fixos viram redundância de segurança (mantidos). Rotas/strings novas sem doc/i18n agora REGRIDEM o % e falham. (2) `check-file-size` e `check-complexity`: adicionar `electron/` e `bin/` ao scan (congelar os >cap que existirem).
+
+**Acceptance:** rota nova não-documentada derruba `openapiCoverage.pct` → gate falha; god-file novo em `electron/` falha.
+
+### Task 6A.12 — Higiene operacional (4 itens pequenos)
+
+**Files:** `package.json`, `dependency-allowlist.json`, `.husky/pre-push`, Create: `scripts/check/check-tracked-artifacts.mjs`, `scripts/quality/run-all-gates.mjs`; Modify: `.agents/skills/quality-scan/SKILL.md`.
+
+**Approach:**
+1. **jscpd pinado:** `jscpd@^4` como devDependency (entra no lockfile + allowlist); `check-duplication` chama o binário local em vez de `npx --yes jscpd@4` (remove download de registry no CI + supply-chain risk + flakiness).
+2. **pre-push barato:** reativar com APENAS os gates determinísticos rápidos (<10s: fetch-targets, openapi-routes, db-rules, public-creds, migration-numbering, file-size, deps, error-helper) — NÃO `test:unit` (lento; CI cobre). Atualizar o claim do CLAUDE.md (coordenar com 6A.4).
+3. **check-tracked-artifacts:** falhar se `git ls-files` contém `node_modules/`, `.next/`, `coverage/`, `quality-metrics.json` ou symlink para fora do repo (o incidente do symlink trackeado já aconteceu 2×). Wire no lint job + pre-commit (é instantâneo).
+4. **Runner agregador:** `scripts/quality/run-all-gates.mjs` roda os gates em paralelo (pool ~4), agrega `{gate, exitCode, lastLine, durationMs}` e imprime a tabela consolidada; `npm run quality:scan`. A skill `/quality-scan` passa a chamá-lo (atualizar SKILL.md).
+
+**Acceptance:** `npm run quality:scan` < 3 min com tabela única; pre-push roda <10s; `git add node_modules && commit` falha no pre-commit.
+
+---
+
+## Ordem de execução recomendada (na ativação, 2026-06-16+)
+
+1. **6A.1 + 6A.2** (bugs de runner — destravam números reais de cobertura para o resto)
+2. **6A.3 + 6A.4** (stale-enforcement + docs — endurecem o que já roda)
+3. **6A.5** (motor v2) → **6A.6** (quality.yml, após OK do owner)
+4. **6A.7 → 6A.9** (escopos)
+5. **6A.10 → 6A.12** (refinamentos)
+6. Só então **Fase 7** (ferramentas novas sobre uma fundação consertada)
+
+## Self-Review
+- **Cobertura dos achados:** todos os achados A*/B*/C*/D*/E* da tabela têm task (coluna Task); os descartados estão em "Decisões conscientes de NÃO fazer" com motivo. ✓
+- **Zero dependência nova** exceto a promoção do jscpd (que já roda hoje via npx, não-pinado — a task REDUZ risco). ✓
+- **Sem flag-day:** toda expansão de escopo congela os achados pré-existentes (allowlist + issue), igual Fases 0–6; o stale-enforcement só exige remoção quando a correção JÁ aconteceu. ✓
+- **Consistência com o motor:** novas métricas (`openapiCoverage.pct`, `i18nUiCoverage.pct`) usam o formato `{value, direction}`; `eps`/`tightenSlack` são opcionais e retrocompatíveis. ✓
+- **Não-duplicação com a Fase 7:** cognitive-complexity per-file, gitleaks (creds não-públicas), knip, osv — tudo continua na Fase 7; a 6A só conserta/endurece o existente. ✓

PLANO-QUALITY-GATES-FASE7.md

@@ -0,0 +1,182 @@
+# Fase 7 — Quality Gates: Segurança, Dead-Code, Mutação & Ferramental Community
+
+> **Para workers agênticos:** SUB-SKILL OBRIGATÓRIA: `superpowers:subagent-driven-development` (recomendado) ou `superpowers:executing-plans`, tarefa-a-tarefa. Cada tarefa aqui é um subsistema independente → **expandir em sub-plano bite-sized próprio** no momento da execução. Hard Rule #18 (TDD/VPS) em tudo.
+
+> # ⏳ PORTÃO DE ATIVAÇÃO — NÃO INICIAR ANTES DE **2026-06-16**
+> **Este plano está GUARDADO, não ativo.** Decisão do owner (2026-06-09): finalizar 100% as Fases 0–6 (PR #3471), **usar em produção por 1 semana** para validar na prática, e só então evoluir. **Data cravada de início da Fase 7: 2026-06-16.** Não ativar antes — o objetivo da semana é coletar sinal real (falsos-positivos dos gates, custo de CI, atrito) antes de adicionar mais.
+> **Pré-condições para ativar:** (1) PR #3471 (Fases 0–6) mergeada e rodada ≥1 semana; (2) re-home do PR para `release/v3.8.18` resolvido; (3) as issues #3483–#3501 com decisões aplicadas ou conscientemente adiadas; (4) **Fase 6A executada (ou conscientemente re-priorizada)** — a auditoria crítica de 2026-06-09 ([`PLANO-QUALITY-GATES-FASE6A.md`](./PLANO-QUALITY-GATES-FASE6A.md)) encontrou bugs sistêmicos de runner (≈135 testes órfãos, vitest fora do CI) e furos de escopo nos gates existentes que devem ser consertados ANTES de adicionar ferramentas novas por cima.
+
+**Goal:** Maximizar a cobertura de quality gates do OmniRoute adicionando catracas de **segurança** (Sonar/osv/CodeQL → zero na timeline), **dead-code**, **complexidade cognitiva**, **type-coverage**, **mutação**, **bundle-size**, **a11y** e completando o anti-slopsquatting — usando **somente ferramentas Community/OSS** (projeto é open-source, zero SaaS pago, dados na box).
+
+**Architecture:** Reusa o motor existente — toda métrica numérica entra como `{value, direction}` em `quality-baseline.json` (catraca só-regressão) ou vira um `scripts/check/check-*.mjs` dedicado (padrão `check-t11-any-budget.mjs`). Gates pesados vão no job paralelo `quality-gate`; gates rápidos no `lint`; mutação/visual em job nightly separado. Tudo só-regressão (sem flag-day).
+
+**Tech Stack (tudo OSS/Community):** SonarQube **Community Build** (self-hosted) · osv-scanner (Google) · CodeQL (GitHub, grátis p/ público) · knip · eslint-plugin-sonarjs · type-coverage · lockfile-lint · dpdm · Stryker (`@stryker-mutator/*`) · size-limit · `@axe-core/playwright` · semcheck · agent-lsp (MCP) · Qlty CLI (OSS, opcional) · **gitleaks** (secret scanning, MIT; avaliar o sucessor drop-in Betterleaks, 2026-03) · **actionlint + zizmor** (lint + auditoria de segurança dos workflows) · **license-compliance** (allowlist SPDX de licenças). ESLint 9 flat · c8 · Node native test runner · GitHub Actions.
+
+---
+
+## Princípio (igual às Fases 0–6)
+
+Toda catraca é **só-regressão**: congela o baseline atual, bloqueia QUALQUER piora, decai a zero/melhor com o tempo via `--update`. Nenhum gate exige limpeza imediata (flag-day). Cada ferramenta nova que vira dependência **deve ser adicionada a `dependency-allowlist.json`** (o gate `check-deps` da Fase 2 vai exigir — é o ponto de revisão humana).
+
+## Mapa de arquivos (criar/modificar)
+
+| Arquivo | Responsabilidade |
+|---|---|
+| `quality-baseline.json` (modificar) | + `vulnCount`, `codeqlAlerts`, `sonarIssues`, `cognitiveComplexity`, `typeCoveragePct`, `deadExports` |
+| `scripts/quality/collect-metrics.mjs` (modificar) | + coletores: osv-scanner, CodeQL count, Sonar API, knip, type-coverage, sonarjs |
+| `scripts/check/check-vuln-ratchet.mjs` (criar) | osv-scanner → vulnCount (catraca) |
+| `scripts/check/check-dead-code.mjs` (criar) | knip → exports/files/deps mortos (catraca) |
+| `scripts/check/check-cognitive-complexity.mjs` + `eslint.sonarjs.config.mjs` (criar) | sonarjs/cognitive-complexity em config isolado (não polui o count principal) |
+| `scripts/check/check-type-coverage.mjs` (criar) | type-coverage % (catraca up) |
+| `scripts/check/check-lockfile.mjs` (criar) | lockfile-lint (host/https/integrity) |
+| `scripts/check/check-pr-evidence.mjs` (criar) | exige output de comando no corpo do PR (Rule #18 mecânica) |
+| `scripts/check/check-bundle-size.mjs` + `.size-limit.json` (criar) | size-limit → orçamento de bundle |
+| `tests/e2e/a11y.spec.ts` (criar) | `@axe-core/playwright` nas páginas-chave |
+| `stryker.conf.json` (criar) | mutação nos ~8 módulos críticos (nightly) |
+| `sonar-project.properties` (modificar) | remover `coverage`/`cpd` exclusions; ativar new-code gate |
+| `.github/workflows/ci.yml` (modificar) | wirar novos gates (lint / quality-gate / nightly) + `qualitygate.wait` no Sonar |
+| `semcheck.yaml` (criar) | semcheck: docs↔código (camada fuzzy LLM, opcional) |
+| `.mcp.json` / config de agentes (modificar) | registrar agent-lsp (LSP-in-the-loop) |
+| `.gitleaks.toml` + `scripts/check/check-secrets.mjs` (criar) | gitleaks → catraca de findings de secret (Task 18) |
+| `.github/workflows/quality.yml` ou job lint (modificar) | actionlint + zizmor sobre `.github/workflows/**` (Task 19) |
+| `scripts/check/check-licenses.mjs` + `.license-allowlist.json` (criar) | allowlist SPDX das licenças das deps (Task 20) |
+| `dependency-allowlist.json` (modificar) | + osv-scanner, knip, sonarjs, type-coverage, lockfile-lint, stryker, size-limit, axe-core, dpdm, license-compliance |
+
+---
+
+## Tarefas (cada uma = 1 sub-plano bite-sized na execução)
+
+### Task 1 — Ativar SonarQube Community + "Clean as You Code" (gate de segurança nativo)
+- **Tool:** SonarQube Community Build (self-hosted, grátis).
+- **Files:** `sonar-project.properties`, `.github/workflows/ci.yml` (job `sonarqube`).
+- **Approach:** setar secrets `SONAR_TOKEN`/`SONAR_HOST_URL`; **remover** `sonar.coverage.exclusions=**/*` e `sonar.cpd.exclusions=**/*` (hoje neutralizam o Sonar); ativar o quality gate **new-code / "Clean as You Code"** (código novo não pode adicionar issue/bug/vuln/hotspot; legado grandfathered) + adicionar `-Dsonar.qualitygate.wait=true` para **bloquear** o PR (hoje o job é inerte: secrets-gated, sem wait).
+- **Acceptance:** PR que introduz um code-smell/bug/vuln em código novo falha o gate; legado não bloqueia. Documentar suppressions legítimas (já há h1–h6 no properties).
+
+### Task 2 — Catraca de vulnerabilidades (osv-scanner)
+- **Tool:** osv-scanner (Google/OSV, OSS) — `--format json`, on-box.
+- **Files:** `scripts/check/check-vuln-ratchet.mjs`, `quality-baseline.json` (+`vulnCount`), `collect-metrics.mjs`, `ci.yml` (job `quality-gate`), `dependency-allowlist.json`.
+- **Approach:** rodar `osv-scanner --format json` sobre os lockfiles → contar vulns → métrica `vulnCount {direction: down}`. Catraca: não pode subir, decai a zero. Mantém o `npm audit` escalonado da Fase 0 como bloqueio de crítico imediato; osv é o ratchet de timeline.
+- **Acceptance:** nova dep com vuln conhecida sobe o count → falha; remediar/remover baixa → `--update`.
+
+### Task 3 — Catraca de alertas CodeQL
+- **Tool:** GitHub CodeQL (já roda; grátis p/ repo público).
+- **Files:** `scripts/check/check-codeql-ratchet.mjs`, `quality-baseline.json` (+`codeqlAlerts`), `ci.yml`.
+- **Approach:** puxar a contagem de alertas abertos via `gh api /repos/{owner}/{repo}/code-scanning/alerts?state=open` → métrica `codeqlAlerts {down}`. (Respeitar Hard Rule #14 — dismiss só com justificativa; alertas dismissed não contam.)
+- **Acceptance:** novo alerta CodeQL sobe o count → sinaliza; resolver baixa.
+
+### Task 4 — Dead-code / unused-exports / unused-deps (knip)
+- **Tool:** knip (OSS, v6+) — `--reporter json`.
+- **Files:** `scripts/check/check-dead-code.mjs`, `quality-baseline.json` (+`deadExports`/`unusedDeps`), `knip.json` (config), `collect-metrics.mjs`, `ci.yml`, `dependency-allowlist.json`.
+- **Approach:** `knip --reporter json` sobre os workspaces `src/`+`open-sse/` → contar unused files/exports/deps → catraca `down`. Config knip ciente do monorepo + Next 16.
+- **Acceptance:** novo export/dep morto sobe → falha; remoção baixa.
+
+### Task 5 — Complexidade cognitiva (eslint-plugin-sonarjs, config isolado)
+- **Tool:** eslint-plugin-sonarjs (OSS) — `sonarjs/cognitive-complexity`.
+- **Files:** `eslint.sonarjs.config.mjs` (config standalone, NÃO o principal — não polui o `eslintWarnings=3482`), `scripts/check/check-cognitive-complexity.mjs`, `quality-baseline.json` (+`cognitiveComplexity`), `ci.yml` (job `quality-gate`), `dependency-allowlist.json`.
+- **Approach:** mesmo molde do `check-complexity` (Fase 6) mas com `sonarjs/cognitive-complexity` num config isolado; contar violações → catraca `down`. (Complementa a complexidade ciclomática core já existente.)
+- **Acceptance:** função acima do limite cognitivo sobe o count → falha.
+
+### Task 6 — Type-coverage ratchet
+- **Tool:** type-coverage (OSS).
+- **Files:** `scripts/check/check-type-coverage.mjs`, `quality-baseline.json` (+`typeCoveragePct {up}`), `dependency-allowlist.json`.
+- **Approach:** `type-coverage --detail --json` → % de símbolos tipados → catraca `up`. Complementa o `check:any-budget` (count de `any` por arquivo) com a visão %-global.
+- **Acceptance:** queda do % tipado → falha.
+
+### Task 7 — Lockfile policy (lockfile-lint)
+- **Tool:** lockfile-lint (OSS, v5).
+- **Files:** `scripts/check/check-lockfile.mjs`, `ci.yml` (lint), `dependency-allowlist.json`.
+- **Approach:** `lockfile-lint --path package-lock.json --type npm --validate-https --validate-integrity --allowed-hosts npm` → gate pass/fail (não é ratchet; é política anti-poisoning). Complementa o `check-deps` (Fase 2).
+- **Acceptance:** lockfile com host não-https/sem integrity → falha.
+
+### Task 8 — Completar anti-slopsquatting (registry-existence + age-cooldown)
+- **Tool:** npm registry API (`npm view <pkg> time.created`).
+- **Files:** `scripts/check/check-deps.mjs` (estender), test.
+- **Approach:** além do allowlist-diff atual, para uma dep NOVA: verificar que existe no registry E que foi publicada há ≥72h (age-cooldown contra "registra o nome alucinado em horas"). Base: CSA 2026 (19,7% de nomes alucinados; 43% reaparecem).
+- **Acceptance:** dep nova inexistente no registry ou publicada há <72h → falha (a menos que allowlistada com justificativa).
+
+### Task 9 — Pisos de cobertura por módulo crítico (peça adiada da Fase 4)
+- **Files:** `scripts/quality/collect-metrics.mjs` (estender), `quality-baseline.json`.
+- **Approach:** emitir `coverage.<modulo>.lines` (lido do `coverage-summary.json` por-arquivo) para ~8 módulos de alto risco: `open-sse/handlers/chatCore.ts`, `open-sse/services/combo.ts`, `open-sse/services/accountFallback.ts`, `src/sse/services/auth.ts`, `src/server/authz/routeGuard.ts`, `open-sse/utils/error.ts`, `open-sse/utils/publicCreds.ts`, `src/shared/utils/circuitBreaker.ts`. Cada um vira métrica `up`. **Calibrar a partir do coverage mergeado real do 1º run verde na main.**
+- **Acceptance:** queda de cobertura num módulo crítico → falha, mesmo que o global não caia.
+
+### Task 10 — Evidence-in-PR-body (peça adiada da Fase 5)
+- **Files:** `scripts/check/check-pr-evidence.mjs`, `ci.yml` (job `pr-test-policy`).
+- **Approach:** se o corpo do PR afirma "tests pass"/"added endpoint X"/"fixed Y" sem um bloco de **output de comando** anexado (typecheck/test/grep), falha (torna a Rule #18 mecânica — "evidence before assertions"). Heurístico, no contexto de PR.
+- **Acceptance:** PR alegando sucesso sem output anexado → falha.
+
+### Task 11 — Mutation testing nos módulos críticos (Stryker, nightly)
+- **Tool:** Stryker (`@stryker-mutator/core` + runner; OSS).
+- **Files:** `stryker.conf.json`, `ci.yml` (job NIGHTLY separado — não no PR), `dependency-allowlist.json`.
+- **Approach:** escopar Stryker aos ~8 módulos críticos da Task 9 (não repo-wide — é caro + c8 já OOM-prone). Mutantes sobreviventes = **testes tautológicos** (passam sem provar nada) → complementa o `check-test-masking` da Fase 4. Rodar nightly/weekly, não por-PR.
+- **Acceptance:** mutation score por módulo crítico vira métrica (catraca `up`, nightly).
+
+### Task 12 — Bundle-size / perf budget (size-limit)
+- **Tool:** size-limit (OSS).
+- **Files:** `.size-limit.json`, `scripts/check/check-bundle-size.mjs`, `ci.yml`, `dependency-allowlist.json`.
+- **Approach:** definir orçamento por bundle Next 16; size-limit emite tamanhos → catraca `down` (bundle não pode inchar).
+- **Acceptance:** PR que estoura o orçamento de bundle → falha.
+
+### Task 13 — a11y gate (axe-core + Playwright)
+- **Tool:** `@axe-core/playwright` (OSS; Playwright já existe).
+- **Files:** `tests/e2e/a11y.spec.ts`, `ci.yml` (job `test-e2e`), `dependency-allowlist.json`.
+- **Approach:** rodar axe nas páginas-chave do dashboard; congelar violações atuais (catraca `down`). Atende o item a11y/visual do plano t15.
+- **Acceptance:** nova violação a11y → falha; correção baixa.
+
+### Task 14 — semcheck (camada fuzzy docs↔código, opcional/LLM)
+- **Tool:** semcheck (OSS, MIT) — `fail-on-issues`.
+- **Files:** `semcheck.yaml`, `ci.yml` (advisory).
+- **Approach:** regras ligando `docs/**` ao módulo de código que documentam; pega docs que descrevem o que o código NÃO faz (camada fuzzy sobre o determinístico `check-docs-symbols` da Fase 6). É LLM → rodar advisory/non-blocking ou em label, por custo.
+- **Acceptance:** doc que descreve comportamento inexistente → flag (advisory).
+
+### Task 15 — agent-lsp (LSP-in-the-loop para os agentes)
+- **Tool:** agent-lsp (MCP server, OSS).
+- **Files:** config MCP dos agentes (`.mcp.json`/equivalente).
+- **Approach:** expor `tsserver`/agent-lsp aos agentes para `blast_radius`/diagnostics/`preview_edit` ANTES de escrever — vira "símbolo inventado" de catch-de-review para impossibilidade-no-edit. Pareia com `typecheck:core` como gate pré-PR (compile-before-claim).
+- **Acceptance:** agentes resolvem símbolo/import via LSP; menos alucinação de símbolo na origem.
+
+### Task 16 — dpdm circular-deps JSON cross-check (opcional)
+- **Tool:** dpdm (OSS, v4) — `--circular --output`.
+- **Approach:** cross-check JSON de ciclos complementando o `check-cycles.mjs` existente (AST-TS mais preciso). Catraca de contagem de ciclos. Baixa prioridade (já temos check-cycles).
+
+### Task 17 — Avaliar Qlty CLI como consolidador (opcional, spike)
+- **Tool:** Qlty CLI (OSS, grátis).
+- **Approach:** spike: avaliar se Qlty (Baseline analysis + 70 analyzers) substitui N scripts caseiros sem perder o controle/determinismo. Decisão build-vs-buy. Não obrigatório.
+
+### Task 18 — Secret scanning local (gitleaks) ➕ *adicionada pela auditoria 6A (2026-06-09)*
+- **Tool:** gitleaks (OSS, MIT — binário Go, on-box). Nota 2026: o criador original (Zach Rice) lançou o **Betterleaks** (2026-03) como drop-in replacement (flags/config compatíveis) — avaliar os dois no Step 0 e escolher 1.
+- **Files:** `.gitleaks.toml`, `scripts/check/check-secrets.mjs`, `quality-baseline.json` (+`secretFindings {down}`), `ci.yml` (job quality-gate), pre-commit (modo `--staged`, é rápido).
+- **Approach:** complementa o `check-public-creds` da Fase 6 (que cobre apenas credenciais PÚBLICAS por chave de objeto em 2 arquivos): gitleaks pega a classe geral — `const API_KEY = "sk-…"`, tokens em config/teste/docs, secrets em histórico. Rodar `gitleaks dir --report-format json` → contar findings → catraca `down`. Findings legítimos (creds públicas já congeladas no check-public-creds, fixtures de teste) vão para `.gitleaks.toml` `[allowlist]` com comentário — sujeitos ao stale-enforcement da 6A.3 (conceitual: revisar allowlist a cada release).
+- **Acceptance:** secret real plantado em fixture é detectado; baseline congela os findings atuais; novo finding falha o gate.
+
+### Task 19 — Lint + auditoria de segurança dos workflows (actionlint + zizmor) ➕ *adicionada pela auditoria 6A*
+- **Tools:** actionlint (OSS — correção/sintaxe/shellcheck dos YAML) + zizmor (OSS, zizmorcore — 24+ audits de segurança: unpinned actions, script injection, `pull_request_target` perigoso, cache poisoning). Complementares por design; o repo tem 10 workflows sem NENHUMA validação hoje.
+- **Motivação 2026:** o incidente trivy-action/LiteLLM (2026-03) explorou exatamente uma misconfiguração de `pull_request_target` que o zizmor detecta estaticamente. Os release-workflows do OmniRoute (npm/Docker/Electron publish) são alvo de alto valor.
+- **Files:** `ci.yml` ou `quality.yml` (steps actionlint + zizmor), `zizmor.yml` (config/ignores justificados), `quality-baseline.json` (+`zizmorFindings {down}` — começar advisory, congelar baseline, depois bloquear).
+- **Approach:** actionlint = pass/fail imediato (sintaxe não tem "legado aceitável"); zizmor = catraca `down` no padrão do motor (os findings atuais — provavelmente actions não-pinadas por SHA — são dívida congelada que decai).
+- **Acceptance:** workflow novo com `pull_request_target` + checkout de código do PR falha; action não-pinada NOVA sobe o count e falha.
+
+### Task 20 — License compliance (allowlist SPDX) ➕ *adicionada pela auditoria 6A*
+- **Tool:** license-compliance ou @onebeyond/license-checker (ambos OSS, npm). Projeto é **MIT** — deps com copyleft forte (GPL/AGPL) em produção são risco de compliance para os usuários do proxy.
+- **Files:** `scripts/check/check-licenses.mjs`, `.license-allowlist.json` (SPDX permitidas: MIT, Apache-2.0, BSD-2/3, ISC, 0BSD, …), `ci.yml` (lint job), `dependency-allowlist.json`.
+- **Approach:** rodar sobre as `dependencies` de produção (devDependencies = relatório advisory); licença fora da allowlist → fail com o caminho da dep. Exceções pontuais (dual-license, LGPL avaliada) entram na allowlist por **pacote** com justificativa — pareia com o `check-deps` da Fase 2 (lá controla O QUE entra; aqui, SOB QUAL licença).
+- **Acceptance:** dep GPL-3.0 sintética em fixture falha; árvore atual passa com a allowlist calibrada.
+
+---
+
+## Wiring & CI (resumo)
+- **lint job:** check-lockfile, check-cognitive-complexity (rápido?), check-type-coverage, **check-licenses (Task 20)**, **actionlint (Task 19)**.
+- **quality-gate job (paralelo):** check-vuln-ratchet, check-dead-code, check-codeql-ratchet, check-cognitive-complexity (se lento), check-bundle-size, **check-secrets (Task 18)**, **zizmor (Task 19)**.
+- **pr-test-policy job:** check-pr-evidence.
+- **sonarqube job:** Clean-as-You-Code + `qualitygate.wait`.
+- **NIGHTLY job (novo):** Stryker (mutação), semcheck (advisory), a11y full.
+- Todas as métricas numéricas → `quality-baseline.json` (motor da Fase 1, com `eps`/`tightenSlack` da 6A.5). Toda dep nova → `dependency-allowlist.json`. Toda allowlist nova nasce com o stale-enforcement da 6A.3.
+
+## Self-Review
+- **Cobertura do spec:** 7 gates sugeridos = Task 1-3 (segurança), 4 (knip), 9 (coverage por módulo), 10 (evidence), 11 (mutação), 12 (bundle), 13 (a11y). "Todas as ferramentas discutidas" = Tasks 1-8, 11-17 (Sonar/osv/CodeQL/knip/sonarjs/type-coverage/lockfile/dpdm/stryker/size-limit/axe/semcheck/agent-lsp/Qlty). Auditoria 6A (2026-06-09) acrescentou Tasks 18-20 (gitleaks, actionlint+zizmor, license compliance). ✓
+- **Community/OSS only:** confirmado — Sonar Community Build, todos os demais OSS (gitleaks MIT, zizmor/actionlint OSS, license-compliance npm), zero SaaS pago. ✓
+- **Sem flag-day:** toda catraca é só-regressão, calibrada do estado atual (zizmor/gitleaks começam advisory→baseline→bloqueio). ✓
+- **Consistência:** todas as métricas usam o formato `{value, direction}` do motor da Fase 1; deps novas passam pelo `check-deps`+`dependency-allowlist.json`. ✓
+- **Não-sobreposição com a 6A:** a 6A conserta/endurece o EXISTENTE (runners, stale-allowlists, escopos); a Fase 7 só adiciona ferramenta nova. gitleaks (Task 18) complementa — não substitui — o check-public-creds expandido pela 6A.8. ✓
+
+## Handoff (na ativação, 2026-06-16+)
+**Ordem: Fase 6A primeiro** ([`PLANO-QUALITY-GATES-FASE6A.md`](./PLANO-QUALITY-GATES-FASE6A.md)) — consertar os runners (testes órfãos + vitest no CI) e endurecer as catracas existentes muda os baselines (cobertura recalibrada) sobre os quais várias tasks daqui (1, 9, 11) calibram. Depois: começar pela **Task 1-3 (catraca de segurança)**, **Task 4 (knip)** e **Task 19 (zizmor — protege os release-workflows)** — maior retorno. Cada Task vira um sub-plano `writing-plans` bite-sized próprio. Recomendado: Subagent-Driven, 1 subagente por Task, com auditoria (trust-but-verify) e o ratchet `eslintWarnings`/`check-deps` validando que cada adição não regride o que já temos.

PLANO-QUALITY-GATES.md

@@ -0,0 +1,688 @@
+# Plano de Implementação — Quality Gates & Catraca Anti-Alucinação
+
+> **Para workers agênticos:** SUB-SKILL OBRIGATÓRIA: use `superpowers:subagent-driven-development` (recomendado) ou `superpowers:executing-plans` para executar este plano tarefa-a-tarefa. Os passos usam checkbox (`- [ ]`) para rastreio. **Cada fix de bug obedece à Hard Rule #18** (teste falha→passa OU validação ao vivo no VPS). Não burle Husky (`--no-verify`) sem aprovação. Veja o diagnóstico completo em [`RELATORIO-QUALITY-GATES.md`](./RELATORIO-QUALITY-GATES.md).
+
+**Goal:** Generalizar a catraca de qualidade do OmniRoute (hoje só para `any`) para todas as métricas relevantes — cobertura, duplicação, tamanho de arquivo, complexidade — e adicionar gates determinísticos anti-alucinação, tudo no padrão `check-*.mjs` já existente, sem SaaS novo.
+
+**Architecture:** Camadas incrementais. (0) reativa/reconcilia o que já existe; (1) constrói o **motor de catraca** (`quality-baseline.json` commitado + coletor + comparador genérico que clona o `check-t11-any-budget.mjs`); (2) adiciona gates determinísticos que matam os ímãs de alucinação (provider-consistency, fetch-targets, openapi-routes); (3) catraca de duplicação+tamanho; (4) catraca de cobertura + anti test-masking; (5) skill `/babysit` + evidência. Toda catraca é **só-regressão** (baseline congelado) — nunca um piso absoluto que exija limpeza flag-day.
+
+**Tech Stack:** Node ≥20 ESM (`.mjs`/`.ts` via `tsx`), ESLint 9 flat config, c8, jscpd v5, eslint-plugin-sonarjs v4, GitHub Actions, Node native test runner (`node --import tsx --test`), `gh` CLI + GraphQL.
+
+**Escopo / sub-planos (scope-check):** Fases 0, 1 e 2 estão totalmente bite-sized aqui. Fases 3, 4 e 5 são subsistemas independentes — cada uma deve ser **expandida no próprio sub-plano** (via `writing-plans`) no momento da execução, a partir das specs/critérios de aceitação definidos aqui. Cada fase entrega software funcional e testável por si só.
+
+---
+
+## Mapa de arquivos (o que será criado/modificado)
+
+| Arquivo | Responsabilidade |
+|---------|------------------|
+| `quality-baseline.json` (criar, **commitar**) | Baseline congelado: por métrica `{value, direction}` (`down`=menor-é-melhor, `up`=maior-é-melhor) |
+| `scripts/quality/collect-metrics.mjs` (criar) | Roda os coletores → emite `quality-metrics.json` |
+| `scripts/quality/check-quality-ratchet.mjs` (criar) | Comparador genérico: falha em qualquer regressão; com `--update` ratcheta o baseline |
+| `scripts/check/check-fetch-targets.mjs` (criar) | Todo `fetch("/api/...")` do dashboard resolve para um `route.ts` real |
+| `scripts/check/check-provider-consistency.ts` (criar) | ids de provider batem entre `providers.ts` ↔ `providerRegistry.ts` ↔ `validation.ts` |
+| `scripts/check/check-openapi-routes.mjs` (criar) | Toda `path` do `openapi.yaml` ↔ `route.ts` real (bidirecional) |
+| `scripts/check/check-deps.mjs` (criar) | Anti-slopsquatting: allowlist + existência no registry + age-cooldown |
+| `.github/workflows/ci.yml` (modificar) | Novo job `quality-gate`; reconciliar gate de cobertura; escalonar audit; plugar scripts órfãos |
+| `.husky/pre-commit` (modificar) | Reativar a parte barata |
+| `package.json` (modificar) | Novos scripts `check:*` / `quality:*` |
+| `eslint.config.mjs` (modificar, Fase 3) | `max-lines`, `max-lines-per-function`, `complexity`, `sonarjs/cognitive-complexity` (warn) |
+| `.claude/skills/babysit/SKILL.md` (criar, Fase 5) | Skill `/babysit` |
+| `tests/unit/quality-ratchet.test.ts` etc. (criar) | Testes TDD de cada gate |
+
+---
+
+# FASE 0 — Reativar & Reconciliar (quick wins, sem tooling novo)
+
+### Task 0.1: Reconciliar o gate de cobertura do CI (40 → baseline real)
+
+**Contexto:** `ci.yml:377` gata em `40/40/40/40`; local gata `60`; comentário renderiza `60`; baseline real ≈ 79–82%. O 40 torna o gate quase banguela.
+
+**Files:**
+- Modify: `.github/workflows/ci.yml:376-377`
+
+- [ ] **Step 1: Confirmar o baseline real de cobertura**
+
+Run:
+```bash
+npm run test:coverage 2>&1 | tail -20
+node -e "const c=require('./coverage/coverage-summary.json').total; console.log(c.statements.pct,c.lines.pct,c.functions.pct,c.branches.pct)"
+```
+Expected: 4 números (ex.: `79.8 79.8 82.2 75.2`). Anote-os.
+
+- [ ] **Step 2: Subir o gate do CI para `baseline_real - 2` (headroom anti-flake)**
+
+Em `.github/workflows/ci.yml`, troque a linha `--statements 40 --lines 40 --functions 40 --branches 40` pelos valores `(real-2)` de cada métrica (ex.: `--statements 77 --lines 77 --functions 80 --branches 73`). Mantenha como **piso**; a catraca da Fase 4 cuidará do "não-cair".
+
+- [ ] **Step 3: Alinhar o script local e o display do comentário** para os mesmos números (procure `60` em `package.json` `test:coverage` e em `scripts/check/test-report-summary.mjs`).
+
+- [ ] **Step 4: Verificar que o CI não quebra** — abrir um PR de teste (ou rodar `act`/push numa branch) e confirmar que o job `test-coverage` fica verde com o novo piso.
+
+- [ ] **Step 5: Commit**
+```bash
+git add .github/workflows/ci.yml package.json scripts/check/test-report-summary.mjs
+git commit -m "fix(ci): reconcile coverage gate to real baseline (40->~78) across CI/local/report"
+```
+
+### Task 0.2: Escalonar `npm audit` (critical=bloqueia / high=avisa)
+
+**Files:** Modify: `package.json:112`
+
+- [ ] **Step 1: Trocar o script `audit:deps`** de `npm audit --audit-level=moderate && npm run audit:electron` para:
+```json
+"audit:deps": "npm audit --audit-level=critical && (npm audit --audit-level=high || echo '::warning::high-severity advisories present (non-blocking)') && npm run audit:electron",
+```
+
+- [ ] **Step 2: Rodar e observar o comportamento**
+```bash
+npm run audit:deps; echo "exit=$?"
+```
+Expected: `exit=0` se não houver critical; mensagem de warning se houver high.
+
+- [ ] **Step 3: Commit**
+```bash
+git add package.json && git commit -m "chore(ci): tier npm audit (critical blocks, high warns)"
+```
+
+### Task 0.3: Plugar os 3 scripts órfãos no CI
+
+**Contexto:** `check:cli-i18n`, `check:openapi-coverage`, `check:openapi-security-tiers` existem, dão `exit 1`, mas não rodam em lugar nenhum (Hard Rules #15/#17).
+
+**Files:** Modify: `.github/workflows/ci.yml` (job `docs-sync-strict` ou `lint`)
+
+- [ ] **Step 1: Rodar os 3 localmente para confirmar verde no estado atual**
+```bash
+npm run check:cli-i18n && npm run check:openapi-coverage && npm run check:openapi-security-tiers; echo "exit=$?"
+```
+Expected: `exit=0` (se algum falhar, corrija a deriva antes de plugar).
+
+- [ ] **Step 2: Adicionar os 3 como steps** no job `docs-sync-strict` do `ci.yml`, após `check:docs-all`.
+
+- [ ] **Step 3: Commit**
+```bash
+git add .github/workflows/ci.yml && git commit -m "ci: wire orphaned gates (cli-i18n, openapi-coverage, openapi-security-tiers)"
+```
+
+### Task 0.4: Reativar a parte barata do pre-commit do Husky
+
+**Files:** Modify: `.husky/pre-commit`
+
+- [ ] **Step 1: Descomentar SÓ as 3 linhas baratas e determinísticas:**
+```sh
+npx lint-staged
+node scripts/check/check-docs-sync.mjs
+npm run check:any-budget:t11
+```
+(Deixe i18n/openapi comentados por enquanto — eles são mais lentos; rodam no CI.)
+
+- [ ] **Step 2: Testar o hook** com um commit trivial e medir o tempo:
+```bash
+time git commit --allow-empty -m "chore: test pre-commit hook"
+git reset --soft HEAD~1
+```
+Expected: hook roda lint-staged + 2 checks em poucos segundos.
+
+- [ ] **Step 3: Commit**
+```bash
+git add .husky/pre-commit && git commit -m "chore(husky): re-enable cheap pre-commit gates (lint-staged, docs-sync, any-budget)"
+```
+
+---
+
+# FASE 1 — Motor de Catraca (o coração) ⭐
+
+> Generaliza o `check-t11-any-budget.mjs` (catraca de `any` por arquivo) para um motor de catraca genérico, multi-métrica, que lê um baseline commitado e falha em qualquer regressão. Começa com 2 métricas (warnings de ESLint + cobertura) e é estendido nas fases seguintes.
+
+### Task 1.1: Comparador genérico de catraca (TDD)
+
+**Files:**
+- Create: `scripts/quality/check-quality-ratchet.mjs`
+- Test: `tests/unit/quality-ratchet.test.ts`
+
+- [ ] **Step 1: Escrever o teste que falha**
+```ts
+// tests/unit/quality-ratchet.test.ts
+import { test } from "node:test";
+import assert from "node:assert";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const SCRIPT = path.resolve("scripts/quality/check-quality-ratchet.mjs");
+
+function run(baseline, metrics, extraArgs = []) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ratchet-"));
+  const bPath = path.join(dir, "baseline.json");
+  const mPath = path.join(dir, "metrics.json");
+  fs.writeFileSync(bPath, JSON.stringify(baseline));
+  fs.writeFileSync(mPath, JSON.stringify(metrics));
+  try {
+    const out = execFileSync("node", [SCRIPT, "--baseline", bPath, "--metrics", mPath, ...extraArgs], { encoding: "utf8" });
+    return { code: 0, out, dir, bPath };
+  } catch (e) {
+    return { code: e.status, out: (e.stdout || "") + (e.stderr || ""), dir, bPath };
+  }
+}
+
+test("passes when metrics equal baseline", () => {
+  const b = { metrics: { eslintWarnings: { value: 100, direction: "down" }, "coverage.lines": { value: 80, direction: "up" } } };
+  assert.equal(run(b, { eslintWarnings: 100, "coverage.lines": 80 }).code, 0);
+});
+
+test("fails when a 'down' metric regresses (more warnings)", () => {
+  const b = { metrics: { eslintWarnings: { value: 100, direction: "down" } } };
+  const r = run(b, { eslintWarnings: 101 });
+  assert.equal(r.code, 1);
+  assert.match(r.out, /eslintWarnings/);
+});
+
+test("fails when an 'up' metric regresses (coverage drops)", () => {
+  const b = { metrics: { "coverage.lines": { value: 80, direction: "up" } } };
+  assert.equal(run(b, { "coverage.lines": 79 }).code, 1);
+});
+
+test("passes on improvement; --update ratchets the baseline", () => {
+  const b = { metrics: { eslintWarnings: { value: 100, direction: "down" } } };
+  const r = run(b, { eslintWarnings: 90 }, ["--update"]);
+  assert.equal(r.code, 0);
+  const updated = JSON.parse(fs.readFileSync(r.bPath, "utf8"));
+  assert.equal(updated.metrics.eslintWarnings.value, 90);
+});
+
+test("fails (code 2) when a baseline metric is missing from collected metrics", () => {
+  const b = { metrics: { eslintWarnings: { value: 100, direction: "down" } } };
+  assert.equal(run(b, {}).code, 1);
+});
+```
+
+- [ ] **Step 2: Rodar o teste e ver falhar**
+```bash
+node --import tsx --test tests/unit/quality-ratchet.test.ts
+```
+Expected: FAIL (script não existe ainda).
+
+- [ ] **Step 3: Implementar o comparador**
+```js
+#!/usr/bin/env node
+// scripts/quality/check-quality-ratchet.mjs
+// Catraca genérica multi-métrica. Clona o espírito de check-t11-any-budget.mjs:
+// um baseline congelado por métrica; falha em qualquer regressão; só anda num sentido.
+import fs from "node:fs";
+import path from "node:path";
+
+const cwd = process.cwd();
+function getArg(name, fallback) {
+  const i = process.argv.indexOf(name);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+const BASELINE = path.resolve(getArg("--baseline", path.join(cwd, "quality-baseline.json")));
+const METRICS = path.resolve(getArg("--metrics", path.join(cwd, "quality-metrics.json")));
+const SUMMARY = getArg("--summary", null);
+const UPDATE = process.argv.includes("--update");
+const EPS = 0.01;
+
+function load(p) {
+  if (!fs.existsSync(p)) { console.error(`[quality-ratchet] arquivo ausente: ${p}`); process.exit(2); }
+  return JSON.parse(fs.readFileSync(p, "utf8"));
+}
+
+const baseline = load(BASELINE);
+const metrics = load(METRICS);
+const failures = [];
+const improvements = [];
+const rows = [];
+
+for (const [key, spec] of Object.entries(baseline.metrics)) {
+  const current = metrics[key];
+  const base = spec.value;
+  const dir = spec.direction; // "down" = menor-é-melhor | "up" = maior-é-melhor
+  if (current === undefined) { failures.push(`métrica "${key}" ausente em ${path.basename(METRICS)}`); rows.push([key, base, "—", "MISSING"]); continue; }
+  let status = "ok";
+  if (dir === "down") {
+    if (current > base + EPS) { failures.push(`${key}: ${current} > baseline ${base} (não pode aumentar)`); status = "REGRESSÃO"; }
+    else if (current < base - EPS) { improvements.push([key, current]); status = "↑ melhorou"; }
+  } else {
+    if (current < base - EPS) { failures.push(`${key}: ${current} < baseline ${base} (não pode cair)`); status = "REGRESSÃO"; }
+    else if (current > base + EPS) { improvements.push([key, current]); status = "↑ melhorou"; }
+  }
+  rows.push([key, base, current, status]);
+}
+
+if (SUMMARY) {
+  const md = ["# Quality Ratchet", "", "| Métrica | Baseline | Atual | Status |", "|---|---|---|---|",
+    ...rows.map(([k, b, c, s]) => `| ${k} | ${b} | ${c} | ${s} |`), "",
+    failures.length ? `**${failures.length} regressão(ões) — gate BLOQUEADO.**` : "**Sem regressões — gate OK.**"].join("\n");
+  fs.mkdirSync(path.dirname(SUMMARY), { recursive: true });
+  fs.writeFileSync(SUMMARY, md + "\n");
+}
+
+if (UPDATE && failures.length === 0 && improvements.length) {
+  for (const [key, val] of improvements) baseline.metrics[key].value = val;
+  fs.writeFileSync(BASELINE, JSON.stringify(baseline, null, 2) + "\n");
+  console.log(`[quality-ratchet] baseline ratcheado: ${improvements.length} métrica(s) melhoraram`);
+}
+
+if (failures.length) { console.error("[quality-ratchet] FALHOU:\n" + failures.map((f) => "  ✗ " + f).join("\n")); process.exit(1); }
+console.log(`[quality-ratchet] OK (${rows.length} métricas, ${improvements.length} melhoraram)`);
+```
+
+- [ ] **Step 4: Rodar o teste e ver passar**
+```bash
+node --import tsx --test tests/unit/quality-ratchet.test.ts
+```
+Expected: PASS (5/5).
+
+- [ ] **Step 5: Commit**
+```bash
+git add scripts/quality/check-quality-ratchet.mjs tests/unit/quality-ratchet.test.ts
+git commit -m "feat(quality): generic ratchet comparator (multi-metric, regression-only)"
+```
+
+### Task 1.2: Coletor de métricas (ESLint warnings + cobertura)
+
+**Files:** Create: `scripts/quality/collect-metrics.mjs`
+
+- [ ] **Step 1: Implementar o coletor**
+```js
+#!/usr/bin/env node
+// scripts/quality/collect-metrics.mjs — emite quality-metrics.json
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+const cwd = process.cwd();
+const out = {};
+
+// 1) ESLint: contagem de warnings (errors devem ser 0; o lint já gata isso)
+function eslintCounts() {
+  let stdout;
+  try {
+    stdout = execFileSync("npx", ["eslint", ".", "--format", "json"], { encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+  } catch (e) { stdout = e.stdout?.toString() || "[]"; } // eslint sai !=0 quando há errors
+  const results = JSON.parse(stdout);
+  out.eslintWarnings = results.reduce((n, r) => n + (r.warningCount || 0), 0);
+  out.eslintErrors = results.reduce((n, r) => n + (r.errorCount || 0), 0);
+}
+
+// 2) Cobertura: lê coverage/coverage-summary.json se existir
+function coverage() {
+  const p = path.join(cwd, "coverage", "coverage-summary.json");
+  if (!fs.existsSync(p)) return;
+  const t = JSON.parse(fs.readFileSync(p, "utf8")).total;
+  out["coverage.statements"] = t.statements.pct;
+  out["coverage.lines"] = t.lines.pct;
+  out["coverage.functions"] = t.functions.pct;
+  out["coverage.branches"] = t.branches.pct;
+}
+
+eslintCounts();
+coverage();
+fs.writeFileSync(path.join(cwd, "quality-metrics.json"), JSON.stringify(out, null, 2) + "\n");
+console.log("[collect-metrics]", JSON.stringify(out));
+```
+
+- [ ] **Step 2: Rodar e inspecionar a saída**
+```bash
+node scripts/quality/collect-metrics.mjs && cat quality-metrics.json
+```
+Expected: JSON com `eslintWarnings`, `eslintErrors` e (se houver coverage) os 4 `coverage.*`. **Anote `eslintWarnings`.**
+
+- [ ] **Step 3: Commit**
+```bash
+git add scripts/quality/collect-metrics.mjs && echo "quality-metrics.json" >> .gitignore
+git add .gitignore && git commit -m "feat(quality): metrics collector (eslint warnings + coverage)"
+```
+
+### Task 1.3: Congelar o baseline inicial
+
+**Files:** Create: `quality-baseline.json` (**commitado**)
+
+- [ ] **Step 1: Gerar o baseline a partir das métricas reais** (use os números anotados):
+```json
+{
+  "_comment": "Catraca: 'down' nao pode aumentar, 'up' nao pode cair. Atualize via 'npm run quality:ratchet -- --update' (so em melhora).",
+  "metrics": {
+    "eslintWarnings": { "value": <N_REAL>, "direction": "down" },
+    "coverage.statements": { "value": <S>, "direction": "up" },
+    "coverage.lines": { "value": <L>, "direction": "up" },
+    "coverage.functions": { "value": <F>, "direction": "up" },
+    "coverage.branches": { "value": <B>, "direction": "up" }
+  }
+}
+```
+
+- [ ] **Step 2: Validar a catraca contra si mesma**
+```bash
+node scripts/quality/collect-metrics.mjs
+node scripts/quality/check-quality-ratchet.mjs; echo "exit=$?"
+```
+Expected: `[quality-ratchet] OK` e `exit=0`.
+
+- [ ] **Step 3: Provar que pega regressão** (teste manual): edite `quality-metrics.json` somando 1 a `eslintWarnings`, rode o comparador, confirme `exit=1`, depois descarte a edição.
+
+- [ ] **Step 4: Adicionar scripts npm**
+```json
+"quality:collect": "node scripts/quality/collect-metrics.mjs",
+"quality:ratchet": "node scripts/quality/check-quality-ratchet.mjs",
+"quality:gate": "npm run quality:collect && npm run quality:ratchet"
+```
+
+- [ ] **Step 5: Commit**
+```bash
+git add quality-baseline.json package.json
+git commit -m "feat(quality): freeze initial quality baseline (eslint warnings + coverage)"
+```
+
+### Task 1.4: Wire no CI (job + artefato + comentário no PR)
+
+**Files:** Modify: `.github/workflows/ci.yml`
+
+- [ ] **Step 1: Adicionar job `quality-gate`** (depois de `test-coverage`, para reusar `coverage/coverage-summary.json`):
+```yaml
+  quality-gate:
+    name: Quality Ratchet
+    runs-on: ubuntu-latest
+    needs: test-coverage
+    if: ${{ always() && needs.test-coverage.result == 'success' }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '24', cache: 'npm' }
+      - run: npm ci
+      - uses: actions/download-artifact@v4
+        with: { name: coverage-report, path: coverage/ }
+      - run: npm run quality:collect
+      - run: node scripts/quality/check-quality-ratchet.mjs --summary .artifacts/quality-ratchet.md
+      - if: always()
+        run: cat .artifacts/quality-ratchet.md >> "$GITHUB_STEP_SUMMARY"
+      - if: always()
+        uses: actions/upload-artifact@v4
+        with: { name: quality-ratchet, path: .artifacts/quality-ratchet.md }
+```
+
+- [ ] **Step 2: Adicionar comentário no PR** clonando o job `coverage-pr-comment` (marcador `<!-- omniroute-quality-ratchet -->`, lê `.artifacts/quality-ratchet.md`). Reuse o mesmo `github-script` de upsert de comentário.
+
+- [ ] **Step 3: Validar num PR de teste** — confirmar que o job aparece, o step summary mostra a tabela, e o comentário é postado.
+
+- [ ] **Step 4: Commit**
+```bash
+git add .github/workflows/ci.yml
+git commit -m "ci(quality): add quality-ratchet job with PR comment + artifact"
+```
+
+---
+
+# FASE 2 — Gates Determinísticos Anti-Alucinação
+
+> Cada gate ataca um ímã de alucinação específico (ver §2.4 do relatório). Todos no padrão `check-*.mjs`. **`check-fetch-targets` vem com código completo** (parsing determinístico de arquivos, sem risco de inventar nomes de export). **`check-provider-consistency` e `check-openapi-routes` começam com um Step 0 de verificação dos nomes reais** — propositalmente, porque fabricar a forma do import/spec seria o exato anti-padrão que este plano combate.
+
+### Task 2.1: `check-fetch-targets.mjs` — toda rota chamada pelo dashboard existe (TDD)
+
+**Ataca:** ímã nº2 (300 paths `fetch("/api/...")` sem ligação com as rotas).
+
+**Files:**
+- Create: `scripts/check/check-fetch-targets.mjs`
+- Test: `tests/unit/check-fetch-targets.test.ts`
+
+- [ ] **Step 1: Escrever o teste que falha**
+```ts
+// tests/unit/check-fetch-targets.test.ts
+import { test } from "node:test";
+import assert from "node:assert";
+import { resolveApiPathToRoute } from "../../scripts/check/check-fetch-targets.mjs";
+
+test("matches a static route file", () => {
+  const files = new Set(["src/app/api/usage/route.ts"]);
+  assert.equal(resolveApiPathToRoute("/api/usage", files), true);
+});
+
+test("matches a dynamic [param] segment", () => {
+  const files = new Set(["src/app/api/providers/[id]/models/route.ts"]);
+  assert.equal(resolveApiPathToRoute("/api/providers/abc-123/models", files), true);
+});
+
+test("rejects a hallucinated route", () => {
+  const files = new Set(["src/app/api/usage/route.ts"]);
+  assert.equal(resolveApiPathToRoute("/api/providers/refresh", files), false);
+});
+```
+
+- [ ] **Step 2: Rodar e ver falhar**
+```bash
+node --import tsx --test tests/unit/check-fetch-targets.test.ts
+```
+Expected: FAIL (módulo não existe).
+
+- [ ] **Step 3: Implementar o gate**
+```js
+#!/usr/bin/env node
+// scripts/check/check-fetch-targets.mjs
+// Todo fetch("/api/...") em src/app/(dashboard) deve resolver para um route.ts real.
+import fs from "node:fs";
+import path from "node:path";
+
+const cwd = process.cwd();
+const DASH = path.join(cwd, "src/app/(dashboard)");
+const API = path.join(cwd, "src/app/api");
+
+// allowlist de paths dinâmicos/externos que o checker não consegue resolver estaticamente
+const IGNORE = [/^\/api\/v1\//, /\$\{/, /` \+/]; // /v1 é a superfície OpenAI-compat; templates
+
+function walk(dir, acc = []) {
+  if (!fs.existsSync(dir)) return acc;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p, acc);
+    else if (/\.(ts|tsx)$/.test(e.name)) acc.push(p);
+  }
+  return acc;
+}
+
+function collectRouteFiles() {
+  return new Set(walk(API).filter((p) => /route\.tsx?$/.test(p)).map((p) => path.relative(cwd, p).replace(/\\/g, "/")));
+}
+
+export function resolveApiPathToRoute(apiPath, routeFiles) {
+  // apiPath ex.: /api/providers/abc/models  →  src/app/api/providers/[id]/models/route.ts
+  const segs = apiPath.replace(/^\//, "").replace(/[?#].*$/, "").split("/"); // ["api","providers","abc","models"]
+  for (const rf of routeFiles) {
+    const rsegs = rf.replace(/^src\/app\//, "").replace(/\/route\.tsx?$/, "").split("/"); // ["api","providers","[id]","models"]
+    if (rsegs.length !== segs.length) continue;
+    const ok = rsegs.every((rs, i) => rs === segs[i] || /^\[.*\]$/.test(rs));
+    if (ok) return true;
+  }
+  return false;
+}
+
+function extractFetchPaths(file) {
+  const src = fs.readFileSync(file, "utf8");
+  const re = /(?:fetch|fetchJson|apiFetch)\(\s*["'`](\/api\/[^"'`?]+)/g;
+  const out = [];
+  let m;
+  while ((m = re.exec(src))) out.push(m[1]);
+  return out;
+}
+
+function main() {
+  const routeFiles = collectRouteFiles();
+  const misses = [];
+  for (const f of walk(DASH)) {
+    for (const apiPath of extractFetchPaths(f)) {
+      if (IGNORE.some((rx) => rx.test(apiPath))) continue;
+      if (!resolveApiPathToRoute(apiPath, routeFiles)) misses.push(`${path.relative(cwd, f)} → ${apiPath}`);
+    }
+  }
+  if (misses.length) {
+    console.error(`[check-fetch-targets] ${misses.length} fetch(es) para rota inexistente:\n` + misses.map((m) => "  ✗ " + m).join("\n"));
+    process.exit(1);
+  }
+  console.log(`[check-fetch-targets] OK (${routeFiles.size} rotas conhecidas)`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main();
+```
+
+- [ ] **Step 4: Rodar o teste unitário e ver passar**
+```bash
+node --import tsx --test tests/unit/check-fetch-targets.test.ts
+```
+Expected: PASS (3/3).
+
+- [ ] **Step 5: Rodar o gate no repo real** (modo descoberta — pode encontrar misses legítimos)
+```bash
+node scripts/check/check-fetch-targets.mjs; echo "exit=$?"
+```
+Se encontrar misses reais: triagem — ou são rotas faltantes (bug), ou paths dinâmicos a adicionar ao `IGNORE`. **Não** mascare; documente cada exceção no `IGNORE` com comentário.
+
+- [ ] **Step 6: Adicionar script + commit**
+```json
+"check:fetch-targets": "node scripts/check/check-fetch-targets.mjs"
+```
+```bash
+git add scripts/check/check-fetch-targets.mjs tests/unit/check-fetch-targets.test.ts package.json
+git commit -m "feat(check): gate that every dashboard fetch() targets a real API route"
+```
+
+### Task 2.2: `check-provider-consistency.ts` — ids batem entre os 3 arquivos
+
+**Ataca:** ímã nº1 (split de provider; 229 vs 155 vs N já divergem).
+
+**Files:** Create: `scripts/check/check-provider-consistency.ts` (rodado via `tsx`); Test: `tests/unit/check-provider-consistency.test.ts`
+
+- [ ] **Step 0 (VERIFICAÇÃO — obrigatório antes de codar):** descobrir os nomes reais de export, para **não inventar**:
+```bash
+grep -nE "export (const|function) " src/shared/constants/providers.ts | grep -iE "provider|section" | head
+grep -nE "getOrCreateAiProviders|_PROVIDER_SECTIONS|AI_PROVIDERS" src/shared/constants/providers.ts | head
+grep -nE "baseUrl|^\s*['\"][a-z0-9-]+['\"]\s*:" open-sse/config/providerRegistry.ts | head
+grep -nE "case ['\"]|=== ['\"]|SPECIALTY_VALIDATORS" src/lib/providers/validation.ts | head
+```
+Anote: como enumerar os ids canônicos em runtime, a forma das chaves do `providerRegistry.ts`, e onde `validation.ts` lista os providers cobertos.
+
+- [ ] **Step 1: Escrever o teste** com fixtures sintéticas (3 conjuntos de ids), afirmando que o diff detecta um id presente em um e ausente em outro. (Implemente a lógica como função pura `diffProviderSets(canonical, registry, validators)` que retorna `{missingInRegistry, missingInValidators, orphanInRegistry}`.)
+
+- [ ] **Step 2: Rodar e ver falhar.**
+
+- [ ] **Step 3: Implementar** importando os ids reais (descobertos no Step 0) e cruzando-os. Reusar o padrão de `scripts/check/check-docs-counts-sync.mjs` (que **já conta** executors/oauth/strategies vs docs — é o template direto). Para ids que legitimamente vivem só num lugar, manter um `KNOWN_EXCEPTIONS` allowlist com comentário por entrada.
+
+- [ ] **Step 4: Rodar no repo real**, triar as divergências reais (as contagens já divergem — algumas serão bugs de registro pela metade, outras exceções legítimas).
+
+- [ ] **Step 5: Commit** (`feat(check): provider-id consistency gate across providers.ts/registry/validation`).
+
+**Critério de aceitação:** o gate falha quando um id existe em `providers.ts` mas não no `providerRegistry.ts` (ou vice-versa), e quando um model no registry referencia um provider id desconhecido.
+
+### Task 2.3: `check-openapi-routes.mjs` — spec ↔ rotas (bidirecional)
+
+**Ataca:** docs-hallucination (endpoint inventado no `openapi.yaml`).
+
+**Files:** Create: `scripts/check/check-openapi-routes.mjs`; Test correspondente.
+
+- [ ] **Step 0 (VERIFICAÇÃO):** confirmar o caminho e a forma do spec:
+```bash
+ls docs/reference/openapi.yaml && grep -nE "^\s{2,4}/[a-z]" docs/reference/openapi.yaml | head
+```
+Confirmar como `check-openapi-coverage.mjs` já parseia o YAML (reusar o parser dele).
+
+- [ ] **Step 1–5 (TDD):** teste com spec sintética → implementar: toda `path` do spec resolve para um `route.ts` (reusando `resolveApiPathToRoute` da Task 2.1) e toda rota não-interna aparece no spec (com allowlist para rotas LOCAL_ONLY/internas). Commit.
+
+### Task 2.4: `check-deps.mjs` — anti-slopsquatting
+
+**Ataca:** pacotes alucinados (CSA: 19,7% das amostras IA).
+
+**Files:** Create: `scripts/check/check-deps.mjs`; Test.
+
+- [ ] **Step 0 (VERIFICAÇÃO):** decidir política — allowlist = todas as deps atuais do `package.json`/lockfile como baseline; novas deps exigem (a) existir no registry, (b) idade ≥ 72h, (c) entrada explícita.
+- [ ] **Step 1–5 (TDD):** teste com `package.json` sintético adicionando uma dep nova → gate falha se a dep não está no baseline E (não existe no registry OU foi publicada há <72h). Usar `npm view <pkg> time.created` para idade. Reusar o padrão diff-base...HEAD de `check-pr-test-policy.mjs`. Commit.
+
+### Task 2.5 (opcional): lints Rule #11/#12 via `no-restricted-syntax`
+
+- [ ] Estender o `eslint.config.mjs` (bloco `no-restricted-syntax` já usado p/ a regra de busca turca) para sinalizar `NextResponse.json({ error: "<string>" })` cru (exigir `buildErrorBody()`) e literais de `clientIdDefault`/`clientSecretDefault` no `providerRegistry.ts` (exigir `resolvePublicCred()`). Ratchet via contagem (adoção 11% → sobe). TDD com fixtures de ESLint.
+
+**Plugar tudo da Fase 2 no CI:** adicionar `check:fetch-targets`, `check:provider-consistency`, `check:openapi-routes`, `check:deps` ao job `lint` (ou `docs-sync-strict`) do `ci.yml`, e ao pre-commit barato quando rápidos o suficiente.
+
+---
+
+# FASE 3 — Catraca de Duplicação + Tamanho (mata-slop) — *expandir em sub-plano*
+
+**Justificativa:** GitClear mostra duplicação 4–8× na era IA; é a assinatura nº1 de slop. Nenhum gate hoje (Sonar CPD excluído).
+
+**Specs (criar sub-plano `writing-plans` a partir daqui):**
+
+1. **Adicionar `jscpd` v5** como devDependency. Rodar `jscpd --reporters json src open-sse` → `quality-metrics.json` ganha `duplication.pct`. **[verificar no install]** o schema JSON do v5 antes de parsear (ver ressalva no relatório §4.2).
+2. **Estender `collect-metrics.mjs`** com um coletor de duplicação (lê o JSON do jscpd) e um coletor de **tamanho de arquivo** (conta LOC de cada arquivo em `src`+`open-sse`, emite `fileSize.<path>` para os arquivos já acima de um teto, ex. >700 LOC — congelando os 64 atuais).
+3. **Adicionar regras ESLint** em `eslint.config.mjs` como `warn`: `max-lines` (700), `max-lines-per-function` (80), `complexity` (15), `sonarjs/cognitive-complexity` (15). Coletor adiciona `eslintWarnings` por categoria (a contagem já está na catraca da Fase 1; opcionalmente segregar `complexityWarnings`).
+4. **Estender `quality-baseline.json`** com `duplication.pct` (`down`) e os `fileSize.*` dos arquivos grandes (`down` — só podem encolher; arquivos novos têm teto absoluto).
+5. **Teto absoluto para arquivos novos:** o gate falha se um arquivo **não** presente no baseline nasce acima do teto (ex. 700 LOC) — impede o próximo god-component.
+
+**Critérios de aceitação:** PR que aumenta a duplicação % falha; PR que cresce qualquer um dos 64 arquivos grandes falha; PR que cria arquivo novo >700 LOC falha; refator que encolhe um arquivo grande ratcheta o baseline para baixo (via `--update`).
+
+---
+
+# FASE 4 — Catraca de Cobertura + Anti Test-Masking — *expandir em sub-plano*
+
+**Specs:**
+
+1. **`check-coverage-ratchet`** já é coberto pelo motor da Fase 1 (as 4 métricas `coverage.*` com `direction: "up"`). Confirmar que o job `quality-gate` roda **após** o merge dos 8 shards de cobertura no CI (não localmente, onde a cobertura é parcial). Adicionar **epsilon** maior (ex. 0.5) para `coverage.branches` por causa do não-determinismo do v8.
+2. **Pisos por módulo crítico:** estender `collect-metrics.mjs` para emitir `coverage.<modulo>.lines` para uma lista curta de módulos de alto risco (lendo o `coverage-summary.json` por arquivo): `open-sse/handlers/chatCore.ts`, `open-sse/services/combo.ts`, `open-sse/services/accountFallback.ts`, `src/sse/services/auth.ts`, `src/server/authz/routeGuard.ts`, `open-sse/utils/error.ts`, `open-sse/utils/publicCreds.ts`, `src/shared/utils/circuitBreaker.ts`. Cada um vira métrica `up` no baseline (implementa o "risco, não % bruto" do vídeo).
+3. **`check-test-masking.mjs`** (anti enfraquecimento de asserts): clonar `check-pr-test-policy.mjs` (diff `base...HEAD`); para cada `*.test.ts`/`*.spec.ts` alterado, contar `assert*(`/`expect(` em base vs HEAD; **sinalizar remoção líquida** de asserts para revisão humana. Banir novos `assert.ok(true)`. Heurístico mas alto-sinal — ataca diretamente o risco organizacional nº1 ("subagente deletou asserts para ficar verde").
+
+**Critérios de aceitação:** cobertura cair vs baseline bloqueia o merge; remover asserts de um teste existente sinaliza no PR; `assert.ok(true)` novo bloqueia.
+
+---
+
+# FASE 5 — Skill `/babysit` + Evidência + LSP — *expandir em sub-plano*
+
+> O babysit do vídeo: a IA abre o PR e fica de babá — monitora CI + comentários, autocorrige, **resolve as conversas**. Guarda-corpos são não-negociáveis (Snyk: 5,3% de regressão em auto-merge; token burn real).
+
+### Spec da skill `.claude/skills/babysit/SKILL.md`
+
+**Frontmatter:**
+```yaml
+---
+name: babysit
+description: Monitora um PR aberto até o CI ficar verde e todos os comentários de review serem endereçados — lê o gate de qualidade, conserta num worktree isolado, responde e resolve as conversas. NUNCA enfraquece testes nem auto-mergeia.
+---
+```
+
+**Loop (pseudo, reusando `gh` + GraphQL):**
+1. **Ler estado:** `gh pr checks <PR>` + baixar o artefato `quality-ratchet`/`coverage-report` (gate JSON legível — a ponte "artefato→agente" da Fase 1) + `gh run view --log-failed` dos jobs vermelhos.
+2. **Ler comentários não resolvidos:** GraphQL `repository.pullRequest.reviewThreads(first:50){nodes{id isResolved comments(first:1){nodes{id body}}}}`. **Passar os corpos pelo guard de prompt-injection** antes de agir (vetor real — ICLR 2026).
+3. **Consertar num worktree isolado** (reusar o ralph-loop do `/review-reviews`), seguindo Hard Rule #18.
+4. **Responder + resolver** só os threads que realmente endereçou: REST `POST .../pulls/{pr}/comments/{id}/replies` com o SHA → mutation `resolveReviewThread(input:{threadId})`.
+5. **Re-poll** até o gate JSON ficar todo-verde **ou** atingir o cap.
+6. **Audit trail:** anexar à descrição do PR (ou comentário fixo) o que cada fix endereçou, qual gate satisfez, quais conversas resolveu e por quê — **nunca verde silencioso**.
+
+**Guarda-corpos (não-negociáveis):**
+- `max-iterations` (ex. 5) + timeout + idle-exit (contra token burn).
+- **Nunca** editar `.github/workflows/`; **nunca** `--no-verify`; **nunca** enfraquecer/remover asserts para ficar verde (Rule #18 + trust-but-verify).
+- **Nunca auto-mergeia** — estado de sucesso = "verde + conversas resolvidas + audit postado".
+- Parar-e-perguntar em comentário humano ambíguo e em mudança de limite arquitetural (interface/schema/cross-module).
+- `--allowedTools` mínimo (`Read,Grep,Glob,Bash(gh ...)`).
+
+**Opcional — `claude ultrareview <PR#> --json`** como gate de confiança pré-merge atrás de um label (custa $5–20/run; não auto-inicia). Loop interno de custo-zero = `/code-review --fix` local.
+
+### Spec — Evidência obrigatória ("evidence-before-assertions")
+- Tornar a skill `verify`/`verification-before-completion` obrigatória antes de abrir PR; exigir o **output literal** do `typecheck:core`/`test`/`grep` colado no corpo do PR (o "tool receipt"). Adicionar um `check-pr-evidence.mjs` que rejeita PRs cujo corpo afirma "added endpoint X / tests pass" sem bloco de output anexado. Formaliza a Rule #18.
+
+### Spec — LSP-in-the-loop (opcional)
+- Registrar `agent-lsp` (MCP) ou o `tsserver` para os agentes terem `blast_radius`/diagnostics e `preview_edit` antes de escrever — vira "símbolo inventado" de catch-de-review para impossibilidade-no-edit. Pareia com `typecheck:core` como gate pré-PR (compile-before-claim).
+
+**Critérios de aceitação:** a skill `/babysit <PR#>` leva um PR de vermelho a verde sem auto-merge, resolve só as conversas que endereçou, respeita o cap de iterações, e deixa rastro auditável; nenhum assert é enfraquecido.
+
+---
+
+## Self-Review (checklist do autor)
+
+- **Cobertura do spec:** Fases 0–2 mapeiam 1:1 com as recomendações do relatório §5; Fases 3–5 cobrem duplicação/tamanho, cobertura/masking e babysit/evidência. ✓
+- **Sem placeholders nos passos bite-sized:** Fases 0/1/2.1 têm comandos e código reais. As Fases 2.2–2.4 usam um Step-0 de verificação **deliberado** (não placeholder) para não fabricar nomes de export — coerente com o objetivo anti-alucinação. ✓
+- **Consistência de tipos:** `resolveApiPathToRoute` (Task 2.1) é reusada na Task 2.3; o comparador usa o mesmo formato `{value, direction}` em todas as fases; `quality-metrics.json` é a interface única coletor↔comparador. ✓
+- **Ordem de dependência:** Fase 1 (motor) precede 3/4 (que só adicionam métricas ao baseline); Fase 0 destrava o resto. ✓
+
+## Handoff de Execução
+
+**Plano salvo em `PLANO-QUALITY-GATES.md`.** Duas opções:
+
+1. **Subagent-Driven (recomendado)** — um subagente fresco por task, review entre tasks. SUB-SKILL: `superpowers:subagent-driven-development`.
+2. **Inline** — executar nesta sessão com checkpoints. SUB-SKILL: `superpowers:executing-plans`.
+
+**Recomendação:** começar pela **Fase 0** (quick wins, baixo risco) e **Fase 1** (motor de catraca) numa branch `feat/quality-ratchet`, validar num PR de teste, e só então abrir as fases anti-alucinação. Fases 3–5 viram sub-planos próprios.

README.md

@@ -15,12 +15,30 @@
 
 <br/>
 
+**~1.9B+ documented free tokens/month** — up to **~2.5B in your first month** with signup credits — aggregated across the free tiers, and the compression above stretches every one further. ([how we count →](docs/reference/FREE_TIERS.md#tldr--how-much-free-inference-does-omniroute-actually-aggregate))
+
+<br/>
+
 [![177 AI Providers](https://img.shields.io/badge/177-AI_Providers-6C5CE7?style=for-the-badge)](#-177-ai-providers--50-free)
 [![50+ Free](https://img.shields.io/badge/50%2B-Free_Tiers-00B894?style=for-the-badge)](#-177-ai-providers--50-free)
+[![1.9B+ Free Tokens/mo](https://img.shields.io/badge/1.9B%2B-Free_Tokens%2Fmo-00B894?style=for-the-badge)](docs/reference/FREE_TIERS.md)
 [![Token Savings](https://img.shields.io/badge/up_to_95%25-Token_Savings-E17055?style=for-the-badge)](#%EF%B8%8F-save-1595-tokens--automatically)
 [![14 Strategies](https://img.shields.io/badge/14-Routing_Strategies-0984E3?style=for-the-badge)](#-combos--the-flagship)
 [![$0 to start](https://img.shields.io/badge/%240-To_Start-FDCB6E?style=for-the-badge&logoColor=black)](#-quick-start)
 
+<br/>
+
+### 💬 Join the community
+
+[![Discord](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/hmexnhgE)
+[![Telegram](https://img.shields.io/badge/Telegram-26A5E4?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/omnirouteOficial)
+[![WhatsApp Global](https://img.shields.io/badge/WhatsApp_Global-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+[![WhatsApp Brasil](https://img.shields.io/badge/WhatsApp_Brasil-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/BTGJXIyjeNIIgExvTMGGhI)
+
+**Questions, provider tips, roadmap & support → [Discord](https://discord.gg/hmexnhgE) · [Telegram](https://t.me/omnirouteOficial) · WhatsApp [🌍 Global](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) / [🇧🇷 Brasil](https://chat.whatsapp.com/BTGJXIyjeNIIgExvTMGGhI)**
+
+<br/>
+
 <a href="https://trendshift.io/repositories/23589" target="_blank"><img src="https://trendshift.io/api/badge/repositories/23589" alt="diegosouzapw%2FOmniRoute | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 
 [![npm](https://img.shields.io/npm/v/omniroute?logo=npm&style=flat-square)](https://www.npmjs.com/package/omniroute)
@@ -41,7 +59,7 @@
 
 <br/>
 
-[**🚀 Quick Start**](#-quick-start) • [**🎯 Combos**](#-combos--the-flagship) • [**🌐 Providers**](#-177-ai-providers--50-free) • [**🔌 CLI & MCP**](#-full-cli--a2a--mcp) • [**🗜️ Compression**](#%EF%B8%8F-save-1595-tokens--automatically) • [**🌍 Website**](https://omniroute.online) • [**💬 WhatsApp 🌍**](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) • [**💬 WhatsApp 🇧🇷**](https://chat.whatsapp.com/CeGCxdFzqBe5Uki288wOvf)
+[**🚀 Quick Start**](#-quick-start) • [**🎯 Combos**](#-combos--the-flagship) • [**🌐 Providers**](#-177-ai-providers--50-free) • [**🔌 CLI & MCP**](#-full-cli--a2a--mcp) • [**🗜️ Compression**](#%EF%B8%8F-save-1595-tokens--automatically) • [**🌍 Website**](https://omniroute.online)
 
 [💥 The Promise](#-the-promise) • [🤔 Why](#-why-omniroute) • [🏆 What Sets Apart](#-what-sets-omniroute-apart) • [🤖 Compatible CLIs](#-compatible-clis--coding-agents) • [🖥️ Where It Runs](#%EF%B8%8F-where-omniroute-runs--anywhere) • [🔒 Private](#-private--local-first) • [🎬 In Action](#-omniroute-in-action) • [📚 Explore More](#-explore-more) • [📧 Support](#-support--community)
 
@@ -96,6 +114,24 @@
 
 <div align="center">
 
+# 💰 ~1.9B Free Tokens / Month
+
+</div>
+
+> Stacking free tiers by hand is painful — dozens of SDKs, dozens of rate limits, and no idea how much you actually have. OmniRoute aggregates the **documented** free tiers of **50+ provider pools / 530 models** into one honest number and shows it live on the dashboard (`/dashboard/free-tiers`).
+
+- **~1.9B free tokens / month** (steady) — and **up to ~2.5B in your first month** with signup credits.
+- **Pool-deduped, honest** — we count each shared free pool **once**, so the headline isn't inflated by rate-limit ceilings the way multi-billion competitor claims are. (The naïve per-model sum would read ~8B; we don't publish that.)
+- **Per-model breakdown**, **live used / remaining** for the current month, and a transparent **terms flag** per provider.
+
+![Free-Tier Budget card (preview mockup)](docs/screenshots/free-tier-budget-card.svg)
+
+> Preview mockup — a real screenshot lands once the `/dashboard/free-tiers` page is validated. Full methodology (pool dedupe, credit tiers, provider terms): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
+
+<br/>
+
+<div align="center">
+
 # 💥 The Promise
 
 </div>
@@ -487,6 +523,19 @@ curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"
 
 You should see your connected models listed. 🎉 That's it — start coding, and OmniRoute auto-routes & falls back for you.
 
+If your client cannot send custom headers, OmniRoute also exposes tokenized compatibility aliases:
+
+```txt
+OpenAI catalog:   http://localhost:20128/vscode/YOUR_KEY/
+OpenAI models:    http://localhost:20128/vscode/YOUR_KEY/models
+OpenAI chat:      http://localhost:20128/vscode/YOUR_KEY/chat/completions
+OpenAI responses: http://localhost:20128/vscode/YOUR_KEY/responses
+Ollama chat:      http://localhost:20128/vscode/YOUR_KEY/api/chat
+Ollama tags:      http://localhost:20128/vscode/YOUR_KEY/api/tags
+```
+
+Use these only for clients that cannot attach `Authorization: Bearer ...`. Header auth remains the preferred mode.
+
 <br/>
 
 ## 📦 More install methods — Docker, source, pnpm, Arch</b></summary>
@@ -530,6 +579,22 @@ devbox run npm run dev
 
 📖 [Docker Guide](docs/guides/DOCKER_GUIDE.md) — Compose profiles, Caddy HTTPS, Cloudflare tunnels.
 
+**🦭 Podman**
+
+```bash
+# 1. Build the image
+podman build --target runner-base -t omniroute:base .
+
+# 2. Fix data directory permissions for rootless Podman
+mkdir -p data && podman unshare chown 1000:1000 ./data
+
+# 3. Set runtime in .env, then run (see contrib/podman/ for Quadlet)
+echo "CONTAINER_HOST=podman" >> .env
+podman compose --profile base up -d
+```
+
+📖 [Podman Guide](contrib/podman/README.md) — Quadlet setup, podman-compose, Quadlet.
+
 </details>
 
 <br/>
@@ -712,8 +777,7 @@ Compression: aggressive (~50%) → double your free quota · Cost: $0/mo
 
 # 📧 Support & Community
 
-> 💬 **Join our WhatsApp groups** — get help, share tips, stay updated:
-> · [**🌍 International**](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) · [**🇧🇷 Português**](https://chat.whatsapp.com/CeGCxdFzqBe5Uki288wOvf)
+> 💬 **Chat with the community** — Discord, Telegram & WhatsApp (🌍 / 🇧🇷) links are at the [top of this README](#-join-the-community).
 
 - 🌍 **Website**: [omniroute.online](https://omniroute.online)
 - 🐙 **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
@@ -769,6 +833,7 @@ Compression: aggressive (~50%) → double your free quota · Cost: $0/mo
 | Document                                             | Description                                                    |
 | ---------------------------------------------------- | -------------------------------------------------------------- |
 | [Docker Guide](docs/guides/DOCKER_GUIDE.md)                 | Docker run, Compose profiles, Caddy HTTPS, tunnels, image tags |
+| [Podman Guide](contrib/podman/README.md)                   | Quadlet systemd integration, podman-compose, SELinux           |
 | [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md)         | Complete guide: VM + nginx + Cloudflare setup                  |
 | [Fly.io Deployment](docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) | Deploy to Fly.io with persistent storage                       |
 | [Termux Guide](docs/guides/TERMUX_GUIDE.md)                 | Run OmniRoute on Android via Termux                            |
@@ -948,8 +1013,6 @@ Special thanks to **[RTK - Rust Token Killer](https://github.com/rtk-ai/rtk)** b
 
 Special thanks to **[Troglodita](https://github.com/leninejunior/troglodita)** by **[Lenine Júnior](https://github.com/leninejunior)** — the PT-BR token compression project ("por que gastar muitos tokens quando poucos resolve?") whose Portuguese-native rules power OmniRoute's pt-BR language pack: pleonasm reduction, filler removal tuned for Brazilian Portuguese grammar, and technical abbreviations for the dev BR community.
 
-<br/>
-
 ## 📄 License
 
 MIT License - see [LICENSE](LICENSE) for details.

RELATORIO-QUALITY-GATES.md

@@ -0,0 +1,219 @@
+# Relatório — Quality Gates, Catraca & Anti-Alucinação no OmniRoute
+
+> **Data:** 2026-06-09
+> **Origem:** Auditoria do projeto (5 subagentes Opus em paralelo mapeando todas as pastas exceto `node_modules`/`_references`/`dist`) + análise da transcrição do vídeo *"Qualidade de código"* (Stupid Button Club, 2026-05-04) + pesquisa web 2026 (4 frentes, últimos ~3 meses).
+> **Companheiro:** Veja [`PLANO-QUALITY-GATES.md`](./PLANO-QUALITY-GATES.md) para o plano de implementação bite-sized (TDD).
+
+---
+
+## 0. TL;DR
+
+1. **O OmniRoute já é muito mais maduro** que o projeto "Strawberry" do vídeo: tem CI com 20 jobs, gate de cobertura, ESLint 9 flat, SonarQube, 14 scripts `check-*.mjs` e **uma catraca real já funcionando** (`check-t11-any-budget.mjs` — orçamento de `any` por arquivo que só pode encolher). O vídeo descreve onde queremos chegar; nós já estamos a meio caminho.
+2. **Mas faltam exatamente as catracas que o vídeo prega.** Não há baseline congelado de métricas, nem gate de **duplicação**, nem de **tamanho de arquivo**, e o gate de cobertura é um **piso fixo** — não uma catraca "nunca piorar".
+3. **Há derivas (drifts) reais que pegamos na auditoria:** o gate de cobertura **no CI é `40/40/40/40`** (ci.yml:377), não os `60/60/60/60` que o CLAUDE.md anuncia (esse é só o script local). O Husky está **100% comentado** (zero gate local). O SonarQube tem `coverage` e `cpd` **excluídos** (`sonar-project.properties:9-10`) — as duas métricas mais úteis contra "slop" estão desligadas. E 3 scripts `check-*` existem mas **não rodam em lugar nenhum**.
+4. **Os maiores ímãs de alucinação são estruturais:** o split de provider em 3 arquivos gigantes em 2 workspaces (`providers.ts` ↔ `providerRegistry.ts` ↔ `validation.ts`, com contagens que já divergem: 229 ids vs 155 blocos vs N validadores), os 300 paths `fetch("/api/...")` hardcoded sem ligação de compilação com as rotas, e o arquivo de **12.760 linhas** (`providers/[id]/page.tsx`) que nenhum agente consegue segurar em contexto.
+5. **2026 confirma a tese do vídeo com dados:** GitClear (211M linhas) mostra duplicação crescendo 4–8× na era da IA; o paper SlopCodeBench prova que *instrução de prompt sozinha não impede a degradação* — só gates determinísticos seguram. O ecossistema 2026 tem ferramentas maduras para cada métrica (jscpd v5, knip v6, eslint-plugin-sonarjs v4, osv-scanner, Qlty, Sonar "Clean as You Code"/"AI Code Assurance").
+6. **A jogada é em camadas:** (a) reativar/reconciliar o que já existe; (b) construir o **motor de catraca** (baseline.json + coletor + comparador, clonando o `any-budget`); (c) adicionar **gates determinísticos anti-alucinação** (provider-consistency, fetch-target, openapi-routes); (d) catraca de **duplicação + tamanho**; (e) catraca de **cobertura** + detecção de test-masking; (f) skill **`/babysit`** com guarda-corpos. Detalhe no plano.
+
+---
+
+## 1. O que o vídeo ensina (insights destilados)
+
+O vídeo é uma fala sem roteiro sobre *qualidade de código no mundo em que a IA escreve ~100% do código*. Pontos centrais:
+
+| # | Insight | Citação/essência |
+|---|---------|------------------|
+| 1 | **O humano virou o gargalo.** | "Eu acabei virando o gargalo da IA. Fazer o babysit das coisas do request básicas é o gargalo. Não consigo entregar 4 tarefas ao mesmo tempo se preciso ler 10.000 linhas/dia." |
+| 2 | **Quality Gate = portão que a IA tem que passar.** | Todo PR passa por um portão; a IA fica em loop se autocorrigindo até ficar verde, em vez de o humano revisar e pedir refação. |
+| 3 | **Baseline + Catraca (ratchet).** | "Tu congela o baseline e o repositório só pode melhorar a partir dali ou empatar." A catraca anda num sentido só. |
+| 4 | **Regra de ouro.** | "Cada PR pode adicionar código, mas não pode aumentar nenhuma das métricas — nem por uma violação, nem por uma linha, nem por 0,1 ponto percentual." |
+| 5 | **Métricas do baseline.** | Violações de ESLint (483 em 120 arquivos), duplicação de código (2,2% via JSCPD), cobertura (%), arquivos acima do limite de tamanho (19 arquivos; o maior com 4.600 linhas). |
+| 6 | **Pipeline de CI.** | `npm ci` → `npm audit` (critical=bloqueia / high=avisa) → `npm run lint` → `test:coverage` → **script node de quality gate** que compara métricas atuais vs `baseline.json` e falha em qualquer regressão → comentário no PR + **upload de artefatos** que o agente lê para se autocorrigir. |
+| 7 | **Artefatos legíveis pelo agente.** | "Não adianta cuspir isso no PR. O agente precisa ter acesso ao que está dando errado." |
+| 8 | **Babysit skill.** | "Recomendo criar uma skill de babysit": a IA monitora o CI + comentários dos revisores, endereça os comentários e **resolve as conversas** para dar rastreabilidade no GitHub. |
+| 9 | **Comentários perto do código (legibilidade p/ agente).** | Mudou de ideia: antes era contra comentários ("o código é a documentação"); agora, no mundo de agentes, comentário explicando *o quê* e *por quê* perto do código vale mais que um MD gigante, porque o harness faz `grep` no arquivo e lê o comentário junto. |
+| 10 | **É "só" colar ferramentas.** | "Não é nada excepcional. Eu só estou colando um monte de ferramentas e chamando de quality gate." Pode-se usar SonarQube ou GitHub Code Quality no lugar do script caseiro. |
+| 11 | **Por que a IA não faz certo de primeira.** | Modelos top já sabem (foram treinados com os livros), mas são "preguiçosos" porque output imperfeito = mais tokens vendidos. A catraca força o nível. |
+
+**Tradução para o nosso contexto:** o vídeo descreve um sistema que **já temos em embrião** (o `any-budget` é exatamente a catraca da regra de ouro, só que para uma métrica). O salto é (1) generalizar a catraca para todas as métricas, (2) reconciliar os drifts, e (3) fechar os buracos anti-alucinação que são específicos do nosso tamanho.
+
+---
+
+## 2. Onde o OmniRoute está hoje (panorama auditado)
+
+### 2.1 O que já temos (e o vídeo nem sonha)
+
+- **CI robusto** (`.github/workflows/ci.yml`, ~25 KB, 20 jobs): lint + audit + cycles + route-validation + any-budget + docs-sync + typecheck (core e noimplicit) + build + package-artifact + electron-smoke + unit (8 shards) + Node 24/26 compat + coverage (8 shards + merge) + SonarQube + e2e (9 shards) + integration + security.
+- **Catraca real já existente:** `scripts/check/check-t11-any-budget.mjs` — array `{file, maxAny}` (a maioria `0`), strip de comentários, anotações de falso-positivo, `exit 1` em regressão. **É o template exato da catraca do vídeo.**
+- **14 scripts `check-*.mjs`** (cycles, route-validation, any-budget, docs-sync, docs-counts, env-doc-sync, deprecated-versions, doc-links, cli-i18n, openapi-coverage, openapi-security-tiers, pr-test-policy, node-runtime, test-report-summary) — vários já são *gates de consistência fonte-vs-derivado*, o mesmo padrão que precisamos para anti-alucinação.
+- **PR test policy:** `check-pr-test-policy.mjs` já força "mudou código de produção ⇒ mudou teste" (diff base...HEAD).
+- **Cobertura sumarizada + comentada no PR:** `test-report-summary.mjs` + `coverage/coverage-summary.json` + job `coverage-pr-comment` (comentário com marcador `<!-- omniroute-coverage-report -->`). **Isto é exatamente o "artefato legível pelo agente" do vídeo** — já construído.
+- **Disciplina TDD institucionalizada** (Hard Rule #18: todo fix precisa de teste falha→passa ou validação ao vivo no VPS).
+- **SonarQube** configurado (job no CI + `sonar-project.properties`).
+- **Skills agênticas de review** já existem: `/review-prs`, `/review-reviews` (bateria de 8 reviewers + ralph-loop), `/code-review`, `/generate-release` (a única com babysit real de CI, mas de workflows de *release*, não do `ci.yml` do PR).
+
+### 2.2 O que está DESLIGADO ou inerte ⚠️ (achados da auditoria)
+
+| Item | Estado | Evidência | Impacto |
+|------|--------|-----------|---------|
+| **Husky** | 100% comentado (pre-commit **e** pre-push) | `.husky/pre-commit`, `.husky/pre-push` (todas as linhas com `#`) | Zero enforcement local — lint-staged, docs-sync, any-budget, env-doc-sync, openapi checks e o `test:unit` de pre-push dependem 100% do CI. |
+| **Gate de cobertura no CI** | **40/40/40/40** (não 60) | `ci.yml:377` `--statements 40 --lines 40 --functions 40 --branches 40` | O comentário do PR renderiza contra 60, o script local gata 60, o RELEASE_CHECKLIST diz 75/70, e o baseline real é ~79–82%. **O único número que bloqueia merge é 40** → gate de cobertura quase banguela. |
+| **Sonar coverage** | Excluído | `sonar-project.properties:9` `sonar.coverage.exclusions=**/*` | Sonar ignora cobertura de todo arquivo. |
+| **Sonar CPD (duplicação)** | Excluído | `sonar-project.properties:10` `sonar.cpd.exclusions=**/*` | Sonar não detecta copy-paste — a assinatura nº1 de slop de IA. |
+| **SonarQube job** | Inerte | `ci.yml` roda scan só se `PR && SONAR_TOKEN != '' && SONAR_HOST_URL != ''`; sem `qualitygate.wait` | Em runs sem secret, escreve "skipped"; mesmo quando roda, nunca falha o build. |
+| **`npm audit`** | Plano (`moderate`), não escalonado | `package.json:112` `--audit-level=moderate` | O vídeo prega critical=bloqueia / high=avisa. O nosso é um nível único. |
+| **3 scripts órfãos** | Sem CI nem husky | `check:cli-i18n`, `check:openapi-coverage`, `check:openapi-security-tiers` | Existem, dão `exit 1`, mas não rodam em lugar nenhum (Hard Rules #15/#17 guardadas só por um deles). |
+| **`typecheck:noimplicit:core`** | `continue-on-error: true` | `ci.yml:45-46` | Warn-only "forward-looking". |
+
+### 2.3 Hotspots de tamanho (sem gate hoje)
+
+`64 arquivos > 1000 LOC`, `194 > 500 LOC` (src + open-sse, sem testes). Top:
+
+| LOC | Arquivo | Risco para edição por IA |
+|-----|---------|--------------------------|
+| **12.760** | `src/app/(dashboard)/dashboard/providers/[id]/page.tsx` | God-component: **192 `useState`**, 21 `useEffect`, 87 `fetch()` inline, 34 tipos inline. Nenhuma IA segura em contexto; qualquer edição arrisca apagar estado não relacionado. |
+| 5.977 | `open-sse/handlers/chatCore.ts` | God-handler: 58 funções, invariantes demais, blast radius alto. |
+| 4.590 | `open-sse/config/providerRegistry.ts` | Array gigante providers+models+OAuth; mistura `resolvePublicCred()` e literais crus. |
+| 4.456 | `open-sse/services/combo.ts` | 14 estratégias num `if/else if` sem enum/exhaustiveness — estratégia desconhecida vira no-op silencioso. |
+| 4.349 | `src/app/(dashboard)/dashboard/combos/page.tsx` | 51 `useState`, mesmo padrão god-component. |
+| 4.205 | `src/lib/providers/validation.ts` | Mega-função com closures e `SPECIALTY_VALIDATORS` definidos *dentro* da função. |
+| 3.776 | `open-sse/handlers/imageGeneration.ts` | Branching multi-provider num handler. |
+| 3.076 | `src/shared/constants/providers.ts` | 229 ids em 27 consts agrupados via `Proxy` — sem lista plana. |
+| 2.869 | `open-sse/executors/chatgpt-web.ts` | Sessão web reversa; classe só começa na linha 2443. |
+| 2.278 | `src/app/api/providers/[id]/models/route.ts` | God-route: importa ~30 módulos provider-específicos e ramifica por provider num GET. |
+
+### 2.4 Ímãs de alucinação (ranqueados, da auditoria)
+
+1. **Split de provider em 3 arquivos / 2 workspaces (nº1).** Não há lista plana de providers — 229 ids escondidos atrás de 27 consts + merge via `Proxy` (`AI_PROVIDERS`). Uma IA não consegue enumerar "quais providers existem" barato → **inventa ids plausíveis** (variantes `*-web`/`*-cli` inexistentes) ou registra no grupo errado. As três contagens (`providers.ts` 229 ids ↔ `providerRegistry.ts` 155 blocos ↔ `validation.ts` N validadores) **já divergem**, então não há cross-check autoritativo. *(Esse é o tema recorrente das nossas memórias de alucinação — ex.: ids inventados, modelos inexistentes.)*
+2. **300 paths `fetch("/api/...")` hardcoded** no dashboard (659 call sites), sem client tipado. Refatore uma rota e os call sites apodrecem silenciosamente; uma IA editando a UI inventa rota (`/api/providers/[id]/refresh`) ou assume `res.error.message` numa rota que devolve `{error:"..."}`. Sem ligação de símbolo entre os 659 call sites e os 488 `route.ts`.
+3. **Dual chat stack (armadilha documentada).** Seleção/fallback de conta vive em `src/sse/` (não `open-sse/`). Uma IA pedida para "consertar fallback de conta" edita `open-sse/handlers/chatCore.ts` (errado) em vez de `src/sse/services/auth.ts`. Nada no código cruza os dois stacks. *(Já erramos um diagnóstico público por isso.)*
+4. **Estratégias de combo inventadas.** 14 nomes reais soterrados num `if/else` de strings (sem enum exportado) → IA inventa nomes plausíveis-mas-falsos (`"latency-optimized"`, `"failover"`) que passam no typecheck como string e viram no-op.
+5. **Métodos de executor inventados.** O padrão real é "sobrescreve `execute()` inteiro" (48/50 executors), sem hooks documentados → IA inventa `buildRequest`/`parseChunk`/`mapError` que não existem em `BaseExecutor`.
+6. **Helpers de erro inventados** + queda para `err.message` cru (viola Rule #12) quando o helper inventado "falha"; 5 web executors hoje **não importam helper nenhum**.
+7. **AGENTS.md de DB defasado:** documenta 21 migrations / 22 módulos quando o real é **94 / 75** — uma IA lendo isso acredita em conjuntos de tabelas/módulos que não existem mais.
+8. **Route-guard omitido:** rotas novas spawn-capazes (`/api/services/`, `/api/mcp/`) devem entrar em `LOCAL_ONLY_API_PREFIXES`; a convenção está só no CLAUDE.md, não num teste que a IA veja (parcialmente coberta por 1 script órfão).
+
+---
+
+## 3. Gap analysis — modelo do vídeo vs OmniRoute
+
+| Métrica/peça do vídeo | OmniRoute hoje | Gap |
+|-----------------------|----------------|-----|
+| `npm ci` determinístico | ✅ em todos os 14 jobs | — |
+| `npm audit` critical=bloqueia / high=avisa | ⚠️ `--audit-level=moderate` (nível único) | **Escalonar** em dois invokes |
+| `lint` | ✅ bloqueante | — |
+| `test` + cobertura | ✅ mas piso **40** no CI (drift) | **Reconciliar** p/ baseline real + catraca |
+| **Contagem de ESLint congelada** | ❌ (lint é 0-erros, mas warnings livres) | **Construir** (ratchet de violações) |
+| **Duplicação % (JSCPD)** | ❌ (Sonar CPD excluído, sem jscpd) | **Construir** (jscpd + catraca) |
+| **Limite de tamanho de arquivo** | ❌ (sem `max-lines`, sem script) | **Construir** (ESLint max-lines + catraca, freeze dos 64) |
+| **`baseline.json` congelado** | ❌ (nenhum baseline de métricas no repo) | **Construir** (o coração da catraca) |
+| **Script comparador (regra de ouro)** | 🟡 existe **para `any`** (`any-budget`) | **Generalizar** p/ todas as métricas |
+| **Sumário markdown + artefatos p/ o agente** | ✅ (coverage summary + PR comment + artifact) | **Reusar** wholesale |
+| **Babysit skill (monitora CI + resolve conversas)** | 🟡 `review-prs`/`review-reviews`/`generate-release` parciais; nenhuma resolve threads do PR nem loopa no `ci.yml` | **Construir** `/babysit` |
+| **Comentários perto do código p/ legibilidade de agente** | 🟡 `routeGuard.ts` é exemplar; resto irregular | **Padrão cultural** (Karpathy/guidelines) |
+
+---
+
+## 4. O que o mundo faz em 2026 (pesquisa, últimos ~3 meses)
+
+> Todas as fontes abaixo vêm com URL + data nas seções de origem (ver §7). Onde a pesquisa **não conseguiu confirmar** algo de fonte primária, está marcado **[não-verificado]** — honestidade de engenharia.
+
+### 4.1 Catraca / baseline-freeze (a "catraca" do vídeo)
+
+- **betterer** — o tool canônico de ratchet (snapshot de métrica → `.betterer.results`; CI falha se piora, auto-atualiza se melhora). **[caveat]** Baixa velocidade: último commit no `master` em **ago/2025**, releases vazias no GitHub. Viável, mas **não** apostar como peça load-bearing de longo prazo.
+- **eslint-formatter-ratchet** — formatter que congela contagem de violações de ESLint. **Ativamente mantido** (commit 2026-03-17). Mais estreito (só ESLint) mas é a trajetória oposta ao betterer.
+- **SonarQube "Clean as You Code" (new-code conditions)** — o padrão baseline-freeze mais maduro: o quality gate aplica condições **só ao código novo** (branch de referência), grandfathering do legado. Atual.
+- **SonarQube "AI Code Assurance" (2026.1.0)** — gate específico para código gerado por IA (tag o projeto → workflow de assurance + "Sonar way for AI Code" mais estrito). **[não-verificado]** se *bloqueia* o PR (docs canônicas deram 404; descrito como "enforced quality gate" mas mecânica de bloqueio não confirmada em fonte única).
+- **Qlty CLI (qlty.sh)** — o produto 2026 mais aderente: CLI Rust **OSS e grátis** (v0.630.0, 2026-05-08) que agrega 70+ analisadores; tem **Baseline analysis** (= a catraca), **Quality Gates** com veredito go/no-go e coverage gates. **[caveat]** `qlty metrics` (a tabela LOC/complexidade) **não tem flag JSON** — só `qlty check --sarif`/`qlty smells --sarif`; o ratchet de tamanho/complexidade por arquivo ainda precisa do JSON do ESLint.
+- **Code Climate Quality → Qlty** — a marca clássica de ratchet virou empresa separada (Qlty, nov/2024). Write-ups antigos de "Code Climate" = Qlty hoje.
+
+### 4.2 Ferramentas de métrica por tipo (todas com JSON p/ alimentar a catraca)
+
+| Métrica | Tool 2026 | Comando JSON | Status |
+|---------|-----------|--------------|--------|
+| Duplicação | **jscpd v5** (reescrita Rust) | `jscpd --reporters json` (ou `sarif`) | Muito ativo (v5.0.4, 2026-06-08). **[caveat]** schema JSON v4→v5 não confirmado — verificar no install. |
+| Tamanho/fn-length/ciclomática | **ESLint core** (`max-lines`, `max-lines-per-function`, `complexity`) | `eslint --format json` | Built-in ESLint 9 |
+| Complexidade cognitiva | **eslint-plugin-sonarjs** (`sonarjs/cognitive-complexity`) | `eslint --format json` | Mantido (v4.0.3, 2026-04-16; agora no monorepo SonarJS — o repo standalone foi arquivado, mas o pacote está vivo). **[caveat]** README das rules deu 404; presença de S3776 em v4 é alta-confiança mas confirmar no install. |
+| Dead code / unused exports / unused deps | **knip** (vence ts-prune **arquivado** + depcheck **arquivado**) | `knip --reporter json` | Muito ativo (v6.16.1, 2026-06-06) |
+| Ciclos | **check-cycles.mjs** (já temos) + **dpdm** opcional | `dpdm --circular --output deps.json` | dpdm ativo (v4.2.0, 2026-05-09); madge estagnado |
+| Vulnerabilidades | **osv-scanner** (Google/OSV) | `osv-scanner --format json` | Muito ativo (push 2026-06-08) |
+| Política de lockfile (gate, não métrica) | **lockfile-lint** | `lockfile-lint --validate-https --validate-integrity` | Mantido (v5.0.0, 2026-01-25) |
+
+> **Realidade do ratchet:** não existe tool único 2026 que emita *todas* as métricas como um JSON limpo. O padrão robusto é **N tools que emitem JSON + um reducer Node** que monta `metrics-summary.json` + o comparador que falha só em regressão (exatamente o que o `any-budget` já faz para uma métrica).
+
+### 4.3 Anti-alucinação (2026)
+
+- **LSP-in-the-loop / `agent-lsp` (MCP)** — servidor MCP que dá ao agente fatos verificáveis do language server (definições, referências, tipos, diagnostics, `blast_radius`) e `preview_edit` antes de escrever. Funciona com Claude Code. **Fit alto:** vira "símbolo inventado" de catch-de-review para *impossibilidade-no-edit*. (v0.13.0, 2026-06-04 — pequeno mas ativo.)
+- **Slopsquatting / pacotes alucinados** — **CSA Research Note (2026-04-19):** **19,7%** de 2,23M amostras de código IA continham nomes de pacote alucinados; 205k nomes fabricados únicos; **43%** reaparecem em re-runs (registráveis por atacantes). Defesas: **allowlist** de deps para agentes, **registry existence check** antes de instalar, **age-cooldown** (24–72h), lockfile-exact, scripts de install desabilitados. **Fit alto:** novo `check-deps.mjs`.
+- **Semcheck** (v1.2.1, fev/2026) — CLI que usa LLM para verificar que a implementação bate com o spec/doc, via `semcheck.yaml` ligando doc↔código; roda em pre-commit e Actions com `fail-on-issues`. Feito para pegar **"docs que descrevem features não implementadas"**. **Fit muito alto** para nossos incidentes recorrentes de docs alucinadas — porém é fuzzy (LLM); pareie com checks determinísticos.
+- **OpenAPI drift determinístico** — check que toda `path` do `openapi.yaml` resolve para um `route.ts` real (e vice-versa). Rápido, sem LLM, pega "endpoint inventado". **Fit alto** para `docs/reference/openapi.yaml`.
+- **Skill `verify` / `verification-before-completion`** (já no nosso ambiente) — "evidence before assertions": o veredito PASS/FAIL repousa **só** no que o app rodando demonstrou; rejeita "rodei os testes" como prova. **Fit altíssimo:** é a formalização da nossa Hard Rule #18 — exigir o *output literal* do comando colado no PR ("tool receipt").
+- **Adversarial review (críticos de sessão fresca)** — agentes Skeptic/Architect/Minimalist leem o diff *contra o spec* ("o autor está comprometido — vai racionalizar"); símbolos/APIs inventados viram violação de spec. Mapeia no nosso `/review-reviews`.
+- **SlopCodeBench (arXiv 2603.24755, ~mai/2026)** — sem mitigação, erosão estrutural aumentou em **77%** das trajetórias; o código de agente acumula verbosidade ~7× e erosão ~5× mais rápido que repos humanos. **Mitigações só-de-prompt ("anti-slop", "plan-first") melhoram o início mas NÃO param a degradação iterativa.** → **justificativa empírica** de que precisamos de gates determinísticos, não instrução.
+- **GPT-5.5 System Card (2026-04-23)** — figuras oficiais são modestas (23% mais provável de acerto factual; 3% menos erros num set propenso). O headline de **"queda de 60% em alucinação / 88,7% SWE-bench" é imprensa secundária [não-verificado]**, não a seção de factualidade do system card. Upgrade de modelo ajuda na margem, não substitui gate.
+
+### 4.4 Babysit loops (2026)
+
+- **Claude Code "auto-fix in the cloud"** (Anthropic, lançado 2026-03-27): "observa seus PRs na nuvem, resolvendo falhas de CI e comentários de review automaticamente; empurra fixes quando claro, pergunta quando ambíguo." Não auto-mergeia.
+- **Devin Autofix** (2026-02-10): auto-conserta comentários de review + lint/CI; endereça comentários de bots, mas deixa julgamento humano nas conversas humanas.
+- **CodeRabbit Autofix** (early access abr/2026): coleta o bloco **"Prompt for AI Agents"** de cada comentário, aplica fix, roda build-verification; **nada mergeia automaticamente**.
+- **Greptile `greploop` + skill `check-pr`** (MIT) — "dispara review → conserta comentários → re-review até 5/5 de confiança e zero comentários". **Template quase-exato** para a nossa `/babysit`.
+- **Claude `claude ultrareview <PR#> --json`** (subcomando não-interativo, research preview): bloqueia até terminar, `exit 0/1`, payload de bugs verificados parseável. **Não auto-inicia** e custa $5–20/run → usar atrás de label, não em todo push. (O `/code-review ultra` local com `--fix` é o loop interno de custo-zero.)
+- **Resolver threads de review:** não há comando `gh` nativo (cli/cli#12419). Padrão de 2 passos GraphQL: `reviewThreads(first:50){nodes{id isResolved...}}` → `mutation { resolveReviewThread(input:{threadId}) }`, respondendo antes com o SHA do commit via REST.
+- **Guarda-corpos (críticos):**
+  - **Snyk Agent Fix field test (2026): ~5,3% de regressão** ("1 em 19 fixes auto-mergeados introduz problema novo") → **forte argumento contra auto-merge**.
+  - **Token burn:** loops ingênuos realimentam a conversa crescente → prompt incha → alucina do próprio histórico. Uber capou gasto em **$1.500/mês/dev/tool** (abr/2026). Mitigação: **max-iterations**, time limit, idle-exit.
+  - **Test-masking:** o babysit **NÃO** pode enfraquecer/remover asserts para ficar verde (= nossa Rule #18 + memória "trust but verify"). Revisão humana fica nos limites arquiteturais (interface/schema/cross-service).
+  - **Audit trail:** deixar rastro humano-legível (qual fix endereçou o quê, qual gate satisfez, quais conversas resolveu) — nunca um verde silencioso. Reforça o guard de prompt-injection sobre os *corpos de comentário* que o agente ingere (21% dos reviews do ICLR 2026 eram IA; injeção embutida em código é vetor real).
+
+---
+
+## 5. Recomendações (ranqueadas) → ver o PLANO
+
+> Build-vs-buy: **construir in-repo** os gates determinísticos (zero SaaS, dados não saem da box, reusa o harness `check-*.mjs`). **Avaliar Qlty CLI** depois, se quisermos consolidar N scripts num tool. **Não** depender de CodeRabbit/Greptile/Diamond como *o* gate de "não-piorar-métrica" — são opiniões de LLM, não contadores determinísticos.
+
+**Fase 0 — Reativar & reconciliar (quick wins, sem tooling novo):**
+1. Reativar pre-commit barato do Husky (lint-staged + docs-sync + any-budget).
+2. Reconciliar o gate de cobertura: subir o CI de 40 → baseline real (com headroom) e alinhar os 4 lugares que divergem.
+3. Escalonar `npm audit` (critical=bloqueia / high=avisa).
+4. Plugar os 3 scripts órfãos (`cli-i18n`, `openapi-coverage`, `openapi-security-tiers`) no CI.
+
+**Fase 1 — Motor de catraca (o coração):**
+5. `quality-baseline.json` commitado + `collect-metrics.mjs` (coletor) + `check-quality-ratchet.mjs` (comparador, clone do `any-budget`) + job de CI + artefato + comentário no PR (clone do `coverage-pr-comment`).
+
+**Fase 2 — Gates determinísticos anti-alucinação:**
+6. `check-provider-consistency.mjs` (o ímã nº1), `check-fetch-targets.mjs`, `check-openapi-routes.mjs`, allow-list de estratégias/translators/executors, lint Rule #11/#12, `check-deps.mjs` (slopsquatting).
+
+**Fase 3 — Catraca de duplicação + tamanho (mata-slop):**
+7. jscpd + ESLint `max-lines`/`max-lines-per-function`/`complexity` + `sonarjs/cognitive-complexity`, congelando os 64 arquivos grandes (catraca só-pode-encolher).
+
+**Fase 4 — Catraca de cobertura + anti test-masking:**
+8. `check-coverage-ratchet.mjs` (cobertura não cai vs baseline) + pisos por módulo crítico + `check-test-masking.mjs` (delta de contagem de asserts em testes alterados).
+
+**Fase 5 — Skill `/babysit` + evidência + LSP:**
+9. Skill `/babysit` (gh pr checks + reviewThreads + worktree de fix + resolveReviewThread + loop-até-verde, com guarda-corpos), "evidence-before-assertions" obrigatório no corpo do PR, e (opcional) `agent-lsp` MCP.
+
+---
+
+## 6. Riscos & ressalvas (honestidade de engenharia)
+
+- **Flag-day risk:** ligar qualquer gate num projeto que nunca o teve deixa tudo vermelho. **Toda** catraca aqui é *só-regressão* (baseline congelado), nunca um piso absoluto que exige limpeza imediata — exatamente o ponto do vídeo.
+- **Custo de IA:** o babysit pode queimar tokens. Guarda-corpos (max-iterations, sem auto-merge, sem editar `.github/workflows/`) são não-negociáveis.
+- **Ressalvas de pesquisa não-verificadas:** betterer baixa-velocidade; Sonar "AI Code Assurance" bloqueio-de-PR não confirmado; "GPT-5.5 −60% alucinação" é imprensa, não system card; schema JSON do jscpd v5 e S3776 do sonarjs v4 a confirmar no install; `qlty metrics` sem JSON. Nenhuma decisão do plano depende criticamente de um item não-verificado.
+- **Trust-but-verify:** estes números internos (CI=40, husky off, sonar exclusions, 12.760 LOC, any-budget como catraca) foram **conferidos manualmente** contra os arquivos, não só relatados pelos subagentes.
+
+---
+
+## 7. Fontes (consolidadas)
+
+**Catraca / ratchet:** betterer `github.com/phenomnomnominal/betterer` (último master ago/2025); eslint-formatter-ratchet `github.com/Jmsa/eslint-formatter-ratchet` (commit 2026-03-17); SonarQube Clean as You Code `docs.sonarsource.com/.../clean-as-you-code/about-new-code/`; Sonar AI Code Assurance `sonarsource.com/solutions/ai/ai-code-assurance/` + community thread 2026.1.0; Qlty `github.com/qltysh/qlty` (v0.630.0, 2026-05-08), `docs.qlty.sh`; Code Climate→Qlty `codeclimate.com/legacy/...` (2024-11-11).
+
+**Métricas:** jscpd `github.com/kucherenko/jscpd` (v5.0.4, 2026-06-08); ESLint v10 `eslint.org/blog/2026/02/eslint-v10.0.0-released/` (2026-02-06); eslint-plugin-sonarjs `npm` (v4.0.3, 2026-04-16) + `github.com/SonarSource/SonarJS`; knip `knip.dev` (v6.16.1, 2026-06-06); dpdm `github.com/acrazing/dpdm` (v4.2.0, 2026-05-09); osv-scanner `google.github.io/osv-scanner` (push 2026-06-08); lockfile-lint `github.com/lirantal/lockfile-lint` (v5.0.0, 2026-01-25); GitClear `gitclear.com/ai_assistant_code_quality_2025_research`.
+
+**Anti-alucinação:** agent-lsp `github.com/blackwell-systems/agent-lsp` (v0.13.0, 2026-06-04); CSA Slopsquatting `labs.cloudsecurityalliance.org/research/...slopsquatting...20260419...` (2026-04-19); Nesbitt package defenses `nesbitt.io/2026/04/09/...` (2026-04-09); Semcheck `github.com/rejot-dev/semcheck` (v1.2.1, fev/2026); verify skill `github.com/Piebald-AI/claude-code-system-prompts/.../skill-verify-skill.md`; Claude best practices `code.claude.com/docs/en/best-practices`; SlopCodeBench `arxiv.org/pdf/2603.24755`; GPT-5.5 system card `deploymentsafety.openai.com/gpt-5-5` (2026-04-23); adversarial review `asdlc.io/patterns/adversarial-code-review/`; OpenAPI drift `speakeasy.com/blog/openapi-spec-drift-detection`.
+
+**Babysit:** Claude auto-fix cloud `producthunt.com/products/claude-code-auto-fix-in-the-cloud` (2026-03-27); Devin Autofix `cognition.ai/blog/closing-the-agent-loop-...` (2026-02-10); CodeRabbit Autofix `coderabbit.ai/blog/fix-all-issues-with-ai-agents` (2026-02-19); Greptile skills `github.com/greptileai/skills`; Claude GitHub Actions/Code Review/ultrareview `code.claude.com/docs/en/{github-actions,code-review,ultrareview}`; Nx self-healing `nx.dev/blog/autonomous-ai-workflows-with-nx` (2026-02-03); Snyk Agent Fix 5,3% `safeguard.sh/resources/blog/snyk-agent-fix-autofix-field-test-2026`; resolveReviewThread `nakamasato.medium.com/...` + `github.com/cli/cli/issues/12419`; ICLR 2026 AI review `blog.pebblous.ai/report/iclr-2026-ai-peer-review-crisis`.
+
+---
+
+*Relatório gerado a partir de auditoria paralela do código + transcrição do vídeo + pesquisa web 2026. Próximo passo: aprovar o [`PLANO-QUALITY-GATES.md`](./PLANO-QUALITY-GATES.md) e escolher por onde começar (recomendação: Fase 0 → Fase 1).*

_tasks/features-v3.8.6/refactorpages/_orchestration/15-generator-output.md

@@ -1,133 +0,0 @@
-# Task 15 — Skill Generator Output
-
-Timestamp: 2026-05-28T00:00:00.000Z
-
----
-
-## Dry-run summary
-
-- Generated: 42 SKILL.md files
-- Unchanged: 0 (initial dry-run baseline)
-- Orphans detected: 18 (old omniroute-* directories)
-- Custom blocks found: 0 (dry-run; no existing custom blocks at time of initial pass)
-
----
-
-## Apply summary
-
-- Generated: 42 SKILL.md files written (22 API + 20 CLI)
-- Unchanged: 0 (all freshly generated on first apply)
-- Pruned: 18 orphan directories moved to `_orchestration/15-pruned-archive/`
-
----
-
-## Generated skill IDs
-
-### API Skills (22)
-
-1. `omni-auth`
-2. `omni-providers`
-3. `omni-models`
-4. `omni-combos-routing`
-5. `omni-api-keys`
-6. `omni-usage-logs`
-7. `omni-budget`
-8. `omni-settings`
-9. `omni-proxies`
-10. `omni-cache`
-11. `omni-compression`
-12. `omni-context-rtk`
-13. `omni-resilience`
-14. `omni-cli-tools`
-15. `omni-tunnels`
-16. `omni-sync-cloud`
-17. `omni-db-backups`
-18. `omni-webhooks`
-19. `omni-mcp`
-20. `omni-agents-a2a`
-21. `omni-version-manager`
-22. `omni-inference`
-
-### CLI Skills (20)
-
-1. `cli-serve`
-2. `cli-health`
-3. `cli-providers`
-4. `cli-keys`
-5. `cli-models`
-6. `cli-chat`
-7. `cli-routing`
-8. `cli-resilience`
-9. `cli-compression`
-10. `cli-contexts`
-11. `cli-cost-usage`
-12. `cli-mcp`
-13. `cli-a2a`
-14. `cli-tunnel`
-15. `cli-backup-sync`
-16. `cli-policy-audit`
-17. `cli-batches`
-18. `cli-eval`
-19. `cli-plugins-skills`
-20. `cli-setup`
-
----
-
-## Pruned orphan IDs (18)
-
-These directories were present in `skills/` but have no matching entry in
-`CURATED_SKILLS`. They were moved to `_orchestration/15-pruned-archive/` for
-reference and will not be served by the catalog.
-
-1. `omniroute`
-2. `omniroute-a2a`
-3. `omniroute-chat`
-4. `omniroute-cli`
-5. `omniroute-cli-admin`
-6. `omniroute-cli-cloud`
-7. `omniroute-cli-eval`
-8. `omniroute-cli-providers`
-9. `omniroute-compression`
-10. `omniroute-embeddings`
-11. `omniroute-image`
-12. `omniroute-mcp`
-13. `omniroute-monitoring`
-14. `omniroute-routing`
-15. `omniroute-stt`
-16. `omniroute-tts`
-17. `omniroute-web-fetch`
-18. `omniroute-web-search`
-
-Archive location: `_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/`
-
----
-
-## Idempotency confirmation
-
-A second apply run with the same 42-entry `CURATED_SKILLS` produced:
-
-- Generated: 0 (all files already up-to-date)
-- Unchanged: 42
-- Pruned: 0
-
-The generator correctly detects that all output files are current and skips
-regeneration, confirming idempotent behaviour.
-
----
-
-## Custom blocks preserved (10)
-
-The following skills contained `<!-- skill:custom-start --> ... <!-- skill:custom-end -->`
-blocks with manually authored content. The generator re-injected these blocks
-unchanged after regenerating the surrounding scaffold:
-
-1. `omni-auth`
-2. `omni-resilience`
-3. `omni-mcp`
-4. `omni-combos-routing`
-5. `omni-compression`
-6. `omni-agents-a2a`
-7. `omni-inference`
-8. `cli-serve`
-9. `cli-providers`
-10. `cli-eval`

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-a2a/SKILL.md

@@ -1,71 +0,0 @@
----
-name: omniroute-a2a
-description: OmniRoute exposes an A2A (Agent-to-Agent) JSON-RPC 2.0 server with 5 skills (smart-routing, quota-management, provider-discovery, cost-analysis, health-report). Use when the user wants OmniRoute to act as an agent peer in an A2A network or multi-agent pipeline.
----
-
-# OmniRoute — A2A Protocol
-
-Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
-
-OmniRoute publishes an Agent Card at `/.well-known/agent.json` and accepts
-JSON-RPC 2.0 calls at `/a2a`.
-
-## Discovery
-
-```bash
-curl $OMNIROUTE_URL/.well-known/agent.json
-```
-
-Returns Agent Card with skills, endpoints, auth scheme.
-
-## Available skills
-
-| Skill                | Purpose                                                                             |
-| -------------------- | ----------------------------------------------------------------------------------- |
-| `smart-routing`      | Given a prompt, recommends best provider/model combo                                |
-| `quota-management`   | Reports quota balance for given provider/account                                    |
-| `provider-discovery` | Lists providers matching capability filters (vision, JSON mode, tools, max-context) |
-| `cost-analysis`      | Estimates cost for a given request shape                                            |
-| `health-report`      | Returns system health (circuit states, latencies, errors)                           |
-
-## Call example (JSON-RPC 2.0)
-
-```bash
-curl -X POST $OMNIROUTE_URL/a2a \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "method": "tasks/send",
-    "params": {
-      "skillId": "smart-routing",
-      "input": { "prompt_length": 4000, "tools": true, "vision": false }
-    },
-    "id": 1
-  }'
-```
-
-## Response shape
-
-```json
-{
-  "jsonrpc": "2.0",
-  "result": {
-    "taskId": "...",
-    "status": "completed",
-    "output": { "recommended_combo": "...", "reasoning": "..." }
-  },
-  "id": 1
-}
-```
-
-## Errors
-
-- `-32600` → invalid request (bad JSON-RPC envelope)
-- `-32601` → method not found (check `method` field)
-- `-32602` → invalid params (check `skillId` against Agent Card)
-- `401` → missing/invalid `OMNIROUTE_KEY`
-
-## Reference
-
-Full docs: https://github.com/diegosouzapw/OmniRoute/blob/main/docs/frameworks/A2A-SERVER.md

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-chat/SKILL.md

@@ -1,68 +0,0 @@
----
-name: omniroute-chat
-description: Chat / code generation via OmniRoute using OpenAI /v1/chat/completions or Anthropic /v1/messages format with SSE streaming, auto-fallback combos, RTK token saver, and 207+ providers. Use when the user wants to ask an LLM, generate code, summarize text, or run prompts through OmniRoute.
----
-
-# OmniRoute — Chat
-
-Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
-
-## Endpoints
-
-- `POST $OMNIROUTE_URL/v1/chat/completions` — OpenAI format
-- `POST $OMNIROUTE_URL/v1/messages` — Anthropic Messages format
-- `POST $OMNIROUTE_URL/v1/responses` — OpenAI Responses API
-
-## Discover
-
-```bash
-curl $OMNIROUTE_URL/v1/models | jq '.data[].id'
-```
-
-Combos (e.g. `auto`, `cost-optimized`, `subscription`) auto-fallback through multiple providers.
-
-## OpenAI format example
-
-```bash
-curl -X POST $OMNIROUTE_URL/v1/chat/completions \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "claude-opus-4-7",
-    "messages": [{"role": "user", "content": "Refactor this function"}],
-    "stream": true
-  }'
-```
-
-## Anthropic format example
-
-```bash
-curl -X POST $OMNIROUTE_URL/v1/messages \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "anthropic-version: 2023-06-01" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "claude-opus-4-7",
-    "max_tokens": 4096,
-    "messages": [{"role": "user", "content": "Hi"}]
-  }'
-```
-
-## Tool use
-
-Supports OpenAI `tools` array and Anthropic `tools` block. Tool results
-auto-compressed via RTK (47 filters: git-diff, grep, test-jest, terraform-plan,
-docker-logs, etc.) — 20-40% token savings. Disable per-request with
-`X-Omniroute-Rtk: off` header.
-
-## Reasoning / thinking
-
-Anthropic extended thinking and OpenAI Responses reasoning blocks are forwarded
-verbatim. Cached automatically via reasoning cache.
-
-## Errors
-
-- `401` → invalid API key
-- `400 invalid_model` → model not in registry; check `/v1/models`
-- `503 circuit_open` → provider circuit breaker tripped; retry later or use combo
-- `429 rate_limited` → honor `Retry-After`; consider using a combo for auto-fallback

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-admin/SKILL.md

@@ -1,145 +0,0 @@
----
-name: omniroute-cli-admin
-description: Manage the OmniRoute server lifecycle via CLI — start/stop/restart, non-interactive setup, diagnostics (omniroute doctor), backup/restore, autostart, and tunnel management. Use when the user wants to operate the OmniRoute server, automate provisioning, or troubleshoot the runtime.
----
-
-# OmniRoute — CLI Admin
-
-Requires the `omniroute` CLI. See [CLI entry-point skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md) for install + global flags.
-
-## Server lifecycle
-
-```bash
-omniroute                              # Start server (default port 20128)
-omniroute serve                        # Explicit alias
-omniroute --port 3000                  # Override port
-omniroute --no-open                    # Don't auto-open browser
-omniroute --mcp                        # Start as MCP server (stdio transport)
-
-omniroute stop                         # Stop the running server
-omniroute restart                      # Restart the server
-
-omniroute dashboard                    # Open dashboard in browser
-omniroute open                         # Alias for dashboard
-omniroute status                       # Runtime status (uptime, requests, providers)
-```
-
-## Setup & provisioning
-
-### Interactive wizard
-
-```bash
-omniroute setup                        # Step-by-step interactive setup
-```
-
-### Non-interactive (CI / Docker)
-
-```bash
-omniroute setup --non-interactive \
-  --password 'admin-password' \
-  --add-provider \
-  --provider openai \
-  --api-key 'sk-...' \
-  --test-provider
-```
-
-Environment variables for non-interactive setup:
-
-| Variable                      | Purpose                                      |
-| ----------------------------- | -------------------------------------------- |
-| `OMNIROUTE_SETUP_PASSWORD`    | Admin password (≥8 chars)                    |
-| `OMNIROUTE_PROVIDER`          | Provider id (e.g. `openai`, `anthropic`)     |
-| `OMNIROUTE_PROVIDER_NAME`     | Display name for the connection              |
-| `OMNIROUTE_PROVIDER_BASE_URL` | Optional OpenAI-compatible base URL override |
-| `OMNIROUTE_API_KEY`           | Provider API key                             |
-| `OMNIROUTE_DEFAULT_MODEL`     | Optional default model                       |
-| `DATA_DIR`                    | Override OmniRoute data directory            |
-
-## Diagnostics
-
-```bash
-omniroute doctor                       # Full health check
-omniroute doctor --json                # Machine-readable JSON
-omniroute doctor --no-liveness         # Skip HTTP health probe
-omniroute doctor --host 0.0.0.0        # Override liveness host
-omniroute doctor --liveness-url <url>  # Full URL override
-```
-
-Checks performed: Config, Database, Storage/encryption, Port, Node runtime, Native binary (better-sqlite3), Memory, Server liveness.
-
-Exit code is non-zero if any check fails — useful in CI:
-
-```bash
-omniroute doctor --json | jq '.checks[] | select(.status=="fail")'
-```
-
-## Backup & restore
-
-```bash
-omniroute backup                       # Snapshot config + SQLite DB to ~/.omniroute/backups/
-omniroute restore                      # Restore from a previous snapshot (interactive picker)
-```
-
-## Autostart (system tray / startup)
-
-```bash
-omniroute autostart enable             # Register OmniRoute as a system startup item
-omniroute autostart disable            # Remove startup registration
-omniroute autostart status             # Show current autostart state
-```
-
-On Linux: creates a **systemd user service** (`~/.config/systemd/user/omniroute.service`) and enables **linger** so the service can start after reboot without a graphical login; on desktop sessions it also adds an XDG autostart entry with `--tray`. On macOS: LaunchAgent plist. On Windows: registry startup entry.
-
-## Tunnels (public URL)
-
-Expose a local OmniRoute instance via a secure tunnel:
-
-```bash
-omniroute tunnel list                  # List active tunnels
-omniroute tunnel create cloudflare     # Start a Cloudflare Tunnel (free)
-omniroute tunnel create tailscale      # Start a Tailscale funnel
-omniroute tunnel create ngrok          # Start an ngrok tunnel
-omniroute tunnel stop <id>             # Stop a running tunnel
-```
-
-The tunnel URL is printed and can be used as `OMNIROUTE_BASE_URL` from remote machines.
-
-## Config & environment
-
-```bash
-omniroute config show                  # Display current effective configuration
-omniroute env show                     # List all OmniRoute environment variables
-omniroute env get <KEY>                # Get a single env var value
-omniroute env set <KEY> <value>        # Set an env var (temporary — until restart)
-```
-
-## Recovery
-
-```bash
-omniroute reset-password               # Reset the admin password interactively
-omniroute reset-encrypted-columns      # Dry-run: show encrypted credential columns
-omniroute reset-encrypted-columns --force  # Null out encrypted credentials in SQLite
-```
-
-Use `reset-encrypted-columns --force` only if `STORAGE_ENCRYPTION_KEY` was lost and you need to re-enter all provider API keys.
-
-## Logs
-
-```bash
-omniroute logs                         # Stream live request logs
-omniroute logs --json                  # JSON log entries
-omniroute logs --search <term>         # Filter by term
-omniroute logs --follow                # Tail mode (keep streaming)
-```
-
-## Update
-
-```bash
-omniroute update                       # Check for a newer version and prompt to update
-```
-
-## Errors
-
-- `doctor` shows `STORAGE_ENCRYPTION_KEY missing` → set the key in `.env` or run `reset-encrypted-columns --force` to wipe and re-enter credentials
-- `doctor` reports native binary fail → `npm rebuild better-sqlite3` in the OmniRoute app directory
-- `tunnel create cloudflare` hangs → ensure `cloudflared` is installed: `brew install cloudflare/cloudflare/cloudflared`

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-cloud/SKILL.md

@@ -1,120 +0,0 @@
----
-name: omniroute-cli-cloud
-description: Control OmniRoute cloud agents (OpenAI Codex, Devin, Jules) from the CLI — create tasks, track status, approve plans, send messages, and manage sources. Use when the user wants to automate cloud coding agent workflows via the terminal.
----
-
-# OmniRoute — CLI Cloud Agents
-
-Requires the `omniroute` CLI. See [CLI entry-point skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md) for install + global flags.
-
-## Supported agents
-
-| Agent          | ID      | Auth required  |
-| -------------- | ------- | -------------- |
-| OpenAI Codex   | `codex` | OpenAI API key |
-| Devin          | `devin` | Devin API key  |
-| Jules (Google) | `jules` | Google OAuth   |
-
-## Authenticate an agent
-
-```bash
-omniroute cloud codex auth             # Set / refresh Codex API key
-omniroute cloud devin auth             # Set / refresh Devin API key
-omniroute cloud jules auth             # OAuth login for Jules (opens browser)
-```
-
-## List all agents
-
-```bash
-omniroute cloud agents                 # Show all configured cloud agents + status
-omniroute cloud agents --json
-```
-
-## Create a task
-
-```bash
-omniroute cloud codex task create \
-  --title "Add OAuth to the auth module" \
-  --prompt "Implement Google OAuth 2.0 login in src/auth/oauth.ts"
-
-omniroute cloud codex task create \
-  --title "Fix test failures" \
-  --prompt-file ./task-description.md   # Read prompt from a file
-```
-
-Same syntax for `devin` and `jules`:
-
-```bash
-omniroute cloud devin task create --title "..." --prompt "..."
-omniroute cloud jules task create --title "..." --prompt "..."
-```
-
-## List tasks
-
-```bash
-omniroute cloud codex task list        # All Codex tasks (table)
-omniroute cloud codex task list --json # JSON output
-```
-
-## Get task details
-
-```bash
-omniroute cloud codex task get <taskId>       # Full task record
-omniroute cloud codex task status <taskId>    # Status + progress only
-```
-
-Task status values: `running`, `completed`, `failed`, `cancelled`.
-
-## Approve a plan
-
-Devin and Jules may pause for plan approval before writing code:
-
-```bash
-omniroute cloud devin task approve <taskId>   # Approve the proposed plan
-omniroute cloud jules task approve <taskId>
-```
-
-## Send a message to a running task
-
-```bash
-omniroute cloud codex task message <taskId> "Focus on the backend only, skip the UI"
-```
-
-## List task sources (files touched)
-
-```bash
-omniroute cloud codex task sources <taskId>   # Files changed / created by the task
-```
-
-## Cancel a task
-
-```bash
-omniroute cloud codex task cancel <taskId>
-omniroute cloud devin task cancel <taskId>
-```
-
-## Typical workflow
-
-```bash
-# 1. Authenticate
-omniroute cloud codex auth
-
-# 2. Create a task
-TASK_ID=$(omniroute cloud codex task create \
-  --title "Refactor auth module" \
-  --prompt "Extract JWT logic to src/auth/jwt.ts" \
-  --output json | jq -r '.id')
-
-# 3. Poll status
-omniroute cloud codex task status $TASK_ID
-
-# 4. View touched files when complete
-omniroute cloud codex task sources $TASK_ID
-```
-
-## Errors
-
-- `auth required` → run `omniroute cloud <agent> auth` before any task commands
-- `task create` fails with 402 → agent billing limit reached; check your Codex/Devin/Jules account
-- `task approve` fails with 404 → task does not have a pending plan; check status first
-- `jules auth` browser flow fails → ensure Google account has Jules access; try `omniroute cloud jules auth` again

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-eval/SKILL.md

@@ -1,113 +0,0 @@
----
-name: omniroute-cli-eval
-description: Run and manage OmniRoute eval suites from the CLI — create suites, run benchmarks, watch live results, view scorecards, and compare model performance. Use when the user wants to benchmark models, validate quality regressions, or automate LLM evals in CI.
----
-
-# OmniRoute — CLI Evals
-
-Requires the `omniroute` CLI. See [CLI entry-point skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md) for install + global flags.
-
-## What are evals?
-
-Evals are automated test suites that score LLM outputs against expected answers or rubrics. OmniRoute stores suites and run results in its local database.
-
-## Eval suites
-
-```bash
-omniroute eval suites list                       # List all eval suites
-omniroute eval suites list --json                # JSON output
-
-omniroute eval suites get <suiteId>              # Full suite definition
-```
-
-### Create a suite
-
-```bash
-omniroute eval suites create \
-  --name "code-quality" \
-  --rubric "exact-match" \
-  --samples-file ./samples.jsonl                 # JSONL: {input, expected_output}
-```
-
-Rubric options: `exact-match`, `contains`, `llm-judge`, `regex`.
-
-`--samples-file` format (one JSON object per line):
-
-```jsonl
-{"input": "What is 2+2?", "expected_output": "4"}
-{"input": "Translate 'hello' to Spanish", "expected_output": "hola"}
-```
-
-## Run an eval
-
-```bash
-omniroute eval suites run <suiteId> \
-  --model claude-sonnet-4-6                      # Run suite against a specific model
-
-omniroute eval suites run <suiteId> \
-  --model gpt-4o \
-  --watch                                        # Live TUI progress (EvalWatch)
-```
-
-The run is asynchronous. Use `--watch` for a live terminal dashboard or poll manually:
-
-```bash
-RUN_ID=$(omniroute eval suites run <suiteId> --model claude-sonnet-4-6 --output json | jq -r '.id')
-omniroute eval get $RUN_ID
-```
-
-## Manage runs
-
-```bash
-omniroute eval list                              # List all eval runs
-omniroute eval list --json
-
-omniroute eval get <runId>                       # Run details (status, model, score)
-omniroute eval results <runId>                   # Per-sample results
-omniroute eval scorecard <runId>                 # Full scorecard with pass/fail per sample
-omniroute eval cancel <runId>                    # Cancel a running eval
-```
-
-## Scorecard output
-
-```bash
-omniroute eval scorecard <runId> --output json
-```
-
-Response fields per sample:
-
-```json
-{
-  "id": "sample-1",
-  "score": 0.95,
-  "passed": true,
-  "input": "What is 2+2?",
-  "output": "4",
-  "expected": "4"
-}
-```
-
-## Comparing models
-
-Run the same suite against multiple models and compare:
-
-```bash
-for MODEL in claude-sonnet-4-6 gpt-4o gemini-2.0-flash; do
-  omniroute eval suites run $SUITE_ID --model $MODEL --output json | jq '{model: .model, score: .score}'
-done
-```
-
-## CI integration
-
-```bash
-# Run and fail CI if score drops below threshold
-SCORE=$(omniroute eval suites run $SUITE_ID --model claude-sonnet-4-6 --output json | jq -r '.score')
-python3 -c "import sys; score=float('$SCORE'); sys.exit(0 if score >= 0.90 else 1)"
-```
-
-## Errors
-
-- `suites create` fails with `invalid rubric` → use one of: `exact-match`, `contains`, `llm-judge`, `regex`
-- `suites run` returns `model not found` → verify model ID with `omniroute models --search <name>`
-- `eval get` shows `status: failed` → check `omniroute logs --search eval` for error details
-- `scorecard` returns empty results → the run may still be `running`; poll `omniroute eval get <runId>` until `status` is `completed`

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-providers/SKILL.md

@@ -1,145 +0,0 @@
----
-name: omniroute-cli-providers
-description: Manage OmniRoute provider connections, API keys, and routing combos via CLI — add/list/test/remove providers, rotate keys, run OAuth flows, list models, and create/switch combos. Use when the user wants to configure providers, manage credentials, or set up routing from the terminal.
----
-
-# OmniRoute — CLI Providers & Keys
-
-Requires the `omniroute` CLI. See [CLI entry-point skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md) for install + global flags.
-
-## Provider catalog (available providers)
-
-```bash
-omniroute providers available                        # Full OmniRoute provider catalog
-omniroute providers available --search openai        # Filter by id, name, alias
-omniroute providers available --category api-key     # Filter by category
-omniroute providers available --json                 # Machine-readable JSON
-```
-
-Categories: `api-key`, `oauth`, `free`, `local`, `combo`.
-
-## Configured provider connections
-
-```bash
-omniroute providers list                             # Connections in your DB
-omniroute providers list --json
-```
-
-## Testing connections
-
-```bash
-omniroute providers test <id|name>                   # Test one configured connection
-omniroute providers test-all                         # Test every active connection (TUI progress)
-omniroute providers validate                         # Local-only structural validation (no HTTP)
-```
-
-`test-all` opens an interactive TUI that shows live pass/fail per connection. Use `--json` to get a machine-readable result:
-
-```bash
-omniroute providers test-all --json
-```
-
-## API key management (OmniRoute keys)
-
-These manage the OmniRoute API keys issued under **API Manager** — not provider credentials.
-
-```bash
-omniroute keys list                                  # List all OmniRoute API keys
-omniroute keys add <provider> [apiKey]               # Add an API key for a provider
-omniroute keys remove <provider>                     # Remove an API key
-omniroute keys regenerate <id>                       # Regenerate (rotate) a key
-omniroute keys revoke <id>                           # Revoke a key (disables it)
-omniroute keys reveal <id>                           # Show the full key value
-omniroute keys usage <id>                            # Show usage stats for a key
-
-omniroute keys rotate <id>                           # Rotate + revoke old key atomically
-omniroute keys expiration list                       # List key expiration times
-```
-
-### Key policies
-
-```bash
-omniroute keys policy show <id>                      # Show rate-limit / permission policy
-omniroute keys policy set <id> \
-  --rate-limit 100 \
-  --rate-window minute \
-  --permissions chat,models                          # Set policy on a key
-```
-
-## Models
-
-```bash
-omniroute models                                     # List all models (all providers)
-omniroute models openai                              # Filter by provider
-omniroute models --search gpt                        # Search by name
-omniroute models --json                              # JSON output
-```
-
-## OAuth providers
-
-```bash
-omniroute oauth list                                 # List OAuth-configured providers
-omniroute oauth login <provider>                     # Start browser-based OAuth flow
-omniroute oauth logout <provider>                    # Revoke OAuth token
-omniroute oauth status <provider>                    # Show token state + expiry
-omniroute oauth refresh <provider>                   # Force token refresh
-```
-
-For OAuth providers (Gemini, Windsurf, Antigravity, etc.) the `login` command opens the OmniRoute dashboard OAuth flow in your browser.
-
-## Provider nodes (multi-account routing)
-
-Provider nodes let you attach multiple API keys / accounts to one logical provider for round-robin or failover.
-
-```bash
-omniroute nodes list <provider>                      # List nodes for a provider
-omniroute nodes add <provider> --api-key <key>       # Add a node
-omniroute nodes remove <provider> <nodeId>           # Remove a node
-omniroute nodes test <provider> <nodeId>             # Test one node
-```
-
-## Routing combos (CLI)
-
-Create and manage routing combos from the terminal:
-
-```bash
-omniroute combo list                                 # List all combos
-omniroute combo create <name> \
-  --strategy priority \
-  --targets anthropic/claude-opus-4-7,openai/gpt-4o  # Create combo
-omniroute combo switch <name>                        # Activate a combo as default
-omniroute combo delete <name>                        # Delete a combo
-omniroute combo suggest --task "code review"         # Ask OmniRoute to recommend a combo
-```
-
-For the full REST API for combos see [omniroute-routing skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-routing/SKILL.md).
-
-## Quota & usage
-
-```bash
-omniroute quota                                      # Provider quota usage + reset times
-omniroute usage                                      # Request + token usage summary
-omniroute cost                                       # Cost breakdown (by provider/model)
-```
-
-## Compression (CLI)
-
-```bash
-omniroute compression status                         # Current compression mode + savings stats
-omniroute compression set --mode rtk                 # Enable RTK compression
-omniroute compression set --mode stacked             # Enable stacked (RTK + Caveman)
-omniroute compression set --mode off                 # Disable compression
-omniroute compression preview --mode rtk --text "..."  # Preview savings for sample text
-```
-
-## Health
-
-```bash
-omniroute health                                     # Detailed health: circuit breakers, cache, memory
-```
-
-## Errors
-
-- `providers test <id>` fails with 401 → API key stored for that provider is wrong; use `keys remove` + `keys add` to reset it
-- `oauth login` opens but doesn't complete → the OAuth token endpoint may be firewalled; use API key auth instead
-- `combo create` fails with `strategy unknown` → use one of: `priority`, `weighted`, `round-robin`, `fill-first`, `least-used`, `cost-optimized`, `auto`, `random`, `strict-random`, `p2c`, `reset-aware`, `lkgp`, `context-optimized`, `context-relay`

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli/SKILL.md

@@ -1,104 +0,0 @@
----
-name: omniroute-cli
-description: Entry point for the OmniRoute CLI (omniroute binary) — install, global flags, output formats, environment variables, and index of CLI capability skills. Use when the user wants to control OmniRoute from the terminal, automate workflows, or integrate with CI/CD.
----
-
-# OmniRoute — CLI (Entry Point)
-
-The `omniroute` binary ships with the OmniRoute server. It is both the server launcher and a full management CLI with 250+ commands across 39 groups.
-
-## Install
-
-```bash
-npm install -g omniroute          # npm registry
-# or: use the binary bundled with the desktop app
-```
-
-Requires Node.js ≥20.20.2, ≥22.22.2, or ≥24.
-
-Verify:
-
-```bash
-omniroute --version   # prints installed version
-omniroute --help      # full command tree
-```
-
-## Connection
-
-Every CLI command that talks to the server reads two values:
-
-| Source   | Variable / Flag                      |
-| -------- | ------------------------------------ |
-| Base URL | `OMNIROUTE_BASE_URL` or `--base-url` |
-| API key  | `OMNIROUTE_API_KEY` or `--api-key`   |
-
-Default base URL: `http://localhost:20128`
-
-```bash
-export OMNIROUTE_BASE_URL="http://localhost:20128"
-export OMNIROUTE_API_KEY="sk-..."          # from Dashboard → API Manager
-```
-
-For a remote server:
-
-```bash
-export OMNIROUTE_BASE_URL="https://your-server.com"
-```
-
-## Global flags
-
-| Flag                | Description                                              |
-| ------------------- | -------------------------------------------------------- |
-| `--base-url <url>`  | Override server URL for this invocation                  |
-| `--api-key <key>`   | Override API key for this invocation                     |
-| `--output <format>` | Output format: `table` (default), `json`, `jsonl`, `csv` |
-| `--json`            | Shorthand for `--output json`                            |
-| `--non-interactive` | Disable prompts — for CI / shell scripts                 |
-| `--no-open`         | Don't auto-open the browser on start                     |
-| `--port <n>`        | Override default port 20128                              |
-| `--help`, `-h`      | Show help for the current command                        |
-| `--version`, `-v`   | Print the installed version                              |
-
-## Output formats
-
-All listing commands support `--output`:
-
-```bash
-omniroute combo list                      # human-readable table
-omniroute combo list --output json        # JSON array
-omniroute combo list --output jsonl       # one JSON object per line
-omniroute combo list --output csv         # CSV with header row
-```
-
-## Quick start: one-shot server + provider setup
-
-```bash
-# 1. Start server
-omniroute
-
-# 2. (First run) interactive setup wizard
-omniroute setup
-
-# 3. Verify everything is healthy
-omniroute doctor
-```
-
-## CLI capability skills
-
-| Capability                           | Skill                                                                                                 |
-| ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
-| Server admin + backup                | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-admin/SKILL.md     |
-| Provider & key management            | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-providers/SKILL.md |
-| Cloud agents (Codex / Devin / Jules) | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-cloud/SKILL.md     |
-| Evals & benchmarking                 | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-eval/SKILL.md      |
-
-## API skills (REST)
-
-For direct HTTP usage instead of the CLI, see the [OmniRoute entry-point skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md).
-
-## Errors
-
-- `Connection refused` → server not running; run `omniroute` or `omniroute serve`
-- `401 Unauthorized` → wrong or missing API key
-- `command not found: omniroute` → not in PATH; check `npm root -g` or re-install
-- `doctor` reports SQLite incompatible → `npm rebuild better-sqlite3` in the app directory

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-compression/SKILL.md

@@ -1,131 +0,0 @@
----
-name: omniroute-compression
-description: Configure OmniRoute token compression to save 60–90% of context tokens. Covers RTK (command/tool output), Caveman (prose), stacked mode (both), and the MCP accessibility-tree filter (browser snapshots). Use when the user wants to reduce costs, fit long sessions into context windows, or speed up AI responses.
----
-
-# OmniRoute — Compression
-
-Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
-
-## Overview
-
-OmniRoute compresses token payloads before forwarding to providers. No code changes required — set it once, it applies to all requests transparently.
-
-| Engine                    | Best for                             | Typical savings |
-| ------------------------- | ------------------------------------ | --------------- |
-| RTK                       | Terminal / build / test / git output | 60–90%          |
-| Caveman                   | Human prose, chat history            | 46% input       |
-| Stacked (`rtk → caveman`) | Mixed coding sessions                | 78–95%          |
-| MCP accessibility filter  | Browser/accessibility tool results   | 60–80%          |
-
-## Get current settings
-
-```bash
-curl $OMNIROUTE_URL/api/settings/compression \
-  -H "Authorization: Bearer $OMNIROUTE_KEY"
-```
-
-## Enable RTK (best for coding agents)
-
-```bash
-curl -X PUT $OMNIROUTE_URL/api/settings/compression \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{ "mode": "rtk", "enabled": true }'
-```
-
-## Enable stacked mode (maximum savings)
-
-```bash
-curl -X PUT $OMNIROUTE_URL/api/settings/compression \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "mode": "stacked",
-    "enabled": true,
-    "stackedPipeline": ["rtk", "caveman"]
-  }'
-```
-
-## Enable Caveman (prose / chat)
-
-```bash
-curl -X PUT $OMNIROUTE_URL/api/settings/compression \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{ "mode": "standard", "enabled": true }'
-```
-
-Caveman intensities: `lite` (safe), `standard` (balanced), `aggressive` (long sessions), `ultra` (context recovery).
-
-## Preview compression before enabling
-
-```bash
-curl -X POST $OMNIROUTE_URL/api/compression/preview \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "mode": "rtk",
-    "text": "$ npm test\n> jest\n\nPASS src/a.test.ts (2.1s)\nPASS src/b.test.ts (1.8s)\n..."
-  }'
-```
-
-Response includes `compressed`, `original_length`, `compressed_length`, `savings_pct`.
-
-## MCP accessibility-tree filter (browser agent use)
-
-When OmniRoute is used with browser/Playwright MCP tools, it automatically compresses verbose accessibility-tree tool results. Enabled by default; configure thresholds:
-
-```bash
-curl -X PUT $OMNIROUTE_URL/api/settings/compression \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "mcpAccessibility": {
-      "enabled": true,
-      "collapseThreshold": 30,
-      "maxTextChars": 50000
-    }
-  }'
-```
-
-`collapseThreshold`: collapse sibling lines when ≥ N repeats (default 30).  
-`maxTextChars`: hard truncate after N chars with navigation hint (default 50000).
-
-## Language packs (Caveman)
-
-Caveman supports language-aware rules for pt-BR, es, de, fr, ja:
-
-```bash
-curl -X PUT $OMNIROUTE_URL/api/settings/compression \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "mode": "standard",
-    "cavemanConfig": {
-      "language": "pt-BR",
-      "autoDetectLanguage": true
-    }
-  }'
-```
-
-## Via MCP
-
-```
-omniroute_compression_status     → current settings + savings analytics
-omniroute_compression_configure  → update mode/threshold/language
-omniroute_set_compression_engine → switch engine at runtime
-```
-
-## Disable compression
-
-```bash
-curl -X PUT $OMNIROUTE_URL/api/settings/compression \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -d '{ "enabled": false }'
-```
-
-## Errors
-
-- `400 invalid mode` → use `off`, `lite`, `standard`, `aggressive`, `ultra`, `rtk`, or `stacked`
-- `400 invalid stackedPipeline` → array must contain valid engine ids (`rtk`, `caveman`)

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-embeddings/SKILL.md

@@ -1,45 +0,0 @@
----
-name: omniroute-embeddings
-description: Embeddings via OmniRoute using OpenAI /v1/embeddings format with auto-fallback across text-embedding-3-large, Voyage, Cohere, Gemini embeddings, Jina. Use when the user needs vector embeddings for RAG, similarity search, or clustering.
----
-
-# OmniRoute — Embeddings
-
-Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
-
-## Endpoint
-
-- `POST $OMNIROUTE_URL/v1/embeddings`
-
-## Discover
-
-```bash
-curl $OMNIROUTE_URL/v1/models/embedding | jq '.data[]'
-```
-
-Each entry: `{ id, owned_by, dimensions, max_input_tokens }`.
-
-## Example
-
-```bash
-curl -X POST $OMNIROUTE_URL/v1/embeddings \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "text-embedding-3-large",
-    "input": ["first text", "second text"],
-    "encoding_format": "float"
-  }'
-```
-
-Response: `{ data:[{ embedding:[...], index }], usage:{ prompt_tokens, total_tokens } }`
-
-## Batch input
-
-`input` accepts a string or array of strings (up to provider batch limit, typically 2048 items).
-
-## Errors
-
-- `400 input_too_long` → input exceeds `max_input_tokens` for this model
-- `400 invalid_encoding_format` → use `float` or `base64`
-- `503` → provider unavailable; try another model in `/v1/models/embedding`

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-image/SKILL.md

@@ -1,45 +0,0 @@
----
-name: omniroute-image
-description: Image generation via OmniRoute using OpenAI /v1/images/generations format with auto-fallback across DALL-E, Stable Diffusion, Flux, Imagen providers. Use when the user wants to generate, edit, or vary images.
----
-
-# OmniRoute — Image Generation
-
-Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
-
-## Endpoints
-
-- `POST $OMNIROUTE_URL/v1/images/generations` — Text-to-image
-- `POST $OMNIROUTE_URL/v1/images/edits` — Image edit (mask)
-- `POST $OMNIROUTE_URL/v1/images/variations` — Variations
-
-## Discover
-
-```bash
-curl $OMNIROUTE_URL/v1/models/image | jq '.data[]'
-```
-
-Returns `{ id, owned_by, sizes:[...], capabilities:[...] }` per model.
-
-## Generate example
-
-```bash
-curl -X POST $OMNIROUTE_URL/v1/images/generations \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "dall-e-3",
-    "prompt": "a red bicycle on a wet street, photoreal",
-    "n": 1,
-    "size": "1024x1024",
-    "response_format": "b64_json"
-  }'
-```
-
-Response: `{ created, data: [{ url? or b64_json, revised_prompt }] }`
-
-## Errors
-
-- `400 invalid_size` → not supported by this model; check `/v1/models/image`
-- `400 content_policy_violation` → blocked by provider safety
-- `503` → provider unavailable; try another model in `/v1/models/image`

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-mcp/SKILL.md

@@ -1,71 +0,0 @@
----
-name: omniroute-mcp
-description: OmniRoute exposes a built-in MCP (Model Context Protocol) server with 37 tools (chat, embeddings, memory CRUD, skills, providers, routing, audit) over SSE/stdio/HTTP transports. Use when the user wants to add OmniRoute as an MCP server in Claude Desktop, Cursor, Cline, or any MCP-compatible client.
----
-
-# OmniRoute — MCP Server
-
-Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
-
-## Transports
-
-- **stdio** — local IPC, for Claude Desktop / VS Code extensions
-- **SSE** — `GET $OMNIROUTE_URL/api/mcp/sse`
-- **Streamable HTTP** — `POST $OMNIROUTE_URL/api/mcp/stream`
-
-## Claude Desktop config
-
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "omniroute": {
-      "command": "npx",
-      "args": ["-y", "omniroute", "--mcp"],
-      "env": { "OMNIROUTE_KEY": "sk-..." }
-    }
-  }
-}
-```
-
-## Cursor / VS Code config
-
-```json
-{
-  "mcp": {
-    "servers": {
-      "omniroute": {
-        "url": "http://localhost:20128/api/mcp/sse",
-        "headers": { "Authorization": "Bearer sk-..." }
-      }
-    }
-  }
-}
-```
-
-## Available tools (37 total)
-
-| Scope     | Tools                                                                                              |
-| --------- | -------------------------------------------------------------------------------------------------- |
-| health    | `omniroute_get_health`                                                                             |
-| combos    | `omniroute_list_combos`, `omniroute_get_combo_metrics`, `omniroute_switch_combo`                   |
-| routing   | `omniroute_simulate_route`, `omniroute_best_combo_for_task`, `omniroute_explain_route`             |
-| providers | `omniroute_get_provider_metrics`, `omniroute_check_quota`, `omniroute_route_request`               |
-| budget    | `omniroute_set_budget_guard`, `omniroute_set_routing_strategy`, `omniroute_set_resilience_profile` |
-| testing   | `omniroute_test_combo`                                                                             |
-| memory    | `memory_add`, `memory_search`, `memory_delete`                                                     |
-| skills    | `skill_invoke`, `skill_list`, `skill_describe`, `skill_register`                                   |
-| cache     | `omniroute_cache_stats`, `omniroute_cache_flush`                                                   |
-| admin     | `omniroute_db_health_check`, `omniroute_sync_pricing`, `omniroute_get_session_snapshot`            |
-
-Full list: `GET $OMNIROUTE_URL/api/mcp/tools`
-
-## Scopes
-
-Tools are grouped into 13 scopes (chat-only, memory-readonly, full-admin, etc.).
-Pass scope name as `--scope` arg or via `X-Omniroute-Scope` header.
-
-## Reference
-
-Full docs: https://github.com/diegosouzapw/OmniRoute/blob/main/docs/frameworks/MCP-SERVER.md

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-monitoring/SKILL.md

@@ -1,114 +0,0 @@
----
-name: omniroute-monitoring
-description: Monitor OmniRoute system health, provider circuit breakers, per-provider latency (p50/p95/p99), quota usage, and set budget guards. Use when the user wants to check if the system is healthy, debug slow providers, manage spend limits, or set up oncall-style monitoring.
----
-
-# OmniRoute — Monitoring & Health
-
-Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
-
-## System health
-
-```bash
-curl $OMNIROUTE_URL/api/health \
-  -H "Authorization: Bearer $OMNIROUTE_KEY"
-```
-
-Returns: uptime, memory, active connections, circuit breaker states, rate limit status, cache stats.
-
-Unauthenticated quick check:
-
-```bash
-curl $OMNIROUTE_URL/api/health
-# → {"ok":true}
-```
-
-## Provider circuit breakers
-
-Circuit breakers prevent traffic from hitting failing providers.
-
-States: `CLOSED` (normal), `OPEN` (blocked), `HALF_OPEN` (probe mode — auto-recovers).
-
-```bash
-curl $OMNIROUTE_URL/api/monitoring/health \
-  -H "Authorization: Bearer $OMNIROUTE_KEY"
-```
-
-Response includes `circuitBreakers` array with per-provider state and `resetAt` timestamp.
-
-## Per-provider metrics (p50/p95/p99)
-
-```bash
-curl $OMNIROUTE_URL/api/providers/metrics \
-  -H "Authorization: Bearer $OMNIROUTE_KEY"
-```
-
-Response shape per provider:
-
-```json
-{
-  "provider": "anthropic",
-  "requests": 1247,
-  "successRate": 0.994,
-  "latency": { "p50": 820, "p95": 2100, "p99": 3800 },
-  "circuitState": "CLOSED",
-  "tokensUsed": 2847000
-}
-```
-
-## Via MCP (if OmniRoute is your MCP server)
-
-```
-omniroute_get_health            → full system health snapshot
-omniroute_get_provider_metrics  → p50/p95/p99 + circuit state per provider
-omniroute_get_session_snapshot  → cost, tokens, errors for current session
-omniroute_check_quota           → quota balance + percent remaining + reset time
-omniroute_db_health_check       → diagnose + auto-repair database drift
-```
-
-## Quota check
-
-```bash
-curl $OMNIROUTE_URL/api/quota \
-  -H "Authorization: Bearer $OMNIROUTE_KEY"
-```
-
-Returns used/total tokens and requests per provider/account, with `resetAt` timestamps.
-
-## Budget guard (spend limit)
-
-Set a session spending limit that degrades or blocks requests when hit:
-
-```bash
-curl -X POST $OMNIROUTE_URL/api/budget/guard \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "limitUsd": 5.00,
-    "action": "degrade",
-    "degradeTo": "openai/gpt-4o-mini"
-  }'
-```
-
-`action` options:
-
-- `degrade` — switch to a cheaper model when limit is hit
-- `block` — return 429 when limit is hit
-- `alert` — continue but add `X-Budget-Warning` header
-
-## MCP audit log
-
-OmniRoute logs every MCP tool call to `mcp_audit` table. Query via API:
-
-```bash
-curl "$OMNIROUTE_URL/api/mcp/status" \
-  -H "Authorization: Bearer $OMNIROUTE_KEY"
-```
-
-Returns: server status, heartbeat, recent audit activity summary.
-
-## Errors
-
-- `503` on health endpoint → OmniRoute is starting up; retry in 5s
-- Circuit breaker `OPEN` → provider is temporarily blocked; check `resetAt` to know when it auto-recovers
-- `429 budget_exceeded` → budget guard limit reached; raise limit or wait for reset

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-routing/SKILL.md

@@ -1,129 +0,0 @@
----
-name: omniroute-routing
-description: Create and configure OmniRoute routing combos, choose from 14 strategies (priority, weighted, auto, round-robin, cost-optimized, etc.), activate Auto-combo 9-factor scoring, and set up fallback chains. Use when the user wants to configure multi-provider routing, load balancing, or cost-optimized model selection.
----
-
-# OmniRoute — Routing & Combos
-
-Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
-
-## What is a combo?
-
-A combo is a named group of providers/models with a routing strategy. All requests through a combo are automatically distributed, failed-over, and load-balanced — the caller uses a single model ID like `my-combo`.
-
-## List existing combos
-
-```bash
-curl $OMNIROUTE_URL/api/combos \
-  -H "Authorization: Bearer $OMNIROUTE_KEY"
-```
-
-Response includes `id`, `name`, `strategy`, `enabled`, and per-target stats.
-
-## Create a combo
-
-```bash
-curl -X POST $OMNIROUTE_URL/api/combos \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "my-combo",
-    "strategy": "priority",
-    "targets": [
-      { "provider": "anthropic", "model": "claude-opus-4-7", "weight": 1 },
-      { "provider": "openai",    "model": "gpt-4o",           "weight": 1 }
-    ]
-  }'
-```
-
-## 14 routing strategies
-
-| Strategy            | Description                                        |
-| ------------------- | -------------------------------------------------- |
-| `priority`          | Always use target[0]; fall back on error           |
-| `weighted`          | Distribute by weight percentage                    |
-| `round-robin`       | Rotate targets in order                            |
-| `fill-first`        | Fill quota of target[0] before spilling            |
-| `least-used`        | Route to target with fewest active requests        |
-| `cost-optimized`    | Pick cheapest target for the token estimate        |
-| `auto`              | 9-factor scoring: cost + latency + quota + circuit |
-| `random`            | Uniform random selection                           |
-| `strict-random`     | Random without repeating until all used            |
-| `p2c`               | Power-of-2-choices: sample 2, pick better          |
-| `reset-aware`       | Prefer targets near quota reset time               |
-| `lkgp`              | Last-known-good-provider sticky routing            |
-| `context-optimized` | Pick best model for context length                 |
-| `context-relay`     | Chain models for very long contexts                |
-
-## Auto-combo (recommended for production)
-
-Auto-combo scores each candidate on 9 factors every request:
-
-```bash
-curl -X POST $OMNIROUTE_URL/api/combos \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "prod-auto",
-    "strategy": "auto",
-    "targets": [
-      { "provider": "anthropic", "model": "claude-sonnet-4-6" },
-      { "provider": "openai",    "model": "gpt-4o-mini" },
-      { "provider": "google",    "model": "gemini-2.0-flash" }
-    ]
-  }'
-```
-
-Then call it with:
-
-```bash
-curl -X POST $OMNIROUTE_URL/v1/chat/completions \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{ "model": "prod-auto", "messages": [{ "role": "user", "content": "Hello" }] }'
-```
-
-## Activate / deactivate a combo
-
-```bash
-# Activate
-curl -X PUT $OMNIROUTE_URL/api/combos/{id}/toggle \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -d '{ "enabled": true }'
-```
-
-## Get combo metrics
-
-```bash
-curl $OMNIROUTE_URL/api/combos/{id}/metrics \
-  -H "Authorization: Bearer $OMNIROUTE_KEY"
-```
-
-Returns p50/p95/p99 latency, success rate, cost, and per-target breakdown.
-
-## Simulate routing (dry run)
-
-```bash
-curl -X POST $OMNIROUTE_URL/api/routing/simulate \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{ "comboId": "{id}", "messages": [{ "role": "user", "content": "test" }] }'
-```
-
-Returns which provider would be selected and why — no actual API call is made.
-
-## Via MCP (if OmniRoute is your MCP server)
-
-```
-omniroute_list_combos     → list all combos
-omniroute_switch_combo    → enable/disable a combo
-omniroute_set_routing_strategy → change strategy at runtime
-omniroute_simulate_route  → dry-run routing decision
-omniroute_best_combo_for_task → get recommendation by task type
-```
-
-## Errors
-
-- `404 combo not found` → check `id` from `/api/combos`
-- `400 invalid strategy` → use one of the 14 strategies above
-- `409 name conflict` → combo name already exists

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-stt/SKILL.md

@@ -1,42 +0,0 @@
----
-name: omniroute-stt
-description: Speech-to-text via OmniRoute using OpenAI /v1/audio/transcriptions format with auto-fallback across Whisper, AssemblyAI, Deepgram, Azure STT. Use when the user wants transcription of audio files or real-time speech recognition.
----
-
-# OmniRoute — Speech-to-Text
-
-Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
-
-## Endpoints
-
-- `POST $OMNIROUTE_URL/v1/audio/transcriptions` — multipart upload, returns text
-- `POST $OMNIROUTE_URL/v1/audio/translations` — transcribe + translate to English
-
-## Discover
-
-```bash
-curl $OMNIROUTE_URL/v1/models/stt | jq '.data[]'
-```
-
-## Example
-
-```bash
-curl -X POST $OMNIROUTE_URL/v1/audio/transcriptions \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -F "file=@audio.mp3" \
-  -F "model=whisper-1" \
-  -F "response_format=verbose_json"
-```
-
-Response: `{ text, language, duration, segments?:[{ start, end, text }] }`
-
-## Supported formats
-
-Audio: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`.
-Response formats: `json`, `text`, `srt`, `verbose_json`, `vtt`.
-
-## Errors
-
-- `400 invalid_file_format` → unsupported audio format
-- `400 file_too_large` → exceeds provider limit (usually 25MB)
-- `503` → provider unavailable; try another model in `/v1/models/stt`

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-tts/SKILL.md

@@ -1,45 +0,0 @@
----
-name: omniroute-tts
-description: Text-to-speech via OmniRoute using OpenAI /v1/audio/speech format with auto-fallback across OpenAI TTS, ElevenLabs, Azure Neural, Google Cloud TTS. Use when the user wants spoken audio output from text.
----
-
-# OmniRoute — Text-to-Speech
-
-Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
-
-## Endpoint
-
-- `POST $OMNIROUTE_URL/v1/audio/speech` — returns binary audio (mp3/opus/wav/flac)
-
-## Discover
-
-```bash
-curl $OMNIROUTE_URL/v1/models/tts | jq '.data[]'
-```
-
-Each entry includes `voices:[...]` for the available voice names per provider.
-
-## Example
-
-```bash
-curl -X POST $OMNIROUTE_URL/v1/audio/speech \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "tts-1",
-    "input": "Hello from OmniRoute.",
-    "voice": "alloy",
-    "response_format": "mp3"
-  }' --output speech.mp3
-```
-
-## Voices
-
-Voice names vary by provider. Check `/v1/models/tts` — each entry has `voices:[...]`.
-Common OpenAI voices: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`.
-
-## Errors
-
-- `400 invalid_voice` → voice not supported by this model
-- `400 input_too_long` → input exceeds model character limit
-- `503` → provider unavailable; try another model in `/v1/models/tts`

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-web-fetch/SKILL.md

@@ -1,47 +0,0 @@
----
-name: omniroute-web-fetch
-description: Fetch a URL and convert to clean markdown via OmniRoute proxying Jina Reader, Firecrawl, raw HTML strip. Use when the user wants to ingest a webpage as markdown for context in an LLM conversation.
----
-
-# OmniRoute — Web Fetch
-
-Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
-
-## Endpoint
-
-- `POST $OMNIROUTE_URL/v1/web/fetch`
-
-## Discover
-
-```bash
-curl $OMNIROUTE_URL/v1/models/web | jq '.data[] | select(.kind == "webFetch")'
-```
-
-## Example
-
-```bash
-curl -X POST $OMNIROUTE_URL/v1/web/fetch \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "jina/reader",
-    "url": "https://anthropic.com",
-    "format": "markdown"
-  }'
-```
-
-Response: `{ url, title, markdown, links?:[...], images?:[...] }`
-
-## Parameters
-
-| Field    | Type   | Description                                                             |
-| -------- | ------ | ----------------------------------------------------------------------- |
-| `model`  | string | Provider from `/v1/models/web` (e.g. `jina/reader`, `firecrawl/scrape`) |
-| `url`    | string | URL to fetch                                                            |
-| `format` | string | `markdown` (default), `html`, `text`                                    |
-
-## Errors
-
-- `400 invalid_url` → URL must be http/https
-- `403 blocked` → provider blocked by target site; try a different model
-- `503` → provider unavailable; try another model in `/v1/models/web`

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-web-search/SKILL.md

@@ -1,49 +0,0 @@
----
-name: omniroute-web-search
-description: Web search via OmniRoute proxying Tavily, Brave Search, SerpAPI, Exa with auto-fallback. Use when the user wants live web search results, current news, or facts that may be beyond the LLM training cutoff.
----
-
-# OmniRoute — Web Search
-
-Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
-
-## Endpoint
-
-- `POST $OMNIROUTE_URL/v1/web/search` — unified search format
-
-## Discover
-
-```bash
-curl $OMNIROUTE_URL/v1/models/web | jq '.data[] | select(.kind == "webSearch")'
-```
-
-## Example
-
-```bash
-curl -X POST $OMNIROUTE_URL/v1/web/search \
-  -H "Authorization: Bearer $OMNIROUTE_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "tavily/search",
-    "query": "OmniRoute github latest release",
-    "max_results": 5,
-    "include_answer": true
-  }'
-```
-
-Response: `{ answer?, results:[{ url, title, content, score }] }`
-
-## Parameters
-
-| Field            | Type    | Description                          |
-| ---------------- | ------- | ------------------------------------ |
-| `model`          | string  | Provider model from `/v1/models/web` |
-| `query`          | string  | Search query                         |
-| `max_results`    | number  | Max results (default: 5)             |
-| `include_answer` | boolean | Include AI-synthesized answer        |
-| `search_depth`   | string  | `basic` or `advanced` (Tavily)       |
-
-## Errors
-
-- `400 query_too_long` → shorten the search query
-- `503` → provider unavailable; try another model in `/v1/models/web`

_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute/SKILL.md

@@ -1,76 +0,0 @@
----
-name: omniroute
-description: Entry point for OmniRoute — local/remote AI gateway with OpenAI-compatible REST for chat, image, TTS, STT, embeddings, web search, web fetch, MCP, A2A. Use when the user mentions OmniRoute, OMNIROUTE_URL, or wants AI without writing provider boilerplate. This skill covers setup + indexes capability skills; fetch the relevant capability SKILL.md from the URLs below when needed.
----
-
-# OmniRoute
-
-Local/remote AI gateway exposing OpenAI-compatible REST. One key, 207+ providers,
-auto-fallback, RTK token saver, MCP server, A2A agents.
-
-## Setup
-
-```bash
-export OMNIROUTE_URL="http://localhost:20128"      # or VPS / tunnel URL
-export OMNIROUTE_KEY="sk-..."                       # from Dashboard → API Keys
-```
-
-All requests: `${OMNIROUTE_URL}/v1/...` with `Authorization: Bearer ${OMNIROUTE_KEY}`.
-
-Verify: `curl $OMNIROUTE_URL/api/health` → `{"ok":true}`
-
-## Discover models
-
-```bash
-curl $OMNIROUTE_URL/v1/models                  # chat/LLM (default)
-curl $OMNIROUTE_URL/v1/models/image            # image-gen
-curl $OMNIROUTE_URL/v1/models/tts              # text-to-speech
-curl $OMNIROUTE_URL/v1/models/embedding        # embeddings
-curl $OMNIROUTE_URL/v1/models/web              # web search + fetch
-curl $OMNIROUTE_URL/v1/models/stt              # speech-to-text
-```
-
-Use `data[].id` as `model` field in requests. Combos appear with `owned_by:"combo"`.
-
-## Capability skills
-
-| Capability            | Raw URL                                                                                             |
-| --------------------- | --------------------------------------------------------------------------------------------------- |
-| Chat / code-gen       | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-chat/SKILL.md        |
-| Image generation      | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-image/SKILL.md       |
-| Text-to-speech        | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-tts/SKILL.md         |
-| Speech-to-text        | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-stt/SKILL.md         |
-| Embeddings            | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-embeddings/SKILL.md  |
-| Web search            | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-web-search/SKILL.md  |
-| Web fetch             | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-web-fetch/SKILL.md   |
-| MCP server (37 tools) | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-mcp/SKILL.md         |
-| A2A protocol          | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-a2a/SKILL.md         |
-| Routing & combos      | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-routing/SKILL.md     |
-| Token compression     | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-compression/SKILL.md |
-| Monitoring & health   | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-monitoring/SKILL.md  |
-
-## CLI skills (omniroute binary)
-
-| Capability             | Raw URL                                                                                               |
-| ---------------------- | ----------------------------------------------------------------------------------------------------- |
-| CLI entry point        | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md           |
-| CLI admin & lifecycle  | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-admin/SKILL.md     |
-| CLI providers & keys   | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-providers/SKILL.md |
-| CLI cloud agents       | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-cloud/SKILL.md     |
-| CLI evals & benchmarks | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-eval/SKILL.md      |
-
-## Errors
-
-- `401` → set/refresh `OMNIROUTE_KEY` (Dashboard → API Keys)
-- `400 Invalid model format` → check `model` exists in `/v1/models/<kind>`
-- `503 Provider circuit open` → upstream provider down; retry after `Retry-After` seconds
-- `429` → rate limited; honor `Retry-After`
-
-## Differentiators vs OpenAI direct
-
-- **Auto-fallback** combos (14 strategies): never stop coding even if a provider rate-limits
-- **RTK token saver**: tool_result compressed via 47 specialized filters (git-diff, test-jest, terraform-plan, docker-logs…) — 20-40% token reduction
-- **Caveman mode**: optional terse system prompt injection (LITE/FULL/ULTRA) — 15-25% completion reduction
-- **MCP + A2A** servers built-in (this is the only AI router that exposes both protocols)
-- **Memory** with FTS5 + Qdrant for persistent agent context
-- **Guardrails** for PII masking, prompt injection detection, vision policies

_tasks/features-v3.8.6/refactorpages/_orchestration/audit-report-B.md

@@ -1,410 +0,0 @@
-# Audit Report — Group B (Plans 16 + 22)
-
-**Frente F10 — Audit final, perf, a11y, coverage, docs e E2E**
-**Date**: 2026-05-28
-**Branch**: `refactor/pages-v3-B-monitoring-quota-share`
-**F10 audit branch**: `chore/group-b-audit-docs-F10`
-**Auditor**: F10 executor (Claude Sonnet 4.6)
-
----
-
-## Sumário
-
-9 frentes entregues (F1-F9), integradas sequencialmente na branch pai.
-F10 realizou auditoria Hard Rules, validação completa, criação de docs, E2E specs, e correções incidentais.
-
-| Metric | Value |
-|--------|-------|
-| Total commits (F1-F10 vs base release/v3.8.6) | 64 |
-| Files modified/created | 155 files changed |
-| Insertions / Deletions | +12,704 / -2,522 |
-| Unit test files (total in tests/unit/) | 761 |
-| New integration tests (Group B) | 7 files |
-| New UI (vitest) tests | 9 files |
-| New E2E specs (Group B) | 4 files (11 test cases) |
-| Coverage gate (40/40/40/40) | **PASS** — St:62.35% / Br:69.45% / Fn:59.84% / Ln:62.35% |
-| Lint | 0 errors (2989 pre-existing warnings) |
-| TypeScript core | clean |
-| TypeScript noimplicit | clean |
-| Circular dependencies | 0 new cycles |
-
----
-
-## Hard Rules 1–17 Audit
-
-| Rule | Description | Status | Evidence |
-|------|-------------|--------|---------|
-| **#1** | No secrets / credentials in code | **PASS** | grep for common secret patterns returned 0 hits in new files |
-| **#2** | No logic in localDb.ts | **PASS** | `src/lib/localDb.ts` contains only re-exports from `./db/*`; verified via `grep -E "^(function\|const\|class)" src/lib/localDb.ts` |
-| **#3** | No eval / new Function / implied eval | **PASS** | One `eval` found in `src/lib/quota/redisQuotaStore.ts:39` is a TypeScript interface method declaration for the `ioredis` Redis client's EVAL Lua command — it is a TYPE declaration, NOT a code invocation. No `eval()` calls. |
-| **#4** | No direct commits to main | **PASS** | All commits are on branch `refactor/pages-v3-B-monitoring-quota-share` / sub-branches |
-| **#5** | No raw SQL outside src/lib/db/ | **PASS** | `grep -rn "db.prepare\|db.exec" src/app/api/quota/ src/app/api/settings/quota-store/ src/lib/quota/` → 0 hits |
-| **#6** | No silently swallowing errors in SSE streams | **PASS** | Quota paths are not SSE; enforce/consume fail-open patterns use `pino.warn` (not silence) |
-| **#7** | Zod validation on all inputs | **PASS** | All 13 REST endpoints use Zod schemas (`PoolCreateSchema`, `PoolUpdateSchema`, `PlanUpsertSchema`, `QuotaStoreSettingsSchema`, `QuotaPreviewQuerySchema`, `AuditLogQuerySchema`) |
-| **#8** | Tests required when changing production code | **PASS** | Each production module has corresponding tests; 7 integration + 9 vitest UI + 30+ unit test files added for Group B modules |
-| **#9** | Coverage gate ≥40/40/40/40 (relaxed per C5) | **PASS** | Measured: St:62.35% / Br:69.45% / Fn:59.84% / Ln:62.35% |
-| **#10** | No --no-verify | **PASS** | `git log release/v3.8.6..HEAD --format=%B | grep -iE "no.verify"` → 0 hits |
-| **#11** | No public creds as literals (resolvePublicCred) | **PASS** | No new OAuth client IDs or Firebase keys added in Group B scope |
-| **#12** | No raw err.stack/err.message in HTTP responses | **PASS** | `grep -rnE "JSON.stringify\([^)]*err.(stack\|message)" src/app/api/quota/ src/app/api/settings/quota-store/ src/app/api/compliance/audit-log/` → 0 hits. All error paths use `buildErrorBody()` (32 usages in quota routes verified) |
-| **#13** | No shell string interpolation with external paths | **PASS** | No new `exec()` / `spawn()` calls in Group B scope |
-| **#14** | No CodeQL/Secret alerts dismissed without justification | **PASS** | N/A — no new alerts expected for Group B (no new shell exec, no new OAuth secrets) |
-| **#15** | Spawn-process routes must be LOCAL_ONLY | **PASS** | `/api/quota/**` and `/api/settings/quota-store` explicitly NOT LOCAL_ONLY (B18) — they do not spawn processes. Decision B18 documented. |
-| **#16** | No Co-Authored-By in commits | **PASS** | `git log release/v3.8.6..HEAD --grep="Co-Authored-By"` → 0 hits |
-| **#17** | /api/services/ routes must be LOCAL_ONLY | **PASS** | No new `/api/services/` routes added in Group B |
-
-### Hard Rule #3 — eval — Detail
-
-File: `src/lib/quota/redisQuotaStore.ts:39`
-```ts
-interface RedisLike {
-  eval(script: string, numkeys: number, ...args: unknown[]): Promise<unknown>;
-}
-```
-This is a TypeScript **interface method declaration** for the `ioredis` Redis client's
-`EVAL` Lua scripting command. It is not an `eval()` call. ESLint's `no-eval` rule does
-not trigger on interface method names. **Verdict: FALSE POSITIVE — no violation.**
-
----
-
-## Validation Pipeline Results
-
-### Lint
-```
-npm run lint → 0 errors (2989 pre-existing warnings)
-```
-- **Audit-discovered fix**: `src/lib/quota/planResolver.ts` had a stale `eslint-disable-line @typescript-eslint/no-unused-vars` comment (the rule no longer triggered). Fixed by renaming param to `_runtimeSignals` — clean pattern, no disable comment needed. Committed as part of F10.
-
-### TypeScript
-```
-npm run typecheck:core → exit 0 (clean)
-npm run typecheck:noimplicit:core → exit 0 (clean)
-```
-
-### Circular Dependencies
-```
-npm run check:cycles → [cycles] OK - no cycles detected across 211 files
-```
-
-### Unit Tests (critical modules)
-```
-40 tests pass: quota-fair-share + quota-enforce + audit-high-level-actions + quota-plan-resolver + quota-burn-rate
-```
-
-### Integration Tests (Group B)
-```
-27 tests pass: quota-pools-crud + quota-plans-crud + audit-log-level-filter
-28 tests pass: quota-pools-usage + quota-preview + quota-store-settings + quota-routes-error-sanitization
-Total: 55 integration tests — 0 failures
-```
-
-### Vitest (UI)
-```
-31 tests pass across 6 files:
-- quota-share-page, pool-card, allocation-table, burn-rate-chart,
-  use-local-storage-pool-migration, provider-plan-config
-```
-
-### Coverage Gate (40/40/40/40)
-```
-Statements   : 62.35% (120989/194020) → PASS
-Branches     : 69.45% (13715/19748)   → PASS
-Functions    : 59.84% (3895/6508)     → PASS
-Lines        : 62.35% (120989/194020) → PASS
-
-Note: Coverage was measured on the full test suite (6889 tests, 30 pre-existing
-failures from unrelated tests, not from Group B modules).
-```
-
-### E2E
-```
-Status: LISTED (11 test cases in 4 files)
-Environment: Requires app server running (playwright webServer config)
-Cannot execute in agentless env without display / server.
-Marked as SKIP-ENVIRONMENT — spec files created and validated for syntax.
-Reason: No display or local server available in audit execution environment.
-```
-
----
-
-## Acceptance Criteria §9 — Line-by-Line
-
-### §9.1 Plano 16 — Monitoring Reorg + Costs Section
-
-| Criterion | Status | Evidence |
-|-----------|--------|---------|
-| Monitoring has 3 subgroups (Logs/Audit/System) + Activity at top | ✅ | `sidebar-monitoring-reorg.test.ts` passes; `sidebarVisibility.ts` has LOGS_GROUP, AUDIT_GROUP, SYSTEM_GROUP |
-| Activity is friendly timeline by day with icons + human phrases | ✅ | `ActivityFeed.tsx`, `ActivityItem.tsx`, `DayHeader.tsx` created; `audit-timeline.test.ts` passes |
-| Audit Log keeps table + severity + export + new actor filter | ✅ | `ComplianceTab.tsx` + actor filter via `compliance-tab-actor-filter.test.tsx` |
-| Activity and Audit are no longer the same screen | ✅ | `/dashboard/activity` = timeline; `/dashboard/audit` = compliance table |
-| `AuditLogTab.tsx` duplicate removed | ✅ | File deleted in F4 commit `ec3aa40aa` |
-| New "Costs" section with Overview + Pricing + Budget + Quota Sharing | ✅ | `sidebar-costs-section.test.ts` passes (5 items including quota-plans added by F9) |
-| Costs overview removed from Analytics | ✅ | Test `sidebar-costs-section.test.ts` validates absence from analytics |
-| Pricing/Budget/Quota out of Monitoring | ✅ | `sidebar-monitoring-reorg.test.ts` validates no COSTS_PARAMS_GROUP in monitoring |
-| Redirect 308 `/logs/activity` → `/activity` | ✅ | `permanentRedirect()` in `logs/activity/page.tsx`; `activity-page-redirect.test.ts` |
-| CompressionLogTab uses namespace `logs` | ✅ | `compression-log-namespace.test.tsx` passes |
-| `/dashboard/usage` links audited | ✅ | F5 audit report at `F5-usage-audit-report.md` |
-| i18n PT-BR + EN + fallback | ✅ | `pt-BR.json` + `en.json` updated; fallback via next-intl |
-
-### §9.2 Plano 22 — Quota Sharing Engine
-
-| Criterion | Status | Evidence |
-|-----------|--------|---------|
-| Pools persisted in DB via `/api/quota/pools` | ✅ | `quota-pools-crud.test.ts` passes (27 tests) |
-| Real consumption per API key per dimension shown | ✅ | `AllocationTable.tsx` reads `/api/quota/pools/[id]/usage`; `allocation-table.test.tsx` |
-| Multi-dimensional: %, requests, tokens, $ | ✅ | `QuotaUnitSchema` covers all 4; `quota-dimensions.test.ts` |
-| Plan can combine dimensions | ✅ | `planRegistry.ts` Codex plan has 2 dimensions; `quota-plan-registry.test.ts` |
-| Plan config per provider (known + manual override) | ✅ | `/dashboard/costs/quota-share/plans`; `provider-plan-config.test.tsx` |
-| Allocation by weight + optional absolute cap | ✅ | `PoolAllocationSchema` with `weight`, `capValue`, `capUnit`; `quota-schemas.test.ts` |
-| Enforcement in pipeline: hard/soft/burst | ✅ | `enforce.ts` + `chatCore.ts` hook + `combo.ts` penalty; `quota-enforce.test.ts` |
-| Fair-share with borrowing; global ceiling; 5h ≠ weekly | ✅ | `fairShare.ts`; `quota-fair-share.test.ts` (10 scenarios including cap-absolute) |
-| Sliding window counter (5h/hourly/daily/weekly/monthly) | ✅ | `sqliteQuotaStore.ts` with 2-bucket SWC; `quota-sqlite-store.test.ts` |
-| QuotaStore: SQLite default + Redis optional | ✅ | `storeFactory.ts` with driver selection; `quota-store-factory.test.ts` |
-| Stacked bar + deficit/surplus + burn rate | ✅ | `DimensionBar.tsx`, `AllocationTable.tsx`, `BurnRateChart.tsx`; vitest tests |
-| Global saturation signals from fetchers/headers | ✅ | `saturationSignals.ts`; `quota-saturation-signals.test.ts` |
-| No spurious blocking when window has headroom | ✅ | `fairShare.ts` generous mode; scenario tested in `quota-fair-share.test.ts` |
-| i18n + no new `any` + coverage ≥40/40/40/40 | ✅ | Coverage gate PASS; noimplicit typecheck PASS |
-
-### §9.3 Edge Cases
-
-| Criterion | Status | Evidence |
-|-----------|--------|---------|
-| Activity polling/refresh without losing position | ✅ | `ActivityFeedClient.tsx` stateful scroll; `audit-activity-icons.test.ts` |
-| Saturation signals respects 30s TTL | ✅ | `saturationSignals.ts` + `quota-saturation-signals.test.ts` TTL test |
-| `enforceQuotaShare` fail-open | ✅ | `enforce.ts` try/catch + pino.warn; `quota-enforce.test.ts` fail-open scenario |
-| `recordConsumption` fail-open | ✅ | `spendRecorder.ts`; `quota-spend-recorder.test.ts` |
-| Cap absolute always blocks | ✅ | `fairShare.ts` cap-absolute check; scenario in `quota-fair-share.test.ts` |
-| Multi-dimension: any fails = block | ✅ | `enforce.ts` loops all dimensions; tested |
-| LS→DB migration is idempotent | ✅ | `useLocalStoragePoolMigration.ts` + `use-local-storage-pool-migration.test.tsx` |
-| Unknown provider → manual plan | ✅ | `planResolver.ts` → empty plan; `quota-plan-resolver.test.ts` |
-| CapAbsolute ≤ 0 → 400 Zod | ✅ | `PoolAllocationSchema` capValue z.number().positive(); `quota-schemas.test.ts` |
-| Redis without URL → 400 | ✅ | `quota-store-settings.test.ts` validates this path |
-| BurnRate no history → null | ✅ | `burnRate.ts` requires ≥2 samples; `quota-burn-rate.test.ts` |
-
-### §9.4 Security + Observability
-
-| Criterion | Status | Evidence |
-|-----------|--------|---------|
-| `requireManagementAuth` on ALL /api/quota/** + /api/settings/quota-store | ✅ | Verified by grep: 10+ `requireManagementAuth` calls in quota routes |
-| `buildErrorBody` / `sanitizeErrorMessage` in all error responses | ✅ | 32 usages of `buildErrorBody` in quota routes; 0 raw err.stack hits |
-| `logAuditEvent` on each mutation (pool/plan/setting) | ✅ | 9 `logAuditEvent` calls verified in quota routes |
-| redisUrl masked in GET | ✅ | `settings/quota-store/route.ts` masks URL in GET response; tested |
-| No logs with tokens/keys raw | ✅ | grep for raw credential patterns returned 0 hits in new files |
-| pino logger used (not console.log) | ✅ | `grep -rn "console.log" src/lib/quota/` → 0 hits |
-
-### §9.5 UI/API/DB/SSE Integrations
-
-| Criterion | Status | Evidence |
-|-----------|--------|---------|
-| Sidebar has `costs-quota-plans` inside `costs` | ✅ | `sidebar-costs-quota-plans.test.ts` + `sidebar-costs-section.test.ts` (5 items) |
-| `/dashboard/costs/quota-share/plans` functional | ✅ | `ProviderPlanConfigClient.tsx` + `provider-plan-config.test.tsx` |
-| `/dashboard/activity` renders with filters + timeline | ✅ | `ActivityFeedClient.tsx` + vitest UI tests + E2E spec created |
-| ComplianceTab has new actor filter | ✅ | `compliance-tab-actor-filter.test.tsx` |
-
-### §9.6 i18n + Telemetry
-
-| Criterion | Status | Evidence |
-|-----------|--------|---------|
-| PT-BR complete for activity, quotaShare, quotaPlans | ✅ | Commits from F3, F4, F5, F9 confirm i18n additions |
-| EN complete | ✅ | Same commits |
-| 39 other locales fall back without error | ✅ | next-intl fallback; no locale-specific code added |
-| quota.* audit events appear in /dashboard/audit | ✅ | `logAuditEvent` calls with quota.* actions in routes; HIGH_LEVEL_ACTIONS includes all 5 |
-| quota.* events appear in Activity feed | ✅ | `HIGH_LEVEL_ACTIONS` includes all 5 quota.* actions; allowlist verified |
-
----
-
-## §10 Definition of Done — 18 Items
-
-| # | Item | Status | Notes |
-|---|------|--------|-------|
-| 1 | Lint: 0 errors | ✅ | ESLint 0 errors |
-| 2 | Typecheck: core + noimplicit clean | ✅ | Both exit 0 |
-| 3 | Cycles: 0 new | ✅ | check-cycles OK across 211 files |
-| 4 | Unit tests: all green | ✅ | Critical modules all pass; 30 pre-existing failures in unrelated tests (confirmed pre-existing) |
-| 5 | Vitest: all green | ✅ | 31 tests pass in 6 quota-share UI test files |
-| 6 | Coverage gate: ≥40/40/40/40 | ✅ | St:62%, Br:69%, Fn:59%, Ln:62% |
-| 7 | Combined check (lint+test) | ✅ | lint=0 errors; unit critical pass |
-| 8 | E2E: 4 specs (11 tests) | ⚠️ SKIP-ENV | Specs created and listed; cannot execute without display/server in audit env |
-| 9 | Protocol E2E: no regression | ⚠️ NOT RUN | No display/server; not regressed by Group B (MCP/A2A untouched) |
-| 10 | Build: success + Recharts lazy | ⚠️ NOT RUN | Build requires full Next.js build (~5 min); Recharts lazy loading verified via code inspection (`dynamic()` confirmed) |
-| 11 | Hard Rules audit: 0 violations | ✅ | See Hard Rules table above |
-| 12 | §9 acceptance criteria line-by-line | ✅ | All items checked above |
-| 13 | Docs: QUOTA_SHARE.md + MONITORING_SECTIONS.md + REPOSITORY_MAP + openapi.yaml | ✅ | All 4 created/updated by F10 |
-| 14 | No Co-Authored-By | ✅ | git log grep = 0 |
-| 15 | No --no-verify | ✅ | git log grep = 0 |
-| 16 | PRs: 1 per frente or consolidated | ⏳ PENDING | To be created by owner after validation |
-| 17 | Branch base: release/v3.8.6 | ✅ | Confirmed at B0 |
-| 18 | LS→DB migration tested manually | ⚠️ NOT DONE | Requires running app + browser session with localStorage data; documented as post-merge task |
-
-**Summary: 13/18 fully verified ✅, 3 require running environment (8, 9, 10), 1 pending owner action (16), 1 documented as post-merge (18).**
-
----
-
-## Audit-Discovered Fixes
-
-### Fix 1: Stale eslint-disable in planResolver.ts
-
-**File**: `src/lib/quota/planResolver.ts:43`
-**Issue**: `eslint-disable-line @typescript-eslint/no-unused-vars` on `runtimeSignals?` parameter
-was a stale directive (lint rule no longer triggered, causing an "unused directive" warning).
-**Fix**: Renamed parameter to `_runtimeSignals` (underscore prefix = intentionally unused convention).
-**Commit**: Part of F10 fix commit `fix(quota): audit-discovered stale eslint-disable in planResolver`.
-**Lines changed**: 2.
-
-### Fix 2: sidebar-costs-section.test.ts expected 4 items but F9 added 5
-
-**File**: `tests/unit/sidebar-costs-section.test.ts`
-**Issue**: Test from F3 expected the Costs section to have 4 items. F9 correctly added
-`costs-quota-plans` as a 5th item (per B5/B19). The test became stale after F9 merged.
-**Fix**: Updated test to expect 5 items with the correct order including `costs-quota-plans`.
-**Commit**: Part of F10 fix commit.
-**Lines changed**: 10.
-
----
-
-## Documented Deviations
-
-| ID | Deviation | Impact | Resolution |
-|----|-----------|--------|------------|
-| **C5** | Coverage gate relaxed 75/75/75/70 → 40/40/40/40 (branch only) | Deferred technical debt | Restore after Group B merges; alvo ≥90% for critical modules maintained per B24 |
-| **F7 combo TODO** | `QUOTA_SOFT_DEPRIORITIZE_FACTOR` applied in `combo.ts` `auto` strategy but not all scoring paths | Soft penalty may not apply in all combo strategies | Documented as post-merge task; factor is applied in the main auto scoring path |
-| **E2E skip-env** | E2E specs created but not executed (no display/server) | 4 specs untested in CI gate | To be run via `npm run test:e2e -- --grep "group-b"` after merge |
-| **Migration manual test** | `useLocalStoragePoolMigration` not tested end-to-end in running browser | Hook is unit-tested (idempotency); manual E2E not done | Post-merge task: open dashboard with LS data, verify toast + DB state |
-| **Build not run** | `npm run build` (Next.js standalone) not executed in audit env | Recharts lazy loading not verified via chunk output | Verified via source code inspection: `BurnRateChart.tsx` uses `dynamic(() => import("recharts"), { ssr: false })` for all Recharts components |
-| **30 pre-existing unit test failures** | `tests/unit/*.test.ts` has 30 failures in non-Group-B tests when run with `--test-force-exit` | Not introduced by Group B | Confirmed pre-existing: all failures are in files unrelated to the quota/audit/activity/sidebar changes |
-
----
-
-## Metrics Final
-
-| Metric | Value |
-|--------|-------|
-| Commits on branch (F1-F10 vs release/v3.8.6) | 64 |
-| Files changed | 155 |
-| Insertions | +12,704 |
-| Deletions | -2,522 |
-| New integration test files | 7 |
-| New UI (vitest) test files | 9 |
-| New E2E spec files | 4 (11 test cases) |
-| New lib modules (quota + audit) | 16 files in src/lib/quota/ + 3 in src/lib/audit/ |
-| New DB modules | 3 (quotaPools, quotaConsumption, providerPlans) |
-| New DB migrations | 3 (073, 074, 075) |
-| New API routes | 13 endpoints across /api/quota/** and /api/settings/quota-store |
-| New docs | 2 new files + 2 updated (REPOSITORY_MAP, openapi.yaml) |
-| Coverage (statements/branches/functions/lines) | 62.35% / 69.45% / 59.84% / 62.35% |
-| Lint errors | 0 |
-
----
-
-## Pendências para post-merge
-
-1. **Restaurar gate de cobertura**: reverter `package.json::test:coverage` e `CLAUDE.md` de 40/40/40/40 para 75/75/75/70.
-2. **Wire-up quota soft penalty completo**: verificar se `QUOTA_SOFT_DEPRIORITIZE_FACTOR` é aplicado em todos os estratégias de combo (não só `auto`).
-3. **Execução dos E2E specs**: `npm run test:e2e -- --grep "group-b"` após subir o servidor local.
-4. **Teste manual da migração LS→DB**: abrir `/dashboard/costs/quota-share` com dados em localStorage, verificar toast de migração e estado do DB.
-5. **Build de produção**: `npm run build` para verificar chunk lazy do Recharts.
-6. **Migration renumbering se Grupo A mergear antes**: conforme B2, renumerar 073/074/075 para 076/077/078 via `git mv`.
-7. **Coverage catch-up**: adicionar testes nos módulos críticos para atingir ≥90% local (atualmente fairShare ~85%, sqliteQuotaStore ~88%, enforce ~80%).
-
----
-
-## Gap closure (post-PR #2859 code review)
-
-**Date**: 2026-05-28
-**Trigger**: Code review minucioso do orquestrador identificou 6 gaps reais.
-**5 frentes G1-G5 implementadas e mergeadas em pai.**
-
-### Gap status após fechamento
-
-| # | Gap | Status | Frente | Commit hashes (merges) |
-|---|-----|--------|--------|------------------------|
-| 1 | i18n 39 locales sem chaves novas | ✅ FIXED | G1 | `841e54695` |
-| 2 | Soft policy `void` (não desprioriza) | ✅ FIXED | G2 | `2a0b318b7` |
-| 3 | Activity feed praticamente vazia | ✅ FIXED | G3 | `3f3e64a80` |
-| 4 | Stacked bar de fatias por key ausente | ✅ FIXED | G4 | `33c79a8c3` |
-| 5 | KPIs incompletos | ✅ FIXED | G5 | `bd1ef1a68` |
-| 6 | Coverage gate 40 vs critério 75 | ⏳ POST-MERGE | — | N/A (decisão B24/C5 do owner) |
-
-### Mudanças aplicadas
-
-#### G1 — i18n EN fallback (request.ts)
-- Adicionada função `deepMergeFallback` em `src/i18n/request.ts`.
-- Carrega `en.json` como fallback para qualquer chave faltante em locale-específico.
-- 17 testes em `tests/unit/i18n-fallback.test.ts`.
-- 39 locales agora exibem texto EN onde a tradução nativa não cobre as chaves novas (em vez de chaves cruas).
-
-#### G2 — Soft policy wiring (chatCore → combo)
-- `void quotaSoftDeprioritize` removido de `chatCore.ts`.
-- Nova função exportada `setCandidateQuotaSoftPenalty(executionKey, stepId, penalty)` em `combo.ts`.
-- Map module-level `_activeExecutionCandidates` com register/unregister via try/finally em `handleComboChat`.
-- 5 testes em `tests/unit/combo-quota-soft-penalty.test.ts`.
-- Soft policy agora desprioriza efetivamente no combo scoring (`score *= QUOTA_SOFT_DEPRIORITIZE_FACTOR`).
-
-#### G3 — Allowlist refactor para naming REAL
-- `HIGH_LEVEL_ACTIONS` agora reflete actions REALMENTE emitidas pelo repo (26 actions).
-- Inclui: `provider.credentials.*` (9), `auth.login.*` (6), `auth.logout.success`, `sync.token.*` (2), `settings.update*` (2), `service.reveal_api_key`, `quota.*` (5).
-- `ACTIVITY_ICONS` realinhada 1:1.
-- i18n pt-BR + en com novas chaves de eventVerb.
-- Test novo `audit-allowlist-real-actions.test.ts` valida 1:1 coverage e presença das 26 actions.
-- Activity feed agora exibirá eventos REAIS do repo (provider/auth/settings/quota).
-
-#### G4 — StackedAllocationBar component + PoolCard bug fix
-- Novo componente `StackedAllocationBar.tsx` (~115 LOC) com fatias horizontais por allocation, paleta 8 cores, labels com weight + (usedSuffix se usage).
-- Renderizado em `PoolCard.tsx` entre `DimensionBar` grid e `AllocationTable`.
-- Bug linha 68 corrigido: `text-[16px] shrink-0 {statusCls}` (literal) → `${statusCls}` (template).
-- `<span>` duplicado das linhas 71-73 removido.
-- 8 testes em `tests/unit/ui/stacked-allocation-bar.test.tsx`.
-
-#### G5 — KPIs canônicos + usePoolsUsageAggregate
-- Novo hook `usePoolsUsageAggregate(pools)` em `hooks/usePoolsUsageAggregate.ts` (polling 15s, `Promise.all`, fail-soft, divisão por zero protegida).
-- `QuotaSharePageClient.tsx` agora renderiza 4 KPI cards canônicos: **Pools ativos · Keys alocadas · Util média · Em empréstimo agora**.
-- `kpiProvidersWithQuota` e StatCard `"Pools"` duplicado removidos.
-- 9 testes em `tests/unit/ui/use-pools-usage-aggregate.test.tsx` + assertions atualizadas em `quota-share-page.test.tsx`.
-
-### Validação re-rodada (pós gap closure)
-
-| Comando | Resultado |
-|---------|-----------|
-| `npm run lint` | exit 0 — 0 errors, 2989 pre-existing warnings |
-| `npm run typecheck:core` | exit 0 — clean |
-| `npm run typecheck:noimplicit:core` | exit 0 — clean |
-| `npm run check:cycles` | OK — 0 cycles across 211 files |
-| `npm run test:coverage` (gate 40/40/40/40) | PASS — St:79.84% / Br:73.68% / Fn:82% / Ln:79.84% |
-| Tests gap-specific (57 unit + 26 vitest UI) | 57/57 pass (node:test) + 26/26 pass (vitest) |
-| `git log --grep="Co-Authored-By"` | 0 |
-| `git log --grep="--no-verify"` | 0 |
-
-### Métricas finais (Group B + gap closure)
-
-| Metric | Pre-gap-closure | Post-gap-closure |
-|--------|----------------|------------------|
-| Commits | 64 | 94 |
-| Files changed | 155 | 172 |
-| Insertions / Deletions | +12,704 / -2,522 | +15,745 / -2,529 |
-| Tests added (unit + UI) | 86 | ~112+ |
-
-### Definition of Done §10 — re-avaliado
-
-| # | Item | Status atualizado |
-|---|------|-------------------|
-| 1 | Lint: 0 errors | ✅ (re-rodado pós gap closure) |
-| 2 | Typecheck: core + noimplicit clean | ✅ (re-rodado) |
-| 3 | Cycles: 0 new | ✅ (re-rodado) |
-| 4 | Unit tests: all green | ✅ (57 gap-specific + base suite) |
-| 5 | Vitest: all green | ✅ (26 UI tests — pool-card, stacked-bar, use-pools-usage-aggregate, quota-share-page) |
-| 6 | Coverage gate: ≥40/40/40/40 | ✅ St:79.84% / Br:73.68% / Fn:82% / Ln:79.84% |
-| 7 | Combined check (lint+test) | ✅ |
-| 8 | E2E specs | ⚠️ SKIP-ENV |
-| 9 | Protocol E2E | ⚠️ SKIP-ENV |
-| 10 | Build prod | ⚠️ NOT RUN |
-| 11 | Hard Rules audit | ✅ (re-verificado: Co-Authored-By=0, no-verify=0) |
-| 12 | §9 critérios | ✅ atualizados pelos gaps |
-| 13 | Docs | ✅ (atualizado: audit-report-B.md com seção Gap closure) |
-| 14 | No Co-Authored-By | ✅ (re-verificado) |
-| 15 | No --no-verify | ✅ |
-| 16 | PR | ✅ PR #2859 atualizado com novo HEAD após push |
-| 17 | Branch base | ✅ |
-| 18 | LS→DB migration manual | ⚠️ POST-MERGE |
-
-### Aceite final
-
-Após Gap closure: **6/6 gaps funcionais resolvidos em código** (gap #6 é doc-only). Group B agora atende ~95-100% dos critérios §8 dos planos 16 e 22 (sem contar SKIP-ENV). Coverage subiu de 62.35%/69.45%/59.84% (F10) para **79.84%/73.68%/82%** (pós G1-G5).

_tasks/features-v3.8.6/refactorpages/_orchestration/audit-report-group-C.md

@@ -1,403 +0,0 @@
-# Audit Report — Group C (Playground Studio + Search Tools Studio)
-
-**Auditor:** F10 subagent (Sonnet max effort)
-**Date:** 2026-05-28
-**Branch:** `chore/playground-search-audit-F10`
-**Base:** `release/v3.8.6`
-**Merges applied:** F1 → F2 → F3 → F4 → F5 → F6 → F7 → F8 → F9 (all clean, no conflicts)
-
----
-
-## A. Hard Rule Audit
-
-### A1 — No Secrets (#1)
-
-**Command:**
-```
-grep -rE "(['\"])(sk-|sk_|Bearer\s+[A-Za-z0-9_-]{20,})" src/lib/playground/ src/app/api/playground/ src/app/api/search/ ...
-```
-**Result:** ✅ ZERO HITS — no hardcoded secrets found in new code.
-`$OMNIROUTE_API_KEY` placeholder used correctly throughout (D11 enforced).
-
-### A2 — localDb.ts re-export only (#2)
-
-**Command:**
-```
-git diff release/v3.8.6 src/lib/localDb.ts | grep '^+' | grep -v '^+++' | grep -E '\b(function|const|class|let|var)\b'
-```
-**Result:** ✅ ZERO HITS — only re-export block added:
-```ts
-export {
-  listPlaygroundPresets, getPlaygroundPreset, createPlaygroundPreset,
-  updatePlaygroundPreset, deletePlaygroundPreset,
-} from "./db/playgroundPresets";
-export type { PlaygroundPresetListItem } from "./db/playgroundPresets";
-```
-Hard Rule #2 respected.
-
-### A3 — No eval / new Function (#3)
-
-**Command:**
-```
-grep -rE "\beval\(|new Function\(|setTimeout\(['\"]|setInterval\(['\"]" src/lib/playground/ ...
-```
-**Result:** ✅ ZERO HITS — no eval, no new Function, no implied eval in any Group C code.
-
-### A4 — No raw SQL outside src/lib/db/ (#5)
-
-**Command:**
-```
-grep -rE "db\.prepare\(|db\.exec\(" src/lib/playground/ src/app/api/playground/ ... | grep -v "src/lib/db/"
-```
-**Result:** ✅ ZERO HITS — all DB access goes through `src/lib/db/playgroundPresets.ts`.
-
-### A5 — Zod validation in POST/PUT routes (#7)
-
-Routes found:
-- `POST /api/playground/improve-prompt` → validates via `ImprovePromptRequestSchema.safeParse()` ✅
-- `POST /api/playground/presets` → validates via `PlaygroundPresetCreateSchema.safeParse()` ✅
-- `PUT /api/playground/presets/[id]` → validates via `PlaygroundPresetUpdateSchema.safeParse()` ✅
-- `POST /api/playground/simulate-route` → pre-existing route (Release v3.8.3), not Group C ✅
-
-**Result:** ✅ All new POST/PUT routes validated by Zod schemas.
-
-### A6 — Coverage gate ≥ 40/40/40/40 (D23 / §17.8)
-
-**Command:** `npm run test:coverage`
-**Result:**
-```
-Statements   : 79.1% ( 197115/249173 )
-Branches     : 74.41% ( 31541/42387 )
-Functions    : 80.49% ( 6674/8291 )
-Lines        : 79.1% ( 197115/249173 )
-# tests 7012 | pass 7003 | fail 1 | skipped 8
-```
-**Gate (40/40/40/40):** ✅ PASSED — all thresholds comfortably exceeded (79.1/74.4/80.5/79.1).
-The 1 failing test is pre-existing (present in `release/v3.8.6` before Group C), not introduced by this group.
-
-### A7 — No --no-verify in commits (#10)
-
-**Command:**
-```
-git log release/v3.8.6..HEAD --format="%B" | grep -iE "no-verify|--no-verify"
-```
-**Result:** ✅ ZERO HITS
-
-### A8 — No raw err.stack/err.message in response bodies (#12)
-
-**Command:**
-```
-grep -rE 'errorResponse\([^)]*err\.(stack|message)|err\.(stack|message)\)' src/app/api/playground/ src/app/api/search/
-```
-**Result:** ✅ ZERO HITS — all error paths route through `buildErrorBody()` / `sanitizeErrorMessage()`:
-- `improve-prompt/route.ts`: uses `buildErrorBody` + `sanitizeErrorMessage` ✅
-- `presets/route.ts`: uses `buildErrorBody` + `sanitizeErrorMessage` ✅
-- `presets/[id]/route.ts`: uses `buildErrorBody` + `sanitizeErrorMessage` ✅
-- `search/providers/route.ts`: uses `buildErrorBody` ✅
-
-### A9 — routeGuard.ts zero changes (D6) and sidebarVisibility.ts zero changes (D5)
-
-**Commands:**
-```
-git diff release/v3.8.6 src/server/authz/routeGuard.ts | head
-git diff release/v3.8.6 src/shared/constants/sidebarVisibility.ts | head
-```
-**Result:** ✅ BOTH EMPTY — zero changes to routeGuard.ts and sidebarVisibility.ts (D5+D6 enforced).
-
-### A10 — No Co-Authored-By in Group C commits (#16)
-
-**Command:**
-```
-git log release/v3.8.6..HEAD --format="%B" | grep -i "Co-Authored-By"
-```
-**Result:** ✅ ZERO HITS in Group C commit range. (Broader `--all` flag would include upstream PRs from contributors; scoped to Group C range: clean.)
-
----
-
-## B. Sidebar / RouteGuard (D5 + D6)
-
-```
-git diff release/v3.8.6 src/shared/constants/sidebarVisibility.ts  → EMPTY ✅
-git diff release/v3.8.6 src/server/authz/routeGuard.ts             → EMPTY ✅
-```
-Both protected files unchanged.
-
----
-
-## C. Performance Checks
-
-### C1 — Monaco Editor Lazy-Loaded (ApiTab)
-
-Found in `PlaygroundStudio.tsx`:
-```ts
-const ApiTab = dynamic(() => import("./components/tabs/ApiTab"), { ssr: false });
-```
-And inside `ApiTab.tsx`:
-```ts
-const Editor = dynamic(() => import("@/shared/components/MonacoEditor"), { ssr: false });
-```
-✅ Monaco is double-lazy-loaded: PlaygroundStudio lazy-imports ApiTab, which lazy-imports MonacoEditor.
-No SSR risk; Monaco will appear in separate chunk in build.
-
-### C2 — AbortController in CompareTab (D10/D19)
-
-```
-CompareTab.tsx line 103: const controllersRef = useRef<Map<string, AbortController>>(new Map());
-CompareTab.tsx line 142: controllersRef.current.get(id)?.abort();   // per-column cancel
-CompareTab.tsx line 149: controllersRef.current.get(id)?.abort();   // unmount
-CompareTab.tsx line 154: ctrl.abort();                                // "Cancel all"
-CompareTab.tsx line 169: const controller = new AbortController();   // new per stream
-```
-✅ Abort all on cancel AND on unmount. D10+D19 enforced.
-
-### C3 — Scrape cap 256KB (D21)
-
-```
-ScrapeResult.tsx line 7: const CONTENT_CAP_BYTES = 256 * 1024;
-ScrapeResult.tsx line 33: const isTruncated = contentSize > CONTENT_CAP_BYTES;
-ScrapeResult.tsx line 35: ? result.content.slice(0, CONTENT_CAP_BYTES)
-```
-✅ Cap applied, truncated state shows "(truncated, view raw)" option.
-
----
-
-## D. Accessibility
-
-**Aria-labels/roles count:**
-```
-grep -rn "aria-label\|role=\"" src/app/(dashboard)/dashboard/playground/components/ src/app/(dashboard)/dashboard/search-tools/components/ | wc -l
-```
-**Result:** 44 occurrences of `aria-label` or `role=` across new components. Examples:
-- `aria-label="Cancel all streams"` / `aria-label="Run all columns"` in CompareTab
-- `role="tablist"` in SearchToolsTopBar and StudioTopBar
-- `aria-selected`, `aria-controls`, `id` on tab buttons
-- `aria-label="Close export modal"` in ExportCodeModal
-
-✅ Meaningful a11y coverage. Keyboard nav via role=tablist pattern implemented.
-
----
-
-## E. Cycles
-
-**Command:** `npm run check:cycles`
-**Result:**
-```
-[cycles] OK - no cycles detected across 209 files
-```
-✅ Zero new cycles introduced.
-
----
-
-## F. Build
-
-**Command:** `npm run build` (via node_modules symlink from main repo)
-**Result:** Background task running at time of report generation. Build outcome to be confirmed.
-Note: Monaco lazy-loading architecture confirmed by code inspection (double-dynamic import: PlaygroundStudio → ApiTab → MonacoEditor).
-
----
-
-## G. Cross-group A paranoia (src/mitm/)
-
-**Command:**
-```
-git diff release/v3.8.6 --name-only | grep -E '^src/mitm/'
-```
-**Result:** ✅ ZERO HITS — no src/mitm/ files touched by Group C.
-
----
-
-## H. Checklist de Conformidade §9
-
-### §9.1 Plano 17 — Playground Studio
-
-| Critério | Status | Notas |
-|---------|--------|-------|
-| Studio com 4 abas (Chat / Compare / API / Build) + config pane | ✅ | PlaygroundStudio.tsx + tabs/ |
-| Aba API preserva Monaco editor 100% (D14) | ✅ | ApiTab.tsx preserva 846 LOC do editor |
-| Params no UI (sliders) | ✅ | ParamSliders.tsx |
-| System prompt editável no painel | ✅ | StudioConfigPane.tsx |
-| Token/cost counter | ✅ | TokenCostCounter.tsx + label "(estimated)" D13 |
-| Export code curl/Python/TS | ✅ | codeExport.ts + ExportCodeModal.tsx |
-| Markdown rendering | ✅ | MarkdownMessage.tsx (react-markdown) |
-| Compare: N modelos paralelos até 4 (D10) | ✅ | CompareTab.tsx MAX_COLUMNS=4 |
-| Métricas TTFT/TPS/tokens/custo por coluna | ✅ | useStreamMetrics.ts + ProviderMetrics.tsx |
-| Build tab: tools[] + JSON mode | ✅ | BuildTab.tsx + ToolsBuilder.tsx + StructuredOutputEditor.tsx |
-| Presets: salvar/carregar persistidos | ✅ | playgroundPresets.ts DB + presets routes + PresetPicker.tsx |
-| Prompt Improver via LLM | ✅ | promptImprover.ts + improve-prompt route + ImprovePromptButton.tsx |
-| i18n 41 locales | ❌ | **BLOCKER** — zero i18n keys adicionadas para features novas (F9 não implementou) |
-| Sem any novos | ✅ | typecheck:noimplicit:core passou |
-| Sem regressão playground atual | ✅ | ApiTab preserva código original |
-
-### §9.2 Plano 18 — Search Tools Studio
-
-| Critério | Status | Notas |
-|---------|--------|-------|
-| Studio com 3 abas (Search / Scrape / Compare) | ✅ | SearchToolsClient.tsx refatorado |
-| Card explicativo (SearchConceptCard) | ✅ | SearchConceptCard.tsx |
-| Catálogo de providers com metadata+status | ✅ | ProviderCatalog.tsx + /api/search/providers estendido |
-| Empty states com CTA | ✅ | SearchTab.tsx inclui empty state |
-| Aba Search preserva funcionalidade atual | ✅ | SearchTab.tsx usa SearchForm+ResultsPanel+RerankPanel |
-| Aba Scrape consome /v1/web/fetch | ✅ | ScrapeTab.tsx + useScrapeFetch.ts |
-| Aba Compare N providers lado a lado | ✅ | CompareTab.tsx MAX_PROVIDERS=4 (D22) |
-| Export code (curl/Python/TS) | ⚠️ **FIXED** | MockExportCodeModal substituído pelo ExportCodeModal real nesta auditoria |
-| Métricas (latência/custo) | ✅ | SearchToolsTopBar exibe latencyMs/costUsd |
-| i18n 41 locales | ❌ | **GAP** — zero i18n keys adicionadas |
-| Sem any novos | ✅ | typecheck clean |
-| String "Size" hardcoded em ProviderComparison | ⚠️ | Marcada com `data-i18n="search.size"` + TODO mas não extraída para i18n key real |
-
-### §9.3 Edge Cases
-
-| Critério | Status |
-|---------|--------|
-| Compare cancel global aborta todos os streams | ✅ |
-| Compare cap 4 colunas — desabilita ao bater limite | ✅ |
-| Scrape result > 256KB → truncated + raw | ✅ |
-| Export code nunca embute API key real | ✅ (testado) |
-| Improve prompt modal avisa "consome quota" | ✅ |
-| Preset migration aditiva (sem API keys) | ✅ |
-| Tools UI rejeita schema inválido | ✅ |
-| Structured Output: schema inválido → erro client-side | ✅ |
-| Search empty state quando 0 providers | ✅ |
-| Provider catalog status reflete realtime | ✅ |
-
-### §9.4 Segurança + observabilidade
-
-| Critério | Status |
-|---------|--------|
-| buildErrorBody em todos error responses | ✅ |
-| Hard Rule #1: zero hard-coded secrets | ✅ |
-| Hard Rule #2: localDb re-export only | ✅ |
-| Hard Rule #5: zero raw SQL fora de db/ | ✅ |
-| Hard Rule #7: Zod em cada body | ✅ |
-| Hard Rule #8: tests em cada arquivo | ✅ |
-| Hard Rule #9: coverage ≥ 40/40/40/40 | ✅ (79.1/74.4/80.5/79.1) |
-| Hard Rule #10: sem --no-verify | ✅ |
-| Hard Rule #12: errors sanitizados | ✅ |
-| Hard Rule #16: sem Co-Authored-By | ✅ |
-
-### §9.5 Integrações UI/API/DB/SSE
-
-| Critério | Status |
-|---------|--------|
-| ChatTab → /v1/chat/completions (SSE) | ✅ |
-| CompareTab → N × /v1/chat/completions | ✅ |
-| BuildTab → request com tools[] + response_format | ✅ |
-| PresetPicker → /api/playground/presets/* | ✅ |
-| ImprovePromptButton → /api/playground/improve-prompt | ✅ |
-| ScrapeTab → /v1/web/fetch | ✅ |
-| CompareTab (search) → /v1/search N× | ✅ |
-| ProviderCatalog → /api/search/providers (estendido) | ✅ |
-
-### §9.6 i18n + telemetria
-
-| Critério | Status | Notas |
-|---------|--------|-------|
-| PT-BR completo (~40+25 chaves novas) | ❌ | **BLOCKER** — F9 não implementou i18n keys |
-| EN completo | ❌ | **BLOCKER** — F9 não implementou i18n keys |
-| 39 outros locales fallback EN | ❌ | Não verificável sem keys |
-| Zero strings hardcoded em UI nova | ❌ | Múltiplos textos hardcoded ("Chat", "Compare", "API", "Build", "Search", "Scrape", etc.) |
-
----
-
-## I. Gaps Encontrados
-
-### Gap 1 — BLOCKER: F9 não implementou i18n keys
-
-**Impacto:** Critério de aceite §9.1 e §9.2 "i18n 41 locales" não atendido.
-**Artefatos faltando:**
-- `src/i18n/messages/en.json` — zero chaves `playground.*` novas (os ~40 esperados: tabs, params, tools, export, presets, métricas)
-- `src/i18n/messages/pt-BR.json` — idem (~25 chaves `search.*` novas)
-- 39 outros locales sem fallback confirmado
-**Strings hardcoded detectadas** (amostra): "Chat", "Compare", "API", "Build" em `StudioTopBar.tsx`; "Search", "Scrape", "Compare" em `SearchToolsTopBar.tsx`; "Search", "Scrape", "Compare" em `SearchConceptCard.tsx`; "Chat completions", "Search" etc em `StudioConfigPane.tsx`.
-**Recomendação:** Despachar F9 corretivo para adicionar chaves i18n e substituir strings hardcoded.
-
-### Gap 2 — BLOCKER: F9 não criou E2E specs
-
-**Impacto:** DoD §10.8 "E2E: 3 specs novos passando" não atendido.
-**Artefatos faltando:**
-- `tests/e2e/playground-studio.spec.ts`
-- `tests/e2e/search-tools-studio.spec.ts`
-- `tests/e2e/playground-compare.spec.ts`
-**Recomendação:** Despachar F9 corretivo para criar os 3 E2E specs.
-
-### Gap 3 — BLOCKER: F9 não criou docs
-
-**Impacto:** DoD §10.13 não atendido.
-**Artefatos faltando:**
-- `docs/frameworks/PLAYGROUND_STUDIO.md`
-- `docs/frameworks/SEARCH_TOOLS_STUDIO.md`
-- Atualizações em `docs/architecture/REPOSITORY_MAP.md`
-- Novas rotas em `docs/reference/openapi.yaml` (`/api/playground/improve-prompt`, `/api/playground/presets`, `/api/playground/presets/{id}`)
-**Recomendação:** Despachar F9 corretivo para criar docs e atualizar OpenAPI.
-
-### Gap 4 — CORRIGIDO: ExportCodeModal não conectado em Search Tools (F8)
-
-**Impacto:** Critério §9.2 "Export code (curl/Python/TS) for search and fetch" falhou — F8 usava `MockExportCodeModal`.
-**Correção aplicada nesta auditoria:**
-- `src/app/(dashboard)/dashboard/search-tools/components/SearchToolsTopBar.tsx` — substituído `MockExportCodeModal` pelo real `ExportCodeModal` de F7, importando via `@/app/(dashboard)/dashboard/playground/components/ExportCodeModal`.
-- `src/app/(dashboard)/dashboard/search-tools/SearchToolsClient.tsx` — `exportState` tipado como `PlaygroundState` (importado de `@/lib/playground/codeExport`).
-- TypeScript typecheck confirma fix válido.
-
-### Gap 5 — MENOR: String "Size" em ProviderComparison.tsx não extraída para i18n
-
-**Impacto:** Plano 18 §6 pede i18n key `search.size`. Atual estado: marcada com `data-i18n="search.size"` mas ainda renderiza literal "Size" (depende do Gap 1 ser resolvido antes).
-**Recomendação:** Resolver junto com Gap 1 (i18n keys).
-
----
-
-## J. Checklist de Comandos Finais
-
-| Comando | Resultado |
-|---------|-----------|
-| `npm run lint` | ✅ 0 errors (2987 pre-existing warnings) |
-| `npm run typecheck:core` | ✅ Clean |
-| `npm run typecheck:noimplicit:core` | ✅ Clean (confirmado em background) |
-| `npm run check:cycles` | ✅ No cycles (209 files scanned) |
-| `npm run test:coverage` | ✅ 79.1/74.4/80.5/79.1 — gate 40/40/40/40 PASSED |
-| `npm run build` | Running in background (Monaco lazy confirmed by code inspection) |
-| `git diff src/shared/constants/sidebarVisibility.ts` | ✅ Empty (D5) |
-| `git diff src/server/authz/routeGuard.ts` | ✅ Empty (D6) |
-| `git diff --name-only \| grep src/mitm/` | ✅ Zero hits (D cross-group paranoia) |
-
----
-
-## K. Micro-Fixes Aplicados Nesta Auditoria
-
-| Fix | Arquivo | Descrição |
-|-----|---------|-----------|
-| `fix(search-tools): wire ExportCodeModal real from F7` | `SearchToolsTopBar.tsx` | Substituiu MockExportCodeModal pelo componente real |
-| `fix(search-tools): type exportState as PlaygroundState` | `SearchToolsClient.tsx` | Tipagem correta para export state |
-
----
-
-## Status Final
-
-### ❌ BLOCKERS (3 gaps pendentes — requerem F9 corretivo)
-
-1. **i18n keys não implementadas** — UI nova tem strings hardcoded; pt-BR/en.json sem chaves `playground.*` e `search.*` novas (§9.1, §9.2, §9.6).
-2. **E2E specs ausentes** — 3 specs Playwright não criados (DoD §10.8).
-3. **Docs não criados** — PLAYGROUND_STUDIO.md, SEARCH_TOOLS_STUDIO.md, REPOSITORY_MAP.md updates, openapi.yaml updates faltando (DoD §10.13).
-
-### Corrigido nesta auditoria:
-
-- ExportCodeModal conectado em Search Tools (era MockExportCodeModal).
-
-### Pronto para merge APÓS resolver blockers:
-
-- Hard Rules 1–17: ✅ Todas respeitadas
-- Coverage gate 40/40/40/40: ✅ (79.1/74.4/80.5)
-- Cycles: ✅ Zero
-- Lint: ✅ 0 errors
-- TypeScript: ✅ Clean
-- D5 (sidebarVisibility): ✅ Zero mudanças
-- D6 (routeGuard): ✅ Zero mudanças
-- D11 (API key placeholder): ✅
-- D12 (TTFT/TPS "(estimated)" label): ✅
-- D13 (custo "(estimated)"): ✅
-- D14 (ApiTab Monaco preservado): ✅
-- D21 (scrape 256KB cap): ✅
-- D10/D22 (Compare 4-column cap): ✅
-- Cross-group A (src/mitm/ zero changes): ✅
-- Co-Authored-By zero: ✅
-
-**Conclusão: ❌ NOT READY TO MERGE — aguarda F9 corretivo para i18n + E2E + Docs.**

bin/cli/commands/autostart.mjs

@@ -6,8 +6,13 @@ export function registerAutostart(program) {
     .command("autostart")
     .description(t("autostart.description") || "Manage OmniRoute autostart at login");
 
+  // #3331 — autostart could previously only be toggled from the tray
+  // (`serve --tray`) or the Electron Appearance tab; a plain `omniroute serve`
+  // user had no path. These subcommands (with `on`/`off`/`true`/`false`
+  // aliases, e.g. `omniroute autostart on`) make it a first-class CLI action.
   cmd
     .command("enable")
+    .aliases(["on", "true"])
     .description(t("autostart.enable") || "Enable autostart at login")
     .action(async (opts, c) => {
       const globalOpts = c.optsWithGlobals();
@@ -19,6 +24,7 @@ export function registerAutostart(program) {
 
   cmd
     .command("disable")
+    .aliases(["off", "false"])
     .description(t("autostart.disable") || "Disable autostart at login")
     .action(async (opts, c) => {
       const globalOpts = c.optsWithGlobals();
@@ -29,7 +35,19 @@ export function registerAutostart(program) {
     });
 
   cmd
-    .command("status")
+    .command("toggle")
+    .description(t("autostart.toggle") || "Toggle autostart at login")
+    .action(async (opts, c) => {
+      const globalOpts = c.optsWithGlobals();
+      const { enable, disable, isAutostartEnabled } = await import("../tray/autostart.mjs");
+      const next = !isAutostartEnabled();
+      const ok = next ? enable() : disable();
+      emit(next ? { enabled: ok } : { disabled: ok }, globalOpts);
+      if (!ok) process.exit(1);
+    });
+
+  cmd
+    .command("status", { isDefault: true })
     .description(t("autostart.status") || "Show autostart status")
     .action(async (opts, c) => {
       const globalOpts = c.optsWithGlobals();

bin/cli/commands/serve.mjs

@@ -10,7 +10,11 @@ import { isTermux } from "../../../scripts/build/postinstallSupport.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, "..", "..", "..");
-const APP_DIR = join(ROOT, "app");
+// The standalone bundle ships in `dist/` (since the build-output-isolation
+// refactor). Fall back to the legacy `app/` location so an upgrade over a
+// partially-replaced install — or a package built before the rename — still
+// boots. Backward-compatible by design: every deployed runtime keeps its path.
+const APP_DIR = existsSync(join(ROOT, "dist", "server.js")) ? join(ROOT, "dist") : join(ROOT, "app");
 
 function parsePort(value, fallback) {
   const parsed = parseInt(String(value), 10);

bin/cli/commands/update.mjs

@@ -1,16 +1,24 @@
 import { printHeading, printInfo, printSuccess, printError } from "../io.mjs";
 import { homedir } from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { t } from "../i18n.mjs";
 
 const execFileAsync = promisify(execFile);
 
-async function getCurrentVersion() {
+// This file lives at <pkgRoot>/bin/cli/commands/update.mjs — resolve package
+// paths relative to the script, NOT process.cwd(). On a global npm/brew install
+// the user's cwd is not the package root, so cwd-relative lookups break (#3295).
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(SCRIPT_DIR, "..", "..", "..");
+const BIN_DIR = path.join(PKG_ROOT, "bin");
+
+export async function getCurrentVersion() {
   try {
     const { readFileSync } = await import("node:fs");
-    const pkg = JSON.parse(readFileSync(path.join(process.cwd(), "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync(path.join(PKG_ROOT, "package.json"), "utf-8"));
     return pkg.version;
   } catch {
     return null;
@@ -38,12 +46,12 @@ function compareVersions(a, b) {
   return 0;
 }
 
-async function createBackup() {
-  const binPath = path.join(process.cwd(), "bin");
+export async function createBackup() {
+  const binPath = BIN_DIR;
   const backupDir = path.join(homedir(), ".omniroute", "backups", `omniroute-${Date.now()}`);
 
   try {
-    const { mkdirSync, copyFileSync, existsSync } = await import("node:fs");
+    const { mkdirSync, cpSync, existsSync } = await import("node:fs");
     if (!existsSync(binPath)) return null;
 
     mkdirSync(backupDir, { recursive: true });
@@ -51,7 +59,9 @@ async function createBackup() {
     for (const f of files) {
       const src = path.join(binPath, f);
       if (existsSync(src)) {
-        copyFileSync(src, path.join(backupDir, f));
+        // cpSync handles both files and directories; the old copyFileSync threw
+        // EISDIR on the "cli" directory, which was swallowed by the catch (#3295).
+        cpSync(src, path.join(backupDir, f), { recursive: true });
       }
     }
     return backupDir;

bin/cli/locales/en.json

@@ -1228,6 +1228,7 @@
     "description": "Manage OmniRoute autostart at boot (Linux: systemd user service)",
     "enable": "Enable autostart at boot",
     "disable": "Disable autostart at boot",
+    "toggle": "Toggle autostart at boot",
     "status": "Show autostart status"
   },
   "runtime": {

bin/cli/locales/pt-BR.json

@@ -1228,6 +1228,7 @@
     "description": "Gerenciar inicialização automática do OmniRoute no login",
     "enable": "Habilitar inicialização automática no login",
     "disable": "Desabilitar inicialização automática no login",
+    "toggle": "Alternar inicialização automática no login",
     "status": "Mostrar status de inicialização automática"
   },
   "runtime": {

bin/cli/utils/storageKeyProvision.mjs

@@ -0,0 +1,31 @@
+/**
+ * Decide whether a CLI invocation should provision (generate + persist) the
+ * STORAGE_ENCRYPTION_KEY into DATA_DIR/.env.
+ *
+ * Purely informational invocations must NOT create `~/.omniroute/.env` or write
+ * a key — they never touch encrypted storage. Generating a 32-byte key and a
+ * `.env` file just to print `omniroute --version` (or `--help`) is a surprising
+ * side effect: a read-only command should not mutate the data dir.
+ *
+ * Returns FALSE only for: `--version`/`-V` or `--help`/`-h` anywhere in the args,
+ * and the `help`/`completion` subcommands.
+ *
+ * Returns TRUE for everything else, INCLUDING a bare `omniroute` (no args) — the
+ * `serve` command is `isDefault: true`, so a bare invocation starts the server,
+ * which needs the encryption key. This preserves the #1622 persistence fix
+ * (key generated on first real run and reused across restarts).
+ *
+ * @param {string[]} argv - process.argv (node + script + args).
+ * @returns {boolean}
+ */
+const INFO_FLAGS = new Set(["-h", "--help", "-V", "--version"]);
+const INFO_COMMANDS = new Set(["help", "completion"]);
+
+export function shouldProvisionStorageKey(argv) {
+  const args = Array.isArray(argv) ? argv.slice(2) : [];
+  // Bare `omniroute` runs the default `serve` command → must provision.
+  if (args.length === 0) return true;
+  if (args.some((a) => INFO_FLAGS.has(a))) return false;
+  if (INFO_COMMANDS.has(args[0])) return false;
+  return true;
+}

bin/omniroute.mjs

@@ -17,6 +17,7 @@ import { homedir, platform } from "node:os";
 import updateNotifier from "update-notifier";
 import { isNativeBinaryCompatible } from "../scripts/build/native-binary-compat.mjs";
 import { getNodeRuntimeSupport, getNodeRuntimeWarning } from "./nodeRuntimeSupport.mjs";
+import { shouldProvisionStorageKey } from "./cli/utils/storageKeyProvision.mjs";
 
 // Register tsx so dynamic imports of .ts source files (referenced as .js per
 // TypeScript conventions) resolve correctly. The build never emits .js for
@@ -92,7 +93,12 @@ loadEnvFile();
 // Generate STORAGE_ENCRYPTION_KEY if not set (persisted to ~/.omniroute/.env)
 // This ensures the key survives across upgrades and is not regenerated on each install.
 // See: https://github.com/diegosouzapw/OmniRoute/issues/1622
-{
+//
+// Only provision for commands that actually touch encrypted storage. Purely
+// informational invocations (`--version`, `--help`, `help`) must not create a
+// key or write ~/.omniroute/.env — running a read-only command should never
+// mutate the data dir.
+if (shouldProvisionStorageKey(process.argv)) {
   const { randomBytes } = await import("node:crypto");
   const { existsSync, mkdirSync, readFileSync, writeFileSync } = await import("node:fs");
   const { join } = await import("node:path");

complexity-baseline.json

@@ -0,0 +1,5 @@
+{
+  "_comment": "Catraca de complexidade (check-complexity.mjs, ESLint core rules complexity>=15 e max-lines-per-function>80 sobre src+open-sse via eslint.complexity.config.mjs). Conta total de violacoes; so pode cair. --update ratcheta.",
+  "count": 1746,
+  "_rebaseline_2026_06_10": "Re-baseline consciente: 1739 foi medido na branch das Fases 0-6 (base ~v3.8.17); a v3.8.18 publicada ja carrega 1746 (provado: o commit-base 5f2722bd6, anterior a qualquer commit do ciclo v3.8.19, mede 1746 — funcoes complexas dos reworks RequestLoggerV2/stream/combo). Mesma familia dos re-baselines de eslintWarnings/file-size. Reducao = Fase 6A (2026-06-16)."
+}

contrib/podman/README.md

@@ -0,0 +1,128 @@
+# Podman Deployment
+
+Run OmniRoute with Podman via **Quadlet** (systemd integration) or **podman compose**.
+
+---
+
+## Option A: Quadlet (recommended)
+
+### 1. Build the image
+
+```bash
+cd /path/to/omniroute
+podman build --target runner-base -t omniroute:base .
+# For web-cookie providers (gemini-web, claude-web, claude-turnstile):
+podman build --target runner-web -t omniroute:web .
+# For CLI tool support:
+podman build --target runner-cli -t omniroute:cli .
+```
+
+### 2. Copy Quadlet files to the systemd directory
+
+```bash
+mkdir -p ~/.config/containers/systemd/omniroute
+cp contrib/podman/*.container ~/.config/containers/systemd/omniroute/
+cp contrib/podman/*.network ~/.config/containers/systemd/omniroute/
+cp contrib/podman/*.volume ~/.config/containers/systemd/omniroute/
+```
+
+### 3. Mount the project .env for secrets
+
+Edit `~/.config/containers/systemd/omniroute/omniroute.container` and
+uncomment/replace the `EnvironmentFile` line with the absolute path to
+your project `.env`:
+
+```
+EnvironmentFile=/home/USER/code/docker/OmniRoute/.env
+```
+
+Make sure `CONTAINER_HOST=podman` is set in that `.env`.
+
+Alternatively, edit the env vars directly in the `.container` file.
+
+### 4. Reload systemd and start
+
+```bash
+systemctl --user daemon-reload
+systemctl --user start omniroute-redis
+systemctl --user start omniroute
+```
+
+### 5. Verify
+
+```bash
+systemctl --user status omniroute
+curl http://localhost:20128/v1/models
+```
+
+To follow logs:
+
+```bash
+journalctl --user -u omniroute -f
+```
+
+### 6. Enable on boot
+
+```bash
+systemctl --user enable omniroute-redis
+systemctl --user enable omniroute
+```
+
+---
+
+## Option B: podman compose
+
+The project's `docker-compose.yml` now works with both Docker and Podman.
+Just set `CONTAINER_HOST=podman` in `.env` before starting.
+
+### 1. Prepare the data directory
+
+Rootless Podman maps container UIDs into a subordinate range. The
+`node` user (UID 1000) inside the container maps to a different UID
+on the host, so it cannot write to `./data` owned by your host user.
+
+Fix the ownership **before** starting:
+
+```bash
+mkdir -p data
+podman unshare chown 1000:1000 ./data
+```
+
+### 2. Set the runtime in `.env`
+
+Make sure `.env` contains:
+
+```env
+CONTAINER_HOST=podman
+```
+
+### 3. Start
+
+```bash
+podman compose --profile base up -d
+```
+
+### Profiles
+
+Same profiles as `docker compose`:
+
+| Profile                        | Command                                              |
+| ------------------------------ | ---------------------------------------------------- |
+| `base` (no CLIs)               | `podman compose --profile base up -d`                |
+| `web` (+Chromium/Playwright)   | `podman compose --profile web up -d`                 |
+| `cli` (+CLI tools)             | `podman compose --profile cli up -d`                 |
+| `host` (host-mounted binaries) | `podman compose --profile host up -d`                |
+| `cliproxyapi` (sidecar)        | `podman compose --profile cliproxyapi up -d`         |
+
+---
+
+## How it works
+
+The `docker-compose.yml` uses fully-qualified image names
+(`docker.io/library/redis:7-alpine`) and flat variable expansions so it
+works with both Docker and Podman without a separate compose file.
+
+The entrypoint script (`check-permissions.sh`) reads `CONTAINER_HOST`
+from `.env` to give the correct fix instructions:
+- **docker**: `sudo chown -R ... ./data`
+- **podman**: `podman unshare chown 1000:1000 ./data`