nodmix 2026.5.25

package/docs/providers/anthropic.md

@@ -0,0 +1,344 @@
+---
+summary: "Use Anthropic Claude via API keys or Claude CLI in Nodmix"
+read_when:
+  - You want to use Anthropic models in Nodmix
+title: "Anthropic"
+---
+
+Anthropic builds the **Claude** model family. Nodmix supports two auth routes:
+
+- **API key** — direct Anthropic API access with usage-based billing (`anthropic/*` models)
+- **Claude CLI** — reuse an existing Claude CLI login on the same host
+
+<Warning>
+Anthropic staff told us Nodmix-style Claude CLI usage is allowed again, so
+Nodmix treats Claude CLI reuse and `claude -p` usage as sanctioned unless
+Anthropic publishes a new policy.
+
+For long-lived gateway hosts, Anthropic API keys are still the clearest and
+most predictable production path.
+
+Anthropic's current public docs:
+
+- [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference)
+- [Claude Agent SDK overview](https://platform.claude.com/docs/en/agent-sdk/overview)
+- [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
+- [Using Claude Code with your Team or Enterprise plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)
+
+</Warning>
+
+## Getting started
+
+<Tabs>
+  <Tab title="API key">
+    **Best for:** standard API access and usage-based billing.
+
+    <Steps>
+      <Step title="Get your API key">
+        Create an API key in the [Anthropic Console](https://console.anthropic.com/).
+      </Step>
+      <Step title="Run onboarding">
+        ```bash
+        nodmix onboard
+        # choose: Anthropic API key
+        ```
+
+        Or pass the key directly:
+
+        ```bash
+        nodmix onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
+        ```
+      </Step>
+      <Step title="Verify the model is available">
+        ```bash
+        nodmix models list --provider anthropic
+        ```
+      </Step>
+    </Steps>
+
+    ### Config example
+
+    ```json5
+    {
+      env: { ANTHROPIC_API_KEY: "sk-ant-..." },
+      agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
+    }
+    ```
+
+  </Tab>
+
+  <Tab title="Claude CLI">
+    **Best for:** reusing an existing Claude CLI login without a separate API key.
+
+    <Steps>
+      <Step title="Ensure Claude CLI is installed and logged in">
+        Verify with:
+
+        ```bash
+        claude --version
+        ```
+      </Step>
+      <Step title="Run onboarding">
+        ```bash
+        nodmix onboard
+        # choose: Claude CLI
+        ```
+
+        Nodmix detects and reuses the existing Claude CLI credentials.
+      </Step>
+      <Step title="Verify the model is available">
+        ```bash
+        nodmix models list --provider anthropic
+        ```
+      </Step>
+    </Steps>
+
+    <Note>
+    Setup and runtime details for the Claude CLI backend are in [CLI Backends](/gateway/cli-backends).
+    </Note>
+
+    ### Config example
+
+    Prefer the canonical Anthropic model ref plus a CLI runtime override:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: { primary: "anthropic/claude-opus-4-7" },
+          models: {
+            "anthropic/claude-opus-4-7": {
+              agentRuntime: { id: "claude-cli" },
+            },
+          },
+        },
+      },
+    }
+    ```
+
+    Legacy `claude-cli/claude-opus-4-7` model refs still work for
+    compatibility, but new config should keep provider/model selection as
+    `anthropic/*` and put the execution backend in provider/model runtime policy.
+
+    <Tip>
+    If you want the clearest billing path, use an Anthropic API key instead. Nodmix also supports subscription-style options from [OpenAI Codex](/providers/openai), [Qwen Cloud](/providers/qwen), [MiniMax](/providers/minimax), and [Z.AI / GLM](/providers/glm).
+    </Tip>
+
+  </Tab>
+</Tabs>
+
+## Thinking defaults (Claude 4.6)
+
+Claude 4.6 models default to `adaptive` thinking in Nodmix when no explicit thinking level is set.
+
+Override per-message with `/think:<level>` or in model params:
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-opus-4-6": {
+          params: { thinking: "adaptive" },
+        },
+      },
+    },
+  },
+}
+```
+
+<Note>
+Related Anthropic docs:
+- [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking)
+- [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
+
+</Note>
+
+## Prompt caching
+
+Nodmix supports Anthropic's prompt caching feature for API-key auth.
+
+| Value               | Cache duration | Description                            |
+| ------------------- | -------------- | -------------------------------------- |
+| `"short"` (default) | 5 minutes      | Applied automatically for API-key auth |
+| `"long"`            | 1 hour         | Extended cache                         |
+| `"none"`            | No caching     | Disable prompt caching                 |
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-opus-4-6": {
+          params: { cacheRetention: "long" },
+        },
+      },
+    },
+  },
+}
+```
+
+<AccordionGroup>
+  <Accordion title="Per-agent cache overrides">
+    Use model-level params as your baseline, then override specific agents via `agents.list[].params`:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: { primary: "anthropic/claude-opus-4-6" },
+          models: {
+            "anthropic/claude-opus-4-6": {
+              params: { cacheRetention: "long" },
+            },
+          },
+        },
+        list: [
+          { id: "research", default: true },
+          { id: "alerts", params: { cacheRetention: "none" } },
+        ],
+      },
+    }
+    ```
+
+    Config merge order:
+
+    1. `agents.defaults.models["provider/model"].params`
+    2. `agents.list[].params` (matching `id`, overrides by key)
+
+    This lets one agent keep a long-lived cache while another agent on the same model disables caching for bursty/low-reuse traffic.
+
+  </Accordion>
+
+  <Accordion title="Bedrock Claude notes">
+    - Anthropic Claude models on Bedrock (`amazon-bedrock/*anthropic.claude*`) accept `cacheRetention` pass-through when configured.
+    - Non-Anthropic Bedrock models are forced to `cacheRetention: "none"` at runtime.
+    - API-key smart defaults also seed `cacheRetention: "short"` for Claude-on-Bedrock refs when no explicit value is set.
+
+  </Accordion>
+</AccordionGroup>
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Fast mode">
+    Nodmix's shared `/fast` toggle supports direct Anthropic traffic (API-key and OAuth to `api.anthropic.com`).
+
+    | Command | Maps to |
+    |---------|---------|
+    | `/fast on` | `service_tier: "auto"` |
+    | `/fast off` | `service_tier: "standard_only"` |
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          models: {
+            "anthropic/claude-sonnet-4-6": {
+              params: { fastMode: true },
+            },
+          },
+        },
+      },
+    }
+    ```
+
+    <Note>
+    - Only injected for direct `api.anthropic.com` requests. Proxy routes leave `service_tier` untouched.
+    - Explicit `serviceTier` or `service_tier` params override `/fast` when both are set.
+    - On accounts without Priority Tier capacity, `service_tier: "auto"` may resolve to `standard`.
+
+    </Note>
+
+  </Accordion>
+
+  <Accordion title="Media understanding (image and PDF)">
+    The bundled Anthropic plugin registers image and PDF understanding. Nodmix
+    auto-resolves media capabilities from the configured Anthropic auth — no
+    additional config is needed.
+
+    | Property        | Value                 |
+    | --------------- | --------------------- |
+    | Default model   | `claude-opus-4-7`     |
+    | Supported input | Images, PDF documents |
+
+    When an image or PDF is attached to a conversation, Nodmix automatically
+    routes it through the Anthropic media understanding provider.
+
+  </Accordion>
+
+  <Accordion title="1M context window (beta)">
+    Anthropic's 1M context window is beta-gated. Enable it per model:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          models: {
+            "anthropic/claude-opus-4-6": {
+              params: { context1m: true },
+            },
+          },
+        },
+      },
+    }
+    ```
+
+    Nodmix maps this to `anthropic-beta: context-1m-2025-08-07` on requests.
+
+    `params.context1m: true` also applies to the Claude CLI backend
+    (`claude-cli/*`) for eligible Opus and Sonnet models, expanding the runtime
+    context window for those CLI sessions to match the direct-API behavior.
+
+    <Warning>
+    Requires long-context access on your Anthropic credential. Legacy token auth (`sk-ant-oat-*`) is rejected for 1M context requests — Nodmix logs a warning and falls back to the standard context window.
+    </Warning>
+
+  </Accordion>
+
+  <Accordion title="Claude Opus 4.7 1M context">
+    `anthropic/claude-opus-4.7` and its `claude-cli` variant have a 1M context
+    window by default — no `params.context1m: true` needed.
+  </Accordion>
+</AccordionGroup>
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="401 errors / token suddenly invalid">
+    Anthropic token auth expires and can be revoked. For new setups, use an Anthropic API key instead.
+  </Accordion>
+
+  <Accordion title='No API key found for provider "anthropic"'>
+    Anthropic auth is **per agent** — new agents do not inherit the main agent's keys. Re-run onboarding for that agent (or configure an API key on the gateway host), then verify with `nodmix models status`.
+  </Accordion>
+
+  <Accordion title='No credentials found for profile "anthropic:default"'>
+    Run `nodmix models status` to see which auth profile is active. Re-run onboarding, or configure an API key for that profile path.
+  </Accordion>
+
+  <Accordion title="No available auth profile (all in cooldown)">
+    Check `nodmix models status --json` for `auth.unusableProfiles`. Anthropic rate-limit cooldowns can be model-scoped, so a sibling Anthropic model may still be usable. Add another Anthropic profile or wait for cooldown.
+  </Accordion>
+</AccordionGroup>
+
+<Note>
+More help: [Troubleshooting](/help/troubleshooting) and [FAQ](/help/faq).
+</Note>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+  <Card title="CLI backends" href="/gateway/cli-backends" icon="terminal">
+    Claude CLI backend setup and runtime details.
+  </Card>
+  <Card title="Prompt caching" href="/reference/prompt-caching" icon="database">
+    How prompt caching works across providers.
+  </Card>
+  <Card title="OAuth and auth" href="/gateway/authentication" icon="key">
+    Auth details and credential reuse rules.
+  </Card>
+</CardGroup>

package/docs/providers/arcee.md

@@ -0,0 +1,144 @@
+---
+summary: "Arcee AI setup (auth + model selection)"
+title: "Arcee AI"
+read_when:
+  - You want to use Arcee AI with Nodmix
+  - You need the API key env var or CLI auth choice
+---
+
+[Arcee AI](https://arcee.ai) provides access to the Trinity family of mixture-of-experts models through an OpenAI-compatible API. All Trinity models are Apache 2.0 licensed.
+
+Arcee AI models can be accessed directly via the Arcee platform or through [OpenRouter](/providers/openrouter).
+
+| Property | Value                                                                                 |
+| -------- | ------------------------------------------------------------------------------------- |
+| Provider | `arcee`                                                                               |
+| Auth     | `ARCEEAI_API_KEY` (direct) or `OPENROUTER_API_KEY` (via OpenRouter)                   |
+| API      | OpenAI-compatible                                                                     |
+| Base URL | `https://api.arcee.ai/api/v1` (direct) or `https://openrouter.ai/api/v1` (OpenRouter) |
+
+## Getting started
+
+<Tabs>
+  <Tab title="Direct (Arcee platform)">
+    <Steps>
+      <Step title="Get an API key">
+        Create an API key at [Arcee AI](https://chat.arcee.ai/).
+      </Step>
+      <Step title="Run onboarding">
+        ```bash
+        nodmix onboard --auth-choice arceeai-api-key
+        ```
+      </Step>
+      <Step title="Set a default model">
+        ```json5
+        {
+          agents: {
+            defaults: {
+              model: { primary: "arcee/trinity-large-thinking" },
+            },
+          },
+        }
+        ```
+      </Step>
+    </Steps>
+  </Tab>
+
+  <Tab title="Via OpenRouter">
+    <Steps>
+      <Step title="Get an API key">
+        Create an API key at [OpenRouter](https://openrouter.ai/keys).
+      </Step>
+      <Step title="Run onboarding">
+        ```bash
+        nodmix onboard --auth-choice arceeai-openrouter
+        ```
+      </Step>
+      <Step title="Set a default model">
+        ```json5
+        {
+          agents: {
+            defaults: {
+              model: { primary: "arcee/trinity-large-thinking" },
+            },
+          },
+        }
+        ```
+
+        The same model refs work for both direct and OpenRouter setups (for example `arcee/trinity-large-thinking`).
+      </Step>
+    </Steps>
+
+  </Tab>
+</Tabs>
+
+## Non-interactive setup
+
+<Tabs>
+  <Tab title="Direct (Arcee platform)">
+    ```bash
+    nodmix onboard --non-interactive \
+      --mode local \
+      --auth-choice arceeai-api-key \
+      --arceeai-api-key "$ARCEEAI_API_KEY"
+    ```
+  </Tab>
+
+  <Tab title="Via OpenRouter">
+    ```bash
+    nodmix onboard --non-interactive \
+      --mode local \
+      --auth-choice arceeai-openrouter \
+      --openrouter-api-key "$OPENROUTER_API_KEY"
+    ```
+  </Tab>
+</Tabs>
+
+## Built-in catalog
+
+Nodmix currently ships this bundled Arcee catalog:
+
+| Model ref                      | Name                   | Input | Context | Cost (in/out per 1M) | Notes                                     |
+| ------------------------------ | ---------------------- | ----- | ------- | -------------------- | ----------------------------------------- |
+| `arcee/trinity-large-thinking` | Trinity Large Thinking | text  | 256K    | $0.25 / $0.90        | Default model; reasoning enabled          |
+| `arcee/trinity-large-preview`  | Trinity Large Preview  | text  | 128K    | $0.25 / $1.00        | General-purpose; 400B params, 13B active  |
+| `arcee/trinity-mini`           | Trinity Mini 26B       | text  | 128K    | $0.045 / $0.15       | Fast and cost-efficient; function calling |
+
+<Tip>
+The onboarding preset sets `arcee/trinity-large-thinking` as the default model.
+</Tip>
+
+## Supported features
+
+| Feature                                       | Supported                                    |
+| --------------------------------------------- | -------------------------------------------- |
+| Streaming                                     | Yes                                          |
+| Tool use / function calling                   | Yes (Trinity Mini, Trinity Large Preview)    |
+| Structured output (JSON mode and JSON schema) | Yes                                          |
+| Extended thinking                             | Yes (Trinity Large Thinking; tools disabled) |
+
+<AccordionGroup>
+  <Accordion title="Environment note">
+    If the Gateway runs as a daemon (launchd/systemd), make sure `ARCEEAI_API_KEY`
+    (or `OPENROUTER_API_KEY`) is available to that process (for example, in
+    `~/.nodmix/.env` or via `env.shellEnv`).
+  </Accordion>
+
+  <Accordion title="OpenRouter routing">
+    When using Arcee models via OpenRouter, the same `arcee/*` model refs apply.
+    Nodmix handles routing transparently based on your auth choice. See the
+    [OpenRouter provider docs](/providers/openrouter) for OpenRouter-specific
+    configuration details.
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="OpenRouter" href="/providers/openrouter" icon="shuffle">
+    Access Arcee models and many others through a single API key.
+  </Card>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+</CardGroup>

package/docs/providers/azure-speech.md

@@ -0,0 +1,119 @@
+---
+summary: "Azure AI Speech text-to-speech for Nodmix replies"
+read_when:
+  - You want Azure Speech synthesis for outbound replies
+  - You need native Ogg Opus voice-note output from Azure Speech
+title: "Azure Speech"
+---
+
+Azure Speech is an Azure AI Speech text-to-speech provider. In Nodmix it
+synthesizes outbound reply audio as MP3 by default, native Ogg/Opus for voice
+notes, and 8 kHz mulaw audio for telephony channels such as Voice Call.
+
+Nodmix uses the Azure Speech REST API directly with SSML and sends the
+provider-owned output format through `X-Microsoft-OutputFormat`.
+
+| Detail                  | Value                                                                                                          |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Website                 | [Azure AI Speech](https://azure.microsoft.com/products/ai-services/ai-speech)                                  |
+| Docs                    | [Speech REST text-to-speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech) |
+| Auth                    | `AZURE_SPEECH_KEY` plus `AZURE_SPEECH_REGION`                                                                  |
+| Default voice           | `en-US-JennyNeural`                                                                                            |
+| Default file output     | `audio-24khz-48kbitrate-mono-mp3`                                                                              |
+| Default voice-note file | `ogg-24khz-16bit-mono-opus`                                                                                    |
+
+## Getting started
+
+<Steps>
+  <Step title="Create an Azure Speech resource">
+    In the Azure portal, create a Speech resource. Copy **KEY 1** from
+    Resource Management > Keys and Endpoint, and copy the resource location
+    such as `eastus`.
+
+    ```
+    AZURE_SPEECH_KEY=<speech-resource-key>
+    AZURE_SPEECH_REGION=eastus
+    ```
+
+  </Step>
+  <Step title="Select Azure Speech in messages.tts">
+    ```json5
+    {
+      messages: {
+        tts: {
+          auto: "always",
+          provider: "azure-speech",
+          providers: {
+            "azure-speech": {
+              voice: "en-US-JennyNeural",
+              lang: "en-US",
+            },
+          },
+        },
+      },
+    }
+    ```
+  </Step>
+  <Step title="Send a message">
+    Send a reply through any connected channel. Nodmix synthesizes the audio
+    with Azure Speech and delivers MP3 for standard audio, or Ogg/Opus when
+    the channel expects a voice note.
+  </Step>
+</Steps>
+
+## Configuration options
+
+| Option                  | Path                                                        | Description                                                                                           |
+| ----------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `apiKey`                | `messages.tts.providers.azure-speech.apiKey`                | Azure Speech resource key. Falls back to `AZURE_SPEECH_KEY`, `AZURE_SPEECH_API_KEY`, or `SPEECH_KEY`. |
+| `region`                | `messages.tts.providers.azure-speech.region`                | Azure Speech resource region. Falls back to `AZURE_SPEECH_REGION` or `SPEECH_REGION`.                 |
+| `endpoint`              | `messages.tts.providers.azure-speech.endpoint`              | Optional Azure Speech endpoint/base URL override.                                                     |
+| `baseUrl`               | `messages.tts.providers.azure-speech.baseUrl`               | Optional Azure Speech base URL override.                                                              |
+| `voice`                 | `messages.tts.providers.azure-speech.voice`                 | Azure voice ShortName (default `en-US-JennyNeural`).                                                  |
+| `lang`                  | `messages.tts.providers.azure-speech.lang`                  | SSML language code (default `en-US`).                                                                 |
+| `outputFormat`          | `messages.tts.providers.azure-speech.outputFormat`          | Audio-file output format (default `audio-24khz-48kbitrate-mono-mp3`).                                 |
+| `voiceNoteOutputFormat` | `messages.tts.providers.azure-speech.voiceNoteOutputFormat` | Voice-note output format (default `ogg-24khz-16bit-mono-opus`).                                       |
+
+## Notes
+
+<AccordionGroup>
+  <Accordion title="Authentication">
+    Azure Speech uses a Speech resource key, not an Azure OpenAI key. The key
+    is sent as `Ocp-Apim-Subscription-Key`; Nodmix derives
+    `https://<region>.tts.speech.microsoft.com` from `region` unless you
+    provide `endpoint` or `baseUrl`.
+  </Accordion>
+  <Accordion title="Voice names">
+    Use the Azure Speech voice `ShortName` value, for example
+    `en-US-JennyNeural`. The bundled provider can list voices through the
+    same Speech resource and filters voices marked deprecated or retired.
+  </Accordion>
+  <Accordion title="Audio outputs">
+    Azure accepts output formats such as `audio-24khz-48kbitrate-mono-mp3`,
+    `ogg-24khz-16bit-mono-opus`, and `riff-24khz-16bit-mono-pcm`. Nodmix
+    requests Ogg/Opus for `voice-note` targets so channels can send native
+    voice bubbles without an extra MP3 conversion.
+  </Accordion>
+  <Accordion title="Alias">
+    `azure` is accepted as a provider alias for existing PRs and user config,
+    but new config should use `azure-speech` to avoid confusion with Azure
+    OpenAI model providers.
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Text-to-speech" href="/tools/tts" icon="waveform-lines">
+    TTS overview, providers, and `messages.tts` config.
+  </Card>
+  <Card title="Configuration" href="/gateway/configuration" icon="gear">
+    Full config reference including `messages.tts` settings.
+  </Card>
+  <Card title="Providers" href="/providers" icon="grid">
+    All bundled Nodmix providers.
+  </Card>
+  <Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
+    Common issues and debugging steps.
+  </Card>
+</CardGroup>