docs(changelog): mention Dockerfile Bun install (#284 )

Merge remote-tracking branch 'origin/main' into fix/dockerfile-install-bun
fix: install Bun in Dockerfile for build scripts
2026-01-06 15:02:27 +01:00 · 2026-01-06 15:00:54 +01:00 · 2026-01-06 09:40:27 +01:00
308 changed files with 3955 additions and 12673 deletions
@@ -6,9 +6,7 @@
 - Docs: `docs/` (images, queue, Pi config). Built output lives in `dist/`.

 ## Build, Test, and Development Commands
- Runtime baseline: Node **22+** (keep Node + Bun paths working).
 - Install deps: `pnpm install`
- Also supported: `bun install` (keep `pnpm-lock.yaml` + Bun patching in sync when touching deps/patches).
 - Prefer Bun for TypeScript execution (scripts, dev, tests): `bun <file.ts>` / `bunx <tool>`.
 - Run CLI in dev: `pnpm clawdbot ...` (bun) or `pnpm dev`.
 - Node remains supported for running built output (`dist/*`) and production installs.
@@ -34,17 +32,11 @@
 - Follow concise, action-oriented commit messages (e.g., `CLI: add verbose flag to send`).
 - Group related changes; avoid bundling unrelated refactors.
 - PRs should summarize scope, note testing performed, and mention any user-facing changes or new flags.
- PR review flow: when given a PR link, review via `gh pr view`/`gh pr diff` and do **not** change branches.
- PR merge flow: create a temp branch from `main`, merge the PR branch into it (prefer squash unless commit history is important; use rebase/merge when it is). Always try to merge the PR unless it’s truly difficult, then use another approach. If we squash, add the PR author as a co-contributor. Apply fixes, add changelog entry (include PR # + thanks), run full gate before the final commit, commit, merge back to `main`, delete the temp branch, and end on `main`.
- When working on a PR: add a changelog entry with the PR number and thank the contributor.
+- When working on a PR: add a changelog entry with the PR ID and thank the contributor.
 - When working on an issue: reference the issue in the changelog entry.
- When merging a PR: leave a PR comment that explains exactly what we did and include the SHA hashes.
+- When merging a PR: leave a PR comment that explains exactly what we did.
 - When merging a PR from a new contributor: add their avatar to the README “Thanks to all clawtributors” thumbnail list.

-### PR Workflow (Review vs Land)
- **Review mode (PR link only):** read `gh pr view/diff`; **do not** switch branches; **do not** change code.
- **Landing mode:** create an integration branch from `main`, bring in PR commits (**prefer rebase** for linear history; **merge allowed** when complexity/conflicts make it safer), apply fixes, add changelog (+ thanks + PR #), run full gate **locally before committing** (`pnpm lint && pnpm build && pnpm test`), commit, merge back to `main`, then `git switch main` (never stay on a topic branch after landing).
-
 ## 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.
@@ -5,37 +5,19 @@
 ## Unreleased

 ### Breaking
- **SECURITY (update ASAP):** inbound DMs are now **locked down by default** on Telegram/WhatsApp/Signal/iMessage/Discord/Slack.
-  - Previously, if you didn’t configure an allowlist, your bot could be **open to anyone** (especially discoverable Telegram bots).
-  - New default: DM pairing (`dmPolicy="pairing"` / `discord.dm.policy="pairing"` / `slack.dm.policy="pairing"`).
-  - To keep old “open to everyone” behavior: set `dmPolicy="open"` and include `"*"` in the relevant `allowFrom` (Discord/Slack: `discord.dm.allowFrom` / `slack.dm.allowFrom`).
-  - Approve requests via `clawdbot pairing list --provider <provider>` + `clawdbot pairing approve --provider <provider> <code>` (Telegram also supports `clawdbot telegram pairing ...`).
 - Timestamps in agent envelopes are now UTC (compact `YYYY-MM-DDTHH:mmZ`); removed `messages.timestampPrefix`. Add `agent.userTimezone` to tell the model the user’s local time (system prompt only).
 - Model config schema changes (auth profiles + model lists); doctor auto-migrates and the gateway rewrites legacy configs on startup.
 - Commands: gate all slash commands to authorized senders; add `/compact` to manually compact session context.
 - Groups: `whatsapp.groups`, `telegram.groups`, and `imessage.groups` now act as allowlists when set. Add `"*"` to keep allow-all behavior.

 ### Fixes
- Skills: harden skill installs with process-group timeouts, clearer timeout messaging, and logged rerun commands when installs fail.
- Heartbeat: default interval now 30m with a new default prompt + HEARTBEAT.md template.
- Onboarding: write auth profiles to the multi-agent path (`~/.clawdbot/agents/main/agent/`) so the gateway finds credentials on first startup. Thanks @minghinmatthewlam for PR #327.
- Docs: add missing `ui:install` setup step in the README. Thanks @hugobarauna for PR #300.
- Build: import tool-display JSON as a module instead of runtime file reads. Thanks @mukhtharcm for PR #312.
- Browser: fix `browser snapshot`/`browser act` timeouts under Bun by patching Playwright’s CDP WebSocket selection. Thanks @azade-c for PR #307.
- Browser: add `--browser-profile` flag and honor profile in tabs routes + browser tool. Thanks @jamesgroat for PR #324.
- Telegram: stop typing after tool results. Thanks @AbhisekBasu1 for PR #322.
 - Messages: stop defaulting ack reactions to 👀 when identity emoji is missing.
 - Auto-reply: require slash for control commands to avoid false triggers in normal text.
- Auto-reply: flag error payloads and improve Bun socket error messaging. Thanks @emanuelst for PR #331.
- Commands: unify native + text chat commands behind `commands.*` config (Discord/Slack/Telegram). Thanks @thewilloftheshadow for PR #275.
 - Auto-reply: treat steer during compaction as a follow-up, queued until compaction completes.
 - Auth: lock auth profile refreshes to avoid multi-instance OAuth logouts; keep credentials on refresh failure.
- Gateway/CLI: stop forcing localhost URL in remote mode so remote gateway config works. Thanks @oswalpalash for PR #293.
 - Onboarding: prompt immediately for OpenAI Codex redirect URL on remote/headless logins.
 - Configure: add OpenAI Codex (ChatGPT OAuth) auth choice (align with onboarding).
 - Doctor: suggest adding the workspace memory system when missing (opt-out via `--no-workspace-suggestions`).
- Doctor: normalize default workspace path to `~/clawd` (avoid `~/clawdbot`).
- Workspace: only create `BOOTSTRAP.md` for brand-new workspaces (don’t recreate after deletion).
 - Build: fix duplicate protocol export, align Codex OAuth options, and add proper-lockfile typings.
 - Build: install Bun in the Dockerfile so `pnpm build` can run Bun scripts. Thanks @loukotal for PR #284.
 - Typing indicators: stop typing once the reply dispatcher drains to prevent stuck typing across Discord/Telegram/WhatsApp.
@@ -59,7 +41,6 @@
 - TUI: migrate key handling to the updated pi-tui Key matcher API.
 - TUI: add `/elev` alias for `/elevated`.
 - Logging: redact sensitive tokens in verbose tool summaries by default (configurable patterns).
- macOS: keep app connection settings local in remote mode to avoid overwriting gateway config. Thanks @ngutman for PR #310.
 - macOS: prefer gateway config reads/writes in local mode (fall back to disk if the gateway is unavailable).
 - macOS: local gateway now connects via tailnet IP when bind mode is `tailnet`/`auto`.
 - macOS: Connections settings now use a custom sidebar to avoid toolbar toggle issues, with rounded styling and full-width row hit targets.
@@ -79,11 +60,9 @@
 - Control UI: let config-form enums select empty-string values. Thanks @sreekaransrinath for PR #268.
 - Control UI: scroll chat to bottom on initial load. Thanks @kiranjd for PR #274.
 - Control UI: add Chat focus mode toggle to collapse header + sidebar.
- Control UI: tighten focus mode spacing (reduce top padding, add comfortable compose inset).
 - Control UI: standardize UI build instructions on `bun run ui:*` (fallback supported).
 - Status: show runtime (docker/direct) and move shortcuts to `/help`.
 - Status: show model auth source (api-key/oauth).
- Status: fix zero token counters for Anthropic (Opus) sessions by normalizing usage fields and ignoring empty usage updates.
 - Block streaming: avoid splitting Markdown fenced blocks and reopen fences when forced to split.
 - Block streaming: preserve leading indentation in block replies (lists, indented fences).
 - Docs: document systemd lingering and logged-in session requirements on macOS/Windows.
@@ -92,8 +71,6 @@
 - Skills: emit MEDIA token after Nano Banana Pro image generation. Thanks @Iamadig for PR #271.
 - WhatsApp: set sender E.164 for direct chats so owner commands work in DMs.
 - Slack: keep auto-replies in the original thread when responding to thread messages. Thanks @scald for PR #251.
- Slack: send typing status updates via assistant threads. Thanks @thewilloftheshadow for PR #320.
- Slack: fix Slack provider startup under Bun by using a named import for Bolt `App`. Thanks @snopoke for PR #299.
 - Discord: surface missing-permission hints (muted/role overrides) when replies fail.
 - Discord: use channel IDs for DMs instead of user IDs. Thanks @VACInc for PR #261.
 - Docs: clarify Slack manifest scopes (current vs optional) with references. Thanks @jarvis-medmatic for PR #235.
@@ -106,18 +83,11 @@
 - Telegram: support media groups (multi-image messages). Thanks @obviyus for PR #220.
 - Telegram/WhatsApp: parse shared locations (pins, places, live) and expose structured ctx fields. Thanks @nachoiacovino for PR #194.
 - Auto-reply: block unauthorized `/reset` and infer WhatsApp senders from E.164 inputs.
- Auto-reply: reset corrupted Gemini sessions when function-call ordering breaks. Thanks @VACInc for PR #297.
 - Auto-reply: track compaction count in session status; verbose mode announces auto-compactions.
- Telegram: notify users when inbound media exceeds size limits. Thanks @jarvis-medmatic for PR #283.
 - Telegram: send GIF media as animations (auto-play) and improve filename sniffing.
 - Bash tool: inherit gateway PATH so Nix-provided tools resolve during commands. Thanks @joshp123 for PR #202.
- Delivery chunking: keep Markdown fenced code blocks valid when splitting long replies (close + reopen fences).
- Auth: prefer OAuth profiles over API keys during round-robin selection (prevents OAuth “lost after one message” when both are configured).
- Models: extend `clawdbot models` status output with a masked auth overview (profiles, env sources, and OAuth counts).

 ### Maintenance
- Agent: add `skipBootstrap` config option. Thanks @onutc for PR #292.
- UI: add favicon.ico derived from the macOS app icon. Thanks @jeffersonwarrior for PR #305.
 - Tooling: replace tsx with bun for TypeScript execution. Thanks @obviyus for PR #278.
 - Deps: bump pi-* stack, Slack SDK, discord-api-types, file-type, zod, and Biome.
 - Skills: add CodexBar model usage helper with macOS requirement metadata.
@@ -16,32 +16,24 @@
 </p>

 **Clawdbot** is a *personal AI assistant* you run on your own devices.
-It answers you on the providers you already use (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat), can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.
+It answers you on the surfaces you already use (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat), can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.

 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](https://docs.clawd.bot/getting-started) · Updating: [https://docs.clawd.bot/updating](https://docs.clawd.bot/updating) · Showcase: [https://docs.clawd.bot/showcase](https://docs.clawd.bot/showcase) · FAQ: [https://docs.clawd.bot/faq](https://docs.clawd.bot/faq) · Wizard: [https://docs.clawd.bot/wizard](https://docs.clawd.bot/wizard) · Nix: [https://github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [https://docs.clawd.bot/docker](https://docs.clawd.bot/docker) · Discord: [https://discord.gg/clawd](https://discord.gg/clawd)
+[Website](https://clawdbot.com) · [Docs](https://github.com/clawdbot/clawdbot/blob/main/docs/index.md) · Showcase: [https://github.com/clawdbot/clawdbot/blob/main/docs/showcase.md](https://github.com/clawdbot/clawdbot/blob/main/docs/showcase.md) · FAQ: [https://github.com/clawdbot/clawdbot/blob/main/docs/faq.md](https://github.com/clawdbot/clawdbot/blob/main/docs/faq.md) · Wizard: [https://github.com/clawdbot/clawdbot/blob/main/docs/wizard.md](https://github.com/clawdbot/clawdbot/blob/main/docs/wizard.md) · Nix: [https://github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [https://github.com/clawdbot/clawdbot/blob/main/docs/docker.md](https://github.com/clawdbot/clawdbot/blob/main/docs/docker.md) · Discord: [https://discord.gg/clawd](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, Windows, and Linux**.
 Works with npm, pnpm, or bun.
-New install? Start here: https://docs.clawd.bot/getting-started

 **Subscriptions (OAuth):**
 - **Anthropic** (Claude Pro/Max)
 - **OpenAI** (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).
-
-## Models (selection + auth)
-
- Models config + CLI: https://docs.clawd.bot/models
- Auth profile rotation (OAuth vs API keys) + fallbacks: https://docs.clawd.bot/model-failover
+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://github.com/clawdbot/clawdbot/blob/main/docs/onboarding.md).

 ## Recommended setup (from source)

-Do **not** download prebuilt binaries. Run from source.
-
-Prefer **Bun**. `pnpm` is also supported (see https://docs.clawd.bot/getting-started).
+Do **not** download prebuilt binaries. Build from source.

 ```bash
 # Clone this repo
@@ -49,23 +41,35 @@ git clone https://github.com/clawdbot/clawdbot.git
 cd clawdbot

 bun install
-bun run ui:install
-bun run ui:build
 bun run build
+bun run ui:build
 bun run clawdbot onboard
 ```

-Note: `bun run clawdbot ...` runs TypeScript directly. `bun run build` produces `dist/` for running via Node / the packaged `clawdbot` binary.
-
-## Quick start (TL;DR)
+## Quick start (from source)

 Runtime: **Node ≥22**.

-Full beginner guide (auth, pairing, providers): https://docs.clawd.bot/getting-started
+From source, **pnpm** is the default workflow. Bun is supported as an optional local workflow; see [`docs/bun.md`](docs/bun.md).

 ```bash
+# Install deps (no Bun lockfile)
+bun install --no-save
+
+# Build TypeScript
+bun run build
+
+# Build Control UI
+bun install --cwd ui --no-save
+bun run --cwd ui build
+
+# Recommended: run the onboarding wizard
 bun run clawdbot onboard

+# Link WhatsApp (stores creds in ~/.clawdbot/credentials)
+bun run clawdbot login
+
+# Start the gateway
 bun run clawdbot gateway --port 18789 --verbose

 # Dev loop (auto-reload on TS changes)
@@ -78,76 +82,51 @@ bun run clawdbot send --to +1234567890 --message "Hello from Clawdbot"
 bun run clawdbot agent --message "Ship checklist" --thinking high
 ```

-Upgrading? https://docs.clawd.bot/updating (and run `clawdbot doctor`).
+Upgrading? `clawdbot doctor`.

 If you run from source, prefer `bun run clawdbot …` or `pnpm clawdbot …` (not global `clawdbot`).

-## Security defaults (DM access)
-
-Clawdbot connects to real messaging surfaces. Treat inbound DMs as **untrusted input**.
-
-Full security guide: https://docs.clawd.bot/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.
- Approve with: `clawdbot pairing approve --provider <provider> <code>` (then the sender is added to a local allowlist store).
- Public inbound DMs require an explicit opt-in: set `dmPolicy="open"` and include `"*"` in the provider allowlist (`allowFrom` / `discord.dm.allowFrom` / `slack.dm.allowFrom`).
-
-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).
- **[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.
+- **[Local-first Gateway](https://github.com/clawdbot/clawdbot/blob/main/docs/gateway.md)** — single control plane for sessions, providers, tools, and events.
+- **[Multi-surface inbox](https://github.com/clawdbot/clawdbot/blob/main/docs/surface.md)** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat, macOS, iOS/Android.
+- **[Voice Wake](https://github.com/clawdbot/clawdbot/blob/main/docs/voicewake.md) + [Talk Mode](https://github.com/clawdbot/clawdbot/blob/main/docs/talk.md)** — always-on speech for macOS/iOS/Android with ElevenLabs.
+- **[Live Canvas](https://github.com/clawdbot/clawdbot/blob/main/docs/mac/canvas.md)** — agent-driven visual workspace with [A2UI](https://github.com/clawdbot/clawdbot/blob/main/docs/mac/canvas.md#canvas-a2ui).
+- **[First-class tools](https://github.com/clawdbot/clawdbot/blob/main/docs/tools.md)** — browser, canvas, nodes, cron, sessions, and Discord/Slack actions.
+- **[Companion apps](https://github.com/clawdbot/clawdbot/blob/main/docs/macos.md)** — macOS menu bar app + iOS/Android [nodes](https://github.com/clawdbot/clawdbot/blob/main/docs/nodes.md).
+- **[Onboarding](https://github.com/clawdbot/clawdbot/blob/main/docs/wizard.md) + [skills](https://github.com/clawdbot/clawdbot/blob/main/docs/skills.md)** — 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://github.com/clawdbot/clawdbot/blob/main/docs/gateway.md) with sessions, presence, config, cron, webhooks, [Control UI](https://github.com/clawdbot/clawdbot/blob/main/docs/web.md), and [Canvas host](https://github.com/clawdbot/clawdbot/blob/main/docs/mac/canvas.md#canvas-a2ui).
+- [CLI surface](https://github.com/clawdbot/clawdbot/blob/main/docs/agent-send.md): gateway, agent, send, [wizard](https://github.com/clawdbot/clawdbot/blob/main/docs/wizard.md), and [doctor](https://github.com/clawdbot/clawdbot/blob/main/docs/doctor.md).
+- [Pi agent runtime](https://github.com/clawdbot/clawdbot/blob/main/docs/agent.md) in RPC mode with tool streaming and block streaming.
+- [Session model](https://github.com/clawdbot/clawdbot/blob/main/docs/session.md): `main` for direct chats, group isolation, activation modes, queue modes, reply-back. Group rules: [Groups](https://github.com/clawdbot/clawdbot/blob/main/docs/groups.md).
+- [Media pipeline](https://github.com/clawdbot/clawdbot/blob/main/docs/images.md): images/audio/video, transcription hooks, size caps, temp file lifecycle. Audio details: [Audio](https://github.com/clawdbot/clawdbot/blob/main/docs/audio.md).

-### 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).
+### Surfaces + providers
+- [Providers](https://github.com/clawdbot/clawdbot/blob/main/docs/surface.md): [WhatsApp](https://github.com/clawdbot/clawdbot/blob/main/docs/whatsapp.md) (Baileys), [Telegram](https://github.com/clawdbot/clawdbot/blob/main/docs/telegram.md) (grammY), [Slack](https://github.com/clawdbot/clawdbot/blob/main/docs/slack.md) (Bolt), [Discord](https://github.com/clawdbot/clawdbot/blob/main/docs/discord.md) (discord.js), [Signal](https://github.com/clawdbot/clawdbot/blob/main/docs/signal.md) (signal-cli), [iMessage](https://github.com/clawdbot/clawdbot/blob/main/docs/imessage.md) (imsg), [WebChat](https://github.com/clawdbot/clawdbot/blob/main/docs/webchat.md).
+- [Group routing](https://github.com/clawdbot/clawdbot/blob/main/docs/group-messages.md): mention gating, reply tags, per-surface chunking and routing. Surface rules: [Surface routing](https://github.com/clawdbot/clawdbot/blob/main/docs/surface.md).

 ### 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 node mode](https://docs.clawd.bot/nodes): system.run/notify + canvas/camera exposure.
+- [macOS app](https://github.com/clawdbot/clawdbot/blob/main/docs/macos.md): menu bar control plane, [Voice Wake](https://github.com/clawdbot/clawdbot/blob/main/docs/voicewake.md)/PTT, [Talk Mode](https://github.com/clawdbot/clawdbot/blob/main/docs/talk.md) overlay, [WebChat](https://github.com/clawdbot/clawdbot/blob/main/docs/webchat.md), debug tools, [remote gateway](https://github.com/clawdbot/clawdbot/blob/main/docs/remote.md) control.
+- [iOS node](https://github.com/clawdbot/clawdbot/blob/main/docs/ios.md): [Canvas](https://github.com/clawdbot/clawdbot/blob/main/docs/mac/canvas.md), [Voice Wake](https://github.com/clawdbot/clawdbot/blob/main/docs/voicewake.md), [Talk Mode](https://github.com/clawdbot/clawdbot/blob/main/docs/talk.md), camera, screen recording, Bonjour pairing.
+- [Android node](https://github.com/clawdbot/clawdbot/blob/main/docs/android.md): [Canvas](https://github.com/clawdbot/clawdbot/blob/main/docs/mac/canvas.md), [Talk Mode](https://github.com/clawdbot/clawdbot/blob/main/docs/talk.md), camera, screen recording, optional SMS.
+- [macOS node mode](https://github.com/clawdbot/clawdbot/blob/main/docs/nodes.md): 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://github.com/clawdbot/clawdbot/blob/main/docs/browser.md): dedicated clawd Chrome/Chromium, snapshots, actions, uploads, profiles.
+- [Canvas](https://github.com/clawdbot/clawdbot/blob/main/docs/mac/canvas.md): [A2UI](https://github.com/clawdbot/clawdbot/blob/main/docs/mac/canvas.md#canvas-a2ui) push/reset, eval, snapshot.
+- [Nodes](https://github.com/clawdbot/clawdbot/blob/main/docs/nodes.md): camera snap/clip, screen record, [location.get](https://github.com/clawdbot/clawdbot/blob/main/docs/location-command.md), notifications.
+- [Cron + wakeups](https://github.com/clawdbot/clawdbot/blob/main/docs/cron.md); [webhooks](https://github.com/clawdbot/clawdbot/blob/main/docs/webhook.md); [Gmail Pub/Sub](https://github.com/clawdbot/clawdbot/blob/main/docs/gmail-pubsub.md).
+- [Skills platform](https://github.com/clawdbot/clawdbot/blob/main/docs/skills.md): bundled, managed, and workspace skills with install gating + UI.

 ### 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).
-
-#### Gateway service (optional)
-
-Install a supervised service (launchd/systemd/Scheduled Task):
-
-```bash
-clawdbot gateway install
-clawdbot gateway service-status
-```
-
-Aliases: `clawdbot service ...` or `clawdbot daemon ...`.
+- [Control UI](https://github.com/clawdbot/clawdbot/blob/main/docs/web.md) + [WebChat](https://github.com/clawdbot/clawdbot/blob/main/docs/webchat.md) served directly from the Gateway.
+- [Tailscale Serve/Funnel](https://github.com/clawdbot/clawdbot/blob/main/docs/tailscale.md) or [SSH tunnels](https://github.com/clawdbot/clawdbot/blob/main/docs/remote.md) with token/password auth.
+- [Nix mode](https://github.com/clawdbot/clawdbot/blob/main/docs/nix.md) for declarative config; [Docker](https://github.com/clawdbot/clawdbot/blob/main/docs/docker.md)-based installs.
+- [Doctor](https://github.com/clawdbot/clawdbot/blob/main/docs/doctor.md) migrations, [logging](https://github.com/clawdbot/clawdbot/blob/main/docs/logging.md).

 ## How it works (short)

@@ -169,12 +148,12 @@ 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.
- **[Nodes](https://docs.clawd.bot/nodes)** — Canvas, camera snap/clip, screen record, `location.get`, notifications, plus macOS‑only `system.run`/`system.notify`.
+- **[Gateway WebSocket network](https://github.com/clawdbot/clawdbot/blob/main/docs/architecture.md)** — single WS control plane for clients, tools, and events (plus ops: [Gateway runbook](https://github.com/clawdbot/clawdbot/blob/main/docs/gateway.md)).
+- **[Tailscale exposure](https://github.com/clawdbot/clawdbot/blob/main/docs/tailscale.md)** — Serve/Funnel for the Gateway dashboard + WS (remote access: [Remote](https://github.com/clawdbot/clawdbot/blob/main/docs/remote.md)).
+- **[Browser control](https://github.com/clawdbot/clawdbot/blob/main/docs/browser.md)** — clawd‑managed Chrome/Chromium with CDP control.
+- **[Canvas + A2UI](https://github.com/clawdbot/clawdbot/blob/main/docs/mac/canvas.md)** — agent‑driven visual workspace (A2UI host: [Canvas/A2UI](https://github.com/clawdbot/clawdbot/blob/main/docs/mac/canvas.md#canvas-a2ui)).
+- **[Voice Wake](https://github.com/clawdbot/clawdbot/blob/main/docs/voicewake.md) + [Talk Mode](https://github.com/clawdbot/clawdbot/blob/main/docs/talk.md)** — always‑on speech and continuous conversation.
+- **[Nodes](https://github.com/clawdbot/clawdbot/blob/main/docs/nodes.md)** — Canvas, camera snap/clip, screen record, `location.get`, notifications, plus macOS‑only `system.run`/`system.notify`.

 ## Tailscale access (Gateway dashboard)

@@ -190,7 +169,7 @@ 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://github.com/clawdbot/clawdbot/blob/main/docs/tailscale.md) · [Web surfaces](https://github.com/clawdbot/clawdbot/blob/main/docs/web.md)

 ## Remote Gateway (Linux is great)

@@ -200,7 +179,7 @@ It’s perfectly fine to run the Gateway on a small Linux instance. Clients (mac
 - **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.

-Details: [Remote access](https://docs.clawd.bot/remote) · [Nodes](https://docs.clawd.bot/nodes) · [Security](https://docs.clawd.bot/security)
+Details: [Remote access](https://github.com/clawdbot/clawdbot/blob/main/docs/remote.md) · [Nodes](https://github.com/clawdbot/clawdbot/blob/main/docs/nodes.md) · [Security](https://github.com/clawdbot/clawdbot/blob/main/docs/security.md)

 ## macOS permissions via the Gateway protocol

@@ -215,7 +194,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://github.com/clawdbot/clawdbot/blob/main/docs/nodes.md) · [macOS app](https://github.com/clawdbot/clawdbot/blob/main/docs/macos.md) · [Gateway protocol](https://github.com/clawdbot/clawdbot/blob/main/docs/architecture.md)

 ## Agent to Agent (sessions_* tools)

@@ -224,7 +203,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://github.com/clawdbot/clawdbot/blob/main/docs/session-tool.md)

 ## Skills registry (ClawdHub)

@@ -270,13 +249,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://github.com/clawdbot/clawdbot/blob/main/docs/ios.md).

 ### 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://github.com/clawdbot/clawdbot/blob/main/docs/android.md).

 ## Agent workspace + skills

@@ -296,23 +275,23 @@ Minimal `~/.clawdbot/clawdbot.json` (model + defaults):
 }
 ```

-[Full configuration reference (all keys + examples).](https://docs.clawd.bot/configuration)
+[Full configuration reference (all keys + examples).](https://github.com/clawdbot/clawdbot/blob/main/docs/configuration.md)

 ## Security model (important)

 - **Default:** tools run on the host for the **main** session, so the agent has full access when it’s just you.
 - **Group/channel safety:** set `agent.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`.
+- **Sandbox defaults:** allowlist `bash`, `process`, `read`, `write`, `edit`; 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://github.com/clawdbot/clawdbot/blob/main/docs/security.md) · [Docker + sandboxing](https://github.com/clawdbot/clawdbot/blob/main/docs/docker.md) · [Sandbox config](https://github.com/clawdbot/clawdbot/blob/main/docs/configuration.md)

-### [WhatsApp](https://docs.clawd.bot/whatsapp)
+### [WhatsApp](https://github.com/clawdbot/clawdbot/blob/main/docs/whatsapp.md)

 - Link the device: `pnpm clawdbot 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://github.com/clawdbot/clawdbot/blob/main/docs/telegram.md)

 - 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.
@@ -325,14 +304,14 @@ Details: [Security guide](https://docs.clawd.bot/security) · [Docker + sandboxi
 }
 ```

-### [Slack](https://docs.clawd.bot/slack)
+### [Slack](https://github.com/clawdbot/clawdbot/blob/main/docs/slack.md)

 - Set `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` (or `slack.botToken` + `slack.appToken`).

-### [Discord](https://docs.clawd.bot/discord)
+### [Discord](https://github.com/clawdbot/clawdbot/blob/main/docs/discord.md)

 - 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.
+- Optional: set `discord.slashCommand`, `discord.dm.allowFrom`, `discord.guilds`, or `discord.mediaMaxMb` as needed.

 ```json5
 {
@@ -342,16 +321,16 @@ Details: [Security guide](https://docs.clawd.bot/security) · [Docker + sandboxi
 }
 ```

-### [Signal](https://docs.clawd.bot/signal)
+### [Signal](https://github.com/clawdbot/clawdbot/blob/main/docs/signal.md)

 - Requires `signal-cli` and a `signal` config section.

-### [iMessage](https://docs.clawd.bot/imessage)
+### [iMessage](https://github.com/clawdbot/clawdbot/blob/main/docs/imessage.md)

 - 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://github.com/clawdbot/clawdbot/blob/main/docs/webchat.md)

 - Uses the Gateway WebSocket; no separate WebChat port/config.

@@ -370,69 +349,69 @@ Browser control (optional):
 ## Docs

 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)
- [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](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)
+- [Start with the docs index for navigation and “what’s where.”](https://github.com/clawdbot/clawdbot/blob/main/docs/index.md)
+- [Read the architecture overview for the gateway + protocol model.](https://github.com/clawdbot/clawdbot/blob/main/docs/architecture.md)
+- [Use the full configuration reference when you need every key and example.](https://github.com/clawdbot/clawdbot/blob/main/docs/configuration.md)
+- [Run the Gateway by the book with the operational runbook.](https://github.com/clawdbot/clawdbot/blob/main/docs/gateway.md)
+- [Learn how the Control UI/Web surfaces work and how to expose them safely.](https://github.com/clawdbot/clawdbot/blob/main/docs/web.md)
+- [Understand remote access over SSH tunnels or tailnets.](https://github.com/clawdbot/clawdbot/blob/main/docs/remote.md)
+- [Follow the onboarding wizard flow for a guided setup.](https://github.com/clawdbot/clawdbot/blob/main/docs/wizard.md)
+- [Wire external triggers via the webhook surface.](https://github.com/clawdbot/clawdbot/blob/main/docs/webhook.md)
+- [Set up Gmail Pub/Sub triggers.](https://github.com/clawdbot/clawdbot/blob/main/docs/gmail-pubsub.md)
+- [Learn the macOS menu bar companion details.](https://github.com/clawdbot/clawdbot/blob/main/docs/mac/menu-bar.md)
+- [Platform guides: Windows](https://github.com/clawdbot/clawdbot/blob/main/docs/windows.md), [Linux](https://github.com/clawdbot/clawdbot/blob/main/docs/linux.md), [macOS](https://github.com/clawdbot/clawdbot/blob/main/docs/macos.md), [iOS](https://github.com/clawdbot/clawdbot/blob/main/docs/ios.md), [Android](https://github.com/clawdbot/clawdbot/blob/main/docs/android.md)
+- [Debug common failures with the troubleshooting guide.](https://github.com/clawdbot/clawdbot/blob/main/docs/troubleshooting.md)
+- [Review security guidance before exposing anything.](https://github.com/clawdbot/clawdbot/blob/main/docs/security.md)

 ## Advanced docs (discovery + control)

- [Discovery + transports](https://docs.clawd.bot/discovery)
- [Bonjour/mDNS](https://docs.clawd.bot/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)
+- [Discovery + transports](https://github.com/clawdbot/clawdbot/blob/main/docs/discovery.md)
+- [Bonjour/mDNS](https://github.com/clawdbot/clawdbot/blob/main/docs/bonjour.md)
+- [Gateway pairing](https://github.com/clawdbot/clawdbot/blob/main/docs/gateway/pairing.md)
+- [Remote gateway README](https://github.com/clawdbot/clawdbot/blob/main/docs/remote-gateway-readme.md)
+- [Control UI](https://github.com/clawdbot/clawdbot/blob/main/docs/control-ui.md)
+- [Dashboard](https://github.com/clawdbot/clawdbot/blob/main/docs/dashboard.md)

 ## 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)
- [Logging](https://docs.clawd.bot/logging)
+- [Health checks](https://github.com/clawdbot/clawdbot/blob/main/docs/health.md)
+- [Gateway lock](https://github.com/clawdbot/clawdbot/blob/main/docs/gateway-lock.md)
+- [Background process](https://github.com/clawdbot/clawdbot/blob/main/docs/background-process.md)
+- [Browser troubleshooting (Linux)](https://github.com/clawdbot/clawdbot/blob/main/docs/browser-linux-troubleshooting.md)
+- [Logging](https://github.com/clawdbot/clawdbot/blob/main/docs/logging.md)

 ## 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://github.com/clawdbot/clawdbot/blob/main/docs/agent-loop.md)
+- [Presence](https://github.com/clawdbot/clawdbot/blob/main/docs/presence.md)
+- [TypeBox schemas](https://github.com/clawdbot/clawdbot/blob/main/docs/typebox.md)
+- [RPC adapters](https://github.com/clawdbot/clawdbot/blob/main/docs/rpc.md)
+- [Queue](https://github.com/clawdbot/clawdbot/blob/main/docs/queue.md)

 ## 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://github.com/clawdbot/clawdbot/blob/main/docs/skills-config.md)
+- [Default AGENTS](https://github.com/clawdbot/clawdbot/blob/main/docs/AGENTS.default.md)
+- [Templates: AGENTS](https://github.com/clawdbot/clawdbot/blob/main/docs/templates/AGENTS.md)
+- [Templates: BOOTSTRAP](https://github.com/clawdbot/clawdbot/blob/main/docs/templates/BOOTSTRAP.md)
+- [Templates: IDENTITY](https://github.com/clawdbot/clawdbot/blob/main/docs/templates/IDENTITY.md)
+- [Templates: SOUL](https://github.com/clawdbot/clawdbot/blob/main/docs/templates/SOUL.md)
+- [Templates: TOOLS](https://github.com/clawdbot/clawdbot/blob/main/docs/templates/TOOLS.md)
+- [Templates: USER](https://github.com/clawdbot/clawdbot/blob/main/docs/templates/USER.md)

 ## 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 app](https://docs.clawd.bot/windows)
- [Linux app](https://docs.clawd.bot/linux)
+- [macOS dev setup](https://github.com/clawdbot/clawdbot/blob/main/docs/mac/dev-setup.md)
+- [macOS menu bar](https://github.com/clawdbot/clawdbot/blob/main/docs/mac/menu-bar.md)
+- [macOS voice wake](https://github.com/clawdbot/clawdbot/blob/main/docs/mac/voicewake.md)
+- [iOS node](https://github.com/clawdbot/clawdbot/blob/main/docs/ios.md)
+- [Android node](https://github.com/clawdbot/clawdbot/blob/main/docs/android.md)
+- [Windows app](https://github.com/clawdbot/clawdbot/blob/main/docs/windows.md)
+- [Linux app](https://github.com/clawdbot/clawdbot/blob/main/docs/linux.md)

 ## Email hooks (Gmail)

-[Gmail Pub/Sub wiring (gcloud + gogcli), hook tokens, and auto-watch behavior are documented here.](https://docs.clawd.bot/gmail-pubsub)
+[Gmail Pub/Sub wiring (gcloud + gogcli), hook tokens, and auto-watch behavior are documented here.](https://github.com/clawdbot/clawdbot/blob/main/docs/gmail-pubsub.md)

 Gateway auto-starts the watcher when `hooks.enabled=true` and `hooks.gmail.account` is set; `clawdbot hooks gmail run` is the manual daemon wrapper if you don’t want auto-start.

@@ -463,6 +442,5 @@ Thanks to all clawtributors:
  <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/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/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/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/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/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/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/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/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/djangonavarro220"><img src="https://avatars.githubusercontent.com/u/251162586?v=4&s=48" width="48" height="48" alt="djangonavarro220" title="djangonavarro220"/></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/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/adamgall"><img src="https://avatars.githubusercontent.com/u/706929?v=4&s=48" width="48" height="48" alt="adamgall" title="adamgall"/></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/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/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/regenrek"><img src="https://avatars.githubusercontent.com/u/5182020?v=4&s=48" width="48" height="48" alt="regenrek" title="regenrek"/></a> <a href="https://github.com/tobiasbischoff"><img src="https://avatars.githubusercontent.com/u/711564?v=4&s=48" width="48" height="48" alt="tobiasbischoff" title="tobiasbischoff"/></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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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>
 </p>
@@ -416,8 +416,7 @@ final class AppState {
            : nil

        Task { @MainActor in
-            // Keep app-only connection settings local to avoid overwriting remote gateway config.
-            var root = ClawdbotConfigFile.loadDict()
+            var root = await ConfigStore.load()
            var gateway = root["gateway"] as? [String: Any] ?? [:]
            var changed = false

@@ -447,12 +446,8 @@ final class AppState {
            }

            guard changed else { return }
-            if gateway.isEmpty {
-                root.removeValue(forKey: "gateway")
-            } else {
-                root["gateway"] = gateway
-            }
-            ClawdbotConfigFile.saveDict(root)
+            root["gateway"] = gateway
+            try? await ConfigStore.save(root)
        }
    }

@@ -187,7 +187,7 @@ actor BridgeServer {
                thinking: "low",
                deliver: false,
                to: nil,
-                provider: .last))
+                channel: .last))

        case "agent.request":
            guard let json = evt.payloadJSON, let data = json.data(using: .utf8) else {
@@ -205,7 +205,7 @@ actor BridgeServer {
                ?? "node-\(nodeId)"
            let thinking = link.thinking?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
            let to = link.to?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
-            let provider = GatewayAgentProvider(raw: link.channel)
+            let channel = GatewayAgentChannel(raw: link.channel)

            _ = await GatewayConnection.shared.sendAgent(GatewayAgentInvocation(
                message: message,
@@ -213,7 +213,7 @@ actor BridgeServer {
                thinking: thinking,
                deliver: link.deliver,
                to: to,
-                provider: provider))
+                channel: channel))

        default:
            break
@@ -79,15 +79,14 @@ final class CanvasA2UIActionMessageHandler: NSObject, WKScriptMessageHandler {
                GatewayProcessManager.shared.setActive(true)
            }

-            let result = await GatewayConnection.shared.sendAgent(
-                GatewayAgentInvocation(
-                    message: text,
-                    sessionKey: self.sessionKey,
-                    thinking: "low",
-                    deliver: false,
-                    to: nil,
-                    provider: .last,
-                    idempotencyKey: actionId))
+            let result = await GatewayConnection.shared.sendAgent(GatewayAgentInvocation(
+                message: text,
+                sessionKey: self.sessionKey,
+                thinking: "low",
+                deliver: false,
+                to: nil,
+                channel: .last,
+                idempotencyKey: actionId))

            await MainActor.run {
                guard let webView else { return }
@@ -33,13 +33,13 @@ extension CronJobEditor {
        case let .systemEvent(text):
            self.payloadKind = .systemEvent
            self.systemEventText = text
-        case let .agentTurn(message, thinking, timeoutSeconds, deliver, provider, to, bestEffortDeliver):
+        case let .agentTurn(message, thinking, timeoutSeconds, deliver, channel, to, bestEffortDeliver):
            self.payloadKind = .agentTurn
            self.agentMessage = message
            self.thinking = thinking ?? ""
            self.timeoutSeconds = timeoutSeconds.map(String.init) ?? ""
            self.deliver = deliver ?? false
-            self.provider = GatewayAgentProvider(raw: provider)
+            self.channel = GatewayAgentChannel(raw: channel)
            self.to = to ?? ""
            self.bestEffortDeliver = bestEffortDeliver ?? false
        }
@@ -166,7 +166,7 @@ extension CronJobEditor {
        if let n = Int(self.timeoutSeconds), n > 0 { payload["timeoutSeconds"] = n }
        payload["deliver"] = self.deliver
        if self.deliver {
-            payload["provider"] = self.provider.rawValue
+            payload["channel"] = self.channel.rawValue
            let to = self.to.trimmingCharacters(in: .whitespacesAndNewlines)
            if !to.isEmpty { payload["to"] = to }
            payload["bestEffortDeliver"] = self.bestEffortDeliver
@@ -13,7 +13,7 @@ extension CronJobEditor {
        self.payloadKind = .agentTurn
        self.agentMessage = "Run diagnostic"
        self.deliver = true
-        self.provider = .last
+        self.channel = .last
        self.to = "+15551230000"
        self.thinking = "low"
        self.timeoutSeconds = "90"
@@ -17,7 +17,7 @@ struct CronJobEditor: View {
    static let scheduleKindNote =
        "“At” runs once, “Every” repeats with a duration, “Cron” uses a 5-field Unix expression."
    static let isolatedPayloadNote =
-        "Isolated jobs always run an agent turn. The result can be delivered to a provider, "
+        "Isolated jobs always run an agent turn. The result can be delivered to a surface, "
            + "and a short summary is posted back to your main chat."
    static let mainPayloadNote =
        "System events are injected into the current main session. Agent turns require an isolated session target."
@@ -42,7 +42,7 @@ struct CronJobEditor: View {
    @State var systemEventText: String = ""
    @State var agentMessage: String = ""
    @State var deliver: Bool = false
-    @State var provider: GatewayAgentProvider = .last
+    @State var channel: GatewayAgentChannel = .last
    @State var to: String = ""
    @State var thinking: String = ""
    @State var timeoutSeconds: String = ""
@@ -309,7 +309,7 @@ struct CronJobEditor: View {
                }
                GridRow {
                    self.gridLabel("Deliver")
-                    Toggle("Deliver result to a provider", isOn: self.$deliver)
+                    Toggle("Deliver result to a surface", isOn: self.$deliver)
                        .toggleStyle(.switch)
                }
            }
@@ -317,15 +317,15 @@ struct CronJobEditor: View {
            if self.deliver {
                Grid(alignment: .leadingFirstTextBaseline, horizontalSpacing: 14, verticalSpacing: 10) {
                    GridRow {
-                        self.gridLabel("Provider")
-                        Picker("", selection: self.$provider) {
-                            Text("last").tag(GatewayAgentProvider.last)
-                            Text("whatsapp").tag(GatewayAgentProvider.whatsapp)
-                            Text("telegram").tag(GatewayAgentProvider.telegram)
-                            Text("discord").tag(GatewayAgentProvider.discord)
-                            Text("slack").tag(GatewayAgentProvider.slack)
-                            Text("signal").tag(GatewayAgentProvider.signal)
-                            Text("imessage").tag(GatewayAgentProvider.imessage)
+                        self.gridLabel("Channel")
+                        Picker("", selection: self.$channel) {
+                            Text("last").tag(GatewayAgentChannel.last)
+                            Text("whatsapp").tag(GatewayAgentChannel.whatsapp)
+                            Text("telegram").tag(GatewayAgentChannel.telegram)
+                            Text("discord").tag(GatewayAgentChannel.discord)
+                            Text("slack").tag(GatewayAgentChannel.slack)
+                            Text("signal").tag(GatewayAgentChannel.signal)
+                            Text("imessage").tag(GatewayAgentChannel.imessage)
                        }
                        .labelsHidden()
                        .pickerStyle(.segmented)
@@ -74,12 +74,12 @@ enum CronPayload: Codable, Equatable {
        thinking: String?,
        timeoutSeconds: Int?,
        deliver: Bool?,
-        provider: String?,
+        channel: String?,
        to: String?,
        bestEffortDeliver: Bool?)

    enum CodingKeys: String, CodingKey {
-        case kind, text, message, thinking, timeoutSeconds, deliver, provider, to, bestEffortDeliver
+        case kind, text, message, thinking, timeoutSeconds, deliver, channel, to, bestEffortDeliver
    }

    var kind: String {
@@ -101,7 +101,7 @@ enum CronPayload: Codable, Equatable {
                thinking: container.decodeIfPresent(String.self, forKey: .thinking),
                timeoutSeconds: container.decodeIfPresent(Int.self, forKey: .timeoutSeconds),
                deliver: container.decodeIfPresent(Bool.self, forKey: .deliver),
-                provider: container.decodeIfPresent(String.self, forKey: .provider),
+                channel: container.decodeIfPresent(String.self, forKey: .channel),
                to: container.decodeIfPresent(String.self, forKey: .to),
                bestEffortDeliver: container.decodeIfPresent(Bool.self, forKey: .bestEffortDeliver))
        default:
@@ -118,12 +118,12 @@ enum CronPayload: Codable, Equatable {
        switch self {
        case let .systemEvent(text):
            try container.encode(text, forKey: .text)
-        case let .agentTurn(message, thinking, timeoutSeconds, deliver, provider, to, bestEffortDeliver):
+        case let .agentTurn(message, thinking, timeoutSeconds, deliver, channel, to, bestEffortDeliver):
            try container.encode(message, forKey: .message)
            try container.encodeIfPresent(thinking, forKey: .thinking)
            try container.encodeIfPresent(timeoutSeconds, forKey: .timeoutSeconds)
            try container.encodeIfPresent(deliver, forKey: .deliver)
-            try container.encodeIfPresent(provider, forKey: .provider)
+            try container.encodeIfPresent(channel, forKey: .channel)
            try container.encodeIfPresent(to, forKey: .to)
            try container.encodeIfPresent(bestEffortDeliver, forKey: .bestEffortDeliver)
        }
@@ -206,7 +206,7 @@ extension CronSettings {
                Text(text)
                    .font(.callout)
                    .textSelection(.enabled)
-            case let .agentTurn(message, thinking, timeoutSeconds, deliver, provider, to, _):
+            case let .agentTurn(message, thinking, timeoutSeconds, deliver, channel, to, _):
                VStack(alignment: .leading, spacing: 4) {
                    Text(message)
                        .font(.callout)
@@ -216,7 +216,7 @@ extension CronSettings {
                        if let timeoutSeconds { StatusPill(text: "\(timeoutSeconds)s", tint: .secondary) }
                        if deliver ?? false {
                            StatusPill(text: "deliver", tint: .secondary)
-                            if let provider, !provider.isEmpty { StatusPill(text: provider, tint: .secondary) }
+                            if let channel, !channel.isEmpty { StatusPill(text: channel, tint: .secondary) }
                            if let to, !to.isEmpty { StatusPill(text: to, tint: .secondary) }
                        }
                    }
@@ -20,7 +20,7 @@ struct CronSettings_Previews: PreviewProvider {
                    thinking: "low",
                    timeoutSeconds: 600,
                    deliver: true,
-                    provider: "last",
+                    channel: "last",
                    to: nil,
                    bestEffortDeliver: true),
                isolation: CronIsolation(postToMainPrefix: "Cron"),
@@ -72,7 +72,7 @@ extension CronSettings {
                thinking: "low",
                timeoutSeconds: 120,
                deliver: true,
-                provider: "whatsapp",
+                channel: "whatsapp",
                to: "+15551234567",
                bestEffortDeliver: true),
            isolation: CronIsolation(postToMainPrefix: "[cron] "),
@@ -59,7 +59,7 @@ final class DeepLinkHandler {
        }

        do {
-            let provider = GatewayAgentProvider(raw: link.channel)
+            let channel = GatewayAgentChannel(raw: link.channel)
            let explicitSessionKey = link.sessionKey?
                .trimmingCharacters(in: .whitespacesAndNewlines)
                .nonEmpty
@@ -72,9 +72,9 @@ final class DeepLinkHandler {
                message: messagePreview,
                sessionKey: resolvedSessionKey,
                thinking: link.thinking?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty,
-                deliver: provider.shouldDeliver(link.deliver),
+                deliver: channel.shouldDeliver(link.deliver),
                to: link.to?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty,
-                provider: provider,
+                channel: channel,
                timeoutSeconds: link.timeoutSeconds,
                idempotencyKey: UUID().uuidString)

@@ -5,7 +5,7 @@ import OSLog

 private let gatewayConnectionLogger = Logger(subsystem: "com.clawdbot", category: "gateway.connection")

-enum GatewayAgentProvider: String, Codable, CaseIterable, Sendable {
+enum GatewayAgentChannel: String, Codable, CaseIterable, Sendable {
    case last
    case whatsapp
    case telegram
@@ -17,7 +17,7 @@ enum GatewayAgentProvider: String, Codable, CaseIterable, Sendable {

    init(raw: String?) {
        let normalized = (raw ?? "").trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
-        self = GatewayAgentProvider(rawValue: normalized) ?? .last
+        self = GatewayAgentChannel(rawValue: normalized) ?? .last
    }

    var isDeliverable: Bool { self != .webchat }
@@ -31,7 +31,7 @@ struct GatewayAgentInvocation: Sendable {
    var thinking: String?
    var deliver: Bool = false
    var to: String?
-    var provider: GatewayAgentProvider = .last
+    var channel: GatewayAgentChannel = .last
    var timeoutSeconds: Int?
    var idempotencyKey: String = UUID().uuidString
 }
@@ -368,7 +368,7 @@ extension GatewayConnection {
            "thinking": AnyCodable(invocation.thinking ?? "default"),
            "deliver": AnyCodable(invocation.deliver),
            "to": AnyCodable(invocation.to ?? ""),
-            "provider": AnyCodable(invocation.provider.rawValue),
+            "channel": AnyCodable(invocation.channel.rawValue),
            "idempotencyKey": AnyCodable(invocation.idempotencyKey),
        ]
        if let timeout = invocation.timeoutSeconds {
@@ -389,7 +389,7 @@ extension GatewayConnection {
        sessionKey: String,
        deliver: Bool,
        to: String?,
-        provider: GatewayAgentProvider = .last,
+        channel: GatewayAgentChannel = .last,
        timeoutSeconds: Int? = nil,
        idempotencyKey: String = UUID().uuidString) async -> (ok: Bool, error: String?)
    {
@@ -399,7 +399,7 @@ extension GatewayConnection {
            thinking: thinking,
            deliver: deliver,
            to: to,
-            provider: provider,
+            channel: channel,
            timeoutSeconds: timeoutSeconds,
            idempotencyKey: idempotencyKey))
    }
@@ -9,7 +9,7 @@ struct GatewaySessionDefaultsRecord: Codable {
 struct GatewaySessionEntryRecord: Codable {
    let key: String
    let displayName: String?
-    let provider: String?
+    let surface: String?
    let subject: String?
    let room: String?
    let space: String?
@@ -71,7 +71,7 @@ struct SessionRow: Identifiable {
    let key: String
    let kind: SessionKind
    let displayName: String?
-    let provider: String?
+    let surface: String?
    let subject: String?
    let room: String?
    let space: String?
@@ -141,7 +141,7 @@ extension SessionRow {
                key: "user@example.com",
                kind: .direct,
                displayName: nil,
-                provider: nil,
+                surface: nil,
                subject: nil,
                room: nil,
                space: nil,
@@ -158,7 +158,7 @@ extension SessionRow {
                key: "discord:channel:release-squad",
                kind: .group,
                displayName: "discord:#release-squad",
-                provider: "discord",
+                surface: "discord",
                subject: nil,
                room: "#release-squad",
                space: nil,
@@ -175,7 +175,7 @@ extension SessionRow {
                key: "global",
                kind: .global,
                displayName: nil,
-                provider: nil,
+                surface: nil,
                subject: nil,
                room: nil,
                space: nil,
@@ -298,7 +298,7 @@ enum SessionLoader {
                key: entry.key,
                kind: SessionKind.from(key: entry.key),
                displayName: entry.displayName,
-                provider: entry.provider,
+                surface: entry.surface,
                subject: entry.subject,
                room: entry.room,
                space: entry.space,
@@ -37,7 +37,7 @@ enum VoiceWakeForwarder {
        var thinking: String = "low"
        var deliver: Bool = true
        var to: String?
-        var provider: GatewayAgentProvider = .last
+        var channel: GatewayAgentChannel = .last
    }

    @discardableResult
@@ -46,14 +46,14 @@ enum VoiceWakeForwarder {
        options: ForwardOptions = ForwardOptions()) async -> Result<Void, VoiceWakeForwardError>
    {
        let payload = Self.prefixedTranscript(transcript)
-        let deliver = options.provider.shouldDeliver(options.deliver)
+        let deliver = options.channel.shouldDeliver(options.deliver)
        let result = await GatewayConnection.shared.sendAgent(GatewayAgentInvocation(
            message: payload,
            sessionKey: options.sessionKey,
            thinking: options.thinking,
            deliver: deliver,
            to: options.to,
-            provider: options.provider))
+            channel: options.channel))

        if result.ok {
            self.logger.info("voice wake forward ok")
@@ -342,7 +342,6 @@ public struct SendParams: Codable, Sendable {
    public let mediaurl: String?
    public let gifplayback: Bool?
    public let provider: String?
-    public let accountid: String?
    public let idempotencykey: String

    public init(
@@ -351,7 +350,6 @@ public struct SendParams: Codable, Sendable {
        mediaurl: String?,
        gifplayback: Bool?,
        provider: String?,
-        accountid: String?,
        idempotencykey: String
    ) {
        self.to = to
@@ -359,7 +357,6 @@ public struct SendParams: Codable, Sendable {
        self.mediaurl = mediaurl
        self.gifplayback = gifplayback
        self.provider = provider
-        self.accountid = accountid
        self.idempotencykey = idempotencykey
    }
    private enum CodingKeys: String, CodingKey {
@@ -368,7 +365,6 @@ public struct SendParams: Codable, Sendable {
        case mediaurl = "mediaUrl"
        case gifplayback = "gifPlayback"
        case provider
-        case accountid = "accountId"
        case idempotencykey = "idempotencyKey"
    }
 }
@@ -380,7 +376,6 @@ public struct PollParams: Codable, Sendable {
    public let maxselections: Int?
    public let durationhours: Int?
    public let provider: String?
-    public let accountid: String?
    public let idempotencykey: String

    public init(
@@ -390,7 +385,6 @@ public struct PollParams: Codable, Sendable {
        maxselections: Int?,
        durationhours: Int?,
        provider: String?,
-        accountid: String?,
        idempotencykey: String
    ) {
        self.to = to
@@ -399,7 +393,6 @@ public struct PollParams: Codable, Sendable {
        self.maxselections = maxselections
        self.durationhours = durationhours
        self.provider = provider
-        self.accountid = accountid
        self.idempotencykey = idempotencykey
    }
    private enum CodingKeys: String, CodingKey {
@@ -409,7 +402,6 @@ public struct PollParams: Codable, Sendable {
        case maxselections = "maxSelections"
        case durationhours = "durationHours"
        case provider
-        case accountid = "accountId"
        case idempotencykey = "idempotencyKey"
    }
 }
@@ -421,7 +413,7 @@ public struct AgentParams: Codable, Sendable {
    public let sessionkey: String?
    public let thinking: String?
    public let deliver: Bool?
-    public let provider: String?
+    public let channel: String?
    public let timeout: Int?
    public let lane: String?
    public let extrasystemprompt: String?
@@ -434,7 +426,7 @@ public struct AgentParams: Codable, Sendable {
        sessionkey: String?,
        thinking: String?,
        deliver: Bool?,
-        provider: String?,
+        channel: String?,
        timeout: Int?,
        lane: String?,
        extrasystemprompt: String?,
@@ -446,7 +438,7 @@ public struct AgentParams: Codable, Sendable {
        self.sessionkey = sessionkey
        self.thinking = thinking
        self.deliver = deliver
-        self.provider = provider
+        self.channel = channel
        self.timeout = timeout
        self.lane = lane
        self.extrasystemprompt = extrasystemprompt
@@ -459,7 +451,7 @@ public struct AgentParams: Codable, Sendable {
        case sessionkey = "sessionKey"
        case thinking
        case deliver
-        case provider
+        case channel
        case timeout
        case lane
        case extrasystemprompt = "extraSystemPrompt"
@@ -1033,41 +1025,33 @@ public struct WebLoginStartParams: Codable, Sendable {
    public let force: Bool?
    public let timeoutms: Int?
    public let verbose: Bool?
-    public let accountid: String?

    public init(
        force: Bool?,
        timeoutms: Int?,
-        verbose: Bool?,
-        accountid: String?
+        verbose: Bool?
    ) {
        self.force = force
        self.timeoutms = timeoutms
        self.verbose = verbose
-        self.accountid = accountid
    }
    private enum CodingKeys: String, CodingKey {
        case force
        case timeoutms = "timeoutMs"
        case verbose
-        case accountid = "accountId"
    }
 }

 public struct WebLoginWaitParams: Codable, Sendable {
    public let timeoutms: Int?
-    public let accountid: String?

    public init(
-        timeoutms: Int?,
-        accountid: String?
+        timeoutms: Int?
    ) {
        self.timeoutms = timeoutms
-        self.accountid = accountid
    }
    private enum CodingKeys: String, CodingKey {
        case timeoutms = "timeoutMs"
-        case accountid = "accountId"
    }
 }

@@ -83,7 +83,7 @@ git commit -m "Add Clawd workspace"
 ## What Clawdbot Does
 - Runs WhatsApp gateway + Pi coding agent so the assistant can read/write chats, fetch context, and run skills via the host Mac.
 - macOS app manages permissions (screen recording, notifications, microphone) and exposes the `clawdbot` CLI via its bundled binary.
- Direct chats collapse into the agent's `main` session by default; groups stay isolated as `agent:<agentId>:<provider>:group:<id>` (rooms/channels: `agent:<agentId>:<provider>:channel:<id>`); heartbeats keep background tasks alive.
+- Direct chats collapse into the shared `main` session by default; groups stay isolated as `surface:group:<id>` (rooms: `surface:channel:<id>`); heartbeats keep background tasks alive.

 ## Core Skills (enable in Settings → Skills)
 - **mcporter** — Tool server runtime/CLI for managing external skill backends.
@@ -12,12 +12,12 @@ Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tag

 1) **Version & metadata**
 - [ ] Bump `package.json` version (e.g., `1.1.0`).
- [ ] Update CLI/version strings: [`src/cli/program.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/program.ts) and the Baileys user agent in [`src/provider-web.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/provider-web.ts).
- [ ] Confirm package metadata (name, description, repository, keywords, license) and `bin` map points to [`dist/entry.js`](https://github.com/clawdbot/clawdbot/blob/main/dist/entry.js) for `clawdbot`.
+- [ ] Update CLI/version strings: `src/cli/program.ts` and the Baileys user agent in `src/provider-web.ts`.
+- [ ] Confirm package metadata (name, description, repository, keywords, license) and `bin` map points to `dist/index.js` for `clawdbot`.
 - [ ] If dependencies changed, run `pnpm install` so `pnpm-lock.yaml` is current.

 2) **Build & artifacts**
- [ ] If A2UI inputs changed, run `pnpm canvas:a2ui:bundle` and commit any updated [`src/canvas-host/a2ui/a2ui.bundle.js`](https://github.com/clawdbot/clawdbot/blob/main/src/canvas-host/a2ui/a2ui.bundle.js).
+- [ ] If A2UI inputs changed, run `pnpm canvas:a2ui:bundle` and commit any updated `src/canvas-host/a2ui/a2ui.bundle.js`.
 - [ ] `pnpm run build` (regenerates `dist/`).
 - [ ] Optional: `npm pack --pack-destination /tmp` after the build; inspect the tarball contents and keep it handy for the GitHub release (do **not** commit it).

@@ -34,11 +34,11 @@ Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tag

 5) **macOS app (Sparkle)**
 - [ ] Build + sign the macOS app, then zip it for distribution.
- [ ] Generate the Sparkle appcast (HTML notes via [`scripts/make_appcast.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/make_appcast.sh)) and update `appcast.xml`.
+- [ ] Generate the Sparkle appcast (HTML notes via `scripts/make_appcast.sh`) and update `appcast.xml`.
 - [ ] Keep the app zip (and optional dSYM zip) ready to attach to the GitHub release.
- [ ] Follow [`docs/mac/release.md`](https://docs.clawd.bot/mac/release) for the exact commands and required env vars.
+- [ ] Follow `docs/mac/release.md` for the exact commands and required env vars.
  - `APP_BUILD` must be numeric + monotonic (no `-beta`) so Sparkle compares versions correctly.
-  - If notarizing, use the `clawdbot-notary` keychain profile created from App Store Connect API env vars (see [`docs/mac/release.md`](https://docs.clawd.bot/mac/release)).
+  - If notarizing, use the `clawdbot-notary` keychain profile created from App Store Connect API env vars (see `docs/mac/release.md`).

 6) **Publish (npm)**
 - [ ] Confirm git status is clean; commit and push as needed.
@@ -8,8 +8,8 @@ read_when:
 Short, exact flow of one agent run. Source of truth: current code in `src/`.

 ## Entry points
- Gateway RPC: `agent` and `agent.wait` in [`src/gateway/server-methods/agent.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server-methods/agent.ts).
- CLI: `agentCommand` in [`src/commands/agent.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/commands/agent.ts).
+- Gateway RPC: `agent` and `agent.wait` in `src/gateway/server-methods/agent.ts`.
+- CLI: `agentCommand` in `src/commands/agent.ts`.

 ## High-level flow
 1) `agent` RPC validates params, resolves session (sessionKey/sessionId), persists session metadata, returns `{ runId, acceptedAt }` immediately.
@@ -36,8 +36,8 @@ Short, exact flow of one agent run. Source of truth: current code in `src/`.
 - `assistant`: streamed deltas from pi-agent-core
 - `tool`: streamed tool events from pi-agent-core

-## Chat provider handling
- `createAgentEventHandler` in [`src/gateway/server-chat.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server-chat.ts):
+## Chat surface handling
+- `createAgentEventHandler` in `src/gateway/server-chat.ts`:
  - buffers assistant deltas
  - emits chat `delta` messages
  - emits chat `final` when **lifecycle end/error** arrives
@@ -53,9 +53,9 @@ Short, exact flow of one agent run. Source of truth: current code in `src/`.
 - `agent.wait` timeout (wait-only, does not stop agent)

 ## Files
- [`src/gateway/server-methods/agent.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server-methods/agent.ts)
- [`src/gateway/server-methods/agent-job.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server-methods/agent-job.ts)
- [`src/commands/agent.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/commands/agent.ts)
- [`src/agents/pi-embedded-runner.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/agents/pi-embedded-runner.ts)
- [`src/agents/pi-embedded-subscribe.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/agents/pi-embedded-subscribe.ts)
- [`src/gateway/server-chat.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server-chat.ts)
+- `src/gateway/server-methods/agent.ts`
+- `src/gateway/server-methods/agent-job.ts`
+- `src/commands/agent.ts`
+- `src/agents/pi-embedded-runner.ts`
+- `src/agents/pi-embedded-subscribe.ts`
+- `src/gateway/server-chat.ts`
@@ -9,13 +9,13 @@ CLAWDBOT runs a single embedded agent runtime derived from **p-mono** (internal

 ## Workspace (required)

-CLAWDBOT uses a single agent workspace directory (`agent.workspace`) as the agent’s **only** working directory (`cwd`) for tools and context.
+You must set an agent home directory via `agent.workspace`. CLAWDBOT uses this as the agent’s **only** working directory (`cwd`) for tools and context.

 Recommended: use `clawdbot setup` to create `~/.clawdbot/clawdbot.json` if missing and initialize the workspace files.

 If `agent.sandbox` is enabled, non-main sessions can override this with
 per-session workspaces under `agent.sandbox.workspaceRoot` (see
-[`docs/configuration.md`](https://docs.clawd.bot/configuration)).
+`docs/configuration.md`).

 ## Bootstrap files (injected)

@@ -31,14 +31,6 @@ On the first turn of a new session, CLAWDBOT injects the contents of these files

 If a file is missing, CLAWDBOT injects a single “missing file” marker line (and `clawdbot setup` will create a safe default template).

-`BOOTSTRAP.md` is only created for a **brand new workspace** (no other bootstrap files present). If you delete it after completing the ritual, it should not be recreated on later restarts.
-
-To disable bootstrap file creation entirely (for pre-seeded workspaces), set:
-
-```json5
-{ agent: { skipBootstrap: true } }
-```
-
 ## Built-in tools (internal)

 p’s embedded core tools (read/bash/edit/write and related internals) are defined in code and always available. `TOOLS.md` does **not** control which tools exist; it’s guidance for how *you* want them used.
@@ -50,7 +42,7 @@ Clawdbot loads skills from three locations (workspace wins on name conflict):
 - Managed/local: `~/.clawdbot/skills`
 - Workspace: `<workspace>/skills`

-Skills can be gated by config/env (see `skills` in [`docs/configuration.md`](https://docs.clawd.bot/configuration)).
+Skills can be gated by config/env (see `skills` in `docs/configuration.md`).

 ## p-mono integration

@@ -74,7 +66,7 @@ Apply these notes **only** when the user is Peter Steinberger at steipete.
 ## Sessions

 Session transcripts are stored as JSONL at:
- `~/.clawdbot/agents/<agentId>/sessions/<SessionId>.jsonl`
+- `~/.clawdbot/sessions/<SessionId>.jsonl`

 The session ID is stable and chosen by CLAWDBOT.
 Legacy Pi/Tau session folders are **not** read.
@@ -89,7 +81,7 @@ message is injected before the next assistant response.

 When queue mode is `followup` or `collect`, inbound messages are held until the
 current turn ends, then a new agent turn starts with the queued payloads. See
-[`docs/queue.md`](https://docs.clawd.bot/queue) for mode + debounce/cap behavior.
+`docs/queue.md` for mode + debounce/cap behavior.

 Block streaming sends completed assistant blocks as soon as they finish; disable
 via `agent.blockStreamingDefault: "off"` if you only want the final response.
@@ -107,4 +99,4 @@ At minimum, set:

 ---

-*Next: [Group Chats](https://docs.clawd.bot/group-messages)* 🦞
+*Next: [Group Chats](./group-messages.md)* 🦞
@@ -47,7 +47,7 @@ From the gateway machine:
 dns-sd -B _clawdbot-bridge._tcp local.
 ```

-More debugging notes: [`docs/bonjour.md`](https://docs.clawd.bot/bonjour).
+More debugging notes: `docs/bonjour.md`.

 #### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD

@@ -56,7 +56,7 @@ Android NSD/mDNS discovery won’t cross networks. If your Android node and the
 1) Set up a DNS-SD zone (example `clawdbot.internal.`) on the gateway host and publish `_clawdbot-bridge._tcp` records.
 2) Configure Tailscale split DNS for `clawdbot.internal` pointing at that DNS server.

-Details and example CoreDNS config: [`docs/bonjour.md`](https://docs.clawd.bot/bonjour).
+Details and example CoreDNS config: `docs/bonjour.md`.

 ### 3) Connect from Android

@@ -80,7 +80,7 @@ clawdbot nodes pending
 clawdbot nodes approve <requestId>
 ```

-Pairing details: [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing).
+Pairing details: `docs/gateway/pairing.md`.

 ### 5) Verify the node is connected

@@ -130,4 +130,4 @@ Camera commands (foreground only; permission-gated):
 - `camera.snap` (jpg)
 - `camera.clip` (mp4)

-See [`docs/camera.md`](https://docs.clawd.bot/camera) for parameters and CLI helpers.
+See `docs/camera.md` for parameters and CLI helpers.
@@ -15,14 +15,14 @@ Last updated: 2026-01-05

 ## Implementation snapshot (current code)

-### TypeScript Gateway ([`src/gateway/server.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server.ts))
+### TypeScript Gateway (`src/gateway/server.ts`)
 - Single HTTP + WebSocket server (default `18789`); bind policy `loopback|lan|tailnet|auto`. Refuses non-loopback binds without auth; Tailscale serve/funnel requires loopback.
 - Handshake: first frame must be a `connect` request; AJV validates request + params against TypeBox schemas; protocol negotiated via `minProtocol`/`maxProtocol`.
 - `hello-ok` includes snapshot (presence/health/stateVersion/uptime/configPath/stateDir), features (methods/events), policy (max payload/buffer/tick), and `canvasHostUrl` when available.
 - Events emitted: `agent`, `chat`, `presence`, `tick`, `health`, `heartbeat`, `cron`, `talk.mode`, `node.pair.requested`, `node.pair.resolved`, `voicewake.changed`, `shutdown`.
 - Idempotency keys are required for `send`, `agent`, `chat.send`, and node invokes; the dedupe cache avoids double-sends on reconnects. Payload sizes are capped per connection.
- Optional node bridge ([`src/infra/bridge/server.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/bridge/server.ts)): TCP JSONL frames (`hello`, `pair-request`, `req/res`, `event`, `invoke`, `ping`). Node connect/disconnect updates presence and flows into the session bus.
- Control UI + Canvas host: HTTP serves Control UI (base path configurable) and can host the A2UI canvas via [`src/canvas-host/server.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/canvas-host/server.ts) (live reload). Canvas host URL is advertised to nodes + clients.
+- Optional node bridge (`src/infra/bridge/server.ts`): TCP JSONL frames (`hello`, `pair-request`, `req/res`, `event`, `invoke`, `ping`). Node connect/disconnect updates presence and flows into the session bus.
+- Control UI + Canvas host: HTTP serves Control UI (base path configurable) and can host the A2UI canvas via `src/canvas-host/server.ts` (live reload). Canvas host URL is advertised to nodes + clients.

 ### iOS node (`apps/ios`)
 - Discovery + pairing: `BridgeDiscoveryModel` uses `NWBrowser` Bonjour discovery and reads TXT fields for LAN/tailnet host hints plus gateway/bridge/canvas ports.
@@ -46,7 +46,7 @@ Last updated: 2026-01-05
 - **Clients (mac app / CLI / web admin)**  
  - One WS connection per client.  
  - Send requests (`health`, `status`, `send`, `agent`, `system-presence`, toggles) and subscribe to events (`tick`, `agent`, `presence`, `shutdown`).
-  - On macOS, the app can also be invoked via deep links (`clawdbot://agent?...`) which translate into the same Gateway `agent` request path (see [`docs/macos.md`](https://docs.clawd.bot/macos)).
+  - On macOS, the app can also be invoked via deep links (`clawdbot://agent?...`) which translate into the same Gateway `agent` request path (see `docs/macos.md`).
 - **Agent process (Pi)**  
  - Spawned by the Gateway on demand for `agent` calls; streams events back over the same WS connection.
 - **WebChat**  
@@ -69,7 +69,7 @@ The bridge port (default `18790`) is a plain TCP service. By default it binds to
 For a tailnet-only setup, bind it to the Tailscale IP instead:

 - Set `bridge.bind: "tailnet"` in `~/.clawdbot/clawdbot.json`.
- Restart the Gateway (or restart the macOS menubar app via [`./scripts/restart-mac.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/restart-mac.sh) on that machine).
+- Restart the Gateway (or restart the macOS menubar app via `./scripts/restart-mac.sh` on that machine).

 This keeps the bridge reachable only from devices on your tailnet (while still listening on loopback for local/SSH port-forwards).

@@ -77,8 +77,8 @@ This keeps the bridge reachable only from devices on your tailnet (while still l

 Only the **Node Gateway** (`clawd` / `clawdbot gateway`) advertises Bonjour beacons.

- Implementation: [`src/infra/bonjour.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/bonjour.ts)
- Gateway wiring: [`src/gateway/server.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server.ts)
+- Implementation: `src/infra/bonjour.ts`
+- Gateway wiring: `src/gateway/server.ts`

 ## Service types

@@ -136,7 +136,7 @@ The log includes browser state transitions (`ready`, `waiting`, `failed`, `cance
 - **Sleep / interface churn**: macOS may temporarily drop mDNS results when switching networks; retry.
 - **Browse works but resolve fails (iOS “NoSuchRecord”)**: make sure the advertiser publishes a valid SRV target hostname.
  - Implementation detail: `@homebridge/ciao` defaults `hostname` to the *service instance name* when `hostname` is omitted. If your instance name contains spaces/parentheses, some resolvers can fail to resolve the implied A/AAAA record.
-  - Fix: set an explicit DNS-safe `hostname` (single label; no `.local`) in [`src/infra/bonjour.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/bonjour.ts).
+  - Fix: set an explicit DNS-safe `hostname` (single label; no `.local`) in `src/infra/bonjour.ts`.

 ## Escaped instance names (`\\032`)
 Bonjour/DNS-SD often escapes bytes in service instance names as decimal `\\DDD` sequences (e.g. spaces become `\\032`).
@@ -155,5 +155,5 @@ Bonjour/DNS-SD often escapes bytes in service instance names as decimal `\\DDD`

 ## Related docs

- Discovery policy and transport selection: [`docs/discovery.md`](https://docs.clawd.bot/discovery)
- Node pairing + approvals: [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing)
+- Discovery policy and transport selection: `docs/discovery.md`
+- Node pairing + approvals: `docs/gateway/pairing.md`
@@ -189,26 +189,10 @@ All existing endpoints accept optional `?profile=<name>` query parameter:
 - `GET /?profile=work` — status for work profile
 - `POST /start?profile=work` — start work profile browser
 - `GET /tabs?profile=work` — list tabs for work profile
- `POST /tabs/open?profile=work` — open tab in work profile
 - etc.

 When `profile` is omitted, uses `browser.defaultProfile` (defaults to "clawd").

-### Agent browser tool
-
-The `browser` tool accepts an optional `profile` parameter for all actions:
-
-```json
-{
-  "action": "open",
-  "targetUrl": "https://example.com",
-  "profile": "work"
-}
-```
-
-This routes the operation to the specified profile's browser instance. Omitting
-`profile` uses the default profile.
-
 ### Profile naming rules

 - Lowercase alphanumeric characters and hyphens only
@@ -237,7 +221,7 @@ The agent should not assume tabs are ephemeral. It should:

 ## CLI quick reference (one example each)

-All commands accept `--browser-profile <name>` to target a specific profile (default: `clawd`).
+All commands accept `--profile <name>` to target a specific profile (default: `clawd`).

 Profile management:
 - `clawdbot browser profiles`
@@ -306,4 +290,4 @@ Notes:

 ## Troubleshooting

-For Linux-specific issues (especially Ubuntu with snap Chromium), see [browser-linux-troubleshooting](https://docs.clawd.bot/browser-linux-troubleshooting).
+For Linux-specific issues (especially Ubuntu with snap Chromium), see [browser-linux-troubleshooting.md](./browser-linux-troubleshooting.md).
@@ -1,34 +1,22 @@
---
-summary: "Bun workflow (preferred): installs, patches, and gotchas vs pnpm"
-read_when:
-  - You want the fastest local dev loop (bun + watch)
-  - You hit Bun install/patch/lifecycle script issues
---
+# Bun (optional)

-# Bun
-
-Goal: run this repo with **Bun** (preferred) without losing pnpm patch behavior.
+Goal: allow running this repo with Bun without maintaining a Bun lockfile or losing pnpm patch behavior.

 ## Status

- Bun is the preferred local runtime for running TypeScript directly (`bun run …`, `bun --watch …`).
- `pnpm` is still fully supported (and used by some docs tooling).
- Bun cannot use `pnpm-lock.yaml` and will ignore it.
+- pnpm remains the primary package manager/runtime for this repo.
+- Bun can be used for local installs/builds/tests, but Bun currently **cannot use** `pnpm-lock.yaml` and will ignore it.

-## Install
+## Install (no Bun lockfile)

-Default:
-
-```sh
-bun install
-```
-
-Note: `bun.lock`/`bun.lockb` are gitignored, so there’s no repo churn either way. If you want *no lockfile writes*:
+Use Bun without writing `bun.lock`/`bun.lockb`:

 ```sh
 bun install --no-save
 ```

+This avoids maintaining two lockfiles. (`bun.lock`/`bun.lockb` are gitignored.)
+
 ## Build / Test (Bun)

 ```sh
@@ -41,7 +29,7 @@ bun run vitest run
 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:

- [`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` runs only for Bun installs and applies every entry from `package.json#pnpm.patchedDependencies` into `node_modules/...` using `git apply` (idempotent).

 To add a new patch that works in both pnpm + Bun:

@@ -18,7 +18,7 @@ You’re putting an agent in a position to:
 Start conservative:
 - Always set `whatsapp.allowFrom` (never run open-to-the-world on your personal Mac).
 - Use a dedicated WhatsApp number for the assistant.
- Heartbeats now default to every 30 minutes. Disable until you trust the setup by setting `agent.heartbeat.every: "0m"`.
+- Keep heartbeats disabled until you trust the setup (omit `agent.heartbeat` or set `agent.heartbeat.every: "0m"`).

 ## Prerequisites

@@ -69,11 +69,6 @@ clawdbot login
 clawdbot gateway --port 18789
 ```

-Optional (supervised, always-on):
-```bash
-clawdbot gateway install
-```
-
 3) Put a minimal config in `~/.clawdbot/clawdbot.json`:

 ```json5
@@ -86,11 +81,11 @@ clawdbot gateway install

 Now message the assistant number from your allowlisted phone.

-## Give the agent a workspace (AGENTS)
+## Give the agent a workspace (AGENTS.md)

 Clawd reads operating instructions and “memory” from its workspace directory.

-By default, Clawdbot uses `~/clawd` as the agent workspace, and will create it (plus starter `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`) automatically on setup/first agent run. `BOOTSTRAP.md` is only created when the workspace is brand new (it should not come back after you delete it).
+By default, Clawdbot uses `~/clawd` as the agent workspace, and will create it (plus starter `AGENTS.md`, `SOUL.md`, `TOOLS.md`) automatically on setup/first agent run.

 Tip: treat this folder like Clawd’s “memory” and make it a git repo (ideally private) so your `AGENTS.md` + memory files are backed up.

@@ -108,16 +103,6 @@ Optional: choose a different workspace with `agent.workspace` (supports `~`).
 }
 ```

-If you already ship your own workspace files from a repo, you can disable bootstrap file creation entirely:
-
-```json5
-{
-  agent: {
-    skipBootstrap: true
-  }
-}
-```
-
 ## The config that turns it into “an assistant”

 CLAWDBOT defaults to a good assistant setup, but you’ll usually want to tune:
@@ -159,16 +144,14 @@ Example:

 ## Sessions and memory

- Session files: `~/.clawdbot/agents/<agentId>/sessions/{{SessionId}}.jsonl`
- Session metadata (token usage, last route, etc): `~/.clawdbot/agents/<agentId>/sessions/sessions.json` (legacy: `~/.clawdbot/sessions/sessions.json`)
+- Session files: `~/.clawdbot/sessions/{{SessionId}}.jsonl`
+- Session metadata (token usage, last route, etc): `~/.clawdbot/sessions/sessions.json` (legacy: `~/.clawdbot/sessions.json`)
 - `/new` or `/reset` starts a fresh session for that chat (configurable via `resetTriggers`). If sent alone, the agent replies with a short hello to confirm the reset.
 - `/compact [instructions]` compacts the session context and reports the remaining context budget.

 ## Heartbeats (proactive mode)

-By default, CLAWDBOT runs a heartbeat every 30 minutes with the prompt:
-`Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`
-Set `agent.heartbeat.every: "0m"` to disable.
+When `agent.heartbeat.every` is set to a positive interval, CLAWDBOT periodically runs a heartbeat prompt (default: `HEARTBEAT`).

 - If the agent replies with `HEARTBEAT_OK` (optionally with short padding; see `agent.heartbeat.ackMaxChars`), CLAWDBOT suppresses outbound delivery for that heartbeat.

@@ -208,12 +191,12 @@ Logs live under `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`).

 ## Next steps

- WebChat: [WebChat](https://docs.clawd.bot/webchat)
- Gateway ops: [Gateway runbook](https://docs.clawd.bot/gateway)
- Cron + wakeups: [Cron + wakeups](https://docs.clawd.bot/cron)
- macOS menu bar companion: [Clawdbot macOS app](https://docs.clawd.bot/macos)
- iOS node app: [iOS app](https://docs.clawd.bot/ios)
- Android node app: [Android app](https://docs.clawd.bot/android)
- Windows status: [Windows app](https://docs.clawd.bot/windows)
- Linux status: [Linux app](https://docs.clawd.bot/linux)
- Security: [Security](https://docs.clawd.bot/security)
+- WebChat: [WebChat](./webchat.md)
+- Gateway ops: [Gateway runbook](./gateway.md)
+- Cron + wakeups: [Cron + wakeups](./cron.md)
+- macOS menu bar companion: [Clawdbot macOS app](./macos.md)
+- iOS node app: [iOS app](./ios.md)
+- Android node app: [Android app](./android.md)
+- Windows status: [Windows app](./windows.md)
+- Linux status: [Linux app](./linux.md)
+- Security: [Security](./security.md)
@@ -91,21 +91,18 @@ Env var equivalent:

 ### Auth storage (OAuth + API keys)

-Clawdbot stores **per-agent** auth profiles (OAuth + API keys) in:
- `<agentDir>/auth-profiles.json` (default: `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`)
+Clawdbot stores **auth profiles** (OAuth + API keys) in:
+- `~/.clawdbot/agent/auth-profiles.json`

 Legacy OAuth imports:
 - `~/.clawdbot/credentials/oauth.json` (or `$CLAWDBOT_STATE_DIR/credentials/oauth.json`)

 The embedded Pi agent maintains a runtime cache at:
- `<agentDir>/auth.json` (managed automatically; don’t edit manually)
-
-Legacy agent dir (pre multi-agent):
- `~/.clawdbot/agent/*` (migrated by `clawdbot doctor` into `~/.clawdbot/agents/<defaultAgentId>/agent/*`)
+- `~/.clawdbot/agent/auth.json` (managed automatically; don’t edit manually)

 Overrides:
 - OAuth dir (legacy import only): `CLAWDBOT_OAUTH_DIR`
- Agent dir (default agent root override): `CLAWDBOT_AGENT_DIR` (preferred), `PI_CODING_AGENT_DIR` (legacy)
+- Agent dir: `CLAWDBOT_AGENT_DIR` (preferred), `PI_CODING_AGENT_DIR` (legacy)

 On first use, Clawdbot imports `oauth.json` entries into `auth-profiles.json`.

@@ -187,57 +184,21 @@ Metadata written by CLI wizards (`onboard`, `configure`, `doctor`, `update`).
 }
 ```

-### `whatsapp.dmPolicy`
-
-Controls how WhatsApp direct chats (DMs) are handled:
- `"pairing"` (default): unknown senders get a pairing code; owner must approve
- `"allowlist"`: only allow senders in `whatsapp.allowFrom` (or paired allow store)
- `"open"`: allow all inbound DMs (**requires** `whatsapp.allowFrom` to include `"*"`)
- `"disabled"`: ignore all inbound DMs
-
-Pairing approvals:
- `clawdbot pairing list --provider whatsapp`
- `clawdbot pairing approve --provider whatsapp <code>`
-
 ### `whatsapp.allowFrom`

 Allowlist of E.164 phone numbers that may trigger WhatsApp auto-replies (**DMs only**).
-If empty and `whatsapp.dmPolicy="pairing"`, unknown senders will receive a pairing code.
+If empty, the default allowlist is your own WhatsApp number (self-chat mode).
 For groups, use `whatsapp.groupPolicy` + `whatsapp.groupAllowFrom`.

 ```json5
 {
  whatsapp: {
-    dmPolicy: "pairing", // pairing | allowlist | open | disabled
    allowFrom: ["+15555550123", "+447700900123"],
    textChunkLimit: 4000 // optional outbound chunk size (chars)
  }
 }
 ```

-### `whatsapp.accounts` (multi-account)
-
-Run multiple WhatsApp accounts in one gateway:
-
-```json5
-{
-  whatsapp: {
-    accounts: {
-      default: {}, // optional; keeps the default id stable
-      personal: {},
-      biz: {
-        // Optional override. Default: ~/.clawdbot/credentials/whatsapp/biz
-        // authDir: "~/.clawdbot/credentials/whatsapp/biz",
-      }
-    }
-  }
-}
-```
-
-Notes:
- Outbound commands default to account `default` if present; otherwise the first configured account id (sorted).
- The legacy single-account Baileys auth dir is migrated by `clawdbot doctor` into `whatsapp/default`.
-
 ### `routing.groupChat`

 Group messages default to **require mention** (either metadata mention or regex patterns). Applies to WhatsApp, Telegram, Discord, and iMessage group chats.
@@ -322,69 +283,6 @@ Notes:
 - Discord/Slack use channel allowlists (`discord.guilds.*.channels`, `slack.channels`).
 - Group DMs (Discord/Slack) are still controlled by `dm.groupEnabled` + `dm.groupChannels`.

-### Multi-agent routing (`routing.agents` + `routing.bindings`)
-
-Run multiple isolated agents (separate workspace, `agentDir`, sessions) inside one Gateway. Inbound messages are routed to an agent via bindings.
-
- `routing.defaultAgentId`: fallback when no binding matches (default: `main`).
- `routing.agents.<agentId>`: per-agent overrides.
-  - `workspace`: default `~/clawd-<agentId>` (for `main`, falls back to legacy `agent.workspace`).
-  - `agentDir`: default `~/.clawdbot/agents/<agentId>/agent`.
- `routing.bindings[]`: routes inbound messages to an `agentId`.
-  - `match.provider` (required)
-  - `match.accountId` (optional; `*` = any account; omitted = default account)
-  - `match.peer` (optional; `{ kind: dm|group|channel, id }`)
-  - `match.guildId` / `match.teamId` (optional; provider-specific)
-
-Deterministic match order:
-1) `match.peer`
-2) `match.guildId`
-3) `match.teamId`
-4) `match.accountId` (exact, no peer/guild/team)
-5) `match.accountId: "*"` (provider-wide, no peer/guild/team)
-6) `routing.defaultAgentId`
-
-Within each match tier, the first matching entry in `routing.bindings` wins.
-
-Example: two WhatsApp accounts → two agents:
-
-```json5
-{
-  routing: {
-    defaultAgentId: "home",
-    agents: {
-      home: { workspace: "~/clawd-home" },
-      work: { workspace: "~/clawd-work" },
-    },
-    bindings: [
-      { agentId: "home", match: { provider: "whatsapp", accountId: "personal" } },
-      { agentId: "work", match: { provider: "whatsapp", accountId: "biz" } },
-    ],
-  },
-  whatsapp: {
-    accounts: {
-      personal: {},
-      biz: {},
-    }
-  }
-}
-```
-
-### `routing.agentToAgent` (optional)
-
-Agent-to-agent messaging is opt-in:
-
-```json5
-{
-  routing: {
-    agentToAgent: {
-      enabled: false,
-      allow: ["home", "work"]
-    }
-  }
-}
-```
-
 ### `routing.queue`

 Controls how inbound messages behave when an agent run is already active.
@@ -397,7 +295,7 @@ Controls how inbound messages behave when an agent run is already active.
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
-      byProvider: {
+      bySurface: {
        whatsapp: "collect",
        telegram: "collect",
        discord: "collect",
@@ -409,27 +307,6 @@ Controls how inbound messages behave when an agent run is already active.
 }
 ```

-### `commands` (chat command handling)
-
-Controls how chat commands are enabled across connectors.
-
-```json5
-{
-  commands: {
-    native: false,          // register native commands when supported
-    text: true,             // parse slash commands in chat messages
-    useAccessGroups: true   // enforce access-group allowlists/policies for commands
-  }
-}
-```
-
-Notes:
- Text commands must be sent as a **standalone** message and use the leading `/` (no plain-text aliases).
- `commands.text: false` disables parsing chat messages for commands.
- `commands.native: true` registers native commands on supported connectors (Discord/Slack/Telegram). Platforms without native commands still rely on text commands.
- `commands.native: false` skips native registration; Discord/Telegram clear previously registered commands on startup. Slack commands are managed in the Slack app.
- `commands.useAccessGroups: false` allows commands to bypass access-group allowlists/policies.
-
 ### `web` (WhatsApp web provider)

 WhatsApp runs through the gateway’s web provider. It starts automatically when a linked session exists.
@@ -461,9 +338,8 @@ Set `telegram.enabled: false` to disable automatic startup.
  telegram: {
    enabled: true,
    botToken: "your-bot-token",
-    dmPolicy: "pairing",                 // pairing | allowlist | open | disabled
-    allowFrom: ["tg:123456789"],         // optional; "open" requires ["*"]
-    groups: { "*": { requireMention: true } },
+    requireMention: true,
+    allowFrom: ["123456789"],
    mediaMaxMb: 5,
    proxy: "socks5://localhost:9050",
    webhookUrl: "https://example.com/telegram-webhook",
@@ -501,10 +377,15 @@ Configure the Discord bot by setting the bot token and optional gating:
      moderation: false
    },
    replyToMode: "off",                     // off | first | all
+    slashCommand: {                         // user-installed app slash commands
+      enabled: true,
+      name: "clawd",
+      sessionPrefix: "discord:slash",
+      ephemeral: true
+    },
    dm: {
      enabled: true,                        // disable all DMs when false
-      policy: "pairing",                    // pairing | allowlist | open | disabled
-      allowFrom: ["1234567890", "steipete"], // optional DM allowlist ("open" requires ["*"])
+      allowFrom: ["1234567890", "steipete"], // optional DM allowlist (ids or names)
      groupEnabled: false,                 // enable group DMs
      groupChannels: ["clawd-dm"]          // optional group DM allowlist
    },
@@ -545,8 +426,7 @@ Slack runs in Socket Mode and requires both a bot token and app token:
    appToken: "xapp-...",
    dm: {
      enabled: true,
-      policy: "pairing", // pairing | allowlist | open | disabled
-      allowFrom: ["U123", "U456", "*"], // optional; "open" requires ["*"]
+      allowFrom: ["U123", "U456", "*"],
      groupEnabled: false,
      groupChannels: ["G123"]
    },
@@ -601,7 +481,6 @@ Clawdbot spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required.
    enabled: true,
    cliPath: "imsg",
    dbPath: "~/Library/Messages/chat.db",
-    dmPolicy: "pairing", // pairing | allowlist | open | disabled
    allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
    includeAttachments: false,
    mediaMaxMb: 16,
@@ -631,18 +510,6 @@ Default: `~/clawd`.
 If `agent.sandbox` is enabled, non-main sessions can override this with their
 own per-session workspaces under `agent.sandbox.workspaceRoot`.

-### `agent.skipBootstrap`
-
-Disables automatic creation of the workspace bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, and `BOOTSTRAP.md`).
-
-Use this for pre-seeded deployments where your workspace files come from a repo.
-
-```json5
-{
-  agent: { skipBootstrap: true }
-}
-```
-
 ### `agent.userTimezone`

 Sets the user’s timezone for **system prompt context** (not for timestamps in
@@ -786,17 +653,14 @@ Z.AI models are available as `zai/<model>` (e.g. `zai/glm-4.7`) and require
 `ZAI_API_KEY` (or legacy `Z_AI_API_KEY`) in the environment.

 `agent.heartbeat` configures periodic heartbeat runs:
- `every`: duration string (`ms`, `s`, `m`, `h`); default unit minutes. Default:
-  `30m`. Set `0m` to disable.
+- `every`: duration string (`ms`, `s`, `m`, `h`); default unit minutes. Omit or set
+  `0m` to disable.
 - `model`: optional override model for heartbeat runs (`provider/model`).
- `target`: optional delivery provider (`last`, `whatsapp`, `telegram`, `discord`, `slack`, `signal`, `imessage`, `none`). Default: `last`.
- `to`: optional recipient override (provider-specific id, e.g. E.164 for WhatsApp, chat id for Telegram).
- `prompt`: optional override for the heartbeat body (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`).
+- `target`: optional delivery channel (`last`, `whatsapp`, `telegram`, `discord`, `imessage`, `none`). Default: `last`.
+- `to`: optional recipient override (E.164 for WhatsApp, chat id for Telegram).
+- `prompt`: optional override for the heartbeat body (default: `HEARTBEAT`).
 - `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery (default: 30).

-Heartbeats run full agent turns. Shorter intervals burn more tokens; adjust `every`
-and/or `model` accordingly.
-
 `agent.bash` configures background bash defaults:
 - `backgroundMs`: time before auto-background (ms, default 10000)
 - `timeoutSec`: auto-kill after this runtime (seconds, default 1800)
@@ -818,7 +682,7 @@ Example (disable browser/canvas everywhere):

 `agent.elevated` controls elevated (host) bash access:
 - `enabled`: allow elevated mode (default true)
- `allowFrom`: per-provider allowlists (empty = disabled)
+- `allowFrom`: per-surface allowlists (empty = disabled)
  - `whatsapp`: E.164 numbers
  - `telegram`: chat ids or usernames
  - `discord`: user ids or usernames (falls back to `discord.dm.allowFrom` if omitted)
@@ -855,7 +719,7 @@ Defaults (if enabled):
 - Debian bookworm-slim based image
 - workspace per session under `~/.clawdbot/sandboxes`
 - auto-prune: idle > 24h OR age > 7d
- tools: allow only `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn` (deny wins)
+- tools: allow only `bash`, `process`, `read`, `write`, `edit` (deny wins)
 - optional sandboxed browser (Chromium + CDP, noVNC observer)
 - hardening knobs: `network`, `user`, `pidsLimit`, `memory`, `cpus`, `ulimits`, `seccompProfile`, `apparmorProfile`

@@ -901,7 +765,7 @@ Defaults (if enabled):
        enableNoVnc: true
      },
      tools: {
-        allow: ["bash", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn"],
+        allow: ["bash", "process", "read", "write", "edit"],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
      },
      prune: {
@@ -936,11 +800,11 @@ URL is injected per session.

 Clawdbot uses the **pi-coding-agent** model catalog. You can add custom providers
 (LiteLLM, local OpenAI-compatible servers, Anthropic proxies, etc.) by writing
-`~/.clawdbot/agents/<agentId>/agent/models.json` or by defining the same schema inside your
+`~/.clawdbot/agent/models.json` or by defining the same schema inside your
 Clawdbot config under `models.providers`.

 When `models.providers` is present, Clawdbot writes/merges a `models.json` into
-`~/.clawdbot/agents/<agentId>/agent/` on startup:
+`~/.clawdbot/agent/` on startup:
 - default behavior: **merge** (keeps existing providers, overrides on name)
 - set `models.mode: "replace"` to overwrite the file contents

@@ -1026,7 +890,7 @@ Notes:
  `google-generative-ai`
 - Use `authHeader: true` + `headers` for custom auth needs.
 - Override the agent config root with `CLAWDBOT_AGENT_DIR` (or `PI_CODING_AGENT_DIR`)
-  if you want `models.json` stored elsewhere (default: `~/.clawdbot/agents/main/agent`).
+  if you want `models.json` stored elsewhere.

 ### `session`

@@ -1038,18 +902,15 @@ Controls session scoping, idle expiry, reset triggers, and where the session sto
    scope: "per-sender",
    idleMinutes: 60,
    resetTriggers: ["/new", "/reset"],
-    // Default is already per-agent under ~/.clawdbot/agents/<agentId>/sessions/sessions.json
-    // You can override with {agentId} templating:
-    store: "~/.clawdbot/agents/{agentId}/sessions/sessions.json",
-    // Direct chats collapse to agent:<agentId>:<mainKey> (default: "main").
-    mainKey: "main",
+    store: "~/.clawdbot/sessions/sessions.json",
+    // mainKey is ignored; primary key is fixed to "main"
    agentToAgent: {
      // Max ping-pong reply turns between requester/target (0–5).
      maxPingPongTurns: 5
    },
    sendPolicy: {
      rules: [
-        { action: "deny", match: { provider: "discord", chatType: "group" } }
+        { action: "deny", match: { surface: "discord", chatType: "group" } }
      ],
      default: "allow"
    }
@@ -1058,10 +919,9 @@ Controls session scoping, idle expiry, reset triggers, and where the session sto
 ```

 Fields:
- `mainKey`: direct-chat bucket key (default: `"main"`). Useful when you want to “rename” the primary DM thread without changing `agentId`.
 - `agentToAgent.maxPingPongTurns`: max reply-back turns between requester/target (0–5, default 5).
 - `sendPolicy.default`: `allow` or `deny` fallback when no rule matches.
- `sendPolicy.rules[]`: match by `provider`, `chatType` (`direct|group|room`), or `keyPrefix` (e.g. `cron:`). First deny wins; otherwise allow.
+- `sendPolicy.rules[]`: match by `surface` (provider), `chatType` (`direct|group|room`), or `keyPrefix` (e.g. `cron:`). First deny wins; otherwise allow.

 ### `skills` (skills config)

@@ -1283,7 +1143,7 @@ Convenience flags (CLI):
 - `clawdbot --dev …` → uses `~/.clawdbot-dev` + shifts ports from base `19001`
 - `clawdbot --profile <name> …` → uses `~/.clawdbot-<name>` (port via config/env/flags)

-See [`docs/gateway.md`](https://docs.clawd.bot/gateway) for the derived port mapping (gateway/bridge/browser/canvas).
+See `docs/gateway.md` for the derived port mapping (gateway/bridge/browser/canvas).

 Example:
 ```bash
@@ -1294,7 +1154,7 @@ clawdbot gateway --port 19001

 ### `hooks` (Gateway webhooks)

-Enable a simple HTTP webhook endpoint on the Gateway HTTP server.
+Enable a simple HTTP webhook surface on the Gateway HTTP server.

 Defaults:
 - enabled: `false`
@@ -1331,7 +1191,7 @@ Requests must include the hook token:

 Endpoints:
 - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
- `POST /hooks/agent` → `{ message, name?, sessionKey?, wakeMode?, deliver?, provider?, to?, thinking?, timeoutSeconds? }`
+- `POST /hooks/agent` → `{ message, name?, sessionKey?, wakeMode?, deliver?, channel?, to?, thinking?, timeoutSeconds? }`
 - `POST /hooks/<name>` → resolved via `hooks.mappings`

 `/hooks/agent` always posts a summary into the main session (and can optionally trigger an immediate heartbeat via `wakeMode: "now"`).
@@ -1461,7 +1321,7 @@ Template placeholders are expanded in `routing.transcribeAudio.command` (and any
 |----------|-------------|
 | `{{Body}}` | Full inbound message body |
 | `{{BodyStripped}}` | Body with group mentions stripped (best default for agents) |
-| `{{From}}` | Sender identifier (E.164 for WhatsApp; may differ per provider) |
+| `{{From}}` | Sender identifier (E.164 for WhatsApp; may differ per surface) |
 | `{{To}}` | Destination identifier |
 | `{{MessageSid}}` | Provider message id (when available) |
 | `{{SessionId}}` | Current session UUID |
@@ -1475,11 +1335,11 @@ Template placeholders are expanded in `routing.transcribeAudio.command` (and any
 | `{{GroupMembers}}` | Group members preview (best effort) |
 | `{{SenderName}}` | Sender display name (best effort) |
 | `{{SenderE164}}` | Sender phone number (best effort) |
-| `{{Provider}}` | Provider hint (whatsapp|telegram|discord|imessage|webchat|…) |
+| `{{Surface}}` | Surface hint (whatsapp|telegram|discord|imessage|webchat|…) |

 ## Cron (Gateway scheduler)

-Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron + wakeups](https://docs.clawd.bot/cron) for the full RFC and CLI examples.
+Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron + wakeups](./cron.md) for the full RFC and CLI examples.

 ```json5
 {
@@ -1492,4 +1352,4 @@ Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron + wa

 ---

-*Next: [Agent Runtime](https://docs.clawd.bot/agent)* 🦞
+*Next: [Agent Runtime](./agent.md)* 🦞
@@ -0,0 +1,49 @@
+---
+summary: "Deprecated newline-delimited control channel API (pre-gateway)"
+read_when:
+  - Maintaining legacy control channel support
+---
+# Control channel API (newline-delimited JSON)
+
+**Deprecated (historical):** superseded by the WebSocket Gateway protocol (`clawdbot gateway`, see `docs/architecture.md` and `docs/gateway.md`).
+Current builds use a WebSocket server on `ws://127.0.0.1:18789` and do **not** expose this TCP control channel.
+
+Legacy endpoint (if present in an older build): `127.0.0.1:18789` (TCP, localhost only), typically reached via SSH port forward in remote mode.
+
+## Frame format
+Each line is a JSON object. Two shapes exist:
+- **Request**: `{ "type": "request", "id": "<uuid>", "method": "health" | "status" | "last-heartbeat" | "set-heartbeats" | "ping", "params"?: { ... } }`
+- **Response**: `{ "type": "response", "id": "<same id>", "ok": true, "payload"?: { ... } }` or `{ "type": "response", "id": "<same id>", "ok": false, "error": "message" }`
+- **Event**: `{ "type": "event", "event": "heartbeat" | "gateway-status" | "log", "payload": { ... } }`
+
+## Methods
+- `ping`: sanity check. Payload: `{ pong: true, ts }`.
+- `health`: returns the gateway health snapshot (same shape as `clawdbot health --json`).
+- `status`: shorter summary (linked/authAge/heartbeatSeconds, session counts).
+- `last-heartbeat`: returns the most recent heartbeat event the gateway has seen.
+- `set-heartbeats { enabled: boolean }`: toggle heartbeat scheduling.
+
+## Events
+- `heartbeat` payload:
+  ```json
+  {
+    "ts": 1765224052664,
+    "status": "sent" | "ok-empty" | "ok-token" | "skipped" | "failed",
+    "to": "+15551234567",
+    "preview": "Heartbeat OK",
+    "hasMedia": false,
+    "durationMs": 1025,
+    "reason": "<error text>" // only on failed/skipped
+  }
+  ```
+- `gateway-status` payload: `{ "state": "starting" | "running" | "restarting" | "failed" | "stopped", "pid"?: number, "reason"?: string }`
+- `log` payload: arbitrary log line; optional, can be disabled.
+
+## Suggested client flow
+1) Connect (or reconnect) → send `ping`.
+2) Send `health` and `last-heartbeat` to populate UI.
+3) Listen for `event` frames; update UI in real time.
+4) For user toggles, send `set-heartbeats` and await response.
+
+## Backward compatibility
+- If the control channel is unavailable: that’s expected on modern builds. Use the Gateway WS protocol instead.
@@ -14,9 +14,9 @@ Last updated: 2025-12-13
 ## Context

 Clawdbot already has:
- A **gateway heartbeat runner** that runs the agent with the configured heartbeat prompt (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`) and suppresses `HEARTBEAT_OK` ([`src/infra/heartbeat-runner.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/heartbeat-runner.ts)).
- A lightweight, in-memory **system event queue** (`enqueueSystemEvent`) that is injected into the next **main session** turn (`drainSystemEvents` in [`src/auto-reply/reply.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/auto-reply/reply.ts)).
- A WebSocket **Gateway** daemon that is intended to be always-on ([`docs/gateway.md`](https://docs.clawd.bot/gateway)).
+- A **gateway heartbeat runner** that runs the agent with `HEARTBEAT` and suppresses `HEARTBEAT_OK` (`src/infra/heartbeat-runner.ts`).
+- A lightweight, in-memory **system event queue** (`enqueueSystemEvent`) that is injected into the next **main session** turn (`drainSystemEvents` in `src/auto-reply/reply.ts`).
+- A WebSocket **Gateway** daemon that is intended to be always-on (`docs/gateway.md`).

 This RFC adds a small “cron job system” so Clawd can schedule future work and reliably wake itself up:
 - **Delayed**: run on the *next* normal heartbeat tick
@@ -75,7 +75,7 @@ Each job is a JSON object with stable keys (unknown keys ignored for forward com
  - For `sessionTarget:"main"`, `wakeMode` controls whether we trigger the heartbeat immediately or just enqueue and wait.
 - `payload` (one of)
  - `{"kind":"systemEvent","text":string}` (enqueue as `System:`)
-  - `{"kind":"agentTurn","message":string,"deliver"?:boolean,"provider"?: "last"|"whatsapp"|"telegram"|"discord"|"signal"|"imessage","to"?:string,"timeoutSeconds"?:number}`
+  - `{"kind":"agentTurn","message":string,"deliver"?:boolean,"channel"?: "last"|"whatsapp"|"telegram"|"discord"|"signal"|"imessage","to"?:string,"timeoutSeconds"?:number}`
 - `isolation` (optional; only meaningful for isolated jobs)
  - `{"postToMainPrefix"?: string}`
 - `runtime` (optional)
@@ -173,14 +173,14 @@ When due:
 - Execute via the same agent runner path as other command-mode runs, but pinned to:
  - `sessionKey = cron:<jobId>`
  - `sessionId = store[sessionKey].sessionId` (create if missing)
- Optionally deliver output (`payload.deliver === true`) to the configured provider/to.
+- Optionally deliver output (`payload.deliver === true`) to the configured channel/to.
 - Isolated jobs always enqueue a summary system event to the main session when they finish (derived from the last agent text output).
  - Prefix defaults to `Cron`, and can be customized via `isolation.postToMainPrefix`.
 - If `deliver` is omitted/false, nothing is sent to external providers; you still get the main-session summary and can inspect the full isolated transcript in `cron:<jobId>`.

 ### “Run in parallel to main”

-Clawdbot currently serializes command execution through a global in-process queue ([`src/process/command-queue.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/process/command-queue.ts)) to avoid collisions.
+Clawdbot currently serializes command execution through a global in-process queue (`src/process/command-queue.ts`) to avoid collisions.

 To support isolated cron jobs running “in parallel”, we should introduce **lanes** (keyed queues) plus a global concurrency cap:
 - Lane `"main"`: inbound auto-replies + main heartbeat.
@@ -198,7 +198,7 @@ We need a way for the Gateway (or the scheduler) to request an immediate heartbe

 Design:
 - `startHeartbeatRunner` owns the real heartbeat execution and installs a wake handler.
- Wake hook lives in [`src/infra/heartbeat-wake.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/heartbeat-wake.ts):
+- Wake hook lives in `src/infra/heartbeat-wake.ts`:
  - `setHeartbeatWakeHandler(fn | null)` installed by the heartbeat runner
  - `requestHeartbeatNow({ reason, coalesceMs? })`
 - If the handler is absent, the request is stored as “pending”; the next time the handler is installed, it runs once.
@@ -275,7 +275,7 @@ Add a `cron` command group (all commands should also support `--json` where sens
    - `--wake now|next-heartbeat`
  - payload flags (choose one):
    - `--system-event "<text>"`
-    - `--message "<agent message>" [--deliver] [--provider last|whatsapp|telegram|discord|slack|signal|imessage] [--to <dest>]`
+    - `--message "<agent message>" [--deliver] [--channel last|whatsapp|telegram|discord|slack|signal|imessage] [--to <dest>]`

 - `clawdbot cron edit <id> ...` (patch-by-flags, non-interactive)
 - `clawdbot cron rm <id>`
@@ -313,7 +313,7 @@ clawdbot cron add \
  --wake now \
  --message "Daily check: scan calendar + inbox; deliver only if urgent." \
  --deliver \
-  --provider last
+  --channel last
 ```

 ### Run weekly (every Wednesday)
@@ -328,7 +328,7 @@ clawdbot cron add \
  --wake now \
  --message "Weekly: summarize status and remind me of goals." \
  --deliver \
-  --provider last
+  --channel last
 ```

 ### “Next heartbeat”
@@ -9,9 +9,9 @@ The Gateway dashboard is the browser Control UI served at `/` by default
 (override with `gateway.controlUi.basePath`).

 Key references:
- [`docs/control-ui.md`](https://docs.clawd.bot/control-ui) for usage and UI capabilities.
- [`docs/tailscale.md`](https://docs.clawd.bot/tailscale) for Serve/Funnel automation.
- [`docs/web.md`](https://docs.clawd.bot/web) for bind modes and security notes.
+- `docs/control-ui.md` for usage and UI capabilities.
+- `docs/tailscale.md` for Serve/Funnel automation.
+- `docs/web.md` for bind modes and security notes.

 Authentication is enforced at the WebSocket handshake via `connect.params.auth`
-(token or password). See `gateway.auth` in [`docs/configuration.md`](https://docs.clawd.bot/configuration).
+(token or password). See `gateway.auth` in `docs/configuration.md`.
@@ -1,7 +1,7 @@
 ---
 summary: "Discord bot support status, capabilities, and configuration"
 read_when:
-  - Working on Discord provider features
+  - Working on Discord surface features
 ---
 # Discord (Bot API)

@@ -11,9 +11,9 @@ Status: ready for DM and guild text channels via the official Discord bot gatewa

 ## Goals
 - Talk to Clawdbot via Discord DMs or guild channels.
- Direct chats collapse into the agent's main session (default `agent:main:main`); guild channels stay isolated as `agent:<agentId>:discord:channel:<channelId>` (display names use `discord:<guildSlug>#<channelSlug>`).
+- Share the same `main` session used by WhatsApp/Telegram/WebChat; guild channels stay isolated as `discord:group:<channelId>` (display names use `discord:<guildSlug>#<channelSlug>`).
 - Group DMs are ignored by default; enable via `discord.dm.groupEnabled` and optionally restrict by `discord.dm.groupChannels`.
- Keep routing deterministic: replies always go back to the provider they arrived on.
+- Keep routing deterministic: replies always go back to the surface they arrived on.

 ## How it works
 1. Create a Discord application → Bot, enable the intents you need (DMs + guild messages + message content), and grab the bot token.
@@ -23,18 +23,13 @@ Status: ready for DM and guild text channels via the official Discord bot gatewa
   - If you prefer env vars, still add `discord: { enabled: true }` to `~/.clawdbot/clawdbot.json` and set `DISCORD_BOT_TOKEN`.
 5. Direct chats: use `user:<id>` (or a `<@id>` mention) when delivering; all turns land in the shared `main` session.
 6. Guild channels: use `channel:<channelId>` for delivery. Mentions are required by default and can be set per guild or per channel.
-7. Direct chats: secure by default via `discord.dm.policy` (default: `"pairing"`). Unknown senders get a pairing code; approve via `clawdbot pairing approve --provider discord <code>`.
-   - To keep old “open to anyone” behavior: set `discord.dm.policy="open"` and `discord.dm.allowFrom=["*"]`.
-   - To hard-allowlist: set `discord.dm.policy="allowlist"` and list senders in `discord.dm.allowFrom`.
-   - To ignore all DMs: set `discord.dm.enabled=false` or `discord.dm.policy="disabled"`.
-8. Group DMs are ignored by default; enable via `discord.dm.groupEnabled` and optionally restrict by `discord.dm.groupChannels`.
-9. Optional guild rules: set `discord.guilds` keyed by guild id (preferred) or slug, with per-channel rules.
-10. Optional native commands: set `commands.native: true` to register native commands in Discord; set `commands.native: false` to clear previously registered native commands. Text commands are controlled by `commands.text` and must be sent as standalone `/...` messages. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
-    - Full command list + config: https://docs.clawd.bot/slash-commands
-11. Optional guild context history: set `discord.historyLimit` (default 20) to include the last N guild messages as context when replying to a mention. Set `0` to disable.
-12. Reactions: the agent can trigger reactions via the `discord` tool (gated by `discord.actions.*`).
-    - The `discord` tool is only exposed when the current provider is Discord.
-13. Native commands use isolated session keys (`discord:slash:${userId}`) rather than the shared `main` session.
+7. Optional DM control: set `discord.dm.enabled = false` to ignore all DMs, or `discord.dm.allowFrom` to allow specific users (ids or names). Use `discord.dm.groupEnabled` + `discord.dm.groupChannels` to allow group DMs.
+8. Optional guild rules: set `discord.guilds` keyed by guild id (preferred) or slug, with per-channel rules.
+9. Optional slash commands: enable `discord.slashCommand` to accept user-installed app commands (ephemeral replies). Slash invocations respect the same DM/guild allowlists.
+10. Optional guild context history: set `discord.historyLimit` (default 20) to include the last N guild messages as context when replying to a mention. Set `0` to disable.
+11. Reactions: the agent can trigger reactions via the `discord` tool (gated by `discord.actions.*`).
+    - The `discord` tool is only exposed when the current surface is Discord.
+12. Slash commands use isolated session keys (`${sessionPrefix}:${userId}`) rather than the shared `main` session.

 Note: Discord does not provide a simple username → id lookup without extra guild context, so prefer ids or `<@id>` mentions for DM delivery targets.
 Note: Slugs are lowercase with spaces replaced by `-`. Channel names are slugged without the leading `#`.
@@ -64,7 +59,7 @@ In your app: **OAuth2** → **URL Generator**

 **Scopes**
 - ✅ `bot`
- ✅ `applications.commands` (required for native commands)
+- ✅ `applications.commands` (only if you want slash commands; otherwise leave unchecked)

 **Bot Permissions** (minimal baseline)
 - ✅ View Channels
@@ -143,7 +138,7 @@ Notes:
  - The bot lacks channel permissions (View/Send/Read History), or
  - Your config requires mentions and you didn’t mention it, or
  - Your guild/channel allowlist denies the channel/user.
- **DMs don’t work**: `discord.dm.enabled=false`, `discord.dm.policy="disabled"`, or you haven’t been approved yet (`discord.dm.policy="pairing"`).
+- **DMs don’t work**: `discord.dm.enabled` may be `false` or `discord.dm.allowFrom` doesn’t include you.

 ## Capabilities & limits
 - DMs and guild text channels (threads are treated as separate channels; voice not supported).
@@ -180,9 +175,14 @@ Notes:
      moderation: false
    },
    replyToMode: "off",
+    slashCommand: {
+      enabled: true,
+      name: "clawd",
+      sessionPrefix: "discord:slash",
+      ephemeral: true
+    },
    dm: {
      enabled: true,
-      policy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["123456789012345678", "steipete"],
      groupEnabled: false,
      groupChannels: ["clawd-dm"]
@@ -208,8 +208,7 @@ Ack reactions are controlled globally via `messages.ackReaction` +
 `messages.ackReactionScope`.

 - `dm.enabled`: set `false` to ignore all DMs (default `true`).
- `dm.policy`: DM access control (`pairing` recommended). `"open"` requires `dm.allowFrom=["*"]`.
- `dm.allowFrom`: DM allowlist (user ids or names). Used by `dm.policy="allowlist"` and for `dm.policy="open"` validation.
+- `dm.allowFrom`: DM allowlist (user ids or names). Omit or set to `["*"]` to allow any DM sender.
 - `dm.groupEnabled`: enable group DMs (default `false`).
 - `dm.groupChannels`: optional allowlist for group DM channel ids or slugs.
 - `groupPolicy`: controls guild channel handling (`open|disabled|allowlist`); `allowlist` requires channel allowlists.
@@ -220,6 +219,7 @@ Ack reactions are controlled globally via `messages.ackReaction` +
 - `guilds.<id>.channels`: channel rules (keys are channel slugs or ids).
 - `guilds.<id>.requireMention`: per-guild mention requirement (overridable per channel).
 - `guilds.<id>.reactionNotifications`: reaction system event mode (`off`, `own`, `all`, `allowlist`).
+- `slashCommand`: optional config for user-installed slash commands (ephemeral responses).
 - `mediaMaxMb`: clamp inbound media saved to disk.
 - `historyLimit`: number of recent guild messages to include as context when replying to a mention (default 20, `0` disables).
 - `actions`: per-action tool gates; omit to allow all (set `false` to disable).
@@ -273,9 +273,11 @@ Allowlist matching notes:
 - Use `*` to allow any sender/channel.
 - When `guilds.<id>.channels` is present, channels not listed are denied by default.

-Native command notes:
- The registered commands mirror Clawdbot’s chat commands.
- Native commands honor the same allowlists as DMs/guild messages (`discord.dm.allowFrom`, `discord.guilds`, per-channel rules).
+Slash command notes:
+- Register a chat input command in Discord with at least one string option (e.g., `prompt`).
+- The first non-empty string option is treated as the prompt.
+- Slash commands honor the same allowlists as DMs/guild messages (`discord.dm.allowFrom`, `discord.guilds`, per-channel rules).
+- Clawdbot will auto-register `/clawd` (or the configured name) if it doesn't already exist.

 ## Tool actions
 The agent can call `discord` with actions like:
@@ -42,7 +42,7 @@ Target direction:
 - The **gateway** advertises its bridge via Bonjour.
 - Clients browse and show a “pick a gateway” list, then store the chosen endpoint.

-Troubleshooting and beacon details: [`docs/bonjour.md`](https://docs.clawd.bot/bonjour).
+Troubleshooting and beacon details: `docs/bonjour.md`.

 #### Current implementation

@@ -77,7 +77,7 @@ If the gateway can detect it is running under Tailscale, it publishes `tailnetDn

 When there is no direct route (or direct is disabled), clients can always connect via SSH by forwarding the loopback gateway port.

-See [`docs/remote.md`](https://docs.clawd.bot/remote).
+See `docs/remote.md`.

 ## Transport selection (client policy)

@@ -92,7 +92,7 @@ Recommended client behavior:

 The gateway is the source of truth for node/client admission.

- Pairing requests are created/approved/rejected in the gateway (see [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing)).
+- Pairing requests are created/approved/rejected in the gateway (see `docs/gateway/pairing.md`).
 - The bridge enforces:
  - auth (token / keypair)
  - scopes/ACLs (bridge is not a raw proxy to every gateway method)
@@ -68,7 +68,7 @@ pnpm test:docker:qr
 ### Notes

 - Gateway bind defaults to `lan` for container use.
- The gateway container is the source of truth for sessions (`~/.clawdbot/agents/<agentId>/sessions/`).
+- The gateway container is the source of truth for sessions (`~/.clawdbot/sessions`).

 ## Per-session Agent Sandbox (host gateway + Docker tools)

@@ -88,7 +88,7 @@ container. The gateway stays on your host, but the tool execution is isolated:
 - Workspace per session under `~/.clawdbot/sandboxes`
 - Auto-prune: idle > 24h OR age > 7d
 - Network: `none` by default (explicitly opt-in if you need egress)
- Default allow: `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`
+- Default allow: `bash`, `process`, `read`, `write`, `edit`
 - Default deny: `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`

 ### Enable sandboxing
@@ -124,7 +124,7 @@ container. The gateway stays on your host, but the tool execution is isolated:
        extraHosts: ["internal.service:10.0.0.5"]
      },
      tools: {
-        allow: ["bash", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn"],
+        allow: ["bash", "process", "read", "write", "edit"],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
      },
      prune: {
@@ -252,7 +252,7 @@ Example:

 ## Troubleshooting

- Image missing: build with [`scripts/sandbox-setup.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/sandbox-setup.sh) or set `agent.sandbox.docker.image`.
+- Image missing: build with `scripts/sandbox-setup.sh` or set `agent.sandbox.docker.image`.
 - Container not running: it will auto-create per session on demand.
 - Permission errors in sandbox: set `docker.user` to a UID:GID that matches your
  mounted workspace ownership (or chown the workspace folder).
@@ -23,25 +23,23 @@
  "navigation": {
    "groups": [
      {
-        "group": "Start Here",
+        "group": "Getting Started",
        "pages": [
-          "getting-started",
-          "wizard",
          "index",
-          "setup",
-          "pairing",
-          "faq",
-          "clawd",
          "showcase",
          "hubs",
-          "onboarding"
+          "onboarding",
+          "clawd",
+          "faq"
        ]
      },
      {
-        "group": "Install Options",
+        "group": "Installation",
        "pages": [
+          "wizard",
          "nix",
-          "docker"
+          "docker",
+          "setup"
        ]
      },
      {
@@ -16,7 +16,6 @@ read_when:
 - Checks sandbox Docker images when sandboxing is enabled (offers to build or switch to legacy names).
 - Detects legacy Clawdis services (launchd/systemd/schtasks) and offers to migrate them.
 - On Linux, checks if systemd user lingering is enabled and can enable it (required to keep the Gateway alive after logout).
- Migrates legacy on-disk state layouts (sessions, agentDir, provider auth dirs) into the current per-agent/per-account structure.

 ## Legacy config file migration
 If `~/.clawdis/clawdis.json` exists and `~/.clawdbot/clawdbot.json` does not, doctor will migrate the file and normalize old paths/image names.
@@ -36,19 +35,6 @@ Current migrations:
 - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
  → `agent.models` + `agent.model.primary/fallbacks` + `agent.imageModel.primary/fallbacks`

-## Legacy state migrations (disk layout)
-
-Doctor can migrate older on-disk layouts into the current structure:
- Sessions store + transcripts:
-  - from `~/.clawdbot/sessions/` to `~/.clawdbot/agents/<agentId>/sessions/`
- Agent dir:
-  - from `~/.clawdbot/agent/` to `~/.clawdbot/agents/<agentId>/agent/`
- WhatsApp auth state (Baileys):
-  - from legacy `~/.clawdbot/credentials/*.json` (except `oauth.json`)
-  - to `~/.clawdbot/credentials/whatsapp/<accountId>/...` (default account id: `default`)
-
-These migrations are best-effort and idempotent; doctor will emit warnings when it leaves any legacy folders behind as backups.
-
 ## Usage

 ```bash
@@ -22,7 +22,7 @@ read_when:

 ## Availability + allowlists
 - Feature gate: `agent.elevated.enabled` (default can be off via config even if the code supports it).
- Sender allowlist: `agent.elevated.allowFrom` with per-provider allowlists (e.g. `discord`, `whatsapp`).
+- Sender allowlist: `agent.elevated.allowFrom` with per-surface allowlists (e.g. `discord`, `whatsapp`).
 - Both must pass; otherwise elevated is treated as unavailable.
 - Discord fallback: if `agent.elevated.allowFrom.discord` is omitted, the `discord.dm.allowFrom` list is used as a fallback. Set `agent.elevated.allowFrom.discord` (even `[]`) to override.

@@ -3,7 +3,7 @@ summary: "Frequently asked questions about Clawdbot setup, configuration, and us
 ---
 # FAQ 🦞

-Common questions from the community. For detailed configuration, see [Configuration](https://docs.clawd.bot/configuration).
+Common questions from the community. For detailed configuration, see [configuration.md](./configuration.md).

 ## Installation & Setup

@@ -14,15 +14,12 @@ Everything lives under `~/.clawdbot/`:
 | Path | Purpose |
 |------|---------|
 | `~/.clawdbot/clawdbot.json` | Main config (JSON5) |
-| `~/.clawdbot/credentials/oauth.json` | Legacy OAuth import (copied into auth profiles on first use) |
-| `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` | Auth profiles (OAuth + API keys) |
-| `~/.clawdbot/agents/<agentId>/agent/auth.json` | Runtime auth cache (managed automatically) |
-| `~/.clawdbot/credentials/` | Provider auth state (e.g. `whatsapp/<accountId>/creds.json`) |
-| `~/.clawdbot/agents/` | Per-agent state (agentDir + sessions) |
-| `~/.clawdbot/agents/<agentId>/sessions/` | Conversation history & state (per agent) |
-| `~/.clawdbot/agents/<agentId>/sessions/sessions.json` | Session metadata (per agent) |
-
-Legacy single-agent path: `~/.clawdbot/agent/*` (migrated by `clawdbot doctor`).
+| `~/.clawdbot/credentials/oauth.json` | OAuth credentials (Anthropic/OpenAI, etc.) |
+| `~/.clawdbot/agent/auth-profiles.json` | Auth profiles (OAuth + API keys) |
+| `~/.clawdbot/agent/auth.json` | Runtime API key cache (managed automatically) |
+| `~/.clawdbot/credentials/` | WhatsApp/Telegram auth tokens |
+| `~/.clawdbot/sessions/` | Conversation history & state |
+| `~/.clawdbot/sessions/sessions.json` | Session metadata |

 Your **workspace** (AGENTS.md, memory files, skills) is separate — configured via `agent.workspace` in your config (default: `~/clawd`).

@@ -40,7 +37,7 @@ Some features are platform-specific:

 ### What are the minimum system requirements?

-**Basically nothing!** The gateway is very lightweight — heavy compute happens on your model provider’s servers (Anthropic/OpenAI/etc.).
+**Basically nothing!** The gateway is very lightweight — all heavy compute happens on Anthropic's servers.

 - **RAM:** 512MB-1GB is enough (community member runs on 1GB VPS!)
 - **CPU:** 1 core is fine for personal use
@@ -122,7 +119,7 @@ They're **separate billing**! An API key does NOT use your subscription.
 pnpm clawdbot login
 ```

-**If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` (and `auth.json` if present) to your server. Legacy installs can still import `~/.clawdbot/credentials/oauth.json` on first use.
+**If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/credentials/oauth.json` to your server. The auth is just a JSON file.

 ### How are env vars loaded?

@@ -144,15 +141,15 @@ Or set `CLAWDBOT_LOAD_SHELL_ENV=1` (timeout: `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=1500

 ### Does enterprise OAuth work?

-**Not currently.** Enterprise accounts use SSO which requires a different auth flow that Clawdbot’s OAuth login doesn’t support yet.
+**Not currently.** Enterprise accounts use SSO which requires a different auth flow that pi-coding-agent doesn't support yet.

-**Workaround:** Ask your enterprise admin to provision an API key (Anthropic or OpenAI) and use it via `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
+**Workaround:** Ask your enterprise admin to provision an API key via the Anthropic console, then use that with `ANTHROPIC_API_KEY`.

 ### OAuth callback not working (containers/headless)?

 OAuth needs the callback to reach the machine running the CLI. Options:

-1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` (and `auth.json` if present) to the container. Legacy flow: copy `~/.clawdbot/credentials/oauth.json` to trigger import.
+1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/credentials/oauth.json` to the container.
 2. **SSH tunnel** — `ssh -L 18789:localhost:18789 user@server`
 3. **Tailscale** — Put both machines on your tailnet.

@@ -194,15 +191,7 @@ OAuth needs the callback to reach the machine running the CLI. Options:

 ### Can I run Clawdbot in Docker?

-Yes — Docker is optional but supported. Recommended: run the setup script:
-
-```bash
-./docker-setup.sh
-```
-
-It builds the image, runs onboarding + login, and starts Docker Compose. For manual steps and sandbox notes, see `docs/docker.md`.
-
-Key considerations:
+There's no official Docker setup yet, but it works. Key considerations:

 - **WhatsApp login:** QR code works in terminal — no display needed.
 - **Persistence:** Mount `~/.clawdbot/` and your workspace as volumes.
@@ -229,7 +218,7 @@ pnpm clawdbot gateway
 bash /app/start.sh
 ```

-For more detail, see `docs/docker.md`.
+Docker support is on the roadmap — PRs welcome!

 ### Can I run Clawdbot headless on a VPS?

@@ -301,7 +290,7 @@ Per-group activation can be changed by the owner:
 - `/activation mention` — respond only when mentioned (default)
 - `/activation always` — respond to all messages

-See [Groups](https://docs.clawd.bot/groups) for details.
+See [groups.md](./groups.md) for details.

 ---

@@ -309,7 +298,7 @@ See [Groups](https://docs.clawd.bot/groups) for details.

 ### How much context can Clawdbot handle?

-Context window depends on the model. Clawdbot uses **autocompaction** — older conversation gets summarized to stay under the limit.
+Claude Opus has a 200k token context window, and Clawdbot uses **autocompaction** — older conversation gets summarized to stay under the limit.

 Practical tips:
 - Keep `AGENTS.md` focused, not bloated.
@@ -338,7 +327,7 @@ cat ~/.clawdbot/clawdbot.json | grep workspace
 - **Telegram** — Via Bot API (grammY).
 - **Discord** — Bot integration.
 - **iMessage** — Via `imsg` CLI (macOS only).
- **Signal** — Via `signal-cli` (see [Signal](https://docs.clawd.bot/signal)).
+- **Signal** — Via `signal-cli` (see [signal.md](./signal.md)).
 - **WebChat** — Browser-based chat UI.

 ### Discord: Bot works in channels but not DMs?
@@ -376,7 +365,7 @@ If you send an image but your Clawd doesn't "see" it, check these:

 Not all models support images! Check `agent.model` in your config:

- ✅ Vision (examples): `anthropic/claude-opus-4-5`, `anthropic/claude-sonnet-4-5`, `anthropic/claude-haiku-4-5`, `openai/gpt-5.2`, `openai/gpt-4o`, `google/gemini-3-pro-preview`, `google/gemini-3-flash-preview`
+- ✅ Vision: `claude-opus-4-5`, `claude-sonnet-4-5`, `claude-haiku-4-5`, `gpt-5.2`, `gpt-4o`, `gemini-pro`
 - ❌ No vision: Most local LLMs (Llama, Mistral), older models, text-only configs

 **2. Is media being downloaded?**
@@ -497,21 +486,24 @@ Headless/system services are not configured out of the box.

 The gateway runs under a supervisor that auto-restarts it. You need to stop the supervisor, not just kill the process.

-**macOS (Clawdbot.app)**
-
- Quit the menu bar app to stop the gateway.
- For debugging, restart via the app (or `scripts/restart-mac.sh` when working in the repo).
- To inspect launchd state: `launchctl print gui/$UID | grep clawdbot`
-
-**macOS (CLI launchd service, if installed)**
-If you haven’t installed a supervisor yet, install one first:
-```bash
-clawdbot gateway install
-# Or: clawdbot service install
-```
+**macOS (launchd)**

 ```bash
+# Check if running
+launchctl list | grep clawdbot
+
+# Stop (disable does NOT stop a running job)
 clawdbot gateway stop
+
+# Stop and disable
+launchctl disable gui/$UID/com.clawdbot.gateway
+launchctl bootout gui/$UID/com.clawdbot.gateway
+
+# Re-enable later
+launchctl enable gui/$UID/com.clawdbot.gateway
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.clawdbot.gateway.plist
+
+# Or just restart
 clawdbot gateway restart
 ```

@@ -543,11 +535,8 @@ pm2 delete clawdbot
 launchctl disable gui/$UID/com.clawdbot.gateway
 launchctl bootout gui/$UID/com.clawdbot.gateway 2>/dev/null

-# Linux: stop systemd user service
-systemctl --user disable --now clawdbot-gateway.service
-
-# Linux (system-wide unit, if installed)
-sudo systemctl disable --now clawdbot-gateway.service
+# Linux: stop systemd service
+sudo systemctl disable --now clawdbot

 # Kill any remaining processes
 pkill -f "clawdbot"
@@ -555,10 +544,10 @@ pkill -f "clawdbot"
 # Remove data
 trash ~/.clawdbot

-# Remove repo and re-clone (adjust path if you cloned elsewhere)
-trash ~/Projects/clawdbot
-git clone https://github.com/clawdbot/clawdbot.git ~/Projects/clawdbot
-cd ~/Projects/clawdbot && pnpm install && pnpm build
+# Remove repo and re-clone
+trash ~/clawdbot
+git clone https://github.com/clawdbot/clawdbot.git
+cd clawdbot && pnpm install && pnpm build
 pnpm clawdbot onboard
 ```

@@ -570,21 +559,17 @@ Quick reference (send these in chat):

 | Command | Action |
 |---------|--------|
-| `/help` | Show available commands |
 | `/status` | Health + session info |
 | `/new` or `/reset` | Reset the session |
-| `/compact [notes]` | Compact session context |
-| `/restart` | Restart Clawdbot |
-| `/activation mention\|always` | Group activation (owner-only) |
+| `/compact` | Compact session context |
+
+Slash commands are owner-only (gated by `whatsapp.allowFrom` and command authorization on other surfaces).
 | `/think <level>` | Set thinking level (off\|minimal\|low\|medium\|high) |
 | `/verbose on\|off` | Toggle verbose mode |
 | `/elevated on\|off` | Toggle elevated bash mode (approved senders only) |
+| `/activation mention\|always` | Group activation (owner-only) |
 | `/model <name>` | Switch AI model (see below) |
-| `/queue <mode>` | Queue mode (see below) |
-
-Slash commands are owner-only (gated by `whatsapp.allowFrom` and command authorization on other surfaces).
-Commands are only recognized when the entire message is the command (slash required; no plain-text aliases).
-Full list + config: https://docs.clawd.bot/slash-commands
+| `/queue instant\|batch\|serial` | Message queuing mode |

 ### How do I switch models on the fly?

@@ -630,8 +615,8 @@ If you don't want to use Anthropic directly, you can use alternative providers:
 ```json5
 {
  agent: {
-    model: { primary: "openrouter/anthropic/claude-sonnet-4-5" },
-    models: { "openrouter/anthropic/claude-sonnet-4-5": {} },
+    model: { primary: "openrouter/anthropic/claude-sonnet-4" },
+    models: { "openrouter/anthropic/claude-sonnet-4": {} },
    env: { OPENROUTER_API_KEY: "sk-or-..." }
  }
 }
@@ -662,8 +647,11 @@ If you get weird errors after switching models, try `/think off` and `/new` to r

 ### How do I stop/cancel a running task?

-Send one of these **as a standalone message** (no slash): `stop`, `abort`, `esc`, `wait`, `exit`.
-These are abort triggers, not slash commands.
+Send `/stop` to immediately abort the current agent run. Other stop words also work:
+- `/stop`
+- `/abort`
+- `/esc`
+- `/exit`

 For background processes (like Codex), use:
 ```
@@ -672,10 +660,8 @@ process action:kill sessionId:XXX

 You can also configure `routing.queue.mode` to control how new messages interact with running tasks:
 - `steer` — New messages redirect the current task
- `followup` — Run messages one at a time
- `collect` — Batch messages, reply once after things settle
- `steer-backlog` — Steer now, process backlog afterward
- `interrupt` — Abort current run, start fresh
+- `interrupt` — Kills current run, starts fresh
+- `collect` — Queues messages for after

 ### Does Codex CLI use my ChatGPT Pro subscription or API credits?

@@ -698,13 +684,11 @@ If you have a ChatGPT subscription, use browser auth to avoid API charges!

 Use `/queue` to control how messages sent in quick succession are handled:

- **`/queue steer`** — New messages steer the current response
- **`/queue collect`** — Batch messages, reply once after things settle
- **`/queue followup`** — One at a time, in order
- **`/queue steer-backlog`** — Steer now, process backlog afterward
- **`/queue interrupt`** — Abort current run, start fresh
+- **`/queue instant`** — New messages interrupt/steer the current response
+- **`/queue batch`** — Messages queue up, processed after current turn
+- **`/queue serial`** — One at a time, in order

-If you tend to send multiple short messages, `/queue steer` feels most natural.
+If you tend to send multiple short messages, `/queue instant` feels most natural.

 ---

@@ -111,7 +111,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: [`docs/presence.md`](https://docs.clawd.bot/presence) for how presence is produced/deduped and why `instanceId` matters.
+See also: `docs/presence.md` for how presence is produced/deduped and why `instanceId` matters.

 ## Events
 - `agent` — streamed tool/output events from the agent run (seq-tagged).
@@ -127,7 +127,7 @@ See also: [`docs/presence.md`](https://docs.clawd.bot/presence) for how presence
 ## Typing and validation
 - Server validates every inbound frame with AJV against JSON Schema emitted from the protocol definitions.
 - Clients (TS/Swift) consume generated types (TS directly; Swift via the repo’s generator).
- Types live in [`src/gateway/protocol/*.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/protocol/*.ts); regenerate schemas/models with `pnpm protocol:gen` (writes [`dist/protocol.schema.json`](https://github.com/clawdbot/clawdbot/blob/main/dist/protocol.schema.json)) and `pnpm protocol:gen:swift` (writes [`apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift`](https://github.com/clawdbot/clawdbot/blob/main/apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift)).
+- Types live in `src/gateway/protocol/*.ts`; regenerate schemas/models with `pnpm protocol:gen` (writes `dist/protocol.schema.json`) and `pnpm protocol:gen:swift` (writes `apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift`).

 ## Connection snapshot
 - `hello-ok` includes a `snapshot` with `presence`, `health`, `stateVersion`, and `uptimeMs` plus `policy {maxPayload,maxBufferedBytes,tickIntervalMs}` so clients can render immediately without extra requests.
@@ -219,13 +219,8 @@ sudo systemctl enable --now clawdbot-gateway.service
 - `clawdbot gateway send --to <num> --message "hi" [--media-url ...]` — send via Gateway (idempotent).
 - `clawdbot gateway agent --message "hi" [--to ...]` — run an agent turn (waits for final by default).
 - `clawdbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
- `clawdbot gateway install|uninstall` — install/remove the supervised gateway service (launchd/systemd/schtasks).
- `clawdbot gateway service-status` — report supervised gateway service status.
 - `clawdbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd/schtasks).
 - Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.
- Service aliases:
-  - `clawdbot service ...` — service controls (install/uninstall/status/stop/restart)
-  - `clawdbot daemon ...` — alias for `clawdbot service ...`

 ## Migration guidance
 - Retire uses of `clawdbot gateway` and the legacy TCP control port.
@@ -20,7 +20,7 @@ This enables:
 - **Bridge**: direct transport endpoint owned by the gateway. The bridge does not decide membership.

 ## API surface (gateway protocol)
-These are conceptual method names; wire them into [`src/gateway/protocol/schema.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/protocol/schema.ts) and regenerate Swift types.
+These are conceptual method names; wire them into `src/gateway/protocol/schema.ts` and regenerate Swift types.

 ### Events
 - `node.pair.requested`
@@ -78,10 +78,10 @@ Optional interactive helper:
 - `clawdbot nodes watch` (subscribe to `node.pair.requested` and prompt in-place)

 Implementation pointers:
- CLI commands: [`src/cli/nodes-cli.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/nodes-cli.ts)
- Gateway handlers + events: [`src/gateway/server.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server.ts) + [`src/gateway/server-methods/nodes.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server-methods/nodes.ts)
- Pairing store: [`src/infra/node-pairing.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/node-pairing.ts) (under `~/.clawdbot/nodes/`)
- Optional macOS UI prompt (frontend only): [`apps/macos/Sources/Clawdbot/NodePairingApprovalPrompter.swift`](https://github.com/clawdbot/clawdbot/blob/main/apps/macos/Sources/Clawdbot/NodePairingApprovalPrompter.swift)
+- CLI commands: `src/cli/nodes-cli.ts`
+- Gateway handlers + events: `src/gateway/server.ts`
+- Pairing store: `src/infra/node-pairing.ts` (under `~/.clawdbot/nodes/`)
+- Optional macOS UI prompt (frontend only): `apps/macos/Sources/Clawdbot/NodePairingApprovalPrompter.swift`
  - Push-first: listens to `node.pair.requested`/`node.pair.resolved`, does a `node.pair.list` on startup/reconnect,
    and only runs a slow safety poll while a request is pending/visible.

@@ -1,133 +0,0 @@
---
-summary: "Beginner guide: from repo checkout to first message (wizard, auth, providers, pairing)"
-read_when:
-  - First time setup from zero
-  - You want the fastest path from checkout → onboarding → first message
---
-
-# Getting Started
-
-Goal: go from **zero** → **first working chat** (with sane defaults) as quickly as possible.
-
-Recommended path: use the **CLI onboarding wizard** (`clawdbot onboard`). It sets up:
- model/auth (OAuth recommended)
- gateway settings
- providers (WhatsApp/Telegram/Discord/…)
- pairing defaults (secure DMs)
- workspace bootstrap + skills
- optional background daemon
-
-If you want the deeper reference pages, jump to: [Wizard](https://docs.clawd.bot/wizard), [Setup](https://docs.clawd.bot/setup), [Pairing](https://docs.clawd.bot/pairing), [Security](https://docs.clawd.bot/security).
-
-## 0) Prereqs
-
- Node `>=22`
- `bun` (preferred) or `pnpm`
- Git
-
-macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough.
-
-## 1) Check out from source
-
-```bash
-git clone https://github.com/clawdbot/clawdbot.git
-cd clawdbot
-bun install
-```
-
-Note: `pnpm` is also supported:
-
-```bash
-pnpm install
-```
-
-## 2) Build the Control UI (recommended)
-
-The Gateway serves the browser dashboard (Control UI) when assets exist.
-
-```bash
-bun run ui:install
-bun run ui:build
-bun run build
-```
-
-If you skip UI build, the gateway still works — you just won’t get the dashboard.
-
-## 3) Run the onboarding wizard
-
-```bash
-bun run clawdbot onboard
-```
-
-What you’ll choose:
- **Local vs Remote** gateway
- **Auth**: Anthropic OAuth or OpenAI OAuth (recommended), API key (optional), or skip for now
- **Providers**: WhatsApp QR login, bot tokens, etc.
- **Daemon**: optional background install (launchd/systemd/Task Scheduler)
-
-Wizard doc: https://docs.clawd.bot/wizard
-
-### Auth: where it lives (important)
-
- OAuth credentials (legacy import): `~/.clawdbot/credentials/oauth.json`
- Auth profiles (OAuth + API keys): `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
-
-Headless/server tip: do OAuth on a normal machine first, then copy `oauth.json` to the gateway host.
-
-## 4) Start the Gateway
-
-If the wizard didn’t start it for you:
-
-```bash
-bun run clawdbot gateway --port 18789 --verbose
-```
-
-Dashboard (local loopback): `http://127.0.0.1:18789/`
-
-## 5) Pair + connect your first chat surface
-
-### WhatsApp (QR login)
-
-```bash
-bun run clawdbot login
-```
-
-Scan via WhatsApp → Settings → Linked Devices.
-
-WhatsApp doc: https://docs.clawd.bot/whatsapp
-
-### Telegram / Discord / others
-
-The wizard can write tokens/config for you. If you prefer manual config, start with:
- Telegram: https://docs.clawd.bot/telegram
- Discord: https://docs.clawd.bot/discord
-
-## 6) DM safety (pairing approvals)
-
-Default posture: unknown DMs get a short code and messages are not processed until approved.
-
-Approve:
-
-```bash
-bun run clawdbot pairing list --provider telegram
-bun run clawdbot pairing approve --provider telegram <CODE>
-```
-
-Pairing doc: https://docs.clawd.bot/pairing
-
-## 7) Verify end-to-end
-
-In a new terminal:
-
-```bash
-bun run clawdbot health
-bun run clawdbot send --to +15555550123 --message "Hello from Clawdbot"
-```
-
-If `health` shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it.
-
-## Next steps (optional, but great)
-
- macOS menu bar app + voice wake: https://docs.clawd.bot/macos
- iOS/Android nodes (Canvas/camera/voice): https://docs.clawd.bot/nodes
- Remote access (SSH tunnel / Tailscale Serve): https://docs.clawd.bot/remote and https://docs.clawd.bot/tailscale
@@ -13,7 +13,7 @@ Goal: Gmail watch -> Pub/Sub push -> `gog gmail watch serve` -> Clawdbot webhook

 - `gcloud` installed and logged in.
 - `gog` (gogcli) installed and authorized for the Gmail account.
- Clawdbot hooks enabled (see [`docs/webhook.md`](https://docs.clawd.bot/webhook)).
+- Clawdbot hooks enabled (see `docs/webhook.md`).
 - `tailscale` logged in if you want a public HTTPS endpoint via Funnel.

 Example hook config (enable Gmail preset mapping):
@@ -30,7 +30,7 @@ Example hook config (enable Gmail preset mapping):
 ```

 To customize payload handling, add `hooks.mappings` or a JS/TS transform module
-under `hooks.transformsDir` (see [`docs/webhook.md`](https://docs.clawd.bot/webhook)).
+under `hooks.transformsDir` (see `docs/webhook.md`).

 ## Wizard (recommended)

@@ -17,8 +17,8 @@ Updated: 2025-12-07
 - **Gateway:** `monitorTelegramProvider` builds a grammY `Bot`, wires mention/allowlist gating, media download via `getFile`/`download`, and delivers replies with `sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument`. Supports long-poll or webhook via `webhookCallback`.
 - **Proxy:** optional `telegram.proxy` uses `undici.ProxyAgent` through grammY’s `client.baseFetch`.
 - **Webhook support:** `webhook-set.ts` wraps `setWebhook/deleteWebhook`; `webhook.ts` hosts the callback with health + graceful shutdown. Gateway enables webhook mode when `telegram.webhookUrl` is set (otherwise it long-polls).
- **Sessions:** direct chats collapse into the agent main session (`agent:<agentId>:<mainKey>`); groups use `agent:<agentId>:telegram:group:<chatId>`; replies route back to the same provider.
- **Config knobs:** `telegram.botToken`, `telegram.dmPolicy`, `telegram.groups` (allowlist + mention defaults), `telegram.allowFrom`, `telegram.groupAllowFrom`, `telegram.groupPolicy`, `telegram.mediaMaxMb`, `telegram.proxy`, `telegram.webhookSecret`, `telegram.webhookUrl`.
+- **Sessions:** direct chats map to `main`; groups map to `telegram:group:<chatId>`; replies route back to the same surface.
+- **Config knobs:** `telegram.botToken`, `telegram.groups` (allowlist + mention defaults), `telegram.allowFrom`, `telegram.mediaMaxMb`, `telegram.proxy`, `telegram.webhookSecret`, `telegram.webhookUrl`.
 - **Tests:** grammy mocks cover DM + group mention gating and outbound send; more media/webhook fixtures still welcome.

 Open questions
@@ -12,7 +12,7 @@ Note: `routing.groupChat.mentionPatterns` is now used by Telegram/Discord/Slack/
 ## 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`).
- Per-group sessions: session keys look like `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.
+- Per-group sessions: session keys look like `whatsapp:group:<jid>` so commands such as `/verbose on` or `/think:high` 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.
 - Ephemeral/view-once: we unwrap those before extracting text/mentions, so pings inside them still trigger.
@@ -52,13 +52,13 @@ Use the group chat command:
 - `/activation mention`
 - `/activation always`

-Only the owner number (from `whatsapp.allowFrom`, or the bot’s own E.164 when unset) can change this. Send `/status` as a standalone message in the group to see the current activation mode.
+Only the owner number (from `whatsapp.allowFrom`, defaulting to the bot’s own E.164 when unset) can change this. `/status` in the group shows the current activation mode.

 ## 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.
 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.
+4) Session-level directives (`/verbose on`, `/think:high`, `/new` or `/reset`, `/compact`) apply only to that group’s session; your personal DM session remains independent.

 ## Testing / verification
 - Automated: `pnpm test -- src/web/auto-reply.test.ts --runInBand` (covers mention gating, history injection, sender suffix).
@@ -70,4 +70,4 @@ Only the owner number (from `whatsapp.allowFrom`, or the bot’s own E.164 when
 ## Known considerations
 - Heartbeats are intentionally skipped for groups to avoid noisy broadcasts.
 - Echo suppression uses the combined batch string; if you send identical text twice without mentions, only the first will get a response.
- Session store entries will appear as `agent:<agentId>:whatsapp:group:<jid>` in the session store (`~/.clawdbot/agents/<agentId>/sessions/sessions.json` by default); a missing entry just means the group hasn’t triggered a run yet.
+- Session store entries will appear as `whatsapp:group:<jid>` in the session store (`~/.clawdbot/sessions/sessions.json` by default); a missing entry just means the group hasn’t triggered a run yet.
@@ -8,12 +8,12 @@ read_when:
 Clawdbot treats group chats consistently across surfaces: WhatsApp, Telegram, Discord, Slack, Signal, iMessage.

 ## Session keys
- Group sessions use `agent:<agentId>:<provider>:group:<id>` session keys (rooms/channels use `agent:<agentId>:<provider>:channel:<id>`).
+- Group sessions use `surface:group:<id>` session keys (rooms/channels use `surface:channel:<id>`).
 - Direct chats use the main session (or per-sender if configured).
 - Heartbeats are skipped for group sessions.

 ## Display labels
- UI labels use `displayName` when available, formatted as `<provider>:<token>`.
+- UI labels use `displayName` when available, formatted as `surface:<token>`.
 - `#room` is reserved for rooms/channels; group chats use `g-<slug>` (lowercase, spaces -> `-`, keep `#@+._-`).

 ## Group policy
@@ -110,7 +110,7 @@ Group owners can toggle per-group activation:
 - `/activation mention`
 - `/activation always`

-Owner is determined by `whatsapp.allowFrom` (or the bot’s self E.164 when unset). Send the command as a standalone message. Other surfaces currently ignore `/activation`.
+Owner is determined by `whatsapp.allowFrom` (or the bot’s self E.164 when unset). Other surfaces currently ignore `/activation`.

 ## Context fields
 Group inbound payloads set:
@@ -127,4 +127,4 @@ The agent system prompt includes a group intro on the first turn of a new group
 - Group replies always go back to the same `chat_id`.

 ## WhatsApp specifics
-See [`docs/group-messages.md`](https://docs.clawd.bot/group-messages) for WhatsApp-only behavior (history injection, mention handling details).
+See `docs/group-messages.md` for WhatsApp-only behavior (history injection, mention handling details).
@@ -11,12 +11,12 @@ Short guide to verify the WhatsApp Web / Baileys stack without guessing.
 - `clawdbot status` — local summary: whether creds exist, auth age, session store path + recent sessions.
 - `clawdbot status --deep` — also probes the running Gateway (WhatsApp connect + Telegram + Discord APIs).
 - `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.
+- Send `/status` 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`.

 ## Deep diagnostics
- Creds on disk: `ls -l ~/.clawdbot/credentials/whatsapp/<accountId>/creds.json` (mtime should be recent).
- Session store: `ls -l ~/.clawdbot/agents/<agentId>/sessions/sessions.json` (path can be overridden in config). Count and recent recipients are surfaced via `status`.
+- Creds on disk: `ls -l ~/.clawdbot/credentials/creds.json` (mtime should be recent).
+- Session store: `ls -l ~/.clawdbot/sessions/sessions.json` (legacy: `~/.clawdbot/sessions.json`; path can be overridden in config). Count and recent recipients are surfaced via `status`.
 - Relink flow: `clawdbot logout && clawdbot login --verbose` when status codes 409–515 or `loggedOut` appear in logs. (Note: the QR login flow auto-restarts once for status 515 after pairing.)

 ## When something fails
@@ -9,16 +9,13 @@ Heartbeat runs periodic agent turns in the **main session** so the model can
 surface anything that needs attention without spamming the user.

 ## Prompt contract
- Heartbeat body defaults to: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.` (configurable via `agent.heartbeat.prompt`).
+- Heartbeat body defaults to `HEARTBEAT` (configurable via `agent.heartbeat.prompt`).
 - If nothing needs attention, the model should reply `HEARTBEAT_OK`.
 - During heartbeat runs, Clawdbot treats `HEARTBEAT_OK` as an ack when it appears at
  the **start or end** of the reply. Clawdbot strips the token and discards the
  reply if the remaining content is **≤ `ackMaxChars`** (default: 30).
 - If `HEARTBEAT_OK` is in the **middle** of a reply, it is not treated specially.
 - For alerts, do **not** include `HEARTBEAT_OK`; return only the alert text.
- Heartbeat prompt text is sent **verbatim** as the user message. Clawdbot does
-  not append extra body text. The system prompt includes a Heartbeats section
-  and the run is flagged as a heartbeat internally.

 ### Stray `HEARTBEAT_OK` outside heartbeats
 If the model accidentally includes `HEARTBEAT_OK` at the start or end of a
@@ -38,11 +35,11 @@ and final replies:
 {
  agent: {
    heartbeat: {
-      every: "30m",           // default: 30m (0m disables)
+      every: "30m",           // duration string: ms|s|m|h (0m disables)
      model: "anthropic/claude-opus-4-5",
-      target: "last",          // last | whatsapp | telegram | discord | slack | signal | imessage | none
-      to: "+15551234567",      // optional provider-specific override (e.g. E.164 or chat id)
-      prompt: "Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.",
+      target: "last",          // last | whatsapp | telegram | none
+      to: "+15551234567",      // optional override for whatsapp/telegram
+      prompt: "HEARTBEAT",     // optional override
      ackMaxChars: 30          // max chars allowed after HEARTBEAT_OK
    }
  }
@@ -50,28 +47,17 @@ and final replies:
 ```

 ### Fields
- `every`: heartbeat interval (duration string; default unit minutes). Default:
-  `30m`. Set to `0m` to disable.
+- `every`: heartbeat interval (duration string; default unit minutes). Omit or set
+  to `0m` to disable.
 - `model`: optional model override for heartbeat runs (`provider/model`).
 - `target`: where heartbeat output is delivered.
-  - `last` (default): send to the last used external provider.
-  - `whatsapp` / `telegram` / `discord` / `slack` / `signal` / `imessage`: force the provider (optionally set `to`).
+  - `last` (default): send to the last used external channel.
+  - `whatsapp` / `telegram`: force the channel (optionally set `to`).
  - `none`: do not deliver externally; output stays in the session (WebChat-visible).
 - `to`: optional recipient override (E.164 for WhatsApp, chat id for Telegram).
- `prompt`: optional override for the heartbeat body (default shown above). Safe to
-  change; heartbeat acks are still keyed off `HEARTBEAT_OK`.
+- `prompt`: optional override for the heartbeat body (default: `HEARTBEAT`).
 - `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery (default: 30).

-## Cost awareness
-Heartbeats run full agent turns. Shorter intervals burn more tokens. If you
-don’t need frequent checks, increase `every`, pick a cheaper `model`, or set
-`target: "none"` to keep results internal.
-
-## HEARTBEAT.md (optional)
-If a `HEARTBEAT.md` file exists in the workspace, the default prompt tells the
-agent to read it. Keep it tiny (short checklist or reminders) to avoid prompt
-bloat.
-
 ## Behavior
 - Runs in the main session (`main`, or `global` when scope is global).
 - Uses the main lane queue; if requests are in flight, the wake is retried.
@@ -80,12 +66,6 @@ bloat.
 - If `target` resolves to no external destination (no last route or `none`), the
  heartbeat still runs but no outbound message is sent.

-## Ideas for use
- Check up on the user (light, respectful pings during daytime).
- Handle mundane tasks (triage inboxes, summarize queues, refresh notes).
- Nudge on open loops or reminders.
- Background monitoring (health checks, status polling, low-priority alerts).
-
 ## Wake hook
 - The gateway exposes a heartbeat wake hook so cron/jobs/webhooks can request an
  immediate run (`requestHeartbeatNow`).
@@ -9,142 +9,140 @@ Use these hubs to discover every page, including deep dives and reference docs t

 ## Start here

- [Index](https://docs.clawd.bot)
- [Getting Started](https://docs.clawd.bot/getting-started)
- [Onboarding](https://docs.clawd.bot/onboarding)
- [Wizard](https://docs.clawd.bot/wizard)
- [Setup](https://docs.clawd.bot/setup)
- [FAQ](https://docs.clawd.bot/faq)
- [Configuration](https://docs.clawd.bot/configuration)
- [Clawd (personal assistant)](https://docs.clawd.bot/clawd)
- [Lore](https://docs.clawd.bot/lore)
+- [Index](./index.md)
+- [Onboarding](./onboarding.md)
+- [Wizard](./wizard.md)
+- [Setup](./setup.md)
+- [FAQ](./faq.md)
+- [Configuration](./configuration.md)
+- [Clawd (personal assistant)](./clawd.md)
+- [Lore](./lore.md)

 ## Installation + distribution

- [Docker](https://docs.clawd.bot/docker)
- [Nix](https://docs.clawd.bot/nix)
+- [Docker](./docker.md)
+- [Nix](./nix.md)

 ## Core concepts

- [Architecture](https://docs.clawd.bot/architecture)
- [Agent runtime](https://docs.clawd.bot/agent)
- [Agent loop](https://docs.clawd.bot/agent-loop)
- [Multi-agent routing](https://docs.clawd.bot/multi-agent)
- [Sessions](https://docs.clawd.bot/session)
- [Sessions (alias)](https://docs.clawd.bot/sessions)
- [Session tools](https://docs.clawd.bot/session-tool)
- [Queue](https://docs.clawd.bot/queue)
- [Slash commands](https://docs.clawd.bot/slash-commands)
- [RPC adapters](https://docs.clawd.bot/rpc)
- [TypeBox schemas](https://docs.clawd.bot/typebox)
- [Presence](https://docs.clawd.bot/presence)
- [Discovery + transports](https://docs.clawd.bot/discovery)
- [Bonjour](https://docs.clawd.bot/bonjour)
- [Provider routing](https://docs.clawd.bot/provider-routing)
- [Groups](https://docs.clawd.bot/groups)
- [Group messages](https://docs.clawd.bot/group-messages)
+- [Architecture](./architecture.md)
+- [Agent runtime](./agent.md)
+- [Agent loop](./agent-loop.md)
+- [Sessions](./session.md)
+- [Sessions (alias)](./sessions.md)
+- [Session tools](./session-tool.md)
+- [Queue](./queue.md)
+- [RPC adapters](./rpc.md)
+- [TypeBox schemas](./typebox.md)
+- [Presence](./presence.md)
+- [Discovery + transports](./discovery.md)
+- [Bonjour](./bonjour.md)
+- [Surface routing](./surface.md)
+- [Groups](./groups.md)
+- [Group messages](./group-messages.md)

 ## Providers + ingress

- [WhatsApp](https://docs.clawd.bot/whatsapp)
- [Telegram](https://docs.clawd.bot/telegram)
- [Telegram (grammY notes)](https://docs.clawd.bot/grammy)
- [Slack](https://docs.clawd.bot/slack)
- [Discord](https://docs.clawd.bot/discord)
- [Signal](https://docs.clawd.bot/signal)
- [iMessage](https://docs.clawd.bot/imessage)
- [WebChat](https://docs.clawd.bot/webchat)
- [Webhooks](https://docs.clawd.bot/webhook)
- [Gmail Pub/Sub](https://docs.clawd.bot/gmail-pubsub)
+- [WhatsApp](./whatsapp.md)
+- [Telegram](./telegram.md)
+- [Telegram (grammY notes)](./grammy.md)
+- [Slack](./slack.md)
+- [Discord](./discord.md)
+- [Signal](./signal.md)
+- [iMessage](./imessage.md)
+- [WebChat](./webchat.md)
+- [Webhooks](./webhook.md)
+- [Gmail Pub/Sub](./gmail-pubsub.md)

 ## Gateway + operations

- [Gateway runbook](https://docs.clawd.bot/gateway)
- [Gateway pairing](https://docs.clawd.bot/gateway/pairing)
- [Gateway lock](https://docs.clawd.bot/gateway-lock)
- [Background process](https://docs.clawd.bot/background-process)
- [Health](https://docs.clawd.bot/health)
- [Heartbeat](https://docs.clawd.bot/heartbeat)
- [Doctor](https://docs.clawd.bot/doctor)
- [Logging](https://docs.clawd.bot/logging)
- [Dashboard](https://docs.clawd.bot/dashboard)
- [Control UI](https://docs.clawd.bot/control-ui)
- [Remote access](https://docs.clawd.bot/remote)
- [Remote gateway README](https://docs.clawd.bot/remote-gateway-readme)
- [Tailscale](https://docs.clawd.bot/tailscale)
- [Security](https://docs.clawd.bot/security)
- [Troubleshooting](https://docs.clawd.bot/troubleshooting)
+- [Gateway runbook](./gateway.md)
+- [Gateway pairing](./gateway/pairing.md)
+- [Gateway lock](./gateway-lock.md)
+- [Background process](./background-process.md)
+- [Health](./health.md)
+- [Heartbeat](./heartbeat.md)
+- [Doctor](./doctor.md)
+- [Logging](./logging.md)
+- [Dashboard](./dashboard.md)
+- [Control UI](./control-ui.md)
+- [Control API (legacy)](./control-api.md)
+- [Remote access](./remote.md)
+- [Remote gateway README](./remote-gateway-readme.md)
+- [Tailscale](./tailscale.md)
+- [Security](./security.md)
+- [Troubleshooting](./troubleshooting.md)

 ## Tools + automation

- [Tools surface](https://docs.clawd.bot/tools)
- [Bash tool](https://docs.clawd.bot/bash)
- [Elevated mode](https://docs.clawd.bot/elevated)
- [Cron + wakeups](https://docs.clawd.bot/cron)
- [Thinking + verbose](https://docs.clawd.bot/thinking)
- [Models](https://docs.clawd.bot/models)
- [Agent send CLI](https://docs.clawd.bot/agent-send)
- [Terminal UI](https://docs.clawd.bot/tui)
- [Browser control](https://docs.clawd.bot/browser)
- [Browser (Linux troubleshooting)](https://docs.clawd.bot/browser-linux-troubleshooting)
+- [Tools surface](./tools.md)
+- [Bash tool](./bash.md)
+- [Elevated mode](./elevated.md)
+- [Cron + wakeups](./cron.md)
+- [Thinking + verbose](./thinking.md)
+- [Models](./models.md)
+- [Agent send CLI](./agent-send.md)
+- [Terminal UI](./tui.md)
+- [Browser control](./browser.md)
+- [Browser (Linux troubleshooting)](./browser-linux-troubleshooting.md)

 ## Nodes, media, voice

- [Nodes overview](https://docs.clawd.bot/nodes)
- [Camera](https://docs.clawd.bot/camera)
- [Images](https://docs.clawd.bot/images)
- [Audio](https://docs.clawd.bot/audio)
- [Location command](https://docs.clawd.bot/location-command)
- [Voice wake](https://docs.clawd.bot/voicewake)
- [Talk mode](https://docs.clawd.bot/talk)
+- [Nodes overview](./nodes.md)
+- [Camera](./camera.md)
+- [Images](./images.md)
+- [Audio](./audio.md)
+- [Location command](./location-command.md)
+- [Voice wake](./voicewake.md)
+- [Talk mode](./talk.md)

 ## Platforms

- [macOS app overview](https://docs.clawd.bot/macos)
- [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)
- [macOS voice overlay](https://docs.clawd.bot/mac/voice-overlay)
- [macOS WebChat](https://docs.clawd.bot/mac/webchat)
- [macOS Canvas](https://docs.clawd.bot/mac/canvas)
- [macOS child process](https://docs.clawd.bot/mac/child-process)
- [macOS health](https://docs.clawd.bot/mac/health)
- [macOS icon](https://docs.clawd.bot/mac/icon)
- [macOS logging](https://docs.clawd.bot/mac/logging)
- [macOS permissions](https://docs.clawd.bot/mac/permissions)
- [macOS remote](https://docs.clawd.bot/mac/remote)
- [macOS signing](https://docs.clawd.bot/mac/signing)
- [macOS release](https://docs.clawd.bot/mac/release)
- [macOS bun gateway](https://docs.clawd.bot/mac/bun)
- [macOS XPC](https://docs.clawd.bot/mac/xpc)
- [macOS skills](https://docs.clawd.bot/mac/skills)
- [macOS Peekaboo plan](https://docs.clawd.bot/mac/peekaboo)
- [iOS node](https://docs.clawd.bot/ios)
- [Android node](https://docs.clawd.bot/android)
- [Windows app](https://docs.clawd.bot/windows)
- [Linux app](https://docs.clawd.bot/linux)
- [Web surfaces](https://docs.clawd.bot/web)
+- [macOS app overview](./macos.md)
+- [macOS dev setup](./mac/dev-setup.md)
+- [macOS menu bar](./mac/menu-bar.md)
+- [macOS voice wake](./mac/voicewake.md)
+- [macOS voice overlay](./mac/voice-overlay.md)
+- [macOS WebChat](./mac/webchat.md)
+- [macOS Canvas](./mac/canvas.md)
+- [macOS child process](./mac/child-process.md)
+- [macOS health](./mac/health.md)
+- [macOS icon](./mac/icon.md)
+- [macOS logging](./mac/logging.md)
+- [macOS permissions](./mac/permissions.md)
+- [macOS remote](./mac/remote.md)
+- [macOS signing](./mac/signing.md)
+- [macOS release](./mac/release.md)
+- [macOS bun gateway](./mac/bun.md)
+- [macOS XPC](./mac/xpc.md)
+- [macOS skills](./mac/skills.md)
+- [macOS Peekaboo plan](./mac/peekaboo.md)
+- [iOS node](./ios.md)
+- [Android node](./android.md)
+- [Windows app](./windows.md)
+- [Linux app](./linux.md)
+- [Web surfaces](./web.md)

 ## Workspace + templates

- [Skills](https://docs.clawd.bot/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](./skills.md)
+- [Skills config](./skills-config.md)
+- [Default AGENTS](./AGENTS.default.md)
+- [Templates: AGENTS](./templates/AGENTS.md)
+- [Templates: BOOTSTRAP](./templates/BOOTSTRAP.md)
+- [Templates: IDENTITY](./templates/IDENTITY.md)
+- [Templates: SOUL](./templates/SOUL.md)
+- [Templates: TOOLS](./templates/TOOLS.md)
+- [Templates: USER](./templates/USER.md)

 ## Experiments + proposals

- [Onboarding config protocol](https://docs.clawd.bot/onboarding-config-protocol)
- [Research: memory](https://docs.clawd.bot/research/memory)
- [Proposal: model config](https://docs.clawd.bot/proposals/model-config)
+- [Onboarding config protocol](./onboarding-config-protocol.md)
+- [Research: memory](./research/memory.md)
+- [Proposal: model config](./proposals/model-config.md)

 ## Testing + release

- [Testing](https://docs.clawd.bot/test)
- [Release checklist](https://docs.clawd.bot/RELEASING)
- [Device models](https://docs.clawd.bot/device-models)
+- [Testing](./test.md)
+- [Release checklist](./RELEASING.md)
+- [Device models](./device-models.md)
@@ -13,31 +13,6 @@ Status: external CLI integration. No daemon.
 - JSON-RPC runs over stdin/stdout (one JSON object per line).
 - Gateway owns the process; no TCP port needed.

-## Multi-account (Apple IDs)
-
-iMessage “multi-account” in one Gateway process is not currently supported in a meaningful way:
- Messages accounts are owned by the signed-in macOS user session.
- `imsg` reads the local Messages DB and sends via that user’s configured services.
- There isn’t a robust “pick AppleID X as the sender” switch we can depend on.
-
-### Practical approach: multiple gateways on multiple Macs/users
-
-If you need two iMessage identities:
- Run one Gateway on each macOS user/machine that’s signed into the desired Apple ID.
- Connect to the desired Gateway remotely (Tailscale preferred; SSH tunnel is the universal fallback).
-
-See:
- `docs/remote.md` (SSH tunnel to `127.0.0.1:18789`)
- `docs/discovery.md` (bridge vs SSH transport model)
-
-### Could we do “iMessage over SSH” from a single Gateway?
-
-Maybe, but it’s a new design:
- Outbound could theoretically pipe `imsg rpc` over SSH (stdio bridge).
- Inbound still needs a remote watcher (DB polling / event stream) and a transport back to the main Gateway.
-
-That’s closer to “remote provider instances” (or “multi-gateway aggregation”) than a small config tweak.
-
 ## Requirements
 - macOS with Messages signed in.
 - Full Disk Access for Clawdbot + the `imsg` binary (Messages DB access).
@@ -51,7 +26,6 @@ That’s closer to “remote provider instances” (or “multi-gateway aggregat
    enabled: true,
    cliPath: "imsg",
    dbPath: "~/Library/Messages/chat.db",
-    dmPolicy: "pairing", // pairing | allowlist | open | disabled
    allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
    groupPolicy: "open",
    groupAllowFrom: ["chat_id:123"],
@@ -65,7 +39,6 @@ That’s closer to “remote provider instances” (or “multi-gateway aggregat

 Notes:
 - `allowFrom` accepts handles (phone/email) or `chat_id:<id>` entries.
- Default: `imessage.dmPolicy="pairing"` — unknown DM senders get a pairing code (approve via `clawdbot pairing approve --provider imessage <code>`). `"open"` requires `allowFrom=["*"]`.
 - `groupPolicy` controls group handling (`open|disabled|allowlist`).
 - `groupAllowFrom` accepts the same entries as `allowFrom`.
 - `service` defaults to `auto` (use `imessage` or `sms` to pin).
@@ -19,29 +19,23 @@ read_when:
 <p align="center">
  <a href="https://github.com/clawdbot/clawdbot">GitHub</a> ·
  <a href="https://github.com/clawdbot/clawdbot/releases">Releases</a> ·
-  <a href="https://docs.clawd.bot">Docs</a> ·
-  <a href="https://docs.clawd.bot/clawd">Clawd setup</a>
+  <a href="https://github.com/clawdbot/clawdbot/blob/main/docs/index.md">Docs</a> ·
+  <a href="./clawd.md">Clawd setup</a>
 </p>

 CLAWDBOT bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / discord.js), and iMessage (imsg CLI) to coding agents like [Pi](https://github.com/badlogic/pi-mono).
 It’s built for [Clawd](https://clawd.me), a space lobster who needed a TARDIS.

-## Start here
-
- **New install from zero:** https://docs.clawd.bot/getting-started
- **Guided setup (recommended):** https://docs.clawd.bot/wizard (`clawdbot onboard`)
-
 ## How it works

 ```
 WhatsApp / Telegram / Discord
        │
        ▼
-  ┌───────────────────────────┐
+  ┌──────────────────────────┐
  │          Gateway          │  ws://127.0.0.1:18789 (loopback-only)
  │     (single source)       │  tcp://0.0.0.0:18790 (Bridge)
-  │                           │  http://<gateway-host>:18793
-  │                           │    /__clawdbot__/canvas/ (Canvas host)
+  │                          │  http://<gateway-host>:18793/__clawdbot__/canvas/ (Canvas host)
  └───────────┬───────────────┘
              │
              ├─ Pi agent (RPC)
@@ -60,8 +54,8 @@ Most operations flow through the **Gateway** (`clawdbot gateway`), a single long
 - **Loopback-first**: Gateway WS defaults to `ws://127.0.0.1:18789`.
  - For Tailnet access, run `clawdbot gateway --bind tailnet --token ...` (token is required for non-loopback binds).
 - **Bridge for nodes**: optional LAN/tailnet-facing bridge on `tcp://0.0.0.0:18790` for paired nodes (Bonjour-discoverable).
- **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__clawdbot__/canvas/` for node WebViews; see [`docs/configuration.md`](https://docs.clawd.bot/configuration) (`canvasHost`).
- **Remote use**: SSH tunnel or tailnet/VPN; see [`docs/remote.md`](https://docs.clawd.bot/remote) and [`docs/discovery.md`](https://docs.clawd.bot/discovery).
+- **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__clawdbot__/canvas/` for node WebViews; see `docs/configuration.md` (`canvasHost`).
+- **Remote use**: SSH tunnel or tailnet/VPN; see `docs/remote.md` and `docs/discovery.md`.

 ## Features (high level)

@@ -70,7 +64,6 @@ Most operations flow through the **Gateway** (`clawdbot gateway`), a single long
 - 🎮 **Discord Bot** — DMs + guild channels via discord.js
 - 💬 **iMessage** — Local imsg CLI integration (macOS)
 - 🤖 **Agent bridge** — Pi (RPC mode) with tool streaming
- 🧠 **Multi-agent routing** — Route provider accounts/peers to isolated agents (workspace + per-agent sessions)
 - 🔐 **Subscription auth** — Anthropic (Claude Pro/Max) + OpenAI (ChatGPT/Codex) via OAuth
 - 💬 **Sessions** — Direct chats collapse into shared `main` (default); groups are isolated
 - 👥 **Group Chat Support** — Mention-based by default; owner can toggle `/activation always|mention`
@@ -135,45 +128,41 @@ Example:
 ## Docs

 - Start here:
-  - [Docs hubs (all pages linked)](https://docs.clawd.bot/hubs)
-  - [FAQ](https://docs.clawd.bot/faq) ← *common questions answered*
-  - [Configuration](https://docs.clawd.bot/configuration)
-  - [Slash commands](https://docs.clawd.bot/slash-commands)
-  - [Multi-agent routing](https://docs.clawd.bot/multi-agent)
-  - [Updating / rollback](https://docs.clawd.bot/updating)
-  - [Pairing (DM + nodes)](https://docs.clawd.bot/pairing)
-  - [Nix mode](https://docs.clawd.bot/nix)
-  - [Clawd personal assistant setup](https://docs.clawd.bot/clawd)
-  - [Skills](https://docs.clawd.bot/skills)
-  - [Skills config](https://docs.clawd.bot/skills-config)
-  - [Workspace templates](https://docs.clawd.bot/templates/AGENTS)
-  - [RPC adapters](https://docs.clawd.bot/rpc)
-  - [Gateway runbook](https://docs.clawd.bot/gateway)
-  - [Nodes (iOS/Android)](https://docs.clawd.bot/nodes)
-  - [Web surfaces (Control UI)](https://docs.clawd.bot/web)
-  - [Discovery + transports](https://docs.clawd.bot/discovery)
-  - [Remote access](https://docs.clawd.bot/remote)
+  - [Docs hubs (all pages linked)](./hubs.md)
+  - [FAQ](./faq.md) ← *common questions answered*
+  - [Configuration](./configuration.md)
+  - [Nix mode](./nix.md)
+  - [Clawd personal assistant setup](./clawd.md)
+  - [Skills](./skills.md)
+  - [Skills config](./skills-config.md)
+  - [Workspace templates](./templates/AGENTS.md)
+  - [RPC adapters](./rpc.md)
+  - [Gateway runbook](./gateway.md)
+  - [Nodes (iOS/Android)](./nodes.md)
+  - [Web surfaces (Control UI)](./web.md)
+  - [Discovery + transports](./discovery.md)
+  - [Remote access](./remote.md)
 - Providers and UX:
-  - [WebChat](https://docs.clawd.bot/webchat)
-  - [Control UI (browser)](https://docs.clawd.bot/control-ui)
-  - [Telegram](https://docs.clawd.bot/telegram)
-  - [Discord](https://docs.clawd.bot/discord)
-  - [iMessage](https://docs.clawd.bot/imessage)
-  - [Groups](https://docs.clawd.bot/groups)
-  - [WhatsApp group messages](https://docs.clawd.bot/group-messages)
-  - [Media: images](https://docs.clawd.bot/images)
-  - [Media: audio](https://docs.clawd.bot/audio)
+  - [WebChat](./webchat.md)
+  - [Control UI (browser)](./control-ui.md)
+  - [Telegram](./telegram.md)
+  - [Discord](./discord.md)
+  - [iMessage](./imessage.md)
+  - [Groups](./groups.md)
+  - [WhatsApp group messages](./group-messages.md)
+  - [Media: images](./images.md)
+  - [Media: audio](./audio.md)
 - Companion apps:
-  - [macOS app](https://docs.clawd.bot/macos)
-  - [iOS app](https://docs.clawd.bot/ios)
-  - [Android app](https://docs.clawd.bot/android)
-  - [Windows app](https://docs.clawd.bot/windows)
-  - [Linux app](https://docs.clawd.bot/linux)
+  - [macOS app](./macos.md)
+  - [iOS app](./ios.md)
+  - [Android app](./android.md)
+  - [Windows app](./windows.md)
+  - [Linux app](./linux.md)
 - Ops and safety:
-  - [Sessions](https://docs.clawd.bot/session)
-  - [Cron + wakeups](https://docs.clawd.bot/cron)
-  - [Security](https://docs.clawd.bot/security)
-  - [Troubleshooting](https://docs.clawd.bot/troubleshooting)
+  - [Sessions](./session.md)
+  - [Cron + wakeups](./cron.md)
+  - [Security](./security.md)
+  - [Troubleshooting](./troubleshooting.md)

 ## The name

@@ -61,7 +61,7 @@ If browse works, but the iOS node can’t connect, try resolving one instance:
 dns-sd -L "<instance name>" _clawdbot-bridge._tcp local.
 ```

-More debugging notes: [`docs/bonjour.md`](https://docs.clawd.bot/bonjour).
+More debugging notes: `docs/bonjour.md`.

 #### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD

@@ -70,7 +70,7 @@ If the iOS node and the gateway are on different networks but connected via Tail
 1) Set up a DNS-SD zone (example `clawdbot.internal.`) on the gateway host and publish `_clawdbot-bridge._tcp` records.
 2) Configure Tailscale split DNS for `clawdbot.internal` pointing at that DNS server.

-Details and example CoreDNS config: [`docs/bonjour.md`](https://docs.clawd.bot/bonjour).
+Details and example CoreDNS config: `docs/bonjour.md`.

 ### 3) Connect from the iOS node app

@@ -102,7 +102,7 @@ clawdbot nodes approve <requestId>

 After approval, the iOS node receives/stores the token and reconnects authenticated.

-Pairing details: [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing).
+Pairing details: `docs/gateway/pairing.md`.

 ### 5) Verify the node is connected

@@ -169,7 +169,7 @@ The response includes `{ format, base64 }` image data (default `format="jpeg"`;

 - **iOS in background:** all `canvas.*` commands fail fast with `NODE_BACKGROUND_UNAVAILABLE` (bring the iOS node app to foreground).
 - **Return to default scaffold:** `canvas.navigate` with `{"url":""}` or `{"url":"/"}` returns to the built-in scaffold page.
- **mDNS blocked:** some networks block multicast; use a different LAN or plan a tailnet-capable bridge (see [`docs/discovery.md`](https://docs.clawd.bot/discovery)).
+- **mDNS blocked:** some networks block multicast; use a different LAN or plan a tailnet-capable bridge (see `docs/discovery.md`).
 - **Wrong node selector:** `--node` can be the node id (UUID), display name (e.g. `iOS Node`), IP, or an unambiguous prefix. If it’s ambiguous, the CLI will tell you.
 - **Stale pairing / Keychain cleared:** if the pairing token is missing (or iOS Keychain was wiped), the node must pair again; approve a new pending request.
 - **App reinstall but no reconnect:** the node restores `instanceId` + last bridge preference from Keychain; if it still comes up “unpaired”, verify Keychain persistence on your device/simulator and re-pair once.
@@ -194,9 +194,9 @@ Non-goals (v1):
 - Perfect App Store compliance; this is **internal-only** initially.

 ### Current repo reality (constraints we respect)
- The Gateway WebSocket server binds to `127.0.0.1:18789` ([`src/gateway/server.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server.ts)) with an optional `CLAWDBOT_GATEWAY_TOKEN`.
- The Gateway exposes a Canvas file server (`canvasHost`) on `canvasHost.port` (default `18793`), so nodes can `canvas.navigate` to `http://<lanHost>:18793/__clawdbot__/canvas/` and auto-reload on file changes ([`docs/configuration.md`](https://docs.clawd.bot/configuration)).
- macOS “Canvas” is controlled via the Gateway node protocol (`canvas.*`), matching iOS/Android ([`docs/mac/canvas.md`](https://docs.clawd.bot/mac/canvas)).
+- The Gateway WebSocket server binds to `127.0.0.1:18789` (`src/gateway/server.ts`) with an optional `CLAWDBOT_GATEWAY_TOKEN`.
+- The Gateway exposes a Canvas file server (`canvasHost`) on `canvasHost.port` (default `18793`), so nodes can `canvas.navigate` to `http://<lanHost>:18793/__clawdbot__/canvas/` and auto-reload on file changes (`docs/configuration.md`).
+- macOS “Canvas” is controlled via the Gateway node protocol (`canvas.*`), matching iOS/Android (`docs/mac/canvas.md`).
 - Voice wake forwards via `GatewayChannel` to Gateway `agent` (mac app: `VoiceWakeForwarder` → `GatewayConnection.sendAgent`).

 ### Recommended topology (B): Gateway-owned Bridge + loopback Gateway
@@ -237,7 +237,7 @@ Desired behavior:
 - If the Swift UI is present: show alert with Approve/Reject/Later.
 - If the Swift UI is not present: `clawdbot` CLI can list pending requests and approve/reject.

-See [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing) for the API/events and storage.
+See `docs/gateway/pairing.md` for the API/events and storage.

 CLI (headless approvals):
 - `clawdbot nodes pending`
@@ -267,7 +267,7 @@ Unify mac Canvas + iOS Canvas under a single conceptual surface:
  - remote iOS node via the bridge

 #### Minimal protocol additions (v1)
-Add to [`src/gateway/protocol/schema.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/protocol/schema.ts) (and regenerate Swift models):
+Add to `src/gateway/protocol/schema.ts` (and regenerate Swift models):

 **Identity**
 - Node identity comes from `connect.params.client.instanceId` (stable), and `connect.params.client.mode = "node"` (or `"ios-node"`).
@@ -366,7 +366,7 @@ open Clawdbot.xcodeproj

 ## Related docs

- [`docs/gateway.md`](https://docs.clawd.bot/gateway) (gateway runbook)
- [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing) (approval + storage)
- [`docs/bonjour.md`](https://docs.clawd.bot/bonjour) (discovery debugging)
- [`docs/discovery.md`](https://docs.clawd.bot/discovery) (LAN vs tailnet vs SSH)
+- `docs/gateway.md` (gateway runbook)
+- `docs/gateway/pairing.md` (approval + storage)
+- `docs/bonjour.md` (discovery debugging)
+- `docs/discovery.md` (LAN vs tailnet vs SSH)
@@ -14,7 +14,7 @@ Clawdbot has two log “surfaces”:

 ## File-based logger

-Clawdbot uses a file logger backed by `tslog` ([`src/logging.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/logging.ts)).
+Clawdbot uses a file logger backed by `tslog` (`src/logging.ts`).

 - Default rolling log file is under `/tmp/clawdbot/` (one file per day): `clawdbot-YYYY-MM-DD.log`
 - The log file path and level can be configured via `~/.clawdbot/clawdbot.json`:
@@ -33,7 +33,7 @@ The file format is one JSON object per line.

 ## Console capture

-The CLI entrypoint enables console capture ([`src/index.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/index.ts) calls `enableConsoleCapture()`).
+The CLI entrypoint enables console capture (`src/index.ts` calls `enableConsoleCapture()`).
 That means every `console.log/info/warn/error/debug/trace` is also written into the file logs,
 while still behaving normally on stdout/stderr.

@@ -89,8 +89,8 @@ clawdbot gateway --verbose --ws-log full

 Clawdbot formats console logs via a small wrapper on top of the existing stack:

- **tslog** for structured file logs ([`src/logging.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/logging.ts))
- **chalk** for colors ([`src/globals.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/globals.ts))
+- **tslog** for structured file logs (`src/logging.ts`)
+- **chalk** for colors (`src/globals.ts`)

 The console formatter is **TTY-aware** and prints consistent, prefixed lines.
 Subsystem loggers are created via `createSubsystemLogger("gateway")`.
@@ -15,7 +15,7 @@ Goal: ship **Clawdbot.app** with a self-contained relay binary that can run both
 App bundle layout:

 - `Clawdbot.app/Contents/Resources/Relay/clawdbot`
-  - bun `--compile` relay executable built from [`dist/macos/relay.js`](https://github.com/clawdbot/clawdbot/blob/main/dist/macos/relay.js)
+  - bun `--compile` relay executable built from `dist/macos/relay.js`
  - Supports:
    - `clawdbot …` (CLI)
    - `clawdbot gateway-daemon …` (LaunchAgent daemon)
@@ -31,7 +31,7 @@ Why the sidecar files matter:
 ## Build pipeline

 Packaging script:
- [`scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh)
+- `scripts/package-mac-app.sh`

 It builds:
 - TS: `pnpm exec tsc`
@@ -47,7 +47,7 @@ Important bundler flags:

 Version injection:
 - `--define "__CLAWDBOT_VERSION__=\"<pkg version>\""`
- [`src/version.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/version.ts) also supports `__CLAWDBOT_VERSION__` (and `CLAWDBOT_BUNDLED_VERSION`) so `--version` doesn’t depend on reading `package.json` at runtime.
+- `src/version.ts` also supports `__CLAWDBOT_VERSION__` (and `CLAWDBOT_BUNDLED_VERSION`) so `--version` doesn’t depend on reading `package.json` at runtime.

 ## Launchd (Gateway as LaunchAgent)

@@ -58,7 +58,7 @@ Plist location (per-user):
 - `~/Library/LaunchAgents/com.clawdbot.gateway.plist`

 Manager:
- [`apps/macos/Sources/Clawdbot/GatewayLaunchAgentManager.swift`](https://github.com/clawdbot/clawdbot/blob/main/apps/macos/Sources/Clawdbot/GatewayLaunchAgentManager.swift)
+- `apps/macos/Sources/Clawdbot/GatewayLaunchAgentManager.swift`

 Behavior:
 - “Clawdbot Active” enables/disables the LaunchAgent.
@@ -77,7 +77,7 @@ Symptom (when mis-signed):

 Fix:
 - The bun executable needs JIT-ish permissions under hardened runtime.
- [`scripts/codesign-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/codesign-mac-app.sh) signs `Relay/clawdbot` with:
+- `scripts/codesign-mac-app.sh` signs `Relay/clawdbot` with:
  - `com.apple.security.cs.allow-jit`
  - `com.apple.security.cs.allow-unsigned-executable-memory`

@@ -87,17 +87,17 @@ Problem:
 - bun can’t load some native Node addons like `sharp` (and we don’t want to ship native addon trees for the gateway).

 Solution:
- Central helper [`src/media/image-ops.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/media/image-ops.ts)
+- Central helper `src/media/image-ops.ts`
  - Prefers `/usr/bin/sips` on macOS (esp. when running under bun)
  - Falls back to `sharp` when available (Node/dev)
 - Used by:
-  - [`src/web/media.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/web/media.ts) (optimize inbound/outbound images)
-  - [`src/browser/screenshot.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/browser/screenshot.ts)
-  - [`src/agents/pi-tools.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/agents/pi-tools.ts) (image sanitization)
+  - `src/web/media.ts` (optimize inbound/outbound images)
+  - `src/browser/screenshot.ts`
+  - `src/agents/pi-tools.ts` (image sanitization)

 ## Browser control server

-The Gateway starts the browser control server (loopback only) from [`src/gateway/server.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server.ts).
+The Gateway starts the browser control server (loopback only) from `src/gateway/server.ts`.
 It’s started from the relay daemon process, so the relay binary includes Playwright deps.

 ## Tests / smoke checks
@@ -125,7 +125,7 @@ Bun may leave dotfiles like `*.bun-build` in the repo root or subfolders.

 ## DMG styling (human installer)

-[`scripts/create-dmg.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/create-dmg.sh) styles the DMG via Finder AppleScript.
+`scripts/create-dmg.sh` styles the DMG via Finder AppleScript.

 Rules of thumb:
 - Use a **72dpi** background image that matches the Finder window size in points.
@@ -10,7 +10,7 @@ read_when:

 Status: draft spec · Date: 2025-12-12

-Note: for iOS/Android nodes that should render agent-edited HTML/CSS/JS over the network, prefer the Gateway `canvasHost` (serves `~/clawd/canvas` over LAN/tailnet with live reload). A2UI is also **hosted by the Gateway** over HTTP. This doc focuses on the macOS in-app canvas panel. See [`docs/configuration.md`](https://docs.clawd.bot/configuration).
+Note: for iOS/Android nodes that should render agent-edited HTML/CSS/JS over the network, prefer the Gateway `canvasHost` (serves `~/clawd/canvas` over LAN/tailnet with live reload). A2UI is also **hosted by the Gateway** over HTTP. This doc focuses on the macOS in-app canvas panel. See `docs/configuration.md`.

 Clawdbot can embed an agent-controlled “visual workspace” panel (“Canvas”) inside the macOS app using `WKWebView`, served via a **custom URL scheme** (no loopback HTTP port required).

@@ -81,7 +81,7 @@ Canvas is exposed via the Gateway **node bridge**, so the agent can:
 This should be modeled after `WebChatManager`/`WebChatSwiftUIWindowController` but targeting `clawdbot-canvas://…` URLs.

 Related:
- For “invoke the agent again from UI” flows, prefer the macOS deep link scheme (`clawdbot://agent?...`) so *any* UI surface (Canvas, WebChat, native views) can trigger a new agent run. See [`docs/macos.md`](https://docs.clawd.bot/macos).
+- For “invoke the agent again from UI” flows, prefer the macOS deep link scheme (`clawdbot://agent?...`) so *any* UI surface (Canvas, WebChat, native views) can trigger a new agent run. See `docs/macos.md`.

 ## Agent commands (current)

@@ -57,26 +57,11 @@ The macOS app requires a symlink named `clawdbot` in `/usr/local/bin` or `/opt/h

 Alternatively, you can manually link it from your Admin account:
 ```bash
-sudo ln -sf "/Users/$(whoami)/Projects/clawdbot/dist/Clawdbot.app/Contents/Resources/Relay/clawdbot" /usr/local/bin/clawdbot
+sudo ln -sf "/Users/$(whoami)/clawdbot/dist/Clawdbot.app/Contents/Resources/Relay/clawdbot" /usr/local/bin/clawdbot
 ```

 ## Troubleshooting

-### Build Fails: Toolchain or SDK Mismatch
-The macOS app build expects the latest macOS SDK and Swift 6.2 toolchain.
-
-**System dependencies (required):**
- **Latest macOS version available in Software Update** (required by Xcode 26.2 SDKs)
- **Xcode 26.2** (Swift 6.2 toolchain)
-
-**Checks:**
-```bash
-xcodebuild -version
-xcrun swift --version
-```
-
-If versions don’t match, update macOS/Xcode and re-run the build.
-
 ### App Crashes on Permission Grant
 If the app crashes when you try to allow **Speech Recognition** or **Microphone** access, it may be due to a corrupted TCC cache or signature mismatch.

@@ -85,7 +70,7 @@ If the app crashes when you try to allow **Speech Recognition** or **Microphone*
   ```bash
   tccutil reset All com.clawdbot.mac.debug
   ```
-2. If that fails, change the `BUNDLE_ID` temporarily in [`scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh) to force a "clean slate" from macOS.
+2. If that fails, change the `BUNDLE_ID` temporarily in `scripts/package-mac-app.sh` to force a "clean slate" from macOS.

 ### Gateway "Starting..." indefinitely
 If the gateway status stays on "Starting...", check if a zombie process is holding the port:
@@ -25,4 +25,4 @@ How to see whether the WhatsApp Web/Baileys bridge is healthy from the menu bar
 - Cache the last good snapshot and the last error separately to avoid flicker; show the timestamp of each.

 ## When in doubt
- You can still use the CLI flow in [`docs/health.md`](https://docs.clawd.bot/health) (`clawdbot status`, `clawdbot status --deep`, `clawdbot health --json`) and tail `/tmp/clawdbot/clawdbot-*.log` for `web-heartbeat` / `web-reconnect`.
+- You can still use the CLI flow in `docs/health.md` (`clawdbot status`, `clawdbot status --deep`, `clawdbot health --json`) and tail `/tmp/clawdbot/clawdbot-*.log` for `web-heartbeat` / `web-reconnect`.
@@ -62,7 +62,7 @@ Use the release note generator so Sparkle renders formatted HTML notes:
 ```bash
 SPARKLE_PRIVATE_KEY_FILE=/Users/steipete/Library/CloudStorage/Dropbox/Backup/Sparkle/ed25519-private-key scripts/make_appcast.sh dist/Clawdbot-0.1.0.zip   https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml
 ```
-Generates HTML release notes from `CHANGELOG.md` (via [`scripts/changelog-to-html.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/changelog-to-html.sh)) and embeds them in the appcast entry.
+Generates HTML release notes from `CHANGELOG.md` (via `scripts/changelog-to-html.sh`) and embeds them in the appcast entry.
 Commit the updated `appcast.xml` alongside the release assets (zip + dSYM) when publishing.

 ## Publish & verify
@@ -5,11 +5,11 @@ read_when:
 ---
 # mac signing (debug builds)

-This app is usually built from [`scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh), which now:
+This app is usually built from `scripts/package-mac-app.sh`, which now:

 - sets a stable debug bundle identifier: `com.clawdbot.mac.debug`
 - writes the Info.plist with that bundle id (override via `BUNDLE_ID=...`)
- calls [`scripts/codesign-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/codesign-mac-app.sh) to sign the main binary, bundled CLI, and app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech). For stable permissions, use a real signing identity; ad-hoc is opt-in and fragile (see [`docs/mac/permissions.md`](https://docs.clawd.bot/mac/permissions)).
+- calls `scripts/codesign-mac-app.sh` to sign the main binary, bundled CLI, and app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech). For stable permissions, use a real signing identity; ad-hoc is opt-in and fragile (see `docs/mac/permissions.md`).
 - uses `CODESIGN_TIMESTAMP=auto` by default; it enables trusted timestamps for Developer ID signatures. Set `CODESIGN_TIMESTAMP=off` to skip timestamping (offline debug builds).
 - inject build metadata into Info.plist: `ClawdbotBuildTimestamp` (UTC) and `ClawdbotGitCommit` (short hash) so the About pane can show build, git, and debug/release channel.
 - **Packaging requires Bun**: The embedded gateway relay is compiled using `bun`. Ensure it is installed (`curl -fsSL https://bun.sh/install | bash`).
@@ -26,7 +26,7 @@ SIGN_IDENTITY="-" scripts/package-mac-app.sh        # explicit ad-hoc (same cave
 ```

 ### Ad-hoc Signing Note
-When signing with `SIGN_IDENTITY="-"` (ad-hoc), the script automatically disables the **Hardened Runtime** (`--options runtime`). This is necessary to prevent crashes when the app attempts to load embedded frameworks (like Sparkle) that do not share the same Team ID. Ad-hoc signatures also break TCC permission persistence; see [`docs/mac/permissions.md`](https://docs.clawd.bot/mac/permissions) for recovery steps.
+When signing with `SIGN_IDENTITY="-"` (ad-hoc), the script automatically disables the **Hardened Runtime** (`--options runtime`). This is necessary to prevent crashes when the app attempts to load embedded frameworks (like Sparkle) that do not share the same Team ID. Ad-hoc signatures also break TCC permission persistence; see `docs/mac/permissions.md` for recovery steps.

 ## Build metadata for About

@@ -46,7 +46,7 @@ Hardening:

 ## Forwarding behavior
 - When Voice Wake is enabled, transcripts are forwarded to the active gateway/agent (the same local vs remote mode used by the rest of the mac app).
- Replies are delivered to the **last-used main provider** (WhatsApp/Telegram/Discord/WebChat). If delivery fails, the error is logged and the run is still visible via WebChat/session logs.
+- Replies are delivered to the **last-used main surface** (WhatsApp/Telegram/Discord/WebChat). If delivery fails, the error is logged and the run is still visible via WebChat/session logs.

 ## Forwarding payload
 - `VoiceWakeForwarder.prefixedTranscript(_:)` prepends the machine hint before sending. Shared between wake-word and push-to-talk paths.
@@ -13,10 +13,10 @@ The macOS menu bar app shows the WebChat UI as a native SwiftUI view and reuses
 ## Launch & debugging
 - Manual: Lobster menu → “Open Chat”.
 - Auto-open for testing: run `dist/Clawdbot.app/Contents/MacOS/Clawdbot --webchat` (or pass `--webchat` to the binary launched by launchd). The window opens on startup.
- Logs: see [`./scripts/clawlog.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/clawlog.sh) (subsystem `com.clawdbot`, category `WebChatSwiftUI`).
+- Logs: see `./scripts/clawlog.sh` (subsystem `com.clawdbot`, category `WebChatSwiftUI`).

 ## How it’s wired
- Implementation: [`apps/macos/Sources/Clawdbot/WebChatSwiftUI.swift`](https://github.com/clawdbot/clawdbot/blob/main/apps/macos/Sources/Clawdbot/WebChatSwiftUI.swift) hosts `ClawdbotChatUI` and speaks to the Gateway over `GatewayConnection`.
+- Implementation: `apps/macos/Sources/Clawdbot/WebChatSwiftUI.swift` hosts `ClawdbotChatUI` and speaks to the Gateway over `GatewayConnection`.
 - Data plane: Gateway WebSocket methods `chat.history`, `chat.send`, `chat.abort`; events `chat`, `agent`, `presence`, `tick`, `health`.
 - Session: usually primary (`main`); multiple transports (WhatsApp/Telegram/Discord/Desktop) share the same key. The onboarding flow uses a dedicated `onboarding` session to keep first-run setup separate.

@@ -21,7 +21,7 @@ read_when:
 - UI automation uses a separate UNIX socket named `bridge.sock` and the PeekabooBridge JSON protocol.
 - Host preference order (client-side): Peekaboo.app → Claude.app → Clawdbot.app → local execution.
 - Security: bridge hosts require TeamID `Y5PE65HELJ`; DEBUG-only same-UID escape hatch is guarded by `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (Peekaboo convention).
- See: [`docs/mac/peekaboo.md`](https://docs.clawd.bot/mac/peekaboo) for the Clawdbot plan and naming.
+- See: `docs/mac/peekaboo.md` for the Clawdbot plan and naming.

 ### Mach/XPC (future direction)
 - Still optional for internal app services, but **not required** for automation now that node.invoke is the surface.
@@ -37,4 +37,4 @@ read_when:
 - Prefer requiring a TeamID match for all privileged surfaces.
 - PeekabooBridge: `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (DEBUG-only) may allow same-UID callers for local development.
 - All communication remains local-only; no network sockets are exposed.
- TCC prompts originate only from the GUI app bundle; run [`scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh) so the signed bundle ID stays stable.
+- TCC prompts originate only from the GUI app bundle; run `scripts/package-mac-app.sh` so the signed bundle ID stays stable.
@@ -13,7 +13,7 @@ Author: steipete · Status: draft spec · Date: 2025-12-20
  - Shows native notifications for Clawdbot/clawdbot events.
  - Owns TCC prompts (Notifications, Accessibility, Screen Recording, Automation/AppleScript, Microphone, Speech Recognition).
  - Runs (or connects to) the **Gateway** and exposes itself as a **node** so agents can reach macOS‑only features.
-  - Hosts **PeekabooBridge** for UI automation (consumed by `peekaboo`; see [`docs/mac/peekaboo.md`](https://docs.clawd.bot/mac/peekaboo)).
+  - Hosts **PeekabooBridge** for UI automation (consumed by `peekaboo`; see `docs/mac/peekaboo.md`).
  - Installs a single CLI (`clawdbot`) by symlinking the bundled binary.

 ## High-level design
@@ -79,7 +79,7 @@ Query parameters:
 - `sessionKey` (optional): explicit session key to use.
 - `thinking` (optional): thinking hint (e.g. `low`; omit for default).
 - `deliver` (optional): `true|false` (default: false).
- `to` / `provider` (optional): forwarded to the Gateway `agent` method (only meaningful with `deliver=true`).
+- `to` / `channel` (optional): forwarded to the Gateway `agent` method (only meaningful with `deliver=true`).
 - `timeoutSeconds` (optional): timeout hint forwarded to the Gateway.
 - `key` (optional): unattended mode key (see below).

@@ -96,7 +96,7 @@ Notes:
 ## Build & dev workflow (native)
 - `cd apps/macos && swift build` (debug) / `swift build -c release`.
 - Run app for dev: `swift run Clawdbot` (or Xcode scheme).
- Package app + CLI: [`scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh) (builds bun CLI + gateway).
+- Package app + CLI: `scripts/package-mac-app.sh` (builds bun CLI + gateway).
 - Tests: add Swift Testing suites under `apps/macos/Tests`.

 ## Open questions / decisions
@@ -13,25 +13,13 @@ Clawdbot handles failures in two stages:

 This doc explains the runtime rules and the data that backs them.

-## Auth storage (keys + OAuth)
-
-Clawdbot uses **auth profiles** for both API keys and OAuth tokens.
-
- Secrets live in `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` (legacy: `~/.clawdbot/agent/auth-profiles.json`).
- Config `auth.profiles` / `auth.order` are **metadata + routing only** (no secrets).
- Legacy import-only OAuth file: `~/.clawdbot/credentials/oauth.json` (imported into `auth-profiles.json` on first use).
-
-Credential types:
- `type: "api_key"` → `{ provider, key }`
- `type: "oauth"` → `{ provider, access, refresh, expires, email? }` (+ `projectId`/`enterpriseUrl` for some providers)
-
 ## Profile IDs

 OAuth logins create distinct profiles so multiple accounts can coexist.
 - Default: `provider:default` when no email is available.
 - OAuth with email: `provider:<email>` (for example `google-antigravity:user@gmail.com`).

-Profiles live in `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` under `profiles`.
+Profiles live in `~/.clawdbot/agent/auth-profiles.json` under `profiles`.

 ## Rotation order

@@ -42,16 +30,10 @@ When a provider has multiple profiles, Clawdbot chooses an order like this:
 3) **Stored profiles**: entries in `auth-profiles.json` for the provider.

 If no explicit order is configured, Clawdbot uses a round‑robin order:
- **Primary key:** profile type (**OAuth before API keys**).
- **Secondary key:** `usageStats.lastUsed` (oldest first, within each type).
+- **Primary key:** `usageStats.lastUsed` (oldest first).
+- **Secondary key:** profile type (OAuth before API keys).
 - **Cooldown profiles** are moved to the end, ordered by soonest cooldown expiry.

-### Why OAuth can “look lost”
-
-If you have both an OAuth profile and an API key profile for the same provider, round‑robin can switch between them across messages unless pinned. To force a single profile:
- Pin with `auth.order[provider] = ["provider:profileId"]`, or
- Use a per-session override via `/model …` with a profile override (when supported by your UI/chat surface).
-
 ## Cooldowns

 When a profile fails due to auth/rate‑limit errors (or a timeout that looks
@@ -85,9 +67,9 @@ timeouts that exhausted profile rotation.

 ## Related config

-See [`docs/configuration.md`](https://docs.clawd.bot/configuration) for:
+See `docs/configuration.md` for:
 - `auth.profiles` / `auth.order`
 - `agent.model.primary` / `agent.model.fallbacks`
 - `agent.imageModel` routing

-See [`docs/models.md`](https://docs.clawd.bot/models) for the broader model selection and fallback overview.
+See `docs/models.md` for the broader model selection and fallback overview.
@@ -7,8 +7,6 @@ read_when:
 ---
 # Models CLI plan

-See [`docs/model-failover.md`](https://docs.clawd.bot/model-failover) for how auth profiles rotate (OAuth vs API keys), cooldowns, and how that interacts with model fallbacks.
-
 Goal: give clear model visibility + control (configured vs available), plus scan tooling
 that prefers tool-call + image-capable models and maintains ordered fallbacks.

@@ -79,7 +77,7 @@ Output
 - Image routing uses `agent.imageModel` **only when configured** and the primary
  model lacks image input.
 - Persist last successful provider/model to session entry; auth profile success is global.
- See [`docs/model-failover.md`](https://docs.clawd.bot/model-failover) for auth profile rotation, cooldowns, and timeout handling.
+- See `docs/model-failover.md` for auth profile rotation, cooldowns, and timeout handling.

 ## Tests

@@ -89,5 +87,5 @@ Output

 ## Docs

- Update [`docs/configuration.md`](https://docs.clawd.bot/configuration) with `agent.models` + `agent.model` + `agent.imageModel`.
+- Update `docs/configuration.md` with `agent.models` + `agent.model` + `agent.imageModel`.
 - Keep this doc current when CLI surface or scan logic changes.
@@ -1,121 +0,0 @@
---
-summary: "Multi-agent routing: isolated agents, provider accounts, and bindings"
-title: Multi-Agent Routing
-read_when: "You want multiple isolated agents (workspaces + auth) in one gateway process."
-status: active
---
-
-# Multi-Agent Routing
-
-Goal: multiple *isolated* agents (separate workspace + `agentDir` + sessions), plus multiple provider accounts (e.g. two WhatsApps) in one running Gateway. Inbound is routed to an agent via bindings.
-
-## What is “one agent”?
-
-An **agent** is a fully scoped brain with its own:
-
- **Workspace** (files, AGENTS.md/SOUL.md/USER.md, local notes, persona rules).
- **State directory** (`agentDir`) for auth profiles, model registry, and per-agent config.
- **Session store** (chat history + routing state) under `~/.clawdbot/agents/<agentId>/sessions`.
-
-The Gateway can host **one agent** (default) or **many agents** side-by-side.
-
-### Single-agent mode (default)
-
-If you do nothing, Clawdbot runs a single agent:
-
- `agentId` defaults to **`main`**.
- Sessions are keyed as `agent:main:<mainKey>`.
- Workspace defaults to `~/clawd` (or `~/clawd-<profile>` when `CLAWDBOT_PROFILE` is set).
- State defaults to `~/.clawdbot/agents/main/agent`.
-
-## Multiple agents = multiple people, multiple personalities
-
-With **multiple agents**, each `agentId` becomes a **fully isolated persona**:
-
- **Different phone numbers/accounts** (per provider `accountId`).
- **Different personalities** (per-agent workspace files like `AGENTS.md` and `SOUL.md`).
- **Separate auth + sessions** (no cross-talk unless explicitly enabled).
-
-This lets **multiple people** share one Gateway server while keeping their AI “brains” and data isolated.
-
-## Routing rules (how messages pick an agent)
-
-Bindings are **deterministic** and **most-specific wins**:
-
-1. `peer` match (exact DM/group/channel id)
-2. `guildId` (Discord)
-3. `teamId` (Slack)
-4. `accountId` match for a provider
-5. provider-level match (`accountId: "*"`)
-6. fallback to `routing.defaultAgentId` (default: `main`)
-
-## Multiple accounts / phone numbers
-
-Providers that support **multiple accounts** (e.g. WhatsApp) use `accountId` to identify
-each login. Each `accountId` can be routed to a different agent, so one server can host
-multiple phone numbers without mixing sessions.
-
-## Concepts
-
- `agentId`: one “brain” (workspace, per-agent auth, per-agent session store).
- `accountId`: one provider account instance (e.g. WhatsApp account `"personal"` vs `"biz"`).
- `binding`: routes inbound messages to an `agentId` by `(provider, accountId, peer)` and optionally guild/team ids.
- Direct chats collapse to `agent:<agentId>:<mainKey>` (per-agent “main”; `session.mainKey`).
-
-## Example: two WhatsApps → two agents
-
-`~/.clawdbot/clawdbot.json` (JSON5):
-
-```js
-{
-  routing: {
-    defaultAgentId: "home",
-
-    agents: {
-      home: {
-        workspace: "~/clawd-home",
-        agentDir: "~/.clawdbot/agents/home/agent",
-      },
-      work: {
-        workspace: "~/clawd-work",
-        agentDir: "~/.clawdbot/agents/work/agent",
-      },
-    },
-
-    // Deterministic routing: first match wins (most-specific first).
-    bindings: [
-      { agentId: "home", match: { provider: "whatsapp", accountId: "personal" } },
-      { agentId: "work", match: { provider: "whatsapp", accountId: "biz" } },
-
-      // Optional per-peer override (example: send a specific group to work agent).
-      {
-        agentId: "work",
-        match: {
-          provider: "whatsapp",
-          accountId: "personal",
-          peer: { kind: "group", id: "1203630...@g.us" },
-        },
-      },
-    ],
-
-    // Off by default: agent-to-agent messaging must be explicitly enabled + allowlisted.
-    agentToAgent: {
-      enabled: false,
-      allow: ["home", "work"],
-    },
-  },
-
-  whatsapp: {
-    accounts: {
-      personal: {
-        // Optional override. Default: ~/.clawdbot/credentials/whatsapp/personal
-        // authDir: "~/.clawdbot/credentials/whatsapp/personal",
-      },
-      biz: {
-        // Optional override. Default: ~/.clawdbot/credentials/whatsapp/biz
-        // authDir: "~/.clawdbot/credentials/whatsapp/biz",
-      },
-    },
-  },
-}
-```
@@ -84,12 +84,12 @@ The macOS packaging flow expects a stable Info.plist template at:
 apps/macos/Sources/Clawdbot/Resources/Info.plist
 ```

-[`scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh) copies this template into the app bundle and patches dynamic fields
+`scripts/package-mac-app.sh` copies this template into the app bundle and patches dynamic fields
 (bundle ID, version/build, Git SHA, Sparkle keys). This keeps the plist deterministic for SwiftPM
 packaging and Nix builds (which do not rely on a full Xcode toolchain).

 ## Related

 - [nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) — full setup guide
- [Wizard](https://docs.clawd.bot/wizard) — non-Nix CLI setup
- [Docker](https://docs.clawd.bot/docker) — containerized setup
+- [Wizard](./wizard.md) — non-Nix CLI setup
+- [Docker](./docker.md) — containerized setup
@@ -14,7 +14,7 @@ macOS can also run in **node mode**: the menubar app connects to the Gateway’s

 ## Pairing + status

-Pairing is gateway-owned and approval-based. See [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing) for the full flow.
+Pairing is gateway-owned and approval-based. See `docs/gateway/pairing.md` for the full flow.

 Quick CLI:

@@ -150,8 +150,8 @@ Nodes may include a `permissions` map in `node.list` / `node.describe`, keyed by

 ## Where to look in code

- CLI wiring: [`src/cli/nodes-cli.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/nodes-cli.ts)
- Canvas snapshot decoding/temp paths: [`src/cli/nodes-canvas.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/nodes-canvas.ts)
- Duration parsing for CLI: [`src/cli/parse-duration.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/parse-duration.ts)
- iOS node commands: [`apps/ios/Sources/Model/NodeAppModel.swift`](https://github.com/clawdbot/clawdbot/blob/main/apps/ios/Sources/Model/NodeAppModel.swift)
+- CLI wiring: `src/cli/nodes-cli.ts`
+- Canvas snapshot decoding/temp paths: `src/cli/nodes-canvas.ts`
+- Duration parsing for CLI: `src/cli/parse-duration.ts`
+- iOS node commands: `apps/ios/Sources/Model/NodeAppModel.swift`
 - Android node commands: `apps/android/app/src/main/java/com/clawdbot/android/node/*`
@@ -9,7 +9,7 @@ Purpose: shared onboarding + config surfaces across CLI, macOS app, and Web UI.

 ## Components
 - Wizard engine: `src/wizard` (session + prompts + onboarding state).
- CLI: [`src/commands/onboard-*.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/commands/onboard-*.ts) uses the wizard with the CLI prompter.
+- CLI: `src/commands/onboard-*.ts` uses the wizard with the CLI prompter.
 - Gateway RPC: wizard + config schema endpoints serve UI clients.
 - macOS: SwiftUI onboarding uses the wizard step model.
 - Web UI: config form renders from JSON Schema + hints.
@@ -41,7 +41,7 @@ The macOS app should:
  - `~/.clawdbot/credentials/oauth.json` (file mode `0600`, directory mode `0700`)

 Why this location matters: it’s the Clawdbot-owned OAuth store.
-Clawdbot also imports `oauth.json` into the agent auth profile store (`~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`) on first use.
+Clawdbot also imports `oauth.json` into the agent auth profile store (`~/.clawdbot/agent/auth-profiles.json`) on first use.

 ### Recommended: OAuth (OpenAI Codex)

@@ -149,7 +149,7 @@ If the Gateway runs on another machine, OAuth credentials must be created/stored

 For now, remote onboarding should:
 - explain why OAuth isn't shown
- point the user at the credential location (`~/.clawdbot/credentials/oauth.json`) and the auth profile store (`~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`) on the gateway host
+- point the user at the credential location (`~/.clawdbot/credentials/oauth.json`) and the auth profile store (`~/.clawdbot/agent/auth-profiles.json`) on the gateway host
 - mention that the **bootstrap ritual happens on the gateway host** (same BOOTSTRAP/IDENTITY/USER files)

 ### Manual credential setup
@@ -1,85 +0,0 @@
---
-summary: "Pairing overview: approve who can DM you + which nodes can join"
-read_when:
-  - Setting up DM access control
-  - Pairing a new iOS/Android node
-  - Reviewing Clawdbot security posture
---
-
-# Pairing
-
-“Pairing” is Clawdbot’s explicit **owner approval** step.
-It is used in two places:
-
-1) **DM pairing** (who is allowed to talk to the bot)
-2) **Node pairing** (which devices/nodes are allowed to join the gateway network)
-
-Security context: https://docs.clawd.bot/security
-
-## 1) DM pairing (inbound chat access)
-
-When a provider is configured with DM policy `pairing`, unknown senders get a short code and their message is **not processed** until you approve.
-
-Default DM policies are documented in: https://docs.clawd.bot/security
-
-### Approve a sender
-
-```bash
-clawdbot pairing list --provider telegram
-clawdbot pairing approve --provider telegram <CODE>
-```
-
-Supported providers: `telegram`, `whatsapp`, `signal`, `imessage`, `discord`, `slack`.
-
-### Where the state lives
-
-Stored under `~/.clawdbot/credentials/`:
- Pending requests: `<provider>-pairing.json`
- Approved allowlist store: `<provider>-allowFrom.json`
-
-Treat these as sensitive (they gate access to your assistant).
-
-### Source of truth (code)
-
- DM pairing storage + code generation: [`src/pairing/pairing-store.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/pairing/pairing-store.ts)
- CLI commands: [`src/cli/pairing-cli.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/pairing-cli.ts)
-
-## 2) Node pairing (iOS/Android nodes joining the gateway)
-
-Nodes (iOS/Android, future hardware, etc.) connect to the Gateway and request to join.
-The Gateway keeps an authoritative allowlist; new nodes require explicit approve/reject.
-
-### Approve a node
-
-```bash
-clawdbot nodes pending
-clawdbot nodes approve <requestId>
-```
-
-### Where the state lives
-
-Stored under `~/.clawdbot/nodes/`:
- `pending.json` (short-lived; pending requests expire)
- `paired.json` (paired nodes + tokens)
-
-### Details
-
-Full protocol + design notes: https://docs.clawd.bot/gateway/pairing
-
-### Source of truth (code)
-
- Node pairing store (pending/paired + token issuance): [`src/infra/node-pairing.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/node-pairing.ts)
- Gateway methods/events (`node.pair.*`): [`src/gateway/server-methods/nodes.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server-methods/nodes.ts)
- CLI: [`src/cli/nodes-cli.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/nodes-cli.ts)
-
-## Related docs
-
- Security model + prompt injection: https://docs.clawd.bot/security
- Updating safely (run doctor): https://docs.clawd.bot/updating
- Provider configs:
-  - Telegram: https://docs.clawd.bot/telegram
-  - WhatsApp: https://docs.clawd.bot/whatsapp
-  - Signal: https://docs.clawd.bot/signal
-  - iMessage: https://docs.clawd.bot/imessage
-  - Discord: https://docs.clawd.bot/discord
-  - Slack: https://docs.clawd.bot/slack
@@ -8,11 +8,11 @@ last_updated: "2026-01-05"
 # Cron Add Hardening & Schema Alignment

 ## Context
-Recent gateway logs show repeated `cron.add` failures with invalid parameters (missing `sessionTarget`, `wakeMode`, `payload`, and malformed `schedule`). This indicates that at least one client (likely the agent tool call path) is sending wrapped or partially specified job payloads. Separately, there is drift between cron provider enums in TypeScript, gateway schema, CLI flags, and UI form types, plus a UI mismatch for `cron.status` (expects `jobCount` while gateway returns `jobs`).
+Recent gateway logs show repeated `cron.add` failures with invalid parameters (missing `sessionTarget`, `wakeMode`, `payload`, and malformed `schedule`). This indicates that at least one client (likely the agent tool call path) is sending wrapped or partially specified job payloads. Separately, there is drift between cron channel enums in TypeScript, gateway schema, CLI flags, and UI form types, plus a UI mismatch for `cron.status` (expects `jobCount` while gateway returns `jobs`).

 ## Goals
 - Stop `cron.add` INVALID_REQUEST spam by normalizing common wrapper payloads and inferring missing `kind` fields.
- Align cron provider lists across gateway schema, cron types, CLI docs, and UI forms.
+- Align cron channel lists across gateway schema, cron types, CLI docs, and UI forms.
 - Make agent cron tool schema explicit so the LLM produces correct job payloads.
 - Fix the Control UI cron status job count display.
 - Add tests to cover normalization and tool behavior.
@@ -31,19 +31,19 @@ Recent gateway logs show repeated `cron.add` failures with invalid parameters (m
 ## Proposed Approach
 1. **Normalize** incoming `cron.add` payloads (unwrap `data`/`job`, infer `schedule.kind` and `payload.kind`, default `wakeMode` + `sessionTarget` when safe).
 2. **Harden** the agent cron tool schema using the canonical gateway `CronAddParamsSchema` and normalize before sending to the gateway.
-3. **Align** provider enums and cron status fields across gateway schema, TS types, CLI descriptions, and UI form controls.
+3. **Align** channel enums and cron status fields across gateway schema, TS types, CLI descriptions, and UI form controls.
 4. **Test** normalization in gateway tests and tool behavior in agent tests.

 ## Multi-phase Execution Plan

 ### Phase 1 — Schema + type alignment
- [x] Expand gateway `CronPayloadSchema` provider enum to include `signal` and `imessage`.
- [x] Update CLI `--provider` descriptions to include `slack` (already supported by gateway).
- [x] Update UI Cron payload/provider union types to include all supported providers.
+- [x] Expand gateway `CronPayloadSchema` channel enum to include `signal` and `imessage`.
+- [x] Update CLI `--channel` descriptions to include `slack` (already supported by gateway).
+- [x] Update UI Cron payload/channel union types to include all supported channels.
 - [x] Fix UI CronStatus type to match gateway (`jobs` instead of `jobCount`).
- [x] Update cron UI provider select to include Discord/Slack/Signal/iMessage.
- [x] Update macOS CronJobEditor provider picker + enum to include Slack/Signal/iMessage.
- [x] Document cron compatibility normalization policy in [`docs/cron.md`](https://docs.clawd.bot/cron).
+- [x] Update cron UI channel select to include Discord/Slack/Signal/iMessage.
+- [x] Update macOS CronJobEditor channel picker + enum to include Slack/Signal/iMessage.
+- [x] Document cron compatibility normalization policy in `docs/cron.md`.

 ### Phase 2 — Input normalization + tooling hardening
 - [x] Add shared cron input normalization helpers (`normalizeCronJobCreate`/`normalizeCronJobPatch`).
@@ -65,8 +65,8 @@ Recent gateway logs show repeated `cron.add` failures with invalid parameters (m
 - If errors persist, extend normalization for additional common shapes (e.g., `schedule.at`, `payload.message` without `kind`).

 ## Optional Follow-ups
- Manual Control UI smoke: add cron job per provider + verify status job count.
+- Manual Control UI smoke: add cron job per channel + verify status job count.

 ## Open Questions
 - Should `cron.add` accept explicit `state` from clients (currently disallowed by schema)?
- Should we allow `webchat` as an explicit delivery provider (currently filtered in delivery resolution)?
+- Should we allow `webchat` as an explicit delivery channel (currently filtered in delivery resolution)?
@@ -1,8 +1,3 @@
---
-summary: "Spec: groupPolicy hardening for Telegram allowlist parity"
-read_when:
-  - Reviewing historical Telegram allowlist normalization changes
---
 # Engineering Execution Spec: groupPolicy Hardening (Telegram Allowlist Parity)

 **Date**: 2026-01-05  
@@ -21,7 +16,7 @@ Follow-up hardening work ensures Telegram allowlists behave consistently across

 ### [MED] F1: Telegram Allowlist Prefix Handling Is Case-Sensitive and Excludes `tg:`

-**Location**: [`src/telegram/bot.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/telegram/bot.ts)
+**Location**: `src/telegram/bot.ts`

 **Problem**: Inbound allowlist normalization only stripped a lowercase `telegram:` prefix. This rejected `TG:123` / `Telegram:123` and did not accept the `tg:` shorthand even though outbound send normalization already accepts `tg:` and case-insensitive prefixes.

@@ -35,7 +30,7 @@ Follow-up hardening work ensures Telegram allowlists behave consistently across

 ### [LOW] F2: Allowlist Entries Are Not Trimmed

-**Location**: [`src/telegram/bot.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/telegram/bot.ts)
+**Location**: `src/telegram/bot.ts`

 **Problem**: Allowlist entries are not trimmed; accidental whitespace causes mismatches.

@@ -47,7 +42,7 @@ Follow-up hardening work ensures Telegram allowlists behave consistently across

 ### Phase 1: Normalize Telegram Allowlist Inputs

-**File**: [`src/telegram/bot.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/telegram/bot.ts)
+**File**: `src/telegram/bot.ts`

 **Changes**:
 1. Trim allowlist entries and drop empty values.
@@ -58,7 +53,7 @@ Follow-up hardening work ensures Telegram allowlists behave consistently across

 ### Phase 2: Add Coverage for Prefix + Whitespace

-**File**: [`src/telegram/bot.test.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/telegram/bot.test.ts)
+**File**: `src/telegram/bot.test.ts`

 **Add Tests**:
 - DM allowlist accepts `TG:` prefix with surrounding whitespace.
@@ -69,8 +64,8 @@ Follow-up hardening work ensures Telegram allowlists behave consistently across
 ### Phase 3: Documentation Updates

 **Files**:
- [`docs/groups.md`](https://docs.clawd.bot/groups)
- [`docs/telegram.md`](https://docs.clawd.bot/telegram)
+- `docs/groups.md`
+- `docs/telegram.md`

 **Changes**:
 - Document `tg:` alias and case-insensitive prefixes for Telegram allowlists.
@@ -88,10 +83,10 @@ Follow-up hardening work ensures Telegram allowlists behave consistently across

 | File | Change Type | Description |
 |------|-------------|-------------|
-| [`src/telegram/bot.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/telegram/bot.ts) | Fix | Trim allowlist values; strip `telegram:` / `tg:` prefixes case-insensitively |
-| [`src/telegram/bot.test.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/telegram/bot.test.ts) | Test | Add DM + group allowlist coverage for `TG:` prefix + whitespace |
-| [`docs/groups.md`](https://docs.clawd.bot/groups) | Docs | Mention `tg:` alias + case-insensitive prefixes |
-| [`docs/telegram.md`](https://docs.clawd.bot/telegram) | Docs | Mention `tg:` alias + case-insensitive prefixes |
+| `src/telegram/bot.ts` | Fix | Trim allowlist values; strip `telegram:` / `tg:` prefixes case-insensitively |
+| `src/telegram/bot.test.ts` | Test | Add DM + group allowlist coverage for `TG:` prefix + whitespace |
+| `docs/groups.md` | Docs | Mention `tg:` alias + case-insensitive prefixes |
+| `docs/telegram.md` | Docs | Mention `tg:` alias + case-insensitive prefixes |

 ---

@@ -36,7 +36,7 @@ Presence entries are produced by multiple sources and then **merged**.

 The Gateway seeds a “self” entry at startup so UIs always show at least the current gateway host.

-Implementation: [`src/infra/system-presence.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/system-presence.ts) (`initSelfPresence()`).
+Implementation: `src/infra/system-presence.ts` (`initSelfPresence()`).

 ### 2) WebSocket connect (connection-derived presence)

@@ -44,7 +44,7 @@ Every WS client must begin with a `connect` request. On successful handshake, th

 This is meant to answer: “Which clients are currently connected?”

-Implementation: [`src/gateway/server.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server.ts) (connect handling uses `connect.params.client.instanceId` when provided; otherwise falls back to `connId`).
+Implementation: `src/gateway/server.ts` (connect handling uses `connect.params.client.instanceId` when provided; otherwise falls back to `connId`).

 #### Why one-off CLI commands do not show up

@@ -58,8 +58,8 @@ Clients can publish richer periodic beacons via the `system-event` method. The m
 - `lastInputSeconds`

 Implementation:
- Gateway: [`src/gateway/server.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server.ts) handles method `system-event` by calling `updateSystemPresence(...)`.
- mac app beaconing: [`apps/macos/Sources/Clawdbot/PresenceReporter.swift`](https://github.com/clawdbot/clawdbot/blob/main/apps/macos/Sources/Clawdbot/PresenceReporter.swift).
+- Gateway: `src/gateway/server.ts` handles method `system-event` by calling `updateSystemPresence(...)`.
+- mac app beaconing: `apps/macos/Sources/Clawdbot/PresenceReporter.swift`.

 ### 4) Node bridge beacons (gateway-owned presence)

@@ -69,7 +69,7 @@ for that node and starts periodic refresh beacons so it does not expire.
 - Connect/disconnect markers: `node-connected`, `node-disconnected`
 - Periodic heartbeat: every 3 minutes (`reason: periodic`)

-Implementation: [`src/gateway/server.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server.ts) (node bridge handlers + timer beacons).
+Implementation: `src/gateway/server.ts` (node bridge handlers + timer beacons).

 ## Merge + dedupe rules (why `instanceId` matters)

@@ -80,7 +80,7 @@ Key points:
 - The best key is a stable, opaque `instanceId` that does not change across restarts.
 - Keys are treated case-insensitively.

-Implementation: [`src/infra/system-presence.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/system-presence.ts) (`normalizePresenceKey()`).
+Implementation: `src/infra/system-presence.ts` (`normalizePresenceKey()`).

 ### mac app identity (stable UUID)

@@ -89,7 +89,7 @@ The mac app uses a persisted UUID as `instanceId` so:
 - renaming the Mac does not create a new “instance”
 - debug/release builds can share the same identity

-Implementation: [`apps/macos/Sources/Clawdbot/InstanceIdentity.swift`](https://github.com/clawdbot/clawdbot/blob/main/apps/macos/Sources/Clawdbot/InstanceIdentity.swift).
+Implementation: `apps/macos/Sources/Clawdbot/InstanceIdentity.swift`.

 `displayName` (machine name) is used for UI, while `instanceId` is used for dedupe.

@@ -99,7 +99,7 @@ Presence entries are not permanent:
 - TTL: entries older than 5 minutes are pruned
 - Max: map is capped at 200 entries (LRU by `ts`)

-Implementation: [`src/infra/system-presence.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/system-presence.ts) (`TTL_MS`, `MAX_ENTRIES`, pruning in `listSystemPresence()`).
+Implementation: `src/infra/system-presence.ts` (`TTL_MS`, `MAX_ENTRIES`, pruning in `listSystemPresence()`).

 ## Remote/tunnel caveat (loopback IPs)

@@ -107,7 +107,7 @@ When a client connects over an SSH tunnel / local port forward, the Gateway may

 To avoid degrading an otherwise-correct client beacon IP, the Gateway avoids writing loopback remote addresses into presence entries.

-Implementation: [`src/gateway/server.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server.ts) (`isLoopbackAddress()`).
+Implementation: `src/gateway/server.ts` (`isLoopbackAddress()`).

 ## Consumers (who reads presence)

@@ -116,8 +116,8 @@ Implementation: [`src/gateway/server.ts`](https://github.com/clawdbot/clawdbot/b
 The mac app’s Instances tab renders the result of `system-presence`.

 Implementation:
- View: [`apps/macos/Sources/Clawdbot/InstancesSettings.swift`](https://github.com/clawdbot/clawdbot/blob/main/apps/macos/Sources/Clawdbot/InstancesSettings.swift)
- Store: [`apps/macos/Sources/Clawdbot/InstancesStore.swift`](https://github.com/clawdbot/clawdbot/blob/main/apps/macos/Sources/Clawdbot/InstancesStore.swift)
+- View: `apps/macos/Sources/Clawdbot/InstancesSettings.swift`
+- Store: `apps/macos/Sources/Clawdbot/InstancesStore.swift`

 The Instances rows show a small presence indicator (Active/Idle/Stale) based on
 the last beacon age. The label is derived from the entry timestamp (`ts`).
@@ -1,25 +0,0 @@
---
-summary: "Routing rules per provider (WhatsApp, Telegram, Discord, web) and shared context"
-read_when:
-  - Changing provider routing or inbox behavior
---
-# Providers & Routing
-
-Updated: 2026-01-06
-
-Goal: deterministic replies per provider, while supporting multi-agent + multi-account routing.
-
- **Provider**: provider label (`whatsapp`, `webchat`, `telegram`, `discord`, `signal`, `imessage`, …). Routing is fixed: replies go back to the origin provider; the model doesn’t choose.
- **AccountId**: provider account instance (e.g. WhatsApp account `"default"` vs `"work"`). Not every provider supports multi-account yet.
- **AgentId**: one isolated “brain” (workspace + per-agent agentDir + per-agent session store).
- **Reply context:** inbound replies include `ReplyToId`, `ReplyToBody`, and `ReplyToSender`, and the quoted context is appended to `Body` as a `[Replying to ...]` block.
- **Canonical direct session (per agent):** direct chats collapse to `agent:<agentId>:<mainKey>` (default `main`). Groups/channels stay isolated per agent:
-  - group: `agent:<agentId>:<provider>:group:<id>`
-  - channel/room: `agent:<agentId>:<provider>:channel:<id>`
- **Session store:** per-agent store lives under `~/.clawdbot/agents/<agentId>/sessions/sessions.json` (override via `session.store` with `{agentId}` templating). JSONL transcripts live next to it.
- **WebChat:** attaches to the selected agent’s main session (so desktop reflects cross-provider history for that agent).
- **Implementation hints:**
-  - Set `Provider` + `AccountId` in each ingress.
-  - Route inbound to an agent via `routing.bindings` (match on `provider`, `accountId`, plus optional peer/guild/team).
-  - Keep routing deterministic: originate → same provider. Use the gateway WebSocket for sends; avoid side channels.
-  - Do not let the agent emit “send to X” decisions; keep that policy in the host code.
@@ -12,13 +12,13 @@ We now serialize command-based auto-replies (WhatsApp Web listener) through a ti
 - Serializing avoids competing for terminal/stdin, keeps logs readable, and reduces the chance of rate limits from upstream tools.

 ## How it works
- [`src/process/command-queue.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/process/command-queue.ts) holds a lane-aware FIFO queue and drains each lane synchronously.
+- `src/process/command-queue.ts` holds a lane-aware FIFO queue and drains each lane synchronously.
 - `runEmbeddedPiAgent` enqueues by **session key** (lane `session:<key>`) to guarantee only one active run per session.
 - Each session run is then queued into a **global lane** (`main` by default) so overall parallelism is capped by `agent.maxConcurrent`.
 - When verbose logging is enabled, queued commands emit a short notice if they waited more than ~2s before starting.
 - Typing indicators (`onReplyStart`) still fire immediately on enqueue so user experience is unchanged while we wait our turn.

-## Queue modes (per provider)
+## Queue modes (per surface)
 Inbound messages can steer the current run, wait for a followup turn, or do both:
 - `steer`: inject immediately into the current run (cancels pending tool calls after the next tool boundary). If not streaming, falls back to followup.
 - `followup`: enqueue for the next agent turn after the current run ends.
@@ -30,12 +30,12 @@ Inbound messages can steer the current run, wait for a followup turn, or do both
 Steer-backlog means you can get a followup response after the steered run, so
 streaming surfaces can look like duplicates. Prefer `collect`/`steer` if you want
 one response per inbound message.
-Send `/queue collect` as a standalone command (per-session) or set `routing.queue.byProvider.discord: "collect"`.
+Inline fix: `/queue collect` (per-session) or set `routing.queue.bySurface.discord: "collect"`.

 Defaults (when unset in config):
 - All surfaces → `collect`

-Configure globally or per provider via `routing.queue`:
+Configure globally or per surface via `routing.queue`:

 ```json5
 {
@@ -45,7 +45,7 @@ Configure globally or per provider via `routing.queue`:
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
-      byProvider: { discord: "collect" }
+      bySurface: { discord: "collect" }
    }
  }
 }
@@ -61,7 +61,8 @@ Summarize keeps a short bullet list of dropped messages and injects it as a synt
 Defaults: `debounceMs: 1000`, `cap: 20`, `drop: summarize`.

 ## Per-session overrides
- Send `/queue <mode>` as a standalone command to store the mode for the current session.
+- `/queue <mode>` as a standalone command stores the mode for the current session.
+- `/queue <mode>` embedded in a message applies **once** (no persistence).
 - Options can be combined: `/queue collect debounce:2s cap:25 drop:summarize`
 - `/queue default` or `/queue reset` clears the session override.

@@ -108,7 +108,7 @@ Save this as `~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist`:
 ### Load the Launch Agent

 ```bash
-launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist
+launchctl load ~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist
 ```

 The tunnel will now:
@@ -130,13 +130,13 @@ lsof -i :18789
 **Restart the tunnel:**

 ```bash
-launchctl kickstart -k gui/$UID/com.clawdbot.ssh-tunnel
+launchctl restart com.clawdbot.ssh-tunnel
 ```

 **Stop the tunnel:**

 ```bash
-launchctl bootout gui/$UID/com.clawdbot.ssh-tunnel
+launchctl unload ~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist
 ```

 ---
@@ -8,7 +8,7 @@ read_when:
 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.

 - 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 [`docs/discovery.md`](https://docs.clawd.bot/discovery)).
+- For **nodes (iOS/Android and future devices)**: prefer the Gateway **Bridge** when on the same LAN/tailnet (see `docs/discovery.md`).

 ## The core idea

@@ -58,4 +58,9 @@ WebChat no longer uses a separate HTTP port. The SwiftUI chat UI connects direct

 The macOS menu bar app can drive the same setup end-to-end (remote status checks, WebChat, and Voice Wake forwarding).

-Runbook: [`docs/mac/remote.md`](https://docs.clawd.bot/mac/remote).
+Runbook: `docs/mac/remote.md`.
+
+## Legacy control channel
+
+Older builds experimented with a newline-delimited TCP control channel on the same port.
+That API is deprecated and should not be relied on. (Historical reference: `docs/control-api.md`.)
@@ -172,7 +172,7 @@ Recommendation: **deep integration in Clawdbot**, but keep a separable core libr

 Shape:
 - `src/memory/*` (library-ish core; pure functions + sqlite adapter)
- [`src/commands/memory/*.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/commands/memory/*.ts) (CLI glue)
+- `src/commands/memory/*.ts` (CLI glue)

 ## “S-Collide” / SuCo: when to use it (research)

@@ -14,7 +14,7 @@ Clawdbot integrates external CLIs via JSON-RPC. Two patterns are used today.
 - Health probe: `/api/v1/check`.
 - Clawdbot owns lifecycle when `signal.autoStart=true`.

-See [`docs/signal.md`](https://docs.clawd.bot/signal) for setup and endpoints.
+See `docs/signal.md` for setup and endpoints.

 ## Pattern B: stdio child process (imsg)
 - Clawdbot spawns `imsg rpc` as a child process.
@@ -27,7 +27,7 @@ Core methods used:
 - `send`
 - `chats.list` (probe/diagnostics)

-See [`docs/imessage.md`](https://docs.clawd.bot/imessage) for setup and addressing (`chat_id` preferred).
+See `docs/imessage.md` for setup and addressing (`chat_id` preferred).

 ## Adapter guidelines
 - Gateway owns the process (start/stop tied to provider lifecycle).
@@ -5,12 +5,7 @@ read_when:
 ---
 # Security 🔒

-Running an AI agent with shell access on your machine is... *spicy*. Here’s how to not get pwned.
-
-Clawdbot is both a product and an experiment: you’re wiring frontier-model behavior into real messaging surfaces and real tools. **There is no “perfectly secure” setup.** The goal is to be deliberate about:
- who can talk to your bot
- where the bot is allowed to act
- what the bot can touch
+Running an AI agent with shell access on your machine is... *spicy*. Here's how to not get pwned.

 ## The Threat Model

@@ -25,57 +20,6 @@ People who message you can:
 - Social engineer access to your data
 - Probe for infrastructure details

-## Core concept: access control before intelligence
-
-Most failures here are not fancy exploits — they’re “someone messaged the bot and the bot did what they asked.”
-
-Clawdbot’s stance:
- **Identity first:** decide who can talk to the bot (DM pairing / allowlists / explicit “open”).
- **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.
-
-## 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:
-
- `pairing` (default): unknown senders receive a short pairing code and the bot ignores their message until approved.
- `allowlist`: unknown senders are blocked (no pairing handshake).
- `open`: allow anyone to DM (public). **Requires** the provider allowlist to include `"*"` (explicit opt-in).
- `disabled`: ignore inbound DMs entirely.
-
-Approve via CLI:
-
-```bash
-clawdbot pairing list --provider <provider>
-clawdbot pairing approve --provider <provider> <code>
-```
-
-Details + files on disk: https://docs.clawd.bot/pairing
-
-## Allowlists (DM + groups) — terminology
-
-Clawdbot has two separate “who can trigger me?” layers:
-
- **DM allowlist** (`allowFrom` / `discord.dm.allowFrom` / `slack.dm.allowFrom`): who is allowed to talk to the bot in direct messages.
-  - When `dmPolicy="pairing"`, approvals are written to `~/.clawdbot/credentials/<provider>-allowFrom.json` (merged with config allowlists).
- **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).
-    - `discord.guilds` / `slack.channels`: per-surface allowlists + mention defaults.
-
-Details: https://docs.clawd.bot/configuration and https://docs.clawd.bot/groups
-
-## Prompt injection (what it is, why it matters)
-
-Prompt injection is when an attacker crafts a message that manipulates the model into doing something unsafe (“ignore your instructions”, “dump your filesystem”, “follow this link and run commands”, etc.).
-
-Even with strong system prompts, **prompt injection is not solved**. What helps in practice:
- Keep inbound DMs locked down (pairing/allowlists).
- Prefer mention gating in groups; avoid “always-on” bots in public rooms.
- Treat links and pasted instructions as hostile by default.
- Run sensitive tool execution in a sandbox; keep secrets out of the agent’s reachable filesystem.
-
 ## Lessons Learned (The Hard Way)

 ### The `find ~` Incident 🦞
@@ -92,17 +36,21 @@ This is social engineering 101. Create distrust, encourage snooping.

 **Lesson:** Don't let strangers (or friends!) manipulate your AI into exploring the filesystem.

-## Configuration Hardening (examples)
+## Configuration Hardening

-### 1) DMs: pairing by default
+### 1. Allowlist Senders

-```json5
+```json
 {
-  whatsapp: { dmPolicy: "pairing" }
+  "whatsapp": {
+    "allowFrom": ["+15555550123"]
+  }
 }
 ```

-### 2) Groups: require mention everywhere
+Only allow specific phone numbers to trigger your AI. Never use `["*"]` in production.
+
+### 2. Group Chat Mentions

 ```json
 {
@@ -134,14 +82,34 @@ We're considering a `readOnlyMode` flag that prevents the AI from:
 - Executing shell commands
 - Sending messages

-## Sandboxing (recommended)
+## Container Isolation (Recommended)

-Two complementary approaches:
+For maximum security, run CLAWDBOT in a container with limited access:

- **Run the full Gateway in Docker** (container boundary): https://docs.clawd.bot/docker
- **Per-session tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): https://docs.clawd.bot/configuration
+```yaml
+# docker-compose.yml
+services:
+  clawdbot:
+    build: .
+    volumes:
+      - ./clawd-sandbox:/home/clawd  # Limited filesystem
+      - /tmp/clawdbot:/tmp/clawdbot    # Logs
+    environment:
+      - CLAWDBOT_SANDBOX=true
+    network_mode: bridge  # Limited network
+```

-Important: `agent.elevated` is an explicit escape hatch that runs bash on the host. Keep `agent.elevated.allowFrom` tight and don’t enable it for strangers.
+### Per-session sandbox (Clawdbot-native)
+
+Clawdbot can also run **non-main sessions** inside per-session Docker containers
+(`agent.sandbox`). This keeps the gateway on your host while isolating agent
+tools in a hard wall container. See `docs/configuration.md` for the full config.
+
+Expose only the services your AI needs:
+- ✅ GoWA API (for WhatsApp)
+- ✅ Specific HTTP APIs
+- ❌ Raw shell access to host
+- ❌ Full filesystem

 ## What to Tell Your AI

@@ -162,7 +130,7 @@ If your AI does something bad:

 1. **Stop it:** stop the macOS app (if it’s supervising the Gateway) or terminate your `clawdbot gateway` process
 2. **Check logs:** `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (or your configured `logging.file`)
-3. **Review session:** Check `~/.clawdbot/agents/<agentId>/sessions/` for what happened
+3. **Review session:** Check `~/.clawdbot/sessions/` for what happened
 4. **Rotate secrets:** If credentials were exposed
 5. **Update rules:** Add to your security prompt

@@ -189,7 +157,7 @@ Mario asking for find ~

 Found a vulnerability in CLAWDBOT? Please report responsibly:

-1. Email: security@clawd.bot
+1. Email: security@[redacted].com
 2. Don't post publicly until fixed
 3. We'll credit you (unless you prefer anonymity)

@@ -6,7 +6,7 @@ read_when:

 # Session Tools

-Goal: small, hard-to-misuse tool set so agents can list sessions, fetch history, and send to another session.
+Goal: small, hard-to-misuse tool surface so agents can list sessions, fetch history, and send to another session.

 ## Tool Names
 - `sessions_list`
@@ -16,7 +16,7 @@ Goal: small, hard-to-misuse tool set so agents can list sessions, fetch history,

 ## Key Model
 - Main direct chat bucket is always the literal key `"main"`.
- Group chats use `<provider>:group:<id>` or `<provider>:channel:<id>`.
+- Group chats use `surface:group:<id>` or `surface:channel:<id>`.
 - Cron jobs use `cron:<job.id>`.
 - Hooks use `hook:<uuid>` unless explicitly set.
 - Node bridge uses `node-<nodeId>` unless explicitly set.
@@ -47,7 +47,7 @@ Row shape (JSON):
 - `model`, `contextTokens`, `totalTokens`
 - `thinkingLevel`, `verboseLevel`, `systemSent`, `abortedLastRun`
 - `sendPolicy` (session override if set)
- `lastProvider`, `lastTo`
+- `lastChannel`, `lastTo`
 - `transcriptPath` (best-effort path derived from store dir + sessionId)
 - `messages?` (only when `messageLimit > 0`)

@@ -84,17 +84,17 @@ Behavior:
  - Max turns is `session.agentToAgent.maxPingPongTurns` (0–5, default 5).
 - Once the loop ends, Clawdbot runs the **agent‑to‑agent announce step** (target agent only):
  - Reply exactly `ANNOUNCE_SKIP` to stay silent.
-  - Any other reply is sent to the target provider.
+  - Any other reply is sent to the target channel.
  - Announce step includes the original request + round‑1 reply + latest ping‑pong reply.

 ## Provider Field
- For groups, `provider` is the provider recorded on the session entry.
- For direct chats, `provider` maps from `lastProvider`.
+- For groups, `provider` is the `surface` recorded on the session entry.
+- For direct chats, `provider` maps from `lastChannel`.
 - For cron/hook/node, `provider` is `internal`.
 - If missing, `provider` is `unknown`.

 ## Security / Send Policy
-Policy-based blocking by provider/chat type (not per session id).
+Policy-based blocking by surface/chat type (not per session id).

 ```json
 {
@@ -102,7 +102,7 @@ Policy-based blocking by provider/chat type (not per session id).
    "sendPolicy": {
      "rules": [
        {
-          "match": { "provider": "discord", "chatType": "group" },
+          "match": { "surface": "discord", "chatType": "group" },
          "action": "deny"
        }
      ],
@@ -114,14 +114,14 @@ Policy-based blocking by provider/chat type (not per session id).

 Runtime override (per session entry):
 - `sendPolicy: "allow" | "deny"` (unset = inherit config)
- Settable via `sessions.patch` or owner-only `/send on|off|inherit` (standalone message).
+- Settable via `sessions.patch` or owner-only `/send on|off|inherit`.

 Enforcement points:
 - `chat.send` / `agent` (gateway)
 - auto-reply delivery logic

 ## sessions_spawn
-Spawn a sub-agent run in an isolated session and announce the result back to the requester chat provider.
+Spawn a sub-agent run in an isolated session and announce the result back to the requester chat surface.

 Parameters:
 - `task` (required)
@@ -131,9 +131,9 @@ Parameters:

 Behavior:
 - Starts a new `subagent:<uuid>` session with `deliver: false`.
- Sub-agents default to the full tool set **minus session tools** (configurable via `agent.subagents.tools`).
+- Sub-agents default to the full tool surface **minus session tools** (configurable via `agent.subagents.tools`).
 - Sub-agents are not allowed to call `sessions_spawn` (no sub-agent → sub-agent spawning).
- After completion (or best-effort wait), Clawdbot runs a sub-agent **announce step** and posts the result to the requester chat provider.
+- After completion (or best-effort wait), Clawdbot runs a sub-agent **announce step** and posts the result to the requester chat surface.
 - Reply exactly `ANNOUNCE_SKIP` during the announce step to stay silent.

 ## Sandbox Session Visibility
@@ -5,7 +5,7 @@ read_when:
 ---
 # Session Management

-Clawdbot treats **one direct-chat session per agent** as primary. Direct chats collapse to `agent:<agentId>:<mainKey>` (default `main`), while group/channel chats get their own keys. `session.mainKey` is honored.
+Clawdbot treats **one session as primary**. The canonical key is fixed to `main` for direct chats (or `global` when scope is global); no configuration is required. `session.mainKey` is ignored. Older/local sessions can stay on disk, but only the primary key is used for desktop/web chat and direct agent calls.

 ## Gateway is the source of truth
 All session state is **owned by the gateway** (the “master” Clawdbot). UI clients (macOS app, WebChat, etc.) must query the gateway for session lists and token counts instead of reading local files.
@@ -15,17 +15,17 @@ All session state is **owned by the gateway** (the “master” Clawdbot). UI cl

 ## Where state lives
 - On the **gateway host**:
-  - Store file: `~/.clawdbot/agents/<agentId>/sessions/sessions.json` (per agent).
-  - Transcripts: `~/.clawdbot/agents/<agentId>/sessions/<SessionId>.jsonl` (one file per session id).
+  - Store file: `~/.clawdbot/sessions/sessions.json` (legacy: `~/.clawdbot/sessions.json`).
+  - Transcripts: `~/.clawdbot/sessions/<SessionId>.jsonl` (one file per session id).
 - The store is a map `sessionKey -> { sessionId, updatedAt, ... }`. Deleting entries is safe; they are recreated on demand.
- Group entries may include `displayName`, `provider`, `subject`, `room`, and `space` to label sessions in UIs.
+- Group entries may include `displayName`, `surface`, `subject`, `room`, and `space` to label sessions in UIs.
 - Clawdbot does **not** read legacy Pi/Tau session folders.

 ## 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.
- Group chats isolate state: `agent:<agentId>:<provider>:group:<id>` (rooms/channels use `agent:<agentId>:<provider>:channel:<id>`).
-  - Legacy `group:<id>` keys are still recognized for migration.
+- Direct chats (WhatsApp, Telegram, Discord, desktop Web Chat) all collapse to the **primary key** so they share context.
+- Multiple phone numbers can map to that same key; they act as transports into the same conversation.
+- Group chats isolate state with `surface:group:<id>` keys (rooms/channels use `surface:channel:<id>`); do not reuse the primary key for groups. (Discord display names show `discord:<guildSlug>#<channelSlug>`.)
+  - Legacy `group:<surface>:<id>` and `group:<id>` keys are still recognized.
 - Other sources:
  - Cron jobs: `cron:<job.id>`
  - Webhooks: `hook:<uuid>` (unless explicitly set by the hook)
@@ -44,7 +44,7 @@ Block delivery for specific session types without listing individual ids.
  session: {
    sendPolicy: {
      rules: [
-        { action: "deny", match: { provider: "discord", chatType: "group" } },
+        { action: "deny", match: { surface: "discord", chatType: "group" } },
        { action: "deny", match: { keyPrefix: "cron:" } }
      ],
      default: "allow"
@@ -57,7 +57,6 @@ Runtime override (owner only):
 - `/send on` → allow for this session
 - `/send off` → deny for this session
 - `/send inherit` → clear override and use config rules
-Send these as standalone messages so they register.

 ## Configuration (optional rename example)
 ```json5
@@ -67,8 +66,8 @@ Send these as standalone messages so they register.
    scope: "per-sender",      // keep group keys separate
    idleMinutes: 120,
    resetTriggers: ["/new", "/reset"],
-    store: "~/.clawdbot/agents/{agentId}/sessions/sessions.json",
-    mainKey: "main",
+    store: "~/.clawdbot/sessions/sessions.json",
+    // mainKey is ignored; primary key is fixed to "main"
  }
 }
 ```
@@ -77,8 +76,8 @@ Send these as standalone messages so they register.
 - `pnpm clawdbot status` — shows store path and recent sessions.
 - `pnpm clawdbot sessions --json` — dumps every entry (filter with `--active <minutes>`).
 - `pnpm clawdbot gateway call sessions.list --params '{}'` — fetch sessions from the running gateway (use `--url`/`--token` for remote gateway access).
- Send `/status` as a standalone message in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, and when your WhatsApp web creds were last refreshed (helps spot relink needs).
- Send `/compact` (optional instructions) as a standalone message to summarize older context and free up window space.
+- Send `/status` in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, and when your WhatsApp web creds were last refreshed (helps spot relink needs).
+- Send `/compact` (optional instructions) to summarize older context and free up window space.
 - JSONL transcripts can be opened directly to review full turns.

 ## Tips
@@ -5,4 +5,4 @@ read_when:
 ---
 # Sessions

-Canonical session management docs live in [`docs/session.md`](https://docs.clawd.bot/session).
+Canonical session management docs live in `docs/session.md`.
@@ -17,7 +17,7 @@ Last updated: 2026-01-01
 ## Prereqs (from source)
 - Node `>=22`
 - `pnpm`
- Docker (optional; only for containerized setup/e2e — see [`docs/docker.md`](https://docs.clawd.bot/docker))
+- Docker (optional; only for containerized setup/e2e — see `docs/docker.md`)

 ## Tailoring strategy (so updates don’t hurt)

@@ -77,7 +77,7 @@ pnpm install
 pnpm gateway:watch
 ```

-`gateway:watch` runs `src/entry.ts gateway --force` and reloads on [`src/**/*.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/**/*.ts) changes.
+`gateway:watch` runs `src/index.ts gateway --force` and reloads on `src/**/*.ts` changes.

 ### 2) Point the macOS app at your running Gateway

@@ -102,22 +102,7 @@ pnpm clawdbot health
 - **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port.
 - **Where state lives:**
  - Credentials: `~/.clawdbot/credentials/`
-  - Sessions: `~/.clawdbot/agents/<agentId>/sessions/`
-  - Logs: `/tmp/clawdbot/`
-
-## Gateway service (optional)
-
-If you want the Gateway supervised outside the macOS app (CLI-only, headless, or remote setups). The macOS app already manages the Gateway via launchd.
-
-```bash
-clawdbot gateway install
-clawdbot gateway service-status
-clawdbot gateway uninstall
-```
-
-Aliases:
- `clawdbot service ...`
- `clawdbot daemon ...`
+  - Sessions/logs: `~/.clawdbot/sessions/`

 ## Updating (without wrecking your setup)

@@ -135,12 +120,12 @@ sudo loginctl enable-linger $USER
 ```

 For always-on or multi-user servers, consider a **system** service instead of a
-user service (no lingering needed). See [`docs/gateway.md`](https://docs.clawd.bot/gateway) for the systemd notes.
+user service (no lingering needed). See `docs/gateway.md` for the systemd notes.

 ## Related docs

- [`docs/gateway.md`](https://docs.clawd.bot/gateway) (Gateway runbook; flags, supervision, ports)
- [`docs/configuration.md`](https://docs.clawd.bot/configuration) (config schema + examples)
- [`docs/discord.md`](https://docs.clawd.bot/discord) and [`docs/telegram.md`](https://docs.clawd.bot/telegram) (reply tags + replyToMode settings)
- [`docs/clawd.md`](https://docs.clawd.bot/clawd) (personal assistant setup)
- [`docs/macos.md`](https://docs.clawd.bot/macos) (macOS app behavior; gateway lifecycle + “Attach only”)
+- `docs/gateway.md` (Gateway runbook; flags, supervision, ports)
+- `docs/configuration.md` (config schema + examples)
+- `docs/discord.md` and `docs/telegram.md` (reply tags + replyToMode settings)
+- `docs/clawd.md` (personal assistant setup)
+- `docs/macos.md` (macOS app behavior; gateway lifecycle + “Attach only”)
@@ -51,8 +51,7 @@ You can still run Clawdbot on your own Signal account if your goal is “respond
    httpPort: 8080,

    // Who is allowed to talk to the bot (DMs)
-    dmPolicy: "pairing", // pairing | allowlist | open | disabled
-    allowFrom: ["+15557654321"], // your personal number ("open" requires ["*"])
+    allowFrom: ["+15557654321"], // your personal number (or "*")

    // Group policy + allowlist
    groupPolicy: "open",
@@ -65,10 +64,6 @@ You can still run Clawdbot on your own Signal account if your goal is “respond
   - Expect `signal.probe.ok=true` and `signal.probe.version`.
 5) DM the bot number from your phone; Clawdbot replies.

-## DM pairing
- Default: `signal.dmPolicy="pairing"` — unknown DM senders get a pairing code.
- Approve via: `clawdbot pairing approve --provider signal <code>`.
-
 ## “Do I need a separate number?”
 - If you want “I text her and she texts me back”, yes: **use a separate Signal account/number for the bot**.
 - Your personal account can run `signal-cli`, but you can’t self-chat (Signal loop protection; Clawdbot ignores sender==account).
@@ -108,7 +103,7 @@ If you have a second phone:
 2) Launch daemon (HTTP preferred), store PID.
 3) Poll `/api/v1/check` until ready.
 4) Open SSE stream; parse `event: receive`.
-5) Translate receive payload into Clawdbot provider model.
+5) Translate receive payload into Clawdbot surface model.
 6) On SSE disconnect, backoff + reconnect.

 ## Storage
@@ -142,6 +142,6 @@ copy). Workspace skills are user-owned and override both on name conflicts.

 ## Config reference

-See [`docs/skills-config.md`](https://docs.clawd.bot/skills-config) for the full configuration schema.
+See `docs/skills-config.md` for the full configuration schema.

 ---
@@ -17,7 +17,7 @@ read_when: "Setting up Slack or debugging Slack socket mode"
   - `channel_rename`
   - `pin_added`, `pin_removed`
 5) Invite the bot to channels you want it to read.
-6) Slash Commands → create `/clawd` if you use `slack.slashCommand`. If you enable `commands.native`, add slash commands for the built-in chat commands (same names as `/help`).
+6) Slash Commands → create the `/clawd` command (or your preferred name).
 7) App Home → enable the **Messages Tab** so users can DM the bot.

 Use the manifest below so scopes and events stay in sync.
@@ -98,8 +98,6 @@ Use this Slack app manifest to create the app quickly (adjust the name/command i
 }
 ```

-If you enable `commands.native`, add one `slash_commands` entry per command you want to expose (matching the `/help` list).
-
 ## Scopes (current vs optional)
 Slack's Conversations API is type-scoped: you only need the scopes for the
 conversation types you actually touch (channels, groups, im, mpim). See
@@ -111,12 +109,12 @@ https://api.slack.com/docs/conversations-api for the overview.
 - `im:write` (open DMs via `conversations.open` for user DMs)
  https://api.slack.com/methods/conversations.open
 - `channels:history`, `groups:history`, `im:history`, `mpim:history`
-  (`conversations.history` in [`src/slack/actions.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/slack/actions.ts))
+  (`conversations.history` in `src/slack/actions.ts`)
  https://api.slack.com/methods/conversations.history
 - `channels:read`, `groups:read`, `im:read`, `mpim:read`
-  (`conversations.info` in [`src/slack/monitor.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/slack/monitor.ts))
+  (`conversations.info` in `src/slack/monitor.ts`)
  https://api.slack.com/methods/conversations.info
- `users:read` (`users.info` in [`src/slack/monitor.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/slack/monitor.ts) + [`src/slack/actions.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/slack/actions.ts))
+- `users:read` (`users.info` in `src/slack/monitor.ts` + `src/slack/actions.ts`)
  https://api.slack.com/methods/users.info
 - `reactions:read`, `reactions:write` (`reactions.get` / `reactions.add`)
  https://api.slack.com/methods/reactions.get
@@ -150,7 +148,6 @@ Slack uses Socket Mode only (no HTTP webhook server). Provide both tokens:
    "groupPolicy": "open",
    "dm": {
      "enabled": true,
-      "policy": "pairing",
      "allowFrom": ["U123", "U456", "*"],
      "groupEnabled": false,
      "groupChannels": ["G123"]
@@ -191,13 +188,6 @@ Ack reactions are controlled globally via `messages.ackReaction` +
 - DMs share the `main` session (like WhatsApp/Telegram).
 - Channels map to `slack:channel:<channelId>` sessions.
 - Slash commands use `slack:slash:<userId>` sessions.
- Native command registration is controlled by `commands.native`; text commands require standalone `/...` messages and can be disabled with `commands.text: false`. Slack slash commands are managed in the Slack app and are not removed automatically. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
- Full command list + config: https://docs.clawd.bot/slash-commands
-
-## DM security (pairing)
- Default: `slack.dm.policy="pairing"` — unknown DM senders get a pairing code.
- Approve via: `clawdbot pairing approve --provider slack <code>`.
- To allow anyone: set `slack.dm.policy="open"` and `slack.dm.allowFrom=["*"]`.

 ## Group policy
 - `slack.groupPolicy` controls channel handling (`open|disabled|allowlist`).
@@ -1,53 +0,0 @@
---
-summary: "Slash commands: text vs native, config, and supported commands"
-read_when:
-  - Using or configuring chat commands
-  - Debugging command routing or permissions
---
-# Slash commands
-
-Commands are handled by the Gateway. Send them as a **standalone** message that starts with `/`.
-Inline text like `hello /status` is ignored.
-
-## Config
-
-```json5
-{
-  commands: {
-    native: false,
-    text: true,
-    useAccessGroups: true
-  }
-}
-```
-
- `commands.text` (default `true`) enables parsing `/...` in chat messages.
-  - On surfaces without native commands (WhatsApp/WebChat/Signal/iMessage), text commands still work even if you set this to `false`.
- `commands.native` (default `false`) registers native commands on Discord/Slack/Telegram.
-  - `false` clears previously registered commands on Discord/Telegram at startup.
-  - Slack commands are managed in the Slack app and are not removed automatically.
- `commands.useAccessGroups` (default `true`) enforces allowlists/policies for commands.
-
-## Command list
-
-Text + native (when enabled):
- `/help`
- `/status`
- `/restart`
- `/activation mention|always` (groups only)
- `/send on|off|inherit` (owner-only)
- `/reset` or `/new`
- `/think <level>` (aliases: `/thinking`, `/t`)
- `/verbose on|off` (alias: `/v`)
- `/elevated on|off` (alias: `/elev`)
- `/model <name>`
- `/queue <mode>` (plus options like `debounce:2s cap:25 drop:summarize`)
-
-Text-only:
- `/compact [instructions]`
-
-## Surface notes
-
- **Text commands** run in the normal chat session (DMs share `main`, groups have their own session).
- **Native commands** use isolated sessions: `discord:slash:<userId>`, `slack:slash:<userId>`, `telegram:slash:<userId>`.
- **Slack:** `slack.slashCommand` is still supported for a single `/clawd`-style command. If you enable `commands.native`, you must create one Slack slash command per built-in command (same names as `/help`).
@@ -1,3 +0,0 @@
-# /landpr
-
-Land PR: rebase onto temp branch from main, fix+tests+changelog, run pnpm lint && pnpm build && pnpm test before commit, commit via committer, fast‑forward main, push, close PR, delete temp branch.
@@ -7,7 +7,7 @@ read_when:

 # Sub-agents

-Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (`subagent:<uuid>`) and, when finished, **announce** their result back to the requester chat provider.
+Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (`subagent:<uuid>`) and, when finished, **announce** their result back to the requester chat surface.

 Primary goals:
 - Parallelize “research / long task / slow tool” work without blocking the main run.
@@ -19,7 +19,7 @@ Primary goals:

 Use `sessions_spawn`:
 - Starts a sub-agent run (`deliver: false`, global lane: `subagent`)
- Then runs an announce step and posts the announce reply to the requester chat provider
+- Then runs an announce step and posts the announce reply to the requester chat surface

 Tool params:
 - `task` (required)
@@ -32,7 +32,7 @@ Tool params:
 Sub-agents report back via an announce step:
 - The announce step runs inside the sub-agent session (not the requester session).
 - If the sub-agent replies exactly `ANNOUNCE_SKIP`, nothing is posted.
- Otherwise the announce reply is posted to the requester chat provider via the gateway `send` method.
+- Otherwise the announce reply is posted to the requester chat surface via the gateway `send` method.

 ## Tool Policy (sub-agent tools)

@@ -0,0 +1,20 @@
+---
+summary: "Routing rules per surface (WhatsApp, Telegram, Discord, web) and shared context"
+read_when:
+  - Changing surface routing or inbox behavior
+---
+# Surfaces & Routing
+
+Updated: 2025-12-07
+
+Goal: make replies deterministic per channel while keeping one shared context for direct chats.
+
+- **Surfaces** (channel labels): `whatsapp`, `webchat`, `telegram`, `discord`, `imessage`, `voice`, etc. Add `Surface` to inbound `MsgContext` so templates/agents can log which channel a turn came from. Routing is fixed: replies go back to the origin surface; the model doesn’t choose.
+- **Reply context:** inbound replies include `ReplyToId`, `ReplyToBody`, and `ReplyToSender`, and the quoted context is appended to `Body` as a `[Replying to ...]` block.
+- **Canonical direct session:** All direct chats collapse into the single `main` session by default (no config needed). Groups stay `surface:group:<id>` (rooms: `surface:channel:<id>`), so they remain isolated.
+- **Session store:** Keys are resolved via `resolveSessionKey(scope, ctx, mainKey)`; the agent JSONL path lives under `~/.clawdbot/sessions/<SessionId>.jsonl`.
+- **WebChat:** Always attaches to `main`, loads the full session transcript so desktop reflects cross-surface history, and writes new turns back to the same session.
+- **Implementation hints:**
+  - Set `Surface` in each ingress (WhatsApp gateway, WebChat bridge, Telegram, Discord, iMessage).
+  - Keep routing deterministic: originate → same surface. Use the gateway WebSocket for sends; avoid side channels.
+  - Do not let the agent emit “send to X” decisions; keep that policy in the host code.
@@ -12,7 +12,7 @@ Status: ready for bot-mode use with grammY (long-polling by default; webhook sup
 ## Goals
 - Let you talk to Clawdbot via a Telegram bot in DMs and groups.
 - Share the same `main` session used by WhatsApp/WebChat; groups stay isolated as `telegram:group:<chatId>`.
- Keep transport routing deterministic: replies always go back to the provider they arrived on.
+- Keep transport routing deterministic: replies always go back to the surface they arrived on.

 ## How it will work (Bot API)
 1) Create a bot with @BotFather and grab the token.
@@ -23,13 +23,11 @@ Status: ready for bot-mode use with grammY (long-polling by default; webhook sup
   - **Webhook mode** is enabled by setting `telegram.webhookUrl` (optionally `telegram.webhookSecret` / `telegram.webhookPath`).
     - The webhook listener currently binds to `0.0.0.0:8787` and serves `POST /telegram-webhook` by default.
     - If you need a different public port/host, set `telegram.webhookUrl` to the externally reachable URL and use a reverse proxy to forward to `:8787`.
-4) Direct chats: secure by default — unknown senders are gated by `telegram.dmPolicy` (default: `"pairing"`). The bot responds with a pairing code that the owner must approve before messages are processed. If you really want public inbound DMs: set `telegram.dmPolicy="open"` and `telegram.allowFrom=["*"]`.
+4) Direct chats: user sends the first message; all subsequent turns land in the shared `main` session (default, no extra config).
 5) Groups: add the bot, disable privacy mode (or make it admin) so it can read messages; group threads stay on `telegram:group:<chatId>`. When `telegram.groups` is set, it becomes a group allowlist (use `"*"` to allow all). Mention/command gating defaults come from `telegram.groups`.
-6) Allowlist + pairing:
-   - Direct chats: `telegram.allowFrom` (chat ids) or pairing approvals via `clawdbot pairing approve --provider telegram <code>` (alias: `clawdbot telegram pairing approve <code>`).
+6) Optional allowlist:
+   - Direct chats: `telegram.allowFrom` by chat id (`123456789`, `telegram:123456789`, or `tg:123456789`; prefixes are case-insensitive).
   - Groups: set `telegram.groupPolicy = "allowlist"` and list senders in `telegram.groupAllowFrom` (fallback: explicit `telegram.allowFrom`).
-   - Commands respect group allowlists/policies by default; set `commands.useAccessGroups: false` to bypass.
-7) Native commands: set `commands.native: true` to register `/` commands; set `commands.native: false` to clear previously registered commands.

 ## Capabilities & limits (Bot API)
 - Sees only messages sent after it’s added to a chat; no pre-history access.
@@ -39,9 +37,9 @@ Status: ready for bot-mode use with grammY (long-polling by default; webhook sup

 ## Planned implementation details
 - Library: grammY is the only client for send + gateway (fetch fallback removed); grammY throttler is enabled by default to stay under Bot API limits.
- Inbound normalization: maps Bot API updates to `MsgContext` with `Provider: "telegram"`, `ChatType: direct|group`, `SenderName`, `MediaPath`/`MediaType` when attachments arrive, `Timestamp`, and reply-to metadata (`ReplyToId`, `ReplyToBody`, `ReplyToSender`) when the user replies; reply context is appended to `Body` as a `[Replying to ...]` block (includes `id:` when available); groups require @bot mention or a `routing.groupChat.mentionPatterns` match by default (override per chat in config).
+- Inbound normalization: maps Bot API updates to `MsgContext` with `Surface: "telegram"`, `ChatType: direct|group`, `SenderName`, `MediaPath`/`MediaType` when attachments arrive, `Timestamp`, and reply-to metadata (`ReplyToId`, `ReplyToBody`, `ReplyToSender`) when the user replies; reply context is appended to `Body` as a `[Replying to ...]` block (includes `id:` when available); groups require @bot mention or a `routing.groupChat.mentionPatterns` match by default (override per chat in config).
 - Outbound: text and media (photo/video/audio/document) with optional caption; chunked to limits. Typing cue sent best-effort.
- Config: `TELEGRAM_BOT_TOKEN` env or `telegram.botToken` required; `telegram.dmPolicy`, `telegram.groups` (group allowlist + mention defaults), `telegram.allowFrom`, `telegram.groupAllowFrom`, `telegram.groupPolicy`, `telegram.mediaMaxMb`, `telegram.replyToMode`, `telegram.proxy`, `telegram.webhookSecret`, `telegram.webhookUrl`, `telegram.webhookPath` supported.
+- Config: `TELEGRAM_BOT_TOKEN` env or `telegram.botToken` required; `telegram.groups` (group allowlist + mention defaults), `telegram.allowFrom`, `telegram.groupAllowFrom`, `telegram.groupPolicy`, `telegram.mediaMaxMb`, `telegram.replyToMode`, `telegram.proxy`, `telegram.webhookSecret`, `telegram.webhookUrl`, `telegram.webhookPath` supported.
  - Ack reactions are controlled globally via `messages.ackReaction` + `messages.ackReactionScope`.
  - Mention gating precedence (most specific wins): `telegram.groups.<chatId>.requireMention` → `telegram.groups."*".requireMention` → default `true`.

@@ -51,13 +49,12 @@ Example config:
  telegram: {
    enabled: true,
    botToken: "123:abc",
-    dmPolicy: "pairing", // pairing | allowlist | open | disabled
    replyToMode: "off",
    groups: {
      "*": { requireMention: true }, // allow all groups
      "123456789": { requireMention: false } // group chat id
    },
-    allowFrom: ["123456789"], // direct chat ids allowed ("open" requires ["*"])
+    allowFrom: ["123456789"], // direct chat ids allowed (or "*")
    groupPolicy: "allowlist",
    groupAllowFrom: ["tg:123456789", "@alice"],
    mediaMaxMb: 5,
@@ -68,12 +65,12 @@ Example config:
  }
 }
 ```
- Tests: grammY-based paths in [`src/telegram/*.test.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/telegram/*.test.ts) cover DM + group gating; add more media and webhook cases as needed.
+- Tests: grammY-based paths in `src/telegram/*.test.ts` cover DM + group gating; add more media and webhook cases as needed.

 ## Group etiquette
 - Keep privacy mode off if you expect the bot to read all messages; with privacy on, it only sees commands/mentions.
 - Make the bot an admin if you need it to send in restricted groups or channels.
- Mention the bot (`@yourbot`), use a `routing.groupChat.mentionPatterns` trigger, or send a standalone `/...` command. Per-group overrides live in `telegram.groups` if you want always-on behavior; if `telegram.groups` is set, add `"*"` to keep existing allow-all behavior.
+- Mention the bot (`@yourbot`) or use a `routing.groupChat.mentionPatterns` trigger; per-group overrides live in `telegram.groups` if you want always-on behavior. If `telegram.groups` is set, add `"*"` to keep existing allow-all behavior.

 ## Reply tags
 To request a threaded reply, the model can include one tag in its output:
@@ -115,12 +115,7 @@ Skills provide your tools. When you need one, check its `SKILL.md`. Keep local n

 ## 💓 Heartbeats - Be Proactive!

-When you receive a heartbeat poll (message matches the configured heartbeat prompt), don't just reply `HEARTBEAT_OK` every time. Use heartbeats productively!
-
-Default heartbeat prompt:
-`Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`
-
-You are free to edit `HEARTBEAT.md` with a short checklist or reminders. Keep it small.
+When you receive a `HEARTBEAT` message, don't just reply `HEARTBEAT_OK` every time. Use heartbeats productively!

 **Things to check (rotate through these, 2-4 times per day):**
 - **Emails** - Any urgent unread messages?
@@ -1,8 +0,0 @@
---
-summary: "Workspace template for HEARTBEAT.md"
-read_when:
-  - Bootstrapping a workspace manually
---
-# HEARTBEAT.md
-
-Keep this file empty unless you want a tiny checklist for heartbeat runs. Keep it small.
@@ -11,7 +11,7 @@ read_when:

 ## Model latency bench (local keys)

-Script: [`scripts/bench-model.ts`](https://github.com/clawdbot/clawdbot/blob/main/scripts/bench-model.ts)
+Script: `scripts/bench-model.ts`

 Usage:
 - `source ~/.profile && bun scripts/bench-model.ts --runs 10`
@@ -35,10 +35,10 @@ read_when:
 - When verbose is on, agents that emit structured tool results (Pi, other JSON agents) send each tool result back as its own metadata-only message, prefixed with `<emoji> <tool-name>: <arg>` when available (path/command); the tool output itself is not forwarded. These tool summaries are sent as soon as each tool finishes (separate bubbles), not as streaming deltas. If you toggle `/verbose on|off` while a run is in-flight, subsequent tool bubbles honor the new setting.

 ## Related
- Elevated mode docs live in [`docs/elevated.md`](https://docs.clawd.bot/elevated).
+- Elevated mode docs live in `docs/elevated.md`.

 ## Heartbeats
- Heartbeat probe body is the configured heartbeat prompt (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`). Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).
+- Heartbeat probe body is `HEARTBEAT`. Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).

 ## Web chat UI
 - The web chat thinking selector mirrors the session's stored level from the inbound session store/config when the page loads.
@@ -14,7 +14,7 @@ Clawdbot standardizes timestamps so the model sees a **single reference time**.
 Inbound messages are wrapped in an envelope like:

 ```
-[Provider ... 2026-01-05T21:26Z] message text
+[Surface ... 2026-01-05T21:26Z] message text
 ```

 The timestamp in the envelope is **always UTC**, with minutes precision.
@@ -203,7 +203,7 @@ Notes:
 - `reactions` returns per-emoji user lists (limited to 100 per reaction).
 - `discord.actions.*` gates Discord tool actions; `roles` + `moderation` default to `false`.
 - `searchMessages` follows the Discord preview spec (limit max 25, channel/author filters accept arrays).
- The tool is only exposed when the current provider is Discord.
+- The tool is only exposed when the current surface is Discord.

 ## Parameters (common)

@@ -247,17 +247,17 @@ Tools are exposed to the model in **two parallel channels**:
 2) **Provider tool schema**: the actual function/tool declarations sent to the model API.

 In pi-mono:
- System prompt builder: [`packages/coding-agent/src/core/system-prompt.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/system-prompt.ts)
+- System prompt builder: `packages/coding-agent/src/core/system-prompt.ts`
  - Builds the `Available tools:` list from `toolDescriptions`.
  - Appends skills and project context.
 - Tool schemas passed to providers:
-  - OpenAI: [`packages/ai/src/providers/openai-responses.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/providers/openai-responses.ts) (`convertTools`)
-  - Anthropic: [`packages/ai/src/providers/anthropic.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/providers/anthropic.ts) (`convertTools`)
-  - Gemini: [`packages/ai/src/providers/google-shared.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/providers/google-shared.ts) (`convertTools`)
+  - OpenAI: `packages/ai/src/providers/openai-responses.ts` (`convertTools`)
+  - Anthropic: `packages/ai/src/providers/anthropic.ts` (`convertTools`)
+  - Gemini: `packages/ai/src/providers/google-shared.ts` (`convertTools`)
 - Tool execution loop:
-  - Agent loop: [`packages/ai/src/agent/agent-loop.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/agent/agent-loop.ts)
+  - Agent loop: `packages/ai/src/agent/agent-loop.ts`
  - Validates tool arguments and executes tools, then appends `toolResult` messages.

 In Clawdbot:
- System prompt append: [`src/agents/system-prompt.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/agents/system-prompt.ts)
- Tool list injected via `createClawdbotCodingTools()` in [`src/agents/pi-tools.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/agents/pi-tools.ts)
+- System prompt append: `src/agents/system-prompt.ts`
+- Tool list injected via `createClawdbotCodingTools()` in `src/agents/pi-tools.ts`
@@ -14,7 +14,7 @@ When your CLAWDBOT misbehaves, here's how to fix it.
 The agent was interrupted mid-response.

 **Causes:**
- User sent `stop`, `abort`, `esc`, `wait`, or `exit`
+- User sent `stop`, `abort`, `esc`, or `exit`
 - Timeout exceeded
 - Process crashed

@@ -50,7 +50,7 @@ Known issue: When you send an image with ONLY a mention (no other text), WhatsAp

 **Check 1:** Is the session file there?
 ```bash
-ls -la ~/.clawdbot/agents/<agentId>/sessions/
+ls -la ~/.clawdbot/sessions/
 ```

 **Check 2:** Is `idleMinutes` too short?
@@ -146,7 +146,7 @@ tccutil reset All com.clawdbot.mac.debug
 ```

 **Fix 2: Force New Bundle ID**
-If resetting doesn't work, change the `BUNDLE_ID` in [`scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh) (e.g., add a `.test` suffix) and rebuild. This forces macOS to treat it as a new app.
+If resetting doesn't work, change the `BUNDLE_ID` in `scripts/package-mac-app.sh` (e.g., add a `.test` suffix) and rebuild. This forces macOS to treat it as a new app.

 ### Gateway stuck on "Starting..."

@@ -167,14 +167,8 @@ clawdbot gateway stop
 # Or: launchctl bootout gui/$UID/com.clawdbot.gateway
 ```

-If no supervisor is installed yet:
-```bash
-clawdbot gateway install
-clawdbot gateway service-status
-```
-
 **Fix 2: 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 `bun` is installed.
+Ensure the gateway relay was properly bundled. Run `./scripts/package-mac-app.sh` and ensure `bun` is installed.

 ## Debug Mode

@@ -194,7 +188,7 @@ clawdbot login --verbose
 | Log | Location |
 |-----|----------|
 | Main logs (default) | `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` |
-| Session files | `~/.clawdbot/agents/<agentId>/sessions/` |
+| Session files | `~/.clawdbot/sessions/` |
 | Media cache | `~/.clawdbot/media/` |
 | Credentials | `~/.clawdbot/credentials/` |

@@ -260,4 +254,4 @@ Then set in config:
 }
 ```

-**Full guide:** See [browser-linux-troubleshooting](https://docs.clawd.bot/browser-linux-troubleshooting)
+**Full guide:** See [browser-linux-troubleshooting.md](./browser-linux-troubleshooting.md)
@@ -66,6 +66,6 @@ Use SSH tunneling or Tailscale to reach the Gateway WS.
 - It registers as a Gateway client with `mode: "tui"` for presence and debugging.

 ## Files
- CLI: [`src/cli/tui-cli.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/tui-cli.ts)
- Runner: [`src/tui/tui.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/tui/tui.ts)
- Gateway client: [`src/tui/gateway-chat.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/tui/gateway-chat.ts)
+- CLI: `src/cli/tui-cli.ts`
+- Runner: `src/tui/tui.ts`
+- Gateway client: `src/tui/gateway-chat.ts`
Author	SHA1	Message	Date
Peter Steinberger	0b5f672353	docs(changelog): mention Dockerfile Bun install (#284 )	2026-01-06 15:02:27 +01:00
Peter Steinberger	9c13819f39	Merge remote-tracking branch 'origin/main' into fix/dockerfile-install-bun	2026-01-06 15:00:54 +01:00
Lukáš LoukotaandClaude Opus 4.5	971153f4de	fix: install Bun in Dockerfile for build scripts The build script was updated to use Bun (`bun scripts/canvas-a2ui-copy.ts`) but the Dockerfile was not updated to install Bun, causing Docker builds to fail with "bun: not found". 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-06 09:40:27 +01:00