chore: update appcast for 2026.1.11

Agents: add Claude Code parameter aliasing for read/write/edit tools

.github/workflows/install-smoke.yml

@@ -0,0 +1,32 @@
+name: Install Smoke
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  install-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout CLI
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 10
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Install pnpm deps (minimal)
+        run: pnpm install --ignore-scripts --frozen-lockfile
+
+      - name: Run installer docker tests
+        env:
+          CLAWDBOT_INSTALL_URL: https://clawd.bot/install.sh
+          CLAWDBOT_INSTALL_CLI_URL: https://clawd.bot/install-cli.sh
+          CLAWDBOT_NO_ONBOARD: "1"
+          CLAWDBOT_INSTALL_SMOKE_SKIP_CLI: "1"
+        run: pnpm test:install:smoke

AGENTS.md

@@ -4,6 +4,7 @@
 - Source code: `src/` (CLI wiring in `src/cli`, commands in `src/commands`, web provider in `src/provider-web.ts`, infra in `src/infra`, media pipeline in `src/media`).
 - Tests: colocated `*.test.ts`.
 - Docs: `docs/` (images, queue, Pi config). Built output lives in `dist/`.
+- Installers served from `https://clawd.bot/*`: live in the sibling repo `../clawd.bot` (`public/install.sh`, `public/install-cli.sh`, `public/install.ps1`).
 
 ## Docs Linking (Mintlify)
 - Docs are hosted on Mintlify (docs.clawd.bot).
@@ -11,6 +12,7 @@
 - Section cross-references: use anchors on root-relative paths (example: `[Hooks](/configuration#hooks)`).
 - When Peter asks for links, reply with full `https://docs.clawd.bot/...` URLs (not root-relative).
 - README (GitHub): keep absolute docs URLs (`https://docs.clawd.bot/...`) so links work on GitHub.
+- Docs content must be generic: no personal device names/hostnames/paths; use placeholders like `user@gateway-host` and “gateway host”.
 
 ## Build, Test, and Development Commands
 - Runtime baseline: Node **22+** (keep Node + Bun paths working).
@@ -61,6 +63,7 @@
 ## Security & Configuration Tips
 - Web provider stores creds at `~/.clawdbot/credentials/`; rerun `clawdbot login` if logged out.
 - Pi sessions live under `~/.clawdbot/sessions/` by default; the base directory is not configurable.
+- Environment variables: see `~/.profile`.
 - Never commit or publish real phone numbers, videos, or live configuration values. Use obviously fake placeholders in docs, tests, and examples.
 
 ## Troubleshooting

CHANGELOG.md

@@ -1,12 +1,121 @@
 # Changelog
 
+## 2026.1.11
+
+### Highlights
+- Plugins are now first-class: loader + CLI management, plus the new Voice Call plugin.
+- Config: modular `$include` support for split config files. (#731) — thanks @pasogott.
+- Agents/Pi: reserve compaction headroom so pre-compaction memory writes can run before auto-compaction.
+- Agents: automatic pre-compaction memory flush turn to store durable memories before compaction.
+
+### Changes
+- Deps: update pi-agent-core/pi-ai/pi-coding-agent/pi-tui and refresh the pi-ai patch.
+- Dev: bump @types/node.
+- macOS: add wizard debug CLI and share wizard parsing helpers.
+- CLI/Onboarding: simplify MiniMax auth choice to a single M2.1 option.
+- CLI: configure section selection now loops until Continue.
+- Docs: explain MiniMax vs MiniMax Lightning (speed vs cost) and restore LM Studio example.
+- Docs: add Cerebras GLM 4.6/4.7 config example (OpenAI-compatible endpoint).
+- Onboarding/CLI: group model/auth choice by provider and label Z.AI as GLM 4.7.
+- Onboarding/Docs: add Moonshot AI (Kimi K2) auth choice + config example.
+- CLI/Onboarding: prompt to reuse detected API keys for Moonshot/MiniMax/Z.AI/Gemini/Anthropic/OpenCode.
+- CLI/Onboarding: move MiniMax to the top of the provider list.
+- CLI/Onboarding: add MiniMax M2.1 Lightning auth choice.
+- CLI/Onboarding: show key previews when reusing detected API keys.
+- Auto-reply: add compact `/model` picker (models + available providers) and show provider endpoints in `/model status`.
+- Control UI: add Config tab model presets (MiniMax M2.1, GLM 4.7, Kimi) for one-click setup.
+- Plugins: add extension loader (tools/RPC/CLI/services), discovery paths, and config schema + Control UI labels (uiHints).
+- Plugins: add `clawdbot plugins install` (path/tgz/npm), plus `list|info|enable|disable|doctor` UX.
+- Plugins: voice-call plugin now real (Twilio/log), adds start/status RPC/CLI/tool + tests.
+- Docs: add plugins doc + cross-links from tools/skills/gateway config.
+- Docs: clarify memory flush behavior + writable workspace requirement in Memory/Session/FAQ.
+- Docs: add beginner-friendly plugin quick start + expand Voice Call plugin docs.
+- Tests: add Docker plugin loader + tgz-install smoke test.
+- Tests: extend Docker plugin E2E to cover installing from local folders (`plugins.load.paths`) and `file:` npm specs.
+- Tests: add coverage for pre-compaction memory flush settings (including read-only/CLI skips).
+- Tests: modernize live model smoke selection for current releases and enforce tools/images/thinking-high coverage. (#769) — thanks @steipete.
+- Agents/Tools: add `apply_patch` tool for multi-file edits (experimental; gated by tools.exec.applyPatch; OpenAI-only).
+- Agents/Tools: rename the bash tool to exec (config alias maintained). (#748) — thanks @myfunc.
+- Agents: add pre-compaction memory flush config (`agents.defaults.compaction.*`) with a soft threshold + system prompt.
+- Config: add `$include` directive for modular config files. (#731) — thanks @pasogott.
+- Build: set pnpm minimum release age to 2880 minutes (2 days). (#718) — thanks @dan-dr.
+- macOS: prompt to install the global `clawdbot` CLI when missing in local mode; install via `clawd.bot/install-cli.sh` (no onboarding) and use external launchd/CLI instead of the embedded gateway runtime.
+- Docs: add gog calendar event color IDs from `gog calendar colors`. (#715) — thanks @mjrussell.
+- Cron/CLI: add `--model` flag to cron add/edit commands. (#711) — thanks @mjrussell.
+- Cron/CLI: trim model overrides on cron edits and document main-session guidance. (#711) — thanks @mjrussell.
+- Skills: bundle `skill-creator` to guide creating and packaging skills.
+- Providers: add per-DM history limit overrides (`dmHistoryLimit`) with provider-level config. (#728) — thanks @pkrmf.
+- Discord: expose channel/category management actions in the message tool. (#730) — thanks @NicholasSpisak.
+- Docs: rename README “macOS app” section to “Apps”. (#733) — thanks @AbhisekBasu1.
+- Gateway: require `client.id` in WebSocket connect params; use `client.instanceId` for presence de-dupe; update docs/tests.
+- macOS: remove the attach-only gateway setting; local mode now always manages launchd while still attaching to an existing gateway if present.
+
+### Installer
+- Postinstall: replace `git apply` with builtin JS patcher (works npm/pnpm/bun; no git dependency) plus regression tests.
+- Postinstall: skip pnpm patch fallback when the new patcher is active.
+- Installer tests: add root+non-root docker smokes, CI workflow to fetch clawd.bot scripts and run install sh/cli with onboarding skipped.
+- Installer UX: support `CLAWDBOT_NO_ONBOARD=1` for non-interactive installs; fix npm prefix on Linux and auto-install git.
+- Installer UX: add `install.sh --help` with flags/env and git install hint.
+- Installer UX: add `--install-method git|npm` and auto-detect source checkouts (prompt to update git checkout vs migrate to npm).
+
+### Fixes
+- Control UI: flatten nav into a single horizontal scroll row on tablet/mobile (and always show collapsed group items). (#771) — thanks @carlulsoe.
+- macOS: start + await local gateway before onboarding wizard begins.
+- macOS: cancel onboarding wizard on close, recover if the gateway drops the session, and time out stalled gateway connects.
+- macOS: wizard debug CLI now surfaces error status instead of exiting as complete.
+- Models/Onboarding: configure MiniMax (minimax.io) via Anthropic-compatible `/anthropic` endpoint by default (keep `minimax-api` as a legacy alias).
+- Agents/Browser: cap Playwright AI snapshots for tool calls (maxChars); CLI snapshots remain full. (#763) — thanks @thesash.
+- Models: normalize Gemini 3 Pro/Flash IDs to preview names for live model lookups. (#769) — thanks @steipete.
+- CLI: fix guardCancel typing for configure prompts. (#769) — thanks @steipete.
+- Providers: default groupPolicy to allowlist across providers and warn in doctor when groups are open.
+- MS Teams: add groupPolicy/groupAllowFrom gating for group chats and warn when groups are open.
+- Providers: strip tool call/result ids from Gemini CLI payloads to avoid API 400s. (#756)
+- Gateway/WebChat: include handshake validation details in the WebSocket close reason for easier debugging; preserve close codes.
+- Gateway/Auth: send invalid connect responses before closing the handshake; stabilize invalid-connect auth test.
+- Gateway: tighten gateway listener detection.
+- Control UI: hide onboarding chat when configured and guard the mobile chat sidebar overlay.
+- Auth: read Codex keychain credentials and make the lookup platform-aware.
+- macOS/Release: avoid bundling dist artifacts in relay builds and generate appcasts from zip-only sources.
+- Doctor: surface plugin diagnostics in the report.
+- Plugins: treat `plugins.load.paths` directory entries as package roots when they contain `package.json` + `clawdbot.extensions`; load plugin packages from config dirs; extract archives without system tar.
+- Config: expand `~` in `CLAWDBOT_CONFIG_PATH` and common path-like config fields (including `plugins.load.paths`); guard invalid `$include` paths. (#731) — thanks @pasogott.
+- Agents: stop pre-creating session transcripts so first user messages persist in JSONL history.
+- Agents: skip pre-compaction memory flush when the session workspace is read-only.
+- Auto-reply: allow inline `/status` for allowlisted senders (stripped before the model); unauthorized senders see it as plain text.
+- Auto-reply: include config-only allowlisted models in `/model` even when the catalog is partial.
+- Auto-reply: allow fuzzy `/model` matches (e.g. `/model kimi` or `/model moonshot/kimi`) when unambiguous.
+- Auto-reply: ignore inline `/status` directives unless the message is directive-only.
+- CLI/Configure: enter the selected section immediately, then return to the section picker.
+- CLI/Configure: apply the chosen auth model as default (skip the extra picker) and refresh the model catalog for new providers.
+- Auto-reply: align `/think` default display with model reasoning defaults. (#751) — thanks @gabriel-trigo.
+- Auto-reply: flush block reply buffers on tool boundaries. (#750) — thanks @sebslight.
+- Auto-reply: allow sender fallback for command authorization when `SenderId` is empty (WhatsApp self-chat). (#755) — thanks @juanpablodlc.
+- Heartbeat: refresh prompt text for updated defaults.
+- Agents/Tools: use PowerShell on Windows to capture system utility output. (#748) — thanks @myfunc.
+- Agents/Tools: normalize Claude Code-style read/write/edit params (file_path/old_string/new_string) and keep sandbox guards in place. (#768) — thanks @hsrvc.
+- Docker: tolerate unset optional env vars in docker-setup.sh under strict mode. (#725) — thanks @petradonka.
+- CLI/Update: preserve base environment when passing overrides to update subprocesses. (#713) — thanks @danielz1z.
+- Agents: treat message tool errors as failures so fallback replies still send; require `to` + `message` for `action=send`. (#717) — thanks @theglove44.
+- Agents: preserve reasoning items on tool-only turns.
+- Agents: enforce `<final>` gating for reasoning-tag providers to prevent tag/reasoning leaks. (#754) — thanks @mcinteerj.
+- Agents/Subagents: wait for completion before announcing, align wait timeout with run timeout, and make announce prompts more emphatic.
+- Agents: route subagent transcripts to the target agent sessions directory and add regression coverage. (#708) — thanks @xMikeMickelson.
+- Agents/Tools: preserve action enums when flattening tool schemas. (#708) — thanks @xMikeMickelson.
+- Gateway/Agents: canonicalize main session aliases for store writes and add regression coverage. (#709) — thanks @xMikeMickelson.
+- Agents: reset sessions and retry when auto-compaction overflows instead of crashing the gateway.
+- Providers/Telegram: normalize command mentions for consistent parsing. (#729) — thanks @obviyus.
+- Providers: skip DM history limit handling for non-DM sessions. (#728) — thanks @pkrmf.
+- Sandbox: fix non-main mode incorrectly sandboxing the main DM session and align `/status` runtime reporting with effective sandbox state.
+- Sandbox/Gateway: treat `agent:<id>:main` as a main-session alias when `session.mainKey` is customized (backwards compatible).
+- Auto-reply: fast-path allowlisted slash commands (inline `/help`/`/commands`/`/status`/`/whoami` stripped before model).
+
 ## 2026.1.10
 
 ### Highlights
 - CLI: `clawdbot status` now table-based + shows OS/update/gateway/daemon/agents/sessions; `status --all` adds a full read-only debug report (tables, log tails, Tailscale summary, and scan progress via OSC-9 + spinner).
 - CLI Backends: add Codex CLI fallback with resume support (text output) and JSONL parsing for new runs, plus a live CLI resume probe.
 - CLI: add `clawdbot update` (safe-ish git checkout update) + `--update` shorthand. (#673) — thanks @fm1randa.
-- Gateway: add OpenAI-compatible `/v1/chat/completions` HTTP endpoint (auth, SSE streaming, per-agent routing). (#680) — thanks @steipete.
+- Gateway: add OpenAI-compatible `/v1/chat/completions` HTTP endpoint (auth, SSE streaming, per-agent routing). (#680).
 
 ### Changes
 - Onboarding/Models: add first-class Z.AI (GLM) auth choice (`zai-api-key`) + `--zai-api-key` flag.
@@ -15,21 +124,26 @@
 - Agents/Browser: add `browser.target` (sandbox/host/custom) with sandbox host-control gating via `agents.defaults.sandbox.browser.allowHostControl`, allowlists for custom control URLs/hosts/ports, and expand browser tool docs (remote control, profiles, internals).
 - Onboarding/Models: add catalog-backed default model picker to onboarding + configure. (#611) — thanks @jonasjancarik.
 - Agents/OpenCode Zen: update fallback models + defaults, keep legacy alias mappings. (#669) — thanks @magimetal.
-- Providers: unify group history context wrappers across providers with per-provider/per-account `historyLimit` overrides (fallback to `messages.groupChat.historyLimit`). Set `0` to disable. (#672) — thanks @steipete.
+- CLI: add `clawdbot reset` and `clawdbot uninstall` flows (interactive + non-interactive) plus docker cleanup smoke test.
+- Providers: move provider wiring to a plugin architecture. (#661).
+- Providers: unify group history context wrappers across providers with per-provider/per-account `historyLimit` overrides (fallback to `messages.groupChat.historyLimit`). Set `0` to disable. (#672).
 - Gateway/Heartbeat: optionally deliver heartbeat `Reasoning:` output (`agents.defaults.heartbeat.includeReasoning`). (#690)
 - Docker: allow optional home volume + extra bind mounts in `docker-setup.sh`. (#679) — thanks @gabriel-trigo.
 
 ### Fixes
+- Auto-reply: suppress draft/typing streaming for `NO_REPLY` (silent system ops) so it doesn’t leak partial output.
 - CLI/Status: expand tables to full terminal width; clarify provider setup vs runtime warnings; richer per-provider detail; token previews in `status` while keeping `status --all` redacted; add troubleshooting link footer; keep log tails pasteable; show gateway auth used when reachable; surface provider runtime errors (Signal/iMessage/Slack); harden `tailscale status --json` parsing; make `status --all` scan progress determinate; and replace the footer with a 3-line “Next steps” recommendation (share/debug/probe).
 - CLI/Gateway: clarify that `clawdbot gateway status` reports RPC health (connect + RPC) and shows RPC failures separately from connect failures.
 - CLI/Update: gate progress spinner on stdout TTY and align clean-check step label. (#701) — thanks @bjesuiter.
 - Telegram: add `/whoami` + `/id` commands to reveal sender id for allowlists; allow `@username` and prefixed ids in `allowFrom` prompts (with stability warning).
+- Heartbeat: strip markup-wrapped `HEARTBEAT_OK` so acks don’t leak to external providers (e.g., Telegram).
 - Control UI: stop auto-writing `telegram.groups["*"]` and warn/confirm before enabling wildcard groups.
 - WhatsApp: send ack reactions only for handled messages and ignore legacy `messages.ackReaction` (doctor copies to `whatsapp.ackReaction`). (#629) — thanks @pasogott.
 - Sandbox/Skills: mirror skills into sandbox workspaces for read-only mounts so SKILL.md stays accessible.
 - Terminal/Table: ANSI-safe wrapping to prevent table clipping/color loss; add regression coverage.
 - Docker: allow optional apt packages during image build and document the build arg. (#697) — thanks @gabriel-trigo.
 - Gateway/Heartbeat: deliver reasoning even when the main heartbeat reply is `HEARTBEAT_OK`. (#694) — thanks @antons.
+- Agents/Pi: inject config `temperature`/`maxTokens` into streaming without replacing the session streamFn; cover with live maxTokens probe. (#732) — thanks @peschee.
 - macOS: clear unsigned launchd overrides on signed restarts and warn via doctor when attach-only/disable markers are set. (#695) — thanks @jeffersonwarrior.
 - Agents: enforce single-writer session locks and drop orphan tool results to prevent tool-call ID failures (MiniMax/Anthropic-compatible APIs).
 - Docs: make `clawdbot status` the first diagnostic step, clarify `status --deep` behavior, and document `/whoami` + `/id`.
@@ -80,6 +194,7 @@
 - Telegram: add `telegram.draftChunk` to tune draft streaming chunking for `streamMode: "block"`. (#667) — thanks @rubyrunsstuff.
 - Tests/Agents: add regression coverage for workspace tool path resolution and bash cwd defaults.
 - iOS/Android: enable stricter concurrency/lint checks; fix Swift 6 strict concurrency issues + Android lint errors (ExifInterface, obsolete SDK check). (#662) — thanks @KristijanJovanovski.
+- Auth: read Codex CLI keychain tokens on macOS before falling back to `~/.codex/auth.json`, preventing stale refresh tokens from breaking gateway live tests.
 - iOS/macOS: share `AsyncTimeout`, require explicit `bridgeStableID` on connect, and harden tool display defaults (avoids missing-resource label fallbacks).
 - Telegram: serialize media-group processing to avoid missed albums under load.
 - Signal: handle `dataMessage.reaction` events (signal-cli SSE) to avoid broken attachment errors. (#637) — thanks @neist.

README.md

@@ -20,22 +20,22 @@ It answers you on the providers you already use (WhatsApp, Telegram, Slack, Disc
 
 If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.
 
-[Website](https://clawdbot.com) · [Docs](https://docs.clawd.bot) · [Getting Started](https://docs.clawd.bot/getting-started) · [Updating](https://docs.clawd.bot/updating) · [Showcase](https://docs.clawd.bot/showcase) · [FAQ](https://docs.clawd.bot/faq) · [Wizard](https://docs.clawd.bot/wizard) · [Nix](https://github.com/clawdbot/nix-clawdbot) · [Docker](https://docs.clawd.bot/docker) · [Discord](https://discord.gg/clawd)
+[Website](https://clawdbot.com) · [Docs](https://docs.clawd.bot) · [Getting Started](https://docs.clawd.bot/start/getting-started) · [Updating](https://docs.clawd.bot/install/updating) · [Showcase](https://docs.clawd.bot/start/showcase) · [FAQ](https://docs.clawd.bot/start/faq) · [Wizard](https://docs.clawd.bot/start/wizard) · [Nix](https://github.com/clawdbot/nix-clawdbot) · [Docker](https://docs.clawd.bot/install/docker) · [Discord](https://discord.gg/clawd)
 
 Preferred setup: run the onboarding wizard (`clawdbot onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Linux, and Windows (via WSL2; strongly recommended)**.
 Works with npm, pnpm, or bun.
-New install? Start here: [Getting started](https://docs.clawd.bot/getting-started)
+New install? Start here: [Getting started](https://docs.clawd.bot/start/getting-started)
 
 **Subscriptions (OAuth):**
 - **[Anthropic](https://www.anthropic.com/)** (Claude Pro/Max)
 - **[OpenAI](https://openai.com/)** (ChatGPT/Codex)
 
-Model note: while any model is supported, I strongly recommend **Anthropic Pro/Max (100/200) + Opus 4.5** for long‑context strength and better prompt‑injection resistance. See [Onboarding](https://docs.clawd.bot/onboarding).
+Model note: while any model is supported, I strongly recommend **Anthropic Pro/Max (100/200) + Opus 4.5** for long‑context strength and better prompt‑injection resistance. See [Onboarding](https://docs.clawd.bot/start/onboarding).
 
 ## Models (selection + auth)
 
-- Models config + CLI: [Models](https://docs.clawd.bot/models)
-- Auth profile rotation (OAuth vs API keys) + fallbacks: [Model failover](https://docs.clawd.bot/model-failover)
+- Models config + CLI: [Models](https://docs.clawd.bot/concepts/models)
+- Auth profile rotation (OAuth vs API keys) + fallbacks: [Model failover](https://docs.clawd.bot/concepts/model-failover)
 
 ## Install (recommended)
 
@@ -54,7 +54,7 @@ The wizard installs the Gateway daemon (launchd/systemd user service) so it stay
 
 Runtime: **Node ≥22**.
 
-Full beginner guide (auth, pairing, providers): [Getting started](https://docs.clawd.bot/getting-started)
+Full beginner guide (auth, pairing, providers): [Getting started](https://docs.clawd.bot/start/getting-started)
 
 ```bash
 clawdbot onboard --install-daemon
@@ -68,7 +68,7 @@ clawdbot message send --to +1234567890 --message "Hello from Clawdbot"
 clawdbot agent --message "Ship checklist" --thinking high
 ```
 
-Upgrading? [Updating guide](https://docs.clawd.bot/updating) (and run `clawdbot doctor`).
+Upgrading? [Updating guide](https://docs.clawd.bot/install/updating) (and run `clawdbot doctor`).
 
 ## From source (development)
 
@@ -94,7 +94,7 @@ Note: `pnpm clawdbot ...` runs TypeScript directly (via `tsx`). `pnpm build` pro
 
 Clawdbot connects to real messaging surfaces. Treat inbound DMs as **untrusted input**.
 
-Full security guide: [Security](https://docs.clawd.bot/security)
+Full security guide: [Security](https://docs.clawd.bot/gateway/security)
 
 Default behavior on Telegram/WhatsApp/Signal/iMessage/Discord/Slack:
 - **DM pairing** (`dmPolicy="pairing"` / `discord.dm.policy="pairing"` / `slack.dm.policy="pairing"`): unknown senders receive a short pairing code and the bot does not process their message.
@@ -106,51 +106,51 @@ Run `clawdbot doctor` to surface risky/misconfigured DM policies.
 ## Highlights
 
 - **[Local-first Gateway](https://docs.clawd.bot/gateway)** — single control plane for sessions, providers, tools, and events.
-- **[Multi-provider inbox](https://docs.clawd.bot/surface)** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat, macOS, iOS/Android.
-- **[Multi-agent routing](https://docs.clawd.bot/configuration)** — route inbound providers/accounts/peers to isolated agents (workspaces + per-agent sessions).
-- **[Voice Wake](https://docs.clawd.bot/voicewake) + [Talk Mode](https://docs.clawd.bot/talk)** — always-on speech for macOS/iOS/Android with ElevenLabs.
-- **[Live Canvas](https://docs.clawd.bot/mac/canvas)** — agent-driven visual workspace with [A2UI](https://docs.clawd.bot/mac/canvas#canvas-a2ui).
+- **[Multi-provider inbox](https://docs.clawd.bot/providers)** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat, macOS, iOS/Android.
+- **[Multi-agent routing](https://docs.clawd.bot/gateway/configuration)** — route inbound providers/accounts/peers to isolated agents (workspaces + per-agent sessions).
+- **[Voice Wake](https://docs.clawd.bot/nodes/voicewake) + [Talk Mode](https://docs.clawd.bot/nodes/talk)** — always-on speech for macOS/iOS/Android with ElevenLabs.
+- **[Live Canvas](https://docs.clawd.bot/platforms/mac/canvas)** — agent-driven visual workspace with [A2UI](https://docs.clawd.bot/platforms/mac/canvas#canvas-a2ui).
 - **[First-class tools](https://docs.clawd.bot/tools)** — browser, canvas, nodes, cron, sessions, and Discord/Slack actions.
-- **[Companion apps](https://docs.clawd.bot/macos)** — macOS menu bar app + iOS/Android [nodes](https://docs.clawd.bot/nodes).
-- **[Onboarding](https://docs.clawd.bot/wizard) + [skills](https://docs.clawd.bot/skills)** — wizard-driven setup with bundled/managed/workspace skills.
+- **[Companion apps](https://docs.clawd.bot/platforms/macos)** — macOS menu bar app + iOS/Android [nodes](https://docs.clawd.bot/nodes).
+- **[Onboarding](https://docs.clawd.bot/start/wizard) + [skills](https://docs.clawd.bot/tools/skills)** — wizard-driven setup with bundled/managed/workspace skills.
 
 ## Everything we built so far
 
 ### Core platform
-- [Gateway WS control plane](https://docs.clawd.bot/gateway) with sessions, presence, config, cron, webhooks, [Control UI](https://docs.clawd.bot/web), and [Canvas host](https://docs.clawd.bot/mac/canvas#canvas-a2ui).
-- [CLI surface](https://docs.clawd.bot/agent-send): gateway, agent, send, [wizard](https://docs.clawd.bot/wizard), and [doctor](https://docs.clawd.bot/doctor).
-- [Pi agent runtime](https://docs.clawd.bot/agent) in RPC mode with tool streaming and block streaming.
-- [Session model](https://docs.clawd.bot/session): `main` for direct chats, group isolation, activation modes, queue modes, reply-back. Group rules: [Groups](https://docs.clawd.bot/groups).
-- [Media pipeline](https://docs.clawd.bot/images): images/audio/video, transcription hooks, size caps, temp file lifecycle. Audio details: [Audio](https://docs.clawd.bot/audio).
+- [Gateway WS control plane](https://docs.clawd.bot/gateway) with sessions, presence, config, cron, webhooks, [Control UI](https://docs.clawd.bot/web), and [Canvas host](https://docs.clawd.bot/platforms/mac/canvas#canvas-a2ui).
+- [CLI surface](https://docs.clawd.bot/tools/agent-send): gateway, agent, send, [wizard](https://docs.clawd.bot/start/wizard), and [doctor](https://docs.clawd.bot/gateway/doctor).
+- [Pi agent runtime](https://docs.clawd.bot/concepts/agent) in RPC mode with tool streaming and block streaming.
+- [Session model](https://docs.clawd.bot/concepts/session): `main` for direct chats, group isolation, activation modes, queue modes, reply-back. Group rules: [Groups](https://docs.clawd.bot/concepts/groups).
+- [Media pipeline](https://docs.clawd.bot/nodes/images): images/audio/video, transcription hooks, size caps, temp file lifecycle. Audio details: [Audio](https://docs.clawd.bot/nodes/audio).
 
 ### Providers
-- [Providers](https://docs.clawd.bot/surface): [WhatsApp](https://docs.clawd.bot/whatsapp) (Baileys), [Telegram](https://docs.clawd.bot/telegram) (grammY), [Slack](https://docs.clawd.bot/slack) (Bolt), [Discord](https://docs.clawd.bot/discord) (discord.js), [Signal](https://docs.clawd.bot/signal) (signal-cli), [iMessage](https://docs.clawd.bot/imessage) (imsg), [WebChat](https://docs.clawd.bot/webchat).
-- [Group routing](https://docs.clawd.bot/group-messages): mention gating, reply tags, per-provider chunking and routing. Provider rules: [Providers](https://docs.clawd.bot/surface).
+- [Providers](https://docs.clawd.bot/providers): [WhatsApp](https://docs.clawd.bot/providers/whatsapp) (Baileys), [Telegram](https://docs.clawd.bot/providers/telegram) (grammY), [Slack](https://docs.clawd.bot/providers/slack) (Bolt), [Discord](https://docs.clawd.bot/providers/discord) (discord.js), [Signal](https://docs.clawd.bot/providers/signal) (signal-cli), [iMessage](https://docs.clawd.bot/providers/imessage) (imsg), [WebChat](https://docs.clawd.bot/web/webchat).
+- [Group routing](https://docs.clawd.bot/concepts/group-messages): mention gating, reply tags, per-provider chunking and routing. Provider rules: [Providers](https://docs.clawd.bot/providers).
 
 ### Apps + nodes
-- [macOS app](https://docs.clawd.bot/macos): menu bar control plane, [Voice Wake](https://docs.clawd.bot/voicewake)/PTT, [Talk Mode](https://docs.clawd.bot/talk) overlay, [WebChat](https://docs.clawd.bot/webchat), debug tools, [remote gateway](https://docs.clawd.bot/remote) control.
-- [iOS node](https://docs.clawd.bot/ios): [Canvas](https://docs.clawd.bot/mac/canvas), [Voice Wake](https://docs.clawd.bot/voicewake), [Talk Mode](https://docs.clawd.bot/talk), camera, screen recording, Bonjour pairing.
-- [Android node](https://docs.clawd.bot/android): [Canvas](https://docs.clawd.bot/mac/canvas), [Talk Mode](https://docs.clawd.bot/talk), camera, screen recording, optional SMS.
+- [macOS app](https://docs.clawd.bot/platforms/macos): menu bar control plane, [Voice Wake](https://docs.clawd.bot/nodes/voicewake)/PTT, [Talk Mode](https://docs.clawd.bot/nodes/talk) overlay, [WebChat](https://docs.clawd.bot/web/webchat), debug tools, [remote gateway](https://docs.clawd.bot/gateway/remote) control.
+- [iOS node](https://docs.clawd.bot/platforms/ios): [Canvas](https://docs.clawd.bot/platforms/mac/canvas), [Voice Wake](https://docs.clawd.bot/nodes/voicewake), [Talk Mode](https://docs.clawd.bot/nodes/talk), camera, screen recording, Bonjour pairing.
+- [Android node](https://docs.clawd.bot/platforms/android): [Canvas](https://docs.clawd.bot/platforms/mac/canvas), [Talk Mode](https://docs.clawd.bot/nodes/talk), camera, screen recording, optional SMS.
 - [macOS node mode](https://docs.clawd.bot/nodes): system.run/notify + canvas/camera exposure.
 
 ### Tools + automation
-- [Browser control](https://docs.clawd.bot/browser): dedicated clawd Chrome/Chromium, snapshots, actions, uploads, profiles.
-- [Canvas](https://docs.clawd.bot/mac/canvas): [A2UI](https://docs.clawd.bot/mac/canvas#canvas-a2ui) push/reset, eval, snapshot.
-- [Nodes](https://docs.clawd.bot/nodes): camera snap/clip, screen record, [location.get](https://docs.clawd.bot/location-command), notifications.
-- [Cron + wakeups](https://docs.clawd.bot/cron); [webhooks](https://docs.clawd.bot/webhook); [Gmail Pub/Sub](https://docs.clawd.bot/gmail-pubsub).
-- [Skills platform](https://docs.clawd.bot/skills): bundled, managed, and workspace skills with install gating + UI.
+- [Browser control](https://docs.clawd.bot/tools/browser): dedicated clawd Chrome/Chromium, snapshots, actions, uploads, profiles.
+- [Canvas](https://docs.clawd.bot/platforms/mac/canvas): [A2UI](https://docs.clawd.bot/platforms/mac/canvas#canvas-a2ui) push/reset, eval, snapshot.
+- [Nodes](https://docs.clawd.bot/nodes): camera snap/clip, screen record, [location.get](https://docs.clawd.bot/nodes/location-command), notifications.
+- [Cron + wakeups](https://docs.clawd.bot/automation/cron-jobs); [webhooks](https://docs.clawd.bot/automation/webhook); [Gmail Pub/Sub](https://docs.clawd.bot/automation/gmail-pubsub).
+- [Skills platform](https://docs.clawd.bot/tools/skills): bundled, managed, and workspace skills with install gating + UI.
 
 ### Runtime + safety
-- [Provider routing](https://docs.clawd.bot/provider-routing), [retry policy](https://docs.clawd.bot/retry), and [streaming/chunking](https://docs.clawd.bot/streaming).
-- [Presence](https://docs.clawd.bot/presence), [typing indicators](https://docs.clawd.bot/typing-indicators), and [usage tracking](https://docs.clawd.bot/usage-tracking).
-- [Models](https://docs.clawd.bot/models), [model failover](https://docs.clawd.bot/model-failover), and [session pruning](https://docs.clawd.bot/session-pruning).
-- [Security](https://docs.clawd.bot/security) and [troubleshooting](https://docs.clawd.bot/troubleshooting).
+- [Provider routing](https://docs.clawd.bot/concepts/provider-routing), [retry policy](https://docs.clawd.bot/concepts/retry), and [streaming/chunking](https://docs.clawd.bot/concepts/streaming).
+- [Presence](https://docs.clawd.bot/concepts/presence), [typing indicators](https://docs.clawd.bot/concepts/typing-indicators), and [usage tracking](https://docs.clawd.bot/concepts/usage-tracking).
+- [Models](https://docs.clawd.bot/concepts/models), [model failover](https://docs.clawd.bot/concepts/model-failover), and [session pruning](https://docs.clawd.bot/concepts/session-pruning).
+- [Security](https://docs.clawd.bot/gateway/security) and [troubleshooting](https://docs.clawd.bot/providers/troubleshooting).
 
 ### Ops + packaging
-- [Control UI](https://docs.clawd.bot/web) + [WebChat](https://docs.clawd.bot/webchat) served directly from the Gateway.
-- [Tailscale Serve/Funnel](https://docs.clawd.bot/tailscale) or [SSH tunnels](https://docs.clawd.bot/remote) with token/password auth.
-- [Nix mode](https://docs.clawd.bot/nix) for declarative config; [Docker](https://docs.clawd.bot/docker)-based installs.
-- [Doctor](https://docs.clawd.bot/doctor) migrations, [logging](https://docs.clawd.bot/logging).
+- [Control UI](https://docs.clawd.bot/web) + [WebChat](https://docs.clawd.bot/web/webchat) served directly from the Gateway.
+- [Tailscale Serve/Funnel](https://docs.clawd.bot/gateway/tailscale) or [SSH tunnels](https://docs.clawd.bot/gateway/remote) with token/password auth.
+- [Nix mode](https://docs.clawd.bot/install/nix) for declarative config; [Docker](https://docs.clawd.bot/install/docker)-based installs.
+- [Doctor](https://docs.clawd.bot/gateway/doctor) migrations, [logging](https://docs.clawd.bot/logging).
 
 ## How it works (short)
 
@@ -173,11 +173,11 @@ WhatsApp / Telegram / Slack / Discord / Signal / iMessage / WebChat
 
 ## Key subsystems
 
-- **[Gateway WebSocket network](https://docs.clawd.bot/architecture)** — single WS control plane for clients, tools, and events (plus ops: [Gateway runbook](https://docs.clawd.bot/gateway)).
-- **[Tailscale exposure](https://docs.clawd.bot/tailscale)** — Serve/Funnel for the Gateway dashboard + WS (remote access: [Remote](https://docs.clawd.bot/remote)).
-- **[Browser control](https://docs.clawd.bot/browser)** — clawd‑managed Chrome/Chromium with CDP control.
-- **[Canvas + A2UI](https://docs.clawd.bot/mac/canvas)** — agent‑driven visual workspace (A2UI host: [Canvas/A2UI](https://docs.clawd.bot/mac/canvas#canvas-a2ui)).
-- **[Voice Wake](https://docs.clawd.bot/voicewake) + [Talk Mode](https://docs.clawd.bot/talk)** — always‑on speech and continuous conversation.
+- **[Gateway WebSocket network](https://docs.clawd.bot/concepts/architecture)** — single WS control plane for clients, tools, and events (plus ops: [Gateway runbook](https://docs.clawd.bot/gateway)).
+- **[Tailscale exposure](https://docs.clawd.bot/gateway/tailscale)** — Serve/Funnel for the Gateway dashboard + WS (remote access: [Remote](https://docs.clawd.bot/gateway/remote)).
+- **[Browser control](https://docs.clawd.bot/tools/browser)** — clawd‑managed Chrome/Chromium with CDP control.
+- **[Canvas + A2UI](https://docs.clawd.bot/platforms/mac/canvas)** — agent‑driven visual workspace (A2UI host: [Canvas/A2UI](https://docs.clawd.bot/platforms/mac/canvas#canvas-a2ui)).
+- **[Voice Wake](https://docs.clawd.bot/nodes/voicewake) + [Talk Mode](https://docs.clawd.bot/nodes/talk)** — always‑on speech and continuous conversation.
 - **[Nodes](https://docs.clawd.bot/nodes)** — Canvas, camera snap/clip, screen record, `location.get`, notifications, plus macOS‑only `system.run`/`system.notify`.
 
 ## Tailscale access (Gateway dashboard)
@@ -194,17 +194,17 @@ Notes:
 - Funnel refuses to start unless `gateway.auth.mode: "password"` is set.
 - Optional: `gateway.tailscale.resetOnExit` to undo Serve/Funnel on shutdown.
 
-Details: [Tailscale guide](https://docs.clawd.bot/tailscale) · [Web surfaces](https://docs.clawd.bot/web)
+Details: [Tailscale guide](https://docs.clawd.bot/gateway/tailscale) · [Web surfaces](https://docs.clawd.bot/web)
 
 ## Remote Gateway (Linux is great)
 
 It’s perfectly fine to run the Gateway on a small Linux instance. Clients (macOS app, CLI, WebChat) can connect over **Tailscale Serve/Funnel** or **SSH tunnels**, and you can still pair device nodes (macOS/iOS/Android) to execute device‑local actions when needed.
 
-- **Gateway host** runs the bash tool and provider connections by default.
+- **Gateway host** runs the exec tool and provider connections by default.
 - **Device nodes** run device‑local actions (`system.run`, camera, screen recording, notifications) via `node.invoke`.
-In short: bash runs where the Gateway lives; device actions run where the device lives.
+In short: exec runs where the Gateway lives; device actions run where the device lives.
 
-Details: [Remote access](https://docs.clawd.bot/remote) · [Nodes](https://docs.clawd.bot/nodes) · [Security](https://docs.clawd.bot/security)
+Details: [Remote access](https://docs.clawd.bot/gateway/remote) · [Nodes](https://docs.clawd.bot/nodes) · [Security](https://docs.clawd.bot/gateway/security)
 
 ## macOS permissions via the Gateway protocol
 
@@ -219,7 +219,7 @@ Elevated bash (host permissions) is separate from macOS TCC:
 - Use `/elevated on|off` to toggle per‑session elevated access when enabled + allowlisted.
 - Gateway persists the per‑session toggle via `sessions.patch` (WS method) alongside `thinkingLevel`, `verboseLevel`, `model`, `sendPolicy`, and `groupActivation`.
 
-Details: [Nodes](https://docs.clawd.bot/nodes) · [macOS app](https://docs.clawd.bot/macos) · [Gateway protocol](https://docs.clawd.bot/architecture)
+Details: [Nodes](https://docs.clawd.bot/nodes) · [macOS app](https://docs.clawd.bot/platforms/macos) · [Gateway protocol](https://docs.clawd.bot/concepts/architecture)
 
 ## Agent to Agent (sessions_* tools)
 
@@ -228,7 +228,7 @@ Details: [Nodes](https://docs.clawd.bot/nodes) · [macOS app](https://docs.clawd
 - `sessions_history` — fetch transcript logs for a session.
 - `sessions_send` — message another session; optional reply‑back ping‑pong + announce step (`REPLY_SKIP`, `ANNOUNCE_SKIP`).
 
-Details: [Session tools](https://docs.clawd.bot/session-tool)
+Details: [Session tools](https://docs.clawd.bot/concepts/session-tool)
 
 ## Skills registry (ClawdHub)
 
@@ -249,7 +249,7 @@ Send these in WhatsApp/Telegram/Slack/WebChat (group commands are owner-only):
 - `/restart` — restart the gateway (owner-only in groups)
 - `/activation mention|always` — group activation toggle (groups only)
 
-## macOS app (optional)
+## Apps (optional)
 
 The Gateway alone delivers a great experience. All apps are optional and add extra features.
 
@@ -275,13 +275,13 @@ Note: signed builds required for macOS permissions to stick across rebuilds (see
 - Voice trigger forwarding + Canvas surface.
 - Controlled via `clawdbot nodes …`.
 
-Runbook: [iOS connect](https://docs.clawd.bot/ios).
+Runbook: [iOS connect](https://docs.clawd.bot/platforms/ios).
 
 ### Android node (optional)
 
 - Pairs via the same Bridge + pairing flow as iOS.
 - Exposes Canvas, Camera, and Screen capture commands.
-- Runbook: [Android connect](https://docs.clawd.bot/android).
+- Runbook: [Android connect](https://docs.clawd.bot/platforms/android).
 
 ## Agent workspace + skills
 
@@ -301,7 +301,7 @@ Minimal `~/.clawdbot/clawdbot.json` (model + defaults):
 }
 ```
 
-[Full configuration reference (all keys + examples).](https://docs.clawd.bot/configuration)
+[Full configuration reference (all keys + examples).](https://docs.clawd.bot/gateway/configuration)
 
 ## Security model (important)
 
@@ -309,15 +309,15 @@ Minimal `~/.clawdbot/clawdbot.json` (model + defaults):
 - **Group/channel safety:** set `agents.defaults.sandbox.mode: "non-main"` to run **non‑main sessions** (groups/channels) inside per‑session Docker sandboxes; bash then runs in Docker for those sessions.
 - **Sandbox defaults:** allowlist `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`; denylist `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`.
 
-Details: [Security guide](https://docs.clawd.bot/security) · [Docker + sandboxing](https://docs.clawd.bot/docker) · [Sandbox config](https://docs.clawd.bot/configuration)
+Details: [Security guide](https://docs.clawd.bot/gateway/security) · [Docker + sandboxing](https://docs.clawd.bot/install/docker) · [Sandbox config](https://docs.clawd.bot/gateway/configuration)
 
-### [WhatsApp](https://docs.clawd.bot/whatsapp)
+### [WhatsApp](https://docs.clawd.bot/providers/whatsapp)
 
 - Link the device: `pnpm clawdbot providers login` (stores creds in `~/.clawdbot/credentials`).
 - Allowlist who can talk to the assistant via `whatsapp.allowFrom`.
 - If `whatsapp.groups` is set, it becomes a group allowlist; include `"*"` to allow all.
 
-### [Telegram](https://docs.clawd.bot/telegram)
+### [Telegram](https://docs.clawd.bot/providers/telegram)
 
 - Set `TELEGRAM_BOT_TOKEN` or `telegram.botToken` (env wins).
 - Optional: set `telegram.groups` (with `telegram.groups."*".requireMention`); when set, it is a group allowlist (include `"*"` to allow all). Also `telegram.allowFrom` or `telegram.webhookUrl` as needed.
@@ -330,11 +330,11 @@ Details: [Security guide](https://docs.clawd.bot/security) · [Docker + sandboxi
 }
 ```
 
-### [Slack](https://docs.clawd.bot/slack)
+### [Slack](https://docs.clawd.bot/providers/slack)
 
 - Set `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` (or `slack.botToken` + `slack.appToken`).
 
-### [Discord](https://docs.clawd.bot/discord)
+### [Discord](https://docs.clawd.bot/providers/discord)
 
 - Set `DISCORD_BOT_TOKEN` or `discord.token` (env wins).
 - Optional: set `commands.native`, `commands.text`, or `commands.useAccessGroups`, plus `discord.dm.allowFrom`, `discord.guilds`, or `discord.mediaMaxMb` as needed.
@@ -347,16 +347,16 @@ Details: [Security guide](https://docs.clawd.bot/security) · [Docker + sandboxi
 }
 ```
 
-### [Signal](https://docs.clawd.bot/signal)
+### [Signal](https://docs.clawd.bot/providers/signal)
 
 - Requires `signal-cli` and a `signal` config section.
 
-### [iMessage](https://docs.clawd.bot/imessage)
+### [iMessage](https://docs.clawd.bot/providers/imessage)
 
 - macOS only; Messages must be signed in.
 - If `imessage.groups` is set, it becomes a group allowlist; include `"*"` to allow all.
 
-### [WebChat](https://docs.clawd.bot/webchat)
+### [WebChat](https://docs.clawd.bot/web/webchat)
 
 - Uses the Gateway WebSocket; no separate WebChat port/config.
 
@@ -376,68 +376,68 @@ Browser control (optional):
 
 Use these when you’re past the onboarding flow and want the deeper reference.
 - [Start with the docs index for navigation and “what’s where.”](https://docs.clawd.bot)
-- [Read the architecture overview for the gateway + protocol model.](https://docs.clawd.bot/architecture)
-- [Use the full configuration reference when you need every key and example.](https://docs.clawd.bot/configuration)
+- [Read the architecture overview for the gateway + protocol model.](https://docs.clawd.bot/concepts/architecture)
+- [Use the full configuration reference when you need every key and example.](https://docs.clawd.bot/gateway/configuration)
 - [Run the Gateway by the book with the operational runbook.](https://docs.clawd.bot/gateway)
 - [Learn how the Control UI/Web surfaces work and how to expose them safely.](https://docs.clawd.bot/web)
-- [Understand remote access over SSH tunnels or tailnets.](https://docs.clawd.bot/remote)
-- [Follow the onboarding wizard flow for a guided setup.](https://docs.clawd.bot/wizard)
-- [Wire external triggers via the webhook surface.](https://docs.clawd.bot/webhook)
-- [Set up Gmail Pub/Sub triggers.](https://docs.clawd.bot/gmail-pubsub)
-- [Learn the macOS menu bar companion details.](https://docs.clawd.bot/mac/menu-bar)
-- [Platform guides: Windows (WSL2)](https://docs.clawd.bot/windows), [Linux](https://docs.clawd.bot/linux), [macOS](https://docs.clawd.bot/macos), [iOS](https://docs.clawd.bot/ios), [Android](https://docs.clawd.bot/android)
-- [Debug common failures with the troubleshooting guide.](https://docs.clawd.bot/troubleshooting)
-- [Review security guidance before exposing anything.](https://docs.clawd.bot/security)
+- [Understand remote access over SSH tunnels or tailnets.](https://docs.clawd.bot/gateway/remote)
+- [Follow the onboarding wizard flow for a guided setup.](https://docs.clawd.bot/start/wizard)
+- [Wire external triggers via the webhook surface.](https://docs.clawd.bot/automation/webhook)
+- [Set up Gmail Pub/Sub triggers.](https://docs.clawd.bot/automation/gmail-pubsub)
+- [Learn the macOS menu bar companion details.](https://docs.clawd.bot/platforms/mac/menu-bar)
+- [Platform guides: Windows (WSL2)](https://docs.clawd.bot/platforms/windows), [Linux](https://docs.clawd.bot/platforms/linux), [macOS](https://docs.clawd.bot/platforms/macos), [iOS](https://docs.clawd.bot/platforms/ios), [Android](https://docs.clawd.bot/platforms/android)
+- [Debug common failures with the troubleshooting guide.](https://docs.clawd.bot/providers/troubleshooting)
+- [Review security guidance before exposing anything.](https://docs.clawd.bot/gateway/security)
 
 ## Advanced docs (discovery + control)
 
-- [Discovery + transports](https://docs.clawd.bot/discovery)
-- [Bonjour/mDNS](https://docs.clawd.bot/bonjour)
+- [Discovery + transports](https://docs.clawd.bot/gateway/discovery)
+- [Bonjour/mDNS](https://docs.clawd.bot/gateway/bonjour)
 - [Gateway pairing](https://docs.clawd.bot/gateway/pairing)
-- [Remote gateway README](https://docs.clawd.bot/remote-gateway-readme)
-- [Control UI](https://docs.clawd.bot/control-ui)
-- [Dashboard](https://docs.clawd.bot/dashboard)
+- [Remote gateway README](https://docs.clawd.bot/gateway/remote-gateway-readme)
+- [Control UI](https://docs.clawd.bot/web/control-ui)
+- [Dashboard](https://docs.clawd.bot/web/dashboard)
 
 ## Operations & troubleshooting
 
-- [Health checks](https://docs.clawd.bot/health)
-- [Gateway lock](https://docs.clawd.bot/gateway-lock)
-- [Background process](https://docs.clawd.bot/background-process)
-- [Browser troubleshooting (Linux)](https://docs.clawd.bot/browser-linux-troubleshooting)
+- [Health checks](https://docs.clawd.bot/gateway/health)
+- [Gateway lock](https://docs.clawd.bot/gateway/gateway-lock)
+- [Background process](https://docs.clawd.bot/gateway/background-process)
+- [Browser troubleshooting (Linux)](https://docs.clawd.bot/tools/browser-linux-troubleshooting)
 - [Logging](https://docs.clawd.bot/logging)
 
 ## Deep dives
 
-- [Agent loop](https://docs.clawd.bot/agent-loop)
-- [Presence](https://docs.clawd.bot/presence)
-- [TypeBox schemas](https://docs.clawd.bot/typebox)
-- [RPC adapters](https://docs.clawd.bot/rpc)
-- [Queue](https://docs.clawd.bot/queue)
+- [Agent loop](https://docs.clawd.bot/concepts/agent-loop)
+- [Presence](https://docs.clawd.bot/concepts/presence)
+- [TypeBox schemas](https://docs.clawd.bot/concepts/typebox)
+- [RPC adapters](https://docs.clawd.bot/reference/rpc)
+- [Queue](https://docs.clawd.bot/concepts/queue)
 
 ## Workspace & skills
 
-- [Skills config](https://docs.clawd.bot/skills-config)
-- [Default AGENTS](https://docs.clawd.bot/AGENTS.default)
-- [Templates: AGENTS](https://docs.clawd.bot/templates/AGENTS)
-- [Templates: BOOTSTRAP](https://docs.clawd.bot/templates/BOOTSTRAP)
-- [Templates: IDENTITY](https://docs.clawd.bot/templates/IDENTITY)
-- [Templates: SOUL](https://docs.clawd.bot/templates/SOUL)
-- [Templates: TOOLS](https://docs.clawd.bot/templates/TOOLS)
-- [Templates: USER](https://docs.clawd.bot/templates/USER)
+- [Skills config](https://docs.clawd.bot/tools/skills-config)
+- [Default AGENTS](https://docs.clawd.bot/reference/AGENTS.default)
+- [Templates: AGENTS](https://docs.clawd.bot/reference/templates/AGENTS)
+- [Templates: BOOTSTRAP](https://docs.clawd.bot/reference/templates/BOOTSTRAP)
+- [Templates: IDENTITY](https://docs.clawd.bot/reference/templates/IDENTITY)
+- [Templates: SOUL](https://docs.clawd.bot/reference/templates/SOUL)
+- [Templates: TOOLS](https://docs.clawd.bot/reference/templates/TOOLS)
+- [Templates: USER](https://docs.clawd.bot/reference/templates/USER)
 
 ## Platform internals
 
-- [macOS dev setup](https://docs.clawd.bot/mac/dev-setup)
-- [macOS menu bar](https://docs.clawd.bot/mac/menu-bar)
-- [macOS voice wake](https://docs.clawd.bot/mac/voicewake)
-- [iOS node](https://docs.clawd.bot/ios)
-- [Android node](https://docs.clawd.bot/android)
-- [Windows (WSL2)](https://docs.clawd.bot/windows)
-- [Linux app](https://docs.clawd.bot/linux)
+- [macOS dev setup](https://docs.clawd.bot/platforms/mac/dev-setup)
+- [macOS menu bar](https://docs.clawd.bot/platforms/mac/menu-bar)
+- [macOS voice wake](https://docs.clawd.bot/platforms/mac/voicewake)
+- [iOS node](https://docs.clawd.bot/platforms/ios)
+- [Android node](https://docs.clawd.bot/platforms/android)
+- [Windows (WSL2)](https://docs.clawd.bot/platforms/windows)
+- [Linux app](https://docs.clawd.bot/platforms/linux)
 
 ## Email hooks (Gmail)
 
-- [docs.clawd.bot/gmail-pubsub](https://docs.clawd.bot/gmail-pubsub)
+- [docs.clawd.bot/gmail-pubsub](https://docs.clawd.bot/automation/gmail-pubsub)
 
 ## Clawd
 
@@ -458,19 +458,20 @@ Special thanks to @andrewting19 for the Anthropic OAuth tool-name fix.
 Thanks to all clawtributors:
 
 <p align="left">
-  <a href="https://github.com/steipete"><img src="https://avatars.githubusercontent.com/u/58493?v=4&s=48" width="48" height="48" alt="steipete" title="steipete"/></a> <a href="https://github.com/joaohlisboa"><img src="https://avatars.githubusercontent.com/u/8200873?v=4&s=48" width="48" height="48" alt="joaohlisboa" title="joaohlisboa"/></a> <a href="https://github.com/mneves75"><img src="https://avatars.githubusercontent.com/u/2423436?v=4&s=48" width="48" height="48" alt="mneves75" title="mneves75"/></a> <a href="https://github.com/rahthakor"><img src="https://avatars.githubusercontent.com/u/8470553?v=4&s=48" width="48" height="48" alt="rahthakor" title="rahthakor"/></a> <a href="https://github.com/joshp123"><img src="https://avatars.githubusercontent.com/u/1497361?v=4&s=48" width="48" height="48" alt="joshp123" title="joshp123"/></a> <a href="https://github.com/mukhtharcm"><img src="https://avatars.githubusercontent.com/u/56378562?v=4&s=48" width="48" height="48" alt="mukhtharcm" title="mukhtharcm"/></a> <a href="https://github.com/maxsumrall"><img src="https://avatars.githubusercontent.com/u/628843?v=4&s=48" width="48" height="48" alt="maxsumrall" title="maxsumrall"/></a> <a href="https://github.com/xadenryan"><img src="https://avatars.githubusercontent.com/u/165437834?v=4&s=48" width="48" height="48" alt="xadenryan" title="xadenryan"/></a> <a href="https://github.com/tobiasbischoff"><img src="https://avatars.githubusercontent.com/u/711564?v=4&s=48" width="48" height="48" alt="Tobias Bischoff" title="Tobias Bischoff"/></a> <a href="https://github.com/hsrvc"><img src="https://avatars.githubusercontent.com/u/129702169?v=4&s=48" width="48" height="48" alt="hsrvc" title="hsrvc"/></a>
-  <a href="https://github.com/magimetal"><img src="https://avatars.githubusercontent.com/u/36491250?v=4&s=48" width="48" height="48" alt="magimetal" title="magimetal"/></a> <a href="https://github.com/jamesgroat"><img src="https://avatars.githubusercontent.com/u/2634024?v=4&s=48" width="48" height="48" alt="jamesgroat" title="jamesgroat"/></a> <a href="https://github.com/NicholasSpisak"><img src="https://avatars.githubusercontent.com/u/129075147?v=4&s=48" width="48" height="48" alt="NicholasSpisak" title="NicholasSpisak"/></a> <a href="https://github.com/dantelex"><img src="https://avatars.githubusercontent.com/u/631543?v=4&s=48" width="48" height="48" alt="dantelex" title="dantelex"/></a> <a href="https://github.com/daveonkels"><img src="https://avatars.githubusercontent.com/u/533642?v=4&s=48" width="48" height="48" alt="daveonkels" title="daveonkels"/></a> <a href="https://github.com/radek-paclt"><img src="https://avatars.githubusercontent.com/u/50451445?v=4&s=48" width="48" height="48" alt="radek-paclt" title="radek-paclt"/></a> <a href="https://github.com/omniwired"><img src="https://avatars.githubusercontent.com/u/322761?v=4&s=48" width="48" height="48" alt="Eng. Juan Combetto" title="Eng. Juan Combetto"/></a> <a href="https://github.com/mbelinky"><img src="https://avatars.githubusercontent.com/u/132747814?v=4&s=48" width="48" height="48" alt="Mariano Belinky" title="Mariano Belinky"/></a> <a href="https://github.com/julianengel"><img src="https://avatars.githubusercontent.com/u/10634231?v=4&s=48" width="48" height="48" alt="julianengel" title="julianengel"/></a> <a href="https://github.com/claude"><img src="https://avatars.githubusercontent.com/u/81847?v=4&s=48" width="48" height="48" alt="claude" title="claude"/></a>
-  <a href="https://github.com/jeffersonwarrior"><img src="https://avatars.githubusercontent.com/u/89030989?v=4&s=48" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/sreekaransrinath"><img src="https://avatars.githubusercontent.com/u/50989977?v=4&s=48" width="48" height="48" alt="sreekaransrinath" title="sreekaransrinath"/></a> <a href="https://github.com/dbhurley"><img src="https://avatars.githubusercontent.com/u/5251425?v=4&s=48" width="48" height="48" alt="dbhurley" title="dbhurley"/></a> <a href="https://github.com/gupsammy"><img src="https://avatars.githubusercontent.com/u/20296019?v=4&s=48" width="48" height="48" alt="gupsammy" title="gupsammy"/></a> <a href="https://github.com/nachoiacovino"><img src="https://avatars.githubusercontent.com/u/50103937?v=4&s=48" width="48" height="48" alt="nachoiacovino" title="nachoiacovino"/></a> <a href="https://github.com/vsabavat"><img src="https://avatars.githubusercontent.com/u/50385532?v=4&s=48" width="48" height="48" alt="Vasanth Rao Naik Sabavat" title="Vasanth Rao Naik Sabavat"/></a> <a href="https://github.com/lc0rp"><img src="https://avatars.githubusercontent.com/u/2609441?v=4&s=48" width="48" height="48" alt="lc0rp" title="lc0rp"/></a> <a href="https://github.com/scald"><img src="https://avatars.githubusercontent.com/u/1215913?v=4&s=48" width="48" height="48" alt="scald" title="scald"/></a> <a href="https://github.com/andranik-sahakyan"><img src="https://avatars.githubusercontent.com/u/8908029?v=4&s=48" width="48" height="48" alt="andranik-sahakyan" title="andranik-sahakyan"/></a> <a href="https://github.com/Nachx639"><img src="https://avatars.githubusercontent.com/u/71144023?v=4&s=48" width="48" height="48" alt="nachx639" title="nachx639"/></a>
-  <a href="https://github.com/sircrumpet"><img src="https://avatars.githubusercontent.com/u/4436535?v=4&s=48" width="48" height="48" alt="sircrumpet" title="sircrumpet"/></a> <a href="https://github.com/rafaelreis-r"><img src="https://avatars.githubusercontent.com/u/57492577?v=4&s=48" width="48" height="48" alt="rafaelreis-r" title="rafaelreis-r"/></a> <a href="https://github.com/meaningfool"><img src="https://avatars.githubusercontent.com/u/2862331?v=4&s=48" width="48" height="48" alt="meaningfool" title="meaningfool"/></a> <a href="https://github.com/ratulsarna"><img src="https://avatars.githubusercontent.com/u/105903728?v=4&s=48" width="48" height="48" alt="ratulsarna" title="ratulsarna"/></a> <a href="https://github.com/lutr0"><img src="https://avatars.githubusercontent.com/u/76906369?v=4&s=48" width="48" height="48" alt="lutr0" title="lutr0"/></a> <a href="https://github.com/AbhisekBasu1"><img src="https://avatars.githubusercontent.com/u/40645221?v=4&s=48" width="48" height="48" alt="abhisekbasu1" title="abhisekbasu1"/></a> <a href="https://github.com/emanuelst"><img src="https://avatars.githubusercontent.com/u/9994339?v=4&s=48" width="48" height="48" alt="emanuelst" title="emanuelst"/></a> <a href="https://github.com/thewilloftheshadow"><img src="https://avatars.githubusercontent.com/u/35580099?v=4&s=48" width="48" height="48" alt="thewilloftheshadow" title="thewilloftheshadow"/></a> <a href="https://github.com/KristijanJovanovski"><img src="https://avatars.githubusercontent.com/u/8942284?v=4&s=48" width="48" height="48" alt="KristijanJovanovski" title="KristijanJovanovski"/></a> <a href="https://github.com/osolmaz"><img src="https://avatars.githubusercontent.com/u/2453968?v=4&s=48" width="48" height="48" alt="osolmaz" title="osolmaz"/></a>
-  <a href="https://github.com/kiranjd"><img src="https://avatars.githubusercontent.com/u/25822851?v=4&s=48" width="48" height="48" alt="kiranjd" title="kiranjd"/></a> <a href="https://github.com/sebslight"><img src="https://avatars.githubusercontent.com/u/19554889?v=4&s=48" width="48" height="48" alt="sebslight" title="sebslight"/></a> <a href="https://github.com/onutc"><img src="https://avatars.githubusercontent.com/u/152018508?v=4&s=48" width="48" height="48" alt="onutc" title="onutc"/></a> <a href="https://github.com/CashWilliams"><img src="https://avatars.githubusercontent.com/u/613573?v=4&s=48" width="48" height="48" alt="CashWilliams" title="CashWilliams"/></a> <a href="https://github.com/search?q=sheeek"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="sheeek" title="sheeek"/></a> <a href="https://github.com/ManuelHettich"><img src="https://avatars.githubusercontent.com/u/17690367?v=4&s=48" width="48" height="48" alt="manuelhettich" title="manuelhettich"/></a> <a href="https://github.com/minghinmatthewlam"><img src="https://avatars.githubusercontent.com/u/14224566?v=4&s=48" width="48" height="48" alt="minghinmatthewlam" title="minghinmatthewlam"/></a> <a href="https://github.com/buddyh"><img src="https://avatars.githubusercontent.com/u/31752869?v=4&s=48" width="48" height="48" alt="buddyh" title="buddyh"/></a> <a href="https://github.com/mcinteerj"><img src="https://avatars.githubusercontent.com/u/3613653?v=4&s=48" width="48" height="48" alt="mcinteerj" title="mcinteerj"/></a> <a href="https://github.com/timkrase"><img src="https://avatars.githubusercontent.com/u/38947626?v=4&s=48" width="48" height="48" alt="timkrase" title="timkrase"/></a>
-  <a href="https://github.com/azade-c"><img src="https://avatars.githubusercontent.com/u/252790079?v=4&s=48" width="48" height="48" alt="azade-c" title="azade-c"/></a> <a href="https://github.com/search?q=Yurii%20Chukhlib"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Yurii Chukhlib" title="Yurii Chukhlib"/></a> <a href="https://github.com/austinm911"><img src="https://avatars.githubusercontent.com/u/31991302?v=4&s=48" width="48" height="48" alt="austinm911" title="austinm911"/></a> <a href="https://github.com/apps/blacksmith-sh"><img src="https://avatars.githubusercontent.com/in/807020?v=4&s=48" width="48" height="48" alt="blacksmith-sh[bot]" title="blacksmith-sh[bot]"/></a> <a href="https://github.com/imfing"><img src="https://avatars.githubusercontent.com/u/5097752?v=4&s=48" width="48" height="48" alt="imfing" title="imfing"/></a> <a href="https://github.com/jarvis-medmatic"><img src="https://avatars.githubusercontent.com/u/252428873?v=4&s=48" width="48" height="48" alt="jarvis-medmatic" title="jarvis-medmatic"/></a> <a href="https://github.com/mahmoudashraf93"><img src="https://avatars.githubusercontent.com/u/9130129?v=4&s=48" width="48" height="48" alt="mahmoudashraf93" title="mahmoudashraf93"/></a> <a href="https://github.com/petter-b"><img src="https://avatars.githubusercontent.com/u/62076402?v=4&s=48" width="48" height="48" alt="petter-b" title="petter-b"/></a> <a href="https://github.com/RandyVentures"><img src="https://avatars.githubusercontent.com/u/149904821?v=4&s=48" width="48" height="48" alt="RandyVentures" title="RandyVentures"/></a> <a href="https://github.com/jalehman"><img src="https://avatars.githubusercontent.com/u/550978?v=4&s=48" width="48" height="48" alt="jalehman" title="jalehman"/></a>
-  <a href="https://github.com/jonasjancarik"><img src="https://avatars.githubusercontent.com/u/2459191?v=4&s=48" width="48" height="48" alt="jonasjancarik" title="jonasjancarik"/></a> <a href="https://github.com/obviyus"><img src="https://avatars.githubusercontent.com/u/22031114?v=4&s=48" width="48" height="48" alt="obviyus" title="obviyus"/></a> <a href="https://github.com/dan-dr"><img src="https://avatars.githubusercontent.com/u/6669808?v=4&s=48" width="48" height="48" alt="dan-dr" title="dan-dr"/></a> <a href="https://github.com/Iamadig"><img src="https://avatars.githubusercontent.com/u/102129234?v=4&s=48" width="48" height="48" alt="iamadig" title="iamadig"/></a> <a href="https://github.com/koala73"><img src="https://avatars.githubusercontent.com/u/996596?v=4&s=48" width="48" height="48" alt="koala73" title="koala73"/></a> <a href="https://github.com/manmal"><img src="https://avatars.githubusercontent.com/u/142797?v=4&s=48" width="48" height="48" alt="manmal" title="manmal"/></a> <a href="https://github.com/neist"><img src="https://avatars.githubusercontent.com/u/1029724?v=4&s=48" width="48" height="48" alt="neist" title="neist"/></a> <a href="https://github.com/ogulcancelik"><img src="https://avatars.githubusercontent.com/u/7064011?v=4&s=48" width="48" height="48" alt="ogulcancelik" title="ogulcancelik"/></a> <a href="https://github.com/pasogott"><img src="https://avatars.githubusercontent.com/u/23458152?v=4&s=48" width="48" height="48" alt="pasogott" title="pasogott"/></a> <a href="https://github.com/VACInc"><img src="https://avatars.githubusercontent.com/u/3279061?v=4&s=48" width="48" height="48" alt="VACInc" title="VACInc"/></a>
-  <a href="https://github.com/zats"><img src="https://avatars.githubusercontent.com/u/2688806?v=4&s=48" width="48" height="48" alt="zats" title="zats"/></a> <a href="https://github.com/antons"><img src="https://avatars.githubusercontent.com/u/129705?v=4&s=48" width="48" height="48" alt="antons" title="antons"/></a> <a href="https://github.com/djangonavarro220"><img src="https://avatars.githubusercontent.com/u/251162586?v=4&s=48" width="48" height="48" alt="Django Navarro" title="Django Navarro"/></a> <a href="https://github.com/search?q=L36%20Server"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="L36 Server" title="L36 Server"/></a> <a href="https://github.com/pcty-nextgen-service-account"><img src="https://avatars.githubusercontent.com/u/112553441?v=4&s=48" width="48" height="48" alt="pcty-nextgen-service-account" title="pcty-nextgen-service-account"/></a> <a href="https://github.com/Syhids"><img src="https://avatars.githubusercontent.com/u/671202?v=4&s=48" width="48" height="48" alt="Syhids" title="Syhids"/></a> <a href="https://github.com/erik-agens"><img src="https://avatars.githubusercontent.com/u/80908960?v=4&s=48" width="48" height="48" alt="erik-agens" title="erik-agens"/></a> <a href="https://github.com/erikpr1994"><img src="https://avatars.githubusercontent.com/u/6299331?v=4&s=48" width="48" height="48" alt="erikpr1994" title="erikpr1994"/></a> <a href="https://github.com/fcatuhe"><img src="https://avatars.githubusercontent.com/u/17382215?v=4&s=48" width="48" height="48" alt="fcatuhe" title="fcatuhe"/></a> <a href="https://github.com/HeimdallStrategy"><img src="https://avatars.githubusercontent.com/u/223014405?v=4&s=48" width="48" height="48" alt="HeimdallStrategy" title="HeimdallStrategy"/></a>
-  <a href="https://github.com/henrino3"><img src="https://avatars.githubusercontent.com/u/4260288?v=4&s=48" width="48" height="48" alt="henrino3" title="henrino3"/></a> <a href="https://github.com/jayhickey"><img src="https://avatars.githubusercontent.com/u/1676460?v=4&s=48" width="48" height="48" alt="jayhickey" title="jayhickey"/></a> <a href="https://github.com/jdrhyne"><img src="https://avatars.githubusercontent.com/u/7828464?v=4&s=48" width="48" height="48" alt="Jonathan D. Rhyne (DJ-D)" title="Jonathan D. Rhyne (DJ-D)"/></a> <a href="https://github.com/jverdi"><img src="https://avatars.githubusercontent.com/u/345050?v=4&s=48" width="48" height="48" alt="jverdi" title="jverdi"/></a> <a href="https://github.com/search?q=Keith%20the%20Silly%20Goose"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Keith the Silly Goose" title="Keith the Silly Goose"/></a> <a href="https://github.com/search?q=Kit"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Kit" title="Kit"/></a> <a href="https://github.com/mitschabaude-bot"><img src="https://avatars.githubusercontent.com/u/247582884?v=4&s=48" width="48" height="48" alt="mitschabaude-bot" title="mitschabaude-bot"/></a> <a href="https://github.com/ngutman"><img src="https://avatars.githubusercontent.com/u/1540134?v=4&s=48" width="48" height="48" alt="ngutman" title="ngutman"/></a> <a href="https://github.com/oswalpalash"><img src="https://avatars.githubusercontent.com/u/6431196?v=4&s=48" width="48" height="48" alt="oswalpalash" title="oswalpalash"/></a> <a href="https://github.com/p6l-richard"><img src="https://avatars.githubusercontent.com/u/18185649?v=4&s=48" width="48" height="48" alt="p6l-richard" title="p6l-richard"/></a>
-  <a href="https://github.com/philipp-spiess"><img src="https://avatars.githubusercontent.com/u/458591?v=4&s=48" width="48" height="48" alt="philipp-spiess" title="philipp-spiess"/></a> <a href="https://github.com/pkrmf"><img src="https://avatars.githubusercontent.com/u/1714267?v=4&s=48" width="48" height="48" alt="pkrmf" title="pkrmf"/></a> <a href="https://github.com/search?q=Sash%20Catanzarite"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Sash Catanzarite" title="Sash Catanzarite"/></a> <a href="https://github.com/search?q=VAC"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="VAC" title="VAC"/></a> <a href="https://github.com/adam91holt"><img src="https://avatars.githubusercontent.com/u/9592417?v=4&s=48" width="48" height="48" alt="adam91holt" title="adam91holt"/></a> <a href="https://github.com/search?q=alejandro%20maza"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="alejandro maza" title="alejandro maza"/></a> <a href="https://github.com/andrewting19"><img src="https://avatars.githubusercontent.com/u/10536704?v=4&s=48" width="48" height="48" alt="andrewting19" title="andrewting19"/></a> <a href="https://github.com/Asleep123"><img src="https://avatars.githubusercontent.com/u/122379135?v=4&s=48" width="48" height="48" alt="Asleep123" title="Asleep123"/></a> <a href="https://github.com/bjesuiter"><img src="https://avatars.githubusercontent.com/u/2365676?v=4&s=48" width="48" height="48" alt="bjesuiter" title="bjesuiter"/></a> <a href="https://github.com/bolismauro"><img src="https://avatars.githubusercontent.com/u/771999?v=4&s=48" width="48" height="48" alt="bolismauro" title="bolismauro"/></a>
-  <a href="https://github.com/cash-echo-bot"><img src="https://avatars.githubusercontent.com/u/252747386?v=4&s=48" width="48" height="48" alt="cash-echo-bot" title="cash-echo-bot"/></a> <a href="https://github.com/search?q=Clawd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Clawd" title="Clawd"/></a> <a href="https://github.com/conhecendocontato"><img src="https://avatars.githubusercontent.com/u/82890727?v=4&s=48" width="48" height="48" alt="conhecendocontato" title="conhecendocontato"/></a> <a href="https://github.com/gtsifrikas"><img src="https://avatars.githubusercontent.com/u/8904378?v=4&s=48" width="48" height="48" alt="gtsifrikas" title="gtsifrikas"/></a> <a href="https://github.com/HazAT"><img src="https://avatars.githubusercontent.com/u/363802?v=4&s=48" width="48" height="48" alt="HazAT" title="HazAT"/></a> <a href="https://github.com/hrdwdmrbl"><img src="https://avatars.githubusercontent.com/u/554881?v=4&s=48" width="48" height="48" alt="hrdwdmrbl" title="hrdwdmrbl"/></a> <a href="https://github.com/hugobarauna"><img src="https://avatars.githubusercontent.com/u/2719?v=4&s=48" width="48" height="48" alt="hugobarauna" title="hugobarauna"/></a> <a href="https://github.com/search?q=Jarvis"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jarvis" title="Jarvis"/></a> <a href="https://github.com/kitze"><img src="https://avatars.githubusercontent.com/u/1160594?v=4&s=48" width="48" height="48" alt="kitze" title="kitze"/></a> <a href="https://github.com/kkarimi"><img src="https://avatars.githubusercontent.com/u/875218?v=4&s=48" width="48" height="48" alt="kkarimi" title="kkarimi"/></a>
-  <a href="https://github.com/levifig"><img src="https://avatars.githubusercontent.com/u/1605?v=4&s=48" width="48" height="48" alt="levifig" title="levifig"/></a> <a href="https://github.com/search?q=Lloyd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Lloyd" title="Lloyd"/></a> <a href="https://github.com/loukotal"><img src="https://avatars.githubusercontent.com/u/18210858?v=4&s=48" width="48" height="48" alt="loukotal" title="loukotal"/></a> <a href="https://github.com/martinpucik"><img src="https://avatars.githubusercontent.com/u/5503097?v=4&s=48" width="48" height="48" alt="martinpucik" title="martinpucik"/></a> <a href="https://github.com/mickahouan"><img src="https://avatars.githubusercontent.com/u/31423109?v=4&s=48" width="48" height="48" alt="mickahouan" title="mickahouan"/></a> <a href="https://github.com/search?q=Miles"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Miles" title="Miles"/></a> <a href="https://github.com/mrdbstn"><img src="https://avatars.githubusercontent.com/u/58957632?v=4&s=48" width="48" height="48" alt="mrdbstn" title="mrdbstn"/></a> <a href="https://github.com/MSch"><img src="https://avatars.githubusercontent.com/u/7475?v=4&s=48" width="48" height="48" alt="MSch" title="MSch"/></a> <a href="https://github.com/nexty5870"><img src="https://avatars.githubusercontent.com/u/3869659?v=4&s=48" width="48" height="48" alt="nexty5870" title="nexty5870"/></a> <a href="https://github.com/prathamdby"><img src="https://avatars.githubusercontent.com/u/134331217?v=4&s=48" width="48" height="48" alt="prathamdby" title="prathamdby"/></a>
-  <a href="https://github.com/reeltimeapps"><img src="https://avatars.githubusercontent.com/u/637338?v=4&s=48" width="48" height="48" alt="reeltimeapps" title="reeltimeapps"/></a> <a href="https://github.com/RLTCmpe"><img src="https://avatars.githubusercontent.com/u/10762242?v=4&s=48" width="48" height="48" alt="RLTCmpe" title="RLTCmpe"/></a> <a href="https://github.com/search?q=Rolf%20Fredheim"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rolf Fredheim" title="Rolf Fredheim"/></a> <a href="https://github.com/rubyrunsstuff"><img src="https://avatars.githubusercontent.com/u/246602379?v=4&s=48" width="48" height="48" alt="rubyrunsstuff" title="rubyrunsstuff"/></a> <a href="https://github.com/search?q=Samrat%20Jha"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Samrat Jha" title="Samrat Jha"/></a> <a href="https://github.com/snopoke"><img src="https://avatars.githubusercontent.com/u/249606?v=4&s=48" width="48" height="48" alt="snopoke" title="snopoke"/></a> <a href="https://github.com/wes-davis"><img src="https://avatars.githubusercontent.com/u/16506720?v=4&s=48" width="48" height="48" alt="wes-davis" title="wes-davis"/></a> <a href="https://github.com/wstock"><img src="https://avatars.githubusercontent.com/u/1394687?v=4&s=48" width="48" height="48" alt="wstock" title="wstock"/></a> <a href="https://github.com/YuriNachos"><img src="https://avatars.githubusercontent.com/u/19365375?v=4&s=48" width="48" height="48" alt="YuriNachos" title="YuriNachos"/></a> <a href="https://github.com/search?q=Zach%20Knickerbocker"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Zach Knickerbocker" title="Zach Knickerbocker"/></a>
-  <a href="https://github.com/zknicker"><img src="https://avatars.githubusercontent.com/u/1164085?v=4&s=48" width="48" height="48" alt="zknicker" title="zknicker"/></a> <a href="https://github.com/search?q=Azade"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Azade" title="Azade"/></a> <a href="https://github.com/search?q=ddyo"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="ddyo" title="ddyo"/></a> <a href="https://github.com/search?q=Erik"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Erik" title="Erik"/></a> <a href="https://github.com/latitudeki5223"><img src="https://avatars.githubusercontent.com/u/119656367?v=4&s=48" width="48" height="48" alt="latitudeki5223" title="latitudeki5223"/></a> <a href="https://github.com/search?q=Manuel%20Maly"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Manuel Maly" title="Manuel Maly"/></a> <a href="https://github.com/search?q=Mourad%20Boustani"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mourad Boustani" title="Mourad Boustani"/></a> <a href="https://github.com/pcty-nextgen-ios-builder"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="pcty-nextgen-ios-builder" title="pcty-nextgen-ios-builder"/></a> <a href="https://github.com/search?q=Quentin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Quentin" title="Quentin"/></a> <a href="https://github.com/search?q=Randy%20Torres"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Randy Torres" title="Randy Torres"/></a>
-  <a href="https://github.com/search?q=William%20Stock"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="William Stock" title="William Stock"/></a>
+  <a href="https://github.com/steipete"><img src="https://avatars.githubusercontent.com/u/58493?v=4&s=48" width="48" height="48" alt="steipete" title="steipete"/></a> <a href="https://github.com/joaohlisboa"><img src="https://avatars.githubusercontent.com/u/8200873?v=4&s=48" width="48" height="48" alt="joaohlisboa" title="joaohlisboa"/></a> <a href="https://github.com/mneves75"><img src="https://avatars.githubusercontent.com/u/2423436?v=4&s=48" width="48" height="48" alt="mneves75" title="mneves75"/></a> <a href="https://github.com/rahthakor"><img src="https://avatars.githubusercontent.com/u/8470553?v=4&s=48" width="48" height="48" alt="rahthakor" title="rahthakor"/></a> <a href="https://github.com/joshp123"><img src="https://avatars.githubusercontent.com/u/1497361?v=4&s=48" width="48" height="48" alt="joshp123" title="joshp123"/></a> <a href="https://github.com/mukhtharcm"><img src="https://avatars.githubusercontent.com/u/56378562?v=4&s=48" width="48" height="48" alt="mukhtharcm" title="mukhtharcm"/></a> <a href="https://github.com/maxsumrall"><img src="https://avatars.githubusercontent.com/u/628843?v=4&s=48" width="48" height="48" alt="maxsumrall" title="maxsumrall"/></a> <a href="https://github.com/xadenryan"><img src="https://avatars.githubusercontent.com/u/165437834?v=4&s=48" width="48" height="48" alt="xadenryan" title="xadenryan"/></a> <a href="https://github.com/tobiasbischoff"><img src="https://avatars.githubusercontent.com/u/711564?v=4&s=48" width="48" height="48" alt="Tobias Bischoff" title="Tobias Bischoff"/></a> <a href="https://github.com/magimetal"><img src="https://avatars.githubusercontent.com/u/36491250?v=4&s=48" width="48" height="48" alt="magimetal" title="magimetal"/></a>
+  <a href="https://github.com/NicholasSpisak"><img src="https://avatars.githubusercontent.com/u/129075147?v=4&s=48" width="48" height="48" alt="NicholasSpisak" title="NicholasSpisak"/></a> <a href="https://github.com/hsrvc"><img src="https://avatars.githubusercontent.com/u/129702169?v=4&s=48" width="48" height="48" alt="hsrvc" title="hsrvc"/></a> <a href="https://github.com/claude"><img src="https://avatars.githubusercontent.com/u/81847?v=4&s=48" width="48" height="48" alt="claude" title="claude"/></a> <a href="https://github.com/jamesgroat"><img src="https://avatars.githubusercontent.com/u/2634024?v=4&s=48" width="48" height="48" alt="jamesgroat" title="jamesgroat"/></a> <a href="https://github.com/dantelex"><img src="https://avatars.githubusercontent.com/u/631543?v=4&s=48" width="48" height="48" alt="dantelex" title="dantelex"/></a> <a href="https://github.com/daveonkels"><img src="https://avatars.githubusercontent.com/u/533642?v=4&s=48" width="48" height="48" alt="daveonkels" title="daveonkels"/></a> <a href="https://github.com/radek-paclt"><img src="https://avatars.githubusercontent.com/u/50451445?v=4&s=48" width="48" height="48" alt="radek-paclt" title="radek-paclt"/></a> <a href="https://github.com/jeffersonwarrior"><img src="https://avatars.githubusercontent.com/u/89030989?v=4&s=48" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/mteam88"><img src="https://avatars.githubusercontent.com/u/84196639?v=4&s=48" width="48" height="48" alt="mteam88" title="mteam88"/></a> <a href="https://github.com/omniwired"><img src="https://avatars.githubusercontent.com/u/322761?v=4&s=48" width="48" height="48" alt="Eng. Juan Combetto" title="Eng. Juan Combetto"/></a>
+  <a href="https://github.com/mbelinky"><img src="https://avatars.githubusercontent.com/u/132747814?v=4&s=48" width="48" height="48" alt="Mariano Belinky" title="Mariano Belinky"/></a> <a href="https://github.com/julianengel"><img src="https://avatars.githubusercontent.com/u/10634231?v=4&s=48" width="48" height="48" alt="julianengel" title="julianengel"/></a> <a href="https://github.com/benithors"><img src="https://avatars.githubusercontent.com/u/20652882?v=4&s=48" width="48" height="48" alt="benithors" title="benithors"/></a> <a href="https://github.com/sreekaransrinath"><img src="https://avatars.githubusercontent.com/u/50989977?v=4&s=48" width="48" height="48" alt="sreekaransrinath" title="sreekaransrinath"/></a> <a href="https://github.com/dbhurley"><img src="https://avatars.githubusercontent.com/u/5251425?v=4&s=48" width="48" height="48" alt="dbhurley" title="dbhurley"/></a> <a href="https://github.com/gupsammy"><img src="https://avatars.githubusercontent.com/u/20296019?v=4&s=48" width="48" height="48" alt="gupsammy" title="gupsammy"/></a> <a href="https://github.com/cristip73"><img src="https://avatars.githubusercontent.com/u/24499421?v=4&s=48" width="48" height="48" alt="cristip73" title="cristip73"/></a> <a href="https://github.com/nachoiacovino"><img src="https://avatars.githubusercontent.com/u/50103937?v=4&s=48" width="48" height="48" alt="nachoiacovino" title="nachoiacovino"/></a> <a href="https://github.com/vsabavat"><img src="https://avatars.githubusercontent.com/u/50385532?v=4&s=48" width="48" height="48" alt="Vasanth Rao Naik Sabavat" title="Vasanth Rao Naik Sabavat"/></a> <a href="https://github.com/lc0rp"><img src="https://avatars.githubusercontent.com/u/2609441?v=4&s=48" width="48" height="48" alt="lc0rp" title="lc0rp"/></a>
+  <a href="https://github.com/scald"><img src="https://avatars.githubusercontent.com/u/1215913?v=4&s=48" width="48" height="48" alt="scald" title="scald"/></a> <a href="https://github.com/andranik-sahakyan"><img src="https://avatars.githubusercontent.com/u/8908029?v=4&s=48" width="48" height="48" alt="andranik-sahakyan" title="andranik-sahakyan"/></a> <a href="https://github.com/Nachx639"><img src="https://avatars.githubusercontent.com/u/71144023?v=4&s=48" width="48" height="48" alt="nachx639" title="nachx639"/></a> <a href="https://github.com/sircrumpet"><img src="https://avatars.githubusercontent.com/u/4436535?v=4&s=48" width="48" height="48" alt="sircrumpet" title="sircrumpet"/></a> <a href="https://github.com/peschee"><img src="https://avatars.githubusercontent.com/u/63866?v=4&s=48" width="48" height="48" alt="peschee" title="peschee"/></a> <a href="https://github.com/rafaelreis-r"><img src="https://avatars.githubusercontent.com/u/57492577?v=4&s=48" width="48" height="48" alt="rafaelreis-r" title="rafaelreis-r"/></a> <a href="https://github.com/meaningfool"><img src="https://avatars.githubusercontent.com/u/2862331?v=4&s=48" width="48" height="48" alt="meaningfool" title="meaningfool"/></a> <a href="https://github.com/ratulsarna"><img src="https://avatars.githubusercontent.com/u/105903728?v=4&s=48" width="48" height="48" alt="ratulsarna" title="ratulsarna"/></a> <a href="https://github.com/lutr0"><img src="https://avatars.githubusercontent.com/u/76906369?v=4&s=48" width="48" height="48" alt="lutr0" title="lutr0"/></a> <a href="https://github.com/AbhisekBasu1"><img src="https://avatars.githubusercontent.com/u/40645221?v=4&s=48" width="48" height="48" alt="abhisekbasu1" title="abhisekbasu1"/></a>
+  <a href="https://github.com/thewilloftheshadow"><img src="https://avatars.githubusercontent.com/u/35580099?v=4&s=48" width="48" height="48" alt="thewilloftheshadow" title="thewilloftheshadow"/></a> <a href="https://github.com/emanuelst"><img src="https://avatars.githubusercontent.com/u/9994339?v=4&s=48" width="48" height="48" alt="emanuelst" title="emanuelst"/></a> <a href="https://github.com/KristijanJovanovski"><img src="https://avatars.githubusercontent.com/u/8942284?v=4&s=48" width="48" height="48" alt="KristijanJovanovski" title="KristijanJovanovski"/></a> <a href="https://github.com/osolmaz"><img src="https://avatars.githubusercontent.com/u/2453968?v=4&s=48" width="48" height="48" alt="osolmaz" title="osolmaz"/></a> <a href="https://github.com/kiranjd"><img src="https://avatars.githubusercontent.com/u/25822851?v=4&s=48" width="48" height="48" alt="kiranjd" title="kiranjd"/></a> <a href="https://github.com/sebslight"><img src="https://avatars.githubusercontent.com/u/19554889?v=4&s=48" width="48" height="48" alt="Sebastian Barrios" title="Sebastian Barrios"/></a> <a href="https://github.com/search?q=sheeek"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="sheeek" title="sheeek"/></a> <a href="https://github.com/onutc"><img src="https://avatars.githubusercontent.com/u/152018508?v=4&s=48" width="48" height="48" alt="onutc" title="onutc"/></a> <a href="https://github.com/CashWilliams"><img src="https://avatars.githubusercontent.com/u/613573?v=4&s=48" width="48" height="48" alt="CashWilliams" title="CashWilliams"/></a> <a href="https://github.com/ManuelHettich"><img src="https://avatars.githubusercontent.com/u/17690367?v=4&s=48" width="48" height="48" alt="manuelhettich" title="manuelhettich"/></a>
+  <a href="https://github.com/minghinmatthewlam"><img src="https://avatars.githubusercontent.com/u/14224566?v=4&s=48" width="48" height="48" alt="minghinmatthewlam" title="minghinmatthewlam"/></a> <a href="https://github.com/myfunc"><img src="https://avatars.githubusercontent.com/u/19294627?v=4&s=48" width="48" height="48" alt="myfunc" title="myfunc"/></a> <a href="https://github.com/buddyh"><img src="https://avatars.githubusercontent.com/u/31752869?v=4&s=48" width="48" height="48" alt="buddyh" title="buddyh"/></a> <a href="https://github.com/mcinteerj"><img src="https://avatars.githubusercontent.com/u/3613653?v=4&s=48" width="48" height="48" alt="mcinteerj" title="mcinteerj"/></a> <a href="https://github.com/timkrase"><img src="https://avatars.githubusercontent.com/u/38947626?v=4&s=48" width="48" height="48" alt="timkrase" title="timkrase"/></a> <a href="https://github.com/azade-c"><img src="https://avatars.githubusercontent.com/u/252790079?v=4&s=48" width="48" height="48" alt="azade-c" title="azade-c"/></a> <a href="https://github.com/obviyus"><img src="https://avatars.githubusercontent.com/u/22031114?v=4&s=48" width="48" height="48" alt="obviyus" title="obviyus"/></a> <a href="https://github.com/bjesuiter"><img src="https://avatars.githubusercontent.com/u/2365676?v=4&s=48" width="48" height="48" alt="bjesuiter" title="bjesuiter"/></a> <a href="https://github.com/superman32432432"><img src="https://avatars.githubusercontent.com/u/7228420?v=4&s=48" width="48" height="48" alt="superman32432432" title="superman32432432"/></a> <a href="https://github.com/search?q=Yurii%20Chukhlib"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Yurii Chukhlib" title="Yurii Chukhlib"/></a>
+  <a href="https://github.com/antons"><img src="https://avatars.githubusercontent.com/u/129705?v=4&s=48" width="48" height="48" alt="antons" title="antons"/></a> <a href="https://github.com/austinm911"><img src="https://avatars.githubusercontent.com/u/31991302?v=4&s=48" width="48" height="48" alt="austinm911" title="austinm911"/></a> <a href="https://github.com/apps/blacksmith-sh"><img src="https://avatars.githubusercontent.com/in/807020?v=4&s=48" width="48" height="48" alt="blacksmith-sh[bot]" title="blacksmith-sh[bot]"/></a> <a href="https://github.com/imfing"><img src="https://avatars.githubusercontent.com/u/5097752?v=4&s=48" width="48" height="48" alt="imfing" title="imfing"/></a> <a href="https://github.com/jarvis-medmatic"><img src="https://avatars.githubusercontent.com/u/252428873?v=4&s=48" width="48" height="48" alt="jarvis-medmatic" title="jarvis-medmatic"/></a> <a href="https://github.com/mahmoudashraf93"><img src="https://avatars.githubusercontent.com/u/9130129?v=4&s=48" width="48" height="48" alt="mahmoudashraf93" title="mahmoudashraf93"/></a> <a href="https://github.com/petter-b"><img src="https://avatars.githubusercontent.com/u/62076402?v=4&s=48" width="48" height="48" alt="petter-b" title="petter-b"/></a> <a href="https://github.com/pkrmf"><img src="https://avatars.githubusercontent.com/u/1714267?v=4&s=48" width="48" height="48" alt="pkrmf" title="pkrmf"/></a> <a href="https://github.com/RandyVentures"><img src="https://avatars.githubusercontent.com/u/149904821?v=4&s=48" width="48" height="48" alt="RandyVentures" title="RandyVentures"/></a> <a href="https://github.com/dan-dr"><img src="https://avatars.githubusercontent.com/u/6669808?v=4&s=48" width="48" height="48" alt="dan-dr" title="dan-dr"/></a>
+  <a href="https://github.com/HeimdallStrategy"><img src="https://avatars.githubusercontent.com/u/223014405?v=4&s=48" width="48" height="48" alt="HeimdallStrategy" title="HeimdallStrategy"/></a> <a href="https://github.com/jalehman"><img src="https://avatars.githubusercontent.com/u/550978?v=4&s=48" width="48" height="48" alt="jalehman" title="jalehman"/></a> <a href="https://github.com/jonasjancarik"><img src="https://avatars.githubusercontent.com/u/2459191?v=4&s=48" width="48" height="48" alt="jonasjancarik" title="jonasjancarik"/></a> <a href="https://github.com/neist"><img src="https://avatars.githubusercontent.com/u/1029724?v=4&s=48" width="48" height="48" alt="neist" title="neist"/></a> <a href="https://github.com/Iamadig"><img src="https://avatars.githubusercontent.com/u/102129234?v=4&s=48" width="48" height="48" alt="iamadig" title="iamadig"/></a> <a href="https://github.com/koala73"><img src="https://avatars.githubusercontent.com/u/996596?v=4&s=48" width="48" height="48" alt="koala73" title="koala73"/></a> <a href="https://github.com/manmal"><img src="https://avatars.githubusercontent.com/u/142797?v=4&s=48" width="48" height="48" alt="manmal" title="manmal"/></a> <a href="https://github.com/ogulcancelik"><img src="https://avatars.githubusercontent.com/u/7064011?v=4&s=48" width="48" height="48" alt="ogulcancelik" title="ogulcancelik"/></a> <a href="https://github.com/pasogott"><img src="https://avatars.githubusercontent.com/u/23458152?v=4&s=48" width="48" height="48" alt="pasogott" title="pasogott"/></a> <a href="https://github.com/petradonka"><img src="https://avatars.githubusercontent.com/u/7353770?v=4&s=48" width="48" height="48" alt="petradonka" title="petradonka"/></a>
+  <a href="https://github.com/VACInc"><img src="https://avatars.githubusercontent.com/u/3279061?v=4&s=48" width="48" height="48" alt="VACInc" title="VACInc"/></a> <a href="https://github.com/zats"><img src="https://avatars.githubusercontent.com/u/2688806?v=4&s=48" width="48" height="48" alt="zats" title="zats"/></a> <a href="https://github.com/search?q=Chris%20Taylor"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Chris Taylor" title="Chris Taylor"/></a> <a href="https://github.com/djangonavarro220"><img src="https://avatars.githubusercontent.com/u/251162586?v=4&s=48" width="48" height="48" alt="Django Navarro" title="Django Navarro"/></a> <a href="https://github.com/gabriel-trigo"><img src="https://avatars.githubusercontent.com/u/38991125?v=4&s=48" width="48" height="48" alt="gabriel-trigo" title="gabriel-trigo"/></a> <a href="https://github.com/search?q=Kit"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Kit" title="Kit"/></a> <a href="https://github.com/search?q=L36%20Server"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="L36 Server" title="L36 Server"/></a> <a href="https://github.com/ngutman"><img src="https://avatars.githubusercontent.com/u/1540134?v=4&s=48" width="48" height="48" alt="ngutman" title="ngutman"/></a> <a href="https://github.com/pcty-nextgen-service-account"><img src="https://avatars.githubusercontent.com/u/112553441?v=4&s=48" width="48" height="48" alt="pcty-nextgen-service-account" title="pcty-nextgen-service-account"/></a> <a href="https://github.com/rubyrunsstuff"><img src="https://avatars.githubusercontent.com/u/246602379?v=4&s=48" width="48" height="48" alt="rubyrunsstuff" title="rubyrunsstuff"/></a>
+  <a href="https://github.com/Syhids"><img src="https://avatars.githubusercontent.com/u/671202?v=4&s=48" width="48" height="48" alt="Syhids" title="Syhids"/></a> <a href="https://github.com/danielz1z"><img src="https://avatars.githubusercontent.com/u/235270390?v=4&s=48" width="48" height="48" alt="danielz1z" title="danielz1z"/></a> <a href="https://github.com/erik-agens"><img src="https://avatars.githubusercontent.com/u/80908960?v=4&s=48" width="48" height="48" alt="erik-agens" title="erik-agens"/></a> <a href="https://github.com/erikpr1994"><img src="https://avatars.githubusercontent.com/u/6299331?v=4&s=48" width="48" height="48" alt="erikpr1994" title="erikpr1994"/></a> <a href="https://github.com/fcatuhe"><img src="https://avatars.githubusercontent.com/u/17382215?v=4&s=48" width="48" height="48" alt="fcatuhe" title="fcatuhe"/></a> <a href="https://github.com/henrino3"><img src="https://avatars.githubusercontent.com/u/4260288?v=4&s=48" width="48" height="48" alt="henrino3" title="henrino3"/></a> <a href="https://github.com/jayhickey"><img src="https://avatars.githubusercontent.com/u/1676460?v=4&s=48" width="48" height="48" alt="jayhickey" title="jayhickey"/></a> <a href="https://github.com/jdrhyne"><img src="https://avatars.githubusercontent.com/u/7828464?v=4&s=48" width="48" height="48" alt="Jonathan D. Rhyne (DJ-D)" title="Jonathan D. Rhyne (DJ-D)"/></a> <a href="https://github.com/juanpablodlc"><img src="https://avatars.githubusercontent.com/u/92012363?v=4&s=48" width="48" height="48" alt="juanpablodlc" title="juanpablodlc"/></a> <a href="https://github.com/jverdi"><img src="https://avatars.githubusercontent.com/u/345050?v=4&s=48" width="48" height="48" alt="jverdi" title="jverdi"/></a>
+  <a href="https://github.com/search?q=Keith%20the%20Silly%20Goose"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Keith the Silly Goose" title="Keith the Silly Goose"/></a> <a href="https://github.com/mitschabaude-bot"><img src="https://avatars.githubusercontent.com/u/247582884?v=4&s=48" width="48" height="48" alt="mitschabaude-bot" title="mitschabaude-bot"/></a> <a href="https://github.com/mjrussell"><img src="https://avatars.githubusercontent.com/u/1641895?v=4&s=48" width="48" height="48" alt="mjrussell" title="mjrussell"/></a> <a href="https://github.com/oswalpalash"><img src="https://avatars.githubusercontent.com/u/6431196?v=4&s=48" width="48" height="48" alt="oswalpalash" title="oswalpalash"/></a> <a href="https://github.com/p6l-richard"><img src="https://avatars.githubusercontent.com/u/18185649?v=4&s=48" width="48" height="48" alt="p6l-richard" title="p6l-richard"/></a> <a href="https://github.com/philipp-spiess"><img src="https://avatars.githubusercontent.com/u/458591?v=4&s=48" width="48" height="48" alt="philipp-spiess" title="philipp-spiess"/></a> <a href="https://github.com/search?q=Sash%20Catanzarite"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Sash Catanzarite" title="Sash Catanzarite"/></a> <a href="https://github.com/search?q=VAC"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="VAC" title="VAC"/></a> <a href="https://github.com/adam91holt"><img src="https://avatars.githubusercontent.com/u/9592417?v=4&s=48" width="48" height="48" alt="adam91holt" title="adam91holt"/></a> <a href="https://github.com/search?q=alejandro%20maza"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="alejandro maza" title="alejandro maza"/></a>
+  <a href="https://github.com/andrewting19"><img src="https://avatars.githubusercontent.com/u/10536704?v=4&s=48" width="48" height="48" alt="andrewting19" title="andrewting19"/></a> <a href="https://github.com/Asleep123"><img src="https://avatars.githubusercontent.com/u/122379135?v=4&s=48" width="48" height="48" alt="Asleep123" title="Asleep123"/></a> <a href="https://github.com/bolismauro"><img src="https://avatars.githubusercontent.com/u/771999?v=4&s=48" width="48" height="48" alt="bolismauro" title="bolismauro"/></a> <a href="https://github.com/cash-echo-bot"><img src="https://avatars.githubusercontent.com/u/252747386?v=4&s=48" width="48" height="48" alt="cash-echo-bot" title="cash-echo-bot"/></a> <a href="https://github.com/search?q=Clawd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Clawd" title="Clawd"/></a> <a href="https://github.com/conhecendocontato"><img src="https://avatars.githubusercontent.com/u/82890727?v=4&s=48" width="48" height="48" alt="conhecendocontato" title="conhecendocontato"/></a> <a href="https://github.com/evalexpr"><img src="https://avatars.githubusercontent.com/u/23485511?v=4&s=48" width="48" height="48" alt="evalexpr" title="evalexpr"/></a> <a href="https://github.com/gtsifrikas"><img src="https://avatars.githubusercontent.com/u/8904378?v=4&s=48" width="48" height="48" alt="gtsifrikas" title="gtsifrikas"/></a> <a href="https://github.com/HazAT"><img src="https://avatars.githubusercontent.com/u/363802?v=4&s=48" width="48" height="48" alt="HazAT" title="HazAT"/></a> <a href="https://github.com/hrdwdmrbl"><img src="https://avatars.githubusercontent.com/u/554881?v=4&s=48" width="48" height="48" alt="hrdwdmrbl" title="hrdwdmrbl"/></a>
+  <a href="https://github.com/hugobarauna"><img src="https://avatars.githubusercontent.com/u/2719?v=4&s=48" width="48" height="48" alt="hugobarauna" title="hugobarauna"/></a> <a href="https://github.com/search?q=Jarvis"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jarvis" title="Jarvis"/></a> <a href="https://github.com/kitze"><img src="https://avatars.githubusercontent.com/u/1160594?v=4&s=48" width="48" height="48" alt="kitze" title="kitze"/></a> <a href="https://github.com/kkarimi"><img src="https://avatars.githubusercontent.com/u/875218?v=4&s=48" width="48" height="48" alt="kkarimi" title="kkarimi"/></a> <a href="https://github.com/levifig"><img src="https://avatars.githubusercontent.com/u/1605?v=4&s=48" width="48" height="48" alt="levifig" title="levifig"/></a> <a href="https://github.com/search?q=Lloyd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Lloyd" title="Lloyd"/></a> <a href="https://github.com/loukotal"><img src="https://avatars.githubusercontent.com/u/18210858?v=4&s=48" width="48" height="48" alt="loukotal" title="loukotal"/></a> <a href="https://github.com/martinpucik"><img src="https://avatars.githubusercontent.com/u/5503097?v=4&s=48" width="48" height="48" alt="martinpucik" title="martinpucik"/></a> <a href="https://github.com/mickahouan"><img src="https://avatars.githubusercontent.com/u/31423109?v=4&s=48" width="48" height="48" alt="mickahouan" title="mickahouan"/></a> <a href="https://github.com/search?q=Miles"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Miles" title="Miles"/></a>
+  <a href="https://github.com/mrdbstn"><img src="https://avatars.githubusercontent.com/u/58957632?v=4&s=48" width="48" height="48" alt="mrdbstn" title="mrdbstn"/></a> <a href="https://github.com/MSch"><img src="https://avatars.githubusercontent.com/u/7475?v=4&s=48" width="48" height="48" alt="MSch" title="MSch"/></a> <a href="https://github.com/nexty5870"><img src="https://avatars.githubusercontent.com/u/3869659?v=4&s=48" width="48" height="48" alt="nexty5870" title="nexty5870"/></a> <a href="https://github.com/prathamdby"><img src="https://avatars.githubusercontent.com/u/134331217?v=4&s=48" width="48" height="48" alt="prathamdby" title="prathamdby"/></a> <a href="https://github.com/reeltimeapps"><img src="https://avatars.githubusercontent.com/u/637338?v=4&s=48" width="48" height="48" alt="reeltimeapps" title="reeltimeapps"/></a> <a href="https://github.com/RLTCmpe"><img src="https://avatars.githubusercontent.com/u/10762242?v=4&s=48" width="48" height="48" alt="RLTCmpe" title="RLTCmpe"/></a> <a href="https://github.com/search?q=Rolf%20Fredheim"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rolf Fredheim" title="Rolf Fredheim"/></a> <a href="https://github.com/roshanasingh4"><img src="https://avatars.githubusercontent.com/u/88576930?v=4&s=48" width="48" height="48" alt="roshanasingh4" title="roshanasingh4"/></a> <a href="https://github.com/search?q=Samrat%20Jha"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Samrat Jha" title="Samrat Jha"/></a> <a href="https://github.com/snopoke"><img src="https://avatars.githubusercontent.com/u/249606?v=4&s=48" width="48" height="48" alt="snopoke" title="snopoke"/></a>
+  <a href="https://github.com/search?q=The%20Admiral"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="The Admiral" title="The Admiral"/></a> <a href="https://github.com/wes-davis"><img src="https://avatars.githubusercontent.com/u/16506720?v=4&s=48" width="48" height="48" alt="wes-davis" title="wes-davis"/></a> <a href="https://github.com/wstock"><img src="https://avatars.githubusercontent.com/u/1394687?v=4&s=48" width="48" height="48" alt="wstock" title="wstock"/></a> <a href="https://github.com/YuriNachos"><img src="https://avatars.githubusercontent.com/u/19365375?v=4&s=48" width="48" height="48" alt="YuriNachos" title="YuriNachos"/></a> <a href="https://github.com/search?q=Zach%20Knickerbocker"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Zach Knickerbocker" title="Zach Knickerbocker"/></a> <a href="https://github.com/zknicker"><img src="https://avatars.githubusercontent.com/u/1164085?v=4&s=48" width="48" height="48" alt="zknicker" title="zknicker"/></a> <a href="https://github.com/search?q=Azade"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Azade" title="Azade"/></a> <a href="https://github.com/carlulsoe"><img src="https://avatars.githubusercontent.com/u/34673973?v=4&s=48" width="48" height="48" alt="carlulsoe" title="carlulsoe"/></a> <a href="https://github.com/search?q=ddyo"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="ddyo" title="ddyo"/></a> <a href="https://github.com/search?q=Erik"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Erik" title="Erik"/></a>
+  <a href="https://github.com/latitudeki5223"><img src="https://avatars.githubusercontent.com/u/119656367?v=4&s=48" width="48" height="48" alt="latitudeki5223" title="latitudeki5223"/></a> <a href="https://github.com/search?q=Manuel%20Maly"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Manuel Maly" title="Manuel Maly"/></a> <a href="https://github.com/search?q=Mourad%20Boustani"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mourad Boustani" title="Mourad Boustani"/></a> <a href="https://github.com/pcty-nextgen-ios-builder"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="pcty-nextgen-ios-builder" title="pcty-nextgen-ios-builder"/></a> <a href="https://github.com/search?q=Quentin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Quentin" title="Quentin"/></a> <a href="https://github.com/search?q=Randy%20Torres"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Randy Torres" title="Randy Torres"/></a> <a href="https://github.com/thesash"><img src="https://avatars.githubusercontent.com/u/1166151?v=4&s=48" width="48" height="48" alt="thesash" title="thesash"/></a> <a href="https://github.com/search?q=William%20Stock"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="William Stock" title="William Stock"/></a>
 </p>

appcast.xml

@@ -2,6 +2,229 @@
 <rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
     <channel>
         <title>Clawdbot</title>
+        <item>
+            <title>2026.1.11</title>
+            <pubDate>Mon, 12 Jan 2026 09:37:49 +0000</pubDate>
+            <link>https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml</link>
+            <sparkle:version>5205</sparkle:version>
+            <sparkle:shortVersionString>2026.1.11</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>Clawdbot 2026.1.11</h2>
+<h3>Highlights</h3>
+<ul>
+<li>Plugins are now first-class: loader + CLI management, plus the new Voice Call plugin.</li>
+<li>Config: modular <code>$include</code> support for split config files. (#731) — thanks @pasogott.</li>
+<li>Agents/Pi: reserve compaction headroom so pre-compaction memory writes can run before auto-compaction.</li>
+<li>Agents: automatic pre-compaction memory flush turn to store durable memories before compaction.</li>
+</ul>
+<h3>Changes</h3>
+<ul>
+<li>Deps: update pi-agent-core/pi-ai/pi-coding-agent/pi-tui and refresh the pi-ai patch.</li>
+<li>Dev: bump @types/node.</li>
+<li>macOS: add wizard debug CLI and share wizard parsing helpers.</li>
+<li>CLI/Onboarding: simplify MiniMax auth choice to a single M2.1 option.</li>
+<li>CLI: configure section selection now loops until Continue.</li>
+<li>Docs: explain MiniMax vs MiniMax Lightning (speed vs cost) and restore LM Studio example.</li>
+<li>Docs: add Cerebras GLM 4.6/4.7 config example (OpenAI-compatible endpoint).</li>
+<li>Onboarding/CLI: group model/auth choice by provider and label Z.AI as GLM 4.7.</li>
+<li>Onboarding/Docs: add Moonshot AI (Kimi K2) auth choice + config example.</li>
+<li>CLI/Onboarding: prompt to reuse detected API keys for Moonshot/MiniMax/Z.AI/Gemini/Anthropic/OpenCode.</li>
+<li>CLI/Onboarding: move MiniMax to the top of the provider list.</li>
+<li>CLI/Onboarding: add MiniMax M2.1 Lightning auth choice.</li>
+<li>CLI/Onboarding: show key previews when reusing detected API keys.</li>
+<li>Auto-reply: add compact <code>/model</code> picker (models + available providers) and show provider endpoints in <code>/model status</code>.</li>
+<li>Control UI: add Config tab model presets (MiniMax M2.1, GLM 4.7, Kimi) for one-click setup.</li>
+<li>Plugins: add extension loader (tools/RPC/CLI/services), discovery paths, and config schema + Control UI labels (uiHints).</li>
+<li>Plugins: add <code>clawdbot plugins install</code> (path/tgz/npm), plus <code>list|info|enable|disable|doctor</code> UX.</li>
+<li>Plugins: voice-call plugin now real (Twilio/log), adds start/status RPC/CLI/tool + tests.</li>
+<li>Docs: add plugins doc + cross-links from tools/skills/gateway config.</li>
+<li>Docs: clarify memory flush behavior + writable workspace requirement in Memory/Session/FAQ.</li>
+<li>Docs: add beginner-friendly plugin quick start + expand Voice Call plugin docs.</li>
+<li>Tests: add Docker plugin loader + tgz-install smoke test.</li>
+<li>Tests: extend Docker plugin E2E to cover installing from local folders (<code>plugins.load.paths</code>) and <code>file:</code> npm specs.</li>
+<li>Tests: add coverage for pre-compaction memory flush settings (including read-only/CLI skips).</li>
+<li>Tests: modernize live model smoke selection for current releases and enforce tools/images/thinking-high coverage. (#769) — thanks @steipete.</li>
+<li>Agents/Tools: add <code>apply_patch</code> tool for multi-file edits (experimental; gated by tools.exec.applyPatch; OpenAI-only).</li>
+<li>Agents/Tools: rename the bash tool to exec (config alias maintained). (#748) — thanks @myfunc.</li>
+<li>Agents: add pre-compaction memory flush config (<code>agents.defaults.compaction.*</code>) with a soft threshold + system prompt.</li>
+<li>Config: add <code>$include</code> directive for modular config files. (#731) — thanks @pasogott.</li>
+<li>Build: set pnpm minimum release age to 2880 minutes (2 days). (#718) — thanks @dan-dr.</li>
+<li>macOS: prompt to install the global <code>clawdbot</code> CLI when missing in local mode; install via <code>clawd.bot/install-cli.sh</code> (no onboarding) and use external launchd/CLI instead of the embedded gateway runtime.</li>
+<li>Docs: add gog calendar event color IDs from <code>gog calendar colors</code>. (#715) — thanks @mjrussell.</li>
+<li>Cron/CLI: add <code>--model</code> flag to cron add/edit commands. (#711) — thanks @mjrussell.</li>
+<li>Cron/CLI: trim model overrides on cron edits and document main-session guidance. (#711) — thanks @mjrussell.</li>
+<li>Skills: bundle <code>skill-creator</code> to guide creating and packaging skills.</li>
+<li>Providers: add per-DM history limit overrides (<code>dmHistoryLimit</code>) with provider-level config. (#728) — thanks @pkrmf.</li>
+<li>Discord: expose channel/category management actions in the message tool. (#730) — thanks @NicholasSpisak.</li>
+<li>Docs: rename README “macOS app” section to “Apps”. (#733) — thanks @AbhisekBasu1.</li>
+<li>Gateway: require <code>client.id</code> in WebSocket connect params; use <code>client.instanceId</code> for presence de-dupe; update docs/tests.</li>
+<li>macOS: remove the attach-only gateway setting; local mode now always manages launchd while still attaching to an existing gateway if present.</li>
+</ul>
+<h3>Installer</h3>
+<ul>
+<li>Postinstall: replace <code>git apply</code> with builtin JS patcher (works npm/pnpm/bun; no git dependency) plus regression tests.</li>
+<li>Postinstall: skip pnpm patch fallback when the new patcher is active.</li>
+<li>Installer tests: add root+non-root docker smokes, CI workflow to fetch clawd.bot scripts and run install sh/cli with onboarding skipped.</li>
+<li>Installer UX: support <code>CLAWDBOT_NO_ONBOARD=1</code> for non-interactive installs; fix npm prefix on Linux and auto-install git.</li>
+<li>Installer UX: add <code>install.sh --help</code> with flags/env and git install hint.</li>
+<li>Installer UX: add <code>--install-method git|npm</code> and auto-detect source checkouts (prompt to update git checkout vs migrate to npm).</li>
+</ul>
+<h3>Fixes</h3>
+<ul>
+<li>Control UI: flatten nav into a single horizontal scroll row on tablet/mobile (and always show collapsed group items). (#771) — thanks @carlulsoe.</li>
+<li>macOS: start + await local gateway before onboarding wizard begins.</li>
+<li>macOS: cancel onboarding wizard on close, recover if the gateway drops the session, and time out stalled gateway connects.</li>
+<li>macOS: wizard debug CLI now surfaces error status instead of exiting as complete.</li>
+<li>Models/Onboarding: configure MiniMax (minimax.io) via Anthropic-compatible <code>/anthropic</code> endpoint by default (keep <code>minimax-api</code> as a legacy alias).</li>
+<li>Agents/Browser: cap Playwright AI snapshots for tool calls (maxChars); CLI snapshots remain full. (#763) — thanks @thesash.</li>
+<li>Models: normalize Gemini 3 Pro/Flash IDs to preview names for live model lookups. (#769) — thanks @steipete.</li>
+<li>CLI: fix guardCancel typing for configure prompts. (#769) — thanks @steipete.</li>
+<li>Providers: default groupPolicy to allowlist across providers and warn in doctor when groups are open.</li>
+<li>MS Teams: add groupPolicy/groupAllowFrom gating for group chats and warn when groups are open.</li>
+<li>Providers: strip tool call/result ids from Gemini CLI payloads to avoid API 400s. (#756)</li>
+<li>Gateway/WebChat: include handshake validation details in the WebSocket close reason for easier debugging; preserve close codes.</li>
+<li>Gateway/Auth: send invalid connect responses before closing the handshake; stabilize invalid-connect auth test.</li>
+<li>Gateway: tighten gateway listener detection.</li>
+<li>Control UI: hide onboarding chat when configured and guard the mobile chat sidebar overlay.</li>
+<li>Auth: read Codex keychain credentials and make the lookup platform-aware.</li>
+<li>macOS/Release: avoid bundling dist artifacts in relay builds and generate appcasts from zip-only sources.</li>
+<li>Doctor: surface plugin diagnostics in the report.</li>
+<li>Plugins: treat <code>plugins.load.paths</code> directory entries as package roots when they contain <code>package.json</code> + <code>clawdbot.extensions</code>; load plugin packages from config dirs; extract archives without system tar.</li>
+<li>Config: expand <code>~</code> in <code>CLAWDBOT_CONFIG_PATH</code> and common path-like config fields (including <code>plugins.load.paths</code>); guard invalid <code>$include</code> paths. (#731) — thanks @pasogott.</li>
+<li>Agents: stop pre-creating session transcripts so first user messages persist in JSONL history.</li>
+<li>Agents: skip pre-compaction memory flush when the session workspace is read-only.</li>
+<li>Auto-reply: allow inline <code>/status</code> for allowlisted senders (stripped before the model); unauthorized senders see it as plain text.</li>
+<li>Auto-reply: include config-only allowlisted models in <code>/model</code> even when the catalog is partial.</li>
+<li>Auto-reply: allow fuzzy <code>/model</code> matches (e.g. <code>/model kimi</code> or <code>/model moonshot/kimi</code>) when unambiguous.</li>
+<li>Auto-reply: ignore inline <code>/status</code> directives unless the message is directive-only.</li>
+<li>CLI/Configure: enter the selected section immediately, then return to the section picker.</li>
+<li>CLI/Configure: apply the chosen auth model as default (skip the extra picker) and refresh the model catalog for new providers.</li>
+<li>Auto-reply: align <code>/think</code> default display with model reasoning defaults. (#751) — thanks @gabriel-trigo.</li>
+<li>Auto-reply: flush block reply buffers on tool boundaries. (#750) — thanks @sebslight.</li>
+<li>Auto-reply: allow sender fallback for command authorization when <code>SenderId</code> is empty (WhatsApp self-chat). (#755) — thanks @juanpablodlc.</li>
+<li>Heartbeat: refresh prompt text for updated defaults.</li>
+<li>Agents/Tools: use PowerShell on Windows to capture system utility output. (#748) — thanks @myfunc.</li>
+<li>Agents/Tools: normalize Claude Code-style read/write/edit params (file_path/old_string/new_string) and keep sandbox guards in place. (#768) — thanks @hsrvc.</li>
+<li>Docker: tolerate unset optional env vars in docker-setup.sh under strict mode. (#725) — thanks @petradonka.</li>
+<li>CLI/Update: preserve base environment when passing overrides to update subprocesses. (#713) — thanks @danielz1z.</li>
+<li>Agents: treat message tool errors as failures so fallback replies still send; require <code>to</code> + <code>message</code> for <code>action=send</code>. (#717) — thanks @theglove44.</li>
+<li>Agents: preserve reasoning items on tool-only turns.</li>
+<li>Agents: enforce <code><final></code> gating for reasoning-tag providers to prevent tag/reasoning leaks. (#754) — thanks @mcinteerj.</li>
+<li>Agents/Subagents: wait for completion before announcing, align wait timeout with run timeout, and make announce prompts more emphatic.</li>
+<li>Agents: route subagent transcripts to the target agent sessions directory and add regression coverage. (#708) — thanks @xMikeMickelson.</li>
+<li>Agents/Tools: preserve action enums when flattening tool schemas. (#708) — thanks @xMikeMickelson.</li>
+<li>Gateway/Agents: canonicalize main session aliases for store writes and add regression coverage. (#709) — thanks @xMikeMickelson.</li>
+<li>Agents: reset sessions and retry when auto-compaction overflows instead of crashing the gateway.</li>
+<li>Providers/Telegram: normalize command mentions for consistent parsing. (#729) — thanks @obviyus.</li>
+<li>Providers: skip DM history limit handling for non-DM sessions. (#728) — thanks @pkrmf.</li>
+<li>Sandbox: fix non-main mode incorrectly sandboxing the main DM session and align <code>/status</code> runtime reporting with effective sandbox state.</li>
+<li>Sandbox/Gateway: treat <code>agent:<id>:main</code> as a main-session alias when <code>session.mainKey</code> is customized (backwards compatible).</li>
+<li>Auto-reply: fast-path allowlisted slash commands (inline <code>/help</code>/<code>/commands</code>/<code>/status</code>/<code>/whoami</code> stripped before model).</li>
+</ul>
+<p><a href="https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md">View full changelog</a></p>
+]]></description>
+            <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.11/Clawdbot-2026.1.11.zip" length="19860746" type="application/octet-stream" sparkle:edSignature="zmN6RovfpvPNm7PPYKDQ2c8nUtlq4k1+S6c3fvZwEHFRwKOxjhQtaW0phriDJwcqfguU3ibAQd/cpRtP4LYdCQ=="/>
+        </item>
+        <item>
+            <title>2026.1.10</title>
+            <pubDate>Sun, 11 Jan 2026 10:26:34 +0000</pubDate>
+            <link>https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml</link>
+            <sparkle:version>4946</sparkle:version>
+            <sparkle:shortVersionString>2026.1.10</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>Clawdbot 2026.1.10</h2>
+<h3>Highlights</h3>
+<ul>
+<li>CLI: <code>clawdbot status</code> now table-based + shows OS/update/gateway/daemon/agents/sessions; <code>status --all</code> adds a full read-only debug report (tables, log tails, Tailscale summary, and scan progress via OSC-9 + spinner).</li>
+<li>CLI Backends: add Codex CLI fallback with resume support (text output) and JSONL parsing for new runs, plus a live CLI resume probe.</li>
+<li>CLI: add <code>clawdbot update</code> (safe-ish git checkout update) + <code>--update</code> shorthand. (#673) — thanks @fm1randa.</li>
+<li>Gateway: add OpenAI-compatible <code>/v1/chat/completions</code> HTTP endpoint (auth, SSE streaming, per-agent routing). (#680) — thanks @steipete.</li>
+</ul>
+<h3>Changes</h3>
+<ul>
+<li>Onboarding/Models: add first-class Z.AI (GLM) auth choice (<code>zai-api-key</code>) + <code>--zai-api-key</code> flag.</li>
+<li>CLI/Onboarding: add OpenRouter API key auth option in configure/onboard. (#703) — thanks @mteam88.</li>
+<li>Agents: add human-delay pacing between block replies (modes: off/natural/custom, per-agent configurable). (#446) — thanks @tony-freedomology.</li>
+<li>Agents/Browser: add <code>browser.target</code> (sandbox/host/custom) with sandbox host-control gating via <code>agents.defaults.sandbox.browser.allowHostControl</code>, allowlists for custom control URLs/hosts/ports, and expand browser tool docs (remote control, profiles, internals).</li>
+<li>Onboarding/Models: add catalog-backed default model picker to onboarding + configure. (#611) — thanks @jonasjancarik.</li>
+<li>Agents/OpenCode Zen: update fallback models + defaults, keep legacy alias mappings. (#669) — thanks @magimetal.</li>
+<li>Providers: unify group history context wrappers across providers with per-provider/per-account <code>historyLimit</code> overrides (fallback to <code>messages.groupChat.historyLimit</code>). Set <code>0</code> to disable. (#672) — thanks @steipete.</li>
+<li>Gateway/Heartbeat: optionally deliver heartbeat <code>Reasoning:</code> output (<code>agents.defaults.heartbeat.includeReasoning</code>). (#690)</li>
+<li>Docker: allow optional home volume + extra bind mounts in <code>docker-setup.sh</code>. (#679) — thanks @gabriel-trigo.</li>
+</ul>
+<h3>Fixes</h3>
+<ul>
+<li>CLI/Status: expand tables to full terminal width; clarify provider setup vs runtime warnings; richer per-provider detail; token previews in <code>status</code> while keeping <code>status --all</code> redacted; add troubleshooting link footer; keep log tails pasteable; show gateway auth used when reachable; surface provider runtime errors (Signal/iMessage/Slack); harden <code>tailscale status --json</code> parsing; make <code>status --all</code> scan progress determinate; and replace the footer with a 3-line “Next steps” recommendation (share/debug/probe).</li>
+<li>CLI/Gateway: clarify that <code>clawdbot gateway status</code> reports RPC health (connect + RPC) and shows RPC failures separately from connect failures.</li>
+<li>CLI/Update: gate progress spinner on stdout TTY and align clean-check step label. (#701) — thanks @bjesuiter.</li>
+<li>Telegram: add <code>/whoami</code> + <code>/id</code> commands to reveal sender id for allowlists; allow <code>@username</code> and prefixed ids in <code>allowFrom</code> prompts (with stability warning).</li>
+<li>Control UI: stop auto-writing <code>telegram.groups["*"]</code> and warn/confirm before enabling wildcard groups.</li>
+<li>WhatsApp: send ack reactions only for handled messages and ignore legacy <code>messages.ackReaction</code> (doctor copies to <code>whatsapp.ackReaction</code>). (#629) — thanks @pasogott.</li>
+<li>Sandbox/Skills: mirror skills into sandbox workspaces for read-only mounts so SKILL.md stays accessible.</li>
+<li>Terminal/Table: ANSI-safe wrapping to prevent table clipping/color loss; add regression coverage.</li>
+<li>Docker: allow optional apt packages during image build and document the build arg. (#697) — thanks @gabriel-trigo.</li>
+<li>Gateway/Heartbeat: deliver reasoning even when the main heartbeat reply is <code>HEARTBEAT_OK</code>. (#694) — thanks @antons.</li>
+<li>macOS: clear unsigned launchd overrides on signed restarts and warn via doctor when attach-only/disable markers are set. (#695) — thanks @jeffersonwarrior.</li>
+<li>Agents: enforce single-writer session locks and drop orphan tool results to prevent tool-call ID failures (MiniMax/Anthropic-compatible APIs).</li>
+<li>Docs: make <code>clawdbot status</code> the first diagnostic step, clarify <code>status --deep</code> behavior, and document <code>/whoami</code> + <code>/id</code>.</li>
+<li>Docs/Testing: clarify live tool+image probes and how to list your testable <code>provider/model</code> ids.</li>
+<li>Tests/Live: make gateway bash+read probes resilient to provider formatting while still validating real tool calls.</li>
+<li>WhatsApp: detect @lid mentions in groups using authDir reverse mapping + resolve self JID E.164 for mention gating. (#692) — thanks @peschee.</li>
+<li>Gateway/Auth: default to token auth on loopback during onboarding, add doctor token generation flow, and tighten audio transcription config to Whisper-only.</li>
+<li>Providers: dedupe inbound messages across providers to avoid duplicate LLM runs on redeliveries/reconnects. (#689) — thanks @adam91holt.</li>
+<li>Agents: strip <code><thought></code>/<code><antthinking></code> tags from hidden reasoning output and cover tag variants in tests. (#688) — thanks @theglove44.</li>
+<li>macOS: save model picker selections as normalized provider/model IDs and keep manual entries aligned. (#683) — thanks @benithors.</li>
+<li>Agents: recognize "usage limit" errors as rate limits for failover. (#687) — thanks @evalexpr.</li>
+<li>CLI: avoid success message when daemon restart is skipped. (#685) — thanks @carlulsoe.</li>
+<li>Commands: disable <code>/config</code> + <code>/debug</code> by default; gate via <code>commands.config</code>/<code>commands.debug</code> and hide from native registration/help output.</li>
+<li>Agents/System: clarify that sub-agents remain sandboxed and cannot use elevated host access.</li>
+<li>Gateway: disable the OpenAI-compatible <code>/v1/chat/completions</code> endpoint by default; enable via <code>gateway.http.endpoints.chatCompletions.enabled=true</code>.</li>
+<li>macOS: stabilize bridge tunnels, guard invoke senders on disconnect, and drain stdout/stderr to avoid deadlocks. (#676) — thanks @ngutman.</li>
+<li>Agents/System: clarify sandboxed runtime in system prompt and surface elevated availability when sandboxed.</li>
+<li>Auto-reply: prefer <code>RawBody</code> for command/directive parsing (WhatsApp + Discord) and prevent fallback runs from clobbering concurrent session updates. (#643) — thanks @mcinteerj.</li>
+<li>WhatsApp: fix group reactions by preserving message IDs and sender JIDs in history; normalize participant phone numbers to JIDs in outbound reactions. (#640) — thanks @mcinteerj.</li>
+<li>WhatsApp: expose group participant IDs to the model so reactions can target the right sender.</li>
+<li>Cron: <code>wakeMode: "now"</code> waits for heartbeat completion (and retries when the main lane is busy). (#666) — thanks @roshanasingh4.</li>
+<li>Agents/OpenAI: fix Responses tool-only → follow-up turn handling (avoid standalone <code>reasoning</code> items that trigger 400 “required following item”) and replay reasoning items in Responses/Codex Responses history for tool-call-only turns.</li>
+<li>Sandbox: add <code>clawdbot sandbox explain</code> (effective policy inspector + fix-it keys); improve “sandbox jail” tool-policy/elevated errors with actionable config key paths; link to docs.</li>
+<li>Hooks/Gmail: keep Tailscale serve path at <code>/</code> while preserving the public path. (#668) — thanks @antons.</li>
+<li>Hooks/Gmail: allow Tailscale target URLs to preserve internal serve paths.</li>
+<li>Auth: update Claude Code keychain credentials in-place during refresh sync; share JSON file helpers; add CLI fallback coverage.</li>
+<li>Auth: throttle external CLI credential syncs (Claude/Codex), reduce Keychain reads, and skip sync when cached credentials are still fresh.</li>
+<li>CLI: respect <code>CLAWDBOT_STATE_DIR</code> for node pairing + voice wake settings storage. (#664) — thanks @azade-c.</li>
+<li>Onboarding/Gateway: persist non-interactive gateway token auth in config; add WS wizard + gateway tool-calling regression coverage.</li>
+<li>Gateway/Control UI: make <code>chat.send</code> non-blocking, wire Stop to <code>chat.abort</code>, and treat <code>/stop</code> as an out-of-band abort. (#653)</li>
+<li>Gateway/Control UI: allow <code>chat.abort</code> without <code>runId</code> (abort active runs), suppress post-abort chat streaming, and prune stuck chat runs. (#653)</li>
+<li>Gateway/Control UI: sniff image attachments for chat.send, drop non-images, and log mismatches. (#670) — thanks @cristip73.</li>
+<li>macOS: force <code>restart-mac.sh --sign</code> to require identities and keep bundled Node signed for relay verification. (#580) — thanks @jeffersonwarrior.</li>
+<li>Gateway/Agent: accept image attachments on <code>agent</code> (multimodal message) and add live gateway image probe (<code>CLAWDBOT_LIVE_GATEWAY_IMAGE_PROBE=1</code>).</li>
+<li>CLI: <code>clawdbot sessions</code> now includes <code>elev:*</code> + <code>usage:*</code> flags in the table output.</li>
+<li>CLI/Pairing: accept positional provider for <code>pairing list|approve</code> (npm-run compatible); update docs/bot hints.</li>
+<li>Branding: normalize user-facing “ClawdBot”/“CLAWDBOT” → “Clawdbot” (CLI, status, docs).</li>
+<li>Auto-reply: fix native <code>/model</code> not updating the actual chat session (Telegram/Slack/Discord). (#646)</li>
+<li>Doctor: offer to run <code>clawdbot update</code> first on git installs (keeps doctor output aligned with latest).</li>
+<li>Doctor: avoid false legacy workspace warning when install dir is <code>~/clawdbot</code>. (#660)</li>
+<li>iMessage: fix reasoning persistence across DMs; avoid partial/duplicate replies when reasoning is enabled. (#655) — thanks @antons.</li>
+<li>Models/Auth: allow MiniMax API configs without <code>models.providers.minimax.apiKey</code> (auth profiles / <code>MINIMAX_API_KEY</code>). (#656) — thanks @mneves75.</li>
+<li>Agents: avoid duplicate replies when the message tool sends. (#659) — thanks @mickahouan.</li>
+<li>Agents: harden Cloud Code Assist tool ID sanitization (toolUse/toolCall/toolResult) and scrub extra JSON Schema constraints. (#665) — thanks @sebslight.</li>
+<li>Agents: sanitize tool results + Cloud Code Assist tool IDs at context-build time (prevents mid-run strict-provider request rejects).</li>
+<li>Agents/Tools: resolve workspace-relative Read/Write/Edit paths; align bash default cwd. (#642) — thanks @mukhtharcm.</li>
+<li>Discord: include forwarded message snapshots in agent session context. (#667) — thanks @rubyrunsstuff.</li>
+<li>Telegram: add <code>telegram.draftChunk</code> to tune draft streaming chunking for <code>streamMode: "block"</code>. (#667) — thanks @rubyrunsstuff.</li>
+<li>Tests/Agents: add regression coverage for workspace tool path resolution and bash cwd defaults.</li>
+<li>iOS/Android: enable stricter concurrency/lint checks; fix Swift 6 strict concurrency issues + Android lint errors (ExifInterface, obsolete SDK check). (#662) — thanks @KristijanJovanovski.</li>
+<li>iOS/macOS: share <code>AsyncTimeout</code>, require explicit <code>bridgeStableID</code> on connect, and harden tool display defaults (avoids missing-resource label fallbacks).</li>
+<li>Telegram: serialize media-group processing to avoid missed albums under load.</li>
+<li>Signal: handle <code>dataMessage.reaction</code> events (signal-cli SSE) to avoid broken attachment errors. (#637) — thanks @neist.</li>
+<li>Docs: showcase entries for ParentPay, R2 Upload, iOS TestFlight, and Oura Health. (#650) — thanks @henrino3.</li>
+<li>Agents: repair session transcripts by dropping duplicate tool results across the whole history (unblocks Anthropic-compatible APIs after retries).</li>
+<li>Tests/Live: reset the gateway session between model runs to avoid cross-provider transcript incompatibilities (notably OpenAI Responses reasoning replay rules).</li>
+</ul>
+<p><a href="https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md">View full changelog</a></p>
+]]></description>
+            <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.10/Clawdbot-2026.1.10.zip" length="199586798" type="application/octet-stream" sparkle:edSignature="Ntb22WL4b0Hu3Ntqm1iqnD+5bUqqa36iSQ8vbT/50C5FnL5IjF4GoHWrfanJ58JhBCQ4eKdK+K0U4OBZiSzZBw=="/>
+        </item>
         <item>
             <title>2026.1.9</title>
             <pubDate>Sat, 10 Jan 2026 05:23:02 +0100</pubDate>

apps/android/app/build.gradle.kts

@@ -21,8 +21,8 @@ android {
     applicationId = "com.clawdbot.android"
     minSdk = 31
     targetSdk = 36
-    versionCode = 20260109
-    versionName = "2026.1.9"
+    versionCode = 20260111
+    versionName = "2026.1.11"
   }
 
   buildTypes {

apps/ios/Sources/Info.plist

@@ -19,9 +19,9 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.1.9</string>
+	<string>2026.1.11</string>
 	<key>CFBundleVersion</key>
-	<string>20260109</string>
+	<string>20260111</string>
 	<key>NSAppTransportSecurity</key>
 	<dict>
 		<key>NSAllowsArbitraryLoadsInWebContent</key>

apps/ios/Tests/Info.plist

@@ -17,8 +17,8 @@
 	<key>CFBundlePackageType</key>
 	<string>BNDL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.1.9</string>
+	<string>2026.1.11</string>
 	<key>CFBundleVersion</key>
-	<string>20260109</string>
+	<string>20260111</string>
 </dict>
 </plist>

apps/macos/Package.swift

@@ -13,6 +13,7 @@ let package = Package(
         .library(name: "ClawdbotDiscovery", targets: ["ClawdbotDiscovery"]),
         .executable(name: "Clawdbot", targets: ["Clawdbot"]),
         .executable(name: "clawdbot-mac-discovery", targets: ["ClawdbotDiscoveryCLI"]),
+        .executable(name: "clawdbot-mac-wizard", targets: ["ClawdbotWizardCLI"]),
     ],
     dependencies: [
         .package(url: "https://github.com/orchetect/MenuBarExtraAccess", exact: "1.2.2"),
@@ -82,6 +83,15 @@ let package = Package(
             swiftSettings: [
                 .enableUpcomingFeature("StrictConcurrency"),
             ]),
+        .executableTarget(
+            name: "ClawdbotWizardCLI",
+            dependencies: [
+                "ClawdbotProtocol",
+            ],
+            path: "Sources/ClawdbotWizardCLI",
+            swiftSettings: [
+                .enableUpcomingFeature("StrictConcurrency"),
+            ]),
         .testTarget(
             name: "ClawdbotIPCTests",
             dependencies: [

apps/macos/Sources/Clawdbot/AppState.swift

@@ -182,14 +182,6 @@ final class AppState {
         }
     }
 
-    var attachExistingGatewayOnly: Bool {
-        didSet {
-            self.ifNotPreview {
-                UserDefaults.standard.set(self.attachExistingGatewayOnly, forKey: attachExistingGatewayOnlyKey)
-            }
-        }
-    }
-
     var remoteTarget: String {
         didSet {
             self.ifNotPreview { UserDefaults.standard.set(self.remoteTarget, forKey: remoteTargetKey) }
@@ -302,8 +294,6 @@ final class AppState {
         self.canvasEnabled = UserDefaults.standard.object(forKey: canvasEnabledKey) as? Bool ?? true
         self.peekabooBridgeEnabled = UserDefaults.standard
             .object(forKey: peekabooBridgeEnabledKey) as? Bool ?? true
-        self.attachExistingGatewayOnly = UserDefaults.standard.bool(forKey: attachExistingGatewayOnlyKey)
-
         if !self.isPreview {
             Task.detached(priority: .utility) { [weak self] in
                 let current = await LaunchAgentManager.status()
@@ -604,7 +594,6 @@ extension AppState {
         state.remoteIdentity = "~/.ssh/id_ed25519"
         state.remoteProjectRoot = "~/Projects/clawdbot"
         state.remoteCliPath = ""
-        state.attachExistingGatewayOnly = false
         return state
     }
 }
@@ -623,10 +612,6 @@ enum AppStateStore {
     static var canvasEnabled: Bool {
         UserDefaults.standard.object(forKey: canvasEnabledKey) as? Bool ?? true
     }
-
-    static var attachExistingGatewayOnly: Bool {
-        UserDefaults.standard.bool(forKey: attachExistingGatewayOnlyKey)
-    }
 }
 
 @MainActor

apps/macos/Sources/Clawdbot/CLIInstallPrompter.swift

@@ -0,0 +1,84 @@
+import AppKit
+import Foundation
+import OSLog
+
+@MainActor
+final class CLIInstallPrompter {
+    static let shared = CLIInstallPrompter()
+    private let logger = Logger(subsystem: "com.clawdbot", category: "cli.prompt")
+    private var isPrompting = false
+
+    func checkAndPromptIfNeeded(reason: String) {
+        guard self.shouldPrompt() else { return }
+        guard let version = Self.appVersion() else { return }
+        self.isPrompting = true
+        UserDefaults.standard.set(version, forKey: cliInstallPromptedVersionKey)
+
+        let alert = NSAlert()
+        alert.messageText = "Install Clawdbot CLI?"
+        alert.informativeText = "Local mode needs the CLI so launchd can run the gateway."
+        alert.addButton(withTitle: "Install CLI")
+        alert.addButton(withTitle: "Not now")
+        alert.addButton(withTitle: "Open Settings")
+        let response = alert.runModal()
+
+        switch response {
+        case .alertFirstButtonReturn:
+            Task { await self.installCLI() }
+        case .alertThirdButtonReturn:
+            self.openSettings(tab: .general)
+        default:
+            break
+        }
+
+        self.logger.debug("cli install prompt handled reason=\(reason, privacy: .public)")
+        self.isPrompting = false
+    }
+
+    private func shouldPrompt() -> Bool {
+        guard !self.isPrompting else { return false }
+        guard AppStateStore.shared.onboardingSeen else { return false }
+        guard AppStateStore.shared.connectionMode == .local else { return false }
+        guard CLIInstaller.installedLocation() == nil else { return false }
+        guard let version = Self.appVersion() else { return false }
+        let lastPrompt = UserDefaults.standard.string(forKey: cliInstallPromptedVersionKey)
+        return lastPrompt != version
+    }
+
+    private func installCLI() async {
+        let status = StatusBox()
+        await CLIInstaller.install { message in
+            await status.set(message)
+        }
+        if let message = await status.get() {
+            let alert = NSAlert()
+            alert.messageText = "CLI install finished"
+            alert.informativeText = message
+            alert.runModal()
+        }
+    }
+
+    private func openSettings(tab: SettingsTab) {
+        SettingsTabRouter.request(tab)
+        SettingsWindowOpener.shared.open()
+        DispatchQueue.main.async {
+            NotificationCenter.default.post(name: .clawdbotSelectSettingsTab, object: tab)
+        }
+    }
+
+    private static func appVersion() -> String? {
+        Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String
+    }
+}
+
+private actor StatusBox {
+    private var value: String?
+
+    func set(_ value: String) {
+        self.value = value
+    }
+
+    func get() -> String? {
+        self.value
+    }
+}

apps/macos/Sources/Clawdbot/CLIInstaller.swift

@@ -2,24 +2,16 @@ import Foundation
 
 @MainActor
 enum CLIInstaller {
-    private static func embeddedHelperURL() -> URL {
-        Bundle.main.bundleURL.appendingPathComponent("Contents/Resources/Relay/clawdbot")
-    }
-
     static func installedLocation() -> String? {
         self.installedLocation(
-            searchPaths: cliHelperSearchPaths,
-            embeddedHelper: self.embeddedHelperURL(),
+            searchPaths: CommandResolver.preferredPaths(),
             fileManager: .default)
     }
 
     static func installedLocation(
         searchPaths: [String],
-        embeddedHelper: URL,
         fileManager: FileManager) -> String?
     {
-        let embedded = embeddedHelper.resolvingSymlinksInPath()
-
         for basePath in searchPaths {
             let candidate = URL(fileURLWithPath: basePath).appendingPathComponent("clawdbot").path
             var isDirectory: ObjCBool = false
@@ -32,10 +24,7 @@ enum CLIInstaller {
 
             guard fileManager.isExecutableFile(atPath: candidate) else { continue }
 
-            let resolved = URL(fileURLWithPath: candidate).resolvingSymlinksInPath()
-            if resolved == embedded {
-                return candidate
-            }
+            return candidate
         }
 
         return nil
@@ -45,58 +34,70 @@ enum CLIInstaller {
         self.installedLocation() != nil
     }
 
-    static func install(statusHandler: @escaping @Sendable (String) async -> Void) async {
-        let helper = self.embeddedHelperURL()
-        guard FileManager.default.isExecutableFile(atPath: helper.path) else {
-            await statusHandler(
-                "Embedded CLI missing in bundle; repackage via scripts/package-mac-app.sh " +
-                    "(or restart-mac.sh without SKIP_GATEWAY_PACKAGE=1).")
+    static func install(statusHandler: @escaping @MainActor @Sendable (String) async -> Void) async {
+        let expected = GatewayEnvironment.expectedGatewayVersion()?.description ?? "latest"
+        let prefix = Self.installPrefix()
+        await statusHandler("Installing clawdbot CLI…")
+        let cmd = self.installScriptCommand(version: expected, prefix: prefix)
+        let response = await ShellExecutor.runDetailed(command: cmd, cwd: nil, env: nil, timeout: 900)
+
+        if response.success {
+            let parsed = self.parseInstallEvents(response.stdout)
+            let installedVersion = parsed.last { $0.event == "done" }?.version
+            let summary = installedVersion.map { "Installed clawdbot \($0)." } ?? "Installed clawdbot."
+            await statusHandler(summary)
             return
         }
 
-        let targets = cliHelperSearchPaths.map { "\($0)/clawdbot" }
-        let result = await self.privilegedSymlink(source: helper.path, targets: targets)
-        await statusHandler(result)
-    }
-
-    private static func privilegedSymlink(source: String, targets: [String]) async -> String {
-        let escapedSource = self.shellEscape(source)
-        let targetList = targets.map(self.shellEscape).joined(separator: " ")
-        let cmds = [
-            "mkdir -p /usr/local/bin /opt/homebrew/bin",
-            targets.map { "ln -sf \(escapedSource) \($0)" }.joined(separator: "; "),
-        ].joined(separator: "; ")
-
-        let script = """
-        do shell script "\(cmds)" with administrator privileges
-        """
-
-        let proc = Process()
-        proc.executableURL = URL(fileURLWithPath: "/usr/bin/osascript")
-        proc.arguments = ["-e", script]
-
-        let pipe = Pipe()
-        proc.standardOutput = pipe
-        proc.standardError = pipe
-
-        do {
-            try proc.run()
-            proc.waitUntilExit()
-            let data = pipe.fileHandleForReading.readToEndSafely()
-            let output = String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-            if proc.terminationStatus == 0 {
-                return output.isEmpty ? "CLI helper linked into \(targetList)" : output
-            }
-            if output.lowercased().contains("user canceled") {
-                return "Install canceled"
-            }
-            return "Failed to install CLI helper: \(output)"
-        } catch {
-            return "Failed to run installer: \(error.localizedDescription)"
+        let parsed = self.parseInstallEvents(response.stdout)
+        if let error = parsed.last(where: { $0.event == "error" })?.message {
+            await statusHandler("Install failed: \(error)")
+            return
         }
+
+        let detail = response.stderr.trimmingCharacters(in: .whitespacesAndNewlines)
+        let fallback = response.errorMessage ?? "install failed"
+        await statusHandler("Install failed: \(detail.isEmpty ? fallback : detail)")
     }
 
-    private static func shellEscape(_ path: String) -> String {
-        "'" + path.replacingOccurrences(of: "'", with: "'\"'\"'") + "'"
+    private static func installPrefix() -> String {
+        FileManager.default.homeDirectoryForCurrentUser
+            .appendingPathComponent(".clawdbot")
+            .path
+    }
+
+    private static func installScriptCommand(version: String, prefix: String) -> [String] {
+        let escapedVersion = self.shellEscape(version)
+        let escapedPrefix = self.shellEscape(prefix)
+        let script = """
+        curl -fsSL https://clawd.bot/install-cli.sh | \
+        bash -s -- --json --no-onboard --prefix \(escapedPrefix) --version \(escapedVersion)
+        """
+        return ["/bin/bash", "-lc", script]
+    }
+
+    private static func parseInstallEvents(_ output: String) -> [InstallEvent] {
+        let decoder = JSONDecoder()
+        let lines = output
+            .split(whereSeparator: \.isNewline)
+            .map { String($0) }
+        var events: [InstallEvent] = []
+        for line in lines {
+            guard let data = line.data(using: .utf8) else { continue }
+            if let event = try? decoder.decode(InstallEvent.self, from: data) {
+                events.append(event)
+            }
+        }
+        return events
+    }
+
+    private static func shellEscape(_ raw: String) -> String {
+        "'" + raw.replacingOccurrences(of: "'", with: "'\"'\"'") + "'"
     }
 }
+
+private struct InstallEvent: Decodable {
+    let event: String
+    let version: String?
+    let message: String?
+}

apps/macos/Sources/Clawdbot/CommandResolver.swift

@@ -84,12 +84,30 @@ enum CommandResolver {
             "/bin",
         ]
         extras.insert(projectRoot.appendingPathComponent("node_modules/.bin").path, at: 0)
-        extras.insert(contentsOf: self.nodeManagerBinPaths(home: home), at: 1)
+        let clawdbotPaths = self.clawdbotManagedPaths(home: home)
+        if !clawdbotPaths.isEmpty {
+            extras.insert(contentsOf: clawdbotPaths, at: 1)
+        }
+        extras.insert(contentsOf: self.nodeManagerBinPaths(home: home), at: 1 + clawdbotPaths.count)
         var seen = Set<String>()
         // Preserve order while stripping duplicates so PATH lookups remain deterministic.
         return (extras + current).filter { seen.insert($0).inserted }
     }
 
+    private static func clawdbotManagedPaths(home: URL) -> [String] {
+        let base = home.appendingPathComponent(".clawdbot")
+        let bin = base.appendingPathComponent("bin")
+        let nodeBin = base.appendingPathComponent("tools/node/bin")
+        var paths: [String] = []
+        if FileManager.default.fileExists(atPath: bin.path) {
+            paths.append(bin.path)
+        }
+        if FileManager.default.fileExists(atPath: nodeBin.path) {
+            paths.append(nodeBin.path)
+        }
+        return paths
+    }
+
     private static func nodeManagerBinPaths(home: URL) -> [String] {
         var bins: [String] = []
 
@@ -387,10 +405,6 @@ enum CommandResolver {
             cliPath: cliPath)
     }
 
-    static var attachExistingGatewayOnly: Bool {
-        UserDefaults.standard.bool(forKey: attachExistingGatewayOnlyKey)
-    }
-
     static func connectionModeIsRemote(defaults: UserDefaults = .standard) -> Bool {
         self.connectionSettings(defaults: defaults).mode == .remote
     }

apps/macos/Sources/Clawdbot/ConfigSettings.swift

@@ -70,7 +70,9 @@ struct ConfigSettings: View {
                 self.allowAutosave = true
             }
     }
+}
 
+extension ConfigSettings {
     private var content: some View {
         VStack(alignment: .leading, spacing: 14) {
             self.header
@@ -461,7 +463,9 @@ struct ConfigSettings: View {
         }
         .padding(.top, 2)
     }
+}
 
+extension ConfigSettings {
     private func loadConfig() async {
         let parsed = await ConfigStore.load()
         let agents = parsed["agents"] as? [String: Any]
@@ -639,7 +643,9 @@ struct ConfigSettings: View {
             return error.localizedDescription
         }
     }
+}
 
+extension ConfigSettings {
     private var browserColor: Color {
         let raw = self.browserColorHex.trimmingCharacters(in: .whitespacesAndNewlines)
         let hex = raw.hasPrefix("#") ? String(raw.dropFirst()) : raw
@@ -736,7 +742,9 @@ struct ConfigSettings: View {
         if host == "::1" { return true }
         return false
     }
+}
 
+extension ConfigSettings {
     private func loadModels() async {
         guard !self.modelsLoading else { return }
         self.modelsLoading = true

apps/macos/Sources/Clawdbot/ConnectionModeCoordinator.swift

@@ -27,8 +27,7 @@ final class ConnectionModeCoordinator {
                 GatewayProcessManager.shared.setActive(true)
                 if GatewayAutostartPolicy.shouldEnsureLaunchAgent(
                     mode: .local,
-                    paused: paused,
-                    attachExistingOnly: AppStateStore.attachExistingGatewayOnly)
+                    paused: paused)
                 {
                     Task { await GatewayProcessManager.shared.ensureLaunchAgentEnabledIfNeeded() }
                 }

apps/macos/Sources/Clawdbot/ConnectionsSettings+ProviderState.swift

@@ -1,8 +1,16 @@
 import SwiftUI
 
 extension ConnectionsSettings {
+    private func providerStatus<T: Decodable>(
+        _ id: String,
+        as type: T.Type) -> T?
+    {
+        self.store.snapshot?.decodeProvider(id, as: type)
+    }
+
     var whatsAppTint: Color {
-        guard let status = self.store.snapshot?.whatsapp else { return .secondary }
+        guard let status = self.providerStatus("whatsapp", as: ProvidersStatusSnapshot.WhatsAppStatus.self)
+        else { return .secondary }
         if !status.configured { return .secondary }
         if !status.linked { return .red }
         if status.lastError != nil { return .orange }
@@ -12,7 +20,8 @@ extension ConnectionsSettings {
     }
 
     var telegramTint: Color {
-        guard let status = self.store.snapshot?.telegram else { return .secondary }
+        guard let status = self.providerStatus("telegram", as: ProvidersStatusSnapshot.TelegramStatus.self)
+        else { return .secondary }
         if !status.configured { return .secondary }
         if status.lastError != nil { return .orange }
         if status.probe?.ok == false { return .orange }
@@ -21,7 +30,8 @@ extension ConnectionsSettings {
     }
 
     var discordTint: Color {
-        guard let status = self.store.snapshot?.discord else { return .secondary }
+        guard let status = self.providerStatus("discord", as: ProvidersStatusSnapshot.DiscordStatus.self)
+        else { return .secondary }
         if !status.configured { return .secondary }
         if status.lastError != nil { return .orange }
         if status.probe?.ok == false { return .orange }
@@ -30,7 +40,8 @@ extension ConnectionsSettings {
     }
 
     var signalTint: Color {
-        guard let status = self.store.snapshot?.signal else { return .secondary }
+        guard let status = self.providerStatus("signal", as: ProvidersStatusSnapshot.SignalStatus.self)
+        else { return .secondary }
         if !status.configured { return .secondary }
         if status.lastError != nil { return .orange }
         if status.probe?.ok == false { return .orange }
@@ -39,7 +50,8 @@ extension ConnectionsSettings {
     }
 
     var imessageTint: Color {
-        guard let status = self.store.snapshot?.imessage else { return .secondary }
+        guard let status = self.providerStatus("imessage", as: ProvidersStatusSnapshot.IMessageStatus.self)
+        else { return .secondary }
         if !status.configured { return .secondary }
         if status.lastError != nil { return .orange }
         if status.probe?.ok == false { return .orange }
@@ -48,7 +60,8 @@ extension ConnectionsSettings {
     }
 
     var whatsAppSummary: String {
-        guard let status = self.store.snapshot?.whatsapp else { return "Checking…" }
+        guard let status = self.providerStatus("whatsapp", as: ProvidersStatusSnapshot.WhatsAppStatus.self)
+        else { return "Checking…" }
         if !status.linked { return "Not linked" }
         if status.connected { return "Connected" }
         if status.running { return "Running" }
@@ -56,35 +69,40 @@ extension ConnectionsSettings {
     }
 
     var telegramSummary: String {
-        guard let status = self.store.snapshot?.telegram else { return "Checking…" }
+        guard let status = self.providerStatus("telegram", as: ProvidersStatusSnapshot.TelegramStatus.self)
+        else { return "Checking…" }
         if !status.configured { return "Not configured" }
         if status.running { return "Running" }
         return "Configured"
     }
 
     var discordSummary: String {
-        guard let status = self.store.snapshot?.discord else { return "Checking…" }
+        guard let status = self.providerStatus("discord", as: ProvidersStatusSnapshot.DiscordStatus.self)
+        else { return "Checking…" }
         if !status.configured { return "Not configured" }
         if status.running { return "Running" }
         return "Configured"
     }
 
     var signalSummary: String {
-        guard let status = self.store.snapshot?.signal else { return "Checking…" }
+        guard let status = self.providerStatus("signal", as: ProvidersStatusSnapshot.SignalStatus.self)
+        else { return "Checking…" }
         if !status.configured { return "Not configured" }
         if status.running { return "Running" }
         return "Configured"
     }
 
     var imessageSummary: String {
-        guard let status = self.store.snapshot?.imessage else { return "Checking…" }
+        guard let status = self.providerStatus("imessage", as: ProvidersStatusSnapshot.IMessageStatus.self)
+        else { return "Checking…" }
         if !status.configured { return "Not configured" }
         if status.running { return "Running" }
         return "Configured"
     }
 
     var whatsAppDetails: String? {
-        guard let status = self.store.snapshot?.whatsapp else { return nil }
+        guard let status = self.providerStatus("whatsapp", as: ProvidersStatusSnapshot.WhatsAppStatus.self)
+        else { return nil }
         var lines: [String] = []
         if let e164 = status.`self`?.e164 ?? status.`self`?.jid {
             lines.append("Linked as \(e164)")
@@ -114,7 +132,8 @@ extension ConnectionsSettings {
     }
 
     var telegramDetails: String? {
-        guard let status = self.store.snapshot?.telegram else { return nil }
+        guard let status = self.providerStatus("telegram", as: ProvidersStatusSnapshot.TelegramStatus.self)
+        else { return nil }
         var lines: [String] = []
         if let source = status.tokenSource {
             lines.append("Token source: \(source)")
@@ -145,7 +164,8 @@ extension ConnectionsSettings {
     }
 
     var discordDetails: String? {
-        guard let status = self.store.snapshot?.discord else { return nil }
+        guard let status = self.providerStatus("discord", as: ProvidersStatusSnapshot.DiscordStatus.self)
+        else { return nil }
         var lines: [String] = []
         if let source = status.tokenSource {
             lines.append("Token source: \(source)")
@@ -173,7 +193,8 @@ extension ConnectionsSettings {
     }
 
     var signalDetails: String? {
-        guard let status = self.store.snapshot?.signal else { return nil }
+        guard let status = self.providerStatus("signal", as: ProvidersStatusSnapshot.SignalStatus.self)
+        else { return nil }
         var lines: [String] = []
         lines.append("Base URL: \(status.baseUrl)")
         if let probe = status.probe {
@@ -199,7 +220,8 @@ extension ConnectionsSettings {
     }
 
     var imessageDetails: String? {
-        guard let status = self.store.snapshot?.imessage else { return nil }
+        guard let status = self.providerStatus("imessage", as: ProvidersStatusSnapshot.IMessageStatus.self)
+        else { return nil }
         var lines: [String] = []
         if let cliPath = status.cliPath, !cliPath.isEmpty {
             lines.append("CLI: \(cliPath)")
@@ -221,11 +243,11 @@ extension ConnectionsSettings {
     }
 
     var isTelegramTokenLocked: Bool {
-        self.store.snapshot?.telegram.tokenSource == "env"
+        self.providerStatus("telegram", as: ProvidersStatusSnapshot.TelegramStatus.self)?.tokenSource == "env"
     }
 
     var isDiscordTokenLocked: Bool {
-        self.store.snapshot?.discord?.tokenSource == "env"
+        self.providerStatus("discord", as: ProvidersStatusSnapshot.DiscordStatus.self)?.tokenSource == "env"
     }
 
     var orderedProviders: [ConnectionProvider] {
@@ -258,19 +280,24 @@ extension ConnectionsSettings {
     func providerEnabled(_ provider: ConnectionProvider) -> Bool {
         switch provider {
         case .whatsapp:
-            guard let status = self.store.snapshot?.whatsapp else { return false }
+            guard let status = self.providerStatus("whatsapp", as: ProvidersStatusSnapshot.WhatsAppStatus.self)
+            else { return false }
             return status.configured || status.linked || status.running
         case .telegram:
-            guard let status = self.store.snapshot?.telegram else { return false }
+            guard let status = self.providerStatus("telegram", as: ProvidersStatusSnapshot.TelegramStatus.self)
+            else { return false }
             return status.configured || status.running
         case .discord:
-            guard let status = self.store.snapshot?.discord else { return false }
+            guard let status = self.providerStatus("discord", as: ProvidersStatusSnapshot.DiscordStatus.self)
+            else { return false }
             return status.configured || status.running
         case .signal:
-            guard let status = self.store.snapshot?.signal else { return false }
+            guard let status = self.providerStatus("signal", as: ProvidersStatusSnapshot.SignalStatus.self)
+            else { return false }
             return status.configured || status.running
         case .imessage:
-            guard let status = self.store.snapshot?.imessage else { return false }
+            guard let status = self.providerStatus("imessage", as: ProvidersStatusSnapshot.IMessageStatus.self)
+            else { return false }
             return status.configured || status.running
         }
     }
@@ -344,35 +371,48 @@ extension ConnectionsSettings {
     func providerLastCheck(_ provider: ConnectionProvider) -> Date? {
         switch provider {
         case .whatsapp:
-            guard let status = self.store.snapshot?.whatsapp else { return nil }
+            guard let status = self.providerStatus("whatsapp", as: ProvidersStatusSnapshot.WhatsAppStatus.self)
+            else { return nil }
             return self.date(fromMs: status.lastEventAt ?? status.lastMessageAt ?? status.lastConnectedAt)
         case .telegram:
-            return self.date(fromMs: self.store.snapshot?.telegram.lastProbeAt)
+            return self
+                .date(fromMs: self.providerStatus("telegram", as: ProvidersStatusSnapshot.TelegramStatus.self)?
+                    .lastProbeAt)
         case .discord:
-            return self.date(fromMs: self.store.snapshot?.discord?.lastProbeAt)
+            return self
+                .date(fromMs: self.providerStatus("discord", as: ProvidersStatusSnapshot.DiscordStatus.self)?
+                    .lastProbeAt)
         case .signal:
-            return self.date(fromMs: self.store.snapshot?.signal?.lastProbeAt)
+            return self
+                .date(fromMs: self.providerStatus("signal", as: ProvidersStatusSnapshot.SignalStatus.self)?.lastProbeAt)
         case .imessage:
-            return self.date(fromMs: self.store.snapshot?.imessage?.lastProbeAt)
+            return self
+                .date(fromMs: self.providerStatus("imessage", as: ProvidersStatusSnapshot.IMessageStatus.self)?
+                    .lastProbeAt)
         }
     }
 
     func providerHasError(_ provider: ConnectionProvider) -> Bool {
         switch provider {
         case .whatsapp:
-            guard let status = self.store.snapshot?.whatsapp else { return false }
+            guard let status = self.providerStatus("whatsapp", as: ProvidersStatusSnapshot.WhatsAppStatus.self)
+            else { return false }
             return status.lastError?.isEmpty == false || status.lastDisconnect?.loggedOut == true
         case .telegram:
-            guard let status = self.store.snapshot?.telegram else { return false }
+            guard let status = self.providerStatus("telegram", as: ProvidersStatusSnapshot.TelegramStatus.self)
+            else { return false }
             return status.lastError?.isEmpty == false || status.probe?.ok == false
         case .discord:
-            guard let status = self.store.snapshot?.discord else { return false }
+            guard let status = self.providerStatus("discord", as: ProvidersStatusSnapshot.DiscordStatus.self)
+            else { return false }
             return status.lastError?.isEmpty == false || status.probe?.ok == false
         case .signal:
-            guard let status = self.store.snapshot?.signal else { return false }
+            guard let status = self.providerStatus("signal", as: ProvidersStatusSnapshot.SignalStatus.self)
+            else { return false }
             return status.lastError?.isEmpty == false || status.probe?.ok == false
         case .imessage:
-            guard let status = self.store.snapshot?.imessage else { return false }
+            guard let status = self.providerStatus("imessage", as: ProvidersStatusSnapshot.IMessageStatus.self)
+            else { return false }
             return status.lastError?.isEmpty == false || status.probe?.ok == false
         }
     }

apps/macos/Sources/Clawdbot/ConnectionsStore+Lifecycle.swift

@@ -100,9 +100,12 @@ extension ConnectionsStore {
         self.whatsappBusy = true
         defer { self.whatsappBusy = false }
         do {
-            let result: WhatsAppLogoutResult = try await GatewayConnection.shared.requestDecoded(
-                method: .webLogout,
-                params: nil,
+            let params: [String: AnyCodable] = [
+                "provider": AnyCodable("whatsapp"),
+            ]
+            let result: ProviderLogoutResult = try await GatewayConnection.shared.requestDecoded(
+                method: .providersLogout,
+                params: params,
                 timeoutMs: 15000)
             self.whatsappLoginMessage = result.cleared
                 ? "Logged out and cleared credentials."
@@ -119,9 +122,12 @@ extension ConnectionsStore {
         self.telegramBusy = true
         defer { self.telegramBusy = false }
         do {
-            let result: TelegramLogoutResult = try await GatewayConnection.shared.requestDecoded(
-                method: .telegramLogout,
-                params: nil,
+            let params: [String: AnyCodable] = [
+                "provider": AnyCodable("telegram"),
+            ]
+            let result: ProviderLogoutResult = try await GatewayConnection.shared.requestDecoded(
+                method: .providersLogout,
+                params: params,
                 timeoutMs: 15000)
             if result.envToken == true {
                 self.configStatus = "Telegram token still set via env; config cleared."
@@ -148,11 +154,9 @@ private struct WhatsAppLoginWaitResult: Codable {
     let message: String
 }
 
-private struct WhatsAppLogoutResult: Codable {
-    let cleared: Bool
-}
-
-private struct TelegramLogoutResult: Codable {
+private struct ProviderLogoutResult: Codable {
+    let provider: String?
+    let accountId: String?
     let cleared: Bool
     let envToken: Bool?
 }

apps/macos/Sources/Clawdbot/ConnectionsStore.swift

@@ -121,12 +121,54 @@ struct ProvidersStatusSnapshot: Codable {
         let lastProbeAt: Double?
     }
 
+    struct ProviderAccountSnapshot: Codable {
+        let accountId: String
+        let name: String?
+        let enabled: Bool?
+        let configured: Bool?
+        let linked: Bool?
+        let running: Bool?
+        let connected: Bool?
+        let reconnectAttempts: Int?
+        let lastConnectedAt: Double?
+        let lastError: String?
+        let lastStartAt: Double?
+        let lastStopAt: Double?
+        let lastInboundAt: Double?
+        let lastOutboundAt: Double?
+        let lastProbeAt: Double?
+        let mode: String?
+        let dmPolicy: String?
+        let allowFrom: [String]?
+        let tokenSource: String?
+        let botTokenSource: String?
+        let appTokenSource: String?
+        let baseUrl: String?
+        let allowUnmentionedGroups: Bool?
+        let cliPath: String?
+        let dbPath: String?
+        let port: Int?
+        let probe: AnyCodable?
+        let audit: AnyCodable?
+        let application: AnyCodable?
+    }
+
     let ts: Double
-    let whatsapp: WhatsAppStatus
-    let telegram: TelegramStatus
-    let discord: DiscordStatus?
-    let signal: SignalStatus?
-    let imessage: IMessageStatus?
+    let providerOrder: [String]
+    let providerLabels: [String: String]
+    let providers: [String: AnyCodable]
+    let providerAccounts: [String: [ProviderAccountSnapshot]]
+    let providerDefaultAccountId: [String: String]
+
+    func decodeProvider<T: Decodable>(_ id: String, as type: T.Type) -> T? {
+        guard let value = self.providers[id] else { return nil }
+        do {
+            let data = try JSONEncoder().encode(value)
+            return try JSONDecoder().decode(type, from: data)
+        } catch {
+            return nil
+        }
+    }
 }
 
 struct ConfigSnapshot: Codable {

apps/macos/Sources/Clawdbot/Constants.swift

@@ -32,9 +32,8 @@ let peekabooBridgeEnabledKey = "clawdbot.peekabooBridgeEnabled"
 let deepLinkKeyKey = "clawdbot.deepLinkKey"
 let modelCatalogPathKey = "clawdbot.modelCatalogPath"
 let modelCatalogReloadKey = "clawdbot.modelCatalogReload"
-let attachExistingGatewayOnlyKey = "clawdbot.gateway.attachExistingOnly"
+let cliInstallPromptedVersionKey = "clawdbot.cliInstallPromptedVersion"
 let heartbeatsEnabledKey = "clawdbot.heartbeatsEnabled"
 let debugFileLogEnabledKey = "clawdbot.debug.fileLogEnabled"
 let appLogLevelKey = "clawdbot.debug.appLogLevel"
 let voiceWakeSupported: Bool = ProcessInfo.processInfo.operatingSystemVersion.majorVersion >= 26
-let cliHelperSearchPaths = ["/usr/local/bin", "/opt/homebrew/bin"]

apps/macos/Sources/Clawdbot/ControlChannel.swift

@@ -212,12 +212,6 @@ final class ControlChannel {
                 return "Gateway connection was closed; start the gateway (localhost:\(port)) and retry."
             case .cannotFindHost, .cannotConnectToHost:
                 let isRemote = CommandResolver.connectionModeIsRemote()
-                if AppStateStore.attachExistingGatewayOnly, !isRemote {
-                    return """
-                    Cannot reach gateway at localhost:\(port) and “Attach existing gateway only” is enabled.
-                    Disable it in Debug Settings or start a gateway on that port.
-                    """
-                }
                 if isRemote {
                     return """
                     Cannot reach gateway at localhost:\(port).

apps/macos/Sources/Clawdbot/DebugSettings.swift

@@ -107,7 +107,7 @@ struct DebugSettings: View {
                     .frame(maxWidth: .infinity, alignment: .leading)
                 }
                 GridRow {
-                    self.gridLabel("CLI helper")
+                    self.gridLabel("CLI")
                     let loc = CLIInstaller.installedLocation()
                     Text(loc ?? "missing")
                         .font(.caption.monospaced())
@@ -772,7 +772,7 @@ struct DebugSettings: View {
     }
 
     private var canRestartGateway: Bool {
-        self.state.connectionMode == .local && !self.state.attachExistingGatewayOnly
+        self.state.connectionMode == .local
     }
 
     private func configURL() -> URL {

apps/macos/Sources/Clawdbot/GatewayAutostartPolicy.swift

@@ -7,9 +7,8 @@ enum GatewayAutostartPolicy {
 
     static func shouldEnsureLaunchAgent(
         mode: AppState.ConnectionMode,
-        paused: Bool,
-        attachExistingOnly: Bool) -> Bool
+        paused: Bool) -> Bool
     {
-        self.shouldStartGateway(mode: mode, paused: paused) && !attachExistingOnly
+        self.shouldStartGateway(mode: mode, paused: paused)
     }
 }

apps/macos/Sources/Clawdbot/GatewayChannel.swift

@@ -1,3 +1,4 @@
+import ClawdbotKit
 import ClawdbotProtocol
 import Foundation
 import OSLog
@@ -75,6 +76,7 @@ actor GatewayChannelActor {
     private var tickIntervalMs: Double = 30000
     private let decoder = JSONDecoder()
     private let encoder = JSONEncoder()
+    private let connectTimeoutSeconds: Double = 6
     private var watchdogTask: Task<Void, Never>?
     private var tickTask: Task<Void, Never>?
     private let defaultRequestTimeoutMs: Double = 15000
@@ -163,7 +165,15 @@ actor GatewayChannelActor {
         self.task = self.session.makeWebSocketTask(url: self.url)
         self.task?.resume()
         do {
-            try await self.sendConnect()
+            try await AsyncTimeout.withTimeout(
+                seconds: self.connectTimeoutSeconds,
+                onTimeout: {
+                    NSError(
+                        domain: "Gateway",
+                        code: 1,
+                        userInfo: [NSLocalizedDescriptionKey: "connect timed out"])
+                },
+                operation: { try await self.sendConnect() })
         } catch {
             let wrapped = self.wrap(error, context: "connect to gateway @ \(self.url.absoluteString)")
             self.connected = false
@@ -192,15 +202,17 @@ actor GatewayChannelActor {
         let osVersion = ProcessInfo.processInfo.operatingSystemVersion
         let platform = "macos \(osVersion.majorVersion).\(osVersion.minorVersion).\(osVersion.patchVersion)"
         let primaryLocale = Locale.preferredLanguages.first ?? Locale.current.identifier
-        let clientName = InstanceIdentity.displayName
+        let clientDisplayName = InstanceIdentity.displayName
+        let clientId = "clawdbot-macos"
 
         let reqId = UUID().uuidString
         var client: [String: ProtoAnyCodable] = [
-            "name": ProtoAnyCodable(clientName),
+            "id": ProtoAnyCodable(clientId),
+            "displayName": ProtoAnyCodable(clientDisplayName),
             "version": ProtoAnyCodable(
                 Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "dev"),
             "platform": ProtoAnyCodable(platform),
-            "mode": ProtoAnyCodable("app"),
+            "mode": ProtoAnyCodable("ui"),
             "instanceId": ProtoAnyCodable(InstanceIdentity.instanceId),
         ]
         client["deviceFamily"] = ProtoAnyCodable("Mac")
@@ -379,7 +391,11 @@ actor GatewayChannelActor {
         }
     }
 
-    func request(method: String, params: [String: AnyCodable]?, timeoutMs: Double? = nil) async throws -> Data {
+    func request(
+        method: String,
+        params: [String: ClawdbotProtocol.AnyCodable]?,
+        timeoutMs: Double? = nil) async throws -> Data
+    {
         do {
             try await self.connect()
         } catch {
@@ -430,8 +446,8 @@ actor GatewayChannelActor {
         if res.ok == false {
             let code = res.error?["code"]?.value as? String
             let msg = res.error?["message"]?.value as? String
-            let details: [String: AnyCodable] = (res.error ?? [:]).reduce(into: [:]) { acc, pair in
-                acc[pair.key] = AnyCodable(pair.value.value)
+            let details: [String: ClawdbotProtocol.AnyCodable] = (res.error ?? [:]).reduce(into: [:]) { acc, pair in
+                acc[pair.key] = ClawdbotProtocol.AnyCodable(pair.value.value)
             }
             throw GatewayResponseError(method: method, code: code, message: msg, details: details)
         }

apps/macos/Sources/Clawdbot/GatewayConnection.swift

@@ -13,6 +13,7 @@ enum GatewayAgentProvider: String, Codable, CaseIterable, Sendable {
     case slack
     case signal
     case imessage
+    case msteams
     case webchat
 
     init(raw: String?) {
@@ -61,8 +62,7 @@ actor GatewayConnection {
         case talkMode = "talk.mode"
         case webLoginStart = "web.login.start"
         case webLoginWait = "web.login.wait"
-        case webLogout = "web.logout"
-        case telegramLogout = "telegram.logout"
+        case providersLogout = "providers.logout"
         case modelsList = "models.list"
         case chatHistory = "chat.history"
         case chatSend = "chat.send"

apps/macos/Sources/Clawdbot/GatewayEndpointStore.swift

@@ -226,7 +226,10 @@ actor GatewayEndpointStore {
         }
         let config = try await self.ensureRemoteConfig(detail: Self.remoteConnectingDetail)
         guard let portInt = config.0.port, let port = UInt16(exactly: portInt) else {
-            throw NSError(domain: "GatewayEndpoint", code: 1, userInfo: [NSLocalizedDescriptionKey: "Missing tunnel port"])
+            throw NSError(
+                domain: "GatewayEndpoint",
+                code: 1,
+                userInfo: [NSLocalizedDescriptionKey: "Missing tunnel port"])
         }
         return port
     }
@@ -290,7 +293,10 @@ actor GatewayEndpointStore {
             let forwarded = try await ensure.task.value
             let stillRemote = await self.deps.mode() == .remote
             guard stillRemote else {
-                throw NSError(domain: "RemoteTunnel", code: 1, userInfo: [NSLocalizedDescriptionKey: "Remote mode is not enabled"])
+                throw NSError(
+                    domain: "RemoteTunnel",
+                    code: 1,
+                    userInfo: [NSLocalizedDescriptionKey: "Remote mode is not enabled"])
             }
 
             if self.remoteEnsure?.token == ensure.token {

apps/macos/Sources/Clawdbot/GatewayEnvironment.swift

@@ -64,19 +64,6 @@ struct GatewayCommandResolution {
 enum GatewayEnvironment {
     private static let logger = Logger(subsystem: "com.clawdbot", category: "gateway.env")
     private static let supportedBindModes: Set<String> = ["loopback", "tailnet", "lan", "auto"]
-    private static let bundledGatewayLabel = "Bundled gateway"
-
-    static func bundledGatewayExecutable() -> String? {
-        guard let res = Bundle.main.resourceURL else { return nil }
-        let path = res.appendingPathComponent("Relay/clawdbot").path
-        return FileManager.default.isExecutableFile(atPath: path) ? path : nil
-    }
-
-    static func bundledNodeExecutable() -> String? {
-        guard let res = Bundle.main.resourceURL else { return nil }
-        let path = res.appendingPathComponent("Relay/node").path
-        return FileManager.default.isExecutableFile(atPath: path) ? path : nil
-    }
 
     static func gatewayPort() -> Int {
         if let raw = ProcessInfo.processInfo.environment["CLAWDBOT_GATEWAY_PORT"] {
@@ -112,32 +99,6 @@ enum GatewayEnvironment {
         }
         let expected = self.expectedGatewayVersion()
 
-        if let bundled = self.bundledGatewayExecutable() {
-            let installed = self.readGatewayVersion(binary: bundled)
-            let bundledNode = self.bundledNodeExecutable()
-            let bundledNodeVersion = bundledNode.flatMap { self.readNodeVersion(binary: $0) }
-            if let expected, let installed, !installed.compatible(with: expected) {
-                let message = self.bundledGatewayIncompatibleMessage(
-                    installed: installed,
-                    expected: expected)
-                return GatewayEnvironmentStatus(
-                    kind: .incompatible(found: installed.description, required: expected.description),
-                    nodeVersion: bundledNodeVersion,
-                    gatewayVersion: installed.description,
-                    requiredGateway: expected.description,
-                    message: message)
-            }
-            let gatewayVersionText = installed?.description ?? "unknown"
-            return GatewayEnvironmentStatus(
-                kind: .ok,
-                nodeVersion: bundledNodeVersion,
-                gatewayVersion: gatewayVersionText,
-                requiredGateway: expected?.description,
-                message: self.bundledGatewayStatusMessage(
-                    gatewayVersion: gatewayVersionText,
-                    nodeVersion: bundledNodeVersion))
-        }
-
         let projectRoot = CommandResolver.projectRoot()
         let projectEntrypoint = CommandResolver.gatewayEntrypoint(in: projectRoot)
 
@@ -158,7 +119,7 @@ enum GatewayEnvironment {
                     nodeVersion: runtime.version.description,
                     gatewayVersion: nil,
                     requiredGateway: expected?.description,
-                    message: "clawdbot CLI not found in PATH; install the global package.")
+                    message: "clawdbot CLI not found in PATH; install the CLI.")
             }
 
             let installed = gatewayBin.flatMap { self.readGatewayVersion(binary: $0) }
@@ -208,7 +169,6 @@ enum GatewayEnvironment {
         let projectEntrypoint = CommandResolver.gatewayEntrypoint(in: projectRoot)
         let status = self.check()
         let gatewayBin = CommandResolver.clawdbotExecutable()
-        let bundled = self.bundledGatewayExecutable()
         let runtime = RuntimeLocator.resolve(searchPaths: CommandResolver.preferredPaths())
 
         guard case .ok = status.kind else {
@@ -216,20 +176,17 @@ enum GatewayEnvironment {
         }
 
         let port = self.gatewayPort()
-        if let bundled {
-            let bind = self.preferredGatewayBind() ?? "loopback"
-            let cmd = [bundled, "gateway-daemon", "--port", "\(port)", "--bind", bind]
-            return GatewayCommandResolution(status: status, command: cmd)
-        }
         if let gatewayBin {
-            let cmd = [gatewayBin, "gateway", "--port", "\(port)"]
+            let bind = self.preferredGatewayBind() ?? "loopback"
+            let cmd = [gatewayBin, "gateway-daemon", "--port", "\(port)", "--bind", bind]
             return GatewayCommandResolution(status: status, command: cmd)
         }
 
         if let entry = projectEntrypoint,
            case let .success(resolvedRuntime) = runtime
         {
-            let cmd = [resolvedRuntime.path, entry, "gateway", "--port", "\(port)"]
+            let bind = self.preferredGatewayBind() ?? "loopback"
+            let cmd = [resolvedRuntime.path, entry, "gateway-daemon", "--port", "\(port)", "--bind", bind]
             return GatewayCommandResolution(status: status, command: cmd)
         }
 
@@ -362,41 +319,4 @@ enum GatewayEnvironment {
         else { return nil }
         return Semver.parse(version)
     }
-
-    private static func readNodeVersion(binary: String) -> String? {
-        let process = Process()
-        process.executableURL = URL(fileURLWithPath: binary)
-        process.arguments = ["--version"]
-        process.environment = ["PATH": CommandResolver.preferredPaths().joined(separator: ":")]
-
-        let pipe = Pipe()
-        process.standardOutput = pipe
-        process.standardError = pipe
-        do {
-            try process.run()
-            process.waitUntilExit()
-            let data = pipe.fileHandleForReading.readToEndSafely()
-            let raw = String(data: data, encoding: .utf8)?
-                .trimmingCharacters(in: .whitespacesAndNewlines)
-                .replacingOccurrences(of: "^v", with: "", options: .regularExpression)
-            return raw?.isEmpty == false ? raw : nil
-        } catch {
-            return nil
-        }
-    }
-
-    private static func bundledGatewayStatusMessage(
-        gatewayVersion: String,
-        nodeVersion: String?) -> String
-    {
-        "\(self.bundledGatewayLabel) \(gatewayVersion) (node \(nodeVersion ?? "unknown"))"
-    }
-
-    private static func bundledGatewayIncompatibleMessage(
-        installed: Semver,
-        expected: Semver) -> String
-    {
-        "\(self.bundledGatewayLabel) \(installed.description) is incompatible with app " +
-            "\(expected.description); rebuild the app bundle."
-    }
 }

apps/macos/Sources/Clawdbot/GatewayLaunchAgentManager.swift

@@ -6,6 +6,17 @@ enum GatewayLaunchAgentManager {
     private static let legacyGatewayLaunchdLabel = "com.steipete.clawdbot.gateway"
     private static let disableLaunchAgentMarker = ".clawdbot/disable-launchagent"
 
+    private enum GatewayProgramArgumentsError: LocalizedError {
+        case message(String)
+
+        var errorDescription: String? {
+            switch self {
+            case let .message(message):
+                message
+            }
+        }
+    }
+
     private static var plistURL: URL {
         FileManager.default.homeDirectoryForCurrentUser
             .appendingPathComponent("Library/LaunchAgents/\(gatewayLaunchdLabel).plist")
@@ -16,32 +27,46 @@ enum GatewayLaunchAgentManager {
             .appendingPathComponent("Library/LaunchAgents/\(legacyGatewayLaunchdLabel).plist")
     }
 
-    private static func gatewayExecutablePath(bundlePath: String) -> String {
-        "\(bundlePath)/Contents/Resources/Relay/clawdbot"
-    }
-
-    private static func relayDir(bundlePath: String) -> String {
-        "\(bundlePath)/Contents/Resources/Relay"
-    }
-
-    private static func gatewayProgramArguments(bundlePath: String, port: Int, bind: String) -> [String] {
-        #if DEBUG
+    private static func gatewayProgramArguments(
+        port: Int,
+        bind: String) -> Result<[String], GatewayProgramArgumentsError>
+    {
         let projectRoot = CommandResolver.projectRoot()
+        #if DEBUG
         if let localBin = CommandResolver.projectClawdbotExecutable(projectRoot: projectRoot) {
-            return [localBin, "gateway", "--port", "\(port)", "--bind", bind]
+            return .success([localBin, "gateway-daemon", "--port", "\(port)", "--bind", bind])
         }
-        if let entry = CommandResolver.gatewayEntrypoint(in: projectRoot),
-           case let .success(runtime) = CommandResolver.runtimeResolution()
-        {
-            return CommandResolver.makeRuntimeCommand(
-                runtime: runtime,
-                entrypoint: entry,
-                subcommand: "gateway",
-                extraArgs: ["--port", "\(port)", "--bind", bind])
+        if let entry = CommandResolver.gatewayEntrypoint(in: projectRoot) {
+            switch CommandResolver.runtimeResolution() {
+            case let .success(runtime):
+                let cmd = CommandResolver.makeRuntimeCommand(
+                    runtime: runtime,
+                    entrypoint: entry,
+                    subcommand: "gateway-daemon",
+                    extraArgs: ["--port", "\(port)", "--bind", bind])
+                return .success(cmd)
+            case .failure:
+                break
+            }
         }
         #endif
-        let gatewayBin = self.gatewayExecutablePath(bundlePath: bundlePath)
-        return [gatewayBin, "gateway-daemon", "--port", "\(port)", "--bind", bind]
+        let searchPaths = CommandResolver.preferredPaths()
+        if let gatewayBin = CommandResolver.clawdbotExecutable(searchPaths: searchPaths) {
+            return .success([gatewayBin, "gateway-daemon", "--port", "\(port)", "--bind", bind])
+        }
+
+        if let entry = CommandResolver.gatewayEntrypoint(in: projectRoot),
+           case let .success(runtime) = CommandResolver.runtimeResolution(searchPaths: searchPaths)
+        {
+            let cmd = CommandResolver.makeRuntimeCommand(
+                runtime: runtime,
+                entrypoint: entry,
+                subcommand: "gateway-daemon",
+                extraArgs: ["--port", "\(port)", "--bind", bind])
+            return .success(cmd)
+        }
+
+        return .failure(.message("clawdbot CLI not found in PATH; install the CLI."))
     }
 
     static func isLoaded() async -> Bool {
@@ -51,18 +76,14 @@ enum GatewayLaunchAgentManager {
     }
 
     static func set(enabled: Bool, bundlePath: String, port: Int) async -> String? {
+        _ = bundlePath
         if enabled, self.isLaunchAgentWriteDisabled() {
-            self.logger.info("launchd enable skipped (attach-only or disable marker set)")
+            self.logger.info("launchd enable skipped (disable marker set)")
             return nil
         }
         if enabled {
             _ = await Launchctl.run(["bootout", "gui/\(getuid())/\(self.legacyGatewayLaunchdLabel)"])
             try? FileManager.default.removeItem(at: self.legacyPlistURL)
-            let gatewayBin = self.gatewayExecutablePath(bundlePath: bundlePath)
-            guard FileManager.default.isExecutableFile(atPath: gatewayBin) else {
-                self.logger.error("launchd enable failed: gateway missing at \(gatewayBin)")
-                return "Embedded gateway missing in bundle; rebuild via scripts/package-mac-app.sh"
-            }
 
             let desiredBind = self.preferredGatewayBind() ?? "loopback"
             let desiredToken = self.preferredGatewayToken()
@@ -72,22 +93,30 @@ enum GatewayLaunchAgentManager {
                 bind: desiredBind,
                 token: desiredToken,
                 password: desiredPassword)
+            let programArgumentsResult = self.gatewayProgramArguments(port: port, bind: desiredBind)
+            guard case let .success(programArguments) = programArgumentsResult else {
+                if case let .failure(error) = programArgumentsResult {
+                    let message = error.localizedDescription
+                    self.logger.error("launchd enable failed: \(message)")
+                    return message
+                }
+                return "Failed to resolve gateway command."
+            }
 
             // If launchd already loaded the job (common on login), avoid `bootout` unless we must
             // change the config. `bootout` can kill a just-started gateway and cause attach loops.
             let loaded = await self.isLoaded()
-            if loaded,
-               let existing = self.readPlistConfig(),
-               existing.matches(desiredConfig)
-            {
-                self.logger.info("launchd job already loaded with desired config; skipping bootout")
-                await self.ensureEnabled()
-                _ = await Launchctl.run(["kickstart", "gui/\(getuid())/\(gatewayLaunchdLabel)"])
-                return nil
+            if loaded {
+                if let existing = self.readPlistConfig(), existing.matches(desiredConfig) {
+                    self.logger.info("launchd job already loaded with desired config; skipping bootout")
+                    await self.ensureEnabled()
+                    _ = await Launchctl.run(["kickstart", "gui/\(getuid())/\(gatewayLaunchdLabel)"])
+                    return nil
+                }
             }
 
             self.logger.info("launchd enable requested port=\(port) bind=\(desiredBind)")
-            self.writePlist(bundlePath: bundlePath, port: port)
+            self.writePlist(programArguments: programArguments)
 
             await self.ensureEnabled()
             if loaded {
@@ -116,19 +145,13 @@ enum GatewayLaunchAgentManager {
         _ = await Launchctl.run(["kickstart", "-k", "gui/\(getuid())/\(gatewayLaunchdLabel)"])
     }
 
-    private static func writePlist(bundlePath: String, port: Int) {
-        let relayDir = self.relayDir(bundlePath: bundlePath)
-        let preferredPath = ([relayDir] + CommandResolver.preferredPaths())
-            .joined(separator: ":")
-        let bind = self.preferredGatewayBind() ?? "loopback"
-        let programArguments = self.gatewayProgramArguments(bundlePath: bundlePath, port: port, bind: bind)
+    private static func writePlist(programArguments: [String]) {
+        let preferredPath = CommandResolver.preferredPaths().joined(separator: ":")
         let token = self.preferredGatewayToken()
         let password = self.preferredGatewayPassword()
         var envEntries = """
             <key>PATH</key>
             <string>\(preferredPath)</string>
-            <key>CLAWDBOT_IMAGE_BACKEND</key>
-            <string>sips</string>
         """
         if let token {
             let escapedToken = self.escapePlistValue(token)
@@ -308,9 +331,6 @@ enum GatewayLaunchAgentManager {
 
 extension GatewayLaunchAgentManager {
     private static func isLaunchAgentWriteDisabled() -> Bool {
-        if UserDefaults.standard.bool(forKey: attachExistingGatewayOnlyKey) {
-            return true
-        }
         let marker = FileManager.default.homeDirectoryForCurrentUser
             .appendingPathComponent(self.disableLaunchAgentMarker)
         return FileManager.default.fileExists(atPath: marker.path)
@@ -319,14 +339,6 @@ extension GatewayLaunchAgentManager {
 
 #if DEBUG
 extension GatewayLaunchAgentManager {
-    static func _testGatewayExecutablePath(bundlePath: String) -> String {
-        self.gatewayExecutablePath(bundlePath: bundlePath)
-    }
-
-    static func _testRelayDir(bundlePath: String) -> String {
-        self.relayDir(bundlePath: bundlePath)
-    }
-
     static func _testPreferredGatewayBind() -> String? {
         self.preferredGatewayBind()
     }

apps/macos/Sources/Clawdbot/GatewayProcessManager.swift

@@ -69,7 +69,6 @@ final class GatewayProcessManager {
 
     func ensureLaunchAgentEnabledIfNeeded() async {
         guard !CommandResolver.connectionModeIsRemote() else { return }
-        guard !AppStateStore.attachExistingGatewayOnly else { return }
         let enabled = await GatewayLaunchAgentManager.isLoaded()
         guard !enabled else { return }
         let bundlePath = Bundle.main.bundleURL.path
@@ -97,15 +96,6 @@ final class GatewayProcessManager {
             if await self.attachExistingGatewayIfAvailable() {
                 return
             }
-            // Respect debug toggle: only attach, never spawn, when enabled.
-            if AppStateStore.attachExistingGatewayOnly {
-                await MainActor.run {
-                    self.status = .failed("Attach-only enabled; no gateway to attach")
-                    self.appendLog("[gateway] attach-only enabled; not spawning local gateway\n")
-                    self.logger.warning("gateway attach-only enabled; not spawning")
-                }
-                return
-            }
             await self.enableLaunchdGateway()
         }
     }
@@ -221,9 +211,21 @@ final class GatewayProcessManager {
     private func describe(details instance: String?, port: Int, snap: HealthSnapshot?) -> String {
         let instanceText = instance ?? "pid unknown"
         if let snap {
-            let linked = snap.web.linked ? "linked" : "not linked"
-            let authAge = snap.web.authAgeMs.flatMap(msToAge) ?? "unknown age"
-            return "port \(port), \(linked), auth \(authAge), \(instanceText)"
+            let linkId = snap.providerOrder?.first(where: {
+                if let summary = snap.providers[$0] { return summary.linked != nil }
+                return false
+            }) ?? snap.providers.keys.first(where: {
+                if let summary = snap.providers[$0] { return summary.linked != nil }
+                return false
+            })
+            let linked = linkId.flatMap { snap.providers[$0]?.linked } ?? false
+            let authAge = linkId.flatMap { snap.providers[$0]?.authAgeMs }.flatMap(msToAge) ?? "unknown age"
+            let label =
+                linkId.flatMap { snap.providerLabels?[$0] } ??
+                linkId?.capitalized ??
+                "provider"
+            let linkText = linked ? "linked" : "not linked"
+            return "port \(port), \(label) \(linkText), auth \(authAge), \(instanceText)"
         }
         return "port \(port), health probe succeeded, \(instanceText)"
     }

apps/macos/Sources/Clawdbot/GeneralSettings.swift

@@ -204,11 +204,6 @@ struct GeneralSettings: View {
                 if !self.isNixMode {
                     self.gatewayInstallerCard
                 }
-                SettingsToggleRow(
-                    title: "Attach only",
-                    subtitle: "Use this when the gateway runs externally; the mac app will only attach " +
-                        "to an already-running gateway and won't start one locally.",
-                    binding: self.$state.attachExistingGatewayOnly)
                 TailscaleIntegrationSection(
                     connectionMode: self.state.connectionMode,
                     isPaused: self.state.isPaused)
@@ -354,7 +349,7 @@ struct GeneralSettings: View {
                 Button {
                     Task { await self.installCLI() }
                 } label: {
-                    let title = self.cliInstalled ? "Reinstall CLI helper" : "Install CLI helper"
+                    let title = self.cliInstalled ? "Reinstall CLI" : "Install CLI"
                     ZStack {
                         Text(title)
                             .opacity(self.isInstallingCLI ? 0 : 1)
@@ -393,7 +388,7 @@ struct GeneralSettings: View {
                     .foregroundStyle(.secondary)
                     .lineLimit(2)
             } else {
-                Text("Symlink \"clawdbot\" into /usr/local/bin and /opt/homebrew/bin for scripts.")
+                Text("Installs a user-space Node 22+ runtime and the CLI (no Homebrew).")
                     .font(.caption)
                     .foregroundStyle(.secondary)
                     .lineLimit(2)
@@ -461,10 +456,8 @@ struct GeneralSettings: View {
         self.isInstallingCLI = true
         defer { isInstallingCLI = false }
         await CLIInstaller.install { status in
-            await MainActor.run {
-                self.cliStatus = status
-                self.refreshCLIStatus()
-            }
+            self.cliStatus = status
+            self.refreshCLIStatus()
         }
     }
 
@@ -503,7 +496,19 @@ struct GeneralSettings: View {
             }
 
             if let snap = snapshot {
-                Text("Linked auth age: \(healthAgeString(snap.web.authAgeMs))")
+                let linkId = snap.providerOrder?.first(where: {
+                    if let summary = snap.providers[$0] { return summary.linked != nil }
+                    return false
+                }) ?? snap.providers.keys.first(where: {
+                    if let summary = snap.providers[$0] { return summary.linked != nil }
+                    return false
+                })
+                let linkLabel =
+                    linkId.flatMap { snap.providerLabels?[$0] } ??
+                    linkId?.capitalized ??
+                    "Link provider"
+                let linkAge = linkId.flatMap { snap.providers[$0]?.authAgeMs }
+                Text("\(linkLabel) auth age: \(healthAgeString(linkAge))")
                     .font(.caption)
                     .foregroundStyle(.secondary)
                 Text("Session store: \(snap.sessions.path) (\(snap.sessions.count) entries)")

apps/macos/Sources/Clawdbot/HealthStore.swift

@@ -4,35 +4,29 @@ import Observation
 import SwiftUI
 
 struct HealthSnapshot: Codable, Sendable {
-    struct Telegram: Codable, Sendable {
+    struct ProviderSummary: Codable, Sendable {
         struct Probe: Codable, Sendable {
             struct Bot: Codable, Sendable {
-                let id: Int?
                 let username: String?
             }
 
-            let ok: Bool
+            struct Webhook: Codable, Sendable {
+                let url: String?
+            }
+
+            let ok: Bool?
             let status: Int?
             let error: String?
             let elapsedMs: Double?
             let bot: Bot?
+            let webhook: Webhook?
         }
 
-        let configured: Bool
-        let probe: Probe?
-    }
-
-    struct Web: Codable, Sendable {
-        struct Connect: Codable, Sendable {
-            let ok: Bool
-            let status: Int?
-            let error: String?
-            let elapsedMs: Double?
-        }
-
-        let linked: Bool
+        let configured: Bool?
+        let linked: Bool?
         let authAgeMs: Double?
-        let connect: Connect?
+        let probe: Probe?
+        let lastProbeAt: Double?
     }
 
     struct SessionInfo: Codable, Sendable {
@@ -50,8 +44,9 @@ struct HealthSnapshot: Codable, Sendable {
     let ok: Bool?
     let ts: Double
     let durationMs: Double
-    let web: Web
-    let telegram: Telegram?
+    let providers: [String: ProviderSummary]
+    let providerOrder: [String]?
+    let providerLabels: [String: String]?
     let heartbeatSeconds: Int?
     let sessions: Sessions
 }
@@ -94,6 +89,13 @@ final class HealthStore {
         }
     }
 
+    // Test-only escape hatch: the HealthStore is a process-wide singleton but
+    // state derivation is pure from `snapshot` + `lastError`.
+    func __setSnapshotForTest(_ snapshot: HealthSnapshot?, lastError: String? = nil) {
+        self.snapshot = snapshot
+        self.lastError = lastError
+    }
+
     func start() {
         guard self.loopTask == nil else { return }
         self.loopTask = Task { [weak self] in
@@ -142,10 +144,49 @@ final class HealthStore {
         }
     }
 
-    private static func isTelegramHealthy(_ snap: HealthSnapshot) -> Bool {
-        guard let tg = snap.telegram, tg.configured else { return false }
+    private static func isProviderHealthy(_ summary: HealthSnapshot.ProviderSummary) -> Bool {
+        guard summary.configured == true else { return false }
         // If probe is missing, treat it as "configured but unknown health" (not a hard fail).
-        return tg.probe?.ok ?? true
+        return summary.probe?.ok ?? true
+    }
+
+    private static func describeProbeFailure(_ probe: HealthSnapshot.ProviderSummary.Probe) -> String {
+        let elapsed = probe.elapsedMs.map { "\(Int($0))ms" }
+        if let error = probe.error, error.lowercased().contains("timeout") || probe.status == nil {
+            if let elapsed { return "Health check timed out (\(elapsed))" }
+            return "Health check timed out"
+        }
+        let code = probe.status.map { "status \($0)" } ?? "status unknown"
+        let reason = probe.error?.isEmpty == false ? probe.error! : "health probe failed"
+        if let elapsed { return "\(reason) (\(code), \(elapsed))" }
+        return "\(reason) (\(code))"
+    }
+
+    private func resolveLinkProvider(
+        _ snap: HealthSnapshot) -> (id: String, summary: HealthSnapshot.ProviderSummary)?
+    {
+        let order = snap.providerOrder ?? Array(snap.providers.keys)
+        for id in order {
+            if let summary = snap.providers[id], summary.linked != nil {
+                return (id: id, summary: summary)
+            }
+        }
+        return nil
+    }
+
+    private func resolveFallbackProvider(
+        _ snap: HealthSnapshot,
+        excluding id: String?) -> (id: String, summary: HealthSnapshot.ProviderSummary)?
+    {
+        let order = snap.providerOrder ?? Array(snap.providers.keys)
+        for providerId in order {
+            if providerId == id { continue }
+            guard let summary = snap.providers[providerId] else { continue }
+            if Self.isProviderHealthy(summary) {
+                return (id: providerId, summary: summary)
+            }
+        }
+        return nil
     }
 
     var state: HealthState {
@@ -153,13 +194,15 @@ final class HealthStore {
             return .degraded(error)
         }
         guard let snap = self.snapshot else { return .unknown }
-        if !snap.web.linked {
-            // WhatsApp Web linking is optional if Telegram is healthy; don't paint the whole app red.
-            return Self.isTelegramHealthy(snap) ? .degraded("Not linked") : .linkingNeeded
+        guard let link = self.resolveLinkProvider(snap) else { return .unknown }
+        if link.summary.linked != true {
+            // Linking is optional if any other provider is healthy; don't paint the whole app red.
+            let fallback = self.resolveFallbackProvider(snap, excluding: link.id)
+            return fallback != nil ? .degraded("Not linked") : .linkingNeeded
         }
-        if let connect = snap.web.connect, !connect.ok {
-            let reason = connect.error ?? "connect failed"
-            return .degraded(reason)
+        // A provider can be "linked" but still unhealthy (failed probe / cannot connect).
+        if let probe = link.summary.probe, probe.ok == false {
+            return .degraded(Self.describeProbeFailure(probe))
         }
         return .ok
     }
@@ -168,19 +211,22 @@ final class HealthStore {
         if self.isRefreshing { return "Health check running…" }
         if let error = self.lastError { return "Health check failed: \(error)" }
         guard let snap = self.snapshot else { return "Health check pending" }
-        if !snap.web.linked {
-            if let tg = snap.telegram, tg.configured {
-                let tgLabel = (tg.probe?.ok ?? true) ? "Telegram ok" : "Telegram degraded"
-                return "\(tgLabel) · Not linked — run clawdbot login"
+        guard let link = self.resolveLinkProvider(snap) else { return "Health check pending" }
+        if link.summary.linked != true {
+            if let fallback = self.resolveFallbackProvider(snap, excluding: link.id) {
+                let fallbackLabel = snap.providerLabels?[fallback.id] ?? fallback.id.capitalized
+                let fallbackState = (fallback.summary.probe?.ok ?? true) ? "ok" : "degraded"
+                return "\(fallbackLabel) \(fallbackState) · Not linked — run clawdbot login"
             }
             return "Not linked — run clawdbot login"
         }
-        let auth = snap.web.authAgeMs.map { msToAge($0) } ?? "unknown"
-        if let connect = snap.web.connect, !connect.ok {
-            let code = connect.status.map(String.init) ?? "?"
-            return "Link stale? status \(code)"
+        let auth = link.summary.authAgeMs.map { msToAge($0) } ?? "unknown"
+        if let probe = link.summary.probe, probe.ok == false {
+            let status = probe.status.map(String.init) ?? "?"
+            let suffix = probe.status == nil ? "probe degraded" : "probe degraded · status \(status)"
+            return "linked · auth \(auth) · \(suffix)"
         }
-        return "linked · auth \(auth) · socket ok"
+        return "linked · auth \(auth)"
     }
 
     /// Short, human-friendly detail for the last failure, used in the UI.
@@ -201,17 +247,11 @@ final class HealthStore {
     }
 
     func describeFailure(from snap: HealthSnapshot, fallback: String?) -> String {
-        if !snap.web.linked {
+        if let link = self.resolveLinkProvider(snap), link.summary.linked != true {
             return "Not linked — run clawdbot login"
         }
-        if let connect = snap.web.connect, !connect.ok {
-            let elapsed = connect.elapsedMs.map { "\(Int($0))ms" } ?? "unknown duration"
-            if let err = connect.error, err.lowercased().contains("timeout") || connect.status == nil {
-                return "Health check timed out (\(elapsed))"
-            }
-            let code = connect.status.map { "status \($0)" } ?? "status unknown"
-            let reason = connect.error ?? "connect failed"
-            return "\(reason) (\(code), \(elapsed))"
+        if let link = self.resolveLinkProvider(snap), let probe = link.summary.probe, probe.ok == false {
+            return Self.describeProbeFailure(probe)
         }
         if let fallback, !fallback.isEmpty {
             return fallback

apps/macos/Sources/Clawdbot/InstancesStore.swift

@@ -242,6 +242,18 @@ final class InstancesStore {
         do {
             let data = try await ControlChannel.shared.health(timeout: 8)
             guard let snap = decodeHealthSnapshot(from: data) else { return }
+            let linkId = snap.providerOrder?.first(where: {
+                if let summary = snap.providers[$0] { return summary.linked != nil }
+                return false
+            }) ?? snap.providers.keys.first(where: {
+                if let summary = snap.providers[$0] { return summary.linked != nil }
+                return false
+            })
+            let linked = linkId.flatMap { snap.providers[$0]?.linked } ?? false
+            let linkLabel =
+                linkId.flatMap { snap.providerLabels?[$0] } ??
+                linkId?.capitalized ??
+                "provider"
             let entry = InstanceInfo(
                 id: "health-\(snap.ts)",
                 host: "gateway (health)",
@@ -253,7 +265,7 @@ final class InstancesStore {
                 lastInputSeconds: nil,
                 mode: "health",
                 reason: "health probe",
-                text: "Health ok · linked=\(snap.web.linked)",
+                text: "Health ok · \(linkLabel) linked=\(linked)",
                 ts: snap.ts)
             if !self.instances.contains(where: { $0.id == entry.id }) {
                 self.instances.insert(entry, at: 0)

apps/macos/Sources/Clawdbot/LogLocator.swift

@@ -29,7 +29,7 @@ enum LogLocator {
         stdoutLog.path
     }
 
-    /// Path to use for the embedded Gateway launchd job stdout/err.
+    /// Path to use for the Gateway launchd job stdout/err.
     static var launchdGatewayLogPath: String {
         gatewayLog.path
     }

apps/macos/Sources/Clawdbot/MenuBar.swift

@@ -70,6 +70,7 @@ struct ClawdbotApp: App {
         }
         .onChange(of: self.state.connectionMode) { _, mode in
             Task { await ConnectionModeCoordinator.shared.apply(mode: mode, paused: self.state.isPaused) }
+            CLIInstallPrompter.shared.checkAndPromptIfNeeded(reason: "connection-mode")
         }
 
         Settings {
@@ -262,6 +263,9 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
         Task { await PortGuardian.shared.sweep(mode: AppStateStore.shared.connectionMode) }
         Task { await PeekabooBridgeHostCoordinator.shared.setEnabled(AppStateStore.shared.peekabooBridgeEnabled) }
         self.scheduleFirstRunOnboardingIfNeeded()
+        DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) {
+            CLIInstallPrompter.shared.checkAndPromptIfNeeded(reason: "launch")
+        }
 
         // Developer/testing helper: auto-open chat when launched with --chat (or legacy --webchat).
         if CommandLine.arguments.contains("--chat") || CommandLine.arguments.contains("--webchat") {

apps/macos/Sources/Clawdbot/MenuContentView.swift

@@ -153,6 +153,9 @@ struct MenuContent: View {
             self.micRefreshTask = nil
             self.micObserver.stop()
         }
+        .task { @MainActor in
+            SettingsWindowOpener.shared.register(openSettings: self.openSettings)
+        }
     }
 
     private var connectionLabel: String {
@@ -276,7 +279,7 @@ struct MenuContent: View {
                     Label("Send Test Notification", systemImage: "bell")
                 }
                 Divider()
-                if self.state.connectionMode == .local, !AppStateStore.attachExistingGatewayOnly {
+                if self.state.connectionMode == .local {
                     Button {
                         DebugActions.restartGateway()
                     } label: {
@@ -301,7 +304,9 @@ struct MenuContent: View {
         SettingsTabRouter.request(tab)
         NSApp.activate(ignoringOtherApps: true)
         self.openSettings()
-        NotificationCenter.default.post(name: .clawdbotSelectSettingsTab, object: tab)
+        DispatchQueue.main.async {
+            NotificationCenter.default.post(name: .clawdbotSelectSettingsTab, object: tab)
+        }
     }
 
     @MainActor

apps/macos/Sources/Clawdbot/MenuSessionsInjector.swift

@@ -99,7 +99,9 @@ final class MenuSessionsInjector: NSObject, NSMenuDelegate {
         }
         return NSRect.zero
     }
+}
 
+extension MenuSessionsInjector {
     // MARK: - Injection
 
     private func inject(into menu: NSMenu) {
@@ -395,13 +397,13 @@ final class MenuSessionsInjector: NSObject, NSMenuDelegate {
     private func controlChannelStatusText(for state: ControlChannel.ConnectionState) -> String {
         switch state {
         case .connected:
-            return "Loading sessions…"
+            "Loading sessions…"
         case .connecting:
-            return "Connecting…"
+            "Connecting…"
         case let .degraded(message):
-            return message.nonEmpty ?? "Gateway disconnected"
+            message.nonEmpty ?? "Gateway disconnected"
         case .disconnected:
-            return "Gateway disconnected"
+            "Gateway disconnected"
         }
     }
 
@@ -508,7 +510,9 @@ final class MenuSessionsInjector: NSObject, NSMenuDelegate {
         item.view = self.makeHostedView(rootView: view, width: width, highlighted: false)
         return item
     }
+}
 
+extension MenuSessionsInjector {
     // MARK: - Cache
 
     private func refreshCache(force: Bool) async {
@@ -579,7 +583,9 @@ final class MenuSessionsInjector: NSObject, NSMenuDelegate {
         }
         return "Sessions unavailable"
     }
+}
 
+extension MenuSessionsInjector {
     // MARK: - Submenus
 
     private func buildSubmenu(for row: SessionRow, storePath: String) -> NSMenu {
@@ -911,7 +917,9 @@ final class MenuSessionsInjector: NSObject, NSMenuDelegate {
         NSPasteboard.general.clearContents()
         NSPasteboard.general.setString(value, forType: .string)
     }
+}
 
+extension MenuSessionsInjector {
     // MARK: - Width + placement
 
     private func findInsertIndex(in menu: NSMenu) -> Int? {
@@ -987,7 +995,9 @@ final class MenuSessionsInjector: NSObject, NSMenuDelegate {
             return lhsName < rhsName
         }
     }
+}
 
+extension MenuSessionsInjector {
     // MARK: - Views
 
     private func makeHostedView(rootView: AnyView, width: CGFloat, highlighted: Bool) -> NSView {

apps/macos/Sources/Clawdbot/Onboarding.swift

@@ -120,22 +120,26 @@ struct OnboardingView: View {
     let permissionsPageIndex = 5
     static func pageOrder(
         for mode: AppState.ConnectionMode,
-        needsBootstrap: Bool) -> [Int]
+        showOnboardingChat: Bool) -> [Int]
     {
         switch mode {
         case .remote:
             // Remote setup doesn't need local gateway/CLI/workspace setup pages,
             // and WhatsApp/Telegram setup is optional.
-            needsBootstrap ? [0, 1, 5, 8, 9] : [0, 1, 5, 9]
+            showOnboardingChat ? [0, 1, 5, 8, 9] : [0, 1, 5, 9]
         case .unconfigured:
-            needsBootstrap ? [0, 1, 8, 9] : [0, 1, 9]
+            showOnboardingChat ? [0, 1, 8, 9] : [0, 1, 9]
         case .local:
-            needsBootstrap ? [0, 1, 3, 5, 8, 9] : [0, 1, 3, 5, 9]
+            showOnboardingChat ? [0, 1, 3, 5, 8, 9] : [0, 1, 3, 5, 9]
         }
     }
 
+    var showOnboardingChat: Bool {
+        self.state.connectionMode == .local && self.needsBootstrap
+    }
+
     var pageOrder: [Int] {
-        Self.pageOrder(for: self.state.connectionMode, needsBootstrap: self.needsBootstrap)
+        Self.pageOrder(for: self.state.connectionMode, showOnboardingChat: self.showOnboardingChat)
     }
 
     var pageCount: Int { self.pageOrder.count }
@@ -151,8 +155,8 @@ struct OnboardingView: View {
 
     var canAdvance: Bool { !self.isWizardBlocking }
     var devLinkCommand: String {
-        let bundlePath = Bundle.main.bundlePath
-        return "ln -sf '\(bundlePath)/Contents/Resources/Relay/clawdbot' /usr/local/bin/clawdbot"
+        let version = GatewayEnvironment.expectedGatewayVersion()?.description ?? "latest"
+        return "npm install -g clawdbot@\(version)"
     }
 
     struct LocalGatewayProbe: Equatable {

apps/macos/Sources/Clawdbot/OnboardingView+Actions.swift

@@ -1,6 +1,7 @@
 import AppKit
 import ClawdbotDiscovery
 import ClawdbotIPC
+import Foundation
 import SwiftUI
 
 extension OnboardingView {
@@ -41,7 +42,9 @@ extension OnboardingView {
     func openSettings(tab: SettingsTab) {
         SettingsTabRouter.request(tab)
         self.openSettings()
-        NotificationCenter.default.post(name: .clawdbotSelectSettingsTab, object: tab)
+        DispatchQueue.main.async {
+            NotificationCenter.default.post(name: .clawdbotSelectSettingsTab, object: tab)
+        }
     }
 
     func handleBack() {

apps/macos/Sources/Clawdbot/OnboardingView+Chat.swift

@@ -3,7 +3,7 @@ import Foundation
 extension OnboardingView {
     func maybeKickoffOnboardingChat(for pageIndex: Int) {
         guard pageIndex == self.onboardingChatPageIndex else { return }
-        guard self.needsBootstrap else { return }
+        guard self.showOnboardingChat else { return }
         guard !self.didAutoKickoff else { return }
         self.didAutoKickoff = true
 

apps/macos/Sources/Clawdbot/OnboardingView+Layout.swift

@@ -54,6 +54,7 @@ extension OnboardingView {
             self.stopPermissionMonitoring()
             self.stopDiscovery()
             self.stopAuthMonitoring()
+            Task { await self.onboardingWizard.cancelIfRunning() }
         }
         .task {
             await self.refreshPerms()

apps/macos/Sources/Clawdbot/OnboardingView+Monitoring.swift

@@ -95,7 +95,7 @@ extension OnboardingView {
         self.installingCLI = true
         defer { installingCLI = false }
         await CLIInstaller.install { message in
-            await MainActor.run { self.cliStatus = message }
+            self.cliStatus = message
         }
         self.refreshCLIStatus()
     }

apps/macos/Sources/Clawdbot/OnboardingView+Pages.swift

@@ -494,9 +494,9 @@ extension OnboardingView {
 
     func cliPage() -> some View {
         self.onboardingPage {
-            Text("Install the helper CLI")
+            Text("Install the CLI")
                 .font(.largeTitle.weight(.semibold))
-            Text("Optional, but recommended: link `clawdbot` so scripts can reach the local gateway.")
+            Text("Required for local mode: installs `clawdbot` so launchd can run the gateway.")
                 .font(.body)
                 .foregroundStyle(.secondary)
                 .multilineTextAlignment(.center)
@@ -522,7 +522,7 @@ extension OnboardingView {
                     .buttonStyle(.borderedProminent)
                     .disabled(self.installingCLI)
 
-                    Button(self.copied ? "Copied" : "Copy dev link") {
+                    Button(self.copied ? "Copied" : "Copy install command") {
                         self.copyToPasteboard(self.devLinkCommand)
                     }
                     .disabled(self.installingCLI)
@@ -541,8 +541,8 @@ extension OnboardingView {
                 } else if !self.cliInstalled, self.cliInstallLocation == nil {
                     Text(
                         """
-                        We install into /usr/local/bin and /opt/homebrew/bin.
-                        Rerun anytime if you move the build output.
+                        Installs a user-space Node 22+ runtime and the CLI (no Homebrew).
+                        Rerun anytime to reinstall or update.
                         """)
                         .font(.footnote)
                         .foregroundStyle(.secondary)

apps/macos/Sources/Clawdbot/OnboardingWizard.swift

@@ -35,6 +35,10 @@ final class OnboardingWizardModel {
     private(set) var errorMessage: String?
     var isStarting = false
     var isSubmitting = false
+    private var lastStartMode: AppState.ConnectionMode?
+    private var lastStartWorkspace: String?
+    private var restartAttempts = 0
+    private let maxRestartAttempts = 1
 
     var isComplete: Bool { self.status == "done" }
     var isRunning: Bool { self.status == "running" }
@@ -46,6 +50,9 @@ final class OnboardingWizardModel {
         self.errorMessage = nil
         self.isStarting = false
         self.isSubmitting = false
+        self.restartAttempts = 0
+        self.lastStartMode = nil
+        self.lastStartWorkspace = nil
     }
 
     func startIfNeeded(mode: AppState.ConnectionMode, workspace: String? = nil) async {
@@ -53,9 +60,18 @@ final class OnboardingWizardModel {
         guard mode == .local else { return }
         self.isStarting = true
         self.errorMessage = nil
+        self.lastStartMode = mode
+        self.lastStartWorkspace = workspace
         defer { self.isStarting = false }
 
         do {
+            GatewayProcessManager.shared.setActive(true)
+            if await GatewayProcessManager.shared.waitForGatewayReady(timeout: 12) == false {
+                throw NSError(
+                    domain: "Gateway",
+                    code: 1,
+                    userInfo: [NSLocalizedDescriptionKey: "Gateway did not become ready. Check that it is running."])
+            }
             var params: [String: AnyCodable] = ["mode": AnyCodable("local")]
             if let workspace, !workspace.isEmpty {
                 params["workspace"] = AnyCodable(workspace)
@@ -89,6 +105,9 @@ final class OnboardingWizardModel {
                 params: params)
             self.applyNextResult(res)
         } catch {
+            if self.restartIfSessionLost(error: error) {
+                return
+            }
             self.status = "error"
             self.errorMessage = error.localizedDescription
             onboardingWizardLogger.error("submit failed: \(error.localizedDescription, privacy: .public)")
@@ -111,30 +130,54 @@ final class OnboardingWizardModel {
 
     private func applyStartResult(_ res: WizardStartResult) {
         self.sessionId = res.sessionid
-        self.status = anyCodableStringValue(res.status) ?? (res.done ? "done" : "running")
+        self.status = wizardStatusString(res.status) ?? (res.done ? "done" : "running")
         self.errorMessage = res.error
         self.currentStep = decodeWizardStep(res.step)
+        if self.currentStep == nil, res.step != nil {
+            onboardingWizardLogger.error("wizard step decode failed")
+        }
         if res.done { self.currentStep = nil }
+        self.restartAttempts = 0
     }
 
     private func applyNextResult(_ res: WizardNextResult) {
-        self.status = anyCodableStringValue(res.status) ?? self.status
+        let status = wizardStatusString(res.status)
+        self.status = status ?? self.status
         self.errorMessage = res.error
         self.currentStep = decodeWizardStep(res.step)
+        if self.currentStep == nil, res.step != nil {
+            onboardingWizardLogger.error("wizard step decode failed")
+        }
         if res.done { self.currentStep = nil }
-        if res.done || anyCodableStringValue(res.status) == "done" || anyCodableStringValue(res.status) == "cancelled"
-            || anyCodableStringValue(res.status) == "error"
+        if res.done || status == "done" || status == "cancelled" || status == "error"
         {
             self.sessionId = nil
         }
     }
 
     private func applyStatusResult(_ res: WizardStatusResult) {
-        self.status = anyCodableStringValue(res.status) ?? "unknown"
+        self.status = wizardStatusString(res.status) ?? "unknown"
         self.errorMessage = res.error
         self.currentStep = nil
         self.sessionId = nil
     }
+
+    private func restartIfSessionLost(error: Error) -> Bool {
+        guard let gatewayError = error as? GatewayResponseError else { return false }
+        guard gatewayError.code == ErrorCode.invalidRequest.rawValue else { return false }
+        let message = gatewayError.message.lowercased()
+        guard message.contains("wizard not found") || message.contains("wizard not running") else { return false }
+        guard let mode = self.lastStartMode, self.restartAttempts < self.maxRestartAttempts else {
+            return false
+        }
+        self.restartAttempts += 1
+        self.sessionId = nil
+        self.currentStep = nil
+        self.status = nil
+        self.errorMessage = "Wizard session lost. Restarting…"
+        Task { await self.startIfNeeded(mode: mode, workspace: self.lastStartWorkspace) }
+        return true
+    }
 }
 
 struct OnboardingWizardStepView: View {
@@ -333,98 +376,3 @@ private struct WizardOptionItem: Identifiable {
 
     var id: Int { self.index }
 }
-
-private struct WizardOption {
-    let value: ProtocolAnyCodable?
-    let label: String
-    let hint: String?
-}
-
-private func decodeWizardStep(_ raw: [String: ProtocolAnyCodable]?) -> WizardStep? {
-    guard let raw else { return nil }
-    do {
-        let data = try JSONEncoder().encode(raw)
-        return try JSONDecoder().decode(WizardStep.self, from: data)
-    } catch {
-        onboardingWizardLogger.error("wizard step decode failed: \(error.localizedDescription, privacy: .public)")
-        return nil
-    }
-}
-
-private func parseWizardOptions(_ raw: [[String: ProtocolAnyCodable]]?) -> [WizardOption] {
-    guard let raw else { return [] }
-    return raw.map { entry in
-        let value = entry["value"]
-        let label = (entry["label"]?.value as? String) ?? ""
-        let hint = entry["hint"]?.value as? String
-        return WizardOption(value: value, label: label, hint: hint)
-    }
-}
-
-private func wizardStepType(_ step: WizardStep) -> String {
-    (step.type.value as? String) ?? ""
-}
-
-private func anyCodableString(_ value: ProtocolAnyCodable?) -> String {
-    switch value?.value {
-    case let string as String:
-        string
-    case let int as Int:
-        String(int)
-    case let double as Double:
-        String(double)
-    case let bool as Bool:
-        bool ? "true" : "false"
-    default:
-        ""
-    }
-}
-
-private func anyCodableStringValue(_ value: ProtocolAnyCodable?) -> String? {
-    value?.value as? String
-}
-
-private func anyCodableBool(_ value: ProtocolAnyCodable?) -> Bool {
-    switch value?.value {
-    case let bool as Bool:
-        bool
-    case let string as String:
-        string.lowercased() == "true"
-    default:
-        false
-    }
-}
-
-private func anyCodableArray(_ value: ProtocolAnyCodable?) -> [ProtocolAnyCodable] {
-    switch value?.value {
-    case let arr as [ProtocolAnyCodable]:
-        arr
-    case let arr as [Any]:
-        arr.map { ProtocolAnyCodable($0) }
-    default:
-        []
-    }
-}
-
-private func anyCodableEqual(_ lhs: ProtocolAnyCodable?, _ rhs: ProtocolAnyCodable?) -> Bool {
-    switch (lhs?.value, rhs?.value) {
-    case let (l as String, r as String):
-        l == r
-    case let (l as Int, r as Int):
-        l == r
-    case let (l as Double, r as Double):
-        l == r
-    case let (l as Bool, r as Bool):
-        l == r
-    case let (l as String, r as Int):
-        l == String(r)
-    case let (l as Int, r as String):
-        String(l) == r
-    case let (l as String, r as Double):
-        l == String(r)
-    case let (l as Double, r as String):
-        String(l) == r
-    default:
-        false
-    }
-}

apps/macos/Sources/Clawdbot/PermissionManager.swift

@@ -345,7 +345,10 @@ final class LocationPermissionRequester: NSObject, CLLocationManagerDelegate {
     }
 
     // Legacy callback (still used on some macOS versions / configurations).
-    nonisolated func locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {
+    nonisolated func locationManager(
+        _ manager: CLLocationManager,
+        didChangeAuthorization status: CLAuthorizationStatus)
+    {
         Task { @MainActor in
             self.finish(status: status)
         }

apps/macos/Sources/Clawdbot/PortGuardian.swift

@@ -344,14 +344,17 @@ actor PortGuardian {
 
     private func isExpected(_ listener: Listener, port: Int, mode: AppState.ConnectionMode) -> Bool {
         let cmd = listener.command.lowercased()
-        let expectedCommands = ["node", "clawdbot", "tsx", "pnpm", "bun"]
+        let full = listener.fullCommand.lowercased()
         switch mode {
         case .remote:
             // Remote mode expects an SSH tunnel for the gateway WebSocket port.
             if port == GatewayEnvironment.gatewayPort() { return cmd.contains("ssh") }
             return false
         case .local:
-            return expectedCommands.contains { cmd.contains($0) }
+            if !cmd.contains("clawdbot") { return false }
+            if full.contains("gateway-daemon") { return true }
+            // If args are unavailable, treat a clawdbot listener as expected.
+            return full == cmd
         case .unconfigured:
             return false
         }

apps/macos/Sources/Clawdbot/Resources/Info.plist

@@ -15,9 +15,9 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>2026.1.9</string>
+    <string>2026.1.11</string>
     <key>CFBundleVersion</key>
-    <string>20260109</string>
+    <string>20260111</string>
     <key>CFBundleIconFile</key>
     <string>Clawdbot</string>
     <key>CFBundleURLTypes</key>

apps/macos/Sources/Clawdbot/SettingsWindowOpener.swift

@@ -0,0 +1,36 @@
+import AppKit
+import SwiftUI
+
+@objc
+private protocol SettingsWindowMenuActions {
+    @objc(showSettingsWindow:)
+    optional func showSettingsWindow(_ sender: Any?)
+
+    @objc(showPreferencesWindow:)
+    optional func showPreferencesWindow(_ sender: Any?)
+}
+
+@MainActor
+final class SettingsWindowOpener {
+    static let shared = SettingsWindowOpener()
+
+    private var openSettingsAction: OpenSettingsAction?
+
+    func register(openSettings: OpenSettingsAction) {
+        self.openSettingsAction = openSettings
+    }
+
+    func open() {
+        NSApp.activate(ignoringOtherApps: true)
+        if let openSettingsAction {
+            openSettingsAction()
+            return
+        }
+
+        // Fallback path: mimic the built-in Settings menu item action.
+        let didOpen = NSApp.sendAction(#selector(SettingsWindowMenuActions.showSettingsWindow(_:)), to: nil, from: nil)
+        if !didOpen {
+            _ = NSApp.sendAction(#selector(SettingsWindowMenuActions.showPreferencesWindow(_:)), to: nil, from: nil)
+        }
+    }
+}

apps/macos/Sources/ClawdbotDiscovery/GatewayDiscoveryModel.swift

@@ -602,7 +602,7 @@ public final class GatewayDiscoveryModel {
             of: #"\s*-?\s*bridge$"#,
             with: "",
             options: .regularExpression)
-        return normalizeHostToken(strippedBridge)
+        return self.normalizeHostToken(strippedBridge)
     }
 }
 

apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift

@@ -1,7 +1,7 @@
 // Generated by scripts/protocol-gen-swift.ts — do not edit by hand
 import Foundation
 
-public let GATEWAY_PROTOCOL_VERSION = 2
+public let GATEWAY_PROTOCOL_VERSION = 3
 
 public enum ErrorCode: String, Codable, Sendable {
     case notLinked = "NOT_LINKED"
@@ -1119,6 +1119,56 @@ public struct ProvidersStatusParams: Codable, Sendable {
     }
 }
 
+public struct ProvidersStatusResult: Codable, Sendable {
+    public let ts: Int
+    public let providerorder: [String]
+    public let providerlabels: [String: AnyCodable]
+    public let providers: [String: AnyCodable]
+    public let provideraccounts: [String: AnyCodable]
+    public let providerdefaultaccountid: [String: AnyCodable]
+
+    public init(
+        ts: Int,
+        providerorder: [String],
+        providerlabels: [String: AnyCodable],
+        providers: [String: AnyCodable],
+        provideraccounts: [String: AnyCodable],
+        providerdefaultaccountid: [String: AnyCodable]
+    ) {
+        self.ts = ts
+        self.providerorder = providerorder
+        self.providerlabels = providerlabels
+        self.providers = providers
+        self.provideraccounts = provideraccounts
+        self.providerdefaultaccountid = providerdefaultaccountid
+    }
+    private enum CodingKeys: String, CodingKey {
+        case ts
+        case providerorder = "providerOrder"
+        case providerlabels = "providerLabels"
+        case providers
+        case provideraccounts = "providerAccounts"
+        case providerdefaultaccountid = "providerDefaultAccountId"
+    }
+}
+
+public struct ProvidersLogoutParams: Codable, Sendable {
+    public let provider: String
+    public let accountid: String?
+
+    public init(
+        provider: String,
+        accountid: String?
+    ) {
+        self.provider = provider
+        self.accountid = accountid
+    }
+    private enum CodingKeys: String, CodingKey {
+        case provider
+        case accountid = "accountId"
+    }
+}
+
 public struct WebLoginStartParams: Codable, Sendable {
     public let force: Bool?
     public let timeoutms: Int?

apps/macos/Sources/ClawdbotProtocol/WizardHelpers.swift

@@ -0,0 +1,106 @@
+import Foundation
+
+public struct WizardOption: Sendable {
+    public let value: AnyCodable?
+    public let label: String
+    public let hint: String?
+
+    public init(value: AnyCodable?, label: String, hint: String?) {
+        self.value = value
+        self.label = label
+        self.hint = hint
+    }
+}
+
+public func decodeWizardStep(_ raw: [String: AnyCodable]?) -> WizardStep? {
+    guard let raw else { return nil }
+    do {
+        let data = try JSONEncoder().encode(raw)
+        return try JSONDecoder().decode(WizardStep.self, from: data)
+    } catch {
+        return nil
+    }
+}
+
+public func parseWizardOptions(_ raw: [[String: AnyCodable]]?) -> [WizardOption] {
+    guard let raw else { return [] }
+    return raw.map { entry in
+        let value = entry["value"]
+        let label = (entry["label"]?.value as? String) ?? ""
+        let hint = entry["hint"]?.value as? String
+        return WizardOption(value: value, label: label, hint: hint)
+    }
+}
+
+public func wizardStatusString(_ value: AnyCodable?) -> String? {
+    (value?.value as? String)?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+}
+
+public func wizardStepType(_ step: WizardStep) -> String {
+    (step.type.value as? String) ?? ""
+}
+
+public func anyCodableString(_ value: AnyCodable?) -> String {
+    switch value?.value {
+    case let string as String:
+        string
+    case let int as Int:
+        String(int)
+    case let double as Double:
+        String(double)
+    case let bool as Bool:
+        bool ? "true" : "false"
+    default:
+        ""
+    }
+}
+
+public func anyCodableBool(_ value: AnyCodable?) -> Bool {
+    switch value?.value {
+    case let bool as Bool:
+        return bool
+    case let int as Int:
+        return int != 0
+    case let double as Double:
+        return double != 0
+    case let string as String:
+        let trimmed = string.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        return trimmed == "true" || trimmed == "1" || trimmed == "yes"
+    default:
+        return false
+    }
+}
+
+public func anyCodableArray(_ value: AnyCodable?) -> [AnyCodable] {
+    switch value?.value {
+    case let arr as [AnyCodable]:
+        return arr
+    case let arr as [Any]:
+        return arr.map { AnyCodable($0) }
+    default:
+        return []
+    }
+}
+
+public func anyCodableEqual(_ lhs: AnyCodable?, _ rhs: AnyCodable?) -> Bool {
+    switch (lhs?.value, rhs?.value) {
+    case let (l as String, r as String):
+        l == r
+    case let (l as Int, r as Int):
+        l == r
+    case let (l as Double, r as Double):
+        l == r
+    case let (l as Bool, r as Bool):
+        l == r
+    case let (l as String, r as Int):
+        l == String(r)
+    case let (l as Int, r as String):
+        String(l) == r
+    case let (l as String, r as Double):
+        l == String(r)
+    case let (l as Double, r as String):
+        String(l) == r
+    default:
+        false
+    }
+}

apps/macos/Sources/ClawdbotWizardCLI/main.swift

@@ -0,0 +1,543 @@
+import ClawdbotProtocol
+import Darwin
+import Foundation
+
+struct WizardCliOptions {
+    var url: String?
+    var token: String?
+    var password: String?
+    var mode: String = "local"
+    var workspace: String?
+    var json: Bool = false
+    var help: Bool = false
+
+    static func parse(_ args: [String]) -> WizardCliOptions {
+        var opts = WizardCliOptions()
+        var i = 0
+        while i < args.count {
+            let arg = args[i]
+            switch arg {
+            case "-h", "--help":
+                opts.help = true
+            case "--json":
+                opts.json = true
+            case "--url":
+                opts.url = nextValue(args, index: &i)
+            case "--token":
+                opts.token = nextValue(args, index: &i)
+            case "--password":
+                opts.password = nextValue(args, index: &i)
+            case "--mode":
+                if let value = nextValue(args, index: &i) {
+                    opts.mode = value
+                }
+            case "--workspace":
+                opts.workspace = nextValue(args, index: &i)
+            default:
+                break
+            }
+            i += 1
+        }
+        return opts
+    }
+
+    private static func nextValue(_ args: [String], index: inout Int) -> String? {
+        guard index + 1 < args.count else { return nil }
+        index += 1
+        return args[index].trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+}
+
+struct GatewayConfig {
+    var mode: String?
+    var bind: String?
+    var port: Int?
+    var remoteUrl: String?
+    var token: String?
+    var password: String?
+    var remoteToken: String?
+    var remotePassword: String?
+}
+
+enum WizardCliError: Error, CustomStringConvertible {
+    case invalidUrl(String)
+    case missingRemoteUrl
+    case gatewayError(String)
+    case decodeError(String)
+    case cancelled
+
+    var description: String {
+        switch self {
+        case let .invalidUrl(raw): "Invalid URL: \(raw)"
+        case .missingRemoteUrl: "gateway.remote.url is missing"
+        case let .gatewayError(msg): msg
+        case let .decodeError(msg): msg
+        case .cancelled: "Wizard cancelled"
+        }
+    }
+}
+
+@main
+struct ClawdbotWizardCLI {
+    static func main() async {
+        let opts = WizardCliOptions.parse(Array(CommandLine.arguments.dropFirst()))
+        if opts.help {
+            printUsage()
+            return
+        }
+
+        let config = loadGatewayConfig()
+        do {
+            guard isatty(STDIN_FILENO) != 0 else {
+                throw WizardCliError.gatewayError("Wizard requires an interactive TTY.")
+            }
+            let endpoint = try resolveGatewayEndpoint(opts: opts, config: config)
+            let client = GatewayWizardClient(
+                url: endpoint.url,
+                token: endpoint.token,
+                password: endpoint.password,
+                json: opts.json)
+            try await client.connect()
+            defer { Task { await client.close() } }
+            try await runWizard(client: client, opts: opts)
+        } catch {
+            fputs("wizard: \(error)\n", stderr)
+            exit(1)
+        }
+    }
+}
+
+private struct GatewayEndpoint {
+    let url: URL
+    let token: String?
+    let password: String?
+}
+
+private func printUsage() {
+    print("""
+    clawdbot-mac-wizard
+
+    Usage:
+      clawdbot-mac-wizard [--url <ws://host:port>] [--token <token>] [--password <password>] [--mode <local|remote>] [--workspace <path>] [--json]
+
+    Options:
+      --url <url>        Gateway WebSocket URL (overrides config)
+      --token <token>    Gateway token (if required)
+      --password <pw>    Gateway password (if required)
+      --mode <mode>      Wizard mode (local|remote). Default: local
+      --workspace <path> Wizard workspace override
+      --json             Print raw wizard responses
+      -h, --help         Show help
+    """)
+}
+
+private func resolveGatewayEndpoint(opts: WizardCliOptions, config: GatewayConfig) throws -> GatewayEndpoint {
+    if let raw = opts.url, !raw.isEmpty {
+        guard let url = URL(string: raw) else { throw WizardCliError.invalidUrl(raw) }
+        return GatewayEndpoint(
+            url: url,
+            token: resolvedToken(opts: opts, config: config),
+            password: resolvedPassword(opts: opts, config: config))
+    }
+
+    let mode = (config.mode ?? "local").lowercased()
+    if mode == "remote" {
+        guard let raw = config.remoteUrl?.trimmingCharacters(in: .whitespacesAndNewlines), !raw.isEmpty else {
+            throw WizardCliError.missingRemoteUrl
+        }
+        guard let url = URL(string: raw) else { throw WizardCliError.invalidUrl(raw) }
+        return GatewayEndpoint(
+            url: url,
+            token: resolvedToken(opts: opts, config: config),
+            password: resolvedPassword(opts: opts, config: config))
+    }
+
+    let port = config.port ?? 18789
+    let host = "127.0.0.1"
+    guard let url = URL(string: "ws://\(host):\(port)") else {
+        throw WizardCliError.invalidUrl("ws://\(host):\(port)")
+    }
+    return GatewayEndpoint(
+        url: url,
+        token: resolvedToken(opts: opts, config: config),
+        password: resolvedPassword(opts: opts, config: config))
+}
+
+private func resolvedToken(opts: WizardCliOptions, config: GatewayConfig) -> String? {
+    if let token = opts.token, !token.isEmpty { return token }
+    if let token = ProcessInfo.processInfo.environment["CLAWDBOT_GATEWAY_TOKEN"], !token.isEmpty {
+        return token
+    }
+    if (config.mode ?? "local").lowercased() == "remote" {
+        return config.remoteToken
+    }
+    return config.token
+}
+
+private func resolvedPassword(opts: WizardCliOptions, config: GatewayConfig) -> String? {
+    if let password = opts.password, !password.isEmpty { return password }
+    if let password = ProcessInfo.processInfo.environment["CLAWDBOT_GATEWAY_PASSWORD"], !password.isEmpty {
+        return password
+    }
+    if (config.mode ?? "local").lowercased() == "remote" {
+        return config.remotePassword
+    }
+    return config.password
+}
+
+private func loadGatewayConfig() -> GatewayConfig {
+    let url = FileManager.default.homeDirectoryForCurrentUser
+        .appendingPathComponent(".clawdbot")
+        .appendingPathComponent("clawdbot.json")
+    guard let data = try? Data(contentsOf: url) else { return GatewayConfig() }
+    guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+        return GatewayConfig()
+    }
+
+    var cfg = GatewayConfig()
+    if let gateway = json["gateway"] as? [String: Any] {
+        cfg.mode = gateway["mode"] as? String
+        cfg.bind = gateway["bind"] as? String
+        cfg.port = gateway["port"] as? Int ?? parseInt(gateway["port"])
+
+        if let auth = gateway["auth"] as? [String: Any] {
+            cfg.token = auth["token"] as? String
+            cfg.password = auth["password"] as? String
+        }
+        if let remote = gateway["remote"] as? [String: Any] {
+            cfg.remoteUrl = remote["url"] as? String
+            cfg.remoteToken = remote["token"] as? String
+            cfg.remotePassword = remote["password"] as? String
+        }
+    }
+    return cfg
+}
+
+private func parseInt(_ value: Any?) -> Int? {
+    switch value {
+    case let number as Int:
+        number
+    case let number as Double:
+        Int(number)
+    case let raw as String:
+        Int(raw.trimmingCharacters(in: .whitespacesAndNewlines))
+    default:
+        nil
+    }
+}
+
+actor GatewayWizardClient {
+    private let url: URL
+    private let token: String?
+    private let password: String?
+    private let json: Bool
+    private let encoder = JSONEncoder()
+    private let decoder = JSONDecoder()
+    private let session = URLSession(configuration: .default)
+    private var task: URLSessionWebSocketTask?
+
+    init(url: URL, token: String?, password: String?, json: Bool) {
+        self.url = url
+        self.token = token
+        self.password = password
+        self.json = json
+    }
+
+    func connect() async throws {
+        let socket = self.session.webSocketTask(with: self.url)
+        socket.maximumMessageSize = 16 * 1024 * 1024
+        socket.resume()
+        self.task = socket
+        try await self.sendConnect()
+    }
+
+    func close() {
+        self.task?.cancel(with: .goingAway, reason: nil)
+        self.task = nil
+    }
+
+    func request(method: String, params: [String: AnyCodable]?) async throws -> ResponseFrame {
+        guard let task = self.task else {
+            throw WizardCliError.gatewayError("gateway not connected")
+        }
+        let id = UUID().uuidString
+        let frame = RequestFrame(
+            type: "req",
+            id: id,
+            method: method,
+            params: params.map { AnyCodable($0) })
+        let data = try self.encoder.encode(frame)
+        try await task.send(.data(data))
+
+        while true {
+            let message = try await task.receive()
+            let frame = try decodeFrame(message)
+            if case let .res(res) = frame, res.id == id {
+                if res.ok == false {
+                    let msg = (res.error?["message"]?.value as? String) ?? "gateway error"
+                    throw WizardCliError.gatewayError(msg)
+                }
+                return res
+            }
+        }
+    }
+
+    func decodePayload<T: Decodable>(_ response: ResponseFrame, as _: T.Type) throws -> T {
+        guard let payload = response.payload else {
+            throw WizardCliError.decodeError("missing payload")
+        }
+        let data = try self.encoder.encode(payload)
+        return try self.decoder.decode(T.self, from: data)
+    }
+
+    private func decodeFrame(_ message: URLSessionWebSocketTask.Message) throws -> GatewayFrame {
+        let data: Data? = switch message {
+        case let .data(data): data
+        case let .string(text): text.data(using: .utf8)
+        @unknown default: nil
+        }
+        guard let data else {
+            throw WizardCliError.decodeError("empty gateway response")
+        }
+        return try self.decoder.decode(GatewayFrame.self, from: data)
+    }
+
+    private func sendConnect() async throws {
+        guard let task = self.task else {
+            throw WizardCliError.gatewayError("gateway not connected")
+        }
+        let osVersion = ProcessInfo.processInfo.operatingSystemVersion
+        let platform = "macos \(osVersion.majorVersion).\(osVersion.minorVersion).\(osVersion.patchVersion)"
+        let client: [String: AnyCodable] = [
+            "id": AnyCodable("clawdbot-macos"),
+            "displayName": AnyCodable(Host.current().localizedName ?? "Clawdbot macOS Wizard CLI"),
+            "version": AnyCodable("dev"),
+            "platform": AnyCodable(platform),
+            "deviceFamily": AnyCodable("Mac"),
+            "mode": AnyCodable("ui"),
+            "instanceId": AnyCodable(UUID().uuidString),
+        ]
+
+        var params: [String: AnyCodable] = [
+            "minProtocol": AnyCodable(GATEWAY_PROTOCOL_VERSION),
+            "maxProtocol": AnyCodable(GATEWAY_PROTOCOL_VERSION),
+            "client": AnyCodable(client),
+            "caps": AnyCodable([String]()),
+            "locale": AnyCodable(Locale.preferredLanguages.first ?? Locale.current.identifier),
+            "userAgent": AnyCodable(ProcessInfo.processInfo.operatingSystemVersionString),
+        ]
+        if let token = self.token {
+            params["auth"] = AnyCodable(["token": AnyCodable(token)])
+        } else if let password = self.password {
+            params["auth"] = AnyCodable(["password": AnyCodable(password)])
+        }
+
+        let reqId = UUID().uuidString
+        let frame = RequestFrame(
+            type: "req",
+            id: reqId,
+            method: "connect",
+            params: AnyCodable(params))
+        let data = try self.encoder.encode(frame)
+        try await task.send(.data(data))
+
+        let message = try await task.receive()
+        let frameResponse = try decodeFrame(message)
+        guard case let .res(res) = frameResponse, res.id == reqId else {
+            throw WizardCliError.gatewayError("connect failed (unexpected response)")
+        }
+        if res.ok == false {
+            let msg = (res.error?["message"]?.value as? String) ?? "gateway connect failed"
+            throw WizardCliError.gatewayError(msg)
+        }
+        _ = try self.decodePayload(res, as: HelloOk.self)
+    }
+}
+
+private func runWizard(client: GatewayWizardClient, opts: WizardCliOptions) async throws {
+    var params: [String: AnyCodable] = [:]
+    let mode = opts.mode.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+    if mode == "local" || mode == "remote" {
+        params["mode"] = AnyCodable(mode)
+    }
+    if let workspace = opts.workspace?.trimmingCharacters(in: .whitespacesAndNewlines), !workspace.isEmpty {
+        params["workspace"] = AnyCodable(workspace)
+    }
+
+    let startResponse = try await client.request(method: "wizard.start", params: params)
+    let startResult = try await client.decodePayload(startResponse, as: WizardStartResult.self)
+    if opts.json {
+        dumpResult(startResponse)
+    }
+
+    let sessionId = startResult.sessionid
+    var nextResult = WizardNextResult(
+        done: startResult.done,
+        step: startResult.step,
+        status: startResult.status,
+        error: startResult.error)
+
+    do {
+        while true {
+            let status = wizardStatusString(nextResult.status) ?? (nextResult.done ? "done" : "running")
+            if status == "cancelled" {
+                print("Wizard cancelled.")
+                return
+            }
+            if status == "error" || (nextResult.done && nextResult.error != nil) {
+                throw WizardCliError.gatewayError(nextResult.error ?? "wizard error")
+            }
+            if status == "done" || nextResult.done {
+                print("Wizard complete.")
+                return
+            }
+
+            if let step = decodeWizardStep(nextResult.step) {
+                let answer = try promptAnswer(for: step)
+                var answerPayload: [String: AnyCodable] = [
+                    "stepId": AnyCodable(step.id),
+                ]
+                if !(answer is NSNull) {
+                    answerPayload["value"] = AnyCodable(answer)
+                }
+                let response = try await client.request(
+                    method: "wizard.next",
+                    params: [
+                        "sessionId": AnyCodable(sessionId),
+                        "answer": AnyCodable(answerPayload),
+                    ])
+                nextResult = try await client.decodePayload(response, as: WizardNextResult.self)
+                if opts.json {
+                    dumpResult(response)
+                }
+            } else {
+                let response = try await client.request(
+                    method: "wizard.next",
+                    params: ["sessionId": AnyCodable(sessionId)])
+                nextResult = try await client.decodePayload(response, as: WizardNextResult.self)
+                if opts.json {
+                    dumpResult(response)
+                }
+            }
+        }
+    } catch WizardCliError.cancelled {
+        _ = try? await client.request(
+            method: "wizard.cancel",
+            params: ["sessionId": AnyCodable(sessionId)])
+        throw WizardCliError.cancelled
+    }
+}
+
+private func dumpResult(_ response: ResponseFrame) {
+    guard let payload = response.payload else {
+        print("{\"error\":\"missing payload\"}")
+        return
+    }
+    let encoder = JSONEncoder()
+    encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+    if let data = try? encoder.encode(payload), let text = String(data: data, encoding: .utf8) {
+        print(text)
+    }
+}
+
+private func promptAnswer(for step: WizardStep) throws -> Any {
+    let type = wizardStepType(step)
+    if let title = step.title, !title.isEmpty {
+        print("\n\(title)")
+    }
+    if let message = step.message, !message.isEmpty {
+        print(message)
+    }
+
+    switch type {
+    case "note":
+        _ = try readLineWithPrompt("Continue? (enter)")
+        return NSNull()
+    case "progress":
+        _ = try readLineWithPrompt("Continue? (enter)")
+        return NSNull()
+    case "action":
+        _ = try readLineWithPrompt("Run? (enter)")
+        return true
+    case "text":
+        let initial = anyCodableString(step.initialvalue)
+        let prompt = step.placeholder ?? "Value"
+        let value = try readLineWithPrompt("\(prompt)\(initial.isEmpty ? "" : " [\(initial)]")")
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? initial : trimmed
+    case "confirm":
+        let initial = anyCodableBool(step.initialvalue)
+        let value = try readLineWithPrompt("Confirm? (y/n) [\(initial ? "y" : "n")]")
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        if trimmed.isEmpty { return initial }
+        return trimmed == "y" || trimmed == "yes" || trimmed == "true"
+    case "select":
+        return try promptSelect(step)
+    case "multiselect":
+        return try promptMultiSelect(step)
+    default:
+        _ = try readLineWithPrompt("Continue? (enter)")
+        return NSNull()
+    }
+}
+
+private func promptSelect(_ step: WizardStep) throws -> Any {
+    let options = parseWizardOptions(step.options)
+    guard !options.isEmpty else { return NSNull() }
+    for (idx, option) in options.enumerated() {
+        let hint = option.hint?.isEmpty == false ? " — \(option.hint!)" : ""
+        print("  [\(idx + 1)] \(option.label)\(hint)")
+    }
+    let initialIndex = options.firstIndex(where: { anyCodableEqual($0.value, step.initialvalue) })
+    let defaultLabel = initialIndex.map { " [\($0 + 1)]" } ?? ""
+    while true {
+        let input = try readLineWithPrompt("Select one\(defaultLabel)")
+        let trimmed = input.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty, let initialIndex {
+            return options[initialIndex].value?.value ?? options[initialIndex].label
+        }
+        if trimmed.lowercased() == "q" { throw WizardCliError.cancelled }
+        if let number = Int(trimmed), (1...options.count).contains(number) {
+            let option = options[number - 1]
+            return option.value?.value ?? option.label
+        }
+        print("Invalid selection.")
+    }
+}
+
+private func promptMultiSelect(_ step: WizardStep) throws -> [Any] {
+    let options = parseWizardOptions(step.options)
+    guard !options.isEmpty else { return [] }
+    for (idx, option) in options.enumerated() {
+        let hint = option.hint?.isEmpty == false ? " — \(option.hint!)" : ""
+        print("  [\(idx + 1)] \(option.label)\(hint)")
+    }
+    let initialValues = anyCodableArray(step.initialvalue)
+    let initialIndices = options.enumerated().compactMap { index, option in
+        initialValues.contains { anyCodableEqual($0, option.value) } ? index + 1 : nil
+    }
+    let defaultLabel = initialIndices.isEmpty ? "" : " [\(initialIndices.map(String.init).joined(separator: ","))]"
+    while true {
+        let input = try readLineWithPrompt("Select (comma-separated)\(defaultLabel)")
+        let trimmed = input.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty {
+            return initialIndices.map { options[$0 - 1].value?.value ?? options[$0 - 1].label }
+        }
+        if trimmed.lowercased() == "q" { throw WizardCliError.cancelled }
+        let parts = trimmed.split(separator: ",").map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+        let indices = parts.compactMap { Int($0) }.filter { (1...options.count).contains($0) }
+        if indices.isEmpty {
+            print("Invalid selection.")
+            continue
+        }
+        return indices.map { options[$0 - 1].value?.value ?? options[$0 - 1].label }
+    }
+}
+
+private func readLineWithPrompt(_ prompt: String) throws -> String {
+    print("\(prompt): ", terminator: "")
+    guard let line = readLine() else {
+        throw WizardCliError.cancelled
+    }
+    return line
+}

apps/macos/Tests/ClawdbotIPCTests/CLIInstallerTests.swift

@@ -5,39 +5,30 @@ import Testing
 @Suite(.serialized)
 @MainActor
 struct CLIInstallerTests {
-    @Test func installedLocationOnlyAcceptsEmbeddedHelper() throws {
+    @Test func installedLocationFindsExecutable() throws {
         let fm = FileManager.default
         let root = fm.temporaryDirectory.appendingPathComponent(
             "clawdbot-cli-installer-\(UUID().uuidString)")
         defer { try? fm.removeItem(at: root) }
 
-        let embedded = root.appendingPathComponent("Relay/clawdbot")
-        try fm.createDirectory(at: embedded.deletingLastPathComponent(), withIntermediateDirectories: true)
-        fm.createFile(atPath: embedded.path, contents: Data())
-        try fm.setAttributes([.posixPermissions: 0o755], ofItemAtPath: embedded.path)
-
         let binDir = root.appendingPathComponent("bin")
         try fm.createDirectory(at: binDir, withIntermediateDirectories: true)
-        let link = binDir.appendingPathComponent("clawdbot")
-        try fm.createSymbolicLink(at: link, withDestinationURL: embedded)
+        let cli = binDir.appendingPathComponent("clawdbot")
+        fm.createFile(atPath: cli.path, contents: Data())
+        try fm.setAttributes([.posixPermissions: 0o755], ofItemAtPath: cli.path)
 
         let found = CLIInstaller.installedLocation(
             searchPaths: [binDir.path],
-            embeddedHelper: embedded,
             fileManager: fm)
-        #expect(found == link.path)
+        #expect(found == cli.path)
 
-        try fm.removeItem(at: link)
-        let other = root.appendingPathComponent("Other/clawdbot")
-        try fm.createDirectory(at: other.deletingLastPathComponent(), withIntermediateDirectories: true)
-        fm.createFile(atPath: other.path, contents: Data())
-        try fm.setAttributes([.posixPermissions: 0o755], ofItemAtPath: other.path)
-        try fm.createSymbolicLink(at: link, withDestinationURL: other)
+        try fm.removeItem(at: cli)
+        fm.createFile(atPath: cli.path, contents: Data())
+        try fm.setAttributes([.posixPermissions: 0o644], ofItemAtPath: cli.path)
 
-        let rejected = CLIInstaller.installedLocation(
+        let missing = CLIInstaller.installedLocation(
             searchPaths: [binDir.path],
-            embeddedHelper: embedded,
             fileManager: fm)
-        #expect(rejected == nil)
+        #expect(missing == nil)
     }
 }

apps/macos/Tests/ClawdbotIPCTests/ConnectionsSettingsSmokeTests.swift

@@ -9,68 +9,76 @@ struct ConnectionsSettingsSmokeTests {
         let store = ConnectionsStore(isPreview: true)
         store.snapshot = ProvidersStatusSnapshot(
             ts: 1_700_000_000_000,
-            whatsapp: ProvidersStatusSnapshot.WhatsAppStatus(
-                configured: true,
-                linked: true,
-                authAgeMs: 86_400_000,
-                self: ProvidersStatusSnapshot.WhatsAppSelf(
-                    e164: "+15551234567",
-                    jid: nil),
-                running: true,
-                connected: false,
-                lastConnectedAt: 1_700_000_000_000,
-                lastDisconnect: ProvidersStatusSnapshot.WhatsAppDisconnect(
-                    at: 1_700_000_050_000,
-                    status: 401,
-                    error: "logged out",
-                    loggedOut: true),
-                reconnectAttempts: 2,
-                lastMessageAt: 1_700_000_060_000,
-                lastEventAt: 1_700_000_060_000,
-                lastError: "needs login"),
-            telegram: ProvidersStatusSnapshot.TelegramStatus(
-                configured: true,
-                tokenSource: "env",
-                running: true,
-                mode: "polling",
-                lastStartAt: 1_700_000_000_000,
-                lastStopAt: nil,
-                lastError: nil,
-                probe: ProvidersStatusSnapshot.TelegramProbe(
-                    ok: true,
-                    status: 200,
-                    error: nil,
-                    elapsedMs: 120,
-                    bot: ProvidersStatusSnapshot.TelegramBot(id: 123, username: "clawdbotbot"),
-                    webhook: ProvidersStatusSnapshot.TelegramWebhook(
-                        url: "https://example.com/hook",
-                        hasCustomCert: false)),
-                lastProbeAt: 1_700_000_050_000),
-            discord: nil,
-            signal: ProvidersStatusSnapshot.SignalStatus(
-                configured: true,
-                baseUrl: "http://127.0.0.1:8080",
-                running: true,
-                lastStartAt: 1_700_000_000_000,
-                lastStopAt: nil,
-                lastError: nil,
-                probe: ProvidersStatusSnapshot.SignalProbe(
-                    ok: true,
-                    status: 200,
-                    error: nil,
-                    elapsedMs: 140,
-                    version: "0.12.4"),
-                lastProbeAt: 1_700_000_050_000),
-            imessage: ProvidersStatusSnapshot.IMessageStatus(
-                configured: false,
-                running: false,
-                lastStartAt: nil,
-                lastStopAt: nil,
-                lastError: "not configured",
-                cliPath: nil,
-                dbPath: nil,
-                probe: ProvidersStatusSnapshot.IMessageProbe(ok: false, error: "imsg not found (imsg)"),
-                lastProbeAt: 1_700_000_050_000))
+            providerOrder: ["whatsapp", "telegram", "signal", "imessage"],
+            providerLabels: [
+                "whatsapp": "WhatsApp",
+                "telegram": "Telegram",
+                "signal": "Signal",
+                "imessage": "iMessage",
+            ],
+            providers: [
+                "whatsapp": AnyCodable([
+                    "configured": true,
+                    "linked": true,
+                    "authAgeMs": 86_400_000,
+                    "self": ["e164": "+15551234567"],
+                    "running": true,
+                    "connected": false,
+                    "lastConnectedAt": 1_700_000_000_000,
+                    "lastDisconnect": [
+                        "at": 1_700_000_050_000,
+                        "status": 401,
+                        "error": "logged out",
+                        "loggedOut": true,
+                    ],
+                    "reconnectAttempts": 2,
+                    "lastMessageAt": 1_700_000_060_000,
+                    "lastEventAt": 1_700_000_060_000,
+                    "lastError": "needs login",
+                ]),
+                "telegram": AnyCodable([
+                    "configured": true,
+                    "tokenSource": "env",
+                    "running": true,
+                    "mode": "polling",
+                    "lastStartAt": 1_700_000_000_000,
+                    "probe": [
+                        "ok": true,
+                        "status": 200,
+                        "elapsedMs": 120,
+                        "bot": ["id": 123, "username": "clawdbotbot"],
+                        "webhook": ["url": "https://example.com/hook", "hasCustomCert": false],
+                    ],
+                    "lastProbeAt": 1_700_000_050_000,
+                ]),
+                "signal": AnyCodable([
+                    "configured": true,
+                    "baseUrl": "http://127.0.0.1:8080",
+                    "running": true,
+                    "lastStartAt": 1_700_000_000_000,
+                    "probe": [
+                        "ok": true,
+                        "status": 200,
+                        "elapsedMs": 140,
+                        "version": "0.12.4",
+                    ],
+                    "lastProbeAt": 1_700_000_050_000,
+                ]),
+                "imessage": AnyCodable([
+                    "configured": false,
+                    "running": false,
+                    "lastError": "not configured",
+                    "probe": ["ok": false, "error": "imsg not found (imsg)"],
+                    "lastProbeAt": 1_700_000_050_000,
+                ]),
+            ],
+            providerAccounts: [:],
+            providerDefaultAccountId: [
+                "whatsapp": "default",
+                "telegram": "default",
+                "signal": "default",
+                "imessage": "default",
+            ])
 
         store.whatsappLoginMessage = "Scan QR"
         store.whatsappLoginQrDataUrl =
@@ -91,60 +99,62 @@ struct ConnectionsSettingsSmokeTests {
         let store = ConnectionsStore(isPreview: true)
         store.snapshot = ProvidersStatusSnapshot(
             ts: 1_700_000_000_000,
-            whatsapp: ProvidersStatusSnapshot.WhatsAppStatus(
-                configured: false,
-                linked: false,
-                authAgeMs: nil,
-                self: nil,
-                running: false,
-                connected: false,
-                lastConnectedAt: nil,
-                lastDisconnect: nil,
-                reconnectAttempts: 0,
-                lastMessageAt: nil,
-                lastEventAt: nil,
-                lastError: nil),
-            telegram: ProvidersStatusSnapshot.TelegramStatus(
-                configured: false,
-                tokenSource: nil,
-                running: false,
-                mode: nil,
-                lastStartAt: nil,
-                lastStopAt: nil,
-                lastError: "bot missing",
-                probe: ProvidersStatusSnapshot.TelegramProbe(
-                    ok: false,
-                    status: 403,
-                    error: "unauthorized",
-                    elapsedMs: 120,
-                    bot: nil,
-                    webhook: nil),
-                lastProbeAt: 1_700_000_100_000),
-            discord: nil,
-            signal: ProvidersStatusSnapshot.SignalStatus(
-                configured: false,
-                baseUrl: "http://127.0.0.1:8080",
-                running: false,
-                lastStartAt: nil,
-                lastStopAt: nil,
-                lastError: "not configured",
-                probe: ProvidersStatusSnapshot.SignalProbe(
-                    ok: false,
-                    status: 404,
-                    error: "unreachable",
-                    elapsedMs: 200,
-                    version: nil),
-                lastProbeAt: 1_700_000_200_000),
-            imessage: ProvidersStatusSnapshot.IMessageStatus(
-                configured: false,
-                running: false,
-                lastStartAt: nil,
-                lastStopAt: nil,
-                lastError: "not configured",
-                cliPath: "imsg",
-                dbPath: nil,
-                probe: ProvidersStatusSnapshot.IMessageProbe(ok: false, error: "imsg not found (imsg)"),
-                lastProbeAt: 1_700_000_200_000))
+            providerOrder: ["whatsapp", "telegram", "signal", "imessage"],
+            providerLabels: [
+                "whatsapp": "WhatsApp",
+                "telegram": "Telegram",
+                "signal": "Signal",
+                "imessage": "iMessage",
+            ],
+            providers: [
+                "whatsapp": AnyCodable([
+                    "configured": false,
+                    "linked": false,
+                    "running": false,
+                    "connected": false,
+                    "reconnectAttempts": 0,
+                ]),
+                "telegram": AnyCodable([
+                    "configured": false,
+                    "running": false,
+                    "lastError": "bot missing",
+                    "probe": [
+                        "ok": false,
+                        "status": 403,
+                        "error": "unauthorized",
+                        "elapsedMs": 120,
+                    ],
+                    "lastProbeAt": 1_700_000_100_000,
+                ]),
+                "signal": AnyCodable([
+                    "configured": false,
+                    "baseUrl": "http://127.0.0.1:8080",
+                    "running": false,
+                    "lastError": "not configured",
+                    "probe": [
+                        "ok": false,
+                        "status": 404,
+                        "error": "unreachable",
+                        "elapsedMs": 200,
+                    ],
+                    "lastProbeAt": 1_700_000_200_000,
+                ]),
+                "imessage": AnyCodable([
+                    "configured": false,
+                    "running": false,
+                    "lastError": "not configured",
+                    "cliPath": "imsg",
+                    "probe": ["ok": false, "error": "imsg not found (imsg)"],
+                    "lastProbeAt": 1_700_000_200_000,
+                ]),
+            ],
+            providerAccounts: [:],
+            providerDefaultAccountId: [
+                "whatsapp": "default",
+                "telegram": "default",
+                "signal": "default",
+                "imessage": "default",
+            ])
 
         let view = ConnectionsSettings(store: store)
         _ = view.body

apps/macos/Tests/ClawdbotIPCTests/GatewayAutostartPolicyTests.swift

@@ -13,19 +13,12 @@ struct GatewayAutostartPolicyTests {
     @Test func ensuresLaunchAgentWhenLocalAndNotAttachOnly() {
         #expect(GatewayAutostartPolicy.shouldEnsureLaunchAgent(
             mode: .local,
-            paused: false,
-            attachExistingOnly: false))
+            paused: false))
         #expect(!GatewayAutostartPolicy.shouldEnsureLaunchAgent(
             mode: .local,
-            paused: false,
-            attachExistingOnly: true))
-        #expect(!GatewayAutostartPolicy.shouldEnsureLaunchAgent(
-            mode: .local,
-            paused: true,
-            attachExistingOnly: false))
+            paused: true))
         #expect(!GatewayAutostartPolicy.shouldEnsureLaunchAgent(
             mode: .remote,
-            paused: false,
-            attachExistingOnly: false))
+            paused: false))
     }
 }

apps/macos/Tests/ClawdbotIPCTests/GatewayConnectionControlTests.swift

@@ -1,17 +1,53 @@
+import Foundation
 import Testing
 @testable import Clawdbot
 @testable import ClawdbotIPC
 
+private final class FakeWebSocketTask: WebSocketTasking, @unchecked Sendable {
+    var state: URLSessionTask.State = .running
+
+    func resume() {}
+
+    func cancel(with _: URLSessionWebSocketTask.CloseCode, reason _: Data?) {
+        self.state = .canceling
+    }
+
+    func send(_: URLSessionWebSocketTask.Message) async throws {}
+
+    func receive() async throws -> URLSessionWebSocketTask.Message {
+        throw URLError(.cannotConnectToHost)
+    }
+
+    func receive(completionHandler: @escaping @Sendable (Result<URLSessionWebSocketTask.Message, Error>) -> Void) {
+        completionHandler(.failure(URLError(.cannotConnectToHost)))
+    }
+}
+
+private final class FakeWebSocketSession: WebSocketSessioning, @unchecked Sendable {
+    func makeWebSocketTask(url _: URL) -> WebSocketTaskBox {
+        WebSocketTaskBox(task: FakeWebSocketTask())
+    }
+}
+
+private func makeTestGatewayConnection() -> GatewayConnection {
+    GatewayConnection(
+        configProvider: {
+            (url: URL(string: "ws://127.0.0.1:1")!, token: nil, password: nil)
+        },
+        sessionBox: WebSocketSessionBox(session: FakeWebSocketSession()))
+}
+
 @Suite(.serialized) struct GatewayConnectionControlTests {
     @Test func statusFailsWhenProcessMissing() async {
-        let result = await GatewayConnection.shared.status()
-        // We don't assert ok because the worker may not be available in CI.
-        // Instead, ensure the call returns without throwing and provides a message.
-        #expect(result.ok == true || result.error != nil)
+        let connection = makeTestGatewayConnection()
+        let result = await connection.status()
+        #expect(result.ok == false)
+        #expect(result.error != nil)
     }
 
     @Test func rejectEmptyMessage() async {
-        let result = await GatewayConnection.shared.sendAgent(
+        let connection = makeTestGatewayConnection()
+        let result = await connection.sendAgent(
             message: "",
             thinking: nil,
             sessionKey: "main",

apps/macos/Tests/ClawdbotIPCTests/HealthDecodeTests.swift

@@ -5,14 +5,14 @@ import Testing
 @Suite struct HealthDecodeTests {
     private let sampleJSON: String = // minimal but complete payload
         """
-        {"ts":1733622000,"durationMs":420,"web":{"linked":true,"authAgeMs":120000,"connect":{"ok":true,"status":200,"error":null,"elapsedMs":800}},"heartbeatSeconds":60,"sessions":{"path":"/tmp/sessions.json","count":1,"recent":[{"key":"abc","updatedAt":1733621900,"age":120000}]}}
+        {"ts":1733622000,"durationMs":420,"providers":{"whatsapp":{"linked":true,"authAgeMs":120000},"telegram":{"configured":true,"probe":{"ok":true,"elapsedMs":800}}},"providerOrder":["whatsapp","telegram"],"heartbeatSeconds":60,"sessions":{"path":"/tmp/sessions.json","count":1,"recent":[{"key":"abc","updatedAt":1733621900,"age":120000}]}}
         """
 
     @Test func decodesCleanJSON() async throws {
         let data = Data(sampleJSON.utf8)
         let snap = decodeHealthSnapshot(from: data)
 
-        #expect(snap?.web.linked == true)
+        #expect(snap?.providers["whatsapp"]?.linked == true)
         #expect(snap?.sessions.count == 1)
     }
 
@@ -20,7 +20,7 @@ import Testing
         let noisy = "debug: something logged\n" + self.sampleJSON + "\ntrailer"
         let snap = decodeHealthSnapshot(from: Data(noisy.utf8))
 
-        #expect(snap?.web.connect?.status == 200)
+        #expect(snap?.providers["telegram"]?.probe?.elapsedMs == 800)
     }
 
     @Test func failsWithoutBraces() async throws {

apps/macos/Tests/ClawdbotIPCTests/HealthStoreStateTests.swift

@@ -0,0 +1,46 @@
+import Foundation
+import Testing
+@testable import Clawdbot
+
+@Suite struct HealthStoreStateTests {
+    @Test @MainActor func linkedProviderProbeFailureDegradesState() async throws {
+        let snap = HealthSnapshot(
+            ok: true,
+            ts: 0,
+            durationMs: 1,
+            providers: [
+                "whatsapp": .init(
+                    configured: true,
+                    linked: true,
+                    authAgeMs: 1,
+                    probe: .init(
+                        ok: false,
+                        status: 503,
+                        error: "gateway connect failed",
+                        elapsedMs: 12,
+                        bot: nil,
+                        webhook: nil
+                    ),
+                    lastProbeAt: 0
+                ),
+            ],
+            providerOrder: ["whatsapp"],
+            providerLabels: ["whatsapp": "WhatsApp"],
+            heartbeatSeconds: 60,
+            sessions: .init(path: "/tmp/sessions.json", count: 0, recent: [])
+        )
+
+        let store = HealthStore.shared
+        store.__setSnapshotForTest(snap, lastError: nil)
+
+        switch store.state {
+        case .degraded(let message):
+            #expect(!message.isEmpty)
+        default:
+            Issue.record("Expected degraded state when probe fails for linked provider")
+        }
+
+        #expect(store.summaryLine.contains("probe degraded"))
+    }
+}
+

apps/macos/Tests/ClawdbotIPCTests/LowCoverageHelperTests.swift

@@ -123,10 +123,6 @@ struct LowCoverageHelperTests {
                 #expect(
                     GatewayLaunchAgentManager._testEscapePlistValue("a&b<c>\"'") ==
                         "a&amp;b&lt;c&gt;&quot;&apos;")
-
-                #expect(GatewayLaunchAgentManager
-                    ._testGatewayExecutablePath(bundlePath: "/App") == "/App/Contents/Resources/Relay/clawdbot")
-                #expect(GatewayLaunchAgentManager._testRelayDir(bundlePath: "/App") == "/App/Contents/Resources/Relay")
             }
     }
 

docker-setup.sh

@@ -132,7 +132,7 @@ upsert_env() {
       local replaced=false
       for k in "${keys[@]}"; do
         if [[ "$key" == "$k" ]]; then
-          printf '%s=%s\n' "$k" "${!k}" >>"$tmp"
+          printf '%s=%s\n' "$k" "${!k-}" >>"$tmp"
           seen["$k"]=1
           replaced=true
           break
@@ -146,7 +146,7 @@ upsert_env() {
 
   for k in "${keys[@]}"; do
     if [[ -z "${seen[$k]:-}" ]]; then
-      printf '%s=%s\n' "$k" "${!k}" >>"$tmp"
+      printf '%s=%s\n' "$k" "${!k-}" >>"$tmp"
     fi
   done
 

docs/automation/cron-jobs.md

@@ -61,9 +61,40 @@ Key behaviors:
 - `wakeMode: "now"` triggers an immediate heartbeat after posting the summary.
 - If `payload.deliver: true`, output is delivered to a provider; otherwise it stays internal.
 
-Use isolated jobs for noisy, frequent, or “background chores” that shouldn’t spam
+Use isolated jobs for noisy, frequent, or "background chores" that shouldn't spam
 your main chat history.
 
+### Payload shapes (what runs)
+Two payload kinds are supported:
+- `systemEvent`: main-session only, routed through the heartbeat prompt.
+- `agentTurn`: isolated-session only, runs a dedicated agent turn.
+
+Common `agentTurn` fields:
+- `message`: required text prompt.
+- `model` / `thinking`: optional overrides (see below).
+- `timeoutSeconds`: optional timeout override.
+- `deliver`: `true` to send output to a provider target.
+- `provider`: `last` or a specific provider.
+- `to`: provider-specific target (phone/chat/channel id).
+- `bestEffortDeliver`: avoid failing the job if delivery fails.
+
+Isolation options (only for `session=isolated`):
+- `postToMainPrefix` (CLI: `--post-prefix`): prefix for the summary system event in main.
+
+### Model and thinking overrides
+Isolated jobs (`agentTurn`) can override the model and thinking level:
+- `model`: Provider/model string (e.g., `anthropic/claude-sonnet-4-20250514`) or alias (e.g., `opus`)
+- `thinking`: Thinking level (`off`, `minimal`, `low`, `medium`, `high`)
+
+Note: You can set `model` on main-session jobs too, but it changes the shared main
+session model. We recommend model overrides only for isolated jobs to avoid
+unexpected context shifts.
+
+Resolution priority:
+1. Job payload override (highest)
+2. Hook-specific defaults (e.g., `hooks.gmail.model`)
+3. Agent config default
+
 ### Delivery (provider + target)
 Isolated jobs can deliver output to a provider. The job payload can specify:
 - `provider`: `whatsapp` / `telegram` / `discord` / `slack` / `signal` / `imessage` / `last`
@@ -72,6 +103,10 @@ Isolated jobs can deliver output to a provider. The job payload can specify:
 If `provider` or `to` is omitted, cron can fall back to the main session’s “last route”
 (the last place the agent replied).
 
+Target format reminders:
+- Slack/Discord targets should use explicit prefixes (e.g. `channel:<id>`, `user:<id>`) to avoid ambiguity.
+- Telegram topics should use the `:topic:` form (see below).
+
 #### Telegram delivery targets (topics / forum threads)
 Telegram supports forum topics via `message_thread_id`. For cron delivery, you can encode
 the topic/thread into the `to` field:
@@ -142,11 +177,34 @@ clawdbot cron add \
   --to "-1001234567890:topic:123"
 ```
 
+Isolated job with model and thinking override:
+```bash
+clawdbot cron add \
+  --name "Deep analysis" \
+  --cron "0 6 * * 1" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --message "Weekly deep analysis of project progress." \
+  --model "opus" \
+  --thinking high \
+  --deliver \
+  --provider whatsapp \
+  --to "+15551234567"
+```
+
 Manual run (debug):
 ```bash
 clawdbot cron run <jobId> --force
 ```
 
+Edit an existing job (patch fields):
+```bash
+clawdbot cron edit <jobId> \
+  --message "Updated prompt" \
+  --model "opus" \
+  --thinking low
+```
+
 Run history:
 ```bash
 clawdbot cron runs --id <jobId> --limit 50

docs/broadcast-groups.md

@@ -180,7 +180,7 @@ In group `120363403215116621@g.us` with agents `["alfred", "baerbel"]`:
 Session: agent:alfred:whatsapp:group:120363403215116621@g.us
 History: [user message, alfred's previous responses]
 Workspace: /Users/pascal/clawd-alfred/
-Tools: read, write, bash
+Tools: read, write, exec
 ```
 
 **Bärbel's context:**
@@ -230,10 +230,10 @@ Give agents only the tools they need:
 {
   "agents": {
     "reviewer": {
-      "tools": { "allow": ["read", "bash"] }  // Read-only
+      "tools": { "allow": ["read", "exec"] }  // Read-only
     },
     "fixer": {
-      "tools": { "allow": ["read", "write", "edit", "bash"] }  // Read-write
+      "tools": { "allow": ["read", "write", "edit", "exec"] }  // Read-write
     }
   }
 }
@@ -330,8 +330,8 @@ tail -f ~/.clawdbot/logs/gateway.log | grep broadcast
   "agents": {
     "list": [
       { "id": "code-formatter", "workspace": "~/agents/formatter", "tools": { "allow": ["read", "write"] } },
-      { "id": "security-scanner", "workspace": "~/agents/security", "tools": { "allow": ["read", "bash"] } },
-      { "id": "test-coverage", "workspace": "~/agents/testing", "tools": { "allow": ["read", "bash"] } },
+      { "id": "security-scanner", "workspace": "~/agents/security", "tools": { "allow": ["read", "exec"] } },
+      { "id": "test-coverage", "workspace": "~/agents/testing", "tools": { "allow": ["read", "exec"] } },
       { "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } }
     ]
   }

docs/cli/gateway.md

@@ -92,7 +92,7 @@ The macOS app “Remote over SSH” mode uses a local port-forward so the remote
 CLI equivalent:
 
 ```bash
-clawdbot gateway status --ssh steipete@peters-mac-studio-1
+clawdbot gateway status --ssh user@gateway-host
 ```
 
 Options:

docs/cli/index.md

@@ -48,6 +48,8 @@ clawdbot [--dev] [--profile <name>] <command>
   onboard
   configure (alias: config)
   doctor
+  reset
+  uninstall
   update
   providers
     list
@@ -61,6 +63,13 @@ clawdbot [--dev] [--profile <name>] <command>
     list
     info
     check
+  plugins
+    list
+    info
+    install
+    enable
+    disable
+    doctor
   message
   agent
   agents
@@ -165,6 +174,20 @@ clawdbot [--dev] [--profile <name>] <command>
   tui
 ```
 
+Note: plugins can add additional top-level commands (for example `clawdbot voicecall`).
+
+## Plugins
+
+Manage extensions and their config:
+
+- `clawdbot plugins list` — discover plugins (use `--json` for machine output).
+- `clawdbot plugins info <id>` — show details for a plugin.
+- `clawdbot plugins install <path|.tgz|npm-spec>` — install a plugin (or add a plugin path to `plugins.load.paths`).
+- `clawdbot plugins enable <id>` / `disable <id>` — toggle `plugins.entries.<id>.enabled`.
+- `clawdbot plugins doctor` — report plugin load errors.
+
+Most plugin changes require a gateway restart. See [/plugin](/plugin).
+
 ## Chat slash commands
 
 Chat messages support `/...` commands (text and native). See [/tools/slash-commands](/tools/slash-commands).
@@ -198,13 +221,15 @@ Options:
 - `--non-interactive`
 - `--mode <local|remote>`
 - `--flow <quickstart|advanced>`
-- `--auth-choice <setup-token|claude-cli|token|openai-codex|openai-api-key|codex-cli|antigravity|gemini-api-key|zai-api-key|apiKey|minimax-cloud|minimax-api|minimax|opencode-zen|skip>`
+- `--auth-choice <setup-token|claude-cli|token|openai-codex|openai-api-key|openrouter-api-key|moonshot-api-key|codex-cli|antigravity|gemini-api-key|zai-api-key|apiKey|minimax-api|opencode-zen|skip>`
 - `--token-provider <id>` (non-interactive; used with `--auth-choice token`)
 - `--token <token>` (non-interactive; used with `--auth-choice token`)
 - `--token-profile-id <id>` (non-interactive; default: `<provider>:manual`)
 - `--token-expires-in <duration>` (non-interactive; e.g. `365d`, `12h`)
 - `--anthropic-api-key <key>`
 - `--openai-api-key <key>`
+- `--openrouter-api-key <key>`
+- `--moonshot-api-key <key>`
 - `--gemini-api-key <key>`
 - `--zai-api-key <key>`
 - `--minimax-api-key <key>`
@@ -253,7 +278,7 @@ Subcommands:
 - `providers add`: wizard-style setup when no flags are passed; flags switch to non-interactive mode.
 - `providers remove`: disable by default; pass `--delete` to remove config entries without prompts.
 - `providers login`: interactive provider login (WhatsApp Web only).
-- `providers logout`: log out of a provider session (WhatsApp Web only).
+- `providers logout`: log out of a provider session (if supported).
 
 Common options:
 - `--provider <name>`: `whatsapp|telegram|discord|slack|signal|imessage|msteams`
@@ -266,7 +291,7 @@ Common options:
 - `--verbose`
 
 `providers logout` options:
-- `--provider <provider>` (default `whatsapp`; supports `whatsapp`/`web`)
+- `--provider <provider>` (default `whatsapp`)
 - `--account <id>`
 
 `providers list` options:
@@ -442,6 +467,36 @@ Options:
 - `--store <path>`
 - `--active <minutes>`
 
+## Reset / Uninstall
+
+### `reset`
+Reset local config/state (keeps the CLI installed).
+
+Options:
+- `--scope <config|config+creds+sessions|full>`
+- `--yes`
+- `--non-interactive`
+- `--dry-run`
+
+Notes:
+- `--non-interactive` requires `--scope` and `--yes`.
+
+### `uninstall`
+Uninstall the gateway service + local data (CLI remains).
+
+Options:
+- `--service`
+- `--state`
+- `--workspace`
+- `--app`
+- `--all`
+- `--yes`
+- `--non-interactive`
+- `--dry-run`
+
+Notes:
+- `--non-interactive` requires `--yes` and explicit scopes (or `--all`).
+
 ## Gateway
 
 ### `gateway`
@@ -691,7 +746,7 @@ Manage:
 
 Inspect:
 - `browser screenshot [targetId] [--full-page] [--ref <ref>] [--element <selector>] [--type png|jpeg]`
-- `browser snapshot [--format aria|ai] [--target-id <id>] [--limit <n>] [--out <path>]`
+- `browser snapshot [--format aria|ai] [--target-id <id>] [--limit <n>] [--interactive] [--compact] [--depth <n>] [--selector <sel>] [--out <path>]`
 
 Actions:
 - `browser navigate <url> [--target-id <id>]`

docs/concepts/agent-workspace.md

@@ -99,6 +99,8 @@ These are the standard files Clawdbot expects inside the workspace:
   - Curated long-term memory.
   - Only load in the main, private session (not shared/group contexts).
 
+See [Memory](/concepts/memory) for the workflow and automatic memory flush.
+
 - `skills/` (optional)
   - Workspace-specific skills.
   - Overrides managed/bundled skills when names collide.

docs/concepts/agent.md

@@ -45,7 +45,10 @@ To disable bootstrap file creation entirely (for pre-seeded workspaces), set:
 
 ## Built-in tools
 
-Core tools (read/bash/edit/write and related system tools) are always available. `TOOLS.md` does **not** control which tools exist; it’s guidance for how *you* want them used.
+Core tools (read/exec/edit/write and related system tools) are always available,
+subject to tool policy. `apply_patch` is optional and gated by
+`tools.exec.applyPatch`. `TOOLS.md` does **not** control which tools exist; it’s
+guidance for how *you* want them used.
 
 ## Skills
 

docs/concepts/architecture.md

@@ -11,9 +11,11 @@ Last updated: 2026-01-05
 
 - A single long‑lived **Gateway** owns all messaging surfaces (WhatsApp via
   Baileys, Telegram via grammY, Slack, Discord, Signal, iMessage, WebChat).
-- All clients (macOS app, CLI, web UI, automations) connect to the Gateway over
-  **one transport: WebSocket** on the configured bind host (default
+- Control-plane clients (macOS app, CLI, web UI, automations) connect to the
+  Gateway over **WebSocket** on the configured bind host (default
   `127.0.0.1:18789`).
+- **Nodes** (macOS/iOS/Android) use the **Bridge** protocol (TCP JSONL) instead
+  of the WebSocket control plane.
 - One Gateway per host; it is the only place that opens a WhatsApp session.
 - A **bridge** (default `18790`) is used for nodes (macOS/iOS/Android).
 - A **canvas host** (default `18793`) serves agent‑editable HTML and A2UI.
@@ -36,6 +38,10 @@ Last updated: 2026-01-05
 - Pair with the Gateway to receive a token.
 - Expose commands like `canvas.*`, `camera.*`, `screen.record`, `location.get`.
 
+Protocol details:
+- [Gateway protocol](/gateway/protocol)
+- [Bridge protocol](/gateway/bridge-protocol)
+
 ### WebChat
 - Static UI that uses the Gateway WS API for chat history and sends.
 - In remote setups, connects through the same SSH/Tailscale tunnel as other

docs/concepts/compaction.md

@@ -22,6 +22,9 @@ You’ll see:
 - `🧹 Auto-compaction complete` in verbose mode
 - `/status` showing `🧹 Compactions: <count>`
 
+Before compaction, Clawdbot can run a **silent memory flush** turn to store
+durable notes to disk. See [Memory](/concepts/memory) for details and config.
+
 ## Manual compaction
 Use `/compact` (optionally with instructions) to force a compaction pass:
 ```

docs/concepts/group-messages.md

@@ -11,7 +11,7 @@ Note: `agents.list[].groupChat.mentionPatterns` is now used by Telegram/Discord/
 
 ## What’s implemented (2025-12-03)
 - Activation modes: `mention` (default) or `always`. `mention` requires a ping (real WhatsApp @-mentions via `mentionedJids`, regex patterns, or the bot’s E.164 anywhere in the text). `always` wakes the agent on every message but it should reply only when it can add meaningful value; otherwise it returns the silent token `NO_REPLY`. Defaults can be set in config (`whatsapp.groups`) and overridden per group via `/activation`. When `whatsapp.groups` is set, it also acts as a group allowlist (include `"*"` to allow all).
-- Group policy: `whatsapp.groupPolicy` controls whether group messages are accepted (`open|disabled|allowlist`). `allowlist` uses `whatsapp.groupAllowFrom` (fallback: explicit `whatsapp.allowFrom`).
+- Group policy: `whatsapp.groupPolicy` controls whether group messages are accepted (`open|disabled|allowlist`). `allowlist` uses `whatsapp.groupAllowFrom` (fallback: explicit `whatsapp.allowFrom`). Default is `allowlist` (blocked until you add senders).
 - Per-group sessions: session keys look like `agent:<agentId>:whatsapp:group:<jid>` so commands such as `/verbose on` or `/think high` (sent as standalone messages) are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads.
 - Context injection: last N (default 50) group messages are prefixed under `[Chat messages since your last reply - for context]`, with the triggering line under `[Current message - respond to this]`.
 - Sender surfacing: every group batch now ends with `[from: Sender Name (+E164)]` so Pi knows who is speaking.
@@ -61,7 +61,7 @@ Only the owner number (from `whatsapp.allowFrom`, or the bot’s own E.164 when
 
 ## How to use
 1) Add Clawd UK (`+447700900123`) to the group.
-2) Say `@clawd …` (or `@clawd uk`, `@clawdbot`, or include the number). Anyone in the group can trigger it.
+2) Say `@clawd …` (or `@clawd uk`, `@clawdbot`, or include the number). Only allowlisted senders can trigger it unless you set `groupPolicy: "open"`.
 3) The agent prompt will include recent group context plus the trailing `[from: …]` marker so it can address the right person.
 4) Session-level directives (`/verbose on`, `/think high`, `/new` or `/reset`, `/compact`) apply only to that group’s session; send them as standalone messages so they register. Your personal DM session remains independent.
 

docs/concepts/groups.md

@@ -1,21 +1,21 @@
 ---
-summary: "Group chat behavior across surfaces (WhatsApp/Telegram/Discord/Slack/Signal/iMessage)"
+summary: "Group chat behavior across surfaces (WhatsApp/Telegram/Discord/Slack/Signal/iMessage/Microsoft Teams)"
 read_when:
   - Changing group chat behavior or mention gating
 ---
 # Groups
 
-Clawdbot treats group chats consistently across surfaces: WhatsApp, Telegram, Discord, Slack, Signal, iMessage.
+Clawdbot treats group chats consistently across surfaces: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams.
 
 ## Beginner intro (2 minutes)
 Clawdbot “lives” on your own messaging accounts. There is no separate WhatsApp bot user.
 If **you** are in a group, Clawdbot can see that group and respond there.
 
 Default behavior:
-- Groups are allowed (`groupPolicy: "open"`).
+- Groups are restricted (`groupPolicy: "allowlist"`).
 - Replies require a mention unless you explicitly disable mention gating.
 
-Translation: anyone in the group can trigger Clawdbot by mentioning it.
+Translation: allowlisted senders can trigger Clawdbot by mentioning it.
 
 > TL;DR
 > - **DM access** is controlled by `*.allowFrom`.
@@ -71,6 +71,10 @@ Control how group/room messages are handled per provider:
     groupPolicy: "disabled",
     groupAllowFrom: ["chat_id:123"]
   },
+  msteams: {
+    groupPolicy: "disabled",
+    groupAllowFrom: ["user@org.com"]
+  },
   discord: {
     groupPolicy: "allowlist",
     guilds: {
@@ -86,17 +90,18 @@ Control how group/room messages are handled per provider:
 
 | Policy | Behavior |
 |--------|----------|
-| `"open"` | Default. Groups bypass allowlists; mention-gating still applies. |
+| `"open"` | Groups bypass allowlists; mention-gating still applies. |
 | `"disabled"` | Block all group messages entirely. |
 | `"allowlist"` | Only allow groups/rooms that match the configured allowlist. |
 
 Notes:
 - `groupPolicy` is separate from mention-gating (which requires @mentions).
-- WhatsApp/Telegram/Signal/iMessage: use `groupAllowFrom` (fallback: explicit `allowFrom`).
+- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams: use `groupAllowFrom` (fallback: explicit `allowFrom`).
 - Discord: allowlist uses `discord.guilds.<id>.channels`.
 - Slack: allowlist uses `slack.channels`.
 - Group DMs are controlled separately (`discord.dm.*`, `slack.dm.*`).
 - Telegram allowlist can match user IDs (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) or usernames (`"@alice"` or `"alice"`); prefixes are case-insensitive.
+- Default is `groupPolicy: "allowlist"`; if your group allowlist is empty, group messages are blocked.
 
 Quick mental model (evaluation order for group messages):
 1) `groupPolicy` (open/disabled/allowlist)

docs/concepts/memory.md

@@ -0,0 +1,69 @@
+---
+summary: "How Clawdbot memory works (workspace files + automatic memory flush)"
+read_when:
+  - You want the memory file layout and workflow
+  - You want to tune the automatic pre-compaction memory flush
+---
+# Memory
+
+Clawdbot memory is **plain Markdown in the agent workspace**. The files are the
+source of truth; the model only "remembers" what gets written to disk.
+
+## Memory files (Markdown)
+
+The default workspace layout uses two memory layers:
+
+- `memory/YYYY-MM-DD.md`
+  - Daily log (append-only).
+  - Read today + yesterday at session start.
+- `MEMORY.md` (optional)
+  - Curated long-term memory.
+  - **Only load in the main, private session** (never in group contexts).
+
+These files live under the workspace (`agents.defaults.workspace`, default
+`~/clawd`). See [Agent workspace](/concepts/agent-workspace) for the full layout.
+
+## When to write memory
+
+- Decisions, preferences, and durable facts go to `MEMORY.md`.
+- Day-to-day notes and running context go to `memory/YYYY-MM-DD.md`.
+- If someone says "remember this," write it down (do not keep it in RAM).
+
+## Automatic memory flush (pre-compaction ping)
+
+When a session is **close to auto-compaction**, Clawdbot triggers a **silent,
+agentic turn** that reminds the model to write durable memory **before** the
+context is compacted. The default prompts explicitly say the model *may reply*,
+but usually `NO_REPLY` is the correct response so the user never sees this turn.
+
+This is controlled by `agents.defaults.compaction.memoryFlush`:
+
+```json5
+{
+  agents: {
+    defaults: {
+      compaction: {
+        reserveTokensFloor: 20000,
+        memoryFlush: {
+          enabled: true,
+          softThresholdTokens: 4000,
+          systemPrompt: "Session nearing compaction. Store durable memories now.",
+          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
+        }
+      }
+    }
+  }
+}
+```
+
+Details:
+- **Soft threshold**: flush triggers when the session token estimate crosses
+  `contextWindow - reserveTokensFloor - softThresholdTokens`.
+- **Silent** by default: prompts include `NO_REPLY` so nothing is delivered.
+- **Two prompts**: a user prompt plus a system prompt append the reminder.
+- **One flush per compaction cycle** (tracked in `sessions.json`).
+- **Workspace must be writable**: if the session runs sandboxed with
+  `workspaceAccess: "ro"` or `"none"`, the flush is skipped.
+
+For the full compaction lifecycle, see
+[Session management + compaction](/reference/session-management-compaction).

docs/concepts/model-providers.md

@@ -76,7 +76,7 @@ Clawdbot ships with the pi‑ai catalog. These providers require **no**
 
 - Provider: `google`
 - Auth: `GEMINI_API_KEY`
-- Example model: `google/gemini-3-pro`
+- Example model: `google/gemini-3-pro-preview`
 - CLI: `clawdbot onboard --auth-choice gemini-api-key`
 
 ### Google Vertex / Antigravity / Gemini CLI
@@ -100,6 +100,8 @@ Clawdbot ships with the pi‑ai catalog. These providers require **no**
 - xAI: `xai` (`XAI_API_KEY`)
 - Groq: `groq` (`GROQ_API_KEY`)
 - Cerebras: `cerebras` (`CEREBRAS_API_KEY`)
+  - GLM models on Cerebras use ids `zai-glm-4.7` and `zai-glm-4.6`.
+  - OpenAI-compatible base URL: `https://api.cerebras.ai/v1`.
 - Mistral: `mistral` (`MISTRAL_API_KEY`)
 - GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`)
 
@@ -108,14 +110,43 @@ Clawdbot ships with the pi‑ai catalog. These providers require **no**
 Use `models.providers` (or `models.json`) to add **custom** providers or
 OpenAI/Anthropic‑compatible proxies.
 
+### Moonshot AI (Kimi)
+
+Moonshot uses OpenAI-compatible endpoints, so configure it as a custom provider:
+
+- Provider: `moonshot`
+- Auth: `MOONSHOT_API_KEY`
+- Example model: `moonshot/kimi-k2-0905-preview`
+- CLI: `clawdbot onboard --auth-choice moonshot-api-key`
+
+```json5
+{
+  agents: {
+    defaults: { model: { primary: "moonshot/kimi-k2-0905-preview" } }
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      moonshot: {
+        baseUrl: "https://api.moonshot.ai/v1",
+        apiKey: "${MOONSHOT_API_KEY}",
+        api: "openai-completions",
+        models: [{ id: "kimi-k2-0905-preview", name: "Kimi K2 0905 Preview" }]
+      }
+    }
+  }
+}
+```
+
 ### MiniMax
 
 MiniMax is configured via `models.providers` because it uses custom endpoints:
 
-- MiniMax Cloud (OpenAI‑compatible): `--auth-choice minimax-cloud`
-- MiniMax API (Anthropic‑compatible): `--auth-choice minimax-api`
+- MiniMax (Anthropic‑compatible): `--auth-choice minimax-api`
 - Auth: `MINIMAX_API_KEY`
 
+See [/providers/minimax](/providers/minimax) for setup details, model options, and config snippets.
+
 ### Local proxies (LM Studio, vLLM, LiteLLM, etc.)
 
 Example (OpenAI‑compatible):

docs/concepts/models.md

@@ -23,6 +23,7 @@ Clawdbot selects models in this order:
 Related:
 - `agents.defaults.models` is the allowlist/catalog of models Clawdbot can use (plus aliases).
 - `agents.defaults.imageModel` is used **only when** the primary model can’t accept images.
+- Per-agent defaults can override `agents.defaults.model` via `agents.list[].model` plus bindings (see [/concepts/multi-agent](/concepts/multi-agent)).
 
 ## Quick model picks (anecdotal)
 
@@ -85,6 +86,25 @@ Example allowlist config:
 }
 ```
 
+## Switching models in chat (`/model`)
+
+You can switch models for the current session without restarting:
+
+```
+/model
+/model list
+/model 3
+/model openai/gpt-5.2
+/model status
+```
+
+Notes:
+- `/model` (and `/model list`) is a compact, numbered picker (model family + available providers).
+- `/model <#>` selects from that picker.
+- `/model status` is the detailed view (auth candidates and, when configured, provider endpoint `baseUrl` + `api` mode).
+
+Full command behavior/config: [Slash commands](/tools/slash-commands).
+
 ## CLI commands
 
 ```bash

docs/concepts/multi-agent.md

@@ -70,6 +70,37 @@ With **multiple agents**, each `agentId` becomes a **fully isolated persona**:
 
 This lets **multiple people** share one Gateway server while keeping their AI “brains” and data isolated.
 
+## One WhatsApp number, multiple people (DM split)
+
+You can route **different WhatsApp DMs** to different agents while staying on **one WhatsApp account**. Match on sender E.164 (like `+15551234567`) with `peer.kind: "dm"`. Replies still come from the same WhatsApp number (no per‑agent sender identity).
+
+Important detail: direct chats collapse to the agent’s **main session key**, so true isolation requires **one agent per person**.
+
+Example:
+
+```json5
+{
+  agents: {
+    list: [
+      { id: "alex", workspace: "~/clawd-alex" },
+      { id: "mia", workspace: "~/clawd-mia" }
+    ]
+  },
+  bindings: [
+    { agentId: "alex", match: { provider: "whatsapp", peer: { kind: "dm", id: "+15551230001" } } },
+    { agentId: "mia",  match: { provider: "whatsapp", peer: { kind: "dm", id: "+15551230002" } } }
+  ],
+  whatsapp: {
+    dmPolicy: "allowlist",
+    allowFrom: ["+15551230001", "+15551230002"]
+  }
+}
+```
+
+Notes:
+- DM access control is **global per WhatsApp account** (pairing/allowlist), not per agent.
+- For shared groups, bind the group to one agent or use [Broadcast groups](/broadcast-groups).
+
 ## Routing rules (how messages pick an agent)
 
 Bindings are **deterministic** and **most-specific wins**:
@@ -157,6 +188,60 @@ multiple phone numbers without mixing sessions.
 }
 ```
 
+## Example: WhatsApp daily chat + Telegram deep work
+
+Split by provider: route WhatsApp to a fast everyday agent and Telegram to an Opus agent.
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "chat",
+        name: "Everyday",
+        workspace: "~/clawd-chat",
+        model: "anthropic/claude-sonnet-4-5"
+      },
+      {
+        id: "opus",
+        name: "Deep Work",
+        workspace: "~/clawd-opus",
+        model: "anthropic/claude-opus-4-5"
+      }
+    ]
+  },
+  bindings: [
+    { agentId: "chat", match: { provider: "whatsapp" } },
+    { agentId: "opus", match: { provider: "telegram" } }
+  ]
+}
+```
+
+Notes:
+- If you have multiple accounts for a provider, add `accountId` to the binding (for example `{ provider: "whatsapp", accountId: "personal" }`).
+- To route a single DM/group to Opus while keeping the rest on chat, add a `match.peer` binding for that peer; peer matches always win over provider-wide rules.
+
+## Example: same provider, one peer to Opus
+
+Keep WhatsApp on the fast agent, but route one DM to Opus:
+
+```json5
+{
+  agents: {
+    list: [
+      { id: "chat", name: "Everyday", workspace: "~/clawd-chat", model: "anthropic/claude-sonnet-4-5" },
+      { id: "opus", name: "Deep Work", workspace: "~/clawd-opus", model: "anthropic/claude-opus-4-5" }
+    ]
+  },
+  bindings: [
+    { agentId: "opus", match: { provider: "whatsapp", peer: { kind: "dm", id: "+15551234567" } } },
+    { agentId: "chat", match: { provider: "whatsapp" } }
+  ]
+}
+```
+
+Peer bindings always win, so keep them above the provider-wide rule.
+
 ## Per-Agent Sandbox and Tool Configuration
 
 Starting with v2026.1.6, each agent can have its own sandbox and tool restrictions:
@@ -186,7 +271,7 @@ Starting with v2026.1.6, each agent can have its own sandbox and tool restrictio
         },
         tools: {
           allow: ["read"],                    // Only read tool
-          deny: ["bash", "write", "edit"],    // Deny others
+          deny: ["exec", "write", "edit", "apply_patch"],    // Deny others
         },
       },
     ],
@@ -200,7 +285,7 @@ Starting with v2026.1.6, each agent can have its own sandbox and tool restrictio
 - **Flexible policies**: Different permissions per agent
 
 Note: `tools.elevated` is **global** and sender-based; it is not configurable per agent.
-If you need per-agent boundaries, use `agents.list[].tools` to deny `bash`.
+If you need per-agent boundaries, use `agents.list[].tools` to deny `exec`.
 For group targeting, use `agents.list[].groupChat.mentionPatterns` so @mentions map cleanly to the intended agent.
 
 See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for detailed examples.

docs/concepts/presence.md

@@ -18,12 +18,12 @@ provide quick operator visibility.
 
 Presence entries are structured objects with fields like:
 
-- `instanceId` (optional but strongly recommended): stable client identity
+- `instanceId` (optional but strongly recommended): stable client identity (usually `connect.client.instanceId`)
 - `host`: human‑friendly host name
 - `ip`: best‑effort IP address
 - `version`: client version string
 - `deviceFamily` / `modelIdentifier`: hardware hints
-- `mode`: `gateway`, `app`, `webchat`, `cli`, `node`, ...
+- `mode`: `ui`, `webchat`, `cli`, `backend`, `probe`, `test`, `node`, ...
 - `lastInputSeconds`: “seconds since last user input” (if known)
 - `reason`: `self`, `connect`, `node-connected`, `periodic`, ...
 - `ts`: last update timestamp (ms since epoch)
@@ -62,7 +62,7 @@ for that node and refreshes it periodically so it doesn’t expire.
 Presence entries are stored in a single in‑memory map:
 
 - Entries are keyed by a **presence key**.
-- The best key is a stable `instanceId` that survives restarts.
+- The best key is a stable `instanceId` (from `connect.client.instanceId`) that survives restarts.
 - Keys are case‑insensitive.
 
 If a client reconnects without a stable `instanceId`, it may show up as a
@@ -94,6 +94,6 @@ indicator (Active/Idle/Stale) based on the age of the last update.
 
 - To see the raw list, call `system-presence` against the Gateway.
 - If you see duplicates:
-  - confirm clients send a stable `instanceId` in the handshake
+  - confirm clients send a stable `client.instanceId` in the handshake
   - confirm periodic beacons use the same `instanceId`
   - check whether the connection‑derived entry is missing `instanceId` (duplicates are expected)

docs/concepts/provider-routing.md

@@ -1,5 +1,5 @@
 ---
-summary: "Routing rules per provider (WhatsApp, Telegram, Discord, web) and shared context"
+summary: "Routing rules per provider (WhatsApp, Telegram, Discord, Slack) and shared context"
 read_when:
   - Changing provider routing or inbox behavior
 ---

docs/concepts/session-pruning.md

@@ -93,7 +93,7 @@ Restrict pruning to specific tools:
   agent: {
     contextPruning: {
       mode: "adaptive",
-      tools: { allow: ["bash", "read"], deny: ["*image*"] }
+      tools: { allow: ["exec", "read"], deny: ["*image*"] }
     }
   }
 }

docs/concepts/session.md

@@ -25,6 +25,12 @@ All session state is **owned by the gateway** (the “master” Clawdbot). UI cl
 Clawdbot trims **old tool results** from the in-memory context right before LLM calls by default.
 This does **not** rewrite JSONL history. See [/concepts/session-pruning](/concepts/session-pruning).
 
+## Pre-compaction memory flush
+When a session nears auto-compaction, Clawdbot can run a **silent memory flush**
+turn that reminds the model to write durable notes to disk. This only runs when
+the workspace is writable. See [Memory](/concepts/memory) and
+[Compaction](/concepts/compaction).
+
 ## Mapping transports → session keys
 - Direct chats collapse to the per-agent primary key: `agent:<agentId>:<mainKey>`.
   - Multiple phone numbers and providers can map to the same agent main key; they act as transports into one conversation.

docs/concepts/system-prompt.md

@@ -19,7 +19,7 @@ The prompt is intentionally compact and uses fixed sections:
 - **Clawdbot Self-Update**: how to run `config.apply` and `update.run`.
 - **Workspace**: working directory (`agents.defaults.workspace`).
 - **Workspace Files (injected)**: indicates bootstrap files are included below.
-- **Sandbox** (when enabled): indicates sandboxed runtime, sandbox paths, and whether elevated bash is available.
+- **Sandbox** (when enabled): indicates sandboxed runtime, sandbox paths, and whether elevated exec is available.
 - **Time**: UTC default + the user’s local time (already converted).
 - **Reply Tags**: optional reply tag syntax for supported providers.
 - **Heartbeats**: heartbeat prompt and ack behavior.

docs/concepts/typebox.md

@@ -91,10 +91,11 @@ Connect (first message):
     "minProtocol": 2,
     "maxProtocol": 2,
     "client": {
-      "name": "macos",
+      "id": "clawdbot-macos",
+      "displayName": "macos",
       "version": "1.0.0",
       "platform": "macos 15.1",
-      "mode": "app",
+      "mode": "ui",
       "instanceId": "A1B2"
     }
   }
@@ -150,10 +151,11 @@ ws.on("open", () => {
     id: "c1",
     method: "connect",
     params: {
-      minProtocol: 2,
-      maxProtocol: 2,
+      minProtocol: 3,
+      maxProtocol: 3,
       client: {
-        name: "example",
+        id: "cli",
+        displayName: "example",
         version: "dev",
         platform: "node",
         mode: "cli"

docs/docs.json

@@ -103,7 +103,11 @@
     },
     {
       "source": "/bash",
-      "destination": "/tools/bash"
+      "destination": "/tools/exec"
+    },
+    {
+      "source": "/tools/bash",
+      "destination": "/tools/exec"
     },
     {
       "source": "/bonjour",
@@ -548,6 +552,10 @@
     {
       "source": "/oauth",
       "destination": "/concepts/oauth"
+    },
+    {
+      "source": "/plugins",
+      "destination": "/plugin"
     }
   ],
   "navigation": {
@@ -571,6 +579,8 @@
       {
         "group": "Install & Updates",
         "pages": [
+          "install/index",
+          "install/installer",
           "install/updating",
           "install/ansible",
           "install/nix",
@@ -598,6 +608,7 @@
           "token-use",
           "concepts/oauth",
           "concepts/agent-workspace",
+          "concepts/memory",
           "concepts/multi-agent",
           "concepts/compaction",
           "concepts/session",
@@ -625,6 +636,8 @@
         "group": "Gateway & Ops",
         "pages": [
           "gateway",
+          "gateway/protocol",
+          "gateway/bridge-protocol",
           "gateway/pairing",
           "gateway/gateway-lock",
           "environment",
@@ -689,7 +702,9 @@
         "group": "Tools & Skills",
         "pages": [
           "tools",
-          "tools/bash",
+          "plugin",
+          "tools/exec",
+          "tools/apply-patch",
           "tools/elevated",
           "tools/browser",
           "tools/browser-linux-troubleshooting",
@@ -757,6 +772,7 @@
         "pages": [
           "testing",
           "scripts",
+          "reference/session-management-compaction",
           "reference/rpc",
           "reference/device-models",
           "reference/test",

docs/experiments/research/memory.md

@@ -192,7 +192,7 @@ Offline-friendly alternatives (in increasing complexity):
 - SuCo (research-grade; attractive if there’s a solid implementation you can embed)
 
 Open question:
-- what’s the **best** offline embedding model for “personal assistant memory” on your machines (MacBook + Castle)?
+- what’s the **best** offline embedding model for “personal assistant memory” on your machines (laptop + desktop)?
   - if you already have Ollama: embed with a local model; otherwise ship a small embedding model in the toolchain.
 
 ## Smallest useful pilot

docs/gateway/authentication.md

@@ -114,7 +114,9 @@ clawdbot doctor
 
 ### Per-session (chat command)
 
-Use `/model <alias-or-id>@<profileId>` to pin a specific provider credential for the current session (example profile ids: `anthropic:claude-cli`, `anthropic:default`). Use `/model status` to see candidates + which one is next.
+Use `/model <alias-or-id>@<profileId>` to pin a specific provider credential for the current session (example profile ids: `anthropic:claude-cli`, `anthropic:default`).
+
+Use `/model` (or `/model list`) for a compact picker; use `/model status` for the full view (candidates + next auth profile, plus provider endpoint details when configured).
 
 ### Per-agent (CLI override)
 

docs/gateway/background-process.md

@@ -1,15 +1,15 @@
 ---
-summary: "Background bash execution and process management"
+summary: "Background exec execution and process management"
 read_when:
-  - Adding or modifying background bash behavior
-  - Debugging long-running bash tasks
+  - Adding or modifying background exec behavior
+  - Debugging long-running exec tasks
 ---
 
-# Background Bash + Process Tool
+# Background Exec + Process Tool
 
-Clawdbot runs shell commands through the `bash` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
+Clawdbot runs shell commands through the `exec` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
 
-## bash tool
+## exec tool
 
 Key parameters:
 - `command` (required)
@@ -24,7 +24,7 @@ Behavior:
 - Foreground runs return output directly.
 - When backgrounded (explicit or timeout), the tool returns `status: "running"` + `sessionId` and a short tail.
 - Output is kept in memory until the session is polled or cleared.
-- If the `process` tool is disallowed, `bash` runs synchronously and ignores `yieldMs`/`background`.
+- If the `process` tool is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
 
 Environment overrides:
 - `PI_BASH_YIELD_MS`: default yield (ms)
@@ -32,9 +32,9 @@ Environment overrides:
 - `PI_BASH_JOB_TTL_MS`: TTL for finished sessions (ms, bounded to 1m–3h)
 
 Config (preferred):
-- `tools.bash.backgroundMs` (default 10000)
-- `tools.bash.timeoutSec` (default 1800)
-- `tools.bash.cleanupMs` (default 1800000)
+- `tools.exec.backgroundMs` (default 10000)
+- `tools.exec.timeoutSec` (default 1800)
+- `tools.exec.cleanupMs` (default 1800000)
 
 ## process tool
 
@@ -59,7 +59,7 @@ Notes:
 
 Run a long task and poll later:
 ```json
-{"tool": "bash", "command": "sleep 5 && echo done", "yieldMs": 1000}
+{"tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000}
 ```
 ```json
 {"tool": "process", "action": "poll", "sessionId": "<id>"}
@@ -67,7 +67,7 @@ Run a long task and poll later:
 
 Start immediately in background:
 ```json
-{"tool": "bash", "command": "npm run build", "background": true}
+{"tool": "exec", "command": "npm run build", "background": true}
 ```
 
 Send stdin:

docs/gateway/bridge-protocol.md

@@ -0,0 +1,67 @@
+---
+summary: "Bridge protocol (nodes): TCP JSONL, pairing, scoped RPC"
+read_when:
+  - Building or debugging node clients (iOS/Android/macOS node mode)
+  - Investigating pairing or bridge auth failures
+  - Auditing the node surface exposed by the gateway
+---
+
+# Bridge protocol (Node transport)
+
+The Bridge protocol is a **narrow, authenticated** transport for nodes
+(iOS/Android/macOS node mode). It keeps the Gateway WS control plane loopback‑only
+and exposes only a scoped set of methods for nodes.
+
+If you are building an operator client (CLI, web UI, automations), use the
+[Gateway protocol](/gateway/protocol).
+
+## Why we have both
+
+- **Security boundary**: the bridge exposes a small allowlist instead of the
+  full gateway API surface.
+- **Pairing + node identity**: node admission is owned by the gateway and tied
+  to a per-node token.
+- **Discovery UX**: nodes can discover gateways via Bonjour on LAN, or connect
+  directly over a tailnet.
+- **Loopback WS**: the full WS control plane stays local unless tunneled via SSH.
+
+## Transport
+
+- TCP, one JSON object per line (JSONL).
+- Gateway owns the listener (default `18790`).
+
+## Handshake + pairing
+
+1) Client sends `hello` with node metadata + token (if already paired).  
+2) If not paired, gateway replies `error` (`NOT_PAIRED`/`UNAUTHORIZED`).  
+3) Client sends `pair-request`.  
+4) Gateway waits for approval, then sends `pair-ok` and `hello-ok`.
+
+`hello-ok` returns `serverName` and may include `canvasHostUrl`.
+
+## Frames
+
+Client → Gateway:
+- `req` / `res`: scoped gateway RPC (chat, sessions, config, health, voicewake)
+- `event`: node signals (voice transcript, agent request, chat subscribe)
+
+Gateway → Client:
+- `invoke` / `invoke-res`: node commands (`canvas.*`, `camera.*`, `screen.record`,
+  `location.get`, `sms.send`)
+- `event`: chat updates for subscribed sessions
+- `ping` / `pong`: keepalive
+
+Exact allowlist is enforced in `src/gateway/server-bridge.ts`.
+
+## Tailnet usage
+
+- Bind the bridge to a tailnet IP: `bridge.bind: "tailnet"` in
+  `~/.clawdbot/clawdbot.json`.
+- Clients connect via MagicDNS name or tailnet IP.
+- Bonjour does **not** cross networks; use manual host/port or wide-area DNS‑SD
+  when needed.
+
+## Versioning
+
+Bridge is currently **implicit v1** (no min/max negotiation). Backward‑compat
+is expected; add a bridge protocol version field before any breaking changes.

docs/gateway/configuration-examples.md

@@ -150,7 +150,8 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
   whatsapp: {
     dmPolicy: "pairing",
     allowFrom: ["+15555550123"],
-    groupPolicy: "open",
+    groupPolicy: "allowlist",
+    groupAllowFrom: ["+15555550123"],
     groups: { "*": { requireMention: true } }
   },
 
@@ -158,7 +159,8 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
     enabled: true,
     botToken: "YOUR_TELEGRAM_BOT_TOKEN",
     allowFrom: ["123456789"],
-    groupPolicy: "open",
+    groupPolicy: "allowlist",
+    groupAllowFrom: ["123456789"],
     groups: { "*": { requireMention: true } }
   },
 
@@ -259,9 +261,9 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
   },
 
   tools: {
-    allow: ["bash", "process", "read", "write", "edit"],
+    allow: ["exec", "process", "read", "write", "edit", "apply_patch"],
     deny: ["browser", "canvas"],
-    bash: {
+    exec: {
       backgroundMs: 10000,
       timeoutSec: 1800,
       cleanupMs: 1800000

docs/gateway/configuration.md

@@ -82,6 +82,132 @@ To prevent the bot from responding to WhatsApp @-mentions in groups (only respon
 }
 ```
 
+## Config Includes (`$include`)
+
+Split your config into multiple files using the `$include` directive. This is useful for:
+- Organizing large configs (e.g., per-client agent definitions)
+- Sharing common settings across environments
+- Keeping sensitive configs separate
+
+### Basic usage
+
+```json5
+// ~/.clawdbot/clawdbot.json
+{
+  gateway: { port: 18789 },
+  
+  // Include a single file (replaces the key's value)
+  agents: { "$include": "./agents.json5" },
+  
+  // Include multiple files (deep-merged in order)
+  broadcast: { 
+    "$include": [
+      "./clients/mueller.json5",
+      "./clients/schmidt.json5"
+    ]
+  }
+}
+```
+
+```json5
+// ~/.clawdbot/agents.json5
+{
+  defaults: { sandbox: { mode: "all", scope: "session" } },
+  list: [
+    { id: "main", workspace: "~/clawd" }
+  ]
+}
+```
+
+### Merge behavior
+
+- **Single file**: Replaces the object containing `$include`
+- **Array of files**: Deep-merges files in order (later files override earlier ones)
+- **With sibling keys**: Sibling keys are merged after includes (override included values)
+- **Sibling keys + arrays/primitives**: Not supported (included content must be an object)
+
+```json5
+// Sibling keys override included values
+{
+  "$include": "./base.json5",   // { a: 1, b: 2 }
+  b: 99                          // Result: { a: 1, b: 99 }
+}
+```
+
+### Nested includes
+
+Included files can themselves contain `$include` directives (up to 10 levels deep):
+
+```json5
+// clients/mueller.json5
+{
+  agents: { "$include": "./mueller/agents.json5" },
+  broadcast: { "$include": "./mueller/broadcast.json5" }
+}
+```
+
+### Path resolution
+
+- **Relative paths**: Resolved relative to the including file
+- **Absolute paths**: Used as-is
+- **Parent directories**: `../` references work as expected
+
+```json5
+{ "$include": "./sub/config.json5" }      // relative
+{ "$include": "/etc/clawdbot/base.json5" } // absolute
+{ "$include": "../shared/common.json5" }   // parent dir
+```
+
+### Error handling
+
+- **Missing file**: Clear error with resolved path
+- **Parse error**: Shows which included file failed
+- **Circular includes**: Detected and reported with include chain
+
+### Example: Multi-client legal setup
+
+```json5
+// ~/.clawdbot/clawdbot.json
+{
+  gateway: { port: 18789, auth: { token: "secret" } },
+  
+  // Common agent defaults
+  agents: {
+    defaults: {
+      sandbox: { mode: "all", scope: "session" }
+    },
+    // Merge agent lists from all clients
+    list: { "$include": [
+      "./clients/mueller/agents.json5",
+      "./clients/schmidt/agents.json5"
+    ]}
+  },
+  
+  // Merge broadcast configs
+  broadcast: { "$include": [
+    "./clients/mueller/broadcast.json5",
+    "./clients/schmidt/broadcast.json5"
+  ]},
+  
+  whatsapp: { groupPolicy: "allowlist" }
+}
+```
+
+```json5
+// ~/.clawdbot/clients/mueller/agents.json5
+[
+  { id: "mueller-transcribe", workspace: "~/clients/mueller/transcribe" },
+  { id: "mueller-docs", workspace: "~/clients/mueller/docs" }
+]
+```
+
+```json5
+// ~/.clawdbot/clients/mueller/broadcast.json5
+{
+  "120363403215116621@g.us": ["mueller-transcribe", "mueller-docs"]
+}
+```
+
 ## Common options
 
 ### Env vars + `.env`
@@ -403,6 +529,10 @@ Use `*.groupPolicy` to control whether group/room messages are accepted at all:
     groupPolicy: "allowlist",
     groupAllowFrom: ["chat_id:123"]
   },
+  msteams: {
+    groupPolicy: "allowlist",
+    groupAllowFrom: ["user@org.com"]
+  },
   discord: {
     groupPolicy: "allowlist",
     guilds: {
@@ -419,12 +549,13 @@ Use `*.groupPolicy` to control whether group/room messages are accepted at all:
 ```
 
 Notes:
-- `"open"` (default): groups bypass allowlists; mention-gating still applies.
+- `"open"`: groups bypass allowlists; mention-gating still applies.
 - `"disabled"`: block all group/room messages.
 - `"allowlist"`: only allow groups/rooms that match the configured allowlist.
-- WhatsApp/Telegram/Signal/iMessage use `groupAllowFrom` (fallback: explicit `allowFrom`).
+- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams use `groupAllowFrom` (fallback: explicit `allowFrom`).
 - Discord/Slack use channel allowlists (`discord.guilds.*.channels`, `slack.channels`).
 - Group DMs (Discord/Slack) are still controlled by `dm.groupEnabled` + `dm.groupChannels`.
+- Default is `groupPolicy: "allowlist"`; if no allowlist is configured, group messages are blocked.
 
 ### Multi-agent routing (`agents.list` + `bindings`)
 
@@ -512,7 +643,7 @@ Read-only tools + read-only workspace:
         },
         tools: {
           allow: ["read", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
-          deny: ["write", "edit", "bash", "process", "browser"]
+          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"]
         }
       }
     ]
@@ -535,7 +666,7 @@ No filesystem access (messaging/session tools enabled):
         },
         tools: {
           allow: ["sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", "whatsapp", "telegram", "slack", "discord", "gateway"],
-          deny: ["read", "write", "edit", "bash", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
+          deny: ["read", "write", "edit", "apply_patch", "exec", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
         }
       }
     ]
@@ -1026,6 +1157,27 @@ Each `agents.defaults.models` entry can include:
 - `alias` (optional model shortcut, e.g. `/opus`).
 - `params` (optional provider-specific API params passed through to the model request).
 
+`params` is also applied to streaming runs (embedded agent + compaction). Supported keys today: `temperature`, `maxTokens`. These merge with call-time options; caller-supplied values win. `temperature` is an advanced knob—leave unset unless you know the model’s defaults and need a change.
+
+Example:
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-sonnet-4-5-20250929": {
+          params: { temperature: 0.6 }
+        },
+        "openai/gpt-5.2": {
+          params: { maxTokens: 8192 }
+        }
+      }
+    }
+  }
+}
+```
+
 Z.AI GLM-4.x models automatically enable thinking mode unless you:
 - set `--thinking off`, or
 - define `agents.defaults.models["zai/<model>"].params.thinking` yourself.
@@ -1127,7 +1279,7 @@ Example:
         maxConcurrent: 1,
         archiveAfterMinutes: 60
       },
-      bash: {
+      exec: {
         backgroundMs: 10000,
         timeoutSec: 1800,
         cleanupMs: 1800000
@@ -1221,6 +1373,42 @@ Example (adaptive tuned):
 
 See [/concepts/session-pruning](/concepts/session-pruning) for behavior details.
 
+#### `agents.defaults.compaction` (reserve headroom + memory flush)
+
+`agents.defaults.compaction.reserveTokensFloor` enforces a minimum `reserveTokens`
+value for Pi compaction (default: `20000`). Set it to `0` to disable the floor.
+
+`agents.defaults.compaction.memoryFlush` runs a **silent** agentic turn before
+auto-compaction, instructing the model to store durable memories on disk (e.g.
+`memory/YYYY-MM-DD.md`). It triggers when the session token estimate crosses a
+soft threshold below the compaction limit.
+
+Defaults:
+- `memoryFlush.enabled`: `true`
+- `memoryFlush.softThresholdTokens`: `4000`
+- `memoryFlush.prompt` / `memoryFlush.systemPrompt`: built-in defaults with `NO_REPLY`
+- Note: memory flush is skipped when the session workspace is read-only
+  (`agents.defaults.sandbox.workspaceAccess: "ro"` or `"none"`).
+
+Example (tuned):
+```json5
+{
+  agents: {
+    defaults: {
+      compaction: {
+        reserveTokensFloor: 24000,
+        memoryFlush: {
+          enabled: true,
+          softThresholdTokens: 6000,
+          systemPrompt: "Session nearing compaction. Store durable memories now.",
+          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
+        }
+      }
+    }
+  }
+}
+```
+
 Block streaming:
 - `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (default off).
 - Provider overrides: `*.blockStreaming` (and per-account variants) to force block streaming on/off.
@@ -1280,10 +1468,14 @@ Z.AI models are available as `zai/<model>` (e.g. `zai/glm-4.7`) and require
 Heartbeats run full agent turns. Shorter intervals burn more tokens; be mindful
 of `every`, keep `HEARTBEAT.md` tiny, and/or choose a cheaper `model`.
 
-`tools.bash` configures background bash defaults:
+`tools.exec` configures background exec defaults:
 - `backgroundMs`: time before auto-background (ms, default 10000)
 - `timeoutSec`: auto-kill after this runtime (seconds, default 1800)
 - `cleanupMs`: how long to keep finished sessions in memory (ms, default 1800000)
+- `applyPatch.enabled`: enable experimental `apply_patch` (OpenAI/OpenAI Codex only; default false)
+- `applyPatch.allowModels`: optional allowlist of model ids (e.g. `gpt-5.2` or `openai/gpt-5.2`)
+Note: `applyPatch` is only under `tools.exec` (no `tools.bash` alias).
+Legacy: `tools.bash` is still accepted as an alias.
 
 `agents.defaults.subagents` configures sub-agent defaults:
 - `maxConcurrent`: max concurrent sub-agent runs (default 1)
@@ -1300,7 +1492,7 @@ Example (disable browser/canvas everywhere):
 }
 ```
 
-`tools.elevated` controls elevated (host) bash access:
+`tools.elevated` controls elevated (host) exec access:
 - `enabled`: allow elevated mode (default true)
 - `allowFrom`: per-provider allowlists (empty = disabled)
   - `whatsapp`: E.164 numbers
@@ -1344,8 +1536,8 @@ Per-agent override (further restrict):
 Notes:
 - `tools.elevated` is the global baseline. `agents.list[].tools.elevated` can only further restrict (both must allow).
 - `/elevated on|off` stores state per session key; inline directives apply to a single message.
-- Elevated `bash` runs on the host and bypasses sandboxing.
-- Tool policy still applies; if `bash` is denied, elevated cannot be used.
+- Elevated `exec` runs on the host and bypasses sandboxing.
+- Tool policy still applies; if `exec` is denied, elevated cannot be used.
 
 `agents.defaults.maxConcurrent` sets the maximum number of embedded agent runs that can
 execute in parallel across sessions. Each session is still serialized (one run
@@ -1363,10 +1555,10 @@ Defaults (if enabled):
 - Debian bookworm-slim based image
 - agent workspace access: `workspaceAccess: "none"` (default)
   - `"none"`: use a per-scope sandbox workspace under `~/.clawdbot/sandboxes`
-  - `"ro"`: keep the sandbox workspace at `/workspace`, and mount the agent workspace read-only at `/agent` (disables `write`/`edit`)
+- `"ro"`: keep the sandbox workspace at `/workspace`, and mount the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`)
   - `"rw"`: mount the agent workspace read/write at `/workspace`
 - auto-prune: idle > 24h OR age > 7d
-- tool policy: allow only `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status` (deny wins)
+- tool policy: allow only `exec`, `process`, `read`, `write`, `edit`, `apply_patch`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status` (deny wins)
   - configure via `tools.sandbox.tools`, override per-agent via `agents.list[].tools.sandbox.tools`
 - optional sandboxed browser (Chromium + CDP, noVNC observer)
 - hardening knobs: `network`, `user`, `pidsLimit`, `memory`, `cpus`, `ulimits`, `seccompProfile`, `apparmorProfile`
@@ -1437,7 +1629,7 @@ Legacy: `perSession` is still supported (`true` → `scope: "session"`,
   tools: {
     sandbox: {
       tools: {
-        allow: ["bash", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
+        allow: ["exec", "process", "read", "write", "edit", "apply_patch", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
         deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
       }
     }
@@ -1577,9 +1769,51 @@ Notes:
   override (see the custom providers section above).
 - Use a fake placeholder in docs/configs; never commit real API keys.
 
+### Moonshot AI (Kimi)
+
+Use Moonshot's OpenAI-compatible endpoint:
+
+```json5
+{
+  env: { MOONSHOT_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: { primary: "moonshot/kimi-k2-0905-preview" },
+      models: { "moonshot/kimi-k2-0905-preview": { alias: "Kimi K2" } }
+    }
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      moonshot: {
+        baseUrl: "https://api.moonshot.ai/v1",
+        apiKey: "${MOONSHOT_API_KEY}",
+        api: "openai-completions",
+        models: [
+          {
+            id: "kimi-k2-0905-preview",
+            name: "Kimi K2 0905 Preview",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 256000,
+            maxTokens: 8192
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+Notes:
+- Set `MOONSHOT_API_KEY` in the environment or use `clawdbot onboard --auth-choice moonshot-api-key`.
+- Model ref: `moonshot/kimi-k2-0905-preview`.
+- Use `https://api.moonshot.cn/v1` if you need the China endpoint.
+
 ### Local models (LM Studio) — recommended setup
 
-Best current local setup (what we’re running): **MiniMax M2.1** on a beefy Mac Studio
+Best current local setup (what we’re running): **MiniMax M2.1** on a powerful local machine
 via **LM Studio** using the **Responses API**.
 
 ```json5
@@ -1622,9 +1856,9 @@ Notes:
 - Responses API enables clean reasoning/output separation; WhatsApp sees only final text.
 - Adjust `contextWindow`/`maxTokens` if your LM Studio context length differs.
 
-### MiniMax API (platform.minimax.io)
+### MiniMax M2.1
 
-Use MiniMax's Anthropic-compatible API directly without LM Studio:
+Use MiniMax M2.1 directly without LM Studio:
 
 ```json5
 {
@@ -1648,25 +1882,7 @@ Use MiniMax's Anthropic-compatible API directly without LM Studio:
             name: "MiniMax M2.1",
             reasoning: false,
             input: ["text"],
-            // Pricing: MiniMax doesn't publish public rates. Override in models.json for accurate costs.
-            cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
-            contextWindow: 200000,
-            maxTokens: 8192
-          },
-          {
-            id: "MiniMax-M2.1-lightning",
-            name: "MiniMax M2.1 Lightning",
-            reasoning: false,
-            input: ["text"],
-            cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
-            contextWindow: 200000,
-            maxTokens: 8192
-          },
-          {
-            id: "MiniMax-M2",
-            name: "MiniMax M2",
-            reasoning: true,
-            input: ["text"],
+            // Pricing: update in models.json if you need exact cost tracking.
             cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
             contextWindow: 200000,
             maxTokens: 8192
@@ -1679,9 +1895,49 @@ Use MiniMax's Anthropic-compatible API directly without LM Studio:
 ```
 
 Notes:
-- Set `MINIMAX_API_KEY` environment variable or use `clawdbot onboard --auth-choice minimax-api`
-- Available models: `MiniMax-M2.1` (default), `MiniMax-M2.1-lightning` (~100 tps), `MiniMax-M2` (reasoning)
-- Pricing is a placeholder; MiniMax doesn't publish public rates. Override in `models.json` for accurate cost tracking.
+- Set `MINIMAX_API_KEY` environment variable or use `clawdbot onboard --auth-choice minimax-api`.
+- Available model: `MiniMax-M2.1` (default).
+- Update pricing in `models.json` if you need exact cost tracking.
+
+### Cerebras (GLM 4.6 / 4.7)
+
+Use Cerebras via their OpenAI-compatible endpoint:
+
+```json5
+{
+  env: { CEREBRAS_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: {
+        primary: "cerebras/zai-glm-4.7",
+        fallbacks: ["cerebras/zai-glm-4.6"]
+      },
+      models: {
+        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
+        "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" }
+      }
+    }
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      cerebras: {
+        baseUrl: "https://api.cerebras.ai/v1",
+        apiKey: "${CEREBRAS_API_KEY}",
+        api: "openai-completions",
+        models: [
+          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },
+          { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" }
+        ]
+      }
+    }
+  }
+}
+```
+
+Notes:
+- Use `cerebras/zai-glm-4.7` for Cerebras; use `zai/glm-4.7` for Z.AI direct.
+- Set `CEREBRAS_API_KEY` in the environment or config.
 
 Notes:
 - Supported APIs: `openai-completions`, `openai-responses`, `anthropic-messages`,
@@ -1775,6 +2031,44 @@ Example:
 }
 ```
 
+### `plugins` (extensions)
+
+Controls plugin discovery, allow/deny, and per-plugin config. Plugins are loaded
+from `~/.clawdbot/extensions`, `<workspace>/.clawdbot/extensions`, plus any
+`plugins.load.paths` entries. **Config changes require a gateway restart.**
+See [/plugin](/plugin) for full usage.
+
+Fields:
+- `enabled`: master toggle for plugin loading (default: true).
+- `allow`: optional allowlist of plugin ids; when set, only listed plugins load.
+- `deny`: optional denylist of plugin ids (deny wins).
+- `load.paths`: extra plugin files or directories to load (absolute or `~`).
+- `entries.<pluginId>`: per-plugin overrides.
+  - `enabled`: set `false` to disable.
+  - `config`: plugin-specific config object (validated by the plugin if provided).
+
+Example:
+
+```json5
+{
+  plugins: {
+    enabled: true,
+    allow: ["voice-call"],
+    load: {
+      paths: ["~/Projects/oss/voice-call-extension"]
+    },
+    entries: {
+      "voice-call": {
+        enabled: true,
+        config: {
+          provider: "twilio"
+        }
+      }
+    }
+  }
+}
+```
+
 ### `browser` (clawd-managed Chrome)
 
 Clawdbot can start a **dedicated, isolated** Chrome/Chromium instance for clawd and expose a small loopback control server.
@@ -1942,6 +2236,7 @@ Requires full Gateway restart:
 - `bridge`
 - `discovery`
 - `canvasHost`
+- `plugins`
 - Any unknown/unsupported config path (defaults to restart for safety)
 
 ### Multi-instance isolation

docs/gateway/discovery.md

@@ -21,6 +21,10 @@ The design goal is to keep all network discovery/advertising in the **Node Gatew
 - **Bridge (direct transport)**: a LAN/tailnet-facing endpoint owned by the gateway that allows authenticated clients/nodes to call a scoped subset of gateway methods. The bridge exists so the gateway can remain loopback-only.
 - **SSH transport (fallback)**: remote control by forwarding `127.0.0.1:18789` over SSH.
 
+Protocol details:
+- [Gateway protocol](/gateway/protocol)
+- [Bridge protocol](/gateway/bridge-protocol)
+
 ## Why we keep both “direct” and SSH
 
 - **Direct bridge** is the best UX on the same network and within a tailnet:

docs/gateway/doctor.md

@@ -111,7 +111,7 @@ Current migrations:
 - `routing.agentToAgent` → `tools.agentToAgent`
 - `routing.transcribeAudio` → `tools.audio.transcription`
 - `identity` → `agents.list[].identity`
-- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/bash/sandbox/subagents)
+- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
 - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
   → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
 

docs/gateway/health.md

@@ -1,16 +1,16 @@
 ---
-summary: "Health check steps for Baileys/WhatsApp connectivity"
+summary: "Health check steps for provider connectivity"
 read_when:
   - Diagnosing web provider health
 ---
 # Health Checks (CLI)
 
-Short guide to verify the WhatsApp Web / Baileys stack without guessing.
+Short guide to verify provider connectivity without guessing.
 
 ## Quick checks
-- `clawdbot status` — local summary: gateway reachability/mode, update hint, creds/auth age, sessions + recent activity.
+- `clawdbot status` — local summary: gateway reachability/mode, update hint, link provider auth age, sessions + recent activity.
 - `clawdbot status --all` — full local diagnosis (read-only, color, safe to paste for debugging).
-- `clawdbot status --deep` — adds gateway health probes to status output (Telegram + Discord APIs; requires reachable gateway).
+- `clawdbot status --deep` — also probes the running Gateway (per-provider probes when supported).
 - `clawdbot health --json` — asks the running Gateway for a full health snapshot (WS-only; no direct Baileys socket).
 - Send `/status` as a standalone message in WhatsApp/WebChat to get a status reply without invoking the agent.
 - Logs: tail `/tmp/clawdbot/clawdbot-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`.
@@ -26,4 +26,4 @@ Short guide to verify the WhatsApp Web / Baileys stack without guessing.
 - No inbound messages → confirm linked phone is online and the sender is allowed (`whatsapp.allowFrom`); for group chats, ensure allowlist + mention rules match (`whatsapp.groups`, `agents.list[].groupChat.mentionPatterns`).
 
 ## Dedicated "health" command
-`clawdbot health --json` asks the running Gateway for its health snapshot (no direct Baileys socket from the CLI). It reports linked creds, auth age, Baileys connect result/status code, session-store summary, and a probe duration. It exits non-zero if the Gateway is unreachable or the probe fails/timeouts. Use `--timeout <ms>` to override the 10s default.
+`clawdbot health --json` asks the running Gateway for its health snapshot (no direct provider sockets from the CLI). It reports linked creds/auth age when available, per-provider probe summaries, session-store summary, and a probe duration. It exits non-zero if the Gateway is unreachable or the probe fails/timeouts. Use `--timeout <ms>` to override the 10s default.

docs/gateway/index.md

@@ -103,12 +103,13 @@ CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b clawdbo
 ```
 
 ## Protocol (operator view)
-- Mandatory first frame from client: `req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{name,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId}, caps, auth?, locale?, userAgent? } }`.
+- Full docs: [Gateway protocol](/gateway/protocol) and [Bridge protocol](/gateway/bridge-protocol).
+- Mandatory first frame from client: `req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{id,displayName?,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId?}, caps, auth?, locale?, userAgent? } }`.
 - Gateway replies `res {type:"res", id, ok:true, payload:hello-ok }` (or `ok:false` with an error, then closes).
 - After handshake:
   - Requests: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
   - Events: `{type:"event", event, payload, seq?, stateVersion?}`
-- Structured presence entries: `{host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }`.
+- Structured presence entries: `{host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }` (for WS clients, `instanceId` comes from `connect.client.instanceId`).
 - `agent` responses are two-stage: first `res` ack `{runId,status:"accepted"}`, then a final `res` `{runId,status:"ok"|"error",summary}` after the run finishes; streamed output arrives as `event:"agent"`.
 
 ## Methods (initial set)
@@ -123,7 +124,7 @@ CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b clawdbo
 - `node.invoke` — invoke a command on a node (e.g. `canvas.*`, `camera.*`).
 - `node.pair.*` — pairing lifecycle (`request`, `list`, `approve`, `reject`, `verify`).
 
-See also: [Presence](/concepts/presence) for how presence is produced/deduped and why `instanceId` matters.
+See also: [Presence](/concepts/presence) for how presence is produced/deduped and why a stable `client.instanceId` matters.
 
 ## Events
 - `agent` — streamed tool/output events from the agent run (seq-tagged).
@@ -259,7 +260,7 @@ Windows installs should use **WSL2** and follow the Linux systemd section above.
 
 ## Operational checks
 - Liveness: open WS and send `req:connect` → expect `res` with `payload.type="hello-ok"` (with snapshot).
-- Readiness: call `health` → expect `ok: true` and `web.linked=true`.
+- Readiness: call `health` → expect `ok: true` and a linked provider in the `providers` payload (when applicable).
 - Debug: subscribe to `tick` and `presence` events; ensure `status` shows linked/auth age; presence entries show Gateway host and connected clients.
 
 ## Safety guarantees

docs/gateway/logging.md

@@ -50,7 +50,7 @@ You can tune console verbosity independently via:
 
 ## Tool summary redaction
 
-Verbose tool summaries (e.g. `🛠️ bash: ...`) can mask sensitive tokens before they hit the
+Verbose tool summaries (e.g. `🛠️ exec: ...`) can mask sensitive tokens before they hit the
 console stream. This is **tools-only** and does not alter file logs.
 
 - `logging.redactSensitive`: `off` | `tools` (default: `tools`)

docs/gateway/protocol.md

@@ -0,0 +1,86 @@
+---
+summary: "Gateway WebSocket protocol: handshake, frames, versioning"
+read_when:
+  - Implementing or updating gateway WS clients
+  - Debugging protocol mismatches or connect failures
+  - Regenerating protocol schema/models
+---
+
+# Gateway protocol (WebSocket)
+
+The Gateway WS protocol is the **full control plane** for Clawdbot. It is
+loopback-only by default and is intended for local clients (CLI, web UI,
+automations).
+
+If you are building a **node client** (iOS/Android/macOS node mode), use the
+[Bridge protocol](/gateway/bridge-protocol) instead.
+
+## Transport
+
+- WebSocket, text frames with JSON payloads.
+- First frame **must** be a `connect` request.
+
+## Handshake (connect)
+
+Client → Gateway:
+
+```json
+{
+  "type": "req",
+  "id": "…",
+  "method": "connect",
+  "params": {
+    "minProtocol": 3,
+    "maxProtocol": 3,
+    "client": {
+      "id": "cli",
+      "version": "1.2.3",
+      "platform": "macos",
+      "mode": "operator"
+    },
+    "caps": [],
+    "auth": { "token": "…" },
+    "locale": "en-US",
+    "userAgent": "clawdbot-cli/1.2.3"
+  }
+}
+```
+
+Gateway → Client:
+
+```json
+{
+  "type": "res",
+  "id": "…",
+  "ok": true,
+  "payload": { "type": "hello-ok", "protocol": 3, "policy": { "tickIntervalMs": 15000 } }
+}
+```
+
+## Framing
+
+- **Request**: `{type:"req", id, method, params}`  
+- **Response**: `{type:"res", id, ok, payload|error}`  
+- **Event**: `{type:"event", event, payload, seq?, stateVersion?}`
+
+Side-effecting methods require **idempotency keys** (see schema).
+
+## Versioning
+
+- `PROTOCOL_VERSION` lives in `src/gateway/protocol/schema.ts`.
+- Clients send `minProtocol` + `maxProtocol`; the server rejects mismatches.
+- Schemas + models are generated from TypeBox definitions:
+  - `pnpm protocol:gen`
+  - `pnpm protocol:gen:swift`
+  - `pnpm protocol:check`
+
+## Auth
+
+- If `CLAWDBOT_GATEWAY_TOKEN` (or `--token`) is set, `connect.params.auth.token`
+  must match or the socket is closed.
+
+## Scope
+
+This protocol exposes the **full gateway API** (status, providers, models,
+chat, agent, sessions, nodes, etc.). The exact surface is defined by the
+TypeBox schemas in `src/gateway/protocol/schema.ts`.

docs/gateway/remote-gateway-readme.md

@@ -11,7 +11,7 @@ Clawdbot.app uses SSH tunneling to connect to a remote gateway. This guide shows
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                          MacBook                              │
+│                        Client Machine                          │
 │                                                              │
 │  Clawdbot.app ──► ws://127.0.0.1:18789 (local port)           │
 │                     │                                        │
@@ -150,4 +150,4 @@ launchctl bootout gui/$UID/com.clawdbot.ssh-tunnel
 | `KeepAlive` | Automatically restarts tunnel if it crashes |
 | `RunAtLoad` | Starts tunnel when the agent loads |
 
-Clawdbot.app connects to `ws://127.0.0.1:18789` on your MacBook. The SSH tunnel forwards that connection to port 18789 on the remote machine where the Gateway is running.
+Clawdbot.app connects to `ws://127.0.0.1:18789` on your client machine. The SSH tunnel forwards that connection to port 18789 on the remote machine where the Gateway is running.

docs/gateway/remote.md

@@ -5,7 +5,7 @@ read_when:
 ---
 # Remote access (SSH, tunnels, and tailnets)
 
-This repo supports “remote over SSH” by keeping a single Gateway (the master) running on a host (e.g., your Mac Studio) and connecting clients to it.
+This repo supports “remote over SSH” by keeping a single Gateway (the master) running on a dedicated host (desktop/server) and connecting clients to it.
 
 - For **operators (you / the macOS app)**: SSH tunneling is the universal fallback.
 - For **nodes (iOS/Android and future devices)**: prefer the Gateway **Bridge** when on the same LAN/tailnet (see [Discovery](/gateway/discovery)).

docs/gateway/sandbox-vs-tool-policy-vs-elevated.md

@@ -1,6 +1,6 @@
 ---
 title: Sandbox vs Tool Policy vs Elevated
-summary: "Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated bash gates"
+summary: "Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated exec gates"
 read_when: "You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change."
 status: active
 ---
@@ -11,7 +11,7 @@ Clawdbot has three related (but different) controls:
 
 1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) decides **where tools run** (Docker vs host).
 2. **Tool policy** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) decides **which tools are available/allowed**.
-3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) is a **bash-only escape hatch** to run on the host when you’re sandboxed.
+3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) is an **exec-only escape hatch** to run on the host when you’re sandboxed.
 
 ## Quick debug
 
@@ -49,10 +49,10 @@ Rules of thumb:
 - `deny` always wins.
 - If `allow` is non-empty, everything else is treated as blocked.
 
-## Elevated: bash-only “run on host”
+## Elevated: exec-only “run on host”
 
-Elevated does **not** grant extra tools; it only affects `bash`.
-- If you’re sandboxed, `/elevated on` (or `bash` with `elevated: true`) runs on the host.
+Elevated does **not** grant extra tools; it only affects `exec`.
+- If you’re sandboxed, `/elevated on` (or `exec` with `elevated: true`) runs on the host.
 - If you’re already running direct, elevated is effectively a no-op (still gated).
 
 Gates:
@@ -74,4 +74,3 @@ Fix-it keys (pick one):
 ### “I thought this was main, why is it sandboxed?”
 
 In `"non-main"` mode, group/channel keys are *not* main. Use the main session key (shown by `sandbox explain`) or switch mode to `"off"`.
-

docs/gateway/sandboxing.md

@@ -17,7 +17,7 @@ This is not a perfect security boundary, but it materially limits filesystem
 and process access when the model does something dumb.
 
 ## What gets sandboxed
-- Tool execution (`bash`, `read`, `write`, `edit`, `process`, etc.).
+- Tool execution (`exec`, `read`, `write`, `edit`, `apply_patch`, `process`, etc.).
 - Optional sandboxed browser (`agents.defaults.sandbox.browser`).
   - By default, the sandbox browser auto-starts (ensures CDP is reachable) when the browser tool needs it.
     Configure via `agents.defaults.sandbox.browser.autoStart` and `agents.defaults.sandbox.browser.autoStartTimeoutMs`.
@@ -27,7 +27,7 @@ and process access when the model does something dumb.
 Not sandboxed:
 - The Gateway process itself.
 - Any tool explicitly allowed to run on the host (e.g. `tools.elevated`).
-  - **Elevated bash runs on the host and bypasses sandboxing.**
+  - **Elevated exec runs on the host and bypasses sandboxing.**
   - If sandboxing is off, `tools.elevated` does not change execution (already on host). See [Elevated Mode](/tools/elevated).
 
 ## Modes
@@ -47,7 +47,7 @@ Group/channel sessions use their own keys, so they count as non-main and will be
 ## Workspace access
 `agents.defaults.sandbox.workspaceAccess` controls **what the sandbox can see**:
 - `"none"` (default): tools see a sandbox workspace under `~/.clawdbot/sandboxes`.
-- `"ro"`: mounts the agent workspace read-only at `/agent` (disables `write`/`edit`).
+- `"ro"`: mounts the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`).
 - `"rw"`: mounts the agent workspace read/write at `/workspace`.
 
 Inbound media is copied into the active sandbox workspace (`media/inbound/*`).
@@ -79,7 +79,7 @@ Docker installs and the containerized gateway live here:
 Tool allow/deny policies still apply before sandbox rules. If a tool is denied
 globally or per-agent, sandboxing doesn’t bring it back.
 
-`tools.elevated` is an explicit escape hatch that runs `bash` on the host.
+`tools.elevated` is an explicit escape hatch that runs `exec` on the host.
 
 Debugging:
 - Use `clawdbot sandbox explain` to inspect effective sandbox mode, tool policy, and fix-it config keys.

docs/gateway/security.md

@@ -34,6 +34,15 @@ Clawdbot’s stance:
 - **Scope next:** decide where the bot is allowed to act (group allowlists + mention gating, tools, sandboxing, device permissions).
 - **Model last:** assume the model can be manipulated; design so manipulation has limited blast radius.
 
+## Plugins/extensions
+
+Plugins run **in-process** with the Gateway. Treat them as trusted code:
+
+- Only install plugins from sources you trust.
+- Prefer explicit `plugins.allow` allowlists.
+- Review plugin config before enabling.
+- Restart the Gateway after plugin changes.
+
 ## DM access model (pairing / allowlist / open / disabled)
 
 All current DM-capable providers support a DM policy (`dmPolicy` or `*.dm.policy`) that gates inbound DMs **before** the message is processed:
@@ -61,8 +70,9 @@ Clawdbot has two separate “who can trigger me?” layers:
 - **Group allowlist** (provider-specific): which groups/channels/guilds the bot will accept messages from at all.
   - Common patterns:
     - `whatsapp.groups`, `telegram.groups`, `imessage.groups`: per-group defaults like `requireMention`; when set, it also acts as a group allowlist (include `"*"` to keep allow-all behavior).
-    - `groupPolicy="allowlist"` + `groupAllowFrom`: restrict who can trigger the bot *inside* a group session (WhatsApp/Telegram/Signal/iMessage).
+    - `groupPolicy="allowlist"` + `groupAllowFrom`: restrict who can trigger the bot *inside* a group session (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams).
     - `discord.guilds` / `slack.channels`: per-surface allowlists + mention defaults.
+  - **Security note:** treat `dmPolicy="open"` and `groupPolicy="open"` as last-resort settings. They should be barely used; prefer pairing + allowlists unless you fully trust every member of the room.
 
 Details: [Configuration](/gateway/configuration) and [Groups](/concepts/groups)
 
@@ -175,7 +185,7 @@ Consider running your AI on a separate phone number from your personal one:
 
 You can already build a read-only profile by combining:
 - `agents.defaults.sandbox.workspaceAccess: "ro"` (or `"none"` for no workspace access)
-- tool allow/deny lists that block `write`, `edit`, `bash`, `process`, etc.
+- tool allow/deny lists that block `write`, `edit`, `apply_patch`, `exec`, `process`, etc.
 
 We may add a single `readOnlyMode` flag later to simplify this configuration.
 
@@ -194,10 +204,10 @@ single container/workspace.
 
 Also consider agent workspace access inside the sandbox:
 - `agents.defaults.sandbox.workspaceAccess: "none"` (default) keeps the agent workspace off-limits; tools run against a sandbox workspace under `~/.clawdbot/sandboxes`
-- `agents.defaults.sandbox.workspaceAccess: "ro"` mounts the agent workspace read-only at `/agent` (disables `write`/`edit`)
+- `agents.defaults.sandbox.workspaceAccess: "ro"` mounts the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`)
 - `agents.defaults.sandbox.workspaceAccess: "rw"` mounts the agent workspace read/write at `/workspace`
 
-Important: `tools.elevated` is the global baseline escape hatch that runs bash on the host. Keep `tools.elevated.allowFrom` tight and don’t enable it for strangers. You can further restrict elevated per agent via `agents.list[].tools.elevated`. See [Elevated Mode](/tools/elevated).
+Important: `tools.elevated` is the global baseline escape hatch that runs exec on the host. Keep `tools.elevated.allowFrom` tight and don’t enable it for strangers. You can further restrict elevated per agent via `agents.list[].tools.elevated`. See [Elevated Mode](/tools/elevated).
 
 ## Browser control risks
 
@@ -252,7 +262,7 @@ Common use cases:
         },
         tools: {
           allow: ["read"],
-          deny: ["write", "edit", "bash", "process", "browser"]
+          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"]
         }
       }
     ]
@@ -276,7 +286,7 @@ Common use cases:
         },
         tools: {
           allow: ["sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", "whatsapp", "telegram", "slack", "discord", "gateway"],
-          deny: ["read", "write", "edit", "bash", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
+          deny: ["read", "write", "edit", "apply_patch", "exec", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
         }
       }
     ]

docs/gateway/troubleshooting.md

@@ -339,8 +339,12 @@ sleep 1
 kill -9 <PID> # last resort
 ```
 
-**Fix 3: Check embedded gateway**
-Ensure the gateway relay was properly bundled. Run [`./scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh) and ensure Node is available (the script downloads a bundled runtime by default).
+**Fix 3: Check the CLI install**
+Ensure the global `clawdbot` CLI is installed and matches the app version:
+```bash
+clawdbot --version
+npm install -g clawdbot@<version>
+```
 
 ## Debug Mode
 

docs/install/bun.md

@@ -39,9 +39,10 @@ bun run vitest run
 ## pnpm patchedDependencies under Bun
 
 pnpm supports `package.json#pnpm.patchedDependencies` and records it in `pnpm-lock.yaml`.
-Bun does not support pnpm patches, so we apply them in `postinstall` when Bun is detected:
+Bun (and npm/yarn) do not support pnpm patches, so we apply them in `postinstall` when pnpm is **not** the installer:
 
-- [`scripts/postinstall.js`](https://github.com/clawdbot/clawdbot/blob/main/scripts/postinstall.js) runs only for Bun installs and applies every entry from `package.json#pnpm.patchedDependencies` into `node_modules/...` using `git apply` (idempotent).
+- [`scripts/postinstall.js`](https://github.com/clawdbot/clawdbot/blob/main/scripts/postinstall.js) detects the package manager via `npm_config_user_agent` and applies every entry from `package.json#pnpm.patchedDependencies` into `node_modules/...` using a built-in JS patcher (no `git`/system `patch` dependency).
+- Under pnpm, this fallback is skipped because pnpm already applies `patchedDependencies` itself.
 
 To add a new patch that works in both pnpm + Bun: