nodmix 2026.5.25

package/docs/providers/fal.md

@@ -0,0 +1,204 @@
+---
+summary: "fal image, video, and music generation setup in Nodmix"
+title: "Fal"
+read_when:
+  - You want to use fal image generation in Nodmix
+  - You need the FAL_KEY auth flow
+  - You want fal defaults for image_generate, video_generate, or music_generate
+---
+
+Nodmix ships a bundled `fal` provider for hosted image, video, and music
+generation.
+
+| Property | Value                                                         |
+| -------- | ------------------------------------------------------------- |
+| Provider | `fal`                                                         |
+| Auth     | `FAL_KEY` (canonical; `FAL_API_KEY` also works as a fallback) |
+| API      | fal model endpoints                                           |
+
+## Getting started
+
+<Steps>
+  <Step title="Set the API key">
+    ```bash
+    nodmix onboard --auth-choice fal-api-key
+    ```
+  </Step>
+  <Step title="Set a default image model">
+    ```json5
+    {
+      agents: {
+        defaults: {
+          imageGenerationModel: {
+            primary: "fal/fal-ai/flux/dev",
+          },
+        },
+      },
+    }
+    ```
+  </Step>
+</Steps>
+
+## Image generation
+
+The bundled `fal` image-generation provider defaults to
+`fal/fal-ai/flux/dev`.
+
+| Capability     | Value                                                       |
+| -------------- | ----------------------------------------------------------- |
+| Max images     | 4 per request                                               |
+| Edit mode      | Flux: 1 reference image; GPT Image 2: 10; Nano Banana 2: 14 |
+| Size overrides | Supported                                                   |
+| Aspect ratio   | Supported for generate and GPT Image 2/Nano Banana 2 edit   |
+| Resolution     | Supported                                                   |
+| Output format  | `png` or `jpeg`                                             |
+
+<Warning>
+Flux image-to-image requests do **not** support `aspectRatio` overrides. GPT
+Image 2 and Nano Banana 2 edit requests use fal's `/edit` endpoint and accept
+aspect-ratio hints.
+</Warning>
+
+Use `outputFormat: "png"` when you want PNG output. fal does not declare an
+explicit transparent-background control in Nodmix, so `background:
+"transparent"` is reported as an ignored override for fal models.
+
+To use fal as the default image provider:
+
+```json5
+{
+  agents: {
+    defaults: {
+      imageGenerationModel: {
+        primary: "fal/fal-ai/flux/dev",
+      },
+    },
+  },
+}
+```
+
+## Video generation
+
+The bundled `fal` video-generation provider defaults to
+`fal/fal-ai/minimax/video-01-live`.
+
+| Capability | Value                                                              |
+| ---------- | ------------------------------------------------------------------ |
+| Modes      | Text-to-video, single-image reference, Seedance reference-to-video |
+| Runtime    | Queue-backed submit/status/result flow for long-running jobs       |
+
+<AccordionGroup>
+  <Accordion title="Available video models">
+    **HeyGen video-agent:**
+
+    - `fal/fal-ai/heygen/v2/video-agent`
+
+    **Seedance 2.0:**
+
+    - `fal/bytedance/seedance-2.0/fast/text-to-video`
+    - `fal/bytedance/seedance-2.0/fast/image-to-video`
+    - `fal/bytedance/seedance-2.0/fast/reference-to-video`
+    - `fal/bytedance/seedance-2.0/text-to-video`
+    - `fal/bytedance/seedance-2.0/image-to-video`
+    - `fal/bytedance/seedance-2.0/reference-to-video`
+
+  </Accordion>
+
+  <Accordion title="Seedance 2.0 config example">
+    ```json5
+    {
+      agents: {
+        defaults: {
+          videoGenerationModel: {
+            primary: "fal/bytedance/seedance-2.0/fast/text-to-video",
+          },
+        },
+      },
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Seedance 2.0 reference-to-video config example">
+    ```json5
+    {
+      agents: {
+        defaults: {
+          videoGenerationModel: {
+            primary: "fal/bytedance/seedance-2.0/fast/reference-to-video",
+          },
+        },
+      },
+    }
+    ```
+
+    Reference-to-video accepts up to 9 images, 3 videos, and 3 audio references
+    through the shared `video_generate` `images`, `videos`, and `audioRefs`
+    parameters, with at most 12 total reference files.
+
+  </Accordion>
+
+  <Accordion title="HeyGen video-agent config example">
+    ```json5
+    {
+      agents: {
+        defaults: {
+          videoGenerationModel: {
+            primary: "fal/fal-ai/heygen/v2/video-agent",
+          },
+        },
+      },
+    }
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Music generation
+
+The bundled `fal` plugin also registers a music-generation provider for the
+shared `music_generate` tool.
+
+| Capability    | Value                                                                                                  |
+| ------------- | ------------------------------------------------------------------------------------------------------ |
+| Default model | `fal/fal-ai/minimax-music/v2.6`                                                                        |
+| Models        | `fal-ai/minimax-music/v2.6`, `fal-ai/ace-step/prompt-to-audio`, `fal-ai/stable-audio-25/text-to-audio` |
+| Runtime       | Synchronous request plus generated audio download                                                      |
+
+Use fal as the default music provider:
+
+```json5
+{
+  agents: {
+    defaults: {
+      musicGenerationModel: {
+        primary: "fal/fal-ai/minimax-music/v2.6",
+      },
+    },
+  },
+}
+```
+
+`fal-ai/minimax-music/v2.6` supports explicit lyrics and instrumental mode.
+ACE-Step and Stable Audio are prompt-to-audio endpoints; choose them with the
+`model` override when you want those model families.
+
+<Tip>
+Use `nodmix models list --provider fal` to see the full list of available fal
+models, including any recently added entries.
+</Tip>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Image generation" href="/tools/image-generation" icon="image">
+    Shared image tool parameters and provider selection.
+  </Card>
+  <Card title="Video generation" href="/tools/video-generation" icon="video">
+    Shared video tool parameters and provider selection.
+  </Card>
+  <Card title="Music generation" href="/tools/music-generation" icon="music">
+    Shared music tool parameters and provider selection.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/config-agents#agent-defaults" icon="gear">
+    Agent defaults including image, video, and music model selection.
+  </Card>
+</CardGroup>

package/docs/providers/fireworks.md

@@ -0,0 +1,144 @@
+---
+summary: "Fireworks setup (auth + model selection)"
+title: "Fireworks"
+read_when:
+  - You want to use Fireworks with Nodmix
+  - You need the Fireworks API key env var or default model id
+  - You are debugging Kimi thinking-off behavior on Fireworks
+---
+
+[Fireworks](https://fireworks.ai) exposes open-weight and routed models through an OpenAI-compatible API. Nodmix includes a bundled Fireworks provider plugin that ships with two pre-cataloged Kimi models and accepts any Fireworks model or router id at runtime.
+
+| Property        | Value                                                  |
+| --------------- | ------------------------------------------------------ |
+| Provider id     | `fireworks` (alias: `fireworks-ai`)                    |
+| Plugin          | bundled, `enabledByDefault: true`                      |
+| Auth env var    | `FIREWORKS_API_KEY`                                    |
+| Onboarding flag | `--auth-choice fireworks-api-key`                      |
+| Direct CLI flag | `--fireworks-api-key <key>`                            |
+| API             | OpenAI-compatible (`openai-completions`)               |
+| Base URL        | `https://api.fireworks.ai/inference/v1`                |
+| Default model   | `fireworks/accounts/fireworks/routers/kimi-k2p5-turbo` |
+| Default alias   | `Kimi K2.5 Turbo`                                      |
+
+## Getting started
+
+<Steps>
+  <Step title="Set the Fireworks API key">
+    <CodeGroup>
+
+```bash Onboarding
+nodmix onboard --auth-choice fireworks-api-key
+```
+
+```bash Direct flag
+nodmix onboard --non-interactive \
+  --auth-choice fireworks-api-key \
+  --fireworks-api-key "$FIREWORKS_API_KEY"
+```
+
+```bash Env only
+export FIREWORKS_API_KEY=fw-...
+```
+
+    </CodeGroup>
+
+    Onboarding stores the key against the `fireworks` provider in your auth profiles and sets the **Fire Pass** Kimi K2.5 Turbo router as the default model.
+
+  </Step>
+  <Step title="Verify the model is available">
+    ```bash
+    nodmix models list --provider fireworks
+    ```
+
+    The list should include `Kimi K2.6` and `Kimi K2.5 Turbo (Fire Pass)`. If `FIREWORKS_API_KEY` is unresolved, `nodmix models status --json` reports the missing credential under `auth.unusableProfiles`.
+
+  </Step>
+</Steps>
+
+## Non-interactive setup
+
+For scripted or CI installs, pass everything on the command line:
+
+```bash
+nodmix onboard --non-interactive \
+  --mode local \
+  --auth-choice fireworks-api-key \
+  --fireworks-api-key "$FIREWORKS_API_KEY" \
+  --skip-health \
+  --accept-risk
+```
+
+## Built-in catalog
+
+| Model ref                                              | Name                        | Input        | Context | Max output | Thinking             |
+| ------------------------------------------------------ | --------------------------- | ------------ | ------- | ---------- | -------------------- |
+| `fireworks/accounts/fireworks/models/kimi-k2p6`        | Kimi K2.6                   | text + image | 262,144 | 262,144    | Forced off           |
+| `fireworks/accounts/fireworks/routers/kimi-k2p5-turbo` | Kimi K2.5 Turbo (Fire Pass) | text + image | 256,000 | 256,000    | Forced off (default) |
+
+<Note>
+  Nodmix pins all Fireworks Kimi models to `thinking: off` because Fireworks rejects Kimi thinking parameters in production. Routing the same model through [Moonshot](/providers/moonshot) directly preserves Kimi reasoning output. See [thinking modes](/tools/thinking) for switching between providers.
+</Note>
+
+## Custom Fireworks model ids
+
+Nodmix accepts any Fireworks model or router id at runtime. Use the exact id shown by Fireworks and prefix it with `fireworks/`. Dynamic resolution clones the Fire Pass template (text + image input, OpenAI-compatible API, default cost zero) and disables thinking automatically when the id matches the Kimi pattern.
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "fireworks/accounts/fireworks/models/<your-model-id>",
+      },
+    },
+  },
+}
+```
+
+<AccordionGroup>
+  <Accordion title="How model id prefixing works">
+    Every Fireworks model ref in Nodmix starts with `fireworks/` followed by the exact id or router path from the Fireworks platform. For example:
+
+    - Router model: `fireworks/accounts/fireworks/routers/kimi-k2p5-turbo`
+    - Direct model: `fireworks/accounts/fireworks/models/<model-name>`
+
+    Nodmix strips the `fireworks/` prefix when constructing the API request and sends the remaining path to the Fireworks endpoint as the OpenAI-compatible `model` field.
+
+  </Accordion>
+
+  <Accordion title="Why thinking is forced off for Kimi">
+    Fireworks K2.6 returns a 400 if the request carries `reasoning_*` parameters even though Kimi supports thinking through Moonshot's own API. The bundled policy (`extensions/fireworks/thinking-policy.ts`) advertises only the `off` thinking level for Kimi model ids, so manual `/think` switches and provider-policy surfaces stay aligned with the runtime contract.
+
+    To use Kimi reasoning end-to-end, configure the [Moonshot provider](/providers/moonshot) and route the same model through it.
+
+  </Accordion>
+
+  <Accordion title="Environment availability for the daemon">
+    If the Gateway runs as a managed service (launchd, systemd, Docker), the Fireworks key must be visible to that process — not just to your interactive shell.
+
+    <Warning>
+      A key exported only in an interactive shell will not help a launchd or systemd daemon unless that environment is imported there too. Set the key in `~/.nodmix/.env` or via `env.shellEnv` to make it readable from the gateway process.
+    </Warning>
+
+    On macOS, `nodmix gateway install` already wires `~/.nodmix/.env` into the LaunchAgent environment file. Re-run install (or `nodmix doctor --fix`) after rotating the key.
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model providers" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+  <Card title="Thinking modes" href="/tools/thinking" icon="brain">
+    `/think` levels, provider policies, and routing reasoning-capable models.
+  </Card>
+  <Card title="Moonshot" href="/providers/moonshot" icon="moon">
+    Run Kimi with native thinking output through Moonshot's own API.
+  </Card>
+  <Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
+    General troubleshooting and FAQ.
+  </Card>
+</CardGroup>

package/docs/providers/github-copilot.md

@@ -0,0 +1,225 @@
+---
+summary: "Sign in to GitHub Copilot from Nodmix using the device flow or non-interactive token import"
+read_when:
+  - You want to use GitHub Copilot as a model provider
+  - You need the `nodmix models auth login-github-copilot` flow
+title: "GitHub Copilot"
+---
+
+GitHub Copilot is GitHub's AI coding assistant. It provides access to Copilot
+models for your GitHub account and plan. Nodmix can use Copilot as a model
+provider in two different ways.
+
+## Two ways to use Copilot in Nodmix
+
+<Tabs>
+  <Tab title="Built-in provider (github-copilot)">
+    Use the native device-login flow to obtain a GitHub token, then exchange it for
+    Copilot API tokens when Nodmix runs. This is the **default** and simplest path
+    because it does not require VS Code.
+
+    <Steps>
+      <Step title="Run the login command">
+        ```bash
+        nodmix models auth login-github-copilot
+        ```
+
+        You will be prompted to visit a URL and enter a one-time code. Keep the
+        terminal open until it completes.
+      </Step>
+      <Step title="Set a default model">
+        ```bash
+        nodmix models set github-copilot/claude-opus-4.7
+        ```
+
+        Or in config:
+
+        ```json5
+        {
+          agents: {
+            defaults: { model: { primary: "github-copilot/claude-opus-4.7" } },
+          },
+        }
+        ```
+      </Step>
+    </Steps>
+
+  </Tab>
+
+  <Tab title="Copilot Proxy plugin (copilot-proxy)">
+    Use the **Copilot Proxy** VS Code extension as a local bridge. Nodmix talks to
+    the proxy's `/v1` endpoint and uses the model list you configure there.
+
+    <Note>
+    Choose this when you already run Copilot Proxy in VS Code or need to route
+    through it. You must enable the plugin and keep the VS Code extension running.
+    </Note>
+
+  </Tab>
+</Tabs>
+
+## Optional flags
+
+| Flag            | Description                                         |
+| --------------- | --------------------------------------------------- |
+| `--yes`         | Skip the confirmation prompt                        |
+| `--set-default` | Also apply the provider's recommended default model |
+
+```bash
+# Skip confirmation
+nodmix models auth login-github-copilot --yes
+
+# Login and set the default model in one step
+nodmix models auth login --provider github-copilot --method device --set-default
+```
+
+## Non-interactive onboarding
+
+If you already have a GitHub OAuth access token for Copilot, import it during
+headless setup with `nodmix onboard --non-interactive`:
+
+```bash
+nodmix onboard --non-interactive --accept-risk \
+  --auth-choice github-copilot \
+  --github-copilot-token "$COPILOT_GITHUB_TOKEN" \
+  --skip-channels --skip-health
+```
+
+You can also omit `--auth-choice`; passing `--github-copilot-token` infers the
+GitHub Copilot provider auth choice. If the flag is omitted, onboarding falls
+back to `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, then `GITHUB_TOKEN`. Use
+`--secret-input-mode ref` with `COPILOT_GITHUB_TOKEN` set to store an env-backed
+`tokenRef` instead of plaintext in `auth-profiles.json`.
+
+<AccordionGroup>
+  <Accordion title="Interactive TTY required">
+    The device-login flow requires an interactive TTY. Run it directly in a
+    terminal, not in a non-interactive script or CI pipeline.
+  </Accordion>
+
+  <Accordion title="Model availability depends on your plan">
+    Copilot model availability depends on your GitHub plan. If a model is
+    rejected, try another ID (for example `github-copilot/gpt-4.1`).
+  </Accordion>
+
+  <Accordion title="Live catalog refresh from the Copilot API">
+    Once the device-login (or env-var) auth path has resolved a GitHub token,
+    Nodmix refreshes the model catalog on demand from `${baseUrl}/models`
+    (the same endpoint VS Code Copilot uses) so the runtime tracks
+    per-account entitlement and accurate context windows without manifest
+    churn. Newly published Copilot models become visible without an Nodmix
+    upgrade, and context windows reflect the real per-model limits
+    (e.g. 400k for the gpt-5.x series, 1M for the internal
+    `claude-opus-*-1m` variants).
+
+    The bundled static catalog stays as the visible fallback when discovery
+    is disabled, the user has no GitHub auth profile, the token-exchange
+    fails, or the `/models` HTTPS call errors. To opt out and rely entirely
+    on the static manifest catalog (offline / air-gapped scenarios):
+
+    ```json5
+    {
+      plugins: {
+        entries: {
+          "github-copilot": {
+            config: { discovery: { enabled: false } },
+          },
+        },
+      },
+    }
+    ```
+
+  </Accordion>
+
+  <Accordion title="Transport selection">
+    Claude model IDs use the Anthropic Messages transport automatically. GPT,
+    o-series, and Gemini models keep the OpenAI Responses transport. Nodmix
+    selects the correct transport based on the model ref.
+  </Accordion>
+
+  <Accordion title="Request compatibility">
+    Nodmix sends Copilot IDE-style request headers on Copilot transports,
+    including built-in compaction, tool-result, and image follow-up turns. It
+    does not enable provider-level Responses continuation for Copilot unless
+    that behavior has been verified against Copilot's API.
+  </Accordion>
+
+  <Accordion title="Environment variable resolution order">
+    Nodmix resolves Copilot auth from environment variables in the following
+    priority order:
+
+    | Priority | Variable              | Notes                            |
+    | -------- | --------------------- | -------------------------------- |
+    | 1        | `COPILOT_GITHUB_TOKEN` | Highest priority, Copilot-specific |
+    | 2        | `GH_TOKEN`            | GitHub CLI token (fallback)      |
+    | 3        | `GITHUB_TOKEN`        | Standard GitHub token (lowest)   |
+
+    When multiple variables are set, Nodmix uses the highest-priority one.
+    The device-login flow (`nodmix models auth login-github-copilot`) stores
+    its token in the auth profile store and takes precedence over all environment
+    variables.
+
+  </Accordion>
+
+  <Accordion title="Token storage">
+    The login stores a GitHub token in the auth profile store and exchanges it
+    for a Copilot API token when Nodmix runs. You do not need to manage the
+    token manually.
+  </Accordion>
+</AccordionGroup>
+
+<Warning>
+The device-login command requires an interactive TTY. Use non-interactive
+onboarding when you need headless setup.
+</Warning>
+
+## Memory search embeddings
+
+GitHub Copilot can also serve as an embedding provider for
+[memory search](/concepts/memory-search). If you have a Copilot subscription and
+have logged in, Nodmix can use it for embeddings without a separate API key.
+
+### Auto-detection
+
+When `memorySearch.provider` is `"auto"` (the default), GitHub Copilot is tried
+at priority 15 -- after local embeddings but before OpenAI and other paid
+providers. If a GitHub token is available, Nodmix discovers available
+embedding models from the Copilot API and picks the best one automatically.
+
+### Explicit config
+
+```json5
+{
+  agents: {
+    defaults: {
+      memorySearch: {
+        provider: "github-copilot",
+        // Optional: override the auto-discovered model
+        model: "text-embedding-3-small",
+      },
+    },
+  },
+}
+```
+
+### How it works
+
+1. Nodmix resolves your GitHub token (from env vars or auth profile).
+2. Exchanges it for a short-lived Copilot API token.
+3. Queries the Copilot `/models` endpoint to discover available embedding models.
+4. Picks the best model (prefers `text-embedding-3-small`).
+5. Sends embedding requests to the Copilot `/embeddings` endpoint.
+
+Model availability depends on your GitHub plan. If no embedding models are
+available, Nodmix skips Copilot and tries the next provider.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+  <Card title="OAuth and auth" href="/gateway/authentication" icon="key">
+    Auth details and credential reuse rules.
+  </Card>
+</CardGroup>