durar-ai 2026.4.4

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

@@ -0,0 +1,233 @@
+---
+summary: "Scripted onboarding and agent setup for the Durar 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 `Durar onboard`.
+
+<Note>
+`--json` does not imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.
+</Note>
+
+## Baseline non-interactive example
+
+```bash
+Durar 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
+Durar onboard --non-interactive \
+  --mode local \
+  --auth-choice openai-api-key \
+  --secret-input-mode ref \
+  --accept-risk
+```
+
+## Provider-specific examples
+
+<AccordionGroup>
+  <Accordion title="Anthropic Claude CLI example">
+    ```bash
+    Durar onboard --non-interactive \
+      --mode local \
+      --auth-choice anthropic-cli \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+
+    Requires Claude CLI already installed and signed in on the same gateway
+    host.
+
+  </Accordion>
+  <Accordion title="Gemini example">
+    ```bash
+    Durar 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
+    Durar 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
+    Durar 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
+    Durar 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
+    Durar 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
+    Durar 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
+    Durar 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
+    Durar 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
+    Durar 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
+    Durar 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"
+    Durar 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>
+
+Anthropic setup-token is available again as a legacy/manual onboarding path.
+Use it with the expectation that Anthropic told Durar users the Durar
+Claude-login path requires **Extra Usage**. For production, prefer an
+Anthropic API key.
+
+## Add another agent
+
+Use `Durar agents add <name>` to create a separate agent with its own workspace,
+sessions, and auth profiles. Running without `--workspace` launches the wizard.
+
+```bash
+Durar agents add work \
+  --workspace ~/.Durar/workspace-work \
+  --model openai/gpt-5.4 \
+  --bind whatsapp:biz \
+  --non-interactive \
+  --json
+```
+
+What it sets:
+
+- `agents.list[].name`
+- `agents.list[].workspace`
+- `agents.list[].agentDir`
+
+Notes:
+
+- Default workspaces follow `~/.Durar/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: [`Durar onboard`](/cli/onboard)

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

@@ -0,0 +1,324 @@
+---
+summary: "Complete reference for CLI setup flow, auth/model setup, outputs, and internals"
+read_when:
+  - You need detailed behavior for Durar 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 `Durar 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 Claude CLI or API key, plus MiniMax, GLM, Ollama, Moonshot, StepFun, and AI Gateway options)
+- Workspace location and bootstrap files
+- Gateway settings (port, bind, auth, tailscale)
+- Channels and providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles, and other bundled channel plugins)
+- Daemon install (LaunchAgent, systemd user unit, or native Windows Scheduled Task with Startup-folder fallback)
+- 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 `~/.Durar/Durar.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 `Durar 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 `~/.Durar/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): 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
+      `Durar 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.
+    - Native Windows: Scheduled Task first
+      - If task creation is denied, Durar falls back to a per-user Startup-folder login item and starts the gateway immediately.
+      - Scheduled Tasks remain preferred because they provide better supervisor status.
+    - Runtime selection: Node (recommended; required for WhatsApp and Telegram). Bun is not recommended.
+  </Step>
+  <Step title="Health check">
+    - Starts gateway (if needed) and runs `Durar health`.
+    - `Durar status --deep` adds the live gateway health probe to status output, including channel probes when supported.
+  </Step>
+  <Step title="Skills">
+    - Reads available skills and checks requirements.
+    - Lets you choose node manager: npm, pnpm, or bun.
+    - 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 Claude CLI">
+    Reuses a local Claude CLI login on the gateway host and switches model
+    selection to a canonical `claude-cli/claude-*` ref.
+
+    This is an available local fallback path in `Durar onboard` and
+    `Durar configure`. For production, prefer an Anthropic API key.
+
+    - 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="OpenAI Code subscription (Codex CLI reuse)">
+    If `~/.codex/auth.json` exists, the wizard can reuse it.
+    Reused Codex CLI credentials stay managed by Codex CLI; on expiry Durar
+    re-reads that source first and, when the provider can refresh it, writes
+    the refreshed credential back to Codex storage instead of taking ownership
+    itself.
+  </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`; API-key setup uses
+    `minimax/...`, and OAuth setup uses `minimax-portal/...`.
+    More detail: [MiniMax](/providers/minimax).
+  </Accordion>
+  <Accordion title="StepFun">
+    Config is auto-written for StepFun standard or Step Plan on China or global endpoints.
+    Standard currently includes `step-3.5-flash`, and Step Plan also includes `step-3.5-flash-2603`.
+    More detail: [StepFun](/providers/stepfun).
+  </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.
+- When onboarding starts from a provider auth choice, the model picker prefers
+  that provider automatically. For Volcengine and BytePlus, the same preference
+  also matches their coding-plan variants (`volcengine-plan/*`,
+  `byteplus-plan/*`).
+- If that preferred-provider filter would be empty, the picker falls back to
+  the full catalog instead of showing no models.
+- Wizard runs a model check and warns if the configured model is unknown or missing auth.
+
+Credential and profile paths:
+
+- Auth profiles (API keys + OAuth): `~/.Durar/agents/<agentId>/agent/auth-profiles.json`
+- Legacy OAuth import: `~/.Durar/credentials/oauth.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
+that agent's `auth-profiles.json` (for example
+`~/.Durar/agents/<agentId>/agent/auth-profiles.json`, or the matching
+`$Durar_STATE_DIR/...` path) to the gateway host. `credentials/oauth.json`
+is only a legacy import source.
+</Note>
+
+## Outputs and internals
+
+Typical fields in `~/.Durar/Durar.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.matrix.*`, `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`
+  - The `setup --node-manager` flag accepts `npm`, `pnpm`, or `bun`.
+  - Manual config can still set `skills.install.nodeManager: "yarn"` later.
+- `wizard.lastRunAt`
+- `wizard.lastRunVersion`
+- `wizard.lastRunCommit`
+- `wizard.lastRunCommand`
+- `wizard.lastRunMode`
+
+`Durar agents add` writes `agents.list[]` and optional `bindings`.
+
+WhatsApp credentials go under `~/.Durar/credentials/whatsapp/<accountId>/`.
+Sessions are stored under `~/.Durar/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 `~/.Durar/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: [`Durar onboard`](/cli/onboard)

package/docs/start/wizard.md

@@ -0,0 +1,127 @@
+---
+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 Durar 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
+Durar onboard
+```
+
+<Info>
+Fastest first chat: open the Control UI (no channel setup needed). Run
+`Durar dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard).
+</Info>
+
+To reconfigure later:
+
+```bash
+Durar configure
+Durar 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
+such as Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search,
+Ollama Web Search, Perplexity, SearXNG, or Tavily. Some providers require an
+API key, while others are key-free. You can also configure this later with
+`Durar 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 provider-specific manual auth), 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.
+   For Anthropic, interactive onboarding/configure offers **Anthropic Claude CLI** as a local fallback and **Anthropic API key** as the recommended production path. Anthropic setup-token is also available again as a legacy/manual Durar path, with Anthropic's Durar-specific **Extra Usage** billing expectation.
+2. **Workspace** — Location for agent files (default `~/.Durar/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** — built-in and bundled chat channels such as BlueBubbles, Discord, Feishu, Google Chat, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and more.
+5. **Daemon** — Installs a LaunchAgent (macOS), systemd user unit (Linux/WSL2), or native Windows Scheduled Task with per-user Startup-folder fallback.
+   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 `Durar 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 `Durar 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 `~/.Durar/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: [`Durar onboard`](/cli/onboard)
+- Onboarding overview: [Onboarding Overview](/start/onboarding-overview)
+- macOS app onboarding: [Onboarding](/start/onboarding)
+- Agent first-run ritual: [Agent Bootstrapping](/start/bootstrapping)