docs(readme): use local SVG flags + convert doc-link tables to lists (#8317)

Flag emoji (regional-indicator) do not render on Windows and several
Safari/WebKit configs, breaking the 'In 42+ languages' table there.
Replace each emoji with a local SVG <img> from flag-icons (MIT), served
from docs/assets/flags/ so the language selector renders everywhere.

Also convert the 5 'Document | Description' reference tables to definition
lists — full-width and scroll-free on GitHub (tables are capped at
width:max-content and scroll horizontally on narrow viewports).

.agents/workflows/deploy-vps.md

@@ -1,76 +0,0 @@
----
-description: Deploy the latest OmniRoute code to the Akamai VPS (69.164.221.35) via npm
----
-
-# Deploy to VPS Workflow
-
-Deploy OmniRoute to the production VPS using `npm install -g` + PM2.
-
-**VPS:** `69.164.221.35` (Akamai, Ubuntu 24.04, 1GB RAM + 2.5GB swap)
-**Local VPS:** `192.168.0.15` (same setup)
-**Process manager:** PM2 (`omniroute`)
-**Port:** `20128`
-
-> [!IMPORTANT]
-> PM2 runs from the global npm package at `/usr/lib/node_modules/omniroute`.
-> **DO NOT** use git clone or local copies. The `npm install -g` command handles
-> building, publishing, and installing the standalone app in one step.
-
-## Steps
-
-### 1. Publish to npm
-
-Ensure the version in `package.json` is bumped and the package is published:
-
-```bash
-npm publish
-```
-
-### 2. Install on VPS and restart PM2
-
-// turbo-all
-
-```bash
-ssh root@69.164.221.35 "npm install -g omniroute@latest && pm2 restart omniroute && pm2 save && echo '✅ Deploy complete!'"
-```
-
-For the local VPS:
-
-```bash
-ssh root@192.168.0.15 "npm install -g omniroute@latest && pm2 restart omniroute && pm2 save && echo '✅ Deploy complete!'"
-```
-
-### 3. Verify the deployment
-
-```bash
-ssh root@69.164.221.35 "pm2 list && cat \$(npm root -g)/omniroute/package.json | grep version | head -1 && curl -s -o /dev/null -w 'HTTP %{http_code}' http://localhost:20128/"
-```
-
-Expected: PM2 shows `online`, version matches published, HTTP returns `307` (redirect to login).
-
-## How it works
-
-1. `npm publish` builds Next.js standalone + bundles everything into the npm package
-2. `npm install -g omniroute@latest` downloads and installs to `/usr/lib/node_modules/omniroute/`
-3. PM2 is registered to run `npm start` from that directory (cwd: `/usr/lib/node_modules/omniroute`)
-4. `pm2 restart omniroute` picks up the new code immediately
-
-## PM2 Setup (one-time)
-
-If PM2 needs to be reconfigured from scratch:
-
-```bash
-ssh root@<VPS> "
-  cd /usr/lib/node_modules/omniroute &&
-  PORT=20128 pm2 start app/server.js --name omniroute --env PORT=20128 &&
-  pm2 save &&
-  pm2 startup
-"
-```
-
-## Notes
-
-- The `.env` file is at `/usr/lib/node_modules/omniroute/.env`. Back it up before major npm updates.
-- PM2 is configured with `pm2 startup` to auto-restart on reboot.
-- Nginx proxies `omniroute.online` → `localhost:20128`.
-- The VPS has only 1GB RAM — builds happen locally via `npm publish`, not on the VPS.

.agents/workflows/generate-release.md

@@ -1,78 +0,0 @@
----
-description: Create a new release, bump version up to 1.x.10 threshold, update changelog, and manage Pull Requests
----
-
-# Generate Release Workflow
-
-Bump version, finalize CHANGELOG, commit, tag, push, publish to npm, and create GitHub release.
-
-## Steps
-
-### 1. Determine new version
-
-Check current version in `package.json` and increment the patch number:
-
-```bash
-grep '"version"' package.json
-```
-
-Version format: `1.x.y` — increment `y` for patch, `x` for minor (threshold: y=10 triggers x+1).
-
-### 2. Finalize CHANGELOG.md
-
-Replace `[Unreleased]` header with the new version and date:
-
-```markdown
-## [1.x.y] — YYYY-MM-DD
-```
-
-### 3. Bump version in package.json
-
-```bash
-sed -i 's/"version": "OLD"/"version": "NEW"/' package.json
-```
-
-### 4. Stage, commit, and tag
-
-// turbo-all
-
-```bash
-git add -A
-git commit -m "feat(release): vX.Y.Z — summary of changes"
-git tag -a vX.Y.Z -m "Release vX.Y.Z — summary"
-```
-
-### 5. Push to GitHub
-
-```bash
-git push origin main
-git push origin vX.Y.Z
-```
-
-### 6. Publish to npm
-
-```bash
-npm publish
-```
-
-Wait for completion (prepublishOnly runs `npm run build:cli` automatically).
-
-### 7. Create GitHub release
-
-```bash
-gh release create vX.Y.Z --title "Release vX.Y.Z" --notes-file /tmp/release_notes.md
-```
-
-### 8. Deploy to VPS (if requested)
-
-See `/deploy-vps` workflow for Akamai VPS or use npm for local VPS:
-
-```bash
-ssh root@<VPS_IP> "npm install -g omniroute@X.Y.Z && pm2 restart omniroute"
-```
-
-## Notes
-
-- Always run `/update-docs` BEFORE this workflow (ensures CHANGELOG and README are current)
-- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`
-- After npm publish, verify with `npm info omniroute version`

.agents/workflows/implement-features.md

@@ -1,131 +0,0 @@
----
-description: Analyze open feature request issues, implement viable ones on dedicated branches, and respond to authors
----
-
-# /implement-features — Feature Request Implementation Workflow
-
-## Overview
-
-Fetches open feature request issues, analyzes each against the current codebase, implements viable ones on dedicated branches, and responds to authors with results. Does NOT merge to main — leaves branches for author validation.
-
-## Steps
-
-### 1. Identify the Repository
-
-// turbo
-
-- Run: `git -C <project_root> remote get-url origin` to extract owner/repo
-
-### 2. Fetch Open Feature Request Issues
-
-// turbo
-
-- Run: `gh issue list --repo <owner>/<repo> --state open --limit 50 --json number,title,labels,body,comments,createdAt,author`
-- Filter for issues that are feature requests (label `enhancement`/`feature`, or body describes new functionality, or previously classified as feature request)
-- Sort by oldest first
-
-### 3. Analyze Each Feature Request
-
-For each feature request issue, perform a **two-level analysis**:
-
-#### Level 1 — Viability Assessment
-
-Ask yourself:
-
-- Does this feature align with the project's goals and architecture?
-- Is the request technically feasible with the current codebase?
-- Does it duplicate existing functionality?
-- Would it introduce breaking changes or security risks?
-- Is there enough detail to implement it?
-
-**Verdict options:**
-
-1. ✅ **VIABLE** — Makes sense, enough detail to implement → Go to Level 2
-2. ❓ **NEEDS MORE INFO** — Good idea but insufficient detail → Post comment asking for specifics
-3. ❌ **NOT VIABLE** — Doesn't fit the project or is fundamentally flawed → Post comment explaining why, close issue
-
-#### Level 2 — Implementation (only for VIABLE features)
-
-1. **Research** — Read all related source files to understand the current architecture
-2. **Design** — Plan the implementation, filling gaps in the original request
-3. **Create branch** — Name format: `feat/issue-<NUMBER>-<short-slug>`
-   ```bash
-   git checkout main
-   git pull origin main
-   git checkout -b feat/issue-<NUMBER>-<short-slug>
-   ```
-4. **Implement** — Build the complete solution following project patterns
-5. **Build** — Run `npm run build` to verify compilation
-6. **Commit** — Commit with: `feat: <description> (#<NUMBER>)`
-7. **Push** — Push the branch: `git push -u origin feat/issue-<NUMBER>-<short-slug>`
-8. **Return to main** — `git checkout main`
-
-### 4. Respond to Authors
-
-#### For VIABLE (implemented) features:
-
-// turbo
-Post a comment on the issue:
-
-````markdown
-## ✅ Feature Implemented!
-
-Hi @<author>! We've analyzed your request and implemented it on a dedicated branch.
-
-**Branch:** `feat/issue-<NUMBER>-<short-slug>`
-
-### What was implemented:
-
-- <bullet list of what was done>
-
-### How to try it:
-
-```bash
-git fetch origin
-git checkout feat/issue-<NUMBER>-<short-slug>
-npm install && npm run dev
-```
-````
-
-### Next steps:
-
-1. **Test it** — Please verify it works as you expected
-2. **Want to improve it?** — You're welcome to contribute! Just:
-   ```bash
-   git checkout feat/issue-<NUMBER>-<short-slug>
-   # Make your improvements
-   git add -A && git commit -m "improve: <your changes>"
-   git push origin feat/issue-<NUMBER>-<short-slug>
-   ```
-   Then open a Pull Request from your branch to `main` 🎉
-3. **Not quite right?** — Let us know in this issue what needs to change
-
-Looking forward to your feedback! 🚀
-
-```
-
-#### For NEEDS MORE INFO:
-// turbo
-Post a comment asking for specific missing details needed to implement, e.g.:
-- "Could you describe the exact behavior when X happens?"
-- "Which API endpoints should be affected?"
-- "Should this apply to all providers or only specific ones?"
-
-Add the context of WHY you need each piece of information.
-
-#### For NOT VIABLE:
-// turbo
-Post a polite comment explaining why the feature doesn't fit at this time:
-- If the idea is decent but timing is wrong: "This is an interesting idea, but it doesn't align with our current priorities. Feel free to open a new issue with more details if you'd like us to reconsider."
-- If fundamentally flawed: Explain the technical or architectural reasons why it won't work, suggest alternatives if possible.
-- Close the issue after posting the comment.
-
-### 5. Summary Report
-Present a summary report to the user via `notify_user`:
-
-| Issue | Title | Verdict | Branch / Action |
-|---|---|---|---|
-| #N | Title | ✅ Implemented | `feat/issue-N-slug` |
-| #N | Title | ❓ Needs Info | Comment posted |
-| #N | Title | ❌ Not Viable | Closed with explanation |
-```

.agents/workflows/issue-triage.md

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

.agents/workflows/resolve-issues.md

@@ -1,120 +0,0 @@
----
-description: Fetch all open GitHub issues, analyze bugs, resolve what's possible, triage the rest, wait for user validation, then commit and release
----
-
-# /resolve-issues — Automated Issue Resolution Workflow
-
-## Overview
-
-This workflow fetches all open issues from the project's GitHub repository, classifies them, analyzes bugs, resolves what can be fixed, and triages issues with insufficient information. **It does NOT merge or release automatically** — it creates a PR and waits for user validation before merging.
-
-## 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. Fetch All Open Issues
-
-// turbo
-
-- Run: `gh issue list --repo <owner>/<repo> --state open --limit 100 --json number,title,labels,body,comments,createdAt,author`
-- Parse the JSON output to get a list of all open issues
-- Sort by oldest first (FIFO)
-
-### 3. Classify Each Issue
-
-For each issue, determine its type:
-
-- **Bug** — Has `bug` label, or body contains error messages, stack traces, "doesn't work", "broken", "crash", "error"
-- **Feature Request** — Has `enhancement`/`feature` label, or body describes new functionality
-- **Question** — Has `question` label, or is asking "how to" something
-- **Other** — Anything else
-
-Focus ONLY on **Bugs** for resolution. Feature requests and questions should be skipped with a note in the final report.
-
-### 4. Analyze Each Bug — For each bug issue:
-
-#### 4a. Check Information Sufficiency
-
-Verify the issue contains enough information to reproduce and fix:
-
-- [ ] Clear description of the problem
-- [ ] Steps to reproduce
-- [ ] Error messages or logs
-- [ ] Expected vs actual behavior
-
-#### 4b. If Information Is INSUFFICIENT
-
-Call the `/issue-triage` workflow (located at `~/.gemini/antigravity/global_workflows/issue-triage.md`):
-// turbo
-
-- Post a comment asking for more details using `gh issue comment`
-- Add `needs-info` label using `gh issue edit`
-- Mark this issue as **DEFERRED** and move to the next one
-
-#### 4c. If Information Is SUFFICIENT
-
-Proceed with resolution:
-
-1. **Create a fix branch** — `git checkout -b fix/issue-<NUMBER>-<short-description>`
-2. **Research** — Search the codebase for files related to the issue
-3. **Root Cause** — Identify the root cause by reading the relevant source files
-4. **Implement Fix** — Apply the fix following existing code patterns and conventions
-5. **Test** — Build the project and run tests to verify the fix
-6. **Commit** — Commit with message format: `fix: <description> (#<issue_number>)`
-
-### 5. Generate Report & Wait for Validation
-
-Present a summary report to the user via `notify_user` with `BlockedOnUser: true`:
-
-| Issue | Title | Status        | Action                        |
-| ----- | ----- | ------------- | ----------------------------- |
-| #N    | Title | ✅ Ready      | Files changed (not committed) |
-| #N    | Title | ❓ Needs Info | Triage comment posted         |
-| #N    | Title | ⏭️ Skipped    | Feature request / not a bug   |
-
-> **⚠️ IMPORTANT**: Do NOT commit, close issues, or generate releases at this step.
-> Wait for the user to review the changes and respond with **OK** before proceeding.
-
-- If the user says **OK** or approves → Proceed to step 6
-- If the user requests changes → Apply the requested adjustments first, then present the report again
-- If the user rejects → Revert the changes and stop
-
-### 6. Commit & Push Fix Branch (only after user approval)
-
-After the user validates:
-
-- Commit each fix individually with message format: `fix: <description> (#<issue_number>)`
-- Push the fix branch: `git push origin fix/issue-<NUMBER>-<short-description>`
-- Create a PR: `gh pr create --title "fix: <description> (#<issue_number>)" --body "<details>" --base main`
-
-### 7. 🛑 WAIT — Notify User & Await PR Verification
-
-**This is a mandatory stop point.** Use `notify_user` with `BlockedOnUser: true`:
-
-- Inform the user that the PR was created and is **awaiting their verification**
-- Include the PR number, URL, and a summary of what was changed
-- **DO NOT merge, close issues, generate releases, or deploy until the user confirms**
-
-Wait for the user to respond:
-
-- **User confirms** → Proceed to step 8
-- **User requests changes** → Apply changes, push to the same branch, notify again
-- **User rejects** → Close the PR and stop
-
-### 8. Merge, Close Issues & Release (only after user confirms PR)
-
-After the user confirms the PR:
-
-1. **Merge** the PR: `gh pr merge <NUMBER> --merge --repo <owner>/<repo>` or via local merge
-2. **Close** resolved issues with a comment: `gh issue close <NUMBER> --repo <owner>/<repo> --comment "Fixed in <commit_hash>. The fix will be included in the next release."`
-3. **Switch to main**: `git checkout main && git pull`
-4. Run the `/update-docs` workflow (at `~/.gemini/antigravity/global_workflows/update-docs.md`) to update CHANGELOG and README
-5. Run the `/generate-release` workflow (at `.agents/workflows/generate-release.md`) to bump version, tag, and publish
-6. Deploy to local VPS: `ssh root@192.168.0.15 "npm install -g omniroute@<VERSION> && pm2 restart omniroute"`
-
-If NO fixes were committed, skip this step and just present the report.

.agents/workflows/review-prs.md

@@ -1,145 +0,0 @@
----
-description: Analyze open Pull Requests from the project's GitHub repository, generate a critical report, and optionally implement approved changes
----
-
-# /review-prs — PR Review & Analysis Workflow
-
-## 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 top of the PR branch** and the user must verify before merge.
-
-## 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. Fetch Open Pull Requests
-
-- Navigate to `https://github.com/<owner>/<repo>/pulls` and scrape all open PRs
-- 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)
-
-### 3. Analyze Each PR — For each open PR, perform the following analysis:
-
-#### 3a. 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
-
-#### 3b. 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?)
-
-#### 3c. 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
-
-#### 3d. 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?)
-
-#### 3e. Test Coverage
-
-- Does the PR include tests?
-- Are edge cases covered?
-- Would existing tests break?
-
-#### 3f. 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
-
-### 4. 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
-
-### 5. Present to User
-
-- Show the report via `notify_user` with `BlockedOnUser: true`
-- Wait for user decision:
-  - **Approved** → Proceed to step 6
-  - **Approved with changes** → Implement the fixes and corrections before merging
-  - **Rejected** → Close the PR or leave a review comment
-
-### 6. Implementation (if approved)
-
-- Checkout the PR branch: `gh pr checkout <NUMBER>`
-- Implement any required fixes identified in the analysis
-- If the Cross-Layer Analysis (3f) identified missing frontend/backend counterparts, implement them
-- **Commit improvements on top of the PR branch** with descriptive commit messages
-- Run the project's test suite to verify nothing breaks
-  // turbo
-- Run: `npm test` or equivalent test command
-- Build the project to verify compilation
-  // turbo
-- Run: `npm run build` or equivalent build command
-- Push the updated branch: `git push origin <branch-name>`
-
-### 7. 🛑 WAIT — Notify User & Await PR Verification
-
-**This is a mandatory stop point.** Use `notify_user` with `BlockedOnUser: true`:
-
-- Inform the user that the PR has been **improved and pushed**, and is **awaiting their verification**
-- Include:
-  - PR number and URL
-  - Summary of improvements/fixes applied
-  - Build/test status
-  - List of files changed
-- **DO NOT merge, generate releases, or deploy until the user confirms**
-
-Wait for the user to respond:
-
-- **User confirms** → Proceed to step 8
-- **User requests more changes** → Apply changes, push to the same branch, notify again
-- **User rejects** → Leave a review comment and stop
-
-### 8. Thank the Contributor
-
-- Post a **thank-you comment** on the PR via the GitHub API
-- The message should:
-  - Thank the author by name/username for their contribution
-  - Briefly mention what the PR accomplishes and any improvements applied
-  - Be friendly, professional, and encouraging
-- Example: _"Thanks @author for this great contribution! 🎉 The [feature/fix] is now merged and will be part of the next release. We appreciate your effort!"_
-
-### 9. Merge & Release (only after user confirms PR)
-
-After the user confirms the PR:
-
-1. **Merge** the PR into main (local merge with `--no-ff` or via `gh pr merge`)
-2. **Push** to main: `git push origin main`
-3. **Clean up** the feature branch: `git branch -d <branch-name>`
-4. **Update CHANGELOG.md** with the new feature/fix
-5. Run the `/generate-release` workflow (at `.agents/workflows/generate-release.md`) to bump version, tag, and publish
-6. Deploy to local VPS: `ssh root@192.168.0.15 "npm install -g omniroute@<VERSION> && pm2 restart omniroute"`

.agents/workflows/update-docs.md

@@ -1,105 +0,0 @@
----
-description: How to automatically summarize recent changes and update README and CHANGELOG
----
-
-# Update Documentation Workflow
-
-Update CHANGELOG.md, README.md, docs/ files, and all multi-language translations whenever features are added or changed.
-
-## Steps
-
-### 1. Summarize recent changes
-
-Review git log and identify new features, fixes, or changes since the last release tag:
-
-```bash
-git log $(git describe --tags --abbrev=0)..HEAD --oneline
-```
-
-### 2. Update English CHANGELOG.md
-
-Add an `[Unreleased]` section (or version header if releasing) with:
-
-- `### ✨ New Features` — each feature as a bullet point
-- `### 🐛 Bug Fixes` — if applicable
-- `### 🧪 Tests` — test count changes
-- `### 📁 New Files` — table of new files with purpose
-
-### 3. Update English README.md
-
-Update the feature tables in these sections:
-
-- **🧠 Routing & Intelligence** — for routing/model features
-- **🛡️ Resilience & Security** — for security/resilience features
-- **📊 Observability & Analytics** — for monitoring features
-- **☁️ Deploy & Sync** — for deployment features
-
-### 4. Update docs/ files
-
-- `docs/FEATURES.md` — update the Settings section description
-- `docs/API_REFERENCE.md` — add new API routes if any
-- `docs/ARCHITECTURE.md` — update architecture if structural changes
-
-### 5. 🌐 Sync Multi-Language Documentation (CRITICAL)
-
-// turbo-all
-
-**This step MUST be run after every README or docs update.**
-
-The project has **30 language versions** of documentation:
-
-**README files (root directory):**
-
-```
-README.md (English - source of truth)
-README.pt-BR.md README.pt.md README.es.md README.fr.md README.it.md
-README.de.md README.nl.md README.sv.md README.no.md README.da.md README.fi.md
-README.ru.md README.uk-UA.md README.bg.md README.sk.md README.pl.md README.ro.md README.hu.md
-README.ar.md README.he.md README.th.md README.in.md README.id.md README.ms.md README.vi.md
-README.ja.md README.ko.md README.zh-CN.md README.phi.md
-```
-
-**docs/i18n/ directories (29 languages):**
-
-```
-docs/i18n/{ar,bg,da,de,es,fi,fr,he,hu,id,in,it,ja,ko,ms,nl,no,phi,pl,pt,pt-BR,ro,ru,sk,sv,th,uk-UA,vi,zh-CN}/
-Each contains: API_REFERENCE.md, ARCHITECTURE.md, CODEBASE_DOCUMENTATION.md, FEATURES.md, TROUBLESHOOTING.md, USER_GUIDE.md
-```
-
-**Sync approach for feature table updates:**
-
-a. Identify which feature table rows were added to English README.md
-b. For each translated README, find the corresponding anchor lines:
-
-- **Routing section:** Find the `💬` (System Prompt) table row — the line before it is always the last routing feature. Insert new routing features before System Prompt.
-- **Resilience section:** Find the `📊` Rate Limits table row (the one in lines 590-600, NOT the quota tracking one in lines 560-570). Insert new resilience features after it.
-  c. The new feature entries can stay in English for technical features, matching the pattern used in the existing translations.
-  d. Use `sed` or similar tool to batch-insert across all 29 translated READMEs.
-
-**Verification:**
-
-```bash
-# Verify all READMEs have the new features
-grep -l "NEW_FEATURE_NAME" README.*.md | wc -l
-# Should return 30 (all language versions)
-```
-
-**FEATURES.md sync:**
-
-```bash
-# Update Settings description in all docs/i18n/*/FEATURES.md
-for dir in docs/i18n/*/; do
-  # Update the Settings section description to mention new features
-  # Check FEATURES.md in each directory
-done
-```
-
-### 6. Verify documentation changes
-
-```bash
-# Check all modified files
-git status --short
-
-# Verify no broken markdown
-# Optional: run markdownlint if available
-```

.dockerignore

@@ -9,6 +9,7 @@
 # Dependencies and build output
 node_modules
 .next
+.build
 out
 build
 dist
@@ -30,3 +31,98 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 .pnpm-debug.log*
+
+# Test suites
+tests
+test-results
+playwright-report
+blob-report
+
+# Documentation
+# 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
+docs/diagrams/**/*.jpeg
+docs/diagrams/**/*.gif
+docs/diagrams/**/*.webp
+# Note: `*.md` matches the root only (Go filepath.Match does not cross /),
+# so nested docs/**/*.md is implicitly kept without a re-include rule.
+*.md
+!README.md
+
+# Electron (separate build)
+electron
+
+# VS Code extension (separate project)
+vscode-extension
+
+# Build artifacts
+*.tgz
+*.AppImage
+*.deb
+*.rpm
+
+# Package manager lock (bun)
+bun.lock
+
+# Agent config
+.agents
+.gemini
+.claude
+.source
+
+# Misc
+llm.txt
+images
+clipr
+omnirouteCloud
+omnirouteSite
+
+# Temporary/Scratch Folders
+_*
+
+# CI/CD and Version Control (that are not actual code)
+.github
+.husky
+.omc
+
+# Test Configs and Reports
+playwright.config.ts
+vitest*.ts
+audit-report.json
+sonar-project.properties
+
+# Deployment Configs
+docker-compose*.yml
+fly.toml
+
+# Consistent with .gitignore
+.DS_Store
+.idea/
+.config/
+.data/
+.omnivscodeagent/
+*.sqlite-*
+*.tsbuildinfo
+next-env.d.ts
+security-analysis/
+.analysis/
+antigravity-manager-analysis/
+.sisyphus/
+.plans/
+app.__qa_backup/
+.app-build-backup-*/
+.gitnexus
+.worktrees
+.next-playwright/
+cloud/
+electron/dist-electron

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.sh]
+indent_size = 4

.env.homolog.example

@@ -0,0 +1,9 @@
+# Homologação E2E real — copie para .env.homolog (NUNCA commitar o real)
+HOMOLOG_BASE_URL=http://192.168.0.15:20128
+# Senha de management do dashboard da VPS (a mesma do /login)
+HOMOLOG_ADMIN_PASSWORD=
+# Deixe vazio: a suíte cria uma API key efêmera via admin e revoga no fim.
+# Só preencha para depurar uma camada isolada com uma key fixa.
+HOMOLOG_API_KEY=
+# Tier crítico (chat real, max_tokens=5). Demais providers: só validação de catálogo.
+HOMOLOG_CRITICAL_PROVIDERS=openai,anthropic,gemini,codex,grok,glm,deepseek,openrouter

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+* @diegosouzapw
+

.github/FUNDING.yml

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

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,171 @@
+name: Bug Report
+description: Report a bug or unexpected behavior in OmniRoute
+title: "[BUG] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. Please fill out the sections below so we can reproduce and fix the issue.
+
+  - type: input
+    id: version
+    attributes:
+      label: OmniRoute Version
+      description: "Run `omniroute --version` or check the left sidebar in the dashboard."
+      placeholder: "e.g. 3.7.9"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: Installation Method
+      options:
+        - npm (global)
+        - Docker / Docker Compose
+        - Electron desktop app
+        - Built from source
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - Windows
+        - macOS
+        - Linux
+    validations:
+      required: true
+
+  - type: input
+    id: os-version
+    attributes:
+      label: OS Version
+      placeholder: "e.g. Windows 11 25H2, macOS 26.5, Ubuntu 26.04"
+    validations:
+      required: false
+
+  - type: input
+    id: node-version
+    attributes:
+      label: Node.js Version
+      description: "Run `node --version`. Skip if using Docker."
+      placeholder: "e.g. 24.15.0"
+    validations:
+      required: false
+
+  - type: input
+    id: provider
+    attributes:
+      label: Provider(s) Involved
+      description: "Which AI provider(s) does this affect?"
+      placeholder: "e.g. Antigravity, OpenRouter, Ollama, Qwen"
+    validations:
+      required: false
+
+  - type: input
+    id: model
+    attributes:
+      label: Model(s) Involved
+      placeholder: "e.g. claude-opus-4-7, gpt-5.5, gemini-3.1-pro"
+    validations:
+      required: false
+
+  - type: input
+    id: client-tool
+    attributes:
+      label: Client Tool
+      description: "Which tool are you using OmniRoute with?"
+      placeholder: "e.g. Claude Code, Cursor, Roo Code, OpenClaw, Gemini CLI, cURL"
+    validations:
+      required: false
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: "A clear description of what the bug is."
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: "Step-by-step instructions to reproduce the behavior."
+      placeholder: |
+        1. Go to '...'
+        2. Click on '...'
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: "What did you expect to happen?"
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: "What actually happened?"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: test-impact
+    attributes:
+      label: Test Impact
+      description: "What automated test coverage should exist for this bug?"
+      options:
+        - Needs a new unit test
+        - Needs a new integration test
+        - Needs a new e2e test
+        - Existing automated test already fails
+        - Unsure
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error Logs / Output
+      description: "Paste any relevant error messages, logs, or terminal output. This will be automatically formatted as code."
+      render: shell
+    validations:
+      required: false
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots
+      description: "If applicable, add screenshots to help explain the problem. Please also include the text of any error messages above — screenshots alone are not searchable."
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: "Any other context about the problem (e.g. proxy config, number of accounts, network setup)."
+    validations:
+      required: false
+
+  - type: textarea
+    id: validation-plan
+    attributes:
+      label: Validation Plan
+      description: "Which commands or tests should prove this bug is fixed?"
+      placeholder: |
+        Example:
+        - node --import tsx --test tests/unit/my-file.test.ts
+        - npm run test:coverage
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question / Help
+    url: https://github.com/diegosouzapw/OmniRoute/discussions
+    about: For questions or help with setup, please use GitHub Discussions instead of opening an issue.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,96 @@
+name: Feature Request
+description: Suggest a new feature or improvement for OmniRoute
+title: "[Feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please describe the problem you're trying to solve and how you'd like it to work.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Use Case
+      description: "What problem does this feature solve? Why do you need it?"
+      placeholder: "I'm trying to ... but currently ..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: "How would you like this to work?"
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: "Have you considered any workarounds or alternative approaches?"
+    validations:
+      required: false
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance Criteria
+      description: "Describe the concrete behaviors or outcomes that should be validated before this is considered done."
+      placeholder: |
+        Example:
+        - API route returns 200 with valid payload
+        - Unit coverage added for the new branch
+        - Existing integrations remain green
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: "Which part of OmniRoute does this relate to?"
+      multiple: true
+      options:
+        - Dashboard / UI
+        - Proxy / Routing
+        - Provider Support
+        - CLI Tools Integration
+        - OAuth / Authentication
+        - Analytics / Usage Tracking
+        - Docker / Deployment
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: provider
+    attributes:
+      label: Related Provider(s)
+      description: "If this relates to specific providers, list them."
+      placeholder: "e.g. Antigravity, OpenRouter, Ollama"
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: "Any other context, mockups, or references."
+    validations:
+      required: false
+
+  - type: textarea
+    id: test-plan
+    attributes:
+      label: Expected Test Plan
+      description: "Which automated tests or coverage changes should accompany this work?"
+      placeholder: |
+        Example:
+        - Add unit tests for open-sse/services/combo.ts
+        - Extend integration coverage for /api/v1/models
+        - Keep npm run test:coverage at 60%+
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/test_coverage_task.yml

@@ -0,0 +1,73 @@
+name: Test Coverage Task
+description: Create a focused coverage-improvement issue tied to concrete files and targets
+title: "[Coverage] "
+labels: ["test", "coverage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template for scoped coverage work. Keep it tied to specific files, measurable targets, and the gate that must stay green.
+
+  - type: input
+    id: baseline
+    attributes:
+      label: Current Coverage Baseline
+      description: "Paste the current overall or file-level coverage number that justifies this task."
+      placeholder: "e.g. Lines 79.00%, Branches 72.85%, open-sse/handlers/chatCore.ts = 67.22%"
+    validations:
+      required: true
+
+  - type: textarea
+    id: scope
+    attributes:
+      label: Target Files Or Modules
+      description: "List the concrete source files or directories that this task will cover."
+      placeholder: |
+        Example:
+        - open-sse/handlers/chatCore.ts
+        - open-sse/services/combo.ts
+        - tests/integration/chat-pipeline.test.ts
+    validations:
+      required: true
+
+  - type: textarea
+    id: scenarios
+    attributes:
+      label: Missing Scenarios
+      description: "Describe the specific behaviors, branches, or failure paths that are currently uncovered."
+      placeholder: |
+        Example:
+        - Upstream timeout path
+        - Empty tool_calls normalization
+        - Fallback route after first provider failure
+    validations:
+      required: true
+
+  - type: input
+    id: target
+    attributes:
+      label: Coverage Target
+      description: "Set the expected target for this task."
+      placeholder: "e.g. Raise open-sse/handlers to 80%+ lines and keep global gate >= 60%"
+    validations:
+      required: true
+
+  - type: textarea
+    id: validation
+    attributes:
+      label: Validation Commands
+      description: "List the commands that must pass before this issue can be closed."
+      placeholder: |
+        Example:
+        - node --import tsx --test tests/unit/my-suite.test.ts
+        - npm run test:coverage
+    validations:
+      required: true
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: "Optional context, blockers, or dependencies."
+    validations:
+      required: false

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

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

.github/copilot-instructions.md

@@ -0,0 +1,15 @@
+# OmniRoute PR and Coverage Instructions
+
+- Treat `npm run test:coverage` as a required gate for PR work.
+- The repository minimum is `60%` for statements, lines, functions, and branches.
+- If a PR changes production code in `src/`, `open-sse/`, `electron/`, or `bin/`, it must include automated tests in the same PR.
+- When reviewing or updating a PR, if the report shows missing tests or coverage below `60%`, do not stop after reporting the problem. Add or update tests in the PR first, rerun the coverage gate, and only then ask for confirmation.
+- Prefer the smallest test layer that proves the behavior:
+  - unit tests first
+  - integration tests when multiple modules or DB state are involved
+  - e2e only when the behavior is truly UI or workflow-dependent
+- For bug issues, try to encode the reproduction as an automated test before or alongside the fix.
+- In the final PR report, include:
+  - the commands you ran
+  - the changed test files
+  - the final coverage result

.github/dependabot.yml

@@ -24,8 +24,47 @@ updates:
         update-types: ["version-update:semver-major"]
       - dependency-name: "eslint-config-next"
         update-types: ["version-update:semver-major"]
+      # typescript majors are peer-blocked by typescript-eslint, which pins a hard
+      # upper bound (8.64.0 → peerDependencies.typescript ">=4.8.4 <6.1.0"). A TS 7
+      # bump therefore violates the peer and takes down the whole toolchain at once —
+      # #7068 grouped it with 6 harmless bumps and turned Build + Lint + Quality Ratchet
+      # + Unit (6/8, 8/8) + Integration (1/2, 2/2) + dast-smoke red in one shot, blocking
+      # the innocuous updates riding along with it. Un-ignore once typescript-eslint
+      # widens the peer, and migrate TS majors intentionally (own PR, own CI run).
+      - dependency-name: "typescript"
+        update-types: ["version-update:semver-major"]
+      # jscpd v5 is a Rust rewrite (native binary, no Node.js programmatic API).
+      # scripts/check/check-duplication.mjs is deliberately pinned to jscpd@4 (it
+      # parses jscpd-report.json against a frozen baseline). A v5 major would break
+      # the duplication gate — migrate the gate intentionally, not via dependabot.
+      - dependency-name: "jscpd"
+        update-types: ["version-update:semver-major"]
+      # @huggingface/transformers is HARD-PINNED at 3.5.2 (exact, no caret) — FROZEN.
+      # It is load-bearing for the LLMLingua ONNX compression engine (open-sse/services/
+      # compression/engines/llmlingua/ — worker.ts pins @huggingface/transformers@3.5.2)
+      # and for local memory embeddings (src/lib/memory/embedding/transformersLocal.ts),
+      # and was VPS-validated at 3.5.2 (#4014). 4.x breaks both, and even 3.x minors must
+      # be re-validated on the VPS — so freeze ALL auto-bumps (no update-types = ignore
+      # every version). Migrate it intentionally, not via dependabot (#4050).
+      - dependency-name: "@huggingface/transformers"
 
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
       interval: "weekly"
+
+  - package-ecosystem: "npm"
+    directory: "/electron"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "deps"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "deps"

.github/pull_request_template.md

@@ -0,0 +1,30 @@
+## Summary
+
+- Describe the user-facing or operational change.
+
+## Related Issues
+
+- Closes #
+- Related to #
+
+## Validation
+
+- [ ] `npm run lint`
+- [ ] `npm run test:unit`
+- [ ] `npm run test:coverage`
+- [ ] Coverage is still `>= 60%` for statements, lines, functions, and branches
+- [ ] SonarQube PR analysis is green or any remaining issues are explicitly documented below
+
+## Tests Added Or Updated
+
+- List every changed or added automated test file.
+- If no production code changed, state that here.
+
+## Coverage Notes
+
+- If this PR changes `src/`, `open-sse/`, `electron/`, or `bin/`, explain which tests cover the change.
+- If coverage moved down in any touched file, explain why and what follow-up task will recover it.
+
+## Reviewer Notes
+
+- Call out any risky areas, migrations, feature flags, or manual validation that reviewers should know about.

.github/workflows/build-fork.yml

@@ -0,0 +1,71 @@
+name: Publish Fork Image to GHCR
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+# Least-privilege default: read-only at the top level; the build job that pushes to
+# GHCR grants packages: write itself (Scorecard TokenPermissions).
+permissions:
+  contents: read
+
+env:
+  IMAGE_NAME: ghcr.io/kang-heewon/omniroute
+
+jobs:
+  build:
+    name: Build and Push Fork Image
+    if: github.repository == 'kang-heewon/OmniRoute'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha,prefix=sha-
+            type=ref,event=tag
+          labels: |
+            org.opencontainers.image.title=omniroute
+            org.opencontainers.image.description=Unified AI proxy/router — fork image
+            org.opencontainers.image.url=https://github.com/kang-heewon/OmniRoute
+            org.opencontainers.image.source=https://github.com/kang-heewon/OmniRoute
+            org.opencontainers.image.licenses=MIT
+
+      - name: Build and push
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          target: runner-base
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/claude.yml

@@ -0,0 +1,54 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+# Least-privilege default: no token permissions at the top level; the `claude` job
+# grants exactly what it needs below (Scorecard TokenPermissions).
+permissions: {}
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr *)'

.github/workflows/codeql.yml

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

.github/workflows/dast-smoke.yml

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

.github/workflows/deploy-vps.yml

@@ -6,6 +6,9 @@ on:
     types: [completed]
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   deploy:
     if: >-
@@ -14,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

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

.github/workflows/electron-release.yml

@@ -11,41 +11,56 @@ on:
         required: true
         type: string
 
+# Least-privilege default: read-only at the top level; each job grants the writes it
+# needs (build/release upload assets, publish-npm forwards npm provenance / packages
+# to the reusable workflow) — Scorecard TokenPermissions.
 permissions:
-  contents: write
+  contents: read
 
 jobs:
   validate:
     name: Validate version
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     outputs:
       version: ${{ steps.validate.outputs.version }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
+          persist-credentials: false
           fetch-depth: 0
 
       - name: Validate version format
         id: validate
+        env:
+          # Pass workflow context via env (never interpolate ${{ ... }} straight
+          # into the run: script body) so the shell receives variables, not
+          # inlined text — zizmor template-injection mitigation. INPUT_VERSION is
+          # the operator-supplied value and is regex-validated below before use.
+          EVENT_NAME: ${{ github.event_name }}
+          INPUT_VERSION: ${{ inputs.version }}
         run: |
-          if [[ "${{ github.event_name }}" == "push" ]]; then
+          if [[ "$EVENT_NAME" == "push" ]]; then
             VERSION="${GITHUB_REF#refs/tags/}"
           else
-            VERSION="${{ inputs.version }}"
+            VERSION="$INPUT_VERSION"
           fi
 
           if [[ ! "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
             echo "Error: Invalid version format. Expected: v1.6.8"
             exit 1
           fi
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
           echo "✓ Valid version: $VERSION"
 
   build:
     name: Build Electron (${{ matrix.platform }})
     needs: validate
     runs-on: ${{ matrix.runner }}
+    permissions:
+      contents: write # electron-builder may publish artifacts with GH_TOKEN
     strategy:
       fail-fast: false
       matrix:
@@ -69,17 +84,17 @@ jobs:
             deb_ext: .deb
 
     steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-
-      - name: Setup Node.js
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - name: Setup Node
         uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
 
       - name: Cache node_modules
-        uses: actions/cache@v5
+        uses: actions/cache@v6.1.0
         with:
           path: node_modules
           key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
@@ -88,16 +103,34 @@ jobs:
 
       - name: Install dependencies
         run: npm ci
+        env:
+          NPM_CONFIG_LEGACY_PEER_DEPS: true
+
+      - name: Sanitize Windows home directory
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          # The default USERPROFILE contains junction points (Application Data)
+          # that cause EPERM errors during Next.js standalone build glob scans.
+          # Create a clean temp profile directory to avoid this.
+          mkdir -p "$RUNNER_TEMP/home"
+          echo "USERPROFILE=$RUNNER_TEMP/home" >> "$GITHUB_ENV"
 
       - name: Build Next.js standalone
         env:
           JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
+          NODE_OPTIONS: "--max_old_space_size=6144"
         run: npm run build
 
       - name: Sync version in electron/package.json
         shell: bash
+        env:
+          # Pass the validated version via env (never interpolate ${{ ... }}
+          # straight into the run: script body) — zizmor template-injection
+          # mitigation. Already regex-validated (^v[0-9]+\.[0-9]+\.[0-9]+$) in
+          # the `validate` job, so it cannot carry shell metacharacters.
+          VERSION: ${{ needs.validate.outputs.version }}
         run: |
-          VERSION="${{ needs.validate.outputs.version }}"
           VERSION_NO_V="${VERSION#v}"
           node -e "
             const fs = require('fs');
@@ -107,6 +140,10 @@ jobs:
           "
           echo "✓ electron/package.json version set to $VERSION_NO_V"
 
+      - name: Install fpm (Linux .deb packaging tool)
+        if: matrix.platform == 'linux'
+        run: sudo gem install fpm --no-document
+
       - name: Install Electron dependencies
         working-directory: electron
         run: npm install --no-audit --no-fund
@@ -117,6 +154,30 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: npm run build:${{ matrix.target }}
 
+      - name: Smoke packaged Electron app
+        if: matrix.platform != 'linux'
+        # 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"
+        run: npm run electron:smoke:packaged
+
+      - name: Smoke packaged Electron app (Linux)
+        if: matrix.platform == 'linux'
+        env:
+          ELECTRON_SMOKE_TIMEOUT_MS: 60000
+          ELECTRON_SMOKE_STREAM_LOGS: "1"
+        run: xvfb-run -a npm run electron:smoke:packaged
+
       - name: Collect installers
         shell: bash
         run: |
@@ -140,6 +201,12 @@ jobs:
               [ -f "$file" ] && cp "$file" "../../release-assets/OmniRoute.exe" && break
             done
           fi
+          # electron-updater manifests (latest.yml / latest-mac.yml / latest-linux.yml)
+          # must be published alongside the installers, or autoUpdater fails with
+          # "Cannot find latest.yml in the latest release artifacts" (#6766).
+          for file in latest*.yml; do
+            [ -f "$file" ] && cp "$file" ../../release-assets/
+          done
 
       - name: Upload artifacts
         uses: actions/upload-artifact@v7
@@ -151,10 +218,13 @@ jobs:
     name: Create Release
     needs: [validate, build]
     runs-on: ubuntu-latest
+    permissions:
+      contents: write # softprops/action-gh-release creates the GitHub Release
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
+          persist-credentials: false
           fetch-depth: 0
 
       - name: Download all artifacts
@@ -164,14 +234,20 @@ jobs:
           merge-multiple: true
 
       - name: Create source archives
+        env:
+          # Pass the validated version via env (never interpolate ${{ ... }}
+          # straight into the run: script body) — zizmor template-injection
+          # mitigation. Already regex-validated (^v[0-9]+\.[0-9]+\.[0-9]+$) in
+          # the `validate` job, so it cannot carry shell metacharacters.
+          VERSION: ${{ needs.validate.outputs.version }}
         run: |
           # Create source code archives (excluding dev dependencies and build artifacts)
-          export TARBALL="OmniRoute-${{ needs.validate.outputs.version }}.source.tar.gz"
-          export ZIPBALL="OmniRoute-${{ needs.validate.outputs.version }}.source.zip"
+          export TARBALL="OmniRoute-${VERSION}.source.tar.gz"
+          export ZIPBALL="OmniRoute-${VERSION}.source.zip"
 
           # Use git archive for clean source export
-          git archive --format=tar.gz --prefix=OmniRoute-${{ needs.validate.outputs.version }}/ HEAD -o "release-assets/$TARBALL"
-          git archive --format=zip --prefix=OmniRoute-${{ needs.validate.outputs.version }}/ HEAD -o "release-assets/$ZIPBALL"
+          git archive --format=tar.gz --prefix="OmniRoute-${VERSION}/" HEAD -o "release-assets/$TARBALL"
+          git archive --format=zip --prefix="OmniRoute-${VERSION}/" HEAD -o "release-assets/$ZIPBALL"
 
           echo "✓ Created source archives:"
           ls -lh "release-assets/$TARBALL" "release-assets/$ZIPBALL"
@@ -180,7 +256,7 @@ jobs:
         run: ls -la release-assets/
 
       - name: Create Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ needs.validate.outputs.version }}
           draft: false
@@ -193,7 +269,26 @@ jobs:
             release-assets/*.AppImage
             release-assets/*.deb
             release-assets/*.blockmap
+            release-assets/*.yml
             release-assets/*.source.tar.gz
             release-assets/*.source.zip
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-npm:
+    name: Publish to npm
+    needs: [validate, release]
+    permissions:
+      # Must be `write`, not `read`: this job calls the reusable npm-publish.yml whose
+      # `publish` job needs `contents: write` (gh release upload — attach the SBOM, #3874).
+      # A reusable workflow's job cannot request more permission than the caller grants,
+      # so a `read` here makes GitHub reject the run at startup (startup_failure).
+      contents: write
+      id-token: write # npm provenance (forwarded to the reusable workflow)
+      packages: write # publish to npm.pkg.github.com
+    uses: ./.github/workflows/npm-publish.yml
+    with:
+      version: ${{ needs.validate.outputs.version }}
+      tag: latest
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

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

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

.github/workflows/mutation-redundancy.yml

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

.github/workflows/nightly-compat.yml

@@ -0,0 +1,126 @@
+name: Nightly Node Compat
+
+# Plano mestre testes+CI (Eixo D2, aprovado 2026-07-04): as matrizes de compatibilidade
+# Node 24/26 custavam ~28% de CADA run do CI pesado (2 execuções completas da suíte por
+# sync da release-PR) para pegar uma classe de quebra que raramente nasce num PR típico.
+# Elas rodam aqui 1×/dia contra o tip da release ativa (mesmo alvo do nightly-release-green)
+# e continuam obrigatórias no gate de release via workflow_dispatch do ci.yml se preciso.
+# fail-fast desligado: numa quebra queremos saber TODAS as versões afetadas de uma vez.
+
+on:
+  schedule:
+    - cron: "47 6 * * *" # 06:47 UTC diário — slot distinto dos demais nightlies
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: "Branch to validate (default: highest release/vX.Y.Z)"
+        required: false
+        type: string
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: nightly-compat
+  cancel-in-progress: true
+
+jobs:
+  resolve-branch:
+    name: Resolve active release branch
+    runs-on: ubuntu-latest
+    outputs:
+      target: ${{ steps.branch.outputs.target }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Resolve active release branch
+        id: branch
+        env:
+          INPUT_BRANCH: ${{ github.event.inputs.branch }}
+        run: |
+          set -euo pipefail
+          if [ -n "${INPUT_BRANCH:-}" ]; then
+            TARGET="$INPUT_BRANCH"
+          else
+            TARGET=$(git for-each-ref --format='%(refname:short)' 'refs/remotes/origin/release/v*' \
+              | sed 's#origin/##' \
+              | sort -t/ -k2 -V \
+              | tail -1)
+          fi
+          case "$TARGET" in
+            release/v[0-9]*.[0-9]*.[0-9]*) ;;
+            *) echo "Refusing non-canonical branch name: $TARGET"; exit 1 ;;
+          esac
+          echo "target=$TARGET" >> "$GITHUB_OUTPUT"
+
+  compat-build-26:
+    name: Node 26 Compatibility Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    needs: resolve-branch
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ needs.resolve-branch.outputs.target }}
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "26"
+          cache: npm
+      - uses: ./.github/actions/npm-ci-retry
+      - run: npm run build
+
+  compat-tests:
+    name: Node ${{ matrix.node }} Compat Tests (${{ matrix.shard }}/4)
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    needs: resolve-branch
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [24, 26]
+        shard: [1, 2, 3, 4]
+    env:
+      JWT_SECRET: ci-nightly-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-nightly-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+      TEST_SHARD: ${{ matrix.shard }}/4
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ needs.resolve-branch.outputs.target }}
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - uses: ./.github/actions/npm-ci-retry
+      - run: npm run check:node-runtime
+      - run: npm run test:unit:ci:shard
+
+  report:
+    name: Open / update tracking issue on failure
+    runs-on: ubuntu-latest
+    if: ${{ !cancelled() && (needs.compat-tests.result == 'failure' || needs.compat-build-26.result == 'failure') }}
+    needs: [resolve-branch, compat-build-26, compat-tests]
+    permissions:
+      issues: write
+    steps:
+      - name: Open or update issue
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TARGET: ${{ needs.resolve-branch.outputs.target }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          TITLE="🌙 nightly-compat: Node 24/26 failures on $TARGET"
+          EXISTING=$(gh issue list --repo "$GITHUB_REPOSITORY" --state open --search "$TITLE in:title" --json number --jq '.[0].number')
+          BODY="Nightly Node-compat run failed on \`$TARGET\`: $RUN_URL — triage which Node version/shard broke (fail-fast off, all versions reported)."
+          if [ -n "$EXISTING" ]; then
+            gh issue comment "$EXISTING" --repo "$GITHUB_REPOSITORY" --body "$BODY"
+          else
+            gh issue create --repo "$GITHUB_REPOSITORY" --title "$TITLE" --body "$BODY"
+          fi

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

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

.github/workflows/nightly-mutation.yml

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

.github/workflows/nightly-property.yml

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

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

@@ -0,0 +1,303 @@
+name: Release-Green (continuous)
+
+# Solution D — continuous, NON-BLOCKING drift signal for the active release branch.
+#
+# WHY: the full gate (ci.yml) only runs on the release PR (PR → main), so reds
+# accrue silently on release/** and explode — in layers — at release time. This
+# workflow reproduces the release-equivalent validation on the release branch and,
+# when there are HARD failures, opens/updates a single tracking issue.
+#
+# WS5.1 (v3.8.49 quality plan) — two modes:
+#   push to release/v* (code paths) → --quick (fast HARD gates, ~5-8min). Catches the
+#     captain's direct pushes (sync-back — the one ungated write path) AND the merged
+#     COMBINATION right after every PR merge, attributing the offending push range in
+#     the issue. Base-red MTTD drops from ≤24h to ≤~15min after the offending push.
+#   schedule (3×/day) → full --with-build --full-ci (the deep sweep incl. build+suites).
+#
+# It is NOT a required status check and never touches a contributor PR — it only
+# reports. Ratchet drift (eslint warnings / cognitive-complexity / file-size) is
+# expected mid-cycle and is reported but never raises the alarm on its own; only
+# real defects (typecheck / lint errors / unit / vitest / db-rules / public-creds /
+# package-artifact) flip the issue open.
+
+on:
+  push:
+    branches: ["release/v*", "main"]
+    paths:
+      - "src/**"
+      - "open-sse/**"
+      - "bin/**"
+      - "electron/**"
+      - "scripts/**"
+      - "tests/**"
+      - "config/**"
+      - "package.json"
+      - "package-lock.json"
+      - "tsconfig*.json"
+  schedule:
+    - cron: "23 5 * * *" # full sweep — off-peak, distinct from other nightlies
+    - cron: "23 12 * * *" # full sweep — midday (WS5.1: 3×/day instead of 1×)
+    - cron: "23 18 * * *" # full sweep — evening
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: "Release branch to validate (default: highest release/vX.Y.Z)"
+        required: false
+        type: string
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  # push storms during merge campaigns collapse to the newest commit per branch;
+  # scheduled full sweeps keep their own single lane.
+  group: release-green-${{ github.event_name }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  OMNIROUTE_SKIP_SYSTEM_TRUST: "1"
+
+jobs:
+  release-green:
+    name: Validate active release branch
+    # On a push, only run for release/* pushes — a push to main is handled by the
+    # main-green job below. Schedule/dispatch always run (they validate the highest release).
+    if: ${{ github.event_name != 'push' || startsWith(github.ref_name, 'release/') }}
+    # Dynamic runner: with USE_VPS_RUNNER=true (release window / on-demand pre-flight)
+    # this runs on the dedicated VPS runner — clean env (no operator OMNIROUTE_API_KEY,
+    # no local noauth CLIs => zero machine-specific false positives) and no contention.
+    # Nightly cron normally finds the var false (VM off) and falls back to hosted.
+    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && fromJSON('["self-hosted","omni-release"]')) || 'ubuntu-latest' }}
+    env:
+      JWT_SECRET: ci-nightly-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-nightly-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Resolve active release branch
+        id: branch
+        env:
+          INPUT_BRANCH: ${{ github.event.inputs.branch }}
+          EVENT_NAME: ${{ github.event_name }}
+          PUSHED_REF: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          if [ -n "${INPUT_BRANCH:-}" ]; then
+            TARGET="$INPUT_BRANCH"
+          elif [ "$EVENT_NAME" = "push" ]; then
+            # validate exactly what was pushed, not the highest branch
+            TARGET="$PUSHED_REF"
+          else
+            # highest release/vX.Y.Z by semver among remote branches
+            TARGET=$(git for-each-ref --format='%(refname:short)' 'refs/remotes/origin/release/v*' \
+              | sed 's#origin/##' \
+              | sort -t/ -k2 -V \
+              | tail -1)
+          fi
+          if [ -z "$TARGET" ]; then echo "No release/v* branch found"; exit 1; fi
+          # Strict format guard — reject anything that isn't release/vX.Y.Z (blocks
+          # ref/command injection via the workflow_dispatch input).
+          if ! printf '%s' "$TARGET" | grep -qE '^release/v[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "Refusing non-canonical branch name: $TARGET"; exit 1
+          fi
+          echo "target=$TARGET" >> "$GITHUB_OUTPUT"
+          echo "Active release branch: $TARGET"
+
+      - name: Checkout the release branch
+        env:
+          TARGET: ${{ steps.branch.outputs.target }}
+        run: |
+          set -euo pipefail
+          git checkout "$TARGET"
+          git log -1 --oneline
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+
+      - uses: ./.github/actions/npm-ci-retry
+
+      - name: Release-green validation (full)
+        id: validate
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+        run: |
+          set +e
+          # --hermetic: scrub live-test trigger vars (self-hosted runner may carry
+          # operator env; hosted ignores the unknown flag before #6300 lands).
+          # push → --quick: fast HARD gates only (~5-8min), per-merge signal.
+          # schedule/dispatch → --with-build --full-ci: ALSO run every static gate from
+          # ci.yml's gate jobs (lint, quality-gate, quality-extended, docs-sync-strict,
+          # pr-test-policy) + build + full suites. PRs into release/** only get the
+          # fast-gates, so these accrue silently and explode in layers on the release PR
+          # (v3.8.46: 11 static base-reds leaked).
+          if [ "$EVENT_NAME" = "push" ]; then
+            MODE="--quick"
+          else
+            MODE="--with-build --full-ci"
+          fi
+          echo "[release-green] mode: $MODE (event: $EVENT_NAME)"
+          # shellcheck disable=SC2086 — MODE is an intentional flag list
+          node scripts/quality/validate-release-green.mjs --json --hermetic $MODE \
+            1> release-green.json 2> release-green.log
+          echo "exit=$?" >> "$GITHUB_OUTPUT"
+          echo "------- report -------"
+          cat release-green.log
+
+      - name: Open / update tracking issue on HARD failure
+        if: steps.validate.outputs.exit != '0'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TARGET: ${{ steps.branch.outputs.target }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          EVENT_NAME: ${{ github.event_name }}
+          BEFORE_SHA: ${{ github.event.before }}
+          AFTER_SHA: ${{ github.event.after }}
+        run: |
+          set -euo pipefail
+          TITLE="🔴 Release branch not green: ${TARGET}"
+          {
+            echo "The **release-green** validation found HARD failures on \`${TARGET}\`."
+            echo "These are real defects that would block the release PR — fix them in the"
+            echo "originating PR branch (via co-authorship), not by demanding it from contributors."
+            echo ""
+            echo "**Run:** ${RUN_URL} (mode: ${EVENT_NAME})"
+            # WS5.1 attribution: on push events the offending change IS this push's range
+            # (one merge per push in the normal queue), so name it — no bisect needed.
+            if [ "$EVENT_NAME" = "push" ] && [ -n "${BEFORE_SHA:-}" ] && \
+               git cat-file -e "$BEFORE_SHA" 2>/dev/null; then
+              echo ""
+              echo "**Offending push range** (\`${BEFORE_SHA:0:9}..${AFTER_SHA:0:9}\`):"
+              echo '```'
+              git log --no-decorate --oneline "${BEFORE_SHA}..${AFTER_SHA}" | head -20
+              echo '```'
+            fi
+            echo ""
+            echo '```'
+            sed -n '/──────── verdict ────────/,$p' release-green.log || tail -40 release-green.log
+            echo '```'
+            echo ""
+            echo "_Ratchet drift (eslint warnings / cognitive-complexity / file-size) listed above is expected mid-cycle and is rebaselined at release — it is NOT a contributor concern and did not, on its own, open this issue._"
+          } > issue-body.md
+
+          EXISTING=$(gh issue list --repo "$GITHUB_REPOSITORY" --state open \
+            --search "in:title $TITLE" --json number --jq '.[0].number' 2>/dev/null || echo "")
+          if [ -n "$EXISTING" ]; then
+            gh issue comment "$EXISTING" --repo "$GITHUB_REPOSITORY" --body-file issue-body.md
+            echo "Updated existing issue #$EXISTING"
+          else
+            gh issue create --repo "$GITHUB_REPOSITORY" --title "$TITLE" --body-file issue-body.md
+          fi
+
+      - name: Upload report artifact
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: release-green-report
+          path: |
+            release-green.json
+            release-green.log
+          if-no-files-found: ignore
+
+  # Companion arm for `main`. Under the parallel-cycle model, main only receives merged
+  # work at the release squash — so a gate/infra fix that lands only on release leaves
+  # main red the whole cycle, and repo-wide gates (CodeQL alert count, ratchet baselines)
+  # turn EVERY PR into main red on a check unrelated to its diff. This detects that and
+  # opens a "🔴 main not green" tracking issue. The PREVENTION is the companion-PR reflex
+  # (Hard Rule #21 area / _shared/merge-gates.md §8); this is the automated backstop.
+  main-green:
+    name: Validate main branch
+    # On a push, only run for a push to main — a push to release/* is handled by
+    # release-green above. Schedule/dispatch always run (they also sweep main).
+    if: ${{ github.event_name != 'push' || github.ref_name == 'main' }}
+    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && fromJSON('["self-hosted","omni-release"]')) || 'ubuntu-latest' }}
+    env:
+      JWT_SECRET: ci-nightly-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-nightly-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: main # literal — no injection surface; scheduled runs default to the repo default branch (a release/v*), so pin main explicitly
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+
+      - uses: ./.github/actions/npm-ci-retry
+
+      - name: Main-green validation
+        id: validate
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+        run: |
+          set +e
+          # push (a merge into main) → --quick fast HARD gates; schedule/dispatch → full sweep.
+          if [ "$EVENT_NAME" = "push" ]; then
+            MODE="--quick"
+          else
+            MODE="--with-build --full-ci"
+          fi
+          echo "[main-green] mode: $MODE (event: $EVENT_NAME)"
+          # shellcheck disable=SC2086 — MODE is an intentional flag list
+          node scripts/quality/validate-release-green.mjs --json --hermetic $MODE \
+            1> main-green.json 2> main-green.log
+          echo "exit=$?" >> "$GITHUB_OUTPUT"
+          echo "------- report -------"
+          cat main-green.log
+
+      - name: Open / update tracking issue on HARD failure
+        if: steps.validate.outputs.exit != '0'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          EVENT_NAME: ${{ github.event_name }}
+        run: |
+          set -euo pipefail
+          TITLE="🔴 main branch not green"
+          {
+            echo "The **main-green** validation found HARD failures on \`main\`."
+            echo ""
+            echo "Because \`main\` only receives merged work at the release squash, a gate/infra"
+            echo "fix that landed only on the release branch leaves \`main\` broken for the whole"
+            echo "cycle — and repo-wide gates (CodeQL alert count, ratchet baselines) then turn"
+            echo "**every open PR into main** red on a check unrelated to its diff. The fix is a"
+            echo "companion PR \`--base main\` carrying the release-side fix (see"
+            echo "\`_shared/merge-gates.md\` §8), NOT chasing each contributor PR."
+            echo ""
+            echo "**Run:** ${RUN_URL} (mode: ${EVENT_NAME})"
+            echo ""
+            echo '```'
+            sed -n '/──────── verdict ────────/,$p' main-green.log || tail -40 main-green.log
+            echo '```'
+            echo ""
+            echo "_Ratchet drift (eslint warnings / cognitive-complexity / file-size) is expected mid-cycle and did NOT, on its own, open this issue._"
+          } > issue-body.md
+
+          EXISTING=$(gh issue list --repo "$GITHUB_REPOSITORY" --state open \
+            --search "in:title $TITLE" --json number --jq '.[0].number' 2>/dev/null || echo "")
+          if [ -n "$EXISTING" ]; then
+            gh issue comment "$EXISTING" --repo "$GITHUB_REPOSITORY" --body-file issue-body.md
+            echo "Updated existing issue #$EXISTING"
+          else
+            gh issue create --repo "$GITHUB_REPOSITORY" --title "$TITLE" --body-file issue-body.md
+          fi
+
+      - name: Upload report artifact
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: main-green-report
+          path: |
+            main-green.json
+            main-green.log
+          if-no-files-found: ignore

.github/workflows/nightly-resilience.yml

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

.github/workflows/nightly-schemathesis.yml

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

.github/workflows/npm-publish.yml

@@ -1,44 +1,341 @@
 name: Publish to npm
 
 on:
+  # 'released' (not 'published') so editing/re-publishing old releases does NOT
+  # re-trigger this workflow. Pairs with the semver guard below as defense in
+  # depth against accidental dist-tag clobbering by old releases.
   release:
-    types: [published]
+    types: [released]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to publish (e.g. 2.9.5 or 3.0.0-rc.15)"
+        required: true
+        type: string
+      tag:
+        description: "npm dist-tag (auto / latest / next / historic)"
+        required: false
+        default: "auto"
+        type: choice
+        options:
+          - auto
+          - latest
+          - next
+          - historic
+      publish_mode:
+        description: "staged = npm stage publish (owner approves with 2FA after the staged boot-verify); direct = legacy immediate publish (emergency fallback only)"
+        required: false
+        default: "staged"
+        type: choice
+        options:
+          - staged
+          - direct
+  workflow_call:
+    inputs:
+      version:
+        description: "Version to publish (without v prefix)"
+        required: true
+        type: string
+      tag:
+        description: "npm dist-tag (auto / latest / next / historic)"
+        required: false
+        default: "auto"
+        type: string
+    secrets:
+      NPM_TOKEN:
+        required: true
 
+# Least-privilege default: read-only at the top level; each publish job grants the
+# id-token (npm provenance) / packages (GitHub Packages) writes it needs (Scorecard
+# TokenPermissions).
 permissions:
   contents: read
-  id-token: write
+
+env:
+  NPM_PUBLISH_NODE_VERSION: "24"
 
 jobs:
   publish:
     runs-on: ubuntu-latest
-    environment: NPM_TOKEN
+    permissions:
+      contents: write # gh release upload (attach SBOM to the GitHub Release)
+      id-token: write # npm provenance
+      packages: write # publish to npm.pkg.github.com
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          # Need full tag history to compare against highest semver when
+          # deciding whether this release should claim dist-tag `latest`.
+          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: ${{ env.NPM_PUBLISH_NODE_VERSION }}
           registry-url: https://registry.npmjs.org
 
       - name: Install dependencies (skip scripts to avoid heavy build)
-        run: npm ci --ignore-scripts
+        run: npm install --ignore-scripts --no-audit --no-fund
 
-      - name: Sync version from release tag
+      - name: Resolve version, dist-tag and skip flag
+        id: resolve
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          REF_NAME: ${{ github.ref_name }}
+          INPUT_VERSION: ${{ inputs.version }}
+          INPUT_TAG: ${{ inputs.tag }}
         run: |
-          VERSION="${GITHUB_REF_NAME}"
-          # Remove 'v' prefix if present (v2.1.0 -> 2.1.0)
+          set -euo pipefail
+
+          # 1) Resolve VERSION from the trigger (all inputs come via env).
+          VERSION="${INPUT_VERSION:-}"
+          if [ -z "$VERSION" ] && [ "$EVENT_NAME" = "release" ]; then
+            VERSION="$REF_NAME"
+          fi
           VERSION="${VERSION#v}"
+          if ! printf '%s' "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+([.-][A-Za-z0-9.-]+)?$'; then
+            echo "Refusing to publish unsafe VERSION value: $VERSION" >&2
+            exit 1
+          fi
+
+          # 2) Resolve dist-tag.
+          #    - explicit 'latest'/'next'/'historic' is honored
+          #    - 'auto' (or empty): pre-release identifiers → 'next';
+          #      stable versions → 'latest' only if VERSION is the highest
+          #      stable semver among `v*` tags (otherwise → 'historic').
+          REQUESTED_TAG="${INPUT_TAG:-auto}"
+          TAG="$REQUESTED_TAG"
+          if [ "$TAG" = "auto" ] || [ -z "$TAG" ]; then
+            if printf '%s' "$VERSION" | grep -qE -- '-(rc|alpha|beta|pre|next)'; then
+              TAG="next"
+            else
+              git fetch --tags --quiet || true
+              HIGHEST=$(git tag -l 'v[0-9]*' | sed 's/^v//' | grep -vE -- '-(rc|alpha|beta|pre|next)' | sort -V | tail -1 || echo "")
+              if [ -n "$HIGHEST" ] && [ "$VERSION" = "$HIGHEST" ]; then
+                TAG="latest"
+              else
+                echo "Version $VERSION is not the highest semver tag (highest=${HIGHEST:-<none>}). Using dist-tag 'historic' to avoid clobbering @latest."
+                TAG="historic"
+              fi
+            fi
+          fi
+
+          # 3) Skip-if-already-published. NOTE: do NOT pass `--silent` to
+          #    `npm view` — it suppresses stdout and breaks the grep, which
+          #    caused old releases (3.2.8) to be re-published and steal
+          #    dist-tag `latest`. See incident notes in CHANGELOG.
+          PUBLISHED="$(npm view "omniroute@${VERSION}" version 2>/dev/null || true)"
+          SKIP="false"
+          if [ "$PUBLISHED" = "$VERSION" ]; then
+            echo "⚠️ omniroute@${VERSION} is already on npm — skipping publish."
+            SKIP="true"
+          fi
+
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=$TAG"          >> "$GITHUB_OUTPUT"
+          echo "skip=$SKIP"        >> "$GITHUB_OUTPUT"
+          echo "📦 Resolved omniroute@$VERSION dist-tag=$TAG skip=$SKIP"
+
+      - name: Sync package.json version
+        if: steps.resolve.outputs.skip != 'true'
+        env:
+          VERSION: ${{ steps.resolve.outputs.version }}
+        run: |
           npm version "$VERSION" --no-git-tag-version --allow-same-version
-          echo "Publishing version: $VERSION"
 
       - name: Build CLI bundle (standalone app)
+        if: steps.resolve.outputs.skip != 'true'
         env:
           JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
-        run: node scripts/prepublish.mjs
+        run: npm run build:cli
 
-      - name: Publish to npm
-        run: npm publish --access public
+      - name: Validate npm package artifact
+        if: steps.resolve.outputs.skip != 'true'
+        run: npm run check:pack-artifact
+
+      - name: Generate CycloneDX SBOM (npm)
+        if: steps.resolve.outputs.skip != 'true'
+        run: npx @cyclonedx/cyclonedx-npm --ignore-npm-errors --output-format JSON --output-file sbom-npm.cdx.json
+
+      - name: Upload SBOM (npm) as workflow artifact
+        if: steps.resolve.outputs.skip != 'true'
+        uses: actions/upload-artifact@v7
+        with:
+          name: sbom-npm
+          path: sbom-npm.cdx.json
+          if-no-files-found: error
+
+      - name: Attach SBOM to GitHub Release
+        if: steps.resolve.outputs.skip != 'true' && github.event_name == 'release'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.ref_name }}
+        run: gh release upload "$TAG" sbom-npm.cdx.json --clobber
+
+      # WS1.2/WS1.3 (#7065 class): the artifact that is about to be published must
+      # BOOT. build:cli already assembled dist/ above; this packs+installs+boots the
+      # real tarball and fails the publish before anything reaches the registry.
+      - name: Boot-smoke the tarball before ANY publish
+        if: steps.resolve.outputs.skip != 'true'
+        run: npm run check:pack-boot
+
+      # WS1.3 (D2, v3.8.49 plan): STAGED publishing by default — `npm stage publish`
+      # parks the exact bytes on the registry WITHOUT making them installable; the
+      # owner then verifies and approves with 2FA (`npm stage approve`), moving the
+      # human gate to AFTER the proof instead of before it. Requires npm >= 11.15
+      # (staged publishing GA 2026-05-22). publish_mode=direct is the emergency
+      # fallback (legacy immediate publish) via workflow_dispatch.
+      - name: Ensure npm supports staged publishing
+        if: steps.resolve.outputs.skip != 'true' && (github.event_name != 'workflow_dispatch' || inputs.publish_mode != 'direct')
+        run: |
+          set -euo pipefail
+          CUR=$(npm --version)
+          if ! node -e "const [a,b]='$(npm --version)'.split('.').map(Number); process.exit(a>11||(a===11&&b>=15)?0:1)"; then
+            # Pinned exact version (supply-chain: never float @latest in the publish
+            # job); bump deliberately when a newer npm is required.
+            echo "npm $CUR < 11.15 — installing pinned npm 11.15.0 for staged publishing"
+            npm install -g --ignore-scripts npm@11.15.0
+          fi
+          npm --version
+
+      - name: Publish to npm (staged — owner approves with 2FA)
+        if: steps.resolve.outputs.skip != 'true' && (github.event_name != 'workflow_dispatch' || inputs.publish_mode != 'direct')
+        env:
+          VERSION: ${{ steps.resolve.outputs.version }}
+          TAG: ${{ steps.resolve.outputs.tag }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          set -euo pipefail
+          # Always pass --tag explicitly. Defense in depth: even if VERSION is
+          # accidentally an older release, the historic tag will NOT claim `@latest`.
+          npm stage publish --provenance --access public --tag "$TAG"
+          {
+            echo "## 📦 omniroute@$VERSION STAGED (not yet installable)"
+            echo ""
+            echo "The exact bytes are parked on the registry. To release them:"
+            echo '```'
+            echo "npm stage list omniroute            # find the stage id"
+            echo "npm stage approve <id>              # owner 2FA — THE publish"
+            echo '```'
+            echo "To verify the staged bytes first: npm stage download <id> → run"
+            echo "scripts/check/check-pack-boot.mjs against them (see RELEASE_CHECKLIST)."
+            echo "To discard: npm stage reject <id>."
+          } >> "$GITHUB_STEP_SUMMARY"
+          echo "✅ Staged omniroute@$VERSION (dist-tag=$TAG) — awaiting owner 'npm stage approve'"
+
+      - name: Publish to npm (DIRECT — emergency fallback)
+        if: steps.resolve.outputs.skip != 'true' && github.event_name == 'workflow_dispatch' && inputs.publish_mode == 'direct'
+        env:
+          VERSION: ${{ steps.resolve.outputs.version }}
+          TAG: ${{ steps.resolve.outputs.tag }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          set -euo pipefail
+          npm publish --provenance --access public --tag "$TAG"
+          echo "✅ Published omniroute@$VERSION (dist-tag=$TAG) [DIRECT mode]"
+
+      - name: Publish to GitHub Packages
+        if: steps.resolve.outputs.skip != 'true'
+        env:
+          VERSION: ${{ steps.resolve.outputs.version }}
+          TAG: ${{ steps.resolve.outputs.tag }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          echo "Configuring for GitHub Packages..."
+          echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" > .npmrc
+          npm pkg set name="@diegosouzapw/omniroute"
+          npm publish --registry=https://npm.pkg.github.com --tag "$TAG" \
+            || echo "⚠️ omniroute@${VERSION} might already be published on GitHub Packages."
+          echo "✅ Action finished for GitHub Packages"
+
+  publish-opencode-plugin:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # npm provenance
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+          # Full history needed for auto-bump: git diff against previous release tag
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NPM_PUBLISH_NODE_VERSION }}
+          registry-url: https://registry.npmjs.org
+
+      - name: Auto-bump plugin version if plugin changed since last release
+        id: bump
+        working-directory: "@omniroute/opencode-plugin"
+        env:
+          CURRENT_TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          PKG_NAME=$(node -p "require('./package.json').name")
+
+          # 1) Skip if current version is not yet published (no bump needed)
+          PUBLISHED="$(npm view "${PKG_NAME}@${PKG_VERSION}" version 2>/dev/null || true)"
+          if [ "$PUBLISHED" != "$PKG_VERSION" ]; then
+            echo "✅ ${PKG_NAME}@${PKG_VERSION} is new — no bump needed."
+            echo "bumped=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # 2) Find the previous release tag (exclude the current one)
+          PREV_TAG=$(git tag -l 'v*' --sort=-version:refname \
+            | grep -v "^${CURRENT_TAG}$" | head -1 || echo "")
+          if [ -z "$PREV_TAG" ]; then
+            echo "No previous tag to compare — skipping bump."
+            echo "bumped=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # 3) Check if plugin dir actually changed since that tag
+          if git diff --quiet "$PREV_TAG" -- "@omniroute/opencode-plugin/"; then
+            echo "⏭️ No plugin changes since $PREV_TAG — nothing to publish."
+            echo "bumped=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # 4) Auto-bump patch version
+          npm version patch --no-git-tag-version --allow-same-version
+          NEW_VERSION=$(node -p "require('./package.json').version")
+          echo "bumped=true" >> "$GITHUB_OUTPUT"
+          echo "📦 Auto-bumped ${PKG_NAME} from ${PKG_VERSION} to ${NEW_VERSION}"
+
+      - name: Install plugin dependencies
+        working-directory: "@omniroute/opencode-plugin"
+        run: npm install --no-audit --no-fund
+
+      - name: Build plugin
+        working-directory: "@omniroute/opencode-plugin"
+        run: npm run clean && npm run build
+
+      - name: Test plugin
+        working-directory: "@omniroute/opencode-plugin"
+        run: npm test
+
+      - name: Publish @omniroute/opencode-plugin to npm
+        working-directory: "@omniroute/opencode-plugin"
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          set -euo pipefail
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          PKG_NAME=$(node -p "require('./package.json').name")
+          # Same hardened skip-check as the main job (no --silent flag).
+          PUBLISHED="$(npm view "${PKG_NAME}@${PKG_VERSION}" version 2>/dev/null || true)"
+          if [ "$PUBLISHED" = "$PKG_VERSION" ]; then
+            echo "⚠️ ${PKG_NAME}@${PKG_VERSION} is already published on npm — skipping."
+            exit 0
+          fi
+          npm publish --provenance --access public --ignore-scripts
+          echo "✅ Published ${PKG_NAME}@${PKG_VERSION}"

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

@@ -0,0 +1,66 @@
+name: opencode-plugin CI
+
+on:
+  push:
+    branches: [main, release/v3.8.2]
+    paths:
+      - "@omniroute/opencode-plugin/**"
+  pull_request:
+    branches: [main, release/v3.8.2]
+    paths:
+      - "@omniroute/opencode-plugin/**"
+    types: [opened, synchronize, reopened, ready_for_review]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    working-directory: "@omniroute/opencode-plugin"
+
+jobs:
+  test:
+    name: Test (Node ${{ matrix.node }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: ["22", "24"]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+          cache-dependency-path: "@omniroute/opencode-plugin/package-lock.json"
+      - run: npm install --no-audit --no-fund
+      - run: npm run build
+      - run: npm test
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: "@omniroute/opencode-plugin/package-lock.json"
+      - run: npm install --no-audit --no-fund
+      - run: npm run build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: opencode-plugin-dist
+          path: "@omniroute/opencode-plugin/dist"
+          retention-days: 7

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

@@ -0,0 +1,65 @@
+name: opencode-provider CI
+
+on:
+  push:
+    branches: [main, release/v3.8.0]
+    paths:
+      - "@omniroute/opencode-provider/**"
+  pull_request:
+    branches: [main, release/v3.8.0]
+    paths:
+      - "@omniroute/opencode-provider/**"
+    types: [opened, synchronize, reopened, ready_for_review]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    working-directory: "@omniroute/opencode-provider"
+
+jobs:
+  test:
+    name: Test (Node ${{ matrix.node }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: ["20", "22", "24"]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+          cache-dependency-path: "@omniroute/opencode-provider/package-lock.json"
+      - run: npm ci
+      - run: npm test
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: "@omniroute/opencode-provider/package-lock.json"
+      - run: npm ci
+      - run: npm run build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: opencode-provider-dist
+          path: "@omniroute/opencode-provider/dist"
+          retention-days: 7

.github/workflows/quality.yml

@@ -0,0 +1,354 @@
+name: Quality Gates
+
+on:
+  pull_request:
+    branches: ["release/**"]
+    types: [opened, synchronize, reopened, ready_for_review]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  # CI must never mutate the runner's OS trust store (2026-07-05: a cert-flow
+  # test installed a fake PEM on a persistent self-hosted runner and broke all
+  # system TLS). Belt-and-suspenders with tests/_setup/isolateDataDir.ts.
+  OMNIROUTE_SKIP_SYSTEM_TRUST: "1"
+  CI_NODE_VERSION: "24"
+
+jobs:
+  # Same classifier as ci.yml (scripts/quality/classify-pr-changes.mjs) so PR→release
+  # path filters share existence reasons: code / docs / i18n / workflow.
+  changes:
+    name: Change Classification
+    runs-on: ubuntu-latest
+    outputs:
+      code: ${{ steps.classify.outputs.code }}
+      docs: ${{ steps.classify.outputs.docs }}
+      i18n: ${{ steps.classify.outputs.i18n }}
+      workflow: ${{ steps.classify.outputs.workflow }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+      - id: classify
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          if [ "$EVENT_NAME" != "pull_request" ]; then
+            {
+              echo "code=true"
+              echo "docs=true"
+              echo "i18n=true"
+              echo "workflow=true"
+            } >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          git diff --name-only "$BASE_SHA" "$HEAD_SHA" > changed-files.txt
+          node scripts/quality/classify-pr-changes.mjs changed-files.txt >> "$GITHUB_OUTPUT"
+
+  # Docs/OpenAPI contract gates only — existence reason is doc accuracy + route refs.
+  # Split out of fast-gates so pure-docs PRs skip typecheck/unit while still validating docs.
+  docs-gates:
+    name: Docs Gates (fast-path)
+    needs: changes
+    if: ${{ github.event_name != 'pull_request' || ((github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) && (needs.changes.outputs.docs == 'true' || needs.changes.outputs.code == 'true')) }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      # One walk of src/app/api for openapi-routes + docs-symbols (both still fail independently).
+      - run: npm run check:api-docs-refs
+      - name: Docs accuracy (fabricated-docs + i18n mirrors, strict)
+        run: npm run check:docs-all
+
+  fast-gates:
+    name: Fast Quality Gates
+    needs: changes
+    # Code surface only — pure docs/i18n PRs skip this bag (docs-gates covers docs).
+    if: ${{ github.event_name != 'pull_request' || ((github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) && needs.changes.outputs.code == 'true') }}
+    # Dynamic runner (same rule as ci.yml): use the self-hosted VPS pool only when the
+    # release captain has USE_VPS_RUNNER=true AND this is not a fork PR (own-origin
+    # branches only — a fork PR must never execute on the LAN runner). Var unset/false
+    # or a fork PR falls back to ubuntu-latest, so this is inert until the flag flips.
+    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)) && fromJSON('["self-hosted","omni-release"]') || 'ubuntu-latest' }}
+    # tsx gates (known-symbols, route-guard-membership) import modules that open
+    # SQLite on load; provide DB env so a fresh CI DB initializes cleanly.
+    env:
+      JWT_SECRET: ci-lint-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-lint-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      - name: Restore ESLint file cache
+        uses: actions/cache@v6
+        with:
+          path: |
+            .eslintcache
+            .eslintcache-complexity
+          key: eslint-${{ runner.os }}-${{ hashFiles('eslint.config.mjs', 'eslint.complexity-ratchets.config.mjs', 'config/quality/eslint-suppressions.json', 'package-lock.json') }}
+          restore-keys: |
+            eslint-${{ runner.os }}-
+      - run: npm run check:provider-consistency
+      - run: npm run check:fetch-targets
+      # docs-all / openapi-routes / docs-symbols live in docs-gates (path-filtered).
+      - run: npm run check:deps
+      - run: npm run check:file-size
+      - run: npm run check:error-helper
+      - run: npm run check:migration-numbering
+      - run: npm run check:public-creds
+      - run: npm run check:db-rules
+      - run: npm run check:known-symbols
+      - run: npm run check:route-guard-membership
+      - run: npm run check:test-discovery
+      - run: npm run check:test-runner-api
+      # Guards tap.testFiles drift: a covering unit test absent from stryker.conf.json
+      # tap.testFiles makes its module's mutants survive on a cold nightly-mutation run,
+      # false-failing the blocking mutationScore ratchet. See check-mutation-test-coverage.mjs.
+      - run: npm run check:mutation-test-coverage
+      - run: npm run check:any-budget:t11
+      # Build-scope guard: fails if worktrees/cruft leak into the tsconfig include
+      # scope (would OOM `next build`). Instant. See incident 2026-06-25 / #5031.
+      - run: npm run check:build-scope
+      # Pack-policy (unexpected-files allowlist) WITHOUT a build — catches a stray file
+      # leaking into the npm tarball (v3.8.36: 6 ops bin/*.sh) per-PR instead of only on
+      # the release PR's heavy Package Artifact job.
+      - run: npm run check:pack-policy
+      # Complexity + cognitive-complexity: ONE ESLint walk (both baselines still
+      # enforced separately by ruleId). Avoids two cold tree walks on fast-path.
+      - run: npm run check:complexity-ratchets
+      - name: Typecheck (core)
+        run: npm run typecheck:core
+      # #7033: dashboard-scoped typecheck gate — src/app/(dashboard) TSX is not
+      # covered by typecheck:core's curated allowlist. See check-dashboard-typecheck.mjs.
+      - name: Typecheck (dashboard)
+        run: npm run check:dashboard-typecheck
+      # WS4.2 (v3.8.49 plan): TypeScript 7 native-compiler SHADOW — advisory only.
+      # TS7 went GA 2026-07-08 with 8-12x type-check speedups; its Compiler API only
+      # arrives in 7.1, so typescript-eslint / type-coverage / Stryker stay on 6.x
+      # (the hybrid is the officially documented pattern). Isolated npx on purpose:
+      # installing an alias package could collide node_modules/.bin/tsc with 6.x.
+      # Promote to the blocking gate after ~1 week of parity with the step above.
+      - name: Typecheck (core) — TS7 native shadow (advisory)
+        continue-on-error: true
+        run: |
+          RC=0
+          START=$(date +%s)
+          npx -y -p typescript@7 tsc --pretty false -p tsconfig.typecheck-core.json || RC=$?
+          echo "[ts7-shadow] exit=$RC elapsed=$(( $(date +%s) - START ))s — the 6.x step above stays authoritative"
+          exit $RC
+      # TIA: build the impact map at runtime (gitignored, ~21MB) and run only the
+      # unit tests impacted by this PR's changed files. On hub/unmapped changes the
+      # selector returns __RUN_ALL__ — full-suite authority is the parallel
+      # `fast-unit` 4-shard job (test:unit:ci:shard; was 2-shard, #6781), NOT an
+      # unsharded re-run here. Stacking unsharded test:unit:ci on top of fast-unit
+      # doubled wall time (~16 min extra on ubuntu-latest) without extra coverage.
+      #
+      # BLOCKING for the *impacted subset* (flipped 2026-06-17). Fail-safe full
+      # coverage remains required via `Unit Tests fast-path` (fast-unit).
+      - name: Impacted unit tests (TIA subset; blocking)
+        env:
+          GITHUB_BASE_REF: ${{ github.base_ref }}
+        run: |
+          git fetch --no-tags origin "$GITHUB_BASE_REF" || true
+          node scripts/quality/build-test-impact-map.mjs
+          SEL="$(node scripts/quality/select-impacted-tests.mjs)"
+          if [ -z "$SEL" ]; then echo "No source/test changes — skipping unit tests"; exit 0; fi
+          # CI runners are 4-vCPU; run at --test-concurrency=4 (matching the ci.yml unit
+          # job) rather than test:unit's local-tuned concurrency=20. Oversubscribing the
+          # runner makes timing-sensitive tests (db-backup, upstream-timeout, ...) flake,
+          # which must not happen on a blocking gate. DATA_DIR isolation keeps the parallel
+          # run race-free regardless of concurrency.
+          if echo "$SEL" | grep -q "__RUN_ALL__"; then
+            echo "Fail-safe: __RUN_ALL__ — deferring FULL unit suite to fast-unit (4-shard)."
+            echo "Not re-running unsharded test:unit:ci here (duplicate of fast-unit coverage)."
+            exit 0
+          fi
+          echo "Running impacted tests:"; echo "$SEL"
+          mapfile -t FILES <<< "$SEL"
+          # Loader parity with test:unit:ci:shard (#6787): tests/unit/dashboard/** runs
+          # under `--import tsx` (CJS transform — required for ESM-only deep imports like
+          # @lobehub/icons/es/* reached via lobeProviderIcons.ts); everything else under
+          # `--import tsx/esm`. A single tsx/esm invocation false-reds every dashboard
+          # module-shape test the impact map selects ("Unexpected token 'export'").
+          DASH=(); REST=()
+          for f in "${FILES[@]}"; do
+            case "$f" in
+              tests/unit/dashboard/*) DASH+=("$f") ;;
+              *) REST+=("$f") ;;
+            esac
+          done
+          RC=0
+          if [ ${#REST[@]} -gt 0 ]; then
+            node --import tsx/esm --import ./open-sse/utils/setupPolyfill.ts --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 "${REST[@]}" || RC=$?
+          fi
+          if [ ${#DASH[@]} -gt 0 ]; then
+            node --import tsx --import ./open-sse/utils/setupPolyfill.ts --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 "${DASH[@]}" || RC=$?
+          fi
+          exit $RC
+
+  fast-vitest:
+    name: Vitest (fast-path)
+    needs: changes
+    if: ${{ github.event_name != 'pull_request' || ((github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) && needs.changes.outputs.code == 'true') }}
+    # Dynamic runner — see fast-gates (own-origin + flag; fork/unset → ubuntu-latest).
+    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)) && fromJSON('["self-hosted","omni-release"]') || 'ubuntu-latest' }}
+    env:
+      JWT_SECRET: ci-lint-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-lint-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      # WS5.2/5.3: JUnit feeds Trunk Flaky Tests — the fast-path runs on EVERY PR,
+      # which is where flaky-detection volume actually comes from (ci.yml's heavy
+      # jobs only run on the release PR). Advisory upload, own-origin only.
+      - run: npm run test:vitest -- --reporter=default --reporter=junit --outputFile.junit=trunk-junit/vitest-fastpath.xml
+      - name: Upload test results to Trunk (advisory)
+        if: ${{ always() && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) }}
+        continue-on-error: true
+        uses: trunk-io/analytics-uploader@385f1ccdf345b4532dc4b6c665dd432b702b8e28 # v2.1.2
+        with:
+          junit-paths: trunk-junit/**/*.xml
+          org-slug: omniroute
+          token: ${{ secrets.TRUNK_TOKEN }}
+
+  fast-unit:
+    name: Unit Tests fast-path (${{ matrix.shard }}/4)
+    needs: changes
+    if: ${{ github.event_name != 'pull_request' || ((github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) && needs.changes.outputs.code == 'true') }}
+    # Dynamic runner — see fast-gates (own-origin + flag; fork/unset → ubuntu-latest).
+    # This is the heaviest fast-path job; 4-way sharding (was 2, #6781) halves the
+    # critical path again (~8.5min → ~4.5min on ubuntu-latest; ~2min on the 8-slot
+    # runner box). Node's native --test-shard=N/total takes any denominator — only
+    # this matrix and the TEST_SHARD env below encode the shard count.
+    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)) && fromJSON('["self-hosted","omni-release"]') || 'ubuntu-latest' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4]
+    env:
+      JWT_SECRET: ci-lint-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-lint-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      # QW-d: fonte única — o mesmo npm script do CI pesado/local. Fecha dois drifts do
+      # comando inline antigo: os dirs `memory` e `usage` estavam FORA do glob (testes
+      # silenciosamente não rodavam no fast path) e o setupPolyfill não era importado.
+      - run: npm run test:unit:ci:shard
+        env:
+          TEST_SHARD: ${{ matrix.shard }}/4
+
+  # ── Pacote 4 (plano mestre testes+CI, aprovado 2026-07-04) ─────────────────────────
+  # No-new-warnings por PR via ESLint bulk suppressions nativo (>=9.24). O baseline
+  # config/quality/eslint-suppressions.json congela as violações EXISTENTES por
+  # arquivo+regra; qualquer warning NOVO aparece e o --max-warnings 0 falha o job — o
+  # drift de +41/+88 warnings por ciclo passa a morrer no PR que o introduz, em vez de
+  # ser rebaselinado às cegas na release. Aperto do baseline (na reconciliação da
+  # release): npx eslint . --prune-suppressions --suppressions-location config/quality/eslint-suppressions.json
+  #
+  # Princípio Zero: bloqueante SÓ para branches internas (as campanhas/sessões são a
+  # origem do drift). PR de FORK roda em modo report (continue-on-error → o job fica
+  # verde com anotação; a campanha /green-prs aplica o fix via co-autoria — o
+  # contribuidor NUNCA é bloqueado nem cobrado).
+  lint-guard:
+    name: No new ESLint warnings
+    needs: changes
+    if: ${{ github.event_name != 'pull_request' || ((github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) && needs.changes.outputs.code == 'true') }}
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      - name: Restore ESLint file cache
+        uses: actions/cache@v6
+        with:
+          path: |
+            .eslintcache
+            .eslintcache-complexity
+          key: eslint-${{ runner.os }}-${{ hashFiles('eslint.config.mjs', 'eslint.complexity-ratchets.config.mjs', 'config/quality/eslint-suppressions.json', 'package-lock.json') }}
+          restore-keys: |
+            eslint-${{ runner.os }}-
+      - name: ESLint (baseline congelado — warning novo = vermelho)
+        # lint:json writes the report; --max-warnings 0 keeps no-new-warnings policy.
+        run: npm run lint:json -- --max-warnings 0
+
+  # Merge-integrity: pega no PR os dois vazamentos crônicos de merge que hoje só
+  # explodem na release-PR. (1) CHANGELOG-eat — o auto-resolve do merge come
+  # bullets vizinhos/seções inteiras (incidente #6193, 2026-07-05: 212 linhas /
+  # 130 bullets); o checkout de PR é refs/pull/N/merge, então comparar contra a
+  # base detecta o eat ANTES do merge. (2) SKILL.md gerado stale vs o catálogo de
+  # agent-skills (#6186 mergeou um id de catálogo sem rodar o gerador → 8 reds de
+  # integration invisíveis até a release).
+  #
+  # Princípio Zero: bloqueante SÓ para branches internas; PR de FORK roda em modo
+  # report (continue-on-error) — a campanha corrige via co-autoria, o contribuidor
+  # nunca é bloqueado.
+  merge-integrity:
+    name: Merge integrity (changelog + generated skills)
+    # Always on non-draft PRs — CHANGELOG/skills can break on docs-only merges too.
+    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) }}
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true }}
+    env:
+      JWT_SECRET: ci-lint-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-lint-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      - name: CHANGELOG integrity (nenhum bullet da base pode sumir no merge-result)
+        run: npm run check:changelog-integrity
+      - name: Agent-skills generator sync (SKILL.md gerado ≡ catálogo)
+        run: npm run check:agent-skills-sync

.github/workflows/scorecard.yml

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

.github/workflows/semgrep.yml

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

.github/workflows/wiki-sync.yml

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

.gitignore

@@ -4,32 +4,64 @@
 .omnivscodeagent/
 omnirouteCloud/
 omnirouteSite/
+_cache/
+_ideia/
+_mono_repo/
+_references/
+_tasks/
+.agents/**
+.claude/**
+.gemini/**
+.config/**
+.data/**
+.logs/**
+.tests/**
+.coverage/**
+coverage/
+.dist/**
+.next/**
+.build/**
+.out/**
+
+# Stryker mutation testing — ephemeral sandbox + generated reports (never commit)
+.stryker-tmp/
+reports/mutation/
+stryker-output-*.json
+
+
+# Memory Bank and Cursor rules (local-only AI agent context)
+memory-bank/
+.cursor/rules/core.mdc
+.cursor/rules/memory-bank.mdc
+
+# Claude Code local state — runtime files only; shared commands at .claude/commands/ are tracked
+.claude/scheduled_tasks.lock
+.claude/scheduled_tasks/
+.claude/sessions/
+.claude/state.json
+.claude/settings.local.json
+
+# Root-level underscore-prefixed directories (private/draft — never commit)
+/_*/
+
+# Draft features documentation (internal only)
+docs/new-features/
 
 # dependencies
 node_modules/
-/.pnp
-.pnp.*
-.yarn/*
-!.yarn/patches
-!.yarn/plugins
-!.yarn/releases
-!.yarn/versions
-
-# testing
-coverage/
-
-# next.js
-.next/
-/out/
-
-# production
-/build
-/app
-cloud/*
-
-# misc
+# Also ignore a root node_modules SYMLINK (worktree setups symlink it from the main
+# checkout). The trailing-slash pattern above only matches a directory, so without this
+# a symlink named node_modules could be staged by `git add -A` and committed.
+/node_modules
+*.map
 .DS_Store
-*.pem
+
+# Obsidian sync plugin — committed for community distribution
+!obsidian-plugin/
+obsidian-plugin/node_modules/
+
+# Serena AI assistant config (local-only tool, not project code)
+.serena/
 
 # debug
 npm-debug.log*
@@ -40,6 +72,10 @@ yarn-error.log*
 # env files (can opt-in for committing if needed)
 .env*
 !.env.example
+!.env.homolog.example
+# Provider API keys (never commit)
+*.api-key
+.nvidia-api-key
 
 # vercel
 .vercel
@@ -50,41 +86,15 @@ next-env.d.ts
 
 # data and logs
 data/
+.data/
 logs/*
+test_output.log
 
 # analysis directories (generated, not tracked)
 .analysis/
 antigravity-manager-analysis/
-
-# docs (allow specific tracked files)
-docs/*
-!docs/ARCHITECTURE.md
-!docs/CODEBASE_DOCUMENTATION.md
-!docs/CONTRIBUTING.md
-!docs/USER_GUIDE.md
-!docs/API_REFERENCE.md
-!docs/TROUBLESHOOTING.md
-!docs/EXECUTION_CONTEXT_PROVIDER_SYNC.md
-!docs/TASK_NEBIUS_BACKEND_ENABLEMENT.md
-!docs/frontend-backend-provider-gap-report.md
-!docs/openapi.yaml
-!docs/RELEASE_CHECKLIST.md
-!docs/PLANO-IMPLANTACAO.md
-!docs/TASKS.md
-!docs/FASE-*.md
-!docs/adr/
-!docs/cli-tools/
-!docs/planning/
-!docs/improvement-plans/
-!docs/api/
-!docs/VM_DEPLOYMENT_GUIDE.md
-!docs/FEATURES.md
-!docs/screenshots/
-!docs/i18n/
-!docs/i18n/**
-!docs/A2A-SERVER.md
-!docs/AUTO-COMBO.md
-!docs/MCP-SERVER.md
+.sisyphus/
+.plans/
 
 # open-sse tests
 open-sse/test/*
@@ -93,30 +103,39 @@ open-sse/test/*
 .github/instructions/codacy.instructions.md
 
 # Playwright
+.playwright-mcp/
 test-results/
 playwright-report/
 blob-report/
 cloud/
+.tmp/
 
 # Security Analysis (standalone project with own git)
 security-analysis/
 
 # Deploy workflow (contains sensitive VPS credentials)
-.agent/workflows/deploy.md
 clipr/
 app.log
 *.tgz
+.gh-discussions.json
+deploy.sh
+docker-compose.minimal.yml
+
 
 # Backup directories
 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 (subproject dependency lock and build artifacts)
-electron/package-lock.json
+# Electron
 electron/dist-electron/
 electron/node_modules/
 icon.iconset/
@@ -128,3 +147,105 @@ vscode-extension/
 *.sqlite-shm
 *.sqlite-wal
 *.sqlite-journal
+
+# IDEA
+.idea/
+
+# Local OpenCode agent config
+.config/
+
+# Empty/dangling files
+typescript
+
+# Gemini Antigravity agent data
+.gemini/
+
+# Superpowers plans/specs (internal tooling, not project code)
+docs/superpowers/
+# Superpowers visual-companion brainstorm mockups (ephemeral)
+.superpowers/
+
+# TIA test-impact map — generated at runtime in CI (build-test-impact-map.mjs), never committed (~21MB)
+config/quality/test-impact-map.json
+
+# GitNexus local index
+.gitnexus
+.worktrees
+bin/omniroute.mjs
+
+# Consistent with .dockerignore / .npmignore
+.omc/
+audit-report.json
+bun.lock
+
+# Private environment variables for .http-client
+http-client.private.env.json
+
+# Note: _ideia/ (feature-triage drafts) is fully covered by the /_*/ rule above
+# and kept as a separate local-only git repo. Never committed to OmniRoute.
+
+# i18n audit artifact (generated by scripts/i18n/audit-dashboard-pages.mjs)
+scripts/i18n/_audit.json
+scripts/i18n/_pending-keys.json
+
+# Private workflow / skill / command implementations
+# These contain proprietary multi-phase logic and should not be committed
+.agents/workflows/implement-features-ag.md
+.agents/workflows/port-upstream-features-ag.md
+.agents/workflows/port-upstream-issues-ag.md
+.agents/skills/implement-features/
+.claude/commands/implement-features-cc.md
+.claude/commands/port-upstream-features-cc.md
+.claude/commands/port-upstream-issues-cc.md
+.claude/worktrees/
+.codegraph/
+
+# Fumadocs generated source
+.source/
+
+# AI agent local settings and configs
+.agents/
+.antigravitycli/
+.claude/
+
+# PR Reviews and local feedback files
+pr_reviews*.json
+
+#hidden local data directories (never commit)
+.local-data/
+.data-dev/
+/.junie/
+
+# internal setup prompts with personal credentials — never commit
+CODEX-SETUP-PROMPT.md
+# Quality ratchet — métricas efêmeras (baseline commitado em config/quality/; métricas não)
+config/quality/quality-metrics.json
+
+# Runtime logs (diretório local, nunca versionado)
+/logs/
+-home-diegosouzapw-dev-automações-bots-yt-downloader-20260504 .txt
+-home-diegosouzapw-dev-automações-bots-yt-downloader-20260410 .txt
+docs/prompts/AGENT-OWNERSHIP-PROTOCOL.omniroute.md
+docs/prompts/AGENT-OWNERSHIP-PROTOCOL.md
+docs/prompts/AGENT-OWNERSHIP-PROTOCOL.omniroute-mim.md
+docs/prompts/AGENT-OWNERSHIP-PROTOCOL.omniroute-mid.md
+omniroute.md
+
+# mise configuration
+mise.toml
+_artifacts/
+.claude-flow/
+
+# ESLint file cache (npm run lint --cache / complexity ratchets)
+.eslintcache
+.eslintcache-complexity
+
+
+# CI/local quality artifacts (eslint-results.json, etc.)
+.artifacts/
+
+# Homologation E2E suite (npm run homolog) — real-environment credentials + report output
+.env.homolog
+tests/homolog/.auth/
+tests/homolog/ui/.auth/
+homolog-report/

.gitleaks.toml

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

.husky/pre-commit

@@ -1 +1,13 @@
+#!/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
+
+# 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
+node scripts/check/check-tracked-artifacts.mjs

.husky/pre-push

@@ -0,0 +1,15 @@
+#!/usr/bin/env sh
+# .husky/pre-push — intentionally light.
+# any-budget + tracked-artifacts already run on pre-commit; re-running them on
+# every push only doubles local wall time for the same existence reason (CI still
+# enforces both). Keep this hook as a PATH/npm sanity check + reminder.
+# Intentionally excludes test:unit / typecheck (slow; covered by CI).
+
+if ! command -v npm >/dev/null 2>&1; then
+  echo "⚠️  npm not found in PATH — skipping pre-push hooks"
+  echo "   Run 'npm run check:any-budget:t11 && npm run check:tracked-artifacts' manually before pushing."
+  exit 0
+fi
+
+# No-op success: real local gates live in pre-commit; CI owns the rest.
+exit 0

.markdownlint.json

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

.mergify.yml

@@ -0,0 +1,55 @@
+# Mergify merge queue — WS3.4/D5 of the v3.8.49 quality/velocity master plan.
+#
+# WHY: ~85-100 active PR authors/month and 300+ PRs/week peaks, all merged by ONE
+# identity. The manual merge-train validated batches by hand; this queue automates
+# it with batching + automatic batch bisection (a red batch of N costs ~log2(N)
+# revalidations instead of N). Mergify Open Source plan: free, unlimited, public repo.
+#
+# GOVERNANCE (non-negotiable, mirrors CLAUDE.md Hard Rules #21/#22 + the owner's
+# pre-merge ⭐ gate):
+#   • A PR enters the queue ONLY via the `queue` label — applied by the owner (or a
+#     session acting for the owner) AFTER the pre-merge ⭐ report/decision. The label
+#     IS the merge approval; Mergify only executes it.
+#   • During a release-freeze (open issue labeled `release-freeze`), do NOT label PRs
+#     targeting the frozen branch — the freeze is a human-honored coordination signal
+#     the queue cannot see. Retarget to the active release/vX+1 first (Hard Rule #21).
+#   • Never label a PR another session is actively working (Hard Rule #22b).
+#   • Fallback path if Mergify misbehaves or the OSS plan changes: the manual
+#     merge-train runbook (docs/ops/MERGE_TRAIN.md) — remove labels, proceed by hand.
+
+queue_rules:
+  - name: release
+    # Any current or future release branch — the reason GitHub's native queue was
+    # rejected (no wildcard support on personal-account repos).
+    queue_conditions:
+      - base~=^release/v\d+\.\d+\.\d+$
+      - label=queue
+      - -draft
+      - -conflict
+    # "Everything that ran is green, nothing still running, AND the always-on
+    # anchor check succeeded" — robust to the path-filtered fast-gates (docs-only
+    # PRs skip code jobs; matrix shard names vary) while never fail-open: a PR with
+    # zero checks cannot vacuously merge, because `Merge integrity` runs on EVERY
+    # non-draft PR (quality.yml) and must be an affirmative success. Review approval
+    # is intentionally NOT a condition here: the owner-applied `queue` label IS the
+    # approval in this repo's single-maintainer model (see governance header).
+    merge_conditions:
+      - "#check-failure=0"
+      - "#check-pending=0"
+      - "#check-success>=1"
+      - check-success=Merge integrity (changelog + generated skills)
+    # Batching: validate up to 10 queued PRs together (the manual train's sweet spot);
+    # don't hold a lone PR hostage waiting for siblings.
+    batch_size: 10
+    batch_max_wait_time: 5 min
+    # Squash keeps the one-commit-per-PR history the CHANGELOG reconciliation expects.
+    merge_method: squash
+
+pull_request_rules:
+  - name: clean up the queue label after merge
+    conditions:
+      - merged
+    actions:
+      label:
+        remove:
+          - queue

.node-version

@@ -0,0 +1 @@
+24

.npmignore

@@ -3,7 +3,22 @@ data/
 **/data/
 **/db.json
 
+# VS Code extension test runtime (large binary, not needed in npm package)
+app/vscode-extension/
+**/data/
+**/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/
@@ -13,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
@@ -21,14 +47,21 @@ scripts/
 .github/
 .husky/
 .vscode/
+.agents/
 .env*
+app/.env
+app/.env*
 eslint.config.mjs
 prettier.config.mjs
 postcss.config.mjs
 next.config.mjs
 tsconfig.json
+tsconfig.typecheck-core.json
+tsconfig.typecheck-noimplicit-core.json
 playwright.config.ts
+vitest.config.ts
 next-env.d.ts
+llm.txt
 
 # Docker
 docker-compose*.yml
@@ -36,9 +69,56 @@ Dockerfile
 .dockerignore
 
 # Misc
-restart.sh
 AGENTS.md
+bun.lock
 
 # Build artifacts (pre-built goes inside app/)
-.next/
-node_modules/
+/.next/
+/node_modules/
+
+# Ignore large binary files and other build directories
+*.tgz
+*.AppImage
+*.deb
+*.rpm
+electron/
+app/electron/
+app/vscode-extension/
+
+# Subprojects
+clipr/
+omnirouteCloud/
+omnirouteSite/
+vscode-extension/
+
+# Root-level underscore-prefixed directories (private/draft — never publish)
+/_*/
+app/_*/
+app/coverage/
+app/logs/
+app/tests/
+
+# Consistent with .gitignore and .dockerignore
+.DS_Store
+.idea/
+.config/
+.data/
+.omnivscodeagent/
+.omc/
+*.sqlite-*
+*.tsbuildinfo
+security-analysis/
+.analysis/
+antigravity-manager-analysis/
+.sisyphus/
+.plans/
+app.__qa_backup/
+.app-build-backup-*/
+.gitnexus
+.worktrees
+.next-playwright/
+test-results/
+playwright-report/
+blob-report/
+coverage/
+@omniroute/

.npmrc

@@ -0,0 +1,14 @@
+# @lobehub/icons declares UI peers that are not needed by our deep icon imports.
+# Keeping peer auto-install disabled prevents npm from pulling @lobehub/ui/mermaid
+# back into the tree and reopening npm audit findings for unused packages.
+legacy-peer-deps=true
+
+# Network resilience: enlarge npm's fetch retry budget so a transient registry
+# socket reset (ECONNRESET) mid-download retries instead of failing the job.
+# npm defaults to only 2 retries with short timeouts; `npm ci` in
+# electron-release.yml hit ECONNRESET during v3.8.41 publish. Applies to every
+# CI workflow (electron / docker / unit) and local installs.
+fetch-retries=5
+fetch-retry-factor=4
+fetch-retry-mintimeout=20000
+fetch-retry-maxtimeout=120000

.nvmrc

@@ -0,0 +1 @@
+24

.prettierignore

@@ -0,0 +1,5 @@
+# Long reference tables are manually aligned; formatting the whole file causes noisy diffs.
+docs/reference/ENVIRONMENT.md
+
+# Dense auto-generated free-tier budget rows (one object per line) — prettier multi-line expand blows past file-size cap 800.
+open-sse/config/freeModelCatalog.data.ts

.size-limit.json

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

.source/dynamic.ts

@@ -0,0 +1,8 @@
+// @ts-nocheck
+import { dynamic } from 'fumadocs-mdx/runtime/dynamic';
+import * as Config from '../source.config';
+
+const create = await dynamic<typeof Config, import("fumadocs-mdx/runtime/types").InternalTypeConfig & {
+  DocData: {
+  }
+}>(Config, {"configPath":"source.config.ts","environment":"next","outDir":".source"}, {"doc":{"passthroughs":["extractedReferences"]}});

.source/source.config.mjs

@@ -0,0 +1,22 @@
+// source.config.ts
+import { defineDocs, defineConfig } from "fumadocs-mdx/config";
+var docs = defineDocs({
+  dir: "docs",
+  docs: {
+    files: [
+      "./architecture/**/*.md",
+      "./guides/**/*.md",
+      "./reference/**/*.md",
+      "./frameworks/**/*.md",
+      "./routing/**/*.md",
+      "./security/**/*.md",
+      "./compression/**/*.md",
+      "./ops/**/*.md"
+    ]
+  }
+});
+var source_config_default = defineConfig();
+export {
+  source_config_default as default,
+  docs
+};

.trivyignore

@@ -0,0 +1,22 @@
+# .trivyignore — accepted-risk suppressions for the container image scan
+#
+# Policy (see docs/security/SUPPLY_CHAIN.md):
+#   - The Trivy steps in .github/workflows/docker-publish.yml run with
+#     `ignore-unfixed: true`, so vulnerabilities WITHOUT a published fix are
+#     already excluded from both the blocking CRITICAL gate and the advisory
+#     Security-tab upload. You do NOT need an entry here for an unfixable
+#     base-image OS CVE — it will not be reported.
+#   - This file is the single auditable home for the rare case where a *fixable*
+#     CVE must be temporarily accepted (e.g. the upstream fix is not yet in the
+#     pinned base tag, or the affected package/binary is provably unreachable
+#     from the proxy request surface and rebuilding now is not justified).
+#
+# Format — one CVE id per line, each with a justification comment and, where
+# possible, an expiry, e.g.:
+#   # CVE-XXXX-YYYY — <why accepted>; revisit on next base-image bump (YYYY-MM-DD)
+#   CVE-XXXX-YYYY
+#
+# Keep this list SHORT and reviewed every release. Prefer fixing (rebuild on a
+# patched base / bump the dep) over suppressing. Stale entries are debt.
+#
+# (No accepted-risk suppressions at present — ignore-unfixed covers the noise.)

.vale.ini

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

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

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

.vscode/settings.json

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

.zizmor.yml

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

@omniroute/opencode-plugin/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.log
+.DS_Store

@omniroute/opencode-plugin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OmniRoute contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

@omniroute/opencode-plugin/README.md

@@ -0,0 +1,296 @@
+# @omniroute/opencode-plugin
+
+> **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
+
+The plugin ships **pre-built inside the `omniroute` npm package** since v3.8.23.
+If you have OmniRoute installed, the plugin is already on disk:
+
+```sh
+# 1. One command — copy the plugin into OpenCode and update opencode.json
+omniroute setup opencode --auth
+
+# 2. Follow the interactive prompt to enter your OmniRoute API key
+# 3. Restart OpenCode — /models lists the full live catalog
+```
+
+The `--auth` flag runs `opencode auth login --provider omniroute` automatically.
+Use `--base-url` to point at a non-default OmniRoute address:
+
+```sh
+omniroute setup opencode --base-url https://or.example.com --auth
+```
+
+### What it does
+
+1. Locates the bundled plugin inside the omniroute installation
+2. Copies `dist/` + `package.json` to `~/.config/opencode/plugins/omniroute/`
+3. Writes/updates `opencode.json` with the plugin entry (idempotent, replaces legacy entries)
+4. (With `--auth`) runs `opencode auth login` so the API key is stored
+
+Re-run any time to update the plugin or change the base URL. Older entries for
+`@omniroute/opencode-provider` or the legacy `opencode-omniroute-auth` package are
+automatically cleaned up.
+
+### Manual install (without omniroute CLI)
+
+If you cannot run `omniroute setup opencode` (local dev, CI, air-gapped), reference
+the built artifact directly:
+
+```sh
+cd @omniroute/opencode-plugin && npm run build && npm pack
+# then extract into ~/.config/opencode/plugins/omniroute-opencode-plugin/
+```
+
+And add the entry to `opencode.json` manually (see Quick Start below).
+
+Peer dep: `@opencode-ai/plugin` (managed by your OpenCode install).
+
+## Quick start (single instance, manual)
+
+```jsonc
+// opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "./plugins/omniroute-opencode-plugin/dist/index.js",
+      {
+        "providerId": "omniroute",
+        "baseURL": "https://or.example.com",
+      },
+    ],
+  ],
+}
+```
+
+```sh
+opencode auth login --provider omniroute
+# prompts for the OmniRoute API key, writes to ~/.local/share/opencode/auth.json
+```
+
+> ⚠ Use the `--provider` flag explicitly. `opencode auth login omniroute` is parsed as a positional `url` argument by current OC releases (≤1.15.5) and fails with `fetch() URL is invalid`. Tracked upstream.
+
+Restart OpenCode. `/models` lists the full live catalog. Variants (`-low`, `-medium`, `-high`, `-thinking`) and combos appear as first-class IDs — OmniRoute is the source of truth, no client-side synthesis.
+
+## Multi-instance (prod + preprod side-by-side)
+
+> ⚠ OC ≤1.15.5 dedupes plugin loads by absolute module path. Two `plugin:` entries pointing at the same `dist/index.js` collapse into one (last-listed options win). Workaround: install the plugin twice into separate directories so each entry resolves to a distinct module file. v0.2.x will introduce an `instances: [...]` shape that registers N providers from a single load.
+
+### Dual-install workaround (works today on OC ≤1.15.5)
+
+Pack the plugin once, extract it twice into named directories, then point each `plugin:` entry at its own copy:
+
+```sh
+# 1. Build + pack the plugin (run from the plugin worktree)
+cd /path/to/OmniRoute/@omniroute/opencode-plugin
+npm run build
+npm pack
+# produces omniroute-opencode-plugin-0.1.0.tgz
+
+# 2. Extract one copy per OmniRoute endpoint
+mkdir -p ~/.config/opencode/plugins/omniroute-opencode-plugin-prod
+mkdir -p ~/.config/opencode/plugins/omniroute-opencode-plugin-preprod
+tar -xzf omniroute-opencode-plugin-0.1.0.tgz -C ~/.config/opencode/plugins/omniroute-opencode-plugin-prod    --strip-components=1
+tar -xzf omniroute-opencode-plugin-0.1.0.tgz -C ~/.config/opencode/plugins/omniroute-opencode-plugin-preprod --strip-components=1
+```
+
+Then in `~/.config/opencode/opencode.json` reference each directory by absolute path:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "./plugins/omniroute-opencode-plugin-prod/dist/index.js",
+      {
+        "providerId": "omniroute",
+        "displayName": "OmniRoute",
+        "baseURL": "https://or.example.com",
+      },
+    ],
+    [
+      "./plugins/omniroute-opencode-plugin-preprod/dist/index.js",
+      {
+        "providerId": "omniroute-preprod",
+        "displayName": "OmniRoute Preprod",
+        "baseURL": "https://or-preprod.example.com",
+      },
+    ],
+  ],
+}
+```
+
+Paths are relative to `~/.config/opencode/`. Each entry now resolves to a distinct module file, so OC loads them as two separate plugin instances. Authenticate each:
+
+```sh
+opencode auth login --provider omniroute
+opencode auth login --provider omniroute-preprod
+```
+
+Each entry gets its own provider id, its own model picker entry, its own slot in `auth.json`, and its own TTL cache. Closures are isolated per plugin instance — no cross-talk.
+
+### After publish (`@omniroute/opencode-plugin` npm)
+
+Once the package is published, the dual-install becomes two `npm install --prefix` commands instead of `tar -xzf`:
+
+```sh
+mkdir -p ~/.config/opencode/plugins/omniroute-opencode-plugin-prod
+mkdir -p ~/.config/opencode/plugins/omniroute-opencode-plugin-preprod
+npm install --prefix ~/.config/opencode/plugins/omniroute-opencode-plugin-prod    @omniroute/opencode-plugin
+npm install --prefix ~/.config/opencode/plugins/omniroute-opencode-plugin-preprod @omniroute/opencode-plugin
+```
+
+`opencode.json` paths become `./plugins/omniroute-opencode-plugin-prod/node_modules/@omniroute/opencode-plugin/dist/index.js` (and the preprod equivalent).
+
+## Features
+
+| Feature                                     | What it does                                                                                                                                                                                                                                                                                                                                                                                                | Hook                         |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| Dynamic `/v1/models`                        | Pulls live catalog (455+ entries on prod) on each refresh, TTL-cached                                                                                                                                                                                                                                                                                                                                       | `provider.models`            |
+| Variants pass-through                       | `-low`/`-medium`/`-high`/`-thinking` ship as first-class IDs from OmniRoute (no client synthesis)                                                                                                                                                                                                                                                                                                           | `provider.models`            |
+| Combo LCD aggregation                       | Combos appear with intersected capabilities + min context/output across members                                                                                                                                                                                                                                                                                                                             | `provider.models` + `config` |
+| `combo/<slug>` namespace + `Combo: ` prefix | Combos surface under `combo/claude-primary` (not the upstream UUID) and the picker shows `Combo: claude-primary` so they stand apart from raw provider/model pairs                                                                                                                                                                                                                                          | both hooks                   |
+| Nice names + cost                           | `/api/pricing/models` display names AND `/api/pricing` per-million-token cost overlaid onto the live catalog                                                                                                                                                                                                                                                                                                | both hooks                   |
+| Canonical-twin dedup + alias-fallback       | `/v1/models` exposes the same upstream model under both short alias (`cc/claude-opus-4-7`) and canonical name (`claude/claude-opus-4-7`); the plugin drops the canonical twin when an alias twin exists (no duplicate rows in the picker) and reverse-maps canonical → alias to pick up enrichment for short aliases (`dg/nova-3 → Deepgram - Nova 3`) that `/api/pricing/models` only indexes by canonical | both hooks                   |
+| Compression pipeline tags                   | Combo names get tagged with their compression pipeline (e.g. `Combo: claude-primary [rtk🟡 → caveman🟠]`) when `features.compressionMetadata: true`. Intensity tokens render as a traffic-light emoji: 🟢 lite/minimal · 🟡 standard · 🟠 aggressive/full · 🔴 ultra                                                                                                                                        | both hooks                   |
+| Provider-tag prefix                         | Prepend short upstream-provider label to enriched names (e.g. `Claude - Claude Opus 4.7` vs `Kiro - Claude Opus 4.7`, `GHM - GPT 5`) so same-id models routed via different upstream connections group visibly in the picker (default-on, opt-out via `features.providerTag: false`)                                                                                                                        | both hooks                   |
+| Usable-only filter                          | Filter to providers with at least one healthy connection in `/api/providers` (opt-in via `features.usableOnly`)                                                                                                                                                                                                                                                                                             | both hooks                   |
+| Disk-cache fallback                         | Last-known-good catalog persisted to disk; hydrates on a cold start when `/v1/models` is unreachable (default-on, opt-out via `features.diskCache: false`)                                                                                                                                                                                                                                                  | `config`                     |
+| Bearer injection + suffix-spoof guard       | Adds `Authorization` on baseURL-matched requests only                                                                                                                                                                                                                                                                                                                                                       | `auth.loader.fetch`          |
+| Gemini schema sanitization                  | Strips `$schema`/`$ref`/`additionalProperties` for `gemini-*`/`google-vertex-gemini/*`                                                                                                                                                                                                                                                                                                                      | `auth.loader.fetch` wrap     |
+| Multi-instance                              | Each plugin entry binds to its own `providerId`; closures isolated                                                                                                                                                                                                                                                                                                                                          | factory                      |
+| Config-hook shim                            | OC ≤1.15.5 fallback: writes static catalog into `config.provider[id]` (config hook is the only one that fires in `serve` mode on these versions)                                                                                                                                                                                                                                                            | `config`                     |
+
+## Plugin options
+
+| Option          | Type     | Default                                    | Description                                                |
+| --------------- | -------- | ------------------------------------------ | ---------------------------------------------------------- |
+| `providerId`    | `string` | `"omniroute"`                              | OpenCode provider id; must be unique across plugin entries |
+| `displayName`   | `string` | `"OmniRoute"` or `OmniRoute (<id>)`        | Label in the OC UI                                         |
+| `modelCacheTtl` | `number` | `300000` (5 min)                           | `/v1/models` TTL in ms                                     |
+| `baseURL`       | `string` | resolved from `auth.json` after `/connect` | Override OmniRoute base URL                                |
+| `features`      | `object` | see below                                  | Feature toggles (all opt-in/out, defaults preserve v0.1.0) |
+
+### `features` block
+
+Every field is optional. Defaults mirror v0.1.0 behaviour so existing `opencode.json` files do not need to change.
+
+| Feature               | Type      | Default | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| --------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `combos`              | `boolean` | `true`  | Discover `/api/combos` and surface them as pseudo-models with LCD capabilities. Combos are keyed under the `combo/<slug>` namespace and labelled `Combo: <name>` in the model picker so they're distinguishable from raw provider/model pairs.                                                                                                                                                                                                                                                                                                                               |
+| `enrichment`          | `boolean` | `true`  | Pull display names from `/api/pricing/models` AND per-million-token pricing (`input`, `output`, `cached` → `cacheRead`, `cache_creation` → `cacheWrite`) from `/api/pricing`, then overlay both onto the live catalog (so the UI shows `Claude 4.7 Opus` with `cost.input: 5`, `cost.output: 25` instead of raw IDs and zeroed cost).                                                                                                                                                                                                                                        |
+| `compressionMetadata` | `boolean` | `false` | Pull `/api/context/combos` so combo names get tagged with their compression pipeline, e.g. `Combo: claude-primary [rtk🟡 → caveman🟠]`. Intensity tokens render as traffic-light emoji (🟢 lite/minimal · 🟡 standard · 🟠 aggressive/full · 🔴 ultra) so the picker advertises "how compressed" each combo is at a glance.                                                                                                                                                                                                                                                  |
+| `providerTag`         | `boolean` | `true`  | Prepend a short upstream-provider label to the enriched display name with `" - "` separator, so `cc/claude-opus-4-7 → Claude - Claude Opus 4.7` differs visibly from `kr/claude-opus-4-7 → Kiro - Claude Opus 4.7` in the OC TUI model picker. Label resolution: use `/api/pricing/models[<alias>].name` verbatim when ≤8 chars (e.g. `Claude`, `Kiro`, `Codex`, `Qwen`), otherwise fall back to `UPPER(alias)` (e.g. `GitHub Models` → `GHM`, `Gemini` → `GEMINI`). Idempotent. Combos intentionally skipped (the `Combo: ` prefix already conveys multi-upstream). |
+| `usableOnly`          | `boolean` | `false` | Read `/api/providers` and filter the catalog to providers that have at least one connection with `isActive: true` AND `testStatus: 'active'`. Subtract-filter semantics: providers unknown to BOTH the pricing-models catalog AND the connection table pass through (so synthetic prefixes like `agentrouter/*` survive). On fetch failure the filter is disabled for the refresh — never hides the whole catalog.                                                                                                                                                           |
+| `diskCache`           | `boolean` | `true`  | Persist the last successful `/v1/models` + `/api/combos` + enrichment + connections + compression snapshot to `${OPENCODE_DATA_DIR ?? ~/.local/share/opencode}/plugins/omniroute-<providerId>.json`. On a subsequent cold start where `/v1/models` throws (network down / IP whitelist drop / 5xx) the static block hydrates from the snapshot so OC's model picker survives offline. Soft-fail on read/write — never blocks publishing.                                                                                                                                     |
+| `geminiSanitization`  | `boolean` | `true`  | Strip `$schema`/`$ref`/`additionalProperties` from tool params when the model id matches `gemini`                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `mcpAutoEmit`         | `boolean` | `false` | Auto-write an `mcp.<providerId>` remote entry into the OC config pointing at `<baseURL>/api/mcp/stream` with the resolved Bearer token                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `mcpToken`            | `string`  | _unset_ | Optional separate Bearer for the auto-emitted MCP entry. Falls back to the provider's `apiKey` (from `auth.json`) when unset                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `fetchInterceptor`    | `boolean` | `true`  | Inject `Authorization: Bearer` + default `Content-Type` on every outbound request targeting `baseURL` (suffix-spoof guarded)                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+
+#### Example — enrichment + compression tags + MCP auto-emit
+
+```jsonc
+{
+  "plugin": [
+    [
+      "@omniroute/opencode-plugin",
+      {
+        "providerId": "omniroute",
+        "baseURL": "https://or.example.com",
+        "features": {
+          "combos": true,
+          "enrichment": true,
+          "compressionMetadata": true,
+          "mcpAutoEmit": true,
+        },
+      },
+    ],
+  ],
+}
+```
+
+With `mcpAutoEmit: true`, the plugin synthesises an `mcp.omniroute` entry equivalent to a manual:
+
+```jsonc
+"mcp": {
+  "omniroute": {
+    "type": "remote",
+    "url": "https://or.example.com/api/mcp/stream",
+    "enabled": true,
+    "headers": { "Authorization": "Bearer <apiKey-from-auth.json>" }
+  }
+}
+```
+
+If you want a narrower-scoped Bearer for MCP (different from the chat/inference key), set `features.mcpToken`. Operator overrides win: if you already set `mcp.omniroute` in `opencode.json`, the plugin will not overwrite it.
+
+#### Example — production-leaning defaults (clean picker, offline resilience)
+
+```jsonc
+{
+  "plugin": [
+    [
+      "@omniroute/opencode-plugin",
+      {
+        "providerId": "omniroute",
+        "baseURL": "https://or.example.com",
+        "features": {
+          "combos": true,
+          "enrichment": true,
+          "compressionMetadata": true,
+          "usableOnly": true,
+          "diskCache": true,
+        },
+      },
+    ],
+  ],
+}
+```
+
+- `usableOnly: true` drops models whose canonical provider has no healthy connection in your OmniRoute instance — your `/models` picker stays focused on what you can actually call.
+- `diskCache: true` (default) writes a snapshot to `${OPENCODE_DATA_DIR}/plugins/omniroute-<providerId>.json` on every healthy refresh. On a cold start where `/v1/models` is unreachable (laptop offline, IP whitelist drop), the snapshot hydrates the static block so OC still shows the catalog instead of a stub.
+- `compressionMetadata: true` annotates combo display names with their pipeline using traffic-light emoji for intensity (e.g. `Combo: claude-primary [rtk🟡 → caveman🟠]`) so the picker advertises which compression each combo applies and how heavy it is at a glance. Palette: 🟢 lite/minimal · 🟡 standard · 🟠 aggressive/full · 🔴 ultra. Unknown intensities fall through to raw text (`[rtk:custom-thing]`) so the plugin never hides a value OmniRoute knows but the plugin doesn't.
+- `providerTag: true` (default) prepends a short upstream-provider label so the picker shows `Claude - Claude Opus 4.7` for `cc/claude-opus-4-7`, `Kiro - Claude Opus 4.7` for `kr/claude-opus-4-7`, and `GHM - GPT 5` for `ghm/gpt-5` (slot.name `GitHub Models` > 8 chars → abbreviated). Critical when the same model id is sold through multiple upstream connections with different cost/auth/rate-limit profiles. Set to `false` to keep the pre-v3.8.3 unsuffixed format.
+
+## Comparison vs `@omniroute/opencode-provider`
+
+[`@omniroute/opencode-provider`](https://github.com/diegosouzapw/OmniRoute/tree/main/%40omniroute/opencode-provider) is the existing config-generator package — it writes a frozen `provider.<id>` block into `opencode.json` at build time. This plugin is the runtime integration.
+
+|                   | `@omniroute/opencode-plugin` (this) | `@omniroute/opencode-provider`    |
+| ----------------- | ----------------------------------- | --------------------------------- |
+| Type              | OC plugin                           | Config generator (CLI/build-time) |
+| Models            | Live from `/v1/models`              | Frozen at scaffold                |
+| Combos            | LCD-aggregated live                 | None                              |
+| Gemini sanitize   | Yes                                 | N/A                               |
+| OC UI integration | `/connect`, `/models`               | None                              |
+| Multi-instance    | Native                              | Manual                            |
+
+Both can coexist; pick the one that fits your environment.
+
+## Requirements
+
+- Node `>=22.22.3` (per `engines.node`); tested on Node 22 and 24.
+- OpenCode: verified end-to-end against `opencode@1.15.5` with `@opencode-ai/plugin@1.15.6`.
+- OC plugin peer (`@opencode-ai/plugin`) `>=1.14.49` for the full feature set (provider hook surfaces models in `/models`). On `<=1.14.48`, the plugin falls back to its `config` hook, writing a static catalog snapshot into `config.provider[id]` so models still appear.
+- The plugin uses the OC v1 plugin shape (`default: { id, server }`) — older OC releases that only walk named exports will reject it. Stay on OC ≥1.15.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

@omniroute/opencode-plugin/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@omniroute/opencode-plugin",
+  "version": "0.2.0",
+  "description": "OpenCode plugin for the OmniRoute AI Gateway. Drives dynamic model discovery, /connect auth flow, and multi-instance OmniRoute providers via the official @opencode-ai/plugin contract.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "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 tests/fork-features.test.ts tests/auto-combo-context.test.ts tests/provider-id-routing.test.ts",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "keywords": [
+    "omniroute",
+    "opencode",
+    "opencode-plugin",
+    "ai-sdk",
+    "openai-compatible",
+    "provider",
+    "gemini",
+    "combos",
+    "mcp"
+  ],
+  "author": "OmniRoute contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/diegosouzapw/OmniRoute.git",
+    "directory": "@omniroute/opencode-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/diegosouzapw/OmniRoute/issues"
+  },
+  "homepage": "https://github.com/diegosouzapw/OmniRoute/tree/main/%40omniroute/opencode-plugin#readme",
+  "engines": {
+    "node": ">=22.22.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.15.6",
+    "@types/node": "^22.19.19",
+    "tsup": "^8.5.1",
+    "tsx": "^4.22.3",
+    "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "esbuild": "^0.28.1"
+  }
+}

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

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

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

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

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

@@ -0,0 +1,147 @@
+/**
+ * T-02 auth-hook contract tests.
+ *
+ * Covers the `createOmniRouteAuthHook(opts)` factory and its loader behaviour
+ * against every Auth flavor (`api`, `oauth`, null, empty key). Validates the
+ * multi-instance fix: provider id flows from plugin options, not a module
+ * constant.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createOmniRouteAuthHook } from "../src/index.js";
+
+test("createOmniRouteAuthHook: default providerId is 'omniroute'", () => {
+  const hook = createOmniRouteAuthHook();
+  assert.equal(hook.provider, "opencode-omniroute");
+});
+
+test("createOmniRouteAuthHook: custom providerId binds to hook.provider (multi-instance)", () => {
+  const hook = createOmniRouteAuthHook({ providerId: "omniroute-preprod" });
+  assert.equal(hook.provider, "opencode-omniroute-preprod");
+});
+
+test("createOmniRouteAuthHook: methods[0] is type 'api' with label including displayName", () => {
+  const hook = createOmniRouteAuthHook();
+  assert.equal(Array.isArray(hook.methods), true);
+  assert.equal(hook.methods.length, 1);
+  const m = hook.methods[0];
+  assert.equal(m.type, "api");
+  assert.equal(m.label, "OmniRoute API Key");
+
+  const custom = createOmniRouteAuthHook({ providerId: "omniroute-preprod" });
+  assert.equal(custom.methods[0].label, "OmniRoute (opencode-omniroute-preprod) API Key");
+});
+
+test("createOmniRouteAuthHook: prompts[0] uses key='apiKey' per @opencode-ai/plugin contract", () => {
+  // NOTE: spec referenced `name: "apiKey"`; the official
+  // @opencode-ai/plugin@1.15.6 prompt shape uses `key` + `message` (no
+  // `name`/`label`/`mask` fields). Asserting against the real type contract.
+  const hook = createOmniRouteAuthHook();
+  const m = hook.methods[0];
+  assert.equal(m.type, "api");
+  // narrow: api method may carry prompts
+  const prompts = "prompts" in m ? m.prompts : undefined;
+  assert.ok(Array.isArray(prompts) && prompts.length === 1, "expected one prompt");
+  const p = prompts![0];
+  assert.equal(p.type, "text");
+  assert.equal((p as { key: string }).key, "apiKey");
+  assert.ok(
+    typeof (p as { message: string }).message === "string" &&
+      (p as { message: string }).message.includes("omniroute"),
+    "prompt message should mention provider id"
+  );
+});
+
+test("loader: valid api auth → {apiKey} when no baseURL option (T-04: fetch omitted)", async () => {
+  // T-04 changed the loader return shape: without a resolvable baseURL the
+  // interceptor cannot gate-keep requests, so the loader falls back to
+  // apiKey-only and the AI-SDK uses its default fetch. See fetch-interceptor
+  // tests for the wired-fetch branches.
+  const hook = createOmniRouteAuthHook();
+  assert.ok(hook.loader, "loader must be defined");
+  const result = await hook.loader!(
+    async () => ({ type: "api", key: "sk-test" }) as never,
+    {} as never
+  );
+  assert.deepEqual(result, { apiKey: "sk-test" });
+});
+
+test("loader: valid api auth → {apiKey, baseURL, fetch} when baseURL option set (T-04)", async () => {
+  const hook = createOmniRouteAuthHook({ baseURL: "https://or.example.com/v1" });
+  const result = await hook.loader!(
+    async () => ({ type: "api", key: "sk-x" }) as never,
+    {} as never
+  );
+  assert.equal((result as { apiKey: string }).apiKey, "sk-x");
+  assert.equal((result as { baseURL: string }).baseURL, "https://or.example.com/v1");
+  assert.equal(
+    typeof (result as { fetch?: unknown }).fetch,
+    "function",
+    "T-04: loader must wire fetch interceptor when baseURL resolves"
+  );
+});
+
+test("loader: features.fetchInterceptor=false AND geminiSanitization=false → no custom fetch (flags honored)", async () => {
+  // Regression: both fetch-layer flags were documented + schema-validated but
+  // silently ignored. Disabling both must fall back to the SDK default fetch.
+  const hook = createOmniRouteAuthHook({
+    baseURL: "https://or.example.com/v1",
+    features: { fetchInterceptor: false, geminiSanitization: false },
+  });
+  const result = await hook.loader!(
+    async () => ({ type: "api", key: "sk-x" }) as never,
+    {} as never
+  );
+  assert.deepEqual(result, { apiKey: "sk-x", baseURL: "https://or.example.com/v1" });
+  assert.equal(
+    (result as { fetch?: unknown }).fetch,
+    undefined,
+    "both flags off must omit the custom fetch"
+  );
+});
+
+test("loader: features.fetchInterceptor=false but geminiSanitization=true → fetch still wired (sanitizer only)", async () => {
+  const hook = createOmniRouteAuthHook({
+    baseURL: "https://or.example.com/v1",
+    features: { fetchInterceptor: false, geminiSanitization: true },
+  });
+  const result = await hook.loader!(
+    async () => ({ type: "api", key: "sk-x" }) as never,
+    {} as never
+  );
+  assert.equal(
+    typeof (result as { fetch?: unknown }).fetch,
+    "function",
+    "geminiSanitization alone must still provide a fetch wrapper"
+  );
+});
+
+test("loader: null/undefined auth → {} (no creds yet, OC surfaces /connect)", async () => {
+  const hook = createOmniRouteAuthHook();
+  const r1 = await hook.loader!(async () => null as never, {} as never);
+  assert.deepEqual(r1, {});
+  const r2 = await hook.loader!(async () => undefined as never, {} as never);
+  assert.deepEqual(r2, {});
+});
+
+test("loader: oauth-flavored auth → {} (wrong method type, ignored)", async () => {
+  const hook = createOmniRouteAuthHook();
+  const result = await hook.loader!(
+    async () =>
+      ({
+        type: "oauth",
+        refresh: "r",
+        access: "a",
+        expires: 0,
+      }) as never,
+    {} as never
+  );
+  assert.deepEqual(result, {});
+});
+
+test("loader: api auth with empty key → {} (empty creds rejected)", async () => {
+  const hook = createOmniRouteAuthHook();
+  const result = await hook.loader!(async () => ({ type: "api", key: "" }) as never, {} as never);
+  assert.deepEqual(result, {});
+});

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

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

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

@@ -0,0 +1,711 @@
+/**
+ * T-05 combo-discovery contract tests.
+ *
+ * Covers:
+ *   - `defaultOmniRouteCombosFetcher(baseURL, apiKey, timeoutMs?)`
+ *     — envelope tolerance (`{combos: [...]}` and bare array), non-2xx errors.
+ *   - `mapComboToModelV2(combo, members, providerId, baseURL)`
+ *     — LCD policy across capabilities, limits, modalities; defensive
+ *       posture on empty members; nice-name preference.
+ *   - `createOmniRouteProviderHook(opts, deps)` extension
+ *     — combos merged into the models map; collision resolution (combo
+ *       wins, warn-once); soft-fail when the combos fetcher throws;
+ *       combos cached + reused under the same TTL key as models.
+ *
+ * Mocking strategy mirrors `provider.test.ts`: both fetchers are
+ * dependency-injected at hook construction, no `fetch` monkey-patch.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  createOmniRouteProviderHook,
+  defaultOmniRouteCombosFetcher,
+  mapComboToModelV2,
+  type OmniRouteCombosFetcher,
+  type OmniRouteModelsFetcher,
+  type OmniRouteRawCombo,
+  type OmniRouteRawModelEntry,
+} from "../src/index.js";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Fixtures
+// ────────────────────────────────────────────────────────────────────────────
+
+const MODEL_PRIMARY: OmniRouteRawModelEntry = {
+  id: "claude-primary",
+  capabilities: {
+    tool_calling: true,
+    reasoning: true,
+    vision: true,
+    thinking: true,
+    temperature: true,
+  },
+  context_length: 200_000,
+  max_output_tokens: 64_000,
+  max_input_tokens: 180_000,
+  input_modalities: ["text", "image"],
+  output_modalities: ["text"],
+};
+
+const MODEL_SECONDARY: OmniRouteRawModelEntry = {
+  id: "claude-secondary",
+  capabilities: {
+    tool_calling: true,
+    reasoning: false,
+    vision: true,
+    thinking: false,
+    temperature: true,
+  },
+  context_length: 100_000,
+  max_output_tokens: 32_000,
+  max_input_tokens: 96_000,
+  input_modalities: ["text", "image"],
+  output_modalities: ["text"],
+};
+
+const MODEL_NO_TOOLS: OmniRouteRawModelEntry = {
+  id: "gemini-3-flash",
+  capabilities: { tool_calling: false, reasoning: false, vision: false, thinking: false },
+  context_length: 1_000_000,
+  max_output_tokens: 8_192,
+  input_modalities: ["text"],
+  output_modalities: ["text"],
+};
+
+const COMBO_CLAUDE_TIER: OmniRouteRawCombo = {
+  id: "combo-claude-tier",
+  name: "Claude Tier",
+  strategy: "priority",
+  models: [
+    { id: "s1", kind: "model", model: "claude-primary", weight: 100 },
+    { id: "s2", kind: "model", model: "claude-secondary", weight: 80 },
+  ],
+};
+
+// ────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ────────────────────────────────────────────────────────────────────────────
+
+function stubModelsFetcher(
+  payload: OmniRouteRawModelEntry[]
+): OmniRouteModelsFetcher & { callCount: () => number } {
+  let n = 0;
+  const f: OmniRouteModelsFetcher = async () => {
+    n++;
+    return payload;
+  };
+  return Object.assign(f, { callCount: () => n });
+}
+
+function stubCombosFetcher(
+  payload: OmniRouteRawCombo[]
+): OmniRouteCombosFetcher & { callCount: () => number; callsBy: () => Array<[string, string]> } {
+  let n = 0;
+  const calls: Array<[string, string]> = [];
+  const f: OmniRouteCombosFetcher = async (baseURL, apiKey) => {
+    n++;
+    calls.push([baseURL, apiKey]);
+    return payload;
+  };
+  return Object.assign(f, {
+    callCount: () => n,
+    callsBy: () => calls,
+  });
+}
+
+function failingCombosFetcher(
+  err = new Error("boom")
+): OmniRouteCombosFetcher & { callCount: () => number } {
+  let n = 0;
+  const f: OmniRouteCombosFetcher = async () => {
+    n++;
+    throw err;
+  };
+  return Object.assign(f, { callCount: () => n });
+}
+
+const apiAuth = (key: string): unknown => ({ type: "api", key });
+
+// Capture console.warn invocations for the duration of a callback, then
+// restore the original. Needed because the collision + soft-fail paths
+// emit warnings we want to assert on.
+async function withWarnCapture<T>(
+  fn: (warnings: Array<{ args: unknown[] }>) => Promise<T>
+): Promise<{ result: T; warnings: Array<{ args: unknown[] }> }> {
+  const original = console.warn;
+  const warnings: Array<{ args: unknown[] }> = [];
+  console.warn = (...args: unknown[]) => {
+    warnings.push({ args });
+  };
+  try {
+    const result = await fn(warnings);
+    return { result, warnings };
+  } finally {
+    console.warn = original;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// defaultOmniRouteCombosFetcher — envelope tolerance + error surfacing
+// ────────────────────────────────────────────────────────────────────────────
+
+test("defaultOmniRouteCombosFetcher: parses {combos:[…]} envelope", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async (input: unknown) => {
+    const url = typeof input === "string" ? input : (input as { url: string }).url;
+    assert.equal(url, "https://or.example.com/api/combos");
+    return new Response(
+      JSON.stringify({
+        combos: [
+          { id: "c1", name: "Combo One", strategy: "priority", models: [] },
+          { id: "c2", name: "Combo Two", strategy: "weighted", models: [] },
+        ],
+      }),
+      { status: 200, headers: { "Content-Type": "application/json" } }
+    );
+  }) as typeof fetch;
+  try {
+    const combos = await defaultOmniRouteCombosFetcher("https://or.example.com", "sk-test");
+    assert.equal(combos.length, 2);
+    assert.equal(combos[0].id, "c1");
+    assert.equal(combos[1].id, "c2");
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("defaultOmniRouteCombosFetcher: parses bare array envelope", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async () => {
+    return new Response(JSON.stringify([{ id: "c1" }, { id: "c2" }, { not_an_id: 42 }]), {
+      status: 200,
+    });
+  }) as typeof fetch;
+  try {
+    const combos = await defaultOmniRouteCombosFetcher("https://or.example.com/v1", "sk-test");
+    // Strip /v1 before /api/combos, AND filter out entries with no string id.
+    assert.equal(combos.length, 2);
+    assert.equal(combos[0].id, "c1");
+    assert.equal(combos[1].id, "c2");
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("defaultOmniRouteCombosFetcher: strips trailing /v1 before /api/combos", async () => {
+  const originalFetch = globalThis.fetch;
+  let observedUrl = "";
+  globalThis.fetch = (async (input: unknown) => {
+    observedUrl = typeof input === "string" ? input : (input as { url: string }).url;
+    return new Response(JSON.stringify({ combos: [] }), { status: 200 });
+  }) as typeof fetch;
+  try {
+    await defaultOmniRouteCombosFetcher("https://or.example.com/v1/", "sk-test");
+    assert.equal(observedUrl, "https://or.example.com/api/combos");
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("defaultOmniRouteCombosFetcher: throws on non-2xx with status code in message", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async () => {
+    return new Response(JSON.stringify({ error: "Invalid token" }), {
+      status: 403,
+      statusText: "Forbidden",
+    });
+  }) as typeof fetch;
+  try {
+    await assert.rejects(
+      async () => {
+        await defaultOmniRouteCombosFetcher("https://or.example.com", "sk-bad");
+      },
+      (err: unknown) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        assert.match(msg, /403/, "status code must appear in message");
+        assert.match(msg, /\/api\/combos/, "url must appear in message");
+        return true;
+      }
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("defaultOmniRouteCombosFetcher: throws when apiKey missing", async () => {
+  await assert.rejects(
+    async () => defaultOmniRouteCombosFetcher("https://or.example.com", ""),
+    /apiKey required/
+  );
+});
+
+test("defaultOmniRouteCombosFetcher: throws when baseURL missing", async () => {
+  await assert.rejects(
+    async () => defaultOmniRouteCombosFetcher("", "sk-test"),
+    /baseURL required/
+  );
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// mapComboToModelV2 — LCD semantics
+// ────────────────────────────────────────────────────────────────────────────
+
+test("mapComboToModelV2: empty members → capabilities all false (defensive)", () => {
+  const m = mapComboToModelV2(
+    { id: "combo-empty", name: "Empty Combo" },
+    [],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m.id, "combo-empty");
+  assert.equal(m.name, "Empty Combo");
+  assert.equal(m.capabilities.temperature, false);
+  assert.equal(m.capabilities.reasoning, false);
+  assert.equal(m.capabilities.attachment, false);
+  assert.equal(m.capabilities.toolcall, false);
+  assert.equal(m.capabilities.input.text, false);
+  assert.equal(m.capabilities.output.text, false);
+  assert.equal(m.limit.context, 0);
+  assert.equal(m.limit.output, 0);
+  assert.equal(m.limit.input, undefined);
+  assert.deepEqual(m.cost, { input: 0, output: 0, cache: { read: 0, write: 0 } });
+});
+
+test("mapComboToModelV2: all members reasoning=true → combo reasoning=true", () => {
+  const m = mapComboToModelV2(
+    { id: "c", models: [] },
+    [
+      MODEL_PRIMARY,
+      {
+        ...MODEL_PRIMARY,
+        id: "p2",
+        capabilities: { ...MODEL_PRIMARY.capabilities, thinking: false, reasoning: true },
+      },
+    ],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m.capabilities.reasoning, true);
+});
+
+test("mapComboToModelV2: any member reasoning=false → combo reasoning=false", () => {
+  const m = mapComboToModelV2(
+    { id: "c", models: [] },
+    [MODEL_PRIMARY, MODEL_NO_TOOLS], // gemini-3-flash has reasoning:false, thinking:false
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m.capabilities.reasoning, false);
+});
+
+test("mapComboToModelV2: limit.context is min of members'", () => {
+  const m = mapComboToModelV2(
+    { id: "c", models: [] },
+    [MODEL_PRIMARY, MODEL_SECONDARY, MODEL_NO_TOOLS],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  // min(200_000, 100_000, 1_000_000) = 100_000
+  assert.equal(m.limit.context, 100_000);
+  // min(64_000, 32_000, 8_192) = 8_192
+  assert.equal(m.limit.output, 8_192);
+});
+
+test("mapComboToModelV2: limit.input only emitted when EVERY member declares one", () => {
+  const m1 = mapComboToModelV2(
+    { id: "c", models: [] },
+    [MODEL_PRIMARY, MODEL_SECONDARY],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  // Both declare max_input_tokens → limit.input = min(180000, 96000)
+  assert.equal(m1.limit.input, 96_000);
+
+  const m2 = mapComboToModelV2(
+    { id: "c", models: [] },
+    [MODEL_PRIMARY, MODEL_NO_TOOLS], // gemini-3-flash doesn't declare max_input_tokens
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m2.limit.input, undefined);
+});
+
+test("mapComboToModelV2: nice name preferred from combo.name", () => {
+  const m1 = mapComboToModelV2(
+    { id: "combo-x", name: "Pretty Name" },
+    [MODEL_PRIMARY],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m1.name, "Pretty Name");
+
+  // Falls back to id when name is absent or empty.
+  const m2 = mapComboToModelV2(
+    { id: "combo-y" },
+    [MODEL_PRIMARY],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m2.name, "combo-y");
+
+  const m3 = mapComboToModelV2(
+    { id: "combo-z", name: "   " },
+    [MODEL_PRIMARY],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m3.name, "combo-z");
+});
+
+test("mapComboToModelV2: attachment AND vision flag both honored across members", () => {
+  // MODEL_PRIMARY: vision=true; MODEL_SECONDARY: vision=true → combo attachment=true
+  const yes = mapComboToModelV2(
+    { id: "c1", models: [] },
+    [MODEL_PRIMARY, MODEL_SECONDARY],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(yes.capabilities.attachment, true);
+
+  // Add a member with no vision/attachment → AND collapses to false
+  const no = mapComboToModelV2(
+    { id: "c2", models: [] },
+    [MODEL_PRIMARY, MODEL_NO_TOOLS],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(no.capabilities.attachment, false);
+});
+
+test("mapComboToModelV2: modalities AND'd across members", () => {
+  const m = mapComboToModelV2(
+    { id: "c", models: [] },
+    [MODEL_PRIMARY, MODEL_SECONDARY], // both have text+image
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m.capabilities.input.text, true);
+  assert.equal(m.capabilities.input.image, true);
+  assert.equal(m.capabilities.input.audio, false);
+
+  // Add a text-only member → image collapses to false.
+  const m2 = mapComboToModelV2(
+    { id: "c", models: [] },
+    [MODEL_PRIMARY, MODEL_NO_TOOLS],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m2.capabilities.input.text, true);
+  assert.equal(m2.capabilities.input.image, false);
+});
+
+test("mapComboToModelV2: api block matches providerId + baseURL", () => {
+  const m = mapComboToModelV2(
+    { id: "c" },
+    [MODEL_PRIMARY],
+    "omniroute-preprod",
+    "https://or-preprod.example.com/v1"
+  );
+  assert.equal(m.providerID, "omniroute-preprod");
+  assert.equal(m.api.id, "openai-compatible");
+  assert.equal(m.api.url, "https://or-preprod.example.com/v1");
+  assert.equal(m.api.npm, "@ai-sdk/openai-compatible");
+  assert.equal(m.status, "active");
+});
+
+test("mapComboToModelV2: explicit member temperature=false drops combo temperature=false", () => {
+  const tempFalse: OmniRouteRawModelEntry = {
+    id: "no-temp",
+    capabilities: { tool_calling: true, temperature: false },
+    context_length: 100_000,
+    max_output_tokens: 8_000,
+    input_modalities: ["text"],
+    output_modalities: ["text"],
+  };
+  const m = mapComboToModelV2(
+    { id: "c" },
+    [MODEL_PRIMARY, tempFalse],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m.capabilities.temperature, false);
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// createOmniRouteProviderHook — combos merge + collision + soft-fail + cache
+// ────────────────────────────────────────────────────────────────────────────
+
+test("models() returns combo entries merged into the map", async () => {
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY, MODEL_SECONDARY, MODEL_NO_TOOLS]);
+  const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher: modelsFetcher, combosFetcher }
+  );
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+
+  // 3 raw models + 1 combo = 4 entries
+  assert.equal(Object.keys(out).length, 4);
+  assert.ok(out["omniroute/claude-primary"]);
+  assert.ok(out["omniroute/claude-secondary"]);
+  assert.ok(out["omniroute/gemini-3-flash"]);
+  assert.ok(out["omniroute/claude-tier"]);
+
+  const combo = out["omniroute/claude-tier"];
+  assert.equal(combo.name, "Claude Tier");
+  assert.equal(combo.providerID, "omniroute");
+  // LCD over claude-primary (200k, reasoning) + claude-secondary (100k, no reasoning)
+  assert.equal(combo.limit.context, 100_000);
+  assert.equal(combo.capabilities.reasoning, false);
+  assert.equal(combo.capabilities.toolcall, true);
+});
+
+test("models(): combo with unknown member ids degrades to all-false LCD posture", async () => {
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY]); // catalog only has claude-primary
+  const combosFetcher = stubCombosFetcher([
+    {
+      id: "phantom",
+      name: "Phantom Combo",
+      models: [
+        { id: "s1", kind: "model", model: "does-not-exist-1", weight: 50 },
+        { id: "s2", kind: "model", model: "does-not-exist-2", weight: 50 },
+      ],
+    },
+  ]);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher: modelsFetcher, combosFetcher }
+  );
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  assert.ok(out["omniroute/phantom-combo"]);
+  // With zero resolvable members, LCD = all-false (defensive posture).
+  assert.equal(out["omniroute/phantom-combo"].capabilities.toolcall, false);
+  assert.equal(out["omniroute/phantom-combo"].capabilities.reasoning, false);
+  assert.equal(out["omniroute/phantom-combo"].limit.context, 0);
+});
+
+test("models(): hidden combos are excluded from the map", async () => {
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY]);
+  const combosFetcher = stubCombosFetcher([
+    {
+      id: "visible",
+      name: "Visible",
+      models: [{ id: "s1", kind: "model", model: "claude-primary", weight: 100 }],
+    },
+    {
+      id: "hidden",
+      name: "Hidden",
+      isHidden: true,
+      models: [{ id: "s1", kind: "model", model: "claude-primary", weight: 100 }],
+    },
+  ]);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher: modelsFetcher, combosFetcher }
+  );
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  assert.ok(out["omniroute/visible"]);
+  assert.ok(!out["omniroute/hidden"], "hidden combo must be omitted");
+});
+
+test("models(): combo name exactly matches raw model id → raw deleted, raw deleted, no warn", async () => {
+  // Combo.name === raw model id triggers the dedup deletion. This mirrors
+  // the real OmniRoute payload where /v1/models pre-mirrors combos as
+  // no-slash raw entries whose ids match /api/combos friendly names.
+  const colliderCombo: OmniRouteRawCombo = {
+    id: "uuid-collider",
+    name: "claude-primary", // EXACT match to MODEL_PRIMARY.id
+    models: [{ id: "s1", kind: "model", model: "claude-secondary", weight: 100 }],
+  };
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY, MODEL_SECONDARY]);
+  const combosFetcher = stubCombosFetcher([colliderCombo]);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher: modelsFetcher, combosFetcher }
+  );
+
+  const { result: out, warnings } = await withWarnCapture(async (_w) => {
+    return hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  });
+
+  // Raw model replaced by combo of the same key; combo now lives at the bare slug.
+  assert.ok(out["omniroute/claude-primary"], "combo surfaces under prefixed key");
+  assert.equal(out["omniroute/claude-primary"].name, "claude-primary");
+
+  // No collision warning fires — dedup makes keys disjoint.
+  const collisionWarns = warnings.filter((w) => {
+    const msg = w.args[0];
+    return typeof msg === "string" && msg.includes("collides");
+  });
+  assert.equal(collisionWarns.length, 0, "no collision warn after dedup");
+});
+
+test("models(): two combos with same slug → second gets disambiguator suffix", async () => {
+  // Both combos slug to `claude` — second must get `claude-<id-prefix>`.
+  const combos: OmniRouteRawCombo[] = [
+    {
+      id: "uuid-a",
+      name: "Claude",
+      models: [{ id: "s", kind: "model", model: "claude-primary", weight: 1 }],
+    },
+    {
+      id: "uuid-b",
+      name: "Claude",
+      models: [{ id: "s", kind: "model", model: "claude-secondary", weight: 1 }],
+    },
+  ];
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    {
+      fetcher: stubModelsFetcher([MODEL_PRIMARY, MODEL_SECONDARY]),
+      combosFetcher: stubCombosFetcher(combos),
+    }
+  );
+
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  // First combo gets the bare slug; second gets disambiguated.
+  assert.ok(out["omniroute/claude"], "first combo at prefixed slug");
+  assert.ok(out["omniroute/claude-uuid"], "second combo disambiguated by id prefix");
+});
+
+test("models(): combos fetch fails → falls back to models-only, warn emitted, no throw", async () => {
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY, MODEL_SECONDARY]);
+  const combosFetcher = failingCombosFetcher(new Error("ECONNRESET"));
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher: modelsFetcher, combosFetcher }
+  );
+
+  const { result: out, warnings } = await withWarnCapture(async () => {
+    return hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  });
+
+  // Catalog includes the models but NOT any combo entries.
+  assert.equal(Object.keys(out).length, 2);
+  assert.ok(out["omniroute/claude-primary"]);
+  assert.ok(out["omniroute/claude-secondary"]);
+
+  // Soft-fail warning surfaced.
+  const softFail = warnings.find((w) => {
+    const msg = w.args[0];
+    return typeof msg === "string" && msg.includes("combos fetch failed");
+  });
+  assert.ok(softFail, "soft-fail warning must be emitted on combos fetch error");
+  assert.equal(combosFetcher.callCount(), 1);
+});
+
+test("models(): combos cached + reused within TTL (one combo fetch per TTL window)", async () => {
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY, MODEL_SECONDARY]);
+  const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
+  let nowMs = 1_000_000;
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1", modelCacheTtl: 60_000 },
+    { fetcher: modelsFetcher, combosFetcher, now: () => nowMs }
+  );
+
+  await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  nowMs += 30_000; // half the TTL
+  const second = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  assert.equal(combosFetcher.callCount(), 1, "combos fetched only once within TTL");
+  assert.equal(modelsFetcher.callCount(), 1, "models fetched only once within TTL");
+  assert.ok(second["omniroute/claude-tier"]);
+});
+
+test("models(): combos refetched after TTL expiry (same key as models)", async () => {
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY]);
+  const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
+  let nowMs = 1_000_000;
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1", modelCacheTtl: 60_000 },
+    { fetcher: modelsFetcher, combosFetcher, now: () => nowMs }
+  );
+
+  await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  nowMs += 60_001;
+  await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  assert.equal(combosFetcher.callCount(), 2, "combos must refetch past TTL");
+  assert.equal(modelsFetcher.callCount(), 2, "models must refetch past TTL");
+});
+
+test("models(): combos fetcher receives the resolved baseURL + apiKey", async () => {
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY]);
+  const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher: modelsFetcher, combosFetcher }
+  );
+  await hook.models!({} as never, { auth: apiAuth("sk-spy") as never });
+  assert.deepEqual(combosFetcher.callsBy()[0], ["https://or.example.com/v1", "sk-spy"]);
+});
+
+test("models(): nested combo-ref context is the min of nested + raw members", async () => {
+  // Top-level combo MASTER-LIGHT has 1 raw model (claude-primary, 200k)
+  // and 2 combo-refs: OldLLM (8k member) and KIRO (32k member). The OLD
+  // plugin would advertise 200k (only the raw model); the fix should
+  // make it advertise 8k (the bottleneck across the member graph).
+  const modelsFetcher = stubModelsFetcher([
+    MODEL_PRIMARY,
+    {
+      id: "oldllm-member-1",
+      context_length: 8_000,
+      max_output_tokens: 4_000,
+      capabilities: {
+        tool_calling: false,
+        reasoning: false,
+        vision: false,
+        thinking: false,
+        temperature: true,
+      },
+      input_modalities: ["text"],
+      output_modalities: ["text"],
+    },
+    {
+      id: "kiro-member-1",
+      context_length: 32_000,
+      max_output_tokens: 8_000,
+      capabilities: {
+        tool_calling: true,
+        reasoning: false,
+        vision: false,
+        thinking: false,
+        temperature: true,
+      },
+      input_modalities: ["text"],
+      output_modalities: ["text"],
+    },
+  ]);
+  const combosFetcher = stubCombosFetcher([
+    {
+      id: "oldllm",
+      name: "OldLLM",
+      models: [{ id: "s1", kind: "model", model: "oldllm-member-1", weight: 100 }],
+    },
+    {
+      id: "kiro",
+      name: "KIRO",
+      models: [{ id: "s1", kind: "model", model: "kiro-member-1", weight: 100 }],
+    },
+    {
+      id: "master-light",
+      name: "MASTER-LIGHT",
+      models: [
+        { id: "r1", kind: "model", model: "claude-primary", weight: 50 },
+        { id: "r2", kind: "combo-ref", comboName: "OldLLM", weight: 25 },
+        { id: "r3", kind: "combo-ref", comboName: "KIRO", weight: 25 },
+      ],
+    },
+  ]);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher: modelsFetcher, combosFetcher }
+  );
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  const masterLight = out["omniroute/master-light"];
+  assert.ok(masterLight, "MASTER-LIGHT entry must exist");
+  assert.equal(
+    masterLight.limit.context,
+    8_000,
+    `expected 8_000 (OldLLM bottleneck), got ${masterLight.limit.context}`
+  );
+});

@omniroute/opencode-plugin/tests/disk-snapshot-perms.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Regression test for the disk-snapshot file permissions (release/v3.8.2
+ * review finding C2). The snapshot embeds provider topology + connection
+ * records and lives alongside auth.json (0o600), so it must NOT be readable by
+ * group/other. Before the fix it was written with the default (typically
+ * world-readable 0o644) mode.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  defaultDiskSnapshotWriter,
+  diskSnapshotPath,
+  type OmniRouteFetchCacheEntry,
+} from "../src/index.js";
+
+function makeEntry(): Omit<OmniRouteFetchCacheEntry, "expiresAt"> {
+  return {
+    rawModels: [],
+    rawCombos: [],
+    rawEnrichment: new Map(),
+    rawCompressionCombos: [],
+    rawConnections: [],
+  };
+}
+
+test("defaultDiskSnapshotWriter writes an owner-only (no group/other) snapshot", async (t) => {
+  // POSIX-only assertion; Windows does not honor numeric file modes.
+  if (process.platform === "win32") {
+    t.skip("file mode semantics are POSIX-only");
+    return;
+  }
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-disk-perms-"));
+  const prevDataDir = process.env.OPENCODE_DATA_DIR;
+  process.env.OPENCODE_DATA_DIR = tmp;
+
+  try {
+    await defaultDiskSnapshotWriter("perm-test", makeEntry());
+
+    const file = diskSnapshotPath("perm-test");
+    assert.ok(fs.existsSync(file), "snapshot file should be written");
+
+    const fileMode = fs.statSync(file).mode & 0o777;
+    assert.equal(
+      fileMode & 0o077,
+      0,
+      `snapshot must not be group/other accessible (got ${fileMode.toString(8)})`
+    );
+
+    const dirMode = fs.statSync(path.dirname(file)).mode & 0o777;
+    assert.equal(
+      dirMode & 0o077,
+      0,
+      `plugins dir must not be group/other accessible (got ${dirMode.toString(8)})`
+    );
+  } finally {
+    if (prevDataDir === undefined) delete process.env.OPENCODE_DATA_DIR;
+    else process.env.OPENCODE_DATA_DIR = prevDataDir;
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});

@omniroute/opencode-plugin/tests/fetch-interceptor.test.ts

@@ -0,0 +1,269 @@
+/**
+ * T-04 fetch-interceptor contract tests.
+ *
+ * Covers `createOmniRouteFetchInterceptor` (URL-prefix gating, header merge,
+ * Content-Type defaulting, input-shape polymorphism) plus the loader
+ * integration that wires it into the AuthHook return shape.
+ *
+ * Strategy: replace `globalThis.fetch` with a closure-based recorder for the
+ * duration of each test (saved-and-restored in try/finally — node:test has
+ * no built-in spy/restore lifecycle). The recorder captures `(input, init)`
+ * as observed by the wrapped global call so we can assert on what was
+ * forwarded after header injection.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createOmniRouteAuthHook, createOmniRouteFetchInterceptor } from "../src/index.js";
+
+type FetchCall = { input: Parameters<typeof fetch>[0]; init?: RequestInit };
+
+function installFetchRecorder(response: Response = new Response("ok")) {
+  const calls: FetchCall[] = [];
+  const original = globalThis.fetch;
+  globalThis.fetch = (async (input: any, init?: any) => {
+    calls.push({ input, init });
+    return response;
+  }) as typeof fetch;
+  const restore = () => {
+    globalThis.fetch = original;
+  };
+  return { calls, restore };
+}
+
+const BASE = "https://or.example.com/v1";
+const KEY = "sk-test-fetch";
+
+test("createOmniRouteFetchInterceptor: targets baseURL → Authorization header injected", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    await f(`${BASE}/chat/completions`, {
+      method: "POST",
+      body: JSON.stringify({ x: 1 }),
+    });
+    assert.equal(calls.length, 1);
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Authorization"), `Bearer ${KEY}`);
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: targets baseURL → Authorization OVERRIDES caller-supplied Bearer", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    await f(`${BASE}/chat/completions`, {
+      method: "POST",
+      body: "{}",
+      headers: { Authorization: "Bearer attacker-key" },
+    });
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    // We own the apiKey for this provider — caller-supplied Bearer must lose.
+    assert.equal(sentHeaders.get("Authorization"), `Bearer ${KEY}`);
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: targets baseURL + body → Content-Type defaults to application/json", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    await f(`${BASE}/chat/completions`, {
+      method: "POST",
+      body: JSON.stringify({ m: "x" }),
+    });
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Content-Type"), "application/json");
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: caller-set Content-Type is NOT overwritten", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    await f(`${BASE}/v2/whatever`, {
+      method: "POST",
+      body: "raw",
+      headers: { "Content-Type": "text/plain; charset=utf-8" },
+    });
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Content-Type"), "text/plain; charset=utf-8");
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: non-baseURL host → passthrough, no Authorization injected", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    await f("https://third-party.example.org/v1/chat", {
+      method: "POST",
+      body: "{}",
+      headers: { "X-Caller": "yes" },
+    });
+    const sent = calls[0]!;
+    // Init forwarded verbatim — no header injection.
+    const sentHeaders = new Headers((sent.init as RequestInit | undefined)?.headers);
+    assert.equal(sentHeaders.get("Authorization"), null, "MUST NOT leak apiKey");
+    assert.equal(sentHeaders.get("X-Caller"), "yes");
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: refuses suffix-spoof — `${base}-attacker.evil` does NOT match baseURL", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    // baseURL is `https://or.example.com/v1`. A spoofed
+    // `https://or.example.com/v1-attacker.evil/chat` shares the literal prefix
+    // but is NOT under our origin path — must be treated as passthrough.
+    await f("https://or.example.com/v1-attacker.evil/chat", {
+      method: "POST",
+      body: "{}",
+    });
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit | undefined)?.headers);
+    assert.equal(sentHeaders.get("Authorization"), null);
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: URL object input is handled", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    await f(new URL(`${BASE}/models`), {});
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Authorization"), `Bearer ${KEY}`);
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: Request input is handled (reads .url)", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    const req = new Request(`${BASE}/chat/completions`, {
+      method: "POST",
+      body: JSON.stringify({ a: 1 }),
+      headers: { "X-Caller": "preserved" },
+    });
+    await f(req);
+    const sent = calls[0]!;
+    // The interceptor forwards the original Request as `input` but layers our
+    // headers into the `init`. We assert against the init view since fetch()
+    // resolves headers from init first when both are present.
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Authorization"), `Bearer ${KEY}`);
+    assert.equal(
+      sentHeaders.get("X-Caller"),
+      "preserved",
+      "Request-attached headers must survive the merge"
+    );
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: trailing slash in baseURL is normalized", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({
+      apiKey: KEY,
+      baseURL: `${BASE}////`,
+    });
+    await f(`${BASE}/models`, {});
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Authorization"), `Bearer ${KEY}`);
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: GET without body does NOT set Content-Type", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    await f(`${BASE}/models`); // no init at all
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Authorization"), `Bearer ${KEY}`);
+    assert.equal(
+      sentHeaders.get("Content-Type"),
+      null,
+      "Content-Type should only default when a body exists"
+    );
+  } finally {
+    restore();
+  }
+});
+
+// ----------------------------------------------------------------------------
+// loader integration
+// ----------------------------------------------------------------------------
+
+test("loader: returns fetch fn when apiKey + baseURL both present (via opts)", async () => {
+  const hook = createOmniRouteAuthHook({ baseURL: BASE });
+  const result = await hook.loader!(async () => ({ type: "api", key: KEY }) as never, {} as never);
+  assert.equal((result as { apiKey: string }).apiKey, KEY);
+  assert.equal((result as { baseURL: string }).baseURL, BASE);
+  assert.equal(
+    typeof (result as { fetch?: unknown }).fetch,
+    "function",
+    "loader must wire fetch interceptor when baseURL resolves"
+  );
+});
+
+test("loader: returns fetch fn when baseURL is stashed on the auth credential", async () => {
+  // Some auth backends attach baseURL alongside the key (post-/connect flow).
+  // The loader should pick it up even when plugin opts.baseURL is unset.
+  const hook = createOmniRouteAuthHook();
+  const result = await hook.loader!(
+    async () => ({ type: "api", key: KEY, baseURL: BASE }) as never,
+    {} as never
+  );
+  assert.equal((result as { baseURL?: string }).baseURL, BASE);
+  assert.equal(typeof (result as { fetch?: unknown }).fetch, "function");
+});
+
+test("loader: omits fetch fn when baseURL missing (apiKey-only return)", async () => {
+  const hook = createOmniRouteAuthHook(); // no baseURL opt
+  const result = await hook.loader!(async () => ({ type: "api", key: KEY }) as never, {} as never);
+  // Interceptor needs a baseURL to gate-keep; without one, fall back to
+  // apiKey-only and let the SDK use its default fetch.
+  assert.deepEqual(result, { apiKey: KEY });
+});
+
+test("loader integration: wired interceptor actually injects Bearer when invoked", async () => {
+  // End-to-end: pull the fetch fn out of the loader return and exercise it,
+  // proving the wiring matches the standalone interceptor's contract.
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const hook = createOmniRouteAuthHook({ baseURL: BASE });
+    const result = await hook.loader!(
+      async () => ({ type: "api", key: KEY }) as never,
+      {} as never
+    );
+    const wiredFetch = (result as { fetch: typeof fetch }).fetch;
+    await wiredFetch(`${BASE}/v1/models`, {});
+    assert.equal(calls.length, 1);
+    const sentHeaders = new Headers((calls[0]!.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Authorization"), `Bearer ${KEY}`);
+  } finally {
+    restore();
+  }
+});

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

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

@omniroute/opencode-plugin/tests/gemini-sanitize.test.ts

@@ -0,0 +1,410 @@
+/**
+ * T-06 Gemini tool-schema sanitisation contract tests.
+ *
+ * Three layers under test:
+ *   1. `sanitizeGeminiToolSchemas` — pure function; key stripping + clone
+ *      semantics on chat-completion + Responses-API shapes.
+ *   2. `shouldSanitizeForGemini` — model-string detection (liberal).
+ *   3. `createGeminiSanitizingFetch` — wrapper composition; URL gating,
+ *      body-shape polymorphism, streaming-body bypass, fail-open behaviour,
+ *      composition with the T-04 Bearer interceptor.
+ *
+ * Strategy: same posture as fetch-interceptor.test.ts — install a
+ * closure-based fetch recorder; assert on the `(input, init)` observed by
+ * the inner fetch after the sanitising wrapper has had its say.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  __resetGeminiStreamingWarning,
+  createGeminiSanitizingFetch,
+  createOmniRouteFetchInterceptor,
+  sanitizeGeminiToolSchemas,
+  shouldSanitizeForGemini,
+} from "../src/index.js";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ────────────────────────────────────────────────────────────────────────────
+
+type FetchCall = { input: Parameters<typeof fetch>[0]; init?: RequestInit };
+
+function recorder(response: Response = new Response("ok")): {
+  fn: typeof fetch;
+  calls: FetchCall[];
+} {
+  const calls: FetchCall[] = [];
+  const fn = (async (input: any, init?: any) => {
+    calls.push({ input, init });
+    return response;
+  }) as typeof fetch;
+  return { fn, calls };
+}
+
+function bodyAsRecord(init: RequestInit | undefined): Record<string, unknown> {
+  const b = init?.body;
+  if (typeof b !== "string") {
+    throw new Error(`expected string body, got ${typeof b}`);
+  }
+  return JSON.parse(b) as Record<string, unknown>;
+}
+
+// Sample tool payloads — small enough to inline, big enough to cover
+// chat-completion + Responses-API + nested properties.
+
+function chatCompletionsWithDollarSchema(): Record<string, unknown> {
+  return {
+    model: "gemini-2.5-pro",
+    tools: [
+      {
+        type: "function",
+        function: {
+          name: "search",
+          parameters: {
+            $schema: "http://json-schema.org/draft-07/schema#",
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              q: { type: "string" },
+            },
+            required: ["q"],
+          },
+        },
+      },
+    ],
+  };
+}
+
+function responsesApiWithRef(): Record<string, unknown> {
+  return {
+    model: "gemini-2.5-flash",
+    tools: [
+      {
+        type: "function",
+        name: "lookup",
+        input_schema: {
+          type: "object",
+          $ref: "#/definitions/Lookup",
+          properties: {
+            id: { type: "string", ref: "Id" },
+          },
+        },
+      },
+    ],
+  };
+}
+
+function nestedPropertiesPayload(): Record<string, unknown> {
+  return {
+    model: "gemini-pro",
+    tools: [
+      {
+        type: "function",
+        function: {
+          name: "deep",
+          parameters: {
+            type: "object",
+            properties: {
+              outer: {
+                type: "object",
+                $schema: "http://json-schema.org/draft-07/schema#",
+                properties: {
+                  inner: {
+                    type: "object",
+                    additionalProperties: true,
+                    $ref: "#/inner",
+                    properties: {
+                      leaf: { type: "string" },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    ],
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// sanitizeGeminiToolSchemas — pure function
+// ────────────────────────────────────────────────────────────────────────────
+
+test("sanitizeGeminiToolSchemas: strips $schema from top-level", () => {
+  const input = {
+    model: "gemini-2.5-pro",
+    $schema: "http://json-schema.org/draft-07/schema#",
+    tools: [],
+  };
+  const out = sanitizeGeminiToolSchemas(input) as Record<string, unknown>;
+  assert.equal(out.$schema, undefined);
+  assert.equal(out.model, "gemini-2.5-pro");
+});
+
+test("sanitizeGeminiToolSchemas: strips $ref + additionalProperties from tools[].function.parameters", () => {
+  const input = chatCompletionsWithDollarSchema();
+  const out = sanitizeGeminiToolSchemas(input) as Record<string, unknown>;
+  const params = (out.tools as Array<{ function: { parameters: Record<string, unknown> } }>)[0]!
+    .function.parameters;
+  assert.equal(params.$schema, undefined);
+  assert.equal(params.additionalProperties, undefined);
+  // Untouched keys survive.
+  assert.equal(params.type, "object");
+  assert.deepEqual(params.required, ["q"]);
+});
+
+test("sanitizeGeminiToolSchemas: strips nested $schema from properties.x.properties.y", () => {
+  const input = nestedPropertiesPayload();
+  const out = sanitizeGeminiToolSchemas(input) as Record<string, unknown>;
+  const params = (out.tools as Array<{ function: { parameters: Record<string, unknown> } }>)[0]!
+    .function.parameters;
+  const outer = (params.properties as Record<string, Record<string, unknown>>).outer!;
+  const inner = (outer.properties as Record<string, Record<string, unknown>>).inner!;
+  assert.equal(outer.$schema, undefined);
+  assert.equal(inner.$ref, undefined);
+  assert.equal(inner.additionalProperties, undefined);
+  // Leaf still intact.
+  assert.deepEqual(inner.properties, { leaf: { type: "string" } });
+});
+
+test("sanitizeGeminiToolSchemas: handles Responses-API tools[].input_schema shape", () => {
+  const input = responsesApiWithRef();
+  const out = sanitizeGeminiToolSchemas(input) as Record<string, unknown>;
+  const inputSchema = (out.tools as Array<{ input_schema: Record<string, unknown> }>)[0]!
+    .input_schema;
+  assert.equal(inputSchema.$ref, undefined);
+  // Nested `ref` (lowercase) also stripped.
+  const props = inputSchema.properties as Record<string, Record<string, unknown>>;
+  assert.equal(props.id!.ref, undefined);
+  assert.equal(props.id!.type, "string");
+});
+
+test("sanitizeGeminiToolSchemas: leaves payload without tools untouched", () => {
+  const input = { model: "gemini-2.5-pro", messages: [{ role: "user", content: "hi" }] };
+  const out = sanitizeGeminiToolSchemas(input) as Record<string, unknown>;
+  assert.deepEqual(out, input);
+});
+
+test("sanitizeGeminiToolSchemas: does not mutate input (returned object is distinct)", () => {
+  const input = chatCompletionsWithDollarSchema();
+  const beforeJson = JSON.stringify(input);
+  const out = sanitizeGeminiToolSchemas(input);
+  // Input bit-identical to its pre-sanitise serialisation.
+  assert.equal(JSON.stringify(input), beforeJson);
+  // Output is a different reference.
+  assert.notEqual(out, input);
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// shouldSanitizeForGemini — detection
+// ────────────────────────────────────────────────────────────────────────────
+
+test("shouldSanitizeForGemini: gemini-2.5-pro → true", () => {
+  assert.equal(shouldSanitizeForGemini({ model: "gemini-2.5-pro" }), true);
+});
+
+test("shouldSanitizeForGemini: models/gemini-pro → true", () => {
+  assert.equal(shouldSanitizeForGemini({ model: "models/gemini-pro" }), true);
+});
+
+test("shouldSanitizeForGemini: google-vertex/gemini-1.5-flash → true", () => {
+  assert.equal(shouldSanitizeForGemini({ model: "google-vertex/gemini-1.5-flash" }), true);
+});
+
+test("shouldSanitizeForGemini: gemini/gemini-2.5-pro → true", () => {
+  assert.equal(shouldSanitizeForGemini({ model: "gemini/gemini-2.5-pro" }), true);
+});
+
+test("shouldSanitizeForGemini: claude-sonnet-4 → false", () => {
+  assert.equal(shouldSanitizeForGemini({ model: "claude-sonnet-4" }), false);
+});
+
+test("shouldSanitizeForGemini: payload.model missing → false", () => {
+  assert.equal(shouldSanitizeForGemini({ messages: [] }), false);
+});
+
+test("shouldSanitizeForGemini: payload is null → false", () => {
+  assert.equal(shouldSanitizeForGemini(null), false);
+});
+
+test("shouldSanitizeForGemini: payload.model is non-string → false", () => {
+  assert.equal(shouldSanitizeForGemini({ model: 42 }), false);
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// createGeminiSanitizingFetch — wrapper
+// ────────────────────────────────────────────────────────────────────────────
+
+const URL_CHAT = "https://or.example.com/v1/chat/completions";
+const URL_RESPONSES = "https://or.example.com/v1/responses";
+const URL_MODELS = "https://or.example.com/v1/models";
+
+test("createGeminiSanitizingFetch: gemini model + chat/completions → tool schemas stripped before forward", async () => {
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+  await wrapped(URL_CHAT, {
+    method: "POST",
+    body: JSON.stringify(chatCompletionsWithDollarSchema()),
+  });
+  assert.equal(rec.calls.length, 1);
+  const forwarded = bodyAsRecord(rec.calls[0]!.init);
+  const params = (
+    forwarded.tools as Array<{ function: { parameters: Record<string, unknown> } }>
+  )[0]!.function.parameters;
+  assert.equal(params.$schema, undefined);
+  assert.equal(params.additionalProperties, undefined);
+});
+
+test("createGeminiSanitizingFetch: non-gemini model + chat/completions → body passed through unchanged", async () => {
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+  const originalBody = JSON.stringify({
+    model: "claude-sonnet-4",
+    tools: [
+      {
+        type: "function",
+        function: {
+          name: "x",
+          parameters: { $schema: "keep-me", type: "object" },
+        },
+      },
+    ],
+  });
+  await wrapped(URL_CHAT, { method: "POST", body: originalBody });
+  // Identity check on body — wrapper must NOT mutate non-Gemini payloads.
+  assert.equal(rec.calls[0]!.init!.body, originalBody);
+});
+
+test("createGeminiSanitizingFetch: gemini model + /v1/models (non-completion endpoint) → body passed through unchanged", async () => {
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+  // GET /v1/models has no body in production; assert that even if a caller
+  // attached a Gemini-shaped body to a non-completion URL, the wrapper
+  // doesn't touch it.
+  const body = JSON.stringify(chatCompletionsWithDollarSchema());
+  await wrapped(URL_MODELS, { method: "POST", body });
+  assert.equal(rec.calls[0]!.init!.body, body);
+});
+
+test("createGeminiSanitizingFetch: gemini model + /responses endpoint → input_schema stripped", async () => {
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+  await wrapped(URL_RESPONSES, {
+    method: "POST",
+    body: JSON.stringify(responsesApiWithRef()),
+  });
+  const forwarded = bodyAsRecord(rec.calls[0]!.init);
+  const schema = (forwarded.tools as Array<{ input_schema: Record<string, unknown> }>)[0]!
+    .input_schema;
+  assert.equal(schema.$ref, undefined);
+});
+
+test("createGeminiSanitizingFetch: gemini model + Request input with body → tool schemas stripped", async () => {
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+  const req = new Request(URL_CHAT, {
+    method: "POST",
+    body: JSON.stringify(chatCompletionsWithDollarSchema()),
+    headers: { "Content-Type": "application/json" },
+  });
+  await wrapped(req);
+  const forwarded = bodyAsRecord(rec.calls[0]!.init);
+  const params = (
+    forwarded.tools as Array<{ function: { parameters: Record<string, unknown> } }>
+  )[0]!.function.parameters;
+  assert.equal(params.$schema, undefined);
+});
+
+test("createGeminiSanitizingFetch: gemini model + ReadableStream body → skipped + warn emitted once", async () => {
+  __resetGeminiStreamingWarning();
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+
+  // Capture console.warn for the duration of this test.
+  const warnings: string[] = [];
+  const originalWarn = console.warn;
+  console.warn = (...args: unknown[]) => {
+    warnings.push(args.map(String).join(" "));
+  };
+
+  try {
+    const stream1 = new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode("{}"));
+        controller.close();
+      },
+    });
+    const stream2 = new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode("{}"));
+        controller.close();
+      },
+    });
+    // Two streaming calls — only one warn expected.
+    await wrapped(URL_CHAT, { method: "POST", body: stream1 });
+    await wrapped(URL_CHAT, { method: "POST", body: stream2 });
+  } finally {
+    console.warn = originalWarn;
+  }
+
+  // Both calls forwarded to inner fetch with their streams intact.
+  assert.equal(rec.calls.length, 2);
+  // ONE warning total — one-shot latch held.
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0]!, /streaming Request body, skipping schema strip/);
+});
+
+test("createGeminiSanitizingFetch: invalid JSON body → pass through, no throw", async () => {
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+  // Garbage body must not crash the wrapper.
+  await wrapped(URL_CHAT, { method: "POST", body: "this is not json{{" });
+  assert.equal(rec.calls.length, 1);
+  assert.equal(rec.calls[0]!.init!.body, "this is not json{{");
+});
+
+test("createGeminiSanitizingFetch: empty body → pass through unchanged", async () => {
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+  await wrapped(URL_CHAT, { method: "POST" });
+  assert.equal(rec.calls.length, 1);
+});
+
+test("createGeminiSanitizingFetch: composes correctly with createOmniRouteFetchInterceptor (Bearer + sanitization)", async () => {
+  // Save and replace globalThis.fetch — the Bearer interceptor calls global
+  // fetch when the URL targets its baseURL.
+  const originalFetch = globalThis.fetch;
+  const observed: FetchCall[] = [];
+  globalThis.fetch = (async (input: any, init?: any) => {
+    observed.push({ input, init });
+    return new Response("ok");
+  }) as typeof fetch;
+
+  try {
+    const composed = createGeminiSanitizingFetch(
+      createOmniRouteFetchInterceptor({
+        apiKey: "sk-test",
+        baseURL: "https://or.example.com/v1",
+      })
+    );
+    await composed(URL_CHAT, {
+      method: "POST",
+      body: JSON.stringify(chatCompletionsWithDollarSchema()),
+    });
+
+    assert.equal(observed.length, 1);
+    // Bearer injected (header concern).
+    const sentHeaders = new Headers((observed[0]!.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Authorization"), "Bearer sk-test");
+    // Schema sanitised (body concern).
+    const forwarded = bodyAsRecord(observed[0]!.init);
+    const params = (
+      forwarded.tools as Array<{ function: { parameters: Record<string, unknown> } }>
+    )[0]!.function.parameters;
+    assert.equal(params.$schema, undefined);
+    assert.equal(params.additionalProperties, undefined);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});

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

@@ -0,0 +1,136 @@
+/**
+ * T-08 multi-instance smoke.
+ *
+ * Validates that two `OmniRoutePlugin(input, opts)` invocations with
+ * different `providerId` values coexist without sharing mutable state.
+ * This is the contract that lets opencode.json declare prod + preprod
+ * side by side:
+ *
+ *   "plugin": [
+ *     ["@omniroute/opencode-plugin", {"providerId": "omniroute-prod",    "baseURL": "https://or.example/v1"}],
+ *     ["@omniroute/opencode-plugin", {"providerId": "omniroute-preprod", "baseURL": "https://or-preprod.example/v1"}]
+ *   ]
+ *
+ * Assertions:
+ *   - Each invocation returns its own hooks object (no identity reuse).
+ *   - Each `auth` hook carries its own `provider` matching opts.providerId.
+ *   - Each `auth.methods` array is its own array (not the same reference).
+ *   - Calling the factory twice with IDENTICAL opts still yields two
+ *     independent objects (no instance reuse / no shared closure cache).
+ *   - Mutating one instance's auth hook does NOT bleed into the other.
+ *   - Each instance's loader closure captures its OWN baseURL — no
+ *     last-write-wins module-scope state.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { OmniRoutePlugin } from "../src/index.js";
+
+const fakeInput = {} as Parameters<typeof OmniRoutePlugin>[0];
+
+test("multi-instance: two plugin invocations bind to their own providerId", async () => {
+  const a = await OmniRoutePlugin(fakeInput, {
+    providerId: "omniroute-prod",
+    baseURL: "https://a.example/v1",
+  });
+  const b = await OmniRoutePlugin(fakeInput, {
+    providerId: "omniroute-preprod",
+    baseURL: "https://b.example/v1",
+  });
+
+  assert.equal(a.auth?.provider, "opencode-omniroute-prod");
+  assert.equal(b.auth?.provider, "opencode-omniroute-preprod");
+});
+
+test("multi-instance: hook objects + nested arrays are independent references", async () => {
+  const a = await OmniRoutePlugin(fakeInput, {
+    providerId: "alpha",
+    baseURL: "https://a.example/v1",
+  });
+  const b = await OmniRoutePlugin(fakeInput, {
+    providerId: "bravo",
+    baseURL: "https://b.example/v1",
+  });
+
+  assert.notEqual(a, b, "top-level hooks objects must not be the same reference");
+  assert.notEqual(a.auth, b.auth, "auth hooks must not be the same reference");
+  assert.notEqual(
+    a.auth?.methods,
+    b.auth?.methods,
+    "methods arrays must not be the same reference"
+  );
+});
+
+test("multi-instance: identical opts twice still yield independent objects", async () => {
+  const opts = { providerId: "twin", baseURL: "https://twin.example/v1" };
+  const first = await OmniRoutePlugin(fakeInput, { ...opts });
+  const second = await OmniRoutePlugin(fakeInput, { ...opts });
+
+  assert.notEqual(first, second);
+  assert.notEqual(first.auth, second.auth);
+  assert.notEqual(first.auth?.methods, second.auth?.methods);
+  // Same provider id is fine — what matters is no shared mutable state.
+  assert.equal(first.auth?.provider, "opencode-twin");
+  assert.equal(second.auth?.provider, "opencode-twin");
+});
+
+test("multi-instance: mutating instance A's auth.methods does not affect instance B", async () => {
+  const a = await OmniRoutePlugin(fakeInput, {
+    providerId: "iso-a",
+    baseURL: "https://a.example/v1",
+  });
+  const b = await OmniRoutePlugin(fakeInput, {
+    providerId: "iso-b",
+    baseURL: "https://b.example/v1",
+  });
+
+  const beforeLen = b.auth?.methods?.length ?? 0;
+  // Mutate a's methods array — extend it; b's must be untouched.
+  // We don't know the concrete method shape so push a sentinel cast.
+  a.auth?.methods?.push({ type: "api", label: "sentinel" } as never);
+  assert.equal(b.auth?.methods?.length, beforeLen, "instance B leaked from instance A mutation");
+});
+
+test("multi-instance: loader closures see their own opts (not last-write-wins)", async () => {
+  // Each plugin's loader builds its loader payload from the providerId/baseURL
+  // captured at invocation time. If the factory accidentally shared a closure
+  // (e.g. a module-scope let that the last invocation overwrites), both
+  // loaders would emit the same baseURL. Verify they don't.
+  const a = await OmniRoutePlugin(fakeInput, {
+    providerId: "omniroute-prod",
+    baseURL: "https://prod.example/v1",
+  });
+  const b = await OmniRoutePlugin(fakeInput, {
+    providerId: "omniroute-preprod",
+    baseURL: "https://preprod.example/v1",
+  });
+
+  assert.ok(a.auth?.loader, "instance A must have a loader");
+  assert.ok(b.auth?.loader, "instance B must have a loader");
+
+  const getAuthA = async () => ({ type: "api", key: "sk-prod" }) as never;
+  const getAuthB = async () => ({ type: "api", key: "sk-preprod" }) as never;
+
+  const rA = (await a.auth!.loader!(getAuthA, {} as never)) as Record<string, unknown>;
+  const rB = (await b.auth!.loader!(getAuthB, {} as never)) as Record<string, unknown>;
+
+  assert.equal(rA.apiKey, "sk-prod");
+  assert.equal(rA.baseURL, "https://prod.example/v1");
+  assert.equal(rB.apiKey, "sk-preprod");
+  assert.equal(rB.baseURL, "https://preprod.example/v1");
+});
+
+test("multi-instance: invalid opts on one instance does not poison the other", async () => {
+  // Sequencing: bad opts → good opts. The bad call must throw cleanly; the
+  // good call must still produce a working hooks object. Confirms no
+  // half-built module-level state survives a failed parse.
+  await assert.rejects(
+    () => OmniRoutePlugin(fakeInput, { providerId: "bad id!" } as never),
+    /providerId/
+  );
+  const ok = await OmniRoutePlugin(fakeInput, {
+    providerId: "recovered",
+    baseURL: "https://ok.example/v1",
+  });
+  assert.equal(ok.auth?.provider, "opencode-recovered");
+});

@omniroute/opencode-plugin/tests/options-schema.test.ts

@@ -0,0 +1,104 @@
+/**
+ * T-08 options-schema tests.
+ *
+ * Covers `parseOmniRoutePluginOptions(opts)` — the strict Zod gate that
+ * validates the second-arg `PluginOptions` bag from opencode.json before
+ * any hook is wired. Anti-pattern checklist mirrored here:
+ *
+ *  - `null` / `undefined` must collapse to `{}` (defaults apply downstream).
+ *  - Unknown keys must THROW (`.strict()` catches opencode.json typos).
+ *  - Validation runs at parse time, not import time (module loads cleanly).
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseOmniRoutePluginOptions } from "../src/index.js";
+
+test("parseOmniRoutePluginOptions: undefined → {}", () => {
+  assert.deepEqual(parseOmniRoutePluginOptions(undefined), {});
+});
+
+test("parseOmniRoutePluginOptions: null → {}", () => {
+  assert.deepEqual(parseOmniRoutePluginOptions(null), {});
+});
+
+test("parseOmniRoutePluginOptions: empty object → {}", () => {
+  assert.deepEqual(parseOmniRoutePluginOptions({}), {});
+});
+
+test("parseOmniRoutePluginOptions: valid providerId → returns it", () => {
+  const r = parseOmniRoutePluginOptions({ providerId: "omniroute-preprod" });
+  assert.equal(r.providerId, "omniroute-preprod");
+});
+
+test("parseOmniRoutePluginOptions: invalid providerId (special chars) → throws", () => {
+  assert.throws(
+    () => parseOmniRoutePluginOptions({ providerId: "omniroute prod!" }),
+    /providerId.*slug/i
+  );
+});
+
+test("parseOmniRoutePluginOptions: empty providerId → throws", () => {
+  assert.throws(() => parseOmniRoutePluginOptions({ providerId: "" }), /providerId/i);
+});
+
+test("parseOmniRoutePluginOptions: valid modelCacheTtl → returns it", () => {
+  const r = parseOmniRoutePluginOptions({ modelCacheTtl: 60_000 });
+  assert.equal(r.modelCacheTtl, 60_000);
+});
+
+test("parseOmniRoutePluginOptions: negative modelCacheTtl → throws", () => {
+  assert.throws(() => parseOmniRoutePluginOptions({ modelCacheTtl: -1 }), /modelCacheTtl/i);
+});
+
+test("parseOmniRoutePluginOptions: zero modelCacheTtl → throws (positive required)", () => {
+  assert.throws(() => parseOmniRoutePluginOptions({ modelCacheTtl: 0 }), /modelCacheTtl/i);
+});
+
+test("parseOmniRoutePluginOptions: invalid baseURL (not a URL) → throws", () => {
+  assert.throws(() => parseOmniRoutePluginOptions({ baseURL: "not-a-url" }), /baseURL/i);
+});
+
+test("parseOmniRoutePluginOptions: unknown key → throws (strict mode catches typos)", () => {
+  assert.throws(
+    () =>
+      parseOmniRoutePluginOptions({
+        providerId: "omniroute",
+        provider_id: "typo-here",
+      }),
+    /provider_id|unrecognized/i
+  );
+});
+
+test("parseOmniRoutePluginOptions: all four fields populated correctly → returns them", () => {
+  const opts = {
+    providerId: "omniroute-prod",
+    displayName: "OmniRoute Production",
+    modelCacheTtl: 120_000,
+    baseURL: "https://or.example.com/v1",
+  };
+  const r = parseOmniRoutePluginOptions(opts);
+  assert.deepEqual(r, opts);
+});
+
+test("parseOmniRoutePluginOptions: error message lists every issue path", () => {
+  // Two bad fields at once → error string should mention BOTH.
+  try {
+    parseOmniRoutePluginOptions({
+      providerId: "",
+      baseURL: "garbage",
+    });
+    assert.fail("expected throw");
+  } catch (err) {
+    const msg = (err as Error).message;
+    assert.match(msg, /providerId/);
+    assert.match(msg, /baseURL/);
+  }
+});
+
+test("parseOmniRoutePluginOptions: module import alone does NOT throw", async () => {
+  // Re-importing the entry must not trigger validation; validation only fires
+  // on explicit parseOmniRoutePluginOptions / OmniRoutePlugin invocation.
+  const mod = await import("../src/index.js");
+  assert.equal(typeof mod.parseOmniRoutePluginOptions, "function");
+});

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

@@ -0,0 +1,99 @@
+/**
+ * Regression test for #6859.
+ *
+ * `resolveOmniRoutePluginOptions()` auto-prefixes `providerId` with
+ * `"opencode-"` (commit 75b52e286) so OpenCode 1.17.8+'s native-adapter gate
+ * accepts it as an OC-registered provider id. That prefixed value must stay
+ * OC-internal (AuthHook.provider / provider registration keys) — it must
+ * NEVER leak into the identifiers OmniRoute's own server parses to resolve
+ * credentials (`mapRawModelToModelV2`'s `id`/`providerID`,
+ * `mapComboToModelV2`'s `providerID`, and the dynamic-hook catalog keys).
+ *
+ * OmniRoute's server-side `parseModel()` (open-sse/services/model.ts) splits
+ * a dispatched model string on `/` to recover the provider name and look up
+ * credentials. If the plugin embeds the OC-gate-prefixed id in that string,
+ * the server looks up credentials for a provider named "opencode-omniroute"
+ * (which never exists in `src/shared/constants/providers.ts`) instead of
+ * "omniroute" — producing the exact "No credentials for opencode-omniroute" /
+ * "No active credentials for provider: opencode-omniroute" errors reported
+ * in #6859.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  createOmniRouteProviderHook,
+  mapRawModelToModelV2,
+  resolveOmniRoutePluginOptions,
+} from "../src/index.js";
+
+/**
+ * Minimal stand-in for OmniRoute's own `parseModel()` (open-sse/services/
+ * model.ts), which splits a dispatched `<providerID>/<modelID>` string on the
+ * FIRST "/" to recover the provider name used for credential lookup. Kept
+ * local (rather than cross-importing the real module) so this package's
+ * self-contained test suite (`cd @omniroute/opencode-plugin && npm test`)
+ * doesn't depend on the root repo's `@/*` path-alias resolution.
+ */
+function splitProviderFromDispatchedModel(modelStr: string): string {
+  const idx = modelStr.indexOf("/");
+  return idx === -1 ? modelStr : modelStr.slice(0, idx);
+}
+
+const apiAuth = (key: string) => ({ type: "api" as const, key });
+
+test("#6859: server-facing model id/providerID must resolve to the unprefixed provider name", () => {
+  const resolved = resolveOmniRoutePluginOptions();
+
+  // The OC-gate-compatible id stays prefixed — it is legitimate for
+  // AuthHook.provider / provider registration.
+  assert.equal(resolved.providerId, "opencode-omniroute");
+
+  // A second, unprefixed id must be exposed for anything that reaches
+  // OmniRoute's own server (model id prefix, ModelV2.providerID, combo keys).
+  assert.equal(
+    resolved.omnirouteProviderId,
+    "omniroute",
+    "resolveOmniRoutePluginOptions() must expose an unprefixed omnirouteProviderId"
+  );
+
+  // A bare raw /v1/models entry (no existing "/" in its id — the common
+  // case for OmniRoute's catalog) mapped with the server-facing id.
+  const model = mapRawModelToModelV2(
+    { id: "claude-opus-4-7" },
+    { providerId: resolved.omnirouteProviderId, baseURL: "http://localhost:20128" }
+  );
+
+  assert.equal(model.providerID, "omniroute");
+  assert.equal(model.id, "omniroute/claude-opus-4-7");
+
+  // OpenCode dispatches back to OmniRoute using `providerID/modelKey`
+  // (matches the issue's own repro: `-m opencode-omniroute/oc/big-pickle`).
+  const dispatchedModelString = `${model.providerID}/claude-opus-4-7`;
+  const parsedProvider = splitProviderFromDispatchedModel(dispatchedModelString);
+
+  assert.equal(
+    parsedProvider,
+    "omniroute",
+    `server-side provider split resolved '${parsedProvider}', expected 'omniroute' — ` +
+      `credentials lookup would fail for an OC-gate-prefixed provider id`
+  );
+});
+
+test("#6859: createOmniRouteProviderHook end-to-end — catalog keys/providerID never carry the OC-gate prefix", async () => {
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    {
+      fetcher: async () => [{ id: "claude-opus-4-7" }],
+      combosFetcher: async () => [],
+    }
+  );
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-test") as never });
+  const model = out["omniroute/claude-opus-4-7"];
+  assert.ok(model, "catalog keyed under the unprefixed provider name");
+  assert.equal(model.providerID, "omniroute");
+  assert.ok(
+    !model.providerID.startsWith("opencode-"),
+    "the OC-gate prefix must never leak into ModelV2.providerID"
+  );
+});

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

@@ -0,0 +1,278 @@
+/**
+ * T-03 provider-hook contract tests.
+ *
+ * Covers `createOmniRouteProviderHook(opts, deps)`:
+ *   - hook.id binds to resolved providerId (single + multi-instance)
+ *   - models() narrows ctx.auth, fetches via injected fetcher, caches per
+ *     (baseURL, apiKey) tuple, refetches after TTL
+ *   - mapRawModelToModelV2 emits a v2 Model shape matching the
+ *     @opencode-ai/sdk/v2 type
+ *
+ * Mocking strategy: the fetcher is dependency-injected at hook construction
+ * (`deps.fetcher`). No global fetch monkey-patch needed. `deps.now` lets us
+ * fast-forward time deterministically for TTL assertions.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  createOmniRouteProviderHook,
+  mapRawModelToModelV2,
+  type OmniRouteRawModelEntry,
+  type OmniRouteModelsFetcher,
+} from "../src/index.js";
+
+const FIXTURE: OmniRouteRawModelEntry[] = [
+  {
+    id: "claude-primary",
+    object: "model",
+    owned_by: "combo",
+    capabilities: { tool_calling: true, reasoning: true, vision: true, thinking: true },
+    context_length: 200000,
+    max_output_tokens: 64000,
+    input_modalities: ["text", "image"],
+    output_modalities: ["text"],
+  },
+  {
+    id: "claude-low",
+    object: "model",
+    owned_by: "combo",
+    capabilities: { tool_calling: true, reasoning: true, vision: true, thinking: false },
+    context_length: 200000,
+    max_output_tokens: 64000,
+    input_modalities: ["text", "image"],
+    output_modalities: ["text"],
+  },
+  {
+    id: "gemini-3-flash",
+    object: "model",
+    owned_by: "google",
+    capabilities: { tool_calling: true, reasoning: false, vision: true, thinking: false },
+    context_length: 1000000,
+    max_output_tokens: 8192,
+    input_modalities: ["text", "image"],
+    output_modalities: ["text"],
+  },
+];
+
+function stubFetcher(payload: OmniRouteRawModelEntry[]): OmniRouteModelsFetcher & {
+  callCount: () => number;
+  callsBy: () => Array<[string, string]>;
+} {
+  let calls: Array<[string, string]> = [];
+  const f: OmniRouteModelsFetcher = async (baseURL, apiKey) => {
+    calls.push([baseURL, apiKey]);
+    return payload;
+  };
+  return Object.assign(f, {
+    callCount: () => calls.length,
+    callsBy: () => calls,
+  });
+}
+
+const apiAuth = (key: string, baseURL?: string): unknown =>
+  baseURL ? { type: "api", key, baseURL } : { type: "api", key };
+
+test("createOmniRouteProviderHook: default providerId is 'omniroute'", () => {
+  const hook = createOmniRouteProviderHook(undefined, { combosFetcher: async () => [] });
+  assert.equal(hook.id, "opencode-omniroute");
+});
+
+test("createOmniRouteProviderHook: custom providerId binds to hook.id (multi-instance)", () => {
+  const a = createOmniRouteProviderHook(
+    { providerId: "omniroute-preprod" },
+    { combosFetcher: async () => [] }
+  );
+  const b = createOmniRouteProviderHook(
+    { providerId: "omniroute-local" },
+    { combosFetcher: async () => [] }
+  );
+  assert.equal(a.id, "opencode-omniroute-preprod");
+  assert.equal(b.id, "opencode-omniroute-local");
+});
+
+test("models: extracts apiKey from ctx.auth (type=api) and calls fetcher with it", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher, combosFetcher: async () => [] }
+  );
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-abc") as never });
+  assert.equal(fetcher.callCount(), 1);
+  assert.deepEqual(fetcher.callsBy()[0], ["https://or.example.com/v1", "sk-abc"]);
+  assert.equal(Object.keys(out).length, 3);
+  // #6859: dynamic-hook catalog keys use the unprefixed omnirouteProviderId
+  // ("omniroute"), not the OC-gate-prefixed hook.id ("opencode-omniroute") —
+  // that prefix must never leak into anything OmniRoute's server parses.
+  assert.ok(out["omniroute/claude-primary"]);
+});
+
+test("models: returns {} when ctx.auth is null/undefined/wrong-type/empty-key", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher, combosFetcher: async () => [] }
+  );
+
+  assert.deepEqual(await hook.models!({} as never, {} as never), {});
+  assert.deepEqual(await hook.models!({} as never, { auth: undefined } as never), {});
+  assert.deepEqual(
+    await hook.models!({} as never, {
+      auth: { type: "oauth", refresh: "r", access: "a", expires: 0 } as never,
+    }),
+    {}
+  );
+  assert.deepEqual(
+    await hook.models!({} as never, { auth: { type: "api", key: "" } as never }),
+    {}
+  );
+  assert.equal(fetcher.callCount(), 0, "fetcher must not be called on auth rejection");
+});
+
+test("models: returns {} when no baseURL resolvable (no opts.baseURL and no auth.baseURL)", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  const hook = createOmniRouteProviderHook({}, { fetcher, combosFetcher: async () => [] });
+  // valid api auth but neither opts nor auth carries a baseURL
+  assert.deepEqual(await hook.models!({} as never, { auth: apiAuth("sk-x") as never }), {});
+  assert.equal(fetcher.callCount(), 0);
+});
+
+test("models: baseURL falls back to auth.baseURL when opts.baseURL absent", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  const hook = createOmniRouteProviderHook({}, { fetcher, combosFetcher: async () => [] });
+  const out = await hook.models!({} as never, {
+    auth: apiAuth("sk-y", "https://or.creds-attached.example/v1") as never,
+  });
+  assert.equal(fetcher.callCount(), 1);
+  assert.equal(fetcher.callsBy()[0][0], "https://or.creds-attached.example/v1");
+  assert.equal(Object.keys(out).length, 3);
+});
+
+test("models: maps a sample /v1/models entry to ModelV2 (sanity)", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  const hook = createOmniRouteProviderHook(
+    { providerId: "omniroute", baseURL: "https://or.example.com/v1" },
+    { fetcher, combosFetcher: async () => [] }
+  );
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-abc") as never });
+  // #6859: dynamic-hook catalog keys/ids/providerID use the unprefixed
+  // omnirouteProviderId ("omniroute") — the OC-gate prefix ("opencode-")
+  // must stay OC-internal (hook.id / AuthHook.provider) and never leak into
+  // anything OmniRoute's own server parses for credential lookup.
+  const claude = out["omniroute/claude-primary"];
+  assert.ok(claude, "claude-primary present");
+  // `mapRawModelToModelV2` stamps the provider prefix on the id so OC's
+  // static-catalog reader resolves `(providerID, modelID)` from the key.
+  assert.equal(claude.id, "omniroute/claude-primary");
+  assert.equal(claude.name, "claude-primary");
+  assert.equal(claude.providerID, "omniroute");
+  assert.equal(claude.api.id, "openai-compatible");
+  assert.equal(claude.api.url, "https://or.example.com/v1");
+  assert.equal(claude.api.npm, "@ai-sdk/openai-compatible");
+  // capabilities: toolcall (one word), reasoning OR thinking, attachment = vision
+  assert.equal(claude.capabilities.toolcall, true);
+  assert.equal(claude.capabilities.reasoning, true);
+  assert.equal(claude.capabilities.attachment, true);
+  assert.equal(claude.capabilities.temperature, true);
+  // modalities mapped from arrays
+  assert.equal(claude.capabilities.input.text, true);
+  assert.equal(claude.capabilities.input.image, true);
+  assert.equal(claude.capabilities.input.audio, false);
+  assert.equal(claude.capabilities.output.text, true);
+  assert.equal(claude.capabilities.output.image, false);
+  // cost is zeroed (OmniRoute /v1/models has no pricing)
+  assert.deepEqual(claude.cost, { input: 0, output: 0, cache: { read: 0, write: 0 } });
+  // limits
+  assert.equal(claude.limit.context, 200000);
+  assert.equal(claude.limit.output, 64000);
+  assert.equal(claude.status, "active");
+});
+
+test("mapRawModelToModelV2: thinking-only model still surfaces reasoning=true", () => {
+  const m = mapRawModelToModelV2(
+    {
+      id: "thinking-only",
+      capabilities: { thinking: true, reasoning: false },
+      context_length: 100000,
+      max_output_tokens: 8192,
+    },
+    { providerId: "omniroute", baseURL: "https://or.example.com/v1" }
+  );
+  assert.equal(m.capabilities.reasoning, true);
+});
+
+test("mapRawModelToModelV2: missing capabilities defaults to all-false (except temperature)", () => {
+  const m = mapRawModelToModelV2(
+    { id: "minimal" },
+    { providerId: "omniroute", baseURL: "https://or.example.com/v1" }
+  );
+  assert.equal(m.capabilities.temperature, true);
+  assert.equal(m.capabilities.reasoning, false);
+  assert.equal(m.capabilities.attachment, false);
+  assert.equal(m.capabilities.toolcall, false);
+  // default modalities = text only
+  assert.equal(m.capabilities.input.text, true);
+  assert.equal(m.capabilities.output.text, true);
+  // missing context / output tokens → 0 fallback (ModelV2.limit.{context,output} required)
+  assert.equal(m.limit.context, 0);
+  assert.equal(m.limit.output, 0);
+});
+
+test("models: caches result for second call within TTL (fetcher called once)", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  let nowMs = 1_000_000;
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1", modelCacheTtl: 60_000 },
+    { fetcher, now: () => nowMs, combosFetcher: async () => [] }
+  );
+
+  const a = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  nowMs += 30_000; // half the TTL
+  const b = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  assert.equal(fetcher.callCount(), 1, "second call within TTL must hit the cache");
+  assert.equal(Object.keys(a).length, 3);
+  assert.equal(Object.keys(b).length, 3);
+});
+
+test("models: refetches after TTL expires", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  let nowMs = 1_000_000;
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1", modelCacheTtl: 60_000 },
+    { fetcher, now: () => nowMs, combosFetcher: async () => [] }
+  );
+
+  await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  nowMs += 60_001; // just past the TTL
+  await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  assert.equal(fetcher.callCount(), 2, "call past TTL must refetch");
+});
+
+test("models: caches per (baseURL, apiKey) tuple (different keys → independent fetches)", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1", modelCacheTtl: 300_000 },
+    { fetcher, combosFetcher: async () => [] }
+  );
+
+  await hook.models!({} as never, { auth: apiAuth("sk-A") as never });
+  await hook.models!({} as never, { auth: apiAuth("sk-B") as never });
+  await hook.models!({} as never, { auth: apiAuth("sk-A") as never }); // cached
+  await hook.models!({} as never, { auth: apiAuth("sk-B") as never }); // cached
+  assert.equal(fetcher.callCount(), 2, "one fetch per distinct apiKey, then cache hits");
+});
+
+test("models: caches per (baseURL, apiKey) tuple (different baseURL → independent fetches)", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  const hook = createOmniRouteProviderHook(
+    { modelCacheTtl: 300_000 }, // no opts.baseURL → falls back to auth.baseURL
+    { fetcher, combosFetcher: async () => [] }
+  );
+
+  await hook.models!({} as never, { auth: apiAuth("sk-same", "https://prod.example/v1") as never });
+  await hook.models!({} as never, {
+    auth: apiAuth("sk-same", "https://preprod.example/v1") as never,
+  });
+  await hook.models!({} as never, { auth: apiAuth("sk-same", "https://prod.example/v1") as never }); // cached
+  assert.equal(fetcher.callCount(), 2, "distinct baseURLs share apiKey but not cache");
+});

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

@@ -0,0 +1,73 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  OmniRoutePlugin,
+  OMNIROUTE_PROVIDER_KEY,
+  DEFAULT_MODEL_CACHE_TTL_MS,
+  resolveOmniRoutePluginOptions,
+} from "../src/index.js";
+
+test("scaffold: exports public surface", () => {
+  assert.equal(
+    typeof OmniRoutePlugin,
+    "function",
+    "OmniRoutePlugin must be a function (Plugin factory)"
+  );
+  assert.equal(OMNIROUTE_PROVIDER_KEY, "omniroute");
+  assert.equal(DEFAULT_MODEL_CACHE_TTL_MS, 300_000);
+});
+
+test("scaffold: default export is v1 plugin shape { id, server: OmniRoutePlugin }", async () => {
+  const mod = await import("../src/index.js");
+  assert.equal(typeof mod.default, "object");
+  assert.equal(mod.default.id, "@omniroute/opencode-plugin");
+  assert.equal(mod.default.server, mod.OmniRoutePlugin);
+});
+
+test("resolveOmniRoutePluginOptions: defaults", () => {
+  const r = resolveOmniRoutePluginOptions();
+  assert.equal(r.providerId, "opencode-omniroute");
+  assert.equal(r.displayName, "OmniRoute");
+  assert.equal(r.modelCacheTtl, 300_000);
+  assert.equal(r.baseURL, undefined);
+});
+
+test("resolveOmniRoutePluginOptions: custom providerId derives displayName", () => {
+  const r = resolveOmniRoutePluginOptions({ providerId: "omniroute-preprod" });
+  assert.equal(r.providerId, "opencode-omniroute-preprod");
+  assert.equal(r.displayName, "OmniRoute (opencode-omniroute-preprod)");
+});
+
+test("resolveOmniRoutePluginOptions: explicit displayName wins", () => {
+  const r = resolveOmniRoutePluginOptions({
+    providerId: "omniroute-x",
+    displayName: "Custom Label",
+  });
+  assert.equal(r.displayName, "Custom Label");
+});
+
+test("resolveOmniRoutePluginOptions: invalid TTL falls back to default", () => {
+  assert.equal(resolveOmniRoutePluginOptions({ modelCacheTtl: 0 }).modelCacheTtl, 300_000);
+  assert.equal(resolveOmniRoutePluginOptions({ modelCacheTtl: -1 }).modelCacheTtl, 300_000);
+});
+
+test("resolveOmniRoutePluginOptions: positive TTL respected", () => {
+  assert.equal(resolveOmniRoutePluginOptions({ modelCacheTtl: 60_000 }).modelCacheTtl, 60_000);
+});
+
+test("OmniRoutePlugin: returns an empty hooks object (scaffold)", async () => {
+  const fakeCtx = {} as Parameters<typeof OmniRoutePlugin>[0];
+  const hooks = await OmniRoutePlugin(fakeCtx);
+  assert.equal(typeof hooks, "object");
+  assert.notEqual(hooks, null);
+});
+
+test("scaffold: built ESM default export resolves with the v1 plugin shape", async () => {
+  // The plugin is ESM-only now — the CJS bundle was dropped to fix the OpenCode
+  // loader (#3883), so there is no more ../dist/index.cjs. Validate that the built
+  // distributable's default export still carries the OpenCode v1 { id, server } shape.
+  const mod = await import("../dist/index.js");
+  assert.strictEqual(typeof mod.default, "object");
+  assert.strictEqual(mod.default.id, "@omniroute/opencode-plugin");
+  assert.strictEqual(typeof mod.default.server, "function");
+});

@omniroute/opencode-plugin/tests/usable-combo.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Regression tests for `isUsableCombo` (release/v3.8.2 code review, finding C1).
+ *
+ * The combo member refs returned by `/api/combos` do NOT carry a separate
+ * `providerId` field — OmniRoute's `normalizeComboRecord` folds the provider
+ * id INTO the full model string (e.g. "cc/claude-opus-4-7"). The previous
+ * implementation read `step.providerId` (always `undefined`), so the
+ * `usableOnly` combo filter silently never dropped anything. These tests pin
+ * the corrected behavior: the verdict is derived from the `step.model` prefix,
+ * mirroring `isUsableRawModelId`'s subtract-filter semantics.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { isUsableCombo, type OmniRouteRawCombo } from "../src/index.js";
+
+/** Build a `usable` set bundle for the tests. */
+function buildUsable(opts: { aliases?: string[]; canonicals?: string[]; known?: string[] }): {
+  aliases: Set<string>;
+  canonicals: Set<string>;
+  knownAliases: Set<string>;
+} {
+  return {
+    aliases: new Set(opts.aliases ?? []),
+    canonicals: new Set(opts.canonicals ?? []),
+    // knownAliases is the union of every prefix the universe is aware of —
+    // usable or not. Default to including the usable aliases too.
+    knownAliases: new Set([...(opts.known ?? []), ...(opts.aliases ?? [])]),
+  };
+}
+
+function combo(models: OmniRouteRawCombo["models"]): OmniRouteRawCombo {
+  return { id: "c1", name: "Test Combo", models };
+}
+
+test("isUsableCombo: member with a usable alias prefix → keep", () => {
+  const usable = buildUsable({ aliases: ["cc"], known: ["cc", "dead"] });
+  const c = combo([{ kind: "model", model: "cc/claude-opus-4-7" }]);
+  assert.equal(isUsableCombo(c, usable), true);
+});
+
+test("isUsableCombo: all members known-but-NOT-usable → drop (the C1 regression)", () => {
+  // Before the fix this returned true unconditionally because step.providerId
+  // was always undefined. Now the known-but-unusable "dead" prefix is dropped.
+  const usable = buildUsable({ aliases: ["cc"], known: ["cc", "dead"] });
+  const c = combo([
+    { kind: "model", model: "dead/legacy-model" },
+    { kind: "model", model: "dead/another" },
+  ]);
+  assert.equal(isUsableCombo(c, usable), false);
+});
+
+test("isUsableCombo: unknown prefix → keep (cannot prove unroutable)", () => {
+  const usable = buildUsable({ aliases: ["cc"], known: ["cc", "dead"] });
+  const c = combo([{ kind: "model", model: "agentrouter/mystery" }]);
+  assert.equal(isUsableCombo(c, usable), true);
+});
+
+test("isUsableCombo: mixed non-usable + usable member → keep", () => {
+  const usable = buildUsable({ aliases: ["cc"], known: ["cc", "dead"] });
+  const c = combo([
+    { kind: "model", model: "dead/legacy" },
+    { kind: "model", model: "cc/claude-opus-4-7" },
+  ]);
+  assert.equal(isUsableCombo(c, usable), true);
+});
+
+test("isUsableCombo: zero members → keep", () => {
+  const usable = buildUsable({ aliases: ["cc"], known: ["cc"] });
+  assert.equal(isUsableCombo(combo([]), usable), true);
+  assert.equal(isUsableCombo(combo(undefined), usable), true);
+});
+
+test("isUsableCombo: only combo-ref steps (no resolvable model) → keep", () => {
+  const usable = buildUsable({ aliases: ["cc"], known: ["cc", "dead"] });
+  const c = combo([{ kind: "combo-ref", comboName: "nested" }]);
+  assert.equal(isUsableCombo(c, usable), true);
+});
+
+test("isUsableCombo: usable canonical prefix → keep", () => {
+  const usable = buildUsable({ canonicals: ["anthropic"], known: ["anthropic", "dead"] });
+  const c = combo([{ kind: "model", model: "anthropic/claude-opus-4-7" }]);
+  assert.equal(isUsableCombo(c, usable), true);
+});

@omniroute/opencode-plugin/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUncheckedIndexedAccess": false,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "node_modules", "tests"]
+}

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

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

@omniroute/opencode-provider/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.log
+.DS_Store

@omniroute/opencode-provider/.npmignore

@@ -0,0 +1,7 @@
+src
+tests
+tsconfig.json
+tsup.config.ts
+node_modules
+.DS_Store
+*.log

@omniroute/opencode-provider/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OmniRoute contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

@omniroute/opencode-provider/README.md

@@ -0,0 +1,156 @@
+# @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.
+
+> Pre-1.0. The API may still change. See `CHANGELOG` in the OmniRoute repo for breaking notes.
+
+## Installation
+
+```bash
+npm install --save-dev @omniroute/opencode-provider
+# or
+pnpm add -D @omniroute/opencode-provider
+```
+
+You also need OpenCode's own runtime dep, but that's a transitive concern — OpenCode itself ships with `@ai-sdk/openai-compatible`. This package only **generates configuration**.
+
+## Quick start
+
+### 1. Scaffold a fresh `opencode.json`
+
+```ts
+import { writeFileSync } from "node:fs";
+import { buildOmniRouteOpenCodeConfig } from "@omniroute/opencode-provider";
+
+const config = buildOmniRouteOpenCodeConfig({
+  baseURL: "http://localhost:20128", // or your OmniRoute deployment URL
+  apiKey: process.env.OMNIROUTE_API_KEY ?? "sk_omniroute",
+});
+
+writeFileSync("opencode.json", JSON.stringify(config, null, 2));
+```
+
+The resulting `opencode.json`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "omniroute": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "OmniRoute",
+      "options": {
+        "baseURL": "http://localhost:20128/v1",
+        "apiKey": "sk_omniroute",
+      },
+      "models": {
+        "claude-opus-4-5-thinking": { "name": "claude-opus-4-5-thinking" },
+        "claude-sonnet-4-5-thinking": { "name": "claude-sonnet-4-5-thinking" },
+        "gemini-3.1-pro-high": { "name": "gemini-3.1-pro-high" },
+        "gemini-3-flash": { "name": "gemini-3-flash" },
+      },
+    },
+  },
+}
+```
+
+### 2. Merge into an existing `opencode.json`
+
+```ts
+import { createOmniRouteProvider } from "@omniroute/opencode-provider";
+
+const provider = createOmniRouteProvider({
+  baseURL: "http://localhost:20128",
+  apiKey: process.env.OMNIROUTE_API_KEY!,
+});
+
+// Place `provider` under provider.omniroute in your opencode.json
+```
+
+If you already have an `opencode.json` on disk and want a non-destructive merge from the OmniRoute side, use `omniroute config opencode` from the CLI (ships with the main OmniRoute install) — it preserves comments and unrelated keys.
+
+## API
+
+### `createOmniRouteProvider(options): OpenCodeProviderEntry`
+
+Returns the value to place under `provider.omniroute` inside `opencode.json`.
+
+| Option        | Type                    | Required | Description                                                                                                  |
+| ------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
+| `baseURL`     | `string`                | Yes      | OmniRoute base URL. Accepts `http://host:port` **or** `http://host:port/v1`. Trailing slashes are tolerated. |
+| `apiKey`      | `string`                | Yes      | OmniRoute API key. Use `sk_omniroute` for local installs that have `REQUIRE_API_KEY=false`.                  |
+| `displayName` | `string`                | No       | Custom name shown in the OpenCode UI. Default: `"OmniRoute"`.                                                |
+| `models`      | `string[]`              | No       | Override the surfaced model catalog. Default: 4 curated models — see `OMNIROUTE_DEFAULT_OPENCODE_MODELS`.    |
+| `modelLabels` | `Record<string,string>` | No       | Human-readable labels keyed by model id.                                                                     |
+
+Throws on empty/invalid input — `baseURL` must be a real URL, `apiKey` must be a non-empty string.
+
+### `buildOmniRouteOpenCodeConfig(options): OpenCodeConfigDocument`
+
+Same options as above, but returns a full document with `$schema` and the `provider.omniroute` wrapper, ready to write to `opencode.json`.
+
+### `normalizeBaseURL(input): string`
+
+Exported for completeness. Strips trailing `/`, deduplicates a trailing `/v1`, and re-appends exactly one `/v1`. Throws on empty / non-URL input.
+
+### Constants
+
+- `OMNIROUTE_PROVIDER_KEY` — `"omniroute"` (the key used under `provider.*`).
+- `OMNIROUTE_PROVIDER_NPM` — `"@ai-sdk/openai-compatible"` (the runtime delegate).
+- `OPENCODE_CONFIG_SCHEMA` — `"https://opencode.ai/config.json"`.
+- `OMNIROUTE_DEFAULT_OPENCODE_MODELS` — readonly list of default model ids.
+
+## Custom model catalog
+
+```ts
+import { createOmniRouteProvider } from "@omniroute/opencode-provider";
+
+createOmniRouteProvider({
+  baseURL: "http://localhost:20128",
+  apiKey: "sk_omniroute",
+  models: ["auto", "claude-opus-4-8", "gpt-5.5"],
+  modelLabels: {
+    auto: "Auto-Combo (recommended)",
+    "claude-opus-4-8": "Claude Opus 4.8",
+    "gpt-5.5": "GPT-5.5",
+  },
+});
+```
+
+Duplicates and empty strings are dropped automatically, and order is preserved.
+
+## Troubleshooting
+
+- **Requests 404 with `/v1/v1/...`** — you're on an old version (≤1.0.0). Update to `≥0.1.0` of this re-released package. The new build normalises `baseURL` automatically.
+- **`401 Invalid API key`** — your OmniRoute instance has `REQUIRE_API_KEY=true` but the key you supplied doesn't exist there. Create one via the dashboard or set `REQUIRE_API_KEY=false` and use `sk_omniroute`.
+- **OpenCode complains the provider has no models** — supply an explicit `models` list; the default 4 may be hidden by your provider visibility settings.
+
+## Related
+
+- [OmniRoute](https://github.com/diegosouzapw/OmniRoute) — the AI gateway this plugin targets.
+- [OpenCode](https://opencode.ai) — the agentic CLI consumer.
+- [`@ai-sdk/openai-compatible`](https://www.npmjs.com/package/@ai-sdk/openai-compatible) — the runtime delegate that actually speaks HTTP.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).

@omniroute/opencode-provider/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@omniroute/opencode-provider",
+  "version": "0.1.0",
+  "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",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "test": "node --import tsx/esm --test tests/index.test.ts",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "keywords": [
+    "omniroute",
+    "opencode",
+    "opencode-ai",
+    "ai-sdk",
+    "openai-compatible",
+    "provider",
+    "ai-gateway",
+    "llm-router"
+  ],
+  "author": "OmniRoute contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/diegosouzapw/OmniRoute.git",
+    "directory": "@omniroute/opencode-provider"
+  },
+  "bugs": {
+    "url": "https://github.com/diegosouzapw/OmniRoute/issues"
+  },
+  "homepage": "https://github.com/diegosouzapw/OmniRoute/tree/main/%40omniroute/opencode-provider#readme",
+  "engines": {
+    "node": ">=22.22.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.19",
+    "tsup": "^8.5.1",
+    "tsx": "^4.22.3",
+    "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "esbuild": "^0.28.1"
+  }
+}

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

@@ -0,0 +1,908 @@
+/**
+ * OpenCode provider plugin for OmniRoute AI Gateway.
+ *
+ * Generates an OpenCode-compatible provider object that points to a running
+ * OmniRoute instance. The output follows the OpenCode config schema
+ * (https://opencode.ai/config.json) and delegates the runtime to
+ * `@ai-sdk/openai-compatible` so OpenCode can drive any OmniRoute-exposed
+ * model through its standard OpenAI-compatible client.
+ *
+ * Two ways to consume the helper:
+ *
+ *  1. As code, when you build your own opencode.json programmatically:
+ *
+ *     ```ts
+ *     import { buildOmniRouteOpenCodeConfig } from "@omniroute/opencode-provider";
+ *     const config = buildOmniRouteOpenCodeConfig({
+ *       baseURL: "http://localhost:20128",
+ *       apiKey: "sk_omniroute",
+ *     });
+ *     // config -> { $schema, provider: { omniroute: { npm, name, options, models } } }
+ *     ```
+ *
+ *  2. As a single-provider entry to merge into an existing opencode.json:
+ *
+ *     ```ts
+ *     import { createOmniRouteProvider } from "@omniroute/opencode-provider";
+ *     const provider = createOmniRouteProvider({ baseURL, apiKey });
+ *     // provider -> the value to place under provider.omniroute in opencode.json
+ *     ```
+ *
+ * Note: `baseURL` accepts both `http://host:port` and `http://host:port/v1`.
+ * The helper normalises trailing slashes / `/v1` so you never get `/v1/v1`.
+ */
+
+export const OMNIROUTE_PROVIDER_KEY = "omniroute" as const;
+export const OMNIROUTE_PROVIDER_NPM = "@ai-sdk/openai-compatible" as const;
+export const OPENCODE_CONFIG_SCHEMA = "https://opencode.ai/config.json" as const;
+
+/**
+ * Default catalog of models surfaced to OpenCode when the caller does not
+ * supply an explicit `models` list.
+ *
+ * Curated set covering the most commonly deployed OmniRoute models. Synced
+ * with the Alph4d0g/opencode-omniroute-auth OMNIROUTE_DEFAULT_MODELS constant
+ * (https://github.com/Alph4d0g/opencode-omniroute-auth, MIT) and extended
+ * with Claude Code passthrough models (`cc/` prefix).
+ */
+export const OMNIROUTE_DEFAULT_OPENCODE_MODELS = [
+  "cc/claude-opus-4-8",
+  "cc/claude-opus-4-7",
+  "cc/claude-sonnet-4-6",
+  "cc/claude-haiku-4-5-20251001",
+  "claude-opus-4-5-thinking",
+  "claude-sonnet-4-5-thinking",
+  "gemini-3.1-pro-high",
+  "gemini-3-flash",
+] as const;
+
+/**
+ * Optional capability flags surfaced to OpenCode's model picker.
+ *
+ * OpenCode reads these per-model keys (snake_case in JSON) to render badges
+ * and to gate features such as image attachments, reasoning mode, temperature
+ * controls and tool-calling. Omitted flags default to OpenCode's heuristics.
+ *
+ * Mirrors the capability shape used by Alph4d0g/opencode-omniroute-auth
+ * (https://github.com/Alph4d0g/opencode-omniroute-auth, MIT).
+ */
+export interface ModelCapabilities {
+  /** Display label shown in the model picker. Falls back to the model id. */
+  label?: string;
+  /** Model accepts image / file attachments. */
+  attachment?: boolean;
+  /** Model exposes a "reasoning" / extended-thinking surface. */
+  reasoning?: boolean;
+  /** Model honours the `temperature` parameter. */
+  temperature?: boolean;
+  /** Model supports tool / function calling. */
+  tool_call?: boolean;
+}
+
+/**
+ * Default per-model context window sizes (tokens) for the curated default catalog.
+ * Matches the context lengths used by OmniRoute's provider registry.
+ */
+export const OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS: Record<string, number> = {
+  "cc/claude-opus-4-8": 1_000_000,
+  "cc/claude-opus-4-7": 1_000_000,
+  "cc/claude-sonnet-4-6": 200_000,
+  "cc/claude-haiku-4-5-20251001": 200_000,
+  "claude-opus-4-5-thinking": 200_000,
+  "claude-sonnet-4-5-thinking": 200_000,
+  "gemini-3.1-pro-high": 1_000_000,
+  "gemini-3-flash": 1_000_000,
+};
+
+/**
+ * Default per-model capability hints for the curated default catalog.
+ *
+ * Conservative defaults: every default model accepts attachments, tool calls
+ * and temperature; `reasoning` is opt-in per model id. Callers override per
+ * model via `OmniRouteProviderOptions.modelCapabilities`.
+ */
+export const OMNIROUTE_DEFAULT_MODEL_CAPABILITIES: Record<string, ModelCapabilities> = {
+  "cc/claude-opus-4-8": { attachment: true, reasoning: true, temperature: true, tool_call: true },
+  "cc/claude-opus-4-7": { attachment: true, reasoning: true, temperature: true, tool_call: true },
+  "cc/claude-sonnet-4-6": { attachment: true, reasoning: true, temperature: true, tool_call: true },
+  "cc/claude-haiku-4-5-20251001": { attachment: true, temperature: true, tool_call: true },
+  "claude-opus-4-5-thinking": {
+    attachment: true,
+    reasoning: true,
+    temperature: true,
+    tool_call: true,
+  },
+  "claude-sonnet-4-5-thinking": {
+    attachment: true,
+    reasoning: true,
+    temperature: true,
+    tool_call: true,
+  },
+  "gemini-3.1-pro-high": { attachment: true, reasoning: true, temperature: true, tool_call: true },
+  "gemini-3-flash": { attachment: true, temperature: true, tool_call: true },
+};
+
+export interface OmniRouteProviderOptions {
+  /** OmniRoute base URL, with or without trailing `/v1`. Required. */
+  baseURL: string;
+  /** OmniRoute API key. Required. Use `sk_omniroute` for local instances without REQUIRE_API_KEY. */
+  apiKey: string;
+  /** Override the display name shown in OpenCode. Default: `"OmniRoute"`. */
+  displayName?: 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>;
+  /**
+   * Optional capability overrides keyed by model id. Merged on top of
+   * `OMNIROUTE_DEFAULT_MODEL_CAPABILITIES` for ids in the default catalog;
+   * 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.
+   */
+  model?: string;
+  /**
+   * Secondary / cheap model for OpenCode (top-level `small_model` key).
+   * Emitted as `"omniroute/<id>"`. When omitted the key is not written.
+   */
+  smallModel?: string;
+}
+
+/** Per-model entry written under `provider.omniroute.models[id]`. */
+export interface OpenCodeModelEntry {
+  name: string;
+  attachment?: boolean;
+  reasoning?: boolean;
+  temperature?: boolean;
+  tool_call?: boolean;
+  /**
+   * Context window limit. OpenCode reads this to determine usable context
+   * length for compaction, overflow detection, and router decisions.
+   * Maps to `limit.context` in OpenCode's provider config schema.
+   */
+  limit?: {
+    /** Maximum context length in tokens (e.g. 200000 for Claude, 1000000 for Gemini). */
+    context: number;
+    /** Optional per-request max input tokens. */
+    input?: number;
+    /** Optional max output tokens. */
+    output?: number;
+  };
+}
+
+export interface OpenCodeProviderEntry {
+  /** Identifier of the OpenCode runtime package that will speak to OmniRoute. */
+  npm: typeof OMNIROUTE_PROVIDER_NPM;
+  /** Display name in the OpenCode UI. */
+  name: string;
+  /** Options forwarded to `@ai-sdk/openai-compatible`. */
+  options: {
+    baseURL: string;
+    apiKey: string;
+  };
+  /** Model catalog surfaced to OpenCode. */
+  models: Record<string, OpenCodeModelEntry>;
+}
+
+export interface OpenCodeConfigDocument {
+  $schema: typeof OPENCODE_CONFIG_SCHEMA;
+  /** Primary model for OpenCode, e.g. `"omniroute/claude-sonnet-4-5-thinking"`. */
+  model?: string;
+  /** Secondary / cheap model for OpenCode, e.g. `"omniroute/gemini-3-flash"`. */
+  small_model?: string;
+  provider: {
+    [OMNIROUTE_PROVIDER_KEY]: OpenCodeProviderEntry;
+  };
+}
+
+function requireNonEmpty(value: unknown, field: string): string {
+  if (typeof value !== "string") {
+    throw new TypeError(`@omniroute/opencode-provider: ${field} must be a string`);
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error(`@omniroute/opencode-provider: ${field} is required and cannot be empty`);
+  }
+  return trimmed;
+}
+
+/**
+ * Normalise the user-supplied baseURL so the final `options.baseURL` always
+ * ends in exactly one `/v1`. Accepts both `http://host` and `http://host/v1`.
+ */
+export function normalizeBaseURL(rawBaseURL: string): string {
+  const trimmed = requireNonEmpty(rawBaseURL, "baseURL");
+  try {
+    new URL(trimmed);
+  } catch {
+    throw new Error(
+      `@omniroute/opencode-provider: baseURL is not a valid URL: ${JSON.stringify(rawBaseURL)}`
+    );
+  }
+  let base = trimmed;
+  let end = base.length;
+  while (end > 0 && base[end - 1] === "/") end--;
+  base = end < base.length ? base.slice(0, end) : base;
+  if (base.endsWith("/v1")) base = base.slice(0, -3);
+  return base + "/v1";
+}
+
+/**
+ * Build the `provider.omniroute` entry for an OpenCode config document.
+ * The returned object is JSON-serialisable and safe to embed verbatim.
+ */
+export function createOmniRouteProvider(options: OmniRouteProviderOptions): OpenCodeProviderEntry {
+  const baseURL = normalizeBaseURL(options.baseURL);
+  const apiKey = requireNonEmpty(options.apiKey, "apiKey");
+
+  const modelList =
+    options.models && options.models.length > 0
+      ? [...options.models]
+      : [...OMNIROUTE_DEFAULT_OPENCODE_MODELS];
+
+  const labels = options.modelLabels ?? {};
+  const overrides = options.modelCapabilities ?? {};
+  const models: Record<string, OpenCodeModelEntry> = {};
+  const seen = new Set<string>();
+  for (const raw of modelList) {
+    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] ?? {};
+    const override = overrides[id] ?? {};
+    const merged: ModelCapabilities = { ...defaults, ...override };
+    const explicitLabel =
+      typeof merged.label === "string" && merged.label.trim()
+        ? merged.label.trim()
+        : typeof labels[id] === "string" && labels[id].trim()
+          ? labels[id].trim()
+          : id;
+    const entry: OpenCodeModelEntry = { name: explicitLabel };
+    if (typeof merged.attachment === "boolean") entry.attachment = merged.attachment;
+    if (typeof merged.reasoning === "boolean") entry.reasoning = merged.reasoning;
+    if (typeof merged.temperature === "boolean") entry.temperature = merged.temperature;
+    if (typeof merged.tool_call === "boolean") entry.tool_call = merged.tool_call;
+
+    // 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 };
+    }
+
+    models[id] = entry;
+  }
+
+  return {
+    npm: OMNIROUTE_PROVIDER_NPM,
+    name: options.displayName?.trim() || "OmniRoute",
+    options: { baseURL, apiKey },
+    models,
+  };
+}
+
+/**
+ * Build a full OpenCode config document (with `$schema` + `provider.omniroute`).
+ * Useful when scaffolding a fresh `opencode.json`.
+ *
+ * When `options.model` / `options.smallModel` are supplied they are emitted as
+ * top-level `model` / `small_model` keys prefixed with `"omniroute/"` so
+ * OpenCode resolves them through the configured provider.
+ */
+export function buildOmniRouteOpenCodeConfig(
+  options: OmniRouteProviderOptions
+): OpenCodeConfigDocument {
+  const doc: OpenCodeConfigDocument = {
+    $schema: OPENCODE_CONFIG_SCHEMA,
+    provider: {
+      [OMNIROUTE_PROVIDER_KEY]: createOmniRouteProvider(options),
+    },
+  };
+
+  if (options.model !== undefined) {
+    const id = options.model.trim();
+    if (id) doc.model = `${OMNIROUTE_PROVIDER_KEY}/${id}`;
+  }
+
+  if (options.smallModel !== undefined) {
+    const id = options.smallModel.trim();
+    if (id) doc.small_model = `${OMNIROUTE_PROVIDER_KEY}/${id}`;
+  }
+
+  return doc;
+}
+
+/**
+ * Merge the OmniRoute provider entry (and optional `model` / `small_model`
+ * keys) into an already-existing OpenCode config object.
+ *
+ * Performs a non-destructive merge: all top-level keys in `existing` are
+ * preserved. The `provider` map is shallow-merged so other providers already
+ * present are not removed. If `existing.provider.omniroute` already exists it
+ * is overwritten by the newly built entry.
+ *
+ * `model` and `small_model` are only written when supplied in `options`.
+ *
+ * @example
+ * ```ts
+ * const existing = JSON.parse(readFileSync("opencode.json", "utf8"));
+ * const updated = mergeIntoExistingConfig(existing, {
+ *   baseURL: "http://localhost:20128",
+ *   apiKey: "sk_omniroute",
+ *   model: "claude-sonnet-4-5-thinking",
+ * });
+ * writeFileSync("opencode.json", JSON.stringify(updated, null, 2));
+ * ```
+ */
+export function mergeIntoExistingConfig(
+  existing: Record<string, unknown>,
+  options: OmniRouteProviderOptions
+): Record<string, unknown> {
+  const partial = buildOmniRouteOpenCodeConfig(options);
+
+  const merged: Record<string, unknown> = { ...existing };
+
+  if (partial.model !== undefined) merged.model = partial.model;
+  if (partial.small_model !== undefined) merged.small_model = partial.small_model;
+
+  const existingProvider =
+    typeof existing.provider === "object" && existing.provider !== null
+      ? (existing.provider as Record<string, unknown>)
+      : {};
+
+  merged.provider = {
+    ...existingProvider,
+    [OMNIROUTE_PROVIDER_KEY]: partial.provider[OMNIROUTE_PROVIDER_KEY],
+  };
+
+  return merged;
+}
+
+/**
+ * The 7 read-only MCP scopes that allow inspection without any write access.
+ * Suitable for shared / public environments.
+ */
+export const OMNIROUTE_MCP_DEFAULT_SCOPES = [
+  "read:health",
+  "read:combos",
+  "read:quota",
+  "read:usage",
+  "read:models",
+  "read:cache",
+  "read:compression",
+] as const;
+
+export type OmniRouteMCPScope = (typeof OMNIROUTE_MCP_DEFAULT_SCOPES)[number] | string;
+
+export interface OmniRouteMCPOptions {
+  /** Absolute path to the MCP server entry point (TypeScript or compiled JS). */
+  serverPath: string;
+  /** OmniRoute API key forwarded to the MCP server as `OMNIROUTE_API_KEY`. */
+  apiKey: string;
+  /**
+   * Management API key used for management-scoped operations.
+   * When supplied it is forwarded as `OMNIROUTE_MANAGEMENT_API_KEY`.
+   */
+  managementApiKey?: string;
+  /**
+   * Comma-separated scope list passed as `OMNIROUTE_MCP_SCOPES`.
+   * When omitted `OMNIROUTE_MCP_ENFORCE_SCOPES` is not set and all scopes are
+   * available (development default). Pass an explicit list to restrict access.
+   */
+  scopes?: OmniRouteMCPScope[];
+  /**
+   * Runtime used to execute the MCP server.
+   *
+   * - `"tsx"` (default) — runs via `npx tsx` for TypeScript source files.
+   * - `"node"` — runs via `node` for compiled JS outputs.
+   */
+  runtime?: "tsx" | "node";
+}
+
+export interface OpenCodeMCPServerEntry {
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+}
+
+/**
+ * Build the `mcp.servers.omniroute` entry for an OpenCode config document.
+ *
+ * @example
+ * ```ts
+ * const mcpEntry = createOmniRouteMCPEntry({
+ *   serverPath: "/home/user/.local/share/omniroute/open-sse/mcp-server/server.ts",
+ *   apiKey: "sk_omniroute",
+ *   managementApiKey: "sk_manage_...",
+ *   scopes: ["read:health", "read:combos", "execute:completions"],
+ * });
+ * // Place at config.mcp.servers.omniroute
+ * ```
+ */
+export function createOmniRouteMCPEntry(options: OmniRouteMCPOptions): OpenCodeMCPServerEntry {
+  const serverPath = requireNonEmpty(options.serverPath, "serverPath");
+  const apiKey = requireNonEmpty(options.apiKey, "apiKey");
+
+  const runtime = options.runtime ?? "tsx";
+
+  const command = runtime === "tsx" ? "npx" : "node";
+  const args = runtime === "tsx" ? ["tsx", serverPath] : [serverPath];
+
+  const env: Record<string, string> = {
+    OMNIROUTE_API_KEY: apiKey,
+  };
+
+  if (options.managementApiKey !== undefined) {
+    const mgmtKey = options.managementApiKey.trim();
+    if (mgmtKey) env.OMNIROUTE_MANAGEMENT_API_KEY = mgmtKey;
+  }
+
+  if (options.scopes !== undefined && options.scopes.length > 0) {
+    env.OMNIROUTE_MCP_ENFORCE_SCOPES = "true";
+    env.OMNIROUTE_MCP_SCOPES = options.scopes.join(",");
+  }
+
+  return { command, args, env };
+}
+
+async function fetchJSON<T>(url: string, apiKey: string, timeoutMs: number): Promise<T> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`received HTTP ${response.status}`);
+    }
+
+    return (await response.json()) as T;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`@omniroute/opencode-provider: request to ${url} failed: ${message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Lightweight model descriptor returned by `fetchLiveModels`.
+ * The shape mirrors the subset of fields that OmniRoute's `/v1/models`
+ * endpoint reliably provides across versions, normalised from both
+ * camelCase and snake_case variants used by different OmniRoute releases.
+ *
+ * Attribution: field-variant normalisation logic adapted from
+ * https://github.com/Alph4d0g/opencode-omniroute-auth (MIT).
+ */
+export interface OmniRouteLiveModel {
+  id: string;
+  name: string;
+  /** Context window length in tokens (e.g. 200000 for Claude, 1000000 for Gemini). */
+  contextLength?: number;
+}
+
+/**
+ * Fetch the live model catalog from a running OmniRoute instance.
+ *
+ * Returns an array of `{ id, name }` objects from `GET /v1/models`. Handles
+ * both the camelCase (`modelId`, `displayName`) and snake_case (`model_id`,
+ * `display_name`) field variants across OmniRoute versions.
+ *
+ * Useful for dynamically populating the `models` option of
+ * `createOmniRouteProvider` / `buildOmniRouteOpenCodeConfig` instead of
+ * relying on `OMNIROUTE_DEFAULT_OPENCODE_MODELS`.
+ *
+ * @param baseURL   - OmniRoute base URL (with or without `/v1`).
+ * @param apiKey    - OmniRoute API key.
+ * @param timeoutMs - Request timeout in milliseconds (default 5000).
+ *
+ * @example
+ * ```ts
+ * const models = await fetchLiveModels("http://localhost:20128", "sk_omniroute");
+ * const config = buildOmniRouteOpenCodeConfig({
+ *   baseURL: "http://localhost:20128",
+ *   apiKey: "sk_omniroute",
+ *   models,                    // OmniRouteLiveModel[] — contextLength auto-extracted
+ *   modelLabels: Object.fromEntries(models.map((m) => [m.id, m.name])),
+ * });
+ * ```
+ */
+export async function fetchLiveModels(
+  baseURL: string,
+  apiKey: string,
+  timeoutMs = 5_000
+): Promise<OmniRouteLiveModel[]> {
+  const key = requireNonEmpty(apiKey, "apiKey");
+  const url = `${normalizeBaseURL(baseURL)}/models`;
+
+  const body = await fetchJSON<unknown>(url, key, timeoutMs);
+
+  const rawList: unknown[] = Array.isArray(body)
+    ? body
+    : body && typeof body === "object" && Array.isArray((body as { data?: unknown[] }).data)
+      ? ((body as { data: unknown[] }).data as unknown[])
+      : [];
+
+  const models: OmniRouteLiveModel[] = [];
+  for (const raw of rawList) {
+    if (typeof raw !== "object" || raw === null) continue;
+    const r = raw as Record<string, unknown>;
+
+    const id =
+      typeof r.id === "string"
+        ? r.id.trim()
+        : typeof r.modelId === "string"
+          ? r.modelId.trim()
+          : typeof r.model_id === "string"
+            ? r.model_id.trim()
+            : "";
+
+    if (!id) continue;
+
+    const name =
+      typeof r.name === "string"
+        ? r.name.trim()
+        : typeof r.displayName === "string"
+          ? r.displayName.trim()
+          : typeof r.display_name === "string"
+            ? r.display_name.trim()
+            : id;
+
+    // Extract context_length from OmniRoute's /v1/models response.
+    // OmniRoute returns context_length in snake_case for both synced
+    // models (with inputTokenLimit) and custom models; the catalog's
+    // getDefaultContextFallback also injects it from registry defaults.
+    const contextLength =
+      typeof r.context_length === "number" && r.context_length > 0
+        ? r.context_length
+        : typeof r.max_context_window_tokens === "number" && r.max_context_window_tokens > 0
+          ? r.max_context_window_tokens
+          : undefined;
+
+    models.push({ id, name: name || id, ...(contextLength ? { contextLength } : {}) });
+  }
+
+  return models;
+}
+
+/**
+ * Valid per-combo compression override values.
+ * An empty string clears any existing override (inherits global setting).
+ */
+export type OmniRouteCompressionOverride =
+  | ""
+  | "off"
+  | "lite"
+  | "standard"
+  | "aggressive"
+  | "ultra"
+  | "rtk"
+  | "stacked";
+
+const VALID_COMPRESSION_OVERRIDES = new Set<string>([
+  "",
+  "off",
+  "lite",
+  "standard",
+  "aggressive",
+  "ultra",
+  "rtk",
+  "stacked",
+]);
+
+/** Slim combo descriptor returned by `listCombos`. */
+export interface OmniRouteCombo {
+  id: string;
+  name: string;
+  strategy: string;
+  active: boolean;
+  compressionOverride: OmniRouteCompressionOverride;
+}
+
+/**
+ * Fetch the active routing combo list from a running OmniRoute instance.
+ *
+ * Returns an array of combo descriptors from `GET /api/combos`. The
+ * `compressionOverride` field reflects the per-combo compression strategy
+ * (one of the 8 recognised values; empty string means "inherit global").
+ *
+ * Requires a management-scoped API key (Bearer `manage` scope) when the
+ * instance has `REQUIRE_API_KEY` enabled.
+ *
+ * @param baseURL          - OmniRoute base URL (with or without `/v1`).
+ * @param managementApiKey - API key with `manage` scope.
+ * @param timeoutMs        - Request timeout in milliseconds (default 5000).
+ */
+export async function listCombos(
+  baseURL: string,
+  managementApiKey: string,
+  timeoutMs = 5_000
+): Promise<OmniRouteCombo[]> {
+  const key = requireNonEmpty(managementApiKey, "managementApiKey");
+  const base = normalizeBaseURL(baseURL).replace(/\/v1$/, "");
+  const url = `${base}/api/combos`;
+
+  const body = await fetchJSON<unknown>(url, key, timeoutMs);
+  const rawList: unknown[] = Array.isArray(body)
+    ? body
+    : body && typeof body === "object" && Array.isArray((body as { combos?: unknown[] }).combos)
+      ? ((body as { combos: unknown[] }).combos as unknown[])
+      : [];
+
+  const combos: OmniRouteCombo[] = [];
+  for (const raw of rawList) {
+    if (typeof raw !== "object" || raw === null) continue;
+    const r = raw as Record<string, unknown>;
+
+    const id = typeof r.id === "string" ? r.id.trim() : "";
+    if (!id) continue;
+
+    const name = typeof r.name === "string" ? r.name.trim() : id;
+    const strategy = typeof r.strategy === "string" ? r.strategy : "";
+    const active = typeof r.active === "boolean" ? r.active : false;
+
+    const rawOverride = typeof r.compressionOverride === "string" ? r.compressionOverride : "";
+    const compressionOverride = VALID_COMPRESSION_OVERRIDES.has(rawOverride)
+      ? (rawOverride as OmniRouteCompressionOverride)
+      : "";
+
+    combos.push({ id, name, strategy, active, compressionOverride });
+  }
+
+  return combos;
+}
+
+/**
+ * Options for `createOmniRouteComboConfig`.
+ * Mirrors the subset of combo fields exposed by the OmniRoute `/api/combos`
+ * PATCH / POST payload that are safe to set programmatically.
+ */
+export interface OmniRouteComboConfigOptions {
+  /** Human-readable combo name. */
+  name: string;
+  /** Routing strategy (e.g. `"priority"`, `"weighted"`, `"round-robin"`). */
+  strategy: string;
+  /**
+   * Per-combo compression override.
+   * Empty string removes any override (inherits global setting).
+   */
+  compressionOverride?: OmniRouteCompressionOverride;
+  /** Whether this combo is active for routing. Default: `true`. */
+  active?: boolean;
+  /**
+   * Ordered list of provider IDs in this combo.
+   * Required for create operations; optional for updates.
+   */
+  providers?: string[];
+}
+
+/**
+ * Build a typed combo payload suitable for OmniRoute's management API.
+ *
+ * The returned object is JSON-serialisable and safe to pass as the body of a
+ * `POST /api/combos` (create) or `PATCH /api/combos/:id` (update) request.
+ *
+ * @example
+ * ```ts
+ * const payload = createOmniRouteComboConfig({
+ *   name: "claude-primary",
+ *   strategy: "priority",
+ *   compressionOverride: "standard",
+ *   providers: ["anthropic-claude-opus", "anthropic-claude-sonnet"],
+ * });
+ * await fetch(`${baseURL}/api/combos`, {
+ *   method: "POST",
+ *   headers: { Authorization: `Bearer ${mgmtKey}`, "Content-Type": "application/json" },
+ *   body: JSON.stringify(payload),
+ * });
+ * ```
+ */
+export function createOmniRouteComboConfig(
+  options: OmniRouteComboConfigOptions
+): Record<string, unknown> {
+  const name = requireNonEmpty(options.name, "name");
+  const strategy = requireNonEmpty(options.strategy, "strategy");
+
+  const payload: Record<string, unknown> = {
+    name,
+    strategy,
+    active: options.active ?? true,
+  };
+
+  if (options.compressionOverride !== undefined) {
+    payload.compressionOverride = options.compressionOverride;
+  }
+
+  if (options.providers !== undefined) {
+    const providers = options.providers.filter((p) => typeof p === "string" && p.trim());
+    if (providers.length > 0) {
+      payload.providers = providers;
+    }
+  }
+
+  return payload;
+}
+
+/**
+ * Override fields supported per agent / mode entry. Mirrors the subset of
+ * OpenCode's `AgentConfig` schema that is safe to set declaratively from a
+ * config generator. Only fields present in
+ * https://opencode.ai/config.json#AgentConfig are exposed.
+ */
+export interface OmniRouteRoleOverrides {
+  /** Forward to OpenCode's `temperature` field. */
+  temperature?: number;
+  /** Forward to OpenCode's `top_p` field. */
+  top_p?: number;
+}
+
+/** Per-role binding used by `createOmniRouteAgentBlock`. */
+export interface OmniRouteAgentRole extends OmniRouteRoleOverrides {
+  /** OmniRoute model id, e.g. `"claude-sonnet-4-5-thinking"`. */
+  modelId: string;
+  /** Optional tools allow-list; per OpenCode schema, map of tool name → enabled. */
+  tools?: Record<string, boolean>;
+  /** Optional system prompt for this agent role. */
+  prompt?: string;
+}
+
+/** Options for `createOmniRouteAgentBlock`. */
+export interface OmniRouteAgentBlockOptions {
+  /** Per-role bindings. Keys become entries under OpenCode's `agent` block. */
+  roles: Record<string, OmniRouteAgentRole>;
+}
+
+/** Single entry inside the emitted OpenCode `agent` block. */
+export interface OpenCodeAgentEntry extends OmniRouteRoleOverrides {
+  /** Always emitted as `"omniroute/<modelId>"`. */
+  model: string;
+  /** Per OpenCode schema, `Record<string, boolean>`. */
+  tools?: Record<string, boolean>;
+  /** Optional system prompt. */
+  prompt?: string;
+}
+
+function buildAgentEntry(role: OmniRouteAgentRole): OpenCodeAgentEntry | undefined {
+  if (!role || typeof role.modelId !== "string") return undefined;
+  const modelId = role.modelId.trim();
+  if (!modelId) return undefined;
+  const entry: OpenCodeAgentEntry = { model: `${OMNIROUTE_PROVIDER_KEY}/${modelId}` };
+  if (typeof role.temperature === "number") entry.temperature = role.temperature;
+  if (typeof role.top_p === "number") entry.top_p = role.top_p;
+  if (role.tools && typeof role.tools === "object" && !Array.isArray(role.tools)) {
+    const tools: Record<string, boolean> = {};
+    for (const [name, enabled] of Object.entries(role.tools)) {
+      if (typeof name !== "string" || !name.trim()) continue;
+      if (typeof enabled !== "boolean") continue;
+      tools[name] = enabled;
+    }
+    if (Object.keys(tools).length > 0) entry.tools = tools;
+  }
+  if (typeof role.prompt === "string" && role.prompt.trim()) {
+    entry.prompt = role.prompt;
+  }
+  return entry;
+}
+
+/**
+ * Build the OpenCode `agent` block, pre-wired so each agent role routes to a
+ * specific OmniRoute model. Useful for `.opencode/agent/*.md` defaults and
+ * scaffolded `opencode.json` files.
+ *
+ * Emitted fields are limited to those declared in OpenCode's `AgentConfig`
+ * schema (`model`, `temperature`, `top_p`, `tools`, `prompt`). The `tools`
+ * field is a `Record<string, boolean>` per the schema, not a string array.
+ *
+ * Roles with empty / missing `modelId` are skipped.
+ *
+ * @example
+ * ```ts
+ * const agentBlock = createOmniRouteAgentBlock({
+ *   roles: {
+ *     build: { modelId: "claude-sonnet-4-5-thinking", temperature: 0.2 },
+ *     plan: { modelId: "claude-opus-4-5-thinking", top_p: 0.95 },
+ *     review: { modelId: "gemini-3-flash", tools: { edit: false, bash: false } },
+ *   },
+ * });
+ * // -> { build: { model: "omniroute/claude-sonnet-4-5-thinking", temperature: 0.2 }, ... }
+ * ```
+ */
+export function createOmniRouteAgentBlock(
+  options: OmniRouteAgentBlockOptions
+): Record<string, OpenCodeAgentEntry> {
+  const out: Record<string, OpenCodeAgentEntry> = {};
+  const roles = options.roles ?? {};
+  for (const [roleName, role] of Object.entries(roles)) {
+    const entry = buildAgentEntry(role);
+    if (entry) out[roleName] = entry;
+  }
+  return out;
+}
+
+/**
+ * Per-mode binding used by `createOmniRouteModesBlock`.
+ *
+ * @deprecated OpenCode's top-level `mode` block is deprecated in favour of
+ * `agent`. Prefer `OmniRouteAgentRole` + `createOmniRouteAgentBlock`. This
+ * type and the corresponding helper are kept for back-compat with configs
+ * still using `mode:`.
+ */
+export interface OmniRouteMode extends OmniRouteAgentRole {}
+
+/**
+ * Options for `createOmniRouteModesBlock`.
+ *
+ * @deprecated See `OmniRouteMode`.
+ */
+export interface OmniRouteModesBlockOptions {
+  /** Per-mode bindings. Keys become entries under OpenCode's deprecated top-level `mode` block. */
+  modes: Record<string, OmniRouteMode>;
+}
+
+/**
+ * Single entry inside the emitted OpenCode `mode` block.
+ *
+ * @deprecated See `OmniRouteMode`.
+ */
+export interface OpenCodeModeEntry extends OpenCodeAgentEntry {}
+
+/**
+ * Build the OpenCode top-level `mode` block, pre-wired so each mode routes to
+ * a specific OmniRoute model. Emits the same shape as the `agent` block since
+ * OpenCode's schema treats them identically (both reference `AgentConfig`).
+ *
+ * Modes with empty / missing `modelId` are skipped.
+ *
+ * @deprecated OpenCode's top-level `mode` block is deprecated in favour of
+ * `agent`. Prefer `createOmniRouteAgentBlock`. This helper is kept for
+ * back-compat with configs still using `mode:`.
+ *
+ * @example
+ * ```ts
+ * const modesBlock = createOmniRouteModesBlock({
+ *   modes: {
+ *     build: { modelId: "claude-sonnet-4-5-thinking", tools: { edit: true, bash: true } },
+ *     plan: { modelId: "claude-opus-4-5-thinking", prompt: "Plan first, code later." },
+ *     review: { modelId: "gemini-3-flash" },
+ *   },
+ * });
+ * ```
+ */
+export function createOmniRouteModesBlock(
+  options: OmniRouteModesBlockOptions
+): Record<string, OpenCodeModeEntry> {
+  const out: Record<string, OpenCodeModeEntry> = {};
+  const modes = options.modes ?? {};
+  for (const [modeName, mode] of Object.entries(modes)) {
+    const entry = buildAgentEntry(mode);
+    if (entry) out[modeName] = entry;
+  }
+  return out;
+}
+
+export default createOmniRouteProvider;

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

@@ -0,0 +1,686 @@
+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,
+  createOmniRouteAgentBlock,
+  createOmniRouteComboConfig,
+  createOmniRouteMCPEntry,
+  createOmniRouteModesBlock,
+  createOmniRouteProvider,
+  fetchLiveModels,
+  listCombos,
+  mergeIntoExistingConfig,
+  normalizeBaseURL,
+  OMNIROUTE_DEFAULT_MODEL_CAPABILITIES,
+  OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS,
+  OMNIROUTE_DEFAULT_OPENCODE_MODELS,
+  OMNIROUTE_MCP_DEFAULT_SCOPES,
+  OMNIROUTE_PROVIDER_NPM,
+  OPENCODE_CONFIG_SCHEMA,
+} from "../src/index.ts";
+
+test("normalizeBaseURL preserves a bare host:port", () => {
+  assert.equal(normalizeBaseURL("http://localhost:20128"), "http://localhost:20128/v1");
+});
+
+test("normalizeBaseURL strips trailing slashes", () => {
+  assert.equal(normalizeBaseURL("http://localhost:20128////"), "http://localhost:20128/v1");
+});
+
+test("normalizeBaseURL deduplicates an existing /v1 suffix", () => {
+  assert.equal(normalizeBaseURL("http://localhost:20128/v1"), "http://localhost:20128/v1");
+  assert.equal(normalizeBaseURL("http://localhost:20128/v1/"), "http://localhost:20128/v1");
+});
+
+test("normalizeBaseURL rejects empty input", () => {
+  assert.throws(() => normalizeBaseURL("   "), /baseURL is required/);
+});
+
+test("normalizeBaseURL rejects malformed URLs", () => {
+  assert.throws(() => normalizeBaseURL("not a url"), /not a valid URL/);
+});
+
+test("createOmniRouteProvider validates required fields", () => {
+  assert.throws(
+    () => createOmniRouteProvider({ baseURL: "", apiKey: "x" } as never),
+    /baseURL is required/
+  );
+  assert.throws(
+    () => createOmniRouteProvider({ baseURL: "http://x", apiKey: "" } as never),
+    /apiKey is required/
+  );
+});
+
+test("createOmniRouteProvider produces the OpenCode-compatible shape", () => {
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+  });
+
+  assert.equal(provider.npm, OMNIROUTE_PROVIDER_NPM);
+  assert.equal(provider.name, "OmniRoute");
+  assert.equal(provider.options.baseURL, "http://localhost:20128/v1");
+  assert.equal(provider.options.apiKey, "sk_omniroute");
+  assert.equal(typeof provider.models, "object");
+});
+
+test("createOmniRouteProvider seeds the default model catalog", () => {
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+  });
+
+  const modelIds = Object.keys(provider.models).sort();
+  const defaultIds = [...OMNIROUTE_DEFAULT_OPENCODE_MODELS].sort();
+  assert.deepEqual(modelIds, defaultIds);
+  for (const id of defaultIds) {
+    assert.equal(provider.models[id]?.name, id);
+    assert.equal(provider.models[id]?.attachment, true);
+  }
+});
+
+test("createOmniRouteProvider honours a custom models list and labels", () => {
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+    models: ["auto", "claude-opus-4-7"],
+    modelLabels: { auto: "Auto-Combo", "claude-opus-4-7": "Opus 4.7" },
+  });
+
+  assert.deepEqual(Object.keys(provider.models), ["auto", "claude-opus-4-7"]);
+  assert.equal(provider.models.auto.name, "Auto-Combo");
+  assert.equal(provider.models["claude-opus-4-7"].name, "Opus 4.7");
+});
+
+test("createOmniRouteProvider deduplicates and trims model ids", () => {
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+    models: ["  auto  ", "auto", "", "claude-opus-4-7"],
+  });
+  assert.deepEqual(Object.keys(provider.models), ["auto", "claude-opus-4-7"]);
+});
+
+test("createOmniRouteProvider honours displayName override", () => {
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+    displayName: "Local OmniRoute",
+  });
+  assert.equal(provider.name, "Local OmniRoute");
+});
+
+test("buildOmniRouteOpenCodeConfig wraps the provider with the OpenCode schema", () => {
+  const doc = buildOmniRouteOpenCodeConfig({
+    baseURL: "http://localhost:20128/v1",
+    apiKey: "sk_omniroute",
+  });
+
+  assert.equal(doc.$schema, OPENCODE_CONFIG_SCHEMA);
+  assert.equal(typeof doc.provider.omniroute, "object");
+  assert.equal(doc.provider.omniroute.options.baseURL, "http://localhost:20128/v1");
+});
+
+test("config document is JSON-serialisable", () => {
+  const doc = buildOmniRouteOpenCodeConfig({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+  });
+  const round = JSON.parse(JSON.stringify(doc));
+  assert.deepEqual(round, doc);
+});
+
+test("buildOmniRouteOpenCodeConfig emits model and small_model prefixed with provider key", () => {
+  const doc = buildOmniRouteOpenCodeConfig({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+    model: "claude-sonnet-4-5-thinking",
+    smallModel: "gemini-3-flash",
+  });
+  assert.equal(doc.model, "omniroute/claude-sonnet-4-5-thinking");
+  assert.equal(doc.small_model, "omniroute/gemini-3-flash");
+});
+
+test("buildOmniRouteOpenCodeConfig omits model and small_model when not supplied", () => {
+  const doc = buildOmniRouteOpenCodeConfig({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+  });
+  assert.equal(doc.model, undefined);
+  assert.equal(doc.small_model, undefined);
+  assert.ok(!("model" in doc));
+  assert.ok(!("small_model" in doc));
+});
+
+test("buildOmniRouteOpenCodeConfig ignores blank model strings", () => {
+  const doc = buildOmniRouteOpenCodeConfig({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+    model: "   ",
+    smallModel: "",
+  });
+  assert.ok(!("model" in doc));
+  assert.ok(!("small_model" in doc));
+});
+
+test("mergeIntoExistingConfig preserves existing provider entries", () => {
+  const existing = {
+    $schema: OPENCODE_CONFIG_SCHEMA,
+    provider: {
+      anthropic: { npm: "@ai-sdk/anthropic", name: "Anthropic", options: {}, models: {} },
+    },
+    keybinds: { submit: "enter" },
+  };
+  const result = mergeIntoExistingConfig(existing, {
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+  });
+  assert.ok("anthropic" in (result.provider as Record<string, unknown>));
+  assert.ok("omniroute" in (result.provider as Record<string, unknown>));
+  assert.deepEqual((result as Record<string, unknown>).keybinds, { submit: "enter" });
+});
+
+test("mergeIntoExistingConfig overwrites existing omniroute entry", () => {
+  const existing = {
+    provider: {
+      omniroute: {
+        npm: "@ai-sdk/openai-compatible",
+        name: "OLD",
+        options: { baseURL: "http://old/v1", apiKey: "old" },
+        models: {},
+      },
+    },
+  };
+  const result = mergeIntoExistingConfig(existing, {
+    baseURL: "http://new",
+    apiKey: "new-key",
+    displayName: "NEW",
+  });
+  const omniroute = (result.provider as Record<string, unknown>).omniroute as { name: string };
+  assert.equal(omniroute.name, "NEW");
+});
+
+test("mergeIntoExistingConfig writes model and small_model when supplied", () => {
+  const result = mergeIntoExistingConfig(
+    {},
+    {
+      baseURL: "http://localhost:20128",
+      apiKey: "sk_omniroute",
+      model: "claude-sonnet-4-5-thinking",
+      smallModel: "gemini-3-flash",
+    }
+  );
+  assert.equal(result.model, "omniroute/claude-sonnet-4-5-thinking");
+  assert.equal(result.small_model, "omniroute/gemini-3-flash");
+});
+
+test("mergeIntoExistingConfig does not add model keys when not supplied", () => {
+  const result = mergeIntoExistingConfig(
+    {},
+    { baseURL: "http://localhost:20128", apiKey: "sk_omniroute" }
+  );
+  assert.ok(!("model" in result));
+  assert.ok(!("small_model" in result));
+});
+
+test("OMNIROUTE_MCP_DEFAULT_SCOPES contains 7 read-only scopes", () => {
+  assert.equal(OMNIROUTE_MCP_DEFAULT_SCOPES.length, 7);
+  assert.ok(OMNIROUTE_MCP_DEFAULT_SCOPES.every((s) => s.startsWith("read:")));
+});
+
+test("createOmniRouteMCPEntry defaults to tsx runtime", () => {
+  const entry = createOmniRouteMCPEntry({
+    serverPath: "/path/to/server.ts",
+    apiKey: "sk_omniroute",
+  });
+  assert.equal(entry.command, "npx");
+  assert.deepEqual(entry.args, ["tsx", "/path/to/server.ts"]);
+  assert.equal(entry.env.OMNIROUTE_API_KEY, "sk_omniroute");
+  assert.ok(!("OMNIROUTE_MCP_ENFORCE_SCOPES" in entry.env));
+  assert.ok(!("OMNIROUTE_MANAGEMENT_API_KEY" in entry.env));
+});
+
+test("createOmniRouteMCPEntry uses node runtime when specified", () => {
+  const entry = createOmniRouteMCPEntry({
+    serverPath: "/path/to/server.js",
+    apiKey: "sk_omniroute",
+    runtime: "node",
+  });
+  assert.equal(entry.command, "node");
+  assert.deepEqual(entry.args, ["/path/to/server.js"]);
+});
+
+test("createOmniRouteMCPEntry sets management key and scopes when supplied", () => {
+  const entry = createOmniRouteMCPEntry({
+    serverPath: "/path/to/server.ts",
+    apiKey: "sk_omniroute",
+    managementApiKey: "sk_manage",
+    scopes: ["read:health", "read:combos", "execute:completions"],
+  });
+  assert.equal(entry.env.OMNIROUTE_MANAGEMENT_API_KEY, "sk_manage");
+  assert.equal(entry.env.OMNIROUTE_MCP_ENFORCE_SCOPES, "true");
+  assert.equal(entry.env.OMNIROUTE_MCP_SCOPES, "read:health,read:combos,execute:completions");
+});
+
+test("createOmniRouteMCPEntry rejects missing required fields", () => {
+  assert.throws(
+    () => createOmniRouteMCPEntry({ serverPath: "", apiKey: "x" }),
+    /serverPath is required/
+  );
+  assert.throws(
+    () => createOmniRouteMCPEntry({ serverPath: "/p", apiKey: "" }),
+    /apiKey is required/
+  );
+});
+
+function startMockServer(
+  handler: (path: string) => unknown
+): Promise<{ url: string; close: () => void }> {
+  return new Promise((resolve) => {
+    const server: Server = createServer((req, res) => {
+      const body = JSON.stringify(handler(req.url ?? ""));
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(body);
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address() as { port: number };
+      resolve({ url: `http://127.0.0.1:${addr.port}`, close: () => server.close() });
+    });
+  });
+}
+
+test("fetchLiveModels handles array envelope", async () => {
+  const { url, close } = await startMockServer(() => [
+    { id: "claude-sonnet", name: "Claude Sonnet" },
+    { id: "gemini-flash", displayName: "Gemini Flash" },
+  ]);
+  try {
+    const models = await fetchLiveModels(url, "sk_test");
+    assert.equal(models.length, 2);
+    assert.equal(models[0].id, "claude-sonnet");
+    assert.equal(models[0].name, "Claude Sonnet");
+    assert.equal(models[1].id, "gemini-flash");
+    assert.equal(models[1].name, "Gemini Flash");
+  } finally {
+    close();
+  }
+});
+
+test("fetchLiveModels handles data-envelope and snake_case fields", async () => {
+  const { url, close } = await startMockServer(() => ({
+    data: [{ model_id: "gpt-4o", display_name: "GPT-4o" }],
+  }));
+  try {
+    const models = await fetchLiveModels(url, "sk_test");
+    assert.equal(models.length, 1);
+    assert.equal(models[0].id, "gpt-4o");
+    assert.equal(models[0].name, "GPT-4o");
+  } finally {
+    close();
+  }
+});
+
+test("fetchLiveModels falls back to id as name when no name field", async () => {
+  const { url, close } = await startMockServer(() => [{ id: "auto" }]);
+  try {
+    const models = await fetchLiveModels(url, "sk_test");
+    assert.equal(models[0].name, "auto");
+  } finally {
+    close();
+  }
+});
+
+test("listCombos normalises compressionOverride", async () => {
+  const { url, close } = await startMockServer(() => ({
+    combos: [
+      {
+        id: "c1",
+        name: "Primary",
+        strategy: "priority",
+        active: true,
+        compressionOverride: "standard",
+      },
+      {
+        id: "c2",
+        name: "Cheap",
+        strategy: "weighted",
+        active: false,
+        compressionOverride: "unknown-value",
+      },
+      { id: "c3", name: "Off", strategy: "round-robin", active: true, compressionOverride: "" },
+    ],
+  }));
+  try {
+    const combos = await listCombos(url, "sk_manage");
+    assert.equal(combos.length, 3);
+    assert.equal(combos[0].compressionOverride, "standard");
+    assert.equal(combos[1].compressionOverride, "");
+    assert.equal(combos[2].compressionOverride, "");
+  } finally {
+    close();
+  }
+});
+
+test("createOmniRouteComboConfig builds minimal payload", () => {
+  const payload = createOmniRouteComboConfig({ name: "my-combo", strategy: "priority" });
+  assert.equal(payload.name, "my-combo");
+  assert.equal(payload.strategy, "priority");
+  assert.equal(payload.active, true);
+  assert.ok(!("compressionOverride" in payload));
+  assert.ok(!("providers" in payload));
+});
+
+test("createOmniRouteComboConfig includes optional fields when supplied", () => {
+  const payload = createOmniRouteComboConfig({
+    name: "full",
+    strategy: "weighted",
+    compressionOverride: "aggressive",
+    active: false,
+    providers: ["provider-a", "provider-b"],
+  });
+  assert.equal(payload.compressionOverride, "aggressive");
+  assert.equal(payload.active, false);
+  assert.deepEqual(payload.providers, ["provider-a", "provider-b"]);
+});
+
+test("OMNIROUTE_DEFAULT_OPENCODE_MODELS includes cc/ prefixed models", () => {
+  const defaults = [...OMNIROUTE_DEFAULT_OPENCODE_MODELS];
+  assert.ok(defaults.includes("cc/claude-opus-4-8"));
+  assert.ok(
+    defaults.some((m) => m.startsWith("cc/")),
+    "should have cc/ prefixed models"
+  );
+  assert.ok(defaults.length >= 7, "should have at least 7 models");
+});
+
+test("OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS covers every default model id", () => {
+  for (const id of OMNIROUTE_DEFAULT_OPENCODE_MODELS) {
+    const ctx = OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS[id];
+    assert.ok(
+      typeof ctx === "number" && ctx > 0,
+      `default context_length for ${id} missing — should be a positive number`
+    );
+    // Sanity: context should be at least 8K, at most 2M tokens
+    assert.ok(ctx >= 8_000, `${id} context_length ${ctx} seems too low`);
+    assert.ok(ctx <= 2_000_000, `${id} context_length ${ctx} seems too high`);
+  }
+});
+
+test("createOmniRouteProvider emits limit.context on default model entries", () => {
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+  });
+  const entry = provider.models["cc/claude-opus-4-8"];
+  assert.ok(entry.limit, "model entry should have a limit field");
+  assert.equal(entry.limit!.context, 1_000_000);
+  assert.equal(provider.models["cc/claude-opus-4-7"].limit!.context, 1_000_000);
+});
+
+test("createOmniRouteProvider omits limit.context for unknown model ids", () => {
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+    models: ["completely-unknown-model"],
+  });
+  const entry = provider.models["completely-unknown-model"];
+  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",
+    apiKey: "sk_omniroute",
+  });
+  const round = JSON.parse(JSON.stringify(provider));
+  for (const id of OMNIROUTE_DEFAULT_OPENCODE_MODELS) {
+    const expectedContext = OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS[id];
+    assert.equal(
+      round.models[id].limit?.context,
+      expectedContext,
+      `${id} should serialise limit.context=${expectedContext}`
+    );
+  }
+});
+
+test("fetchLiveModels extracts context_length from snake_case field", async () => {
+  const { url, close } = await startMockServer(() => ({
+    data: [
+      { id: "cc/claude-opus-4-7", name: "Claude Opus 4.7", context_length: 200_000 },
+      { id: "gemini-3.1-pro-high", name: "Gemini 3.1 Pro", context_length: 1_000_000 },
+      { id: "no-context", name: "No Context" },
+    ],
+  }));
+  try {
+    const models = await fetchLiveModels(url, "sk_test");
+    const claude = models.find((m) => m.id === "cc/claude-opus-4-7");
+    assert.ok(claude, "claude model should be present");
+    assert.equal(claude!.contextLength, 200_000);
+    const gemini = models.find((m) => m.id === "gemini-3.1-pro-high");
+    assert.equal(gemini!.contextLength, 1_000_000);
+    const noCtx = models.find((m) => m.id === "no-context");
+    assert.equal(noCtx!.contextLength, undefined);
+  } finally {
+    close();
+  }
+});
+
+test("OMNIROUTE_DEFAULT_MODEL_CAPABILITIES covers every default model id", () => {
+  for (const id of OMNIROUTE_DEFAULT_OPENCODE_MODELS) {
+    const caps = OMNIROUTE_DEFAULT_MODEL_CAPABILITIES[id];
+    assert.ok(caps, `default capabilities for ${id} missing`);
+    assert.equal(caps.attachment, true, `${id} should default to attachment=true`);
+    assert.equal(caps.tool_call, true, `${id} should default to tool_call=true`);
+  }
+});
+
+test("createOmniRouteProvider emits default capability flags inline with the model entry", () => {
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+  });
+  const entry = provider.models["cc/claude-opus-4-8"];
+  assert.equal(entry.name, "cc/claude-opus-4-8");
+  assert.equal(entry.attachment, true);
+  assert.equal(entry.reasoning, true);
+  assert.equal(entry.temperature, true);
+  assert.equal(entry.tool_call, true);
+});
+
+test("createOmniRouteProvider modelCapabilities overrides defaults and merges per id", () => {
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+    modelCapabilities: {
+      "cc/claude-opus-4-7": { reasoning: false, label: "Opus (no thinking)" },
+    },
+  });
+  const entry = provider.models["cc/claude-opus-4-7"];
+  assert.equal(entry.name, "Opus (no thinking)");
+  assert.equal(entry.reasoning, false);
+  assert.equal(entry.attachment, true);
+  assert.equal(entry.tool_call, true);
+});
+
+test("createOmniRouteProvider applies capability overrides to non-default model ids", () => {
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+    models: ["custom-model"],
+    modelCapabilities: {
+      "custom-model": { attachment: false, tool_call: true, label: "Custom" },
+    },
+  });
+  const entry = provider.models["custom-model"];
+  assert.equal(entry.name, "Custom");
+  assert.equal(entry.attachment, false);
+  assert.equal(entry.tool_call, true);
+  assert.equal(entry.reasoning, undefined);
+  assert.equal(entry.temperature, undefined);
+});
+
+test("createOmniRouteProvider modelLabels still works when modelCapabilities omits label", () => {
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+    models: ["claude-opus-4-5-thinking"],
+    modelLabels: { "claude-opus-4-5-thinking": "Opus 4.5 (legacy label)" },
+  });
+  assert.equal(provider.models["claude-opus-4-5-thinking"].name, "Opus 4.5 (legacy label)");
+});
+
+test("createOmniRouteAgentBlock builds provider-prefixed entries per role", () => {
+  const block = createOmniRouteAgentBlock({
+    roles: {
+      build: { modelId: "claude-sonnet-4-5-thinking", temperature: 0.2 },
+      plan: { modelId: "claude-opus-4-5-thinking", top_p: 0.95 },
+      review: { modelId: "gemini-3-flash", temperature: 0.0 },
+    },
+  });
+  assert.equal(block.build.model, "omniroute/claude-sonnet-4-5-thinking");
+  assert.equal(block.build.temperature, 0.2);
+  assert.equal(block.plan.model, "omniroute/claude-opus-4-5-thinking");
+  assert.equal(block.plan.top_p, 0.95);
+  assert.equal(block.review.model, "omniroute/gemini-3-flash");
+  assert.equal(block.review.temperature, 0.0);
+});
+
+test("createOmniRouteAgentBlock omits optional fields when not supplied", () => {
+  const block = createOmniRouteAgentBlock({
+    roles: { build: { modelId: "claude-sonnet-4-5-thinking" } },
+  });
+  assert.equal(block.build.model, "omniroute/claude-sonnet-4-5-thinking");
+  assert.ok(!("temperature" in block.build));
+  assert.ok(!("top_p" in block.build));
+  assert.ok(!("tools" in block.build));
+  assert.ok(!("prompt" in block.build));
+});
+
+test("createOmniRouteAgentBlock skips roles with empty modelId", () => {
+  const block = createOmniRouteAgentBlock({
+    roles: {
+      build: { modelId: "claude-sonnet-4-5-thinking" },
+      plan: { modelId: "   " },
+      review: { modelId: "" },
+    },
+  });
+  assert.deepEqual(Object.keys(block), ["build"]);
+});
+
+test("createOmniRouteAgentBlock emits tools as Record<string, boolean> per OC schema", () => {
+  const block = createOmniRouteAgentBlock({
+    roles: {
+      build: {
+        modelId: "claude-sonnet-4-5-thinking",
+        tools: { edit: true, bash: true, web: false },
+        prompt: "Edit files carefully.",
+      },
+    },
+  });
+  assert.deepEqual(block.build.tools, { edit: true, bash: true, web: false });
+  assert.equal(block.build.prompt, "Edit files carefully.");
+});
+
+test("createOmniRouteAgentBlock filters invalid tool entries and omits empty maps", () => {
+  const block = createOmniRouteAgentBlock({
+    roles: {
+      build: {
+        modelId: "claude-sonnet-4-5-thinking",
+        // @ts-expect-error — exercising runtime guard against bad input
+        tools: { edit: true, bash: "yes", "": true, web: null },
+      },
+      plan: {
+        modelId: "claude-opus-4-5-thinking",
+        tools: {},
+      },
+    },
+  });
+  assert.deepEqual(block.build.tools, { edit: true });
+  assert.ok(!("tools" in block.plan));
+});
+
+test("createOmniRouteModesBlock builds provider-prefixed mode entries", () => {
+  const block = createOmniRouteModesBlock({
+    modes: {
+      build: { modelId: "claude-sonnet-4-5-thinking", tools: { edit: true, bash: true } },
+      plan: { modelId: "claude-opus-4-5-thinking", prompt: "Plan first, code later." },
+      review: { modelId: "gemini-3-flash" },
+    },
+  });
+  assert.equal(block.build.model, "omniroute/claude-sonnet-4-5-thinking");
+  assert.deepEqual(block.build.tools, { edit: true, bash: true });
+  assert.equal(block.plan.prompt, "Plan first, code later.");
+  assert.equal(block.review.model, "omniroute/gemini-3-flash");
+});
+
+test("createOmniRouteModesBlock skips modes with empty modelId", () => {
+  const block = createOmniRouteModesBlock({
+    modes: {
+      build: { modelId: "claude-sonnet-4-5-thinking" },
+      plan: { modelId: "" },
+    },
+  });
+  assert.deepEqual(Object.keys(block), ["build"]);
+});
+
+test("createOmniRouteModesBlock honours numeric overrides limited to OC schema", () => {
+  const block = createOmniRouteModesBlock({
+    modes: {
+      build: {
+        modelId: "claude-sonnet-4-5-thinking",
+        temperature: 0.7,
+        top_p: 0.9,
+      },
+    },
+  });
+  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/);
+});

@omniroute/opencode-provider/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUncheckedIndexedAccess": false,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "node_modules", "tests"]
+}

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

@@ -0,0 +1,18 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm", "cjs"],
+  dts: true,
+  clean: true,
+  sourcemap: false,
+  splitting: false,
+  treeshake: true,
+  target: "node22",
+  outDir: "dist",
+  minify: false,
+});
+
+// CJS consumers should prefer named imports (`require(pkg).createOmniRouteProvider`).
+// The `default` export is also exposed for ESM ergonomics, which makes tsup warn
+// about mixed exports — that's expected and harmless for this package.

AGENTS.md

@@ -3,158 +3,594 @@
 ## Project
 
 Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support
-(OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks, Cohere, etc.)
-with **MCP Server** (16 tools for agent control) and **A2A v0.3 Protocol** (Agent-to-Agent orchestration).
+with **250 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** (94 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.
+
+> **Live counts (v3.8.47)**: providers 250 · MCP tools 94 · MCP scopes 30 · A2A skills 6 ·
+> open-sse services 134 · routing strategies 17 · auto-combo scoring factors 12 ·
+> DB modules 95 · DB migrations 110 · base tables 17 · search providers 11 ·
+> i18n locales 42. **Refresh with `npm run check:docs-all`.**
+
+## Doc Accuracy Discipline (read before writing any doc)
+
+> **If `grep -rn "name" src/ open-sse/ bin/` returns nothing, the name does not exist. Do not document it.**
+
+The recurring failure mode in AI-generated docs is _plausible-but-unverified specifics_.
+Every claim in a `.md` file under `docs/` should be verifiable against the source.
+
+**Rules (enforced by `npm run check:fabricated-docs`):**
+
+1. **Never state an API name, endpoint, path, CLI command, or env var without grepping for it first.**
+   ```bash
+   grep -rn "theName" src/ open-sse/ bin/
+   # 0 hits → do not document
+   ```
+2. **Never write a line count, file size, migration count, provider count, or strategy count from memory.**
+   ```bash
+   wc -l <file>           # exact line count
+   ls <dir>/*.ts | wc -l  # file count
+   ```
+3. **Every code example should be copy-pasted from real usage or actually run** — not synthesized.
+   Link to a real call site (`path:line`) instead of inventing a signature.
+4. **Prefer citing real source (`file.ts:line`) over paraphrasing behavior** — verifiable and self-correcting.
+5. **A shorter doc that is 100% accurate beats a comprehensive one with fabrications.**
+   Wrong docs cost more than missing docs, because people trust and act on them.
+
+The script `scripts/check/check-fabricated-docs.mjs` extracts every route path, env var, hook
+name, function name, and file reference from `docs/**/*.md` and verifies each one against the
+codebase. Run it locally before pushing docs; it runs in CI via `npm run check:docs-all`.
 
 ## Stack
 
-- **Runtime**: Next.js 16 (App Router), Node.js, ES Modules
-- **Language**: TypeScript 5.9 (`src/`) + JavaScript (`open-sse/`)
+- **Runtime**: Next.js 16 (App Router), Node.js `>=22.0.0 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
+- **Language**: TypeScript 6.0 (`src/`) + JavaScript (`open-sse/`, `electron/`)
 - **Database**: better-sqlite3 (SQLite) — `DATA_DIR` configurable, default `~/.omniroute/`
-- **Streaming**: SSE via `open-sse` internal package
+- **Streaming**: SSE via `open-sse` internal workspace package
 - **Styling**: Tailwind CSS v4
-- **Docker**: Multi-stage Dockerfile, 3 profiles (base / cli / host)
-- **i18n**: next-intl with 30 languages (`src/i18n/messages/`)
+- **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
+
+---
+
+## Build, Lint, and Test Commands
+
+| 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
+
+```bash
+# All tests (unit + vitest + ecosystem + e2e)
+npm run test:all
+
+# Single test file (Node.js native test runner — most tests use this)
+node --import tsx/esm --test tests/unit/your-file.test.ts
+node --import tsx/esm --test tests/unit/plan3-p0.test.ts
+node --import tsx/esm --test tests/unit/fixes-p1.test.ts
+node --import tsx/esm --test tests/unit/security-fase01.test.ts
+
+# Integration tests
+node --import tsx/esm --test tests/integration/*.test.ts
+
+# Vitest (MCP server, autoCombo)
+npm run test:vitest
+
+# E2E with Playwright
+npm run test:e2e
+
+# Protocol clients E2E (MCP transports, A2A)
+npm run test:protocols:e2e
+
+# Ecosystem compatibility tests
+npm run test:ecosystem
+
+# Coverage (see CONTRIBUTING.md)
+npm run test:coverage
+```
+
+**For authoritative coverage requirements, test execution, and PR gates, see [`CONTRIBUTING.md`](CONTRIBUTING.md#running-tests).**
+
+---
+
+## Code Style Guidelines
+
+### Formatting (Prettier — enforced via lint-staged)
+
+2 spaces · semicolons required · double quotes (`"`) · 100 char width · es5 trailing commas.
+Always run `prettier --write` on changed files.
+
+### TypeScript
+
+- **Target**: ES2022 · **Module**: `esnext` · **Resolution**: `bundler`
+- `strict: false` — prefer explicit types, don't rely on inference
+- Path aliases: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
+
+### ESLint Rules
+
+- **Security (error, everywhere)**: `no-eval`, `no-implied-eval`, `no-new-func`
+- **Relaxed in `open-sse/` and `tests/`**: `@typescript-eslint/no-explicit-any` = warn
+- React hooks rules and `@next/next/no-assign-module-variable` disabled in `open-sse/` and `tests/`
+
+### Naming
+
+| Element             | Convention                       | Example                              |
+| ------------------- | -------------------------------- | ------------------------------------ |
+| Files               | camelCase / kebab-case           | `chatCore.ts`, `tokenHealthCheck.ts` |
+| React components    | PascalCase                       | `Dashboard.tsx`, `ProviderCard.tsx`  |
+| Functions/variables | camelCase                        | `getHealth()`, `switchCombo()`       |
+| Constants           | UPPER_SNAKE                      | `MAX_RETRIES`, `DEFAULT_TIMEOUT`     |
+| Interfaces          | PascalCase (`I` prefix optional) | `ProviderConfig`                     |
+| Enums               | PascalCase (members too)         | `LogLevel.Error`                     |
+
+### Imports
+
+- **Order**: external → internal (`@/`, `@omniroute/open-sse`) → relative (`./`, `../`)
+- **No barrel imports** from `localDb.ts` — import from the specific `db/` module instead
+
+### Error Handling
+
+- try/catch with specific error types; always log with context (pino logger)
+- Never silently swallow errors in SSE streams — use abort signals for cleanup
+- Return proper HTTP status codes (4xx client, 5xx server)
+
+### Security
+
+- **NEVER** commit API keys, secrets, or credentials
+- Validate all user inputs with Zod schemas
+- Auth middleware required on all API routes
+- Never log SQLite encryption keys
+- Sanitize user content (dompurify for HTML)
+- **Public upstream OAuth identifiers** (Gemini / Antigravity / Windsurf-style client_id/secret + Firebase Web keys extracted from public CLIs): use `resolvePublicCred()` from `open-sse/utils/publicCreds.ts`, **never** as string literals. Full pattern in `docs/security/PUBLIC_CREDS.md`.
+- **Error responses** (HTTP / SSE / executor / MCP): use `buildErrorBody()` or `sanitizeErrorMessage()` from `open-sse/utils/error.ts`, **never** put raw `err.stack` / `err.message` in a Response body. Full pattern in `docs/security/ERROR_SANITIZATION.md`.
+- **`exec()` / `spawn()` with runtime values**: pass via the `env` option, **never** string-interpolate paths/values into the script body. Reference: `src/mitm/cert/install.ts::updateNssDatabases`.
+- Prefer secure-by-default libraries when available — see [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults) for the curated list (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink, etc.).
+
+---
 
 ## Architecture
 
 ### Data Layer (`src/lib/db/`)
 
-All persistence uses SQLite through domain-specific modules:
+All persistence uses SQLite through **95 domain-specific modules** in `src/lib/db/`. Top modules:
 
-| Module         | Responsibility                             |
-| -------------- | ------------------------------------------ |
-| `core.ts`      | SQLite engine, migrations, WAL, encryption |
-| `providers.ts` | Provider connections & nodes               |
-| `models.ts`    | Model aliases, MITM aliases, custom models |
-| `combos.ts`    | Combo configurations                       |
-| `apiKeys.ts`   | API key management & validation            |
-| `settings.ts`  | Settings, pricing, proxy config            |
-| `backup.ts`    | Backup / restore operations                |
+- Core: `core.ts`, `migrationRunner.ts`, `encryption.ts`, `stateReset.ts`
+- Providers / catalog: `providers.ts`, `models.ts`, `providerLimits.ts`, `compressionAnalytics.ts`
+- Routing: `combos.ts`, `modelComboMappings.ts`, `domainState.ts`, `commandCodeAuth.ts`
+- Auth: `apiKeys.ts`, `secrets.ts`, `registeredKeys.ts`, `sessionAccountAffinity.ts`
+- Usage / billing: `quotaSnapshots.ts`, `creditBalance.ts`, `usage*.ts`, `compressionCacheStats.ts`
+- 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`
 
-`src/lib/localDb.ts` is a **re-export layer only** — all 27+ consumers import from it,
-but the real logic lives in `src/lib/db/`.
+Live count: `ls src/lib/db/*.ts | wc -l` (currently 95). Drift detection: `npm run check:docs-counts`.
+Schema migrations live in `db/migrations/` (**110 files** as of v3.8.43) 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 **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**: 110 files (`001_initial_schema.sql` → `110_*.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`,
+  `combos.ts` → `combos`). Encryption helpers protect sensitive fields at rest.
+- **`localDb.ts`** re-exports all domain modules — consumers import from here for convenience.
+
+### API Route Layer (`src/app/api/v1/`)
+
+Next.js App Router routes — each follows a consistent pattern:
+
+```
+Route → CORS preflight → Body validation (Zod) → Optional auth (extractApiKey/isValidApiKey)
+  → 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 (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.
 
 ### Request Pipeline (`open-sse/`)
 
-| Handler                 | Role                                        |
-| ----------------------- | ------------------------------------------- |
-| `chatCore.js`           | Main chat completions proxy (SSE / non-SSE) |
-| `responsesHandler.js`   | OpenAI Responses API compat                 |
-| `responseTranslator.js` | Format translation for Responses API        |
-| `embeddings.js`         | Embedding proxy                             |
-| `imageGeneration.js`    | Image generation proxy                      |
-| `sseParser.js`          | SSE stream parser                           |
-| `usageExtractor.js`     | Token usage extraction from responses       |
+The `open-sse/` workspace is the core streaming engine. Full request flow:
 
-Translation between provider formats: `open-sse/translator/`
+```
+Client Request
+  → src/app/api/v1/.../route.ts (Next.js route)
+    → open-sse/handlers/chatCore.ts::handleChatCore()
+      → Semantic/signature cache check
+      → Rate limit check (rateLimitManager)
+      → Combo routing? → open-sse/services/combo.ts::handleComboChat()
+        → resolveComboTargets() → ordered ResolvedComboTarget[]
+        → For each target: handleSingleModel() (wraps chatCore)
+      → translateRequest() (open-sse/translator/)
+        → Convert source format (e.g., OpenAI) → target format (e.g., Claude)
+      → getExecutor() → provider-specific executor instance
+        → executor.execute() (BaseExecutor → DefaultExecutor or provider-specific)
+          → buildUrl() + buildHeaders() + transformRequest()
+          → fetch() to upstream provider
+          → Retry logic with exponential backoff
+      → Response translation back to client format
+      → If Responses API: responsesTransformer.ts TransformStream
+  → SSE stream or JSON response to client
+```
+
+**Handlers** (`open-sse/handlers/`): `chatCore.ts`, `responsesHandler.ts`, `embeddings.ts`,
+`imageGeneration.ts`, `videoGeneration.ts`, `musicGeneration.ts`, `audioSpeech.ts`,
+`audioTranscription.ts`, `moderations.ts`, `rerank.ts`, `search.ts`.
+
+**Upstream headers**: merged after default auth; same header name replaces executor value.
+**T5 intra-family fallback** recomputes headers using only the fallback model id.
+Forbidden header names: `src/shared/constants/upstreamHeaders.ts` — keep sanitize,
+Zod schemas, and unit tests aligned when editing.
+
+### Provider Categories
+
+- **Free** (3): Qoder AI, Qwen Code, Kiro AI
+- **OAuth** (14): Claude Code, Antigravity, Codex, GitHub Copilot, Cursor, Kimi Coding, Kilo Code, Cline, Qwen (⚠️ free tier discontinued 2026-04-15), Kiro, Qoder, Gemini, Windsurf (v3.8), GitLab Duo (v3.8)
+- **API Key** (120+): OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Perplexity,
+  Together, Fireworks, Cerebras, Cohere, NVIDIA, Nebius, SiliconFlow, Hyperbolic,
+  HuggingFace, OpenRouter, Vertex AI, Cloudflare AI, Scaleway, AI/ML API, Pollinations,
+  Puter, Longcat, Alibaba, Kimi, Minimax, Blackbox, Synthetic, Kilo Gateway,
+  Z.AI, GLM, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld,
+  NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper, Brave, Exa,
+  Tavily, OpenCode Zen/Go, Bailian Coding Plan, DeepInfra, Vercel AI Gateway,
+  Lambda AI, SambaNova, nScale, OVHcloud AI, Baseten, PublicAI, Moonshot AI,
+  Meta Llama API, v0 (Vercel), Morph, Featherless AI, FriendliAI, LlamaGate,
+  Galadriel, Weights & Biases Inference, Volcengine, AI21 Labs, Venice.ai,
+  Codestral, Upstage, Maritalk, Xiaomi MiMo, Inference.net, NanoGPT, Predibase,
+  Bytez, Heroku AI, Databricks, Snowflake Cortex, GigaChat (Sber), CrofAI,
+  AgentRouter, ChatGPT Web, Baidu Qianfan, AWS Polly, RunwayML, GitLab Duo,
+  Amazon Q, Empower, Poe, and many more.
+- **Self-Hosted** (8+): LM Studio, vLLM, Lemonade, Llamafile, Triton, Docker Model Runner, Xinference, Oobabooga
+- **Custom**: OpenAI-compatible (`openai-compatible-*`) and Anthropic-compatible (`anthropic-compatible-*`) prefixes
+
+Providers are registered in `src/shared/constants/providers.ts` with Zod validation at module load.
+
+### Executors (`open-sse/executors/`)
+
+Provider-specific request executors: `base.ts`, `default.ts`, `cursor.ts`, `codex.ts`,
+`antigravity.ts`, `github.ts`, `kiro.ts`, `qoder.ts`, `vertex.ts`,
+`cloudflare-ai.ts`, `opencode.ts`, `pollinations.ts`, `puter.ts`.
+
+#### Executor Internals
+
+- **`base.ts`** (`BaseExecutor`): Abstract base with `buildUrl()`, `buildHeaders()`,
+  `transformRequest()`, retry logic (exponential backoff), and `execute()`. Subclasses
+  override URL/header/transform methods for provider-specific behavior.
+- **`default.ts`** (`DefaultExecutor extends BaseExecutor`): Handles most OpenAI-compatible
+  providers. Reads provider config from `providerRegistry.ts` to resolve base URL, auth
+  header format, and request transformations.
+- **`getExecutor()`** (`executors/index.ts`): Factory that returns the correct executor
+  instance based on provider ID. Provider-specific executors (Cursor, Codex, Vertex, etc.)
+  override only what differs from the default.
+
+### Translator (`open-sse/translator/`)
+
+Translates between API formats (OpenAI-format ↔ Anthropic, Gemini, etc.).
+Includes request/response translators with helpers for image handling.
+
+#### Translator Internals
+
+- **`translator/index.ts`**: Exports `translateRequest()` and format constants. Called by
+  `chatCore.ts` before executor dispatch.
+- **Flow**: `translateRequest(body, sourceFormat, targetFormat)` → detects source format
+  (OpenAI, Anthropic, Gemini) → applies the matching translator module → returns
+  transformed body ready for the target provider.
+- **Response translation** runs in reverse after upstream response, converting back to
+  the client's expected format.
+
+### Transformer (`open-sse/transformer/`)
+
+`responsesTransformer.ts` — transforms Responses API format to/from Chat Completions format.
+
+#### Transformer Internals
+
+- **`createResponsesApiTransformStream()`**: Returns a `TransformStream` that converts
+  Chat Completions SSE chunks (`data: {"choices":[...]}`) into Responses API SSE events
+  (`response.output_item.added`, `response.output_text.delta`, etc.).
+- Used when the client sends a Responses API request: the request is internally converted
+  to Chat Completions format, dispatched normally, and the response is piped through this
+  transform stream before reaching the client.
+
+### Services (`open-sse/services/`)
+
+134 service modules in `open-sse/services/` (top-level only; more 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`,
+`emergencyFallback.ts`, `workflowFSM.ts`, `backgroundTaskDetector.ts`, `ipFilter.ts`,
+`signatureCache.ts`, `volumeDetector.ts`, `contextHandoff.ts`, `compression/` (prompt
+compression pipeline), and more.
+
+#### Prompt Compression Pipeline (`compression/`)
+
+Modular prompt compression that runs proactively before the existing reactive context manager.
+
+- **`strategySelector.ts`**: Selects compression mode based on config, compression combo assignments,
+  combo overrides, auto-trigger thresholds, and defaults. Priority: assigned compression combo >
+  combo override > auto-trigger > default mode > off.
+- **`lite.ts`**: 5 lite-mode techniques: `collapseWhitespace`, `dedupSystemPrompt`,
+  `compressToolResults`, `removeRedundantContent`, `replaceImageUrls`. Target: 10-15% savings at
+  <1ms latency.
+- **`caveman.ts` / `cavemanRules.ts`**: Caveman-style semantic condensation backed by built-in
+  rules plus file-loaded language packs under `compression/rules/`.
+- **`engines/rtk/`**: Rule-based terminal/tool-output compression inspired by RTK patterns. Detects
+  command output classes, applies JSON filter packs, deduplicates repeated lines, strips ANSI/code
+  noise, and preserves errors/actionable context. The RTK JSON DSL supports replace,
+  match-output short-circuit, strip/keep, per-line truncation, head/tail/max-line truncation,
+  inline tests, trust-gated project/global custom filters, and optional redacted raw-output
+  retention for authenticated recovery.
+- **`engines/registry.ts`**: Registers engines (`caveman`, `rtk`) and powers stacked pipelines.
+- **`stats.ts`**: Per-request compression stats tracking (original tokens, compressed tokens,
+  savings %, techniques used, engine breakdown, compression combo id).
+- **`types.ts`**: `CompressionMode` (off/lite/standard/aggressive/ultra/rtk/stacked),
+  `CompressionConfig`, `CompressionStats`, `CompressionResult`.
+- DB settings in `src/lib/db/compression.ts`, compression combos in
+  `src/lib/db/compressionCombos.ts`, API routes under `src/app/api/settings/compression/`,
+  `src/app/api/context/*`, and preview/language-pack routes under `src/app/api/compression/*`.
+
+#### Combo Routing Engine (`combo.ts`)
+
+- **`handleComboChat()`**: Entry point for combo-routed requests. Receives the combo config
+  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** (17): 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, headroom, fusion. 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.
+
+### Domain Layer (`src/domain/`)
+
+Policy engine modules: `policyEngine.ts`, `comboResolver.ts`, `costRules.ts`,
+`degradation.ts`, `fallbackPolicy.ts`, `lockoutPolicy.ts`, `modelAvailability.ts`,
+`providerExpiration.ts`, `quotaCache.ts`, `responses.ts`, `configAudit.ts`.
 
 ### MCP Server (`open-sse/mcp-server/`)
 
-16 tools for AI agent control via **3 transport modes**:
-- **stdio** — Local IDE integration (Claude Desktop, Cursor, VS Code)
-- **SSE** — Remote Server-Sent Events at `/api/mcp/sse`
-- **Streamable HTTP** — Modern bidirectional HTTP at `/api/mcp/stream`
+**94 tools** total (`TOTAL_MCP_TOOL_COUNT`, `open-sse/mcp-server/server.ts`): a 34-entry base registry (`MCP_TOOLS` in `schemas/tools.ts`, bundling the core / cache / compression / 1proxy / advanced tools) **plus** standalone module sets — memory (3), skill (4), agentSkill (3), pool (6), gamification (8), plugin (8), notion (6), obsidian (22). 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (30 scopes — see `OMNIROUTE_MCP_SCOPES`), Zod schemas. See [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md).
 
-HTTP transports run in-process via `httpTransport.ts` singleton using `WebStandardStreamableHTTPServerTransport`.
+**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,
+set_routing_strategy, set_resilience_profile, test_combo, get_provider_metrics,
+best_combo_for_task, explain_route, get_session_snapshot, db_health_check, sync_pricing.
 
-| Category   | Tools                                                                                                                     |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------- |
-| Essential  | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog` |
-| Advanced   | `simulate_route`, `set_budget_guard`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot` |
+**Cache tools** (2): cache_stats, cache_flush.
 
-- Scoped authorization (9 scopes), audit logging, Zod schemas
-- IDE configs for Claude Desktop, Cursor, VS Code Copilot
+**Compression tools** (5): compression_status, compression_configure, set_compression_engine,
+list_compression_combos, compression_combo_stats.
+
+**1proxy tools** (3): oneproxy_fetch, oneproxy_rotate, oneproxy_stats.
+
+**Memory tools** (3): memory_search, memory_add, memory_clear.
+
+**Skill tools** (4): skills_list, skills_enable, skills_execute, skills_executions.
+
+**Agent-skill tools** (3): A2A skill discovery / invocation bridges.
+
+**Gamification tools** (8): levels, badges, leaderboard, and community-federation queries.
+
+**Plugin tools** (8): plugin marketplace listing, install/enable/disable, and runtime inspection.
+
+**Notion tools** (6) + **Obsidian tools** (22): knowledge-base read/write integrations (the largest tool family — vault search, note CRUD, WebDAV-backed file ops).
+
+#### MCP Internals
+
+- **Tool registration**: Each tool is an object with `{ name, description, inputSchema: ZodSchema,
+handler: async (args) => {...} }`. Zod validates inputs before the handler fires.
+- **`createMcpServer()`** and **`startMcpStdio()`** exported from `mcp-server/index.ts`.
+  `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** (30): Control which tool categories an API key can access. Enforcement happens
+  before handler dispatch.
+- **Audit**: Every tool invocation is logged to SQLite (`mcp_audit` table) with tool name,
+  args, success/failure, API key attribution, and timestamp.
 
 ### A2A Server (`src/lib/a2a/`)
 
-Agent-to-Agent v0.3 protocol:
+JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup.
+Agent Card at `/.well-known/agent.json`.
+Skills (6): `smartRouting.ts`, `quotaManagement.ts`, `providerDiscovery.ts`, `costAnalysis.ts`, `healthReport.ts`, `listCapabilities.ts`.
 
-- JSON-RPC 2.0: `message/send`, `message/stream`, `tasks/get`, `tasks/cancel`
-- Agent Card at `/.well-known/agent.json`
-- Skills: `smart-routing`, `quota-management`
-- SSE streaming with 15s heartbeat
-- Task Manager with state machine and TTL-based cleanup
+#### A2A Internals
 
-### Auto-Combo Engine (`open-sse/services/autoCombo/`)
+- **`taskManager.ts`**: State machine lifecycle for tasks: `submitted → working →
+completed | failed | canceled`. Tasks have TTL and are cleaned up automatically.
+- **JSON-RPC methods**: `message/send` (sync), `message/stream` (SSE), `tasks/get`,
+  `tasks/cancel`. Dispatched via `POST /a2a`.
+- **Skills**: Registered in a DB-backed registry. Each skill receives task context
+  (messages, metadata) and returns structured results. `quotaManagement.ts` summarizes
+  quota; `smartRouting.ts` recommends routing decisions.
+- **Agent Card**: `/.well-known/agent.json` exposes capabilities, skills, and metadata
+  for client auto-discovery.
 
-Self-healing routing optimization:
-- 6-factor scoring, 4 mode packs, bandit exploration
-- Progressive cooldown, probe-based re-admission
+### ACP Module (`src/lib/acp/`)
 
-### Dashboard (`src/app/(dashboard)/`)
+Agent Communication Protocol registry and manager.
 
-| Page                         | Description                                                    |
-| ---------------------------- | -------------------------------------------------------------- |
-| `/dashboard`                 | Home with quick start, provider overview                       |
-| `/dashboard/endpoint`        | **Endpoints** (tabbed): Endpoint Proxy, MCP, A2A, API Endpoints |
-| `/dashboard/providers`       | Provider management and connections                            |
-| `/dashboard/combos`          | Combo configurations with routing strategies                   |
-| `/dashboard/logs`            | Request, Proxy, Audit, Console logs (tabbed)                   |
-| `/dashboard/analytics`       | Usage analytics and evaluations                                |
-| `/dashboard/costs`           | Cost tracking and breakdown                                    |
-| `/dashboard/health`          | Uptime, circuit breakers, latency                              |
-| `/dashboard/cli-tools`       | CLI tool integrations (Claude, Codex, Antigravity, etc.)       |
-| `/dashboard/media`           | Image, Video, Music generation playground                      |
-| `/dashboard/settings`        | System settings with multiple tabs                             |
-| `/dashboard/api-manager`     | API key management with model permissions                      |
+### Memory System (`src/lib/memory/`)
 
-### OAuth & Tokens (`src/lib/oauth/`)
+Extraction, injection, retrieval, summarization, and store modules for persistent
+conversational memory across sessions.
 
-18 modules handling OAuth flows, token refresh, and provider credentials.
-Default credentials are hardcoded in `src/lib/oauth/constants/oauth.ts`,
-overridable via env vars or `data/provider-credentials.json`.
+### Skills System (`src/lib/skills/`)
 
-### Supporting Systems
+Extensible skill framework: registry, executor, sandbox, built-in skills,
+custom skill support, interception, and injection.
 
-| System                     | Location                                          |
-| -------------------------- | ------------------------------------------------- |
-| Usage tracking & analytics | `src/lib/usageDb.ts`, `src/lib/usageAnalytics.ts` |
-| Token health checks        | `src/lib/tokenHealthCheck.ts`                     |
-| Cloud sync                 | `src/lib/cloudSync.ts`                            |
-| Proxy logging              | `src/lib/proxyLogger.ts`                          |
-| Data paths resolution      | `src/lib/dataPaths.ts`                            |
+#### Skills Internals
+
+- **`registry.ts`**: DB-backed skill registration and discovery. Skills have metadata
+  (name, description, version, enabled status) stored in SQLite.
+- **`executor.ts`**: Execution engine with configurable timeout and retry logic.
+  Receives skill name + input, looks up the skill, runs it in the sandbox.
+- **`sandbox.ts`**: Isolation layer for custom (user-provided) skills. Limits resource
+  access and execution time.
+- **Built-in skills**: Ship with OmniRoute (e.g., quota management, routing). Located
+  alongside the registry.
+- **Interception/Injection**: Skills can intercept requests in the pipeline (pre/post
+  processing) or inject context into prompts.
+
+### Compliance (`src/lib/compliance/`)
+
+Policy index for compliance enforcement.
+
+### MITM Proxy (`src/mitm/`)
+
+MITM proxy capability with certificate management, DNS handling, and target routing.
+
+### Middleware (`src/middleware/`)
+
+Request middleware including `promptInjectionGuard.ts`.
+
+### Guardrails (`src/lib/guardrails/`)
+
+Hot-reloadable guardrails framework (3 built-in: pii-masker, prompt-injection, vision-bridge). Fail-open. The `pii-masker` guardrail is registered and runs on every request, but its data-mutating logic is **opt-in** and OFF by default — it only redacts when `PII_REDACTION_ENABLED` (request) / `PII_RESPONSE_SANITIZATION` (response + streaming) are enabled (both `defaultValue: "false"`); with them off, payloads pass through untouched. A request can additionally opt OUT of any guardrail via header (`x-omniroute-disabled-guardrails`). Never make PII default-on (Hard Rule #20). See [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md).
+
+### Cloud Agents (`src/lib/cloudAgent/`)
+
+`CloudAgentBase` abstract class + 3 agents (codex-cloud, devin, jules). Tasks persisted in `cloud_agent_tasks`; management auth required. See [`docs/frameworks/CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md).
+
+### Evals (`src/lib/evals/`)
+
+Generic eval framework: `evalRunner.ts`, `runtime.ts`. Targets: combo / model / suite-default. See [`docs/frameworks/EVALS.md`](docs/frameworks/EVALS.md).
+
+### Webhooks (`src/lib/webhookDispatcher.ts`)
+
+HMAC-signed delivery, exponential backoff, auto-disable after 10 failures. 7 event types. See [`docs/frameworks/WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md).
+
+### Authorization Pipeline (`src/server/authz/`)
+
+`classify → policies → enforce`. 3 route classes (PUBLIC / CLIENT_API / MANAGEMENT). See [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md).
+
+### Reasoning Replay (`src/lib/db/reasoningCache.ts` + `open-sse/services/reasoningCache.ts`)
+
+Hybrid in-memory + SQLite cache for `reasoning_content`. Re-injects on multi-turn for strict providers (DeepSeek V4, Kimi K2, Qwen-Thinking, GLM, xiaomi-mimo). See [`docs/routing/REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md).
+
+### Tunnels (`src/lib/{cloudflaredTunnel,ngrokTunnel}.ts` + `src/app/api/tunnels/`)
+
+Cloudflare Quick/Named, ngrok, Tailscale Funnel. See [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md).
 
 ### Adding a New Provider
 
 1. Register in `src/shared/constants/providers.ts`
-2. Add executor in `open-sse/executors/`
-3. Add translator rules in `open-sse/translator/` (if non-OpenAI format)
+2. Add executor in `open-sse/executors/` (if custom logic needed)
+3. Add translator in `open-sse/translator/` (if non-OpenAI format)
 4. Add OAuth config in `src/lib/oauth/constants/oauth.ts` (if OAuth-based)
+5. Add models in `open-sse/config/providerRegistry.ts`
+
+---
+
+## Subdirectory AGENTS.md Files
+
+- **[`src/lib/db/AGENTS.md`](src/lib/db/AGENTS.md)** — SQLite persistence, domain modules, migrations
+- **[`open-sse/services/AGENTS.md`](open-sse/services/AGENTS.md)** — Routing engine, combo resolution, strategy selection
+
+## Reference Documentation (docs/)
+
+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 (12-factor, 18 strategies)      | [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md)                                                      |
+| Resilience (3 layers)                      | [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md)                                |
+| Skills                                     | [`docs/frameworks/SKILLS.md`](docs/frameworks/SKILLS.md)                                                        |
+| Memory                                     | [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md)                                                        |
+| Cloud agents                               | [`docs/frameworks/CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md)                                              |
+| Guardrails                                 | [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md)                                                    |
+| Evals                                      | [`docs/frameworks/EVALS.md`](docs/frameworks/EVALS.md)                                                          |
+| Compliance                                 | [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md)                                                    |
+| Webhooks                                   | [`docs/frameworks/WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md)                                                    |
+| Authz                                      | [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md)                                          |
+| Stealth                                    | [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md)                                              |
+| Reasoning replay                           | [`docs/routing/REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md)                                          |
+| Agent protocols (A2A / ACP / Cloud)        | [`docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)                          |
+| MCP server                                 | [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md)                                                |
+| A2A server                                 | [`docs/frameworks/A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md)                                                |
+| API reference                              | [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md) + [`docs/openapi.yaml`](docs/openapi.yaml) |
+| Provider catalog (auto-generated)          | [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md)                                  |
+| Tunnels                                    | [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md)                                                        |
+| Electron desktop                           | [`docs/guides/ELECTRON_GUIDE.md`](docs/guides/ELECTRON_GUIDE.md)                                                |
+| Release flow                               | [`docs/ops/RELEASE_CHECKLIST.md`](docs/ops/RELEASE_CHECKLIST.md)                                                |
+| Quality gates (35 gates, allowlist policy) | [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md)                                      |
+| Cluster opt-in profiles (memory, bifrost)  | [`docs/architecture/cluster-decisions.md`](docs/architecture/cluster-decisions.md)                              |
+
+---
+
+## Fork / Upstream Workflow
+
+This repository is a fork of `diegosouzapw/OmniRoute`. Keep fork-only operational
+changes (for example GHCR image publishing, personal deployment workflows, or local
+automation) out of upstream contribution PRs.
+
+When preparing a PR for upstream, always start the work branch from `upstream/main`,
+not from this fork's `main`:
+
+```bash
+git fetch upstream
+git switch -c <branch-name> upstream/main
+```
+
+Only cherry-pick or reapply the changes intended for the upstream PR.
+
+---
 
 ## Review Focus
 
-### Security
-
-- No hardcoded API keys or secrets in commits
-- Auth middleware on all API routes
-- Input validation on user-facing endpoints (Zod schemas)
-- SQLite encryption key must not be logged
-
-### Architecture
-
-- DB operations go through `src/lib/db/` modules, never raw SQL in routes
-- Provider requests flow through `open-sse/handlers/`
-- Translations use `open-sse/translator/` modules
-- `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module
-- MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`, not standalone routes
-
-### Code Quality
-
-- Consistent error handling with try/catch
-- Proper HTTP status codes
-- No memory leaks in SSE streams (abort signals, cleanup)
-- Rate limit headers must be parsed correctly
-- All API inputs validated with Zod schemas
-
-### Docker
-
-- Dockerfile has two targets: `runner-base` and `runner-cli`
-- `docker-compose.yml` — development (3 profiles)
-- `docker-compose.prod.yml` — isolated production instance (port 20130)
-- Data persists in named volumes (`omniroute-data` / `omniroute-prod-data`)
-
-### Review Mode
-
-- Provide analysis and suggestions only
-- Focus on bugs, security, performance, and best practices
+- **DB ops** go through `src/lib/db/` modules, never raw SQL in routes
+- **Provider requests** flow through `open-sse/handlers/`
+- **MCP/A2A pages** are tabs inside `/dashboard/endpoint`, not standalone routes
+- **No memory leaks** in SSE streams (abort signals, cleanup)
+- **Rate limit headers** must be parsed correctly
+- All API inputs validated with **Zod schemas**
+- **Provider constants** validated at module load via Zod (`src/shared/validation/providerSchema.ts`)
+- **Pricing data** syncs from LiteLLM via `src/lib/pricingSync.ts`
+- **Memory/Skills** are cross-cutting: affect MCP tools, request pipeline, and A2A skills
+- **⛔ NEVER close a contributor's PR** after using their code — always merge via GitHub so they get credit. See `.agents/workflows/review-prs.md` for full policy.