@route_33/opencode 0.4.4 → 0.4.6

package/README.md

@@ -30,7 +30,7 @@ This plugin never writes your `opencode.json` or `opencode.jsonc`: opencode has
 
 Run `opencode auth login` and choose `route_33`, or set the `ROUTE33_API_KEY` environment variable. Without a key, the TUI wizard offers to save one: per-project inside a git workspace, global otherwise. A globally stored key applies only outside git workspaces — inside a workspace, keys resolve from the environment, the workspace config, or `.opencode/route33.key` (per-project keys are the metering boundary). Skipping the project-key wizard snoozes it for 7 days — "Skip" for that workspace only, "Skip for all workspaces" everywhere (both live in opencode's TUI kv store; remove `project-key-prompt.dismissed-at*` from `~/.local/state/opencode/kv.json` to re-arm sooner). `ROUTE33_BASE_URL` overrides the default gateway URL; `ROUTE33_TUI_PROMPT=0` disables the wizard.
 
-Your key is never written into the resolved provider configuration: authentication is attached per request at fetch time, so `opencode debug config` output contains no credential material.
+Your key is never written into the resolved provider configuration: authentication is attached per request at fetch time, so `opencode debug config` output contains no credential material. One inert exception: the options carry the non-secret marker `__route33_fetch_shim_auth__` as `apiKey`, because the native per-model SDKs used for `anthropic/`, `openai/`, and `mistralai/` models (`@ai-sdk/anthropic`, `@ai-sdk/openai`, `@ai-sdk/mistral`) refuse to construct a request without one — the marker satisfies that null check, never authenticates anything (the gateway reads only the request-time `Authorization` header, which the fetch shim injects), and no vendor env var (`ANTHROPIC_API_KEY` etc.) is needed or consulted. The marker is skipped by key resolution and never overrides an `apiKey` you authored yourself; it is visible in config dumps precisely because it is not a secret.
 
 ## Model catalog
 
@@ -100,6 +100,20 @@ Model references in your config that differ from the served ID only by digit-bou
 
 The plugin reads only these variables. `ROUTE33_ENRICH_CAPS` is no longer supported.
 
+## Exhaustion retry
+
+Starting with v0.4.6, the plugin wraps live chat/compat requests in an exhaustion retry layer. It triggers only on an HTTP `429` whose error code is `PROVIDER_LANES_EXHAUSTED` (all provider lanes exhausted). It reads the gateway's `Retry-After` response header and falls back to a client-side schedule of `5·2^(n−1)` seconds capped at 1200 when the header is missing. It waits through the delay while respecting the request's abort signal, then re-issues the identical request. It keeps retrying indefinitely until the request succeeds or the user cancels it.
+
+Non-exhaustion errors (network failures, 4xx responses from the gateway other than the exhaustion code, etc.) are passed through untouched.
+
+Each wait is logged with the attempt number, waited seconds, and the gateway's `correlationId`:
+
+```
+route33: exhausted; waiting <seconds>s before retry <attempt> (correlationId=<correlationId>)
+```
+
+The provider option `headerTimeout` is set to `1_500_000` ms (25 minutes). This is higher than opencode's own 300-second fetch default so that scheduled waits are not aborted while waiting for a lane to cool down. It is safe because the gateway caps provider hangs at 120 s TTFB and 240 s first-event timeouts, so the connection is never silent for anywhere near 25 minutes.
+
 ## License
 
 Proprietary — "SEE LICENSE IN LICENSE". Install and use as-is via npm; copying, modification, and redistribution are not permitted. Provided AS-IS, without warranty or liability.

package/dist/index.js

@@ -94,6 +94,9 @@ var logger = {
 // src/shared/models-dev-ttl-ms.ts
 var MODELS_DEV_TTL_MS = 864e5;
 
+// src/shared/native-sdk-api-key-placeholder.ts
+var NATIVE_SDK_API_KEY_PLACEHOLDER = "__route33_fetch_shim_auth__";
+
 // src/shared/resolve-cache-dir.ts
 import * as os2 from "os";
 import * as path3 from "path";
@@ -217,9 +220,10 @@ function usable4(value) {
 }
 function keyFromConfig(cfg) {
   const literal = usable4(cfg?.provider?.route_33?.options?.apiKey);
-  if (literal !== void 0 && !literal.includes(UNRESOLVED_TEMPLATE_MARKER2))
-    return literal;
-  return void 0;
+  if (literal === void 0) return void 0;
+  if (literal.includes(UNRESOLVED_TEMPLATE_MARKER2)) return void 0;
+  if (literal === NATIVE_SDK_API_KEY_PLACEHOLDER) return void 0;
+  return literal;
 }
 function resolveKey(cfg, env = process.env, worktree) {
   return usable4(env[ENV_API_KEY]) ?? keyFromConfig(cfg) ?? readWorkspaceKey(worktree) ?? (worktree !== void 0 && isInsideGitWorktree(worktree) ? void 0 : readAuthEntry(env).key);
@@ -242,6 +246,96 @@ function buildRoute33Auth(env = process.env, worktree) {
   };
 }
 
+// src/config/abortable-sleep.ts
+function abortableSleep(ms, signal) {
+  return new Promise((resolve3, reject) => {
+    if (signal === void 0) {
+      setTimeout(resolve3, ms);
+      return;
+    }
+    if (signal.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve3();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/config/parse-exhaustion-envelope.ts
+var EXHAUSTION_CODE = "PROVIDER_LANES_EXHAUSTED";
+async function parseExhaustionEnvelope(response) {
+  let body;
+  try {
+    body = await response.clone().json();
+  } catch (error) {
+    if (error instanceof Error) return void 0;
+    throw error;
+  }
+  if (typeof body !== "object" || body === null || Array.isArray(body))
+    return void 0;
+  const nestedError = Reflect.get(body, "error");
+  const nestedCode = typeof nestedError === "object" && nestedError !== null ? Reflect.get(nestedError, "code") : void 0;
+  if (Reflect.get(body, "code") !== EXHAUSTION_CODE && nestedCode !== EXHAUSTION_CODE)
+    return void 0;
+  const directId = Reflect.get(body, "correlationId");
+  const nestedId = typeof nestedError === "object" && nestedError !== null ? Reflect.get(nestedError, "correlationId") : void 0;
+  return {
+    correlationId: typeof directId === "string" ? directId : typeof nestedId === "string" ? nestedId : void 0
+  };
+}
+
+// src/config/exhaustion-retry-fetch.ts
+function buildExhaustionRetryFetch(innerFetch, options) {
+  const sleep = options?.sleep ?? abortableSleep;
+  const maxWaitSeconds = options?.maxWaitSeconds ?? 1200;
+  const baseSeconds = options?.baseSeconds ?? 5;
+  return async (input, init) => {
+    const body = init?.body;
+    const resendable = body === void 0 || typeof body === "string" || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || body instanceof Blob || body instanceof URLSearchParams || body instanceof FormData;
+    let model;
+    if (typeof body === "string") {
+      try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+          const candidate = Reflect.get(parsed, "model");
+          if (typeof candidate === "string") model = candidate;
+        }
+      } catch (error) {
+        if (!(error instanceof SyntaxError)) throw error;
+      }
+    }
+    let attempt = 0;
+    while (true) {
+      const response = await innerFetch(input, init);
+      if (response.status !== 429) return response;
+      const contentType = response.headers.get("content-type") ?? "";
+      if (!/(?:^|\/)json(?:;|$)|\+json(?:;|$)/i.test(contentType)) return response;
+      const exhaustion = await parseExhaustionEnvelope(response);
+      if (exhaustion === void 0 || !resendable) return response;
+      attempt += 1;
+      const retryAfter = response.headers.get("retry-after");
+      const advisedSeconds = retryAfter !== null && /^\d+$/.test(retryAfter) ? Number(retryAfter) : void 0;
+      const seconds = advisedSeconds !== void 0 && advisedSeconds > 0 ? Math.min(advisedSeconds, maxWaitSeconds) : Math.min(baseSeconds * 2 ** (attempt - 1), maxWaitSeconds);
+      logger.warn("provider lanes exhausted; retrying", {
+        attempt,
+        seconds,
+        correlationId: exhaustion.correlationId,
+        ...model === void 0 ? {} : { model }
+      });
+      await sleep(seconds * 1e3, init?.signal ?? void 0);
+      if (init?.signal?.aborted === true) throw init.signal.reason;
+    }
+  };
+}
+
 // src/config/live-auth-fetch.ts
 function buildLiveAuthFetch(resolveKeyNow, innerFetch) {
   return (input, init) => {
@@ -290,10 +384,13 @@ function buildOpenAiChatCompatFetch(fetchImpl) {
 
 // src/config/build-options.ts
 function buildOptions(baseURL, resolveKeyNow = () => void 0) {
-  const options = { baseURL };
-  options.fetch = buildLiveAuthFetch(
-    resolveKeyNow,
-    buildOpenAiChatCompatFetch()
+  const options = {
+    baseURL,
+    apiKey: NATIVE_SDK_API_KEY_PLACEHOLDER,
+    headerTimeout: 15e5
+  };
+  options.fetch = buildExhaustionRetryFetch(
+    buildLiveAuthFetch(resolveKeyNow, buildOpenAiChatCompatFetch())
   );
   return options;
 }
@@ -479,6 +576,7 @@ var CatalogFetchError = class extends Error {
 var DEFAULT_FETCH_TIMEOUT_MS = 5e3;
 
 // src/catalog/extract-pricing.ts
+var PRICING_CURRENCY = "USD";
 function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -495,6 +593,9 @@ var MODELS_DEV_KEYS = [
   "cache_read",
   "cache_write"
 ];
+function parsePricingCurrency(value) {
+  return value === void 0 || value === PRICING_CURRENCY ? PRICING_CURRENCY : void 0;
+}
 function perTokenRate(value) {
   if (typeof value !== "string" || value.trim() === "") return void 0;
   const parsed = Number(value);
@@ -506,11 +607,15 @@ function toPer1M(perToken) {
 function per1MRate(value) {
   return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
 }
-function extractOpenRouterPricing(raw) {
+function extractOpenRouterPricing(raw, currency) {
   const input = perTokenRate(raw.prompt);
   const output = perTokenRate(raw.completion);
   if (input === void 0 || output === void 0) return void 0;
-  const cost = { input: toPer1M(input), output: toPer1M(output) };
+  const cost = {
+    input: toPer1M(input),
+    output: toPer1M(output),
+    currency
+  };
   for (const [field, target] of [
     ["input_cache_read", "cache_read"],
     ["input_cache_write", "cache_write"]
@@ -522,11 +627,11 @@ function extractOpenRouterPricing(raw) {
   }
   return cost;
 }
-function extractModelsDevPricing(raw) {
+function extractModelsDevPricing(raw, currency) {
   const input = per1MRate(raw.input);
   const output = per1MRate(raw.output);
   if (input === void 0 || output === void 0) return void 0;
-  const cost = { input, output };
+  const cost = { input, output, currency };
   for (const field of ["cache_read", "cache_write"]) {
     if (raw[field] === void 0) continue;
     const rate = per1MRate(raw[field]);
@@ -537,11 +642,13 @@ function extractModelsDevPricing(raw) {
 }
 function extractPricing(raw) {
   if (!isRecord4(raw)) return void 0;
+  const currency = parsePricingCurrency(raw.currency);
+  if (currency === void 0) return void 0;
   const hasOpenRouterKeys = OPENROUTER_KEYS.some((key) => key in raw);
   const hasModelsDevKeys = MODELS_DEV_KEYS.some((key) => key in raw);
   if (hasOpenRouterKeys && hasModelsDevKeys) return void 0;
-  if (hasOpenRouterKeys) return extractOpenRouterPricing(raw);
-  if (hasModelsDevKeys) return extractModelsDevPricing(raw);
+  if (hasOpenRouterKeys) return extractOpenRouterPricing(raw, currency);
+  if (hasModelsDevKeys) return extractModelsDevPricing(raw, currency);
   return void 0;
 }
 
@@ -623,6 +730,7 @@ function toCatalogModels(entries, env) {
     if (capabilities !== void 0) model.capabilities = capabilities;
     const variants = parseVariants(entry.variants);
     if (variants !== void 0) model.variants = variants;
+    if (typeof entry.hasZdrLane === "boolean") model.hasZdrLane = entry.hasZdrLane;
     const modalities = parseModalities(entry.modalities);
     if (modalities !== void 0) model.modalities = modalities;
     if (typeof entry.attachment === "boolean") model.attachment = entry.attachment;
@@ -1036,6 +1144,11 @@ var FORCED_OPTION_FIELDS = /* @__PURE__ */ new Set([
   "baseURL",
   "headers"
 ]);
+function isForcedValue(field, value) {
+  if (field === "apiKey" && value === NATIVE_SDK_API_KEY_PLACEHOLDER)
+    return false;
+  return FORCED_OPTION_FIELDS.has(field);
+}
 function mergeProvider(target, patch) {
   if (target.npm === void 0) target.npm = patch.npm;
   if (target.name === void 0) target.name = patch.name;
@@ -1045,7 +1158,7 @@ function mergeProvider(target, patch) {
     const options = target.options;
     for (const [field, value] of Object.entries(patch.options)) {
       if (value === void 0) continue;
-      if (FORCED_OPTION_FIELDS.has(field) || options[field] === void 0)
+      if (isForcedValue(field, value) || options[field] === void 0)
         options[field] = value;
     }
   }

package/dist/tui/index.js

@@ -31,6 +31,9 @@ var logger = {
   }
 };
 
+// src/shared/native-sdk-api-key-placeholder.ts
+var NATIVE_SDK_API_KEY_PLACEHOLDER = "__route33_fetch_shim_auth__";
+
 // src/shared/resolve-cache-dir.ts
 import * as os from "os";
 import * as path2 from "path";
@@ -142,9 +145,10 @@ function usable3(value) {
 }
 function keyFromConfig(cfg) {
   const literal = usable3(cfg?.provider?.route_33?.options?.apiKey);
-  if (literal !== void 0 && !literal.includes(UNRESOLVED_TEMPLATE_MARKER))
-    return literal;
-  return void 0;
+  if (literal === void 0) return void 0;
+  if (literal.includes(UNRESOLVED_TEMPLATE_MARKER)) return void 0;
+  if (literal === NATIVE_SDK_API_KEY_PLACEHOLDER) return void 0;
+  return literal;
 }
 function resolveKey(cfg, env = process.env, worktree) {
   return usable3(env[ENV_API_KEY]) ?? keyFromConfig(cfg) ?? readWorkspaceKey(worktree) ?? (worktree !== void 0 && isInsideGitWorktree(worktree) ? void 0 : readAuthEntry(env).key);

package/docs/gateway-limits-variants-broadcast.md

@@ -125,7 +125,7 @@ These entries were cross-checked against models.dev on 2026-08-10 and should be
 - Anthropic `claude-opus-4-8`, `claude-sonnet-5`, `claude-fable-5`: `1,000,000` context / `128,000` output
 - Anthropic `claude-haiku-4-5`: `200,000` context / `64,000` output
 - `moonshotai/kimi-k3`: `1,048,576` context / `131,072` output, with the `max` variant (`reasoningEffort: "max"`)
-- `minimax/minimax-m3`, `nvidia/nemotron-3-ultra`, `mistralai/mistral-medium-3.5`, and `qwen/qwen3.7-plus` keep their curated values (none of these appear in models.dev, so platform values stand).
+- `minimax/minimax-m3`, `nvidia/nemotron-3-ultra`, and `mistralai/mistral-medium-3.5` keep their curated values (none of these appear in models.dev, so platform values stand).
 
 ## Alternative: separate metadata endpoint
 

package/docs/getting-started.html

@@ -0,0 +1,570 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>The route33 opencode Setup — Complete Guide</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --paper: #f5f1e8;
+    --paper-raised: #fdfbf6;
+    --ink: #1a1a18;
+    --ink-soft: #4a4a44;
+    --ink-faint: #8a8a80;
+    --accent: #f0b90b;
+    --accent-soft: #f7d654;
+    --line: #d8d2c2;
+    --code-bg: #26241f;
+    --code-ink: #e8e4d8;
+    --ok: #2e7d4f;
+    --warn: #b45309;
+  }
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  html { scroll-behavior: smooth; }
+  body {
+    background: var(--paper);
+    color: var(--ink);
+    font-family: 'Inter', system-ui, sans-serif;
+    font-size: 16px;
+    line-height: 1.65;
+    -webkit-font-smoothing: antialiased;
+  }
+  .wrap { max-width: 820px; margin: 0 auto; padding: 0 24px 96px; }
+
+  header {
+    border-bottom: 3px solid var(--ink);
+    padding: 48px 0 32px;
+    margin-bottom: 40px;
+  }
+  .brand {
+    display: flex; align-items: center; gap: 12px;
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 13px; font-weight: 600;
+    letter-spacing: 0.08em; text-transform: uppercase;
+    color: var(--ink-soft); margin-bottom: 20px;
+  }
+  .brand-mark {
+    width: 28px; height: 28px; border: 2.5px solid var(--ink);
+    border-radius: 50%; display: inline-flex; align-items: center; justify-content: center;
+    font-weight: 600; font-size: 14px; color: var(--ink);
+    border-bottom-color: var(--accent);
+  }
+  h1 {
+    font-size: clamp(30px, 5vw, 42px);
+    font-weight: 700; letter-spacing: -0.02em; line-height: 1.15;
+  }
+  h1 .hl { box-shadow: inset 0 -0.38em 0 var(--accent); }
+  .lede { margin-top: 14px; font-size: 18px; color: var(--ink-soft); max-width: 62ch; }
+
+  .toc {
+    background: var(--paper-raised);
+    border: 1px solid var(--line);
+    border-radius: 8px;
+    padding: 20px 24px;
+    margin: 32px 0 8px;
+  }
+  .toc-title {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 11.5px; font-weight: 600; letter-spacing: 0.08em;
+    text-transform: uppercase; color: var(--ink-faint); margin-bottom: 10px;
+  }
+  .toc ol { margin: 0 0 0 20px; }
+  .toc li { margin: 4px 0; font-size: 14.5px; }
+
+  section { margin-top: 56px; }
+  .step-head { display: flex; align-items: baseline; gap: 14px; margin-bottom: 6px; }
+  .step-num {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 13px; font-weight: 600;
+    background: var(--ink); color: var(--paper);
+    padding: 3px 10px; border-radius: 3px;
+    flex-shrink: 0; transform: translateY(-2px);
+  }
+  h2 { font-size: 24px; font-weight: 700; letter-spacing: -0.01em; }
+  h3 { font-size: 17px; font-weight: 600; margin-top: 28px; margin-bottom: 8px; }
+  p { margin: 12px 0; color: var(--ink-soft); }
+  p strong, li strong { color: var(--ink); }
+  ul, ol { margin: 12px 0 12px 22px; color: var(--ink-soft); }
+  li { margin: 6px 0; }
+  a { color: var(--ink); text-decoration-color: var(--accent); text-decoration-thickness: 2px; text-underline-offset: 2px; }
+  a:hover { background: var(--accent-soft); }
+
+  code {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 0.86em;
+    background: rgba(26,26,24,0.07);
+    padding: 2px 6px; border-radius: 4px;
+  }
+  pre {
+    background: var(--code-bg); color: var(--code-ink);
+    border-radius: 8px; padding: 18px 20px;
+    margin: 16px 0; overflow-x: auto;
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 13.5px; line-height: 1.6;
+    border-left: 4px solid var(--accent);
+  }
+  pre code { background: none; padding: 0; font-size: inherit; }
+  pre .c { color: #8a8577; }
+  pre .p { color: var(--accent); }
+
+  .note, .warning, .tip {
+    border-radius: 8px; padding: 14px 18px; margin: 18px 0;
+    font-size: 14.5px; line-height: 1.55;
+  }
+  .note { background: var(--paper-raised); border: 1px solid var(--line); border-left: 4px solid var(--ink); }
+  .warning { background: #fdf3e0; border: 1px solid #ecd9ae; border-left: 4px solid var(--warn); }
+  .tip { background: #eef5ef; border: 1px solid #cfe3d3; border-left: 4px solid var(--ok); }
+  .note .tag, .warning .tag, .tip .tag {
+    display: block; font-family: 'JetBrains Mono', monospace;
+    font-size: 11px; font-weight: 600; letter-spacing: 0.08em;
+    text-transform: uppercase; margin-bottom: 4px; color: var(--ink);
+  }
+  .note p, .warning p, .tip p { margin: 4px 0; }
+
+  table { width: 100%; border-collapse: collapse; margin: 18px 0; font-size: 14px; }
+  th {
+    text-align: left; font-family: 'JetBrains Mono', monospace;
+    font-size: 11.5px; letter-spacing: 0.06em; text-transform: uppercase;
+    color: var(--ink-soft); border-bottom: 2px solid var(--ink);
+    padding: 8px 12px 8px 0;
+  }
+  td { padding: 9px 12px 9px 0; border-bottom: 1px solid var(--line); vertical-align: top; color: var(--ink-soft); }
+  td code { font-size: 12.5px; }
+
+  .checklist { list-style: none; margin-left: 0; }
+  .checklist li { padding-left: 30px; position: relative; margin: 10px 0; }
+  .checklist li::before {
+    content: ""; position: absolute; left: 0; top: 3px;
+    width: 16px; height: 16px;
+    border: 2px solid var(--ink); border-radius: 4px;
+    background: var(--paper-raised);
+  }
+  .checklist li::after {
+    content: ""; position: absolute; left: 4.5px; top: 6px;
+    width: 5px; height: 9px;
+    border: solid var(--ok); border-width: 0 2.5px 2.5px 0;
+    transform: rotate(42deg);
+  }
+
+  .tree {
+    background: var(--code-bg); color: var(--code-ink);
+    border-radius: 8px; padding: 18px 20px;
+    margin: 16px 0; overflow-x: auto;
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 13px; line-height: 1.7;
+    border-left: 4px solid var(--accent);
+    white-space: pre;
+  }
+  .tree .dir { color: var(--accent); font-weight: 600; }
+  .tree .cm { color: #8a8577; }
+
+  footer {
+    margin-top: 80px; padding-top: 24px;
+    border-top: 1px solid var(--line);
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 12px; color: var(--ink-faint);
+    display: flex; justify-content: space-between; flex-wrap: wrap; gap: 8px;
+  }
+</style>
+</head>
+<body>
+<div class="wrap">
+<header>
+  <div class="brand"><span class="brand-mark">R</span> route33.ai &times; opencode</div>
+  <h1>The route33 opencode setup, <span class="hl">end to end</span></h1>
+  <p class="lede">Everything you need for a fully-equipped opencode harness on the route33.ai gateway: the terminal, the provider plugin, the oh-my-openagent orchestration layer, codebase intelligence, and how to shape your own agents. Roughly fifteen minutes, soup to nuts.</p>
+</header>
+
+<nav class="toc">
+  <div class="toc-title">In this guide</div>
+  <ol>
+    <li><a href="#stack">The moving parts</a></li>
+    <li><a href="#wezterm">WezTerm — the terminal</a></li>
+    <li><a href="#opencode-install">opencode itself</a></li>
+    <li><a href="#plugin">@route_33/opencode — the provider plugin</a></li>
+    <li><a href="#auth">Connecting your API key</a></li>
+    <li><a href="#omoa">oh-my-openagent — the orchestration layer</a></li>
+    <li><a href="#codebase-mcp">codebase-memory-mcp — codebase intelligence</a></li>
+    <li><a href="#dot-opencode">The .opencode/ directory, explained</a></li>
+    <li><a href="#agents">Configuring your own agents</a></li>
+    <li><a href="#verify">Verifying the whole stack</a></li>
+    <li><a href="#reference">Reference: env vars &amp; troubleshooting</a></li>
+  </ol>
+</nav>
+
+<!-- ============ 1. THE STACK ============ -->
+<section id="stack">
+  <div class="step-head"><span class="step-num">1</span><h2>The moving parts</h2></div>
+  <p>Five pieces of software cooperate in this setup. Knowing which layer owns what saves you from debugging the wrong one later:</p>
+  <table>
+    <tr><th>Layer</th><th>Component</th><th>What it owns</th></tr>
+    <tr><td><strong>Terminal</strong></td><td>WezTerm</td><td>Renders the TUI. GPU-accelerated, multiplexed panes, configured in Lua.</td></tr>
+    <tr><td><strong>Agent runtime</strong></td><td>opencode</td><td>The TUI + server. Loads plugins, MCP servers, agents, commands.</td></tr>
+    <tr><td><strong>Provider</strong></td><td>@route_33/opencode</td><td>Registers the <code>route_33</code> provider: key-scoped model discovery, cost/limit metadata, auth, key-setup wizard.</td></tr>
+    <tr><td><strong>Orchestration</strong></td><td>oh-my-openagent</td><td>The agent roster (Sisyphus, Oracle, explore, …), delegation categories, background tasks, fallback strategy, CodeGraph.</td></tr>
+    <tr><td><strong>Code intelligence</strong></td><td>codebase-memory-mcp</td><td>A knowledge graph of your repo (callers, traces, architecture) over MCP. Optional — see the note in its section.</td></tr>
+  </table>
+</section>
+
+<!-- ============ 2. WEZTERM ============ -->
+<section id="wezterm">
+  <div class="step-head"><span class="step-num">2</span><h2>WezTerm — the terminal</h2></div>
+  <p>opencode is a full-screen TUI. Any modern terminal works, but WezTerm is the recommended one: GPU-accelerated rendering, native panes and tabs (handy when oh-my-openagent fans out background agents), and a Lua config file that lives happily in version control.</p>
+
+  <h3>Install (macOS)</h3>
+  <pre><code><span class="p">$</span> brew install --cask wezterm</code></pre>
+  <p>Linux and Windows packages are on <a href="https://wezterm.org/installation.html">wezterm.org</a>.</p>
+
+  <h3>Minimal config</h3>
+  <p>WezTerm reads <code>~/.wezterm.lua</code> (or <code>~/.config/wezterm/wezterm.lua</code>). A sensible starting point for opencode work:</p>
+  <pre><code><span class="c">-- ~/.wezterm.lua</span>
+local wezterm = require 'wezterm'
+local config = wezterm.config_builder()
+
+config.font = wezterm.font 'JetBrains Mono'
+config.font_size = 13.0
+config.color_scheme = 'Builtin Solarized Dark'
+config.window_padding = { left = 12, right = 12, top = 12, bottom = 12 }
+
+<span class="c">-- Panes for watching background agents alongside your main session</span>
+config.keys = {
+  { key = 'd', mods = 'CMD',       action = wezterm.action.SplitHorizontal },
+  { key = 'd', mods = 'CMD|SHIFT', action = wezterm.action.SplitVertical },
+}
+
+return config</code></pre>
+
+  <div class="tip">
+    <span class="tag">Why panes matter here</span>
+    <p>oh-my-openagent can render background agents into visible terminal panes (<code>tmux: enabled</code> in its config). With WezTerm splits you get the same visibility natively — main session on the left, a log tail or second session on the right.</p>
+  </div>
+</section>
+
+<!-- ============ 3. OPENCODE ============ -->
+<section id="opencode-install">
+  <div class="step-head"><span class="step-num">3</span><h2>opencode itself</h2></div>
+  <p>You need opencode <strong>1.17.0 or newer</strong> (the plugin peer-depends on it). Installers:</p>
+  <pre><code><span class="c"># macOS / Linux — install script</span>
+<span class="p">$</span> curl -fsSL https://opencode.ai/install | bash
+
+<span class="c"># or Homebrew</span>
+<span class="p">$</span> brew install sst/tap/opencode
+
+<span class="c"># or npm</span>
+<span class="p">$</span> npm install -g opencode-ai</code></pre>
+  <p>Check what you got:</p>
+  <pre><code><span class="p">$</span> opencode --version
+1.17.20</code></pre>
+</section>
+<section id="plugin">
+  <div class="step-head"><span class="step-num">4</span><h2>@route_33/opencode — the provider plugin</h2></div>
+  <p>This is the piece that makes route33 models appear in opencode. It discovers the catalog live from the gateway, decorates models with cost/limit/capability metadata, and owns authentication.</p>
+
+  <h3>Install with the built-in installer</h3>
+  <pre><code><span class="p">$</span> opencode plugin @route_33/opencode</code></pre>
+  <p>Run it from your project directory to register the plugin in that project's <code>.opencode/</code>, or pass <code>--global</code> (or run it from your home directory) to register it in <code>~/.config/opencode/</code> for every project. Either way it patches two config files at the chosen level:</p>
+  <table>
+    <tr><th>File</th><th>What it registers</th></tr>
+    <tr><td><code>opencode.json(c)</code></td><td>The <strong>server plugin</strong> — model discovery, cost/limit enrichment, auth.</td></tr>
+    <tr><td><code>tui.json</code></td><td>The <strong>TUI plugin</strong> — the first-run key-setup wizard.</td></tr>
+  </table>
+  <p>Re-running with a new version needs <code>--force</code> to replace the existing pin.</p>
+
+  <div class="warning">
+    <span class="tag">"Package not found" outside the route33 repo?</span>
+    <p>The installer resolves the module name against npm — it works from any directory <em>as long as the package is published</em>. If your registry doesn't serve <code>@route_33/opencode</code> yet (or you're on a pre-release checkout), install from a local path instead. Two forms are known to work:</p>
+    <pre><code><span class="c">// opencode.json(c) — bare relative path, resolved against the config file's location</span>
+{
+  "plugin": ["../packages/integrations/opencode-route33"]
+}</code></pre>
+    <pre><code><span class="c">// or an absolute file:// URL (works everywhere, but is machine-bound)</span>
+{
+  "plugin": ["file:///Users/you/route_33/packages/integrations/opencode-route33"]
+}</code></pre>
+    <p>Avoid the <code>file:../relative</code> form — empirically (opencode 1.18.4) it fails to resolve. A local-path install covers the server plugin only; add the same entry to <code>tui.json</code> yourself if you want the key-setup wizard, and run <code>bun install &amp;&amp; bun run build</code> in the package directory first so <code>dist/</code> exists.</p>
+  </div>
+
+  <h3>Prefer to do it by hand?</h3>
+  <pre><code><span class="c">// ~/.config/opencode/opencode.json</span>
+{
+  "plugin": ["@route_33/opencode"]
+}</code></pre>
+  <pre><code><span class="c">// ~/.config/opencode/tui.json</span>
+{
+  "plugin": ["@route_33/opencode"]
+}</code></pre>
+
+  <div class="note">
+    <span class="tag">Good to know</span>
+    <p>The plugin never writes to your config on its own. opencode has no TUI-plugin auto-discovery, so if you skip the <code>tui.json</code> entry the setup wizard simply never appears — the server plugin (the part that actually serves models) works regardless.</p>
+  </div>
+
+  <div class="tip">
+    <span class="tag">Working inside the route33 repo?</span>
+    <p>You're already done with this step. The repo's <code>.opencode/opencode.jsonc</code> declares <code>@route_33/opencode@latest</code> for you — skip ahead to <a href="#auth">the auth step</a>.</p>
+  </div>
+</section>
+
+<section id="auth">
+  <div class="step-head"><span class="step-num">5</span><h2>Connecting your API key</h2></div>
+  <p>Mint a key in the route33 dashboard under your organization's <em>API keys</em> section — one per project, since per-project keys are the metering boundary. Then pick whichever resolution path fits your workflow; the first one that resolves wins.</p>
+
+  <h3>Option A — environment variable (highest precedence)</h3>
+  <pre><code><span class="p">$</span> export ROUTE33_API_KEY=r33_your_key_here</code></pre>
+  <p>Good for CI, containers, and one-off shells.</p>
+
+  <h3>Option B — opencode's auth store</h3>
+  <pre><code><span class="p">$</span> opencode auth login</code></pre>
+  <p>Choose <code>route_33</code> from the provider list and paste your key.</p>
+
+  <h3>Option C — let the wizard handle it</h3>
+  <p>If neither of the above is set, the TUI wizard pops up on first launch and offers to save a key for you:</p>
+  <ul>
+    <li><strong>Inside a git workspace</strong> → saved per-project to <code>&lt;project&gt;/.opencode/route33.key</code>. The file is written with mode <code>0600</code> and the plugin auto-adds it (plus <code>tui.json</code>) to <code>.opencode/.gitignore</code> so it never gets committed.</li>
+    <li><strong>Outside a git workspace</strong> → saved globally. A global key only applies <em>outside</em> git workspaces — inside one, the per-project key always wins.</li>
+  </ul>
+
+  <div class="note">
+    <span class="tag">Snoozing the wizard</span>
+    <p>Hitting "Skip" silences the prompt for 7 days — for that workspace only, or everywhere if you pick "Skip for all workspaces". To re-arm it sooner, remove the <code>project-key-prompt.dismissed-at*</code> entries from <code>~/.local/state/opencode/kv.json</code>. To disable the wizard permanently, set <code>ROUTE33_TUI_PROMPT=0</code>.</p>
+  </div>
+
+  <h3>Pointing at a non-production gateway (optional)</h3>
+  <p>Out of the box the plugin talks to <code>https://api.route33.ai/v1</code>. To develop against a local kind cluster:</p>
+  <pre><code><span class="c"># Example: your local kind cluster's API host</span>
+<span class="p">$</span> export ROUTE33_BASE_URL=https://api-&lt;hash&gt;-&lt;user&gt;-&lt;workspace&gt;.route33.ai/v1</code></pre>
+  <p>In the route33 repo, that hostname is computed for you by <code>deploy/lib/workspace-env.sh</code> (the <code>R33_HOST_API</code> variable).</p>
+</section>
+<section id="omoa">
+  <div class="step-head"><span class="step-num">6</span><h2>oh-my-openagent — the orchestration layer</h2></div>
+  <p><strong>oh-my-openagent</strong> (OMOA) is the plugin that turns a single opencode session into an orchestrated agent harness. It ships the named agent roster you interact with — Sisyphus (the orchestrator), Oracle (deep reasoning), explore and librarian (parallel search), Metis and Momus (planning) — plus delegation categories, background tasks, runtime model fallback, and a built-in CodeGraph for code intelligence.</p>
+
+  <h3>Install</h3>
+  <p>Add it to the <code>plugin</code> array in both config files, alongside the route33 plugin:</p>
+  <pre><code><span class="c">// ~/.config/opencode/opencode.json</span>
+{
+  "plugin": [
+    "oh-my-openagent@latest",
+    "@route_33/opencode@latest"
+  ]
+}</code></pre>
+  <pre><code><span class="c">// ~/.config/opencode/tui.json</span>
+{
+  "plugin": ["oh-my-openagent@latest"]
+}</code></pre>
+
+  <h3>Configure: oh-my-openagent.jsonc</h3>
+  <p>OMOA reads its own config file, <code>oh-my-openagent.jsonc</code>, from the same directory as your opencode config — global at <code>~/.config/opencode/</code>, per-project at <code>&lt;repo&gt;/.opencode/</code>. This is where you bind models to agents and categories. The route33 repo ships a working example — the highlights:</p>
+  <pre><code><span class="c">// .opencode/oh-my-openagent.jsonc (abridged)</span>
+{
+  <span class="c">// 429/5xx depletion failover, back to primary once quota resets</span>
+  "runtime_fallback": { "enabled": true, "notify_on_fallback": true },
+
+  <span class="c">// OMOA's built-in CodeGraph = the single code-intelligence source</span>
+  "codegraph": { "enabled": true, "telemetry": false },
+
+  <span class="c">// Fan-out limits for parallel background agents</span>
+  "background_task": {
+    "defaultConcurrency": 8,
+    "providerConcurrency": { "route_33": 10, "route_33/anthropic": 4 }
+  },
+
+  "agents": {
+    "sisyphus":  { "model": "route_33/moonshotai/kimi-k3", "variant": "max" },
+    "oracle":    { "model": "route_33/openai/gpt-5.6-sol", "variant": "high" },
+    "explore":   { "model": "route_33/openai/gpt-5.6-luna" },
+    "librarian": { "model": "route_33/openai/gpt-5.6-luna" }
+  },
+
+  "categories": {
+    "visual-engineering": { "model": "route_33/openai/gpt-5.6-sol", "variant": "high" },
+    "deep":               { "model": "route_33/openai/gpt-5.6-terra", "variant": "xhigh" },
+    "quick":              { "model": "route_33/openai/gpt-5.6-luna" },
+    "writing":            { "model": "route_33/moonshotai/kimi-k2.7-code" }
+  }
+}</code></pre>
+  <p>The mental model: <strong><code>agents</code></strong> binds a model to a named persona, <strong><code>categories</code></strong> binds a model to a <em>kind of work</em> (visual, deep research, quick fixes, writing). When Sisyphus delegates, the category resolver picks the model from the category first, falling back to the agent default.</p>
+
+  <div class="note">
+    <span class="tag">Variants</span>
+    <p><code>"variant"</code> selects a reasoning tier the model advertises (e.g. kimi-k3's <code>max</code>, gpt-5.6's <code>high</code>/<code>xhigh</code>). Variants come from the gateway's broadcast — the route33 plugin passes them through verbatim, so OMOA variant names and gateway variant names are the same vocabulary.</p>
+  </div>
+
+  <div class="tip">
+    <span class="tag">Flavours</span>
+    <p>Keep alternate OMOA configs as <em>flavours</em> in <code>.opencode/omo-flavours/&lt;name&gt;.jsonc</code> (the route33 repo keeps <code>r33-kimi-k3.jsonc</code> there). Copy one over <code>oh-my-openagent.jsonc</code> to switch the whole model matrix in one move.</p>
+  </div>
+</section>
+
+<section id="codebase-mcp">
+  <div class="step-head"><span class="step-num">7</span><h2>codebase-memory-mcp — codebase intelligence</h2></div>
+  <p><strong>codebase-memory-mcp</strong> builds a persistent knowledge graph of your repository — functions, classes, call chains, architecture — and exposes it to opencode over MCP. Agents can then answer "who calls this?" or "trace this call chain" structurally instead of grepping.</p>
+
+  <h3>Install and register</h3>
+  <pre><code><span class="c"># Install the CLI + server (auto-detects opencode and offers to register itself)</span>
+<span class="p">$</span> npm install -g codebase-memory-mcp
+<span class="p">$</span> codebase-memory-mcp install</code></pre>
+  <p>Or register it manually in your opencode config:</p>
+  <pre><code><span class="c">// ~/.config/opencode/opencode.json</span>
+{
+  "mcp": {
+    "codebase-memory-mcp": {
+      "type": "local",
+      "enabled": true,
+      "command": ["codebase-memory-mcp"]
+    }
+  }
+}</code></pre>
+  <p>Then index your repo once — agents do the rest via tools like <code>search_graph</code>, <code>trace_path</code>, <code>get_code_snippet</code>, and <code>get_architecture</code>:</p>
+  <pre><code><span class="p">$</span> codebase-memory-mcp cli index_repository '{"path": "."}'</code></pre>
+  <p>An optional graph-visualization UI runs on port 9749 (<code>codebase-memory-mcp --ui=true</code>).</p>
+
+  <div class="warning">
+    <span class="tag">Pick ONE code-intelligence source</span>
+    <p>OMOA ships its own built-in CodeGraph with a fresher watcher-based index. Running both means two indexes and agents torn between two tool vocabularies. The route33 repo's decision (2026-07-14): <strong>CodeGraph on, codebase-memory-mcp off</strong> — that's why <code>.opencode/opencode.jsonc</code> carries it under <code>"enabled": false</code> and the four <code>codebase-memory-*</code> skills sit in OMOA's <code>disabled_skills</code>. Flip the flag to <code>true</code> only if you've disabled CodeGraph.</p>
+  </div>
+</section>
+<section id="dot-opencode">
+  <div class="step-head"><span class="step-num">8</span><h2>The .opencode/ directory, explained</h2></div>
+  <p>opencode merges configuration from two roots. Everything in this guide lands in one of them:</p>
+  <table>
+    <tr><th>Root</th><th>Scope</th><th>Commit?</th></tr>
+    <tr><td><code>~/.config/opencode/</code></td><td>Global — every project on your machine</td><td>n/a (your dotfiles)</td></tr>
+    <tr><td><code>&lt;repo&gt;/.opencode/</code></td><td>Project — wins over global inside that repo</td><td>Yes, mostly — see below</td></tr>
+  </table>
+
+  <p>A fully-equipped project directory (this is the route33 repo's real layout):</p>
+  <div class="tree"><span class="dir">.opencode/</span>
+|-- <span class="dir">opencode.jsonc</span>          <span class="cm"># plugins + MCP servers for THIS project</span>
+|-- <span class="dir">oh-my-openagent.jsonc</span>   <span class="cm"># OMOA model matrix: agents + categories</span>
+|-- <span class="dir">agents/</span>                 <span class="cm"># custom agent definitions (*.md with frontmatter)</span>
+|   `-- 2po-commit.md
+|-- <span class="dir">commands/</span>               <span class="cm"># custom slash commands (*.md)</span>
+|   `-- 2po-commit.md
+|-- <span class="dir">omo-flavours/</span>           <span class="cm"># alternate OMOA configs to swap in</span>
+|   `-- r33-kimi-k3.jsonc
+|-- <span class="dir">route33.key</span>             <span class="cm"># per-project API key (GIT-IGNORED, mode 0600)</span>
+|-- <span class="dir">tui.json</span>                <span class="cm"># TUI plugin registration (GIT-IGNORED)</span>
+`-- <span class="dir">.gitignore</span>              <span class="cm"># guards the two files above + node_modules</span></div>
+
+  <h3>What each file is for</h3>
+  <table>
+    <tr><th>File</th><th>Purpose</th></tr>
+    <tr><td><code>opencode.jsonc</code></td><td>Project-level opencode config: the <code>plugin</code> array, <code>mcp</code> servers, provider overrides. JSONC — comments allowed.</td></tr>
+    <tr><td><code>tui.json</code></td><td>TUI plugin registration. Written by <code>opencode plugin</code> or the wizard; git-ignored because it can hold machine-local state.</td></tr>
+    <tr><td><code>oh-my-openagent.jsonc</code></td><td>OMOA's own config — the agent/category model matrix from <a href="#omoa">section 6</a>.</td></tr>
+    <tr><td><code>agents/*.md</code></td><td>Custom agents (next section). Markdown body = system prompt, YAML frontmatter = config.</td></tr>
+    <tr><td><code>commands/*.md</code></td><td>Custom slash commands — a prompt template invoked as <code>/name</code> in the TUI.</td></tr>
+    <tr><td><code>route33.key</code></td><td>The per-project API key written by the wizard. Never committed — the plugin maintains <code>.opencode/.gitignore</code> for you.</td></tr>
+    <tr><td><code>AGENTS.md</code> (repo root)</td><td>Not inside <code>.opencode/</code>, but part of the same story: the project knowledge base every agent reads. The route33 repo's root <code>AGENTS.md</code> is the canonical example.</td></tr>
+  </table>
+
+  <div class="note">
+    <span class="tag">Global vs project, in practice</span>
+    <p>Keep your <em>personal</em> setup global — plugins, the auth-store key, your default OMOA matrix in <code>~/.config/opencode/</code>. Keep <em>team-shared</em> setup in the repo — the project's plugin pins, the OMOA matrix tuned to this codebase, custom agents and commands everyone should have. Project config wins on conflict, so a repo can tighten a model choice without touching your other projects.</p>
+  </div>
+</section>
+<section id="agents">
+  <div class="step-head"><span class="step-num">9</span><h2>Configuring your own agents</h2></div>
+  <p>Custom agents are Markdown files with YAML frontmatter, dropped in <code>.opencode/agents/</code> (project) or <code>~/.config/opencode/agents/</code> (global). The filename becomes the agent name; the frontmatter configures it; the Markdown body is the system prompt.</p>
+
+  <h3>Anatomy of an agent file</h3>
+  <p>This is a trimmed version of the route33 repo's real <code>.opencode/agents/2po-commit.md</code> — a locked-down commit agent that can run git but can't edit files:</p>
+  <pre><code>---
+description: Create git commits for current changes
+mode: primary
+model: route_33/openai/gpt-5.6-luna
+hidden: true
+permission:
+  edit: deny
+  bash:
+    "*": deny
+    "git status*": allow
+    "git diff*": allow
+    "git add*": allow
+    "git commit*": allow
+  webfetch: deny
+---
+
+You are a git commit assistant. Your only job is to stage and
+commit ALL changes with a well-crafted commit message.
+...</code></pre>
+
+  <h3>The frontmatter keys that matter</h3>
+  <table>
+    <tr><th>Key</th><th>Values</th><th>Effect</th></tr>
+    <tr><td><code>description</code></td><td>free text</td><td>Shown in the agent picker; also how the orchestrator decides when to delegate to this agent.</td></tr>
+    <tr><td><code>mode</code></td><td><code>primary</code> | <code>subagent</code> | <code>all</code></td><td><code>primary</code> = you can switch to it directly (Tab in the TUI). <code>subagent</code> = only invocable via delegation.</td></tr>
+    <tr><td><code>model</code></td><td><code>provider/model</code></td><td>Pin this agent to a model — e.g. a cheap <code>gpt-5.6-luna</code> for a high-volume commit bot. Beats the global default.</td></tr>
+    <tr><td><code>hidden</code></td><td><code>true</code> | <code>false</code></td><td>Hide from the picker while keeping it delegable.</td></tr>
+    <tr><td><code>permission</code></td><td>per-tool allow/deny</td><td>Default-deny with glob exceptions, as above: this agent can only run four git commands and nothing else.</td></tr>
+  </table>
+
+  <h3>Custom slash commands</h3>
+  <p>The sibling <code>.opencode/commands/</code> folder holds prompt templates invoked as <code>/name</code>. Same Markdown format — a <code>description</code> in frontmatter, the prompt in the body, optional <code>agent</code> and <code>model</code> pins. The repo's <code>2po-commit.md</code> command is the companion to the agent above: typing <code>/2po-commit</code> runs that prompt through that agent.</p>
+
+  <div class="tip">
+    <span class="tag">The design rule of thumb</span>
+    <p><strong>Agents</strong> are for <em>who does the work</em> (a persona with a model and a permission envelope). <strong>Commands</strong> are for <em>what work to do</em> (a reusable prompt). <strong>OMOA categories</strong> are for <em>which model fits this kind of work</em> when the orchestrator delegates. Most setups need a handful of commands, one or two custom agents, and zero new categories.</p>
+  </div>
+</section>
+<section id="verify">
+  <div class="step-head"><span class="step-num">10</span><h2>Verifying the whole stack</h2></div>
+  <p>Launch <code>opencode</code> in your project and run through this checklist:</p>
+  <ul class="checklist">
+    <li>route33 models appear in the model picker as <code>vendor/slug</code> IDs (<code>anthropic/claude-haiku-4-5</code>, <code>openai/gpt-5.5</code>, …)</li>
+    <li>Costs and context limits show up on model entries</li>
+    <li>A chat request to a route33 model completes</li>
+    <li>The agent picker (Tab) lists the OMOA roster — Sisyphus, Oracle, explore, librarian, plus your custom agents</li>
+    <li>Your custom slash command appears when you type <code>/</code></li>
+    <li>Asking "who calls X?" uses graph tools (CodeGraph or codebase-memory-mcp, whichever you enabled)</li>
+  </ul>
+
+  <div class="warning">
+    <span class="tag">Seeing "0 models injected"?</span>
+    <p>The warning <code>route33: no model catalog available — 0 models injected</code> means no key resolved. Re-run <code>opencode auth login</code>, check your <code>ROUTE33_API_KEY</code>, or confirm <code>.opencode/route33.key</code> exists in your project. The key dictates which models are available — without one, discovery has nothing to work with.</p>
+  </div>
+</section>
+
+<section id="reference">
+  <div class="step-head"><span class="step-num">&#9881;</span><h2>Reference: env vars &amp; troubleshooting</h2></div>
+  <table>
+    <tr><th>Variable</th><th>Effect</th></tr>
+    <tr><td><code>ROUTE33_API_KEY</code></td><td>Gateway API key. Highest precedence.</td></tr>
+    <tr><td><code>ROUTE33_BASE_URL</code></td><td>Override the default gateway URL (<code>https://api.route33.ai/v1</code>).</td></tr>
+    <tr><td><code>ROUTE33_TUI_PROMPT</code></td><td>Set to <code>0</code> to disable the key-setup wizard.</td></tr>
+    <tr><td><code>ROUTE33_DISCOVERY</code></td><td>Set to <code>0</code> to disable dynamic catalog discovery (injects zero models, no warning).</td></tr>
+    <tr><td><code>ROUTE33_STRICT</code></td><td>Set to <code>0</code> to downgrade unknown-model reference errors to a warning plus a stub entry.</td></tr>
+    <tr><td><code>ROUTE33_CACHE_DIR</code></td><td>Override the on-disk catalog cache directory.</td></tr>
+  </table>
+
+  <h3>Common bumps</h3>
+  <table>
+    <tr><th>Symptom</th><th>Likely cause and fix</th></tr>
+    <tr><td>No route33 models in picker</td><td>No key resolved → <a href="#auth">section 5</a>. Or discovery opted out → unset <code>ROUTE33_DISCOVERY</code>.</td></tr>
+    <tr><td>Key wizard never appears</td><td>Missing <code>tui.json</code> plugin entry → <a href="#plugin">section 4</a>. Or snoozed → clear <code>project-key-prompt.dismissed-at*</code> in <code>~/.local/state/opencode/kv.json</code>.</td></tr>
+    <tr><td>Global key ignored inside a repo</td><td>By design — per-project keys win inside git workspaces. Save a project key via the wizard.</td></tr>
+    <tr><td>Agents use the wrong models</td><td>Project <code>oh-my-openagent.jsonc</code> overrides global → check <code>&lt;repo&gt;/.opencode/</code> first.</td></tr>
+    <tr><td>Duplicate graph tools / confused search</td><td>Both CodeGraph and codebase-memory-mcp enabled → pick one, <a href="#codebase-mcp">section 7</a>.</td></tr>
+    <tr><td><code>file:</code>-prefixed local plugin path fails</td><td>Known opencode quirk — use the bare relative form (<code>../packages/integrations/opencode-route33</code>) or an absolute <code>file://</code> URL → <a href="#plugin">section 4</a>.</td></tr>
+    <tr><td><code>opencode plugin</code> says "package not found"</td><td>Your npm registry doesn't serve <code>@route_33/opencode</code> → install from a local path instead, <a href="#plugin">section 4</a>.</td></tr>
+  </table>
+
+  <h3>Small conveniences worth knowing</h3>
+  <ul>
+    <li><strong>Dot/dash tolerance</strong> — a config reference like <code>anthropic/claude-opus-4.8</code> automatically resolves to the served <code>anthropic/claude-opus-4-8</code>. Arbitrary renames don't resolve.</li>
+    <li><strong>Stale-cache fallback</strong> — if the gateway is unreachable, the plugin serves the last good cached catalog rather than failing. Only a cold start with no cache and no gateway yields zero models.</li>
+    <li><strong>Live key reload</strong> — a key saved through the wizard takes effect immediately, no restart needed.</li>
+  </ul>
+</section>
+
+<footer>
+  <span>@route_33/opencode &middot; v0.4.0</span>
+  <span>source: packages/integrations/opencode-route33</span>
+</footer>
+</div>
+</body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@route_33/opencode",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "description": "opencode provider plugin for the route33.ai AI gateway \u2014 key-scoped model discovery, cost/limit enrichment, auth, and the key-setup wizard.",