@quantumclaw/quantumclaw 2026.3.22

package/docs/start/wizard-cli-automation.md

@@ -0,0 +1,215 @@
+---
+summary: "Scripted onboarding and agent setup for the QuantumClaw CLI"
+read_when:
+  - You are automating onboarding in scripts or CI
+  - You need non-interactive examples for specific providers
+title: "CLI Automation"
+sidebarTitle: "CLI automation"
+---
+
+# CLI Automation
+
+Use `--non-interactive` to automate `quantumclaw onboard`.
+
+<Note>
+`--json` does not imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.
+</Note>
+
+## Baseline non-interactive example
+
+```bash
+quantumclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice apiKey \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --secret-input-mode plaintext \
+  --gateway-port 18789 \
+  --gateway-bind loopback \
+  --install-daemon \
+  --daemon-runtime node \
+  --skip-skills
+```
+
+Add `--json` for a machine-readable summary.
+
+Use `--secret-input-mode ref` to store env-backed refs in auth profiles instead of plaintext values.
+Interactive selection between env refs and configured provider refs (`file` or `exec`) is available in the onboarding flow.
+
+In non-interactive `ref` mode, provider env vars must be set in the process environment.
+Passing inline key flags without the matching env var now fails fast.
+
+Example:
+
+```bash
+quantumclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice openai-api-key \
+  --secret-input-mode ref \
+  --accept-risk
+```
+
+## Provider-specific examples
+
+<AccordionGroup>
+  <Accordion title="Gemini example">
+    ```bash
+    quantumclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice gemini-api-key \
+      --gemini-api-key "$GEMINI_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Z.AI example">
+    ```bash
+    quantumclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice zai-api-key \
+      --zai-api-key "$ZAI_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Vercel AI Gateway example">
+    ```bash
+    quantumclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice ai-gateway-api-key \
+      --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Cloudflare AI Gateway example">
+    ```bash
+    quantumclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice cloudflare-ai-gateway-api-key \
+      --cloudflare-ai-gateway-account-id "your-account-id" \
+      --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
+      --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Moonshot example">
+    ```bash
+    quantumclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice moonshot-api-key \
+      --moonshot-api-key "$MOONSHOT_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Mistral example">
+    ```bash
+    quantumclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice mistral-api-key \
+      --mistral-api-key "$MISTRAL_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Synthetic example">
+    ```bash
+    quantumclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice synthetic-api-key \
+      --synthetic-api-key "$SYNTHETIC_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="OpenCode example">
+    ```bash
+    quantumclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice opencode-zen \
+      --opencode-zen-api-key "$OPENCODE_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+    Swap to `--auth-choice opencode-go --opencode-go-api-key "$OPENCODE_API_KEY"` for the Go catalog.
+  </Accordion>
+  <Accordion title="Ollama example">
+    ```bash
+    quantumclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice ollama \
+      --custom-model-id "qwen3.5:27b" \
+      --accept-risk \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Custom provider example">
+    ```bash
+    quantumclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice custom-api-key \
+      --custom-base-url "https://llm.example.com/v1" \
+      --custom-model-id "foo-large" \
+      --custom-api-key "$CUSTOM_API_KEY" \
+      --custom-provider-id "my-custom" \
+      --custom-compatibility anthropic \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+
+    `--custom-api-key` is optional. If omitted, onboarding checks `CUSTOM_API_KEY`.
+
+    Ref-mode variant:
+
+    ```bash
+    export CUSTOM_API_KEY="your-key"
+    quantumclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice custom-api-key \
+      --custom-base-url "https://llm.example.com/v1" \
+      --custom-model-id "foo-large" \
+      --secret-input-mode ref \
+      --custom-provider-id "my-custom" \
+      --custom-compatibility anthropic \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+
+    In this mode, onboarding stores `apiKey` as `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`.
+
+  </Accordion>
+</AccordionGroup>
+
+## Add another agent
+
+Use `quantumclaw agents add <name>` to create a separate agent with its own workspace,
+sessions, and auth profiles. Running without `--workspace` launches the wizard.
+
+```bash
+quantumclaw agents add work \
+  --workspace ~/.quantumclaw/workspace-work \
+  --model openai/gpt-5.2 \
+  --bind whatsapp:biz \
+  --non-interactive \
+  --json
+```
+
+What it sets:
+
+- `agents.list[].name`
+- `agents.list[].workspace`
+- `agents.list[].agentDir`
+
+Notes:
+
+- Default workspaces follow `~/.quantumclaw/workspace-<agentId>`.
+- Add `bindings` to route inbound messages (the wizard can do this).
+- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
+
+## Related docs
+
+- Onboarding hub: [Onboarding (CLI)](/start/wizard)
+- Full reference: [CLI Setup Reference](/start/wizard-cli-reference)
+- Command reference: [`quantumclaw onboard`](/cli/onboard)

package/docs/start/wizard-cli-reference.md

@@ -0,0 +1,299 @@
+---
+summary: "Complete reference for CLI setup flow, auth/model setup, outputs, and internals"
+read_when:
+  - You need detailed behavior for quantumclaw onboard
+  - You are debugging onboarding results or integrating onboarding clients
+title: "CLI Setup Reference"
+sidebarTitle: "CLI reference"
+---
+
+# CLI Setup Reference
+
+This page is the full reference for `quantumclaw onboard`.
+For the short guide, see [Onboarding (CLI)](/start/wizard).
+
+## What the wizard does
+
+Local mode (default) walks you through:
+
+- Model and auth setup (OpenAI Code subscription OAuth, Anthropic API key or setup token, plus MiniMax, GLM, Ollama, Moonshot, and AI Gateway options)
+- Workspace location and bootstrap files
+- Gateway settings (port, bind, auth, tailscale)
+- Channels and providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost plugin, Signal)
+- Daemon install (LaunchAgent or systemd user unit)
+- Health check
+- Skills setup
+
+Remote mode configures this machine to connect to a gateway elsewhere.
+It does not install or modify anything on the remote host.
+
+## Local flow details
+
+<Steps>
+  <Step title="Existing config detection">
+    - If `~/.quantumclaw/quantumclaw.json` exists, choose Keep, Modify, or Reset.
+    - Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass `--reset`).
+    - CLI `--reset` defaults to `config+creds+sessions`; use `--reset-scope full` to also remove workspace.
+    - If config is invalid or contains legacy keys, the wizard stops and asks you to run `quantumclaw doctor` before continuing.
+    - Reset uses `trash` and offers scopes:
+      - Config only
+      - Config + credentials + sessions
+      - Full reset (also removes workspace)
+  </Step>
+  <Step title="Model and auth">
+    - Full option matrix is in [Auth and model options](#auth-and-model-options).
+  </Step>
+  <Step title="Workspace">
+    - Default `~/.quantumclaw/workspace` (configurable).
+    - Seeds workspace files needed for first-run bootstrap ritual.
+    - Workspace layout: [Agent workspace](/concepts/agent-workspace).
+  </Step>
+  <Step title="Gateway">
+    - Prompts for port, bind, auth mode, and tailscale exposure.
+    - Recommended: keep token auth enabled even for loopback so local WS clients must authenticate.
+    - In token mode, interactive setup offers:
+      - **Generate/store plaintext token** (default)
+      - **Use SecretRef** (opt-in)
+    - In password mode, interactive setup also supports plaintext or SecretRef storage.
+    - Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
+      - Requires a non-empty env var in the onboarding process environment.
+      - Cannot be combined with `--gateway-token`.
+    - Disable auth only if you fully trust every local process.
+    - Non-loopback binds still require auth.
+  </Step>
+  <Step title="Channels">
+    - [WhatsApp](/channels/whatsapp): optional QR login
+    - [Telegram](/channels/telegram): bot token
+    - [Discord](/channels/discord): bot token
+    - [Google Chat](/channels/googlechat): service account JSON + webhook audience
+    - [Mattermost](/channels/mattermost) plugin: bot token + base URL
+    - [Signal](/channels/signal): optional `signal-cli` install + account config
+    - [BlueBubbles](/channels/bluebubbles): recommended for iMessage; server URL + password + webhook
+    - [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access
+    - DM security: default is pairing. First DM sends a code; approve via
+      `quantumclaw pairing approve <channel> <code>` or use allowlists.
+  </Step>
+  <Step title="Daemon install">
+    - macOS: LaunchAgent
+      - Requires logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
+    - Linux and Windows via WSL2: systemd user unit
+      - Wizard attempts `loginctl enable-linger <user>` so gateway stays up after logout.
+      - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
+    - Runtime selection: Node (recommended; required for WhatsApp and Telegram). Bun is not recommended.
+  </Step>
+  <Step title="Health check">
+    - Starts gateway (if needed) and runs `quantumclaw health`.
+    - `quantumclaw status --deep` adds gateway health probes to status output.
+  </Step>
+  <Step title="Skills">
+    - Reads available skills and checks requirements.
+    - Lets you choose node manager: npm or pnpm (bun not recommended).
+    - Installs optional dependencies (some use Homebrew on macOS).
+  </Step>
+  <Step title="Finish">
+    - Summary and next steps, including iOS, Android, and macOS app options.
+  </Step>
+</Steps>
+
+<Note>
+If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
+If Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
+</Note>
+
+## Remote mode details
+
+Remote mode configures this machine to connect to a gateway elsewhere.
+
+<Info>
+Remote mode does not install or modify anything on the remote host.
+</Info>
+
+What you set:
+
+- Remote gateway URL (`ws://...`)
+- Token if remote gateway auth is required (recommended)
+
+<Note>
+- If gateway is loopback-only, use SSH tunneling or a tailnet.
+- Discovery hints:
+  - macOS: Bonjour (`dns-sd`)
+  - Linux: Avahi (`avahi-browse`)
+</Note>
+
+## Auth and model options
+
+<AccordionGroup>
+  <Accordion title="Anthropic API key">
+    Uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
+  </Accordion>
+  <Accordion title="Anthropic OAuth (Claude Code CLI)">
+    - macOS: checks Keychain item "Claude Code-credentials"
+    - Linux and Windows: reuses `~/.claude/.credentials.json` if present
+
+    On macOS, choose "Always Allow" so launchd starts do not block.
+
+  </Accordion>
+  <Accordion title="Anthropic token (setup-token paste)">
+    Run `claude setup-token` on any machine, then paste the token.
+    You can name it; blank uses default.
+  </Accordion>
+  <Accordion title="OpenAI Code subscription (Codex CLI reuse)">
+    If `~/.codex/auth.json` exists, the wizard can reuse it.
+  </Accordion>
+  <Accordion title="OpenAI Code subscription (OAuth)">
+    Browser flow; paste `code#state`.
+
+    Sets `agents.defaults.model` to `openai-codex/gpt-5.4` when model is unset or `openai/*`.
+
+  </Accordion>
+  <Accordion title="OpenAI API key">
+    Uses `OPENAI_API_KEY` if present or prompts for a key, then stores the credential in auth profiles.
+
+    Sets `agents.defaults.model` to `openai/gpt-5.4` when model is unset, `openai/*`, or `openai-codex/*`.
+
+  </Accordion>
+  <Accordion title="xAI (Grok) API key">
+    Prompts for `XAI_API_KEY` and configures xAI as a model provider.
+  </Accordion>
+  <Accordion title="OpenCode">
+    Prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`) and lets you choose the Zen or Go catalog.
+    Setup URL: [opencode.ai/auth](https://opencode.ai/auth).
+  </Accordion>
+  <Accordion title="API key (generic)">
+    Stores the key for you.
+  </Accordion>
+  <Accordion title="Vercel AI Gateway">
+    Prompts for `AI_GATEWAY_API_KEY`.
+    More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway).
+  </Accordion>
+  <Accordion title="Cloudflare AI Gateway">
+    Prompts for account ID, gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
+    More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway).
+  </Accordion>
+  <Accordion title="MiniMax">
+    Config is auto-written. Hosted default is `MiniMax-M2.7`; `MiniMax-M2.5` stays available.
+    More detail: [MiniMax](/providers/minimax).
+  </Accordion>
+  <Accordion title="Synthetic (Anthropic-compatible)">
+    Prompts for `SYNTHETIC_API_KEY`.
+    More detail: [Synthetic](/providers/synthetic).
+  </Accordion>
+  <Accordion title="Ollama (Cloud and local open models)">
+    Prompts for base URL (default `http://127.0.0.1:11434`), then offers Cloud + Local or Local mode.
+    Discovers available models and suggests defaults.
+    More detail: [Ollama](/providers/ollama).
+  </Accordion>
+  <Accordion title="Moonshot and Kimi Coding">
+    Moonshot (Kimi K2) and Kimi Coding configs are auto-written.
+    More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot).
+  </Accordion>
+  <Accordion title="Custom provider">
+    Works with OpenAI-compatible and Anthropic-compatible endpoints.
+
+    Interactive onboarding supports the same API key storage choices as other provider API key flows:
+    - **Paste API key now** (plaintext)
+    - **Use secret reference** (env ref or configured provider ref, with preflight validation)
+
+    Non-interactive flags:
+    - `--auth-choice custom-api-key`
+    - `--custom-base-url`
+    - `--custom-model-id`
+    - `--custom-api-key` (optional; falls back to `CUSTOM_API_KEY`)
+    - `--custom-provider-id` (optional)
+    - `--custom-compatibility <openai|anthropic>` (optional; default `openai`)
+
+  </Accordion>
+  <Accordion title="Skip">
+    Leaves auth unconfigured.
+  </Accordion>
+</AccordionGroup>
+
+Model behavior:
+
+- Pick default model from detected options, or enter provider and model manually.
+- Wizard runs a model check and warns if the configured model is unknown or missing auth.
+
+Credential and profile paths:
+
+- OAuth credentials: `~/.quantumclaw/credentials/oauth.json`
+- Auth profiles (API keys + OAuth): `~/.quantumclaw/agents/<agentId>/agent/auth-profiles.json`
+
+Credential storage mode:
+
+- Default onboarding behavior persists API keys as plaintext values in auth profiles.
+- `--secret-input-mode ref` enables reference mode instead of plaintext key storage.
+  In interactive setup, you can choose either:
+  - environment variable ref (for example `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`)
+  - configured provider ref (`file` or `exec`) with provider alias + id
+- Interactive reference mode runs a fast preflight validation before saving.
+  - Env refs: validates variable name + non-empty value in the current onboarding environment.
+  - Provider refs: validates provider config and resolves the requested id.
+  - If preflight fails, onboarding shows the error and lets you retry.
+- In non-interactive mode, `--secret-input-mode ref` is env-backed only.
+  - Set the provider env var in the onboarding process environment.
+  - Inline key flags (for example `--openai-api-key`) require that env var to be set; otherwise onboarding fails fast.
+  - For custom providers, non-interactive `ref` mode stores `models.providers.<id>.apiKey` as `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`.
+  - In that custom-provider case, `--custom-api-key` requires `CUSTOM_API_KEY` to be set; otherwise onboarding fails fast.
+- Gateway auth credentials support plaintext and SecretRef choices in interactive setup:
+  - Token mode: **Generate/store plaintext token** (default) or **Use SecretRef**.
+  - Password mode: plaintext or SecretRef.
+- Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
+- Existing plaintext setups continue to work unchanged.
+
+<Note>
+Headless and server tip: complete OAuth on a machine with a browser, then copy
+`~/.quantumclaw/credentials/oauth.json` (or `$QUANTUMCLAW_STATE_DIR/credentials/oauth.json`)
+to the gateway host.
+</Note>
+
+## Outputs and internals
+
+Typical fields in `~/.quantumclaw/quantumclaw.json`:
+
+- `agents.defaults.workspace`
+- `agents.defaults.model` / `models.providers` (if Minimax chosen)
+- `tools.profile` (local onboarding defaults to `"coding"` when unset; existing explicit values are preserved)
+- `gateway.*` (mode, bind, auth, tailscale)
+- `session.dmScope` (local onboarding defaults this to `per-channel-peer` when unset; existing explicit values are preserved)
+- `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
+- Channel allowlists (Slack, Discord, Matrix, Microsoft Teams) when you opt in during prompts (names resolve to IDs when possible)
+- `skills.install.nodeManager`
+- `wizard.lastRunAt`
+- `wizard.lastRunVersion`
+- `wizard.lastRunCommit`
+- `wizard.lastRunCommand`
+- `wizard.lastRunMode`
+
+`quantumclaw agents add` writes `agents.list[]` and optional `bindings`.
+
+WhatsApp credentials go under `~/.quantumclaw/credentials/whatsapp/<accountId>/`.
+Sessions are stored under `~/.quantumclaw/agents/<agentId>/sessions/`.
+
+<Note>
+Some channels are delivered as plugins. When selected during setup, the wizard
+prompts to install the plugin (npm or local path) before channel configuration.
+</Note>
+
+Gateway wizard RPC:
+
+- `wizard.start`
+- `wizard.next`
+- `wizard.cancel`
+- `wizard.status`
+
+Clients (macOS app and Control UI) can render steps without re-implementing onboarding logic.
+
+Signal setup behavior:
+
+- Downloads the appropriate release asset
+- Stores it under `~/.quantumclaw/tools/signal-cli/<version>/`
+- Writes `channels.signal.cliPath` in config
+- JVM builds require Java 21
+- Native builds are used when available
+- Windows uses WSL2 and follows Linux signal-cli flow inside WSL
+
+## Related docs
+
+- Onboarding hub: [Onboarding (CLI)](/start/wizard)
+- Automation and scripts: [CLI Automation](/start/wizard-cli-automation)
+- Command reference: [`quantumclaw onboard`](/cli/onboard)

package/docs/start/wizard.md

@@ -0,0 +1,125 @@
+---
+summary: "CLI onboarding: guided setup for gateway, workspace, channels, and skills"
+read_when:
+  - Running or configuring CLI onboarding
+  - Setting up a new machine
+title: "Onboarding (CLI)"
+sidebarTitle: "Onboarding: CLI"
+---
+
+# Onboarding (CLI)
+
+CLI onboarding is the **recommended** way to set up QuantumClaw on macOS,
+Linux, or Windows (via WSL2; strongly recommended).
+It configures a local Gateway or a remote Gateway connection, plus channels, skills,
+and workspace defaults in one guided flow.
+
+```bash
+quantumclaw onboard
+```
+
+<Info>
+Fastest first chat: open the Control UI (no channel setup needed). Run
+`quantumclaw dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard).
+</Info>
+
+To reconfigure later:
+
+```bash
+quantumclaw configure
+quantumclaw agents add <name>
+```
+
+<Note>
+`--json` does not imply non-interactive mode. For scripts, use `--non-interactive`.
+</Note>
+
+<Tip>
+CLI onboarding includes a web search step where you can pick a provider
+(Perplexity, Brave, Gemini, Grok, or Kimi) and paste your API key so the agent
+can use `web_search`. You can also configure this later with
+`quantumclaw configure --section web`. Docs: [Web tools](/tools/web).
+</Tip>
+
+## QuickStart vs Advanced
+
+Onboarding starts with **QuickStart** (defaults) vs **Advanced** (full control).
+
+<Tabs>
+  <Tab title="QuickStart (defaults)">
+    - Local gateway (loopback)
+    - Workspace default (or existing workspace)
+    - Gateway port **18789**
+    - Gateway auth **Token** (auto‑generated, even on loopback)
+    - Tool policy default for new local setups: `tools.profile: "coding"` (existing explicit profile is preserved)
+    - DM isolation default: local onboarding writes `session.dmScope: "per-channel-peer"` when unset. Details: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals)
+    - Tailscale exposure **Off**
+    - Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your phone number)
+  </Tab>
+  <Tab title="Advanced (full control)">
+    - Exposes every step (mode, workspace, gateway, channels, daemon, skills).
+  </Tab>
+</Tabs>
+
+## What onboarding configures
+
+**Local mode (default)** walks you through these steps:
+
+1. **Model/Auth** — choose any supported provider/auth flow (API key, OAuth, or setup-token), including Custom Provider
+   (OpenAI-compatible, Anthropic-compatible, or Unknown auto-detect). Pick a default model.
+   Security note: if this agent will run tools or process webhook/hooks content, prefer the strongest latest-generation model available and keep tool policy strict. Weaker/older tiers are easier to prompt-inject.
+   For non-interactive runs, `--secret-input-mode ref` stores env-backed refs in auth profiles instead of plaintext API key values.
+   In non-interactive `ref` mode, the provider env var must be set; passing inline key flags without that env var fails fast.
+   In interactive runs, choosing secret reference mode lets you point at either an environment variable or a configured provider ref (`file` or `exec`), with a fast preflight validation before saving.
+2. **Workspace** — Location for agent files (default `~/.quantumclaw/workspace`). Seeds bootstrap files.
+3. **Gateway** — Port, bind address, auth mode, Tailscale exposure.
+   In interactive token mode, choose default plaintext token storage or opt into SecretRef.
+   Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
+4. **Channels** — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles, or iMessage.
+5. **Daemon** — Installs a LaunchAgent (macOS) or systemd user unit (Linux/WSL2).
+   If token auth requires a token and `gateway.auth.token` is SecretRef-managed, daemon install validates it but does not persist the resolved token into supervisor service environment metadata.
+   If token auth requires a token and the configured token SecretRef is unresolved, daemon install is blocked with actionable guidance.
+   If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, daemon install is blocked until mode is set explicitly.
+6. **Health check** — Starts the Gateway and verifies it's running.
+7. **Skills** — Installs recommended skills and optional dependencies.
+
+<Note>
+Re-running onboarding does **not** wipe anything unless you explicitly choose **Reset** (or pass `--reset`).
+CLI `--reset` defaults to config, credentials, and sessions; use `--reset-scope full` to include workspace.
+If the config is invalid or contains legacy keys, onboarding asks you to run `quantumclaw doctor` first.
+</Note>
+
+**Remote mode** only configures the local client to connect to a Gateway elsewhere.
+It does **not** install or change anything on the remote host.
+
+## Add another agent
+
+Use `quantumclaw agents add <name>` to create a separate agent with its own workspace,
+sessions, and auth profiles. Running without `--workspace` launches onboarding.
+
+What it sets:
+
+- `agents.list[].name`
+- `agents.list[].workspace`
+- `agents.list[].agentDir`
+
+Notes:
+
+- Default workspaces follow `~/.quantumclaw/workspace-<agentId>`.
+- Add `bindings` to route inbound messages (onboarding can do this).
+- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
+
+## Full reference
+
+For detailed step-by-step breakdowns and config outputs, see
+[CLI Setup Reference](/start/wizard-cli-reference).
+For non-interactive examples, see [CLI Automation](/start/wizard-cli-automation).
+For the deeper technical reference, including RPC details, see
+[Onboarding Reference](/reference/wizard).
+
+## Related docs
+
+- CLI command reference: [`quantumclaw onboard`](/cli/onboard)
+- Onboarding overview: [Onboarding Overview](/start/onboarding-overview)
+- macOS app onboarding: [Onboarding](/start/onboarding)
+- Agent first-run ritual: [Agent Bootstrapping](/start/bootstrapping)

package/docs/style.css

@@ -0,0 +1,37 @@
+#content > h1:first-of-type {
+  display: none !important;
+}
+
+.nav-tabs {
+  position: relative;
+}
+
+.nav-tabs-item > div {
+  opacity: 0;
+}
+
+.nav-tabs-underline {
+  position: absolute;
+  left: 0;
+  bottom: 0;
+  height: 1.5px;
+  width: var(--nav-tab-underline-width, 0);
+  transform: translateX(var(--nav-tab-underline-x, 0));
+  background-color: rgb(var(--primary));
+  border-radius: 999px;
+  pointer-events: none;
+  opacity: 0;
+  transition:
+    transform 260ms ease-in-out,
+    width 260ms ease-in-out,
+    opacity 160ms ease-in-out;
+  will-change: transform, width;
+}
+
+html.dark .nav-tabs-underline {
+  background-color: rgb(var(--primary-light));
+}
+
+.nav-tabs-underline-ready .nav-tabs-underline {
+  opacity: 1;
+}