durar-ai 2026.4.4

package/docs/providers/deepseek.md

@@ -0,0 +1,53 @@
+---
+summary: "DeepSeek setup (auth + model selection)"
+read_when:
+  - You want to use DeepSeek with Durar
+  - You need the API key env var or CLI auth choice
+---
+
+# DeepSeek
+
+[DeepSeek](https://www.deepseek.com) provides powerful AI models with an OpenAI-compatible API.
+
+- Provider: `deepseek`
+- Auth: `DEEPSEEK_API_KEY`
+- API: OpenAI-compatible
+- Base URL: `https://api.deepseek.com`
+
+## Quick start
+
+Set the API key (recommended: store it for the Gateway):
+
+```bash
+Durar onboard --auth-choice deepseek-api-key
+```
+
+This will prompt for your API key and set `deepseek/deepseek-chat` as the default model.
+
+## Non-interactive example
+
+```bash
+Durar onboard --non-interactive \
+  --mode local \
+  --auth-choice deepseek-api-key \
+  --deepseek-api-key "$DEEPSEEK_API_KEY" \
+  --skip-health \
+  --accept-risk
+```
+
+## Environment note
+
+If the Gateway runs as a daemon (launchd/systemd), make sure `DEEPSEEK_API_KEY`
+is available to that process (for example, in `~/.Durar/.env` or via
+`env.shellEnv`).
+
+## Built-in catalog
+
+| Model ref                    | Name              | Input | Context | Max output | Notes                                             |
+| ---------------------------- | ----------------- | ----- | ------- | ---------- | ------------------------------------------------- |
+| `deepseek/deepseek-chat`     | DeepSeek Chat     | text  | 131,072 | 8,192      | Default model; DeepSeek V3.2 non-thinking surface |
+| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text  | 131,072 | 65,536     | Reasoning-enabled V3.2 surface                    |
+
+Both bundled models currently advertise streaming usage compatibility in source.
+
+Get your API key at [platform.deepseek.com](https://platform.deepseek.com/api_keys).

package/docs/providers/fireworks.md

@@ -0,0 +1,69 @@
+---
+summary: "Fireworks setup (auth + model selection)"
+read_when:
+  - You want to use Fireworks with Durar
+  - You need the Fireworks API key env var or default model id
+---
+
+# Fireworks
+
+[Fireworks](https://fireworks.ai) exposes open-weight and routed models through an OpenAI-compatible API. Durar now includes a bundled Fireworks provider plugin.
+
+- Provider: `fireworks`
+- Auth: `FIREWORKS_API_KEY`
+- API: OpenAI-compatible chat/completions
+- Base URL: `https://api.fireworks.ai/inference/v1`
+- Default model: `fireworks/accounts/fireworks/routers/kimi-k2p5-turbo`
+
+## Quick start
+
+Set up Fireworks auth through onboarding:
+
+```bash
+Durar onboard --auth-choice fireworks-api-key
+```
+
+This stores your Fireworks key in Durar config and sets the Fire Pass starter model as the default.
+
+## Non-interactive example
+
+```bash
+Durar onboard --non-interactive \
+  --mode local \
+  --auth-choice fireworks-api-key \
+  --fireworks-api-key "$FIREWORKS_API_KEY" \
+  --skip-health \
+  --accept-risk
+```
+
+## Environment note
+
+If the Gateway runs outside your interactive shell, make sure `FIREWORKS_API_KEY`
+is available to that process too. A key sitting only in `~/.profile` will not
+help a launchd/systemd daemon unless that environment is imported there as well.
+
+## Built-in catalog
+
+| Model ref                                              | Name                        | Input      | Context | Max output | Notes                                      |
+| ------------------------------------------------------ | --------------------------- | ---------- | ------- | ---------- | ------------------------------------------ |
+| `fireworks/accounts/fireworks/routers/kimi-k2p5-turbo` | Kimi K2.5 Turbo (Fire Pass) | text,image | 256,000 | 256,000    | Default bundled starter model on Fireworks |
+
+## Custom Fireworks model ids
+
+Durar accepts dynamic Fireworks model ids too. Use the exact model or router id shown by Fireworks and prefix it with `fireworks/`.
+
+Example:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "fireworks/accounts/fireworks/routers/kimi-k2p5-turbo",
+      },
+    },
+  },
+}
+```
+
+If Fireworks publishes a newer model such as a fresh Qwen or Gemma release, you can switch to it directly by using its Fireworks model id without waiting for a bundled catalog update.

package/docs/providers/github-copilot.md

@@ -0,0 +1,80 @@
+---
+summary: "Sign in to GitHub Copilot from Durar using the device flow"
+read_when:
+  - You want to use GitHub Copilot as a model provider
+  - You need the `Durar models auth login-github-copilot` flow
+title: "GitHub Copilot"
+---
+
+# GitHub Copilot
+
+## What is GitHub Copilot?
+
+GitHub Copilot is GitHub's AI coding assistant. It provides access to Copilot
+models for your GitHub account and plan. Durar can use Copilot as a model
+provider in two different ways.
+
+## Two ways to use Copilot in Durar
+
+### 1) Built-in GitHub Copilot provider (`github-copilot`)
+
+Use the native device-login flow to obtain a GitHub token, then exchange it for
+Copilot API tokens when Durar runs. This is the **default** and simplest path
+because it does not require VS Code.
+
+### 2) Copilot Proxy plugin (`copilot-proxy`)
+
+Use the **Copilot Proxy** VS Code extension as a local bridge. Durar talks to
+the proxy’s `/v1` endpoint and uses the model list you configure there. 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.
+
+Use GitHub Copilot as a model provider (`github-copilot`). The login command runs
+the GitHub device flow, saves an auth profile, and updates your config to use that
+profile.
+
+## CLI setup
+
+```bash
+Durar models auth login-github-copilot
+```
+
+You'll be prompted to visit a URL and enter a one-time code. Keep the terminal
+open until it completes.
+
+### Optional flags
+
+```bash
+Durar models auth login-github-copilot --yes
+```
+
+To also apply the provider's recommended default model in one step, use the
+generic auth command instead:
+
+```bash
+Durar models auth login --provider github-copilot --method device --set-default
+```
+
+## Set a default model
+
+```bash
+Durar models set github-copilot/gpt-4o
+```
+
+### Config snippet
+
+```json5
+{
+  agents: { defaults: { model: { primary: "github-copilot/gpt-4o" } } },
+}
+```
+
+## Notes
+
+- Requires an interactive TTY; run it directly in a terminal.
+- Copilot model availability depends on your plan; if a model is rejected, try
+  another ID (for example `github-copilot/gpt-4.1`).
+- Claude model IDs use the Anthropic Messages transport automatically; GPT, o-series,
+  and Gemini models keep the OpenAI Responses transport.
+- The login stores a GitHub token in the auth profile store and exchanges it for a
+  Copilot API token when Durar runs.

package/docs/providers/glm.md

@@ -0,0 +1,68 @@
+---
+summary: "GLM model family overview + how to use it in Durar"
+read_when:
+  - You want GLM models in Durar
+  - You need the model naming convention and setup
+title: "GLM Models"
+---
+
+# GLM models
+
+GLM is a **model family** (not a company) available through the Z.AI platform. In Durar, GLM
+models are accessed via the `zai` provider and model IDs like `zai/glm-5`.
+
+## CLI setup
+
+```bash
+# Generic API-key setup with endpoint auto-detection
+Durar onboard --auth-choice zai-api-key
+
+# Coding Plan Global, recommended for Coding Plan users
+Durar onboard --auth-choice zai-coding-global
+
+# Coding Plan CN (China region), recommended for Coding Plan users
+Durar onboard --auth-choice zai-coding-cn
+
+# General API
+Durar onboard --auth-choice zai-global
+
+# General API CN (China region)
+Durar onboard --auth-choice zai-cn
+```
+
+## Config snippet
+
+```json5
+{
+  env: { ZAI_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "zai/glm-5" } } },
+}
+```
+
+`zai-api-key` lets Durar detect the matching Z.AI endpoint from the key and
+apply the correct base URL automatically. Use the explicit regional choices when
+you want to force a specific Coding Plan or general API surface.
+
+## Current bundled GLM models
+
+Durar currently seeds the bundled `zai` provider with these GLM refs:
+
+- `glm-5.1`
+- `glm-5`
+- `glm-5-turbo`
+- `glm-5v-turbo`
+- `glm-4.7`
+- `glm-4.7-flash`
+- `glm-4.7-flashx`
+- `glm-4.6`
+- `glm-4.6v`
+- `glm-4.5`
+- `glm-4.5-air`
+- `glm-4.5-flash`
+- `glm-4.5v`
+
+## Notes
+
+- GLM versions and availability can change; check Z.AI's docs for the latest.
+- Default bundled model ref is `zai/glm-5`.
+- For provider details, see [/providers/zai](/providers/zai).

package/docs/providers/google.md

@@ -0,0 +1,149 @@
+---
+title: "Google (Gemini)"
+summary: "Google Gemini setup (API key + OAuth, image generation, media understanding, web search)"
+read_when:
+  - You want to use Google Gemini models with Durar
+  - You need the API key or OAuth auth flow
+---
+
+# Google (Gemini)
+
+The Google plugin provides access to Gemini models through Google AI Studio, plus
+image generation, media understanding (image/audio/video), and web search via
+Gemini Grounding.
+
+- Provider: `google`
+- Auth: `GEMINI_API_KEY` or `GOOGLE_API_KEY`
+- API: Google Gemini API
+- Alternative provider: `google-gemini-cli` (OAuth)
+
+## Quick start
+
+1. Set the API key:
+
+```bash
+Durar onboard --auth-choice gemini-api-key
+```
+
+2. Set a default model:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "google/gemini-3.1-pro-preview" },
+    },
+  },
+}
+```
+
+## Non-interactive example
+
+```bash
+Durar onboard --non-interactive \
+  --mode local \
+  --auth-choice gemini-api-key \
+  --gemini-api-key "$GEMINI_API_KEY"
+```
+
+## OAuth (Gemini CLI)
+
+An alternative provider `google-gemini-cli` uses PKCE OAuth instead of an API
+key. This is an unofficial integration; some users report account
+restrictions. Use at your own risk.
+
+- Default model: `google-gemini-cli/gemini-3.1-pro-preview`
+- Alias: `gemini-cli`
+- Install prerequisite: local Gemini CLI available as `gemini`
+  - Homebrew: `brew install gemini-cli`
+  - npm: `npm install -g @google/gemini-cli`
+- Login:
+
+```bash
+Durar models auth login --provider google-gemini-cli --set-default
+```
+
+Environment variables:
+
+- `Durar_GEMINI_OAUTH_CLIENT_ID`
+- `Durar_GEMINI_OAUTH_CLIENT_SECRET`
+
+(Or the `GEMINI_CLI_*` variants.)
+
+If Gemini CLI OAuth requests fail after login, set
+`GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host and
+retry.
+
+If login fails before the browser flow starts, make sure the local `gemini`
+command is installed and on `PATH`. Durar supports both Homebrew installs
+and global npm installs, including common Windows/npm layouts.
+
+Gemini CLI JSON usage notes:
+
+- Reply text comes from the CLI JSON `response` field.
+- Usage falls back to `stats` when the CLI leaves `usage` empty.
+- `stats.cached` is normalized into Durar `cacheRead`.
+- If `stats.input` is missing, Durar derives input tokens from
+  `stats.input_tokens - stats.cached`.
+
+## Capabilities
+
+| Capability             | Supported         |
+| ---------------------- | ----------------- |
+| Chat completions       | Yes               |
+| Image generation       | Yes               |
+| Image understanding    | Yes               |
+| Audio transcription    | Yes               |
+| Video understanding    | Yes               |
+| Web search (Grounding) | Yes               |
+| Thinking/reasoning     | Yes (Gemini 3.1+) |
+
+## Direct Gemini cache reuse
+
+For direct Gemini API runs (`api: "google-generative-ai"`), Durar now
+passes a configured `cachedContent` handle through to Gemini requests.
+
+- Configure per-model or global params with either
+  `cachedContent` or legacy `cached_content`
+- If both are present, `cachedContent` wins
+- Example value: `cachedContents/prebuilt-context`
+- Gemini cache-hit usage is normalized into Durar `cacheRead` from
+  upstream `cachedContentTokenCount`
+
+Example:
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "google/gemini-2.5-pro": {
+          params: {
+            cachedContent: "cachedContents/prebuilt-context",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Image generation
+
+The bundled `google` image-generation provider defaults to
+`google/gemini-3.1-flash-image-preview`.
+
+- Also supports `google/gemini-3-pro-image-preview`
+- Generate: up to 4 images per request
+- Edit mode: enabled, up to 5 input images
+- Geometry controls: `size`, `aspectRatio`, and `resolution`
+
+The OAuth-only `google-gemini-cli` provider is a separate text-inference
+surface. Image generation, media understanding, and Gemini Grounding stay on
+the `google` provider id.
+
+## Environment note
+
+If the Gateway runs as a daemon (launchd/systemd), make sure `GEMINI_API_KEY`
+is available to that process (for example, in `~/.Durar/.env` or via
+`env.shellEnv`).

package/docs/providers/groq.md

@@ -0,0 +1,105 @@
+---
+title: "Groq"
+summary: "Groq setup (auth + model selection)"
+read_when:
+  - You want to use Groq with Durar
+  - You need the API key env var or CLI auth choice
+---
+
+# Groq
+
+[Groq](https://groq.com) provides ultra-fast inference on open-source models
+(Llama, Gemma, Mistral, and more) using custom LPU hardware. Durar connects
+to Groq through its OpenAI-compatible API.
+
+- Provider: `groq`
+- Auth: `GROQ_API_KEY`
+- API: OpenAI-compatible
+
+## Quick start
+
+1. Get an API key from [console.groq.com/keys](https://console.groq.com/keys).
+
+2. Set the API key:
+
+```bash
+export GROQ_API_KEY="gsk_..."
+```
+
+3. Set a default model:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "groq/llama-3.3-70b-versatile" },
+    },
+  },
+}
+```
+
+## Config file example
+
+```json5
+{
+  env: { GROQ_API_KEY: "gsk_..." },
+  agents: {
+    defaults: {
+      model: { primary: "groq/llama-3.3-70b-versatile" },
+    },
+  },
+}
+```
+
+## Audio transcription
+
+Groq also provides fast Whisper-based audio transcription. When configured as a
+media-understanding provider, Durar uses Groq's `whisper-large-v3-turbo`
+model to transcribe voice messages through the shared `tools.media.audio`
+surface.
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        models: [{ provider: "groq" }],
+      },
+    },
+  },
+}
+```
+
+## Environment note
+
+If the Gateway runs as a daemon (launchd/systemd), make sure `GROQ_API_KEY` is
+available to that process (for example, in `~/.Durar/.env` or via
+`env.shellEnv`).
+
+## Audio notes
+
+- Shared config path: `tools.media.audio`
+- Default Groq audio base URL: `https://api.groq.com/openai/v1`
+- Default Groq audio model: `whisper-large-v3-turbo`
+- Groq audio transcription uses the OpenAI-compatible `/audio/transcriptions`
+  path
+
+## Available models
+
+Groq's model catalog changes frequently. Run `Durar models list | grep groq`
+to see currently available models, or check
+[console.groq.com/docs/models](https://console.groq.com/docs/models).
+
+Popular choices include:
+
+- **Llama 3.3 70B Versatile** - general-purpose, large context
+- **Llama 3.1 8B Instant** - fast, lightweight
+- **Gemma 2 9B** - compact, efficient
+- **Mixtral 8x7B** - MoE architecture, strong reasoning
+
+## Links
+
+- [Groq Console](https://console.groq.com)
+- [API Documentation](https://console.groq.com/docs)
+- [Model List](https://console.groq.com/docs/models)
+- [Pricing](https://groq.com/pricing)