@qadanm/opencode-smart-router 0.0.0-stage → 0.4.0

package/docs/DEBUGGING-GUI.md

@@ -0,0 +1,70 @@
+# Debugging the desktop panel
+
+Written after a session where the panel vanished and four plausible causes were
+investigated before the real one. Read this before touching GUI code.
+
+## Check the server version first
+
+The desktop panel needs **OpenCode Desktop 2.2.x or newer**. A 2.1.x server has no
+GUI plugin API: it will not report `gui` in `/api/plugin`, and it cannot load
+`gui-experimental.cjs` at all.
+
+```bash
+opencode api get /api/info          # must say 2.2.x
+opencode api get /api/plugin        # opcode-smart-router must have features.gui: true
+```
+
+**The common trap:** `opencode` on `PATH` may be an older Homebrew install than
+the app. Running `opencode service restart` then restarts the *old* server, and it
+takes the port the app was using. The app reconnects to it, and the panel stops
+loading with no useful error.
+
+```bash
+which opencode && opencode --version           # CLI on PATH
+ls ~/Library/Application\ Support/ai.opencode.desktop/cli/   # app's bundled CLI
+```
+
+They must both be 2.2.x. If they are not, either `brew upgrade opencode-v2` or
+restart the app itself (`⌘Q`, then relaunch) instead of using the service command.
+The app spawns its own bundled server, which is the one that can load a GUI.
+
+## Then check the id rules
+
+Documented in the GUI guide, and easy to misread:
+
+> A plugin whose id "nests under one with a dot, has one nested under it, or is in
+> the `opencode` namespace" does not load its GUI.
+
+Concretely, this is wrong:
+
+```
+server part  id: "opencode-smart-router"
+tui part     id: "opencode-smart-router.tui"     ◄ nests under the server id
+```
+
+The TUI id must be a sibling, not a child. `test/first-run.test.ts` asserts that no
+two plugin ids nest, because the failure costs the entire panel and produces only
+a generic request failure in the app.
+
+## What the symptoms actually mean
+
+| Symptom | Usual cause |
+|---|---|
+| `Request failed / UnsupportedContentType` | Client and server versions disagree, or the GUI never registered |
+| Tab strip resets to the new-tab page | No GUI entry was loaded for that plugin |
+| `features` has no `gui` | Server too old, or the plugin id nests |
+| Panel renders but RPC fails | Server part failed to load — a plugin with no server part has no GUI |
+| Panel blank, no error | Something in `setup()` threw. A GUI whose setup throws loses the plugin, not just the panel |
+
+## Rules that keep this debuggable
+
+1. **`features.gui: true` is the single fact to check first.** It answers "did the
+   app even find my GUI" before any speculation about bundles, exports or code.
+2. **Never gate a required surface on an optional check.** The panel once rendered
+   as an empty box because it waited for `onboarding()` to settle, and that call
+   did not. Show the normal state; let optional data arrive later.
+3. **A convenience must never be able to break the product.** The auto-open path
+   touches four host APIs inside `setup()`; it is wrapped so a throw cannot remove
+   the plugin.
+4. **Test the version you think you are testing.** `/api/info` reports the server
+   actually running, which is not necessarily the one you started.

package/docs/INSTALL.md

@@ -0,0 +1,120 @@
+# Install, verify, and remove
+
+# Install, verify, and remove
+
+## Install
+
+One command, from a checkout. Requires Node 20.12+, npm and git. No `jq`.
+
+```bash
+./install              # interactive
+./install --yes        # non-interactive, for CI or an LLM
+./install --dry-run    # print every step, change nothing
+```
+
+It validates the source (typecheck and the full suite), backs up your config,
+builds the bundle, installs it, adds exactly one entry to `plugins`, and confirms
+the bundle loads. Any failure exits non-zero and leaves the machine untouched,
+because every check runs before anything is written.
+
+The install is **versioned and additive**. Each run writes to its own directory:
+
+```text
+~/.config/opencode/plugins/opencode-smart-router/<timestamp>/index.js
+```
+
+and only the config pointer changes. A running OpenCode server keeps the module it
+already loaded; the new version takes effect on the next start. This matters more
+than it sounds: replacing files inside the watched plugin directory invalidates the
+plugin module mid-session and makes the provider's model list go empty, which shows
+up as `Model unavailable: <provider>/<model>` for a model that is perfectly fine.
+
+## Verify
+
+```bash
+./install --dry-run        # reports the current state without changing it
+```
+
+Then restart OpenCode and run `/router-status` in a session. It prints the active
+plan, the allowance windows, and the model the router would pick.
+
+## Disable without uninstalling
+
+Set `"enabled": false` in `~/.config/opencode/smart-router.json` and restart. The
+plugin stays installed and inert; your config, credentials and providers are
+untouched either way.
+
+## Uninstall
+
+```bash
+./scripts/uninstall.sh
+```
+
+Removes the plugin directory and every `plugins` entry under it, then offers the
+exact pre-removal config as a restore point. Restart OpenCode afterwards.
+
+## Update
+
+Run `./install` again. It installs a new versioned directory and repoints the
+config, so old versions can be deleted safely once the new one is confirmed:
+
+```bash
+ls ~/.config/opencode/plugins/opencode-smart-router/
+```
+
+## Rollback
+
+Every install prints the backup it made. Two options:
+
+```bash
+./scripts/uninstall.sh                             # clean removal
+./scripts/uninstall.sh --restore-backup <file>     # restore an exact prior config
+```
+
+## Verify quota and routing
+
+The router exposes an RPC status method:
+
+```bash
+opencode api POST /api/rpc/smart-router/status -d '{"input":{}}'
+```
+
+Use `opencode api` so authentication is handled by OpenCode. The output labels each provider quota source as `provider`, `estimate`, or `unknown`.
+
+For durable usage history, per-model totals and rolling-window forecasts:
+
+```bash
+opencode api POST /api/rpc/smart-router/usage -d '{"input":{}}'
+```
+
+This reports each provider's five-hour, seven-day and monthly consumption with input, output, cache-read and cache-write tokens, the cache share, per-model totals, and a forecast per window. A plan with no five-hour window reports that row as not applicable rather than as 0% used. It makes no inference request.
+
+For a safe dry-run of a routing decision without changing the model:
+
+```bash
+opencode api POST /api/rpc/smart-router/preview \
+  -d '{"input":{"sessionID":"ses_…","text":"Implement a small feature in src/app.ts"}}'
+```
+
+A safe smoke test:
+
+1. Create a new session with a cheap or free model.
+2. Send a narrow CSS change with an explicit file path.
+3. The session should switch to an economy model before the request, and the file should change.
+4. Send an ordinary feature request; it should use a standard model at or above the intelligence floor.
+5. Send a redesign with a screenshot; it should require a vision model and record a premium approval suggestion.
+6. Run `/router-approve` and repeat the redesign; a premium model may be selected once.
+7. Select a model manually in the desktop picker; the next prompt must not be overridden, and `/router-status` should show `manual`.
+8. Run `/router-auto` to resume.
+
+## Configuration
+
+No config file is required. To customize:
+
+```bash
+cp ~/Documents/opencode-smart-router/config.example.json \
+   ~/.config/opencode/smart-router.json
+chmod 600 ~/.config/opencode/smart-router.json
+```
+
+A project may add `.opencode/smart-router.json`. It can tighten privacy and spending policy but cannot loosen global restrictions.

package/docs/LIMITATIONS.md

@@ -0,0 +1,213 @@
+# Limitations and precise blockers
+
+This file records what is proven, what is estimated, and what the installed OpenCode version cannot support.
+
+## 1. Desktop GUI
+
+Installed OpenCode Desktop is **2.1.4**. Its `app.asar` does not contain the experimental GUI plugin loader or the `./gui-experimental` export. The GUI plugin SDK is present in `@opencode/plugin` 2.2.0 and later.
+
+Therefore the deployed interface is:
+
+- native slash commands registered by the server plugin (`/router-status`, `/router-explain`, `/router-report`, `/router-mode`, `/router-approve`, `/router-auto`, `/router-pin`, `/router-exclude`, `/router-pause`, `/router-resume`, `/router-dry-run`, `/router-premium-budget`, `/router-reserve`, `/router-reset-metrics`);
+- a typed RPC surface at `rpc.smart-router.*`, suitable for a future official GUI part.
+
+The router engine does not depend on any panel being open. A side panel was not claimed or faked. On OpenCode 2.2.0 or later, the same RPC surface can back a native settings page or side panel without changing routing core.
+
+## 2. Command Code billing endpoints
+
+Command Code exposes no stable public usage API in its documented Provider API. The plugin reads the same read-only alpha routes the official CLI uses:
+
+```text
+/alpha/whoami?limits=1
+/alpha/billing/credits
+/alpha/billing/subscriptions
+/alpha/usage/summary
+```
+
+These are **undocumented and unstable**. They can change without notice. The adapter:
+
+- uses only `GET`;
+- never discovers or calls mutation endpoints;
+- validates numeric and timestamp shapes;
+- preserves `orgId` when the account belongs to an organization;
+- limits polling to a conservative interval with exponential backoff;
+- keeps the last good snapshot marked `stale` on failure;
+- falls back to a clearly labeled local ledger estimate;
+- never reports missing data as unlimited usage.
+
+The provider API key that OpenCode uses for inference is **not authorized** for these billing routes. The adapter discovers the CLI-compatible key instead. In this installation the working source is:
+
+```text
+~/.config/opencode/commandcode.key
+```
+
+The key is read only from owner-only files, is never logged or persisted by the plugin, and is sent only to `https://api.commandcode.ai`.
+
+Provider-reported values are account-level: remaining included credits, purchased/free extras, five-hour and weekly used/cap/reset, plan, and billing-period spend. There is no per-model provider breakdown. Per-model usage and remaining model allowance are local estimates from observed step costs.
+
+The billing-period usage summary and the remaining-credit balance are **separate accounting pools** and do not reconcile exactly. The adapter treats the remaining-credit balance as authoritative for monthly usage and allowance protection; the summary is kept only as a diagnostic cross-check. The exact reason for the difference is not documented by the provider.
+
+## 3. OpenCode Go usage endpoint
+
+The Go meter endpoint is a read-only, best-effort integration:
+
+```text
+GET https://opencode.ai/zen/go/v1/usage
+```
+
+It is queried with OpenCode's existing OAuth access token from the `opencode` connection. It returns percentages and reset times, not dollar balances. It is not part of the public inference schema and may change. On failure, the router uses the local ledger and labels the source `estimate` or `unknown`.
+
+## 4. Prompt rejection is untyped
+
+The V2 prompt admission hook can mutate a prompt but exposes no typed rejection operation. The router blocks admission by throwing `RouterBlockedError` from the prompt hook. On the installed 2.1.4 server this was verified to reject the prompt with HTTP 500 and no provider request; the session title changes to `BLOCKED` and the reason is recorded in the decision.
+
+This is safe but not polished: the HTTP error is generic, so the title and notification are the user-facing explanation. `routing.failClosed` defaults to true. Manual selections and paused routing are outside the strict block.
+
+A routing exception must also block. The earlier catch-and-continue path was a fail-open defect and is being removed.
+
+## 5. Manual CLI selection at session creation
+
+Manual model changes made while the plugin is active are detected through `session.model.selected` and respected. A model passed only at CLI session creation, before the plugin has seen a prompt, is indistinguishable from the session default. The first prompt may therefore be routed normally. Selecting a model in the desktop picker after the session exists is detected.
+
+## 6. Subagents
+
+Child sessions are routed independently. Premium is never propagated from a parent task into a child session; premium mode is capped at balanced for child sessions and one-shot approvals are not inherited. This prevents a premium task from multiplying premium usage through subagent calls. A child can still use a standard model appropriate to its own prompt.
+
+## 7. Billing caps
+
+Client-side quota estimates are not a mathematically guaranteed billing cap. Provider-side enforcement remains authoritative. The router:
+
+- never purchases credits;
+- never enables top-ups;
+- never changes billing settings;
+- blocks automatic routing when provider-reported windows are at the configured reserve;
+- treats a reported zero remaining balance as exhausted even if the provider has not set its `exceeded` flag, so it blocks before knowingly entering purchased credits;
+- blocks when purchased credits would be consumed unless `allowExtraUsage` is explicitly enabled;
+- cannot guarantee that an undocumented provider endpoint or a provider-side fallback will never charge an extra balance.
+
+If Command Code's billing routes fail and the local ledger is incomplete, the router labels the data estimated and fails conservatively rather than assuming capacity.
+
+The purchased-credit guard is unit-tested, including the explicitly-allowed case. It is a client-side policy guarantee, not a provider-side billing lock.
+
+## 8. Cache and context accounting
+
+Prompt caches are provider- and model-specific. A model switch is priced as a cache loss in the router's estimate. The router keeps the current model when the estimated savings are below the hysteresis threshold, and uses a wider threshold above 300K context tokens. It never truncates, summarizes, or deletes conversation history to make a model eligible.
+
+Command Code DeepSeek V4.1 Flash has documented time-of-day pricing: off-peak rates for 17 hours per day and 2x rates from 01:00 to 04:00 and 06:00 to 10:00 UTC, Monday through Friday. The router applies that multiplier to input, output, cache-read, and cache-loss estimates. Models without documented peak metadata use flat catalog rates; their time-of-day pricing is not assumed.
+
+Context-health recommendations are non-destructive: they advise a new session and never compact anything on their own.
+
+Router-driven compaction is governed by `contextManagement.mode`:
+
+- `native` (default) and `conservative` never compact except when the transcript would genuinely exceed the model's verified accepted window. The provider's native handling is preferred; the router steps in only for that case, and announces it.
+- `budget-optimized` preserves the legacy behavior: it compacts early to keep a session on the cheapest qualified route. It exists for small plans and small-window models.
+
+In every mode the window used is the one the provider actually accepts, never a theoretical maximum, and the current model's window is used rather than another provider's variant of the same model. Provider-side prompt caching is never disabled by any mode.
+
+## 8a. OpenDesign plan accounting
+
+OpenDesign Pro exposes two independent credit pools: Design Plan credits ($360/month, $90 per rolling seven days, no five-hour window) and plan model credits ($120/month, no usage windows). They are reported side by side and **never summed**. The advertised $480 total is not a single spendable balance, and Design Plan credit multipliers apply only inside the Design Plan pool.
+
+These figures are **estimated**, not provider-confirmed. An OpenDesign inference key cannot read quota: `GET /v1/usage` and `/v1/me` return 404 and the account-control host rejects an inference key. A control key would enable verified reads; none is configured, and the router never acquires one automatically. Because usage from the OpenDesign app is invisible to the router, the estimate is a lower bound.
+
+`minimax-m3.1-flash`'s Design Plan multiplier is unpublished, so a neutral 1x is applied and the uncertainty is reported rather than hidden. The same applies to the GLM cache-read price.
+
+OpenDesign quota cannot be verified without an account control key. Re-probed on
+2026-10-30 against the live gateway: `/v1/models` returns 200 with the inference
+key, while `/v1/usage`, `/v1/me`, `/v1/credits`, `/v1/billing`, `/v1/account`,
+`/v1/subscription`, `/v1/limits` and `/v1/quota` all return 404. The key is valid
+and authorized for inference; no usage surface exists for it. Quota therefore
+reports `estimated`, derived from this router's own consumption against the
+published plan caps with a configurable safety margin.
+
+That estimate is a lower bound, because usage from the OpenDesign desktop app and
+any other client on the same subscription is invisible to the router. The state
+label is the honest part: `estimated` never becomes `verified` without a control
+key, and `test/opendesign-quota-honesty.test.ts` pins that so it cannot drift.
+
+## 8b. Measured speed
+
+Generation speed is recorded as output tokens per second, which separates a slow provider from a model that reasons for longer. It is compared against the fastest eligible route rather than an absolute figure, is neutral below a configurable sample floor, and raises effective cost without ever making a route ineligible. With few samples it does not change decisions. It is machinery that needs production traffic before it can discriminate.
+
+## 9. Precision of scores
+
+The intelligence floor and design thresholds are planning inputs, not guarantees. Intelligence values come from published model cards where available; design scores are curated and explicitly separate. Models without credible scores are not approved for automatic substantive work. The router does not invent benchmark results.
+
+## 10. What was not done
+
+- No separate dashboard or daemon was installed.
+- No third-party classification service receives prompts, code, or screenshots.
+- No provider billing settings, credentials, or model connections were changed.
+- No project configuration outside the router's optional project override was modified.
+
+## 11. Why a session may stop using your default model
+
+Two independent reasons can move a session off DeepSeek V4.1 Flash, and both are
+correct behavior rather than faults.
+
+**The transcript outgrew the window.** DeepSeek V4.1 Flash has a 328k window, and
+presence in a request requires about 20k of headroom inside 95% of it, so it
+stops being eligible at roughly 291,600 tokens of transcript. Past that point the
+router names the model it dropped, both token counts, and the fact that a new
+session restores it.
+
+**Another model is genuinely cheaper right now.** A session can sit inside a
+model's window and still lose on cost, because credit multipliers and peak
+pricing differ per model. On OpenDesign, Minimax M3.1 Flash carries a neutral
+multiplier while DeepSeek's is 0.5, and DeepSeek doubles during 01:00 to 04:00
+and 06:00 to 10:00 UTC on weekdays. At a 309k transcript on a weekday, MiniMax
+can therefore be about 1.3x cheaper, and the router picks it on merit. In that
+case the context warning is deliberately silent, because nothing was displaced:
+the model never would have won.
+
+Observed live on 2026-10-30, and superseded later the same day. A 309,321-token
+session selected `opendesign/minimax-m3.1-flash` because three conditions held at
+once:
+
+- OpenCode Go was at 90% of a 10% monthly reserve, so it was blocked.
+- Command Code was at 86% of a 15% weekly reserve, so it was blocked.
+- On OpenDesign, DeepSeek was judged against a 328,000 window and needed 329,321.
+
+The first two were correct. The third was not: the 328,000 window was an advisory
+gateway budget that the gateway does not enforce, and DeepSeek would now be
+chosen for that session. The quotas remain real; the context rejection was a
+consequence of the wrong window, which is documented in the section below.
+
+### OpenDesign's context budget is advisory, and was measured
+
+DeepSeek V4.1 Flash shows a 1,048,000-token window in the router. It used to show
+328,000, because the gateway publishes `context_budget: 328000` alongside
+`context_limit: 1048000` and the router treated the budget as the ceiling.
+
+That was wrong. The gateway does not enforce `context_budget`. Measured on
+2026-10-30 with six single requests on `deepseek-v4.1-flash`, `max_tokens: 1`,
+synthetic unique filler, so nothing could be prefix-cached:
+
+| Prompt tokens | Result |
+|---|---|
+| 355,588 | 200 |
+| 753,476 | 200 |
+| 999,593 | 200 |
+| 1,043,337 | 200 |
+| about 1,060,000 | 400 `context_length_exceeded` |
+| about 2.4M | 400 `context_length_exceeded` |
+
+The enforced ceiling is the vendor `context_limit` of 1,048,000, confirmed on both
+sides of the boundary. Total cost of the probes was $0.006.
+
+One control mattered: the first probe reported 355,328 of 355,588 tokens as
+cached, which is implausible for a payload that had never been sent. Repeating it
+with random text produced `cached_tokens: 0`, proving the gateway really did
+tokenize and accept the full input. Without that, a 200 on mostly-cached input
+would have been weak evidence.
+
+The router now uses the vendor limit for a model whose ceiling has been measured,
+and keeps the conservative budget for every other model. That is a per-model
+allowlist rather than a blanket rule, because guessing a larger window than a
+provider accepts fails mid-session with an opaque rejection, which is the failure
+mode this project already hit once.
+
+The router still keeps a 20,000-token margin and a 95% safety fraction, so the
+usable transcript is about 975,600 tokens rather than exactly 1,048,000. That
+margin is not part of the gateway's limit; it is the router refusing to send a
+request that has no room left for the reply.

package/docs/MODELS.md

@@ -0,0 +1,124 @@
+# Approved model registry
+
+The router starts from a curated seed and merges live metadata from OpenCode. A model is eligible only when it is approved here, present in the connected provider catalog, and meets every task requirement.
+
+## Scoring
+
+- **Intelligence** is a curated coding-intelligence score. Where available it comes from Command Code's published model cards. The standard floor is **39.5**, the DeepSeek V4.1 Flash score. It is not a general "best model" score.
+- **Design** is a separate curated score for front-end and UX quality. It is not benchmarked by the same method as intelligence.
+- **Vision** means the model accepts native image input in the live catalog.
+- **Premium** is a policy label for high-cost models. A premium model is never selected for economy or ordinary standard work.
+- **Monthly allowance** is public-rate usage included by the subscription. OpenCode Go values come from the plan catalog's Go table (Go Plus is a separate, larger table); selecting the wrong tier overstates capacity by roughly 2x. Command Code values are the GOAT per-model allowances. Provider-reported totals override these numbers for the plan-level balance.
+- **Time-of-day pricing** is applied only where documented. Command Code DeepSeek V4.1 Flash is listed at off-peak rates and charges 2x from 01:00 to 04:00 and 06:00 to 10:00 UTC, Monday through Friday; the router applies that multiplier to input, output, cache-read, and cache-loss estimates. Models without documented peak metadata use flat catalog rates.
+
+These scores are planning inputs, not marketing claims. Models marked **unverified** or **unscored** are not approved for automatic substantive work.
+
+## Economy (Tier 1)
+
+Used only for narrow, mechanically verifiable work with an explicit scope and deterministic validation.
+
+| Provider / model | Intelligence | Design | Vision | Monthly allowance |
+|---|---:|---:|---|---:|
+| `opencode-go/gpt-6-luna` | 38.1 | 55 | text, image, PDF | $60 |
+| `opencode-go/mimo-v2.6-flash` | 37.9 | 50 | text, image, audio, video | $120 |
+| `opencode-go/hy3` | 25.3 | 45 | text | $240 |
+| `opencode-go/longcat-2.0` | 19.1 | 40 | text | $240 |
+| `commandcode/gpt-6-luna` | 38.1 | 55 | text, image, PDF | $20 |
+
+These models are below the standard intelligence floor. They cannot be selected for feature work, debugging, refactoring, architecture, security, or tests.
+
+## Standard (Tier 2)
+
+The default for substantive software engineering. Every model here meets or exceeds the DeepSeek V4.1 Flash floor.
+
+| Provider / model | Intelligence | Design | Vision | Monthly allowance |
+|---|---:|---:|---|---:|
+| `opencode-go/deepseek-v4.1-flash` | 39.5 | 65 | text, image | $160 |
+| `opencode-go/glm-5.3-flash` | 41.8 | 65 | text, image, video | $180 |
+| `opencode-go/minimax-m3.1-flash` | 42.7 | 60 | text, image, video | $80 |
+| `opencode-go/claude-haiku-5-5` | 43.4 | 70 | text, image, PDF | $60 |
+| `opencode-go/mimo-v2.6-pro` | 46.3 | 62 | text, image, audio, video | $60 |
+| `commandcode/deepseek-v4.1-flash` | 39.5 | 65 | text, image | $80 |
+| `commandcode/z-ai/glm-5.3-flash` | 41.8 | 65 | text, image, video, PDF | $80 |
+| `commandcode/claude-haiku-5-5` | 43.4 | 70 | text, image, PDF | $20 |
+
+Design-intensive work requires at least a 60 design score. Sophisticated design work requires at least 75. A standard model below 75 still requires premium approval for sophisticated design.
+
+Claude Haiku 5.5 (**43.4** intelligence, **70** design) is a concrete example of why intelligence and design are separate gates. It clears the 39.5 intelligence floor, so it is valid for ordinary feature work and standard design. It does **not** clear the 75 sophisticated-design floor. When no sophisticated-qualified model is available, the router may use it only as an explicitly labeled standard-design fallback:
+
+> `Standard design route: design 70 is below the sophisticated 75 threshold`
+
+It is never reported as meeting every hard requirement for sophisticated design, and a premium design route still requires approval.
+
+## Premium (Tier 3)
+
+Premium models are available only when:
+
+- the task is premium-tier or the user explicitly asks for a premium model,
+- `premium.mode` is not `off`,
+- and either a one-shot approval is active for the session or Premium Allowed mode has a remaining configured budget.
+
+They are never used for trivial or ordinary standard work. They are never selected silently.
+
+| Provider / model | Intelligence | Design | Vision | Monthly allowance |
+|---|---:|---:|---|---:|
+| `opencode-go/glm-5.3` | 44.8 | 80 | text | $120 |
+| `opencode-go/kimi-k3` | 43.6 | 72 | text, image, video | $60 |
+| `opencode-go/grok-4.7` | 46.4 | 75 | text, image, PDF | $60 |
+| `opencode-go/qwen3.8-max` | 40.2 | 70 | text, image, video | $60 |
+| `opencode-go/step-5-preview` | 43.7 | 70 | text, image, video | $60 |
+| `commandcode/claude-sonnet-5-5` | 56.0 | 90 | text, image, PDF | $10 |
+| `commandcode/meta/muse-spark-1.3` | 48.1 | 82 | text, image, video, PDF, audio | $20 |
+| `commandcode/xai/grok-4.7` | 46.4 | 75 | text, image, PDF | $20 |
+| `commandcode/Qwen/Qwen3.8-Max` | 40.2 | 70 | text, image, video, PDF | $20 |
+| `commandcode/stepfun/Step-5-Preview` | 43.7 | 70 | text, image, video | $20 |
+
+`opencode-go/glm-5.3` is text-only and can never receive a screenshot, even if its intelligence would otherwise qualify. This is enforced as a hard vision rule.
+
+## Known but unapproved
+
+These models are discovered but deliberately excluded from automatic routing:
+
+- `commandcode/google/gemini-4-argon`, `opencode-go/gemini-4-argon`: unscored in the current model cards.
+- `commandcode/claude-opus-5-5`, `commandcode/gpt-6.1-sol`, `commandcode/gpt-6-astra`, `commandcode/claude-fable-5-1`: frontier-priced and unscored here. They require explicit user qualification.
+- `opencode-go/kimi-k3.1-pro`: unscored.
+- `opencode-go/deepseek-v4-pro`: below the current floor and text only.
+- `commandcode/deepseek/deepseek-v4.1-flash`: duplicate route for the same upstream model; the GOAT ID is approved instead.
+- `meta/muse-spark-1.3-contributor`, `opencode-go/muse-spark-1.3-contributor`, `opencode-go/iceman-contributor-free`: training-enabled. Blocked unless `privacy.allowTrainingModels` is explicitly enabled.
+- `opencode-go/beam-free`: free promotional model, not qualified for automatic work.
+
+## Changing the registry
+
+Use `/router-exclude provider/model` to remove a model from automatic routing. To approve a discovered model, add its exact key to `models.approved` in `~/.config/opencode/smart-router.json` and assign it a tier in `models.tierOverrides`. A discovered model without a tier remains unapproved.
+
+Do not approve a model solely because it is cheaper or newer. Qualify it on real tasks first.
+
+## User-defined model definitions
+
+If a provider exposes a model that is not in the seed, qualify it explicitly in `models.definitions`. A definition is metadata, not a new provider or a proxy. The model still comes from the connected provider catalog.
+
+```jsonc
+{
+  "models": {
+    "definitions": [
+      {
+        "key": "acme/coder-v2",
+        "providerID": "acme",
+        "modelID": "coder-v2",
+        "name": "Acme Coder V2",
+        "context": 200000,
+        "maxOutput": 32768,
+        "input": ["text", "image"],
+        "cost": [{ "input": 0.2, "output": 0.8, "cache": { "read": 0.02, "write": 0 } }],
+        "intelligence": 41.0,
+        "design": 60,
+        "tier": 2,
+        "approved": true,
+        "monthlyAllowanceUsd": 100
+      }
+    ]
+  }
+}
+```
+
+Definitions are merged with the seed and live catalog. `tier` is required; `approved` defaults to true only because the definition itself is an explicit qualification. Do not add a definition for a model you have not tested.