nodmix 2026.5.25

package/docs/providers/opencode-go.md

@@ -0,0 +1,123 @@
+---
+summary: "Use the OpenCode Go catalog with the shared OpenCode setup"
+read_when:
+  - You want the OpenCode Go catalog
+  - You need the runtime model refs for Go-hosted models
+title: "OpenCode Go"
+---
+
+OpenCode Go is the Go catalog within [OpenCode](/providers/opencode).
+It uses the same `OPENCODE_API_KEY` as the Zen catalog, but keeps the runtime
+provider id `opencode-go` so upstream per-model routing stays correct.
+
+| Property         | Value                           |
+| ---------------- | ------------------------------- |
+| Runtime provider | `opencode-go`                   |
+| Auth             | `OPENCODE_API_KEY`              |
+| Parent setup     | [OpenCode](/providers/opencode) |
+
+## Built-in catalog
+
+Nodmix sources most Go catalog rows from the bundled pi model registry and
+supplements current upstream rows while the registry catches up. Run
+`nodmix models list --provider opencode-go` for the current model list.
+
+The provider includes:
+
+| Model ref                       | Name                  |
+| ------------------------------- | --------------------- |
+| `opencode-go/glm-5`             | GLM-5                 |
+| `opencode-go/glm-5.1`           | GLM-5.1               |
+| `opencode-go/kimi-k2.5`         | Kimi K2.5             |
+| `opencode-go/kimi-k2.6`         | Kimi K2.6 (3x limits) |
+| `opencode-go/deepseek-v4-pro`   | DeepSeek V4 Pro       |
+| `opencode-go/deepseek-v4-flash` | DeepSeek V4 Flash     |
+| `opencode-go/mimo-v2-omni`      | MiMo V2 Omni          |
+| `opencode-go/mimo-v2-pro`       | MiMo V2 Pro           |
+| `opencode-go/minimax-m2.5`      | MiniMax M2.5          |
+| `opencode-go/minimax-m2.7`      | MiniMax M2.7          |
+| `opencode-go/qwen3.5-plus`      | Qwen3.5 Plus          |
+| `opencode-go/qwen3.6-plus`      | Qwen3.6 Plus          |
+
+## Getting started
+
+<Tabs>
+  <Tab title="Interactive">
+    <Steps>
+      <Step title="Run onboarding">
+        ```bash
+        nodmix onboard --auth-choice opencode-go
+        ```
+      </Step>
+      <Step title="Set a Go model as default">
+        ```bash
+        nodmix config set agents.defaults.model.primary "opencode-go/kimi-k2.6"
+        ```
+      </Step>
+      <Step title="Verify models are available">
+        ```bash
+        nodmix models list --provider opencode-go
+        ```
+      </Step>
+    </Steps>
+  </Tab>
+
+  <Tab title="Non-interactive">
+    <Steps>
+      <Step title="Pass the key directly">
+        ```bash
+        nodmix onboard --opencode-go-api-key "$OPENCODE_API_KEY"
+        ```
+      </Step>
+      <Step title="Verify models are available">
+        ```bash
+        nodmix models list --provider opencode-go
+        ```
+      </Step>
+    </Steps>
+  </Tab>
+</Tabs>
+
+## Config example
+
+```json5
+{
+  env: { OPENCODE_API_KEY: "YOUR_API_KEY_HERE" }, // pragma: allowlist secret
+  agents: { defaults: { model: { primary: "opencode-go/kimi-k2.6" } } },
+}
+```
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Routing behavior">
+    Nodmix handles per-model routing automatically when the model ref uses
+    `opencode-go/...`. No additional provider config is required.
+  </Accordion>
+
+  <Accordion title="Runtime ref convention">
+    Runtime refs stay explicit: `opencode/...` for Zen, `opencode-go/...` for Go.
+    This keeps upstream per-model routing correct across both catalogs.
+  </Accordion>
+
+  <Accordion title="Shared credentials">
+    The same `OPENCODE_API_KEY` is used by both the Zen and Go catalogs. Entering
+    the key during setup stores credentials for both runtime providers.
+  </Accordion>
+</AccordionGroup>
+
+<Tip>
+See [OpenCode](/providers/opencode) for the shared onboarding overview and the full
+Zen + Go catalog reference.
+</Tip>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="OpenCode (parent)" href="/providers/opencode" icon="server">
+    Shared onboarding, catalog overview, and advanced notes.
+  </Card>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+</CardGroup>

package/docs/providers/opencode.md

@@ -0,0 +1,149 @@
+---
+summary: "Use OpenCode Zen and Go catalogs with Nodmix"
+read_when:
+  - You want OpenCode-hosted model access
+  - You want to pick between the Zen and Go catalogs
+title: "OpenCode"
+---
+
+OpenCode exposes two hosted catalogs in Nodmix:
+
+| Catalog | Prefix            | Runtime provider |
+| ------- | ----------------- | ---------------- |
+| **Zen** | `opencode/...`    | `opencode`       |
+| **Go**  | `opencode-go/...` | `opencode-go`    |
+
+Both catalogs use the same OpenCode API key. Nodmix keeps the runtime provider ids
+split so upstream per-model routing stays correct, but onboarding and docs treat them
+as one OpenCode setup.
+
+## Getting started
+
+<Tabs>
+  <Tab title="Zen catalog">
+    **Best for:** the curated OpenCode multi-model proxy (Claude, GPT, Gemini).
+
+    <Steps>
+      <Step title="Run onboarding">
+        ```bash
+        nodmix onboard --auth-choice opencode-zen
+        ```
+
+        Or pass the key directly:
+
+        ```bash
+        nodmix onboard --opencode-zen-api-key "$OPENCODE_API_KEY"
+        ```
+      </Step>
+      <Step title="Set a Zen model as the default">
+        ```bash
+        nodmix config set agents.defaults.model.primary "opencode/claude-opus-4-6"
+        ```
+      </Step>
+      <Step title="Verify models are available">
+        ```bash
+        nodmix models list --provider opencode
+        ```
+      </Step>
+    </Steps>
+
+  </Tab>
+
+  <Tab title="Go catalog">
+    **Best for:** the OpenCode-hosted Kimi, GLM, and MiniMax lineup.
+
+    <Steps>
+      <Step title="Run onboarding">
+        ```bash
+        nodmix onboard --auth-choice opencode-go
+        ```
+
+        Or pass the key directly:
+
+        ```bash
+        nodmix onboard --opencode-go-api-key "$OPENCODE_API_KEY"
+        ```
+      </Step>
+      <Step title="Set a Go model as the default">
+        ```bash
+        nodmix config set agents.defaults.model.primary "opencode-go/kimi-k2.6"
+        ```
+      </Step>
+      <Step title="Verify models are available">
+        ```bash
+        nodmix models list --provider opencode-go
+        ```
+      </Step>
+    </Steps>
+
+  </Tab>
+</Tabs>
+
+## Config example
+
+```json5
+{
+  env: { OPENCODE_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
+}
+```
+
+## Built-in catalogs
+
+### Zen
+
+| Property         | Value                                                                   |
+| ---------------- | ----------------------------------------------------------------------- |
+| Runtime provider | `opencode`                                                              |
+| Example models   | `opencode/claude-opus-4-6`, `opencode/gpt-5.5`, `opencode/gemini-3-pro` |
+
+### Go
+
+| Property         | Value                                                                    |
+| ---------------- | ------------------------------------------------------------------------ |
+| Runtime provider | `opencode-go`                                                            |
+| Example models   | `opencode-go/kimi-k2.6`, `opencode-go/glm-5`, `opencode-go/minimax-m2.5` |
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="API key aliases">
+    `OPENCODE_ZEN_API_KEY` is also supported as an alias for `OPENCODE_API_KEY`.
+  </Accordion>
+
+  <Accordion title="Shared credentials">
+    Entering one OpenCode key during setup stores credentials for both runtime
+    providers. You do not need to onboard each catalog separately.
+  </Accordion>
+
+  <Accordion title="Billing and dashboard">
+    You sign in to OpenCode, add billing details, and copy your API key. Billing
+    and catalog availability are managed from the OpenCode dashboard.
+  </Accordion>
+
+  <Accordion title="Gemini replay behavior">
+    Gemini-backed OpenCode refs stay on the proxy-Gemini path, so Nodmix keeps
+    Gemini thought-signature sanitation there without enabling native Gemini
+    replay validation or bootstrap rewrites.
+  </Accordion>
+
+  <Accordion title="Non-Gemini replay behavior">
+    Non-Gemini OpenCode refs keep the minimal OpenAI-compatible replay policy.
+  </Accordion>
+</AccordionGroup>
+
+<Tip>
+Entering one OpenCode key during setup stores credentials for both the Zen and
+Go runtime providers, so you only need to onboard once.
+</Tip>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
+    Full config reference for agents, models, and providers.
+  </Card>
+</CardGroup>

package/docs/providers/openrouter.md

@@ -0,0 +1,349 @@
+---
+summary: "Use OpenRouter's unified API to access many models in Nodmix"
+read_when:
+  - You want a single API key for many LLMs
+  - You want to run models via OpenRouter in Nodmix
+  - You want to use OpenRouter for image generation
+  - You want to use OpenRouter for music generation
+  - You want to use OpenRouter for video generation
+title: "OpenRouter"
+---
+
+OpenRouter provides a **unified API** that routes requests to many models behind a single
+endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
+
+## Getting started
+
+<Steps>
+  <Step title="Get your API key">
+    Create an API key at [openrouter.ai/keys](https://openrouter.ai/keys).
+  </Step>
+  <Step title="Run onboarding">
+    ```bash
+    nodmix onboard --auth-choice openrouter-api-key
+    ```
+  </Step>
+  <Step title="(Optional) Switch to a specific model">
+    Onboarding defaults to `openrouter/auto`. Pick a concrete model later:
+
+    ```bash
+    nodmix models set openrouter/<provider>/<model>
+    ```
+
+  </Step>
+</Steps>
+
+## Config example
+
+```json5
+{
+  env: { OPENROUTER_API_KEY: "sk-or-..." },
+  agents: {
+    defaults: {
+      model: { primary: "openrouter/auto" },
+    },
+  },
+}
+```
+
+## Model references
+
+<Note>
+Model refs follow the pattern `openrouter/<provider>/<model>`. For the full list of
+available providers and models, see [/concepts/model-providers](/concepts/model-providers).
+</Note>
+
+Bundled fallback examples:
+
+| Model ref                         | Notes                        |
+| --------------------------------- | ---------------------------- |
+| `openrouter/auto`                 | OpenRouter automatic routing |
+| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 via MoonshotAI     |
+| `openrouter/moonshotai/kimi-k2.5` | Kimi K2.5 via MoonshotAI     |
+
+## Image generation
+
+OpenRouter can also back the `image_generate` tool. Use an OpenRouter image model under `agents.defaults.imageGenerationModel`:
+
+```json5
+{
+  env: { OPENROUTER_API_KEY: "sk-or-..." },
+  agents: {
+    defaults: {
+      imageGenerationModel: {
+        primary: "openrouter/google/gemini-3.1-flash-image-preview",
+        timeoutMs: 180_000,
+      },
+    },
+  },
+}
+```
+
+Nodmix sends image requests to OpenRouter's chat completions image API with `modalities: ["image", "text"]`. Gemini image models receive supported `aspectRatio` and `resolution` hints through OpenRouter's `image_config`. Use `agents.defaults.imageGenerationModel.timeoutMs` for slower OpenRouter image models; the `image_generate` tool's per-call `timeoutMs` parameter still wins.
+
+## Video generation
+
+OpenRouter can also back the `video_generate` tool through its asynchronous `/videos` API. Use an OpenRouter video model under `agents.defaults.videoGenerationModel`:
+
+```json5
+{
+  env: { OPENROUTER_API_KEY: "sk-or-..." },
+  agents: {
+    defaults: {
+      videoGenerationModel: {
+        primary: "openrouter/google/veo-3.1-fast",
+      },
+    },
+  },
+}
+```
+
+Nodmix submits text-to-video and image-to-video jobs to OpenRouter, polls
+the returned `polling_url`, and downloads the completed video from
+OpenRouter's `unsigned_urls` or the documented job content endpoint.
+Reference images are sent as first/last frame images by default; images
+tagged with `reference_image` are sent as OpenRouter input references. The
+bundled `google/veo-3.1-fast` default advertises the currently supported 4/6/8
+second durations, `720P`/`1080P` resolutions, and `16:9`/`9:16` aspect
+ratios. Video-to-video is not registered for OpenRouter because the upstream
+video generation API currently accepts text and image references.
+
+## Music generation
+
+OpenRouter can also back the `music_generate` tool through chat completions
+audio output. Use an OpenRouter audio model under
+`agents.defaults.musicGenerationModel`:
+
+```json5
+{
+  env: { OPENROUTER_API_KEY: "sk-or-..." },
+  agents: {
+    defaults: {
+      musicGenerationModel: {
+        primary: "openrouter/google/lyria-3-pro-preview",
+        timeoutMs: 180_000,
+      },
+    },
+  },
+}
+```
+
+The bundled OpenRouter music provider defaults to
+`google/lyria-3-pro-preview` and also exposes
+`google/lyria-3-clip-preview`. Nodmix sends `modalities: ["text",
+"audio"]`, enables streaming, collects the streamed audio chunks, and saves
+the result as generated media for channel delivery. Reference images are
+accepted for Lyria models through the shared `music_generate image=...`
+parameter.
+
+## Text-to-speech
+
+OpenRouter can also be used as a TTS provider through its OpenAI-compatible
+`/audio/speech` endpoint.
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+      provider: "openrouter",
+      providers: {
+        openrouter: {
+          model: "hexgrad/kokoro-82m",
+          voice: "af_alloy",
+          responseFormat: "mp3",
+        },
+      },
+    },
+  },
+}
+```
+
+If `messages.tts.providers.openrouter.apiKey` is omitted, TTS reuses
+`models.providers.openrouter.apiKey`, then `OPENROUTER_API_KEY`.
+
+## Speech-to-text (inbound audio)
+
+OpenRouter can transcribe inbound voice/audio attachments through the shared
+`tools.media.audio` path using its STT endpoint (`/audio/transcriptions`).
+This applies to any channel plugin that forwards inbound voice/audio into
+media understanding preflight.
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        models: [{ provider: "openrouter", model: "openai/whisper-large-v3-turbo" }],
+      },
+    },
+  },
+}
+```
+
+Nodmix sends OpenRouter STT requests as JSON with base64 audio under
+`input_audio` (OpenRouter STT contract), not as multipart OpenAI form uploads.
+
+## Authentication and headers
+
+OpenRouter uses a Bearer token with your API key under the hood.
+
+On real OpenRouter requests (`https://openrouter.ai/api/v1`), Nodmix also adds
+OpenRouter's documented app-attribution headers:
+
+| Header                    | Value                                                                                                  |
+| ------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `HTTP-Referer`            | `https://nodmix.ai`                                                                                  |
+| `X-OpenRouter-Title`      | `Nodmix`                                                                                             |
+| `X-OpenRouter-Categories` | `cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent` |
+
+<Warning>
+If you repoint the OpenRouter provider at some other proxy or base URL, Nodmix
+does **not** inject those OpenRouter-specific headers or Anthropic cache markers.
+</Warning>
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Response caching">
+    OpenRouter response caching is opt-in. Enable it per OpenRouter model with
+    model params:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          models: {
+            "openrouter/auto": {
+              params: {
+                responseCache: true,
+                responseCacheTtlSeconds: 300,
+              },
+            },
+          },
+        },
+      },
+    }
+    ```
+
+    Nodmix sends `X-OpenRouter-Cache: true` and, when configured,
+    `X-OpenRouter-Cache-TTL`. `responseCacheClear: true` forces a refresh for
+    the current request and stores the replacement response. Snake_case aliases
+    (`response_cache`, `response_cache_ttl_seconds`, and
+    `response_cache_clear`) are also accepted.
+
+    This is separate from provider prompt caching and from OpenRouter's
+    Anthropic `cache_control` markers. It is only applied on verified
+    `openrouter.ai` routes, not custom proxy base URLs.
+
+  </Accordion>
+
+  <Accordion title="Anthropic cache markers">
+    On verified OpenRouter routes, Anthropic model refs keep the
+    OpenRouter-specific Anthropic `cache_control` markers that Nodmix uses for
+    better prompt-cache reuse on system/developer prompt blocks.
+  </Accordion>
+
+  <Accordion title="Anthropic reasoning prefill">
+    On verified OpenRouter routes, Anthropic model refs with reasoning enabled
+    drop trailing assistant prefill turns before the request reaches OpenRouter,
+    matching Anthropic's requirement that reasoning conversations end with a user
+    turn.
+  </Accordion>
+
+  <Accordion title="Thinking / reasoning injection">
+    On supported non-`auto` routes, Nodmix maps the selected thinking level to
+    OpenRouter proxy reasoning payloads. Unsupported model hints and
+    `openrouter/auto` skip that reasoning injection. Hunter Alpha also skips
+    proxy reasoning for stale configured model refs because OpenRouter could
+    return final answer text in reasoning fields for that retired route.
+  </Accordion>
+
+  <Accordion title="DeepSeek V4 reasoning replay">
+    On verified OpenRouter routes, `openrouter/deepseek/deepseek-v4-flash` and
+    `openrouter/deepseek/deepseek-v4-pro` fill missing `reasoning_content` on
+    replayed assistant turns so thinking/tool conversations keep DeepSeek V4's
+    required follow-up shape. Nodmix sends OpenRouter-supported
+    `reasoning_effort` values for these routes; `xhigh` is the highest advertised
+    level, and stale `max` overrides are mapped to `xhigh`.
+  </Accordion>
+
+  <Accordion title="OpenAI-only request shaping">
+    OpenRouter still runs through the proxy-style OpenAI-compatible path, so
+    native OpenAI-only request shaping such as `serviceTier`, Responses `store`,
+    OpenAI reasoning-compat payloads, and prompt-cache hints is not forwarded.
+  </Accordion>
+
+  <Accordion title="Gemini-backed routes">
+    Gemini-backed OpenRouter refs stay on the proxy-Gemini path: Nodmix keeps
+    Gemini thought-signature sanitation there, but does not enable native Gemini
+    replay validation or bootstrap rewrites.
+  </Accordion>
+
+  <Accordion title="Provider routing metadata">
+    OpenRouter supports a `provider` request object for underlying provider
+    routing. Configure a default policy for all OpenRouter text-model requests
+    with `models.providers.openrouter.params.provider`:
+
+    ```json5
+    {
+      models: {
+        providers: {
+          openrouter: {
+            params: {
+              provider: {
+                sort: "latency",
+                require_parameters: true,
+                data_collection: "deny",
+              },
+            },
+          },
+        },
+      },
+    }
+    ```
+
+    Nodmix forwards that object to OpenRouter as the request `provider`
+    payload. Use OpenRouter's documented snake_case fields, including `sort`,
+    `only`, `ignore`, `order`, `allow_fallbacks`, `require_parameters`,
+    `data_collection`, `quantizations`, `max_price`, `preferred_max_latency`,
+    `preferred_min_throughput`, `zdr`, and `enforce_distillable_text`.
+
+    Per-model params still override the provider-wide routing object:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          models: {
+            "openrouter/anthropic/claude-sonnet-4-6": {
+              params: {
+                provider: {
+                  order: ["anthropic"],
+                  allow_fallbacks: false,
+                },
+              },
+            },
+          },
+        },
+      },
+    }
+    ```
+
+    This only applies on OpenRouter chat-completions routes. Direct Anthropic,
+    Google, OpenAI, or custom provider routes ignore OpenRouter routing params.
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
+    Full config reference for agents, models, and providers.
+  </Card>
+</CardGroup>