@quantumclaw/quantumclaw 2026.3.22

package/docs/providers/deepgram.md

@@ -0,0 +1,93 @@
+---
+summary: "Deepgram transcription for inbound voice notes"
+read_when:
+  - You want Deepgram speech-to-text for audio attachments
+  - You need a quick Deepgram config example
+title: "Deepgram"
+---
+
+# Deepgram (Audio Transcription)
+
+Deepgram is a speech-to-text API. In QuantumClaw it is used for **inbound audio/voice note
+transcription** via `tools.media.audio`.
+
+When enabled, QuantumClaw uploads the audio file to Deepgram and injects the transcript
+into the reply pipeline (`{{Transcript}}` + `[Audio]` block). This is **not streaming**;
+it uses the pre-recorded transcription endpoint.
+
+Website: [https://deepgram.com](https://deepgram.com)  
+Docs: [https://developers.deepgram.com](https://developers.deepgram.com)
+
+## Quick start
+
+1. Set your API key:
+
+```
+DEEPGRAM_API_KEY=dg_...
+```
+
+2. Enable the provider:
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        models: [{ provider: "deepgram", model: "nova-3" }],
+      },
+    },
+  },
+}
+```
+
+## Options
+
+- `model`: Deepgram model id (default: `nova-3`)
+- `language`: language hint (optional)
+- `tools.media.audio.providerOptions.deepgram.detect_language`: enable language detection (optional)
+- `tools.media.audio.providerOptions.deepgram.punctuate`: enable punctuation (optional)
+- `tools.media.audio.providerOptions.deepgram.smart_format`: enable smart formatting (optional)
+
+Example with language:
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        models: [{ provider: "deepgram", model: "nova-3", language: "en" }],
+      },
+    },
+  },
+}
+```
+
+Example with Deepgram options:
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        providerOptions: {
+          deepgram: {
+            detect_language: true,
+            punctuate: true,
+            smart_format: true,
+          },
+        },
+        models: [{ provider: "deepgram", model: "nova-3" }],
+      },
+    },
+  },
+}
+```
+
+## Notes
+
+- Authentication follows the standard provider auth order; `DEEPGRAM_API_KEY` is the simplest path.
+- Override endpoints or headers with `tools.media.audio.baseUrl` and `tools.media.audio.headers` when using a proxy.
+- Output follows the same audio rules as other providers (size caps, timeouts, transcript injection).

package/docs/providers/github-copilot.md

@@ -0,0 +1,72 @@
+---
+summary: "Sign in to GitHub Copilot from QuantumClaw using the device flow"
+read_when:
+  - You want to use GitHub Copilot as a model provider
+  - You need the `quantumclaw 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. QuantumClaw can use Copilot as a model
+provider in two different ways.
+
+## Two ways to use Copilot in QuantumClaw
+
+### 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 QuantumClaw 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. QuantumClaw 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
+quantumclaw 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
+quantumclaw models auth login-github-copilot --profile-id github-copilot:work
+quantumclaw models auth login-github-copilot --yes
+```
+
+## Set a default model
+
+```bash
+quantumclaw 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`).
+- The login stores a GitHub token in the auth profile store and exchanges it for a
+  Copilot API token when QuantumClaw runs.

package/docs/providers/glm.md

@@ -0,0 +1,43 @@
+---
+summary: "GLM model family overview + how to use it in QuantumClaw"
+read_when:
+  - You want GLM models in QuantumClaw
+  - 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 QuantumClaw, GLM
+models are accessed via the `zai` provider and model IDs like `zai/glm-5`.
+
+## CLI setup
+
+```bash
+# Coding Plan Global, recommended for Coding Plan users
+quantumclaw onboard --auth-choice zai-coding-global
+
+# Coding Plan CN (China region), recommended for Coding Plan users
+quantumclaw onboard --auth-choice zai-coding-cn
+
+# General API
+quantumclaw onboard --auth-choice zai-global
+
+# General API CN (China region)
+quantumclaw onboard --auth-choice zai-cn
+```
+
+## Config snippet
+
+```json5
+{
+  env: { ZAI_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "zai/glm-5" } } },
+}
+```
+
+## Notes
+
+- GLM versions and availability can change; check Z.AI's docs for the latest.
+- Example model IDs include `glm-5`, `glm-4.7`, and `glm-4.6`.
+- For provider details, see [/providers/zai](/providers/zai).

package/docs/providers/google.md

@@ -0,0 +1,78 @@
+---
+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 QuantumClaw
+  - 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
+quantumclaw onboard --auth-choice google-api-key
+```
+
+2. Set a default model:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "google/gemini-3.1-pro-preview" },
+    },
+  },
+}
+```
+
+## Non-interactive example
+
+```bash
+quantumclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice google-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.
+
+Environment variables:
+
+- `QUANTUMCLAW_GEMINI_OAUTH_CLIENT_ID`
+- `QUANTUMCLAW_GEMINI_OAUTH_CLIENT_SECRET`
+
+(Or the `GEMINI_CLI_*` variants.)
+
+## 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+) |
+
+## Environment note
+
+If the Gateway runs as a daemon (launchd/systemd), make sure `GEMINI_API_KEY`
+is available to that process (for example, in `~/.quantumclaw/.env` or via
+`env.shellEnv`).

package/docs/providers/groq.md

@@ -0,0 +1,96 @@
+---
+title: "Groq"
+summary: "Groq setup (auth + model selection)"
+read_when:
+  - You want to use Groq with QuantumClaw
+  - 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. QuantumClaw 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, QuantumClaw uses Groq's `whisper-large-v3-turbo`
+model to transcribe voice messages.
+
+```json5
+{
+  media: {
+    understanding: {
+      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 `~/.quantumclaw/.env` or via
+`env.shellEnv`).
+
+## Available models
+
+Groq's model catalog changes frequently. Run `quantumclaw 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)

package/docs/providers/huggingface.md

@@ -0,0 +1,209 @@
+---
+summary: "Hugging Face Inference setup (auth + model selection)"
+read_when:
+  - You want to use Hugging Face Inference with QuantumClaw
+  - You need the HF token env var or CLI auth choice
+title: "Hugging Face (Inference)"
+---
+
+# Hugging Face (Inference)
+
+[Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers) offer OpenAI-compatible chat completions through a single router API. You get access to many models (DeepSeek, Llama, and more) with one token. QuantumClaw uses the **OpenAI-compatible endpoint** (chat completions only); for text-to-image, embeddings, or speech use the [HF inference clients](https://huggingface.co/docs/api-inference/quicktour) directly.
+
+- Provider: `huggingface`
+- Auth: `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` (fine-grained token with **Make calls to Inference Providers**)
+- API: OpenAI-compatible (`https://router.huggingface.co/v1`)
+- Billing: Single HF token; [pricing](https://huggingface.co/docs/inference-providers/pricing) follows provider rates with a free tier.
+
+## Quick start
+
+1. Create a fine-grained token at [Hugging Face → Settings → Tokens](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained) with the **Make calls to Inference Providers** permission.
+2. Run onboarding and choose **Hugging Face** in the provider dropdown, then enter your API key when prompted:
+
+```bash
+quantumclaw onboard --auth-choice huggingface-api-key
+```
+
+3. In the **Default Hugging Face model** dropdown, pick the model you want (the list is loaded from the Inference API when you have a valid token; otherwise a built-in list is shown). Your choice is saved as the default model.
+4. You can also set or change the default model later in config:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
+    },
+  },
+}
+```
+
+## Non-interactive example
+
+```bash
+quantumclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice huggingface-api-key \
+  --huggingface-api-key "$HF_TOKEN"
+```
+
+This will set `huggingface/deepseek-ai/DeepSeek-R1` as the default model.
+
+## Environment note
+
+If the Gateway runs as a daemon (launchd/systemd), make sure `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN`
+is available to that process (for example, in `~/.quantumclaw/.env` or via
+`env.shellEnv`).
+
+## Model discovery and onboarding dropdown
+
+QuantumClaw discovers models by calling the **Inference endpoint directly**:
+
+```bash
+GET https://router.huggingface.co/v1/models
+```
+
+(Optional: send `Authorization: Bearer $HUGGINGFACE_HUB_TOKEN` or `$HF_TOKEN` for the full list; some endpoints return a subset without auth.) The response is OpenAI-style `{ "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }`.
+
+When you configure a Hugging Face API key (via onboarding, `HUGGINGFACE_HUB_TOKEN`, or `HF_TOKEN`), QuantumClaw uses this GET to discover available chat-completion models. During **interactive setup**, after you enter your token you see a **Default Hugging Face model** dropdown populated from that list (or the built-in catalog if the request fails). At runtime (e.g. Gateway startup), when a key is present, QuantumClaw again calls **GET** `https://router.huggingface.co/v1/models` to refresh the catalog. The list is merged with a built-in catalog (for metadata like context window and cost). If the request fails or no key is set, only the built-in catalog is used.
+
+## Model names and editable options
+
+- **Name from API:** The model display name is **hydrated from GET /v1/models** when the API returns `name`, `title`, or `display_name`; otherwise it is derived from the model id (e.g. `deepseek-ai/DeepSeek-R1` → “DeepSeek R1”).
+- **Override display name:** You can set a custom label per model in config so it appears the way you want in the CLI and UI:
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
+        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
+      },
+    },
+  },
+}
+```
+
+- **Provider / policy selection:** Append a suffix to the **model id** to choose how the router picks the backend:
+  - **`:fastest`** — highest throughput (router picks; provider choice is **locked** — no interactive backend picker).
+  - **`:cheapest`** — lowest cost per output token (router picks; provider choice is **locked**).
+  - **`:provider`** — force a specific backend (e.g. `:sambanova`, `:together`).
+
+  When you select **:cheapest** or **:fastest** (e.g. in the onboarding model dropdown), the provider is locked: the router decides by cost or speed and no optional “prefer specific backend” step is shown. You can add these as separate entries in `models.providers.huggingface.models` or set `model.primary` with the suffix. You can also set your default order in [Inference Provider settings](https://hf.co/settings/inference-providers) (no suffix = use that order).
+
+- **Config merge:** Existing entries in `models.providers.huggingface.models` (e.g. in `models.json`) are kept when config is merged. So any custom `name`, `alias`, or model options you set there are preserved.
+
+## Model IDs and configuration examples
+
+Model refs use the form `huggingface/<org>/<model>` (Hub-style IDs). The list below is from **GET** `https://router.huggingface.co/v1/models`; your catalog may include more.
+
+**Example IDs (from the inference endpoint):**
+
+| Model                  | Ref (prefix with `huggingface/`)    |
+| ---------------------- | ----------------------------------- |
+| DeepSeek R1            | `deepseek-ai/DeepSeek-R1`           |
+| DeepSeek V3.2          | `deepseek-ai/DeepSeek-V3.2`         |
+| Qwen3 8B               | `Qwen/Qwen3-8B`                     |
+| Qwen2.5 7B Instruct    | `Qwen/Qwen2.5-7B-Instruct`          |
+| Qwen3 32B              | `Qwen/Qwen3-32B`                    |
+| Llama 3.3 70B Instruct | `meta-llama/Llama-3.3-70B-Instruct` |
+| Llama 3.1 8B Instruct  | `meta-llama/Llama-3.1-8B-Instruct`  |
+| GPT-OSS 120B           | `openai/gpt-oss-120b`               |
+| GLM 4.7                | `zai-org/GLM-4.7`                   |
+| Kimi K2.5              | `moonshotai/Kimi-K2.5`              |
+
+You can append `:fastest`, `:cheapest`, or `:provider` (e.g. `:together`, `:sambanova`) to the model id. Set your default order in [Inference Provider settings](https://hf.co/settings/inference-providers); see [Inference Providers](https://huggingface.co/docs/inference-providers) and **GET** `https://router.huggingface.co/v1/models` for the full list.
+
+### Complete configuration examples
+
+**Primary DeepSeek R1 with Qwen fallback:**
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "huggingface/deepseek-ai/DeepSeek-R1",
+        fallbacks: ["huggingface/Qwen/Qwen3-8B"],
+      },
+      models: {
+        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
+        "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
+      },
+    },
+  },
+}
+```
+
+**Qwen as default, with :cheapest and :fastest variants:**
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "huggingface/Qwen/Qwen3-8B" },
+      models: {
+        "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
+        "huggingface/Qwen/Qwen3-8B:cheapest": { alias: "Qwen3 8B (cheapest)" },
+        "huggingface/Qwen/Qwen3-8B:fastest": { alias: "Qwen3 8B (fastest)" },
+      },
+    },
+  },
+}
+```
+
+**DeepSeek + Llama + GPT-OSS with aliases:**
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "huggingface/deepseek-ai/DeepSeek-V3.2",
+        fallbacks: [
+          "huggingface/meta-llama/Llama-3.3-70B-Instruct",
+          "huggingface/openai/gpt-oss-120b",
+        ],
+      },
+      models: {
+        "huggingface/deepseek-ai/DeepSeek-V3.2": { alias: "DeepSeek V3.2" },
+        "huggingface/meta-llama/Llama-3.3-70B-Instruct": { alias: "Llama 3.3 70B" },
+        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
+      },
+    },
+  },
+}
+```
+
+**Force a specific backend with :provider:**
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1:together" },
+      models: {
+        "huggingface/deepseek-ai/DeepSeek-R1:together": { alias: "DeepSeek R1 (Together)" },
+      },
+    },
+  },
+}
+```
+
+**Multiple Qwen and DeepSeek models with policy suffixes:**
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest" },
+      models: {
+        "huggingface/Qwen/Qwen2.5-7B-Instruct": { alias: "Qwen2.5 7B" },
+        "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest": { alias: "Qwen2.5 7B (cheap)" },
+        "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fast)" },
+        "huggingface/meta-llama/Llama-3.1-8B-Instruct": { alias: "Llama 3.1 8B" },
+      },
+    },
+  },
+}
+```

package/docs/providers/index.md

@@ -0,0 +1,69 @@
+---
+summary: "Model providers (LLMs) supported by QuantumClaw"
+read_when:
+  - You want to choose a model provider
+  - You need a quick overview of supported LLM backends
+title: "Provider Directory"
+---
+
+# Model Providers
+
+QuantumClaw can use many LLM providers. Pick a provider, authenticate, then set the
+default model as `provider/model`.
+
+Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/etc.)? See [Channels](/channels).
+
+## Quick start
+
+1. Authenticate with the provider (usually via `quantumclaw onboard`).
+2. Set the default model:
+
+```json5
+{
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
+}
+```
+
+## Provider docs
+
+- [Amazon Bedrock](/providers/bedrock)
+- [Anthropic (API + Claude Code CLI)](/providers/anthropic)
+- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
+- [GLM models](/providers/glm)
+- [Google (Gemini)](/providers/google)
+- [Groq (LPU inference)](/providers/groq)
+- [Hugging Face (Inference)](/providers/huggingface)
+- [Kilocode](/providers/kilocode)
+- [LiteLLM (unified gateway)](/providers/litellm)
+- [MiniMax](/providers/minimax)
+- [Mistral](/providers/mistral)
+- [Model Studio (Alibaba Cloud)](/providers/modelstudio)
+- [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
+- [NVIDIA](/providers/nvidia)
+- [Ollama (cloud + local models)](/providers/ollama)
+- [OpenAI (API + Codex)](/providers/openai)
+- [OpenCode (Zen + Go)](/providers/opencode)
+- [OpenRouter](/providers/openrouter)
+- [Perplexity (web search)](/providers/perplexity-provider)
+- [Qianfan](/providers/qianfan)
+- [Qwen (OAuth)](/providers/qwen)
+- [SGLang (local models)](/providers/sglang)
+- [Together AI](/providers/together)
+- [Vercel AI Gateway](/providers/vercel-ai-gateway)
+- [Venice (Venice AI, privacy-focused)](/providers/venice)
+- [vLLM (local models)](/providers/vllm)
+- [Volcengine (Doubao)](/providers/volcengine)
+- [xAI](/providers/xai)
+- [Xiaomi](/providers/xiaomi)
+- [Z.AI](/providers/zai)
+
+## Transcription providers
+
+- [Deepgram (audio transcription)](/providers/deepgram)
+
+## Community tools
+
+- [Claude Max API Proxy](/providers/claude-max-api-proxy) - Community proxy for Claude subscription credentials (verify Anthropic policy/terms before use)
+
+For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,
+see [Model providers](/concepts/model-providers).