@quantumclaw/quantumclaw 2026.3.22

package/docs/providers/xai.md

@@ -0,0 +1,60 @@
+---
+summary: "Use xAI Grok models in QuantumClaw"
+read_when:
+  - You want to use Grok models in QuantumClaw
+  - You are configuring xAI auth or model ids
+title: "xAI"
+---
+
+# xAI
+
+QuantumClaw ships a bundled `xai` provider plugin for Grok models.
+
+## Setup
+
+1. Create an API key in the xAI console.
+2. Set `XAI_API_KEY`, or run:
+
+```bash
+quantumclaw onboard --auth-choice xai-api-key
+```
+
+3. Pick a model such as:
+
+```json5
+{
+  agents: { defaults: { model: { primary: "xai/grok-4" } } },
+}
+```
+
+## Current bundled model catalog
+
+QuantumClaw now includes these xAI model families out of the box:
+
+- `grok-4`, `grok-4-0709`
+- `grok-4-fast-reasoning`, `grok-4-fast-non-reasoning`
+- `grok-4-1-fast-reasoning`, `grok-4-1-fast-non-reasoning`
+- `grok-4.20-reasoning`, `grok-4.20-non-reasoning`
+- `grok-code-fast-1`
+
+The plugin also forward-resolves newer `grok-4*` and `grok-code-fast*` ids when
+they follow the same API shape.
+
+## Web search
+
+The bundled `grok` web-search provider uses `XAI_API_KEY` too:
+
+```bash
+quantumclaw config set tools.web.search.provider grok
+```
+
+## Known limits
+
+- Auth is API-key only today. There is no xAI OAuth/device-code flow in QuantumClaw yet.
+- `grok-4.20-multi-agent-experimental-beta-0304` is not supported on the normal xAI provider path because it requires a different upstream API surface than the standard QuantumClaw xAI transport.
+- Native xAI server-side tools such as `x_search` and `code_execution` are not yet first-class model-provider features in the bundled plugin.
+
+## Notes
+
+- QuantumClaw applies xAI-specific tool-schema and tool-call compatibility fixes automatically on the shared runner path.
+- For the broader provider overview, see [Model providers](/providers/index).

package/docs/providers/xiaomi.md

@@ -0,0 +1,86 @@
+---
+summary: "Use Xiaomi MiMo models with QuantumClaw"
+read_when:
+  - You want Xiaomi MiMo models in QuantumClaw
+  - You need XIAOMI_API_KEY setup
+title: "Xiaomi MiMo"
+---
+
+# Xiaomi MiMo
+
+Xiaomi MiMo is the API platform for **MiMo** models. QuantumClaw uses the Xiaomi
+OpenAI-compatible endpoint with API-key authentication. Create your API key in the
+[Xiaomi MiMo console](https://platform.xiaomimimo.com/#/console/api-keys), then configure the
+bundled `xiaomi` provider with that key.
+
+## Model overview
+
+- **mimo-v2-flash**: default text model, 262144-token context window
+- **mimo-v2-pro**: reasoning text model, 1048576-token context window
+- **mimo-v2-omni**: reasoning multimodal model with text and image input, 262144-token context window
+- Base URL: `https://api.xiaomimimo.com/v1`
+- API: `openai-completions`
+- Authorization: `Bearer $XIAOMI_API_KEY`
+
+## CLI setup
+
+```bash
+quantumclaw onboard --auth-choice xiaomi-api-key
+# or non-interactive
+quantumclaw onboard --auth-choice xiaomi-api-key --xiaomi-api-key "$XIAOMI_API_KEY"
+```
+
+## Config snippet
+
+```json5
+{
+  env: { XIAOMI_API_KEY: "your-key" },
+  agents: { defaults: { model: { primary: "xiaomi/mimo-v2-flash" } } },
+  models: {
+    mode: "merge",
+    providers: {
+      xiaomi: {
+        baseUrl: "https://api.xiaomimimo.com/v1",
+        api: "openai-completions",
+        apiKey: "XIAOMI_API_KEY",
+        models: [
+          {
+            id: "mimo-v2-flash",
+            name: "Xiaomi MiMo V2 Flash",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 262144,
+            maxTokens: 8192,
+          },
+          {
+            id: "mimo-v2-pro",
+            name: "Xiaomi MiMo V2 Pro",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 1048576,
+            maxTokens: 32000,
+          },
+          {
+            id: "mimo-v2-omni",
+            name: "Xiaomi MiMo V2 Omni",
+            reasoning: true,
+            input: ["text", "image"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 262144,
+            maxTokens: 32000,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+## Notes
+
+- Default model ref: `xiaomi/mimo-v2-flash`.
+- Additional built-in models: `xiaomi/mimo-v2-pro`, `xiaomi/mimo-v2-omni`.
+- The provider is injected automatically when `XIAOMI_API_KEY` is set (or an auth profile exists).
+- See [/concepts/model-providers](/concepts/model-providers) for provider rules.

package/docs/providers/zai.md

@@ -0,0 +1,46 @@
+---
+summary: "Use Z.AI (GLM models) with QuantumClaw"
+read_when:
+  - You want Z.AI / GLM models in QuantumClaw
+  - You need a simple ZAI_API_KEY setup
+title: "Z.AI"
+---
+
+# Z.AI
+
+Z.AI is the API platform for **GLM** models. It provides REST APIs for GLM and uses API keys
+for authentication. Create your API key in the Z.AI console. QuantumClaw uses the `zai` provider
+with a Z.AI API key.
+
+## 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 models are available as `zai/<model>` (example: `zai/glm-5`).
+- `tool_stream` is enabled by default for Z.AI tool-call streaming. Set
+  `agents.defaults.models["zai/<model>"].params.tool_stream` to `false` to disable it.
+- See [/providers/glm](/providers/glm) for the model family overview.
+- Z.AI uses Bearer auth with your API key.

package/docs/reference/AGENTS.default.md

@@ -0,0 +1,126 @@
+---
+title: "Default AGENTS.md"
+summary: "Default QuantumClaw agent instructions and skills roster for the personal assistant setup"
+read_when:
+  - Starting a new QuantumClaw agent session
+  - Enabling or auditing default skills
+---
+
+# AGENTS.md - QuantumClaw Personal Assistant (default)
+
+## First run (recommended)
+
+QuantumClaw uses a dedicated workspace directory for the agent. Default: `~/.quantumclaw/workspace` (configurable via `agents.defaults.workspace`).
+
+1. Create the workspace (if it doesn’t already exist):
+
+```bash
+mkdir -p ~/.quantumclaw/workspace
+```
+
+2. Copy the default workspace templates into the workspace:
+
+```bash
+cp docs/reference/templates/AGENTS.md ~/.quantumclaw/workspace/AGENTS.md
+cp docs/reference/templates/SOUL.md ~/.quantumclaw/workspace/SOUL.md
+cp docs/reference/templates/TOOLS.md ~/.quantumclaw/workspace/TOOLS.md
+```
+
+3. Optional: if you want the personal assistant skill roster, replace AGENTS.md with this file:
+
+```bash
+cp docs/reference/AGENTS.default.md ~/.quantumclaw/workspace/AGENTS.md
+```
+
+4. Optional: choose a different workspace by setting `agents.defaults.workspace` (supports `~`):
+
+```json5
+{
+  agents: { defaults: { workspace: "~/.quantumclaw/workspace" } },
+}
+```
+
+## Safety defaults
+
+- Don’t dump directories or secrets into chat.
+- Don’t run destructive commands unless explicitly asked.
+- Don’t send partial/streaming replies to external messaging surfaces (only final replies).
+
+## Session start (required)
+
+- Read `SOUL.md`, `USER.md`, and today+yesterday in `memory/`.
+- Read `MEMORY.md` when present; only fall back to lowercase `memory.md` when `MEMORY.md` is absent.
+- Do it before responding.
+
+## Soul (required)
+
+- `SOUL.md` defines identity, tone, and boundaries. Keep it current.
+- If you change `SOUL.md`, tell the user.
+- You are a fresh instance each session; continuity lives in these files.
+
+## Shared spaces (recommended)
+
+- You’re not the user’s voice; be careful in group chats or public channels.
+- Don’t share private data, contact info, or internal notes.
+
+## Memory system (recommended)
+
+- Daily log: `memory/YYYY-MM-DD.md` (create `memory/` if needed).
+- Long-term memory: `MEMORY.md` for durable facts, preferences, and decisions.
+- Lowercase `memory.md` is legacy fallback only; do not keep both root files on purpose.
+- On session start, read today + yesterday + `MEMORY.md` when present, otherwise `memory.md`.
+- Capture: decisions, preferences, constraints, open loops.
+- Avoid secrets unless explicitly requested.
+
+## Tools & skills
+
+- Tools live in skills; follow each skill’s `SKILL.md` when you need it.
+- Keep environment-specific notes in `TOOLS.md` (Notes for Skills).
+
+## Backup tip (recommended)
+
+If you treat this workspace as Clawd’s “memory”, make it a git repo (ideally private) so `AGENTS.md` and your memory files are backed up.
+
+```bash
+cd ~/.quantumclaw/workspace
+git init
+git add AGENTS.md
+git commit -m "Add Clawd workspace"
+# Optional: add a private remote + push
+```
+
+## What QuantumClaw Does
+
+- Runs WhatsApp gateway + Pi coding agent so the assistant can read/write chats, fetch context, and run skills via the host Mac.
+- macOS app manages permissions (screen recording, notifications, microphone) and exposes the `quantumclaw` CLI via its bundled binary.
+- Direct chats collapse into the agent's `main` session by default; groups stay isolated as `agent:<agentId>:<channel>:group:<id>` (rooms/channels: `agent:<agentId>:<channel>:channel:<id>`); heartbeats keep background tasks alive.
+
+## Core Skills (enable in Settings → Skills)
+
+- **mcporter** — Tool server runtime/CLI for managing external skill backends.
+- **Peekaboo** — Fast macOS screenshots with optional AI vision analysis.
+- **camsnap** — Capture frames, clips, or motion alerts from RTSP/ONVIF security cams.
+- **oracle** — OpenAI-ready agent CLI with session replay and browser control.
+- **eightctl** — Control your sleep, from the terminal.
+- **imsg** — Send, read, stream iMessage & SMS.
+- **wacli** — WhatsApp CLI: sync, search, send.
+- **discord** — Discord actions: react, stickers, polls. Use `user:<id>` or `channel:<id>` targets (bare numeric ids are ambiguous).
+- **gog** — Google Suite CLI: Gmail, Calendar, Drive, Contacts.
+- **spotify-player** — Terminal Spotify client to search/queue/control playback.
+- **sag** — ElevenLabs speech with mac-style say UX; streams to speakers by default.
+- **Sonos CLI** — Control Sonos speakers (discover/status/playback/volume/grouping) from scripts.
+- **blucli** — Play, group, and automate BluOS players from scripts.
+- **OpenHue CLI** — Philips Hue lighting control for scenes and automations.
+- **OpenAI Whisper** — Local speech-to-text for quick dictation and voicemail transcripts.
+- **Gemini CLI** — Google Gemini models from the terminal for fast Q&A.
+- **agent-tools** — Utility toolkit for automations and helper scripts.
+
+## Usage Notes
+
+- Prefer the `quantumclaw` CLI for scripting; mac app handles permissions.
+- Run installs from the Skills tab; it hides the button if a binary is already present.
+- Keep heartbeats enabled so the assistant can schedule reminders, monitor inboxes, and trigger camera captures.
+- Canvas UI runs full-screen with native overlays. Avoid placing critical controls in the top-left/top-right/bottom edges; add explicit gutters in the layout and don’t rely on safe-area insets.
+- For browser-driven verification, use `quantumclaw browser` (tabs/status/screenshot) with the QuantumClaw-managed Chrome profile.
+- For DOM inspection, use `quantumclaw browser eval|query|dom|snapshot` (and `--json`/`--out` when you need machine output).
+- For interactions, use `quantumclaw browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run` (click/type require snapshot refs; use `evaluate` for CSS selectors).

package/docs/reference/RELEASING.md

@@ -0,0 +1,42 @@
+---
+title: "Release Policy"
+summary: "Public release channels, version naming, and cadence"
+read_when:
+  - Looking for public release channel definitions
+  - Looking for version naming and cadence
+---
+
+# Release Policy
+
+QuantumClaw has three public release lanes:
+
+- stable: tagged releases that publish to npm `latest`
+- beta: prerelease tags that publish to npm `beta`
+- dev: the moving head of `main`
+
+## Version naming
+
+- Stable release version: `YYYY.M.D`
+  - Git tag: `vYYYY.M.D`
+- Beta prerelease version: `YYYY.M.D-beta.N`
+  - Git tag: `vYYYY.M.D-beta.N`
+- Do not zero-pad month or day
+- `latest` means the current stable npm release
+- `beta` means the current prerelease npm release
+- Beta releases may ship before the macOS app catches up
+
+## Release cadence
+
+- Releases move beta-first
+- Stable follows only after the latest beta is validated
+- Detailed release procedure, approvals, credentials, and recovery notes are
+  maintainer-only
+
+## Public references
+
+- [`.github/workflows/quantumclaw-npm-release.yml`](https://github.com/quantumclaw/quantumclaw/blob/main/.github/workflows/quantumclaw-npm-release.yml)
+- [`scripts/quantumclaw-npm-release-check.ts`](https://github.com/quantumclaw/quantumclaw/blob/main/scripts/quantumclaw-npm-release-check.ts)
+
+Maintainers use the private release docs in
+[`quantumclaw/maintainers/release/README.md`](https://github.com/quantumclaw/maintainers/blob/main/release/README.md)
+for the actual runbook.

package/docs/reference/api-usage-costs.md

@@ -0,0 +1,144 @@
+---
+summary: "Audit what can spend money, which keys are used, and how to view usage"
+read_when:
+  - You want to understand which features may call paid APIs
+  - You need to audit keys, costs, and usage visibility
+  - You’re explaining /status or /usage cost reporting
+title: "API Usage and Costs"
+---
+
+# API usage & costs
+
+This doc lists **features that can invoke API keys** and where their costs show up. It focuses on
+QuantumClaw features that can generate provider usage or paid API calls.
+
+## Where costs show up (chat + CLI)
+
+**Per-session cost snapshot**
+
+- `/status` shows the current session model, context usage, and last response tokens.
+- If the model uses **API-key auth**, `/status` also shows **estimated cost** for the last reply.
+
+**Per-message cost footer**
+
+- `/usage full` appends a usage footer to every reply, including **estimated cost** (API-key only).
+- `/usage tokens` shows tokens only; OAuth flows hide dollar cost.
+
+**CLI usage windows (provider quotas)**
+
+- `quantumclaw status --usage` and `quantumclaw channels list` show provider **usage windows**
+  (quota snapshots, not per-message costs).
+
+See [Token use & costs](/reference/token-use) for details and examples.
+
+## How keys are discovered
+
+QuantumClaw can pick up credentials from:
+
+- **Auth profiles** (per-agent, stored in `auth-profiles.json`).
+- **Environment variables** (e.g. `OPENAI_API_KEY`, `BRAVE_API_KEY`, `FIRECRAWL_API_KEY`).
+- **Config** (`models.providers.*.apiKey`, `tools.web.search.*`, `tools.web.fetch.firecrawl.*`,
+  `memorySearch.*`, `talk.apiKey`).
+- **Skills** (`skills.entries.<name>.apiKey`) which may export keys to the skill process env.
+
+## Features that can spend keys
+
+### 1) Core model responses (chat + tools)
+
+Every reply or tool call uses the **current model provider** (OpenAI, Anthropic, etc). This is the
+primary source of usage and cost.
+
+See [Models](/providers/models) for pricing config and [Token use & costs](/reference/token-use) for display.
+
+### 2) Media understanding (audio/image/video)
+
+Inbound media can be summarized/transcribed before the reply runs. This uses model/provider APIs.
+
+- Audio: OpenAI / Groq / Deepgram (now **auto-enabled** when keys exist).
+- Image: OpenAI / Anthropic / Google.
+- Video: Google.
+
+See [Media understanding](/nodes/media-understanding).
+
+### 3) Memory embeddings + semantic search
+
+Semantic memory search uses **embedding APIs** when configured for remote providers:
+
+- `memorySearch.provider = "openai"` → OpenAI embeddings
+- `memorySearch.provider = "gemini"` → Gemini embeddings
+- `memorySearch.provider = "voyage"` → Voyage embeddings
+- `memorySearch.provider = "mistral"` → Mistral embeddings
+- `memorySearch.provider = "ollama"` → Ollama embeddings (local/self-hosted; typically no hosted API billing)
+- Optional fallback to a remote provider if local embeddings fail
+
+You can keep it local with `memorySearch.provider = "local"` (no API usage).
+
+See [Memory](/concepts/memory).
+
+### 4) Web search tool
+
+`web_search` uses API keys and may incur usage charges depending on your provider:
+
+- **Brave Search API**: `BRAVE_API_KEY` or `plugins.entries.brave.config.webSearch.apiKey`
+- **Gemini (Google Search)**: `GEMINI_API_KEY` or `plugins.entries.google.config.webSearch.apiKey`
+- **Grok (xAI)**: `XAI_API_KEY` or `plugins.entries.xai.config.webSearch.apiKey`
+- **Kimi (Moonshot)**: `KIMI_API_KEY`, `MOONSHOT_API_KEY`, or `plugins.entries.moonshot.config.webSearch.apiKey`
+- **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `plugins.entries.perplexity.config.webSearch.apiKey`
+
+Legacy `tools.web.search.*` provider paths still load through the temporary compatibility shim, but they are no longer the recommended config surface.
+
+**Brave Search free credit:** Each Brave plan includes \$5/month in renewing
+free credit. The Search plan costs \$5 per 1,000 requests, so the credit covers
+1,000 requests/month at no charge. Set your usage limit in the Brave dashboard
+to avoid unexpected charges.
+
+See [Web tools](/tools/web).
+
+### 5) Web fetch tool (Firecrawl)
+
+`web_fetch` can call **Firecrawl** when an API key is present:
+
+- `FIRECRAWL_API_KEY` or `tools.web.fetch.firecrawl.apiKey`
+
+If Firecrawl isn’t configured, the tool falls back to direct fetch + readability (no paid API).
+
+See [Web tools](/tools/web).
+
+### 6) Provider usage snapshots (status/health)
+
+Some status commands call **provider usage endpoints** to display quota windows or auth health.
+These are typically low-volume calls but still hit provider APIs:
+
+- `quantumclaw status --usage`
+- `quantumclaw models status --json`
+
+See [Models CLI](/cli/models).
+
+### 7) Compaction safeguard summarization
+
+The compaction safeguard can summarize session history using the **current model**, which
+invokes provider APIs when it runs.
+
+See [Session management + compaction](/reference/session-management-compaction).
+
+### 8) Model scan / probe
+
+`quantumclaw models scan` can probe OpenRouter models and uses `OPENROUTER_API_KEY` when
+probing is enabled.
+
+See [Models CLI](/cli/models).
+
+### 9) Talk (speech)
+
+Talk mode can invoke **ElevenLabs** when configured:
+
+- `ELEVENLABS_API_KEY` or `talk.apiKey`
+
+See [Talk mode](/nodes/talk).
+
+### 10) Skills (third-party APIs)
+
+Skills can store `apiKey` in `skills.entries.<name>.apiKey`. If a skill uses that key for external
+APIs, it can incur costs according to the skill’s provider.
+
+See [Skills](/tools/skills).

package/docs/reference/credits.md

@@ -0,0 +1,30 @@
+---
+summary: "Project origin, contributors, and license."
+read_when:
+  - You want the project backstory or contributor credits
+title: "Credits"
+---
+
+# Credits and Acknowledgments
+
+## The name
+
+QuantumClaw = CLAW + TARDIS, because every space lobster needs a time and space machine.
+
+## Credits
+
+- **Peter Steinberger** ([@steipete](https://x.com/steipete)) - Creator, lobster whisperer
+- **Mario Zechner** ([@badlogicc](https://x.com/badlogicgames)) - Pi creator, security pen tester
+- **Clawd** - The space lobster who demanded a better name
+
+## Core contributors
+
+- **Maxim Vovshin** (@Hyaxia, [36747317+Hyaxia@users.noreply.github.com](mailto:36747317+Hyaxia@users.noreply.github.com)) - Blogwatcher skill
+- **Nacho Iacovino** (@nachoiacovino, [nacho.iacovino@gmail.com](mailto:nacho.iacovino@gmail.com)) - Location parsing (Telegram and WhatsApp)
+- **Vincent Koc** ([@vincentkoc](https://github.com/vincentkoc), [@vincent_koc](https://x.com/vincent_koc)) - Agents, Telemetry, Hooks, Security
+
+## License
+
+MIT - Free as a lobster in the ocean.
+
+> "We are all just playing with our own prompts." (An AI, probably high on tokens)

package/docs/reference/device-models.md

@@ -0,0 +1,47 @@
+---
+summary: "How QuantumClaw vendors Apple device model identifiers for friendly names in the macOS app."
+read_when:
+  - Updating device model identifier mappings or NOTICE/license files
+  - Changing how Instances UI displays device names
+title: "Device Model Database"
+---
+
+# Device model database (friendly names)
+
+The macOS companion app shows friendly Apple device model names in the **Instances** UI by mapping Apple model identifiers (e.g. `iPad16,6`, `Mac16,6`) to human-readable names.
+
+The mapping is vendored as JSON under:
+
+- `apps/macos/Sources/QuantumClaw/Resources/DeviceModels/`
+
+## Data source
+
+We currently vendor the mapping from the MIT-licensed repository:
+
+- `kyle-seongwoo-jun/apple-device-identifiers`
+
+To keep builds deterministic, the JSON files are pinned to specific upstream commits (recorded in `apps/macos/Sources/QuantumClaw/Resources/DeviceModels/NOTICE.md`).
+
+## Updating the database
+
+1. Pick the upstream commits you want to pin to (one for iOS, one for macOS).
+2. Update the commit hashes in `apps/macos/Sources/QuantumClaw/Resources/DeviceModels/NOTICE.md`.
+3. Re-download the JSON files, pinned to those commits:
+
+```bash
+IOS_COMMIT="<commit sha for ios-device-identifiers.json>"
+MAC_COMMIT="<commit sha for mac-device-identifiers.json>"
+
+curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${IOS_COMMIT}/ios-device-identifiers.json" \
+  -o apps/macos/Sources/QuantumClaw/Resources/DeviceModels/ios-device-identifiers.json
+
+curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${MAC_COMMIT}/mac-device-identifiers.json" \
+  -o apps/macos/Sources/QuantumClaw/Resources/DeviceModels/mac-device-identifiers.json
+```
+
+4. Ensure `apps/macos/Sources/QuantumClaw/Resources/DeviceModels/LICENSE.apple-device-identifiers.txt` still matches upstream (replace it if the upstream license changes).
+5. Verify the macOS app builds cleanly (no warnings):
+
+```bash
+swift build --package-path apps/macos
+```