clawdbot 2026.1.4-1

package/docs/typebox.md

@@ -0,0 +1,42 @@
+---
+summary: "TypeBox schemas as the single source of truth for the gateway protocol"
+read_when:
+  - Updating protocol schemas or codegen
+---
+# TypeBox as Protocol Source of Truth
+
+Last updated: 2025-12-09
+
+We use TypeBox schemas in `src/gateway/protocol/schema.ts` as the single source of truth for the Gateway control plane (connect/req/res/event frames and payloads). All derived artifacts should be generated from these schemas, not edited by hand.
+
+## Current pipeline
+
+- **TypeBox → JSON Schema**: `pnpm protocol:gen` writes `dist/protocol.schema.json` (draft-07) and runs AJV in the server tests.
+- **TypeBox → Swift**: `pnpm protocol:gen:swift` generates `apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift`.
+
+## Problem
+
+- We want strong typing in Swift, including a sealed `GatewayFrame` enum with a discriminator and a forward-compatible `unknown` case.
+
+## Preferred plan (next step)
+
+- Add a small, custom Swift generator driven directly by the TypeBox schemas:
+  - Emit a sealed `enum GatewayFrame: Codable { case req(RequestFrame), res(ResponseFrame), event(EventFrame) }`.
+  - Emit strongly typed payload structs/enums (`ConnectParams`, `HelloOk`, `RequestFrame`, `ResponseFrame`, `EventFrame`, `PresenceEntry`, `Snapshot`, `StateVersion`, `ErrorShape`, `AgentEvent`, `TickEvent`, `ShutdownEvent`, `SendParams`, `AgentParams`, `ErrorCode`, `PROTOCOL_VERSION`).
+  - Custom `init(from:)` / `encode(to:)` enforces the `type` discriminator and can include an `unknown` case for forward compatibility.
+  - Wire a new script (e.g., `pnpm protocol:gen:swift`) into `protocol:check` so CI fails if the generated Swift is stale.
+
+Why this path:
+- Single source of truth stays TypeBox; no new IDL to maintain.
+- Predictable, strongly typed Swift (no optional soup).
+- Small deterministic codegen (~150–200 LOC script) we control.
+
+## Alternative (if we want off-the-shelf codegen)
+
+- Wrap the existing JSON Schema into an OpenAPI 3.1 doc (auto-generated) and use **swift-openapi-generator** or **openapi-generator swift5**. More moving parts, but also yields enums with discriminator support. Keep this as a fallback if we don’t want a custom emitter.
+
+## Action items
+
+- Implement `protocol:gen:swift` that reads the TypeBox schemas and emits the sealed Swift enum + payload structs.
+- Update `protocol:check` to include the Swift generator output in the diff check.
+- Remove quicktype output once the custom generator is in place (or keep it for docs only).

package/docs/voicewake.md

@@ -0,0 +1,61 @@
+---
+summary: "Global voice wake words (Gateway-owned) and how they sync across nodes"
+read_when:
+  - Changing voice wake words behavior or defaults
+  - Adding new node platforms that need wake word sync
+---
+# Voice Wake (Global Wake Words)
+
+Clawdbot treats **wake words as a single global list** owned by the **Gateway**.
+
+- There are **no per-node custom wake words**.
+- **Any node/app UI may edit** the list; changes are persisted by the Gateway and broadcast to everyone.
+- Each device still keeps its own **Voice Wake enabled/disabled** toggle (local UX + permissions differ).
+
+## Storage (Gateway host)
+
+Wake words are stored on the gateway machine at:
+
+- `~/.clawdbot/settings/voicewake.json`
+
+Shape:
+
+```json
+{ "triggers": ["clawd", "claude", "computer"], "updatedAtMs": 1730000000000 }
+```
+
+## Protocol
+
+### Methods
+
+- `voicewake.get` → `{ triggers: string[] }`
+- `voicewake.set` with params `{ triggers: string[] }` → `{ triggers: string[] }`
+
+Notes:
+- Triggers are normalized (trimmed, empties dropped). Empty lists fall back to defaults.
+- Limits are enforced for safety (count/length caps).
+
+### Events
+
+- `voicewake.changed` payload `{ triggers: string[] }`
+
+Who receives it:
+- All WebSocket clients (macOS app, WebChat, etc.)
+- All connected bridge nodes (iOS/Android), and also on node connect as an initial “current state” push.
+
+## Client behavior
+
+### macOS app
+
+- Uses the global list to gate `VoiceWakeRuntime` triggers.
+- Editing “Trigger words” in Voice Wake settings calls `voicewake.set` and then relies on the broadcast to keep other clients in sync.
+
+### iOS node
+
+- Uses the global list for `VoiceWakeManager` trigger detection.
+- Editing Wake Words in Settings calls `voicewake.set` (over the bridge) and also keeps local wake-word detection responsive.
+
+### Android node
+
+- Exposes a Wake Words editor in Settings.
+- Calls `voicewake.set` over the bridge so edits sync everywhere.

package/docs/web.md

@@ -0,0 +1,115 @@
+---
+summary: "Gateway web surfaces: Control UI, bind modes, and security"
+read_when:
+  - You want to access the Gateway over Tailscale
+  - You want the browser Control UI and config editing
+---
+# Web (Gateway)
+
+The Gateway serves a small **browser Control UI** (Vite + Lit) from the same port as the Gateway WebSocket:
+
+- default: `http://<host>:18789/`
+- optional prefix: set `gateway.controlUi.basePath` (e.g. `/clawdbot`)
+
+The UI talks directly to the Gateway WS and supports:
+- Chat (`chat.history`, `chat.send`, `chat.abort`)
+- Chat tool cards (agent tool events)
+- Connections (provider status, WhatsApp QR, Telegram config)
+- Instances (`system-presence`)
+- Sessions (`sessions.list`, `sessions.patch`)
+- Cron (`cron.*`)
+- Skills (`skills.status`, `skills.update`, `skills.install`)
+- Nodes (`node.list`, `node.describe`, `node.invoke`)
+- Config (`config.get`, `config.set`) for `~/.clawdbot/clawdbot.json`
+- Debug (status/health/models snapshots + manual calls)
+
+## Webhooks
+
+When `hooks.enabled=true`, the Gateway also exposes a small webhook surface on the same HTTP server.
+See `docs/configuration.md` → `hooks` for auth + payloads.
+
+## Config (default-on)
+
+The Control UI is **enabled by default** when assets are present (`dist/control-ui`).
+You can control it via config:
+
+```json5
+{
+  gateway: {
+    controlUi: { enabled: true, basePath: "/clawdbot" } // basePath optional
+  }
+}
+```
+
+## Tailscale access
+
+### Integrated Serve (recommended)
+
+Keep the Gateway on loopback and let Tailscale Serve proxy it:
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "serve" }
+  }
+}
+```
+
+Then start the gateway:
+
+```bash
+clawdbot gateway
+```
+
+Open:
+- `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`)
+
+### Tailnet bind + token (legacy)
+
+```json5
+{
+  gateway: {
+    bind: "tailnet",
+    controlUi: { enabled: true }
+  }
+}
+```
+
+Then start the gateway (token required for non-loopback binds):
+
+```bash
+export CLAWDBOT_GATEWAY_TOKEN="…your token…"
+clawdbot gateway
+```
+
+Open:
+- `http://<tailscale-ip>:18789/` (or your configured `gateway.controlUi.basePath`)
+
+### Public internet (Funnel)
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "funnel" },
+    auth: { mode: "password" } // or CLAWDBOT_GATEWAY_PASSWORD
+  }
+}
+```
+
+## Security notes
+
+- Binding the Gateway to a non-loopback address **requires** auth (`CLAWDBOT_GATEWAY_TOKEN` or `gateway.auth`).
+- The UI sends `connect.params.auth.token` or `connect.params.auth.password`.
+- Use `gateway.auth.allowTailscale: false` to require explicit credentials even in Serve mode.
+- `gateway.tailscale.mode: "funnel"` requires `gateway.auth.mode: "password"` (shared password).
+
+## Building the UI
+
+The Gateway serves static files from `dist/control-ui`. Build them with:
+
+```bash
+pnpm ui:install
+pnpm ui:build
+```

package/docs/webchat.md

@@ -0,0 +1,34 @@
+---
+summary: "Loopback WebChat static host and Gateway WS usage for chat UI"
+read_when:
+  - Debugging or configuring WebChat access
+---
+# WebChat (SwiftUI + Gateway WS)
+
+Updated: 2025-12-17
+
+## What it is
+- A native SwiftUI chat UI (macOS app / iOS) that talks directly to the Gateway WebSocket.
+- No embedded browser/WKWebView and no bundled static WebChat HTTP server.
+- Data plane is entirely Gateway WS: methods `chat.history`, `chat.send`, `chat.abort`; events `chat`, `agent`, `presence`, `tick`, `health`.
+
+## How it connects
+- The UI performs Gateway WS `connect`, then calls `chat.history` for bootstrap and `chat.send` for sends; it listens to `chat/agent/presence/tick/health` events.
+- History comes from the Gateway via `chat.history` (no local session file watching).
+- If Gateway WS is unavailable, the UI surfaces the error and blocks send.
+
+## Remote use
+- In remote mode, the macOS app forwards the Gateway WebSocket control port via SSH and uses that for the SwiftUI chat UI.
+- You generally should not need to manage tunnels manually; see `RemoteTunnelManager` in the app.
+
+## Config
+- WebChat does not have a separate HTTP port/config anymore.
+- Gateway WS is configured via the app’s gateway endpoint settings (`GatewayEndpointStore`) or `clawdbot gateway --port` when running locally.
+
+## Failure handling
+- UI errors when the Gateway handshake fails or the WS drops.
+- No fallback transport; the Gateway WS is required.
+
+## Dev notes
+- macOS glue: `apps/macos/Sources/Clawdbot/WebChatSwiftUI.swift` + `apps/macos/Sources/Clawdbot/WebChatManager.swift`.
+- Remote tunnel helper: `apps/macos/Sources/Clawdbot/RemotePortTunnel.swift`.

package/docs/webhook.md

@@ -0,0 +1,132 @@
+---
+summary: "Webhook ingress for wake and isolated agent runs"
+read_when:
+  - Adding or changing webhook endpoints
+  - Wiring external systems into Clawdbot
+---
+
+# Webhooks
+
+Gateway can expose a small HTTP webhook surface for external triggers.
+
+## Enable
+
+```json5
+{
+  hooks: {
+    enabled: true,
+    token: "shared-secret",
+    path: "/hooks"
+  }
+}
+```
+
+Notes:
+- `hooks.token` is required when `hooks.enabled=true`.
+- `hooks.path` defaults to `/hooks`.
+
+## Auth
+
+Every request must include the hook token:
+- `Authorization: Bearer <token>`
+- or `x-clawdbot-token: <token>`
+- or `?token=<token>`
+
+## Endpoints
+
+### `POST /hooks/wake`
+
+Payload:
+```json
+{ "text": "System line", "mode": "now" }
+```
+
+- `text` required (string)
+- `mode` optional: `now` | `next-heartbeat` (default `now`)
+
+Effect:
+- Enqueues a system event for the **main** session
+- If `mode=now`, triggers an immediate heartbeat
+
+### `POST /hooks/agent`
+
+Payload:
+```json
+{
+  "message": "Run this",
+  "name": "Email",
+  "sessionKey": "hook:email:msg-123",
+  "wakeMode": "now",
+  "deliver": false,
+  "channel": "last",
+  "to": "+15551234567",
+  "thinking": "low",
+  "timeoutSeconds": 120
+}
+```
+
+- `message` required (string)
+- `name` optional (used in the summary prefix)
+- `sessionKey` optional (default random `hook:<uuid>`)
+- `wakeMode` optional: `now` | `next-heartbeat` (default `now`)
+- `deliver` optional (default `false`)
+- `channel` optional: `last` | `whatsapp` | `telegram`
+- `to` optional (channel-specific target)
+- `thinking` optional (override)
+- `timeoutSeconds` optional
+
+Effect:
+- Runs an **isolated** agent turn (own session key)
+- Always posts a summary into the **main** session
+- If `wakeMode=now`, triggers an immediate heartbeat
+
+### `POST /hooks/<name>` (mapped)
+
+Custom hook names are resolved via `hooks.mappings` (see configuration). A mapping can
+turn arbitrary payloads into `wake` or `agent` actions, with optional templates or
+code transforms.
+
+Mapping options (summary):
+- `hooks.presets: ["gmail"]` enables the built-in Gmail mapping.
+- `hooks.mappings` lets you define `match`, `action`, and templates in config.
+- `hooks.transformsDir` + `transform.module` loads a JS/TS module for custom logic.
+- Use `match.source` to keep a generic ingest endpoint (payload-driven routing).
+- TS transforms require a TS loader (e.g. `tsx`) or precompiled `.js` at runtime.
+- `clawdbot hooks gmail setup` writes `hooks.gmail` config for `clawdbot hooks gmail run`.
+
+## Responses
+
+- `200` for `/hooks/wake`
+- `202` for `/hooks/agent` (async run started)
+- `401` on auth failure
+- `400` on invalid payload
+- `413` on oversized payloads
+
+## Examples
+
+```bash
+curl -X POST http://127.0.0.1:18789/hooks/wake \
+  -H 'Authorization: Bearer SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"New email received","mode":"now"}'
+```
+
+```bash
+curl -X POST http://127.0.0.1:18789/hooks/agent \
+  -H 'x-clawdbot-token: SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'
+```
+
+```bash
+curl -X POST http://127.0.0.1:18789/hooks/gmail \
+  -H 'Authorization: Bearer SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'
+```
+
+## Security
+
+- Keep hook endpoints behind loopback, tailnet, or trusted reverse proxy.
+- Use a dedicated hook token; do not reuse gateway auth tokens.
+- Avoid including sensitive raw payloads in webhook logs.

package/docs/whatsapp.md

@@ -0,0 +1,142 @@
+---
+summary: "WhatsApp (web provider) integration: login, inbox, replies, media, and ops"
+read_when:
+  - Working on WhatsApp/web provider behavior or inbox routing
+---
+# WhatsApp (web provider)
+
+Updated: 2025-12-23
+
+Status: WhatsApp Web via Baileys only. Gateway owns the single session.
+
+## Goals
+- One WhatsApp identity, one gateway session.
+- Deterministic routing: replies return to WhatsApp, no model routing.
+- Model sees enough context to understand quoted replies.
+
+## Architecture (who owns what)
+- **Gateway** owns the Baileys socket and inbox loop.
+- **CLI / macOS app** talk to the gateway; no direct Baileys use.
+- **Active listener** is required for outbound sends; otherwise send fails fast.
+
+## Getting a phone number
+
+WhatsApp requires a real mobile number for verification. VoIP and virtual numbers are usually blocked.
+
+**Recommended approaches:**
+- **Local eSIM** from your country's mobile carrier (most reliable)
+  - Austria: [hot.at](https://www.hot.at)
+  - UK: [giffgaff](https://www.giffgaff.com) — free SIM, no contract
+- **Prepaid SIM** — cheap, just needs to receive one SMS for verification
+
+**Avoid:** TextNow, Google Voice, most "free SMS" services — WhatsApp blocks these aggressively.
+
+**Tip:** The number only needs to receive one verification SMS. After that, WhatsApp Web sessions persist via `creds.json`.
+
+## Login + credentials
+- Login command: `clawdbot login` (QR via Linked Devices).
+- Credentials stored in `~/.clawdbot/credentials/creds.json`.
+- Backup copy at `creds.json.bak` (restored on corruption).
+- Logout: `clawdbot logout` deletes creds and session store.
+- Logged-out socket => error instructs re-link.
+
+## Inbound flow (DM + group)
+- WhatsApp events come from `messages.upsert` (Baileys).
+- Inbox listeners are detached on shutdown to avoid accumulating event handlers in tests/restarts.
+- Status/broadcast chats are ignored.
+- Direct chats use E.164; groups use group JID.
+- **Allowlist**: `whatsapp.allowFrom` enforced for direct chats only.
+  - If `whatsapp.allowFrom` is empty, default allowlist = self number (self-chat mode).
+- **Self-chat mode**: avoids auto read receipts and ignores mention JIDs.
+- Read receipts sent for non-self-chat DMs.
+
+## Message normalization (what the model sees)
+- `Body` is the current message body with envelope.
+- Quoted reply context is **always appended**:
+  ```
+  [Replying to +1555 id:ABC123]
+  <quoted text or <media:...>>
+  [/Replying]
+  ```
+- Reply metadata also set:
+  - `ReplyToId` = stanzaId
+  - `ReplyToBody` = quoted body or media placeholder
+  - `ReplyToSender` = E.164 when known
+- Media-only inbound messages use placeholders:
+  - `<media:image|video|audio|document|sticker>`
+
+## Groups
+- Groups map to `whatsapp:group:<jid>` sessions.
+- Activation modes:
+  - `mention` (default): requires @mention or regex match.
+  - `always`: always triggers.
+- `/activation mention|always` is owner-only.
+- Owner = `whatsapp.allowFrom` (or self E.164 if unset).
+- **History injection**:
+  - Recent messages (default 50) inserted under:
+    `[Chat messages since your last reply - for context]`
+  - Current message under:
+    `[Current message - respond to this]`
+  - Sender suffix appended: `[from: Name (+E164)]`
+- Group metadata cached 5 min (subject + participants).
+
+## Reply delivery (threading)
+- WhatsApp Web sends standard messages (no quoted reply threading in the current gateway).
+- Reply tags are ignored on this surface.
+
+## Outbound send (text + media)
+- Uses active web listener; error if gateway not running.
+- Text chunking: 4k max per message.
+- Media:
+  - Image/video/audio/document supported.
+  - Audio sent as PTT; `audio/ogg` => `audio/ogg; codecs=opus`.
+  - Caption only on first media item.
+  - Media fetch supports HTTP(S) and local paths.
+  - Animated GIFs: WhatsApp expects MP4 with `gifPlayback: true` for inline looping.
+    - CLI: `clawdbot send --media <mp4> --gif-playback`
+    - Gateway: `send` params include `gifPlayback: true`
+
+## Media limits + optimization
+- Default cap: 5 MB (per media item).
+- Override: `agent.mediaMaxMb`.
+- Images are auto-optimized to JPEG under cap (resize + quality sweep).
+- Oversize media => error; media reply falls back to text warning.
+
+## Heartbeats
+- **Gateway heartbeat** logs connection health (`web.heartbeatSeconds`, default 60s).
+- **Agent heartbeat** is global (`agent.heartbeat.*`) and runs in the main session.
+  - Uses `HEARTBEAT` prompt + `HEARTBEAT_OK` skip behavior.
+  - Delivery defaults to the last used channel (or configured target).
+
+## Reconnect behavior
+- Backoff policy: `web.reconnect`:
+  - `initialMs`, `maxMs`, `factor`, `jitter`, `maxAttempts`.
+- If maxAttempts reached, web monitoring stops (degraded).
+- Logged-out => stop and require re-link.
+
+## Config quick map
+- `whatsapp.allowFrom` (DM allowlist).
+- `whatsapp.groups` (group mention gating defaults/overrides)
+- `routing.groupChat.mentionPatterns`
+- `routing.groupChat.historyLimit`
+- `messages.messagePrefix` (inbound prefix)
+- `messages.responsePrefix` (outbound prefix)
+- `agent.mediaMaxMb`
+- `agent.heartbeat.every`
+- `agent.heartbeat.model` (optional override)
+- `agent.heartbeat.target`
+- `agent.heartbeat.to`
+- `session.*` (scope, idle, store; `mainKey` is ignored)
+- `web.enabled` (disable provider startup when false)
+- `web.heartbeatSeconds`
+- `web.reconnect.*`
+
+## Logs + troubleshooting
+- Subsystems: `whatsapp/inbound`, `whatsapp/outbound`, `web-heartbeat`, `web-reconnect`.
+- Log file: `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (configurable).
+- Troubleshooting guide: `docs/refactor/web-gateway-troubleshooting.md`.
+
+## Tests
+- `src/web/auto-reply.test.ts` (mention gating, history injection, reply flow)
+- `src/web/monitor-inbox.test.ts` (inbound parsing + reply context)
+- `src/web/outbound.test.ts` (send mapping + media)

package/docs/wizard.md

@@ -0,0 +1,158 @@
+---
+summary: "CLI onboarding wizard: guided setup for gateway, workspace, providers, and skills"
+read_when:
+  - Running or configuring the onboarding wizard
+  - Setting up a new machine
+---
+
+# Onboarding Wizard (CLI)
+
+The onboarding wizard is the **recommended** way to set up Clawdbot on any OS.
+It configures a local Gateway or a remote Gateway connection, plus providers, skills,
+and workspace defaults in one guided flow.
+
+Primary entrypoint:
+
+```bash
+clawdbot onboard
+```
+
+Follow‑up reconfiguration:
+
+```bash
+clawdbot configure
+```
+
+## What the wizard does
+
+**Local mode (default)** walks you through:
+- Model/auth (Anthropic OAuth recommended, API key optional, Minimax M2.1 via LM Studio)
+- Workspace location + bootstrap files
+- Gateway settings (port/bind/auth/tailscale)
+- Providers (WhatsApp, Telegram, Discord, Signal)
+- Daemon install (LaunchAgent / systemd user unit / Scheduled Task)
+- Health check
+- Skills (recommended)
+
+**Remote mode** only configures the local client to connect to a Gateway elsewhere.
+It does **not** install or change anything on the remote host.
+
+## Flow details (local)
+
+1) **Existing config detection**
+   - If `~/.clawdbot/clawdbot.json` exists, choose **Keep / Modify / Reset**.
+   - Reset uses `trash` (never `rm`) and offers scopes:
+     - Config only
+     - Config + credentials + sessions
+     - Full reset (also removes workspace)
+
+2) **Model/Auth**
+   - **Anthropic OAuth (recommended)**: browser flow; paste the `code#state`.
+   - **API key**: stores the key for you.
+   - **Minimax M2.1 (LM Studio)**: config is auto‑written for the LM Studio endpoint.
+   - **Skip**: no auth configured yet.
+
+3) **Workspace**
+   - Default `~/clawd` (configurable).
+   - Seeds the workspace files needed for the agent bootstrap ritual.
+
+4) **Gateway**
+   - Port, bind, auth mode, tailscale exposure.
+   - Auth recommendation: keep **Off** for single-machine loopback setups. Use **Token** for multi-machine access or non-loopback binds.
+   - Non‑loopback binds require auth.
+
+5) **Providers**
+   - WhatsApp: optional QR login.
+   - Telegram: bot token.
+   - Discord: bot token.
+   - Signal: optional `signal-cli` install + account config.
+   - iMessage: local `imsg` CLI path + DB access.
+
+6) **Daemon install**
+   - macOS: LaunchAgent
+   - Linux: systemd user unit
+   - Windows: Scheduled Task
+
+7) **Health check**
+   - Starts the Gateway (if needed) and runs `clawdbot health`.
+
+8) **Skills (recommended)**
+   - Reads the available skills and checks requirements.
+   - Lets you choose a node manager: **npm / pnpm / bun**.
+   - Installs optional dependencies (some use Homebrew on macOS).
+
+9) **Finish**
+   - Summary + next steps, including iOS/Android/macOS apps for extra features.
+   - If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
+
+## Remote mode
+
+Remote mode configures a local client to connect to a Gateway elsewhere.
+
+What you’ll set:
+- Remote Gateway URL (`ws://...`)
+- Optional token
+
+Notes:
+- No remote installs or daemon changes are performed.
+- If the Gateway is loopback‑only, use SSH tunneling or a tailnet.
+- Discovery hints:
+  - macOS: Bonjour (`dns-sd`)
+  - Linux: Avahi (`avahi-browse`)
+
+## Non‑interactive mode
+
+Use `--non-interactive` to automate or script onboarding:
+
+```bash
+clawdbot onboard --non-interactive \
+  --mode local \
+  --auth-choice apiKey \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback \
+  --skip-skills
+```
+
+Add `--json` for a machine‑readable summary.
+
+## Gateway wizard RPC
+
+The Gateway exposes the wizard flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).
+Clients (macOS app, Control UI) can render steps without re‑implementing onboarding logic.
+
+## Signal setup (signal-cli)
+
+The wizard can install `signal-cli` from GitHub releases:
+- Downloads the appropriate release asset.
+- Stores it under `~/.clawdbot/tools/signal-cli/<version>/`.
+- Writes `signal.cliPath` to your config.
+
+Notes:
+- JVM builds require **Java 21**.
+- Native builds are used when available.
+- Windows auto‑install is not supported yet (manual install required).
+
+## What the wizard writes
+
+Typical fields in `~/.clawdbot/clawdbot.json`:
+- `agent.workspace`
+- `agent.model` / `models.providers` (if Minimax chosen)
+- `gateway.*` (mode, bind, auth, tailscale)
+- `telegram.botToken`, `discord.token`, `signal.*`, `imessage.*`
+- `skills.install.nodeManager`
+- `wizard.lastRunAt`
+- `wizard.lastRunVersion`
+- `wizard.lastRunCommit`
+- `wizard.lastRunCommand`
+- `wizard.lastRunMode`
+
+WhatsApp credentials go to `~/.clawdbot/credentials/`.
+Sessions are stored under `~/.clawdbot/sessions/`.
+
+## Related docs
+
+- macOS app onboarding: `docs/onboarding.md`
+- Config reference: `docs/configuration.md`
+- Providers: `docs/whatsapp.md`, `docs/telegram.md`, `docs/discord.md`, `docs/signal.md`, `docs/imessage.md`
+- Skills: `docs/skills.md`, `docs/skills-config.md`